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:
- Sign up for Twilio and purchase your first SIM cards for Twilio Programmable Wireless
- Install Raspbian on a Raspberry Pi and configure it for a serial connection
- Configure Raspbian to turn off power to video displays and increase maximum power to USB devices
- Download and install Twilio ppp connection scripts
- Automatically connect via cellular at boot
- Raspberry Pi Model A+ (Other Pi models should work with minor changes)
- Huawei Model E397u-53 (Cricket) USB Modem
- OR USB Modem supporting these bands in your country
- 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.)
- 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
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.
Note: Orders of 10 SIMs or more will be delivered with the SIM cards already registered to your account.
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.
Follow that up by next picking a distinct Unique Name for this SIM.
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.
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.
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?
- Download Raspbian Stretch LITE 4.14 with Twilio modifications
- Burn an SD card using Etcher
- 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.
- Navigate to the Raspbian download page and download the newest distribution of Raspbian Lite
- Using the Etcher burning tool (or other option), flash the image to the MicroSD or SD card
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.
Load the MicroSD or SD card and navigate to the boot drive root, or
/boot/ depending on how it appears. Open the file
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.
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
ed instead of
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.
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):
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
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:
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.
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.
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.
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.
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:
wget https://github.com/twilio/wireless-ppp-scripts/archive/master.zip unzip master.zip rm master.zip 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).
sudo ifconfig wlan0 down
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 -c 3 www.twilio.com
And there you have it - cellular connectivity!
Now that it works, let's 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 fi
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
Feel free to restart now with
sudo shutdown -r 0 , then immediately ping Twilio again with
ping -c 3 www.twilio.com
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: