Skip to content

ESP32 Smart Car Development Documentation


Table of Contents

  1. Project Overview
  2. Hardware Configuration
  3. Communication Architecture
  4. CAN Communication Protocol
  5. ESP32 Code Description
  6. Debugging and Maintenance

1. Project Overview

1.1 Project Introduction

This project implements a 4-wheel smart car based on the ESP32-S3, communicating with the host computer (ROS2) via CAN bus, and supporting Bluetooth gamepad control.

1.2 Features

Feature Description
Motor control 4 encoder motors, PWM speed control
Motion mode differential steering mode
Communication method CAN bus TWAI (primary), Bluetooth gamepad (local)
Sensors MPU6050 gyroscope, QMC5883L magnetometer (optional), encoders
Reported data battery voltage, attitude angle, linear velocity, angular velocity, motor speed, encoder cumulative value

1.3 Development Guide

Development board documentation

This project uses the VS Code + PlatformIO development environment.

If you have not used it before, you can search for related tutorials on Bilibili; it is easy to get started.

2. Hardware Configuration

2.1 Hardware List

Device Model/Specification Quantity Description
Main control ESP32-S3-DevKitC-1 1 main controller, integrated motor driver
Motor 36-555 4 DC geared motor
Encoder Hall encoder 4 integrated on the motor
Gyroscope MPU6050 1 built into the development board
Magnetometer QMC5883L 1 not used
Bluetooth gamepad BLE gamepad 1 local control
CAN transceiver USB-to-CAN analyzer 1 connected to the computer
CAN-to-TTL module CAN-to-TTL 1 connected to the ESP32

2.2 Pin Assignment

ESP32-S3 引脚资源:
├── GPIO5        : TWAI TX (CAN发送)
├── GPIO6        : TWAI RX (CAN接收)
├── GPIO2        : ADC (电池电压检测)
├── GPIO46       : LED指示
└── 编码器引脚   : 通过配置读取

2.3 CAN Bus Wiring

ESP32-S3              CAN转TTL模块          
─────────────────     ────────────────     
GPIO5 (TX)       →      TX                  
GPIO6 (RX)       →      RX                  
3.3V             →      VCC
GND              →      GND                 

CAN转TTL模块另一头       CAN收发器              电脑
──────────────────     ──────────────      ───────────
CANH              →      CANH       ->         usb
CANL              →      CANL

2.4 CAN Transceiver and Host Computer

Please see the folder "CAN Transceiver Documentation" in the delivery directory.


3. Communication Architecture

┌─────────────┐     USB-CAN      ┌──────────────┐    CAN总线    ┌─────────────────┐
│   ROS2 PC   │ ←──────────────→ │ USB-CAN收发器 │ ←───────────→ │ CAN转TTL模块   │
└─────────────┘                  └──────────────┘               └───────┬─────────┘
                                                                        │
                                                                        ↓
┌─────────────┐                          ┌────────────────────────────────────┐
│ 蓝牙手柄     │ ←──── BLE ──────────────→ │          ESP32-S3 (TWAI)          │
│ (本地控制)   │                          │  ┌────────────────────────────────┐│
└─────────────┘                          │  │ •  TWAI控制器(硬件处理CAN协议) ││
                                          │  │ •  蓝牙优先级最高               ││
                                          │  └────────────────────────────────┘│
                                          └───────────────────────────────────┘

4. CAN Communication Protocol

4.1 Communication Parameters

Parameter Value
Baud rate 500Kbps
Frame format standard frame (11-bit ID)
Data format little-endian (low byte first)
Filter receive all frames

4.2 CAN ID Allocation Table

ID Direction Function Data length
0x101 uplink attitude data 8 bytes
0x102 uplink motor speed (4 motors) 8 bytes
0x103 uplink encoder cumulative value (1-2) 8 bytes
0x104 uplink encoder cumulative value (3-4) 8 bytes
0x105 uplink sync frame (packet loss detection + latency estimation) 8 bytes
0x201 downlink PWM mode control (+seq) 8 bytes
0x202 downlink ROS speed mode control (+seq) 8 bytes
0x203 downlink brake command (+seq) 2 bytes

0x101 - Attitude Data (8 bytes)

Byte Type Name Unit Description
0-1 uint16 voltage 0.01V battery voltage, e.g. 241=24.1V
2-3 int16 angleZ deg heading angle, -180~180
4-5 int16 linearX mm/s X-axis linear velocity
6-7 int16 linearY mm/s Y-axis linear velocity

Test examples:

Scenario Data (hex) Description
stationary F1 00 00 00 00 00 00 00 voltage 24.1V, heading 0°, linear velocity 0
turning right 90° F1 00 5A 00 00 00 00 00 voltage 24.1V, heading 90°, linear velocity 0
moving forward F1 00 00 00 64 00 00 00 voltage 24.1V, heading 0°, X linear velocity 100mm/s
fully charged moving forward C8 00 00 00 64 00 00 00 voltage 20.0V, heading 0°, X linear velocity 100mm/s

0x102 - Motor Speed (8 bytes)

Byte Type Name Unit
0-1 int16 rpm1 RPM
2-3 int16 rpm2 RPM
4-5 int16 rpm3 RPM
6-7 int16 rpm4 RPM

Test examples:

Scenario Data (hex) Description
stationary 00 00 00 00 00 00 00 00 all stopped
forward 32 00 1E 00 0A 00 14 00 Motor 1=50, Motor 2=30, Motor 3=10, Motor 4=20 RPM
backward CE FF E2 FF F6 FF 0A 00 Motor 1=-50, Motor 2=-30, Motor 3=-10, Motor 4=10 RPM

0x103 - Encoder Cumulative Value 1-2 (8 bytes)

Byte Type Name Description
0-3 int32 encoder1 cumulative pulse count of encoder 1
4-7 int32 encoder2 cumulative pulse count of encoder 2

Test example: [0x64 0x00 0x00 0x00 0xE8 0x03 0x00 0x00] → Encoder 1=100, Encoder 2=1000

0x104 - Encoder Cumulative Value 3-4 (8 bytes)

Byte Type Name Description
0-3 int32 encoder3 cumulative pulse count of encoder 3
4-7 int32 encoder4 cumulative pulse count of encoder 4

Test example: [0x00 0x00 0x00 0x00 0x10 0x27 0x00 0x00] → Encoder 3=0, Encoder 4=10000

0x105 - Sync Frame (8 bytes, ESP32 → PC, 1Hz)

Used by the host computer to implement packet loss detection and latency estimation. Sent periodically by the ESP32, carrying system uptime and frame sequence number.

Byte Type Name Description
0-3 uint32 uptime_ms system uptime (ms), can be used for latency estimation
4-5 uint16 frame_seq global frame sequence number, monotonically increasing; a jump indicates packet loss
6 uint8 rx_seq_echo sequence number of the most recently received downlink frame; the host can calculate RTT from it
7 uint8 reserved reserved

Test examples:

Scenario Data (hex) Description
1 second after startup E8 03 00 00 05 00 00 00 uptime=1000ms, seq=5, rx_echo=0
running for 10 seconds 10 27 00 00 32 00 0A 00 uptime=10000ms, seq=50, rx_echo=10

0x201 - PWM Mode Control (8 bytes)

Byte Type Name Range Description
0-1 int16 x_speed -100~100 X-axis power percentage
2-3 int16 y_speed -100~100 Y-axis power percentage
4-5 int16 z_speed -100~100 Z-axis power percentage
6 uint8 seq 0~255 frame sequence number, incremented by the host, used for packet loss detection
7 uint8 reserved - reserved

Test examples (host fills: CAN ID = 0x201, data 8-byte hex, data length 8):

Scenario Data (hex 8 bytes) X Z Description
forward 50% 32 00 00 00 00 00 00 00 50 0 X-axis 50% forward
forward 100% 64 00 00 00 00 00 00 00 100 0 X-axis full speed forward
backward 50% CE FF 00 00 00 00 00 00 -50 0 X-axis -50% backward
clockwise rotation 50% 00 00 00 00 32 00 00 00 0 50 Z-axis 50% right turn
counterclockwise rotation 50% 00 00 00 00 CE FF 00 00 00 0 -50 Z-axis -50% left turn
stop 00 00 00 00 00 00 00 00 0 0 all zero

Note: rubber wheels do not support lateral movement; fill 0 for the Y axis.

0x202 - ROS Speed Mode Control (8 bytes)

Byte Type Name Unit Description
0-1 int16 x_speed mm/s X-axis linear velocity
2-3 int16 y_speed mm/s Y-axis linear velocity
4-5 int16 z_speed deg/s Z-axis angular velocity
6 uint8 seq 0~255 frame sequence number, incremented by the host, used for packet loss detection
7 uint8 reserved - reserved

Test examples (host fills: CAN ID = 0x202, data 8-byte hex, data length 8):

Scenario Data (hex 8 bytes) X(mm/s) Z(deg/s) Description
forward 0.2m/s C8 00 00 00 00 00 00 00 200 0 about 0.2m/s forward
forward 0.8m/s 20 03 00 00 00 00 00 00 800 0 about 0.8m/s forward
backward 0.2m/s 38 FF 00 00 00 00 00 00 -200 0 about 0.2m/s backward
rotation 90°/s 00 00 00 00 5A 00 00 00 0 90 90°/s clockwise rotation
stop 00 00 00 00 00 00 00 00 0 0 all zero

0x203 - Brake Command (2 bytes)

Byte Type Name Range Description
0 uint8 brakeForce 0~100 brake force, 0=coast to stop, 1~100=active braking + parking hold
1 uint8 seq 0~255 frame sequence number, incremented by the host, used for packet loss detection
  • brakeForce = 0: coast to stop (motor released, freely decelerates to a stop)
  • brakeForce > 0: active braking → motor short-circuit braking until fully stopped → automatically enters parking position hold (encoder closed-loop back-calc, resists external pushing force)

Test examples (host fills: CAN ID = 0x203, data length 2):

Scenario Data (hex) Description
coast to stop 00 brake force 0, release the motor to stop freely
gentle braking 30 30% brake force braking, parking hold after stopping
emergency braking 64 100% full-force braking, parking hold after stopping

5. ESP32 Code Description

5.1 Code Structure

cust20/
├── src/
│   ├── main.cpp          # 主程序入口
│   └── main.h            # 全局变量和函数声明
├── lib/
│   ├── CanBus/           # CAN通信模块
│   │   ├── CanBus.h/cpp      # MCP2515方案(参考)
│   │   ├── CanBusTTL.h/cpp   # CAN转TTL方案(参考)
│   │   └── CanBusTWAI.h/cpp  # TWAI方案(当前使用)
│   ├── Config/            # 配置存储
│   ├── ControlStick/      # 蓝牙手柄
│   ├── encoder/           # 编码器驱动
│   ├── motor/            # 电机驱动
│   ├── Pid/              # PID控制
│   ├── protocal/         # 通信协议定义
│   └── Head.h            # 硬件参数配置
└── platformio.ini        # 项目配置

5.2 Core Class Description

CanBusTWAI Class

Uses the built-in TWAI controller of the ESP32-S3 to automatically process the CAN protocol via hardware.

class CanBusTWAI
{
public:
    // 初始化TWAI控制器
    bool begin(CanRxCallback callback);

    // 发送原始CAN帧
    bool sendFrame(uint16_t canId, const uint8_t* data, uint8_t len);

    // 发送姿态数据帧
    bool sendPoseData(float voltage, int16_t angleZ, ...);

    // 发送电机转速帧
    bool sendMotorRpm(int16_t rpm1, int16_t rpm2, int16_t rpm3);

    // 发送编码器累计值帧
    bool sendEncoderTicks(int32_t tick1, int32_t tick2, ...);
};

handleCanFrame Callback Function

Parses the CAN commands sent by the host:

  • 0x201 PWM mode → calls controlEMotors()
  • 0x202 ROS mode → calls controlEMotors() after unit conversion
  • 0x203 brake command → calls stop()

5.3 Multi-task Architecture

The ESP32-S3 dual-core processor assigns tasks as follows:

Task Core Description
loop() Core 1 main loop
xCore_task Core 0 motor control, sensor acquisition
twaiTask Core 0 CAN frame reception (independent task)

5.4 Key Parameters (must be adjusted yourself)

/**Head.h*/
// 根据实际情况修改参数配置
const int maxRpm = 110;              // 电机最大转速RPM
const int gear = 90;                 // 减速比
const float wheelCircumference = PI * 80;  // 轮子周长(mm)
const int wheelSpacing = 220;        // 轮间距(mm)
const int wheelBase = 200;           // 轴距(mm)
/**main.h*/
// 可以根据实际情况修改参数配置
const int gapNotice = 100;  // 定时发送状态的间隔,单位毫秒
const int outPutCountLimit = 10; // 电机满负荷运行多少次后降低速度
const float maxDe = 0.3;    // 电机如果超负荷运行,最大降速比例
/**pid.h*/
// 必须根据实际情况修改参数配置,例如下行数据的频率,影响到电机的转速
double kp = 0.25;  // 比例系数
double ki = 0.02;  // 积分系数
double kd = 0.5;  // 微分系数

5.5 Data Reporting Period

  • Attitude data: 100ms (10Hz)
  • Motor speed: 100ms (10Hz)
  • Encoder: 100ms (10Hz)

6. Debugging and Maintenance

6.1 Debugging Methods

Serial Monitor

Baud rate 115200, can view:

  • TWAI initialization status

  • Received commands

  • Motor speed feedback

  • Error messages

6.2 Contact Information

If you have any questions, please contact technical support at 15827639032.


Appendix

A. CAN Frame Test Quick Reference Table

Operation CAN ID Data (hex 8 bytes) Data length
50% power forward 0x201 32 00 00 00 00 00 01 00 8
100% power forward 0x201 64 00 00 00 00 00 02 00 8
50% power backward 0x201 CE FF 00 00 00 00 03 00 8
50% clockwise rotation 0x201 00 00 00 00 32 00 04 00 8
50% counterclockwise rotation 0x201 00 00 00 00 CE FF 05 00 8
stop 0x201 00 00 00 00 00 00 06 00 8
forward 0.2m/s 0x202 C8 00 00 00 00 00 01 00 8
forward 0.8m/s 0x202 20 03 00 00 00 00 02 00 8
backward 0.2m/s 0x202 38 FF 00 00 00 00 03 00 8
rotation 90°/s 0x202 00 00 00 00 5A 00 04 00 8
stop 0x202 00 00 00 00 00 00 05 00 8
coast to stop 0x203 00 01 00 00 00 00 00 00 2
gentle braking + parking 0x203 1E 02 00 00 00 00 00 00 2
emergency braking + parking 0x203 64 03 00 00 00 00 00 00 2
Data meaning CAN ID Data (hex 8 bytes)
voltage 24.1V, stationary 0x101 F1 00 00 00 00 00 00 00
voltage 24.1V, heading 90° 0x101 F1 00 5A 00 00 00 00 00
voltage 24.1V, X linear velocity 100mm/s 0x101 F1 00 00 00 64 00 00 00
Motor 1=50, 2=30, 3=10, 4=20 RPM 0x102 32 00 1E 00 0A 00 14 00
Encoder 1=100, Encoder 2=1000 0x103 64 00 00 00 E8 03 00 00
Encoder 3=0, Encoder 4=10000 0x104 00 00 00 00 10 27 00 00
sync: uptime=1000ms, seq=5 0x105 E8 03 00 00 05 00 00 00

USB-CAN Analyzer Host Computer Operation Steps

  1. Wire as shown below: connect the Dupont wires to esp2, and plug the USB into the computer.

Img

  1. Install the driver and host software according to the documentation in the materials package.

  2. Upload the ESP32 code to the development board.

  3. Open the host software; a "connect" dialog will pop up automatically. If not, connect manually.

Img

  1. Configure the test packet yourself.

Img

B. Revision History

Version Date Changes
1.0 2026-05-12 initial version
1.1 2026-05-14 switched to TWAI solution, added CAN transceiver wiring instructions
1.2 2026-05-27 added complete test data tables for each CAN ID and USB-CAN host software operation instructions
1.3 2026-06-26 added 0x105 sync frame; added seq sequence number to 0x201/0x202/0x203; expanded 0x102 to 4 motors 8 bytes