diff --git a/Tools/mavlink_serial_bridge.py b/Tools/mavlink_serial_bridge.py new file mode 100755 index 00000000000..bfa0d19fbea --- /dev/null +++ b/Tools/mavlink_serial_bridge.py @@ -0,0 +1,298 @@ +#!/usr/bin/env python3 +""" +Virtual COM port bridge via MAVLink SERIAL_CONTROL. + +Creates a virtual serial port (PTY) and forwards all traffic bidirectionally +through MAVLink SERIAL_CONTROL messages to a PX4 serialpassthrough module. +See docs/en/uart/serial_passthrough.md for the protocol this implements. + +Usage: + Tools/mavlink_serial_bridge.py --connection tcp:10.41.1.1:5790 --port esc0 --setup + Tools/mavlink_serial_bridge.py --connection udpin:0.0.0.0:14550 --port telem2 --port-baud 115200 + Tools/mavlink_serial_bridge.py --connection udpin:0.0.0.0:14550 --port gps1 --port-baud 9600 + Tools/mavlink_serial_bridge.py --connection udpin:0.0.0.0:14550 --port gps2 --port-baud 57600 + +Add --verbose/-v to print a hex dump of every forwarded packet. +""" + +import argparse +import os +import pty +import select +import struct +import sys +import tty +import threading +import time + +try: + from pymavlink import mavutil +except ImportError as e: + print("Failed to import pymavlink: " + str(e)) + print("") + print("You may need to install it with:") + print(" pip3 install --user pymavlink") + print("") + sys.exit(1) + +# SERIAL_CONTROL_FLAG bitmask values +SERIAL_CONTROL_FLAG_REPLY = 1 +SERIAL_CONTROL_FLAG_RESPOND = 2 +SERIAL_CONTROL_FLAG_EXCLUSIVE = 4 + +MAX_PAYLOAD = 70 + +# pymavlink is not thread-safe; hold this for every mav access from the bridge threads +MAV_LOCK = threading.Lock() + +PORT_MAP = { + 'telem1': 0, + 'telem2': 1, + 'gps1': 2, + 'gps2': 3, + 'telem3': 4, + 'telem4': 5, + 'esc0': 20, + 'esc1': 21, + 'esc2': 22, + 'esc3': 23, + 'esc4': 24, + 'esc5': 25, + 'esc6': 26, + 'esc7': 27, +} + + +def send_serial_control(mav, device, port_baud, data=b''): + """Send a SERIAL_CONTROL message with the RESPOND|EXCLUSIVE flags used throughout the bridge.""" + # pymavlink needs all 70 entries; MAVLink 2 trims trailing zeros on the wire + payload = list(data) + [0] * (MAX_PAYLOAD - len(data)) + with MAV_LOCK: + mav.mav.serial_control_send( + device=device, + flags=SERIAL_CONTROL_FLAG_RESPOND | SERIAL_CONTROL_FLAG_EXCLUSIVE, + timeout=0, + baudrate=port_baud, + count=len(data), + data=payload, + ) + + +def setup_passthrough(mav): + """ + Set PASSTHRU_EN=1 via PARAM_SET and reboot the FMU. + Waits for the FMU to come back online before returning. + """ + param_id = b'PASSTHRU_EN' + param_id_padded = param_id[:16].ljust(16, b'\x00') + + print("Setting PASSTHRU_EN=1...") + mav.mav.param_set_send( + target_system=mav.target_system, + target_component=mav.target_component, + param_id=param_id_padded, + param_value=struct.unpack('f', struct.pack(' MAVLink: {len(data)} bytes: {data.hex(' ')}") + except Exception as e: + print(f"ERROR: pty_to_mavlink crashed: {e}", file=sys.stderr) + finally: + self.stop.set() + + def mavlink_to_pty(self): + """Receive SERIAL_CONTROL FLAG_REPLY messages, write immediately to PTY.""" + try: + while not self.stop.is_set(): + with MAV_LOCK: + msg = self.mav.recv_match(type='SERIAL_CONTROL', blocking=False) + if msg is None: + # Nothing buffered (locally or at the OS level) right now — + # block until the connection's fd has more data. + select.select([self.mav.fd], [], [], 0.2) + continue + if not (msg.flags & SERIAL_CONTROL_FLAG_REPLY): + continue + + if msg.device != self.device: + if self.verbose: + print(f" Ignoring message for device {msg.device} (current device: {self.device})") + # Stale reply for the previous ESC channel — discard. + continue + reply = bytes(msg.data[:msg.count]) + if reply: + os.write(self.master_fd, reply) + if self.verbose: + print(f" MAVLink -> PTY: {msg.count} bytes: {reply.hex(' ')}") + except Exception as e: + print(f"ERROR: mavlink_to_pty crashed: {e}", file=sys.stderr) + finally: + self.stop.set() + + def stdin_listener(self): + """Read SWITCH commands from stdin to hot-swap ESC channel.""" + try: + for line in sys.stdin: + line = line.strip() + if line.startswith('SWITCH '): + try: + new_device = int(line.split()[1]) + except (IndexError, ValueError): + continue + self.device = new_device + print(f" Switching to device {self.device}") + send_serial_control(self.mav, self.device, self.port_baud) + except Exception as e: + print(f"ERROR: stdin_listener crashed: {e}", file=sys.stderr) + finally: + self.stop.set() + + +def run_bridge(connection_str, baud, device, port_baud, setup=False, verbose=False): + master_fd, slave_fd = pty.openpty() + slave_path = os.ttyname(slave_fd) + + # Set PTY to raw mode — prevents line discipline from transforming/buffering binary data + tty.setraw(master_fd) + tty.setraw(slave_fd) + + print(f"Virtual COM port: {slave_path}", flush=True) + + mav = mavutil.mavlink_connection(connection_str, baud=baud) + print(f"Waiting for heartbeat on {connection_str}...") + while True: + hb = mav.recv_match(type='HEARTBEAT', blocking=True) + if hb and hb.get_srcSystem() != 0 and hb.get_srcComponent() == 1: + mav.target_system = hb.get_srcSystem() + mav.target_component = hb.get_srcComponent() + break + print(f"Heartbeat received (sysid={mav.target_system}, compid={mav.target_component})") + + if setup: + setup_passthrough(mav) + + # Send an init message with count=0 to trigger FMU-side startForDevice() + # before any data arrives. baudrate field carries the target UART baud rate. + print(f"Initializing FMU passthrough: device={device}, port_baud={port_baud}...") + send_serial_control(mav, device, port_baud) + time.sleep(2) # Give FMU time to spawn the task + print("Bridge running. Press Ctrl+C to stop.\n", flush=True) + + bridge = SerialBridge(mav, master_fd, device, port_baud, verbose) + threads = [threading.Thread(target=fn, daemon=True) + for fn in (bridge.pty_to_mavlink, bridge.mavlink_to_pty, bridge.stdin_listener)] + for t in threads: + t.start() + + # stop.wait() only returns without a KeyboardInterrupt if a thread crashed. + crashed = True + try: + bridge.stop.wait() # blocks until Ctrl+C (KeyboardInterrupt) or a thread crash + except KeyboardInterrupt: + print("\nShutting down.") + crashed = False + finally: + bridge.stop.set() + try: os.write(slave_fd, b'\x00') + except OSError: pass + try: os.close(slave_fd) + except OSError: pass + try: os.close(master_fd) + except OSError: pass + for t in threads: + t.join(timeout=0.5) + mav.close() + + if crashed: + sys.exit(1) + + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description='Virtual COM port bridge via MAVLink SERIAL_CONTROL') + parser.add_argument('--connection', default='udpin:0.0.0.0:14550', + help='MAVLink connection string (default: udpin:0.0.0.0:14550)') + parser.add_argument('--baud', type=int, default=57600, + help='Serial baud rate if using serial connection (default: 57600)') + parser.add_argument('--port', default='esc0', + choices=list(PORT_MAP.keys()), + help='Target port on the FMU (default: esc0). SERIAL_CONTROL device IDs: ' + + ', '.join(f'{name}={dev}' for name, dev in PORT_MAP.items())) + parser.add_argument('--port-baud', type=int, default=115200, + help='Baudrate to set on the target UART (default: 115200; ignored for esc ports, which use 19200)') + parser.add_argument('--setup', action='store_true', default=False, + help='Set PASSTHRU_EN=1 and reboot FMU before starting bridge') + parser.add_argument('--verbose', '-v', action='store_true', default=False, + help='Print a hex dump of every forwarded packet (noisy, disabled by default)') + args = parser.parse_args() + + device = PORT_MAP[args.port] + port_baud = 19200 if args.port.startswith('esc') else args.port_baud + print(f"Port: {args.port} (device ID {device}), UART baud: {port_baud}") + + run_bridge( + connection_str=args.connection, + baud=args.baud, + device=device, + port_baud=port_baud, + setup=args.setup, + verbose=args.verbose, + ) diff --git a/docs/en/peripherals/dshot.md b/docs/en/peripherals/dshot.md index a9ac36de315..9316846eaf5 100644 --- a/docs/en/peripherals/dshot.md +++ b/docs/en/peripherals/dshot.md @@ -145,21 +145,20 @@ PX4 automatically reads the full EEPROM from each ESC on boot. The ground station can then display individual settings and allow the user to modify them. Changes are written back to the ESC one byte at a time using the DShot programming protocol. - - +See [Serial Passthrough (MAVLink SERIAL_CONTROL)](../uart/serial_passthrough.md) for build configuration, supported channels, and limitations. diff --git a/docs/en/releases/1.18.md b/docs/en/releases/1.18.md index a5fee42826c..6958de9d87c 100644 --- a/docs/en/releases/1.18.md +++ b/docs/en/releases/1.18.md @@ -166,8 +166,9 @@ For users upgrading from v1.17, please take a moment to review the following bef | `COM_OBC_LOSS_T` | Timeout for missing heartbeats from the onboard computer is always 5 seconds (was the default). ([PX4-Autopilot#27261](https://github.com/PX4/PX4-Autopilot/pull/27261)) | | `COM_LKDOWN_TKO` | Takeoff failure detection always runs for 3 seconds (was the default). ([PX4-Autopilot#27262](https://github.com/PX4/PX4-Autopilot/pull/27262)) | -- [Serial Passthrough (MAVLink SERIAL_CONTROL)](../uart/serial_passthrough.md): new `serialpassthrough` driver enables MAVLink clients to read from and write to FC serial ports (TEL1/2, GPS1/2, TEL3/4). - On STM32F7/H7 boards, ESC signal pins can also be written via a software bit-bang UART (device IDs 20–27): note that a bridge application is also required, so this functionality is not usable out of the box. +- [Serial Passthrough (MAVLink SERIAL_CONTROL)](../uart/serial_passthrough.md): new `serialpassthrough` driver enables MAVLink clients to read from and write to FC serial ports (`TELEM1`/`TELEM2`, `GPS1`/`GPS2`, `TELEM3`/`TELEM4`). + On STM32F7/H7 boards, ESC signal pins can also be written via a software bit-bang UART (device IDs 20–27). + Host tools connect through a bridge application, such as [`Tools/mavlink_serial_bridge.py`](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/mavlink_serial_bridge.py) (it isn't part of the v1.18 release, but the version on `main` works with v1.18 firmware). ([PX4-Autopilot#27605: feat(drivers): implemented serial passthrough](https://github.com/PX4/PX4-Autopilot/pull/27605)). - UAVCAN: firmware can now be flashed onto connected CAN nodes directly from the SD card. Place node firmware `.bin` files at the card root or in `/fs/microsd/ufw_staging/`; on boot the UAVCAN server migrates them into `/fs/microsd/ufw/`, tracks them in an `FW.db` database, and flashes any connected node whose firmware version does not match. ([PX4-Autopilot#27043](https://github.com/PX4/PX4-Autopilot/pull/27043)) diff --git a/docs/en/releases/main.md b/docs/en/releases/main.md index cd202e12b6a..f4722d7fdab 100644 --- a/docs/en/releases/main.md +++ b/docs/en/releases/main.md @@ -55,6 +55,8 @@ Please continue reading for [upgrade instructions](#upgrade-guide). ### Hardware Support - [DroneCAN ESCs](../dronecan/escs.md) no longer need to set `UAVCAN_PUB_ARM` as `ArmingStatus` is published automatically whenever `UAVCAN_ENABLE` is `3` (ESC output enabled). ([PX4-Autopilot#28364](https://github.com/PX4/PX4-Autopilot/pull/28364)) +- [Serial Passthrough](../uart/serial_passthrough.md): new reference [bridge application](../uart/serial_passthrough.md#bridge-application), `Tools/mavlink_serial_bridge.py`, exposes a flight controller serial port or ESC signal pin as a virtual serial port on a Linux/macOS host, so ESC configuration and GPS tools can connect to it over MAVLink. + ([PX4-Autopilot#28782: feat(tools): add mavlink_serial_bridge.py reference bridge application](https://github.com/PX4/PX4-Autopilot/pull/28782)) ### Common diff --git a/docs/en/uart/serial_passthrough.md b/docs/en/uart/serial_passthrough.md index 19e3183781b..022ef504673 100644 --- a/docs/en/uart/serial_passthrough.md +++ b/docs/en/uart/serial_passthrough.md @@ -23,12 +23,12 @@ The following device IDs are allowed (note that this is a subset of the IDs spec | Device ID | Target | | --------- | ----------------------------------- | -| `0` | TEL1 | -| `1` | TEL2 | -| `2` | GPS1 | -| `3` | GPS2 | -| `4` | TEL3 | -| `5` | TEL4 | +| `0` | `TELEM1` | +| `1` | `TELEM2` | +| `2` | `GPS1` | +| `3` | `GPS2` | +| `4` | `TELEM3` | +| `5` | `TELEM4` | | `20` | ESC channel 0 ([bitbang](#bitbang)) | | `21` | ESC channel 1 (bitbang) | | `22` | ESC channel 2 (bitbang) | @@ -50,11 +50,6 @@ Note that the `PASSTHRU_EN` parameter need not be set. ## ESC Channel Mode (Bitbang UART) {#bitbang} -::: tip -This feature is not yet useful because PX4 does not ship a ready-made tool for using serial passthrough with common ESC configuration or firmware flashing tools. -Information on how such a tool might be developed is given below in [Bridge Application](#bridge-application). -::: - Device IDs 20–27 route through a software bit-bang UART on the ESC signal pin rather than a hardware UART. This is useful for communicating with ESCs that expose a UART telemetry or configuration port on their signal wire (such as BLHeli_32 passthrough, AM32, or ESC configuration tools). @@ -67,15 +62,78 @@ When a request arrives for a different ESC channel, the driver stops the current Bitbang UART support requires that both `CONFIG_DRIVERS_SERIALPASSTHROUGH=y` and `CONFIG_SERIALPASSTHROUGH_BITBANG=y` are set before building (the timer is selected with `CONFIG_UART_BITBANG_TIMER`, and defaults to `TIM13`). The `PASSTHRU_EN` parameter must be set to `1` and the device rebooted in order to enable this mode. -### Bridge Application +## Bridge Application -Developers can create their own bridge application if needed. -This would connect to the vehicle over MAVLink, expose a virtual serial port (e.g. a Unix PTY) to the tool on the host, and translate traffic bidirectionally. +[`Tools/mavlink_serial_bridge.py`](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/mavlink_serial_bridge.py) is a reference bridge application (Linux/macOS only): it connects to the vehicle over MAVLink, exposes a virtual serial port (a Unix PTY) to a serial tool on the host, such as an ESC configurator, and translates traffic bidirectionally. + +The script supports all [device IDs](#device-ids), selected with its `--port` option: + +| `--port` | Device ID | Target | +| ------------- | --------- | ---------------- | +| `telem1` | `0` | `TELEM1` | +| `telem2` | `1` | `TELEM2` | +| `gps1` | `2` | `GPS1` | +| `gps2` | `3` | `GPS2` | +| `telem3` | `4` | `TELEM3` | +| `telem4` | `5` | `TELEM4` | +| `esc0`–`esc7` | `20`–`27` | ESC channels 0–7 | + +Install its only dependency and run it, for example to bridge ESC channel 0: + +```sh +pip3 install --user pymavlink +./Tools/mavlink_serial_bridge.py --connection /dev/ttyUSB0 --port esc0 --setup +``` + +`--connection` takes a [pymavlink connection string](https://mavlink.io/en/mavgen_python/#connection_string) for the link to the vehicle, such as a telemetry radio (`/dev/ttyUSB0`, with `--baud` if it isn't 57600) or a network link (`tcp::`, or `udpin:0.0.0.0:14550`). +A `udp:127.0.0.1:` string only receives MAVLink traffic sent to this machine, for example by a local MAVLink router. + +`--setup` sets `PASSTHRU_EN=1` and reboots the flight controller, so DShot/PWM outputs are not started until the next reboot (see [PX4 Configuration (ESC targets)](#px4-configuration-esc-targets)). +Use it only with `esc*` ports, and again after each reboot, since PX4 resets the parameter at boot. +For `telem*` and `gps*` ports, leave out `--setup`: they don't need `PASSTHRU_EN`. + +The script prints the PTY path it created (e.g. `/dev/pts/5`). +Once it prints `Bridge running`, point any tool that expects a serial connection (ESC configurator, GPS/RTK utility, and so on) at that path. +Run it with `-h` for the full list of options. + +For `esc*` ports the UART baud rate is fixed at 19200 (the bitbang limit) and `--port-baud` is ignored. + +Developers can create their own bridge application in another language if needed, following the protocol described below. Data written to the PTY would be sent as `SERIAL_CONTROL` messages with `SERIAL_CONTROL_FLAG_RESPOND | SERIAL_CONTROL_FLAG_EXCLUSIVE` set, and incoming `SERIAL_CONTROL` reply messages (with `FLAG_REPLY` set) would be written back to the PTY. To initialise the passthrough, the bridge should send one `SERIAL_CONTROL` message with the target device ID, the desired UART baud rate in the `baudrate` field, and `count=0` (no payload), then wait approximately 2 seconds for PX4 to spawn the passthrough task before sending real traffic. For ESC bitbang mode (device IDs 20–27), the bridge must first set `PASSTHRU_EN=1` via `PARAM_SET`, confirm the `PARAM_VALUE` acknowledgement, send `MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN`, and wait for the FMU heartbeat to return before sending the init message — this ensures the DShot/PWM drivers are not running when the bitbang driver takes over the ESC signal pins. +### Switching Devices at Runtime + +The bridge reads commands from its standard input, so that a host tool that launches it as a subprocess can change the target device without restarting the bridge. +This is mainly intended for tools that work through several ESCs in sequence, such as flashing or configuring each ESC channel in turn. + +To switch, write a line in the following form to the bridge's stdin (or type it and press Enter when running it interactively): + +```text +SWITCH +``` + +`` is the numeric [device ID](#device-ids) (for example `SWITCH 21` for ESC channel 1), not the `--port` name. +Lines that are not valid `SWITCH` commands are ignored. + +When a valid command is received, the bridge: + +1. Prints `Switching to device `. +2. Sends a `SERIAL_CONTROL` init message (`count=0`) for the new device, using the same UART baud rate the bridge was started with. +3. Forwards all further PTY traffic to the new device, and discards replies that still arrive from the previous device. + +The PTY path does not change, so the host tool can keep its serial port open across the switch. + +Note the following when using `SWITCH`: + +- The bridge does not wait after sending the init message. + Allow some time for PX4 to stop the previous instance and start the new one (up to 100 ms for ESC channels) before sending data. +- The baud rate is not changed, so switching between ESC channels (19200 baud) works as expected, but switching between ESC and `telem*`/`gps*` targets keeps the original baud rate. +- `--setup` is only applied at startup. + `PASSTHRU_EN` must already be enabled before you switch to an ESC channel. + ## Configuration ### Firmware Configuration (Build-Time)