|
| 1 | +# 🌐 Hướng Dẫn Tích Hợp Gateway (ThingsBoard Chuẩn) |
| 2 | + |
| 3 | +Tài liệu này hướng dẫn chi tiết từng bước cách lập trình và kết nối một thiết bị Gateway (ví dụ Raspberry Pi, ESP32) vào hệ thống VTA Pro IoT. |
| 4 | + |
| 5 | +Gateway đóng vai trò là cầu nối (bridge) giữa các thiết bị con (như cảm biến Bluetooth, Zigbee, RS485/Modbus) và Server (Đám mây). Gateway sẽ đại diện cho các thiết bị con giao tiếp với Server qua giao thức MQTT. |
| 6 | + |
| 7 | +## 1. Thông Tin Kết Nối Cơ Bản |
| 8 | + |
| 9 | +Để Gateway kết nối được với Server, bạn cần các thông tin sau: |
| 10 | +- **Giao thức**: MQTT (hoặc MQTT qua WebSockets) |
| 11 | +- **Host (Máy chủ)**: `mqtt.greeniq.vn` (hoặc `localhost` nếu chạy ở môi trường dev) |
| 12 | +- **Port**: `1883` (MQTT TCP) hoặc `8083` (MQTT WebSockets) |
| 13 | +- **Client ID**: Bất kỳ chuỗi ngẫu nhiên nào (mỗi Gateway phải có 1 Client ID duy nhất) |
| 14 | +- **Username**: MÃ BẢO MẬT (Device Credential) của Gateway |
| 15 | +- **Password**: `super_secret_backend` (Hoặc tuỳ cấu hình của bạn, đối chiếu trong mục Thiết bị) |
| 16 | + |
| 17 | +> **Lưu ý Quan Trọng**: Trên giao diện Web, khi tạo Gateway, bạn bắt buộc phải bật tuỳ chọn **"Là Gateway"**. Nếu không, Server sẽ chặn mọi bản tin thuộc namespace `v1/gateway/*`. |
| 18 | +
|
| 19 | +--- |
| 20 | + |
| 21 | +## 2. Các Topic MQTT Hỗ Trợ Cho Gateway |
| 22 | + |
| 23 | +Hệ thống tuân thủ 100% chuẩn MQTT Gateway API của ThingsBoard PE/CE. Gateway của bạn cần Gửi (Publish) và Lắng nghe (Subscribe) các Topic sau: |
| 24 | + |
| 25 | +### 2.1. Đăng ký (Kết nối) thiết bị con |
| 26 | +Khi một thiết bị con (ví dụ: `Cam_Bien_Zigbee_1`) kết nối vào mạng cục bộ của Gateway, Gateway cần báo cho Server biết. |
| 27 | + |
| 28 | +- **Topic (Gửi đi)**: `v1/gateway/connect` |
| 29 | +- **Payload**: |
| 30 | + ```json |
| 31 | + { |
| 32 | + "device": "Cam_Bien_Zigbee_1", |
| 33 | + "type": "sensor" |
| 34 | + } |
| 35 | + ``` |
| 36 | +*Server sẽ tự động tạo một thiết bị mới tên là `Cam_Bien_Zigbee_1` (nếu chưa có) và gán nó làm thiết bị con của Gateway.* |
| 37 | + |
| 38 | +### 2.2. Ngắt kết nối thiết bị con |
| 39 | +Khi thiết bị con mất kết nối khỏi mạng cục bộ, Gateway cần báo lại cho Server. |
| 40 | + |
| 41 | +- **Topic (Gửi đi)**: `v1/gateway/disconnect` |
| 42 | +- **Payload**: |
| 43 | + ```json |
| 44 | + { |
| 45 | + "device": "Cam_Bien_Zigbee_1" |
| 46 | + } |
| 47 | + ``` |
| 48 | + |
| 49 | +### 2.3. Gửi Dữ liệu Đo đạc (Telemetry) |
| 50 | +Đây là luồng dữ liệu quan trọng nhất. Gateway có thể gửi dữ liệu của một hoặc nhiều thiết bị con cùng một lúc (Batching). |
| 51 | + |
| 52 | +- **Topic (Gửi đi)**: `v1/gateway/telemetry` |
| 53 | +- **Payload**: |
| 54 | + ```json |
| 55 | + { |
| 56 | + "Cam_Bien_Zigbee_1": [ |
| 57 | + { |
| 58 | + "ts": 1700000000000, |
| 59 | + "values": { |
| 60 | + "temperature": 29.5, |
| 61 | + "humidity": 60 |
| 62 | + } |
| 63 | + } |
| 64 | + ], |
| 65 | + "May_Bom_1": [ |
| 66 | + { |
| 67 | + "values": { |
| 68 | + "flow_rate": 15.2, |
| 69 | + "status": 1 |
| 70 | + } |
| 71 | + } |
| 72 | + ] |
| 73 | + } |
| 74 | + ``` |
| 75 | +*(Ghi chú: Trường `ts` là thời gian Timestamp tính bằng mili giây. Nếu bỏ trống, Server sẽ tự động lấy thời gian hiện tại).* |
| 76 | + |
| 77 | +### 2.4. Gửi Thuộc tính Thiết bị (Client Attributes) |
| 78 | +Thuộc tính là các thông số ít biến động (như phiên bản Firmware, mức Pin, địa chỉ IP). |
| 79 | + |
| 80 | +- **Topic (Gửi đi)**: `v1/gateway/attributes` |
| 81 | +- **Payload**: |
| 82 | + ```json |
| 83 | + { |
| 84 | + "Cam_Bien_Zigbee_1": { |
| 85 | + "firmware": "v2.0.1", |
| 86 | + "battery": 85, |
| 87 | + "ip_address": "192.168.1.101" |
| 88 | + } |
| 89 | + } |
| 90 | + ``` |
| 91 | + |
| 92 | +### 2.5. Lắng nghe Lệnh điều khiển (RPC) từ Server |
| 93 | +Để Gateway có thể nhận lệnh điều khiển từ người dùng trên Web (Ví dụ: bấm nút Bật Máy Bơm), Gateway phải **đăng ký theo dõi (Subscribe)** topic này. |
| 94 | + |
| 95 | +- **Topic (Subscribe)**: `v1/gateway/rpc` |
| 96 | +- **Payload Server gửi xuống**: |
| 97 | + ```json |
| 98 | + { |
| 99 | + "device": "May_Bom_1", |
| 100 | + "data": { |
| 101 | + "id": 892312, |
| 102 | + "method": "setRelay", |
| 103 | + "params": { |
| 104 | + "pin": 1, |
| 105 | + "state": true |
| 106 | + } |
| 107 | + } |
| 108 | + } |
| 109 | + ``` |
| 110 | + |
| 111 | +### 2.6. Phản hồi Lệnh điều khiển (RPC Response) |
| 112 | +Sau khi thực thi lệnh (Ví dụ: bật rơ le thành công), Gateway phải báo cáo kết quả về cho Server. |
| 113 | + |
| 114 | +- **Topic (Gửi đi)**: `v1/gateway/rpc/response` |
| 115 | +- **Payload**: |
| 116 | + ```json |
| 117 | + { |
| 118 | + "device": "May_Bom_1", |
| 119 | + "id": 892312, |
| 120 | + "data": { |
| 121 | + "success": true, |
| 122 | + "message": "Relay turned on successfully" |
| 123 | + } |
| 124 | + } |
| 125 | + ``` |
| 126 | +*(Bắt buộc: `id` trong gói phản hồi phải khớp với `id` mà Server đã gửi xuống trong lệnh RPC).* |
| 127 | + |
| 128 | +### 2.7. Yêu cầu Cấu hình (Attributes Request) |
| 129 | +Khi một thiết bị con vừa khởi động, nó có thể cần lấy các cấu hình từ Server (Shared Attributes) do người dùng thiết lập trên Web (Ví dụ: Ngưỡng nhiệt độ cảnh báo). |
| 130 | + |
| 131 | +- **Topic (Gửi đi)**: `v1/gateway/attributes/request` |
| 132 | +- **Payload**: |
| 133 | + ```json |
| 134 | + { |
| 135 | + "id": 1, |
| 136 | + "device": "Cam_Bien_Zigbee_1", |
| 137 | + "clientKeys": "firmware,battery", |
| 138 | + "sharedKeys": "targetTemperature,alarmThreshold" |
| 139 | + } |
| 140 | + ``` |
| 141 | + |
| 142 | +- **Topic nhận kết quả (Subscribe)**: `v1/gateway/attributes/response` |
| 143 | +- **Payload Server trả về**: |
| 144 | + ```json |
| 145 | + { |
| 146 | + "id": 1, |
| 147 | + "device": "Cam_Bien_Zigbee_1", |
| 148 | + "value": { |
| 149 | + "targetTemperature": 25.0, |
| 150 | + "alarmThreshold": 80.0 |
| 151 | + } |
| 152 | + } |
| 153 | + ``` |
| 154 | + |
| 155 | +--- |
| 156 | + |
| 157 | +## 3. Quy Trình Khởi Động Chuẩn (Dành cho Lập trình viên Firmware) |
| 158 | + |
| 159 | +Khi viết code cho Gateway (ví dụ dùng Python paho-mqtt hoặc C++ PubSubClient), hãy tuân theo quy trình sau để đảm bảo hoạt động ổn định: |
| 160 | + |
| 161 | +1. **Khởi tạo kết nối MQTT**: Kết nối tới Broker bằng Credential của Gateway. Bật cờ `clean_session=True` hoặc `False` tuỳ nhu cầu (Khuyên dùng `False` để không lỡ mất tin nhắn RPC khi mạng chập chờn). |
| 162 | +2. **Subscribe các Topic nhận lệnh**: |
| 163 | + - Subscribe `v1/gateway/rpc` (QoS 1) |
| 164 | + - Subscribe `v1/gateway/attributes/response` (QoS 1) |
| 165 | +3. **Đồng bộ danh sách thiết bị**: Khi Gateway khởi động, duyệt qua danh sách các thiết bị con đang kết nối thực tế. Gửi lệnh `v1/gateway/connect` cho từng thiết bị. |
| 166 | +4. **Vòng lặp chính**: |
| 167 | + - Lấy dữ liệu từ cổng Serial/Modbus/Zigbee... |
| 168 | + - Đóng gói thành mảng JSON. |
| 169 | + - Publish lên `v1/gateway/telemetry`. |
| 170 | +5. **Xử lý ngắt kết nối MQTT**: Thiết lập LWT (Last Will and Testament) hoặc tự động kết nối lại khi mất mạng. |
0 commit comments