Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-03-23 10:03:41 +08:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

feat(boards/modalai/voxl2): add Debian packaging framework

Browse Source 
Add a scalable .deb packaging framework for VOXL2, built on the
existing cmake/package.cmake CPack infrastructure. The framework
handles multi-processor boards by having the POSIX (_default) build
own the .deb and pull in the companion SLPI build's artifacts.

Board-specific files:
- cmake/package.cmake: CPack variable overrides (name, deps, version)
- cmake/install.cmake: install() rules for all .deb contents
- debian/postinst: px4-* symlinks, DSP signature, directory setup
- debian/prerm: service stop, symlink cleanup
- debian/voxl-px4.service: systemd unit (after sscrpcd)

Infrastructure changes:
- cmake/package.cmake: hook for board-specific CPack overrides
- platforms/posix/CMakeLists.txt: hook for board install.cmake
- Makefile: %_deb pattern rule (build _default, then cpack -G DEB)
- CI: auto-discover _deb targets, collect .deb artifacts, upload
  to GitHub Releases

Future boards: add cmake/package.cmake + cmake/install.cmake and
CI discovers it automatically. No new file formats or tools needed.

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Ramon Roche
2026-03-13 21:59:58 -07:00
parent 9901b3c156
commit adb2df5ca7
13 changed files with 576 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/en/SUMMARY.md
View File

@@ -476,6 +476,7 @@
- [Flight Controller Porting Guide](hardware/porting_guide.md)
- [PX4 Board Configuration (kconfig)](hardware/porting_guide_config.md)
- [NuttX Board Porting Guide](hardware/porting_guide_nuttx.md)
- [Board Firmware Packaging (.deb)](hardware/board_packaging.md)
- [Serial Port Mapping](hardware/serial_port_mapping.md)
- [Airframes](dev_airframes/index.md)
- [Adding a New Airframe](dev_airframes/adding_a_new_frame.md)

298
docs/en/hardware/board_packaging.md Normal file
View File

@@ -0,0 +1,298 @@
# Board Firmware Packaging
PX4 supports building distributable firmware packages for Linux-based (POSIX) boards.
While NuttX boards produce `.px4` firmware files that are flashed via QGroundControl, POSIX boards can produce `.deb` (Debian) packages that are installed using standard Linux package management tools (`dpkg`, `apt`).
This page covers how manufacturers can add `.deb` packaging to their boards, with examples for both single-processor and multi-processor architectures.
## Overview
The packaging framework uses [CMake CPack](https://cmake.org/cmake/help/latest/module/CPack.html) with the DEB generator.
It is built on two extension points in the PX4 build system:
- **`boards/<vendor>/<board>/cmake/package.cmake`**: CPack variable overrides (package name, version, dependencies, architecture, maintainer info). Loaded during CMake configure.
- **`boards/<vendor>/<board>/cmake/install.cmake`**: `install()` rules that define what goes into the package (binaries, scripts, config files, service files). Loaded from `platforms/posix/CMakeLists.txt` where build targets are available.
When a board provides these files, CI automatically discovers and builds the `_deb` target alongside the normal firmware build.
## Build Command
For any board with packaging support:
```sh
make <vendor>_<board>_deb
```
For example:
```sh
make modalai_voxl2_deb
```
This builds the `_default` configuration (and any companion builds for multi-processor boards), then runs `cpack -G DEB` in the build directory.
The resulting `.deb` file is placed in `build/<vendor>_<board>_default/`.
## Adding Packaging to a Board
### File Structure
```
boards/<vendor>/<board>/
cmake/
package.cmake # CPack configuration (required)
install.cmake # Install rules (required)
debian/
postinst # Post-install script (optional)
prerm # Pre-remove script (optional)
<name>.service # Systemd unit file (optional)
```
### Step 1: CPack Configuration (package.cmake)
This file sets CPack variables that control the `.deb` metadata.
It is included from `cmake/package.cmake` after the base CPack defaults are configured.
```cmake
# boards/<vendor>/<board>/cmake/package.cmake
# Derive Debian-compatible version from git tag
# v1.17.0-alpha1-42-gabcdef -> 1.17.0~alpha1.42.gabcdef
# v1.17.0 -> 1.17.0
string(REGEX REPLACE "^v" "" _deb_ver "${PX4_GIT_TAG}")
string(REGEX REPLACE "-" "~" _deb_ver "${_deb_ver}")
string(REGEX REPLACE "~([0-9]+)~" ".\\1." _deb_ver "${_deb_ver}")
# Target architecture (use the target arch, not the build host)
set(CPACK_DEBIAN_ARCHITECTURE "arm64")
# Package identity
set(CPACK_DEBIAN_PACKAGE_NAME "my-px4-board")
set(CPACK_DEBIAN_FILE_NAME "my-px4-board_${_deb_ver}_arm64.deb")
# Install prefix
set(CPACK_PACKAGING_INSTALL_PREFIX "/usr")
set(CPACK_INSTALL_PREFIX "/usr")
set(CPACK_SET_DESTDIR true)
# Package metadata
set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "PX4 Autopilot for My Board")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Vendor <support@vendor.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS "some-dependency (>= 1.0)")
set(CPACK_DEBIAN_PACKAGE_CONFLICTS "")
set(CPACK_DEBIAN_PACKAGE_REPLACES "")
# Disable shlibdeps for cross-compiled boards
set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS OFF)
# Include post-install and pre-remove scripts (optional)
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
"${PX4_BOARD_DIR}/debian/postinst;${PX4_BOARD_DIR}/debian/prerm")
```
**Key variables:**
| Variable | Purpose |
|---|---|
| `CPACK_DEBIAN_ARCHITECTURE` | Target architecture. Set explicitly for cross-compiled boards since `dpkg --print-architecture` reports the build host, not the target. |
| `CPACK_DEBIAN_PACKAGE_NAME` | Package name as it appears in `dpkg -l`. |
| `CPACK_DEBIAN_FILE_NAME` | Output `.deb` filename. |
| `CPACK_DEBIAN_PACKAGE_DEPENDS` | Runtime dependencies (comma-separated, Debian format). |
| `CPACK_DEBIAN_PACKAGE_SHLIBDEPS` | Set to `OFF` for cross-compiled boards where `dpkg-shlibdeps` cannot inspect target binaries. |
### Step 2: Install Rules (install.cmake)
This file defines what files are packaged in the `.deb`.
It is included from `platforms/posix/CMakeLists.txt` where the `px4` build target is available.
All paths are relative to `CPACK_PACKAGING_INSTALL_PREFIX` (typically `/usr`). Use `../` to install outside the prefix (e.g., `../etc/` installs to `/etc/`).
**Minimal example (single-processor board):**
```cmake
# boards/<vendor>/<board>/cmake/install.cmake
# PX4 binary
install(TARGETS px4 RUNTIME DESTINATION bin)
# Module alias script (generated during build)
install(PROGRAMS ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/px4-alias.sh DESTINATION bin)
# Startup scripts
install(PROGRAMS
${PX4_BOARD_DIR}/target/my-px4-start
DESTINATION bin
)
# Configuration files
install(FILES
${PX4_BOARD_DIR}/target/my-config.conf
DESTINATION ../etc/my-board
)
# Systemd service
install(FILES ${PX4_BOARD_DIR}/debian/my-px4.service
DESTINATION ../etc/systemd/system
)
# Component metadata
install(FILES
${PX4_BINARY_DIR}/actuators.json.xz
${PX4_BINARY_DIR}/parameters.json.xz
DESTINATION ../data/px4/etc/extras
OPTIONAL
)
install(FILES ${PX4_BINARY_DIR}/events/all_events.json.xz
DESTINATION ../data/px4/etc/extras
OPTIONAL
)
```
### Step 3: Debian Scripts (optional)
#### postinst
Runs after the package is installed. Common tasks:
- Create `px4-*` module symlinks from `px4-alias.sh`
- Set up required directories with correct ownership
- Run `systemctl daemon-reload` to pick up the service file
- Board-specific setup (e.g., DSP signature generation)
```bash
#!/bin/bash
set -e
# Create px4-* symlinks
if [ -f /usr/bin/px4-alias.sh ]; then
grep "^alias " /usr/bin/px4-alias.sh | \
sed "s/alias \(px4-[a-zA-Z0-9_]*\)=.*/\1/" | while read cmd; do
ln -sf px4 "/usr/bin/${cmd}"
done
fi
# Create data directories
mkdir -p /data/px4/param
mkdir -p /data/px4/etc/extras
# Reload systemd
if command -v systemctl > /dev/null 2>&1; then
systemctl daemon-reload
fi
```
#### prerm
Runs before the package is removed:
```bash
#!/bin/bash
set -e
# Stop the service
if command -v systemctl > /dev/null 2>&1; then
systemctl stop my-px4 2>/dev/null || true
fi
# Remove px4-* symlinks
for f in /usr/bin/px4-*; do
if [ -L "$f" ] && [ "$(readlink "$f")" = "px4" ]; then
rm -f "$f"
fi
done
```
Both scripts must be executable (`chmod +x`).
## Multi-Processor Boards
Some boards run PX4 across multiple processors, for example the ModalAI VOXL2 which has a POSIX apps processor (ARM) and a Hexagon DSP (SLPI).
These produce two separate CMake builds, but the `.deb` must contain artifacts from both.
### How It Works
1. The `_default` build (POSIX/apps processor) owns the `.deb`.
2. The Makefile `%_deb` target builds `_default`, which chains any companion builds as CMake prerequisites.
3. The `install.cmake` pulls companion build artifacts via absolute path to the sibling build directory.
4. CPack runs in the `_default` build tree and produces a single `.deb`.
### Companion Build Artifacts
In `install.cmake`, reference the companion build output by absolute path:
```cmake
# DSP firmware blob from companion SLPI build
set(SLPI_BUILD_DIR "${PX4_SOURCE_DIR}/build/<vendor>_<board>-slpi_default")
install(FILES ${SLPI_BUILD_DIR}/platforms/qurt/libpx4.so
DESTINATION lib/rfsa/adsp
OPTIONAL
)
```
The `OPTIONAL` keyword allows the `.deb` to build even when the companion build hasn't run (useful for development/testing of just the apps-processor side).
### VOXL2 Reference
The VOXL2 board is a complete working example of multi-processor packaging:
```
boards/modalai/voxl2/
cmake/
package.cmake # CPack config: voxl-px4, arm64, deps, shlibdeps off
install.cmake # px4 binary, SLPI libpx4.so, scripts, configs, metadata
debian/
postinst # Symlinks, DSP signature, directory setup
prerm # Stop service, remove symlinks
voxl-px4.service # Systemd unit (after sscrpcd, restart on-failure)
target/
voxl-px4 # Main startup wrapper
voxl-px4-start # PX4 module startup script
```
The resulting `.deb` installs:
| Path | Contents |
|---|---|
| `/usr/bin/px4` | Apps processor PX4 binary |
| `/usr/bin/px4-alias.sh` | Module alias script |
| `/usr/bin/voxl-px4` | Startup wrapper |
| `/usr/bin/voxl-px4-start` | Module startup script |
| `/usr/lib/rfsa/adsp/libpx4.so` | DSP firmware (from SLPI build) |
| `/etc/modalai/*.config` | Board configuration files |
| `/etc/systemd/system/voxl-px4.service` | Systemd service |
| `/data/px4/etc/extras/*.json.xz` | Component metadata |
## CI Integration
### Automatic Discovery
The CI system (`Tools/ci/generate_board_targets_json.py`) automatically discovers boards with `cmake/package.cmake` and adds a `<vendor>_<board>_deb` target to the board's existing CI group.
No manual CI configuration is needed.
### Artifact Collection
The `Tools/ci/package_build_artifacts.sh` script collects `.deb` files alongside `.px4` and `.elf` artifacts.
On tagged releases, `.deb` files are uploaded to both S3 and GitHub Releases.
## Version Format
The `.deb` version is derived from `PX4_GIT_TAG` using Debian-compatible formatting:
| Git Tag | Debian Version | Notes |
|---|---|---|
| `v1.17.0` | `1.17.0` | Stable release |
| `v1.17.0-beta1` | `1.17.0~beta1` | Pre-release (`~` sorts before release) |
| `v1.17.0-alpha1-42-gabcdef` | `1.17.0~alpha1.42.gabcdef` | Development build |
The `~` prefix in Debian versioning ensures pre-releases sort lower than the final release: `1.17.0~beta1 < 1.17.0`.
## Checklist for New Boards
1. Create `boards/<vendor>/<board>/cmake/package.cmake` with CPack variables
2. Create `boards/<vendor>/<board>/cmake/install.cmake` with install rules
3. (Optional) Create `boards/<vendor>/<board>/debian/postinst` and `prerm`
4. (Optional) Create `boards/<vendor>/<board>/debian/<name>.service`
5. Test locally: `make <vendor>_<board>_deb`
6. Verify: `dpkg-deb --info build/<vendor>_<board>_default/<name>_*.deb`
7. Verify: `dpkg-deb --contents build/<vendor>_<board>_default/<name>_*.deb`
8. CI picks it up automatically on the next push