Skip to main content

AladdinSDS Configuration

info

The Aladdin SDS ecosystem includes two services, each with its own configuration:

  1. AladdinSDS (this page) - Main scanning/detection service
    Configuration: C:\ProgramData\Datalogic\AladdinSDS\config.toml

  2. Datalogic SDS Updater - Manages service updates
    Configuration: C:\ProgramData\Datalogic\SDSUpdater\config.toml
    → See SDS Updater Configuration

This page documents all configuration sections and options for the main AladdinSDS service.

Configuration File Location​

Windows

C:\ProgramData\Datalogic\AladdinSDS\config.toml

Linux

/usr/lib/AladdinSDS/config.toml

Format Notes​

The configuration uses TOML (Tom's Obvious, Minimal Language) format:

  • Strings must be in quotes: "value"
  • Numbers have no quotes: 1234
  • Booleans: true or false (no quotes)
  • Windows paths: Use double backslashes "C:\\Path\\To\\File"

Configuration Sections​

[agent] - Agent Behavior​

Controls core agent behavior including telemetry, downloads, and logging.

sendTelemetryMs​

  • Type: Integer (milliseconds)
  • Default: 3600000
  • Valid Range: 60000 (1 min) to 86400000 (24 hours)
  • Description: How often the agent sends device telemetry data to the Edge gateway.
  • Examples:
    • 300000 = 5 minutes (frequent monitoring)
    • 3600000 = 1 hour (default)
    • 7200000 = 2 hours (minimal network usage)
[agent]
sendTelemetryMs = 3600000

downloadPath​

  • Type: String (file path)
  • Default: "download/"
  • Description: Directory where SDS packages are downloaded. Supports relative or absolute paths.
  • Windows Recommended: "C:\\ProgramData\\Datalogic\\AladdinSDS\\download"
  • Linux Recommended: "/var/lib/AladdinSDS/download"
warning

Ensure this directory has write permissions and sufficient disk space for package downloads.

downloadPath = "download/"

logLevel​

  • Type: String (enum)
  • Default: "INFO"
  • Valid Values: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "OFF"
  • Description: Controls logging verbosity. Higher detail levels (TRACE, DEBUG) consume more disk space and CPU.
  • Recommended: "INFO" for production, "DEBUG" for troubleshooting
logLevel = "INFO"

[files] - File Transfer Service​

HTTP server configuration for receiving firmware packages and file uploads from devices.

protocol​

  • Type: String (enum)
  • Default: "http"
  • Valid Values: "http", "https"
  • Description: Protocol used for file uploads from devices or external systems.
[files]
protocol = "http"

port​

  • Type: Integer (TCP port)
  • Default: 8090
  • Valid Range: 1024-65535 (avoid privileged ports below 1024)
  • Description: TCP port for the file transfer HTTP server. Used for uploading firmware packages and device configurations.
port = 8090

downloadTimeoutMs​

  • Type: Integer (milliseconds)
  • Default: 3600000
  • Valid Range: 60000 (1 min) to unlimited
  • Description: Maximum time allowed to download a firmware package before timing out.
downloadTimeoutMs = 3600000

[mqtt] - MQTT Broker Connection​

Settings for the MQTT message broker used to communicate with the Edge gateway and cloud services.

clientId​

  • Type: String
  • Default: Auto-generated UUID
  • Description: Unique MQTT client identifier. Must be unique across all clients connecting to the same broker.
  • Format: Any string, typically UUID or hostname format
[mqtt]
clientId = "332f75bb-d0bd-4630-a81d-fa10e3225211"

port​

  • Type: Integer (TCP port)
  • Default: 1883 (unencrypted) or 8883 (TLS/SSL)
  • Description: TCP port of the MQTT broker for device-to-gateway communication.
port = 1883

protocol​

  • Type: String (enum)
  • Default: "tcp"
  • Valid Values: "tcp" (no encryption), "ssl" (TLS encryption)
  • Description: Determines encryption and transport mechanism for MQTT connections.
protocol = "tcp"

username (Optional)​

  • Type: String
  • Description: MQTT authentication username. Uncomment and set if your broker requires authentication.
# username = "aladdin-sds-client"

password (Optional)​

  • Type: String
  • Description: MQTT authentication password. Uncomment and set if your broker requires authentication.
# password = "your-secure-password-here"

[mqtt.certificates] - TLS/SSL Certificates​

Certificate configuration for secure MQTT connections (when protocol = "ssl").

caFilePath​

  • Type: String (file path)
  • Format: PEM encoded .crt or .pem file
  • Default: "./certs/ca.crt"
  • Description: Path to the Certificate Authority (CA) certificate that signed the broker's certificate. Used to verify the broker's identity.
[mqtt.certificates]
caFilePath = "./certs/ca.crt"

crtFilePath​

  • Type: String (file path)
  • Format: PEM encoded .crt or .pem file
  • Default: "./certs/client.crt"
  • Description: Path to this client's public certificate for mutual TLS authentication. Required if broker enforces client certificate verification.
crtFilePath = "./certs/client.crt"

keyFilePath​

  • Type: String (file path)
  • Format: PEM encoded .key or .pem file
  • Default: "./certs/client.key"
  • Description: Path to this client's private key corresponding to the client certificate. Keep this file secure with restricted permissions (owner read-only).
keyFilePath = "./certs/client.key"
danger

Protect the private key file (client.key) - it should only be readable by the AladdinSDS service account.

[http] - HTTP API Server​

REST API server configuration for device management, configuration, and monitoring.

tlsEnabled​

  • Type: Boolean
  • Default: false
  • Description: When true, the API server uses HTTPS instead of HTTP.
[http]
tlsEnabled = false

host​

  • Type: String (IP address or hostname)
  • Default: "localhost"
  • Description: IP address or hostname the HTTP server listens on.
  • Values:
    • "localhost" or "127.0.0.1" = Local access only (secure, default)
    • "0.0.0.0" = Listen on all network interfaces (allows remote access)
    • Specific IP = Listen only on that interface
host = "localhost"

port​

  • Type: Integer (TCP port)
  • Default: 9000
  • Valid Range: 1024-65535
  • Description: TCP port for the REST API HTTP/HTTPS server. Used to access the AladdinSDS API and web interface.
port = 9000

[service] - Service Metadata​

Service version and identification information.

version​

  • Type: String (semantic version)
  • Format: MAJOR.MINOR.PATCH (e.g., 1.1.2)
  • Description: Current version of the AladdinSDS service. This reflects the installed binary version.
[service]
version = "1.1.2"

[edge] - Edge Gateway Connection​

Settings for communicating with the Datalogic Edge gateway for cloud connectivity.

host​

  • Type: String (hostname or IP address)
  • Default: "localhost"
  • Description: Network address of the Edge gateway.
  • Values:
    • "localhost" = Edge running on same machine (development/testing)
    • IP address = Remote Edge (e.g., "192.168.1.100")
    • Hostname = DNS-resolvable name (e.g., "edge-gateway.local")
[edge]
host = "localhost"

[usbDeviceFilter] - USB Device Filtering​

Controls which USB devices the service monitors and manages.

connectionFilter​

  • Type: String (enum)
  • Default: "All"
  • Valid Values:
    • "All" = Detect all Datalogic device connections (default)
    • "Host" = Only manage device host connections
    • "Service" = Only manage device service connections
    • "OEM" = Only manage device OEM host connections
  • Description: Determines which USB devices are detected and managed by the service.
[usbDeviceFilter]
connectionFilter = "All"

[updater] - Auto-Update Settings​

Configuration for the automatic service updater component.

windowsPath​

  • Type: String (file path)
  • Default: "C:\\Program Files\\Datalogic\\SDSUpdater\\DatalogicSDSUpdater.exe"
  • Description: Full path to the SDSUpdater.exe on Windows systems. The service calls this executable to check for and install updates.
[updater]
windowsPath = "C:\\Program Files\\Datalogic\\SDSUpdater\\DatalogicSDSUpdater.exe"

linuxPath​

  • Type: String (file path)
  • Default: "/usr/bin/datalogic-sds-updater"
  • Description: Full path to the sds-updater binary on Linux systems.
linuxPath = "/usr/bin/datalogic-sds-updater"

scheduleEnabled​

  • Type: Boolean
  • Default: true
  • Description: When true, the updater checks for and installs updates on schedule. When false, updates must be triggered manually via API.
scheduleEnabled = true

scheduleHour​

  • Type: Integer (24-hour format)
  • Default: 6
  • Valid Range: 0-23 (0 = midnight, 12 = noon, 23 = 11 PM)
  • Description: Hour of the day (local time) when scheduled update checks run.
scheduleHour = 6

triggerOnStart​

  • Type: Boolean
  • Default: true
  • Description: When true, the updater checks for updates immediately when the service starts. When false, only scheduled or manual updates occur.
triggerOnStart = true

manifestUrl​

  • Type: String (URL)
  • Default: "https://aladdin.datalogic.com/sds/aladdin-sds-manifest.json"
  • Description: URL of the JSON manifest file listing available service updates. The updater fetches this file to determine if new versions are available.
manifestUrl = "https://aladdin.datalogic.com/sds/aladdin-sds-manifest.json"

[commands.beep] - Device Beep Command​

Default parameters for the device beep/buzzer command.

count​

  • Type: Integer
  • Default: 1
  • Description: Number of times the device beeps when the beep command is executed.
[commands.beep]
count = 1

delayMs​

  • Type: Integer (milliseconds)
  • Default: 500
  • Description: Time delay between consecutive beeps.
delayMs = 500

Common Configuration Scenarios​

Enable HTTPS for API Server​

To secure the REST API with HTTPS/TLS:

[http]
tlsEnabled = true
protocol = "ssl"

Configure for Remote Access​

To allow API access from other machines on the network:

[http]
host = "0.0.0.0"
port = 9000

Enable MQTT Encryption​

To use TLS encryption for MQTT communication:

[mqtt]
protocol = "ssl"
port = 8883

[mqtt.certificates]
caFilePath = "./certs/ca.crt"
crtFilePath = "./certs/client.crt"
keyFilePath = "./certs/client.key"

Enable MQTT Authentication​

To authenticate with an MQTT broker:

[mqtt]
username = "aladdin-sds-user"
password = "secure-password-here"

Disable Scheduled Updates​

To prevent automatic updates and require manual update checks:

[updater]
scheduleEnabled = false
triggerOnStart = false

Configure Frequent Telemetry​

To send device telemetry more frequently:

[agent]
sendTelemetryMs = 300000  # 5 minutes instead of 1 hour

After Making Changes​

  1. Backup: Always backup the original config.toml before making changes
  2. Restart Service: Restart the AladdinSDS Windows Service for changes to take effect
  3. Verify: Check the service logs to ensure the service started correctly
tip

Access the service logs in: C:\Program Files\Datalogic\AladdinSDS\ or the user-selected installation folder under log/ directory.