udmi

UDMI / Docs / Specs / Tech Stack

UDMI Technology Stack

The complete UDMI specification (super set of the base schema), specifies a complete technology stack for compliant IoT devices.

Core Requirements

• Google Cloud’s MQTT Protocol Bridge.
  • This is not the same as a generic MQTT Broker, but it is compatible with standard client-side libraries.
  • Other transports (non-Google MQTT, CoAP, etc…) are acceptable with prior approval.
  • Connected to a specific Cloud IoT Registry designated for each site-specific project.
• Utilizes the MQTT Topic table listed below.
• JSON encoding following the core schema definition, specifying the semantic structure of the data.

MQTT Topic Suffix Table

Type	Category	subFolder	MQTT Topic Suffix	Schema File
state	state	n/a	{topic_prefix}/state	state.json
config	config	n/a	{topic_prefix}/config	config.json
pointset	event	pointset	{topic_prefix}/events/pointset	pointset.json
system	event	system	{topic_prefix}/events/system	system.json

For GCP implementations the full topic would be /devices/{device_id}/{suffix}

Backend Systems

Any backend system (in a GCP project) should adhere to the following guidelines:

• All messages to/from the devices should conform to the UDMI schema payloads (pass validation).
• All exchanges with the devices should go through a PubSub topic:
  • The state and event messages are published to a topic configured through the IoT Core registry.
  • If necessary, any config or command messages should go through a PubSub topic, and then converted to the requisite Cloud IoT config write using a simple cloud function.
• To make data persistent, it can be written to a back-end database. See the udmi_target and udmi_state example cloud functions for details.
• A similar function called device_config shows how PubSub can be used to update the Cloud IoT configuration.

A config push can be tested with something like:

gcloud pubsub topics publish target \
    --attribute subFolder=config,deviceId=AHU-1,projectId=bos-daq-testing,cloudRegion=us-central1,deviceRegistryId=registrar_test \
    --message '{"version": 1, "timestamp": "2019-01-17T14:02:29.364Z"}'

The reason for the redirection of any data through a PubSub topic is so that the Cloud IoT registry, if necessary, can be housed in a different cloud project from the backend applications.

Types and Topics

When using the GCP Cloud IoT Core MQTT Bridge there are multiple ways the specific schema used during validation is chosen.

• All messages have their attributes validated against the .../attributes.json schema. These attributes are automatically defined server-side by the MQTT Client ID and Topic, and are not explicitly included in any message payload.
• A device event message is validated against the sub-schema indicated by the MQTT topic subFolder. E.g., the MQTT topic /devices/{device-id}/events/pointset will be validated against .../pointset.json.
• Device state messages are validated against the .../state.json schema on /devices/{device-id}/state MQTT topic.
• (There currently is no stream validation of device config messages, which are sent on the /devices/{device-id}/config topic.)

This site is open source. Improve this page.