paparazzi/sw/ext/README.md

External Libraries and Tools

This directory contains git submodules referencing external libraries and tools used by Paparazzi. These modules provide essential functionality for communications, flight control, simulation, cryptography, and more.

Table of Contents

• Quick Start
• Installing All Modules
• Installing Individual Modules
• Available Modules
• OpenCV Bebop Setup
• Troubleshooting

---

Quick Start

Initialize and build all external modules:

make -C sw/ext

This will checkout and compile all dependencies automatically.

---

Installing All Modules

To install and build all external modules at once:

make -C sw/ext

This runs the complete build chain for all modules that require compilation (chibios, fatfs, libsbp, TRICAL, hacl-c, key_generator, rustlink, ecl, matrix, mavlink, dronecan, and unifiedmocaprouter).

---

Installing Individual Modules

To install or update only a specific module, run:

make -C sw/ext <module-name>

Example:

make -C sw/ext chibios
make -C sw/ext mavlink

Each module target will sync and update the git submodule, then build if required.

---

Available Modules

See the main Makefile in this directory for the complete list of modules and their build targets. Common modules include:

• chibios — Operating system for embedded systems
• fatfs — FAT filesystem library
• mavlink — MAVLink message definitions and code generation
• pprzlink — Paparazzi-specific communications protocol
• libsbp — Swift Binary Protocol for GNSS/RTK
• TRICAL — Magnetometer automatic calibration
• opencv_bebop — Computer vision library (see detailed instructions below)
• dronecan — DroneCAN protocol support
• And many more... — See Makefile for details

---

OpenCV Bebop Setup

This module provides advanced computer vision capabilities for Bebop drones.

Prerequisites

This guide has been tested on Ubuntu 22.04. For Ubuntu 20.04 instructions, see: conf/modules/cv_opencvdemo.xml

Building OpenCV Bebop

From the paparazzi source directory:

cd sw/ext
make opencv_bebop

Verify Installation

After a successful build, you should have these directories:

sw/ext/opencv_bebop/build_arm/
sw/ext/opencv_bebop/build_pc/
sw/ext/opencv_bebop/install_arm/
sw/ext/opencv_bebop/install_pc/

These contain compiled binaries for ARM (autopilot) and PC (simulation) targets.

Configuring Your Airframe Module

To use OpenCV in your airframe, configure your module XML with build flags for both autopilot (ap) and simulation (nps) targets.

Example airframe module configuration:

<makefile target="ap">
    <file name="opencv_example.cpp"/>
    <file name="opencv_image_functions.cpp"/>
    <flag name="CXXFLAGS" value="I$(PAPARAZZI_SRC)/sw/ext/opencv_bebop/install_arm/include/opencv4"/>
    
    <flag name="LDFLAGS" value="L$(PAPARAZZI_HOME)/sw/ext/opencv_bebop/install_arm/lib"/>
    <flag name="LDFLAGS" value="lopencv_world"/>
    <flag name="LDFLAGS" value="L$(PAPARAZZI_HOME)/sw/ext/opencv_bebop/install_arm/lib/opencv4/3rdparty"/>
    <flag name="LDFLAGS" value="llibprotobuf"/>
    <flag name="LDFLAGS" value="llibjpeg-turbo"/>
    <flag name="LDFLAGS" value="llibpng"/>
    <flag name="LDFLAGS" value="llibtiff"/>
    <flag name="LDFLAGS" value="llibopenjp2"/>
    <flag name="LDFLAGS" value="lzlib"/>
    <flag name="LDFLAGS" value="lade"/>
    <flag name="LDFLAGS" value="ldl"/>
    <flag name="LDFLAGS" value="lm"/>
    <flag name="LDFLAGS" value="lpthread"/>
    <flag name="LDFLAGS" value="lrt"/>
  </makefile>
  <makefile target="nps">
    <file name="opencv_example.cpp"/>
    <file name="opencv_image_functions.cpp"/>
    
    <flag name="CXXFLAGS" value="I$(PAPARAZZI_SRC)/sw/ext/opencv_bebop/install_pc/include/opencv4"/>
    
    <flag name="LDFLAGS" value="L$(PAPARAZZI_HOME)/sw/ext/opencv_bebop/install_pc/lib"/>
    <flag name="LDFLAGS" value="lopencv_world"/>
    <flag name="LDFLAGS" value="L$(PAPARAZZI_HOME)/sw/ext/opencv_bebop/install_pc/lib/opencv4/3rdparty"/>
    <flag name="LDFLAGS" value="llibprotobuf"/>
    <flag name="LDFLAGS" value="lade"/>
    <flag name="LDFLAGS" value="L/usr/lib/x86_64-linux-gnu"/>
    <flag name="LDFLAGS" value="ljpeg"/>
    <flag name="LDFLAGS" value="lpng"/>
    <flag name="LDFLAGS" value="ltiff"/>
    <flag name="LDFLAGS" value="lopenjp2"/>
    <flag name="LDFLAGS" value="L/usr/lib/x86_64-linux-gnu/hdf5/serial"/>
    <flag name="LDFLAGS" value="lhdf5"/>
    <flag name="LDFLAGS" value="lcrypto"/>
    <flag name="LDFLAGS" value="lcurl"/>
    <flag name="LDFLAGS" value="lpthread"/>
    <flag name="LDFLAGS" value="lsz"/>
    <flag name="LDFLAGS" value="lz"/>
    <flag name="LDFLAGS" value="ldl"/>
    <flag name="LDFLAGS" value="lm"/>
    <flag name="LDFLAGS" value="lfreetype"/>
    <flag name="LDFLAGS" value="lharfbuzz"/>
    <flag name="LDFLAGS" value="lrt"/>

  </makefile>
</module>

Using OpenCV in C++ Code

Include the OpenCV headers in your C++ files:

#include "opencv_image_functions.h"

using namespace std;
#include <opencv2/core/core.hpp>
#include <opencv2/imgproc/imgproc.hpp>
using namespace cv;

You can then use provided wrapper functions like grayscale_opencv_to_yuv422() in your code:

// Convert and process images
Mat image = imread("image.jpg");
Mat gray;
cvtColor(image, gray, COLOR_BGR2GRAY);
// ... your vision processing

Team Consistency

Important: Ensure all team members use the same build environment and configuration. Inconsistent builds can lead to compatibility issues during testing and deployment, leading to high dependency on one laptop/person.

---

Troubleshooting

Build Failures

• Module not found: Ensure you're running make from the paparazzi root or using make -C sw/ext
• Dependency errors: Check that required packages are installed (see individual module documentation)
• Python build issues: Some modules (mavlink, dronecan) require Python packages. See Makefile for details on MY_MAVLINKTOOLS and MY_DRONECANTOOLS

Submodule Issues

If a submodule is in a bad state, reinitialize it:

# Sync and reset a specific module
cd <paparazzi-root>
git submodule sync sw/ext/<module-name>
git submodule update --init --recursive sw/ext/<module-name>

# Or reset all modules
git submodule update --init --recursive

---