ESP32 实战教程：做一个手机网页控制的双轴舵机云台
本文按“先跑通、再测量、最后工程化”的顺序整理。不同开发板、模块批次和库版本可能存在差异，请以手中硬件的丝印、数据手册与实际串口日志为准。
一、为什么值得做
双轴云台是一个很适合把网页、实时通信和机械控制揉在一起的小项目。手机拖动滑块，ESP32 收到目标角度，两个舵机分别控制水平和俯仰。看起来只是两个角度，实际却会遇到电源压降、机械卡死、网络命令过密和舵机突然跳动。把这些问题处理好，项目才不会一激动就把摄像头甩向墙角。
这次不追求把所有功能一次堆满。先完成一个最小闭环：硬件能初始化、原始数据有变化、异常时能明确报错；随后再加入标定、滤波和状态机；最后才连接网页、MQTT 或本地存储。这个顺序看起来慢一点，实际会少掉很多“到底是线错了、库错了，还是页面错了”的集体猜谜。
二、硬件清单与接线重点
准备 ESP32、两个 SG90 或同类舵机、双轴支架和独立 5 V 电源。舵机电流不能从 ESP32 的 3.3 V 引脚获取，电源容量应考虑两个舵机同时启动的峰值；信号地与 ESP32 共地。安装前先让舵机回到中位，再固定舵臂，避免软件 90 度对应机械结构的极限位置。
第一次接线建议使用短线，在断电状态下逐根核对，并记录开发板型号、GPIO 编号、模块供电电压和接口地址。不要只写“接到 SDA”，因为换一块板后默认 SDA 可能不同。电机、舵机、风扇和继电器等负载应使用合适的独立电源，GPIO 只负责信号，不能兼职当小型发电站。
三、工作原理
常见模拟舵机通过约 50 Hz 的控制脉冲确定目标位置。网页发送的是目标角度，控制层先裁剪到安全范围，再按固定速度逐步逼近，PWM 层最后把角度换成脉宽。分层之后，网页刷新、机械限位和舵机输出不会互相纠缠。网络断开时可以保持当前位置或缓慢回到预设位，具体策略应在项目开始前明确。
把系统分成五层会更容易排错：电气连接、驱动通信、原始数据、业务换算、显示与联网。每层都留一个可观察点，例如电源电压、初始化返回值、原始帧、换算结果和页面状态。上层失败时先确认下层证据，不要页面上没有数字就立刻换三套库。
四、第一次实验与标定
不要默认两个舵机都能安全转到 0～180 度。先拆下负载，小步测试最小与最大脉宽，再装回支架观察是否碰撞。记录每个轴的安全角度范围、中位偏移和方向。水平轴左右颠倒可以在映射层反向，不必把代码里所有加减号翻个遍。
标定数据应与设备配置一起保存，并记录时间、参考物、环境和固件版本。更换模块、改变机械结构或升级算法后应重新验证。只记一个最终系数而不记原始数据，下一次发现偏差时很难判断是传感器老化、结构变化，还是当初计算时手滑。
五、最小可运行代码
下面的代码用于验证关键链路。安装对应库后，根据自己的开发板修改引脚、地址和参数：
#include <ESP32Servo.h>
Servo panServo, tiltServo;
float panNow = 90, tiltNow = 90;
float panTarget = 90, tiltTarget = 90;
void setup() {
panServo.attach(18, 500, 2400);
tiltServo.attach(19, 500, 2400);
}
void loop() {
panTarget = constrain(panTarget, 15, 165);
tiltTarget = constrain(tiltTarget, 25, 145);
panNow += constrain(panTarget - panNow, -1.0f, 1.0f);
tiltNow += constrain(tiltTarget - tiltNow, -1.0f, 1.0f);
panServo.write((int)panNow);
tiltServo.write((int)tiltNow);
delay(20);
}
示例故意保留串口输出，因为学习阶段最重要的是能看到系统正在做什么。代码跑通后再逐步拆分模块，不能因为最终产品没有串口窗口，就在开发阶段也把所有线索关掉。
六、数据处理与状态设计
网页端每 50～100 毫秒发送一次最新目标即可，不需要把触摸移动产生的每个像素都排队送过去。消息可以包含序号、pan、tilt 和模式，ESP32 只执行最新序号。设备向页面回传当前角度、目标角度、在线状态和限位告警，用户才能知道指令是否真正生效。
建议为设备统一设计四种状态：INIT 表示初始化，RUNNING 表示数据有效，DEGRADED 表示部分功能仍可用，ERROR 表示需要人工处理。每次状态变化记录原因和时间。错误恢复要有间隔，不能每个循环都重新初始化外设，否则日志会被刷满，设备也只是在高频重复同一个错误。
七、常见问题与排错顺序
舵机动作时 ESP32 重启，十有八九先查电源和共地。机械抖动可能来自齿轮间隙、目标值频繁变化或 PWM 范围不合适。网页失控时要设置命令超时，不能让旧连接残留的消息继续操纵设备。所有角度都必须在设备端再次限幅，不能相信浏览器一定听话。
排错时按以下顺序进行：先测供电和地线，再确认引脚与接口参数；然后只运行最小示例，打印原始数据；最后才恢复网页和自动控制。每次只改一个变量，并保留失败时的原始输出。最怕的是接线、库版本和业务代码同时修改，最终虽然偶然成功，却不知道是哪一步真正起了作用。
八、从演示变成长期运行设备
把网页控制设为局域网访问并增加口令，远程开放时使用可信网络入口。控制任务保持固定周期，网络任务只更新目标值；两者之间使用队列或受保护的共享状态。带摄像头时要限制帧率与分辨率，避免视频流把控制消息挤在门外。
程序结构上，可以把驱动、数据模型、业务状态机、网络和存储拆开。采样任务只负责产生带时间戳的有效数据，网页负责读取快照，日志任务负责批量落盘。任何网络故障都不应阻止本地采样，任何页面刷新也不应改变控制周期。配置保存在 NVS 时加入默认值、范围检查和版本迁移。
九、建议完成的测试清单
- 冷启动、复位和断电重启后，设备能否进入明确状态；
- 外设拔掉、接错或返回异常值时，程序是否会卡死；
- 连续运行两小时，内存、温度、供电和日志是否稳定；
- 阈值附近反复变化时，输出是否存在抖动或频繁动作；
- 更换同型号模块后，原标定是否仍然适用；
- Wi-Fi 断开、网页关闭或存储满时，本地核心功能是否继续工作；
- 对涉及人体、机械运动和大电流的项目，保护措施是否独立于软件存在。
建议建立实验表，至少记录原始值、处理值、单位、采样周期、错误次数、供电方式和测试结论。遇到偶发问题时，再增加启动次数和运行时长。工程经验常常不是来自“成功一次”，而是来自知道失败出现在哪个边界。
十、还能怎么扩展
可接入 ESP32-CAM 做可视云台，增加预置位、巡航、目标跟随和红外补光。若负载较重，应换用金属齿舵机或专用云台，并重新评估供电、结构强度和运动速度，而不是指望小舵机靠意志力升级。
扩展功能时仍然遵循一次增加一层的原则。先证明新模块独立工作，再接入现有状态机；先保存原始值，再绘制漂亮曲线。这样教程不仅能展示结果，也能给读者留下一条可以照着走的排错路线。
十一、总结
本项目的重点不是某一行库函数，而是把硬件、数据、状态和异常组合成一个可解释的小系统。能读取只是起点，能标定、能发现错误、能恢复、能留下日志，才算真正完成。实际制作后，建议继续补充接线照片、串口截图和一次真实失败记录，这些往往比“运行成功”四个字更有参考价值。
参考资料
打赏
如果这篇学习记录对你有帮助，欢迎扫码支持后续整理。
打赏支持：王庆岩
浙公网安备 33010602011771号