HAL and tiers

The Hardware Abstraction Layer (HAL) is how the agent adapts to different companion computers. It identifies the board, loads the matching YAML profile, and hands the profile’s hardware facts (buses, encoders, cameras, radios, displays, GPIO) to the installer and the services. The board list is on Supported hardware.

Board detection

Detection lives in ados.hal.detect. It tries each source in order and stops at the first match:

/etc/ados/board_override, if present. It holds a board profile’s YAML file name without the extension (for example rock-5c-lite). Use it as the manual correction when detection picks the wrong board. An unknown value is logged and ignored.
The first token of /proc/device-tree/compatible, which uniquely identifies a board even when several boards share a model string.
/proc/device-tree/model, matched against each profile’s model_patterns.
The Hardware or model line of /proc/cpuinfo, matched the same way.
The generic profile for the architecture: generic-arm64, or generic-x86_64 on x86.

Some boards ship one device tree for several hardware bins. A profile can list variants, which are resolved by CPU core count. RAM and core count come from psutil. The result is persisted as a hardware snapshot; print it with:

ados hardware show --json

Default tier

Each board profile declares a default_tier (1-4) describing compute class. It is reported in status and used to refuse plugins whose compatibility.min_tier the board cannot meet. Which services run is decided by the node profile (drone/ground_station/workstation/compute), not the tier. The generic profiles are tiered from detected RAM:

Detected RAM	Tier
Under 512 MB	1
512 MB to under 2 GB	2
2 GB to 4 GB	3
Over 4 GB	4

See Node profiles for what each profile runs, and Manifest for compatibility.min_tier.

Board profile schema

Each profile is a YAML file at src/ados/hal/boards/<name>.yaml, validated by the BoardProfile Pydantic model in src/ados/hal/detect.py. Keys the model does not define are ignored. The file name (without .yaml) is the board id used by board_override and by extension supported_boards lists.

Key	Type	Purpose
`name`	string, required	Human-readable board name.
`vendor`, `soc`, `arch`	string	Manufacturer, SoC model, and `aarch64`, `armv7l` or `x86_64`.
`model_patterns`	list of strings	Substrings matched against the device-tree compatible string, model and `/proc/cpuinfo`.
`default_tier`	1-4	Compute class. See Default tier.
`min_kernel_version`	string	Lowest supported kernel, when the board needs one.
`uart_paths`	list	Serial ports to probe for the flight controller.
`hw_video_codecs`	list	Hardware codecs such as `h264_enc`, `h265_enc`, `h264_dec`.
`gpio_pins`	list of ints	Free GPIO pins.
`gpio_outputs`	list of `{id, pin, function}`	GPIO output lines such as a buzzer or status LED.
`gpio_buttons`	list of `{id, pin, header_pin, function}`	Front-panel button wiring.
`buttons`	`{up, down, select, back}`	Panel button pins by role. Without it the panel uses its built-in pins.
`video`	object	`csi_ports`, `csi_connector`, `max_encode_resolution`, `max_encode_fps`, `encoder_api`.
`compute`	object	`npu_tops` and `local_inference` (`none` or `onnx`, for a CPU strong enough to run the detector without an NPU).
`cameras.supported`	list	Camera bindings: type (`csi`, `usb`, `ip`), sensor, bus, overlay, ISP flags and capture modes.
`radios.supported`	list	Radios the installer builds a driver for: chipset, driver, install method, modules, `mesh_capable`.
`flight_controller.interfaces`	list	Priority-ordered flight controller links (`uart`, `usb-acm`, `usb`) with path and baud hints.
`displays.supported`	list	Display bindings: type, controller, bus, resolution, overlay, GPIO claims and touch controller.
`variants`	list	Same-device-tree variants selected by `cpu_cores`, overriding `name`, `soc` or `default_tier`.

A short real profile, cm4.yaml:

name: "Raspberry Pi CM4"
vendor: "Raspberry Pi"
soc: "BCM2711"
arch: "aarch64"
model_patterns:
  - "Raspberry Pi Compute Module 4"
  - "Raspberry Pi CM4"
default_tier: 3
gpio_pins: [2, 3, 14, 15, 18]
uart_paths:
  - /dev/ttyAMA0
  - /dev/ttyS0
hw_video_codecs:
  - h264_enc
  - h264_dec
  - h265_dec
video:
  csi_ports: 0
  max_encode_resolution: "1920x1080"
  max_encode_fps: 30
  encoder_api: v4l2

For a profile that uses every section, read src/ados/hal/boards/rock-5c-lite.yaml or rk3576.yaml in the ADOSDroneAgent repository.

HAL modules

Module	Purpose
`detect.py`	Board identification and profile loading
`camera.py`	Camera detection (CSI, USB V4L2)
`camera_cli.py`	Camera helpers for the CLI
`gpio.py`	GPIO pin access for buttons and LEDs
`usb.py`	USB device enumeration
`modem.py`	Cellular modem AT commands

Adding a new board

Read the board identity

SSH into the board and read the strings detection matches against:

tr '\0' '\n' < /proc/device-tree/compatible
cat /proc/device-tree/model

Create the YAML file

Create src/ados/hal/boards/<your-board>.yaml. The file name becomes the board id. At minimum:

name: "Your Board Name"
vendor: "Manufacturer"
soc: "SoC Model"
arch: "aarch64"
model_patterns:
  - "string from the compatible node or model"
default_tier: 3
uart_paths:
  - /dev/ttyS0
hw_video_codecs:
  - h264_enc

Describe the hardware

Add the sections from the schema that apply: video, compute, cameras, radios, flight_controller, displays, GPIO and buttons.

Pick the default tier

Choose the tier from the board’s RAM and accelerator, using the RAM bands above as a guide. The tier only gates extensions that set compatibility.min_tier.

Test

Install the agent on the board and check what it detected:

ados hardware show --json

The board name and tier should match your YAML file. If detection picked another profile, check model_patterns, or write the file name to /etc/ados/board_override to confirm the profile loads.

Submit a pull request

Add the YAML file and open a pull request against altnautica/ADOSDroneAgent. Include the board model, where to buy it, and any quirks you found while testing.

The generic profiles work on any 64-bit ARM or x86_64 machine, so you can run the agent without a custom profile. A board profile improves detection and enables board-specific hardware such as the right UART path, cameras, displays and button pins.

Get started

Set up and use

Link, video and flight systems

Reference

Diagnose

Board detection

Default tier

Board profile schema

HAL modules

Adding a new board

Next steps

Supported hardware

Systemd services

​Board detection

​Default tier

​Board profile schema

​HAL modules

​Adding a new board

​Next steps

Supported hardware

Systemd services

Board detection

Default tier

Board profile schema

HAL modules

Adding a new board

Next steps