M5Stack Unit 4EncoderMotor Driver I²C Control Protocol
1. Basic Information
| Item | Description |
|---|---|
| Bus | I²C |
| Default I²C Address (7-bit) | 0x24 |
| I²C Address Range | 0x08 ~ 0x77 |
| Communication Rate | 100k / 400k |
| Register Address Width | 8 bit |
| Register Data Width | 8 bit / 16 bit / 32 bit / float |
| Firmware Version | V1 |
| Protocol Date | 2026-08-25 |
1.1 Access Permissions
| Permission | Meaning |
|---|---|
R | Read-only |
| W | Write-only |
R/W | Read/write |
Reserved | Reserved; do not access |
2. Register/Command Overview
This section lists all accessible addresses.
| Address/Address Range | Name | Length | Permission | Default | Retained After Power-Off | Summary | Details |
|---|---|---|---|---|---|---|---|
0x20 ~ 0x23 | Motor PWM Duty | 4 | R/W | 0 | No | 4-channel motor PWM duty cycle, INT8, range -127 ~ 127 | 4.1 |
0x30 ~ 0x3F | Motor Encoder | 16 | R/W | \ | No | Encoder counts for 4 motors, INT32 per channel | 4.2 |
0x40 ~ 0x43 | Motor Speed | 4 | R | Runtime | No | Speed of 4 motors, INT8, range -127 ~ 127 | 4.3 |
0x50 ~ 0x5C | Motor1 Mode | 13 | R/W | \ | No | Motor1 operating mode, position PID, speed PID, and target values | 4.4 |
0x60 ~ 0x6C | Motor2 Mode | 13 | R/W | \ | No | Motor2 operating mode, position PID, speed PID, and target values | 4.5 |
0x70 ~ 0x7C | Motor3 Mode | 13 | R/W | \ | No | Motor3 operating mode, position PID, speed PID, and target values | 4.6 |
0x80 ~ 0x8C | Motor4 Mode | 13 | R/W | \ | No | Motor4 operating mode, position PID, speed PID, and target values | 4.7 |
0x90 ~ 0x93 | VIN Current | 4 | R | Runtime | No | VIN current, unit A, float | 4.8 |
0xB0 ~ 0xB3 | VIN ADC / VIN Voltage | 4 | R | Runtime | No | 12-bit ADC raw value and VIN voltage in mV | 4.9 |
0xC0 ~ 0xC4 | RGB LED | 5 | R/W | 0x00 | No | RGB LED color and brightness | 4.10 |
0xD0 | Encoder AB or BA | 1 | R/W | 0 | Yes | Encoder AB/BA direction configuration | 4.11 |
0xD1 | Soft Start and Stop | 1 | R/W | 0x00 | Yes | Soft-start/soft-stop switch, effective in Normal and Speed modes | 4.12 |
0xE0 ~ 0xEB | UID | 12 | R | \ | No | 12-byte device UID, read-only | 4.13 |
0xFE | Firmware Version | 1 | R | Runtime | No | Firmware version number | 4.14 |
0xFF | I2C Address | 1 | R/W | 0x24 | Yes | I²C address, range 0x08 ~ 0x77 | 4.15 |
3. Address Conventions
| Address | Name | Description |
|---|---|---|
0x20 ~ 0x23 | Motor PWM Duty | PWM duty cycle registers for 4 motors |
0x30 ~ 0x3F | Motor Encoder | Encoder count registers for 4 motors |
0x40 ~ 0x43 | Motor Speed | Speed registers for 4 motors |
0x50 ~ 0x5C | Motor1 Mode | Motor1 mode and control parameters |
0x60 ~ 0x6C | Motor2 Mode | Motor2 mode and control parameters |
0x70 ~ 0x7C | Motor3 Mode | Motor3 mode and control parameters |
0x80 ~ 0x8C | Motor4 Mode | Motor4 mode and control parameters |
0x90 ~ 0x93 | VIN Current | VIN current register |
0xB0 ~ 0xB3 | VIN ADC / VIN Voltage | VIN ADC and voltage registers |
0xC0 ~ 0xC4 | RGB LED | RGB LED control registers |
0xD0 | Encoder AB or BA | Restarts automatically immediately after writing and takes effect; the written data is automatically saved to Flash |
0xD1 | Soft Start and Stop | The written data is automatically saved to Flash |
0xE0 ~ 0xEB | UID | Device UID read-only register, corresponding to the 12-byte UID |
0xFE | Firmware Version | Firmware version number |
0xFF | I2C Address | Reads and writes the I2C address; after writing, the firmware reinitializes I2C immediately and the new address takes effect without a restart; the written data is automatically saved to Flash |
4. Register Details
4.1 Motor PWM Duty
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x20 ~ 0x23 | 4 byte | R/W | Sets or reads the PWM duty cycle of the 4 motors |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x20 | -127 ~ 127 | 0 | Motor1_PWM_Duty, INT8 |
0x21 | -127 ~ 127 | 0 | Motor2_PWM_Duty, INT8 |
0x22 | -127 ~ 127 | 0 | Motor3_PWM_Duty, INT8 |
0x23 | -127 ~ 127 | 0 | Motor4_PWM_Duty, INT8 |
4.2 Motor Encoder
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x30 ~ 0x3F | 16 byte | R/W | Sets or reads the encoder count values of the 4 motors |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x30 ~ 0x33 | INT32 | 0 | Motor1_Encoder, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x34 ~ 0x37 | INT32 | 0 | Motor2_Encoder, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x38 ~ 0x3B | INT32 | 0 | Motor3_Encoder, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x3C ~ 0x3F | INT32 | 0 | Motor4_Encoder, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
4.3 Motor Speed
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x40 ~ 0x43 | 4 byte | R | Reads the speed of the 4 motors |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x40 | -127 ~ 127 | Runtime | Motor1_Speed, INT8 |
0x41 | -127 ~ 127 | Runtime | Motor2_Speed, INT8 |
0x42 | -127 ~ 127 | Runtime | Motor3_Speed, INT8 |
0x43 | -127 ~ 127 | Runtime | Motor4_Speed, INT8 |
Notes
1. The motor encoder speed measurement period is 20 ms. Motor Speed represents the encoder count increment over the most recent 20 ms; it is not RPM, PWM duty cycle, or linear speed.
2. The underlying type of the Motor Speed register is INT8, which can represent -127 ~ 127. The actual achievable speed depends on the motor, load, power supply, motor drive capability, and encoder installation. With the current standard motor/driver configuration, the measured maximum is approximately ±23.
4.4 Motor1 Mode
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x50 ~ 0x5C | 13 byte | R/W | Motor1 mode, position-loop parameters, speed-loop parameters, and target values |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x50 | 0 ~ 2 | 0 | Motor1_Mode: 0 Normal; 1 Position Lock; 2 Speed Lock |
0x51 | 0 ~ 255 | 3 | Motor1_Position_P |
0x52 | 0 ~ 255 | 1 | Motor1_Position_I |
0x53 | 0 ~ 255 | 15 | Motor1_Position_D |
0x54 ~ 0x57 | INT32 | \ | Motor1_Position_Point, target position in Position mode, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x58 | -127 ~ 127 | 127 | Motor1_Position_MAX_Speed |
0x59 | 0 ~ 255 | 10 | Motor1_Speed_P |
0x5A | 0 ~ 255 | 1 | Motor1_Speed_I |
0x5B | 0 ~ 255 | 15 | Motor1_Speed_D |
0x5C | -127 ~ 127 | 5 | Motor1_Speed_Point, target 20 ms encoder increment in Speed mode |
4.5 Motor2 Mode
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x60 ~ 0x6C | 13 byte | R/W | Motor2 mode, position-loop parameters, speed-loop parameters, and target values |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x60 | 0 ~ 2 | 0 | Motor2_Mode: 0 Normal; 1 Position Lock; 2 Speed Lock |
0x61 | 0 ~ 255 | 3 | Motor2_Position_P |
0x62 | 0 ~ 255 | 1 | Motor2_Position_I |
0x63 | 0 ~ 255 | 15 | Motor2_Position_D |
0x64 ~ 0x67 | INT32 | \ | Motor2_Position_Point, target position in Position mode, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x68 | -127 ~ 127 | 127 | Motor2_Position_MAX_Speed |
0x69 | 0 ~ 255 | 10 | Motor2_Speed_P |
0x6A | 0 ~ 255 | 1 | Motor2_Speed_I |
0x6B | 0 ~ 255 | 15 | Motor2_Speed_D |
0x6C | -127 ~ 127 | 5 | Motor2_Speed_Point, target 20 ms encoder increment in Speed mode |
4.6 Motor3 Mode
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x70 ~ 0x7C | 13 byte | R/W | Motor3 mode, position-loop parameters, speed-loop parameters, and target values |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x70 | 0 ~ 2 | 0 | Motor3_Mode: 0 Normal; 1 Position Lock; 2 Speed Lock |
0x71 | 0 ~ 255 | 3 | Motor3_Position_P |
0x72 | 0 ~ 255 | 1 | Motor3_Position_I |
0x73 | 0 ~ 255 | 15 | Motor3_Position_D |
0x74 ~ 0x77 | INT32 | \ | Motor3_Position_Point, target position in Position mode, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x78 | -127 ~ 127 | 127 | Motor3_Position_MAX_Speed |
0x79 | 0 ~ 255 | 10 | Motor3_Speed_P |
0x7A | 0 ~ 255 | 1 | Motor3_Speed_I |
0x7B | 0 ~ 255 | 15 | Motor3_Speed_D |
0x7C | -127 ~ 127 | 5 | Motor3_Speed_Point, target 20 ms encoder increment in Speed mode |
4.7 Motor4 Mode
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x80 ~ 0x8C | 13 byte | R/W | Motor4 mode, position-loop parameters, speed-loop parameters, and target values |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x80 | 0 ~ 2 | 0 | Motor4_Mode: 0 Normal; 1 Position Lock; 2 Speed Lock |
0x81 | 0 ~ 255 | 3 | Motor4_Position_P |
0x82 | 0 ~ 255 | 1 | Motor4_Position_I |
0x83 | 0 ~ 255 | 15 | Motor4_Position_D |
0x84 ~ 0x87 | INT32 | \ | Motor4_Position_Point, target position in Position mode, little-endian: byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216 |
0x88 | -127 ~ 127 | 127 | Motor4_Position_MAX_Speed |
0x89 | 0 ~ 255 | 10 | Motor4_Speed_P |
0x8A | 0 ~ 255 | 1 | Motor4_Speed_I |
0x8B | 0 ~ 255 | 15 | Motor4_Speed_D |
0x8C | -127 ~ 127 | 5 | Motor4_Speed_Point, target 20 ms encoder increment in Speed mode |
Motor1 ~ Motor4 Speed Point General Notes
1. Motor*_Speed_Point is the target Motor Speed in Speed Lock mode. Its unit is exactly the same as that of 0x40 ~ 0x43: the 20 ms encoder count increment.
2. The underlying type of the Motor*_Speed_Point register is INT8, and the protocol layer accepts writes from -127 ~ 127. This does not mean that a standard motor can actually reach the full speed range. With the current standard motor/driver configuration, the recommended effective closed-loop target range is 0, ±3 ~ ±23; below approximately ±3, the motor may not rotate stably due to static friction or the startup dead zone.
3. When the set value exceeds the actually achievable speed, the firmware continues to adjust and may saturate the PWM output. The Motor Speed feedback value is not guaranteed to reach the Speed Point setting. When checking whether Speed Lock is working correctly, use target values within the actually achievable range first.
4.8 VIN Current
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0x90 ~ 0x93 | 4 byte | R | Reads the VIN input current |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0x90 ~ 0x93 | float | Runtime | VIN Current, unit A; little-endian byte order |
4.9 VIN ADC / VIN Voltage
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xB0 ~ 0xB3 | 4 byte | R | Reads the VIN ADC raw value and VIN voltage |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xB0 | 0 ~ 255 | Runtime | ADC Value 12bits-L |
0xB1 | 0 ~ 15 | Runtime | ADC Value 12bits-H, high bits of the 12-bit ADC |
0xB2 | 0 ~ 255 | Runtime | VIN(mV)-LSB |
0xB3 | 0 ~ 255 | Runtime | VIN(mV)-MSB |
Notes
1. ADC raw value formula: ADC = ADC_L + ADC_H * 256, range 0 ~ 4095.
2. Voltage conversion formula specified in the protocol: Voltage = (ADC / 4095) * 3.3 / 0.16.
3. VIN(mV) represents the actual VIN voltage, and its formula is: VIN_mV = LSB + MSB * 256.
4.10 RGB LED
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xC0 ~ 0xC4 | 5 byte | R/W | Sets or reads the RGB LED color and brightness |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xC0 | 0 ~ 255 | 0 | B, blue component |
0xC1 | 0 ~ 255 | 0 | G, green component |
0xC2 | 0 ~ 255 | 0 | R, red component |
0xC3 | \ | \ | Dummy |
0xC4 | 0 ~ 255 | 127 | brightness, brightness |
4.11 Encoder AB or BA
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xD0 | 1 byte | R/W | Configures the encoder AB/BA direction |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xD0 | 0 ~ 1 | 0 | 0: AB, default; 1: BA |
Notes
1. After writing to this register, the device automatically restarts immediately to apply the change.
2. The written data is automatically saved to Flash. Avoid frequent writes to prevent Flash damage.
4.12 Soft Start and Stop
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xD1 | 1 byte | R/W | Configures soft start and soft stop for the 4 motors |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xD1 bit0 | 0 ~ 1 | 0 | Motor1 soft start/soft stop: 0 disabled, 1 enabled |
0xD1 bit1 | 0 ~ 1 | 0 | Motor2 soft start/soft stop: 0 disabled, 1 enabled |
0xD1 bit2 | 0 ~ 1 | 0 | Motor3 soft start/soft stop: 0 disabled, 1 enabled |
0xD1 bit3 | 0 ~ 1 | 0 | Motor4 soft start/soft stop: 0 disabled, 1 enabled |
0xD1 bit4 ~ bit7 | \ | \ | Unused |
Notes
1. Soft start and soft stop apply to Normal and Speed modes and have no effect in Position mode.
2. The written data is automatically saved to Flash. Avoid frequent writes to prevent Flash damage.
4.13 UID
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xE0 ~ 0xEB | 12 byte | R | Reads the device UID; the data comes from g_uid[12] written by read_uid() |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xE0 | 0 ~ 255 | Runtime | UID byte0 |
0xE1 | 0 ~ 255 | Runtime | UID byte1 |
0xE2 | 0 ~ 255 | Runtime | UID byte2 |
0xE3 | 0 ~ 255 | Runtime | UID byte3 |
0xE4 | 0 ~ 255 | Runtime | UID byte4 |
0xE5 | 0 ~ 255 | Runtime | UID byte5 |
0xE6 | 0 ~ 255 | Runtime | UID byte6 |
0xE7 | 0 ~ 255 | Runtime | UID byte7 |
0xE8 | 0 ~ 255 | Runtime | UID byte8 |
0xE9 | 0 ~ 255 | Runtime | UID byte9 |
0xEA | 0 ~ 255 | Runtime | UID byte10 |
0xEB | 0 ~ 255 | Runtime | UID byte11 |
4.14 Firmware Version
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xFE | 1 byte | R | Reads the firmware version number |
4.15 I2C Address
| Address/Address Range | Length | Permission | Description |
|---|---|---|---|
0xFF | 1 byte | R/W | Sets or reads the device I²C address |
Parameters
| Address/Offset | Value/Range | Default | Description |
|---|---|---|---|
0xFF | 0x08 ~ 0x77 | 0x24 | Device I²C address |
Notes
1. The written data is automatically saved to Flash. Avoid frequent writes to prevent Flash damage.
2. After the address is written, the firmware reinitializes I2C immediately and uses the new address without restarting the device.
5. Version History
| Document Version | Firmware Version | Date | Update Description |
|---|---|---|---|
| V1.0 | V1 | 2026-08-25 | Initial version |