Get Started with the Twilio Developer Kit for Broadband IoT

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

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

The Developer Kit for Broadband IoT is not currently available to buy, but its components, listed below, are readily available from a wide variety of electronics suppliers, so it’s very easy to assemble your own kit.

You will also need to order and register a Programmable Wireless SIM.

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

You will also need your computer.

This guide requires a 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. This guide has all the information you need — come back here when you’re done.

The Broadband IoT Developer Kit can also be used with Super SIM. The default PPP connection can be configured for the correct APN setting (super) with the following commands:

sudo systemctl disable twilio_ppp@twilio-wireless
sudo systemctl enable twilio_ppp@twilio-supersim

You can use Super SIM for connectivity for the Developer Kit, but keep in mind that it cannot yet be used for Trust Onboard-based authentication.

Super SIM usage requires version 0.9.6 of the Twiliio Raspberry Pi OS image or above.

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

You’re now ready to put the hardware together. Just follow these steps:

  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 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@
    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 MQTT app

With all the hardware working, we’re ready to build our first IoT application. We’ll be using a technology called MQTT to transmit sensor data generated by the Developer Kit. Picture it as an IoT device in the field relaying data back to base. That data might be the location of a shipping container, the state of a piece of machinery, or any other useful item of information that you need to track.

MQTT (Message Queuing Telemetry Transport) is a publish/subscribe messaging protocol that works over the Internet. It’s widely supported by IoT devices, so sticking with MQTT means your device ecosystem is expandable.

To build our IoT app, we need an ‘MQTT broker’, which is the server-side system that routes messages from sources (publishers) to receivers (subscribers). We’ll set up a broker next. Once that’s done, we will configure the Developer Kit to take regular sensor readings and send them to the broker. Last of all, we’ll use the broker to route commands to the Developer Kit.

Set up an MQTT broker

We’re going to use HiveMQ’s free MQTT broker, but there are other public MQTT brokers that you may prefer to use instead — there is a list of them here.

HiveMQ’s broker is completely open. Anyone can subscribe or publish to your topic. In production, always use encrypted communications only, and either set up your own MQTT broker or use a private broker service.

Let’s use HiveMQ’s web UI to set up the broker.

  1. On your computer, visit HiveMQ’s MQTT web client page.
  2. Click Connect:
  3. In the Subscriptions section, click Add New Topic Subscription.
  4. Think up a topic name, make a note of it, and enter it in the Topic field. Make sure you add /# to the end:
  5. Click Subscribe.
  6. In the Publish section, enter your topic name followed by /info in the Topic field and then key in Hello, World! in the Message field:
  7. Click Publish.
  8. Check the Messages section to make sure the message you just sent was received by the broker:

Connect to the MQTT broker from the Developer Kit

Go back to your terminal or PuTTY window where you SSH’d into the Pi. We’re going to connect the Developer Kit to the broker we just set up and tried out.

  1. On the Raspberry Pi, run the following command: wget \ quest/programmable_wireless/ \ broadband/
  2. Open the file in a text editor on the Pi, such as nano:
  3. Look for the section marked # EDIT THESE and change some of the items as follows:
    • MQTT_CLIENT_ID — Set this to the topic name you created above.
    • MQTT_PUBLISH_TOPIC — Same as the above, followed by the text /info.
    • MQTT_STATE_TOPIC — Same as the MQTT_CLIENT_ID, but this time followed by /state.
  4. Exit the text editor. For example, in nano hit ctrl-x.
  5. Save the file. For example, in nano, type y then hit Enter.
  6. Run the script:

Switch back to the browser window or tab showing the MQTT broker interface. You should see a series of messages being logged — the messages currently being sent by your Developer Kit!

Receiving MQTT messages on the Developer Kit

The Python script you downloaded in the section above can also handle incoming messages. It uses the popular Paho MQTT library to do so. It is configured to watch out for and act upon three commands:

  • units
  • display
  • displayUrl

Let’s see what they do.

  1. Switch to HiveMQ in your computer’s browser.
  2. In the Publish section, set the topic to your chosen topic name plus /state then enter the following in the Message field:
    {"units": "fahrenheit"}
  3. Click Publish.

After a short time, the Developer Kit will register the command and update its output. It won’t switch units until the next reading is taken and this occurs every 60 seconds.

Now for the next command:

  1. In the Publish section, set the topic to your chosen topic name plus /state then enter the following in the Message field:
    {"display": "image"}
  2. Click Publish.

You should very quickly see the Twilio logo pop up on the display.

The third command, displayUrl, is used with display. Using the process outlined above, create and send the following message to the same topic:

{"display": "image", "displayUrl": ""}

You can change displayUrl to reference any publicly available GIF, JPEG, or PNG image.

To switch back the temperature data, send this message:

{"display": "temperature"}

to the same /state topic as before.

And that’s it — you have created a two-way IoT application that leverages the popular MQTT protocol to transmit data from your Developer Kit and to control the Developer Kit by sending it commands. Well done!

Where next?

The script gives you the foundation on which you can build a full temperature and humidity monitoring system. It contains all the logic you need to drive the temperature and humidity sensor, display, and MQTT from the Raspberry Pi. Having completed this guide, why not explore the script’s code further, to see how you can add new commands?

We have a brief follow-up article which describes how the script works and what libraries it uses which may be of help.

The Developer Kit connects the sensor and display modules using the Grove System, an ecosystem of IoT-oriented modules that use the same connector. You can explore adding different components to your Developer Kit.

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 Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

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

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