Rate this page:

Get Started with Programmable Wireless Trust Onboard

On October 31, 2022, support for Programmable Wireless Trust Onboard will end. On this date, Programmable Wireless Trust Onboard certificates will no longer be available for sync or download in Console. Trust Onboard certificates that have already been synced to your backend services can continue to be used to authenticate devices until the device certificates expire in 30 years’ time. Trust Onboard SIMs will continue to work for connectivity as regular Programmable Wireless SIMs, which can connect to T-Mobile USA’s network in the United States and their global connectivity partners around the world.

This Quickstart guide will help you use a Twilio Programmable Wireless SIM with Trust Onboard to set up your Azure IoT backend, then set up and connect a development device, and finally build and run your first Azure-connected IoT application.

The Raspberry Pi-based development rig

The device side of your application will run on the following off-the-shelf hardware:

  • A Raspberry Pi. This guide was written using the Pi 4 Model B, but there are other versions of the Pi available — it should work with any of them, but we’ve only tested the 400, 4, and 3B. To run the Pi, you will also need:
    • A Micro SD card of 8GB or above.
    • A Micro SD card-to-USB adapter.
    • A monitor and an HDMI-to-micro-HDMI cable.
    • A keyboard and mouse.
    • A 5V, 2A (10W) USB-C AC adaptor.
  • A Seeed LTE Cat-1 Pi Hat for cellular connectivity.
  • A Grove I2C Temperature and Humidity sensor to generate data.
  • A Grove I2C OLED display to show information.
  • A short Micro USB cable.

To complete this guide you will also need your computer.

This guide requires an active Programmable Wireless SIM with Trust Onboard and a Twilio account. You will not be able to proceed without a SIM that has been activated. If you haven’t activated your Programmable Wireless SIM in the Twilio Console, please do so now before proceeding.

1. Configure your Azure IoT Hub

First of all, you need to sync the Device Certificate from your SIM with the Azure IoT backend. This step is needed to validate the SIM when it comes online later. On Azure, you will need to set up an IoT Hub and a Device Provisioning Service (DPS):

  1. On your computer, visit
  2. If you don’t already have an account, sign up for one now.
    Note You can select the Free Trial account to avoid being charged since this tutorial doesn’t require any paid services.
  3. If there’s no menu at the left-hand side of the screen, click the hamburger menu to call it up:
  4. Click Create Resource Group in the menu and then fill in the form that appears as follows:
    • Subscription Select Free Trial if it’s available, or your existing subscription tier.
    • Subscription Resource group Give the group a memorable name.
    • Region Leave this as is:
  5. Click Review + create and then Create.
  6. Select All Resources from the hamburger menu, click + Add, and search for IoT Hub in the list and select it. Click Create then follow the IoT Hub creation steps:
    • Subscription Select Free Trial if it’s available, or your existing subscription tier.
    • Subscription Resource group Select the group you created just now.
    • Region Leave this as is.
    • IoT hub name Give the hub a memorable name:
  7. Click Next: Size and scale.
  8. Under Pricing and scale tier select F1: Free Tier.
  9. Click Review + create and then Create.
  10. Select All Resources from the hamburger menu, click + Add, and search for IoT Hub Device Provisioning Service in the list and select it. Click Create then follow these steps:
    • Name Give your IoT Hub Device Provisioning Service a name.
    • Resource group Select the group you created earlier.
    • Location Leave this as is.
  11. Click Create:
  12. Select All Resources from the hamburger menu. Click on the name of the IoT Hub Provisioning Service you just created. It may not appear immediately, so you may need to wait a moment or two for Azure to finish deploying the resource. If you feel you’ve been waiting too long, click Refresh above the list of resources.
  13. Select Linked IoT hubs in the DPS instance’s left-hand side menu.
  14. Click + Add and add the IoT Hub you created just now.
  15. Under Access Policy select iothubowner.
  16. Click Save:
  17. Click Overview in the DPS instance’s left-hand side menu. Make a note of the DPS’ ID Scope value — copy and paste into a text document — as you’ll need it soon:
  18. Click Shared access policies in the DPS instance’s left-hand side menu.
  19. Select provisioningserviceowner.
  20. Copy the Primary key connection string — click the Copy to Clipboard icon — as you’ll need it soon:

Syncing certificates via the Console will only be valid until October 31, 2022. After that date, customers will need to email Twilio Customer Support in order to obtain a copy of their Trust Onboard certificates, and upload the certificates to Azure manually.

  1. Go to the Twilio Console and navigate to the Trust Onboard page.
  2. In the Microsoft Azure IoT box, click Sync:
    sync with azure
  3. Select your registered Programmable Wireless with Trust Onboard SIM and click Sync.
  4. Paste the Primary key connection string you copied from Azure into the MICROSOFT AZURE CONNECTION STRING field and click Sync:
    Enter your primary key connection string
  5. Look for a success message that you’ve synced.

Your Twilio and Microsoft Azure accounts are now synchronized using the Trust Onboard Device Certificates.

You can confirm this by clicking on SIMs in the sidebar and then selecting your Programmable Wireless SIM with Trust Onboard. Scroll down to the Trust Onboard section and click Download Certificates. This will drop a .zip file named for the SIM’s SID into your downloads folder. Unzip the file and make a note of the first part of the name of the ...-available.pem file.

In the Azure portal, at the Home screen, click All Resources then on the name of your Device Provisioning Service. Now click on Manage enrollments — it’s in the left-hand menu of the DPS readout — and then on the Individual Enrollments tab. Look under Registration ID — you should see an ID that matches the first part of the name of the .pem file you examined above.

Now let’s get your device hardware ready.

3. Device setup

The software

Before you assemble the hardware, you should install the Raspberry Pi’s operating system on the Micro SD card. We have prepared a version of the OS that comes pre-installed with all the tools you will need to complete this tutorial. You can download the latest version here.

  1. Unpack the downloaded .bz2 archive into a .img file.
  2. Put the Micro SD card into the USB card adapter and connect it to your computer.
  3. Write the image .img file to the Micro SD card. If you don’t know how to do this for your computer, we recommend that you download and run Etcher, which will guide you through the process.

The Raspberry Pi Foundation has a very good walkthrough of its own that covers the hardware setup process — you should use this to set your own Pi hardware, but there’s no need to follow its guidance on OS installation. And please don’t power up your Pi yet.

The hardware

You’re now ready to put the hardware together. Just follow these steps. The pictures show the Raspberry Pi 3, but the process is the exactly the same for other versions:

  1. If you have not done so yet, fit the Micro SD card into the slot on the underside of the Raspberry Pi:
    The Pi Micro SD card slot is on its underside
  2. Fit the Twilio Programmable Wireless SIM into the LTE Hat’s SIM slot. The slot takes a Nano-size SIM — the smallest SIM form-factor — so take care removing your Twilio SIM from its mount:
    Slot your SIM into the Hat
  3. Turn the Pi over and slot the LTE Pi Hat onto the Pi’s GPIO header:
    Fit the Hat onto the Pi GPIO pins
  4. Connect the two bundled cellular antennas to the LTE Hat, one to the connector marked LTE Main, the other to LTE Div:
    Connect the antennas
  5. Connect the Micro USB cable between the micro USB port on the LTE Hat and a full USB port on the Pi.
    Connect the Micro USB cable between Pi and Hat
  6. Connect the display and the temperature sensor. Their modules have connectors that each take a four-color cables. The cables fit in only one orientation: if they don’t slide into place smoothly, check that you’re not attempting to insert them the wrong way. Now connect the components to the Hat’s two connectors:
    Connect the display and sensor with the Grove connectors
  7. Connect the Pi to the monitor and keyboard.
  8. Power up the Pi by plugging the AC adapter into the wall and the USB-C cable into the Pi.

Once you connect the Pi to power, it should start up quickly. The Hat has a green light marked PWR to indicate that it is powered up — you can see it in the picture below. Close by is a network light, NET, which will go a steady blue when the Hat is connected to the cellular network:

The Hat’s net and power lights

If the LTE Hat’s blue network light does not light up, or just blinks, check that the SIM is seated correctly (pushed in until it ‘locks’ and with the connectors face up) and has been activated in the Twilio Console.

Test the components

It’s good practice to check that you have correctly connected the temperature and humidity sensor, and the display unit. You can do this by running a few simple Python programs that we have installed for you. If your Pi has booted to the commmand line, run these commands there. If it it has booted to the desktop, as new Pis do, select Terminal from the Raspberry > Accessories menu:

  1. First, test the temperature sensor with the following command:
    python -m grove.grove_temperature_humidity_sensor_sht3x_45
  2. You should see a temperature and humidity value displayed to the Pi console:
    Temperature in Celsius is 23.69 C
    Relative Humidity is 42.39 %

    If not, make sure that the sensor cable is seated correctly at both ends then use sudo shutdown -r now to restart the Pi. Go back to step 1.
  3. Hit ctrl-c to quit the first test program.
  4. Run the command:
    python -m grove.grove_oled_display_128x128
  5. If you were successful, you should see Hello, World! on the attached display.

4. Build an Azure app

Sending data from device to the cloud

You now want to start sending data from your IoT device to the Azure IoT Cloud. First, you need to install the Azure command line tool so that you can monitor all of the events that get sent.

  1. Open a new terminal on your computer.
  2. Install Azure CLI.
    • On Windows, download the official installer and run it. When prompted, allow it to make changes to your computer. Once installed you can use either the Windows Command Prompt or PowerShell to complete the objectives.
    • If you are a macOS user with homebrew installed, run brew update and then brew install azure-cli in a Terminal window.
    • If you aren’t in either of the above categories, go to this page and follow the instructions for your platform.
  3. Login to your Azure account by running:
    az login

    This will pop up a browser window in which you’ll be asked to sign in.
  4. Install the Azure CLI IoT extension:
    az extension add --name azure-cli-iot-ext
  5. Start the monitor:
    az iot hub monitor-events -n YOUR_HUB_NAME

    Replace YOUR_HUB_NAME with the name of the hub (not the DPS) that you created in the Configure your Azure IoT Hub section, above. You will see:
    Starting event monitor, use ctrl-c to stop...

If you experience any problems with step 5, you may need to update an older installation of the Azure CLI IoT extension. Run az extension remove --name azure-cli-iot-ext and then go back to step 4.

Your Raspberry Pi won’t push anything up to the cloud until you tell it to do so. Let’s do that now.

  1. Find the Azure ID Scope that you obtained in the Configure your Azure IoT Hub section.
  2. Hop over to your Pi, store the ID Scope in a text file using the command line and this command:
    echo -n YOUR_ID_SCOPE > ~/azure_id_scope.txt

    So, if your ID Scope is 0ne00000001, you should run echo -n 0ne00000001 > ~/azure_id_scope.txt.
  3. Run the demo app on the Pi:

With these few steps, you’re sending data to the cloud. Watch the Azure CLI monitor in the terminal and the Pi’s OLED display as cloud and hardware interact.

Now it’s time to reverse the flow and make data rain down from the cloud.

Sending data from cloud to device

You’re going to use commands sent by the cloud to switch the Pi’s display from Celsius and Fahrenheit. After you have this working, you’ll have two-way conversations which you can adapt to your own use-case.

Discover your device name

  1. If it’s no longer running, turn the Pi’s Python demo application back on:
  2. From another terminal on your computer — not the one with your Azure monitor — ask the Azure CLI to list all devices associated with your Device Hub:
    az iot hub device-identity list -n YOUR_HUB_NAME

    Replace YOUR_HUB_NAME with the name that you created in the Configure your Azure IoT Hub section, above.
  3. Azure will return and print a list of associated devices in JSON form. Find the deviceId property — this is your Raspberry Pi’s ID — and paste it into a text document for use later.

Send a cloud-to-device message from the Azure CLI

On the command line, send a message to the Pi via Azure:

az iot device c2d-message send -d YOUR_DEVICE_ID -n YOUR_HUB_NAME --data 'Twilio and Azure: Wow!' --props 'units=fahrenheit'​`

Substitute the device ID you got just now for YOUR_DEVICE_ID and replace YOUR_HUB_NAME with your hub’s name. Hit Enter on your keyboard to send the message.

If all went well, in a few seconds you should soon see a message in the Pi’s console that looks something like this:

Received Message [0]:
    Data: <<<Twilio and Azure: Wow!>>> & Size=22
    Properties: {'iothub-ack': 'none', 'units': 'fahrenheit'}

When the next temperature reading is taken, you’ll see your device now displays a Fahrenheit value instead of Celsius.

You can reverse it at any time with a message like this:

az iot device c2d-message send -d YOUR_DEVICE_ID -n YOUR_HUB_NAME --data 'Turning units back' --props 'units=celsius'

Well done — you’ve completed this getting started guide. You have assembled a system that allows an IoT device to securely log data with Microsoft Azure and a means to send command messages via Azure to the device. Now it’s over to you — you can adapt the system you have created to meet the needs of your own use-case. We can't wait to see what you build.

What next?

One of the major benefits of basing your IoT application around Microsoft Azure is the access this cloud platform gives you to additional functionality that can help you gain insights from the operation of your application. One of these is the ability to visualize the data you receive from your devices. We have a follow-up tutorial which adds visualization to the app you have just created — why not continue with it now?

If you haven’t yet run through our guide Get Started with Programmable Wireless and the Raspberry Pi 4, why not try it now? You’ve performed the key device setup tasks already, so you can jump straight in to create an app that uses the popular IoT-centric publish/subscribe messaging protocol MQTT to relay sensor data via the Cloud, and send commands back to the hardware.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more