Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

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?

Twilio Narrowband Alfa Developer Kit MQTT Quickstart

If you received the Alfa Developer Kit that was distributed to SIGNAL attendees, this Quickstart guide is for you.

We will guide you through registering your Narrowband SIM in the Programmable Wireless Console, setting up your Alfa Developer Kit, then connecting to a public MQTT broker. We'll then publish and subscribe to topics and change the state of the board.

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 - Pushbutton, Ultrasonic, Temperature/Humidity
  • Lithium battery
  • Micro-USB cable
  • Additional cabling

Additional details about the development board are available here.

Also try the general "Hello World!" quickstart for this board, or the Machine to Machine commands Quickstart.

I'm ready to go, let's party.

Register your narrowband SIM

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

Enter 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 chip card.
  4. Enter this number in the Registration Code field.
  5. Click Register SIM Card.

Narrowband SIM Registration Code

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

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

Learn more about Rate Plans here.

Activate your SIM

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

Activate a Narrowband SIM

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

Find all your registered SIMs in the Sims section of the Console. You can manage the SIM lifecycle, change the SIM's Rate Plan, see its Usage and monitor events on the SIM.

The SIM is registered. What next?

Set up the Narrowband kit hardware

Insert SIM into the 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

Connect the LTE antenna

The Alfa Developer Kit comes with two antennas: LTE and 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

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

Plug in the lithium battery

  • Insert the JST connector of the lithium battery into the battery port to the right of the micro USB port.

We highly recommend you plug the lithium battery in at all times. Although Narrowband is relatively low power, when the antenna turns on USB might not deliver enough power.

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 eventually connected, it will turn blue. (See graphic above for LED location 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

For this quickstart, we're going to use the excellent open MQTT broker provided by HiveMQ. We'll also use their MQTT web client.

(You can find other public MQTT brokers here).

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

In production, 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. Subscribe to the topic SOMERANDOMSTRING/# (SOMERANDOM string is something you make up - just keep note of it for later):
    Subscribe to a MQTT Topic HiveMQ
  4. Under "Publish" use the topic SOMERANDOMSTRING/data and send the message "Hello, World!":
    hivemq-client-subscribe-data.png
  5. Verify you got the message

If that worked, great!

Next let's get the development evnironment ready for the Narrowband kit.

Great, we're in! Let's get our development environment ready.

Get your development environment ready for the Narrowband kit

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

Install USB programming support

In order to flash the Alfa Development kit for these objectives, you'll need to install USB programming support.

Steps differ slightly for each platform – find yours below.

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

Windows

Important: For Windows 10, read the below note.

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](http://www.espruino.com/files/stm32_vcp_1.4.0.zip)
  • 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

  • Windows XP [users download version 1.3.1 drivers](http://www.espruino.com/files/stm32_vcp_1.3.1.zip).
  • 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 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.

OSX

The quickest way to install the necessary driver on OSX is by using 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

*NIX

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 OS'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

Download (or Upgrade) the Arduino IDE

The Arduino IDE supports Mac OSX, *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+](https://www.arduino.cc/en/Main/Software)

Install Board Support for the Alfa Development Board

At this point, you have USB support and an updated Arduino IDE. Next, you'll install board support for the Alfa development kit.

  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. Copy 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. Click back into the menu: Tools > Boards > Boards Manager
  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. In the menu: Tools > Boards > Wio Tracker LTE
  13. Now, verify the board shows up over serial. (If you haven't rebooted after installing the driver, you may need to reboot now).
    - Back in the menu: Tools > Port > **{Your Modem Port Here}** (See below for the pattern)
    - OSX: /dev/{cu|tty}.usbmodem{XXXX}
    - Linux: /dev/ttyACM{X}
    - Windows: COM{X}

Now you're able to flash the board.

Next, install the MQTT client for the kit

Install the MQTT Client

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

Next, install the SDK and examples for the Alfa kit.

Install the Breakout SDK

Now, visit the Breakout SDK Repository releases.

  1. Close the Arduino IDE if it's still open
  2. Expand the Assets section:
    assets_massive_sdk_releases.png
  3. Click to download the ZIP file of the latest release (probably the top entry of Asset`)
  4. Note where the zip file was saved
  5. Open the Arduino IDE
  6. Select Sketch > Include Library > Add .ZIP Library (and select the .zip file downloaded)
  7. Restart the Arduino IDE

And that should do it! Next, let's look at some code.

Great, it's set up. Let's play with some code.

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

sample-code-alfa-kit.png

2. Navigate to the first tab of the resulting IDE window. Uncomment the code which will turn on SampleButton.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 config.h tab of the IDE window.
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. (Reminder: 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

1. Open the serial monitor again (close it if open, then in the menu: Tools > Serial Monitor) 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.

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

Pretty cool - now let's send messages the other way.

Send a message from the cloud client to the broker

This is an easy one.

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

A note on "retain": If you hit 'retain', the MQTT broker will store the message and redeliver it if your board rejoins the topic. This is very usefu for recovering state after power cycling.

Program the LED to change color in reaction 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 mqtt.h tab of the IDE:

mqtt_header_file.png

- Find the static void device_state_callback(MQTT::MessageData &message) { function - Find the LOG(L_WARN, "Unknown state: %.*s\r\n", message_str.len, message_str.s); line - DELETE that line and in its place paste this handler 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. Now, 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? Congrats! Let's look at what's next.

Wow, pretty colors! What's next?

Where to next?

Congratulations on hitting for the cycle. You can now:

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

Now that you have your Narrowband Developer Board activated, we can't wait to see what you do next. Here's some inspiration to help get the creativity flowing:

  1. Visit the examples in the Breakdown 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.