UDMI / Docs / Guides / Telemetry Implementation Notes
UDMI offers a lot of flexibility for the messages associated with telemetry. There are some aspects of telemetry concepts in general that might warrant additional clarification on projects in order to provide a consistent implementation across installations.
UDMI stipulates that units of measure must be provided if the telemetry value is numeric, but does not prescribe what system to use to represent them. There are a number of systems that could be considered that offer unambiguous fixed numeric or fixed string codes for units of measure.
The Unified Code for Units of Measure (UCUM) is a system of codes for unambiguously representing units of measure. Its focus is on machine-to-machine communication, and various tools exist to aid with validation and conversion.
The BACnetEngineeringUnits enumeration from the BACnet protocol specification provides a standardised numeric identifier for the unit of measure associated with a BACnet property value, ensuring that BACnet devices can unambiguously interpret engineering units without relying on free-text strings.
The Digital Building Ontology project provides a list of units of measure as strings.
QUDT (Quantities, Units, Dimensions, and Data Types) is an ontology that provides a standardised, machine-readable framework to represent physical quantities, their units and dimensions, enabling unambiguous interpretation and conversion.
A core design philosophy of UDMI is that at any one time, one device has one current configuration. This configuration specifies a number of aspects that relate to telemetry, such as which points are included within the pointset sent by the device.
If a target system requires just 1 point from a device, and a separate target system requires 10 points from the same device, the configuration will need to contain all 11 points. That is, both target systems will receive all 11 points.
Further, if the former target system requires the 1 point to be sent every minute, and the latter target system requires all 10 points to be sent once every 24 hours, then both target systems will receive all 11 points every minute.
UDMI stipulates that numeric values must be serialised as a JSON number, and the associated units must be provided separately in metadata. That is, numeric values are sent on the wire as numbers only in the events/pointset message. It is up to the target systems to apply or suffix the meaning (the units of measure) when interpreting or displaying the number.
A similar stipulation is not explicitly made for boolean values, although it could be encouraged to serialise boolean values using the true and false JSON literals. This may appear to work well for boolean points such as 'pump run status' (where it could be presumed that true means 'pump running'), but the interpretation could be less clear for boolean points such as 'door open status' (where it may not be clear if true means 'open' or 'not open'). UDMI does not have a dedicated construct to store the fixed meanings of true and false within metadata currently, and so it would be up to the target systems to capture and apply the meaning when displaying the boolean value.
Likewise there is no stipulation made for enumerated, or 'multi-state', values which are commonplace in smart building systems. Communication protocols such as BACnet, KNX, DALI and OPC all have standardised notions of enumerated, or 'multi-state' points, and they all transmit their values on the wire by using fixed integers to represent the ordinal. These fixed integers all have fixed meanings. UDMI does not have a dedicated construct to store the meanings of integers within metadata currently, and there is no concept of an enum data type in JSON. At present, UDMI is unopinionated on whether the integer value is sent, or a string representation of the fixed meaning.
For both boolean and enumerated values, the decision as to whether to send the values in their source form (typically true, false, or an integer), or whether to send their fixed meanings as a string, should be influenced by the capabilities of the target systems and their associated ETL pipelines. The decision may also be influenced by the capabilities of any writeback mechanism that the systems may implement.
UDMI has a construct to control the tolerance for change of value updates for numeric points, but there is no construct to selectively enable or disable change of value updates for boolean or string points.
The status of a point can be used to give additional context to the value of a point. For example, a temperature sensor point could have a value of -3276, and an accompanying status for the point could provide the context that the point is deemed to be in 'fault', and therefore the value should perhaps be considered invalid.
In UDMI the status of a point is conveyed in a separate message to the value of the point, which could arrive at separate times. This is different to other protocols such as BACnet where the status of a point is conveyed at the same time within the same 'object' as the value. In UDMI the status of a point is sent in the /state message, whereas the value of a point is sent in the /events/pointset message.
This is worth being cognisant of for target systems that make decisions based on the value of points. If a /state message isn't received before an associated /events/pointset message, the target system could make decisions based on a potentially invalid value.
UDMI does not prescribe the order of messages in this scenario, but it could be considered beneficial to ensure that /state messages are sent prior to any corresponding /events/pointset messages, so that the target system can correctly contextualise upcoming values.
UDMI stipulates that a device must subscribe to its associated /config topic with QoS 1. UDMI does not stipulate what QoS a device should use when publishing messages.
UDMI does not stipulate other features of MQTT such as LWT, retained messages, or persistent or clean sessions.
UDMI stipulates the names for the lower topic levels that a device must use when publishing messages. It does not stipulate the names to use for the higher topic levels, nor its structure.
Some MQTT implementations, such as ClearBlade IoT Core's MQTT bridge, stipulate what the complete topic structure and naming must be. In the case of ClearBlade IoT Core, for an /events/pointset message from device FCU-1 it would mandate the topic structure and naming below.
/devices/FCU-1/events/pointset
Using this topic structure and naming may not be possible if an installation is using a regular MQTT broker that is shared across multiple sites. In this case it may warrant introducing a site code in the first level of the topic structure to provide namespace isolation for devices across different sites, such as the example below.
GB-LON-HQ/devices/FCU-1/events/pointset
US-NYC-HQ/devices/FCU-1/events/pointset