Rate this page:

Get Started with Programmable Wireless, the Raspberry Pi 4, and the Seeed LTE Cat 1 Pi Hat

This tutorial has been deprecated and will shortly be removed, as will the modified version of the Raspberry Pi OS that it requires. We strongly recommend you head instead to Get Started with Programmable Wireless and the Raspberry Pi 4, which uses up-to-date hardware are the standard Pi OS.

This tutorial will help you use a Twilio Programmable Wireless SIM to build and run your first IoT application.

The Raspberry Pi 4 and Seeed LTE Cat 1 Pi Hat

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.

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

Set up your device

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

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

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

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 Raspberry Pi. 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 Pi to take regular sensor readings and send them to the broker. Last of all, we’ll use the broker to route commands back to the Pi.

1. 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. You can do this on your computer, or you can do this on the Pi too: just fire up a browser from the desktop.

  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:

2. Connect to the MQTT broker from the Raspberry Pi

We’re going to connect the Pi to the broker we just set up and tried out.

  1. On the Raspberry Pi, run the following command in a Terminal window or at the command line:
  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 Pi!

Receiving MQTT messages on the Raspberry Pi

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 your HiveMQ browser window.
  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 Raspberry Pi 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 Raspberry Pi and to control the Pi by sending it commands. Well done!

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