Kết nối MQTT

FastBee bản mã nguồn mở tích hợp sẵn MQTT Broker phát triển dựa trên Netty, không cần triển khai thêm EMQX. Bài viết này giới thiệu cách thiết bị kết nối nền tảng qua giao thức MQTT.

Quy trình kết nối

Tạo và phát hành sản phẩm MQTT trong quản lý sản phẩm, xác nhận Product ID, mã thiết bị, tài khoản MQTT và mật khẩu
Thiết bị hoặc MQTTX dùng clientId, userName, password theo quy ước để kết nối dịch vụ MQTT
Sau khi kết nối thành công, publish /info/post trước, rồi publish /property/post hoặc /event/post
Phía nền tảng xác nhận đường truyền khép kín qua trạng thái chạy, nhật ký sự kiện và nhật ký lệnh trong chi tiết thiết bị

Thông tin kết nối

Tham số	Kết nối TCP	Kết nối WebSocket
Địa chỉ	IP máy chủ	`ws://ip-may-chu:8083/mqtt`
Cổng	1883	8083
Giao thức	MQTT 3.1.1	MQTT over WebSocket

Xác thực thiết bị

提示

Kiểu xác thực: S = xác thực đơn giản, E = xác thực mã hóa
Sau khi sản phẩm bật mã ủy quyền thiết bị, mã ủy quyền không được để trống
User ID là ID của người dùng đăng nhập, dùng User ID khác nhau thì thiết bị thuộc về người dùng khác nhau
Mã thiết bị có thể là mã do nền tảng tạo, cũng có thể là mã duy nhất như MAC/IMEI của thiết bị (nền tảng sẽ tự động đăng ký thiết bị)

Xác thực đơn giản (khuyến nghị dùng khi kiểm thử)

clientId = S&mã thiết bị&Product ID&User ID
userName = tài khoản MQTT
password = mật khẩu MQTT
password = mật khẩu MQTT&mã ủy quyền thiết bị (khi sản phẩm bật ủy quyền thiết bị)

Ví dụ:

clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"

Xác thực mã hóa (khuyến nghị dùng cho môi trường sản xuất)

clientId = E&mã thiết bị&Product ID&User ID
userName = tài khoản MQTT
password = mã hóa AES(mật khẩu MQTT&timestamp hết hạn&mã ủy quyền(tùy chọn))

Mật khẩu dùng khóa sản phẩm mã hóa AES-CBC (offset wumei-smart-open, đầu ra Base64)
Timestamp hết hạn chính xác đến mili giây, khuyến nghị trong vòng 24 giờ

Ví dụ:

clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"

Giải thích mã hóa AES

Áp dụng chế độ mã hóa AES-CBC, khi kiểm thử có thể dùng công cụ mã hóa/giải mã trực tuyến:

Tham số	Giá trị
Chế độ mã hóa	CBC
Padding	pkcs5padding
Khối dữ liệu	128 bit
Offset	`wumei-smart-open`
Đầu ra	Base64
Mật khẩu	Khóa sản phẩm
Nội dung mã hóa	`mật khẩu MQTT&expireTime&mã ủy quyền(tùy chọn)`

Topic	Mô tả
`/{productId}/{deviceNum}/function/get`	Subscribe lệnh nền tảng (đặt thuộc tính, gọi chức năng)
`/{productId}/{deviceNum}/info/get`	Subscribe yêu cầu thông tin thiết bị (sau khi nhận thì publish thông tin thiết bị)
`/{productId}/{deviceNum}/monitor/get`	Subscribe yêu cầu giám sát thời gian thực (trả về số lần và khoảng cách)
`/{productId}/{deviceNum}/ntp/get`	Subscribe đồng bộ đồng hồ (tùy chọn)
`/{deviceNum}/http/upgrade/set`	Subscribe nâng cấp OTA theo cách HTTPS
`/{deviceNum}/fetch/upgrade/set`	Subscribe nâng cấp OTA theo cách gói nhị phân

Topic publish (thiết bị → nền tảng)

Topic	Mô tả
`/{productId}/{deviceNum}/property/post`	Publish dữ liệu thuộc tính/chức năng (hiển thị thời gian thực và lưu trữ)
`/{productId}/{deviceNum}/event/post`	Publish sự kiện
`/{productId}/{deviceNum}/info/post`	Publish thông tin thiết bị
`/{productId}/{deviceNum}/monitor/post`	Publish dữ liệu giám sát thời gian thực (chỉ biểu đồ thời gian thực, không lưu trữ)
`/{productId}/{deviceNum}/ntp/post`	Publish đồng bộ đồng hồ (tùy chọn)
`/{deviceNum}/http/upgrade/reply`	Phản hồi nâng cấp OTA theo cách HTTPS
`/{deviceNum}/fetch/upgrade/reply`	Phản hồi nâng cấp OTA theo cách gói nhị phân

提示

{productId} là Product ID (không phải mã sản phẩm), lấy trong chi tiết sản phẩm trên nền tảng
{deviceNum} là mã thiết bị, hoàn toàn khớp với thiết bị trên nền tảng

Định dạng dữ liệu

Thiết bị và nền tảng tương tác bằng định dạng JSON.

Publish thuộc tính/chức năng/sự kiện — `/property/post`, `/event/post`

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "nhiệt độ bình thường"
}, {
    "id": "switch",
    "value": "1",
    "remark": "công tắc đã bật"
}]

id: định danh Thing Model, xem trong chi tiết sản phẩm, duy nhất trong một sản phẩm
value: giá trị truyền dạng chuỗi; kiểu boolean dùng "0"/"1"; kiểu enum tương ứng giá trị khóa enum; kiểu mảng phân tách bằng dấu phẩy
remark: thông tin ghi chú, có thể xem trong nhật ký thiết bị

Subscribe lệnh nền tảng — `/function/get`

json

[{
    "id": "gear",
    "value": "1",
    "remark": "Scene Linkage kích hoạt"
}, {
    "id": "switch",
    "value": "0",
    "remark": "tắt theo hẹn giờ"
}]

Publish thông tin thiết bị — `/info/post`

json

{
    "rssi": -43,
    "firmwareVersion": 1.2,
    "status": 3,
    "userId": 1,
    "longitude": 0,
    "latitude": 0,
    "summary": {
        "name": "FastBee",
        "chip": "ESP32"
    }
}

Trường	Mô tả
rssi	Cường độ tín hiệu (rất tốt [-55~0], tốt [-70~-55], trung bình [-85~-70], kém [-100~-85])
firmwareVersion	Số phiên bản firmware
status	Trạng thái thiết bị, cố định là 3 (online)
userId	User ID
longitude/latitude	Tùy chọn, định vị thiết bị
summary	Tùy chọn, thông tin tóm tắt thiết bị

Giám sát thời gian thực — `/monitor/get`, `/monitor/post`

Nền tảng gửi yêu cầu giám sát xuống:

json

{
    "count": 60,
    "interval": 1000
}

Thiết bị báo dữ liệu theo số lần và khoảng cách chỉ định:

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": ""
}]

Đồng bộ đồng hồ — `/ntp/post`, `/ntp/get`

Thiết bị publish:

json

{
    "deviceSendTime": "1592361428000"
}

Nền tảng phản hồi:

json

{
    "deviceSendTime": "1592361428000",
    "serverRecvTime": "1592366463548",
    "serverSendTime": "1592366463548"
}

Thời gian hiện tại của thiết bị = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

Quy tắc định danh Thing Model

Tất cả định danh duy nhất trong một sản phẩm, chủ yếu dùng chữ cái và số, tránh ký tự đặc biệt
Định dạng ID mô hình con của kiểu đối tượng: parentId_childId
Định danh kiểu mảng bắt đầu bằng array_chỉ số (chỉ số là hai chữ số, ví dụ array_00_power_switch), độ dài mảng không quá 100

Cấu hình mạng AP cho thiết bị (tùy chọn, chỉ thiết bị WiFi)

Thiết bị bật hotspot (địa chỉ 192.168.4.1), đầu di động truyền thông tin cấu hình qua dịch vụ Web của thiết bị.

Phát hiện thiết bị

GET http://192.168.4.1/api/wifi/status

HTTP 200 nghĩa là phát hiện được thiết bị, response bao gồm thông tin thiết bị và trạng thái mạng hiện tại.

API cấu hình

POST http://192.168.4.1/api/wifi/config?SSID=tên WiFi&password=mật khẩu WiFi&userId=User ID

Tham số	Mô tả
SSID	Tên WiFi (bắt buộc, tương thích ssid viết thường)
password	Mật khẩu WiFi (bắt buộc, tương thích bí danh pwd)
userId	User ID (bắt buộc)
deviceNum	Mã thiết bị (tùy chọn)
extra	Mã sản phẩm (tùy chọn)

HTTP 200 nghĩa là cấu hình mạng thành công (sau đó thiết bị tự chuyển sang chế độ STA), 400 nghĩa là thiếu tham số bắt buộc, 500 nghĩa là lưu thất bại. Giải thích chi tiết API xem tại «Cấu hình mạng · API cấu hình mạng AP cho điện thoại/đầu di động».

Dùng MQTTX kiểm thử

Tải client MQTTX
Tạo kết nối mới:
- Host: mqtt://ip-may-chu, Port: 1883
- Client ID: S&mã thiết bị&Product ID&1
- Username: tài khoản MQTT
- Password: mật khẩu MQTT
Subscribe /{productId}/{deviceNum}/function/get
Publish thông tin thiết bị tới /{productId}/{deviceNum}/info/post
Publish dữ liệu thuộc tính tới /{productId}/{deviceNum}/property/post
Quan sát trạng thái online và dữ liệu chạy của thiết bị trên bảng điều khiển nền tảng

Checklist nghiệm thu liên hợp

Bước	Nội dung nghiệm thu	Biểu hiện thành công
1	Sản phẩm đã phát hành	Trạng thái sản phẩm là đã phát hành
2	MQTTX kết nối	Chi tiết thiết bị hiển thị online
3	`/info/post`	Các trường thông tin thiết bị, tín hiệu, phiên bản được cập nhật
4	`/property/post`	Trạng thái chạy hiển thị giá trị thuộc tính Thing Model
5	`/event/post`	Nhật ký sự kiện xuất hiện sự kiện báo lên
6	`/function/get`	Thiết bị nhận được lệnh sau khi nền tảng gửi xuống
7	Trả kết quả về	Thiết bị trả về theo kết quả gửi xuống, trạng thái nền tảng được làm mới
8	Quy tắc/kịch bản	Các quy tắc, kịch bản, cảnh báo liên quan có thể được kích hoạt

Lỗi thường gặp

Kết nối bị từ chối

Cổng 1883 của máy chủ đã mở chưa
MQTT Broker tích hợp sẵn đã khởi động chưa
Định dạng clientId có đúng không (S&mã thiết bị&Product ID&User ID)
Sản phẩm có bật mã ủy quyền thiết bị không
Thiết bị có bị vô hiệu hóa không

Thiết bị online nhưng thuộc tính không làm mới

Topic publish có phải /{productId}/{deviceNum}/property/post không
productId có dùng Product ID (không phải mã sản phẩm) không
deviceNum có hoàn toàn khớp với mã thiết bị không
Message body có phải định dạng mảng JSON không
id có hoàn toàn khớp với định danh Thing Model không
value có phù hợp kiểu dữ liệu không

Nền tảng gửi xuống nhưng thiết bị không nhận được

Thiết bị đã subscribe /{productId}/{deviceNum}/function/get chưa
Thiết bị còn online không
Thing Model có phải chức năng ghi được hoặc thuộc tính gửi xuống được không
Người dùng có quyền xem chi tiết thiết bị và gửi lệnh không

Quy tắc hoặc cảnh báo không kích hoạt

Dữ liệu thiết bị có vào trạng thái chạy của nền tảng không
Sản phẩm, thiết bị, biến mà kịch bản hoặc quy tắc gắn với có đúng không
Biểu thức điều kiện có nhất quán với kiểu giá trị báo lên không
Cấu hình cảnh báo đã bật chưa

Chuyển đổi Rule Script

Nếu thiết bị dùng định dạng dữ liệu tùy biến, có thể viết logic chuyển đổi trong Rule Script, chuyển dữ liệu thô sang định dạng chuẩn của nền tảng. Chi tiết xem Rule Script (简体中文).

Kết nối MQTT ​

Quy trình kết nối ​

Thông tin kết nối ​

Xác thực thiết bị ​

Xác thực đơn giản (khuyến nghị dùng khi kiểm thử) ​

Xác thực mã hóa (khuyến nghị dùng cho môi trường sản xuất) ​

Giải thích mã hóa AES ​

Topic subscribe (nền tảng → thiết bị) ​

Topic publish (thiết bị → nền tảng) ​

Định dạng dữ liệu ​

Publish thuộc tính/chức năng/sự kiện — /property/post, /event/post ​

Subscribe lệnh nền tảng — /function/get ​

Publish thông tin thiết bị — /info/post ​

Giám sát thời gian thực — /monitor/get, /monitor/post ​

Đồng bộ đồng hồ — /ntp/post, /ntp/get ​

Quy tắc định danh Thing Model ​

Cấu hình mạng AP cho thiết bị (tùy chọn, chỉ thiết bị WiFi) ​

Phát hiện thiết bị ​

API cấu hình ​

Dùng MQTTX kiểm thử ​

Checklist nghiệm thu liên hợp ​

Lỗi thường gặp ​

Kết nối bị từ chối ​

Thiết bị online nhưng thuộc tính không làm mới ​

Nền tảng gửi xuống nhưng thiết bị không nhận được ​

Quy tắc hoặc cảnh báo không kích hoạt ​

Chuyển đổi Rule Script ​

Tài liệu liên quan ​

Kết nối MQTT

Quy trình kết nối

Thông tin kết nối

Xác thực thiết bị

Xác thực đơn giản (khuyến nghị dùng khi kiểm thử)

Xác thực mã hóa (khuyến nghị dùng cho môi trường sản xuất)

Giải thích mã hóa AES

Topic subscribe (nền tảng → thiết bị)

Topic publish (thiết bị → nền tảng)

Định dạng dữ liệu

Publish thuộc tính/chức năng/sự kiện — `/property/post`, `/event/post`

Subscribe lệnh nền tảng — `/function/get`

Publish thông tin thiết bị — `/info/post`

Giám sát thời gian thực — `/monitor/get`, `/monitor/post`

Đồng bộ đồng hồ — `/ntp/post`, `/ntp/get`

Quy tắc định danh Thing Model

Cấu hình mạng AP cho thiết bị (tùy chọn, chỉ thiết bị WiFi)

Phát hiện thiết bị

API cấu hình

Dùng MQTTX kiểm thử

Checklist nghiệm thu liên hợp

Lỗi thường gặp

Kết nối bị từ chối

Thiết bị online nhưng thuộc tính không làm mới

Nền tảng gửi xuống nhưng thiết bị không nhận được

Quy tắc hoặc cảnh báo không kích hoạt

Chuyển đổi Rule Script

Tài liệu liên quan