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?

Programmable Wireless: Headless Raspberry Pi with USB Modem Quickstart

With a few pieces of hardware, these instructions, and Twilio Programmable Wireless you can disconnect your devices from their wired perches and deploy them into the field where they'll be more useful.

In this quickstart, we'll use a Raspberry Pi running the Raspbian operating system, a USB to UART bridge, a Huawei E397 (Cricket) USB Modem and some packaged scripts and finish with a Raspberry Pi on the internet using cellular connectivity. This particular quickstart will leave you with a headless Raspberry Pi, one that you manage via serial or SSH and not a monitor, keyboard, or mouse.

In this Quickstart, you'll learn how to:

  1. Sign up for Twilio and purchase your first SIM cards for Twilio Programmable Wireless
  2. Install Raspbian on a Raspberry Pi and configure it for a serial connection
  3. Configure Raspbian to turn off power to video displays and increase maximum power to USB devices
  4. Download and install Twilio ppp connection scripts
  5. Automatically connect via cellular at boot

Hardware Prerequisites

  • Raspberry Pi Model A+ (Other Pi models should work with minor changes)
  • Huawei Model E397u-53 (Cricket) USB Modem
  • 3.3v USB to Serial Adapter (For example, this model)
  • Twilio SIM Card
  • Minimum 4GB MicroSD Card
    • (OR SD Card depending on Raspberry Pi Model. See product documentation.)

Setup Requirements

  • USB WiFi or Ethernet Adapter (for some models of Pi including A+)
    • Necessary to download apt packages and ppp scripts
  • Mac, *NIX or Windows computer
  • (Optional for initial setup) HDMI Monitor, USB Hub, Keyboard and Mouse for Raspberry Pi

Not the quickstart you were looking to complete? See our other Programmable Wireless quickstarts or see all Wireless resources.

I'm in. Show me how to disconnect!

Already have a Twilio account and SIM card? Go ahead and skip ahead to the next step to register and activate it.

Before you can connect with Twilio Programmable Wireless, sign up for a Twilio account.

Next, visit the Programmable Wireless Console. On the Orders page, you can purchase a set of 3 starter SIMs or make a larger custom order.

Order SIM Cards from Twilio

Note: Orders of 10 SIMs or more will be delivered with the SIM cards already registered to your account.

Sounds excellent! How do I connect the SIM?

Register Your SIM, assign a rate plan, and activate

Once you receive your shipment of SIMs, choose one of the cards and remove it from any packaging. Once removed, head over to the Register a SIM page in the Wireless Console.

SIM Card Registration Code

Follow that up by next picking a distinct Unique Name for this SIM.

Choose a rate plan

Next, select a rate plan from the options provided.

By default, Twilio has entered rate plans which are close to what are used in the field. Although beyond the scope of this quickstart, Rate Plans let you control every aspect of what your device can do in the field... and how much data it can use.

Activate the SIM card

When you're happy with the naming and rate plan, 'Activate' the SIM card.

Note: While you can use small amounts of data to evaluate Twilio before the SIM is active, you'll need to activate it for real-world workflows.

I'm active! Let's grab some Raspberry Pi.

Flash Raspbian Lite to your Raspberry Pi SD Card

Since our goal with this setup is a headless Raspberry Pi, we want to start with the lightweight version of the Raspbian operating system on our Pi before we make our changes.

Want to use an already built image incorporating Twilio's modifications and scripts?

  1. Download Raspbian Stretch LITE 4.14 with Twilio modifications
  2. Burn an SD card using Etcher
  3. Skip ahead to the next step

Note: This image will not always be up to date with the most recent Raspbian release - be sure to update the image if you choose to install it. Always check the Raspbian download page for the latest image.

  1. Navigate to the Raspbian download page and download the newest distribution of Raspbian Lite
  2. Using the Etcher burning tool (or other option), flash the image to the MicroSD or SD card

Activate the serial port on the Pi Header and increase USB current

Depending on whether you already have the driver installed for your USB serial adapter or not, first install your serial driver before attempting these steps. Driver details should be included with the cable or adapter you purchased, or found online with a search.

Download the drives for your operating system if you're using the serial adapter from the hardware requirements section above.

Once the serial adapter is working, there are two paths to setting up your Pi. You can either edit the boot configuration of the Raspberry Pi on the machine you use to flash Raspbian or on the Pi itself. Depending on your preference, select one path to enable the onboard serial connection and increase the maximum current available to USB devices.

Configure the Raspberry Pi by editing on another machine (recommended)

Load the MicroSD or SD card and navigate to the boot drive root, or /boot/ depending on how it appears. Open the file config.txt.

At the end of that file, add two lines:


And save the file. You can now safely eject the card and insert it into the Pi. Do not power it up yet. Skip the next section.

Configure the Raspberry Pi by editing on the Pi (if you didn't follow the step above)

Insert the MicroSD or SD card into the Raspberry Pi. Plug an HDMI monitor into the HDMI port of the Pi. Plug a USB Keyboard and Mouse into the Pi (possibly using a USB hub).

Once you are satisfied with the physical setup, power on the Pi by plugging in a MicroUSB Cable.

When the Pi has booted fully, open the file /boot/config.txt in a text editor (feel free to use your choice of editor such as vi or ed instead of nano):

sudo nano /boot/config.txt

Inside that file, scroll to the bottom and add two lines:


Save the file and exit. Now, power down the Raspberry Pi:

sudo shutdown -h 0

Once you have verified the Pi is fully powered down, remove the MicroUSB cable powering the Pi.

Let's connect via serial!

Connect to the Raspberry Pi using the serial adapter

It's time to physically wire the USB to Serial adapter to the Raspberry Pi. First, familiarize yourself with the pinout on the Pi (if you are not using a Raspberry Pi A+ or B+ see here for pinout diagram):

Raspberry Pi Pin Numbering

Connections based on recommended cable

The following pin descriptions are only for the serial adapter listed in the hardware requirements above. Search for your cable's pin descriptions if you chose an alternate version.

If you purchased the UART cable in the article description, here is the wire mapping:

  • Red cable: Leave disconnected
  • Black cable: GND
  • Green cable: TXD
  • White cable: RXD

Connections based on other UART cable

If you are using a different adapter, we're going to use three pins to connect:

  • 6 - GND
  • 8 - Rx
  • 10 - Tx

First, connect GND on your serial adapter to pin 6 on the Pi (the pin on the adapter may instead look like ⏚ with a pointed bottom). Ensure a snug fit, GND is the reference voltage for the other signals and communication will be unreliable if the connection is loose.

Next, very carefully connect pin 8, Tx, on the Pi to Rx on the Adapter. Note: this is not a typo - pins are labeled from the perspective of the device, so where the Pi receives you want to transmit.

Similarly, connect pin 10, Rx, to Tx on the adapter.

When complete (and depending on the model of Pi and Adapter you purchased) your setup should look similar to the following:

Raspberry Pi with Serial Adapter

Turn on your Raspberry Pi

It's time to fire up your Raspberry Pi. Double check and make sure your SD card, SIM card, UART cables, and now that the power adapter is plugged in. You should see the red and green lights on your Raspberry Pi start flashing.

Start Your serial terminal

Next, on your development machine, connect the USB-Serial adapter and open a serial terminal to connect to it at 115,200 baud. On Mac OS X (and some flavors of *NIX), you can use the screen serial terminal in a manner similar to:

screen /dev/tty.<some name of device> 115200

On Windows, we recommend using PuTTY. Your adapter will appear as a COM port, and PuTTY will allow you to connect.

Temporarily connect to the Internet using Wired or WiFi

Your Raspberry Pi model may or may not have provisions to connect to the internet onboard (the A+, for example, doesn't).

If it doesn't include connectivity, the default installation of Raspbian includes drivers for many USB WiFi and USB Ethernet adapters. While you will end this guide with cellular internet connectivity, temporarily attach a USB WiFi or Ethernet adapter. If you are using ethernet, connect a cable between the Pi and a modem, router, or switch to give it connectivity.

Plug in the USB Modem, turn on the Pi, and login

It's now the moment of truth. First, plug in the USB Modem to the Pi. Then, power on your Pi using the MicroUSB cable and watch your serial terminal.

When presented with a login prompt, log in using the username pi and the password raspberry by simply typing in your serial terminal. If necessary (usually for WiFi), connect the board to the internet via your network.

I feel us getting closer - let's continue!

Install Twilio connection scripts and connect

We have a number of connectivity scripts at this repository to facilitate getting you online using ppp. However, in order to connect you need to first install two packages:

# Optional
sudo apt-get update

# Mandatory
sudo apt-get install ppp usb-modeswitch

Once ppp and usb-modeswitch are installed, you are free to download the Twilio connection scripts. In a directory you control, run the following:

cd wireless-ppp-scripts-master
sudo cp chatscripts/twilio /etc/chatscripts
sudo cp peers/twilio /etc/ppp/peers

And... actually, that's it! Bring down your current temporary internet connection with one of the following commands. (If it doesn't work, you can use the ifconfig command on the Pi to see the name of your connection).

For WiFi:

sudo ifconfig wlan0 down

For Ethernet:

sudo ifconfig eth0 down

Finally, you can connect to Twilio Programmable Wireless! Run the ppp script to connect the USB Modem:

sudo pon twilio

Ready for the magic? Verify you have a connection by pinging – what else? – Twilio's API:

ping -I ppp0 -c 3

And there you have it - cellular connectivity!

Now that it works, let's set up the Pi to connect to Twilio at startup.

If you have issues connecting, first check your modem is not in mass storage mode. If it is correct, try to get a clear view of the sky or move to an area of better connectivity.

If you still have issues, feel free to talk to support.

Let's finish this install

Set up the Pi to connect to Twilio at startup

Whenever the Pi power cycles, we want it to automatically connect using Twilio. However, if the USB modem isn't inserted, that's a waste of time - we won't be able to make the connection. If the modem is connected we can also save some power by powering down the HDMI and RCA connection (it is going to run headless, after all).

Open up the file /etc/rc.local in your favorite text editor: sudo nano /etc/rc.local

At the end of the file but before the 'exit' line, add the following:

gsm_loaded=`dmesg | grep -i "gsm"`

if [ -n "$gsm_loaded" ]; then
     /usr/bin/tvservice -o
     pon twilio

Now, when you start the Raspberry Pi it will watch for the USB modem's connection. If it sees the 'GSM' string, it will automatically disable the displays and connect to Twilio with ppp.

Feel free to restart now with sudo shutdown -r 0 , then immediately ping Twilio again with ping -c 3

Nice! It works - what's next?

Where to next?

Now that you have a headless Raspberry Pi connected to Twilio, we can't wait to see what you do with it. Here are some possible places to go next:

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.