Telemetry API
The telemetry API consists of two parts, the GraphQL API and the socket.io API for live telemetry.
GraphQL API to get historical telemetry data
The API can be accessed through the Unwired Edge Cloud Console Developer Tools.
The GraphQL API can be used to get historical data. It uses a pagination mechanism to get the data in chunks. You have to specify the time range you want to get data for and the number of messages you want to get per request. The API will return a cursor that can be used to get the next chunk of data. The cursor is next_cursor and must be passed to the next request as cursor parameter. Repeat this until the next_cursor is null.
The before parameter is exclusive, so the message with the timestamp specified in before will not be included in the response, the after_or_at parameter is inclusive, so the message with the timestamp specified in after_or_at will be included in the response.
This API is limited to our data retention policy, which is currently 14 days.
Request example:
query DM_get_devices_messages {
DM_get_devices_messages(
macs: ["555527054B8D"]
type: modemd_signal
after_or_at: "2023-12-05T00:00:00Z"
before: "2023-12-06T00:00:00Z"
take: 2
) {
next_cursor
messages {
mac
type
data
}
}
}
Response could look like:
{
"data": {
"DM_get_devices_messages": {
"next_cursor": "time:1702312764000,id:ois1WYwBs1Jz1YAEcH4z",
"messages": [
{
"mac": "555527054B8D",
"type": "modemd_signal",
"data": "{\"device\":\"555527054B8D\",\"interface-metric\":1201,\"mode\":\"LTE\",\"modemid\":1,\"modemstate\":\"connected\",\"operator-name\":\"3 AT\",\"quality\":94,\"received\":\"2023-12-05T23:59:58.56170222Z\",\"rsrp\":-83,\"rsrq\":-11,\"rssi\":-55,\"slotid\":1,\"snr\":9.4,\"state\":\"connected\",\"time\":\"2023-12-05T23:59:58Z\"}"
},
{
"mac": "555527054B8D",
"type": "modemd_signal",
"data": "{\"device\":\"555527054B8D\",\"interface-metric\":1200,\"mode\":\"LTE\",\"modemid\":0,\"modemstate\":\"connected\",\"operator-name\":\"3 AT\",\"quality\":100,\"received\":\"2023-12-05T23:59:55.956741958Z\",\"rsrp\":-79,\"rsrq\":-9,\"rssi\":-51,\"slotid\":0,\"snr\":13.4,\"state\":\"connected\",\"time\":\"2023-12-05T23:59:55Z\"}"
}
]
}
}
}
For pagination add the next_cursor to the the next request as cursor variable:
query DM_get_devices_messages {
DM_get_devices_messages(
macs: ["209727054B8D"]
type: modemd_signal
after_or_at: "2023-12-05T00:00:00Z"
before: "2023-12-06T00:00:00Z"
take: 2
cursor: "time:1702312764000,id:ois1WYwBs1Jz1YAEcH4z"
) {
next_cursor
messages {
mac
type
data
}
}
}
Live Telemetry
We provide subscription based live telemetry data through a socket.io API. You can subscribe to 1..n devices and get all telemetry data for that device in real time.
Socket.io has a well defined protocol to connect to the server and subscribe to events. You can find a good documentation here: https://socket.io/docs/v4/client-api/
Caution
Events might NOT be transmitted in order or in real time if the device has e.g. bad reception.
Your application should be able to handle this. Use data.time to sort the data in the correct order, which is the time the event was created on the device.
The field .received will indicate when the data was received by the server.
Endpoint
The endpoint for the socket.io API is https://admin.wifi.unwired.at/socket.io.
The namespace must be /devices.
Authentication
The socket.io API uses the same authentication mechanism as the GraphQL API. You need to provide a valid API key or the user JWT in the HTTP Authorization header. The API key must have at least the Device Reader role.
Example api key header:
"authorization: apikey 1234567890abcdef1234567890abcdef"Example jwt key:
"authorization: bearer eyJhb..."
Subscription
To subscribe to events you need to send a subscribe event to the server. The event must have a type and macs field. The type field is the type of telemetry event you want to subscribe to, the macs field is an array of mac addresses you want to subscribe to.
socket.emit("subscribe", { type: params.type, macs: ["555527054B8D"] });
The server will respond with an ACK event if the subscription was successful or an ERROR event if the subscription failed.
The socket.io client has to listen on the event event to receive telemetry data.
All subscribed events will be received on that channel, so you have to filter the incoming events by the type and mac field.
socket.on("event", ({ mac, type, data }) => {
// handle data of event
});
Javascript Example
import io from "socket.io-client";
// Note that socket.io-client automagically adds socket.io to the path between the host and the namespace. This might be different with other client implementations.
const socket = io("wss://admin.wifi.unwired.at/devices", {
addTrailingSlash: true,
withCredentials: true,
extraHeaders: {
authorization:
"apikey 57993d741de6d95b080de5fdd6cef748d42802fe43e721b20abcdefh",
},
});
socket.on("event", ( mac, type, data }) => {
// handle data of event
console.log(data);
});
socket.on("connect", () => {
console.log("connected");
socket.emit("subscribe", { type: params.type, macs: ["555527054B8D"] });
});
Message Types
These types of telemetry events are available through the API at the moment:
Modem Telemetry - modemd-signal
can include GPS data
{
"device": "555527054B8D",
"interface-metric": 1201,
"mode": "LTE",
"modemid": 1,
"modemstate": "connected",
"operator-name": "3 AT",
"quality": 94,
"received": "2023-12-05T23:59:58.56170222Z",
"rsrp": -83,
"rsrq": -11,
"rssi": -55,
"slotid": 1,
"snr": 9.4,
"state": "connected",
"time": "2023-12-05T23:59:58Z",
"location": {
"latitude": 48.20849,
"longitude": 16.37208,
"speed": 0
}
}
SMS Telemetry - sms
{
"message": "your data is used up",
"time": "2019-04-01T20:43:57Z",
"sender_number": "+1234",
"sms_received_at": "2022-04-01T20:43:57Z",
"slot_id": "unknown",
"imei": "12337389457230984"
}
Self Test - selftest
{
"time": "2019-04-01T20:43:57Z",
"status": "FAIL",
"wifi": {
"found": 1,
"status": "OK",
"system": 1
},
"wwan": {
"found": 0,
"status": "FAIL",
"system": 0
}
}
Heartbeat - heartbeat
{
"time": "2019-04-01T20:43:57Z",
"uptime": 12345,
"config_hash": "config hash"
}