MQTT Gateway API

Gateway API cho phép một thiết bị gateway đại diện cho nhiều thiết bị backend. Gateway duy trì một kết nối MQTT duy nhất tới VieLang IoT và proxy dữ liệu cho hàng trăm thiết bị bên dưới.

Kết nối

Gateway kết nối như một thiết bị bình thường, dùng Access Token của gateway:

Host: vielang.io
Port: 1883
Username: {gateway-access-token}

Đăng ký thiết bị

Khi thiết bị backend kết nối qua gateway, gateway báo cho server:

Topic:   v1/gateway/connect
Payload: { "device": "Device-A" }

Thiết bị sẽ được tự động tạo trên server nếu chưa tồn tại.

Ngắt kết nối:

Topic:   v1/gateway/disconnect
Payload: { "device": "Device-A" }

Gửi Telemetry

Gateway gửi telemetry cho nhiều thiết bị trong một message:

Topic: v1/gateway/telemetry

{
  "Device-A": [
    {
      "ts": 1609459200000,
      "values": { "temperature": 25.5, "humidity": 60 }
    }
  ],
  "Device-B": [
    {
      "ts": 1609459201000,
      "values": { "status": "active", "signal": -75 }
    }
  ],
  "Device-C": [
    { "ts": 1609459200000, "values": { "energy": 1250.5 } },
    { "ts": 1609459260000, "values": { "energy": 1251.2 } }
  ]
}

Mỗi thiết bị có thể có nhiều timestamp trong cùng một message.

Gửi Attributes

Topic: v1/gateway/attributes

{
  "Device-A": {
    "model": "DHT22",
    "firmware": "v1.0.0",
    "location": "Room-101"
  },
  "Device-B": {
    "model": "ESP32",
    "firmware": "v2.1.0"
  }
}

Đọc Attributes từ Server

Request:

Topic:   v1/gateway/attributes/request
Payload: {
  "id": 1,
  "device": "Device-A",
  "client": true,
  "sharedKeys": "config,threshold"
}

Response (subscribe topic):

Topic:   v1/gateway/attributes/response
Payload: {
  "id": 1,
  "device": "Device-A",
  "value": {
    "shared": {
      "config": "active",
      "threshold": 30
    }
  }
}

Nhận Attribute Updates từ Server

Subscribe để nhận thay đổi shared attributes:

Topic:   v1/gateway/attributes
Payload: {
  "device": "Device-A",
  "data": { "threshold": 35, "config": "updated" }
}

RPC — Nhận lệnh từ Server

Subscribe: v1/gateway/rpc

Server gửi lệnh RPC:

{
  "device": "Device-A",
  "data": {
    "id": 1,
    "method": "reboot",
    "params": { "timeout": 60 }
  }
}

Gateway chuyển đến thiết bị, sau đó gửi response:

Topic:   v1/gateway/rpc
Payload: {
  "device": "Device-A",
  "id": 1,
  "data": { "result": "rebooting" }
}

Claiming Device

Topic:   v1/gateway/claim
Payload: {
  "Device-A": {
    "secretKey": "my-secret",
    "durationMs": 3600000
  }
}

Ví dụ Python Gateway

import paho.mqtt.client as mqtt
import json
import time

GATEWAY_TOKEN = "your-gateway-token"
BROKER = "vielang.io"

client = mqtt.Client()
client.username_pw_set(GATEWAY_TOKEN)
client.connect(BROKER, 1883)
client.loop_start()

# Đăng ký thiết bị
def connect_device(device_name):
    client.publish(
        "v1/gateway/connect",
        json.dumps({"device": device_name})
    )

# Gửi telemetry cho nhiều thiết bị
def send_telemetry(data: dict):
    """
    data = {
        "Sensor-01": [{"ts": 1609459200000, "values": {"temp": 25}}],
        "Sensor-02": [{"ts": 1609459200000, "values": {"temp": 27}}],
    }
    """
    client.publish("v1/gateway/telemetry", json.dumps(data))

# Polling loop
devices = ["Sensor-01", "Sensor-02", "Sensor-03"]
for d in devices:
    connect_device(d)

while True:
    telemetry = {}
    for device in devices:
        telemetry[device] = [{
            "ts": int(time.time() * 1000),
            "values": {
                "temperature": read_temperature(device),
                "humidity": read_humidity(device)
            }
        }]
    send_telemetry(telemetry)
    time.sleep(30)

Lợi ích của Gateway Pattern

Kết nối trực tiếp	Qua Gateway
N thiết bị = N kết nối MQTT	N thiết bị = 1 kết nối MQTT
Mỗi thiết bị cần credentials	Chỉ gateway cần credentials
Thiết bị cần IP trực tiếp	Thiết bị kết nối nội bộ (RS485, BLE, ZigBee...)
Khó scale	Scale đến hàng nghìn thiết bị

Protocol Bridge với IoT Gateway

VieLang IoT cung cấp sẵn IoT Gateway application hỗ trợ bridge các giao thức:

Modbus RTU/TCP
BACnet
OPC-UA
BLE
ZigBee
CAN Bus

Xem tài liệu IoT Gateway riêng để cấu hình connector.