ThingsCloud MicroPython SDK 使用教程
ThingsCloud MicroPython SDK 使用教程
本教程帮助你使用 ThingsCloud MicroPython SDK,将 ESP32/ESP8266 等设备快速接入 ThingsCloud 物联网平台。
简介
ThingsCloud MicroPython SDK 是专为 ThingsCloud 物联网平台设计的轻量级 SDK,帮助物联网设备开发者快速将设备接入云平台。该 SDK 采用简洁的 API 设计,无需深入了解 MQTT 协议细节即可快速上手。
获取 SDK
完整代码和示例请访问 GitHub 仓库: https://github.com/IoT-ThingsCloud/thingscloud-micropython-sdk
特性
- 轻量级 MQTT 客户端,专为 ThingsCloud 优化
- 简单易用的 API,无需了解 MQTT 细节
- 支持属性上报、命令接收、事件上报等完整功能
- 支持两种认证模式:直接连接和一型一密
- 完整的示例代码,快速上手
支持的硬件平台
本 SDK 支持所有运行 MicroPython 的硬件平台,包括但不限于:
| 芯片/开发板 | 说明 |
|---|---|
| ESP32 | 乐鑫 ESP32 系列芯片,支持 WiFi 和蓝牙 |
| ESP8266 | 乐鑫 ESP8266 系列芯片,低成本 WiFi 方案 |
| STM32 | 意法半导体 STM32 系列微控制器 |
| RP2040 | 树莓派 Pico 系列(需配合网络模块) |
| RPi Pico W | 树莓派 Pico W(内置 WiFi) |
| Pyboard | MicroPython 官方开发板 |
提示
使用非 ESP32/ESP8266 平台时,需要自行配置网络连接模块。
准备工作
1. 安装 MicroPython 固件
首先需要为你的 ESP32 开发板烧录 MicroPython 固件。
- 从 MicroPython 官网 下载最新的 ESP32 固件
- 使用 esptool 或 Thonny IDE 烧录固件
2. 安装开发工具
推荐使用以下任一 IDE:
- Thonny IDE - 适合初学者,支持 MicroPython
- uPyCraft - 专为 MicroPython 设计
3. 获取设备证书
在 ThingsCloud 控制台创建设备后,在设备详情页的「连接」页面获取:
- AccessToken: 设备访问令牌(MQTT 用户名)
- ProjectKey: 项目密钥(MQTT 密码)
- MQTT 主机: MQTT 服务器域名
安装 SDK
- 从 GitHub 仓库下载
thingscloud_mqtt_lib.py文件 - 使用 Thonny IDE 或 uPyCraft 将文件上传到你的 MicroPython 设备中
# 克隆仓库
git clone https://github.com/IoT-ThingsCloud/thingscloud-micropython-sdk.git
# 或直接下载 thingscloud_mqtt_lib.py 文件
快速开始
模式一:直接连接(推荐用于开发调试)
使用 AccessToken 直接连接,适合开发调试阶段:
from thingscloud_mqtt_lib import ThingsCloudMQTTClient
import time
# 创建客户端
client = ThingsCloudMQTTClient(
project_key="YOUR_PROJECT_KEY",
server="YOUR_MQTT_HOST",
port=1883,
access_token="YOUR_ACCESS_TOKEN"
)
# 连接到 ThingsCloud
client.connect()
# 上报属性
client.report_attributes({
"temperature": 25.5,
"humidity": 60
})
# 保持连接并处理消息
while True:
client.check_msg()
time.sleep(1)
模式二:一型一密(推荐用于量产部署)
使用 DeviceKey 和 TypeKey 动态获取 AccessToken,适合量产部署:
from thingscloud_mqtt_lib import ThingsCloudMQTTClient
# 创建客户端(不需要 access_token)
client = ThingsCloudMQTTClient(
project_key="YOUR_PROJECT_KEY",
server="YOUR_MQTT_HOST",
port=1883
)
# 使用一型一密模式连接
# 设备会自动在平台创建并获取 AccessToken
client.connect_with_device_cert(
device_key="your_device_key", # 设备唯一标识
type_key="your_type_key", # 设备类型标识
api_endpoint="your_api_endpoint"
)
# 连接成功后即可正常使用
client.report_attributes({"temperature": 25.5})
功能详解
上报属性
设备连接后,可以随时向云端上报属性数据:
# 上报单个属性
client.report_attributes({"temperature": 25.5})
# 上报多个属性
client.report_attributes({
"temperature": 25.5,
"humidity": 60,
"status": "online"
})
# 设置上报响应回调(可选)
def on_attributes_response(response):
if response.get("result") == 1:
print("上报成功")
else:
print("上报失败:", response)
client.on_attributes_response(on_attributes_response)
接收属性下发
设备可以接收云端主动下发的属性,用于配置更新或远程控制:
def on_attributes_push(attributes):
print("收到下发属性:", attributes)
# 处理下发的属性
if "switch" in attributes:
switch_state = attributes["switch"]
print(f"设置开关状态: {switch_state}")
# 执行开关控制逻辑...
if "report_interval" in attributes:
interval = attributes["report_interval"]
print(f"更新上报间隔: {interval}秒")
# 设置属性下发回调
client.on_attributes_push(on_attributes_push)
接收命令
设备可以接收云端下发的命令并执行,然后回复执行结果:
def on_command(command):
method = command.get("method")
params = command.get("params")
cmd_id = command.get("id")
print(f"收到命令: {method}, 参数: {params}")
# 执行命令逻辑...
# 回复命令
client.reply_command(method, {"status": "success"}, reply_id=cmd_id)
# 设置命令回调
client.on_command_send(on_command)
上报事件
设备可以向云端上报事件消息:
# 上报告警事件
client.report_event("alert", {
"level": "warning",
"message": "温度过高"
})
完整示例:WiFi + 温湿度上报
以下是一个完整的示例,展示如何连接 WiFi 并定时上报温湿度数据:
import network
import time
from thingscloud_mqtt_lib import ThingsCloudMQTTClient
# WiFi 配置
WIFI_SSID = "your_wifi_ssid"
WIFI_PASSWORD = "your_wifi_password"
# ThingsCloud 配置
PROJECT_KEY = "YOUR_PROJECT_KEY"
MQTT_HOST = "YOUR_MQTT_HOST"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
# 连接 WiFi
def connect_wifi():
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
if not wlan.isconnected():
print("正在连接 WiFi...")
wlan.connect(WIFI_SSID, WIFI_PASSWORD)
while not wlan.isconnected():
time.sleep(1)
print("WiFi 已连接:", wlan.ifconfig())
# 属性下发回调
def on_attributes_push(attributes):
print("收到下发属性:", attributes)
# 命令回调
def on_command(command):
method = command.get("method")
params = command.get("params")
cmd_id = command.get("id")
print(f"收到命令: {method}, 参数: {params}")
# 回复命令
client.reply_command(method, {"status": "success"}, reply_id=cmd_id)
# 主程序
def main():
# 连接 WiFi
connect_wifi()
# 创建 MQTT 客户端
global client
client = ThingsCloudMQTTClient(
project_key=PROJECT_KEY,
server=MQTT_HOST,
port=1883,
access_token=ACCESS_TOKEN
)
# 设置回调
client.on_attributes_push(on_attributes_push)
client.on_command_send(on_command)
# 连接到 ThingsCloud
client.connect()
print("已连接到 ThingsCloud")
# 主循环
while True:
# 模拟读取传感器数据
temperature = 25.5 # 实际使用时替换为传感器读取代码
humidity = 60.0
# 上报属性
client.report_attributes({
"temperature": temperature,
"humidity": humidity
})
print(f"已上报: 温度={temperature}°C, 湿度={humidity}%")
# 等待并检查消息
for _ in range(10): # 每 10 秒上报一次
client.check_msg()
time.sleep(1)
if __name__ == "__main__":
main()
更多示例
GitHub 仓库提供了丰富的示例代码:
MQTT 基础示例
- 01_direct_connect - 直接连接
- 02_dynamic_cert - 一型一密连接
- 03_report_attributes - 上报属性
- 04_report_events - 上报事件
- 05_receive_pushed_attributes - 接收下发属性
- 06_receive_commands - 接收下发命令
- 07_custom_data_stream - 自定义数据流
IoT 应用教程
- DHT 温湿度传感器 - 定时读取 DHT11/DHT22 传感器数据
- 继电器控制 - 接收云端命令控制继电器开关
API 参考
初始化
client = ThingsCloudMQTTClient(
project_key, # 项目 ProjectKey(必需)
server, # MQTT 服务器地址(必需)
port=1883, # 端口号
access_token=None # 设备 AccessToken(可选,用于一型一密模式)
)
连接方法
| 方法 | 说明 |
|---|---|
client.connect() | 直接连接(需要先设置 access_token) |
client.connect_with_device_cert(device_key, type_key, api_endpoint) | 一型一密模式连接 |
client.disconnect() | 断开连接 |
client.is_connected() | 检查连接状态 |
client.check_msg() | 检查消息(非阻塞) |
client.wait_msg() | 等待消息(阻塞) |
属性相关
| 方法 | 说明 |
|---|---|
client.report_attributes(data) | 上报属性 |
client.get_attributes(keys) | 获取指定属性 |
client.get_attributes() | 获取所有属性 |
client.on_attributes_push(callback) | 设置属性推送回调 |
client.on_attributes_response(callback) | 设置属性上报响应回调 |
命令相关
| 方法 | 说明 |
|---|---|
client.on_command_send(callback) | 设置命令接收回调 |
client.reply_command(method, params, reply_id) | 回复命令 |
事件相关
| 方法 | 说明 |
|---|---|
client.report_event(event_type, data) | 上报事件 |
常见问题
连接失败怎么办?
检查以下几点:
- WiFi 是否正常连接
- AccessToken 和 ProjectKey 是否正确
- 服务器地址和端口是否正确
- 设备是否已在平台创建
一型一密模式如何使用?
一型一密模式适合量产设备,只需配置 ProjectKey、TypeKey 和 DeviceKey,设备会自动获取 AccessToken。需要在控制台开启设备的动态注册功能。
如何调试?
可以使用 ThingsCloud 控制台的设备调试功能,查看消息收发情况。