企业官网建设流程全解析

1. ESP32 多外设联调时 Key 分散管理的真实痛点

做 ESP32 项目的人大多经历过这样一个阶段：PWM 调光跑通了，I2C 驱动 xl9555 扩展 IO 也跑通了，WiFi 远程下发指令也跑通了，但把三个示例拼到一个工程里之后，配置文件开始失控。每个示例里都有一份自己的 endpoint、自己的鉴权字段、自己的模型 ID，改一处忘一处，串口日志里就开始出现 401、连接超时、返回体解析失败。

我这次要做的，是把 PWM 呼吸灯、I2C 读写 xl9555、WiFi 远程控制这三条链路，统一收敛到一套 Key 和一套 endpoint 上。核心思路很简单：外设驱动层保持不动，把「远程指令解析」这一层抽出来，所有需要调用大模型或云端接口的地方，都走同一个 Base URL、同一个 API Key、同一个 Model ID。这样你在调 PWM 占空比的时候，不会因为另一个示例里的 Key 过期而整个工程编译通过但运行报错。

适合谁看：已经能点亮 LED、能跑通 I2C 扫描、但还没把多个示例整合成一个可维护工程的 ESP32 入门到中级开发者。你需要有 ESP-IDF 环境，知道idf.py build flash monitor怎么用，知道menuconfig在哪里。

这篇文章不会教你从零装工具链，而是聚焦在「整合」这件事上。我会给出可复制的配置片段、串口日志验证步骤，以及当 401 或reading choices报错出现时，怎么一步步定位到是 Key 的问题还是外设初始化顺序的问题。

先说结论性的操作路径：把 xl9555 的 I2C 初始化、PWM 的 LEDC 初始化、WiFi 的 STA 连接这三块分别封装成独立函数，然后在主任务里按「I2C → PWM → WiFi → 远程指令循环」的顺序调用。远程指令循环里，所有需要鉴权的请求都从一个统一的配置结构体里取字段。这个结构体的值，来自你在 TaoToken 控制台创建的一份 Key。

2. TaoToken 前置准备：一份 Key 覆盖 PWM、I2C 与 WiFi 控制链路

在动手改代码之前，先把「一份 Key」这件事落地。TaoToken 的定位是统一模型接入层，你不需要为每个示例单独申请不同的 Key，也不需要把 endpoint 写死在每个.c文件里。

你需要做三件事：

第一，拿到 API Key。访问https://taotoken.net/api-keys，创建一个 Key。这个 Key 就是你后面所有请求里Authorization: Bearer <你的Key>的那一串。注意，创建之后只显示一次，复制到安全的地方。

第二，确认 Base URL。所有请求的根地址是https://taotoken.net/api。注意这里不要加 UTM 参数，API 调用就是纯地址。你在代码里配置的时候，写成https://taotoken.net/api即可，后面拼具体的路径。

第三，确认 Model ID。如果你只是做本地外设控制，远程指令解析可以用一个轻量模型；如果你要让模型根据自然语言生成 PWM 占空比或 xl9555 的 IO 配置，那就选一个指令跟随能力好的模型。Model ID 在模型列表里能看到，复制下来。

这三样东西——Base URL、API Key、Model ID——就是「三件套」。后面无论你是用 Cline、Codex 还是自己写的 HTTP 客户端，都是填这三个字段。

为什么强调「统一」？因为 ESP32 工程里最容易出问题的地方，就是不同示例用了不同的鉴权方式。比如 PWM 示例里可能用的是某个平台的 token，I2C 示例里用的是另一个平台的 key，WiFi 示例里又硬编码了一个 endpoint。整合的时候，你把这三处都改成从同一个app_config.h里读取，问题就收敛了。

具体到文件组织，我建议在工程根目录下建一个main/app_config.h，内容如下：

#ifndef APP_CONFIG_H #define APP_CONFIG_H #define TAOTOKEN_BASE_URL "https://taotoken.net/api" #define TAOTOKEN_API_KEY "sk-你的实际Key" #define TAOTOKEN_MODEL_ID "你的ModelID" #define WIFI_SSID "你的2.4G热点" #define WIFI_PASSWORD "你的密码" #define XL9555_I2C_SCL GPIO_NUM_10 #define XL9555_I2C_SDA GPIO_NUM_11 #define XL9555_INT_IO GPIO_NUM_17 #define PWM_LED_GPIO GPIO_NUM_15 #define PWM_FREQ_HZ 5000 #define PWM_DUTY_RES LEDC_TIMER_12_BIT #endif

这个头文件里，TaoToken 的三件套和硬件引脚定义放在一起。这样你在改 Key 的时候，只改这一处；在改引脚的时候，也只改这一处。串口日志里如果出现 401，你第一反应就是检查这个文件里的TAOTOKEN_API_KEY是不是复制错了。

注意：不要把真实 Key 提交到公开仓库。本地开发可以先用这个方式，等要分享代码的时候，把 Key 换成从 NVS 读取或者用编译宏传入。

3. 可复制配置：PWM、I2C、xl9555 与 WiFi 的 settings 片段

这一节给出可以直接粘贴的配置片段。你不需要一次全用，但建议按顺序来：先让 PWM 单独跑起来，再加 I2C，再加 xl9555，最后加 WiFi 和远程指令。

3.1 PWM 调光配置片段

PWM 部分用 LEDC 外设。duty_res最大可以设到 14 位，但 12 位（4095）对调光来说已经足够平滑。呼吸灯的本质是定时器周期性改变占空比。

#include "driver/ledc.h" void pwm_init(void) { ledc_timer_config_t timer_cfg = { .speed_mode = LEDC_LOW_SPEED_MODE, .duty_resolution = PWM_DUTY_RES, .timer_num = LEDC_TIMER_0, .freq_hz = PWM_FREQ_HZ, .clk_cfg = LEDC_AUTO_CLK, }; ledc_timer_config(&timer_cfg); ledc_channel_config_t ch_cfg = { .gpio_num = PWM_LED_GPIO, .speed_mode = LEDC_LOW_SPEED_MODE, .channel = LEDC_CHANNEL_0, .timer_sel = LEDC_TIMER_0, .duty = 0, .hpoint = 0, }; ledc_channel_config(&ch_cfg); ledc_fade_func_install(0); } void pwm_set_duty_percent(int percent) { if (percent < 0) percent = 0; if (percent > 100) percent = 100; uint32_t duty = (uint32_t)(percent * 4095 / 100); ledc_set_duty_and_update(LEDC_LOW_SPEED_MODE, LEDC_CHANNEL_0, duty, 0); }

这里ipoint的概念在 LEDC 里对应的是hpoint + duty，但实际调光你只需要关心duty。ledc_set_duty_and_update会立即生效，配合ledc_fade_func_install可以做渐变。

3.2 I2C 与 xl9555 配置片段

I2C 用新版driver/i2c_master.h。xl9555 的地址通常是0x20，具体看你的模块。初始化流程是：先建 I2C 总线，再建设备句柄，然后读写。

#include "driver/i2c_master.h" #include "xl9555.h" static i2c_master_bus_handle_t i2c_bus_handle; static i2c_master_dev_handle_t xl9555_dev_handle; void i2c_xl9555_init(void) { i2c_master_bus_config_t bus_cfg = { .i2c_port = I2C_NUM_0, .sda_io_num = XL9555_I2C_SDA, .scl_io_num = XL9555_I2C_SCL, .clk_source = I2C_CLK_SRC_DEFAULT, .glitch_ignore_cnt = 7, .flags.enable_internal_pullup = true, }; i2c_new_master_bus(&bus_cfg, &i2c_bus_handle); i2c_device_config_t dev_cfg = { .dev_addr_length = I2C_ADDR_BIT_LEN_7, .device_address = 0x20, .scl_speed_hz = 100000, }; i2c_master_bus_add_device(i2c_bus_handle, &dev_cfg, &xl9555_dev_handle); }

xl9555 的写函数：先写寄存器地址，再写低八位和高八位。读函数：先写寄存器地址，然后读数据。

esp_err_t xl9555_write_word(uint8_t reg, uint16_t value) { uint8_t buf[3] = { reg, value & 0xFF, (value >> 8) & 0xFF }; return i2c_master_transmit(xl9555_dev_handle, buf, 3, 100); } esp_err_t xl9555_read_word(uint8_t reg, uint16_t *value) { uint8_t data[2]; esp_err_t ret = i2c_master_transmit_receive( xl9555_dev_handle, &reg, 1, data, 2, 100); if (ret == ESP_OK) { *value = data[0] | (data[1] << 8); } return ret; }

3.3 WiFi STA 配置片段

WiFi 只支持 2.4G 频段。初始化顺序：esp_netif_init→esp_event_loop_create_default→esp_netif_create_default_wifi_sta→esp_wifi_init→ 注册事件 →esp_wifi_set_mode→esp_wifi_start。

#include "esp_wifi.h" #include "esp_event.h" #include "esp_netif.h" static EventGroupHandle_t wifi_event_group; #define WIFI_CONNECTED_BIT BIT0 static void wifi_event_handler(void *arg, esp_event_base_t base, int32_t id, void *data) { if (base == WIFI_EVENT && id == WIFI_EVENT_STA_START) { esp_wifi_connect(); } else if (base == WIFI_EVENT && id == WIFI_EVENT_STA_DISCONNECTED) { esp_wifi_connect(); } else if (base == IP_EVENT && id == IP_EVENT_STA_GOT_IP) { xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT); } } void wifi_init_sta(void) { 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_ERROR_CHECK(esp_event_handler_register( WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL)); ESP_ERROR_CHECK(esp_event_handler_register( IP_EVENT, IP_EVENT_STA_GOT_IP, &wifi_event_handler, NULL)); wifi_config_t wifi_cfg = { .sta = { .ssid = WIFI_SSID, .password = WIFI_PASSWORD, .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_cfg)); ESP_ERROR_CHECK(esp_wifi_start()); }

3.4 远程指令解析的 HTTP 配置片段

这是把三件套用起来的地方。当 WiFi 连上之后，你可以从远程下发指令，比如「把亮度调到 60%」或「读取 xl9555 的 IO0_0 电平」。解析可以用模型来做，也可以自己写规则。如果用模型，请求体里带上 Base URL、Key、Model ID。

#include "esp_http_client.h" esp_err_t call_taotoken_model(const char *prompt, char *out, size_t out_len) { esp_http_client_config_t cfg = { .url = TAOTOKEN_BASE_URL "/v1/chat/completions", .method = HTTP_METHOD_POST, .timeout_ms = 15000, }; esp_http_client_handle_t client = esp_http_client_init(&cfg); char auth[128]; snprintf(auth, sizeof(auth), "Bearer %s", TAOTOKEN_API_KEY); esp_http_client_set_header(client, "Authorization", auth); esp_http_client_set_header(client, "Content-Type", "application/json"); char body[512]; snprintf(body, sizeof(body), "{\"model\":\"%s\",\"messages\":[{\"role\":\"user\",\"content\":\"%s\"}]}", TAOTOKEN_MODEL_ID, prompt); esp_http_client_set_post_field(client, body, strlen(body)); esp_err_t err = esp_http_client_perform(client); if (err == ESP_OK) { int len = esp_http_client_read_response(client, out, out_len - 1); if (len > 0) out[len] = '\0'; } esp_http_client_cleanup(client); return err; }

注意：实际生产里不要把 prompt 直接拼进 JSON，要做转义。这里为了演示可读性简化了。

4. 验证请求与串口日志：从本地外设到远程控制的闭环

配置写完之后，怎么确认真的跑通了？不要一次性把所有代码都烧进去，按下面的顺序分步验证。

第一步，只烧 PWM。在app_main里调用pwm_init()，然后循环pwm_set_duty_percent从 0 到 100 再回 0。串口应该看到 LED 呼吸。如果 LED 不亮，先检查PWM_LED_GPIO是不是你板子上实际的 LED 引脚，再检查duty_res和freq是否冲突。

第二步，加 I2C 和 xl9555。调用i2c_xl9555_init()，然后读一次xl9555_read_word(0x00, &val)。串口打印xl9555 input: 0x%04X。如果返回ESP_ERR_TIMEOUT，大概率是 SDA/SCL 接反或者上拉没使能。我试过在bus_cfg里把enable_internal_pullup设为 true，能解决大部分模块自带无上拉的问题。

第三步，加 WiFi。调用wifi_init_sta()，然后xEventGroupWaitBits等WIFI_CONNECTED_BIT。串口应该出现got ip: 192.168.x.x。如果一直重连，检查 SSID 是不是 5G 的，ESP32 只认 2.4G。

第四步，加远程指令。WiFi 连上后，调用call_taotoken_model("把亮度设为60", resp, sizeof(resp))。串口打印返回的 JSON。如果返回 401，说明 Key 不对；如果返回reading choices之类的解析错误，说明返回体结构和你的解析代码不匹配。

一个完整的串口日志应该长这样：

I (1234) PWM: pwm init done I (1240) I2C: xl9555 init done, input=0xFFFF I (2000) WIFI: got ip: 192.168.1.100 I (2100) HTTP: status=200 I (2150) HTTP: resp={"choices":[{"message":{"content":"亮度已设为60%"}}]} I (2200) PWM: duty set to 60%

看到最后一行duty set to 60%，闭环就通了。从远程下发自然语言，到模型解析出 60，再到 PWM 实际改变占空比，整条链路用的是同一份 Key。

如果你想让模型直接输出 xl9555 的寄存器操作，可以在 prompt 里约定格式，比如「返回 JSON：{"reg":"0x02","value":"0x00"}」，然后在 ESP32 侧解析这个 JSON 并调用xl9555_write_word。这样远程控制扩展 IO 也不需要额外鉴权。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来。你在整合过程中大概率会遇到下面几个。

401 Unauthorized。最常见。原因：TAOTOKEN_API_KEY复制时多了空格，或者 Key 已经失效。排查：把 Key 打印出来看长度，正常是sk-开头的一长串。注意不要在日志里完整打印 Key，打印前 8 位和后 4 位即可。如果确认 Key 没问题，检查Authorization头是不是写成了Bearer<Key>少了空格。

local proxy failed。这个报错通常出现在你本地有代理设置，但 ESP32 请求走的是直连。排查：确认你的开发环境没有强制 HTTP 代理，esp_http_client_config_t里没有设置proxy。如果你在 PC 上调试，先curl一下https://taotoken.net/api看通不通。

reading choices 失败。这个报错说明 HTTP 请求成功了，但返回体里没有choices字段，或者你的解析代码在找choices时越界。排查：先把原始返回体完整打印出来，看结构。如果是错误响应，里面会有error字段而不是choices。常见原因是 Model ID 写错了，或者请求体里的model字段和实际可用模型不匹配。

OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类工具，它们可能走 OAuth 流程。在 ESP32 上你不需要 OAuth，直接用 API Key 即可。如果你在 PC 端用 Cline 或 CC Switch 配置，注意 Base URL 填https://taotoken.net/api，Key 填 API Key，Model ID 填你选的模型。三件套缺一不可。

xl9555 读回全 0 或全 1。这不是 Key 的问题，是 I2C 的问题。检查设备地址：有的模块是 0x20，有的是 0x21。用i2c_master_probe扫一下总线。另外，xl9555 的输入寄存器在电平变化后需要重新读，如果你用了中断，记得在中断回调里置位事件组，任务里再读。

PWM 无输出。检查ledc_channel_config里的gpio_num是不是被 xl9555 占用了。如果你把 LED 接在 xl9555 的扩展 IO 上，那 PWM 应该由 xl9555 输出，而不是 ESP32 的 LEDC。这两条链路不要混。

WiFi 连上但 HTTP 超时。检查 DNS。ESP32 默认用 DHCP 拿到的 DNS，如果路由器 DNS 有问题，可以手动设esp_netif_set_dns_info。另外，timeout_ms设 15000 比较稳妥，模型响应有时会超过 5 秒。

6. 统一 Key 之后的工程维护与 CTA

把三件套收敛到app_config.h之后，工程维护会轻松很多。你改 Key 只改一处，改引脚只改一处，改模型只改一处。后续如果要加新的外设，比如 I2S 麦克风或者 OTA，也只需要在这个文件里加配置，然后在主任务里加初始化调用。

如果你在排障过程中需要确认 API 的详细参数，可以看接入文档：https://taotoken.net/doc。如果你只是想先验证模型能不能正常返回，可以用模型对话页面：https://taotoken.net/chat。如果你打算长期做 ESP32 加 Agent 的项目，比如让模型根据传感器数据自动决策，那 Coding Plan 会更合适：https://taotoken.net/coding-plan。

最后给一个实用技巧：在app_main里加一个版本打印，把TAOTOKEN_BASE_URL和TAOTOKEN_MODEL_ID打出来（Key 只打后四位）。这样每次烧录后，串口第一屏就能确认当前工程用的是哪套配置，避免烧错固件还以为是代码问题。