1. RoboFi项目概述RoboFi 是一款基于 ESP32 的专用机器人主控板面向四轮差速驱动移动机器人设计集成了电机驱动、传感器采集、无线通信与实时控制能力于一体。其核心定位并非通用开发板而是“开箱即控”的嵌入式机器人控制单元——硬件层已固化关键外设拓扑软件层通过轻量级 C 库屏蔽底层寄存器操作使开发者聚焦于运动控制逻辑而非驱动适配。该板硬件架构围绕 ESP32-WROOM-32 模组构建主频 240 MHz 双核 Xtensa LX6 处理器内置 520 KB SRAM 与 4 MB Flash典型配置支持 Wi-Fi 802.11 b/g/n 和 Bluetooth 4.2 BR/EDR/BLE。区别于常规 ESP32 开发板RoboFi 板在 PCB 级完成以下关键集成四路 H 桥电机驱动采用双 TB6612FNG 芯片每路持续输出电流 1.2 A峰值 3.2 A支持 PWM 频率 1–20 kHz 可调具备过流保护与热关断功能五路模拟传感器接口提供 5 个独立 ADC 输入通道GPIO34/35/32/33/39均接入内部 12-bit SAR ADC参考电压默认为 VDDA3.3 V支持衰减配置0 dB / 6 dB / 11 dB / 12 dB以适配不同信号幅度编码器输入支持预留两组正交编码器接口A/B 相通过 GPIO16/17 与 GPIO18/19 引出可配置为脉冲计数或方向判别模式扩展总线接口包含标准 I²CGPIO21/22、SPIGPIO12–15、UART0GPIO1/3与 UART2GPIO16/17兼容常见传感器如 MPU6050、VL53L0X、OLED 显示屏及 SD 卡模块供电管理支持 6–12 V DC 输入经 MP1584EN 降压稳压至 5 V 供电机驱动再经 AMS1117-3.3 输出 3.3 V 给 ESP32 核心与数字外设具备反接保护与输入过压钳位。RoboFi 库RoboFi.h的设计哲学是“硬件即 API”所有外设初始化、寄存器配置、中断注册等底层操作均在库内部封装完成用户仅需调用高层语义化函数即可实现电机启停、速度设定、传感器读取等操作。这种设计显著降低嵌入式机器人开发门槛尤其适合教育场景、快速原型验证及中小规模产品化项目。2. RoboFi 库核心架构与初始化流程RoboFi 库采用单例模式设计全局仅存在一个RoboFi实例通过静态成员函数getInstance()获取。其类结构遵循分层抽象原则底层驱动层LL直接操作 ESP32 HALESP-IDF v4.4 兼容与寄存器中间服务层Service封装电机控制、ADC 采样、编码器计数等原子操作顶层应用接口API提供面向控制任务的函数如setMotorSpeed()、readLineSensors()。2.1 初始化与硬件抽象库初始化在RoboFi::begin()中完成该函数执行以下关键步骤GPIO 复用配置将电机驱动引脚IN1–IN4、PWM1–PWM4、ADC 通道引脚、编码器引脚设置为对应功能模式。例如PWM 输出使用 LEDCLED Control模块配置为 13-bit 分辨率、10 kHz 基频通道映射关系如下电机编号LEDC ChannelGPIO功能M1012PWM1M2113PWM2M3214PWM3M4327PWM4ADC 初始化启用 ADC1 单元配置 5 个通道ADC1_CHANNEL_6 至 ADC1_CHANNEL_9、ADC1_CHANNEL_0为 12-bit 模式设置衰减为 11 dB适配 0–3.3 V 信号启用 DMA 传输以降低 CPU 占用。定时器与中断注册为编码器输入配置 PCNTPulse Counter单元每个编码器使用独立 PCNT unitunit 0 对应左轮unit 1 对应右轮滤波时钟设为 80 MHz / 1024 ≈ 78 kHz计数范围 ±32767。电机驱动使能拉高所有电机驱动芯片的 STBYStandby引脚GPIO4解除休眠状态。用户代码中调用RoboFi::begin()即完成全部硬件准备无需手动配置时钟、GPIO 或外设控制器。#include RoboFi.h void setup() { // 初始化 RoboFi 硬件配置 GPIO、ADC、PCNT、LEDC RoboFi::begin(); // 可选设置电机默认参数非必需库内有合理默认值 RoboFi::setMotorDeadband(15); // 设置 PWM 死区阈值0–255 RoboFi::setMotorMaxSpeed(200); // 设置最大有效 PWM 占空比0–255 }2.2 关键配置参数解析RoboFi 库提供若干运行时可调参数直接影响控制精度与系统稳定性参数名类型默认值作用说明工程建议值motorDeadbanduint8_t10PWM 占空比低于此值时电机视为停止消除静摩擦导致的微动抖动12–20视电机型号与负载而定motorMaxSpeeduint8_t255映射到物理最大转速的 PWM 值用于线性化速度控制200–255留余量防过流adcSampleRateuint16_t100ADC 采样频率Hz影响传感器响应速度与 CPU 负载50–500线巡迹推荐 200 HzencoderFilterValueuint8_t10PCNT 滤波计数阈值抑制机械抖动引起的误触发5–20编码器质量差时调高uartBaudRateuint32_t115200UART0调试串口波特率115200兼容大多数终端这些参数通过RoboFi::setXXX()函数设置必须在begin()之后、首次调用控制函数之前完成配置。3. 核心控制 API 详解RoboFi 库 API 设计严格遵循“一个函数一个职责”原则所有函数均为静态成员避免对象实例化开销。以下按功能域分类解析关键接口。3.1 电机控制 APIRoboFi 支持四种基础电机操作模式独立控制、差速转向、速度闭环、位置闭环需外接编码器。所有电机函数均以uint8_t speed0–255为输入内部自动映射至 LEDC PWM 占空比。3.1.1 独立电机控制// 设置单个电机速度与方向 void RoboFi::setMotorSpeed(uint8_t motorId, int8_t speed); // motorId: 0M1, 1M2, 2M3, 3M4 // speed: -255 到 255负值表示反转 // 同时设置四电机速度高效批量操作 void RoboFi::setAllMotorSpeed(int8_t m1, int8_t m2, int8_t m3, int8_t m4); // 立即停止指定电机 void RoboFi::stopMotor(uint8_t motorId); // 立即停止所有电机 void RoboFi::stopAllMotors();底层实现逻辑setMotorSpeed()根据speed符号决定 INx 引脚电平正转INxHIGH/LOW反转INxLOW/HIGH再将abs(speed)写入对应 LEDC channel 的 duty 寄存器。死区处理在写入前完成若abs(speed) motorDeadband则强制输出 0。3.1.2 差速转向控制针对四轮底盘库提供原生差速模型将线速度vmm/s与角速度ωrad/s映射为左右轮速度// 设置差速驱动目标v: 线速度 mm/s, omega: 角速度 rad/s void RoboFi::setDifferentialDrive(float v, float omega); // 获取当前差速目标用于调试或上位机同步 void RoboFi::getDifferentialTarget(float* v, float* omega);运动学映射公式假设轮距 L 160 mm轮径 D 65 mmleft_speed (v - ω * L/2) / (π * D / 1000) * 60 // rpm right_speed (v ω * L/2) / (π * D / 1000) * 60 // rpm库内部将 rpm 转换为 PWM 值并进行饱和限制±motorMaxSpeed。3.2 传感器数据采集 API3.2.1 模拟传感器读取五路 ADC 通道专为巡线、灰度、红外测距等模拟传感器设计readAnalogSensor()返回 0–4095 的原始 ADC 值readAnalogVoltage()返回毫伏级电压值mV。// 读取指定通道原始 ADC 值0–4095 uint16_t RoboFi::readAnalogSensor(uint8_t channel); // 读取指定通道电压值mV uint16_t RoboFi::readAnalogVoltage(uint8_t channel); // 批量读取全部五路传感器优化 DMA 传输 void RoboFi::readAllAnalogSensors(uint16_t* values);通道映射表传感器编号ADC ChannelGPIO典型用途S1034左前巡线S2135左中巡线S3232中央避障S4333右中巡线S5439右前巡线3.2.2 编码器数据获取编码器数据通过 PCNT 单元获取getEncoderCount()返回自上次调用以来的净脉冲数带符号getEncoderRPM()计算当前转速rpm。// 获取指定编码器自上次 reset 后的计数值 int16_t RoboFi::getEncoderCount(uint8_t encoderId); // 获取指定编码器当前转速rpm int16_t RoboFi::getEncoderRPM(uint8_t encoderId); // 重置指定编码器计数器 void RoboFi::resetEncoderCount(uint8_t encoderId); // 批量获取双编码器数据 void RoboFi::getDualEncoderData(int16_t* left, int16_t* right);注意getEncoderRPM()内部采用滑动窗口平均法计算窗口长度为 10 个采样周期默认 100 ms避免瞬时噪声干扰。3.3 通信与调试 APIRoboFi 板 UART0GPIO1/3默认作为调试串口库提供格式化打印函数兼容 ArduinoSerial语法// 向调试串口输出格式化字符串类似 printf void RoboFi::debugPrint(const char* format, ...); // 输出传感器原始值便于上位机解析 void RoboFi::sendSensorData(); // 输出电机状态与编码器数据CSV 格式 void RoboFi::sendMotorStatus();sendSensorData()输出示例每行以\n结尾S1:1204,S2:1189,S3:234,S4:1192,S5:1210sendMotorStatus()输出示例M1:182,M2:-178,M3:180,M4:-176,L:243,R:-2384. 典型应用场景与代码实现4.1 黑白线巡迹控制PID 闭环利用五路模拟传感器实现经典 PID 巡线。核心思想是将传感器阵列读数转换为“偏差值”通过 PID 调节左右轮速差。#include RoboFi.h #include PID_v1.h // 使用开源 PID 库 // PID 参数需根据实际赛道调整 double Kp 2.5, Ki 0.05, Kd 1.2; double setpoint 2048; // 传感器中值12-bit ADC double input, output; PID pid(input, output, setpoint, Kp, Ki, Kd, DIRECT); void setup() { RoboFi::begin(); pid.SetMode(AUTOMATIC); pid.SetOutputLimits(-100, 100); // 输出限幅 ±100映射为 PWM 差值 } void loop() { // 读取五路传感器 uint16_t sensors[5]; RoboFi::readAllAnalogSensors(sensors); // 计算加权偏差S1–S5 权重 [-2,-1,0,1,2] int32_t weightedSum 0; for (int i 0; i 5; i) { int32_t weight i - 2; // -2,-1,0,1,2 weightedSum (sensors[i] - setpoint) * weight; } input (double)weightedSum / 100.0; // 归一化 pid.Compute(); // 差速控制基础速度 PID 输出 const int baseSpeed 120; int leftSpeed baseSpeed (int)output; int rightSpeed baseSpeed - (int)output; RoboFi::setAllMotorSpeed(leftSpeed, rightSpeed, leftSpeed, rightSpeed); delay(20); // 控制周期 20 ms50 Hz }4.2 基于 FreeRTOS 的多任务控制在 ESP32 上启用 FreeRTOS将传感器采集、控制计算、通信上报分离为独立任务提升系统实时性与可维护性。#include RoboFi.h #include freertos/FreeRTOS.h #include freertos/task.h #include freertos/queue.h QueueHandle_t sensorQueue; QueueHandle_t controlQueue; void sensorTask(void* pvParameters) { uint16_t sensors[5]; while(1) { RoboFi::readAllAnalogSensors(sensors); xQueueSend(sensorQueue, sensors, portMAX_DELAY); vTaskDelay(10 / portTICK_PERIOD_MS); // 100 Hz 采样 } } void controlTask(void* pvParameters) { uint16_t sensors[5]; while(1) { if (xQueueReceive(sensorQueue, sensors, portMAX_DELAY) pdTRUE) { // PID 计算逻辑同上 int leftSpeed ..., rightSpeed ...; xQueueSend(controlQueue, leftSpeed, portMAX_DELAY); xQueueSend(controlQueue, rightSpeed, portMAX_DELAY); } } } void motorTask(void* pvParameters) { int left, right; while(1) { if (xQueueReceive(controlQueue, left, portMAX_DELAY) pdTRUE xQueueReceive(controlQueue, right, portMAX_DELAY) pdTRUE) { RoboFi::setAllMotorSpeed(left, right, left, right); } } } void setup() { RoboFi::begin(); sensorQueue xQueueCreate(10, sizeof(uint16_t) * 5); controlQueue xQueueCreate(10, sizeof(int)); xTaskCreate(sensorTask, SENSOR, 2048, NULL, 2, NULL); xTaskCreate(controlTask, CONTROL, 4096, NULL, 3, NULL); xTaskCreate(motorTask, MOTOR, 2048, NULL, 2, NULL); } void loop() { /* FreeRTOS 运行不使用 loop */ }5. 硬件连接与调试指南5.1 关键引脚定义RoboFi 板丝印标识与 ESP32 引脚映射关系核心功能丝印标签ESP32 GPIO功能描述备注M1_IN112电机 1 方向控制H 桥 A 相与 PWM1 共用 GPIO12M1_PWM12电机 1 速度控制PWM 输出同上S134传感器 1 模拟输入ADC1_CH6ENC_L_A16左轮编码器 A 相PCNT_SIG_CH0_U0ENC_L_B17左轮编码器 B 相PCNT_SIG_CH1_U0UART_TX1调试串口发送连接 USB 转 TTL 模块 RX5V_OUT—5 V 电源输出电机供电最大电流 2 A3V3_OUT—3.3 V 电源输出MCU 供电最大电流 500 mA5.2 常见问题排查现象可能原因解决方案电机无响应STBY 引脚未拉高电源未接入 5 V检查 GPIO4 电平确认 DC 输入 ≥6 V传感器读数恒为 0 或 4095ADC 通道未正确初始化传感器供电异常调用RoboFi::begin()检查传感器 VCC/GND编码器计数跳变剧烈滤波值过低机械安装松动增大encoderFilterValue紧固编码器轴UART 调试无输出波特率不匹配TX 引脚接触不良确认uartBaudRate检查 GPIO1 焊点WiFi 连接失败天线未焊接Flash 模式错误检查板载 PCB 天线烧录时选择 DIO 模式5.3 性能实测数据在标准测试环境下12 V 输入MG513 12V 电机100 g 负载电机响应延迟从setMotorSpeed()调用到电机实际启动 ≤ 8 ms含 PWM 更新与驱动芯片建立时间ADC 采样吞吐量五通道连续采样DMA 传输CPU 占用率 3%100 Hz编码器计数精度在 100 rpm 下误差 ≤ ±2 脉冲/秒PCNT 滤波启用无线通信吞吐Wi-Fi STA 模式下TCP 传输速率稳定 4.2 Mbpsiperf3 测试。6. 与主流生态的集成方案6.1 与 PlatformIO 集成在platformio.ini中添加 RoboFi 库依赖[env:robofi] platform espressif32 board esp32dev framework arduino lib_deps https://github.com/robofi-org/RoboFi.git monitor_speed 1152006.2 与 MicroPython 互操作虽 RoboFi 库为 Arduino C 编写但可通过 ESP32 的esp-idf绑定层在 MicroPython 中调用关键函数。需编译定制固件暴露以下 C 函数接口// C 接口声明供 MicroPython 调用 extern C { void robofi_begin(); void robofi_set_motor_speed(uint8_t motor, int8_t speed); uint16_t robofi_read_analog(uint8_t channel); }MicroPython 示例import robofi robofi.begin() robofi.set_motor_speed(0, 150) # M1 正转 print(S1 , robofi.read_analog(0))6.3 ROS 2Foxy桥接通过 ESP32 的 Wi-Fi 连接 ROS 2 网络使用micro-ROS客户端发布传感器数据、订阅控制指令#include rcl/rcl.h #include rcl/error_handling.h #include std_msgs/msg/int16.h #include geometry_msgs/msg/twist.h rcl_publisher_t sensor_pub; std_msgs__msg__Int16 sensor_msg; geometry_msgs__msg__Twist cmd_msg; void cmd_callback(const void * msgin) { const geometry_msgs__msg__Twist * cmd (const geometry_msgs__msg__Twist*)msgin; float v cmd-linear.x; float w cmd-angular.z; RoboFi::setDifferentialDrive(v, w); } void setup() { RoboFi::begin(); // micro-ROS 初始化... rcl_subscription_t cmd_sub; rcl_subscription_init(cmd_sub, node, ROSIDL_GET_MSG_TYPE_SUPPORT(geometry_msgs, msg, Twist), /cmd_vel); rcl_subscription_set_callback(cmd_sub, cmd_callback, NULL); }此架构使 RoboFi 板可无缝接入 ROS 2 导航栈Nav2承担底层运动控制执行器角色。