Azure IoT cloud monitored and controlled Raspberry Pi Pico

With Azure IoT cloud service, user can controll and monitor Raspberry Pi Pico. Azure IoT Central, one of the Azure IoT service, includes IoT Hub, IoT DPS, device authentification, DB (saving for 30 days) and UI which supports data monitoring, data rule engine and extension services. Some companies use Azure IoT Central as their own business web solution.

To connect Azure IoT Central and use it, device certification, software program, and Central setup will be prepared. In the below steps show how to build all process.

Raspberry Pi Pico configuration

Refer the below link to configure Raspberry Pi Pico in Window 10.

https://www.hackster.io/lawrence-wiznet-io/how-to-setup-raspberry-pi-pico-c-c-sdk-in-window10-f2b816

Generate new X.509 cert.

For security commnunication between Raspberry Pi Pico and Azure IoT Central, new device certification will be registered to IoT Central. X.509 cert. can be generated by Openssl as self-signed Root CA cert.

https://docs.microsoft.com/en-us/azure/iot-hub/tutorial-x509-openssl

1. Create the root CA directory structure

Run Window command prompt app and type the below commands. root CA directory will be created to any folder in PC driver.

mkdir rootca
cd rootca
mkdir certs db private
touch db/index
openssl rand -hex 16 > db/serial
echo 1001 > db/crlnumber

touch db/index command is not existed in Window OS. In db folder, index file should be created by manually. (No recommand use fsutil)

2. Create a root CA configuration file

Create rootca.conf file in \rootca\ folder and copy and paste it. commonName is Root CA name and it will be changed as any name.

[default]
name                     = rootca
domain_suffix            = example.com
aia_url                  = http://$name.$domain_suffix/$name.crt
crl_url                  = http://$name.$domain_suffix/$name.crl
default_ca               = ca_default
name_opt                 = utf8,esc_ctrl,multiline,lname,align

[ca_dn]
commonName               = "Test Root CA"

[ca_default]
home                     = ../rootca 
database                 = $home/db/index
serial                   = $home/db/serial
crlnumber                = $home/db/crlnumber
certificate              = $home/$name.crt
private_key              = $home/private/$name.key
RANDFILE                 = $home/private/random
new_certs_dir            = $home/certs
unique_subject           = no
copy_extensions          = none
default_days             = 3650
default_crl_days         = 365
default_md               = sha256
policy                   = policy_c_o_match

[policy_c_o_match]
countryName              = optional
stateOrProvinceName      = optional
organizationName         = optional
organizationalUnitName   = optional
commonName               = supplied
emailAddress             = optional

[req]
default_bits             = 2048
encrypt_key              = yes
default_md               = sha256
utf8                     = yes
string_mask              = utf8only
prompt                   = no
distinguished_name       = ca_dn
req_extensions           = ca_ext

[ca_ext]
basicConstraints         = critical,CA:true
keyUsage                 = critical,keyCertSign,cRLSign
subjectKeyIdentifier     = hash

[sub_ca_ext]
authorityKeyIdentifier   = keyid:always
basicConstraints         = critical,CA:true,pathlen:0
extendedKeyUsage         = clientAuth,serverAuth
keyUsage                 = critical,keyCertSign,cRLSign
subjectKeyIdentifier     = hash

[client_ext]
authorityKeyIdentifier   = keyid:always
basicConstraints         = critical,CA:false
extendedKeyUsage         = clientAuth
keyUsage                 = critical,digitalSignature
subjectKeyIdentifier     = hash

3. Create a root CA

In \rootca\ folder, run Window command prompt app and run the below command to create root CA. Enter PEM pass phrase (any words, more than 5 characters) to generate private.key

openssl req -new -config rootca.conf -out rootca.csr -keyout private/rootca.key
openssl ca -selfsign -config rootca.conf -in rootca.csr -out rootca.crt -extensions ca_ext

4. Create the subordinate CA directory structure

This process is for sub CA in root CA folder, run the below commands. No use touch db/index, manually create index file in db folder.

mkdir subca
cd subca
mkdir certs db private
touch db/index
openssl rand -hex 16 > db/serial
echo 1001 > db/crlnumber

5. Create a subordinate CA configuration file

Create rootca.conf file in \subca\ folder and copy and paste it. commonName should be the diffent name from Root CA commonName.

[default]
name                     = subca
domain_suffix            = example.com
aia_url                  = http://$name.$domain_suffix/$name.crt
crl_url                  = http://$name.$domain_suffix/$name.crl
default_ca               = ca_default
name_opt                 = utf8,esc_ctrl,multiline,lname,align

[ca_dn]
commonName               = "Test Subordinate CA"

[ca_default]
home                     = . 
database                 = $home/db/index
serial                   = $home/db/serial
crlnumber                = $home/db/crlnumber
certificate              = $home/$name.crt
private_key              = $home/private/$name.key
RANDFILE                 = $home/private/random
new_certs_dir            = $home/certs
unique_subject           = no
copy_extensions          = copy 
default_days             = 365
default_crl_days         = 90 
default_md               = sha256
policy                   = policy_c_o_match

[policy_c_o_match]
countryName              = optional
stateOrProvinceName      = optional
organizationName         = optional
organizationalUnitName   = optional
commonName               = supplied
emailAddress             = optional

[req]
default_bits             = 2048
encrypt_key              = yes
default_md               = sha256
utf8                     = yes
string_mask              = utf8only
prompt                   = no
distinguished_name       = ca_dn
req_extensions           = ca_ext

[ca_ext]
basicConstraints         = critical,CA:true
keyUsage                 = critical,keyCertSign,cRLSign
subjectKeyIdentifier     = hash

[sub_ca_ext]
authorityKeyIdentifier   = keyid:always
basicConstraints         = critical,CA:true,pathlen:0
extendedKeyUsage         = clientAuth,serverAuth
keyUsage                 = critical,keyCertSign,cRLSign
subjectKeyIdentifier     = hash

[client_ext]
authorityKeyIdentifier   = keyid:always
basicConstraints         = critical,CA:false
extendedKeyUsage         = clientAuth
keyUsage                 = critical,digitalSignature
subjectKeyIdentifier     = hash

6. Create a subordinate CA

In \subca\ folder, run Window command prompt app and run the below command to create sub CA. Enter PEM pass phrase (any words, more than 5 characters) to generate private.key

openssl rand -hex 16 > ../rootca/db/serial
openssl req -new -config subca.conf -out subca.csr -keyout private/subca.key
openssl ca -config ../rootca/rootca.conf -in subca.csr -out subca.crt -extensions sub_ca_ext

Register X/509 Cert. to Azure IoT Central

1.Create new Azure IoT Central

a. Login Azure service portal https://www.portal.azure.com/

b. Search 'IoT Central' on the top of azure portal web page

c. Create new IoT Central application

d. Fulfill the information

e. Go to resource after finising IoT Central deployment succeeded

f. Go to created IoT Central application web page

2. Register Sub CA to Azure IoT Central

Enter the created Azure IoT Central application from portal and go to Adminstration > Device connection menu. Create new Device Enrollment group and register Sub CA.

After register X.509 Cert, IoT Central requests extra verified Cert. Generate Verificaiton Code and copy it.

Run Window command prompt app in Sub CA folder and the below commands. Type Verification Code into Common Name as the below bash

openssl genpkey -out pop.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl req -new -key pop.key -out pop.csr

  -----
  Country Name (2 letter code) [XX]:.
  State or Province Name (full name) []:.
  Locality Name (eg, city) [Default City]:.
  Organization Name (eg, company) [Default Company Ltd]:.
  Organizational Unit Name (eg, section) []:.
  Common Name (eg, your name or your server hostname) []:BB0C656E69AF75E3FB3C8D922C1760C58C1DA5B05AAA9D0A
  Email Address []:

  Please enter the following 'extra' attributes
  to be sent with your certificate request
  A challenge password []:
  An optional company name []:

In Sub CA folder, run the below command to create the extra verified Cert. And upload to IoT Central.

openssl ca -config subca.conf -in pop.csr -out pop.crt -extensions client_ext

3. Generate Raspberry Pi Pico device Cert.

In Sub CA folder, run Window command prompt app and the below commands. Common Name is device ID will be registered to IoT Central. This device ID will be used in software program. (Please not forget Common Name)

openssl genpkey -out device.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl req -new -key device.key -out device.csr

-----
Country Name (2 letter code) [XX]:.
State or Province Name (full name) []:.
Locality Name (eg, city) [Default City]:.
Organization Name (eg, company) [Default Company Ltd]:.
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server hostname) []:`<your device ID>`
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Run the below commands to finish generating Raspberry Pi Pico device Cert.

openssl req -text -in device.csr -noout
openssl ca -config subca.conf -in device.csr -out device.crt -extensions client_ext

Software programming

1. Download IoT Central example

Download IoT Central example from github.com into C:\RP2040\ folder. azure_central_ll_example.c is the main example code.

https://github.com/joon874/RP2040-HAT-AZURE-C

2. Setup Raspberry Pi Pico Cert.

Setup Raspberry Pi Pico Cert. into C:\RP2040\RP2040-HAT-AZURE-C\examples\sample_certs.c. Copy device.key and device.crt in VS Code

• pico_az_id_scope = Azure IoT Central ID Scope in Web page
• pico_az_COMMON_NAME = device ID registered as Common Name
• pico_az_CERTIFICATE[] = device.key in Sub CA folder
• pico_az_PRIVATE_KEY[] = device.crt in Sub CA folder

const char pico_az_id_scope[] = "[ID Scope]";

const char pico_az_COMMON_NAME[] = "[custom-hsm-device]";

const char pico_az_CERTIFICATE[] = 
"-----BEGIN CERTIFICATE-----""\n"
"-----END CERTIFICATE-----";

const char pico_az_PRIVATE_KEY[] = 
"-----BEGIN PRIVATE KEY-----""\n"
"-----END PRIVATE KEY-----";

3. Description example application Functions

deviceMethodCallback() is callback function for recieved commands from Azure IoT Central. There are 3 types of commands to control Raspberry Pi Pico. "LEDON" and "LEDOFF" are onboard LED control commands. "STOP" command is for finishing Raspberry Pi Pico application.

C:\RP2040\RP2040-HAT-AZURE-C\examples\azure_central_ll_example.c

117 if (strcmp("LEDON", method_name) == 0) {
118 
119     printf("\nReceived device powerReset request.\n");
120
121     const char deviceMethodResponse[] = "{ \"Response\": \"LEDON\" }";
122     *response_size = sizeof(deviceMethodResponse)-1;
123     *response = malloc(*response_size);
124     (void)memcpy(*response, deviceMethodResponse, *response_size);
125
126     gpio_put(ONBOARD_LED, 1);
127
128     result = 200;
129
130 }
...

This example application basically send demo telemetry data, which includes temperature and humidity, to Azure IoT Central every interval time.

374 do
375 {
376     // Construct the iothub message
377     telemetry_temperature = 30.0f + ((float)rand() / RAND_MAX) * 15.0f;
378     telemetry_humidity = 50.0f + ((float)rand() / RAND_MAX) * 20.0f;
379
380     sprintf(telemetry_msg_buffer, "{\"temperature\":%.3f,\"humidity\":%.3f}",
381        telemetry_temperature, telemetry_humidity);
382     IOTHUB_MESSAGE_HANDLE message_handle = IoTHubMessage_CreateFromString(telemetry_msg_buffer);
...

The sending message interval time value is defined as TIME_BETWEEN_MESSAGES

80 #define TIME_BETWEEN_MESSAGES 1000 // ms unit

Setup Azure IoT Central

1. Create Device template

To send commands and recieve telemetry data, Device templates should be created for the target Raspberry Pi Pico.

a. Go to Device templates menu and create New

b. Select IoT device type and click Next

c. Enter device template name and click Next.

d. Then click Create

e. Click Custom model

f. Click + Add capablilty in examples templates

g. Add Telemetry for 'temperature', 'humidity' and Command for 'LEDON', 'LEDOFF', 'STOP' type formats

h. Pulish new device template

2. Create New IoT Device

Before Raspberry Pi Pico connect to Azure IoT Central, IoT device should be created on Devices menu with the same device ID as device Cert.

a. Go to Devices menu and click New

b. Enter device display name and device ID. Then select Device template

c. Click created device and check Commands type on Commands tab

Build and Run

1. Build and Run the application

Run VS Code or Developer command prompt for VS 2019 and build the application. copy main.uf2 file into Raspberry Pi Pico board. Raspberry Pi Pico automatically sends telemetry data to Azure IoT Central

2. Monitoring Telemetry data

Go to Raw data tap on Device page. It shows all telemetry data from Raspberry Pi Pico.

3. Send commands to control Raspberry Pi Pico

Go to Commands tap on Device page. Run 3 types of commands and check the Raspberry Pi Pico board working.

4. Create Dashboard

Azure IoT Central supports Dashboard page for monitoring device. Go to Dashboard menu and create own dashboard for Raspberry Pi Pico.