Add an IoT Edge Device on Ubuntu

Prerequisites

• Before you begin, ensure you have the following:

  • An IoT Edge device added to the Datalogic Connect and noted down the Device ID of the edge device.

  • The device credentials from the edge device credentials page:

  • Scope ID: This is your DPS (Device Provisioning Service) scope identifier

  • Primary Key: The device's primary authentication key

  • Your Organization ID: This identifies your tenant in the IoT Platform

  • SAS Devices Key: Used for device authentication (this is the "SAS-IoT-Devices primaryKey")

  • SAS Smart Enrollment Key: Required for communication between the device and the platform (this is the "API token")

  • SAS Blob Storage URL: The URL for the blob storage associated with your edge device.

You'll need to note these values as they'll be required during the installation and configuration process.

Credential Field Mapping

When you see these fields in the Edge Device Credentials page:

• Scope ID → Use directly as id_scope in configuration
• Primary Key → Use as symmetric_key value in IoT Edge config
• Organization ID → Use as tenantId in Redis configuration
• SAS Devices Key → Use as modulePrimaryKey in Redis configuration
• SAS Smart Enrollment Key → Use as deviceHubApiKey in Redis configuration

Network Requirements

To ensure proper communication between your IoT Edge device and Datalogic Connect services, make sure the following network endpoints are accessible:

Endpoint	Port	Protocol	Notes
*.azure-devices.net	8883, 443	MQTT, HTTPS	Send diagnostic data, receive cloud commands
global.azure-devices-provisioning.net	443	HTTPS	Device provisioning
*.blob.core.windows.net	443	HTTPS	File upload, Docker image pull
crsolinfraprodeuw.azurecr.io	443	HTTPS	Container registry

Firewall Configuration

If your device is behind a corporate firewall, ensure these endpoints are whitelisted to allow proper IoT Edge functionality.

Add an IoT Edge Device on Ubuntu 22.04

1. Install IoT Edge:
   • Installing can be done with a few commands. Open a terminal and run the following commands:

      wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
      sudo dpkg -i packages-microsoft-prod.deb
      rm packages-microsoft-prod.deb

2. Install a container engine:
   • On the Ubuntu device, open the terminal.
   • Install the IoT Edge runtime by running the following commands:

      sudo apt-get update; \
      sudo apt-get install moby-engine

   • Run the following command to create the daemon.json with the local logging driver and restart the Docker service:

        sudo touch /etc/docker/daemon.json && echo '{ "log-driver": "local" }' | sudo tee /etc/docker/daemon.json | sudo systemctl restart docker

Once these steps are completed, the Docker daemon's logging driver will be set to the local logging driver. You can modify the daemon.json file to configure other Docker settings if needed.

3. Install the IoT Edge runtime:

   • On the Ubuntu device, open the terminal.

   • Install the IoT Edge runtime by running the following commands:

      sudo apt-get update; \
      sudo apt-get install aziot-edge
      sudo mkdir -p /srv/redis /srv/mosquitto/log /srv/mosquitto/config /srv/mosquitto/config/certs /srv/MqttTranslationModule/log /srv/MqttTranslationModule/certs /srv/DeviceHubModule/log /srv/DeviceHubModule/certs /srv/DeviceHubModule/config /srv/StorageModule/log srv/StorageModule/config /tmp/edgeAgent /tmp/edgeHub /srv/shared/downloads /srv/otel
      sudo chown 1000 /srv/redis /srv/mosquitto/log /srv/mosquitto/config /srv/mosquitto/config/certs /srv/MqttTranslationModule/log /srv/MqttTranslationModule/certs /srv/DeviceHubModule/log /srv/DeviceHubModule/certs /srv/DeviceHubModule/config /srv/StorageModule/log srv/StorageModule/config /srv/shared/downloads /srv/otel
      sudo echo -e "port 1883\n\n#to enable mTLS uncomment the next three lines and set require_certificate true\n#cafile /mosquitto/config/certs/ca.crt\n#certfile /mosquitto/config/certs/server.crt\n#keyfile /mosquitto/config/certs/server.key\n\nrequire_certificate false\n#use_identity_as_username true\nallow_anonymous true\n#use_username_as_clientid true" > /srv/mosquitto/config/mosquitto.conf
     

   • Configure Storage Module by running the following command:

      sudo nano /srv/StorageModule/config/config.yaml

   • Paste the following configuration, replacing {BLOB_STORAGE_URL} with the value retrieved from the Datalogic Connect in the Blob storage URL field of the edge device configuration:

     app:
       azure:
         blob-storage-url: { BLOB_STORAGE_URL }

   • Configure the Open telemetry collector configuration file by running the following command:

      sudo nano /srv/otel/config.yml

   • Paste the following configuration

     receivers:
       otlp:
         protocols:
           grpc:
             endpoint: 0.0.0.0:4317
     
     exporters:
       debug:
         verbosity: detailed
       azuremonitor:
         spaneventsenabled: true
     extensions:
       zpages:
     processors:
       filter:
         error_mode: ignore
         logs:
           log_record:
             - "severity_number < SEVERITY_NUMBER_WARN"
     
     service:
       extensions: [zpages]
       pipelines:
         traces:
           receivers: [otlp]
           exporters: [debug, azuremonitor]
         metrics:
           receivers: [otlp]
           exporters: [debug, azuremonitor]
         logs:
           receivers: [otlp]
           processors: [filter]
           exporters: [debug, azuremonitor]

   • Configure the IoT Edge configuration file by running the following command:

      sudo nano /etc/aziot/config.toml

   • In the provisioning section, set the following parameters:

     [provisioning]
     source = "dps"
     global_endpoint = "https://global.azure-devices-provisioning.net"
     id_scope = "<SCOPE_ID>"
     
     [provisioning.attestation]
     method = "symmetric_key"
     registration_id = "<DEVICE_ID>"
     symmetric_key = { value = "<PRIMARY_KEY>" }
     
     [image_garbage_collection]
     enabled = true
     cleanup_recurrence = "1d"
     image_age_cleanup_threshold = "7d"
     cleanup_time = "00:00"

     Make sure to replace <SCOPE_ID>, <DEVICE_ID>, and <PRIMARY_KEY> with the values from your device credentials.

   • Run the following command to apply the configuration changes:

      sudo iotedge config apply

Once these steps are completed, the IoT Edge device should be successfully registered and connected to the Datalogic Connect. You can verify the device's status by running the sudo iotedge list command in the device's terminal.

4. Update edge configuration on Redis

   • Run the following command to open redis-cli:

      sudo docker exec -it redis /bin/sh -c 'redis-cli HMSET itmConfig scopeId "<SCOPE_ID>" tenantId "<ORGANIZATION_ID>" modulePrimaryKey "<SAS_DEVICES_KEY>" deviceHubApiKey "<SAS_SMART_ENROLLMENT_KEY>"'
      sudo iotedge system restart

   • Replace the placeholders with your actual values from the device credentials:

     • <SCOPE_ID>: Your Scope ID
     • <ORGANIZATION_ID>: Your Organization ID
     • <SAS_DEVICES_KEY>: Your SAS Devices Key
     • <SAS_SMART_ENROLLMENT_KEY>: Your SAS Smart Enrollment Key

Now the IoT Edge device is successfully connected to the Datalogic Connect and ready to receive and process messages from the leaf devices.