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: "modemd-signal", 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: "modemd-signal", macs: ["555527054B8D"] });
});

Message Types

These types of telemetry events are available through the API at the moment:

Modem Telemetry - `modemd-signal`

The modemd-signal event is sent regularly by the device and contains information about the modem signal quality and the current state of the modem. It can also contain the current GPS location of the device if the device has GPS capabilities.

{
  "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`

The SMS event is sent when an SMS is received by the device. It includes context information about the SMS and how it was received.

{
  "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`

The self test event is sent when the device performs a self test. It includes information about the test results.

{
  "time": "2019-04-01T20:43:57Z",
  "status": "FAIL",
  "wifi": {
    "found": 1,
    "status": "OK",
    "system": 1
  },
  "wwan": {
    "found": 0,
    "status": "FAIL",
    "system": 0
  }
}

Heartbeat - `heartbeat`

The heartbeat event is sent regularly by the device to signal that it is running. It includes information about the uptime of the device and the hash of the current configuration.

{
  "time": "2019-04-01T20:43:57Z",
  "uptime": 12345,
  "config_hash": "config hash"
}