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 Electron

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.

Sign Into (or Up For) a Twilio Account

Sign up for a free Twilio trial here if you need a Twilio account, or sign into your existing Twilio account.

Once logged in, visit the console for Twilio Device Manager.

Deploy a Fleet of Particle Electrons

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.

Locating the default Ffleet in the Twilio Console

You can also deploy a 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 Fleets, it's time to move to Deployments.

        Configure the Default Fleet Deployment

        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:

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

        Click through to the new deployment through the 'Configure the Deployment' link.

        Every deployment is configured with a default Service Instance.

        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!

              Create a Particle Electron Device and a Device Key

              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:

              Create a New ESP8266 Device in Deployed Devices

              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:

                    Create New Device Key Button

                    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!

                    Create a Device Key in Sync Deployed Devices

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

                          Create a Sync Document

                          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.

                                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 also set the key 'led' to 'OFF'. Logic on the Electron will then keep that LED unlit when it connects.

                                Prerequisites to Use a Particle Electron with Sync

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

                                Ready to run? Here is a link to the code (if you are logged into the Particle IDE, cloning comes by default!). Optionally, you can also grab it on Github.

                                Here's all you need to do to sync with Sync:

                                • Edit sync_key and sync_password
                                • (Optionally) change the topic (ONLY if you renamed the Document)
                                • Flash your Electron!
                                      Change your key and password in the code to connect your Electron to Sync for IoT.

                                      Edit Credentials on the Electron to Connect

                                      Change your key and password in the code to connect your Electron to Sync for IoT.

                                      Let's take a closer look at how this works.

                                      Library Inclusiuon

                                      We installed two libraries in the Particlde Web IDE:

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

                                      You can manually install libraries by clicking the 'Libraries' button on the left sidebar:

                                      Install Libraries in the Particle IDE

                                      A dialog will appear that will guide you to choose the application.

                                      How to Update Sync from the Electron

                                      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.

                                            Leave the lines uncommented to send data back through Sync on a timer.

                                            Optionally Send Data Back to Sync

                                            Leave the lines uncommented to send data back through Sync on a timer.

                                            Every (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.

                                            Flash the Electron and Send Electrons Through the LED

                                            Flash the code to the Electron and optionally open a serial monitor. For *NIX we like screen, on Windows we like PuTTY.

                                            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

                                                  Particle Electron Deployed Devices

                                                  Wow - look at those electrons flow from the Electron!

                                                  A Fully Synced Internet of Things!

                                                  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.

                                                  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.