The gateway functionality is used for systems that have legacy, heritage, or traditional devices that do not communicate directly to the cloud using a MQTT/UDMI connection. For example, an older BACnet based system could use a gateway to translate on-prem communications into UDMI.
The Google Cloud IoT Core Gateway Documentation provides an overview of the cloud-side implementation of a gateway. UDMI, then, specifies an additional layer of specification around the associated message formats.
Conceptually, there are two types of entities involved: the gateway device, and the proxied device. Both of these are ‘devices’ in the sense that they have an entry in a cloud registry and have device-level UDMI data, but they have fundamentally different roles.
There are two modes for gateway operation: implicit and explicit.
In the explicit mode, the gateway functionality is configured dynamically through gateway config messages, which tell it the local devices it should proxy for.
In the implicit gateway configuration, the gateway will be directly configured to proxy a set of devices, essentially ignoring any gateway information in the associated config block.
The general sequence of events for gateway operation is:
The 🧬gateway block in the config simply specifies the list of target proxy devices. On a config update, the gateway is responsible for handling any change in this list (added or removed devices). The details of proxied devices are kept to a minimum here (IDs only) to avoid overflowing the allowed block size in cases where there are a large number of devices.
Any attach errors, e.g. the gateway can not successfully attach to the target
device, should be reported in the gateway block of the state message
A 🧬logentry) message should be used to detail the nature of the problem. If the gateway can attach successfully, any other errors, e.g. the inability to communicate with the device over the local network, should be indicated as part of the proxy device status block.
Telemetry from the gateway would primarily consist of standard messages, which provide a running commentary about gateway operation. Specifically, if there is an error attaching, then there should be appropriate logging to help diagnose the problem.
The 🧬gateway block within the metadata
specifies any information necessary either for the initial (manual) configuration of the device or
ongoing validation of operation. E.g., if a gateway device has a unique MAC address used for local
communications, it would be indicated here.
Proxy devices are those that have a logical cloud device entry (in a registry), and are associated (bound) to a particular gateway. On-prem, the device itself talks a local protocol (e.g. BACnet), but does not have a direct cloud connection.
Proxy Device Full Config Example
Proxy device config contain a special
🧬localnet block section that
specifies information required by the gateway to contact the local device.
E.g., the fact that a device is ‘BACnet’ and also the device’s BACnet object
ID. Based on this, the gateway can communicate with the target device and proxy
all other messages.
Additionally, the gateway is responsible for proxying all other supported operations of the config
bundle. E.g., if a pointset has a
🧬set_value
parameter specified, the gateway would need to convert that into the local protocol
and trigger the required functionality.
There is no gateway-specific state information, but similar to config the gateway is responsible for proxying all relevant state from the local device into the proxied device’s state block. E.g., if the device is in an alarm state, then the gateway would have to transform that from the local format into the appropriate UDMI message.
Telemetry is handled similarly, with the gateway responsible for proxying data from local devices through to UDMI. In many cases, this would be translating specific device points into a pointset message.
Proxy Device Full Metadata Example
The 🧬localnet block within the metadata
describes the presence of the device on a local network. This can/should be used for initial
programming and configuration of the device, or to validate proper device configuration. The gateway
implementation itself would not directly deal with this block.