Reach a server

MQTT TCP telemetry

The usual channel for sensors and remote commands, but plaintext by default — use TLS on the public internet.

Reach a server MQTT ESP32 Wi-Fi parts

Official path: examples/protocols/mqtt/tcp

01 Overview

MQTT is the de facto standard for IoT telemetry and remote commands. This example demonstrates an ESP32 connecting to a broker over TCP, subscribing and publishing.

It solves bidirectional messaging: sensor data upstream, control commands downstream. Compared to HTTP polling, MQTT's persistent connection gives lower latency and less server load.

Typical use: temperature/humidity reporting, remote switches, alert push. Ideal for always-on or frequent small data exchanges.

Not for: LAN-only web pages (use HTTP), BLE-only communication (use BLE), or public internet without TLS (use the SSL example).

The official TCP example is plaintext — data can be sniffed. For production, switch to the SSL example or use a cloud SDK with TLS.

This is an ESP-IDF official example showing the MQTT event-driven model, a good starting point for understanding the ESP-MQTT library.

02 Hardware

MCU: Any ESP32 series; this example uses no special peripherals.
Wi-Fi: Wi-Fi must already work; MQTT reuses the same stack, no extra pins.
Power: For battery devices, design with deep sleep; don't keep TCP open all day.
Antenna: Ensure proper antenna matching; weak signal causes frequent disconnects.
No extra hardware: A dev board running ESP-IDF is enough; no external sensors needed.
Debug: Use UART logs to watch MQTT events for connection troubleshooting.

03 Software flow

1. Configure Wi-Fi SSID/password, wait for GOT_IP event.

2. Set broker URI and client ID, register event callback.

3. On CONNECTED, subscribe to topics and publish initial messages.

4. On DATA, parse the payload; the official code only logs, you must handle business logic.

5. Handle ERROR and DISCONNECTED events to implement reconnection.

6. In production, client IDs and topics must be unique per device.

7. For power saving, combine with deep sleep: wake, report quickly, disconnect.

04 Core points

Stable IP before MQTT. Don't connect before the network is ready.
Plain MQTT is not a public-internet product. Use TLS or VPN.
Client ID must be unique. Duplicates cause mutual disconnects.
Choose QoS carefully. QoS 1/2 add overhead but improve reliability.
Don't copy the example blindly. It only logs; production needs payload parsing.
Custom work: broker (AWS IoT, Aliyun), TLS certificates, report period.

中文

连上服务器

MQTT TCP 上报

传感上报和远程命令最常见的通道，但默认明文，公网需 TLS。

连上服务器 MQTT ESP32 Wi-Fi parts

官方路径: examples/protocols/mqtt/tcp

01 项目概述

MQTT 是物联网设备上报遥测和接收远程命令的事实标准。本示例演示 ESP32 通过 TCP 直连 MQTT 代理，完成订阅和发布。

它解决的是设备与云端的双向消息问题：传感器数据上行，控制指令下行。相比 HTTP 轮询，MQTT 长连接延迟更低，服务器压力更小。

典型应用：温湿度上报、远程开关、告警推送。适合需要持续在线或频繁小数据交互的场景。

不适用于：仅局域网网页控制（用 HTTP 更简单）、仅 BLE 通信（用 BLE 协议）、需要高可靠公网传输（必须用 SSL 示例）。

官方 TCP 示例默认明文，数据可被窃听。公网部署务必改用 SSL 示例，或使用带 TLS 的云平台 SDK。

本示例是 ESP-IDF 官方例程，展示了 MQTT 事件驱动模型，是理解 ESP-MQTT 库的起点。

02 项目硬件描述

MCU: 任意 ESP32 系列，本示例不依赖特定外设。
Wi-Fi: 需先完成 Wi-Fi 连接，MQTT 复用同一网络栈，不占用额外引脚。
电源: 若为电池供电，需考虑深睡与唤醒，避免长时间保持 TCP 连接。
天线: 确保 PCB 天线或外置天线匹配，信号弱会导致频繁断线重连。
无额外硬件: 本示例仅需一个能跑 ESP-IDF 的开发板，无需外接传感器。
调试: 建议通过 UART 日志观察 MQTT 事件，便于排查连接问题。

03 项目软件流程描述

1. 配置 Wi-Fi SSID/密码，等待 GOT_IP 事件。

2. 设置 MQTT broker URI、Client ID，注册事件回调。

3. 在 CONNECTED 事件中订阅主题，并发布初始消息。

4. 在 DATA 事件中解析接收到的 payload，官方示例仅打印，实际需按业务处理。

5. 处理 ERROR 和 DISCONNECTED 事件，实现重连逻辑。

6. 量产时 Client ID 和主题必须按设备唯一，避免冲突。

7. 如需省电，可结合深睡，在唤醒后快速上报并断开。

04 项目核心点

先稳 IP，再开 MQTT。 网络未就绪前不要尝试连接。
明文不能出公网。 公网必须使用 TLS 或 VPN。
Client ID 必须唯一。 重复会导致互踢。
QoS 选择要谨慎。 QoS 1/2 增加开销，但更可靠。
不要照搬示例。 示例只打印，生产需解析 payload 并处理业务。
可定制： 云平台（如 AWS IoT、阿里云）、TLS 证书、上报周期。