Scalar Item
A data item is a single controllable and/or observable piece of data.
A scalar item is a data item which represents a simple value type such as an integer or string. Scalar items standardize how data is interpreted, how data can be accessed, and any constraints on the value of data.
A scalar item is a single addressable instance of a Scalar Item Class.
In a static UDR file, scalar items must be children of the scalar items object.
Attributes
Instance attributes are per-scalar-item-instance; they can vary between instances of the scalar item.
Class (Required)
Indicates the id of the defined scalar item class of which this is an instance. If the scalar item class is nested within one or more categories, the full path must include the category id hierarchy.
ID (Required)
The id is a unique string identifying this scalar item. This must be unique within the scalar items object within the device class containing the scalar item (or list of scalar items retrieved from a device), unless it is paired with a revision of the same class using the same id (see versioning).
If multiple scalar items are instantiated using the count attribute, each instance will be identified
starting with the unique id followed by the !
delimiter and instance number (starting at 1), and incrementing
by 1 for each instance. For example “id!1” would be followed by “id!2”.
When ordering of multiple scalar item instances of the same class is required, they shall be instantiated either
using the count mechanism described above, or may be manually instantiated with the same unique id followed
by the !
delimiter and an instance number.
The id must remain consistent through revisions of a Device Class, as this uniquely identifies the scalar item.
An example of a complete scalar item instance id for the second intensity scalar item in a device where there are 3
revisions of the intensity scalar item presented might take the form: intensity!2.3
.
Friendly Name
The friendly name attribute provides a string that could be used to identify a particular instance of a scalar item in a software user interface, in order to provide more context to a user. It is not intended to uniquely identify the scalar item in a database.
Count
The count attribute provides a mechanism for instantiating multiple scalar item instances of the same class.
If multiple scalar items are instantiated using the count attribute, each instance will be identified
starting with the unique id followed by the !
delimiter and instance number (starting at 1), and incrementing
by 1 for each instance. For example “id!1” would be followed by “id!2”.
Access and Lifetime (Required)
Access and Lifetime define how the data associated with a scalar item is stored, how it can be changed, and when it is invalidated.
Access defines whether the value of a scalar item can be changed by a user.
Read-Only scalar items cannot be changed.
Read-Write scalar items can be changed.
Lifetime defines how the value of a scalar item is stored.
Static scalar items apply to all instances of a device. This data may or may not be retrievable from an individual device.
Persistent scalar items are individual to a specific device instance, and their data is retained between device power cycles.
Runtime scalar items are individual to a specific device instance, and their data is not retained between device power cycles.
Read-Only |
Read-Write |
|
---|---|---|
Static |
Data that is the same for all instances (units) of a device class. Example: Device Manufacturer. |
N/A |
Persistent |
Data that is per-device-instance and stored persistently but cannot be changed from outside the device. Example: Serial Number. |
Data that is per-device-instance and stored persistently and can be changed from outside the device. Example: User-Assigned Device Name. |
Runtime |
Data that is measured or calculated at runtime and is not retained between power cycles. This is typically status and health data. Example: Temperature Sensors. |
Data that can be changed from outside the device that is not retained between power cycles. This is typically data that is used to trigger the device to do an action. Example: Intensity. |
Minimum
This attribute defines a minimum value for the scalar item. It applies in different ways when combined with different data types. If this attribute and minscalaritem is absent, the minimum is assumed to be 0:
When applied to… |
Minimum indicates… |
---|---|
number |
The number’s minimum value. |
string |
N/A |
binary |
N/A |
boolean |
N/A |
enum |
N/A |
Maximum
This attribute defines a maximum value for the scalar item. It applies in different ways when combined with different data types. If this attribute and maxscalaritem is absent, the maximum is assumed to be 0:
Maximum when applied to…
When applied to… |
Maximum indicates… |
---|---|
number |
The number’s maximum value. |
string |
N/A |
binary |
N/A |
boolean |
N/A |
enum |
The maximum enumerated index. |
Default
This attribute defines a default value for the scalar item. It applies in different ways when combined with different data types. If this value falls outside of the defined or calculated (from one or more other scalar items) min/max, then the nearest in range value shall be used.
If this attribute is provided it overrides any default defined in the scalar item class of which this is an instance.
Default when applied to…
When applied to… |
Default indicates… |
---|---|
number |
The number’s default value. |
string |
N/A |
binary |
N/A |
boolean |
N/A |
enum |
The default enumerated index. |
Minimum scalar item
Indicates the modifier type, and id of another scalar item instance which this scalar item should
observe for a new minimum value. This should take the form modifiertype;id
. The modifier type
must be one of those defined below, and the id must be a valid identifier.
When this attribute is defined and the modifier type is absolute, any discrete value provided in minimum will be ignored.
For scalar items with a data type of number this can be any of the following (all other types shall always use absolute):
addend |
The value provided should be added to that previously defined |
multiplier |
The value provided is a multiplier to that previously defined |
absolute |
The value provided should replace that previously defined |
Maximum scalar item
Indicates the modifier type, and id of another scalar item instance which this scalar item should
observe for a new maximum value. This should take the form modifiertype;id
. The modifier type
must be one of those defined below, and the id must be a valid identifier.
When this attribute is defined and the modifier type is absolute, any discrete value provided in maximum will be ignored.
For scalar items with a data type of number this can be any of the following (all other types shall always use absolute):
addend |
The value provided should be added to that previously defined |
multiplier |
The value provided is a multiplier to that previously defined |
absolute |
The value provided should replace that previously defined |
Children
Scalar items may not have any children.
Markup
UDR Type:
scalaritem
Members:
Key
Value Type
Represents
class
string
id
string
friendlyname
string
count
string
access
string
lifetime
string
minimum
number
maximum
number
default
number
minscalaritem
string
maxscalaritem
string
atomic-data-objects-scalar-item-instance-maximum-scalar-item
Example:
{
"udrtype": "scalaritem",
"class": "org.esta.lib.identification.1/firmware-version",
"id": "my-firmware-version",
"friendlyname": "Firmware Version",
"access": "readonly",
"lifetime": "persistent"
}