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:
- Create a device record in the Twilio Console,
- provision credentials for the device,
- connect that device using MQTT, and
- 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.
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.
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.
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.
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.
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.
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 \
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.
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.
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.