mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 14:19:57 +08:00
feat(tools): add mavlink_serial_bridge.py reference bridge application (#28782)
* feat(tools): add mavlink_serial_bridge.py reference bridge application Implements the SERIAL_CONTROL bridge application described in the Bridge Application section of docs/en/uart/serial_passthrough.md: it connects to the vehicle over MAVLink, exposes a virtual serial port (PTY), and translates traffic bidirectionally for any passthrough-capable port (TEL/GPS/ESC bitbang). Existing ESC configuration/flashing tools and GPS/RTK utilities can point at the exposed PTY without native MAVLink support. Also updates serial_passthrough.md to reference this implementation instead of only describing the pattern in the abstract. Signed-off-by: Phil-Engljaehringer <philipp.engljahringer@auterion.com> * fix: add send_serial_control function * docs: document mavlink_serial_bridge.py usage and limits Explain what the bridge supports and how to run it safely: the example connection string only listened on loopback, and --setup reboots the flight controller with motor outputs disabled without saying so. Restore the DShot ESC Serial Passthrough section, which was commented out until a bridge existed, and update the v1.18 and main release notes so v1.18 users know the bridge on main works with their firmware. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Hamish Willee <hamishwillee@gmail.com> * fix: removed duplicated port-map * fix: send_serial_control adjust padding * fix: set target_system and target_component only once * fix: implemented changes requested by alex * fix: implemented changes requested by hamish * fix: avoid indefinite loop waiting for heartbeat * fix: no chunking in send function needed * fix: add lock and avoid trailing 0x00 sent on shutdown * docs: explained SWITCH <device_id> feature in docs --------- Signed-off-by: Phil-Engljaehringer <philipp.engljahringer@auterion.com> Signed-off-by: Hamish Willee <hamishwillee@gmail.com> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
This commit is contained in:
1 parent
2a4ce5dd86
commit
b798249a61
5 files changed
+385
-27
No files matched your search
Executable
+298
@@ -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('<i', 1))[0],
|
||||
param_type=mavutil.mavlink.MAV_PARAM_TYPE_INT32,
|
||||
)
|
||||
# Wait for PARAM_VALUE confirmation (up to 3 s)
|
||||
ack = mav.recv_match(type='PARAM_VALUE', blocking=True, timeout=3)
|
||||
if ack:
|
||||
print(f"PARAM_VALUE ack: {ack.param_id.rstrip(chr(0))} = {ack.param_value}")
|
||||
else:
|
||||
print("WARNING: no PARAM_VALUE ack received, continuing anyway")
|
||||
|
||||
print("Sending reboot command (MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN)...")
|
||||
mav.mav.command_long_send(
|
||||
target_system=mav.target_system,
|
||||
target_component=mav.target_component,
|
||||
command=mavutil.mavlink.MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN,
|
||||
confirmation=0,
|
||||
param1=1, # reboot autopilot
|
||||
param2=0,
|
||||
param3=0,
|
||||
param4=0,
|
||||
param5=0,
|
||||
param6=0,
|
||||
param7=0,
|
||||
)
|
||||
print("Reboot command sent. Waiting for FMU to come back online...")
|
||||
time.sleep(2) # Give the FMU time to start rebooting
|
||||
# Overall deadline: heartbeats from other components must not keep the wait alive
|
||||
deadline = time.monotonic() + 30
|
||||
while time.monotonic() < deadline:
|
||||
hb = mav.recv_match(type='HEARTBEAT', blocking=True, timeout=deadline - time.monotonic())
|
||||
if hb and hb.get_srcSystem() == mav.target_system and hb.get_srcComponent() == mav.target_component:
|
||||
break
|
||||
else:
|
||||
raise TimeoutError("FMU did not come back online within 30 seconds")
|
||||
print("FMU back online")
|
||||
|
||||
|
||||
class SerialBridge:
|
||||
"""Forwards bytes between a PTY and SERIAL_CONTROL messages for one FMU device."""
|
||||
|
||||
def __init__(self, mav, master_fd, device, port_baud, verbose=False):
|
||||
self.mav = mav
|
||||
self.master_fd = master_fd
|
||||
self.device = device
|
||||
self.port_baud = port_baud
|
||||
self.verbose = verbose
|
||||
self.stop = threading.Event()
|
||||
|
||||
def pty_to_mavlink(self):
|
||||
"""Read from PTY master, forward as SERIAL_CONTROL messages."""
|
||||
try:
|
||||
while not self.stop.is_set():
|
||||
try:
|
||||
data = os.read(self.master_fd, MAX_PAYLOAD)
|
||||
except OSError:
|
||||
break
|
||||
if self.stop.is_set(): # wake-up byte from shutdown, don't forward
|
||||
break
|
||||
if not data:
|
||||
continue
|
||||
send_serial_control(self.mav, self.device, self.port_baud, data)
|
||||
if self.verbose:
|
||||
print(f" PTY -> 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 <device_id> 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,
|
||||
)
|
||||
@@ -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.
|
||||
|
||||
<!-- Section below commented out until serial passthrough bridge productised: https://github.com/PX4/PX4-Autopilot/pull/27654#discussion_r3434404781 -->
|
||||
<!--
|
||||
## ESC Serial Passthrough
|
||||
|
||||
<Badge type="tip" text="PX4 v1.18" />
|
||||
<Badge type="tip" text="main (PX4 v2.0)" />
|
||||
|
||||
PX4 supports direct UART communication through an ESC signal pin using a software bit-bang UART.
|
||||
This enables ESC configuration tools, such as _BLHeli Suite_ and the _AM32 configurator_, to communicate with the ESC using UART over MAVLink.
|
||||
Note that a MAVLink-to-UART bridge is required on the ground station or companion computer side (you'll need to write your own).
|
||||
On STM32F7/H7 boards, PX4 can pass UART traffic through an ESC signal pin using a software bit-bang UART.
|
||||
This lets ESC configuration and firmware tools on a ground station or companion computer talk to the ESC over MAVLink, without disconnecting it from the flight controller.
|
||||
|
||||
To use it, run the [bridge application](../uart/serial_passthrough.md#bridge-application) (`Tools/mavlink_serial_bridge.py`) on the computer connected to the vehicle, and point the tool at the virtual serial port it creates.
|
||||
Only one ESC channel can be used at a time, at up to 19200 baud.
|
||||
|
||||
::: warning
|
||||
The `PASSTHRU_EN` parameter must be set to `1` (and the vehicle rebooted) before using ESC bitbang passthrough.
|
||||
This **disables DShot and PWM output** at boot.
|
||||
After the next reboot, `PASSTHRU_EN` automatically resets to `0`, thereby restoring normal DShot/PWM operation.
|
||||
ESC passthrough disables DShot and PWM outputs, so the motors can't be driven while it's in use.
|
||||
The bridge's `--setup` option sets `PASSTHRU_EN` to `1` and reboots the flight controller, which then boots with DShot and PWM outputs off.
|
||||
PX4 resets `PASSTHRU_EN` to `0` during that boot, so normal outputs return on the next reboot.
|
||||
:::
|
||||
|
||||
See [Serial Passthrough (MAVLink SERIAL_CONTROL)](../uart/serial_passthrough.md) for full configuration details.
|
||||
-->
|
||||
See [Serial Passthrough (MAVLink SERIAL_CONTROL)](../uart/serial_passthrough.md) for build configuration, supported channels, and limitations.
|
||||
@@ -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))
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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:<ip>:<port>`, or `udpin:0.0.0.0:14550`).
|
||||
A `udp:127.0.0.1:<port>` 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 <device_id>
|
||||
```
|
||||
|
||||
`<device_id>` 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 <device_id>`.
|
||||
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)
|
||||
|
||||
Reference in new issue
Block a user