# MQTT Gateway API Reference
### Introduction
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
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
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
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
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
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
#### Server-side RPC
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
MQTT transport can be fully customized for specific use-case by changing the corresponding module.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://astian.gitbook.io/jiot/api/mqtt-gateway-api-reference.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.