Design rationale index

Summary¶

Every significant design decision in libdrone has a documented rationale — not just what was decided, but why, and what alternatives were rejected. This index maps the major decisions to the atoms that contain their rationale. Version 3.0.0 is a substantial cut from the previous version: the printed-frame structural decisions, the five-variant platform family reasoning, and the IFF/operational-security decisions are gone, because the things they were reasoning about are gone — printed-frame design and the institutional tier catalog were dropped entirely in the move to ld310. What remains here is what survived that cut: EMC and electronics decisions, wire and power decisions, and software/firmware/protocol decisions. Those old entries aren't lost — the articles they pointed to are deprecated, not deleted, kept as a data source if any of that reasoning is ever needed again.

Concept¶

Why design rationale matters more than design decisions¶

A design decision without documented rationale looks arbitrary to the next person who encounters it. They will either follow it blindly — possibly in a context where the original reasoning no longer applies — or override it without understanding what they are losing. Documented rationale transforms a constraint into a principle: "we chose X because Y, given constraints A and B." When Y changes or A and B no longer hold, the decision can be revisited intelligently rather than by accident. This index is itself an example: it exists in its current, much shorter form precisely because the context that justified its previous entries changed.

Reference¶

Electronics and EMC decisions¶

Decision	Atom	Why — and why not the alternative
Star grounding at ESC pad	star-grounding	All high-current return paths terminate at one point. Ground loops between distributed return paths are the primary EMC noise source — star topology eliminates them structurally.
1000µF capacitor directly on ESC pads	capacitor-placement-emc	Wire inductance of even 50mm of lead wire defeats the capacitor's function during motor back-EMF spikes. Distance is performance — the capacitor must be on the pads, not on a pigtail.
EMC separation by cable routing, not printed channels	electronics-installation	The old printed Platform enforced power/signal separation with physical channel geometry. A bought frame has no such geometry — the same separation is now enforced by routing discipline and zip-ties instead. The principle didn't change; the enforcement mechanism did.
External compass, mounted clear of high-current wiring	gnss-gps	Motor current creates magnetic fields that corrupt a compass at typical frame distances. Separation from the battery lead and phase wires is what matters, regardless of frame architecture.
Matek H7A3-SLIM FC	flight-controller-hardware	H7-class needed for 8kHz loop rate plus RPM filter simultaneously, with headroom to spare.
Pilotix AM32 ESC	electronic-speed-controllers	Open firmware, bidirectional DShot telemetry, EU-accessible supply chain. BLHeli_32 went closed in 2022 — vendor lock-in risk.
Ferrite bead on VTX power wire	ferrite-beads	Any switching regulator on the VTX rail — whether a separate buck module or, on the current build, the FC's own switchable BEC — injects harmonics that need frequency-selective attenuation at the source.
Conformal coating before first flight	conformal-coating	Moisture-induced shorts are the leading cause of electronics failure in field deployments. The cost is 20 minutes; the benefit is permanent.

Wire and power decisions¶

Decision	Atom	Why — and why not the alternative
Colour discipline: red/black power, blue/green signal	wire-gauge-selection	Field rewiring in poor light by a fatigued operator. Colour code must survive the worst maintenance context without a wiring diagram.
Twisted pairs on motor phase wires	twisted-pairs	Motor phase wires carry fast-switching high current — strong RF emitters. Twisting cancels the magnetic field and eliminates the wire-as-antenna problem.

Software, firmware and protocol decisions¶

Decision	Atom	Why — and why not the alternative
Betaflight for Agile	betaflight-setup	8kHz PID loop, RPM filter, aggressive manual tuning — right fit for a cheap, crashable practice platform.
ArduPilot for Cinematic	ardupilot-copter	Flown manually day to day, like Betaflight — but ArduPilot adds GPS-guided planning and full telemetry as an option Betaflight has no path to at all. The firmware choice is about what it makes possible later, not how the drone flies normally.
ELRS MAVLink mode on Cinematic (not plain RCIN)	elrs-mavlink-mode	Wired in from the start so the planning option (QGroundControl, mission upload) is available whenever wanted, without rewiring — even though day-to-day flying stays manual.
ELRS at 250Hz LBT	elrs-protocol	EU LBT regulatory compliance requires Listen Before Talk. 250Hz balances latency against range better than 500Hz or 50Hz for this use case.
AM32 over BLHeli_32	foss-stack-libdrone	BLHeli_32 went closed source in 2022. AM32 is MIT-licensed, actively maintained, supports BiDi DShot. Any firmware that can go closed can go abandoned — openness is a reliability argument, not just a philosophy argument.
MSP DisplayPort for OSD	digital-fpv	FC generates all OSD data; HDZero VTX renders it. No custom OSD hardware. Any FC that supports MSP DisplayPort works without modification.
8kHz PID loop (not 4kHz or 1kHz)	pid-loop-rate	Lower loop latency allows higher PID gains at the same stability margin — better disturbance rejection. The H7A3's hardware FPU makes 8kHz plus RPM filter possible simultaneously.
RPM filter over static notch filter	rpm-filter	Motor frequencies move with throttle. A static notch misses the noise except at one throttle point. RPM filter tracks the noise wherever it goes using BiDi DShot eRPM telemetry.

Procedure¶

Rationale¶

This index exists as a dedicated article rather than a section inside platform-architecture because the decision record is a living document. Its size and shape change as the project's scope changes — version 3.0.0 is smaller than version 2.0.0 not because less thought has gone into the project, but because a large fraction of what version 2.0.0 documented was reasoning about a printed frame and an institutional tier catalog that no longer exist. A dedicated article lets the index be pruned and rebuilt without touching the architecture overview, and gives contributors one search target for "why does libdrone do X this way."

Connections¶

requires: - platform-architecture related: - schema-specification - contributing-guide - foss-principles leads_to: - contributing-guide