Overview
AladdinSDS is the service that runs on each POS (point of sale) system and speaks for the Datalogic fixed retail scanners and handheld scanners plugged into it. Toward the store it is the client of the IoT Edge Gateway. It reports the scanners, receives the commands that operators issue from the Datalogic Connect web application and moves firmware and configuration files between the gateway and the scanners. Toward the POS it exposes a local HTTP API and a WebSocket event feed for the applications that run there.
This page describes those flows; the installation steps are in Windows and Linux, the settings in the Configuration reference, and the component itself in the Introduction.
Scanner Discovery
AladdinSDS does not need to be told which scanners are attached. When the service starts, it enumerates the USB and serial ports of the POS, identifies every Datalogic scanner it finds and then keeps listening for scanners that are plugged in or unplugged while it runs. The diagram shows the sequence.
A scanner can be reached over two channels. The host interface, a USB-COM or USB-OEM connection, also carries the barcodes to the POS application. The service port is a second channel that AladdinSDS uses for configuration and firmware without disturbing the host application. Which channels the service monitors is a setting, see USB Device Filtering.
Each scanner is identified by its serial number. A handheld scanner docked on a fixed retail scanner is discovered as a child of that scanner and reported with its parent, so the device tree in the web application mirrors the counter. AladdinSDS also represents the POS itself as a device, identified by a host ID that defaults to the hostname of the POS; commands that concern the service rather than a scanner, such as a restart or an update, are addressed to it.
The models that AladdinSDS manages, and the commands each one supports, are listed under Supported Devices.
Connection to the IoT Edge Gateway
The gateway runs the MQTT broker of the store, and AladdinSDS connects to it as an MQTT client. The address of the gateway is the one setting the administrator must enter after installation, see Edge Gateway Connection; the broker port is 1883 by default, see MQTT Broker Connection. AladdinSDS also listens for a broker announced on the local network through multicast DNS and, if it finds one, prefers it to the configured address.
There is no separate registration call. Connecting and reporting is the registration: as soon as the connection is up, AladdinSDS publishes a connection snapshot that lists the POS and every scanner currently attached, and from then on it publishes a connection report each time a scanner appears or disappears. The gateway forwards each report to the cloud services under the identity of the scanner that produced it. The diagram shows the first connection of a new scanner.
A scanner the organization has never seen appears in the web application as To be approved; until an operator approves it, the gateway does not forward its reports, and if the gateway acknowledges reports it tells AladdinSDS that they were rejected and why. Once approved, the scanner becomes Provisioned and its data starts flowing. The approval is described under Device Approval and Enrollment; the procedure is Enroll FRS/HHS device on Datalogic Connect.
The connection is plain MQTT by default. The configuration reference also describes an encrypted variant on port 8883, with a certificate authority file, a client certificate and a private key placed on the POS, see TLS/SSL Certificates. How the gateway itself accepts device connections is described under How Devices Connect.
What AladdinSDS Reports
AladdinSDS sends three kinds of report to the gateway without being asked. The table lists them; the answers to commands are described under Commands.
| Report | When it is sent | What it carries |
|---|---|---|
| Connection | On connection, when a scanner is plugged or unplugged, and again at a regular interval as a full snapshot | Whether the POS or the scanner is online, its model and, for a docked scanner, its parent |
| Diagnostic | At the telemetry interval, one hour by default, and on request | Properties (model, serial number, firmware version) and telemetry of each scanner; hostname, operating system, CPU, memory and disk of the POS |
| Scan | On every barcode read | The decoded content and the raw data of the barcode |
The telemetry interval is sendTelemetryMs under Agent Behavior.
The gateway can acknowledge each diagnostic report, telling AladdinSDS whether it was forwarded or rejected, for example because the scanner is not yet approved or has been blocked; a report that is not acknowledged in time is sent again. This tracking is off by default. What the cloud services do with the reports is described under Device Data Ingestion.
Commands
A command issued in the web application, or through the Datalogic Connect REST API, reaches the gateway of the store and is delivered to AladdinSDS on the POS that holds the scanner. Each command carries a unique command ID; AladdinSDS answers on a response channel dedicated to that ID, so the cloud services can match every answer to the command that caused it. The diagram shows one command.
Commands come in two kinds:
- Short commands, such as Beep, Reset, Get Logs, enable or disable the scanner, read its configuration, information, health or statistics. They answer once, with the result.
- Long-running commands, such as a firmware update or Change configuration with an SDS package. They answer several times: progress updates while the work runs, then the final result. The cloud services show the command as
IN_PROGRESSuntil that final answer arrives, see Command Lifecycle.
A scanner executes one command at a time. When a scanner is busy, a short command is queued and runs as soon as the scanner is free, while a long-running command is refused so that a firmware update is never interrupted by another one. A queued command that cannot run within a short time is discarded and reported as failed; a command that reuses an ID still in progress is refused.
The same commands are available to local applications through the HTTP API, see Local Integration; a command that arrives locally goes through the same execution path and the same busy rule.
File Transfer
Firmware images, configuration files and SDS packages are stored on the cloud services, but the POS never downloads them from the Internet. A command that carries a file references it by a path on the gateway; AladdinSDS asks the gateway for the file over HTTP on port 8090, checks that the POS has enough disk space, downloads it into its download folder and reports the download progress as part of the command. The first request for a file makes the gateway fetch it from the cloud; later requests from the same store are served from the copy the gateway keeps, see File and Package Distribution.
The same port carries the other direction. A file produced on the POS, such as the logs collected by Get Logs, is uploaded to the gateway under the command that requested it; the gateway forwards it to the cloud services as the response attachment of that command, and the web application offers it under View response.
The protocol and port of the gateway file service, and the download folder on the POS, are set under File Transfer Service.
SDS Packages
An SDS package is a ZIP file created in the Aladdin application for one scanner model. It may contain a firmware image, a configuration file, or both, together with a manifest that names the target model and says whether the scanner must be reset afterwards. How to create one is described in SDS Package Generation; how to send it to the scanners of an organization, in the Configurations Page.
A package reaches AladdinSDS in one of three ways: as the attachment of a Change configuration command from the cloud, through the local HTTP API from an application on the POS, or by being placed in the download folder, from where AladdinSDS picks it up and applies it to every attached scanner of the matching model. Whatever the way, the package goes through the same phases. The diagram shows them.
- Extract and validate. AladdinSDS unpacks the package and compares its manifest with the scanner: the model must match, and the firmware release and configuration in the package are compared with the ones on the scanner. A package for another model fails here. A scanner that already has both the firmware and the configuration of the package is reported as completed without any change.
- Firmware upgrade, only if the release differs. The scanner restarts at the end; AladdinSDS waits for it to come back before going on.
- Configuration, only if the configuration differs. The configuration file is written to the scanner, and the scanner is reset if the package asks for it.
- Completion. The result of both steps decides the final answer to the command, and the extracted files are cleaned up.
Every phase is reported as progress on the command and as a status event on the local WebSocket feed, so an operator in the web application and an application on the POS follow the same execution.
Offline Behavior
AladdinSDS does not depend on the gateway to do its local work. If the gateway cannot be reached when the service starts, the service starts anyway: scanners are discovered, the local HTTP API and the WebSocket feed work, and the service keeps trying to connect at increasing intervals until the gateway answers. When the connection comes up, or comes back after an interruption, AladdinSDS re-subscribes to the commands of every attached scanner and publishes a fresh connection snapshot and the telemetry of every scanner, so the gateway and the cloud services see the current state and not the state before the outage.
Reports produced while the connection is down are held in memory and delivered when it returns; they do not survive a restart of the service, and the snapshot sent at the next connection makes up for them. Commands issued while the POS is unreachable are a matter for the gateway and the cloud services, see Downstream: Commands and Actions.
The gateway also tells AladdinSDS whether it currently reaches the cloud. A gateway that is up but cut off from the Internet keeps accepting reports and stores them for the cloud, see Upstream: Device Data and Events; when it reports that the cloud is back, AladdinSDS publishes its snapshot and telemetry again.
Keeping AladdinSDS Up to Date
The Updater is a separate service, installed by the same installer as the SDS Updater component, that installs new versions of AladdinSDS. AladdinSDS launches it: at a daily hour, when scheduled updates are enabled, and optionally each time the service starts. The Updater downloads a manifest that lists the available versions and, for each platform, the installer, its size and its SHA-256 checksum; if the manifest names a newer version, the Updater downloads the installer, verifies it and installs it, and AladdinSDS comes back at the new version. The manifest URL and the schedule are set under Auto-Update Settings.
An operator can also start an update from the cloud: a command addressed to the POS carries the manifest, or a path to it on the gateway, and AladdinSDS hands it to the Updater, which reports the outcome on the response of that command. Installing a version older than the current one is refused unless the command, or the configuration, allows a downgrade.
The Windows installation guide asks to unselect the SDS Updater component during installation. Follow that guide for the supported setup; the Updater flow above applies only where the component is installed.
Local Integration
Applications running on the POS, or on another machine that can reach it, integrate with AladdinSDS through two published interfaces on port 9000:
- The HTTP API, described in the Aladdin SDS API reference, lists the attached scanners and executes on them the same commands the cloud can send, including a package execution. The interactive documentation is served by the service itself at
/docs, as noted in Windows and Linux. - The WebSocket feed, described in Scanner Events and in the Aladdin SDS WebSocket AsyncAPI documentation, pushes every barcode read and every status change (a scanner connected or disconnected, a command or package progressing) to the subscribed applications without polling.
By default the HTTP API listens on localhost only. To reach it from another machine, change the listening address as described under HTTP API Server, and consider enabling HTTPS on the same page.