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

About¶

This document is the standalone Interface Control Document (ICD) for the libdrone GX12-7 dual payload connector standard. It defines the mechanical interface, electrical pinout, software protocol contracts, and operational requirements independently of any specific payload or platform version. Third-party payload developers should implement against this document — not against the Payload SDK, which is a higher-level guide.

The connector standard is versioned independently of the platform: a new platform version does not imply a new ICD revision unless the interface itself changes.

Scope¶

This ICD defines: - The mechanical interface: connector type, gender, orientation, bore profile, retention - The electrical interface: pinout, signal types, voltage levels, current limits - The software protocol interface: MSP framing, command bus, GPS format, I2C address space, GPIO behaviour — the contracts a payload must meet to interoperate correctly - Operational requirements: mating/demating procedure, dust cap discipline, inspection - The PSB-1 Payload Shield Board: reference hardware implementation of this interface

This ICD does not define: - Payload mechanical design beyond the connector interface - Application-level payload firmware (see LD-PAY-001 Payload SDK) - Any platform-specific geometry beyond what is necessary to define the interface

Standard Adoption¶

Third parties are explicitly encouraged to implement this interface standard.

A payload built to this ICD works on any compliant platform regardless of manufacturer. libdrone maintains the canonical reference implementation and the authoritative documentation. Compatible implementations by others validate the standard — a broader ecosystem benefits every payload developer, every operator, and every institution that has invested in GX12-compatible hardware.

Your payload IP stays yours. CERN OHL-S v2 copyleft applies to modifications of the libdrone platform hardware. It does not apply to payload designs that use the GX12 interface standard. A company that builds a proprietary sensor payload to this ICD and sells it commercially retains full ownership of that payload design. The platform is open. Your payload is yours.

libdrone is the canonical source: the organisation that authored this ICD, flew the reference payloads, published the case studies, and maintains the ecosystem. A compatible implementation by a third party is a feature of an open standard, not a threat to it.

1. Interface Overview¶

The libdrone payload interface consists of two GX12-7 aviation connectors mounted on the Platform middle layer, side by side in the electronics zone. Together they provide full electrical access to the drone's power, communications, and auxiliary I/O systems for any compliant payload.

2. Mechanical Interface¶

2.1 Connector Positions¶

All positions measured from X body centre (Y+ = nose, Y− = tail, X+ = right).

Both connectors share the same Y position — side by side at Y = −66mm in the electronics zone, clear of the battery strap (Y = −39mm) and fan (Y = −138mm).

2.2 Connector Geometry¶

2.3 Chimney Bore Profile — D-D Shape (Critical)¶

The chimney bore is not a simple round hole. The GX12-7 male panel mount body has two parallel flats machined on opposite sides. The bore must match this D-D profile to prevent the connector rotating when payloads are connected or disconnected. Rotation under repeated mating cycles will back off the retention nut regardless of Loctite, leading to connector loss in flight.

D-D profile construction (FreeCAD Sketcher): 1. Draw a circle diameter 11.87mm (GX12ChimneyBoreOD) 2. Add two parallel constraint lines at ±5.40mm from centre (= GX12ChimneyBoreFlatFlat / 2) 3. Trim the circle arcs outside those lines 4. Result: D-D profile with correct clearance on all surfaces

Post-print support removal: Clear support material with a pick or wire. Do NOT ream with a round drill bit — a 12mm drill cannot enter a 11.87mm bore cleanly, and forcing it destroys the anti-rotation flats.

Verification: Insert GX12-7 male body dry with flats aligned. Must seat flush with no binding. Panel nut must thread onto chimney without cross-threading.

2.4 Vibration Retention¶

A single nut is insufficient — drone vibration will back it off in flight.

Required retention: double nut + Loctite 243 blue (medium strength) - Inner nut: against Platform underside at body OD collar - Outer nut: locks against inner nut - Loctite 243: applied to outer nut thread only

The D-D chimney bore prevents connector body rotation. The double nut + Loctite prevents axial backing-off under vibration. Both are required.

2.5 Dust Cap Requirement¶

Dust caps are mandatory on drone-side male connectors whenever no payload is fitted. The pins face upward — an uncapped connector in rain, dust, or a crash will be damaged. Caps fit over the male pins. One cap per connector, two per drone.

3. Electrical Interface¶

3.1 Connector A — Left (X = −25mm) — Signal + Power¶

Wire exit slot faces LEFT toward the signal wire channel (X = −20mm).

3.2 Connector B — Right (X = +25mm) — Data + Aux¶

Wire exit slot faces RIGHT toward the power wire channel (X = +20mm).

3.3 Electrical Limits¶

3.4 Wiring Recommendations¶

• Twist I2C SCL/SDA pair (A5/A6) — minimises capacitive coupling at 400kHz
• Twist UART4 TX/RX pair (A3/A4) and UART5 TX/RX pair (B3/B4)
• 5V and GND (A1/A2) run separately — no twisting required
• GPS tap (B2) and shield GND (B1) run separately
• Keep payload-side cable length ≤ 300mm from connector to first PCB

4. Software Protocol Interface¶

This section defines the software contracts on each signal path. A payload implementing these contracts will interoperate correctly with any libdrone running standard Betaflight firmware configuration.

4.1 Realtime Bus — MSP on UART4 (Conn A PIN 4, payload → drone)¶

The payload sends telemetry to the flight controller for display in the pilot's HDZero goggles via OSD. The protocol is MSP (MultiWii Serial Protocol) v1.

Frame format:

Byte 0:    0x24  '$'   — preamble
Byte 1:    0x4D  'M'   — preamble
Byte 2:    0x3C  '<'   — direction: payload to FC
Byte 3:    N           — payload byte count (0–255)
Byte 4:    CMD         — MSP command code
Bytes 5…N+4: data     — payload bytes
Byte N+5:  CRC        — XOR of bytes 3 through N+4

MSP command for OSD text injection: MSP_DISPLAYPORT (0xB6 / 182)

The OSD text field update sequence:

1. Send MSP_DISPLAYPORT with sub-command 0x03 (write string):
   [row, col, attr, char0, char1, ..., 0x00]
   row:  0–15  (OSD row, top = 0)
   col:  0–29  (OSD column, left = 0)
   attr: 0x00  (normal) or 0x01 (blink)

2. Send MSP_DISPLAYPORT with sub-command 0x04 (draw screen):
   No data bytes — triggers OSD refresh

Recommended OSD field assignments for sensor payloads:

Update rate: 2–10 Hz recommended. Above 10 Hz wastes bandwidth with no visible benefit — the OSD refreshes at video frame rate (60 Hz) regardless.

Minimum viable OSD implementation (one field, one line):

def msp_write_osd(uart, row, col, text):
    data = bytes([row, col, 0x00]) + text.encode() + b'\x00'
    n = len(data)
    cmd = 182  # MSP_DISPLAYPORT
    crc = n ^ cmd
    for b in data:
        crc ^= b
    frame = b'$M<' + bytes([n, cmd]) + data + bytes([crc])
    uart.write(frame)
    # Send draw command
    draw = b'$M<' + bytes([1, 182, 0x04]) + bytes([1 ^ 182 ^ 4])
    uart.write(draw)

4.2 Control Bus — UART4 (Conn A PIN 3, drone → payload)¶

The flight controller forwards commands to the payload, triggered by pilot radio switch actions. The protocol is plain text, newline-terminated strings at 115200 baud.

Standard command vocabulary (compliant payloads must respond to these):

Custom commands: Payloads may define additional commands using the same newline-terminated text format. Custom commands must not conflict with the standard vocabulary above.

FC configuration (Betaflight): UART4 must be configured in Betaflight as a pass-through UART to the payload. The radio switch assignment maps AUX channel to the command string via Betaflight scripting or a Lua script on the TX16S. Default mapping: AUX switch high → ENABLE\n, low → DISABLE\n.

4.3 GPS Bus — UART (Conn B PIN 2, drone → payload, read-only)¶

The payload receives live GPS position from the drone's M10Q GNSS receiver.

Protocol: NMEA 0183, 57600 baud, 8N1
Update rate: 10 Hz (one position fix every 100ms)
Sentences present: GGA (position + fix quality), RMC (position + speed + heading)
1MΩ series resistor: Already installed on drone side — do not add another

Recommended sentences to parse:

$GPGGA,143423.00,5007.40123,N,01527.45678,E,1,14,0.85,312.4,M,43.2,M,,*6A
         ↑time    ↑lat        ↑lon          ↑fix ↑sats    ↑alt(m)

$GPRMC,143423.00,A,5007.40123,N,01527.45678,E,0.5,234.1,080326,,,A*7C
         ↑time  ↑valid ↑lat      ↑lon          ↑knots ↑heading ↑date

Minimum GPS parse for logging (MicroPython):

def parse_gga(sentence):
    parts = sentence.split(',')
    if len(parts) < 10 or parts[6] == '0':
        return None  # no fix
    lat_raw = float(parts[2])
    lat = int(lat_raw / 100) + (lat_raw % 100) / 60
    if parts[3] == 'S': lat = -lat
    lon_raw = float(parts[4])
    lon = int(lon_raw / 100) + (lon_raw % 100) / 60
    if parts[5] == 'W': lon = -lon
    alt = float(parts[9])
    sats = int(parts[7])
    return lat, lon, alt, sats

Do not drive this pin. The 1MΩ resistor protects the flight controller's GPS receiver. Driving B2 from the payload side will corrupt FC GPS data.

4.4 Sensor Bus — I2C (Conn A PIN 5/6)¶

The payload connects I2C sensors to the shared I2C bus. The flight controller is the I2C master. The payload's sensors are slaves.

Bus parameters:

Reserved I2C addresses (already in use on drone):

Payload must not use these addresses. I2C address conflicts will corrupt flight controller sensor readings. If your sensor uses a reserved address, use an I2C multiplexer (TCA9548A at address 0x70–0x77).

Known payload device addresses:

4.5 AUX GPIO Bus — (Conn B PIN 5/6, drone → payload)¶

Two radio-controlled GPIO outputs from the flight controller to the payload.

Electrical behaviour: - Logic HIGH: 3.3V, driven by FC GPIO output - Logic LOW: 0V - Source current: ≤ 10mA — use a MOSFET for any load above this - Payload must not source current back into these pins - Recommended: 10kΩ series resistor on payload side (already present on PSB-1)

Timing: - Transition time: < 20ms from pilot switch throw to GPIO change at payload - Debounce: FC applies software debounce — payload sees clean transitions - No need for hardware debounce on payload side

Default mapping (Betaflight standard configuration):

GPIO logic in MicroPython:

from machine import Pin

gpio1 = Pin(GPIO1_PIN, Pin.IN)   # Conn B PIN 5
gpio2 = Pin(GPIO2_PIN, Pin.IN)   # Conn B PIN 6

if gpio1.value():
    enable_payload()
if gpio2.value():
    trigger_camera()

4.6 Three-Bus Compliance Requirement¶

Every compliant payload must implement all three buses:

A payload that only logs to SD (no realtime) is non-compliant. A payload that only streams OSD (no storage) is non-compliant. Both buses must be active. The control bus (UART4 TX) must at minimum respond to ENABLE and DISABLE.

5. PSB-1 — Payload Shield Board (Reference Hardware)¶

The PSB-1 is the reference hardware implementation of this ICD. It provides all required discrete components — power MOSFET, LDO regulator, diode-OR gate, pull-up resistors, protection resistors — pre-built and tested, so payload builders begin with a known-good hardware baseline.

5.1 PSB-1 Function¶

5.2 PSB-1 Connector Header Pinout¶

Headers are 2.54mm pitch. Labels match GX12 pin names.

Connector A header (J1):

Connector B header (J2):

MCU header (J3/J4): Matches ESP32-S3 mini dev board. All GX12 signals pre-routed to correct ESP32-S3 GPIO pins per libdrone.py default pin map.

5.3 PSB-1 Perfboard Build (Prototype)¶

Before ordering a fabricated PCB, build the PSB-1 circuit on 2.54mm perfboard. The circuit has 12 components — one evening of work.

Bill of materials:

Test sequence before first flight: 1. With no MCU installed: verify 5V at J1 pin 1 when master switch ON 2. Verify 3.3V at LDO output 3. Verify 5V drops to 0V when master switch OFF 4. Install ESP32-S3 dev board. Flash libdrone.py test sketch. 5. Verify OSD test string appears in HDZero goggles 6. Verify GPS position appears in serial monitor at 57600 baud 7. Verify GPIO1 toggles correctly when AUX3 switch thrown on TX16S

6. Mating and Demating Procedure¶

6.1 Mating (payload installation)¶

1. Verify drone is disarmed and battery removed.
2. Remove dust caps from both drone-side connectors. Store caps in field bag.
3. Align payload female Connector A with drone male Connector A — match anti-rotation flats.
4. Seat connector — should feel positive engagement with no resistance.
5. Screw lock ring clockwise until finger-tight. Do not use tools.
6. Repeat for Connector B.
7. Visually verify both lock rings are fully seated.

6.2 Demating (payload removal)¶

1. Disarm drone. Remove battery if fitted.
2. Unscrew Connector B lock ring counter-clockwise. Pull straight out.
3. Unscrew Connector A lock ring counter-clockwise. Pull straight out.
4. Fit dust caps on both drone-side male connectors immediately.
5. Inspect pins visually before next use.

7. Inspection Criteria¶

Inspect drone-side connectors every 10 flights or after any crash. Inspect payload-side connectors before each payload installation.

8. Compliance Statement¶

8.1 Mechanical compliance¶

A payload claiming mechanical compliance with libdrone ICD GX12-7 v1.0.1 must:

1. Use GX12-7 female cable-mount connectors on the payload cable
2. Implement Pin A1/A2 power and GND connection
3. Not exceed the electrical limits defined in §3.3
4. Not connect Pin A7 or B7 (reserved)
5. Not drive the GPS tap pin B2 (read-only)
6. Implement dust cap storage discipline when not mated

8.2 Software compliance¶

A payload claiming full software compliance must additionally:

1. Implement MSP OSD output on UART4 RX (§4.1) at minimum 2 Hz
2. Respond to ENABLE and DISABLE commands on UART4 TX (§4.2)
3. Parse NMEA GGA sentences from GPS tap (§4.3) for position logging
4. Not use I2C addresses 0x68, 0x69, or 0x0D (reserved — §4.4)
5. Implement all three buses: storage, realtime, control (§4.6)

8.3 Partial compliance¶

Payloads that implement mechanical compliance but not full software compliance must declare which protocol elements they implement. Partial compliance is acceptable for prototypes and specialised payloads. Label as: "Compliant: LD-PAY-002 v1.0.1 mechanical" or "Compliant: LD-PAY-002 v1.0.1 full".

Revision History¶