การเชื่อมต่อ MQTT

FastBee รุ่นโอเพนซอร์สมี MQTT Broker ในตัวที่พัฒนาบน Netty ไม่ต้องปรับใช้ EMQX เพิ่มเติม บทนี้อธิบายวิธีที่อุปกรณ์เชื่อมต่อกับแพลตฟอร์มผ่านโปรโตคอล MQTT

ขั้นตอนการเชื่อมต่อ

1. สร้างและเผยแพร่ผลิตภัณฑ์ MQTT ในการจัดการผลิตภัณฑ์ ยืนยัน product ID, หมายเลขอุปกรณ์, บัญชี MQTT และรหัสผ่าน
2. อุปกรณ์หรือ MQTTX ใช้ clientId, userName, password ที่กำหนดเชื่อมต่อกับบริการ MQTT
3. หลังเชื่อมต่อสำเร็จ ให้เผยแพร่ /info/post ก่อน แล้วจึงเผยแพร่ /property/post หรือ /event/post
4. ฝั่งแพลตฟอร์มยืนยันวงปิดของเส้นทางผ่านสถานะการทำงาน บันทึกเหตุการณ์ และบันทึกคำสั่งในหน้ารายละเอียดอุปกรณ์

ข้อมูลการเชื่อมต่อ

พารามิเตอร์	การเชื่อมต่อ TCP	การเชื่อมต่อ WebSocket
ที่อยู่	IP เซิร์ฟเวอร์	ws://server-ip:8083/mqtt
พอร์ต	1883	8083
โปรโตคอล	MQTT 3.1.1	MQTT over WebSocket

การยืนยันตัวตนอุปกรณ์

提示

• ประเภทการยืนยันตัวตน: S = การยืนยันตัวตนแบบง่าย, E = การยืนยันตัวตนแบบเข้ารหัส
• เมื่อผลิตภัณฑ์เปิดใช้รหัสอนุญาตอุปกรณ์ รหัสอนุญาตต้องไม่ว่าง
• User ID คือ ID ของผู้ใช้ที่เข้าสู่ระบบ การใช้ User ID ต่างกันทำให้อุปกรณ์เป็นของผู้ใช้คนละคน
• หมายเลขอุปกรณ์อาจเป็นหมายเลขที่แพลตฟอร์มสร้าง หรือรหัสเฉพาะ เช่น MAC/IMEI ของอุปกรณ์ (แพลตฟอร์มจะลงทะเบียนอุปกรณ์โดยอัตโนมัติ)

การยืนยันตัวตนแบบง่าย (แนะนำสำหรับการทดสอบ)

clientId = S&device-number&product-id&user-id
userName = บัญชี MQTT
password = รหัสผ่าน MQTT
password = รหัสผ่าน MQTT&รหัสอนุญาตอุปกรณ์ (เมื่อผลิตภัณฑ์เปิดใช้การอนุญาตอุปกรณ์)

ตัวอย่าง:

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

การยืนยันตัวตนแบบเข้ารหัส (แนะนำสำหรับการผลิต)

clientId = E&device-number&product-id&user-id
userName = บัญชี MQTT
password = เข้ารหัส AES(รหัสผ่าน MQTT&การประทับเวลาหมดอายุ&รหัสอนุญาต(ไม่บังคับ))

• รหัสผ่านถูกเข้ารหัสด้วย AES-CBC โดยใช้คีย์ผลิตภัณฑ์ (ค่า offset wumei-smart-open ผลลัพธ์เป็น Base64)
• การประทับเวลาหมดอายุมีความละเอียดถึงมิลลิวินาที แนะนำไม่เกิน 24 ชั่วโมง

ตัวอย่าง:

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

คำอธิบายการเข้ารหัส AES

ใช้โหมดการเข้ารหัส AES-CBC สำหรับการทดสอบสามารถใช้ เครื่องมือเข้ารหัส/ถอดรหัสออนไลน์:

พารามิเตอร์	ค่า
โหมดการเข้ารหัส	CBC
Padding	pkcs5padding
บล็อกข้อมูล	128 บิต
ค่า offset	wumei-smart-open
ผลลัพธ์	Base64
รหัสผ่าน	คีย์ผลิตภัณฑ์
เนื้อหาที่เข้ารหัส	รหัสผ่าน MQTT&expireTime&รหัสอนุญาต(ไม่บังคับ)

หัวข้อที่สมัครรับ (แพลตฟอร์ม → อุปกรณ์)

หัวข้อ	คำอธิบาย
/{productId}/{deviceNum}/function/get	สมัครรับคำสั่งจากแพลตฟอร์ม (การตั้งค่าคุณสมบัติ การเรียกฟังก์ชัน)
/{productId}/{deviceNum}/info/get	สมัครรับคำขอข้อมูลอุปกรณ์ (เมื่อได้รับให้เผยแพร่ข้อมูลอุปกรณ์)
/{productId}/{deviceNum}/monitor/get	สมัครรับคำขอตรวจสอบแบบเรียลไทม์ (ส่งกลับจำนวนครั้งและช่วงเวลา)
/{productId}/{deviceNum}/ntp/get	สมัครรับการซิงโครไนซ์เวลา (ไม่บังคับ)
/{deviceNum}/http/upgrade/set	สมัครรับการอัปเกรด OTA แบบ HTTPS
/{deviceNum}/fetch/upgrade/set	สมัครรับการอัปเกรด OTA แบบแพ็กเกจไบนารี

หัวข้อที่เผยแพร่ (อุปกรณ์ → แพลตฟอร์ม)

หัวข้อ	คำอธิบาย
/{productId}/{deviceNum}/property/post	เผยแพร่ข้อมูลคุณสมบัติ/ฟังก์ชัน (แสดงแบบเรียลไทม์และจัดเก็บ)
/{productId}/{deviceNum}/event/post	เผยแพร่เหตุการณ์
/{productId}/{deviceNum}/info/post	เผยแพร่ข้อมูลอุปกรณ์
/{productId}/{deviceNum}/monitor/post	เผยแพร่ข้อมูลตรวจสอบแบบเรียลไทม์ (เฉพาะกราฟเรียลไทม์ ไม่จัดเก็บ)
/{productId}/{deviceNum}/ntp/post	เผยแพร่การซิงโครไนซ์เวลา (ไม่บังคับ)
/{deviceNum}/http/upgrade/reply	ตอบกลับการอัปเกรด OTA แบบ HTTPS
/{deviceNum}/fetch/upgrade/reply	ตอบกลับการอัปเกรด OTA แบบแพ็กเกจไบนารี

提示

• {productId} คือ product ID (ไม่ใช่หมายเลขผลิตภัณฑ์) ดูได้ในหน้ารายละเอียดผลิตภัณฑ์ของแพลตฟอร์ม
• {deviceNum} คือหมายเลขอุปกรณ์ ต้องตรงกับอุปกรณ์บนแพลตฟอร์มทุกประการ

รูปแบบข้อมูล

อุปกรณ์และแพลตฟอร์มแลกเปลี่ยนข้อมูลในรูปแบบ JSON

เผยแพร่คุณสมบัติ/ฟังก์ชัน/เหตุการณ์ — /property/post, /event/post

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "อุณหภูมิปกติ"
}, {
    "id": "switch",
    "value": "1",
    "remark": "เปิดสวิตช์แล้ว"
}]

• id: ตัวระบุ Thing Model ดูได้ในรายละเอียดผลิตภัณฑ์ ไม่ซ้ำกันภายใต้ผลิตภัณฑ์เดียวกัน
• value: ค่าส่งผ่านเป็นสตริง ชนิดบูลีนใช้ "0"/"1" ชนิด enum ใช้ค่าคีย์ของ enum ชนิดอาร์เรย์คั่นด้วยเครื่องหมายจุลภาค
• remark: ข้อมูลหมายเหตุ ดูได้ในบันทึกอุปกรณ์

สมัครรับคำสั่งจากแพลตฟอร์ม — /function/get

[{
    "id": "gear",
    "value": "1",
    "remark": "ทริกเกอร์จาก Scene Linkage"
}, {
    "id": "switch",
    "value": "0",
    "remark": "ปิดตามเวลาที่ตั้งไว้"
}]

เผยแพร่ข้อมูลอุปกรณ์ — /info/post

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

ฟิลด์	คำอธิบาย
rssi	ความแรงสัญญาณ (ดีมาก [-55~0], ดี [-70~-55], ปานกลาง [-85~-70], แย่ [-100~-85])
firmwareVersion	หมายเลขเวอร์ชันเฟิร์มแวร์
status	สถานะอุปกรณ์ คงที่เป็น 3 (ออนไลน์)
userId	User ID
longitude/latitude	ไม่บังคับ ตำแหน่งอุปกรณ์
summary	ไม่บังคับ ข้อมูลสรุปของอุปกรณ์

การตรวจสอบแบบเรียลไทม์ — /monitor/get, /monitor/post

แพลตฟอร์มส่งคำขอตรวจสอบลง:

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

อุปกรณ์รายงานข้อมูลตามจำนวนครั้งและช่วงเวลาที่กำหนด:

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

การซิงโครไนซ์เวลา — /ntp/post, /ntp/get

อุปกรณ์เผยแพร่:

{
    "deviceSendTime": "1592361428000"
}

แพลตฟอร์มตอบกลับ:

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

เวลาปัจจุบันของอุปกรณ์ = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

กฎของตัวระบุ Thing Model

• ตัวระบุทั้งหมดต้องไม่ซ้ำกันภายใต้ผลิตภัณฑ์เดียวกัน ใช้ตัวอักษรและตัวเลขเป็นหลัก หลีกเลี่ยงอักขระพิเศษ
• รูปแบบ ID โมเดลย่อยของชนิดอ็อบเจกต์: parentId_childId
• ตัวระบุชนิดอาร์เรย์ต้องขึ้นต้นด้วย array_index (index เป็นตัวเลขสองหลัก เช่น array_00_power_switch) ความยาวอาร์เรย์ไม่เกิน 100

การตั้งค่าเครือข่ายแบบ AP ของอุปกรณ์ (ไม่บังคับ เฉพาะอุปกรณ์ WiFi)

อุปกรณ์เปิดฮอตสปอต (ที่อยู่ 192.168.4.1) และฝั่งมือถือส่งข้อมูลการกำหนดค่าผ่านบริการเว็บของอุปกรณ์

ตรวจจับอุปกรณ์

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

HTTP 200 หมายถึงตรวจพบอุปกรณ์ การตอบกลับมีข้อมูลอุปกรณ์และสถานะเครือข่ายปัจจุบัน

อินเทอร์เฟซการกำหนดค่า

POST http://192.168.4.1/api/wifi/config?SSID=ชื่อ-WiFi&password=รหัสผ่าน-WiFi&userId=รหัสผู้ใช้

พารามิเตอร์	คำอธิบาย
SSID	ชื่อ WiFi (จำเป็น รองรับ ssid ตัวพิมพ์เล็ก)
password	รหัสผ่าน WiFi (จำเป็น รองรับชื่อแทน pwd)
userId	User ID (จำเป็น)
deviceNum	หมายเลขอุปกรณ์ (ไม่บังคับ)
extra	หมายเลขผลิตภัณฑ์ (ไม่บังคับ)

HTTP 200 หมายถึงตั้งค่าเครือข่ายสำเร็จ (อุปกรณ์จะสลับเป็นโหมด STA โดยอัตโนมัติ) 400 หมายถึงพารามิเตอร์ที่จำเป็นขาดหายไป 500 หมายถึงบันทึกไม่สำเร็จ รายละเอียดอินเทอร์เฟซดูใน《การกำหนดค่าเครือข่าย · API การตั้งค่าเครือข่ายแบบ AP สำหรับโทรศัพท์/มือถือ》

ทดสอบด้วย MQTTX

1. ดาวน์โหลดไคลเอนต์ MQTTX
2. สร้างการเชื่อมต่อใหม่:
   • Host: mqtt://server-ip, Port: 1883
   • Client ID: S&device-number&product-id&1
   • Username: บัญชี MQTT
   • Password: รหัสผ่าน MQTT
3. สมัครรับ /{productId}/{deviceNum}/function/get
4. เผยแพร่ข้อมูลอุปกรณ์ไปยัง /{productId}/{deviceNum}/info/post
5. เผยแพร่ข้อมูลคุณสมบัติไปยัง /{productId}/{deviceNum}/property/post
6. สังเกตสถานะออนไลน์และข้อมูลการทำงานของอุปกรณ์ในคอนโซลแพลตฟอร์ม

เช็กลิสต์ตรวจรับการทดสอบร่วม

ขั้นตอน	เนื้อหาที่ตรวจรับ	ผลลัพธ์ที่สำเร็จ
1	ผลิตภัณฑ์ได้รับการเผยแพร่แล้ว	สถานะผลิตภัณฑ์เป็นเผยแพร่แล้ว
2	MQTTX เชื่อมต่อ	รายละเอียดอุปกรณ์แสดงออนไลน์
3	/info/post	ฟิลด์ข้อมูลอุปกรณ์ สัญญาณ และเวอร์ชันได้รับการอัปเดต
4	/property/post	สถานะการทำงานแสดงค่าคุณสมบัติ Thing Model
5	/event/post	บันทึกเหตุการณ์มีเหตุการณ์ที่รายงาน
6	/function/get	อุปกรณ์ได้รับคำสั่งหลังแพลตฟอร์มส่งลง
7	ส่งผลลัพธ์กลับ	อุปกรณ์ส่งกลับตามผลการส่งลง สถานะแพลตฟอร์มรีเฟรช
8	กฎ/ฉาก	กฎ ฉาก และการแจ้งเตือนที่เกี่ยวข้องถูกกระตุ้นได้

ข้อผิดพลาดที่พบบ่อย

การเชื่อมต่อถูกปฏิเสธ

1. พอร์ต 1883 ของเซิร์ฟเวอร์เปิดอยู่หรือไม่
2. MQTT Broker ในตัวเริ่มทำงานหรือไม่
3. รูปแบบ clientId ถูกต้องหรือไม่ (S&device-number&product-id&user-id)
4. ผลิตภัณฑ์เปิดใช้รหัสอนุญาตอุปกรณ์หรือไม่
5. อุปกรณ์ถูกปิดใช้งานหรือไม่

อุปกรณ์ออนไลน์แต่คุณสมบัติไม่รีเฟรช

1. หัวข้อที่เผยแพร่เป็น /{productId}/{deviceNum}/property/post หรือไม่
2. productId ใช้ product ID (ไม่ใช่หมายเลขผลิตภัณฑ์) หรือไม่
3. deviceNum ตรงกับหมายเลขอุปกรณ์ทุกประการหรือไม่
4. เนื้อหาข้อความเป็นรูปแบบอาร์เรย์ JSON หรือไม่
5. id ตรงกับตัวระบุ Thing Model ทุกประการหรือไม่
6. value ตรงกับชนิดข้อมูลหรือไม่

แพลตฟอร์มส่งลงแล้วแต่อุปกรณ์ไม่ได้รับ

1. อุปกรณ์สมัครรับ /{productId}/{deviceNum}/function/get หรือไม่
2. อุปกรณ์ยังออนไลน์อยู่หรือไม่
3. Thing Model เป็นฟังก์ชันที่เขียนได้หรือคุณสมบัติที่ส่งลงได้หรือไม่
4. ผู้ใช้มีสิทธิ์ดูรายละเอียดอุปกรณ์และส่งคำสั่งลงหรือไม่

กฎหรือการแจ้งเตือนไม่ถูกกระตุ้น

1. ข้อมูลอุปกรณ์เข้าสู่สถานะการทำงานของแพลตฟอร์มหรือไม่
2. ผลิตภัณฑ์ อุปกรณ์ และตัวแปรที่ผูกกับฉากหรือกฎถูกต้องหรือไม่
3. นิพจน์เงื่อนไขตรงกับชนิดของค่าที่รายงานหรือไม่
4. การกำหนดค่าการแจ้งเตือนเปิดใช้งานอยู่หรือไม่

การแปลงด้วย Rule Script

หากอุปกรณ์ใช้รูปแบบข้อมูลแบบกำหนดเอง สามารถเขียนตรรกะการแปลงใน Rule Script เพื่อแปลงข้อมูลดิบเป็นรูปแบบมาตรฐานของแพลตฟอร์ม รายละเอียดดูที่ Rule Script (ภาษาจีน)

เอกสารที่เกี่ยวข้อง

• การจัดการผลิตภัณฑ์ (ภาษาจีน)
• การจัดการอุปกรณ์ (ภาษาจีน)
• Thing Model (ภาษาจีน)
• Scene Linkage (ภาษาจีน)