Bebop 2 (fw 4.7.1) flight control law: static analysis notes
Scope: controller side only (setpoints, loop structure, gains, saturation, mixing, flight modes). BLDC I2C protocol and the Kalman estimator are out of scope. Ghidra on port 8192 was only read from. Everything else came from the shell (llvm-objdump on dragon-prog, strings, config files). No firmware was executed.
Labels: EVIDENCE = directly observed (file plus address or string). INFERENCE = my interpretation. Rootfs prefix below is .../firmware/extracted/bebop-2-4.7.1/rootfs, shortened to rootfs/.
0. Headline corrections to what was assumed
Section titled “0. Headline corrections to what was assumed”-
libCondor.so is NOT part of flight control. EVIDENCE:
rootfs/usr/lib/libCondor.so(114 KB) exportscondor::Engine::setAttitude(float x6)@0xa0ec,Engine::setCamera2gc,setCameraGain,setPrediction,getTranslation, plusviz::warp,viz::Pyramid_*,viz::sobel_*,condor::Prediction,condor::AdaptiveFrameRateFSM,DumpWriter/DumpReader(attitude dump files). It is a vision/image-motion library (camera attitude fed into image warping and translation estimation, i.e. video stabilisation / vision odometry). INFERENCE: thesetAttitudethunk at dragon-prog 0x33b30 hands the estimated drone attitude to that vision engine, it does not command anything. It contains no PID, gain, motor or mixer strings (grep of strings for pid/gain/thrust/motor/hover/tilt/speed/mix found onlysetCameraGain). -
The control law lives in dragon-prog itself (the “Colibry” framework, C++ with Eigen), configured by text files in
rootfs/etc/colibry/. EVIDENCE: dragon-prog strings (gainsQuaternionSet,QuadMixRPMController,BLDCMotorController, …) match the cfg keys one for one, and/etc/colibry/common/root.cfgand/etc/colibry/%s/root.cfgare loaded by dragon-prog (strings). The flying-state machine classes are in namespaceMykonos3(RTTIN8Mykonos3...ControlState*), the generic nodes areColibry::*. Mykonos3 is just the internal codename, the build isro.build.alchemy.variant=milos. -
Which cfg set applies to the Bebop 2:
rootfs/etc/build.propsaysro.parrot.build.variant=milos(uidardrone3-milos-4.7.1).etc/boxinit.standalone.milosboard.rcandetc/default.milosboard.propexist. INFERENCE (high): the active tree isetc/colibry/common/*.cfgoverlaid byetc/colibry/milosboard/*.cfg(milosboard/root.cfg includes../drone.cfg ../controller.cfg ...). Only the milosboardcontroller.cfg,drone.cfg,estimator.cfg,helper.cfg,event.cfgdiffer from common. Notemilosboard/event.cfgturns flyawayDetectionActive on and sets altGroundDetectThreshold 0.7. -
A second autopilot exists:
rootfs/etc/boxinit.d/50-arducopter.rcdefines anarducopterservice (MAVLink over UDP 14550/14551, serial /dev/ttyPA1) markeddisabled, andusr/bin/arducopter.shexecs/usr/bin/arducopteror a user-supplied/data/ftp/internal_000/ardupilot/arducopter. Thearducopterbinary is NOT in this rootfs. EVIDENCE for that:ls rootfs/usr/bin/arducopter*returns only the .sh. So the stock flight controller is Colibry, and ArduPilot is an optional sideload.
1. Architecture of the control chain
Section titled “1. Architecture of the control chain”1.1 Node list (EVIDENCE)
Section titled “1.1 Node list (EVIDENCE)”Strings at dragon-prog 0x4bd8cc..0x4bdb08 are the controller node names, in registration order: QuadQuaternionLoopController, QuadSpeedLoopController, HeightLoopController, QuadMixRPMController, QuadAngleInputController, (AngleRef), QuadAngleFeedforwardController, QuadHeightInputController, QuadHeightRefController, QuadEventDetectionController, QuadPositionRefController, QuadPositionLoopController, QuadObstacleAvoidanceController, VideoAngleInputController, (VideoAngleRef), DemoTrajectoryRefController, FollowMeTrajectoryRefController, BLDCMotorController, PWMMotorController. They are all referenced from the config singleton constructor FUN_001536d4 (singleton getter FUN_001036a8), at e.g. 0x1539fc for QuadMixRPMController.
Exported Colibry symbols: droneAngleRef, videoAngleRef, QuadAngleRefController::initConfig @0x28eca8, ESCMotorModel::Estimator vtable @0x579be8, BLDCMotorController vtable @0x57a000, PWMMotorController vtable @0x579fb8, ACQCON_colibry_Thread_Handler @0x4dd18.
Telemetry names (EVIDENCE, dragon-prog strings) give the signal chain: control.eulerAnglesRef.0..2, control.angularVelocityRef.0..2, control.angularAccelerationRef.0..2, control.weightAccelerationRefBody/NED, control.altitudeAccelerationRefBody/NED, control.altitudeRef, control.verticalVelocityRef, control.linearPositionRef.*, control.linearVelocityRefNED.*, control.linearAccelerationRefNED.*, control.uSat.0..5 (six saturated commands), control.motorsCommandsRPM.0..3, control.motorsCommandsPWM.0..3, flag commandsAreSaturated.
1.2 Cascade (INFERENCE from node names, telemetry names and gain units)
Section titled “1.2 Cascade (INFERENCE from node names, telemetry names and gain units)”position loop (QuadPositionLoopController) -> speed loop (QuadSpeedLoopController, outputs a tilt angle: gains are in rad per m/s) -> attitude loop (QuadQuaternionLoopController, quaternion error PID plus derivative-of-rate term, outputs angular acceleration in rad/s^2, which is what [s-2] on KP means) -> QuadMixRPMController (turns angular accelerations plus a thrust acceleration into four motor RPMs) -> BLDCMotorController (sends RPM to the BLDC board). Altitude is a parallel chain: HeightLoopController outputs a thrust specific force in m/s^2.
EVIDENCE for units: controller.cfg comments, e.g. thetaKP [s-2], speed gains [rad.m-1.s], height commands [m/s2].
An “ideal model” reference generator sits between user references and the loops. EVIDENCE: reference.cfg has idealModel_A_tilt (3x3), idealModel_B_tilt, idealModel_A_psi (6x6), idealModel_B_psi, gainQuatIdealModelTiltAngle/Rate/Acc/Jerk, gainIdealModelHeight/SpeedZ/MotorSpeed/MotorAcc, maxAttitudeIdealCommand, maxHeightIdealCommand (85 percent of total max command). The ideal-model A matrices are discrete state transitions with dt 0.005 s (EVIDENCE: idealModel_A_psi has 0.005 on the superdiagonal), so the reference trajectory runs at 200 Hz.
INFERENCE: the controllers are a feedforward from an ideal (trajectory) model plus feedback PID on the error, which is why there is also QuadAngleFeedforwardController and an efficiency*/ffLoss* feedforward in controller.cfg.
1.3 Loop rate (EVIDENCE)
Section titled “1.3 Loop rate (EVIDENCE)”milosboard/root.cfg: adcFsSet default 198.3642578125 Hz (simulator 200 Hz). Cfg comment says runtime Ts = adcTs/adcFs. So the whole Colibry cycle is about 200 Hz, tied to IMU/ADC sampling. Filters in reference.cfg (“Butterworth order 2, Fc 5, Fs 200”) agree.
2. Gains, limits and constants (Bebop 2 effective values)
Section titled “2. Gains, limits and constants (Bebop 2 effective values)”All EVIDENCE (cfg files). “MB” = etc/colibry/milosboard/, “C” = etc/colibry/common/. MB overrides C where both exist.
2.1 Attitude loop (MB/controller.cfg gainsQuaternionSet)
Section titled “2.1 Attitude loop (MB/controller.cfg gainsQuaternionSet)”Set “Default” (the others in brackets):
- theta (pitch): KP 264.7408, KI 264.7408, KD 33.0926, KDD 0.5295
- phi (roll): KP 242.5376, KI 242.5376, KD 30.3349, KDD 0.4879
- psi (yaw): KP 300.0, KI 0.0, KD 30.0, KDD 0.0
- “Flip”: same theta and phi, psi all zero (yaw loop off during a flip)
- “Rescue”: same theta and phi, psi KP 0, KI 0, KD 11.0
Units from cfg comments: KP [s-2], KI [s-3], KD [s-1], KDD dimensionless. The common/ set (theta/phi KP 140, KI 140, KD 15; psi 50/10/11) is NOT used on the Bebop 2 because MB overrides it. It is probably the chimera/other board value.
Other attitude values (C/controller.cfg):
quatControlMaxIntegral = [1500, 1500, 20]rad/s^2,quatControlResetIntegral=false,enableAerodynamicTorqueCompensation=[true,true,false](roll, pitch, yaw),rpmMaxAttitudeCommandSetDefault [273,273,273] rad/s^2 and Flyaway [273,273,9] (yaw command pinned small during emergency landing after flyaway),rpmMaxYawCommand 60,rpmMinForControl 6.1920m/s^2,efficiencyLossVz=[-0.03,-0.03,0]. Reading of the structure: INFERENCE that the KI = KP equality on pitch and roll means integral time of 1 s, and KDD is a feedforward on angular acceleration. Not verified in code.
2.2 Altitude (C/controller.cfg, no MB override)
Section titled “2.2 Altitude (C/controller.cfg, no MB override)”ctrlGainAltitudeSet: Default kp 4.170, ki 1.158, kd 5.800 (units s-2, s-3, s-1). “Freefall” kp 2.0, ki 0, kd 15.01. “Throttle” all 0 (open loop manual throttle state).
Limits: heightCommandMax 23.5536 m/s^2, heightFeedforwardCommandMin 1.6529, heightFeedforwardCommandMax 15.5230, maxHeightIntegralCommand 1.1777, heightCommandCompensationMax 2.0, maxThrottleUserCommand 9.81, RpmFfMaxForTakeOff 15.5230, take-off slopes 0.08 and 0.08 with minAltitudeCommandeForSecondSlope 9.6750, ffLossForFlip 5.8, ffLossSlopeForFlip 0.3, motorsCommandsSlopeForBraking [24400 x4] RPM/s, emergencyLandingParameters: timeStepToCheckGPSAltitude 20, timeStepToReduceHeightFF 60, ffwdCmdHeight [8.83, 8.06, 6.86, 3.0] m/s^2.
2.3 Position and speed (C/controller.cfg)
Section titled “2.3 Position and speed (C/controller.cfg)”- ctrlGainPosition kp 0.8, ki 0, kd 1.6 (same for GPS); Carpet (optical flow) kp 3.0, ki 0.4, kd 3.0;
maxPositionIntegral 10(times DEG_TO_RAD times g). - ctrlGainSpeed kp 0.2612, ki 0.1606, kd 0 (rad per m/s).
speedLoopSaturationSpeed 1.0m/s.maxSpeedIntegral: MB [11.6667, 11.6667] deg (C has [10,10]). - ctrlGainCylinderRestriction kp 0.17, ki 0, kd 0.15.
2.4 Reference limits (C/reference.cfg)
Section titled “2.4 Reference limits (C/reference.cfg)”- Tilt:
angleRefMaxUser [35,35]deg, “Flying” [35,35], “Flip” [1000,1000], “Flyaway” [10,10]. User-selectableusrConfigMaxTilt 15.0deg default (the ARSDK MaxTilt setting,ARDrone3.max_tiltstring).angleSaturationSpeed 5,angleDesaturationSpeed 2deg/s,angleSaturatedMin 20,speedMinForAngleSaturation 3m/s. - Rates:
usrConfigMaxAngularRateRefFlying 300deg/s,usrConfigRotationSpeed 180deg/s (ARSDK MaxRotationSpeed default),maxRRefSet User 235,swipeRotationSpeed 180,maxAngularRateRefGotofix 200. - Vertical:
usrConfigVerticalSpeed 1.0m/s default,maxVerticalSpeed 6.0,minVerticalSpeedUser -6.0, “Default” min vertical speed -2.0,maxVerticalAccelerationForFlying 6,...ForTakeoff 2,...ForFlip 6,maxVerticalSpeedForHeightStepTakeoff 1.0,landingSpeedSet Normal 1.1 / Fast 2.0m/s,altitudeForSlowLanding 4.0,takeOffHeightSet default 1.0 (fvt 1.5)m,minAltitude 0.5,usrConfigMaxAltitude 1000,usrConfigMaxThrottle 1.0g. - Horizontal:
maxHorizontalSpeed 12,maxHorizontalAcceleration 3,userCommandFilterB [0.14961, 0.14961, 0],A [1, -0.90599, 0.2052](second-order low-pass on the stick input). - Flight plan:
speedToReturnHome 8,minHeightToReturnHome 20,mk3GeneralSettings velocityMax 10, verticalVelocityMax 2.5, accMax 2, jerkMax 4.
2.5 Physical model used by the mixer (MB/drone.cfg motorsParameters)
Section titled “2.5 Physical model used by the mixer (MB/drone.cfg motorsParameters)”- mass 0.500 kg; Jx 0.001491, Jy 0.001458, Jz 0.003328 kg m^2
- motorsRpmMax 12200 x4, motorsRpmMin 3000 x4 (RPM)
- motorA 2.15e-8 x4 (N per RPM^2, thrust coefficient)
- motorB [-2.85e-10, +2.85e-10, -2.85e-10, +2.85e-10] (N m per RPM^2, reaction torque, sign gives spin direction)
- motorJp 7.94e-6 (rotor inertia), motorAlpha 0, motorBeta -pi/2 for all four (thrust axis orientation angles, see 3.3)
- motorX [+0.0875, +0.0875, -0.0875, -0.0875] m, motorY [-0.115, +0.115, +0.115, -0.115] m, motorZ 0
- rpmErrorMargin 1.0 RPM
motorsCommandOutputType "RPM",motorsSpeedObservation "AVAILABLE"(so RPM feedback from the BLDC is used; the PWM model blockpwmMotorsModelis zeroed/unused exceptmotorsKv 1630).- Other:
motorOmega0 90 rad/s,motorSigma 0.9, dragCxShell 0.35, CyShell 0.40, CzShell 0.9, Cr 0.5s^-1 (NoShell values identical).
2.6 Numeric cross-check that the throttle unit is “specific thrust”: 4Aw^2/m (INFERENCE, strong)
Section titled “2.6 Numeric cross-check that the throttle unit is “specific thrust”: 4Aw^2/m (INFERENCE, strong)”Using mass 0.5 and A 2.15e-8, w = sqrt(a*m/(4A)) turns cfg thrust accelerations into round RPM figures:
| cfg constant (m/s^2) | RPM |
|---|---|
| rpmMinForControl 6.1920 | 6000.0 (= 2 x motorsRpmMin) |
| heightFeedforwardCommandMin 1.6529 | 3100 |
| heightFeedforward Max / RpmFfMaxForTakeOff 15.5230 | 9500 |
| minAltitudeCommandeForSecondSlope 9.6750 | 7500 |
| minThrustForTakeoffDetection 8.3080 (states.cfg) | 6950 |
| heightCommandMax 23.5536 | 11702 (about 96 percent of 12200) |
| hover, 9.81 | 7552 |
| Derived figures: max thrust at 12200 RPM is 12.80 N (25.6 m/s^2, thrust-to-weight 2.61), min thrust at 3000 RPM is 1.55 N total. Yaw torque to thrust ratio B/A is 0.01326 m. This exactness means the cfg’s m/s^2 thrust values are converted with exactly this quadratic model, and the cfg in the firmware was authored in RPM and expressed as accelerations. |
3. Where setpoints become per-motor speeds (the mixer)
Section titled “3. Where setpoints become per-motor speeds (the mixer)”3.1 Location (EVIDENCE)
Section titled “3.1 Location (EVIDENCE)”QuadMixRPMController::processequivalent: dragon-prog function at 0x2a6e98 (ARM, ends about 0x2a78ac, cold paths at 0x2a7440..0x2a7780). Ghidra 8192 does not have it defined as a function (decompile returns FUNCTION_NOT_FOUND), so I read it withllvm-objdump -d --triple=armv7 usr/bin/dragon-prog(disassembly saved at.../scratchpad/dp.dis).- Config reader for it: 0x2a63b0. It reads exactly these keys of
motorsParameters: mass (0x2a63e4), motorsRpmMax (0x2a6594), motorsRpmMin (0x2a6608), motorA (0x2a667c), motorB (0x2a66f0), motorJp (0x2a6764), motorAlpha (0x2a67d8), motorBeta (0x2a684c), motorX (0x2a68c0), motorY (0x2a6934), motorZ (0x2a69a8), rpmErrorMargin (0x2a6a1c). - Allocation-matrix builder: 0x2a78d0. It calls
sincosfon per-motor angles at config offsets +96 and +112 (the motorAlpha and motorBeta arrays) and builds a 4-column matrix with multiplies of X, Y, A, B per motor. Follow-up code at 0x2a8270 / 0x2a899c / 0x2a8b04 (writes r4+372) / 0x2a8dc4 (writes r4+436) computes a pseudo-inverse (Eigen householder,sqrtfuse at 0x2a9144..0x2a91b8) into the matrix the runtime function uses. - Final conversion to the HAL: the 4 floats are truncated to 16-bit unsigned and stored at 0x4177ec:
vldmia ... vcvt.s32.f32 ... strhx4. EVIDENCE: that function copies four floats into a uint16[4] buffer with no saturation of its own. The matching reset at 0x41762c zeroes four uint16. INFERENCE: this is the Data conversion betweencontrol.motorsCommandsRPM(float[4]) andHAL_BLDC_motor_command_t(type name present in strings), after which HAL_BLDC_mykonos3_write calls HAL_BLDC_set_ref_speed (string at 0x508520).
3.2 What the runtime function does (EVIDENCE from disassembly, interpretation in INFERENCE tags)
Section titled “3.2 What the runtime function does (EVIDENCE from disassembly, interpretation in INFERENCE tags)”- Builds a 6-element command vector v at output buffer
[r4+0x50]from the input pointers:- v0 = minus *in(r4+0x14) (negated, i.e. NED up is negative)
- v1 = in(r4+0x0c)[0], v2 = in(r4+0x0c)[1], v4 = in(r4+0x0c)[2] (three consecutive floats from one input struct)
- v3 = minus (in(r4+0x10)[0] minus in(r4+0x14)[0])
- v5 = minus in(r4+0x18)[0]
INFERENCE: v1, v2, v4 are the three angular-acceleration commands (control.angularAccelerationRef.0..2) and v0 is the thrust acceleration. v3 and v5 are two further body-frame terms that I could not name (open question). This matches
control.uSat.0..5having six entries.
- Thrust channel: for each motor i,
w_i = sqrtf( (-in14) * c_i / s )where c_i are four precomputed constants at r4+372..384 and s is a scalar read through[r4+0x1c]. Written to r4+84, 88, 92, 96. INFERENCE: this is the nonlinear hover/feedforward RPM per motor from the quadratic thrust law (consistent with 2.6). - Each of the other channels k (1..5) contributes a 4-vector
v_k * M[k][i]at r4+100+16(k-1)… using coefficient rows at r4+436..500. Channels 3 and 5 are divided by[r4+0x1c], the others are not. Contributions are stored at r4+100.., 116.., 132.., 148.., 164.. (four floats each). - Per motor i:
w_i = base_i + sum over channels of contribution. For motor 0 these are the floats at r4+84,100,116,132,148,164; motor 1 at +88,104,120,136,152,168; motor 2 +92,108,124,140,156,172; motor 3 +96,112,128,144,160,176. Result stored at r4+596..608. - Clamp: each w_i is clamped to
[lo_i, hi_i]with lo from[r4+0x40] + 32..44and hi from[r4+0x24]+ 0..12 (INFERENCE: motorsRpmMin / motorsRpmMax, 3000 and 12200). - Saturation handling (loop at 0x2a7148..0x2a72fc, up to 99 iterations, counter starting at 5): if a motor violates its bounds, the code removes or scales channel contributions starting from the highest channel index, using a
vdivof the remaining headroom over the offending contribution (INFERENCE: the standard “priority-based desaturation”: thrust channel 0 is never reduced, then channels dropped in order 5, 4, 3, 2, 1, with partial scaling on the channel that crosses the bound). INFERENCE for what that means physically: if yaw is channel 4 and the extra terms are 3 and 5, then yaw is sacrificed before roll and pitch, matching the cfg’s “Flyaway” yaw clamp to 9 and the general quad practice. This role assignment is unverified. - After clamping it writes the four final speeds to output buffer
[r4+0x34]and then post-processes the residual for the sixuSatoutputs and thecommandsAreSaturatedflag (0x2a74b8 onward, partially read only).
3.3 Mixing matrix: what can and cannot be said
Section titled “3.3 Mixing matrix: what can and cannot be said”The firmware mixer is not a hard-coded +/-1 table. It is a model-based control allocation built at start-up from motorX/Y/Z, motorAlpha/Beta, motorA, motorB and motorJp, pseudo-inverted, and applied as a linear increment on top of a sqrt thrust term, with priority desaturation. EVIDENCE: sections 3.1 and 3.2.
What the geometry in the cfg implies (INFERENCE, arithmetic from the cfg):
- Layout is a rectangular X, not a square: |x| 0.0875 m, |y| 0.115 m, arm length 0.1445 m, angle from the body x axis 52.7 degrees. So roll authority per newton is larger than pitch authority (arm 0.115 vs 0.0875) while Jx and Jy are nearly equal (0.001491 vs 0.001458).
- Spin pairs: motorB signs are (-, +, -, +), so motors 0 and 2 (diagonal) share one direction and motors 1 and 3 share the opposite one. That is a normal quad with diagonally paired directions. This confirms the standard X topology assumption at the level of “diagonals match”, EVIDENCE for the sign pattern, INFERENCE for the conclusion.
- Motor numbering by position, treating +x as forward: motor 0 at (+0.0875, -0.115), motor 1 at (+0.0875, +0.115), motor 2 at (-0.0875, +0.115), motor 3 at (-0.0875, -0.115). So 0 and 1 are the front pair, 2 and 3 the rear pair, 0 and 3 share y = -0.115, 1 and 2 share y = +0.115. Whether +y is the drone’s right (FRD body frame, which is what Colibry uses elsewhere: NED,
-in14for up) or its left is NOT proven. INFERENCE only: under FRD, motor 0 front-left, 1 front-right, 2 rear-right, 3 rear-left. I recall from public Parrot material that Bebop motor 1 is front-left, which would match, but I cannot cite it from this rootfs. - Static (small-signal) inverse implied by that geometry, ignoring Jp, alpha, beta and motor dynamics, in FRD with thrust T = sum of per-motor thrusts, roll torque tau_x, pitch torque tau_y, yaw torque tau_z, per-motor thrust F_i:
F_i = T/4 - sign(y_i) * tau_x / (4*0.115) + sign(x_i) * tau_y / (4*0.0875) + sign(B_i) * tau_z / (4*0.01326), thenw_i = sqrt(F_i / 2.15e-8). Torque sign convention for B (whether positive B means a positive or negative body yaw reaction) is not established by the cfg. So the yaw sign in this table is unverified. The roll and pitch signs follow from r x F with up = -z. As a mixing table (rows motors 0..3, columns T, roll, pitch, yaw; sign is the sign of that motor’s thrust change for a positive tau_x, tau_y, tau_z), INFERENCE: motor 0 (+, +, +, -), motor 1 (+, -, +, +), motor 2 (+, -, -, -), motor 3 (+, +, -, +). Positive tau_x (roll right) raises the y < 0 side (motors 0 and 3). The yaw column assumes positive B means positive tau_z, which is unverified. The real firmware matrix additionally carries beta = -pi/2 and the rotor inertia term Jp, which I did not decode, so treat the table as the first-order picture only.
3.4 Output limits and the 16000 RPM figure
Section titled “3.4 Output limits and the 16000 RPM figure”- Controller side limit: motorsRpmMax 12200 and motorsRpmMin 3000 (EVIDENCE, cfg). The 16000 RPM number in the brief is the BLDC board’s own ceiling for set_ref_speed (given in the brief, not found in my scope). INFERENCE: the controller never asks for more than 12200 because the mixer clamps to motorsRpmMax, so the board limit is a safety net only.
- Rate limit when stopping:
motorsCommandsSlopeForBraking [24400 x4]RPM/s (EVIDENCE cfg), used by the WaitMotorBraking state. - Start-up: the BLDC performs its own ramp (strings
_is_BLDC_starting_up_motors(): motors start-up velocity ramp refused,...Timeout when waiting the end of the motors starting-up ramp,E_BLDC_STATUS_RAMPING). dragon-prog has aWaitMotorRampingstate that waits for the ramp to end. - Safety errors reported from the board (strings): E_BLDC_ERR_PROPELLER_SECURITY, E_BLDC_ERR_MOTOR_STALLED, E_BLDC_ERR_BATTERY_VOLTAGE, E_BLDC_ERR_LIPO_CELLS, E_BLDC_ERR_TEMPERATURE, E_BLDC_ERR_COMM_LOST, E_BLDC_ERR_H_BRIDGE, E_BLDC_ERR_MOSFETS, E_BLDC_ERR_EEPROM, E_BLDC_ERR_ASSERT, E_BLDC_BROWNOUT. A spin-direction facility exists (
motors_spin_dir <= 15,Bad motors_spin_dir value,HAL_BLDC_reverse_motors,HAL_BLDC_start_motors_with_direction), where the value is a 4-bit field (one bit per motor). The parser using it, FUN_00042688 @0x42688, is the command-line option handler, so spin direction is a startup parameter, not set per control cycle. I did not decode the bit meaning (BLDC protocol agent scope).
4. Flight modes and states
Section titled “4. Flight modes and states”4.1 State machine (EVIDENCE)
Section titled “4.1 State machine (EVIDENCE)”RTTI classes Mykonos3::ControlState*: Init, Landed, Takeoff, TakeoffGround, TakeoffFlying, WaitMotorRamping, WaitThrownTakeoff, Flying, FlyingThrottle, Hovering, HoveringGps, HoveringRescue, GoToFix, Flip, Landing, LandingFlying, LandingGps, Emergency, EmergencyLanding, WaitMotorBraking, MagnetoCalibration, NavGps, ReturnHome, RelativeNavigation, FollowMe, LookAtMe, PilotedPOI, WallLock, DemoMagicCarpet, Animation. Estimator states: Init, RunningFlying, Error. Events are routed by EventsFsm (strings: “controller event: %s(%d)”, “EventsFsm: No transition from current state!”). Flying-state events reported to the app are the COLIBRY_EVENT_MSG_NEW_FLYINGSTATE_* family (LANDED, TAKEOFF_GROUND, MOTOR_RAMPING, HOVERING, FLYING, FLYING_THROTTLE, LANDING, EMERGENCY, EMERGENCY_LANDING, WAIT_THROWN_TAKEOFF, MAGNETO_CALIBRATION, DISCONNECTION, INIT, UNKNOWN).
4.2 Gain and limit sets switch per state (EVIDENCE: the “Set” structures)
Section titled “4.2 Gain and limit sets switch per state (EVIDENCE: the “Set” structures)”The cfg sets (gainsQuaternionSet Default/Flip/Rescue, ctrlGainAltitudeSet Default/Freefall/Throttle, angleRefMaxSet Flying/Flip/Flyaway, rpmMaxAttitudeCommandSet Default/Flyaway, gainQuatIdealModelYawSet User/Flightplan/FollowMe/WallLock/Demo/Animation, maxPsiRefSet, maxRRefSet, minVerticalSpeedSet, landingSpeedSet) are selected by an init-value variable each (the first string of each set, e.g. “gainsQuaternionSetInitValue”). INFERENCE: the active state machine selects the set name.
4.3 Stabilised vs manual unstabilised
Section titled “4.3 Stabilised vs manual unstabilised”EVIDENCE: FlyingThrottle state with ctrlGainAltitudeSet Throttle (all zeros): altitude loop is open, the user stick sets thrust directly, capped by maxThrottleUserCommand 9.81 m/s^2 and usrConfigMaxThrottle (1.0 g default, colibry_setUserConfigMaxThrottleCommand). The attitude loops still run in that state (the quaternion set stays Default). INFERENCE: this is what the brief calls manual unstabilised for altitude only. The brief’s getManualFlightUnstabilized @0x00100400 is a flight-plan/MAVLink-side function I did not trace. I cannot say from the cfgs that any state disables the attitude loop, the only state that zeroes the yaw loop is Flip (psi gains 0), and the Rescue set zeroes yaw P and I. I did not find a mode with the attitude loop off.
4.4 Take-off (EVIDENCE cfg and strings)
Section titled “4.4 Take-off (EVIDENCE cfg and strings)”Sequence: TakeoffGround -> MotorRamping (BLDC start ramp) -> feedforward thrust ramp (altitudeCommandFirstSlope 0.08, ...SecondSlope 0.08, RpmFfMaxForTakeOff 15.523, initFeedforwardForTakeoff) until takeoff is detected (minThrustForTakeoffDetection 8.308 m/s^2, takeOffDetectionAcceleroThreshold -10, takeOffDetectionAcceleroCount 10, takeoffDetectionPressureMinHeight 1.0; string “Takeoff ground detected by feedForwardReachedMaxValue” means the ramp hitting its cap also ends the phase), then TakeoffFlying to takeOffHeightSet default 1.0 m (exit at takeOffHeightToExitTakeoff 95 percent of height input), maxVerticalAccelerationForTakeoff 2, maxVerticalSpeedForHeightStepTakeoff 1.0. Thrown take-off: WaitThrownTakeoff, waitForThrowTimeout 10 s, tooMuchAngle ThrownTakeoff 150 deg, freefall* detection (entry < 2 m/s^2 for 40 ms, exit > 4.9 m/s^2 for 25 ms, shock 20 m/s^2).
4.5 Landing (EVIDENCE)
Section titled “4.5 Landing (EVIDENCE)”landingSpeedSet Normal 1.1 m/s, Fast 2.0 m/s, altitudeForSlowLanding 4.0 m, minVerticalSpeedPercentageForLanding 0.8. Ground detection variants (strings): “Ground detection for Landing with Accelero/Gyro”, “…with GPS speed” (gpsSpeedGroundDetectThreshold 0.15 m/s for 2 s, altitude under 1 m), “…with pressure” (altitudeMaxForGroundDetection 8, acczGroundDetectThreshold 1.5, altGroundDetectThreshold 0.3, MB sets 0.7). After landing, WaitMotorBraking runs with waitAfterBrakingFinishedDuration 2.2 s and the 24400 RPM/s slope.
4.6 Emergency and fail-safes (EVIDENCE strings + cfg)
Section titled “4.6 Emergency and fail-safes (EVIDENCE strings + cfg)”- User
api_EmergencyCommand,COLIBRY_EVENT_..._EMERGENCY, stateEmergency(motors cut).EMERGENCY_LANDING_COMMAND,api_ForceLandingCommand. - Cut-out detection (
cutOutDetectionConfig, strings “CutOut detected on angle error with counter / with timer”, “…with 3 axis accelero and diff gyro”, “…with accZ and gyro diff”): thresholdscutoutDetectionAcceleroThreshold,cutoutDiffGyroThreshold,cutoutDetectionErrorPhiThreshold,cutoutDetectionErrorThetaThreshold,cutoutDetectionCounterTime,cutoutBufferSize 1(the numeric values for the first four are not in the cfg files I read, so they are compiled defaults, open). - Too much angle:
tooMuchAngleSetDefault 90 deg (aboveheightMaxForToomuchangle 3 m), ThrownTakeoff 150. - Freefall detection: see 4.4. The Freefall altitude gain set (kp 2, ki 0, kd 15.01) is used during it.
- Flyaway:
flyawayDetectionActivetrue on milosboard (false in common),gpsAltErrorThresholdForFlyawayDetect 50 m,speedZRefThresholdForFlyawayDetection 0.01,throttleCmdThresholdForFlyawayDetection 0.01, strings “Flyaway detected with altitude pressure”; reaction is an emergency landing with the “Flyaway” angle limit 10 deg and yaw clamp 9. - Emergency landing:
emergencyLandingParameterswith a feedforward descent profileffwdCmdHeight [8.83, 8.06, 6.86, 3.0]m/s^2 stepped everytimeStepToReduceHeightFF 60 s, GPS altitude checked every 20 s. Using 2.6 these are 7165, 6845, 6315 and 4176 RPM, so a stepped, slowly decreasing hover thrust. - Hovering rescue:
minVerticalSpeedErrorForRescue 0.35,tiltMaxForVzRescue 40 deg,tiltRateMaxForAngleRescue 90 deg/s,yawRateMaxForAngleRescue 180 deg/s, duration 0.7 to 3.0 s, uses the “Rescue” gain set (yaw P and I off). - Flip:
tresholdVbatMinForFlipPercent 4,thresholdMaxHorizontalSpeedForFlip 10m/s,maxAngularRateRefToFinishFlip 216deg/s, angle limit 1000 deg, “Flip” gains,ffLossForFlip 5.8. Strings: “Flip refused because of horizontal speed is over … or on battery voltage”. - Battery: strings BATTERY_LOW and BATTERY_CRITICAL, “Could not apply takeoff command due to critical battery level”. Power model
hoveringPower 91 W,batteryEnergyMax 29.97 Wh,nominalVoltage 11.1 V(helper.cfg). - Disconnection handling:
disconnectionAltitudeThreshold 2 m,disconnectionSamplesSafeRange 150. - Geofence:
flightCylinderWidthMax 20,usrConfigMaxDistance 2000,usrConfigNoFlyOverMaxDistance false.
5. Config file catalog (all EVIDENCE: files exist and contain what is stated)
Section titled “5. Config file catalog (all EVIDENCE: files exist and contain what is stated)”rootfs/etc/colibry/ has a subdirectory per board: common, milosboard (Bebop 2), milosblack, milosthermal, mykonos3board, chimeraboard, each with a root.cfg that @includes the rest, plus default|fvt|simulator/init.cfg selecting workingModeInitValue, takeOffHeightInitValue, demoMagicCarpetInitValue.
| File | Holds |
|---|---|
| common/root.cfg | log sets, enabledSensorsSet (ultrasound, verticalCamera, gps, magnetometer), includes |
| common/controller.cfg, milosboard/controller.cfg | PID gains for attitude, altitude, position, speed, cylinder; limits; braking slope |
| common/reference.cfg | tilt, rate, vertical and horizontal limits, ideal-model matrices, animations, flight plan limits |
| common/states.cfg | take-off detection thrust, rescue, GoToFix, flip, thrown take-off parameters |
| common/event.cfg, milosboard/event.cfg | take-off/ground/freefall/flyaway/cut-out detection |
| milosboard/drone.cfg | mass, inertia, motor limits and geometry, A, B, Jp, drag, PWM model |
| common/helper.cfg, milosboard/helper.cfg | ultrasound bias, barometer compensation maps, power and battery constants |
| common/estimator.cfg, milosboard/estimator.cfg | estimator tuning (other agent) |
| common/video.cfg | camera FOV related |
Related: rootfs/etc/PAL/tlm-blackbox.cfg and etc/libshsettings (telemetry and persisted settings, not read in detail), etc/boxinit.d/50-arducopter.rc (disabled sideload). The milosboard/reference.cfg and states.cfg are empty placeholders, so the common values apply to the Bebop 2. |
6. Open questions
Section titled “6. Open questions”- Channel roles in QuadMixRPMController: which of the six inputs v0..v5 are thrust, roll, pitch, yaw and the two extra terms (v3, v5)? Needs the Input struct registration (FUN_003aabd0 style data bindings at 0x3aabd0 and neighbours) traced against the telemetry names. My guess (v0 thrust, v1/v2/v4 angular accelerations) is not verified, and the desaturation priority order depends on it.
- The exact numeric mixing matrix: the constants at r4+372..384 and r4+436..500 are computed at runtime by the pseudo-inverse (0x2a8270..0x2a8dc4). The role of motorAlpha/motorBeta (-pi/2) and motorJp in them is undecoded. A dynamic run is out of scope, but emulating 0x2a78d0 with the cfg values would produce the matrix.
- Is the per-channel linear gain constant in RPM per unit command, or recomputed from the current hover RPM each cycle? (The disassembly reads fixed r4 offsets inside process, so probably fixed, but the writer at 0x2a8b04 may run every cycle.)
- +y direction and motor 0..3 physical positions and spin sense (B sign convention): not provable from the rootfs. The public Parrot motor numbering (1 front-left…) would need an external citation, and the
motors_spin_dirbit mapping lives in the BLDC protocol agent’s area. - Where each cfg Set is selected (which state picks Flip/Rescue/Freefall/Throttle): not traced, would require decompiling the ControlState* enter methods (vtables are exported, e.g.
_ZTVN8Mykonos318ControlStateFlyingE). - Compiled defaults for cutout thresholds (not in cfg).
getManualFlightUnstabilized@0x100400 andsetAttitudethunk @0x33b30 were not traced (the latter is a libCondor call that is vision related, see section 0.1). Whether a truly unstabilised (attitude loop off) mode exists was not found.motorMaxCommandsRPMstring exists in dragon-prog and might be an extra clamp ahead of the HAL (I did not find its use).- The BLDC 16000 RPM ceiling for set_ref_speed (from the brief) is outside my files, so it is unverified here.
- The FUN_001536d4 config singleton is 1100+ decompiled lines, and the full parameter-to-offset map has not been built. Doing it would let every
r4+offsetin the mixer be tied to a cfg key.
Comments
Spotted a mistake, or tried this on your own Bebop? Leave a note. Comments are kept on this site's own server.