卡在哪一步，就从哪一步查起
把故障按烧录、供电、接线与舵机、配网与网络、API 与控制五个环节分开，每组一张表列出现象、原因、解法。参数、端口与错误码一并写进表里。
烧录环节
| 现象 |
原因 |
解法 |
| Linux 下端口不出现，或提示 Permission Denied |
当前用户没有串口设备权限 |
把用户加入 dialout 组：sudo usermod -a -G dialout $USER，并登出后重新登录才生效 |
| 点 Upload 上传失败 |
板子没进下载模式，或 USB 线只能供电不能传数据 |
上传时按住 BOOT 键，或换一根 USB 线；S3 板还要确认 USB CDC On Boot 设为 Enabled，这是复位后能找回端口的关键 |
| 工具里找不到端口 |
缺 USB 转串口驱动 |
按板型装驱动：CP210x 对应 Lolin S2 Mini，CH340 对应部分 ESP32 板；Windows 10/11 通常自带 |
供电环节
| 现象 |
原因 |
解法 |
| 上电后机器人不动 |
电源或舵机连接没接好 |
先复查电源与舵机连接；若是多路舵机同时启动拉低 VCC 的 brownout，在 Web 设置里调大 motorCurrentDelay
|
| 电池供电、做动作时整机崩溃 |
电池带载时瞬时压降过大 |
官方建议调高 motorCurrentDelay；进阶用户换 LiPo 电芯常能解决 |
供电与 PWM 相关的参数列在下表：
| 参数 |
官方值 |
说明 |
| PWM 定时器 |
ESP32PWM::allocateTimer(n)，占硬件定时器 0–3 |
50Hz；定时器数量有限，加外设挤占会带来网络异常 |
| 角度映射 |
0–180° 对应 732–2929μs |
在 servos[i].attach() 调用里设置 |
| 270° 舵机 |
官方给 833–2167μs |
用了更大行程的舵机需自行改映射，官方仅给出这组数值 |
motorCurrentDelay |
默认 20ms |
在相邻舵机脉冲间错峰，避免 VCC 跌落；可在 Web 设置里改 |
接线与舵机环节
| 现象 |
原因 |
解法 |
| 舵机反向、乱动、抽风 |
官方经验值：99% 是插错槽 |
先查这一路槽位与接线，别急着换件；棕线必须对准地轨一侧
|
| 整机朝向拿不准、分不清哪头是前 |
缺一个统一的方向记号 |
按官方记号对齐：Notch（缺口）= front 为前，USB port = back 为后
|
配网与网络环节
| 现象 |
原因 |
解法 |
| WiFi 列表里搜不到机器狗的热点 |
官方固件文档与固件源码给的热点名不一致 |
Sesame-Controller-BETA（固件文档）与 Sesame-Controller（源码 AP_SSID）两个名字都试一下；密码都是 12345678
|
| 连不上家庭 WiFi |
网络模式没开、凭据错，或连了 5GHz |
确认 ENABLE_NETWORK_MODE 为 true、NETWORK_SSID 与 NETWORK_PASS 正确；WiFi 必须是 2.4GHz（ESP32 不支持 5GHz）；看串口监视器的连网状态；必要时调大连接超时（官方排障段标注 currently 10 seconds / 20 attempts） |
| 打不开 sesame-robot.local |
系统缺 mDNS 支持，或路由器拦了 mDNS |
Windows 装 Bonjour，Linux 安装并启动 avahi-daemon，或直接用串口显示的 IP；部分路由器需检查 mDNS 设置 |
API 与控制环节
| 现象 |
原因 |
解法 |
| 发命令没反应、状态不更新 |
请求方法或请求头不对 |
确认是 POST /api/command 且带 Content-Type: application/json；用 GET 请求该端点会返回 405；先用一条简单 cURL 验证连通性，再看串口监视器的解析输出 |
以为能做到、官方却明确不支持
有些没反应的情况，根源是预期超出了官方给的能力边界。把下面几条对上号，按边界调整玩法范围即可。
| 期望 |
官方边界 |
结论 |
| 靠传感器自己看路、保持平衡 |
没有摄像头、雷达、IMU |
基础版本不带这些传感器 |
| 自主避障、建图导航 |
动作来自预编排序列，没有闭环控制，不做避障与 SLAM |
这类能力不在基础版本里 |
| 负重或长时间连续行走 |
MG90 舵机力矩有限 |
不能负载，也不适合长续航 |