Menu

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?

IOT: Twilio Broadband IoT Developer Kit with Trust Onboard SIM

If you received the Twilio Broadband Developer Kit at the Microsoft //build 2019 conference, this Quickstart is for you.

This Quickstart will guide you through registering your Twilio IoT SIM with Trust Onboard in the Programmable Wireless Console, setting up your Broadband IoT Developer Kit, setting up your Azure IoT backend, and running your first IoT application.

broadband-dev-kit.png

This kit comes with the Twilio Programmable Wireless SIM with Trust Onboard, which is suitable for Broadband IoT applications requiring low latency, high bandwidth and secure connectivity.

What's in the Twilio Broadband IoT Developer Kit?

  • Twilio IoT SIM with Trust Onboard
  • Raspberry Pi 3b+
  • Seeed LTE Cat 1 cellular module, Antennas
  • Temperature/Humidity sensor
  • OLED display
  • Power adapter and switch
  • USB - mini USB cable
  • Ethernet cable and ethernet - USB adapter
Let's get started

Sign up for - or sign in to - Twilio

If you haven't yet, you'll need to sign up for an account with Twilio. You can sign up for a free Twilio trial account here.

If you already have an account, you can login here.

Register your Twilio IoT SIM with Trust Onboard

Follow these steps to create a Rate Plan and Activate your SIM on the network.

Enter the SIM registration codetob-sim.png

  1. Open the Programmable Wireless Console.
  2. From the Programmable Wireless menu, click SIMs and click the red plus ('+') button to open the Register a Starter SIM page.
  3. Find the 10 alphanumeric character SIM registration key in the center of the reverse side of the Narrowband IoT SIM chip card:
  4. Enter this number in the Registration Code field.
  5. Click Register SIM Card.

register-tob-sim1.png

Choose a Unique SIM Name

  1. In the Unique Name field, give your SIM a friendly unique name. This is used to identify this SIM in the SIMs section of the Console.
  2. Click Continue.

Create a Rate Plan

  1. Click the red + button to create a Rate Plan.
  2. In the dialog that appears, give the Rate Plan a unique name. This will be used in the Console.
  3. Click Save to continue.

The Rate Plan is now set.

Detailed information about Rate Plans is available in Understanding Rate Plans.

Activate your SIM

  1. Click 'Activate' to activate your SIM on the network.
  2. Wait for up to a couple minutes as your SIM activates.

View SIM configuration details

  1. Once your new SIM has been activated, the View SIM Detail button should appear.
  2. Click the View SIM Detail button to open the Configure tab for your newly activated SIM.

sim-activation.png

My SIM is Active, what next?

Sync the Trust Onboard Device Certificate to your Azure IoT backend

Next, we want to sync the Device Certificate from our Trust Onboard SIM with the Azure IoT backend. This step is needed to validate the SIM when it comes online later.

Configure your Azure IoT Hub

On Azure, you will need to set up an IoT Hub and a Device Provisioning Service (DPS).

  • Visit https://portal.azure.com/ - (sign up for an account if you don’t already have one.)
  • Select ‘Resource Groups’ in the side menu and click on Add a new Resource Group and complete the creation steps.

add-resource-azure.png

  • Click on Create a new resource and search for ‘IoT Hub’ in the list and select it. Follow the IoT Hub creation steps.

iot-hub.png

  • Select ‘Create a Resource’ in the side menu
    • Search for ‘IoT Hub Device Provisioning Service’ in the list and select it
    • Click Create
    • Name your IoT Hub Device Provisioning Service
    • Complete the creation steps
    • Click into your newly created IoT Hub DPS instance

dps.png

  • Select ‘Linked IoT hubs’ in the DPS instance’s menu
    • Click ‘Add’ and add the IoT Hub you created above
    • Click on ‘Overview’ in the DPS instance’s menu
    • Make note of the ‘ID Scope’ value on that page, we’ll need it soon

id-scope.png

  • Click on ‘Shared access policies’ in the DPS instance’s menu
    • Select ‘provisioningserviceowner’
    • Copy the ‘Primary Key Connection String’ (be sure to select Connection String, not just the key), make note of this string, we’ll need it soon.

conn-string.png

Sync Device Certificates to Microsoft Azure

Go back to the Twilio Console and navigate to the SIM configuration page where you left off in Step 1 (if you exited out, you can find your SIM's config page here).

  • Next to 'Microsoft Azure', select the 'Sync' button
  • Paste in the Primary Key Connection String to sync
  • Look for a green success message that you've synced

tob-console.png

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

My Azure IoT backend is ready. What’s next ?

Insert the smallest form factor of the Twilio IoT SIM in the slot available on the Pi Hat board.

Set up the hardware

Now, it's time to put all the hardware together. Work through these steps carefully, it's easy to break some of the fragile parts.

Insert the SIM Card and Attach the LTE Antenna

Insert SIM into the SIM slot on the Pi Hat board.

sim-insert.png

The Broadband IoT Developer Kit comes with two antennas: LTE and GPS.

In this case, we will use the LTE antenna. Carefully connect the black rectangular LTE antenna to the receptacle labeled LTE on the back of the Pi Hat Board (as shown in the photo).

Connect the Pi Hat to the Raspberry Pi

Use the USB to micro USB angled cable to connect the Pi Hat board to the Raspberry Pi. The larger side goes to the Pi while the smaller goes to the MicroUSB port onboard the HAT.

cable-setup.png

Connect the Display and Temperature Sensor

The temperature sensor and display are individually addressable. It doesn't matter which order you connect the two as long as you make a good connection.

Remove either from the package, and connect the included Grove cable between it and one Grove header on the Pi Hat. Likewise, remove the other and connect it to the second Grove header.

display-sensor.png

Connect the power adapter to the Raspberry Pi

Insert the micro USB cable into the Raspberry Pi (the lower board) and connect the other end to a wall power source.

network-light.png

My Pi is Powered Up! Let's cloud.

Run the Quickstart App

Next, we want to start sending data from our IoT Device to the Azure IoT Cloud. We need to install the Azure CLI to monitor all of the events that get sent. Let's test that out first.

Download and run the Azure CLI

  1. Download and install the Azure CLI. Instructions will vary by platform.

    On Windows, download the MSI Installer from this page 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 Mac OSX user with homebrew installed, in a new terminal you can run brew update && brew install azure-cli. You can use your choice of terminal to complete objectives.

    If you aren't in either category, follow the instructions for your platform from this page to install the Azure CLI.
  2. Open a second terminal or process (if applicable). You will need to monitor Azure with one window, and keep your SSH connection with the Raspberry Pi open in the other.
  3. When the CLI is running, login to your Azure account by running az login
  4. Add the Azure CLI IoT extension: az extension add --name azure-cli-iot-ext
  5. Start the monitor: az iot hub monitor-events -n YOUR_NAME

    Replace YOUR_NAME with the name of the hub (NOT the DPS) you created in the first objective.

With that... it'll sit there. Your Raspberry Pi won't push anything up to the cloud until you tell it to, explicitly.

Let's do that now.

  1. Find the ID Scope from Azure (you likely pasted it into a text file in the first objective)
  2. On the command line on your Raspberry Pi (your SSH window), register the ID Scope with the device.
    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 telemetry demo on the Pi:

    python /home/pi/Breakout_Trust_Onboard_SDK/cloud-support/azure-iot/samples/python/twilio_trust_onboard_azure.py​
    
  4. Watch the magic on the Azure CLI Monitor - and the LCD!

With those few steps, you're sending data to the cloud! Watch the telemetry roll onto your command line.

Next up, let's reverse course and make data rain down from the clouc.

Show Me Cloud to Device Messages

Sending Data from Cloud to Device

In this step, we'll concentrate on getting data from the cloud back to our nodes. We're going to use it to switch between Celsius and Fahrenheit on the display, but after you have this working you'll have two-way conversations which you can overload to do your bidding.

Find Out Your Device Name

  1. If its no longer running, turn the Python demo application back on:
    python /home/pi/Breakout_Trust_Onboard_SDK/cloud-support/azure-iot/samples/python/twilio_trust_onboard_azure.py​
    
  2. From another other terminal or process (not the one with your 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 your Device Hub's name.
  3. Azure will return a list of associated devices. Find the deviceId of your Raspberry Pi and save the ID somewhere:
    Finding the Device ID with Twilio and Azure IoT

Send a Cloud to Device Message from the Azure CLI

  1. On the command line, send a message to the Pi from the Azure Cloud:
    az iot device c2d-message send -d YOUR_DEVICE_ID -n YOUR_HUB_NAME --data 'Twilio and Azure: Wow!' --props 'units=fahrenheit'​
    


    Substitute your actual device ID for YOUR_DEVICE_ID
    Replace YOUR_HUB_NAME with your Hub's name
  2. 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 Raspberry Pi's console that looks similar to this:

Received Message [0]:
    Data: <<<Twilio and Azure: Wow!>>> & Size=22
    Properties: {'units': 'fahrenheit'}
    Total calls received: 1

During the next temperature reading, you'll see your device now displays Fahrenheit 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 'Hello World' --props 'units=celsius'

Now you've got data going from the cloud and to the cloud, and you're monitoring (and orchestrating) it all from the CLI.

Next, let's look at taking our command line IoT integration a step further into the visual realm.

Awesome! Show Me What Visuals You Have in Mind

Visualize Events in Time Series Insights

At this point you've got a fully working system. You have two way communications: both from device to cloud and cloud to device. You have status and sensor readings headed to the cloud, and you can switch units displayed on the monitor from the cloud.

Ideally, now would want to visualize telemetry you send to Azure... instead of watching on the command line. Using the Azure Time Series Insights service you can turn your sensor data into a visualization.

Create a Time Series Insights environmenttime-series.png

  • In a browser tab, navigate to the main Azure Portal
  • Search 'Time Series Insights' and select 'Time Series Insights environment'
  • Click the '+ Add' button
  • In the "Create Time Series Insights environment" Basic pane, follow in the fields as follows:
    Environment name: Pick a good name for the Insights environment - you can't change it after it's created. We named ours twilioIoTTutorial
    Subscription:
    Select the name of your trial
    Resource Group: Select the Resource Group which you've been working in this mission
    Location: East US
    Pricing Tier: PAYG
    Property Name: deviceId
    Storage account name: Any name for the resource which will store any events you send. We used tutorialstoragetwilio
    Storage account replication: Locally redundant storage (LRS)

iot-event-setup.png

When you're done filling in the form, you'll next need an event source for your insights.


Click the 'Next: Event Source' button to continue.

  • In the Event Source pane, fill out the form in this way:
    Create an Event Source: Yes
    Name: Something memorable (we used Twilio-IoT-Event-Source)
    Source type: IoT Hub
    Select a hub: Select the hub you're using for this mission today
    Subscription: Select your subscription
    IoT Hub name: Choose the IoT Hub you're using today
    IoT Hub access policy name: iothubowner
    IoT Hub consumer group: Click 'New' to create a new consumer group, and name it something memorable. (We used eventconsumertwilioiot)
    Click the blue 'Add' button when done.
    Property name: Leave it blank

create-time-series-insights.png

Now click 'Review + create', then 'Create'

You now have an Event Source - your already existing IoT Hub - and a Time Series Insights environment. Next, we'll examine the new environment.

Examine the new environment

Once everything is deployed, open up the new environment.

  • In the search bar, search for 'time series' and select Time Series Insights environments

time-series-insights.png

  • Select the environment you just set up. On the left sidebar, select 'Data Access Policies'. Verify your name is there:
    If it isn't, read about Azure access policies and grant permission to the resource

data-access-policies.png

  • Click 'Overview' on the left sidebar. Select the 'Time Series Insights explorer URL':

time-series-link.png

Explore the Time Series Insights Explorer

Welcome to the Time Series Insights Explorer! The Explorer is an amazing way to visualize all of your time series data - conveniently, it's perfect for exactly the type of data you're sending in this mission.

Let's get a beautiful visualization up on your screen:

  • On the left sidebar, expand the 'Time Series Instances' tab and select your device:

twilio-iot-tutorial.png

  • Pick 'Show humidity' then 'Show temperatureFahrenheit'

Now you've got a graph! Excellent work - you can see all of your observations over the course of the Mission in one place.

Hovering your mouse will show you the exact reading at every point and the timestamp on the reading. Filter your data by dragging the slider on the time scale.

You can 'Refresh' to bring in new data at the top of the screen. Drag the timeline slider to visualize more of the events rolling in.

graph-iot-event.png

If you click under the time slider, you'll receive some extra controls. You'll be able to set some built-in timeframes for averages, or set your own interval with a slider:

time-series-graph.png

When you're done playing with the options, it's time to build a model.

Build a Time Series Explorer Model

Next, you're going to build a model - and add location awareness to your data. With that, you'll be ready to scale – and monitor temperature (or any telemetry) all over the world.

Let's get to it:

  • Click the 'Models' icon in the left sidebar
  • Click the 'Add' button to add a new type
  • Enter the following things:
    • Name: Weather
    • Description: Weather definitions

Then, start entering the first variable.
Name: Avg Temp F
Kind: Numeric
Value: temperatureFahrenheit (Double)
Filter: Leave it blank
Aggregation Option: AVG

Click the 'Add Variable Button' then enter into the second:

Name: Max Humidity
Kind: Numeric
Value: humidity (Double)
Filter: Leave it blank
Aggregation Option: MAX

type.png

'Create' it. On the left side, click 'Hierarchies' then click the green 'Add' button.

Enter the following (for each new level, click the '+ Add Level' button):


Name: Location Hierarcy
Level 1: Country
Level 2: State
Level 3: City
Level 4: Location .

hierarchy.png
'Create' the Hierarchy

  • In the left sidebar, select 'Instances'
  • Click the device you've been using on this mission
  • Under 'Type' select 'Weather'
  • For a description, use Weather Node 0.1 (or a better name)
  • Check the box for 'Location Hierarchy'Now it's up to you! Enter your individual values for Country, State, City, and Location. (You can see our choices below.)

edit-instance.png

Go back to the 'Analyze' screen.

  • On the left side, you can now expand the Location Hierarchy and pick the device. Show the two new Weather variables you set, Average Temperature and Max Humidity:

graph-final.png

You now have a geo-tagged temperature monitoring system ready to scale using Twilio Trust Onboard and Azure, all monitored with Azure's Time Series Insights! You're ready to scale horizontally and add your nodes all over the world.

We hope you enjoyed this Quickstart building with the Twilio Broadband IoT Developer Kit with Trust Onboard SIM, and you enjoyed the DevKit and integration. Now it's up to you - we can't wait to see what you build.

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.