Menu

Expand
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?

Get Started with the Twilio Developer Kit for Narrowband IoT

We will guide you through registering your Narrowband SIM in the Programmable Wireless Console, setting up your Developer Kit for Narrowband IoT then connecting via T-Mobile USA’s NB-IoT network to a public MQTT broker. We'll then publish and subscribe to topics and change the state of the board.

You’ll then be able to use the Kit to build your own Massive IoT application. Massive IoT encompasses use cases that involve huge numbers of low-complexity devices that send or receive messages infrequently. Typical applications include low-cost sensors, utility meters and location trackers — devices often deployed in challenging radio conditions such as the basement of a building, or at an extreme distance from the nearest network tower.

Alfa Developer Kit Box

You should have the following components in your kit:

  • Programmable Wireless Narrowband IoT SIM (full size, mini, micro, and nano).
  • ‘Alfa’ Development board.
  • LTE antenna.
  • GPS antenna.
  • Set of Grove sensors: push button, ultrasonic, and temperature/humidity.
  • Micro-USB cable.
  • Additional cabling.

Additional Sample Code

If you want to skip this tutorial and work directly with the Kit’s sensors, then you should check out the Kit’s sample code, which covers setting up the modem, reading data from one of the sensors, and sending and receiving data via MQTT.

Supported sensors include:

For a detailed description on how to configure the samples, please see the Breakout SDK for Massive IoT’s documentation.

Please note that only SARA-N410-02B-based Wio Tracker boards are compatible with the T-Mobile NB-IoT network.

I'm ready to go...

Register your Narrowband SIM

These steps show you how to create a Narrowband Rate Plan and activate your SIM on the network.

1. Enter Your Registration Code

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

Narrowband SIM Registration Code

2. Choose a Unique 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.

Narrowband SIM Unique Name

3. Create a Rate Plan

  1. Click the red '+' button to create a Narrowband 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.

Narrowband SIM Rate Plan creation

You can learn more about Rate Plans here.

4. Activate Your SIM

  • Click the Activate Now button to activate your SIM on the network.

Activate a Narrowband SIM

5. View SIM Configuration Details

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

View Narrowband SIM connection status and details

Alternately, you can also view the SIM configuration details from the menu:

  1. From the Programmable Wireless menu, click SIMS.
  2. Select the newly created SIM, in this case, "My First NarrowBand SIM".
  3. Click the Configure tab to view the properties of the newly activated SIM.

Viewing Narrowband SIM details

You can find all of your registered SIMs in the SIMs section of the Console, where you can manage the SIM lifecycle, change the SIM’s Rate Plan, view its usage, and monitor events on the SIM.

The SIM is registered. What next?

Set up the Developer Kit for Narrowband IoT

1. Insert the SIM into the Alfa development board

  • Insert the smallest form factor of the Narrowband SIM in the bottom of the two slots available on the Developer board:

alfa-developer-board-sim-holder.png

2. Connect the LTE antenna

The Developer Kit for Narrowband IoT comes with two antennas: one for LTE, the other for GPS. In this case, we will use the LTE antenna.

  • Carefully connect the black rectangular LTE antenna to the pin labeled LTE on the back of the Developer Board:

SEED-Board-back.png

3. Plug in the USB cable

  1. Insert the micro USB cable into the Developer Board.
  2. Plug the other end of the USB cable into a USB port on your computer to install the firmware:

SEED-Board-front.png

Let’s connect to the network.

Currently, only the T-Mobile Narrowband network in the United States is supported.

Connecting to the network for the first time can take a couple minutes.

  • The Network LED to the left of the Reset button will initially be orange. When the board is eventually connected, the light will turn blue. The graphic above shows the location of the LED on the development board.

If the LED doesn’t turn blue, try another location — you may not have cell coverage in your current location. If you still aren’t having any success, let us know via help-wireless@twilio.com.

Please reboot your device and try again (hit RESET or power cycle) if your device doesn’t attach to the network in around two minutes.

Show me how to talk to clouds.

Connect a web client to the MQTT broker

We’re going to use the open MQTT broker provided by HiveMQ. We’ll also use its MQTT web client.

If you prefer, you can try any one of a number of other public MQTT brokers.

Note HiveMQ’s broker is completely open, and we'll be using it unencrypted. Anyone can subscribe or publish to your topic.

In production, always use encrypted communications only. Additionally, either set up your own MQTT broker or get a private broker service.

Let’s connect to the broker now.

  1. Visit HiveMQ’s MQTT web client Page.
  2. Hit the Connect button:
    Connect to the HiveMQ Public Broker

  3. Enter some random string as the topic name (just keep a note of it for later) followed by /# and click Subscribe:
    Subscribe to a MQTT Topic HiveMQ

  4. Under Publish use the topic name you entered in step 3, this time followed by /data, and send the message "Hello, World!":
    hivemq-client-subscribe-data.png

  5. Verify you got the message.

If that worked, great! Now let’s get the development evnironment ready for the Developer Kit for Narrowband IoT.

We're in — let’s get our development environment ready.

Prepare your development environment

We’re going to walk through a number of steps to set up your development environment will be set up for the Developer Kit for Narrowband IoT.

Install USB Programming Support

In order to prepare the Kit for these remainder of this guide, you need to install USB programming support.

Steps differ slightly for each platform — find yours below.

Note You'll probably need to restart your computer after installing the driver. Don’t worry, we’ll be here waiting for you after.

Windows

Important For Windows 10, read the note below.

On Windows, you'll most likely need to install ST’s USB driver for USB COM ports to work.

  • Non-Windows XP users download version 1.4.0 drivers.
  • Unzip the file and run the executable
  • Visit C:\Program Files (x86)\STMicroelectronics\Software\Virtual comport driver in Windows Explorer.
  • Double-click either dpinst_amd64.exe for 64-bit systems or dpinst_x86.exe for 32-bit machines.

  • Windows XP users download version 1.3.1 drivers.
  • Unzip the file and run VCP_V1.3.1_Setup.exe.
  • Go to C:\Program Files\STMicroelectronics\Software\Virtual comport driver in Windows Explorer.
  • Double-click and run the executable.

Special note for Windows 10

Many Windows 10 users have issues flashing the board in DFU mode.

  • You need to download and install a utility called Zadig.

Once Zadig is installed, follow the instructions on this ST forum thread to change the USB mode of the Kit. You will then be able to follow the rest of the Quickstart.

macOS

The quickest way to install the necessary driver on macOS makes use of Homebrew.

  1. Install Homebrew by running this in a Terminal:
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  2. Install dfu-util using Homebrew by typing the following in a Terminal:
    brew install dfu-util libusb

Note Use dfu-util 0.9 or greater, if available. If you already have it installed, check the dfu-util version using brew info dfu-util

Ubuntu

1. Install an updated dfu-util: sudo apt-get install dfu-util
2. Configure the permissions for the new USB serial port. (Without this, you may face permission issues when flashing the board.)

sudo tee -a /etc/udev/rules.d/50-twilio-local.rules << _DONE_
# Twilio Alfa kit
# Bus 001 Device 035: ID 0483:5740 STMicroelectronics STM32F407
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", GROUP="dialout", MODE="0666"
_DONE_

3. Plug in the developer kit (insert the USB cable in the correct orientation, and plug in the other end to your computer)
4. Verify the permissions: ls -l /dev/ttyACM* the device should be readable and writable by all users:
crw-rw-rw- 1 root dialout 166, 0 Jul 23 16:41 /dev/ttyACM0

Other *NIX

Unfortunately, we can’t cover every operating system. However, dfu-util is supported in many package managers; check your own operating system’s instructions via search.

You likely will need to follow steps 2 and 3 from the Ubuntu section above.

Set up the Arduino IDE for Narrowband development

1. Download (or Upgrade) the Arduino IDE

The Arduino IDE supports macOS, *nix and Windows systems, but installation is platform dependent.

If you already have the IDE installed, ensure you have version 1.8.9 or higher.

1. Download Arduino IDE 1.8.9+

You can get the IDE here.

2. Install Board Support for the Alfa Development Board

At this point, you have USB support and an updated Arduino IDE. Now you'll install board support for the Developer Kit for Narrowband IoT. The following screens show this process performed on a Mac, but it’ll look much the same on other platforms.

  1. Insert the Micro-USB cable into the Developer Board.
  2. Insert the other end of the USB cable in your computer.
  3. Open the Arduino IDE if it isn't open yet.
  4. Click into the menu Arduino > Preferences.
  5. Enter this URL into the Additional Boards Manager URLs field: https://raw.githubusercontent.com/Seeed-Studio/Seeed_Platform/master/package_seeeduino_boards_index.json
    Adding Seeed JSON into Arduino
  6. Click OK.
  7. Select Tools > Boards > Boards Manager from the menu.
  8. Type "Seeed" into the search field:
    Adding board support for the Narrowband kit to Arduino
  9. Select Seeed STM32F4 Boards (version 1.2.5 or later).
  10. Click Install.
  11. Close the Boards Manager window.
  12. Select Tools > Boards > Wio Tracker LTE from the menu.
  13. Verify that the board shows up over serial. If you haven't rebooted after installing the driver, you may need to reboot now. From the menu, select Tools > Port > {Your Modem Port Here} (See below for the pattern)
    • macOS: /dev/{cu|tty}.usbmodem{XXXX}
    • Linux: /dev/ttyACM{X}
    • Windows: COM{X}

Now you’re able to flash the board.

3. Install the MQTT client

  1. Open the menu Tools -> Library Manager.
  2. Enter the search term "Paho":
    mqtt-library-download.png
  3. Select the library ArduinoMQTT by Oleg Kovalenko.
  4. Click Install.

4. Install the Breakout SDK

  1. Close the Arduino IDE if it’s still open.
  2. Visit Breakout SDK Repository releases.
  3. Expand the Assets section:
    assets_massive_sdk_releases.png
  4. Click to download the ZIP file of the latest release (probably the top entry of Assets).
  5. Note where the ZIP file was saved.
  6. Re-open the Arduino IDE.
  7. Select Sketch > Include Library > Add .ZIP Library
  8. Select the ZIP file you just downloaded.
  9. Restart the Arduino IDE.

And that should do it! Now let’s look at some code.

My Kit’s set up. I’m ready to play with some code.

Connect to the MQTT broker and publish messages

1. Create a new example sketch with the sample code. In the File menu: Examples > Breakout Arduino Library > AlfaKit > Sample:


2. Navigate to the first tab of the IDE window which has just appeared and uncomment the code which will turn on SampleButton.h and SampleTemperatureAndHumidity.h:

// These three samples use the same port on the development board, D38, so only one can be used
// at a time by default.  You can edit the header file to specify D20 to use two of the
// components simultaneously.
#include "SampleButton.h"
#include "SampleTemperatureAndHumidity.h"
//#include "SampleUltrasonic.h"

3. Navigate to the IDE window’s config.h tab.
4. Change the MQTT_BROKER_HOST, MQTT_PUBLISH_TOPIC, MQTT_STATE_TOPIC, MQTT_LOGIN, and MQTT_PASSWORD variables to:
MQTT_BROKER_HOST Your broker, or broker.hivemq.com if you are using HiveMQ.
MQTT_BROKER_PORT Leave it as 1883 for unencrypted. (However, in production you need encrypted comms!)
MQTT_CLIENT_ID Change the USERNAME part of the string to your randomstring, SOMERANDOMSTRING.
MQTT_PUBLISH_TOPIC Use your random string followed by /data, i.e. SOMERANDOMSTRING/data
MQTT_STATE_TOPIC Use your random string followed by /state, i.e. SOMERANDOMSTRING/state
MQTT_LOGIN Use anything, ignored on a public broker
MQTT_PASSWORD Use anything, ignored on a public broker

#define MQTT_BROKER_HOST "broker.hivemq.com"
// MQTT_BROKER_PORT generally is 1883 for clear-text, 8883 for TLS
#define MQTT_BROKER_PORT 1883
#define MQTT_KEEP_ALIVE 0
#define MQTT_CLIENT_ID "SOMERANDOMSTRING-alfa-kit"
#define MQTT_PUBLISH_TOPIC "SOMERANDOMSTRING/data"
#define MQTT_STATE_TOPIC "SOMERANDOMSTRING/state"

#ifdef USE_USERNAME_PASSWORD
#define MQTT_LOGIN "SOMERANDOMSTRING-1"
#define MQTT_PASSWORD "SOMERANDOMSTRING-2"
#endif

5. Uncomment the line #define USE_USERNAME_PASSWORD:

// To enable an authentication mechanism, un-comment the #define below.  The following are supported mechanisms:
//
// USE_USERNAME_PASSWORD - Enables cleartext username/password authentication.
// USE_TLS_CERTIFICATES - Enables TLS and uses client certificates for authentication; TLS with username/password not supported at this time.
// USE_TLS_USERNAME_PASSWORD - Coming soon

//#define USE_TLS_CERTIFICATES
#define USE_USERNAME_PASSWORD

6. Put your board in bootloader mode: hold BOOT0, hit RST, release RST, release BOOT0.
7. Click Sketch > Upload to upload the example to the Developer Board.
8. Tap the RST button to reboot the board.

Verify you can send messages to the cloud

1. Open the serial monitor again (close it if open, then select Tools > Serial Monitor from the menu).
2. Watch for connection on the board. The STA status light on board will be yellow when seeking connection, and the serial monitor will show:

waitForNetworkRegistration():259 .. waiting for network registration
processURCEPSRegistration():260 Received URC for CEREG [2,2]. Set a handler with setHandlerEPSRegistrationURC() if you wish to receive this event in your application

in a loop.

When connected, the light will turn blue and you will see this message:

setHostDeviceInformation():431 Setting HostDeviceInformation to: "Twilio-Alfa_Telemetry","Twilio_u-blox","WioLTE-Cat-NB1_SARA-N410-02B","twilio-v0.1.0_u-blox-vL0.0.00.00.07.07 [Sep 07 2018 19:37:56]"
setHostDeviceInformation():436 .. setting HostDeviceInformation successful.
modem_setup():60 ... done waiting.

3. Surf back to the browser tab where you have the MQTT client.
4. Finally, we need a trigger for messages. The Developer Kit comes with a small push-button. Locate it and connect it to one end of one of the supplied yellow-white-red-black cables. Connect the other end of the cable to the Alfa’s D38 connector on the underside of the board. The code is already set up to make use of the button:

Ready for the moment of truth? Hit the button and watch for the message in the browser client...

If you see a message congratulating you on hitting the button, you did it! You now have one-way communications with the cloud. Your messages are traveling over the air and making it to the MQTT broker:

MQTT Message in HiveMQ Browser Client

Next let’s see how to receive messages from the cloud.

Let’s send messages the other way.

Send a message from the cloud client to the broker

  1. Switch back over the cloud MQTT client.
  2. Send a message to the SOMERANDOMSTRING/state topic:
    publish-state-message-retain-mqtt.png

Note If you check the retain box, the MQTT broker will store the message and redeliver it if your board rejoins the topic. This is very useful for recovering state after power-cycling your device.

Program the LED to change color in response to messages

1. Add code to import the LED library and set a constant pin (at the top of your sketch/main .ino file (the first tab in the IDE), above #include "mqtt.h" ):

#include <Seeed_ws2812.h>
WS2812 strip = WS2812(1, 17);

2. In the setup() function, add code to initialize the LED to white:

void setup() {
    pinMode(RGB_LED_PWR_PIN, OUTPUT);
    digitalWrite(RGB_LED_PWR_PIN, HIGH);
    strip.begin();
    strip.brightness = 5;
    strip.WS2812SetRGB(0, 0x20, 0x20, 0x20);
    strip.WS2812Send();

    owl_log_set_level(L_INFO);
...

3. Edit the state callback in the IDE’s mqtt.h tab:

mqtt_header_file.png

• Find the function beginning static void device_state_callback(MQTT::MessageData &message) {...
• Find the line LOG(L_WARN, "Unknown state: %.*s\r\n", message_str.len, message_str.s); and replace the whole line with the following code:

if (str_equal_char(message_str, "red")) {
    strip.WS2812SetRGB(0, 0x30, 0x00, 0x00);
} else if (str_equal_char(message_str, "green")) {
    strip.WS2812SetRGB(0, 0x00, 0x30, 0x00);
} else if (str_equal_char(message_str, "blue")) {
    strip.WS2812SetRGB(0, 0x00, 0x00, 0x30);
} else if (str_equal_char(message_str, "yellow")) {
    strip.WS2812SetRGB(0, 0x30, 0x30, 0x00);
} else if (str_equal_char(message_str, "teal")) {
    strip.WS2812SetRGB(0, 0x00, 0x30, 0x30);
} else if (str_equal_char(message_str, "purple")) {
    strip.WS2812SetRGB(0, 0x30, 0x00, 0x30);
} else if (str_equal_char(message_str, "white")) {
    strip.WS2812SetRGB(0, 0x30, 0x30, 0x30);
} else if (str_equal_char(message_str, "black")) {
    strip.WS2812SetRGB(0, 0x00, 0x00, 0x00);
} else {
    LOG(L_WARN, "Unknown state: %.*s\r\n", message_str.len, message_str.s);
    return;
}
strip.WS2812Send();
LOG(L_WARN, "Set color to: %.*s\r\n", message_str.len, message_str.s);

4. Reset the board and cycle the serial monitor (close it, and reopen the monitor).
5. Switch to the HiveMQ client tab in your browser.
• Send any of the following commands (case sensitive, no whitespace):
red, green, blue, yellow, teal, purple, white, black.

If the LED color didn’t change, double-check all the work. Make sure you make your edits in the right place.

If it worked? Well done! Let’s look at what you might like to do next...

Wow, pretty colors! What’s next?

Where to go next?

Congratulations — you’ve reached the end of this Quickstart. You can now:

  • Publish messages to the cloud from the board.
  • Receive cloud messages on the board.

Now that you have your Developer Kit for Narrowband IoT activated and doing cool things, we can’t wait to see what you build with it next. Here’s some inspiration to help get your creativite juices flowing:

  1. Visit the examples area in the Breakdown SDK repository.
  2. See how to send a command to the SIM through the Commands API.
  3. Learn more about Narrowband and Twilio Programmable Wireless.
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.