Skip to content

UlisesGascon/poc-azure-iot-du-custom-package

Repository files navigation

POC - Azure IOT Hub with Device Update installing custom package

Proof of Concept - how to use custom debian/ubuntu packages with Azure IOT Device Update

Prerequisites

  • Machine/VM/Device with Ubuntu 18.04 (at least 2GB RAM).
  • Azure subscription.
  • Azure IOT Hub. Steps
  • Enable Device Update for Azure IOT Hub. Steps
  • Register an Azure Edge Device in Azure IOT Hub. steps
  • Get familiar with Azure IOT Device Update. Docs
  • Get familiar with how a sample .NET 7.0. application is packed for Ubuntu 18.04 Ref
  • Get familiar with how the custom packages are distributed using a Github Repository. Ref

Notes

  • Ubuntu 18.04 is used as a base OS for this POC. It is possible to use other OS, but it is not covered in this POC. Higher versions of Ubuntu are not supported by Azure IOT Device Update at the moment of writing this POC.
  • In this poc, we will use a custom package that is hosted on a public github repository. It is possible to use a private repository, but it is not covered in this POC.
  • The Ubuntu 18.04 machine should have internet access to be able to download packages from the internet.
  • The Ubuntu 18.04 machine should have access to Azure IOT Hub to be able to download packages from Azure IOT Device Update.
  • The Ubuntu 18.04 used as Operating System is the server version. It is possible to use the desktop version, but it is not covered in this POC.

Steps

Configure Azure IOT Edge Runtime

  1. Install IoT Edge runtime on device
wget https://packages.microsoft.com/config/ubuntu/18.04/multiarch/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
  1. Install Container Runtime
sudo apt-get update; \
  sudo apt-get install moby-engine
  1. Use local logging driver
sudo nano /etc/docker/daemon.json

Replace the content with:

{
  "registry-mirrors": ["http://localhost:5000"]
}
sudo systemctl restart docker
  1. Install IoT Edge runtime
sudo apt-get update; \
   sudo apt-get install aziot-edge
  1. Provision the device with its cloud identity
sudo iotedge config mp --connection-string 'PASTE_DEVICE_CONNECTION_STRING_HERE'
sudo iotedge config apply
sudo cat /etc/aziot/config.toml

Deploy Azure IOT Edge Modules

Follow this steps

To deploy your IoT Edge modules, go to your IoT hub in the Azure portal, then:

  1. Select Devices from the IoT Hub menu.
  2. Select your device to open its page.
  3. Select the Set Modules tab.
  4. Since we want to deploy the IoT Edge default modules (edgeAgent and edgeHub), we don't need to add any modules to this pane, so select Review + create at the bottom.
  5. You see the JSON confirmation of your modules. Select Create to deploy the modules.

It will generate a deployment manifest similar to this one:

{
    "modulesContent": {
        "$edgeAgent": {
            "properties.desired": {
                "schemaVersion": "1.1",
                "runtime": {
                    "type": "docker",
                    "settings": {}
                },
                "systemModules": {
                    "edgeAgent": {
                        "settings": {
                            "image": "mcr.microsoft.com/azureiotedge-agent:1.4"
                        },
                        "type": "docker"
                    },
                    "edgeHub": {
                        "restartPolicy": "always",
                        "settings": {
                            "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
                        },
                        "status": "running",
                        "type": "docker"
                    }
                },
                "modules": {}
            }
        },
        "$edgeHub": {
            "properties.desired": {
                "schemaVersion": "1.1",
                "storeAndForwardConfiguration": {
                    "timeToLiveSecs": 7200
                },
                "routes": {}
            }
        }
    }
}

Note: It might take a few seconds (up to 2 mins) for the portal to reflect the deployments status correctly. Sometimes one of the modules seems to be in status error.

Verify Modules deployment

IOT Edge Runtime

sudo iotedge system status
sudo iotedge system logs
sudo iotedge check

Docker containers

docker ps

Install device update agent on Ubuntu

  1. Install device update agent
sudo apt-get install deviceupdate-agent 
  1. Configure device update agent
sudo nano /etc/adu/du-config.json

Replace the content with:

{
  "schemaVersion": "1.1",
  "aduShellTrustedUsers": [
    "adu",
    "do"
  ],
  "iotHubProtocol": "mqtt",
  "manufacturer": "Contoso",
  "model": "Video",
  "agents": [
    {
      "name": "corretto-machine-edge-01",
      "runas": "adu",
      "connectionSource": {
        "connectionType": "string",
        "connectionData": "PASTE_DEVICE_CONNECTION_STRING_HERE"
      },
      "manufacturer": "Contoso",
      "model": "Video"
    }
  ]
}
  1. Restart the device update agent
sudo systemctl restart deviceupdate-agent
  1. Check the status of the device update agent
sudo systemctl status deviceupdate-agent

Add a tag to your device

Follow this steps

  1. Sign in to the Azure portal and go to the IoT hub.
  2. On the left pane, under Devices, find your IoT Edge device and go to the Device twin or module twin.
  3. In the module twin of the Device Update agent module, delete any existing Device Update tag values by setting them to null. If you're using Device identity with Device Update agent, make these changes on the device twin.
  4. Add a new Device Update tag value.

In our case the tag is:

"tags": {
    "ADUGroup": "test-corretto"
},

Add Custom Package Debian Repository Origin

  1. Add POC - Custom Package Debian Repository public key to your trusted keys
wget -qO - https://raw.githubusercontent.com/UlisesGascon/poc-custom-package-debian-repository/main/PUBLIC.KEY | sudo apt-key add -
  1. Add POC - Custom Package Debian Repository repository as source list
echo "deb https://raw.githubusercontent.com/UlisesGascon/poc-custom-package-debian-repository/main/ bionic main" | sudo tee /etc/apt/sources.list.d/ulisesgascon.list
  1. Update the package list
sudo apt-get update

Note: this step can be automated using ADU

Import and deploy the update

  1. Download the files to your machine:
  1. Import the update Following this steps, but use the files downloaded in the previous step and not the ones mentioned in the example.

  2. Check that the group test-corretto is listed, and that the update is available. Following this steps

  3. Deploy the update Following this steps

Check that the update was applied

  1. Check that demoapi is running.
systemctl -l status demoapi.service
  1. Check that demoapi services is responsive.
curl http://localhost:5000/WeatherForecast

The expected response is similar to:

[{"date":"2023-08-04","temperatureC":4,"temperatureF":39,"summary":"Warm"},{"date":"2023-08-05","temperatureC":-14,"temperatureF":7,"summary":"Scorching"},{"date":"2023-08-06","temperatureC":-14,"temperatureF":7,"summary":"Warm"},{"date":"2023-08-07","temperatureC":-4,"temperatureF":25,"summary":"Chilly"},{"date":"2023-08-08","temperatureC":7,"temperatureF":44,"summary":"Cool"}]

About

poc-azure-iot-du-custom-package

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

 

Packages

No packages published