-
Notifications
You must be signed in to change notification settings - Fork 37
Showing devices on a Map
The list of devices is provided by the IoT Hub Manager API.
The device telemetry, which includes the (geo)location, is provided by the Device Telemetry API.
The user selects a device group, which implicitly define the query to use to fetch the list of devices. See the Config UI API for more information.
GET {IoT Hub manager endpoint}/devices?query={query}
Content-Type: application/json; charset=utf-8
{
Count: ...
Items: [
{ device }
{ device }
{ device }
...
]
"$metadata": {
$type: DevicesList;1
$uri: {IoT Hub manager endpoint}/devices?query={query}
}
}
Note that the content of the response might change over time, for instance when devices are added or removed, and when device properties change. For instance a query like "all devices with firmware 1.2" would return a different list over time. The UI decides whether to cache and reuse the query result, or whether to repeat the query to refresh the response.
For a given period, the UI gets the telemetry from the Device Telemetry API. Each telemetry record includes the location, which is just a value like any other. Some devices might not provide a location, in which case they won't appear in the map. The most recent telemetry message is sufficient to locate the device, so the UI asks only for the last record for each device (using order=desc
and grouplimit=1
).
The color and size of the device marker on the map might depend on the telemetry values. For example, the size of the marker could depend on the temperature value, or the number of people in a building, etc. To set a device color using it's alert status instead, see "Coloring markers on a Map using alerts data".
Request with GET:
GET {Device Telemetry endpoint}/messages?from={time}&to={time}&order=desc&grouplimit=1&devices=id1,id2,id3,...
Request with POST:
POST {Device Telemetry endpoint}/messages-query
Content-Type: application/json; charset=utf-8
{
From: {time}
To: {time}
Order: desc
GroupLimit: 1
Devices: [ id1, id2, id3, ... ]
}
Content-Type: application/json; charset=utf-8
{
Items: [
{
deviceid
time
value 1
value 2
value N
$metadata
},
{
deviceid
time
value 1
value 2
value N
$metadata
},
...
],
"$metadata": {
$type: MessagesList;1
$uri: ...
}
}