Skip to content Skip to navigation Skip to topbar

On this page

Device Resource

(warning)

Microvisor Public Beta

Microvisor is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until Microvisor's General Availability (GA) release.

A Device instance represents a single Microvisor-empowered IoT device. For clarity, device (no cap) refers to physical hardware. Device (initial cap) refers to a Device API resource.

Device resources are accessed at this endpoint:

https://microvisor.twilio.com/v1/Devices

Make a GET request to the endpoint to receive a list (in JSON) of all Device resources.

Every Device instance can be referenced in the API either by its unique SID or a user-defined unique name:

1https://microvisor.twilio.com/v1/Devices/{sid}
2https://microvisor.twilio.com/v1/Devices/{uniqueName}

The Device instance representing a real device is used to deploy uploaded code to that device.

(information)

Info

Customers may request that device data be deleted. If you wish to do so, please contact Twilio Support through the Console or Help Center. For more information on Twilio's data retention and deletion policy, please see this support document.

Device Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<UV>Optional

A 34-character string that uniquely identifies this Device.

Pattern: ^UV[0-9a-fA-F]{32}$Min length: 34Max length: 34

unique_namestringOptional

A developer-defined string that uniquely identifies the Device. This value must be unique for all Devices on this Account. The unique_name value may be used as an alternative to the sid in the URL path to address the resource.

account_sidSID<AC>Optional

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

appobjectOptional

Information about the target App and the App reported by this Device. Contains the properties target_sid, date_targeted, update_status (one of up-to-date, pending and error), update_error_code, reported_sid and date_reported.

loggingobjectOptional

Object specifying whether application logging is enabled for this Device. Contains the properties enabled and date_expires.

date_createdstring<date-time>Optional

The date that this Device was created, given in ISO 8601 format.

date_updatedstring<date-time>Optional

The date that this Device was last updated, given in ISO 8601 format.

urlstring<uri>Optional

The URL of this resource.

linksobject<uri-map>Optional

The absolute URLs of related resources.

Status values

The table below describes the available status values of a Device instance:

Status	Description
`up-to-date`	The device has received with the most recent application code deployed to it
`scheduled`	Application code has been marked for deployment but has yet to be installed on the device
`error`	Application code marked for deployment could not be downloaded for some reason

Get a Device

GET https://microvisor.twilio.com/v1/Devices/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

A 34-character string that uniquely identifies this Device.

Request a single Device resource

1curl -X GET "https://microvisor.twilio.com/v1/Devices/UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3  "unique_name": "This is my device; there are many like it.",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "app": {
6    "target_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "target_hash": null,
8    "date_targeted": "2021-01-01T12:34:56Z",
9    "update_status": "up-to-date",
10    "update_error_code": 0,
11    "reported_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12    "date_reported": "2021-01-01T12:34:56Z"
13  },
14  "logging": {
15    "enabled": true,
16    "date_expires": "2021-01-01T12:34:56Z"
17  },
18  "date_created": "2021-01-01T12:34:56Z",
19  "date_updated": "2021-01-01T12:34:56Z",
20  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "links": {
22    "device_configs": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configs",
23    "device_secrets": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets"
24  }
25}

Get all Devices

GET https://microvisor.twilio.com/v1/Devices

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Request a list of Device resources

1curl -X GET "https://microvisor.twilio.com/v1/Devices?PageSize=20" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "devices": [],
3  "meta": {
4    "page": 0,
5    "page_size": 50,
6    "first_page_url": "https://microvisor.twilio.com/v1/Devices?PageSize=50&Page=0",
7    "previous_page_url": null,
8    "url": "https://microvisor.twilio.com/v1/Devices?PageSize=50&Page=0",
9    "next_page_url": null,
10    "key": "devices"
11  }
12}

Update a Device

POST https://microvisor.twilio.com/v1/Devices/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

A 34-character string that uniquely identifies this Device.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

UniqueNamestringOptional

A unique and addressable name to be assigned to this Device by the developer. It may be used in place of the Device SID.

TargetAppstringOptional

The SID or unique name of the App to be targeted to the Device.

LoggingEnabledbooleanOptional

A Boolean flag specifying whether to enable application logging. Logs will be enabled or extended for 24 hours.

RestartAppbooleanOptional

Set to true to restart the App running on the Device.

Give a Device a memorable name

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateDevice() {
11  const device = await client.microvisor.v1
12    .devices("Sid")
13    .update({ uniqueName: "My Device Name" });
14
15  console.log(device.uniqueName);
16}
17
18updateDevice();

Output

1{
2  "sid": "Sid",
3  "unique_name": "My Device Name",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "app": {
6    "target_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "target_hash": null,
8    "date_targeted": "2021-01-01T12:34:56Z",
9    "update_status": "pending",
10    "update_error_code": 0,
11    "reported_sid": null,
12    "date_reported": "2021-01-01T12:34:56Z"
13  },
14  "logging": {
15    "enabled": false,
16    "date_expires": null
17  },
18  "date_created": "2015-07-30T20:00:00Z",
19  "date_updated": "2015-07-30T20:00:00Z",
20  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "links": {
22    "device_configs": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configs",
23    "device_secrets": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets"
24  }
25}

(information)

Info

Remember, a Device can be identified either by is SID, or by its unique name, if you have applied one.

Deploy an App to the Device

1curl -X POST "https://microvisor.twilio.com/v1/Devices/Sid" \
2--data-urlencode "TargetApp=KAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "sid": "Sid",
3  "unique_name": "UniqueName",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "app": {
6    "target_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "target_hash": null,
8    "date_targeted": "2021-01-01T12:34:56Z",
9    "update_status": "pending",
10    "update_error_code": 0,
11    "reported_sid": null,
12    "date_reported": "2021-01-01T12:34:56Z"
13  },
14  "logging": {
15    "enabled": false,
16    "date_expires": null
17  },
18  "date_created": "2015-07-30T20:00:00Z",
19  "date_updated": "2015-07-30T20:00:00Z",
20  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "links": {
22    "device_configs": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configs",
23    "device_secrets": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets"
24  }
25}

Enable application code logging

1curl -X POST "https://microvisor.twilio.com/v1/Devices/UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
2--data-urlencode "LoggingEnabled=true" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3  "unique_name": "UniqueName",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "app": {
6    "target_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "target_hash": null,
8    "date_targeted": "2021-01-01T12:34:56Z",
9    "update_status": "pending",
10    "update_error_code": 0,
11    "reported_sid": null,
12    "date_reported": "2021-01-01T12:34:56Z"
13  },
14  "logging": {
15    "enabled": false,
16    "date_expires": null
17  },
18  "date_created": "2015-07-30T20:00:00Z",
19  "date_updated": "2015-07-30T20:00:00Z",
20  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "links": {
22    "device_configs": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configs",
23    "device_secrets": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets"
24  }
25}

(information)

Info

Application code logging is enabled by default.

Restart an App

1curl -X POST "https://microvisor.twilio.com/v1/Devices/UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
2--data-urlencode "RestartApp=true" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3  "unique_name": "UniqueName",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "app": {
6    "target_sid": "KAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "target_hash": null,
8    "date_targeted": "2021-01-01T12:34:56Z",
9    "update_status": "pending",
10    "update_error_code": 0,
11    "reported_sid": null,
12    "date_reported": "2021-01-01T12:34:56Z"
13  },
14  "logging": {
15    "enabled": false,
16    "date_expires": null
17  },
18  "date_created": "2015-07-30T20:00:00Z",
19  "date_updated": "2015-07-30T20:00:00Z",
20  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21  "links": {
22    "device_configs": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configs",
23    "device_secrets": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets"
24  }
25}

Restarting an app using this call will instruct Microvisor to start the loaded application afresh. This can be a useful call to make during remote debugging, particularly if your application is experiencing unexpected behavior right after it starts.