In this guide, we'll show you how to use the lightweight messaging protocol MQTT with Twilio Sync for IoT and Particle's Photon WiFi IoT Platform. We'll cover the Twilio Device Manager and Device Fleets, then cover connecting your Photon to Sync to make API calls and blink that blue LED onboard.
Get excited - it's internet blinking time!
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, head on over to Twilio Device Manager.
In Sync, when we talk about a Device Fleet we're referring to a collection of devices, keys, certificates, and configurations. While you can create many fleets, the fleets themselves will be isolated from each other.
Sync automatically creates one Default Fleet for you; get started by navigating to it in the Device Management console:
Optionally, deploy a new fleet using the API.
Once you are familiar with how Fleets are constructed, we're ready to proceed with Deployments.
As soon as your Default Fleet is ready, Twilio will also automatically configure a default Deployment. You'll see that the 'Default Deployment' field in your Default Fleet is populated, matching the following picture:
Now, click through to the new deployment by clicking the 'Configure the Deployment' link.
As you can see, Twilio also has also automatically linked your deployment with a default Sync Service Instance.
Instances work like databases; all of the data from the 'conversation' you'll have with the Photon (or any other device you add to this Deployment) will be stored in this one Sync instance.
You can also configure a new Deployment through the API, as shown in the following snippet.
Once you've wrapped your head around the Deployment, you're now ready to create your first Device and a Key for the Photon's authentication.
In the Device Manager, a Device is a piece of hardware.
When some hardware connects, Twilio determines which Device it should match with based on the credential it provides, either a certificate or a key. While Certificates are preferred when possible, we'll be using Device Keys today to authenticate the Photon.
While inside your Fleet, click the 'Devices' link on the sidebar. If you're in the mood, enter a Friendly and/or Unique name, then hit the 'Create' button.
Now (in your Device configuration) click the 'Keys' link in the left sidebar then the red plus sign (+) to create a new Device Key.
The Device SID should automatically be populated in the appropriate field (but can always be found by navigating back into the Deployment to your Device). Enter a Unique Name then 'Create'. Save both the Key and the Secret once your key is created - once the secret is lost, you can't recover it!
As before, you can also create and delete Device Keys using the API. Here's an example of doing it programatically:
In the C++ Photon code, 'KEY' will take the value of
sync_key, while 'SECRET' will go in
A Document is the simplest type of Sync object and perfect for sharing state in a small application... like blinking an LED. Note that you have to create this Document before you connect your Photon to Sync; the Photon will connect to the topic based upon the name of this Document.
While creating it, we also initialize 'led' to 'OFF'. When the Photon connects, it will receive this message and (of course) keep the onboard LED unlit.
The TL;DR on that code?
- Optionally uncomment the lines which send updates back to Sync
- Optionally change the topic (if you renamed the Document)
- Flash your Photon!
That's the quickest quickstart, but we'll explain a bit of what's happening here...
In the Particle Web IDE, we installed two libraries:
In the IDE, you can manually install libraries by clicking the 'Libraries' button on the left sidebar:
...then you will be guided through a dialog where you choose which saved app to add the library.
Using our code, you can also choose to send updates back to Sync. While we imagine you'll send sensor readings, timings, or events back our code currently is just sending back a "Hello, World!" message.
If you uncomment those lines, every
(2*(1000*60)) milliseconds (2 seconds) the Photon will send a message back to Sync. Embedded in that message is a command to turn the LED back on, and a happy greeting. Yes, the Photon will send a message that results in the Photon releasing photons. (We heard you like Photons...)
While we have written properly formatted JSON directly into that code, you can also use ArduinoJSON to format a JSON string for you. For more complex updates, we'd suggest familiarizing yourself with the library.
Once all the variables are set, you're ready to rock. Upload the code to the board and (optionally - if you're connected over USB to the Photon) open a serial monitor. On *NIX we like screen, on Windows we like PuTTY.
Assuming you entered everything correctly it should be all happy messages, but you should see a basic debugging readout otherwise.
If it's working? Let's blink that LED! Use the Document UPDATE call, now setting 'led' to 'ON'.
You should see two updates - one from Sync in your language or on the command line informing you the update went through, and another on the device (the LED!).
Boom! Photons from the Photon!
Now you've got a blinking LED on your Particle Photon, all backed up with the synchronized power of Sync for IoT. Now you can build out or build up, the infrastructure backing that little light is ready to scale in whichever direction you need - Twilio is ready for it all.
Let us know what you've built - or what you're building - by contacting us on Twitter!