Near Real-Time Device Status

Background

The deviceStream API is a scalable GraphQL Subscription API that enables real-time monitoring of various key attributes of Poly devices and provides an update when their values change. Most notably this includes the connection status between Poly devices and the Poly Lens cloud. If a device disconnects from the Poly Lens cloud, it likely means the device has stopped working and is no longer connected to the outside network.

With this API, you can monitor multiple devices at once using a single GraphQL Subscription stream, making it an effective tool for overseeing devices in VIP rooms, spotting devices with connectivity problems as soon as they run into issues, or any scenario where prompt alerts are crucial.

Arguments

The deviceStream subscription API needs the following arguments. The values are case-sensitive.

Argument	Description	Type
`deviceIds`	Unique identifier of the device(s) you want to monitor; Array type argument; Accepts multiple device IDs to monitor.	`[String!]!`

Fields

The deviceStream subscription API returns the following fields.

Field	Description	Type
`connected`	Connection status between Poly device and Poly Lens cloud.	`Boolean`
`externalIp`	External IP address of the device.	`String`
`hardwareRevision`	The revision number of the device's hardware.	`String`
`id`	Unique identifier of the device.	`String!`
`macAddress`	Mac address of the device.	`String`
`modelId`	The unique model name or number of the device .	`String`
`name`	Official name of product without manufacturer name, e.g. Studio P15.	`String`
`productId`	Product identifier of the device.	`String`
`roomId`	Unique identifier of the room.	`String`
`siteId`	Unique identifier of the site.	`String`
`softwareBuild`	Unique identifier of the ‘build’ of the device software. This helps differentiate different builds within the same version.	`String`
`softwareVersion`	Product software version.	`String`
`tenantId`	The Poly Lens account identifier of the device.	`String`

`deviceStream` Subscription API in the Poly Lens GraphQL Playground - Monitoring Device Connection Status

Let's consider a scenario where you need to be promptly notified if a device in a VIP room loses its connection to the Poly Lens Cloud, likely indicating that the device may no longer be operational. To monitor for connectivity state changes, you can use the following query.

See this subscription in the GraphQL Playground.

subscription DeviceStream($deviceIds: [String!]!) {
 deviceStream(deviceIds: $deviceIds) {
  connected 
  id
  }
}

Arguments passed for the above query

{
  "deviceIds": ["xxxxxxxxxxxxxxxxxxxxxxxxxxxx240e", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxa5f0"]
}

Important Note: The API stream is engineered to track state changes across multiple devices simultaneously. To prevent exceeding rate limits, it's highly recommended to use a single API stream for multiple devices. This can be achieved by listing device IDs separated by commas within an array, as illustrated in the example above.

Response for the above query

Now, if you disconnect one of the devices, the Poly Lens deviceStream Subscription API will return a response with the value of the connected field as false. Then, when you reconnect the device, the API will return a response with the value of the connected field as true.

// Response received at 21:15:50
{
  "data": {
    "deviceStream": {
      "connected": true, 
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxa5f0"
    }
  }
}

// Response received at 21:04:31
{
  "data": {
    "deviceStream": {
      "connected": false,
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxa5f0"
    }
  }
}

The `deviceStream` Subscription API in the Poly Lens GraphQL Playground – Monitoring Other Attributes

Now suppose you want to monitor certain devices for changes in the rooms or sites (with which those devices are associated), or for changes in device software version etc. You can do it using this API. In fact, you can monitor for changes in values of any of the fields in this API. See the below example.

See this subscription in the GraphQL Playground.

subscription DeviceStream($deviceIds: [String!]!) {
 deviceStream(deviceIds: $deviceIds) {
  connected
  externalIp
  hardwareRevision
  id
  macAddress
  modelId
  name
  productId
  roomId
  siteId
  softwareBuild
  softwareVersion
  tenantId
 }
}

Arguments passed for the above query

{
  "deviceIds": ["xxxxxxxxeef4"]
}

Response for the above query

Now, if you move a device from a certain room at a certain site to a different room at a different site, the deviceStream Subscription API will return a response with updated values for the fields roomId and siteId.

// Response received at 20:26:46
{
  "data": {
    "deviceStream": {
      "connected": true,
      "externalIp": "xx.xxx.xxx.70",
      "hardwareRevision": "7",
      "id": "xxxxxxxxeef4",
      "macAddress": "xx:xx:xx:xx:xx:f4",
      "modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx18a8",
      "name": "G7500",
      "productId": "G 7500",
      "roomId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxc4f1",
      "siteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxf199",
      "softwareBuild": "1011026",
      "softwareVersion": "4.1.0",
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8028"
    }
  }
}

// Response received at 20:20:27
{
  "data": {
    "deviceStream": {
      "connected": true,
      "externalIp": "xx.xxx.xxx.70",
      "hardwareRevision": "7",
      "id": "xxxxxxxxeef4",
      "macAddress": "xx:xx:xx:xx:xx:f4",
      "modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx18a8",
      "name": "G7500",
      "productId": "G 7500",
      "roomId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx7c2a",
      "siteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx09fa2",
      "softwareBuild": "xxx1026",
      "softwareVersion": "4.1.0",
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8028"
    }
  }
}

Summary

The deviceStream subscription API is just a small example of the power of the Poly Lens GraphQL Subscription APIs. We'll be updating this page with more examples over time. If you have specific content requests or questions, reach out to DL-DeveloperSupport@poly.com.

Background​

Arguments​

Fields​

deviceStream Subscription API in the Poly Lens GraphQL Playground - Monitoring Device Connection Status​

The deviceStream Subscription API in the Poly Lens GraphQL Playground – Monitoring Other Attributes​