Skip to main content

Crate moqros_cli

Crate moqros_cli 

Source
Expand description

§moqros-cli

crates.io

ROS 2 nodes that bridge topics to and from Media over QUIC (MoQ) relays, built on the moqros library:

  • moqros-pub publishes ROS topics to a relay: images as video, any other message type as JSON or CDR data.
  • moqros-sub subscribes to broadcasts and republishes them as ROS topics.
  • moqros-bridge does both in one node, over one relay connection.
moqros-pub --url http://localhost:4443/anon --topic /camera/image_raw --reliable
moqros-sub --url http://localhost:4443/anon --broadcast camera/image_raw --topic /remote/image

The moqros repository has a Docker sample that runs a relay, the bridges, and a browser viewer.

§Installing

The bridges need a ROS 2 environment, libvpx, pkg-config, and libclang at build time (see Development).

With cargo:

source /opt/ros/jazzy/setup.bash
IDL_PACKAGE_FILTER="std_msgs;sensor_msgs;geometry_msgs;nav_msgs;rosgraph_msgs;diagnostic_msgs" cargo install moqros-cli

As a ROS 2 package with colcon (crates/moqros-cli has an ament_cargo package.xml):

pip install colcon-cargo colcon-ros-cargo
cargo install cargo-ament-build

cd ~/ros2_ws/src && git clone https://github.com/yuma-m/moqros
cd ~/ros2_ws
rosdep install --from-paths src -iy
source /opt/ros/jazzy/setup.bash
colcon build
source install/setup.bash
ros2 run moqros-cli moqros-pub --help

§Features

FeatureWhat
av1AV1 through libaom. Needs libaom at build time (apt install libaom-dev, brew install aom).
h264H.264 through Cisco’s OpenH264 binary, loaded at runtime from OPENH264_LIBRARY.
hwHardware encoders through GStreamer. Needs the GStreamer development files at build time.

VP8 is always available.

§Bridge behavior

  • QoS: both bridges default to the best-effort sensor_data profile. Pass --reliable to match a reliable publisher, which is recommended for large uncompressed images. With best-effort QoS, large images are split into many UDP fragments, and losing any one of them drops the whole frame.

  • Latency: if the encoder falls behind, moqros-pub drops all but the newest pending image, and moqros-sub always jumps to the newest group.

  • Reconnects: the relay connection redials automatically, and moqros-sub resubscribes when a broadcast comes back. It also resubscribes when the relay retracts a broadcast or routes it to another publisher of the same name, since the relay doesn’t end subscriptions then.

  • Stamps and frames: moqros-pub announces each image topic’s header.stamp (as the capture time of the video timeline) and header.frame_id in the broadcast’s catalog, and moqros-sub republishes the images with them. The stamps stay in the publisher’s clock, sim time included. --stamp receive (or stamp=receive) stamps them with the local receive time instead, as does a publisher that announces no capture times; --frame-id (or frame_id=) overrides the frame.

  • Shutdown: on SIGINT or SIGTERM (docker stop, systemd), both bridges close the relay session before exiting, so the relay ends their broadcasts right away and a restarted moqros-pub can announce them again.

  • Logging: both bridges log their message rate every 10 s (message rate).

  • Diagnostics: every bridge node publishes one diagnostic_msgs/msg/DiagnosticStatus per topic and broadcast on /diagnostics each second (--diagnostics-period-ms, 0 turns it off), with the message counts and rate. A bridge that has received nothing for 5 s, or dropped more than half of its messages since the last report, is a warning; one waiting to restart is an error. View it with rqt_robot_monitor or ros2 topic echo /diagnostics. It needs bindings for diagnostic_msgs (include it in IDL_PACKAGE_FILTER); without them the node logs a warning and runs without diagnostics.

  • Codec: moqros-pub --codec vp8|av1|h264. AV1 needs the av1 feature. H.264 needs the h264 feature and Cisco’s OpenH264 binary:

    export OPENH264_LIBRARY=$(./scripts/fetch_openh264.sh)   # downloads from ciscobinary.openh264.org
    cargo run -p moqros-cli --features h264 --bin moqros-pub -- --codec h264 ...

    Browsers decode all three through WebCodecs; AV1 needs a reasonably recent browser.

  • Renditions (simulcast): moqros-pub --rendition 360p@500000 (repeatable) also encodes each video scaled down to 360 rows at 500 kbit/s, into a track of its own in the same broadcast; images no taller than a rendition skip it. Browsers pick a rendition themselves; moqros-sub --max-height 480 (or max_height=) republishes the largest rendition at most 480 rows tall instead of the largest. Each rendition costs one more encode per image, and bitrate changes at runtime only apply to the full-size one.

  • Hardware encoding: built with the hw feature, moqros-pub encodes on a GPU through GStreamer when it can (--hw auto, the default): VA-API on Intel and AMD GPUs, and NVENC on NVIDIA GPUs, for each codec the GPU supports (H.264 on most, AV1 on recent ones, VP8 on few). It tries each known encoder element and keeps the first one that starts and honors keyframe requests, logging which one it uses; with none, it logs a warning and encodes in software, so the codec’s own feature is still needed. A hardware encoder that fails mid-stream (e.g. after a GPU reset) is replaced by software, starting with a keyframe, and an encoder that failed at a resolution isn’t tried again at that resolution until the process restarts. --hw off always encodes in software, and --hw require fails instead of falling back. Decoding (moqros-sub) always runs in software.

    # Build: GStreamer development files. Run: the plugins with the encoders and parsers, and the GPU driver.
    sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
      gstreamer1.0-plugins-base gstreamer1.0-plugins-bad   # + gstreamer1.0-vaapi on Ubuntu 22.04
    cargo run -p moqros-cli --features hw,av1 --bin moqros-pub -- --codec av1 ...

    gst-inspect-1.0 va and gst-inspect-1.0 nvcodec list the encoders GStreamer found; the node needs access to the GPU (/dev/dri/renderD* for VA-API, the video or render group). With H.264 on a hardware encoder, OpenH264 is only loaded if the bridge has to fall back to software.

§ROS arguments and parameters

Both bridges accept the standard --ros-args: remap the node name (-r __node:=…) and namespace (-r __ns:=…), and set ROS parameters with -p or --params-file. Each command-line flag can also be set as a parameter of the same name in snake_case (--keyframe-interval-ms becomes keyframe_interval_ms). A flag on the command line wins over a parameter, and a parameter wins over environment variables and defaults. Bool flags also take a value (--reliable=false). Parameters are read at startup, and parameters that match no flag are ignored with a warning. The one exception is bitrate: setting it on a running node with video topics (ros2 param set /moqros_pub bitrate 500000) changes the video bitrate of every topic. VP8 and AV1 encoders adjust in place; H.264 and hardware encoders restart with a keyframe. Other parameters set at runtime only log that the node needs a restart. In a parameter file, key a namespaced node by its fully qualified name (/front/moqros_pub); the bare node name only matches in the root namespace.

ros2 run moqros-cli moqros-pub --ros-args -r __ns:=/front \
  -p topic:=/front/image_raw -p bitrate:=1000000 -p reliable:=true
ros2 run moqros-cli moqros-sub --ros-args --params-file crates/moqros-cli/config/moqros.yaml

A repeatable flag (--topic, --broadcast) takes a string array parameter, one element per occurrence (-p "topic:=[/a, /b]"). If the flag is also on the command line, the command line replaces the whole array.

The colcon package installs a launch file (moqros.launch.py) and a sample parameter file (config/moqros.yaml):

ros2 launch moqros-cli moqros.launch.py url:=http://localhost:4443/anon namespace:=camera

The launch file uses $MOQROS_URL when url isn’t given, and publishes the broadcast <namespace>/image_raw (namespace:=/front gives front/image_raw). For a client certificate (see Authentication), add tls_cert:=… tls_key:=…, or set $MOQROS_TLS_CERT and $MOQROS_TLS_KEY.

§Several topics

One moqros-pub can publish several topics, and one moqros-sub can republish several broadcasts. Repeat --topic or --broadcast, and add options after the name, separated by commas:

moqros-pub --topic /camera/image_raw --topic /imu,format=json --topic /scan,format=cdr,mode=stream
moqros-sub --broadcast camera/image_raw,topic=/remote/image --broadcast imu --broadcast scan,topic=/remote/scan
BridgeOptionsDefaults
moqros-pub --topic TOPIC,…format, type, mode, broadcast--format and --mode for every topic. The broadcast name is the topic without its leading slash.
moqros-sub --broadcast NAME,…topic, type, frame_id, stamp--frame-id and --stamp for every broadcast. The topic is /moqros/<broadcast> (/moqros/image for a lone broadcast).

moqros-bridge does both in one node and over one relay connection, e.g. for a robot that streams its camera and takes velocity commands. It takes --topic like moqros-pub and --broadcast like moqros-sub, with the same options. The flags that name a single topic or broadcast (--type, and the other side’s name) are left out; use the options instead:

moqros-bridge --topic /camera/image_raw --topic /odom,format=json --broadcast cmd_vel,topic=/cmd_vel

moqros-sub --broadcast-prefix robots also republishes every broadcast announced under robots/ (now or later), on /moqros/<broadcast> (--topic-template '/remote/{name}' names it otherwise). A broadcast whose name doesn’t make a plain topic name (e.g. robots/r-2/camera) is skipped with a warning; see Security.

Each topic becomes a broadcast of its own. --type and --broadcast of moqros-pub, and --topic and --type of moqros-sub, name a single topic, so they only work with one --topic or --broadcast. A topic without a type starts when it appears in the ROS graph, which tells its type. moqros-sub waits for all its broadcasts at once, and starts each one when it’s announced. It skips a broadcast whose topic it can’t create (e.g. a message type this build has no bindings for), and goes on with the rest. A topic or broadcast that stops or fails later is restarted on its own, one second later at first and up to 30 seconds later while it keeps failing, so the others go on. The node exits on SIGINT or SIGTERM, when the relay connection gives up, or when a topic can’t be started at all (e.g. an unavailable codec).

§Other message types

moqros-pub --format json|cdr publishes a topic of any message type. The default, --format video, is for sensor_msgs/msg/Image and sensor_msgs/msg/CompressedImage (JPEG or PNG, e.g. image_transport’s /camera/image_raw/compressed), which is decoded before it’s encoded as video. compressedDepth images aren’t supported.

moqros-pub --topic /imu --format json                  # the type is looked up in the ROS graph
moqros-pub --topic /scan,format=cdr,type=sensor_msgs/msg/LaserScan,mode=stream
moqros-sub --broadcast imu --topic /moqros/imu         # format and type come from the catalog
  • json: each message is one JSON document, in r2r’s mapping of the message fields. Any hang consumer can read it, including a browser; the web viewer shows the latest message. Large arrays (point clouds, images) get big and slow as JSON, so use cdr for those.
  • cdr: each message is its ROS serialization, passed through untouched. It’s compact and lossless, but only ROS-aware consumers can decode it. Images sent as cdr arrive uncompressed and bit-exact.
  • --mode snapshot (default): each message is a MoQ group of its own, and subscribers skip to the newest one when they fall behind. Suits sensor data and state.
  • --mode stream: messages go into one group and are delivered in order, none skipped. Suits logs and commands. The publisher and the relay keep the group’s messages, and a subscriber that joins late gets them all from the start of the group. A group holds at most 8192 messages or 32 MB (moq-net’s limits); the next message then starts a new group, and late joiners start there. For long-running, high-rate topics use snapshot.
  • Type: without --type, moqros-pub waits for the topic to appear and asks the ROS graph for its type. Relative topic names resolve against the node’s namespace, but remappings aren’t applied. The type goes into the catalog, so moqros-sub republishes with the same type (--type overrides it).
  • Supported types: r2r generates message bindings at build time, and the data bridges only handle types it generated. With IDL_PACKAGE_FILTER set, list every package you need (the Docker image includes std_msgs, sensor_msgs, geometry_msgs, nav_msgs, rosgraph_msgs, and diagnostic_msgs).

moqros-sub handles both kinds of broadcast: it republishes video as rgb8 images (--encoding or encoding= picks bgr8, rgba8, bgra8 or mono8 instead, e.g. for OpenCV), and data tracks as their message type. It fails if a broadcast comes back carrying something different from before.

§Security

Keep these in mind before you connect the bridges to a relay beyond localhost:

  • Anyone the relay lets publish can reach ROS. moqros-sub republishes whatever arrives on its broadcasts as ROS messages. On a relay with anonymous publishing, someone else can publish under the same name and inject messages into your ROS graph, e.g. geometry_msgs/msg/Twist on a command topic. Broadcast names aren’t secret: subscribers can list what’s announced under a path.
  • --broadcast-prefix lets publishers create topics. Every broadcast announced under the prefix becomes a ROS topic on this node, named after the broadcast and typed by its catalog. Only names that make plain topic names (letters, digits, _ and /) are used, and each broadcast and topic is taken once, but use a prefix only on a relay where you trust everyone who may publish under it.
  • Decoded pictures are capped. A few bytes of bitstream can declare a huge picture, so moqros-sub rejects pictures above 8K UHD (7680×4320 pixels) instead of allocating them, and resubscribes.
  • http:// relay URLs trust the network. QUIC always encrypts the stream, but with an http:// URL the client fetches the certificate fingerprint it trusts over plain HTTP, so anyone on the path can swap it and read or alter the stream. --insecure skips verification entirely. Outside development, give the relay a real certificate ([listen] tls.cert/tls.key) and use https:// URLs. The bridges log a warning at startup for an http:// URL whose host isn’t this machine (localhost, *.localhost, a loopback address), and for --insecure.

§Authentication

Replace public in the relay’s [auth] section with url, pointing at an auth server: the relay asks it about every session. moq auth serve from the moq project is the reference one. It admits a session by a client certificate (mTLS) or a JWT, and grants publish and subscribe patterns. See the upstream authentication documentation for its flags. Give each client only what it needs: the robot publishes, viewers subscribe.

Bridges: client certificates. For a device that runs unattended, issue it a certificate from your own CA. Point the relay’s [listen] tls.root at the CA, and pass the certificate and its key to the bridge:

moqros-pub --url https://relay.example.com/robot --tls-cert robot.pem --tls-key robot.key --topic /camera/image_raw

--tls-cert and --tls-key also come from MOQROS_TLS_CERT and MOQROS_TLS_KEY, or the tls_cert and tls_key ROS parameters; in the library, use ClientConfig::with_client_cert. Nothing secret goes into the URL, and you revoke a device by its certificate. moq auth serve grants every certificate its CA signed the same patterns. To scope each device to its own path, run an auth server of your own that decides by the certificate’s name or fingerprint, which the relay passes along with each session.

Viewers: JWTs. Browsers present a JWT in the jwt query parameter of the relay URL. Issue it from your own backend once the viewer has signed in, signed with the key moq auth serve verifies, and add it to the viewer’s relay URL (see the web viewer). A token’s root is the path it’s valid under, and its publish and subscribe patterns say what it may do there.

The bridges accept a token too (--url "https://relay.example.com/robot?jwt=…"), but prefer certificates: a URL ends up in shell history and process lists, and the bridges reuse it on every reconnect without asking for a new token, so once it expires they can’t reconnect. They do hide the token (jwt=REDACTED, or a JWT-shaped path segment as /REDACTED) when they log the URL.

§Cloudflare MoQ relay

The bridges and the web viewer also work with Cloudflare’s MoQ relays, which speak the IETF MoQ Transport drafts (draft-16 here). Create a relay in the Cloudflare dashboard (Media > Realtime > MoQ Relay) or through its API; it comes with a publish/subscribe token and a subscribe-only token. The token goes in the URL path:

moqros-pub --url "https://draft-16.cloudflare.mediaoverquic.com/$CF_PUB_TOKEN" --topic /camera/image_raw
moqros-sub --url "https://draft-16.cloudflare.mediaoverquic.com/$CF_SUB_TOKEN" --broadcast camera/image_raw

For the viewer, put the subscribe-only token’s URL in the Relay URL field. Each token covers its whole relay, so give viewers the subscribe-only one. The bridges hide the token (/REDACTED) when they log the URL, but Cloudflare’s own access logs see it, and so do shell history and process lists; prefer short-lived tokens and revoke them after testing. The relays are a beta product, so the endpoint and the drafts it speaks may change.

§License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

§Library

The library part of this crate is shared plumbing for the bridge binaries, not a stable API. Use moqros instead.

Structs§

Bridges
What a bridge node does: ROS topics to publish to the relay, and broadcasts to republish on ROS.
BroadcastSpec
A broadcast for moqros-sub: BROADCAST[,topic=…][,type=…][,frame_id=…][,stamp=…][,max_height=…][,encoding=…].
DiagnosticsArgs
Diagnostics flags.
Discovery
Broadcasts moqros-sub finds by prefix, and republishes on topics named after them.
EncoderArgs
Video encoder flags.
PubTopic
What moqros-pub does with one topic.
QosArgs
ROS QoS flags.
Relay
The relay connection of a bridge node: a publisher for its topics, a subscriber for its broadcasts, or both over one connection.
RelayArgs
Relay connection flags.
RepublishArgs
How MoQ -> ROS bridges republish video.
RepublishOptions
How a broadcast’s video is republished on ROS: from the flags, or a broadcast’s options.
SharedNode
A node shared between spawn_spinner and code that adds subscriptions while it spins.
Spinner
Stops the spawn_spinner thread when dropped.
SubBroadcast
What moqros-sub does with one broadcast.
TopicSpec
A topic for moqros-pub: TOPIC[,format=…][,type=…][,mode=…][,broadcast=…].

Enums§

Format
What moqros-pub sends.

Constants§

DEFAULT_SUB_TOPIC
Topic of a lone broadcast that neither topic= nor --topic names.
DEFAULT_TOPIC_TEMPLATE
Default of Discovery::topic_template.

Functions§

check_no_loop
Refuse a bridge that would feed its own output back in: a broadcast or a ROS topic that both directions use. Every message would go round the loop forever.
init
Create the ROS node and parse T from the command line and the node’s ROS parameters.
init_logging
parse_encoding
Parse a pixel encoding images can be republished in: rgb8, bgr8, rgba8, bgra8 or mono8.
pub_topics
Fill in each topic’s options from the flags: format and mode apply to every topic, while ros_type and broadcast name one topic, so they need exactly one.
run_bridges
Run bridges until the relay connection gives up, the ROS spinner dies, or SIGINT or SIGTERM arrives (which closes the connection first, so the relay ends this node’s broadcasts and subscriptions right away).
shutdown_signal
Resolves with the signal’s name on the first SIGINT (Ctrl-C) or SIGTERM (docker stop, systemd), so the bridges can close their relay connection before exiting.
spawn_spinner
Spin node on a blocking thread until the returned guard is dropped.
strip_ros_args
Drop the ROS arguments (--ros-args … [--], possibly repeated) from args.
sub_broadcasts
Fill in each broadcast’s options from the flags: options apply to every broadcast, while topic and ros_type name one broadcast, so they need exactly one. Without either topic= or --topic, a lone broadcast goes to DEFAULT_SUB_TOPIC, and each of several to /moqros/<broadcast>.