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?

Python Quickstart for Twilio Sync for IoT

This guide will demonstrate how to use the Twilio Device Manager and the Paho Python MQTT client for python to experiment with Sync's IoT support using only your laptop and a Python interpreter. We're going to:

  1. Create a device record in the Twilio Console,
  2. provision credentials for the device,
  3. connect that device using MQTT, and
  4. collaborate over Sync objects.

To get off the ground, we're going to do all this using our localhost machine, to show the infrastructure in motion. But the very same code could just as well be deployed to a physical hardware device. And as always with Twilio, everything comes with a REST API so you can automate these steps at well. After working through this guide, we encourage you to check out the Device Management API documentation and dig further in to the possibilities.

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.

Provision a Device Fleet and Deployment

Our first step is to provision a Device Fleet. Fleets are isolation containers for your devices, their credentials, and deployments. Within a Fleet, each of those may be reassigned or reassociated with each other, but across fleets your configuration and credentials are safely isolated. We’ll create our fleet in the Console Device Manager, clicking the plus sign and Create. No need to fill in any fields just yet.

Creating a fleet in the Twilio Console


        Now, a fleet on its own doesn’t express any behavior for your devices. To what resources a device is bound — in our case, a Sync instance — is configured by a Deployment; your solutions will always have at least one deployment.

        In our case, since we just created a fleet, you’ll notice right away that the new fleet already has a default deployment configured, which itself is preconfigured with a brand new Sync instance. This Sync instance will contain the data we exchange with our test device.

        A default deployment is automatically provisioned for each new Device Fleet.
        Every deployment is configured with a default Service Instance.

        As your app grows, you can consider using multiple sync instances and multiple deployments to isolate your users and their application state. For now, we’ll rely on these convenient defaults to get going.

        Create a Device and its Credentials

        In the Device Manager REST API, a Device represents a connection from a deployed unit of hardware. The connecting hardware identifies itself with its credential, and that determines to which Deployment it pertains. For optimum security, we recommend certificates and TLS-secured connections from MQTT devices, so that’s what we’ll show you here.

        Creating a device is predictably simple. From your default deployment, click Devices in the left menu, select Create a Device (or the plus sign, if you already have some), and fill in the Deployment SID from the previous step. You can leave all the other fields blank for now.

        Creating a Device in the Twilio Console

        This will show you a simple overview of the device. From here, explore the list of Certificates (from the contextual menu on the left) and create a new certificate. In the future, you can provide your own signed certificates here; for the moment, choose the self-signed variation. After creation, download the certificate and the key. Also make note of the password.

        Create a Device Certificate
        Download your Device Certificate Key

        You will provide these two data — a certificate (.pem) and the matching encrypted private key (.key) — to the Paho MQTT client. Paho needs the latter in unencrypted form, so using the passphrase from above.

        $ openssl rsa -in CY499a5cbd774f4970a9ab51e2e8c4fb57.key \
        -out CY499a5cbd774f4970a9ab51e2e8c4fb57.key.decrypted

        Create a Sync Document

        The simplest of Sync Objects is a Document, and today an object must exist before an MQTT device can subscribe to it. So let’s do that, using Postman, Curl, or one of the Twilio Helper Libraries.

              Use the Sync Service SID (`ISxxx`) from your default deployment, above.

              Create a Sync Document

              Use the Sync Service SID (`ISxxx`) from your default deployment, above.

              Subscribe to the Sync Document from MQTT

              Paho is a commonly-used Python MQTT client. In our penultimate step here, we’ll initialize that client with the provisioned certificate so we can test the end-to-end flow.

              $ pip install paho-mqtt

              Copy the python script here to a file and edit it with the locations of your actual certificate files.

                    Run this from the terminal, or deploy it to a device.

                    Subscribe your MQTT Client to the Document

                    Run this from the terminal, or deploy it to a device.

                    When you run this script, the current current state of MyDoc will be printed upon connection; this is the impact of qos=1 in an MQTT client subscribing to Sync Objects. The subscription is live; if we touch the same document again, we’ll see another message printed out.

                          The new data will appear as an MQTT message in the running client.

                          Update the Document

                          The new data will appear as an MQTT message in the running client.

                          Next Steps

                          From here, you can experiment with publishing to MQTT, subscribing to various different objects, restarting the client to see how sync recovers state, and explore the in-browser and mobile SDKs of Sync itself.

                          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.