Bebop/BLDC

== General ==
The BLDC of the Bebop is the Brushless Driver Controller that controls all 4 brushless motors from the Bebop. Motors are 12 permanent magnets. This BLDC contains a closed loop Rotation Per Minute (RPM) controller, and also reads out the battery voltage.
== Default LED behavior ==
* Green LED blinking: bootloader mode.
* Green LED fixed: nominal mode.
* Red LED blinking: critical mode (error code: 10 or 11)
* Orange LED fixed: minor error detected.
== Sounds signification ==
* Each motor makes a single tone after a successful init of the firmware.
* No sound after the init: critical failure detected during the init.
* All motors tone in infinite loop after a error detection. Use the command CLEAR_ERROR or PLAY_SOUND 0 for stopping.
== BLDC Protocol ==
BLDC is an i2c slave device. Its 7-bits slave address is 0x08.
* 0x02 SET_REF_SPEED
* 0x20 GET_OBS_DATA
* 0x40 START_PROP
* 0x4D TOGGLE_GPIO
* 0x60 STOP_PROP
* 0x80 CLEAR_ERROR
* 0x82 PLAY_SOUND
* 0xA0 GET_INFO
=== START_PROP (0x40) ===
Starts all propellers. The propellers will not start when the current error is not cleared. Motors ramp together, spin together, stop together. It's not possible to spin motors separately.
Optional argument:1 byte
* 0: Motor bitmask (0000ABCD, A:Left Upper, B:Right Upper, C: Right Back, D: Left Back) where 1 is clockwise and 0 is counterclockwise
Receive: 0 byte
=== SET_REF_SPEED (0x02) ===
Sets the RPM reference of the motors. This request is ignored while START_PROP has not been sent and accepted.
Arguments: 10 bytes
* 0-1: RPM reference Left Front motor (uint16)
* 2-3: RPM reference Right Front motor (uint16)
* 4-5: RPM reference Right Back motor (uint16)
* 6-7: RPM reference Left Back motor (uint16)
* 8: Reserved (0x00)
* 9: Checksum (see section bellow)
Receive: 0 byte
=== GET_OBS_DATA (0x20) ===
Gets the observed data from the motors and battery.
Arguments: 0 byte
Receive: 15 bytes
* 0-1: RPM observed Left Front motor (uint16)*
* 2-3: RPM observed Right Front motor (uint16)*
* 4-5: RPM observed Right Back motor (uint16)*
* 6-7: RPM observed Left Back motor (uint16)*
* 8-9: Battery voltage in mV (uint16)
* 10: Status (uint8)
* 11: Errno (uint8)
* 12: bitmask of motors in fault (uint8)
* 13: Temperature in degrees Celcius (uint8)
* 14: Checksum (see section below)
* Bit 15 is reserved for detecting maximum RPM (depending on voltage and altitude)
==== Status ====
is the combination of two uint4 words:
* The first uint4 saves the state of the system state machine when an error occurred.
* The second uint4 indicates the current state of the system state machine.
Values of the state machine are:
* 0: Init system
* 1: System in idle (waiting for the START_PROP command)
* 2: Ramping motors
* 3/4: Spinning motors
* 5: Stopping motors
* 6: System aborted (critical error)
==== Errno ====
Error values are set in order of importance: if two errors occurred, the most important error smashes the less important.
* 0: No error
* 1: EEPROM corruption
* 2: Motor stalled*
* 3: Propeller security*
* 4: Communication lost
* 9: Battery voltage too low
* 10: Incorrect number of LIPO cells
* 11: Unplugged motor or broken motor phase or defectuous MOS*
* Impacted motors information is given in byte12 as bitmask (0000ABCD, A:Left Upper, B:Right Upper, C: Right Back, D: Left Back) where 1 is fault and 0 is no fault.
=== TOGGLE_GPIO (0x4D) ===
Toggle GPIO outputs. The reset will put the BLDC into bootloader mode.
Arguments: 1 byte
* 0: GPIO bitmask (bit 0: Reset, bit 1: Red LED, bit 2: Green LED)
Receive: 0 bytes
=== STOP_PROP (0x60) ===
Stop the propellers when turning.
Arguments: 0 bytes
Receive: 0 bytes
=== CLEAR_ERROR (0x80) ===
Clear the current error.
Arguments: 0 bytes
Receive: 0 bytes
=== PLAY_SOUND (0x82) ===
Play a sound. A negative number will loop the sound.
Arguments: 1 byte
* 0: Sound number (0: None, 1: Short beep, 2: Boot beep, 3: Be-Bop-Ah-Lula, negative: repeat) (int8)
Receive: 0 bytes
=== GET_INFO (0xA0) ===
Get information about the BLDC.
Arguments: 0 bytes
Receive: 4 bytes or 13 bytes
* 0: Software version (major)
* 1: Software version (minor)
* 2: Software type (ascii code)
* 3: Number of motors controlled
* 4-5: Number of flights (uint16)
* 4-5: Time last flight (uint16)
* 6-9: Full flight time (uint32)
* 10: Last error code
== Checksum ==
For all the packets with arguments or where we receive bytes there is a checksum byte at the end. This checksum is a simple XOR algorithm including the first command byte.
// Credits to Christophe De Wagter for figuring out the Checksum
checksum = CMD_BYTE;
for(int i = 0; i < packet_size; i++)
 checksum = checksum ^ packet[i];
== Bootloader Protocol ==
When the chip is powered on or reseted, the bootloader is started. Green LED is blinking. See the Cypress bootloader protocol documentation AN60317 or use the embedded tool BLDC_Host_Bootloader for flashing a new firmware or leaving the bootloader mode and launching the applicative firmware. Use the PSoC Creator 2.2 (or a more recent version) for creating your own cyacd files. Compile your bootloadable (applicative) project with the hex and elf files of the bootloader project (not given). Use the Miniprog3 for flashing your own bootloader application.
=== BLDC_Host_Bootloader === 
Optional arguments: new_firmware.cyacd backup_firmware.cyacd
Default behavior when no arguments are given:
* new_firmware.cyacd is /lib/firmware/BLDC.cyacd
* backup_firmware.cyacd is /lib/firmware/.BLDC.cyacd
Behavior:
If new_firmware.cyacd is present it will used to be flashed in the microcontroler. Once successfully flashed, the file will be renamed into backup_firmware.cycad. Backup file is used for fixing firmware flash corruption or restoring firmware after a flashling failure with (incorrect firmware, process aborted, etc).
If new_firmware.cyacd is not present: nothing to flash. The bootloader will quit and launch the applicative firmware.
Applicative firmware is launched if and only if no flash corruptions have been found, else the bootloader never leaves.
=== Reseting the chip ===
Toggle the \xres io will get the chip reseted and forced it to jump in bootloader mode.
echo 1 > /sys/class/gpio/gpio199
echo 0 > /sys/class/gpio/gpio199
== BLDC Test Bench ==
This tool is used for testing motors with different kind of velocity reference inputs. Kill the Bebop software before calling it. Use the -h for displaying the help.
Cvs file is created in /tmp and can be post processed with Scilab.
Note: due to memory usage limitation in the microcontroler, motor settings and velocity regulator settings cannot be changed or read.