Parameters
The configuration and state of any device can be represented by a list of parameters holding information about the device, including:
· identification: device type and supplier name, software revision, etc.
· status: alarms, voltage, current, temperature, input signal presence and format, etc.
· configuration: user-specified setup parameters (gain, delay, output video format, etc.)
Each parameter is identified with an Object Identifier (OID), and consists of two parts: the descriptor and the value. The descriptor defines the structure of the data, and the value is the content, which is dependent on the descriptor. The descriptor may also specify a constraint, which limits the value to a certain set of valid values.
Object Identifiers (OIDs)
Each parameter is identified by a unique object ID (OID). There are 2 types of OIDs supported: numeric and string. All devices must support numeric OIDs, and may optionally support string OIDs. However, use of meaningful string OIDs is strongly recommended for new designs, as it clarifies code and simplifies the development of CustomPanels. Handling of Numeric and String OID parameters utilize different message types. Devices implementing String OIDs must support both message types.
Numeric OIDs
Numeric OIDs are 2-byte integers, and referenced in this document as a 16-bit hex value, for example: 0x0105. In JSON messaging, numeric OIDs are encoded as strings. For example, the OID 0x0105 is encoded as the string "0x105".
String OIDs
String OIDs allow text-based parameter identifiers, and must follow the following encoding rules:
· Must not contain spaces
· May only contain the following characters: a-z A-Z 0-9 .(dot) _ (underscore)
· Are case sensitive
· There is no set limit to the String OID identifier length; however string OIDs over 255 characters cannot be carried over CAN or TCP/IP binary protocol.
A string OID identifier should not be confused with the parameter name. A string ID is the variable name, the Parameter Name is the display name for the parameter. For example a parameter may have the OID “mle.2.keyer.3.ckey-state” and the parameter name could be “Chroma Key”. Software refers to the value “mle.2.keyer.3.ckey-state”, but the default label on the DashBoard GUI would be “Chroma Key”.
Descriptors
Parameters are defined using a descriptor containing its name, data type, data length, constraint (set of permitted values) and other information. When DashBoard first contacts a device, it requests the list of parameters for that device, and the descriptor for each parameter. This information is used to create an appropriate user interface for the device and to properly interpret and display parameter values reported by the device.
In JSON messaging, descriptor objects are identified by the naming convention _d_oid.
The descriptor for each parameter contains the following fields:
Field |
Description |
oid |
Object Identifier for this Parameter |
version |
Version of the descriptor |
name |
Parameter name to be displayed in a user interface |
data type |
Data type (integer, float, string, or array thereof) |
data size |
Nominal size of the data field |
access |
Read/write access indicator |
precision |
Precision to displayed for printed numbers |
widget |
Graphical display hint for this parameter |
constraint |
An object specifying the set of permitted values for the parameter |
Version
The current version is 2. Permitted versions are 0, 1 and 2. Versions 0 and 1 are identical to version 2, except that widget hints are ignored.
Name
This field provides the parameter name to be displayed in DashBoard. The name does not need to be unique. It may be ignored by some software (e.g. the SNMP agent).
Data Type and Size
Data type indicates the storage type for the parameter value.
Access
This field indicates whether the parameter can be modified. This enables the control software to display an appropriate control for read-only values, or to disallow edits. In OGP, the supported values are:
Access |
Value |
Description |
ACCESS_READWRITE |
0x01 |
Parameter may be modified by the control client |
ACCESS_READONLY |
0x00 |
Parameter is read-only, and may not be set by the client |
Precision
When used with numbers — this field defines the number of digits following the decimal point displayed for printed numbers. It applies mainly to floating point numbers.
When used with string arrays —this field defines the maximum number of bytes reserved for a single element in the array. If it is 0, no limit is set for each element, and the maximum number of bytes in a parameter value is shared arbitrarily amongst all elements in the array.
Constraint
Constraints allow data to be limited to a certain range or certain values.
Widget Hint
The widget hint specifies the type of graphical control that should be used to display this parameter. To ensure backward compatibility with DashBoard 1.0, widget hints are ignored if the version field is less than 2.