# 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](https://admin.wifi.unwired.at/developer/playground).

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:

```graphql
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:

```json
{
  "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:

```graphql
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.

```javascript
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.

```javascript
socket.on("event", ({ mac, type, data }) => {
  // handle data of event
});
```

### Javascript Example

```javascript
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

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

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

```json
{
  "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"
}
```