"libdrone — Interface Control Document: GX12-7 Dual Payload Connector Standard"

Contributing to libdrone¶

libdrone is an open aerial payload platform. Contributions are welcome at every level — payload designs, documentation improvements, firmware configs, field validation data, and translations.

This document explains how to build a compliant payload, what GX12 compatible means, and how to submit work to the community library.

Your payload IP stays yours¶

This is the most important thing to understand before building on libdrone.

CERN OHL-S v2 — the licence governing libdrone's hardware design — applies to modifications of the libdrone platform itself. It does not apply to payloads that use the GX12 interface standard.

If you design a proprietary sensor payload to the GX12 standard and sell it commercially, that payload design is entirely your intellectual property. You are not required to open source it. You are not required to publish it. The platform is open. Your payload is yours.

This is intentional. It is what makes commercial payload development safe on an open platform. It is stated clearly here so you do not need a lawyer to confirm it before starting work.

What "GX12 compatible" means¶

A compliant payload implements the libdrone GX12-7 dual connector standard as defined in payloads/LD_-_ICD_GX12_v246.md (LD-PAY-002).

Mechanically compliant means: - GX12-7 female cable-mount connectors on both payload cables - Connector A plugged into left drone connector (signal/power) - Connector B plugged into right drone connector (data/aux) - Dust caps stored when not mated

Electrically compliant means: - Does not exceed 2A on Pin A1 (5V) - Does not drive Pin B2 (GPS tap — read-only) - Does not connect reserved pins A7 or B7 - 3.3V logic on all GPIO pins — not 5V tolerant

Software compliant (full compliance) additionally means: - MSP OSD output on UART4 RX at minimum 2Hz - Responds to ENABLE and DISABLE commands on UART4 TX - Parses NMEA GGA from GPS tap for position logging - Does not use reserved I2C addresses 0x68, 0x69, or 0x0D - Implements storage bus, realtime bus, and control bus

Partial compliance is acceptable for prototypes and specialised payloads. Label your payload clearly: "Compliant: LD-PAY-002 v1.0.1 mechanical" or "Compliant: LD-PAY-002 v1.0.1 full".

Building a compliant payload¶

Start here:

1. Read the ICD — payloads/LD_-_ICD_GX12_v246.md The complete hardware and software contract. Everything a payload must do to interoperate correctly.

2. Read the Payload SDK — payloads/LD_-_Payload_SDK_v246.md Higher-level guide. Explains the three-bus architecture, the master enable circuit, the mast mechanical standard, and the reference payload designs. Written for builders who have never read the drone documentation.

3. Build the PSB-1 — payloads/LD_-_PSB1_Build_Guide_v100.md The reference hardware implementation. A perfboard build with ~12 components that gives you the power MOSFET, LDO, diode-OR gate, and GPIO protection pre-built. One evening. ~€8.

4. Use libdrone.py — code/libdrone.py MicroPython library for ESP32-S3. Wraps MSP framing, NMEA parsing, GPIO debouncing, and SD card logging into clean Python objects. A payload developer writes sensor code only.

5. Copy the minimal template — in payloads/LD_-_PSB1_Build_Guide_v100.md Replace read_sensor() with your hardware. Everything else — GPS, OSD, commands, logging — is already handled.

Submitting a payload to the community library¶

A community payload design should include:

payloads/community/[your-payload-name]/
  README.md          — what it does, who it's for, field notes
  BOM.md             — components, quantities, sources, costs
  wiring.md          — connections from GX12 headers to sensor
  firmware/          — MicroPython source files
  cad/               — STL files and/or CadQuery source
  compliance.md      — which ICD compliance level, any exceptions

Requirements for inclusion: - Implements GX12-7 A/B pinout standard (LD-PAY-002) - Documented weight and CG impact on AUW - Tested on at least one libdrone variant (document which) - EMC notes for your sensor type - Licence declared (your choice — CERN OHL-S v2 not required for payloads)

Submit via pull request to the libdrone GitHub repository. Open an issue first if you want feedback on the design before building.

Other contributions¶

Documentation improvements: Fix errors, add clarity, translate to other languages. All documentation is CC BY-SA 4.0 — same licence applies to your contribution.

Field validation data: Flew libdrone somewhere interesting? Measured something useful? Documented a failure mode? Open an issue or submit data to the community library.

Firmware configurations: Alternative Betaflight or ArduPilot configs for specific use cases, tested and documented, belong in code/Firmware/.

Bug reports: Found a discrepancy between documents? A wrong value? A step that doesn't work? Open a GitHub issue with the doc_id, section, and what you found. Tier 1 (Variables file) is always authoritative for numeric values.

The one rule¶

Do not submit anything that facilitates weaponisation, autonomous target acquisition, kinetic payload delivery, or surveillance of individuals without consent. This applies to platform modifications and community payloads alike. The non-weaponisation declaration in the platform documentation is not decorative.

"The drone flies. The payload thinks. The data is safe."

libdrone — EU-origin open aerial payload platform. CERN OHL-S v2 hardware. CC BY-SA 4.0 documentation. MIT software.