HAL and Tiers

The Hardware Abstraction Layer (HAL) is how the agent adapts to different companion computers. It reads the board identity at boot, loads the matching YAML profile, and configures the agent’s features based on the board’s capabilities.

Board detection

The detection logic lives in ados.hal.detect and runs at agent startup:

Read /proc/device-tree/model (the Linux device tree model string)
Compare against model_patterns in each board YAML file
Pick the first profile whose pattern matches as a substring
If no match, fall back to generic-arm64.yaml

The detection also reads system information:

Total RAM from /proc/meminfo
CPU core count from os.cpu_count()
Architecture from platform.machine()

Board profile schema

Each profile is a YAML file at src/ados/hal/boards/<name>.yaml. Here is the full schema:

# Required fields
name: "Human readable board name"
vendor: "Board manufacturer"
soc: "SoC model"
arch: "aarch64"               # aarch64 | armv7l
model_patterns:                # Strings to match in /proc/device-tree/model
  - "Exact Match String"
  - "alternative-match"
default_tier: 3                # 1 | 2 | 3 | 4

# Bus definitions
gpio_pins:                     # Available GPIO pin numbers
  - 2
  - 3
  - 14
  - 15

uart_paths:                    # Serial ports for FC auto-detection
  - /dev/ttyAMA0
  - /dev/ttyS0

hw_video_codecs:               # Hardware-accelerated codecs
  - h264_enc
  - h264_dec
  - h265_enc
  - h265_dec
  - av1_dec

# Optional: detailed bus definitions
buses:
  uart:
    - id: uart0
      path: /dev/ttyS0
      baud: 921600
      fc_capable: true
  usb:
    - id: usb0
      path: "/dev/bus/usb/001/*"
      type: usb2
  i2c:
    - id: i2c0
      path: /dev/i2c-0
      speed_hz: 400000
  spi:
    - id: spi0
      path: /dev/spidev0.0
  pcie:
    - id: pcie0
      type: pcie3.0
      lanes: 1

# Optional: detailed board info
board:
  id: board-slug
  manufacturer: Company
  status: supported           # supported | experimental | community

# Optional: compute details
compute:
  cores: 4
  core_type: "Cortex-A76 x2 + Cortex-A55 x2"
  max_freq_mhz: 2400
  gpu: null                    # null if fused off or absent
  npu_tops: 6.0               # null if no NPU
  hw_encoder: ["h264", "h265"]
  hw_decoder: ["h264", "h265", "vp9", "av1"]
  ram_mb: 4096
  ram_type: LPDDR4X

# Optional: storage
storage:
  emmc: true
  sd_card: true
  nand: false

# Optional: network
network:
  wifi: true
  ethernet: true
  bluetooth: true

# Optional: video
video:
  csi_ports: 1
  csi_connector: "31-pin 0.3mm Radxa FPC"
  max_encode_resolution: "3840x2160"
  max_encode_fps: 60
  encoder_api: rkmpp

# Optional: power
power:
  typical_watts: 4.0
  max_watts: 8.5
  voltage: 5.0
  input: "USB-C 5V/3A"

# Optional: feature profiles
profiles:
  tier: pro
  max_features:
    - mavlink_proxy
    - mqtt_gateway
    - video_pipeline
    - rest_api
    - vision_engine
    - wfb_ng
    - cloud_relay
  video_capable: true
  recommended_resolution: "1920x1080"
  memory_budget_mb: 4096

# Optional: ground station buttons (for boards used in GS role)
gpio_buttons:
  - id: btn_b1
    pin: 5
    header_pin: 29
    function: "ground-station menu up"

Tier mapping

The tier system determines which features are active. The agent picks a tier based on three inputs (in priority order):

Explicit config (agent.tier in config.yaml) overrides everything
Board profile (default_tier in the YAML file) is the fallback
RAM-based fallback if running on generic-arm64 with no explicit tier

Tier feature matrix

Feature	Tier 1	Tier 2	Tier 3	Tier 4
MAVLink proxy	Yes	Yes	Yes	Yes
REST API	No	Yes	Yes	Yes
Health monitoring	No	Yes	Yes	Yes
mDNS discovery	No	Yes	Yes	Yes
Video pipeline	No	No	Yes	Yes
WFB-ng link	No	No	Yes	Yes
Cloud relay	No	No	Yes	Yes
Peripherals manager	No	No	Yes	Yes
Vision host and model registry	No	No	No	Yes

RAM guidelines

Tier	Minimum RAM	Typical boards
1	minimal	(no current board profile defaults here)
2	256-512 MB	Raspberry Pi 3/CM3, Radxa Cubie A7Z, generic ARM64
3	1-2 GB	Raspberry Pi 4B/CM4, Jetson Nano, Radxa CM3, RV1126B
4	4 GB+	ROCK 5C Lite, RPi 5/CM5, Jetson Orin Nano, Orange Pi 5, Radxa CM4

HAL modules

Beyond board detection, the HAL provides several hardware abstraction modules:

Module	Purpose
`detect.py`	Board identification and profile loading
`camera.py`	Camera detection (CSI, USB V4L2)
`gpio.py`	GPIO pin access for buttons, LEDs
`usb.py`	USB device enumeration and hot-plug
`hotplug.py`	Device hot-plug event handling
`modem.py`	Cellular modem AT commands

Adding a new board

To add support for a board that is not in the built-in list:

Identify the model string

SSH into the board and read the device tree model:

cat /proc/device-tree/model

This is the string you will match against.

Create the YAML file

Create src/ados/hal/boards/your-board.yaml with at minimum:

name: "Your Board Name"
vendor: "Manufacturer"
soc: "SoC Model"
arch: "aarch64"
model_patterns:
  - "Exact string from /proc/device-tree/model"
default_tier: 3
uart_paths:
  - /dev/ttyS0
hw_video_codecs:
  - h264_enc

Add bus definitions

List the UART ports the FC might connect to, USB ports, I2C buses, and any other relevant hardware.

Set the right tier

Based on the board’s RAM and capabilities, pick an appropriate default tier. When in doubt, start lower and test.

Test

Install the agent on the board and verify detection:

ados status --json

The board name, tier, and features should match your YAML file.

Submit a PR

Add the YAML file and submit a pull request to altnautica/ADOSDroneAgent. Include the board model, where to buy it, and any quirks you discovered during testing.

The generic-arm64 fallback profile works on any 64-bit ARM board. You can use the agent without a custom profile. Adding a board profile just improves auto-detection accuracy and enables board-specific features (like the right UART path or GPIO buttons).

​HAL and Tiers

​Board detection

​Board profile schema

​Tier mapping

​Tier feature matrix

​RAM guidelines

​HAL modules

​Adding a new board

HAL and Tiers

Board detection

Board profile schema

Tier mapping

Tier feature matrix

RAM guidelines

HAL modules

Adding a new board