Draft: Bebop 2 BLDC Motor Controller I2C Protocol
STATUS: first-pass draft, partly unverified. Strings-level only; see HARDWARE_REVERSE_ENGINEERING.md section 11c.
Overview
Section titled “Overview”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.
Hardware Configuration
Section titled “Hardware Configuration”I2C Interface
Section titled “I2C Interface”- Device path:
/dev/i2c-1 - I2C Address:
0x08(7-bit address) - Device: Cypress PSOC (Programmable System on Chip)
Reset Control
Section titled “Reset Control”- 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)
Protocol Structure
Section titled “Protocol Structure”Communication Pattern
Section titled “Communication Pattern”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
Frame Format
Section titled “Frame Format”- CRC Method: Yes (CRC validation is performed on responses)
- Data packaging: Space-separated or binary format depending on command
Commands (from BLDC_Test_Bench)
Section titled “Commands (from BLDC_Test_Bench)”Motor Control Commands
Section titled “Motor Control Commands”| 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 |
Configuration Commands
Section titled “Configuration Commands”| 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 |
Testing/Speed Commands
Section titled “Testing/Speed Commands”| 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 |
Response Data Formats
Section titled “Response Data Formats”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 PWMFields:
- Vbat: Battery voltage (decivolts, resolution 0.1V)
- TicksSpeed: Raw encoder ticks or speed feedback
- RefSpeed: Reference (target) speed
- ObsSpeed: Observed (actual) speed from tachometer
- SatSpeed: Saturation value from speed regulator
- Feedforward: Feedforward term (open-loop compensation)
- IntegralPID: Integral term of PID regulator
- PIDres: PID result / control signal
- PWM: PWM duty cycle output to motor
Simplified format (when verbose off):
Message PWM ObsSpeed VbatStatus Response
Section titled “Status Response”Vbat Status Errno MotFault TempCelFields:
- 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
Version Response
Section titled “Version Response”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)
Status Values
Section titled “Status Values”BLDC State Enumeration
Section titled “BLDC State Enumeration”E_BLDC_STATUS_IDLE: Motor controller ready, motors not runningE_BLDC_STATUS_RUNNING: Motors are spinningE_BLDC_STATUS_CRITICAL: Critical error detected
Error Codes (ERRNO field)
Section titled “Error Codes (ERRNO field)”| 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) |
Detailed Error Types (from strings)
Section titled “Detailed Error Types (from strings)”- 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
Motor Speed Parameters
Section titled “Motor Speed Parameters”Speed Range
Section titled “Speed Range”- 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)
Speed Control
Section titled “Speed Control”- 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)
GPIO Control
Section titled “GPIO Control”Controllable Pins (via -G command)
Section titled “Controllable Pins (via -G command)”- 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)
Bootloader Protocol
Section titled “Bootloader Protocol”BLDC_Host_Bootloader Usage
Section titled “BLDC_Host_Bootloader Usage”- 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
Key Library Functions (from HAL_BLDC_*)
Section titled “Key Library Functions (from HAL_BLDC_*)”Core I2C Operations
Section titled “Core I2C Operations”HAL_BLDC_open(): Initialize I2C connection to BLDC controllerHAL_BLDC_read(): Read response data from BLDCHAL_BLDC_write(): Send command to BLDCHAL_BLDC_write_read(): Atomic write-then-read transaction
Motor Control Functions
Section titled “Motor Control Functions”HAL_BLDC_init(): Initialize BLDC subsystemHAL_BLDC_set_ref_speed(): Set target speeds for motorsHAL_BLDC_simple_start_motors(): Start motors with default directionHAL_BLDC_simple_start_motors_with_direction(): Start with specific directionHAL_BLDC_secure_start_motors(): Start with auto-error-clearHAL_BLDC_stop_motors(): Stop all motorsHAL_BLDC_get_observed_data(): Read speed and statusHAL_BLDC_get_observed_data_with_pwm(): Read with PWM dataHAL_BLDC_reverse_motors(): Reverse spin directionHAL_BLDC_clear_error(): Clear error flagHAL_BLDC_get_version(): Read firmware versionHAL_BLDC_get_rc_data(): Read RC input data (if available)HAL_BLDC_play_test_note(): Play audio test tone
Implementation Notes
Section titled “Implementation Notes”Frame Validation
Section titled “Frame Validation”- 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
Timing Constraints
Section titled “Timing Constraints”- I2C timeout configurable via command
- PSOC reset timing: 100-200 ms between control transitions
- Bootloader invocation: ~1.5 seconds for full cycle
Constraints and Limits
Section titled “Constraints and Limits”- 4 motors only (single unified board)
- 7-bit I2C addressing (standard)
- Maximum speed: 16000 RPM per motor
- CRC validation mandatory for all responses
Testing & Verification
Section titled “Testing & Verification”Factory Test Script (BLDC_Factory_Tests.sh)
Section titled “Factory Test Script (BLDC_Factory_Tests.sh)”Performs automated tests:
- I2C presence check (scans for device at 0x8)
- Voltage monitoring (expected ~9.5V nominal)
- Autotest verification (battery and MOSFET health)
- GPIO reset control (XRES pin functionality)
- Bootloader invocation for firmware validation
Test Tools
Section titled “Test Tools”i2c_cmd: Generic I2C register read/write utilitytest-BLDC: Basic motor control test binaryBLDC_Test_Bench: Full-featured test and characterization toolBLDC_Host_Bootloader: Firmware update utilitycheck_motors: Motor health check utility
Protocol Examples
Section titled “Protocol Examples”Initialize and Check Status
Section titled “Initialize and Check Status”1. HAL_BLDC_open() -> Open /dev/i2c-1, address 0x082. HAL_BLDC_get_version() -> Read "Version: 0xXX, Silicon Id: 0xYY, Silicon Rev: 0xZZ"3. HAL_BLDC_get_observed_data() -> Read current motor speeds and voltageStart Motors
Section titled “Start Motors”1. HAL_BLDC_clear_error() -> Clear any prior errors2. HAL_BLDC_simple_start_motors() -> Send start command with default CW direction3. Poll HAL_BLDC_get_observed_data() -> Monitor speed ramp-upSet Speed and Monitor
Section titled “Set Speed and Monitor”1. HAL_BLDC_set_ref_speed(motor1, motor2, motor3, motor4) -> Set RPM targets2. Poll HAL_BLDC_get_observed_data() -> Read ObsSpeed fields to verify3. Check SatSpeed and IntegralPID to see controller effortEmergency Stop
Section titled “Emergency Stop”1. HAL_BLDC_stop_motors() -> Immediate motor stop2. HAL_BLDC_clear_error() -> Acknowledge error if triggeredFuture Implementation Considerations
Section titled “Future Implementation Considerations”- 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.