一套 AI 视觉 + 手机遥控 + 直驱运动控制 的智能小车工程：ESP32-S3-CAM 采集画面，板载直调云端多模态模型解析目标并生成控制指令，经软件 I2C 直接驱动哪吒扩展板的电机与舵机，手机 App 负责图传、操控与 AI 目标下发。
手机 App ──BLE 配网 / WiFi 图传+指令──▶ 视觉大脑板(ESP32-S3) ──软件 I2C──▶ 哪吒扩展板 ──▶ 电机/舵机/灯
◀──────────── WS 状态 / exec_status 上行 ────────────────┘
当前为开发进行中版本：BLE 配网、WS 指令/状态、UDP 图传、软件 I2C 直驱（四轮电机 / 四个舵机 / 三路灯光）均已接通可跑；板载 DIRECT AI（
ai_goal）已实现，任务级闭环真机联调中。
⚠️ 本项目已取消独立的 STM32 执行板（原Stm32-Executor/，因硬件问题裁撤），改由视觉板直驱。旧的 UART 帧协议与双板架构只存在于 git 历史。
- 📷 实时图传：WiFi UDP 推流 JPEG 帧（低延迟、分片自愈），App 内查看画面并框选/标注目标。
- 🎮 遥控操控：虚拟摇杆 + 指令面板，小车前进/后退/转向（可切换原地旋转式转向）、机械臂升降/移爪/夹爪、三路灯光开关、一键回正。
- 🎯 指定点移动 / 插话：
/move to <x> <y> [global]（词表goto）让板子自行导航到地面坐标；AI 任务进行中输入非空文本即为插话（ai_chat），补充要求而不打断闭环。 - 🧠 板载 AI 视觉控制：手机下发文字/区域目标 → 板子直调云端多模态模型 → 指令 → 直驱落地（任务级迭代闭环，
ai_goal/ai_oneshot）。板端维护画面标定（单应）+ 物体空间记忆 + 车姿态累积，并按需带上上一帧做运动对比。 - 🧭 标定网格：图传可叠加标定网格（
/grid），配合板端单应标定读屏幕 (u,v) 与实测地面距离取标定点。 - 🦾 机械臂二连杆 IK：给末端目标位姿（轴前方 cm + 地面以上 cm），板载反解并联动左右两舵机。
- 📶 BLE 一次性配网：App 扫描广播名
VisionS3后写入 WiFi 账号，板子 NVS 存储、在线换网生效（不重启）。 - 🧩 哪吒协议直驱：绕过任何执行板，软件 I2C 直接下发舵机 PWM / 电机 PWM / 灯光字节。
整体角色与通信链路如下（详见各子工程 CLAUDE.md）：
┌────────────────────┐ ① BLE 配网 / 兜底控制（GATT，广播名 VisionS3）
│ 手机 App │ ◀───────────────────────────────────────┐
│ Mobile-RemoteCtrl │ ② WiFi WebSocket（端口 81）： │
│ (Godot / Android) │ 指令 JSON / 状态 / 消息（文本） │
│ │ ③ WiFi UDP：图传 JPEG 分片（二进制） │
└────────────────────┘ ◀───────────────────────────────────────▶│
▼
┌──────────────────────────┐ ┌──────────────────────────────────────┐
│ 云端多模态 AI │ ④ai_goal │ 视觉/控制大脑板 Stm32-Vision │
│ (DeepSeek 等，可配) │ ────────▶│ ESP32-S3-CAM(N16R8) + OV3660 │
│ │ │ 抓帧 · 图传 · 配网 · 词表分发 │
│ │ │ 板载 AI 闭环 · exec 直驱执行层 │
└──────────────────────────┘ └────────────────┬─────────────────────┘
⑤ 软件 I2C（SCL=GPIO47 / SDA=GPIO14）
从机 0x80，无 MCU 中转
▼
┌──────────────────────────────────────────┐
│ 哪吒（NeZha）扩展板 │
│ 4 路电机 PWM · 4 路舵机 PWM · 灯带 │
│ → 4×N20 四轮 · 4×MG90S(转向+机械臂) │
└──────────────────────────────────────────┘
| # | 链路 | 说明 |
|---|---|---|
| ① | BLE | 手机 → 大脑板：一次性配网（WiFi SSID/密码、AI 接口参数）+ 兜底控制。连接后让出 2.4G 射频，断线自动恢复 |
| ② | WiFi WebSocket | 大脑板 ⇄ 手机：指令 JSON 下行 + status/ai_result/exec_status/log（调试）/state（查询回包）上行 |
| ③ | WiFi UDP | 大脑板 → 手机：JPEG 图传分片（每数据报 14B 大端头 + 载荷） |
| ④ | 云端 AI | 大脑板 ⇄ 模型：DIRECT 直调（板子自己上传画面、解析指令、执行闭环） |
| ⑤ | 软件 I2C | 大脑板 → 哪吒板：舵机/电机/灯光命令，本板即执行器 |
词表 JSON（
CommandProto）只由手机 App 持有；「词表 → 哪吒 I2C 命令」的翻译在大脑板command+direct_exec模块。
| 仓库目录 | 角色 | 语言 / 工具链 | 说明 |
|---|---|---|---|
Stm32-Vision/ |
视觉大脑板 兼执行器 | C++ · Arduino IDE / arduino-cli（esp32 core 3.3.x） | 摄像头抓帧、WS/UDP 图传、BLE 配网、词表分发、板载 AI、软件 I2C 直驱 |
Mobile-RemoteCtrl/ |
手机遥控 App | GDScript · Godot 4.7.1 mono（Android） | 三通道通信、虚拟摇杆、图传显示、图片标注、BLE 配网界面、聊天指令区 |
⚠️ 大脑板依赖自编译内核库（esp32 core 3.3.11，用 esp32-arduino-lib-builder 在 WSL 自编译后覆盖到 Arduino15）： ① mbedTLS SSL 收发缓冲设 8192B（CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN/CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN），否则 AI 直连 TLS 握手因内部堆碎片化失败（-17040/-32512）； ② lwIP TCP 缓冲上调（CONFIG_TCP_SND_BUF_DEFAULT=32768 /CONFIG_TCP_WND_DEFAULT=16384），否则 40KB 级请求体发送write()超时。
整车 = ESP32-S3-CAM 大脑板 + 淘宝现成的小车/机械臂套件（驱动板 + 骨架 + 电机 + 舵机 + 电池）。
| 分类 | 部件 | 选型 / 规格 | 数量 | 作用与接入 |
|---|---|---|---|---|
| 视觉计算 | 视觉大脑板 | ESP32-S3-CAM（N16R8）：ESP32-S3 + 16MB Flash + 8MB PSRAM | 1 | 抓帧/图传/配网/指令分发/板载 AI + 直驱执行器；camera.h 顶部 CAMERA_MODEL_ESP32S3_EYE |
| 视觉计算 | 摄像头 | OV3660（换装，非板载 OV2640） | 1 | 画面采集；默认倒置与镜像已在 camera.cpp init 回正（画面所见即真实方位） |
| 驱动 | 驱动板 | 哪吒（NeZha）扩展板，I2C 从机地址 0x80 |
1 | 4 路电机 PWM + 4 路舵机 PWM + 灯带；大脑板软件 I2C 直驱（SCL=GPIO47 / SDA=GPIO14） |
| 执行机构 | 直流减速电机 | N20 直流电机（四轮驱动，无编码器） | 4 | 哪吒板 Motor1–4；轮位 M1 左后 / M2 右后 / M3 右前 / M4 左前 |
| 执行机构 | 舵机 | MG90S 模拟舵机（180°，PWM 50..250） | 4 | 哪吒板 Servo1=转向；Servo2=移爪 / Servo3=夹爪 / Servo4=抬落（机械臂） |
| 结构 | 车轮 | 套件配套轮 | 4 | 装于四个 N20 电机 |
| 结构 | 车架 + 机械臂 | 套件骨架（小车底盘 + 3 自由度机械臂） | 1 套 | 承载上述部件 |
| 供电 | 电池组 | 12V / 1200mAh | 1 | 底盘动力与逻辑供电 |
| 连接 | 杜邦线 | 若干 | — | 哪吒板 ↔ 大脑板（I2C）、电机/舵机走线 |
| 紧固 | 螺丝螺帽 | 若干 | — | 结构装配 |
接线要点（大脑板 ↔ 哪吒扩展板）
| 信号 | 大脑板 GPIO | 哪吒板 |
|---|---|---|
| 软件 I2C SCL | GPIO47 | SCL |
| 软件 I2C SDA | GPIO14 | SDA |
| 电源 | 5V / GND | 5V / GND |
⚠️ 无编码器 ⇒ 无里程计：直驱固件不做定距/定角闭环，move的distance_cm与spin的angle_deg按实测标定表的时长近似到点自停（粗用，供微操/标定）；arm的dist_cm按「每 cm ≈ 固定拍数」近似。原执行板上的速度 PID、里程计、到位判定随执行板一并裁撤。
| 部件 | 值 |
|---|---|
| 转向 Servo1 | 150 正前 / 120 左死 / 180 右死 |
| 移爪 Servo2 | 中位 200，行程 120..250 |
| 夹爪 Servo3 | 夹紧 50 / 张开 140（中位即张开） |
| 抬落 Servo4 | 中位 180，行程 115..250 |
| 机械臂几何 | 二连杆 L1=L2=7.5cm，肩轴离地 9.5cm，可达半径 4..15cm |
| 灯光 | 前灯 / 氛围灯 / 尾灯（左右一起） |
① 视觉大脑板 ESP32-S3-CAM
② 小车 / 机械臂套件（驱动板 + 骨架 + 电机 + 舵机）
把整车/细节照片以对应文件名存入 docs/img/build/ 即替换占位。
整车正面（docs/img/build/car-front.png）
整车侧面（docs/img/build/car-side.png）
内部走线 / 板载布置（docs/img/build/car-internal.png）
动作演示抓取（docs/img/build/car-action.png）
App 界面（遥控 / 图传）（docs/img/build/app-screenshot.png）
固件内置的是默认出厂实测值；换镜头、移相机、换电机/舵机、改底盘后，以下几处手动校准需要重做。所有校准数据集中在 Stm32-Vision/Calibration.h（Calibration.cpp 提供机械臂散点接入），改完重新编译烧录即生效（数据只进 flash、不占运行内存），无需动其它源文件。
| 校准项 | 为什么需要手动校准 | 在哪改（Calibration.h） |
|---|---|---|
| 画面坐标 ↔ 实际坐标映射 | 屏幕归一化像素 (u,v) 与车头系地面厘米依靠实测标定点拟合单应；相机角度/高度或换镜头都会变，标定不准会让 AI 的像素观测失真 | kGroundCal：每行 {u, v, x右, y前}，≥4 点、尽量覆盖整个屏幕 |
| 机械臂移动 | 机械臂夹心目标位姿(x,h) ⇄ 移爪/抬落两舵机 PWM 是非线性映射，靠实测散点做 IDW 插值；舵机压力/装配都会影响，错位或末端对不准要重测 | kArmPts：每点 {移爪PWM, 抬落PWM, x车前, h离地}；连续动作步长与定距在 ARM_STEP_CM、ARM_CNT_PER_CM |
| 小车定距前进 | 电机无编码器，move distance_cm 只能按时长近似，需按油门实测车速与起停余量 |
MV_SPEED_X/Y、MV_COAST_X/Y（按油门插值表） |
| 小车定角原地转向 | 同理，spin angle_deg 按时长近似，需按转速实测毫秒/度 |
SPIN_MSDEG_X/Y、必要时调整 SPIN_MIN_SPEED |
🔧 校准提示
- 舵机限位/回中也在此文件：
STEER/REACH/GRIP/LIFT_*_CENTER/_LO/_HI，首次装机或换舵机后按实际行程复核。- 画面标定点：App 图传开
/grid叠加网格，读网格交点屏幕坐标 (u,v)，再用直尺/米测出对应地面 (x,y) 填入kGroundCal。- 机械臂标定点：把臂摆到若干到位姿，记录两个舵机 PWM 与实测夹心 (x 车前、h 离地) 填入
kArmPts。- 定距/定角：让车前进设定距离、原地旋转设定角度，实测实际位移/转角，按油门/转速填
MV_*/SPIN_MSDEG_*表。- 上表均有默认值可直接跑；仅当某处行为不对或硬件变更时才需重校。
- 烧录大脑板 → 上电后板子广播 BLE
VisionS3。 - App 配网：连接该广播，写入 WiFi 账号密码与 AI 接口参数（URL/Key/模型）。
- 连上 WiFi：App 经 WebSocket（端口 81）取得指令/状态通道，按需开启图传（UDP）。
- 遥控：摇杆驱车（可在「关于」页切换为原地旋转式转向）、按钮控机械臂/灯光；或在聊天区直接输入文字下发 AI 目标。
- 调试：
/log exec on看板端状态推送与执行日志、/log ai on看 AI 时序日志、/log all on转发板端全部串口输出（聊天区内容统一落盘user://logs/app.log）、/grid on叠加图传标定网格。
主要面向本人维护迭代的工程文档；各子目录由各自仓库独立演进，本仓库为统一收纳视图。