Link Search Menu Expand Document
Source on GitLab

Pipe Utilities

These are the everyday commands for working with MPA pipes: listing what’s available in /run/mpa, reading a pipe’s info, sending control commands, shutting down a pipe’s server, and recording camera pipes to disk. They are small companions to libmodal-pipe, which defines the pipe architecture itself. Most live in the voxl-mpa-tools package; voxl-inspect-pipe-info ships with libmodal-pipe.

Table of contents

  1. voxl-list-pipes
  2. voxl-inspect-pipe-info
  3. voxl-send-command
  4. voxl-kill-pipe
  5. voxl-record-video
  6. voxl-record-raw-image
  7. Source

voxl-list-pipes

Lists all available MPA pipes in /run/mpa, grouped and sorted by pipe type (read from each pipe’s info file). Use -t <type> to print only pipe names of one type.

voxl2:/$ voxl-list-pipes --help

voxl-list-pipes

List all of the available MPA pipes

Options:
	-h|--help        : Show this help message
	-t <type>        : Show only pipes of this type

voxl2:/$ voxl-list-pipes -t imu_data_t

imu_apps

voxl-inspect-pipe-info

Reads and pretty-prints the JSON info file for a pipe, showing its name, location, type, owning server, pipe size, and server PID, plus the pipe’s available_commands when the server declares them.

voxl2:/$ voxl-inspect-pipe-info --help

Tool to read and print the json info for a pipe

-h, --help                print this help message

example useage:

/# voxl-inspect-pipe-info imu_apps

voxl2:/$ voxl-inspect-pipe-info imu_apps

{
	"name":	"imu_apps",
	"location":	"/run/mpa/imu_apps/",
	"type":	"imu_data_t",
	"server_name":	"voxl-imu-server",
	"size_bytes":	131072,
	"server_pid":	2214
}

voxl-send-command

Sends a control command to a pipe’s control channel by writing it into /run/mpa/<pipe>/control. The first argument is the pipe name (or path); everything after it is sent as the command. The commands a server accepts are listed in the available_commands field of its pipe info, which you can read with voxl-inspect-pipe-info.

voxl2:/$ voxl-send-command qvio reset_vio_soft

Successfully sent command to /run/mpa/qvio/control

If the pipe does not exist or has no control channel, it prints Unable to find valid pipe that accepts control commands at: <pipe> and exits with an error.

voxl-kill-pipe

Tells the server that owns a given pipe to shut down, and cleans up any dangling pipes it leaves behind.

voxl2:/$ voxl-kill-pipe --help

Tool to stop the owning process for a given pipe name
and clean up any dangling pipes that may remain.

This will first send SIGINT to simulate ctrl-C and wait
for the specified timeout (default 2 seconds).
If the process does not exit gracefully in the timeout, it
will be sent SIGKILL to force the process to stop with blind
and barbaric fury.

If the process does not exit gracefully, it may leave the
specified pipe dangling in the file system. If that were to
occur, this program will cleanup the pipe from the file system.

You can perform this same operation with this function that is
part of libmodal_pipe: pipe_kill_server_process(pipe_path, 2.0)

-h, --help                print this help message
-t, --timeout_s{seconds}  timeout to wait before sending SIGKILL
                            default is 2.0 seconds.

example useage:

long method to kill voxl-imu-server:
/# voxl_kill_pipe /run/mpa/imu0/

shortcut method to kill voxl-camera-server
/# voxl_kill_pipe tracking

voxl2:/$ voxl-kill-pipe tracking

voxl-record-video

Records an encoded camera pipe to disk as an H.264/H.265 video file (default output /data/video/voxl-record-video.h264). Encoder parameters can be overridden on the command line. Stop recording with Ctrl-C; the tool prints the output file path on exit.

voxl2:/$ voxl-record-video --help

Record camera pipe to disk

Options are:
  -o, --out <path>          Output file path
  -h, --help                Print this help message

Encoder options (override defaults):
      --qfixed <int>        Fixed QP (default 38)
      --qmin <int>          Min QP (default 15)
      --qmax <int>          Max QP (default 50)
      --pframes <int>       Number of P-frames between I-frames (default 29)
      --mbps <float>        Target Mbps for CBR/CQP (default 2.00)
      --codec <h264|h265>   Codec (default h265)
      --br <cbr|vbr|cq>     Bitrate control (default cbr)

Examples:
  voxl-record-video hires
  voxl-record-video hires -o /data/vid.h265 --codec h265 --qfixed 34 --pframes 29 --mbps 3.0 --br cbr

voxl2:/$ voxl-record-video hires -o /data/vid.h265

voxl-record-raw-image

Saves raw frames from a camera pipe to disk (default directory /data/raw-images/), typically for inspecting raw or YUV image formatting or for post-processing in MATLAB or OpenCV. Added in voxl-mpa-tools 1.5.9, it can also convert frames to JPEG (-j, with -q quality), skip frames between saves (-s), and embed the timestamp, exposure, and gain metadata in the file name (-m).

voxl2:/$ voxl-record-raw-image --help


Record a raw image from an MPA pipe to disk
This is typically used for inspecting raw or YUV
image data formatting or for loading into something
like MATLAB or OpenCV for post-processing.

Optional arguments are:
-d, --dir {dir}       directory to save output files in (default: /data/raw-images/)
-h, --help            print this help message
-j, --jpeg            convert to JPEG before saving (supports NV12, NV21, RGB, RAW8 formats)
-q, --jpeg-quality    JPEG quality for compression (1-100, default: 90)
-n, --num-images {n}  number of images to save from the pipe (default 1)
-m, --meta            save metadata in file name (timestamp (us), exposure (us), gain)
-s, --skip {n}        skip n frames before saving a new frame

typical usage:
-/# voxl-record-raw-image tracking
-/# voxl-record-raw-image tracking -d /data/tracking_test_1/ -n 10
-/# voxl-record-raw-image hires_misp_color -j -q 95

voxl2:/$ voxl-record-raw-image tracking -n 10

Source

voxl-list-pipes, voxl-send-command (scripts), voxl-kill-pipe, voxl-record-video, and voxl-record-raw-image (tools) are part of voxl-mpa-tools. voxl-inspect-pipe-info lives in libmodal-pipe.