M5Stack Unit EncoderMotor Driver I²C Control Protocol

1. Basic Information

Item	Description
Bus	I²C
Default I²C Address (7-bit)	0x2F
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	VF3
Protocol Date	`2025-08-06`

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`	`Motor PWM Duty`	`1`	`R/W`	0	No	Motor PWM duty cycle, `INT8`, range `-127 ~ 127`	`4.1`
`0x30 ~ 0x33`	`Motor Encoder`	`4`	`R/W`	\	No	Motor encoder count, `INT32`	`4.2`
`0x40`	`Motor Speed`	`1`	`R`	Runtime	No	Motor speed, `INT8`, range `-127 ~ 127`	`4.3`
`0x50 ~ 0x5C`	`Motor1 Mode`	`13`	`R/W`	\	No	Motor operating mode, position PID, speed PID, and target values	`4.4`
`0x90 ~ 0x93`	`VIN Current`	`4`	`R`	Runtime	No	VIN current, unit `A`, `float`	`4.5`
`0xB0 ~ 0xB3`	`VIN ADC / VIN Voltage`	`4`	`R`	Runtime	No	12-bit ADC raw value and VIN voltage in mV	`4.6`
`0xD0`	`Encoder AB or BA`	`1`	`R/W`	0	Yes	Encoder AB/BA direction configuration	`4.7`
`0xD1`	`Soft Start and Stop`	`1`	`R/W`	0x00	Yes	Soft-start/soft-stop switch, effective only in Normal mode	`4.8`
`0xD2`	`Motor Sleep`	`1`	`R/W`	0x01	No	Motor sleep/run control	`4.9`
`0xC0 ~ 0xC4`	`RGB LED`	`5`	`R/W`	0x0	No	RGB LED color and brightness	`4.10`
`0xE0 ~ 0xEB`	`UID`	`12`	`R`	Runtime	No	MCU 12-byte UID	`4.11`
`0xFE`	`Firmware Version`	`1`	`R`	Runtime	No	Firmware version number	`4.12`
`0xFF`	`I2C Address`	`1`	`R/W`	0x2F	Yes	I²C address, range `0x08 ~ 0x77`	`4.13`

3. Register Addresses

Address	Name	Description
`0x20`	`Motor PWM Duty`	Motor PWM duty cycle register
`0x30 ~ 0x33`	`Motor Encoder`	Motor encoder count register
`0x40`	`Motor Speed`	Motor speed register
`0x50 ~ 0x5C`	`Motor1 Mode`	Motor mode and control parameters
`0x90 ~ 0x93`	`VIN Current`	VIN current register
`0xB0 ~ 0xB3`	`VIN ADC / VIN Voltage`	VIN ADC and voltage 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
`0xD2`	`Motor Sleep`	Runtime setting; restores the default run state after reset or power-on
`0xC0 ~ 0xC4`	`RGB LED`	RGB LED control registers
`0xE0 ~ 0xEB`	`UID`	MCU 12-byte UID storage register
`0xFE`	`Firmware Version`	Firmware version number
`0xFF`	`I2C Address`	Reinitializes the I²C peripheral immediately after writing and then uses the new address; the host should wait about `300 ms` before accessing the new address

4. Register Details

This section describes only the parameter meanings and value ranges that the overview table cannot express.

4.1 Motor PWM Duty

Address/Address Range	Length	Permission	Description
`0x20`	`1 byte`	`R/W`	Sets or reads the motor PWM duty cycle

Parameters

Address/Offset	Value/Range	Default	Description
`0x20`	`-127 ~ 127`	0	`Motor1_PWM_Duty`, `INT8`

4.2 Motor Encoder

Address/Address Range	Length	Permission	Description
`0x30 ~ 0x33`	`4 byte`	`R/W`	Sets or reads the motor encoder count value

Parameters

Address/Offset	Value/Range	Default	Description
`0x30`	`0 ~ 255`	0	`Motor1_Encoder-byte0`
`0x31`	`0 ~ 255`	0	`Motor1_Encoder-byte1`
`0x32`	`0 ~ 255`	0	`Motor1_Encoder-byte2`
`0x33`	`0 ~ 255`	-	`Motor1_Encoder-byte3`
`0x30 ~ 0x33`	`INT32`	0	`Motor1_Encoder`, little-endian: `byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216`

4.3 Motor Speed

Address/Address Range	Length	Permission	Description
`0x40`	`1 byte`	`R`	Reads the motor speed

Parameters

Address/Offset	Value/Range	Default	Description
`0x40`	`-127 ~ 127`	Runtime	`Motor1_Speed`, `INT8`

Notes

1. The motor encoder speed measurement period is `20 ms`.

4.4 Motor1 Mode

Address/Address Range	Length	Permission	Description
`0x50 ~ 0x5C`	`13 byte`	`R/W`	Motor 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/Open loop; `1` Position Lock; `2` Speed Lock
`0x51`	`0 ~ 255`	1	`Motor1_Position_P`
`0x52`	`0 ~ 255`	1	`Motor1_Position_I`
`0x53`	`0 ~ 255`	17	`Motor1_Position_D`
`0x54 ~ 0x57`	`INT32`	\	`Motor1_Position_Point`, little-endian: `byte0 + byte1 * 256 + byte2 * 65536 + byte3 * 16777216`
`0x58`	`-127 ~ 127`	127	`Motor1_Position_MAX_Speed`, `INT8`; the position loop uses its absolute value as the maximum output limit
`0x59`	`0 ~ 255`	10	`Motor1_Speed_P`
`0x5A`	`0 ~ 255`	1	`Motor1_Speed_I`
`0x5B`	`0 ~ 255`	15	`Motor1_Speed_D`
`0x5C`	`-127 ~ 127`	127	`Motor1_Speed_Point`

Notes

1. The sign of `Motor1_Position_MAX_Speed` does not change the position control direction. The firmware uses its absolute value as the maximum speed limit; `-128` is an invalid value.

4.5 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/VIN Current byte0~byte3`	Runtime	`VIN Current`, unit `A`; little-endian byte order

4.6 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: `Voltage = (ADC / 4095) * 3.3 * 6`.

3. `VIN(mV)` represents the actual VIN voltage, and its formula is: `VIN_mV = LSB + MSB * 256`.

4.7 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.8 Soft Start and Stop

Address/Address Range	Length	Permission	Description
`0xD1`	`1 byte`	`R/W`	Configures motor soft start and soft stop

Parameters

Address/Offset	Value/Range	Default	Description
`0xD1`	`0 ~ 1`	`0x00`	Soft start/soft stop: `0` disabled, `1` enabled

Notes

1. Soft start and soft stop apply only to Normal/Open loop mode.

2. The written data is automatically saved to Flash. Avoid frequent writes to prevent Flash damage.

4.9 Motor Sleep

Address/Address Range	Length	Permission	Description
`0xD2`	`1 byte`	`R/W`	Configures the motor sleep or run state

Parameters

Address/Offset	Value/Range	Default	Description
`0xD2`	`0 ~ 1`	`0x01`	`Motor nSleep`: `0` Sleep; `1` run

Notes

1. This register is a runtime setting and is not saved to Flash.

2. After a device reset or power-on, this register returns to the default value `0x01` (Run).

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 UID

Address/Address Range	Length	Permission	Description
`0xE0 ~ 0xEB`	`12 byte`	`R`	Reads the MCU 12-byte UID

Parameters

Address/Offset	Value/Range	Default	Description
`0xE0 ~ 0xEB`	`UID byte0~byte11`	Runtime	Corresponds to the 12-byte UID value read by `read_uid()` into `g_uid[0] ~ g_uid[11]`

4.12 Firmware Version

Address/Address Range	Length	Permission	Description
`0xFE`	`1 byte`	`R`	Reads the firmware version number

4.13 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`	`0x2F`	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 device immediately reinitializes the I²C peripheral and then uses the new address. The host should wait about `300 ms` before accessing the new address.

5. Version History

Document Version	Firmware Version	Date	Update Description
`V1.0`	`VF3`	`2025-08-06`	Initial version