X-LINUX-AZURE expansion package

Coming soon

1. 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-AWS Starter package: TODO.
• X-LINUX-AZURE Distribution package: an OpenEmbedded meta-layer to be added on top of the STM32MPx Distribution Package to generate AZURE expansion package.

2. X-LINUX-AZURE package software setup

As prerequisite, you must have set up an iotedge device on Azure IoT Hub or Azure IoT Central to connect it.

Please refer to Azure IoT Hub documentation or Azure IoT Central documentation to start.

You also need a direct internet connection. For connection with proxy, refer to Azure IoT Edge documentation

On STM32MP2-eval (cut 1.1), only the first ethernet port (the closest to the power supply) is working for internet connection

2.1. Configuration with DPS provisioning and 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 key in 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

2.2. Configuration without DPS and authentication via x509 certificate and private key stored in OP-TEE

Warning

Not available yet on MP2

• Set the PKCS11 paths

 export PKCS11_LIB="/usr/lib/libckteec.so.0"
 export OPENSSL_CONF_FILE="/etc/pki/openssl-pkcs11-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 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

• Make the directory if doesn't exist and change ownership to aziotcs and set 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 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

• Change openssl pkcs11 engine configuration file

 sed -i "s/##pkcs11_pin##/${PKCS11_USER_PIN}/g" ${OPENSSL_CONF_FILE}

• Generate certificate

 OPENSSL_CONF=${OPENSSL_CONF_FILE} openssl req -new -x509 -days 3652 -sha256 -engine pkcs11 -keyform engine -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

2.3. Configuration without DPS and authentication via x509 certificate and private key stored in TPM

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

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

2.4. Troubleshooting

2.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 a normal to have 2 errors on EdgeAgent end EdgeHub because they do not have been deployed yet.

2.4.2. Logging

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

 iotedge system logs -- -f

2.4.3. TPM Azure Service issue

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

 systemctl stop aziot-tpmd
 systemctl disable aziot-tpmd

3. How to run the Simulated Sensor Module

3.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 few minutes (~10 minutes), your device should have the following modules installed:
  • edgeAgent
  • edgeHub
  • SimulatedTemperatureSensor

• You also should see messages sent by the module on device raw data section.

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

3.2. On Azure IoT Hub

From device configuration view:

• Click on "Set Modules"
• Choose "Marketplace Module" from the "Add" button.
• On "Simulated Temperature Sensor", click on "Simulated Temperature Sensor" from "Select" button.
• Click on" Review + Create", then click on "Create"

• After few minutes (~10 minutes), your device should have the following modules installed:
  • edgeAgent
  • edgeHub
  • SimulatedTemperatureSensor

• From a console logged to azure or on cloud shell, run the following command to see get the simulated messages:

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

Amazon Web Service

Internet of things

Open portable trusted execution environment

Trusted platform module