Skip to content

Latest commit

 

History

History
216 lines (161 loc) · 8.44 KB

README.md

File metadata and controls

216 lines (161 loc) · 8.44 KB
Raw


An extensible cross-platform camera server built on top of GStreamer and Rust-MAVLink


Build status Cargo download Crate info Documentation


Key Features

  • Create and manage streams:
    • from local devices, like most USB cameras (using video4linux)
    • from remote devices, like most IP cameras
    • with supported encodings: H264, MJPG, Raw (YUYV)
  • REST API for full control over streams and easy integrations
    • With Swagger UI always available for easy development (What is this?)
  • Configure video4linux camera controls, like brightness, saturation, etc.
  • SDP files available, allowing easy access from video players like VLC
  • Redirect 3rd party streams, advertising them via MAVLink protocol
  • MAVLink protocol using rust-mavlink:
    • Work with multiple cameras
    • Interface video4linux camera controls
  • WebRTC-ready, for modern control stations, available from any H264 source.
  • Remember configured streams
  • Rotated logs with configurable path and verbosity level
  • Generate thumbnails/snapshots for streams from local devices
  • Configurable via CLI arguments
  • Cross-platform, deployed for x64 and armv7 Linux

Table of Contents

How to use it

1. Downloading

Download the mavlink-camera-manager binary for your architecture from our releases, or build it from sources as described here

2. Installing

  • First, install the required runtime dependencies (assuming a Ubuntu-based distro):
sudo apt update -y && \
sudo apt install -y --no-install-recommends \
   libgstreamer1.0-0 \
   libgstreamer-plugins-base1.0-0 \
   libgstreamer-plugins-bad1.0-0 \
   libgstrtspserver-1.0-0 \
   gstreamer1.0-x \
   gstreamer1.0-nice

note: We recommend GStreamer 1.24.0 or above. Previous versions have thread leaks when using WebRTC. You can check it by running gst-launch-1.0 --version.

  • Extract the zip
  • optionally, put the folder to your Linux PATH

3. Running

After the installation, the binary can be run by calling it from the terminal, as simple as:

mavlink-camera-manager --mavlink=tcpout:0.0.0.0:14000 --verbose

At this point, the API should be ready. By default, it's accessible from any computer in the same network at port 6020, but it is customizable using the --rest-server CLI argument.

For more information about the CLI arguments, mavlink-camera-manager --help will give a list of accepted parameters for your version.

  • Along with the REST API, a simple management interface is available at http://localhost:6020, in which streams can be created and managed: picture 1

  • For developers, the Swagger UI with documentation for the entire REST API can be found at http://localhost:6020/docs picture 2

Quick test guide

The short clip below shows how an H264 UDP stream can be configured using the management interface, and how it can be accessed as a WebRTC stream.

Creating H264 Usb camera stream and testing it via WebRTC

Receiving a stream from a MAVLink ground control station like QGroundControl

The video should automatically popup if you are using any modern GCS, like QGroundControl, that has support for MAVLink camera messages.

  1. Start mavlink-camera-manager
  2. Start mavproxy or sim_vehicle with a TCP server at 5777 (mavlink-camera-manager's default can be changed via the CLI argument --mavlink)
  3. Open your Ground Control Station
  4. Done

Receiving a stream from a GStreamer pipeline

  1. Start mavlink-camera-manager
  2. Run the following pipeline:
  • If RTSP (any encoding):
gstreamer-launch-1.0 rtspsrc location=$RTSP_ADDR latency=0 \
   ! decodebin
   ! fpsdisplaysink sync=false
  • If UDP (H264 only):
gstreamer-launch-1.0 udpsrc port=$PORT \
   ! application/x-rtp,payload=96 \
   ! rtph264depay \
   ! avdec_h264 discard-corrupted-frames=true \
   ! videoconvert
   ! fpsdisplaysink sync=false

How to build it

This section assumes a Ubuntu 24.04, adaptation will be necessary for other distros.

  1. Install the development dependencies:
sudo apt update -y &&\
sudo apt install -y --no-install-recommends \
   libunwind-dev \
   libclang-dev \
   pkg-config \
   build-essential \
   curl \
   gnupg \
   ca-certificates \
   git \
   libmount-dev \
   libsepol-dev \
   libselinux1-dev \
   libglib2.0-dev \
   libgudev-1.0-dev \
   gstreamer1.0-tools \
   gstreamer1.0-nice \
   libgstreamer1.0-dev \
   libgstreamer-plugins-base1.0-dev \
   libgstreamer-plugins-bad1.0-dev \
   libgstrtspserver-1.0-dev

  1. Install cargo if not available (official instructions here)

  2. Install NodeJS greater or equal to 19 (official instructions here), and the latest Yarn (official instructions here), as shown below:

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg &&\
echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" \
  | sudo tee /etc/apt/sources.list.d/nodesource.list &&\
curl -fsSL https://dl.yarnpkg.com/debian/pubkey.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/yarnkey.gpg &&\
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/yarn.list &&\
sudo apt-get update -y &&\
  sudo apt-get install -y --no-install-recommends \
  nodejs \
  yarn
  1. Clone this repository and enter it
git clone https://github.com/mavlink/mavlink-camera-manager.git &&\
cd mavlink-camera-manager
  1. Build it with cargo:
cargo build --release

note: If the compilation fails to find one of these packages, make sure that they are visible for pkg-config, which may be necessary to set PKG_CONFIG_PATH environment variable.

License

This project is licensed under the MIT License.

Project origins

The Mavlink Camera Manager project originated as a personal experiment by @patrickelectric, driven by the need to address a critical challenge in remotely operated vehicles – effectively managing and providing camera streams to the topside computer. At the time, there was a noticeable absence of open-source alternatives, which motivated the project's inception.

Over time, the project gained recognition and was officially embraced by Blue Robotics as a core development effort. It became an integral part of their operating system, BlueOS, and was widely distributed worldwide. The adoption of the Mavlink Camera Manager by Blue Robotics served as a testament to its capabilities and value.

Due to increasing interest from other developers and integrators, the project was transferred to the MAVLink organization on May 25, 2023.