Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Get Started with Trust Onboard

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

If you have the Twilio Broadband Developer Kit from Twilio SIGNAL 2019 or from the Microsoft Build 2019 conference, this Quickstart is for you.

How do you get a Twilio Developer Kit for Broadband IoT?

If you don’t yet own a Developer Kit, you can order one via the Console. You’ll need a Twilio account to complete the order, but clicking on the link above will walk you through the setup process.

What’s in the Twilio Developer Kit for Broadband IoT?

  • Twilio Programmable Wireless SIM with Trust Onboard.
  • Raspberry Pi Model 3 B+.
  • Seeed LTE Cat-1 Cellular Hat and antennas.
  • I2C Temperature and Humidity sensor.
  • I2C OLED display.
  • Micro SD card and adapter.
  • Power adapter and switch.
  • Micro USB cable.
  • Ethernet cable and USB-to-Ethernet adapter.

To complete this guide you will also need your computer.

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

Configure your Azure IoT Hub

First of all, we want to sync the Device Certificate from our 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 portal.azure.com.
  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 we’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 we’ll need it soon:

Sync Device Certificates to Microsoft Azure

  1. Go to the Twilio Console and navigate to the Trust Onboard page.
  2. In the Microsoft Azure IoT box, click Sync:
  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:
  5. Look for a green 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 Developer Kit ready.

Developer Kit setup

The software

Before you assemble the hardware, you should update 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; you can download the latest version here. We recommend the latest ‘buster’ image, but also provide ‘stretch’ images for folks who prefer that version.
  • Unpack the downloaded .bz2 archive into a .img file.
  • Put the Micro SD card into the adapter and connect it to your computer.
  • 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 hardware

  1. Fit the Micro SD card into the slot on the underside of the Raspberry Pi:
  2. Turn the Pi over:
  3. 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:
  4. Slot the LTE Pi Hat onto the Pi’s GPIO header:
  5. Connect the two bundled cellular antennas to the LTE Hat, one to the connector marked LTE Main, the other to LTE Div:
  6. Connect the small USB adaptor to the micro USB port on the LTE Hat and a full USB port on the Pi.
    Note Don’t connect this cable to the micro USB port on the Pi!
  7. Connect the display and the temperature sensor. Their modules have connectors that each take one of the bundled 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:
  8. Power up the Pi by plugging the bundled AC adapter into the wall and the micro USB end into the Pi. The supplied adapter will deliver the 12.5W minimum needed to fully power both the Pi and the cellular modem. Flip the switch on the power cable to power up the Kit:

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

The Pi’s power indicator is red and located in front of the Micro SD card slot. The Pi also has a green system activity light which will flash as the unit boots up; when it stops, you’re ready to log in.

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.

Connect your computer to the Developer Kit

Connect the bundled Ethernet cable to the Pi’s Ethernet port, and connect the other end of it to your computer using the supplied USB-to-Ethernet adapter:

The version of the Pi OS that we provide will automatically put the Pi at address 192.168.253.100. Windows users should use PuTTY or Powershell’s built-in SSH client, while Unix and macOS users can use ssh in a terminal to log into the Pi.

If you are on a shared computer or you have used a previous version of the firmware, you might see a certificate error. Follow the steps presented in the error message to remove the server key and try again.

  1. When the green light on the Pi (not the Hat) stops blinking enter:
    ssh pi@192.168.253.100.
    Note If the connection times out, your computer may not have received an IP address from the Pi. Try reconnecting the Ethernet-USB adapter and check your computer’s network settings to ensure it is getting an address and not setting one itself.
  2. When you see the password prompt, enter raspberry.

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:

  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 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.

Build an Azure app

Sending data from device to the cloud

We now want to start sending data from our IoT device to the Azure IoT Cloud. We need to install the Azure command line tool so that we can monitor all of the events that get sent. Let’s do that out first.

  1. Open a second terminal or process (if applicable). You will need to monitor Azure in one window and keep your SSH connection with the Developer Kit open in another.
  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 Developer Kit 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. At the command line on your Developer Kit SSH session, store the ID Scope in a text file:
    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 Developer Kit:
    /usr/share/trust_onboard/samples/azure-iot/python/twilio_trust_onboard_azure.py​

With these few steps, you’re sending data to the cloud. Watch the Azure CLI monitor in the terminal and the Developer Kit’s 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

In this section, we’ll concentrate on getting data from the cloud to the Developer Kit. We’re going to use commands sent by the cloud to switch the Kit’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 Python demo application back on:
    /usr/share/trust_onboard/samples/azure-iot/python/twilio_trust_onboard_azure.py​
  2. From another other terminal or process — but 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 Developer Kit’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 Developer Kit:

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 in the previous section 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 Developer Kit’s console that looks similar to 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 the Twilio Developer Kit for Broadband IoT, why not try it now? You’ve performed the key Developer Kit set-up 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 from the Developer Kit 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 browsing the Twilio tag on Stack Overflow.