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: static and dynamic. In the dynamic mode, the gateway functionality is configured dynamically through gateway config messages, which tell it the local devices it should proxy for. In a static gateway configuration, the gateway will be statically configured to proxy a set of devices, essentially ignoring any information in the associated config block.
The general sequence of events for gateway operation is:
- Optional metadata specifies configuration paramaters that should be used at install time to properly (manually) setup the device.
- (dynamic only) On startup, the gateway connects to the cloud and receives a configuration block that details which proxy devices the gateway should proxy for.
- Gateway 'attaches' (Cloud IoT terminology) to the proxied devices, receiving a configuration block for each proxied device. Any attach errors are indicated in the gateway status block and sent along as a logentry event.
- (dynamic only) The proxied device's config block specifies any local connection parameters for the proxied device, e.g. the BacNET device id.
- The gateway proxies communication to/from the device, translating between native (e.g. BacNET) communications and UDMI-based messages.
The gateway config block 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 state and a logentry message 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.
Telemety from the gateway would primarily consist of standard system messages, which provide a running comentary about gateway operation. Specificaly, if there is an error attaching, then there should be appropriate logging to help diagnose the problem.
The gateway metadata block 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 config blocks contain a special localnet 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 "set_value" parameter is 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 similarly 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.
A proxy device metadata section describes localnet with 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.