从闪灯到联网：ESP32 开发的起点与智能家居实战

然后设置目标芯片、编译：

idf.py set-target esp32
idf.py build

成功的话，会看到 build/hello_esp32.bin。

烧录到底在做什么：分区、bootloader 与 esptool

很多人觉得'烧录'就是把 .bin 文件塞进 Flash，其实背后是三个二进制片段协同工作。idf.py flash 实际是调用了 esptool.py，通过串口把以下内容写到固定地址：

少任何一个，设备都起不来。

进入下载模式需要同时满足两个条件：拉低 GPIO0（一般是 BOOT 按钮）并触发一次复位（RST 按钮）。手动操作顺序是：按住 BOOT → 按一下 RST → 松开 RST → 再松开 BOOT。之后芯片进入等待串口指令的状态。如果你用的 USB-TTL 模块支持 DTR/RTS（如 CP2102、CH340G），idf.py flash 能自动完成这些动作，不用每次去按，方便很多。

分区表：设计 Flash 布局，别等 OTA 失败再回头看

默认项目会用 partitions_singleapp.csv，定义了三块：

# Name, Type, SubType, Offset, Size
nvs, data, nvs, 0x9000, 0x6000
phy_init, data, phy, 0xf000, 0x1000
factory, app, factory, 0x10000, 0xF0000

• nvs：存 Wi-Fi 密码等非易失数据
• phy_init：射频校准参数
• factory：主程序

如果未来计划做 OTA，就必须改成双 APP 分区模式，像这样：

# Name, Type, SubType, Offset, Size
nvs, data, nvs, 0x9000, 0x6000
phy_init, data, phy, 0xf000, 0x1000
ota_0, app, ota_0, 0x10000, 0x80000
ota_1, app, ota_1, 0x90000, 0x80000

然后在 idf.py menuconfig 里选择自定义分区表路径，并记着重新烧录分区表（地址 0x8000），否则旧的布局依然生效。

让设备联网：Wi-Fi 连接 + 获取 IP

在 main.c 中加入 Wi-Fi 初始化逻辑。需要先初始化 NVS 和网络栈，然后配置 STA 模式：

#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "freertos/event_groups.h"

#define WIFI_SSID "你的 WiFi 名称"
#define WIFI_PASS "你的 WiFi 密码"
#define EXAMPLE_ESP_MAXIMUM_RETRY 5

static EventGroupHandle_t s_wifi_event_group;

static void event_handler(void* arg, esp_event_base_t event_base, int32_t event_id, void *event_data) {
    static int retry = 0;
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
        esp_wifi_connect();
    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        if (retry < EXAMPLE_ESP_MAXIMUM_RETRY) {
            esp_wifi_connect();
            retry++;
            ESP_LOGI("wifi", "重连第 %d 次", retry);
        }
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
        ESP_LOGI("wifi", "获取 IP: " IPSTR, IP2STR(&event->ip_info.ip));
        retry = 0;
    }
}

void wifi_init_sta(void) {
    s_wifi_event_group = xEventGroupCreate();
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    esp_netif_create_default_wifi_sta();
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));
    esp_event_handler_instance_t instance_any_id;
    esp_event_handler_instance_t instance_got_ip;
    ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler, NULL, &instance_any_id));
    ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler, NULL, &instance_got_ip));
    wifi_config_t wifi_config = {
        .sta = {
            .ssid = WIFI_SSID,
            .password = WIFI_PASS,
            .threshold.authmode = WIFI_AUTH_WPA2_PSK,
        },
    };
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
    ESP_ERROR_CHECK(esp_wifi_start());
    ESP_LOGI("wifi", "STA 模式启动，正在连接...");
}

别忘了在 app_main() 里初始化 NVS 并调用 wifi_init_sta()：

void app_main(void) {
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NEW_VERSION_DETECTED) {
        nvs_flash_erase();
        nvs_flash_init();
    }
    wifi_init_sta();
}

编译、烧录后，打开串口监视（idf.py monitor，默认波特率 115200），应该能看到获取 IP 的日志。

接入 Home Assistant：模拟 ESPHome 的自动发现

自己搭 MQTT 服务器然后写一套发现逻辑当然可以，但走 ESPHome 的协议兼容模式更快——Home Assistant 能零配置发现设备。

首先在 menuconfig 里启用 mDNS 和 MQTT 客户端支持（Component config → LWIP → mDNS support；Component config → MQTT → Enable MQTT client）。

拿到 IP 后，发一条自发现消息到 homeassistant/light/esp32_led/config：

#include "mqtt_client.h"

static esp_mqtt_client_handle_t client;

static void mqtt_publish_discovery() {
    const char* topic = "homeassistant/light/esp32_led/config";
    const char* payload = R"({ "name": "ESP32 板载灯", "cmd_topic": "light/esp32_led/set", "stat_topic": "light/esp32_led/state" })";
    esp_mqtt_client_publish(client, topic, payload, 0, 1, true);
}

Home Assistant 收到这条消息后会立即创建一个灯光实体。接着订阅 light/esp32_led/set 主题，收到 ON 或 OFF 时控制 GPIO，并反馈状态：

static void mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data) {
    esp_mqtt_event_handle_t event = event_data;
    if (strcmp(event->topic, "light/esp32_led/set") == 0) {
        if (strncmp(event->data, "ON", event->data_len) == 0) {
            gpio_set_level(LED_GPIO, 1);
            esp_mqtt_client_publish(client, "light/esp32_led/state", "ON", 0, 1, 0);
        } else {
            gpio_set_level(LED_GPIO, 0);
            esp_mqtt_client_publish(client, "light/esp32_led/state", "OFF", 0, 1, 0);
        }
    }
}

现在打开 Home Assistant 的手机 APP，就能直接控制板载灯了。

踩坑记录：几点经验

下面是我在实际项目中碰到的几个高频问题，提前知道能省很多时间。

• 烧录超时 (Timed out waiting for packet header)：确认进入了下载模式；有些 USB 线或端口供电不稳，换根线或者换后置 USB 口试试。
• Invalid head of packet (0x00)：电源问题居多，用外部 5V 供电，别完全依赖电脑 USB。
• 编译找不到 esp_wifi.h：环境变量没生效，运行 . ./export.sh 再试。
• 日志全是乱码：波特率设成 115200，日志默认就是这个速率。
• Wi-Fi 连不上：中文 SSID 或特殊字符容易出问题，先用纯英文测试；核对密码大小写。
• OTA 升级失败：分区表里没有 OTA 分区，用 idf.py partition-table 查看当前布局。

还有一个需要特别注意的地方：Flash 加密。如果你在 menuconfig 中开启了 Security features → Enable flash encryption on boot，第一次烧录后 Flash 就锁定了，后续所有固件必须签名，否则芯片拒绝启动。调试阶段强烈建议关掉它。

从点灯到连网再到接入 Home Assistant，你走完的是一条从'能跑'到'能用'的必经之路。后面还会遇到低功耗设计、安全固件、OAT 升级、弱网重连、大量设备管理等更深入的问题，但这些的根基，正是今天你对固件烧录、分区表和联网机制的理解。