简介:本文面向想用摄像头或HMI屏做AI原型的开发者,按接口规划、模型选型、API调用和安全排查的顺序,讲清ESP32-S3如何完成拍照、编码、请求和显示。文中给出鉴权、证书校验、NTP时间同步、退避重试和图像上传的完整代码,读者可以直接修改套用,尽快跑通从拍照到返回结果的全流程。
原型阶段最耗时的往往不是业务逻辑,而是接线、供电、下载和联调。本文以乐鑫(Espressif)的 ESP32-S3 系列为例,说明如何把摄像头或HMI终端接入云端大模型。
芯片的核心数、架构、内存和外设参数,请以乐鑫官网(espressif.com)公开的 ESP32-S3 数据手册和技术参考手册为准。动手前先核对手册,再决定接线方式和程序结构。
示例代码基于以下版本编写:
升级 core 或库之前,先阅读对应版本的变更说明。若某个 API 名称发生变化,以新版本文档为准修改代码。
如果使用的是带摄像头的 ESP32-S3 开发板,摄像头引脚定义通常写在板子的 camera_pins.h 或原理图中。
摄像头和屏幕通常同时占用大量 GPIO。动手前先列一张表,写清每组接口的用途和冲突风险。表中引脚归属以具体开发板原理图为准。
| 接口 | 典型用途 | 规划要点 |
|---|---|---|
| SPI | 屏幕、SD 卡 | 与摄像头数据线分开,避免引脚重叠 |
| I2C | 触摸芯片、温湿度传感器 | 确认各器件地址不冲突 |
| UART | 外接模块、串口日志 | 若与 USB 日志共用,调试时注意占用 |
| GPIO / PWM | 按键、蜂鸣器、背光 | 背光可用 PWM 调光,减少瞬间电流 |
| 摄像头并口 | 图像数据、同步信号 | 逐一核对引脚映射和时钟配置 |
摄像头方案还要关注内存。分辨率越高,单帧 JPEG 越大。原型阶段可以先用 QVGA(320×240)或更低分辨率跑通流程,确认无误后再逐步提高。板载内存不够时,需要外接 PSRAM,或者降低帧率。
屏幕背光和电机启动瞬间电流较大,容易造成复位。建议为这些负载单独供电,并与开发板共地。
单 USB 接口同时负责供电、下载和串口日志。遇到无法下载、供电不足或日志乱码时,依次检查三处:USB 线是否支持数据传输,端口是否被其他程序占用,供电是否稳定。
选择模型前,先明确任务类型。图像识别需要多模态能力,文本问答关注上下文长度和响应速度,设备控制则需要指令理解和工具调用能力。高频而简单的判断可以交给小模型或本地规则,复杂任务再交给更强的模型。
比较候选模型时,统一使用下面几个口径:
下面是选型记录模板。表中数值需要按各平台实时文档填写,这里留空:
| 任务类型 | 模态 | 上下文长度 | 首字 / 整体延迟 | RPM / TPM | 计费方式 | 数据合规 |
|---|---|---|---|---|---|---|
| 图像识别 | 图像加文本 | 待填写 | 待实测 | 待填写 | 待填写 | 待填写 |
| 文本问答 | 文本 | 待填写 | 待实测 | 待填写 | 待填写 | 待填写 |
价格和限额变化较快,请以百度智能云词元所的实时文档为准。
完整流程分为六步:联网、采集、编码、请求、解析、显示。示例假设平台采用常见的对话接口格式,实际字段、接口地址和模型名称请以平台文档为准。
密钥和地址统一放在 secrets.h 中,并把该文件加入 .gitignore:
// secrets.h,不要提交到代码仓库#define WIFI_SSID "your-ssid"#define WIFI_PASSWORD "your-password"#define API_URL "https://api.example.com/v1/chat/completions" // 从平台接口文档复制#define API_KEY "your-api-key" // 从平台控制台生成#define MODEL_NAME "your-model-name" // 从平台模型列表复制// 平台域名对应的根证书(PEM 格式),从证书颁发机构或平台文档获取static const char* ROOT_CA = R"(-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----)";
HTTPS 证书有有效期。设备时间不对时,TLS 握手会失败,表现看起来像网络问题。因此 configTime 之后要等待时间真正生效,再发起请求:
bool syncTime() {configTime(0, 0, "pool.ntp.org");for (int i = 0; i < 20; i++) {if (time(nullptr) > 1700000000) { // 约为 2023 年 11 月之后,说明 NTP 已生效return true;}delay(500);}return false; // 超时后不要发起 HTTPS 请求,先排查网络和 NTP 服务器}
下面的代码完成鉴权、超时、状态码判断和退避重试。最多发起 4 次请求,即首次请求加 3 次重试,退避间隔依次为 1 秒、2 秒、4 秒,退避总等待为 7 秒。
#include <WiFi.h>#include <WiFiClientSecure.h>#include <HTTPClient.h>#include <ArduinoJson.h>#include "secrets.h"const int kMaxAttempts = 4;const uint32_t kBackoffMs[] = {1000, 2000, 4000};// 发送 POST 请求。返回 HTTP 状态码;网络或 TLS 错误时返回负数。int postJson(const String& body, String& resp) {WiFiClientSecure client;client.setCACert(ROOT_CA); // 校验服务端证书,不要使用 setInsecure()HTTPClient http;http.setTimeout(15000);if (!http.begin(client, API_URL)) {return -1;}http.addHeader("Content-Type", "application/json");http.addHeader("Authorization", String("Bearer ") + API_KEY);int code = http.POST(body);if (code > 0) {resp = http.getString();}http.end();return code;}// 429、5xx 和网络错误会重试,其余错误直接停止。String sendWithRetry(const String& body) {for (int attempt = 0; attempt < kMaxAttempts; attempt++) {String resp;int code = postJson(body, resp);if (code == 200) {JsonDocument doc;if (deserializeJson(doc, resp)) {Serial.println("JSON parse failed");return ""; // 解析失败通常说明接口格式变化,重试没有意义}return doc["choices"][0]["message"]["content"].as<String>();}bool retryable = (code < 0 || code == 429 || code >= 500);Serial.printf("attempt %d, HTTP %d\n", attempt + 1, code); // 只打印状态码if (!retryable || attempt == kMaxAttempts - 1) {return ""; // 401、403 等错误需要检查密钥和请求头}delay(kBackoffMs[attempt]);}return "";}String askCloudModel(const String& prompt) {JsonDocument req;req["model"] = MODEL_NAME;req["messages"][0]["role"] = "user";req["messages"][0]["content"] = prompt; // ArduinoJson 自动转义引号等字符String body;serializeJson(req, body);return sendWithRetry(body);}void setup() {Serial.begin(115200);WiFi.begin(WIFI_SSID, WIFI_PASSWORD);while (WiFi.status() != WL_CONNECTED) {delay(500);Serial.print(".");}Serial.println("\nWiFi connected");if (!syncTime()) {Serial.println("NTP sync failed");}}void loop() {if (WiFi.status() == WL_CONNECTED && time(nullptr) > 1700000000) {String answer = askCloudModel("请用一句话描述设备当前状态");if (answer.length() > 0) {Serial.println(answer);}}delay(10000);}
代码中有几处需要注意:
图像请求的流程是:拍照得到 JPEG 缓冲区,做 base64 编码,再放入请求体。多数平台要求以 data:image/jpeg;base64, 开头的数据 URL,具体格式以平台文档为准。
摄像头初始化如下。引脚字段需要从开发板的 camera_pins.h 中填入:
#include "esp_camera.h"#include "mbedtls/base64.h"#include "camera_pins.h" // 引脚定义,以开发板为准const size_t kMaxBodyBytes = 64 * 1024; // 平台请求体上限,以文档为准bool initCamera() {camera_config_t config = {};// pin_xclk、pin_d0 到 pin_d7、pin_vsync 等字段从 camera_pins.h 填入config.xclk_freq_hz = 20000000;config.pixel_format = PIXFORMAT_JPEG;config.frame_size = FRAMESIZE_QVGA; // 原型阶段先用 QVGAconfig.jpeg_quality = 12; // 数值越大压缩越狠,图像越小config.fb_count = 1;config.fb_location = CAMERA_FB_IN_PSRAM; // 没有 PSRAM 时改为 CAMERA_FB_IN_DRAMconfig.grab_mode = CAMERA_GRAB_LATEST;return esp_camera_init(&config) == ESP_OK;}
拍照、编码并发送的代码如下:
String askCloudModelWithImage(const String& prompt) {camera_fb_t* fb = esp_camera_fb_get();if (!fb || fb->format != PIXFORMAT_JPEG) {if (fb) esp_camera_fb_return(fb);Serial.println("capture failed");return "";}// base64 输出长度为 4 * ceil(n / 3),额外 1 字节留给结束符size_t b64Cap = 4 * ((fb->len + 2) / 3) + 1;uint8_t* b64 = (uint8_t*)ps_malloc(b64Cap);if (!b64) {esp_camera_fb_return(fb);Serial.println("out of memory");return "";}size_t b64Len = 0;int ret = mbedtls_base64_encode(b64, b64Cap, &b64Len, fb->buf, fb->len);esp_camera_fb_return(fb); // 编码完成后尽早归还帧缓冲if (ret != 0) {free(b64);return "";}// 提示词先用 ArduinoJson 转义,避免引号破坏 JSON 结构JsonDocument tmp;tmp.set(prompt);String quotedPrompt;serializeJson(tmp, quotedPrompt);String head = String("{\"model\":\"") + MODEL_NAME +"\",\"messages\":[{\"role\":\"user\",\"content\":[""{\"type\":\"text\",\"text\":" + quotedPrompt + "},""{\"type\":\"image_url\",\"image_url\":{\"url\":\"data:image/jpeg;base64,";const String tail = "\"}}]}]}";// base64 字符集不含需要转义的字符,可以直接拼接String body;body.reserve(head.length() + b64Len + tail.length());body += head;body.concat(reinterpret_cast<const char*>(b64), b64Len);body += tail;free(b64);if (body.length() > kMaxBodyBytes) {Serial.println("body too large, upload to object storage first");return ""; // 超限处理见下文}return sendWithRetry(body);}
这段代码有两点需要留意。第一,base64 会让数据体积增加约三分之一,加上请求头和提示词后,内存峰值接近三份数据。若内存紧张,可以降低分辨率或 jpeg_quality,或者改用 HTTP 流式发送。第二,若请求体超过平台上限,先把 JPEG 上传到对象存储(例如使用带时效的预签名 PUT 地址),再把返回的图片 URL 放入 image_url.url 字段。上传地址同样必须使用 HTTPS。
常见状态码的处理方式如下:
云端返回文本后,可以在屏幕上显示识别结果、状态标签或控制建议。展示逻辑建议按下面四种状态组织:
请求成功时回到正常状态。请求失败且存在缓存时进入缓存状态,缓存超时后进入过期状态。没有缓存且请求失败时直接进入错误状态。
原型阶段最容易忽视的是密钥和费用。建议做到以下几点:
按最小闭环的思路推进,每一项通过后再进入下一项:
按这个顺序推进,每一步出现的问题都容易定位,也能避免在硬件、网络和云端接口之间同时排查。