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?

Using Twilio Sync with MQTT on a Particle Photon

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.

Sign Up For (or Into) a Twilio Account

Either create a new Twilio account (sign up for a free Twilio trial here), or sign into your existing Twilio account.

Once logged in, head on over to Twilio Device Manager.

Deploy a Fleet of Particle Photons

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:

Locating the default Ffleet in the Twilio Console

Optionally, deploy a new fleet using the API.

        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.

        Once you are familiar with how Fleets are constructed, we're ready to proceed with Deployments.

        Configure the Default Fleet's Deployment

        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:

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

        Now, click through to the new deployment by clicking the 'Configure the Deployment' link.

        Every deployment is configured with a default Service Instance.

        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.

              Create a Particle Photon Device and a Device Key

              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.

              Create a New ESP8266 Device in Deployed Devices

              Now (in your Device configuration) click the 'Keys' link in the left sidebar then the red plus sign (+) to create a new Device Key.

              Create New Device Key Button

              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!

              Create a Device Key in Sync Deployed Devices

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

                    Create a Sync Document

                    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.

                          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.

                          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.

                          Prerequisites to Use a Particle Photon with Sync

                          For this guide's development, we used a Particle Photon with the Particle Web IDE.

                          To skip ahead, here is a link to the code (if you are logged into the Particle IDE, it should clone by default!). Or, grab it from Github here.

                          The TL;DR on that code?

                          • Change sync_key and sync_password
                          • Optionally uncomment the lines which send updates back to Sync
                          • Optionally change the topic (if you renamed the Document)
                          • Flash your Photon!
                                Enter your Device Key and Password to authenticate with Sync MQTT.

                                Add Your Sync Credentials to the Particle IDE

                                Enter your Device Key and Password to authenticate with Sync MQTT.

                                That's the quickest quickstart, but we'll explain a bit of what's happening here...

                                Starting from Scratch

                                In the Particle Web IDE, we installed two libraries:

                                • ArduinoJSON (by Benoit Blanchon - GitHub)
                                • MQTT-TLS (by Hirotaka - GitHub)

                                In the IDE, you can manually install libraries by clicking the 'Libraries' button on the left sidebar:

                                Install Libraries in the Particle IDE

                                ...then you will be guided through a dialog where you choose which saved app to add the library.

                                How to Update Sync from the Photon

                                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.

                                      Send "Hello, World!" from the Particle Photon back to Sync - it will be broadcast to all topic subscribers.

                                      Send updates to Sync from the Photon

                                      Send "Hello, World!" from the Particle Photon back to Sync - it will be broadcast to all topic subscribers.

                                      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.

                                      Burn the Photon and... Release Photons from the LED

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

                                            Particle Photon Blink LED Over Deployed Devices

                                            Boom! Photons from the Photon!

                                            A Fully Synced Internet of Things!

                                            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!

                                            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.