Điều khiển thiết bị (RPC)

RPC (Remote Procedure Call) cho phép giao tiếp hai chiều giữa server và thiết bị: server gửi lệnh xuống thiết bị, thiết bị phản hồi kết quả.

Hai loại RPC

Server-side RPC — Server gọi thiết bị

Server gửi lệnh đến thiết bị. Dùng để:

Bật/tắt relay, đèn, motor
Cấu hình lại thiết bị
Yêu cầu thiết bị reboot
Đọc trạng thái hiện tại

Client-side RPC — Thiết bị gọi server

Thiết bị gửi yêu cầu đến server, server trả lời. Dùng để:

Thiết bị hỏi server thời gian hiện tại
Thiết bị yêu cầu quyền truy cập
Thiết bị lấy cấu hình từ hệ thống khác

Server-side RPC

Lightweight RPC (ngắn hạn)

Phù hợp khi thiết bị đang online. Timeout mặc định 10 giây.

One-way (không cần phản hồi):

POST /api/plugins/rpc/oneway/{deviceId}
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "method": "setGpio",
  "params": { "pin": 4, "value": 1 }
}

Two-way (cần phản hồi từ thiết bị):

POST /api/plugins/rpc/twoway/{deviceId}
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "method": "getTemperature",
  "params": {},
  "timeout": 5000
}

# Response khi thiết bị trả lời:
{ "temperature": 25.5 }

Persistent RPC (lâu dài)

Phù hợp khi thiết bị có thể offline. Lệnh được lưu DB, gửi lại khi thiết bị online.

POST /api/plugins/rpc/twoway/{deviceId}
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "method": "updateConfig",
  "params": { "interval": 60, "mode": "eco" },
  "persistent": true,
  "timeout": 86400000,
  "retries": 3
}

Cấu trúc RPC request:

Field	Bắt buộc	Mặc định	Mô tả
`method`	✓	—	Tên phương thức
`params`	✓	—	Tham số (JSON)
`timeout`	✗	10000ms	Timeout chờ phản hồi
`persistent`	✗	false	Lưu DB khi thiết bị offline
`retries`	✗	0	Số lần gửi lại
`expirationTime`	✗	—	Thời điểm hết hạn (ms)

Thiết bị nhận lệnh qua MQTT

# Subscribe topic nhận lệnh
mosquitto_sub \
  -h localhost -p 1883 \
  -u "ACCESS_TOKEN" \
  -t "v1/devices/me/rpc/request/+"

# Khi nhận lệnh:
# Topic: v1/devices/me/rpc/request/1
# Payload: {"method": "setGpio", "params": {"pin": 4, "value": 1}}

# Thiết bị gửi phản hồi:
mosquitto_pub \
  -h localhost -p 1883 \
  -u "ACCESS_TOKEN" \
  -t "v1/devices/me/rpc/response/1" \
  -m '{"result": "ok"}'

Thiết bị nhận lệnh qua HTTP (long polling)

# Thiết bị poll chờ lệnh (timeout 30s)
GET http://localhost:8080/api/v1/ACCESS_TOKEN/rpc
# Response khi có lệnh:
{"id": 1, "method": "setGpio", "params": {"pin": 4, "value": 1}}

# Gửi phản hồi
POST http://localhost:8080/api/v1/ACCESS_TOKEN/rpc/1
Content-Type: application/json
{"result": "ok"}

Client-side RPC

Thiết bị chủ động gửi yêu cầu đến server.

Qua MQTT

# Thiết bị gửi yêu cầu
mosquitto_pub \
  -h localhost -p 1883 \
  -u "ACCESS_TOKEN" \
  -t "v1/devices/me/rpc/request/1" \
  -m '{"method": "getCurrentTime", "params": {}}'

# Subscribe nhận phản hồi
mosquitto_sub \
  -h localhost -p 1883 \
  -u "ACCESS_TOKEN" \
  -t "v1/devices/me/rpc/response/1"

# Server trả lời:
{"currentTime": 1735000000000}

Xử lý trong Rule Engine

Client-side RPC tạo message type TO_SERVER_RPC_REQUEST. Rule chain xử lý và trả lời qua node RPC Call Reply:

[Message Type Filter]  type == TO_SERVER_RPC_REQUEST
         ↓ True
[Script Node]  transform request → response
         ↓ Success
[RPC Call Reply]  gửi phản hồi về thiết bị

Xem trạng thái RPC

# Lấy danh sách RPC đang chờ
GET /api/device/{deviceId}/rpc
  ?pageSize=10&page=0
Authorization: Bearer {JWT}

# Lấy chi tiết một RPC
GET /api/rpc/persistent/{rpcId}
Authorization: Bearer {JWT}