Today we'll mix the lightweight messaging protocol MQTT with Twilio Sync for IoT, the Arduino IDE, and the Seeed Studio LinkIt ONE. We'll use the Twilio Device Manager to create a Device Fleet then show a LinkIt ONE to Sync connection. We'll do all of that using either Twilio's Programmable Wireless connectivity over GPRS, or through a friendly WiFi network.
Oh, and we almost forgot - we'll use this ultra-powerful enterprise grade setup to blink an LED. C'mon, we'll show you!
Sync for IoT is currently in Developer Preview, which means access is by invite only. If you'd like to try what you see in these docs, sign up for the developer preview and the team at Twilio will get you onboarded as soon as possible.
Once you are logged in, click this Twilio Device Manager link to go to the Sync for IoT console.
This code will work both over WiFi or with 2G/GPRS via Twilio's Programmable Wireless. To switch between the two, set
false. (More detail below).
If you are connecting with Programmable Wireless, here's the order of operations:
- Navigate to the Programmable Wireless section of the console with your SIMs handy
- If your SIM is already associated with your account, follow the instructions on the SIMs page (Click the plus '+' button)
- If you have an unassociated SIM , follow the instructions in 'Starter SIMs'
Once your SIM is active, associated, and has a data plan, insert it into the LinkIt ONE. Only punch out the medium sized SIM (if you do accidentally punch out too much, friction should still hold it though). Note: the proper orientation is 'reversed' from most phones; the angled side should face out.
If you haven't yet, attach the antennas as shown above.
While most of your code will be transferrable, it’s important to note: for new product development 2G isn’t a good choice.
A Device Fleet is a collection of devices, certificates or keys, and unique configurations inside Twilio Sync. While you can create many fleets, any individual fleet will always be isolated. That's perfect for a use case where you want to prevent the accidental interaction of your things.
For today though, a Default Fleet is already provisioned for you. Get started by navigating to it in the Device Management console:
(Note you may also deploy a fleet through the REST API.)
It's now time to work on the deployment.
Twilio will automatically give you a default Deployment and configure it upon Fleet creation. The 'Default Deployment' field in your Fleet will look similar to the following screenshot:
Click the 'Configure the Deployment' link:
Twilio also automatically created a new Sync Service Instance. An instance is similar to an isolated database. When you make updates on Sync primitives (such as the Document type we're using here), they are stored only in this Sync instance.
As before, you can create a Deployment with the API.
Once you've got the Deployment handled (and an instance pointer), it's time to create a Device Certificate for authentication.
For Sync for IoT, a Device refers to a particular piece of hardware managed through the Device Manager. When your hardware connects to Sync, Twilio identifies it either through a key or certificate. The LinkIt is a powerful board and can handle certificate based authentication; we strongly encourage you to use certificate credentialing wherever you can.
Click the 'Devices' link on the left sidebar from inside your Fleet. Enter a Unique and Friendly name for the LinkIt ONE then hit the 'Create' button.
You can also create a Device through the API.
While still in your device, click the 'Certificate' link in the left sidebar then the red plus sign (+) and create a new Device Certificate. As you are clicking from inside the device, it will automatically associate this Certificate with the LinkIt.
Enter a name then check the 'Self-signed certificate' box. Finally, hit the 'Create' button to create your certificate.
In the success screen (similar to the above), download both the Certificate and Private key, and copy the key decryption password to a safe place. Note: this is your last chance to do this! If you miss this step you'll have to create a new certificate!
- Also, download Twilio's root certificate (naming it
root.crt) which you'll use to verify you are talking to Twilio:
Optionally, you can create device certificates with the API as well.
On the LinkIt, you will be copying the root certificate, client certificate, and a decrypted client key to the root filesystem. Save those in a safe place for now, we'll go over those steps in detail.
A Document is the simplest type of object in Sync (perfect for, say, tracking LED status!). You will have to create a document before you connect your LinkIt ONE to Sync. The Document name will map directly to a topic name in MQTT, where you will subscribe on the LinkIt. Be sure to name your Document 'BoardLED' (follow our capitalization).
We create a new document
BoardLED, and initialize
led key to value
For this guide's development, we used a LinkIt ONE with the Arduino IDE. The canonical guide for getting the LinkIt on the Arduino IDE can be found here on MediaTek's site. Note that you will likely have to install the serial port driver as well; be sure to do that before attempting the steps.
We also have a blog post detailing the steps to get the LinkIt ONE working with the Arduino IDE if you are still stuck.
Once you are inside the Arduino IDE, install one library from the Library Manager (menus: 'Sketch' -> 'Include Library' -> 'Library Manager' on a Mac):
- ArduinoJSON (by Benoit Blanchon - GitHub)
This library and future updates are installed and managed directly inside the IDE.
You also need to install MediaTek's
aws_mbedtls_mqtt library (Github here).
- Download the aws_mbedtls_mqrtt library as a ZIP File (click here for the master branch ZIP)
- Inside of Arduino, surf to the 'Add ZIP Library' link. For Mac, this is found in the 'Sketch' -> 'Library' submenu
- Find the ZIP file and install it
Note that there are three files in this package; copy the
.ino file as well as
SyncLinkItHelper.hpp. As you're only adding two additional files, once you have the sketch open you can also create named tabs and paste the contents inside.
Above, you created a device certificate for the LinkIt ONE and downloaded an encrypted key and certificate. You also downloaded a Root Certificate. (You didn't? Here is the link again: Root Certificate for LinkIt ONE Sync ).
- Set your LinkIt ONE to 'MASS STORAGE' Mode. The outer switch points to 'MS' (similar to updating firmware.)
- You should see a USB disk appear in your filesystem. Copy '
root.crt' to it.
- Rename the
CYxxxxxx.pemfile to '
client.crt' and copy it to the LinkIt's root file system.
- The CYxxxx.key file needs to be decrypted before copying to the LinkIt. On *NIX, this is done with:
openssl rsa -in CYxxxxxxxxxx.key -out CYxxxxxxxxxx.key.decrypted
(Use the password tyou saved from the certificate screen)
- Rename the decrypted file to '
client.key' and copy it to the root filesystem of the LinkIt.
- Unplug the LinkIt ONE, switch the outer switch back to 'UART', then plug the LinkIt back into a USB port.
First, modify the
WIFI_USED boolean to choose GPRS (
false) or WiFi (
If you choose GPRS with Twilio Programmable Wireless, everything should be good to go assuming you have a working SIM card inserted. You don't need to change and of the
GPRS_* variables, but double check your status in the Programmable Wireless console.
If you choose WiFi, also edit the
WIFI_PASSWORD variables with your WiFi network's SSID and password, respectively. If you are not using WPA security, also edit
We're getting close now - it's time to upload everything to the board.
Edits done, compile and upload the code to the LinkIt ONE. Open the Arduino Serial Monitor (the menu 'Tools' -> 'Serial Monitor'). You should see some signs of life assuming you followed the steps above.
But wait - that's not the demo! Let's blink that onboard LED.
Set 'led' to 'ON' in the Document you created above.
You should quickly see three signs your API Request went through:
- Sync lets you know the command was successful
- The onboard LED will light
- The LinkIt ONE will give you a success message over serial
If you look in the
main_thread(void* user_data) function in the
.ino file, there are commented lines which would send updates back from the LinkIt to the document. Remove the comment block to send a
msg back to Sync periodically.
Whatever you send back to Sync should be in JSON format. You can either generate JSON through the ArduinoJSON library or craft it inline like we've done here.
Very simple, right? Blinky lights, Sync Documents, powerful infrastructure - and zero wires!
While we know that your application isn't just blinking that single LED, the infrastructure you now have in place is ready for wherever you want to take it. You can scale out to many more devices or build up a backend dashboard or... well, the or is on you.
Let us know where your imagination and your business takes you - we'll be watching for your tweets on Twitter!