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 Sync for IoT and Programmable Wireless on a LinkIt ONE

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.

Sign Up For (or Sign Into) a Twilio Account

Either create a new Twilio account (you can sign up for a free Twilio trial), or sign into an existing Twilio account.

Once you are logged in, click this Twilio Device Manager link to go to the Sync for IoT console.

Purchase and Activate a Programmable Wireless SIM Card (Optional)

This code will work both over WiFi or with 2G/GPRS via Twilio's Programmable Wireless. To switch between the two, set WIFI_USED to true or 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.

SIM Card Insertion LinkIt

If you haven't yet, attach the antennas as shown above.

A General Warning About 2G Development

While most of your code will be transferrable, it’s important to note: for new product development 2G isn’t a good choice.

American 2G networks are being deprecated. For new product development, we suggest researching 4G alternatives or discussing your idea with the Twilio Programmable Wireless team.

Deploy a Fleet of LinkIt ONE Things

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:

Locating the default Ffleet in the Twilio Console

(Note you may also deploy a fleet through the REST API.)

Loading Code Sample...
      
      
      
      
      Using the API to create a Device Fleet in Sync for IoT.

      Create a Device Fleet

      Using the API to create a Device Fleet in Sync for IoT.

      It's now time to work on the deployment.

      Configure the New Fleet's 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:

      A default deployment is automatically provisioned for each new Device Fleet.

      Click the 'Configure the Deployment' link:

      Every deployment is configured with a default Service Instance.

      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.

      Loading Code Sample...
          
          
          
          

          Once you've got the Deployment handled (and an instance pointer), it's time to create a Device Certificate for authentication.

          Create a LinkIt ONE Device and Device Certificate

          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.

          Create a New ESP8266 Device in Deployed Devices

          You can also create a Device through the API.

          Loading Code Sample...
              
              
              
              

              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.

              Sync Certificate and Key Download for ESP32

              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:

              Root Certificate for LinkIt ONE Sync

              Optionally, you can create device certificates with the API as well.

              Loading Code Sample...
                  
                  
                  
                  

                  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.

                  Create a Sync Document

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

                  Loading Code Sample...
                      
                      
                      
                      
                      Use the Sync Service SID from the 'Configure Deployment' Screen, as Shown Above.

                      Create a Sync Document

                      Use the Sync Service SID from the 'Configure Deployment' Screen, as Shown Above.

                      We create a new document BoardLED, and initialize led key to value OFF.

                      Prerequisites to Use a LinkIt ONE with Sync

                      You can grab all of our LinkIt code quickly from Github.

                      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.

                      Install Using the Library Manager

                      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.

                      Install Using a ZIP File

                      You also need to install MediaTek's aws_mbedtls_mqtt library (Github here).

                      1. Download the aws_mbedtls_mqrtt library as a ZIP File (click here for the master branch ZIP)
                      2. Inside of Arduino, surf to the 'Add ZIP Library' link. For Mac, this is found in the 'Sketch' -> 'Library' submenu
                      3. Find the ZIP file and install it

                      Add All Our Code to the Arduino IDE

                      Note that there are three files in this package; copy the .ino file as well as SyncLinkItHelper.cpp and 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.

                      Add Your Credentials to the LinkIt's File System

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

                      Choose to Connect Over GPRS or WiFi

                      First, modify the WIFI_USED boolean to choose GPRS (false) or WiFi (true).

                      Loading Code Sample...
                          
                          
                          
                          
                          If you aren't using GPRS, edit the WiFi SSID and password to connect to a friendly network.

                          Optionally Add Your WiFi Credentials to the LinkIt Code

                          If you aren't using GPRS, edit the WiFi SSID and password to connect to a friendly network.

                          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_AP and WIFI_PASSWORD variables with your WiFi network's SSID and password, respectively. If you are not using WPA security, also edit WIFI_AUTH.

                          Burn the Code to the LinkIt and Toggle the LED

                          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.

                          Loading Code Sample...
                              
                              
                              
                              

                              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

                              LinkIt ONE Blinking Over Sync

                              Sending Updates Back to Sync from the LinkIt

                              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.

                              Loading Code Sample...
                                  
                                  
                                  
                                  
                                  Comment out these lines to periodically update the BoardLED Document from the LinkIt ONE.

                                  Optionally Send Data Back to Sync

                                  Comment out these lines to periodically update the BoardLED Document from the LinkIt ONE.

                                  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.

                                  Link(It)ing Your Internet of Things

                                  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!

                                  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.

                                  Loading Code Sample...