Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Semantic Field Types
#1
<please don't post here. This is an informational thread. There is another thread in this forum area for discussion of the information represented here. We want to keep this thread clean for reference purposes. Once this information is well worked out, it will be moved into the appropriate formal technical documents.>

Much of the standardization of devices doesn't necessarily have to be at the level of a formal interface for each device. A lot of the flexibility that accrues from standardization can be gotten purely from each field being marked as having a specific 'semantic' type, i.e. what it means in terms of it's usage by the user and what it does or the information it provides, not a definition of its data type, limits, etc..., though each semantic type will defintely require specific types and reactions.

Any field can be marked by a driver with a semantic field type, and driver writers are very much encouraged to do so, though they MUST strictly follow the guidelines set forth here, else their use of the semantic type is not only of no use, it's actually detrimental. For the most part it is not difficult to meet the requirements, since those requirements are typically based on what would be the most common choices(s) a driver writer would make anyway.

Note that there are multiple purpose for semantic field types, so there are multiple reasons why you would mark them, and sometimes a single field will be marked for multiple reasons.
  • In some cases the field type provides a hint as to appropriate graphical representation or input mechanism. E.g. if selecting fields for a slider widget, obviously semantic types that have a representation that is displayable and/or manipulable by a slider would be the ones presented.
  • Sometimes it's the other way around, where you select a specific semantic field type and a graphical representation of the appropriate type is automatically selected for you.
  • There may be situations where calculations related to a specific type of information are being done, and so CQC may wish to only present those fields of that sort, such as perhaps humidity fields.
  • It is not the case that the semantic field type provides a highly detailed indication of type. For example, a ColCookie type obviously indicates a field holding a collection cookie, but it doesn't say what particularly that cookie is. It could be the collection of a currently playing song, a collection being previewed before playback, etc... So some are more targeted than others.

The rest of this thread documents each semantic field type, though some have no well defined meaning yet and another thread will be created for discussion of these types and how to tighten them up and improve understanding of the requirements.
Dean Roddey
Software Geek Extraordinaire
Reply
#2
These are the Semantic Field Types currently proposed. Most of these already exist, though some are being proposed here. Please comment on these (or others that might be useful), in the other thread for semantic field type discussion.

Analog IO
[INDENT]These fields provide analog inputs and outputs. Inputs MUST be read-only. Outputs MUST be at least writable, and often will be readable as well since most devices will likely allow the current output level to be read. These fields MUST be floating point values so as to deal with voltages that are typically non-integral. If the value is integral then the field will just never have any decimal digits. It typically will provide a numeric Range type limit but that is not required if it is not useful for a given input or output. It is RECOMMENDED where appropriate that the user be able to provide a custom range limit on inputs.[/INDENT]


BoolSwitch
[INDENT]This one is pretty straightforward. It is used when you want to switch something off or on that is not one of the more specialized semantic types, e.g. LightSwitch, Power, Mute, etc... It MUST be a Boolean field, and MUST be at least writeable. Usually it is read/write since the current state of the switch will be available from the device, but that is not required.[/INDENT]

CatCookie

ChannelAdj
[INDENT]This MUST be a Boolean field, where writing False to it adjusts a channel down, and True adjust a channel up. What type of channel is not implied, it could be TV, radio tuner, whatever. Given the way it works, the field MUST be write-only, so that multiple writes of the same value will be passed on to the driver.[/INDENT]

ClrLight
[INDENT]This MUST be a String field, which contains an HSV color in the form of three space separated decimal numbers. The first is the Hue, which is a value from 0 to 359. The second is the saturation which is from 0 to 255, and the last is the value (or brightness) which is also 0 to 55. Generally the field should be read/write but MUST be at least writeable in order to control the light.[/INDENT]

ColCookie

ContactClosure
[INDENT]Fields of this type sense the closed/opened state of a contact. So they MUST be Boolean fields and ReadOnly. For read/write contacts use Relay.[/INDENT]

CurChannel
[INDENT]Fields of this type MUST be String, Card, or Float, and typically will be read only. No assumption of writeability is implied by this semantic type. It is generally for display of current channels, and is mostly for field selection filtering to find current channels to display.[/INDENT]

CurExtHumidity
[INDENT]Fields of this type MUST be Card or Float, and MUST have a Range limit from 0 to 100, indicating a humidity percentage for an external humidity sensor, as opposed to an internal one. It is read only.[/INDENT]

CurExtTemp
[INDENT]Fields of this type MUST be Int and read only, and represents an external temperature, not an internal one. It MUST have a Range limit, and it is RECOMMENDED that the user be able to provide more range restricted limits (than the min/max of the device) that better suit local conditions. It MUST be read only[/INDENT]

CurHumidty
[INDENT]These fields MUST be Card or Float and must have a Range limit of 0 to 100, representing a humidity percentage, in this case for an internal humidity measurement. It MUST be read only.[/INDENT]

CurTemp
[INDENT]Fields of this type MUST be Int and read only. It represents an internal temperature, as opposed to an external one. It MUST have a Range limit, and it is RECOMMENDED that the user be able to provide more range restricted limits that are more suited to local conditions. It MUST be read only[/INDENT]

CurWeather
[INDENT]Fields of this type MUST be of read-only and of String type and provide a short description current weather conditions. This is not a forecast value, but the short descriptions typically provided by weather drivers, such as Cloudy, Rainy, etc... Forecast fields have their own type.[/INDENT]

CurWeatherFC
[INDENT]Fields of this type MUST be read-only and of String type and provide a current weather forecast. This is for the longer form forecast description, as opposed to the short (Rainy, Cloudy, etc...) description that is provided by CurWeather.[/INDENT]

DigitalIO
[INDENT]The field MUST be Boolean, and MAY be either read, write, or read/write depending on wheather it's an input, or output. Inputs MUST be read only. Outputs MUST be at least writeable, but typically are read/write since most devices will report the current state.[/INDENT]

Dimmer
[INDENT]A Dimmer is used to control the level of a dimmable lighting load. In theory it could be used for something that's not a light, but that is its primary purpose. It MUST be a Cardinal field, with a numeric range limit of 0 to 100. Map the actual device values into that percentage range. It MUST be both readable and writeable.[/INDENT]

DriverMoniker
[INDENT]The field MUST be of String type and holds a driver moniker. Typically it would be read only, but not necessarily. It's unlikely any auto-generation tools would make use of such a field, but it's there for field selection filtering to find such fields if desired.[/INDENT]

Generic
[INDENT]Any field not specifically marked will be of the Generic type. You wouldn't ever specific mark a field Generic, you'd just use the field registration method that doesn't take a semantic type.[/INDENT]

HighSetPnt
[INDENT]These types of fields MUST be of type Int and have a range limit that indicates the available range of set point values. It must be at least writeable, and where possible readable.[/INDENT]

HumSensor
[INDENT]These types of fields MUST be Card and have a Range limit of 0 to 100, representing a humidity percentage. It MUST be read only. These are separate for CurHumidity and CurExtHumidity in that these are not implying external or home atmospheric humidity that the user would experience, but other types of humidity sensors.[/INDENT]
Dean Roddey
Software Geek Extraordinaire
Reply
#3
[Split this list because I hit the character limit on the first post]

ItemCookie

LEDStatus
[INDENT]These fields MUST be Boolean. They represent the state of an LED, usually in lighting systems. They MAY be read, write, or read/write depending on the capabilities of the device[/INDENT]

LightSwitch
[INDENT]This type has the same restrictions as the more basic BoolSwitch type. It just provides more specific semantics in that it implies that the thing to be switched is a light, as opposed to something else.[/INDENT]

LowSetPnt
[INDENT]These types of fields MUST be of type Int and have a range limit that indicates the available range of set point values. It must be at least writeable, and where possible readable.[/INDENT]

MediaCookie

MediaRepoDrv

MediaSrc

MediaState
[INDENT]This type provides information about the playback state of a media stream (audio or video.) It lets the clients of the driver know what the current playback state is. This MUST be a read-only, enumerated string field. The enumerated values are listed below and what they mean:
  • Undefined - The state is not one of the standard ones, and can't be reported.
  • Buffering - The device is buffering data from the source, often indicating insufficient data rate
  • Loading - The device is doing the initial location of the media and starting the loading process
  • Playing - Media is currently actively playing back, i.e. not paused.
  • Paused - Media is loaded, but currently paused
  • Stopped - No media is currently loaded. When commanded to stop, the driver should not just pause, but stop and unload media. This allows for moving to the next item in the playlist if applicable.
[/INDENT]

MediaTransport
[INDENT]This type provides transport control over media streams. It must be an enumerated string field, and write only. It MUST provide the following enumerated values: Pause, Play, Stop, Next, Previous, FF, and Rewind. If a given driver cannot handle one of these values, it MUST just ignore the command.[/INDENT]

MotionSensor
[INDENT]The type of these fields ultimately is not very important. Motion sensor fields are assumed to exist purely to represent the motion sensor within the driver and to provide a source field name for motion triggers that get sent out. But they are not expected to hold any useful information. But, for the sake of consistency, the MUST be Boolean fields, and readable since they have to have some sort of access.[/INDENT]


Mute
[INDENT]This type has the same restrictions as the more basic BoolSwitch type. It just provides more specific semantics in that it implies that it controls some audio muting attribute of the owning device.[/INDENT]

Power
[INDENT]In pre-V2 drivers this type of field is used to both get and set the power state of a device, or sub-unit of the device. It must be Boolean and MUST be at least writeable, and hopefully readable though that is not required.

In the V2 world this type of field is used to request a power state change. It doesn't reflect the current power state. It is Boolean and write-only. When written to, the device must begin the transition to the requested power state if not there already. It MAY complete the transition before returning if that happens quickly, but it is not necessary. See the PowerState type below.[/INDENT]

PowerState
[INDENT]This type is primarily used by the Power device class, and provides a standard means of indicating power status (which can be more complex than just Off and On.) It MUST be a read only, enumerated string field, with the following values:
  • Off - The device is fully off.
  • Starting - The device has been powered on but is not yet ready.
  • Ready - The device is powered up and ready.
  • Stopping - The device is still powered on but is stopping.
  • Failed - The device is powered on, but has failed to start for some reason and likely will not change without manual intervention of some sort.
The Power device class uses it conjunction with the Power field, see the Power type above.[/INDENT]

Relay
[INDENT]This field must be of Boolean type and at least writable. Typically it will be readable as well, but that is not required.[/INDENT]

RFIDTag

SecZoneStat
[INDENT]This field MUST be a read only string field, with an enumerated limit that indicates the possible zone statuses. It is REQUIRED that these match the standard zone trigger states of Secure, Not Ready, and Violated, with an extra value of Unknown to deal with states outside of the V2 understanding of zone states. If further state information is required, then a separate, driver specific, field must be provided for each zone. This is somewhat limiting but required in order to generate portable security oriented logic and interfaces. The values means:
  • Secure - The zone is secure, without concern for whether the containing area is armed or disarmed, i.e. the window is closed, the door is closed, etc...
  • Not Ready - The zone is not secure, but its owning area is not in alarm, so it currently doesn't technically constitute a security problem.
  • Violated - The zone is not ready, and the owning area is in alarm.
  • Unknown - The state of the zone is not provably one of the above standard states.
[/INDENT]

SourceInp
[INDENT]This field MUST be either a String field that contains the name of a source input, or a Card field that indicates an input number. In a given device class these fields may be readable or writeable, or both, depending on device capabilities, but will typically be read/write. If writeable, then it MUST have an Enum or Range limit that indicates the available settable inputs (or input modes.)[/INDENT]

TempSensor
[INDENT]This field MUST be Int or Float and represents the value of a temperature sensor. If possible it SHOULD have an appropriate Range limit so that it can be used in various display widgets. It MUST be read only. These are separate for CurTemp and CurExtTemp in that these are not implying atmospheric temps that the user would experience, but other temp sensors for things like water temperature and the like[/INDENT]

TitleCookie

TunerFreq
[INDENT]These fields MUST either be a String with a pre-formatted tuner frequency in it, or a floating point value that contains the integral and fractional kilo/megahertz of the frequency. Though it MAY be writeable to set the frequency, no assumptions are made about that wrt to this type. It's assumed it's just for display.[/INDENT]

Volume
[INDENT]These fields MUST be percentage ranges, Card fields with a Range limit of 0 to 100. Any other scale is not allowed. We have to standardized on a percentage based scale for portability reasons. It can be read, write, or read/write depending on the capabilities of the device.[/INDENT]

VolumeAdj
[INDENT]These fields MUST be Boolean, where writing False to them reduces volume and writing True increases volume. It MUST be write only, so that multiple writes of the same value will be forward to the driver.[/INDENT]
Dean Roddey
Software Geek Extraordinaire
Reply


Possibly Related Threads...
Thread Author Replies Views Last Post
  Semantic Field Type Discussion Dean Roddey 18 3,515 06-23-2014, 08:29 AM
Last Post: Dean Roddey

Forum Jump:


Users browsing this thread: 1 Guest(s)