X-LINUX-AZURE expansion package

Applicable for

STM32MP25x lines

---

Important

This version of X-LINUX-AZURE expansion package is validated against the ecosystem release v5.1.0 . It has not been ported yet on ecosystem release v6.0.0 .

1. Article purpose

X-LINUX-AZURE is an OpenSTLinux distribution expansion package that enables the development of your IoT solution by bringing Microsoft^® Azure^® IoT Edge software, which transforms your STM32MPU into an IoT edge device that connects to Azure^® IoT Hub.

The purpose of this article is to explain step by step:

• How to install X-LINUX-AZURE expansion package on top of OpenSTLinux distribution.
• How to configure your IoT edge device to connect to Azure IoT Hub
• How to secure the device identity and cloud connection with the use of OP-TEE or TPM for cryptographic operations with private key secure storage
• How to deploy modules on your IoT edge device

2. X-LINUX-AZURE package software description

2.1. Overview

2.1.1. Connectivity

X-LINUX-AZURE enables your STM32 Arm^® Cortex^® MPUs  to:

• Connect to Azure IoT Hub as an IoT edge device
• Connect client devices to local IoT edge hub (MQTT, AMQP)
• Deploy your own code with custom modules on your IoT edge device

To learn more, see Azure IoT Edge documentation.

2.1.2. Software architecture

The X-LINUX-AZURE Expansion Package provides open-source components that enable you to develop your own IoT solution.

As an example, the X-LINUX-AZURE Expansion Package provides a basic graphical demonstration application to interact with Azure IoT Edge runtime.

2.2. Versioning

The latest version of the X-LINUX-AZURE expansion package is 5.1.0.

Since its release v5.1.0, the major and minor versions of the X-LINUX-AZURE OpenSTLinux expansion package are aligned on the major and minor versions of the OpenSTLinux Distribution. This prevents painful backward compatibility attempts and makes dependencies straightforward.

The X-LINUX-AZURE generic versioning vx.y.z is built as follows:

• x: major version matching the OpenSTLinux Distribution major version. Each new major version is incompatible with previous OpenSTLinux Distribution versions.
• y: minor version matching the OpenSTLinux Distribution minor version. Each new minor version might be incompatible with previous OpenSTLinux Distribution versions.
• z: patch version to introduce bug fixes. A patch version is implemented in a backward compatible manner.

2.3. Associated licenses

See X-LINUX-AZURE licenses.

3. Prerequisites

• Knowledge of the Azure IoT Edge and Azure IoT Hub is advised.
  • Learn about Azure IoT Edge
  • Learn about Azure IoT Hub
• An Azure IoT Hub account is needed to connect your board as a IoT Edge device, you can start with a free account.

Instead of Azure IoT Hub, you can use Azure IoT Central to connect your device.

3.1. Hardware prerequisites

• One STM32 MPU board

STM32MP257x-DKx - hardware description

STM32MP257x-EV1 - hardware description

• TPM development kit (required if TPM is chosen as a secure solution, only available with X-LINUX-AWS Distribution Package).

Refer to X-LINUX-TPM_expansion_package for list of compatible TPM.

• Internet access.
  • For Wi-Fi^® connection, see how to setup a WLAN connection.
  • For connection with a proxy, see how to configure proxy support

3.2. Software prerequisites

The X-LINUX-AZURE expansion package runs with OpenSTLinux ecosystem release v6.0.0 .

4. X-LINUX-AZURE package software installation

There are two possibilities to install the additional X-LINUX-AZURE expansion package software to port on top of OpenSTLinux:

• X-LINUX-AZURE_Starter Package: quickly and easily bring Azure IoT Edge on the STM32 MPU.
• X-LINUX-AZURE Distribution Package: an OpenEmbedded meta-layer to be added on top of the STM32 MPU Distribution Package to generate an image with X-LINUX-AZURE expansion package.

Information

The X-LINUX-TPM expansion package is not delivered as a Starter Package. Consequently TPM cannot be used as a secure solution for X-LINUX-AZURE Starter Package. TPM can be used as a secure solution with the X-LINUX-AZURE Distribution Package.

5. X-LINUX-AZURE package software setup

This section describes how to connect to Azure IoT Edge once the X-LINUX-AZURE expansion package software has been successfully installed on the board.

It shows three methods to connect:

• With DPS (Device Provisioning Server) and symmetric key stored in the file system
• Without DPS (Device Provisioning Server) with keys either stores in:
  • OP-TEE
  • TPM

These three methods can be used with the Distribution Package. The Starter Package does not support TPM.

5.1. Configuration with DPS provisioning: authentication with symmetric key stored in file system

This configuration is used for fast prototyping using IoT Central for example.

Warning

Symmetric key usage is not recommended for production. Storing a key in the file system is not recommended for production. Use OP-TEE or TPM instead.

• Customize the following variables

export REGISTRATION_ID="STM32MP257F-EV1-******"
export ID_SCOPE="0ne******"
export SYMMETRIC_KEY="**********"

• Create a configuration file

cat >/etc/aziot/config.toml <<EOL
# ==============================================================================
# Hostname
# ==============================================================================
hostname = "$(hostname)"

# ==============================================================================
# Provisioning
# ==============================================================================
# DPS provisioning with symmetric key
[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net/"
id_scope = "${ID_SCOPE}"

[provisioning.attestation]
method = "symmetric_key"
registration_id = "${REGISTRATION_ID}"

symmetric_key = { value = "${SYMMETRIC_KEY}" }
EOL

• Apply the configuration

iotedge config apply

5.2. Configuration without DPS: authentication via X.509 certificate and private key stored in OP-TEE

• Set the PKCS#11 paths

export PKCS11_LIB="/usr/lib/libckteec.so.0"
export OPENSSL_CONF_FILE="/etc/pki/openssl-pkcs11-provider-optee.cnf"

• Customize the following variables

export PKCS11_SLOT="1"
export PKCS11_TOKEN_LABEL="AZ_TOKEN"
export PKCS11_KEY_LABEL="AZ_key"
export PKCS11_KEY_ID="0"
export PKCS11_SO_PIN="1234567890"
export PKCS11_USER_PIN="12345"
export DEVICE_NAME="STM32MP257F-EV1-******"
export IOT_HUB_HOST_NAME="******.azure-devices.net"
export CERTIFICATE_CN="$DEVICE_NAME"

• Set the certificate paths

export CERTIFICATE_DIR="/var/aziot/certs"
export CERTIFICATE_NAME="${CERTIFICATE_CN}.pem"

• Create the configuration file

cat >/etc/aziot/config.toml <<EOL
# ==============================================================================
# Hostname
# ==============================================================================
hostname = "$(hostname)"

# ==============================================================================
# Provisioning
# ==============================================================================

# Manual provisioning with X.509 certificate
[provisioning]
source = "manual"
iothub_hostname = "${IOT_HUB_HOST_NAME}"
device_id = "${DEVICE_NAME}"

[provisioning.authentication]
method = "x509"
identity_pk = "pkcs11:slot-id=${PKCS11_SLOT};object=${PKCS11_KEY_LABEL}?pin-value=${PKCS11_USER_PIN}" 

identity_cert = "file://${CERTIFICATE_DIR}/${CERTIFICATE_NAME}"                

[aziot_keys]
pkcs11_lib_path = "${PKCS11_LIB}"
pkcs11_base_slot = "pkcs11:slot-id=${PKCS11_SLOT}?pin-value=${PKCS11_USER_PIN}"
EOL

• Create the directory if it does not exist, change its ownership to aziotcs, and set the permissions

mkdir ${CERTIFICATE_DIR} -p
chown aziotcs:aziotcs ${CERTIFICATE_DIR}
chmod 755 ${CERTIFICATE_DIR}

• Configure PKCS11

pkcs11-tool --module ${PKCS11_LIB} --init-token --slot ${PKCS11_SLOT} --label ${PKCS11_TOKEN_LABEL} --so-pin ${PKCS11_SO_PIN}
pkcs11-tool --module ${PKCS11_LIB} --label ${PKCS11_TOKEN_LABEL} --slot ${PKCS11_SLOT} --login --so-pin ${PKCS11_SO_PIN} --init-pin --pin ${PKCS11_USER_PIN}

• Generate the key pair

pkcs11-tool --module ${PKCS11_LIB} -l --slot ${PKCS11_SLOT} --pin ${PKCS11_USER_PIN} --keypairgen --key-type rsa:2048 --label ${PKCS11_KEY_LABEL} --id ${PKCS11_KEY_ID} --usage-decrypt --usage-sign

• Set the token user pin to be used by the OpenSSL configuration file

echo ${PKCS11_USER_PIN} > /etc/pki/pin.txt

• Generate the certificate

OPENSSL_CONF=${OPENSSL_CONF_FILE} openssl req -new -x509 -days 3652 -sha256 -key "pkcs11:type=private;object=${PKCS11_KEY_LABEL};token=${PKCS11_TOKEN_LABEL}" -subj "/CN=${CERTIFICATE_CN}" -out ${CERTIFICATE_DIR}/${CERTIFICATE_NAME}

• Give aziotcs ownership to certificate and set read and write permission for aziotcs, read-only for others

chown aziotcs:aziotcs ${CERTIFICATE_DIR}/${CERTIFICATE_NAME}
chmod 644 ${CERTIFICATE_DIR}/${CERTIFICATE_NAME}

• Compute certificate fingerprint

openssl x509 -noout -fingerprint -sha1 -inform pem -in ${CERTIFICATE_DIR}/${CERTIFICATE_NAME} | sed 's/://g' | sed 's/.*=//'

• Register the certificate fingerprint generated by the last command on Microsoft Azure IoT Hub and associate it to your device

• Apply the configuration

iotedge config apply

5.3. Configuration without DPS: authentication via X.509 certificate and private key stored in TPM

Information

TPM is not available when installed with Starter Package

Follow the instructions of the previous section (OP-TEE configuration), simply changing the following variables:

export PKCS11_LIB="/usr/lib/pkcs11/libtpm2_pkcs11.so"
export OPENSSL_CONF_FILE="/etc/pki/openssl-pkcs11-provider-tpm2.cnf"

5.4. Troubleshooting

5.4.1. Sanity check

You can check your configuration by running the following command:

iotedge check

If your board has never been connected, it is normal to have two errors on EdgeAgent and EdgeHub because they have not been deployed yet.

5.4.2. Logging

You can see the IoTEdge logs by running the following command:

iotedge system logs -- -f

5.4.3. TPM Azure Service issue

If you are not using a TPM for authentication, you might see TPM issues in logs that prevent connection. You can disable the service if you do not need it:

systemctl stop aziot-tpmd
systemctl disable aziot-tpmd

6. How to run the Simulated Sensor Module

6.1. On Azure IoT Central

• Create a new edge manifest from the following JSON file:

{
    "modulesContent": {
        "$edgeAgent": {
            "properties.desired": {
                "schemaVersion": "1.0",
                "runtime": {
                    "type": "docker",
                    "settings": {
                        "minDockerVersion": "v1.25",
                        "loggingOptions": "",
                        "registryCredentials": {}
                    }
                },
                "systemModules": {
                    "edgeAgent": {
                        "type": "docker",
                        "settings": {
                            "image": "mcr.microsoft.com/azureiotedge-agent:1.0.9",
                            "createOptions": "{}"
                        }
                    },
                    "edgeHub": {
                        "type": "docker",
                        "status": "running",
                        "restartPolicy": "always",
                        "settings": {
                            "image": "mcr.microsoft.com/azureiotedge-hub:1.0.9",
                            "createOptions": "{}"
                        }
                    }
                },
                "modules": {
                    "SimulatedTemperatureSensor": {
                        "version": "1.0",
                        "type": "docker",
                        "status": "running",
                        "restartPolicy": "always",
                        "settings": {
                            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                            "createOptions": "{}"
                        }
                    }
                }
            }
        },
        "$edgeHub": {
            "properties.desired": {
                "schemaVersion": "1.0",
                "routes": {
                    "route": "FROM /* INTO $upstream"
                },
                "storeAndForwardConfiguration": {
                    "timeToLiveSecs": 7200
                }
            }
        },
        "SimulatedTemperatureSensor": {
            "properties.desired": {
                "SendData": true,
                "SendInterval": 10
            }
        }
    }
}

• Assign the manifest to your device
• After about ten minutes, the following modules are installed on your device:
  • edgeAgent
  • edgeHub
  • SimulatedTemperatureSensor

• You can also observe messages sent by the module in the device raw data section.

More information about IoT Edge on IoT Central can be found here.

6.2. On Azure IoT Hub

From the device configuration view:

• Click on "Set Modules"
• Choose "Marketplace Module" from the "Add" button
• On "Simulated Temperature Sensor", click on "Simulated Temperature Sensor" from the "Select" button
• Click on "Review + Create", then click on "Create"
• After about ten minutes, the following modules are installed on your device:
  • edgeAgent
  • edgeHub
  • SimulatedTemperatureSensor

• From a console logged into Azure or on Cloud shell, run the following command to see the simulated messages:

az iot hub monitor-events --device-id YOUR_DEVICE_ID --hub-name YOUR_HUB_NAME