In this guide, we'll show you how to use the lightweight messaging protocol MQTT with Twilio Sync for IoT and Particle's cellular IoT platform, the Electron. We'll cover the Twilio Device Manager and Device Fleets, then cover connecting to Sync with your Electron to blink an LED through API calls.
Cut the cord, we're going to wirelessly blink an LED!
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 logged in, visit the console for Twilio Device Manager.
In Sync, a Device Fleet is a collection of devices, keys, certificates, and configurations. While you can create multiple fleets, every fleet will be isolated from every other fleet.
One Default Fleet is automatically created for you; navigate to it in the Device Management console.
You can also deploy a Fleet using the API.
Once you are familiar with Fleets, it's time to move to Deployments.
As soon as the Default Fleet is built, Twilio will also configure a default Deployment. The 'Default Deployment' field in your Default Fleet is populated, echoing the following screenshot:
Click through to the new deployment through the 'Configure the Deployment' link.
Twilio also has also automatically linked your deployment with a default Sync Service Instance.
Instances are like databases. All of the data from the 'conversation' you'll have with the Electron (or any other device in this Deployment) will only be stored in this one Sync instance.
You can also (of course) configure a new Deployment through the API:
Deployments down, you're now ready to create your first Device and a Key to authenticate your Electron!
A Device is any single piece of hardware registered in Twilio's Device Manager.
A piece of hardware connects and authenticates, then Twilio determines which Device it should match based on the credential it provides - certificate or key. We'll be using Device Keys today with the Particle Electron, but where possible you should use Device Certificates.
Inside your Fleet on the sidebar, click the 'Devices' link, then 'Create a Device'. Enter a Friendly and Unique name, then hit the red 'Create' button:
You can also provision new Devices using the API, as illustrated here.
In your Device configuration, click the 'Keys' link in the left sidebar then the red plus sign (+) to start creating a new Device Key:
The appropriate field should auto-populate a device key (or find it by navigating back into the Deployment to your Device). Enter a Unique Name then 'Create' the Key. Important: both the Key and the Secret must be saved once your key is created. The secret can't be recovered after this!
You can also create and delete Device Keys using the API. Here's a programatic example:
Inside the C++ Electron code, 'KEY' will go inside
sync_key, while 'SECRET' will map to
The Document is the most basic Sync object - perfect for sharing state in a small LED-blinking application. The MQTT topic the Electron subscribes to is based on the document name - we highly suggest you call your first document
BoardLED to match our code.
We also set the key 'led' to 'OFF'. Logic on the Electron will then keep that LED unlit when it connects.
Here's all you need to do to sync with Sync:
- (Optionally) change the topic (ONLY if you renamed the Document)
- Flash your Electron!
Let's take a closer look at how this works.
We installed two libraries in the Particlde Web IDE:
You can manually install libraries by clicking the 'Libraries' button on the left sidebar:
A dialog will appear that will guide you to choose the application.
You can also choose to send updates back to Sync with our code. We're just sending back a "Hello, World!" message - surely you'll eventually be editing this to send back sensor readings and event values.
(2*(1000*60)) milliseconds (2 seconds) the Electron will send a message back to Sync, updating the 'led' back to 'ON' (insert your joke here about Electrons flowing!).
We've added some properly formatted JSON in that example, but note you can also use ArduinoJSON to format a JSON string for you. As your updates become more complex, we suggest using the library.
Assuming you entered everything correctly, you should see some happy messages scroll by, ending with a notice about subscribing to Sync (and then the current state of the document). We've also added some minor debugging serial output which can assist in the non-happy case.
But if it's working? Make that LED blink!
Modify the Document using the UPDATE api call, setting 'led' to 'ON'.
Quickly, you'll see two updates:
- A response to curl, informing you your update went through
- Light from the LED
Wow - look at those electrons flow from the Electron!
While you won't be stopping with a blinking LED, you've now got an internet controlled light source all backed up by Sync for IoT and Twilio's powerful and scalable infrastructure. Whatever you've got in store, we're ready to scale and expand - up or out - with your business.
We're very interested in where you're planning on taking things - please contact us on Twitter and let us know! We can't wait to see what you build. Especially if it blinks.