---
title: MQTT APIs
tags: ThingsBoard
image: https://i.imgur.com/F18K3Oq.png
disque: hackmd
---

# MQTT APIs


[toc]

## MQTT Gateway APIs
:::info
* 網關(gateway)是TB平台中一種特殊類型設備，能夠充當連接到不同系統的外部設備和TB之間的橋樑。
* MQTT Gateway APIs提供使用單個MQTT連線，連接了多個設備和TB平台之間交換感測資料的能力。
* https://thingsboard.io/docs/reference/gateway-mqtt-api/
* 網關硬體基本上不受限，若未安裝TB Gateway軟體與相對應的Connectors，則需自行處理感測設備與網關間的介接，感測資料回傳僅需遵循MQTT Gateway APIs文件即可。
* 網關同時也是TB平台中的設備，可以利用現有的MQTT設備API，更新配置和接收設備相關訊息。
* https://thingsboard.io/docs/reference/mqtt-api/
:::

### Telemetry Upload Example
* Telemetry upload API (ts: timestamp, [Epoch](https://www.epochconverter.com/) timestamp in milliseconds)
* Topic to publish: v1/gateway/**telemetry**
* Payload type: Strings/JSON/XML/Characters
* Payload

{
   "UGS 000001":[
      {
         "ts":1629700292000,
         "values":{
            "level":94,
            "battery":97
         }
      }
   ]
}

{
  "UGS 000001": [
    {
      "ts": 1626166875000,
      "values": {
        "level": 600,
        "battery": 98
      }
    },
    {
      "ts": 1626166880000,
      "values": {
        "level": 598,
        "battery": 97
      }
    }
  ],
  "UGS 000002": [
    {
      "ts": 1626166875000,
      "values": {
        "level": 588,
        "battery": 96
      }
    }
  ]
}

{ 
  "00:02:04:6d:b3:41": [
    { 
        "level": 672,
        "battery": 98
    }
  ],
  "00:02:04:6d:b3:42": [
    { 
        "level": 668,
        "battery": 97
    }
  ]
}

{ "00:02:04:6d:b3:41": [ { "level": 680, "battery": 99 } ], "00:02:04:6d:b3:42": [ { "level": 680, "battery": 99 } ] }

{
  "UGS 000001": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 80
      }
    }
  ],
  "UGS 000002": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 88,
        "level": 90
      }
    }
  ],
  "UGS 000003": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 88,
        "level": 60
      }
    }
  ],
  "UGS 000004": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 90,
        "level": 86
      }
    }
  ],
  "UGS 000005": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 80
      }
    }
  ],
  "UGS 000006": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 82
      }
    }
  ],
  "UGS 000007": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 92,
        "level": 80
      }
    }
  ],
  "UGS 000008": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 90
      }
    }
  ],
  "UGS 000009": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 88
      }
    }
  ],
  "UGS 0000010": [
    {
      "ts": 1627339246000,
      "values": {
        "battery": 99,
        "level": 92
      }
    }
  ]
}

### Attribute Upload Example
* Attributes API
* Upload client-side device attributes to the server
* v1/gateway/**attributes**
* Request client-side and shared device attributes from the server
* server to client (topic to publish): v1/gateway/**attributes/request**
* client (topic to subscribe): v1/gateway/**attributes/response**
* client to server (topic to publish): v1/gateway/**attributes**
* Subscribe to shared device attributes from the server
* client (topic to subscribe): v1/gateway/attributes

{"UGS 000001":{"fw-ver":"v0.0.1"}}

{
   "UGS 000001":{
      "latitude":24.83561582598249,
      "longitude":121.05507009746219
   }
}


{"id": 1, "device": "UGS 000001", "client": true, "key": "fw-ver"}

## MQTT Device APIs

### Telemetry Upload API

#### Attributes API

#### Request attribute values from the server

#### Publish attribute update to the server

#### Subscribe to attribute updates from the server

## RPC APIs

### Server-side RPC

### Client-side RPC

## MQTT Client (e.g. MQTTBox)

APIs
---
* Device Connect API
* Topic to publish: v1/gateway/**connect**
* Payload type: Strings/JSON/XML/Characters
* Payload

{"device":"Device A"}


* Device Disconnect API
* Topic to publish: v1/gateway/**disconnect**
* Payload type: Strings/JSON/XML/Characters
* Payload

{"device":"Device A"}

Resource(s)
---
* [Facebook ThingsBoard Taiwan Group](https://facebook.com/groups/thingsboard)
* https://avantec-thingsboard.readthedocs.io/en/latest/protocol/thingsboard-mqtt-api.html
* https://thingsboard.io/docs/reference/gateway-mqtt-api/
* https://thingsboard.io/docs/reference/mqtt-api/