IoT Edge Gateway
The IoT Edge Gateway is the part of Datalogic Connect that runs inside the store. It is a server, or a virtual machine, that hosts the Azure IoT Edge runtime and a set of Datalogic Connect modules; the devices of the store talk to it over the local network, and it alone talks to the cloud services over the Internet. This page describes what the gateway runs, how it is onboarded, how devices connect to it and how data, commands and files move through it. The installation steps live in Add an IoT Edge Device on Ubuntu and Add an IoT Edge Device on Windows with EFLOW; for the components around it, see Architecture.
Role in the Store
Every store has one gateway. Mobile computers connect to it directly over the local network; fixed retail scanners and handheld scanners connect through the POS they are plugged into, where AladdinSDS speaks for them. The gateway is the only component of the store that needs an outbound connection to the Internet, and it needs no inbound one: the endpoints it must reach are listed under Network Requirements, together with the local ports the devices use to reach the gateway. For the hardware sizing per number of devices, see Supported Devices.
What Runs on the Gateway
The gateway runs as a set of containers managed by the Azure IoT Edge runtime. The table lists the modules of the base gateway, what each one does and the port, if any, that it exposes to the local network.
| Module | What it does | Local port |
|---|---|---|
edgeAgent, edgeHub | The IoT Edge runtime: pulls the modules described by the deployment manifest, keeps them running, routes messages between them and to the cloud | none |
nanomq | The local MQTT broker: the entry point for every device and POS in the store | 1883, 9883 |
MqttTranslationModule | Moves messages between the local MQTT broker and the routing of the IoT Edge runtime, in both directions | none |
DeviceHubModule | Keeps the identity and the approval state of each device, forwards its reports to the cloud and delivers the commands that come back | none |
ProvisioningModule | The certificate authority of the store: issues client certificates to devices and the server certificate of the gateway | 8098 |
StorageModule | Serves configuration and firmware files to the devices and receives the files they upload, such as logs | 8090 |
redis, otelcollector | Local state store and diagnostics of the gateway itself | none |
The ports and their protocols are the ones listed under Network Requirements. Nothing on the gateway is configured by hand: broker, storage, certificate and telemetry settings arrive in the deployment manifest at enrollment, and the operator can see the modules with iotedge list as described in Verify the installation.
The module set depends on the Active manifest chosen when the gateway is created in the web application. The base manifest runs the modules above; other manifests add modules for the use cases they serve. See Add an Edge Device.
Onboarding a Gateway
A gateway becomes part of an organization in three steps: the operator creates it in the web application, installs the runtime on the machine, then enrolls it. The diagram shows the exchange.
- The operator creates an Edge Device with a name, a Serial Number, the Active manifest and the Device IP. The serial number becomes the identity of the gateway; the Device IP must be the static address of the machine, because the gateway issues its own server certificate for that address.
- From the device's Overview page the operator downloads the installation script, which embeds the Scope ID, the Edge Device ID and the Primary Key of the gateway, and runs it on the machine. The script installs the container engine and the IoT Edge runtime and provisions the gateway against the Azure Device Provisioning Service (DPS) with its symmetric key.
- Once the runtime reports
edgeAgentrunning, the operator enrolls the gateway in the web application. The cloud services deliver the deployment manifest; the runtime pulls the module images from the container registry listed under Network Requirements and starts them.
Enrolling before the runtime has finished provisioning can leave the modules unconfigured; the tutorials say when to wait. For the values involved, see Provisioning values.
How Devices Connect
Every device reaches the gateway through the local MQTT broker, in one of two ways.
- Plain MQTT on port
1883. A POS running AladdinSDS connects here by default: its configuration names the address of the gateway and the broker port, see Configuration. A mobile computer enrolled without an enrollment token connects the same way. - MQTT over mutual TLS on port
9883. The device presents a client certificate issued by the gateway. To obtain it, the device contacts the gateway on port8098with the Enrollment code the operator generated on the gateway from the web application, generates its key pair and receives a certificate signed by the certificate authority of the store, valid for that device only. From then on the device connects on9883and no longer needs the code. AladdinSDS can also connect over TLS with a client certificate when its configuration is set to do so.
Connecting is not enough to exchange data. The first time an unknown device connects, the gateway reports it to the cloud services as To be approved and holds its reports until an operator approves it; a Blocked device is ignored. Once approved, the device receives its cloud identity and moves to Provisioned. The approval is described under Device Approval and Enrollment; the procedures are Enroll a Mobile Device and, for scanners on a POS, Enroll FRS/HHS device.
An enrollment without a token needs only port 1883. An enrollment with a token also needs port 8098, for the certificate, and then port 9883, for the connection. If a host firewall blocks them, the token-based enrollment fails while the plain one succeeds. See Add the inbound firewall rules.
Upstream: Device Data and Events
Devices send their data without being asked: a connection event when they go online or offline, their properties (model, serial number, firmware version) and their telemetry (such as battery state). The gateway forwards each report to the cloud services under the identity of the device that produced it, and acknowledges the report to the device, telling it whether the report was forwarded or rejected, for example because the device is not yet approved. A device that stays silent for longer than its keep-alive interval is marked offline by the gateway.
The diagram shows the path of a report, with and without a cloud connection.
When the Internet connection of the store is down, the gateway keeps working locally: devices stay connected, their reports are acknowledged and the IoT Edge runtime stores the messages bound for the cloud on disk. When the connection returns, the stored messages are delivered in order. The buffer has a time limit: messages older than the limit are dropped. What the cloud services do with the reports is described under Device Data Ingestion.
Downstream: Commands and Actions
A command sent from the web application or the REST API, alone or as part of an action on a group, reaches the gateway of the store through the cloud services and is passed to the device over the local MQTT broker: directly for a mobile computer, through AladdinSDS for a scanner connected to a POS. The diagram shows the exchange.
The device may answer twice: first that it accepted the command and is working on it, then with the final result. The gateway relays both to the cloud services, which move the command through IN_PROGRESS to COMPLETED or FAILED; a device that never sends the final answer within the time limit leaves the command FAILED. The statuses and their meaning are described under Command Lifecycle. A command destined for a device that is offline waits at the gateway until the device reconnects or the command expires.
The gateway is a device too: the web application sends it the Enrollment code command, see Edge Devices.
File and Package Distribution
Configuration and firmware files are stored on the cloud services, but the devices never download them from the Internet. A command that carries a file, such as Change configuration or a firmware update, references the file by its path; the device asks the gateway for it on port 8090. The diagram shows what happens on the first and on the following requests.
The first time a file is requested, the gateway downloads it from the cloud storage, verifies its checksum and keeps a local copy; every later request from the store is served from that copy over the local network. Ten POS updating to the same firmware therefore cost one Internet download. The same port carries the opposite direction: a file produced by a device, such as the result of Get Logs, is uploaded to the gateway and forwarded to the cloud services as the response attachment of the command. For the operator side, see Configuration File Distribution.
Status Reporting
The gateway reports on two sides. To the cloud, the IoT Edge runtime reports the state of the gateway and of its modules, and the gateway reports the connection state of every device behind it; the web application shows the gateway on its Overview page and the devices attached to it under Connected Devices. To the store, the gateway publishes on the local MQTT broker whether it is ready and whether it currently reaches the cloud, so that AladdinSDS and the mobile computers can tell a gateway that is down from a gateway that is merely offline from the Internet. The message is retained by the broker: a device that connects later reads the latest state at once.