Skip to content

Draft: Bebop 2 BLDC Motor Controller I2C Protocol

STATUS: first-pass draft, partly unverified. Strings-level only; see HARDWARE_REVERSE_ENGINEERING.md section 11c.

The Bebop 2 uses a Cypress PSOC-based BLDC (Brushless DC) motor controller accessible via I2C. The controller manages four brushless motors with integrated speed regulation, feedback, and safety features.

  • Device path: /dev/i2c-1
  • I2C Address: 0x08 (7-bit address)
  • Device: Cypress PSOC (Programmable System on Chip)
  • GPIO Pin: GPIO 199
  • Function: XRES (reset) signal for the PSOC controller
  • Path: /sys/class/gpio/gpio199/value
  • Control: Write 1 to reset (OFF), 0 to enable (ON)

The protocol uses a request-response pattern with I2C write-read (WR) transactions:

  • Write phase: Send command with parameters
  • Read phase: Receive response data with CRC validation
  • CRC Method: Yes (CRC validation is performed on responses)
  • Data packaging: Space-separated or binary format depending on command
Command Flag Parameters Purpose
Get Info -I --get_info None Retrieve BLDC firmware version and configuration
Start Motors -S --secure_start_motors None Start motors (auto-clears errors)
Start with Direction -D --direction_start_motors Direction bits Start motors with specific spin direction
Stop Motors -H --stop_motors None Stop all motors
Set Reference Speed -R --set_ref_speed RPM1 RPM2 RPM3 RPM4 Set target speed for each of 4 motors
Get Observed Speed -O --get_obs_speed None Read current motor speeds and status
Reverse Direction -A --rev_spin_dir None Reverse all motor spin directions
Clear Error -C --clear_error None Acknowledge and clear error flag
Command Flag Parameters Purpose
Set GPIO -G --GPIO r g p s Control BLDC GPIO pins (LED, reset, enable)
Play Sound -M --Musique m Play audio tone (m < 0 = loop, m = 0 = stop, m > 0 = once)
I2C Timeout -X --set_i2c_timeout ms Set I2C timeout (max 30000 ms)
Motor Settings Read -r --read_set ID Read motor setting by ID
Motor Settings Write -w --write_set ID VAL Write motor setting
All Settings -a --read_all_set None Read all motor settings
Command Flag Parameters Purpose
Steps -s --steps MIN INCR MAX or SPEED Speed ramping (increment/decrement)
Multisinus -m --multisinus X Multi-frequency wave centered at speed X
Chirp -b --chirp f1 f2 X A Frequency sweep (f1-f2 Hz) amplitude A
Launch -l --launch None Execute configured speed pattern
PID Monitor -p --pid None Launch pattern + monitor PID states

Observed Speed Response (from BLDC_Test_Bench -O)

Section titled “Observed Speed Response (from BLDC_Test_Bench -O)”

Format: Space-separated values

<field1> <field2> <field3> <field4> <field5> <field6> <field7> <field8> ...

Field positions (1-indexed):

  • Field 5: VBAT (battery voltage in decivolts, e.g., 95 = 9.5V)
  • Field 7: ERRNO (error number, see error codes below)
  • Field 8: FMOT (faulty motors bitmask, shows motor faults)

Full message format (verbose):

Message Vbat TicksSpeed RefSpeed ObsSpeed SatSpeed Feedforward IntegralPID PIDres PWM

Fields:

  1. Vbat: Battery voltage (decivolts, resolution 0.1V)
  2. TicksSpeed: Raw encoder ticks or speed feedback
  3. RefSpeed: Reference (target) speed
  4. ObsSpeed: Observed (actual) speed from tachometer
  5. SatSpeed: Saturation value from speed regulator
  6. Feedforward: Feedforward term (open-loop compensation)
  7. IntegralPID: Integral term of PID regulator
  8. PIDres: PID result / control signal
  9. PWM: PWM duty cycle output to motor

Simplified format (when verbose off):

Message PWM ObsSpeed Vbat
Vbat Status Errno MotFault TempCel

Fields:

  • Vbat: Battery voltage (format: “%u.%u” = integer.decimal volts)
  • Status: BLDC operational state
  • Errno: Error number (see error codes)
  • MotFault: Faulty motors bitmask
  • TempCel: Temperature in Celsius

Format: Version: 0x%x, Silicon Id: 0x%x, Silicon Rev: 0x%x

  • Provides BLDC firmware version and hardware identification
  • Format from bootloader: '%u.%u.%c.%u' (major.minor.letter.revision)
  • E_BLDC_STATUS_IDLE: Motor controller ready, motors not running
  • E_BLDC_STATUS_RUNNING: Motors are spinning
  • E_BLDC_STATUS_CRITICAL: Critical error detected
Code Meaning
0 No error (nominal)
10 Autotest LiPo failure (battery issue)
11 Autotest MOSFET failure (H-bridge failure)
Other Minor fault (detailed in MotFault field)
  • Motor stalled or low speed: Motor cannot reach target speed
  • Shock on propeller detected: Mechanical obstruction or impact
  • Communication with motor failed by timeout: I2C communication lost
  • Incorrect motor setting value: Configuration parameter out of bounds
  • Defectuous H-bridge or broken motor phases: Power driver failure
  • Motor firmware flash update failed: Bootloader error
  • BLDC temperature out of bounds: Thermal shutdown condition
  • Maximum speed: 16000 RPM (per motor constraint in code: motor_speed <= 16000)
  • Regulation mode: Two modes available
    • Closed-loop: Uses PID feedback control from tachometer
    • Open-loop: Direct PWM control (referenced as “PWM” in output)
  • Reference speed command: Set target RPM for each of 4 motors individually
  • Observed speed feedback: Read actual RPM from built-in tachometer
  • Saturation: Speed regulator output saturation (PID limit)
  • r (Red LED): GPIO control for red status LED
  • g (Green LED): GPIO control for green status LED
  • p (P7 Reset): PSOC reset pin control
  • s (Switch ENb): Enable switch for Evinrude (motor enable pin)

Format: BLDC_Test_Bench -G r g p s (each field is 0 or 1)

  • Triggered after XRES (GPIO 199) control in factory test
  • Performs firmware updates to BLDC controller
  • Validates application firmware via checksum (types 0x00 and 0x01)
  • Uses same I2C communication layer as main firmware
  • HAL_BLDC_open(): Initialize I2C connection to BLDC controller
  • HAL_BLDC_read(): Read response data from BLDC
  • HAL_BLDC_write(): Send command to BLDC
  • HAL_BLDC_write_read(): Atomic write-then-read transaction
  • HAL_BLDC_init(): Initialize BLDC subsystem
  • HAL_BLDC_set_ref_speed(): Set target speeds for motors
  • HAL_BLDC_simple_start_motors(): Start motors with default direction
  • HAL_BLDC_simple_start_motors_with_direction(): Start with specific direction
  • HAL_BLDC_secure_start_motors(): Start with auto-error-clear
  • HAL_BLDC_stop_motors(): Stop all motors
  • HAL_BLDC_get_observed_data(): Read speed and status
  • HAL_BLDC_get_observed_data_with_pwm(): Read with PWM data
  • HAL_BLDC_reverse_motors(): Reverse spin direction
  • HAL_BLDC_clear_error(): Clear error flag
  • HAL_BLDC_get_version(): Read firmware version
  • HAL_BLDC_get_rc_data(): Read RC input data (if available)
  • HAL_BLDC_play_test_note(): Play audio test tone
  • All data frames include CRC (Cyclic Redundancy Check)
  • Response validation: CRC error: Obtained: %u Computed: %u
  • Empty frame detection: Protocol checks for non-zero data length
  • I2C timeout configurable via command
  • PSOC reset timing: 100-200 ms between control transitions
  • Bootloader invocation: ~1.5 seconds for full cycle
  • 4 motors only (single unified board)
  • 7-bit I2C addressing (standard)
  • Maximum speed: 16000 RPM per motor
  • CRC validation mandatory for all responses

Factory Test Script (BLDC_Factory_Tests.sh)

Section titled “Factory Test Script (BLDC_Factory_Tests.sh)”

Performs automated tests:

  1. I2C presence check (scans for device at 0x8)
  2. Voltage monitoring (expected ~9.5V nominal)
  3. Autotest verification (battery and MOSFET health)
  4. GPIO reset control (XRES pin functionality)
  5. Bootloader invocation for firmware validation
  • i2c_cmd: Generic I2C register read/write utility
  • test-BLDC: Basic motor control test binary
  • BLDC_Test_Bench: Full-featured test and characterization tool
  • BLDC_Host_Bootloader: Firmware update utility
  • check_motors: Motor health check utility
1. HAL_BLDC_open() -> Open /dev/i2c-1, address 0x08
2. HAL_BLDC_get_version() -> Read "Version: 0xXX, Silicon Id: 0xYY, Silicon Rev: 0xZZ"
3. HAL_BLDC_get_observed_data() -> Read current motor speeds and voltage
1. HAL_BLDC_clear_error() -> Clear any prior errors
2. HAL_BLDC_simple_start_motors() -> Send start command with default CW direction
3. Poll HAL_BLDC_get_observed_data() -> Monitor speed ramp-up
1. HAL_BLDC_set_ref_speed(motor1, motor2, motor3, motor4) -> Set RPM targets
2. Poll HAL_BLDC_get_observed_data() -> Read ObsSpeed fields to verify
3. Check SatSpeed and IntegralPID to see controller effort
1. HAL_BLDC_stop_motors() -> Immediate motor stop
2. HAL_BLDC_clear_error() -> Acknowledge error if triggered
  • The protocol uses write-read I2C transactions (not separate write then read)
  • CRC validation is mandatory; implement if creating custom client
  • Timeout handling is critical for reliable communication
  • PSOC requires proper reset sequence for bootloader entry
  • Direction control uses bitmask (one bit per motor)
  • PID parameters appear tuned in BLDC firmware (not accessible via protocol)

Comments

Spotted a mistake, or tried this on your own Bebop? Leave a note. Comments are kept on this site's own server.