网络与通信库

本文引用的文件

产品概述

本章节面向 mPython/ESP32-S3 平台的网络与通信能力，聚焦四类常用接口：HTTP 客户端（urequests）、MQTT 客户端（umqtt.simple）、无线广播（radio，基于 ESP-NOW）以及低功耗蓝牙（bluetooth）。它们分别覆盖“请求-响应”的 HTTP 访问、轻量级发布/订阅消息、短距无连接组网与 BLE 设备互联等典型物联网场景，适合传感器数据上报、远程控制、设备间近场通信与云端交互。

核心业务流程

  • HTTP 客户端流程

    • 解析 URL、选择端口与协议（http/https）

    • 建立 socket 连接（可选 SSL）

    • 组装请求头与正文（表单/JSON/文件上传）

    • 发送请求并读取响应状态码与头部

    • 封装 Response 对象，提供 content/text/json 便捷访问

  • MQTT 客户端流程

    • 创建 MQTTClient，配置服务器、认证、保活、遗嘱

    • 建立 TCP/SSL 连接并完成握手

    • 发布/订阅主题，设置回调处理入站消息

    • 通过 wait_msg/check_msg 在主循环中驱动消息收发

    • robust 版本在异常时自动重连

  • 无线广播（ESP-NOW）流程

    • 初始化 Wi-Fi STA/AP 与 ESP-NOW 栈

    • 添加对端 MAC（支持加密/PMK）

    • 发送单播/广播消息，接收回调或轮询

    • 查询对端列表、MAC、RSSI 等信息

  • BLE 流程

    • 启用 BLE，配置地址模式、MTU、配对参数等

    • 作为广播者/观察者/中央/外围角色运行

    • 注册 GATT 服务/特征，读写/通知/指示

    • 发现远程服务/特征/描述符，执行读/写/交换 MTU

    • 使用 L2CAP 通道进行面向连接的数据传输

graph TB
A["应用代码"] --> B["HTTP 客户端<br/>urequests"]
A --> C["MQTT 客户端<br/>umqtt.simple / robust"]
A --> D["无线广播<br/>radio (ESP-NOW)"]
A --> E["BLE 模块<br/>bluetooth"]
B --> F["TCP/SSL 套接字"]
C --> G["TCP/SSL 套接字"]
D --> H["ESP-NOW 栈"]
E --> I["BLE 控制器/GAP/GATT/L2CAP"]

图表来源

章节来源

功能模块清单

  • urequests（HTTP 客户端）

    • 职责：提供简洁的 HTTP 请求方法（GET/POST/PUT/PATCH/DELETE/HEAD），统一封装响应体与 JSON 解析，支持表单/JSON/文件上传与 HTTPS。

    • 用户价值：快速对接 Web API、云平台与本地服务；减少底层 socket 编程复杂度。

    • 验收要点：URL 解析正确、参数编码、Content-Type 设置、HTTPS 握手、响应状态码与文本/JSON 获取、超时与错误提示。

  • umqtt.simple（MQTT 客户端）

    • 职责：实现 MQTT 连接、发布、订阅、心跳与遗嘱；robust 版本提供断线重连。

    • 用户价值：稳定可靠的发布/订阅消息通道，适配弱网与延迟环境。

    • 验收要点：连接/断开、QoS0/1 发布、订阅回调触发、遗嘱生效、check_msg/wait_msg 行为、异常重连。

  • radio（无线广播，ESP-NOW）

    • 职责：基于 ESP-NOW 的无连接短距通信，支持多通道、对端管理、广播/单播、RSSI 与加密。

    • 用户价值：多板组网、低开销、低延迟的近场通信。

    • 验收要点：通道配置、对端添加/删除、发送成功返回、接收字符串/字节、广播与 RSSI、加密 PMK。

  • bluetooth（BLE）

    • 职责：提供 GAP/GATT/L2CAP 的低功耗蓝牙能力，涵盖广播、扫描、连接、服务发现、读写通知、配对绑定。

    • 用户价值：构建 BLE 外设/中心设备，实现手机/网关/传感器互联。

    • 验收要点：active/config/irq 事件、gap_advertise/gap_scan/gap_connect、gatts/gattc 操作、L2CAP 收发、MTU 交换、配对与密钥存储。

章节来源

数据与状态

  • HTTP 响应模型

    • Response 对象缓存 body，提供 content（bytes）、text（str）、json（dict）与 recv。

    • 内部维护 raw socket 引用，close 释放资源。

  • MQTT 会话与消息

    • MQTTClient 维护 client_id、server/port、ssl、keepalive、遗嘱、PID 与回调。

    • publish 支持 QoS0/1；wait_msg/check_msg 驱动消息分发。

    • robust.MQTTClient 在 OSError 时指数退避重连。

  • ESP-NOW 对端与队列

    • MPythonESPNow 维护 peer_list、broadcast 标志、Wi-Fi 通道与加密 PMK。

    • 支持 send_data/send_msg/broadcast_data，recv/recv_msg 返回源地址与数据，含 RSSI（平台相关）。

  • BLE 角色与句柄

    • BLE 对象管理活动状态、配置项（mac/addr_mode/gap_name/mtu/bond/mitm/io/le_secure）。

    • GAP：广播 interval_us、扫描 duration_ms/interval/window、连接参数。

    • GATT：服务/特征/描述符句柄，读写/通知/指示、缓冲大小。

    • L2CAP：PSM/CID/MTU 与信用流控。

classDiagram
class Response {
+raw
+encoding
-_cached
+close()
+content
+text
+json()
+recv(dataLen)
}
class MQTTClient {
+client_id
+server
+port
+ssl
+keepalive
+lw_topic
+lw_msg
+cb
+connect(clean_session)
+disconnect()
+ping()
+publish(topic, msg, retain, qos)
+subscribe(topic, qos)
+wait_msg()
+check_msg()
}
class MPythonESPNow {
+wifi_sta
+wifi_ap
+wifi_channel
+peer_list
+broadcast
+set_add_peer(peer_mac)
+send_data(peer_id, msg)
+send_msg(peer_mac, msg)
+broadcast_data(msg)
+recv(timeout_ms)
+get_peer_list(encrypt)
+get_mac(mode)
+deinit()
}
class BLE {
+active([active])
+config(param=value...)
+irq(handler)
+gap_advertise(interval_us, adv_data, resp_data, connectable)
+gap_scan(duration_ms, interval_us, window_us, active)
+gap_connect(addr_type, addr, scan_duration_ms, min_conn_interval_us, max_conn_interval_us)
+gatts_register_services(services_definition)
+gattc_discover_services(conn_handle, uuid)
+l2cap_listen(psm, mtu)
+l2cap_connect(conn_handle, psm, mtu)
}
Response --> "uses" usocket
MQTTClient --> "uses" socket
MPythonESPNow --> "uses" network.WLAN
BLE --> "uses" bluetooth 控制器

图表来源

章节来源

关键约束与边界

  • 协议与依赖

    • urequests 依赖 usocket/ussl/urllib.parse/ujson；仅支持 HTTP/1.0 请求格式，不支持分块传输与重定向。

    • umqtt.simple 仅实现 QoS0/1；QoS2 未实现以控制固件体积；所有主题与消息为字节。

    • radio 基于 ESP-NOW，需在同一频道内通信，最大包长受协议限制（文档示例为 250 字节级别）。

    • bluetooth 为底层 BLE 抽象，部分特性（如 L2CAP）在不同堆栈/平台上可用性不同。

  • 性能与资源

    • HTTP 请求默认超时（例如 30 秒），注意内存占用与网络抖动。

    • MQTT 主循环需定期调用 wait_msg/check_msg 以处理消息；robust 版本有重连延时。

    • ESP-NOW 适合短距、低开销、多节点组网；加密会引入额外开销。

    • BLE 广播间隔与扫描窗口影响功耗与发现速度；MTU 协商影响吞吐。

  • 安全与配置

    • HTTPS 需要证书校验策略由底层实现决定；MQTT 可配置用户名/密码与遗嘱。

    • ESP-NOW 支持 PMK 加密与 LMN；BLE 支持配对/绑定与 MITM 选项。

  • 兼容性

    • 不同板型/固件可能包含/排除某些模块（如 radio 在 ESP32 与 ESP32-S3 的实现差异）。

    • BLE 常量与事件需在应用中自行定义（节省空间）。

章节来源

详细 API 参考

urequests（HTTP 客户端）

  • 类与方法

    • Response

      • close()：关闭底层 socket 并清理缓存

      • content：返回响应体字节（带缓存）

      • text：按 encoding 解码为字符串

      • json()：将响应体解析为 dict

      • recv(dataLen)：从原始流读取指定长度

    • request(method, url, data=None, json=None, headers={}, params=None, files=None)

      • 支持 GET/POST/PUT/PATCH/DELETE/HEAD 快捷函数

      • 自动处理 URL 参数编码、表单/JSON 序列化、文件上传 multipart/form-data

      • 支持 https（ussl）与 http（明文）

  • 典型用法

    • 获取 JSON 数据：get(url).json()

    • 提交表单：post(url, data={...})

    • 上传文件：post(url, files={'name': ('path', 'type')})

sequenceDiagram
participant App as "应用"
participant UR as "urequests.request"
participant Sock as "socket/ssl"
App->>UR : get/post/put/...
UR->>UR : 解析URL/参数/编码
UR->>Sock : 建立连接(可选SSL)
UR->>Sock : 发送请求头与正文
Sock-->>UR : 状态行与头部
UR-->>App : Response(content/text/json)

图表来源

  • firmware/port/modules/urequests.py:41-165

章节来源

umqtt.simple（MQTT 客户端）

  • 类与方法

    • MQTTClient(client_id, server, port=0, user=None, password=None, keepalive=0, ssl=False, ssl_params={})

    • set_callback(f)：设置订阅消息回调 f(topic, msg)

    • set_last_will(topic, msg, retain=False, qos=0)：设置遗嘱

    • connect(clean_session=True)：建立连接

    • disconnect()：断开连接

    • ping()：心跳

    • publish(topic, msg, retain=False, qos=0)：发布消息（QoS0/1）

    • subscribe(topic, qos=0)：订阅主题

    • wait_msg()：阻塞等待消息

    • check_msg()：非阻塞检查消息

  • robust 增强

    • reconnect()：异常后自动重连

    • publish()/wait_msg()：捕获 OSError 并重连

flowchart TD
Start(["启动"]) --> Init["创建MQTTClient"]
Init --> Connect{"连接成功?"}
Connect -- 否 --> Reconnect["reconnect()重试"]
Reconnect --> Connect
Connect -- 是 --> Loop{"主循环"}
Loop --> Publish["publish(topic,msg,qos)"]
Loop --> Subscribe["subscribe(topic,qos)"]
Loop --> Wait["wait_msg()/check_msg()"]
Wait --> Callback["回调f(topic,msg)"]
Callback --> Loop
Publish --> Loop
Subscribe --> Loop

图表来源

  • firmware/port/modules/umqtt/simple.py:8-103

  • firmware/port/modules/umqtt/robust.py:20-46

章节来源

radio（无线广播，ESP-NOW）

  • 能力概览

    • 基于 ESP-NOW，支持多通道、对端管理、广播/单播、RSSI、加密（PMK）

    • 适用于 30 米范围内多板组网

  • 主要方法

    • on()/off()：开启/关闭无线电

    • config(channel)：配置通道（1~13）

    • receive()/receive_bytes()：接收消息（字符串/字节），可返回 (msg, mac)

    • send()/send_bytes()：发送消息（字符串/字节），返回成功与否

    • 高级封装（ESP32-S3 示例）：MPythonESPNow 提供 add_peer、send_data、broadcast_data、recv、get_peer_list、get_mac、set_pmk_encrypt 等

sequenceDiagram
participant A as "设备A"
participant RadioA as "radio(MPYthonESPNow)"
participant RadioB as "radio(MPYthonESPNow)"
A->>RadioA : set_add_peer(B_MAC)
A->>RadioA : send_msg(B_MAC, msg)
RadioA->>RadioB : ESP-NOW 单播
RadioB-->>RadioB : recv()/recv_msg()
Note over RadioB : 可获取MAC/RSSI(平台相关)

图表来源

  • esp32s3/firmware/modules/radio.py:46-132

章节来源

bluetooth（BLE）

  • 角色与生命周期

    • 激活与配置：active([active])、config(...)（mac/addr_mode/gap_name/mtu/bond/mitm/io/le_secure）

    • 事件：irq(handler) 统一处理 GAP/GATT/L2CAP 事件

  • GAP

    • 广播：gap_advertise(interval_us, adv_data, resp_data, connectable)

    • 扫描：gap_scan(duration_ms, interval_us, window_us, active)

    • 连接：gap_connect(addr_type, addr, scan_duration_ms, min_conn_interval_us, max_conn_interval_us)

    • 断开：gap_disconnect(conn_handle)

  • GATT 服务器

    • gatts_register_services(services_definition)：注册服务/特征/描述符

    • gatts_read/write/notify/indicate：读写与推送

    • gatts_set_buffer：设置值缓冲大小

  • GATT 客户端

    • gattc_discover_services/characteristics/descriptors：发现

    • gattc_read/write：读取/写入

    • gattc_exchange_mtu：交换 MTU

  • L2CAP

    • l2cap_listen/connect/disconnect/send/recvinto：面向连接通道

sequenceDiagram
participant Central as "中央设备"
participant Peripheral as "外围设备"
Central->>Peripheral : gap_scan -> _IRQ_SCAN_RESULT
Central->>Peripheral : gap_connect -> _IRQ_PERIPHERAL_CONNECT
Peripheral->>Central : gatts_notify/indicate
Central->>Peripheral : gattc_read/write
Central->>Peripheral : gattc_exchange_mtu -> _IRQ_MTU_EXCHANGED
Central->>Peripheral : l2cap_connect -> _IRQ_L2CAP_CONNECT

图表来源

章节来源

故障排查与最佳实践

  • HTTP

    • 若出现“Unsupported protocol”或“Invalid URL”，检查 URL 格式与协议前缀

    • 大文件或慢网络建议合理设置超时与重试

    • 文件上传需确保 Content-Type 与 boundary 正确

  • MQTT

    • 未设置回调即订阅会报错；确保先 set_callback

    • 主循环必须调用 wait_msg()/check_msg() 以处理消息

    • 网络不稳定时使用 robust 版本，避免频繁手动重连

  • ESP-NOW

    • 对端未添加或信道不一致会导致发送失败；确认 channel 与 MAC

    • 加密需双方设置相同 PMK；否则无法解密

    • 接收侧需及时消费缓冲区，避免丢包

  • BLE

    • 广播/扫描参数影响功耗与发现成功率；按需调整 interval/window

    • MTU 协商前后可测量实际吞吐；过大可能导致丢包

    • 配对/绑定需实现 _IRQ_GET_SECRET/_IRQ_SET_SECRET 以持久化密钥

[本节为通用指导，不直接分析具体文件]

结论

urequests、umqtt.simple、radio 与 bluetooth 共同构成了 mPython/ESP32-S3 平台的核心网络与通信能力。根据应用场景选择合适的协议与抽象层：HTTP 用于云端交互，MQTT 用于轻量消息总线，ESP-NOW 用于近场多节点组网，BLE 用于低功耗设备互联。结合本文档的 API 说明与流程图，可快速搭建稳定的 IoT 解决方案。

[本节为总结性内容，不直接分析具体文件]