> For the complete documentation index, see [llms.txt](https://astian.gitbook.io/jiot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://astian.gitbook.io/jiot/api/mqtt-gateway-api-reference.md).

# MQTT Gateway API Reference

### Introduction <a href="#introduction" id="introduction"></a>

The Gateway is a special type of device in JIoT that is able to act as a bridge between external devices connected to different systems and JIoT. Gateway API provides the ability to exchange data between **multiple devices** and the platform using **single MQTT connection**. The Gateway also acts as a JIoT device and can leverage existing [MQTT Device API](/jiot/api/mqtt-device-api-reference.md) to report stats, receive configuration updates and much more.

The API listed below is used by **JIoT open-source IoT Gateway**.

### Basic MQTT API <a href="#basic-mqtt-api" id="basic-mqtt-api"></a>

Please refer to generic [MQTT Device API](/jiot/api/mqtt-device-api-reference.md) to get information about data format, authentication options, etc.

### Device Connect API <a href="#device-connect-api" id="device-connect-api"></a>

In order to inform JIoT that device is connected to the Gateway, one needs to publish following message:

```
Topic: v1/gateway/connect
Message: {"device":"Device A"}
```

where **Device A** is your device name.

Once received, JIoT will lookup or create a device with the name specified. Also, JIoT will publish messages about new attribute updates and RPC commands for a particular device to this Gateway.

### Device Disconnect API <a href="#device-disconnect-api" id="device-disconnect-api"></a>

In order to inform JIoT that device is disconnected from the Gateway, one needs to publish following message:

```
Topic: v1/gateway/disconnect
Message: {"device":"Device A"}
```

where **Device A** is your device name.

Once received, JIoT will no longer publish updates for this particular device to this Gateway.

### Attributes API <a href="#attributes-api" id="attributes-api"></a>

JIoT attributes API allows devices to

* Upload client-side device attributes to the server.
* Request client-side and shared device attributes from the server.
* Subscribe to shared device attributes from the server.

**Publish attribute update to the server**

In order to publish client-side device attributes to JIoT server node, send PUBLISH message to the following topic:

```
Topic: v1/gateway/attributes
Message: {"Device A":{"attribute1":"value1", "attribute2": 42}, "Device B":{"attribute1":"value1", "attribute2": 42}}
```

where **Device A** and **Device B** are your device names, **attribute1** and **attribute2** are attribute keys.

**Request attribute values from the server**

In order to request client-side or shared device attributes to JIoT server node, send PUBLISH message to the following topic:

```
Topic: v1/gateway/attributes/request
Message: {"id": $request_id, "device": "Device A", "client": true, "key": "attribute1"}
```

where **$request\_id** is your integer request identifier, **Device A** is your device name, **client** identifies a client or shared attribute scope and **key** is the attribute key.

Before sending PUBLISH message with the request, client need to subscribe to

```
Topic: v1/gateway/attributes/response
```

and expect messages with result in the following format:

```
Message: {"id": $request_id, "device": "Device A", "value": "value1"}
```

**Subscribe to attribute updates from the server**

In order to subscribe to shared device attribute changes, send SUBSCRIBE message to the following topic:

```
v1/gateway/attributes
```

and expect messages with result in the following format:

```
Message: {"device": "Device A", "data": {"attribute1": "value1", "attribute2": 42}}
```

### Telemetry upload API <a href="#telemetry-upload-api" id="telemetry-upload-api"></a>

In order to publish device telemetry to JIoT server node, send PUBLISH message to the following topic:

```
Topic: v1/gateway/telemetry
```

Message:

```
{
  "Device A": [
    {
      "ts": 1483228800000,
      "values": {
        "temperature": 42,
        "humidity": 80
      }
    },
    {
      "ts": 1483228801000,
      "values": {
        "temperature": 43,
        "humidity": 82
      }
    }
  ],
  "Device B": [
    {
      "ts": 1483228800000,
      "values": {
        "temperature": 42,
        "humidity": 80
      }
    }
  ]
}
```

where **Device A** and **Device B** are your device names, **temperature** and **humidity** are telemetry keys and **ts** is unix timestamp in milliseconds.

### RPC API <a href="#rpc-api" id="rpc-api"></a>

#### Server-side RPC <a href="#server-side-rpc" id="server-side-rpc"></a>

In order to subscribe to RPC commands from the server, send SUBSCRIBE message to the following topic:

```
v1/gateway/rpc
```

and expect messages with individual commands in the following format:

```
{"device": "Device A", "data": {"id": $request_id, "method": "toggle_gpio", "params": {"pin":1}}}
```

Once command is processed by device, gateway can send commands back using following format:

```
{"device": "Device A", "id": $request_id, "data": {"success": true}}
```

where **$request\_id** is your integer request identifier, **Device A** is your device name and **method** is your RPC method name.

### Protocol customization <a href="#protocol-customization" id="protocol-customization"></a>

MQTT transport can be fully customized for specific use-case by changing the corresponding module.