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 an ESP32

In this quickstart, we'll combine the lightweight messaging protocol MQTT with Twilio Sync for IoT, the Arduino IDE, and Espressif's powerful ESP32. We'll walk through the Twilio Device Manager to create a Device Fleet then detail the ESP32 to Sync connection. Last but not least... we'll light up an LED! Let's make some magic and some photons!

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 Sign Up For - 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 Device Manager link to go to the Sync for IoT console.

Deploy a Fleet of ESP32 Things

A Device Fleet is a collection of devices, keys, certificates, and configurations inside of Sync. While you can have multiple fleets, every individual fleet is isolated. That's perfect for the common use case where you want to keep your thing collections from accidentally interacting.

A default Fleet is already provisioned for you automatically, navigate to it in the Device Management console.

Locating the default Ffleet in the Twilio Console

Note it is also easy to deploy a fleet through the REST 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.

        Fleet created, now it's time to work on the deployment.

        Configure the Default Fleet's Deployment

        Twilio will automatically configure a default Deployment once the Fleet is created. The 'Default Deployment' field in your Fleet will be populated similar to the following screenshot:

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

        Click the link labeled 'Configure the Deployment':

        Every deployment is configured with a default Service Instance.

        Twilio also has automatically created a new Sync Service Instance as you can see above. An instance is similar to a database; the updates you make on Sync primitives (such as the Document we use today) are stored only in this one Sync instance.

        As before, you can also create a Deployment through the API.


              Once you've got a handle on the Deployment (and a pointer to the instance), you're ready to create a Device Certificate for authentication.

              Create an ESP32 Device and a Device Certificate

              A Device refers to a particular piece of hardware and is (appropriately enough) managed through the Device Manager. When an IoT device connects to Sync, Twilio will identify the device based upon the credentials you supply, either through a key or certificate. Our ESP32 has the resources to handle a certificate - and we encourage you to use certificate credentialing whenever possible. (See the ESP8266 Sync for IoT guide for an example of device key authentication to Sync).

              Now, inside your Fleet, click the 'Devices' link on the left. Enter a clever or memorable Friendly and Unique name - probably something ESP32 related - then hit the 'Create' button.

              Creating a Device in the Twilio Console

              As seen here, you can also create a Device through the API.


                    Next, when in your fleet, click the 'Certificate' link in the left sidebar followed by the red plus sign (+) to create a new Device Certificate. It will automatically link to the ESP32 device you created a second ago.

                    Enter a friendly name for your certificate and check the 'Self-signed certificate' box. Next, hit the 'Create' button!

                    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. Note: you will not have another chance to do this! You'll have to create a new certificate if you miss this step!

                    As always, you can also create and delete Device Certificates programmatically using the API.


                          In the ESP32 C++ Arduino code, you will be copying the certificate as well as a decrypted key to the certificates.hpp file.

                          Create a Sync Document

                          A Document is the simplest type of Sync object - great for a small application such as an LED blinker. You will have to create that document in some way before you connect your ESP32 to Sync; the Document name will directly map to the subscribed topic of the ESP32. Name your Document 'BoardLED' (case sensitive).

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

                                Prerequisites to Use an ESP32 with Sync

                                You can grab all of our code on Github, here.

                                For this guide's development, we used a ESP32 development board (the 'Developer Edition', from Adafruit) with the Arduino IDE. If you pick the same board, use the 'ESP32 Dev Module' selection from the boards menu in the IDE.

                                Also, we connected an LED to pin 23 on that board then through a resistor to ground, so the LED would be active high. Use a suitable resistor to protect the LED (here is a LED resistor calculator to help).

                                LED Schematic for Deployed Devices and ESP32

                                Any other suitable ESP32 with an LED will work fine, just be sure to change the target pin in the code and select the proper board in the menu.

                                Once you are inside the Arduino IDE, install two libraries:

                                • ArduinoJSON (by Benoit Blanchon - GitHub)
                                • PubSubClient (by Nick O'Leary - GitHub)

                                On my machine, the Library Manager was found through the menu combination 'Sketch' -> 'Include Library' -> 'Library Manager'. The libraries are installed and managed directly inside the IDE.

                                Add Your Credentials to the ESP32

                                A few steps above, you created a certificate for the ESP32 and downloaded an encrypted key and certificate. You will now need to add your decrypted client key and your client certificate.

                                Let's start with the client certificate - it can be used verbatim. In the Arduino IDE, go to the certificates.hpp file.

                                1. Open the CYxxx.pem client certificate file in your choice of text editor and copy everything (including the lines which start with hyphens ['---']).
                                2. Paste it all between the () into client_cert inside certificates.hpp:
                                  const char* client_cert = R"(PASTE_IT_HERE)";​
                                  You can look at the root_cert for a hint if you need help.
                                3. Before you can paste the key, you have to decrypt the .key file. On *NIX, this can be done with:
                                  openssl rsa -in  CYxxxxxxxxxx.key -out CYxxxxxxxxxx.key.decrypted​
                                  Enter your password to decrypt it.
                                4. Open it your choice of text editor and copy the decrypted key (again including the hyphen lines).
                                5. Paste it all between the () into client_key inside certificates.hpp:
                                  const char* client_key = R"(PASTE_IT_HERE)";​

                                      In certificates.hpp, paste your decrypted client key and your client certificate you downloaded.

                                      Paste Your Client Key and Certificate

                                      In certificates.hpp, paste your decrypted client key and your client certificate you downloaded.

                                      Once you've added your client key and certificate, we can turn our attention to the .ino file.

                                      Edit the Code with Your WiFi Credentials

                                      Switch tabs to the .ino file now. You'll need to make edits to the C++ sketch to get it on your network:

                                      • ssid
                                      • password
                                            Add your WiFi SSID and password to connect to a friendly WiFi network with the ESP32.

                                            Connect to Sync for IoT with an ESP32

                                            Add your WiFi SSID and password to connect to a friendly WiFi network with the ESP32.

                                            The next two variables may not have to change; if you didn't name your Sync Document BoardLED you will have to change it here though.

                                            • sync_document
                                            • sync_device_name

                                            If you are not using an LED on pin 23, be sure to also change LED_PIN.

                                            Upload the Code to the ESP32 and Blink the LED

                                            Once all the variables are set, it's blinky time.

                                            Upload the code to the ESP. Open the Arduino Serial Monitor (the menu 'Tools' -> 'Serial Monitor'). You should see something like this streaming over serial:

                                            WiFi connected!  IP address:
                                            Attempting to connect to Twilio Sync...
                                            Connected!  Subscribing to sync/docs/BoardLED
                                            Message arrived on topic {"led":"OFF"}
                                            LED turned off!

                                            But wait - there's more! Let's blink that LED. Use the following code to send an UPDATE request to Sync and change the state of led.


                                                  Boom! Light!

                                                  You'll see three updates in quick succession:

                                                  • Sync will respond letting you know the command was successful
                                                  • The LED will light up
                                                  • You'll get a happy message from the ESP32 over serial

                                                  ESP32 Blinking Over Sync Deployed Devices

                                                  Updating Sync from the ESP32

                                                  If you look in the code, there are a few commented out lines which show how to send updates back from the ESP32. Remove the comments to send a msg back to Sync.

                                                        Uncomment these lines to send data back to Sync on a timer.

                                                        Optionally Send Data Back to Sync

                                                        Uncomment these lines to send data back to Sync on a timer.

                                                        Note that whatever you send should be in JSON format. You can generate JSON through the ArduinoJSON library rather simply, or craft it inline like we've done here.

                                                        The Internet of Synced Things

                                                        It's that simple - blinky lights and a ESP32 all mediated through a Sync Document with the power of Twilio's Sync for IoT and MQTT.

                                                        Now you can take this infrastructure in any direction you desire, sharing the BoardLED Document across many devices - or perhaps using it on your server and creating a dashboard. Wherever you take it, let us know what you've built 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.