Skip to main content

Configuration

This page lists the configuration sections and options of the AladdinSDS service, as they appear in its config.toml file. The sections in square brackets are the same on every platform. For what the service does with them, see the Overview; for setup, see Windows Installation or Linux Installation.

Configuration Files​

The location of config.toml, the recommended download folder, the path of the Updater binary and the way to restart the service depend on the platform:

PlatformReference
WindowsWindows
LinuxLinux

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 IoT 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.
  • Recommended values: see Windows and Linux
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 IoT 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 = "<generated-uuid>"

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-mqtt-password>"

[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 = "<installed-version>"

[edge] - Edge Gateway Connection​

Settings for communicating with the IoT Edge Gateway for cloud connectivity.

host​

  • Type: String (hostname or IP address)
  • Default: "localhost"
  • Description: Network address of the IoT 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.

note

This section applies only where the SDS Updater component is installed. The Windows installation guide asks to deselect it during setup.

windowsPath​

  • Type: String (file path)
  • Default: "C:\\Program Files\\Datalogic\\SDSUpdater\\DatalogicSDSUpdater.exe"
  • Description: Full path to DatalogicSDSUpdater.exe on Windows systems. The service calls this executable to check for and install updates. See Windows.
[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 datalogic-sds-updater binary on Linux systems. See Linux.
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

Configure for Remote Access​

To allow API access from other machines on the network:

[http]
host = "0.0.0.0"
port = 9000
warning

The API is then reachable by any host that can reach the POS. Enable HTTPS with tlsEnabled = true in the same section.

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 = "<your-mqtt-user>"
password = "<your-mqtt-password>"

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 back up the original config.toml before making changes
  2. Restart Service: Restart the AladdinSDS service for changes to take effect, see Windows or Linux
  3. Verify: Check the service logs to ensure the service started correctly, see Windows or Linux