Enrolling and deploying devices is at the crux of IoT Device Manager. In this guide, we will go through the process of registering your devices in the system and deploying them in order to get access to Twilio services.
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.
In order to enable connectivity for your devices, you will first want to make them known to Twilio Runtime. There is a couple of problems we are solving by explicitly registering your connected endpoints.
- Device identification: since IoT devices are typically connected to physical environment, we want to interpret the data they send or receive in correct context.
- Device authentication: we want to ensure that device identity is trustworthy and related security threats are mitigated.
In the most basic case, your new devices should get registered under a default fleet, assigned to a default deployment of that fleet.
- Log into Twilio developer Console and navigate to Device Manager > Default Fleet > Devices.
- Click the Create new Device button (+)
Supply some attributes for device identification purposes:
- Optionally, specify a Friendly Name for your device. A friendly name can contain any human readable text that helps you to understand and track the purpose of your device in the future. If you leave this field blank, friendly name will be null in the REST API.
- Optionally, specify a Unique Name for your device. Unlike the friendly name above, unique name is machine readable (e.g. device serial number), and may be used as a handle to access the device resource programmaticaly, via the REST API. As its name suggests, there can be only one device with given unique name in the current fleet, and an attempt to create another one with the same name will conflict and fail. If you leave the unique name blank, a randomly generated SID will be displayed instead in the fleet listing table. Unlike the friendly name, the unique name is immutable and cannot be changed after a device gets created.
Optionally, supply some attributes for device configuration purposes:
- Optionally, specify an Identity to associate a human identity with your device. In a wearable application example, this could contain a string (e.g. obfuscated email, etc) that uniquely identifies a human wearing a wireless sensor. Providing this mapping in the device registry enables us to convey additional context with the events that your application generates, also restricting access to data via ACL. In case this field is left blank, the device SID will be used instead to represent the device identity in Twilio Runtime service stack.
- Optionally, provide a Deployment SID for your device configuration. If this field is left blank, a default deployment configuration will be used instead. Refer to Configuring Deployments section below for more details on how to set up your deployments.
- Leave the Enabled box checked if you want to allow your device to connect to Twilio right away. Disabling the device blocks its connectivity, as our gateways will reject all connection atempts. You can use this flag e.g. to perform device maintenance and ensure that it does not send or receive wrong data while being in a transient or incomplete state.
Your new device is now created and 4 auto-populated attributes are displayed.
- Device SID: automatically generated SID is the way to uniquely identify and address your device. Additionally, you may use a unique name instead, if one was provided.
- Date authenticated: contains date/time of the last successful authentication, i.e. the time when this device last connected to any Twilio gateway.
- Date created: contains current date/time, will never change after creation.
- Date updated: contains date/time of the last device resource update, which is initially set to the creation time.
In a similar manner, you can later locate your created devices in the fleet listing and update their attributes. Most device attributes listed above are mutable, with one notable exception of the unique name, which is immutable in order to guarantee uniqueness.
- Log into Twilio developer Console and navigate to the fleet that contains your devices, e.g. Device Manager > Default Fleet > Devices.
- Click on the device that you wish to remove and click on Delete this Device link.
Note: device removal is a destructive and irreversible operation. The credentials that were paired with the removed device are not deleted, and are instead de-associated. You can either remove or repurpose device certificates or keys later, and meanwhile their Device SID attribute is going to be reset. For details on credential management, please refer to Adding Credentials section.
Registering devices with IoT Device Manager makes them recognized by the system, but does not yet prime to access Twilio services. By assigning your devices to deployments, we group them to enable easy access to shared configuration, and link to specific service instances. The default deployment has already been created under your fleet, and it will automatically capture all devices enrolled to that fleet, unless you provide an override (see Deployment SID attribute under Enrolling Devices section above).
The default deployment is also linked with a newly created Sync service instance for your convenience. You can locate the instance by following the "Configure this Instance" shortcut under the deployment resource in Twilio developer Console, which leads to the Sync service configuration page. Alternatively, you can navigate to Sync Services listing and locate an instance where Friendly Name contains "Default deployment of <fleet friendly name or SID>".
For more advanced applications, a single default deployment of the fleet may not be sufficient. Instead, you may prefer to create additional deployments within the same fleet. In the Developer Preview phase of Sync for IoT, we support a couple of ways how additional deployments may be useful.
- Data access isolation: deployment attributes can configure a different Sync service instance, where the device data is projected to.
- Sub-fleet device grouping: you can use deployments as sub-groups of the fleet, and browse devices using deployment specific filters.
Follow these steps in order to create a new deployment.
- Log into Twilio developer Console and navigate to Device Manager > Default Fleet > Deployments.
- Click the Create new Deployment button (+)
- Optionally, specify a Friendly Name for your deployment. If you leave it blank, a randomly generated SID will be displayed instead in the deployment listing table, and it will be tricker to find later.
- Optionally, specify a Sync Service Instance linked with your deployment. The dataset, i.e. objects published and subscribed to by your devices, is going to hosted in this Sync service, identified by SID (ISxx). You can locate a suitable Sync service by clicking on the "Configure this Instance" link and picking one. If you don't have a separate Sync service created yet, feel free to do it now by navigating to Sync Services in developer Console.
- Your new deployment is now created and is currently not associated with any devices yet. The deployment contains 3 additional auto-populated attributes.
- Deployment SID: regardless of whether the friendly name was set or not, the resulting SID is going to be unique way to address your deployment.
- Date created: contains current date/time, will never change after creation.
- Date updated: contains date/time of the last deployment resource update, which is initially set to the creation time.
In a similar manner, you can later locate your created deployments in the fleet listing and update their attributes.
- Log into Twilio developer Console and navigate to the fleet that contains your deployments, e.g. Device Manager > Default Fleet > Deployments.
- Click on the deployment that you wish to remove and click on Delete this Deployment link.
Note: deployment removal is a destructive and irreversible operation. The devices that were mapped and configured by the removed deployments are not deleted, and are instead de-associated. You can assign released devices to a different deployment, and meanwhile their Deployment SID attribute is going to be reset.
Like everything in Twilio, all above functions may be invoked from your service backend programmatically, via REST APIs.