Technical report
One door to the physical world: the voxyn hardware abstraction layer
Driver registration from configuration, a single async execute entry for structured intents, and coordinated emergency stop across every loaded backend.
Abstract
Higher layers—skills, NLU, API—should not import board-specific SDKs. voxyn’s Hardware Abstraction Layer (HAL) loads drivers declared under hardware.drivers in configuration, instantiates them via DriverRegistry.create, and exposes one async execute(intent) method that dispatches on action: move, servo, motor, sequence, parallel, wait, stop, and others. emergency_stop awaits stop_all() on every registered driver concurrently. Mock drivers provide safe default when nothing is configured or when a driver fails to connect. This note summarizes that design as implemented in voxyn/hardware/hal.py; it does not enumerate every driver type or electrical interface.
Keywords: robotics middleware, driver model, PCA9685, GPIO, mock hardware, asyncio
1. Rationale
The module docstring states the contract explicitly: nothing outside the HAL should talk to drivers directly. That keeps NLU prompts and REST handlers free of vendor types and makes unit tests swap in mocks without changing call sites.
2. Configuration and lifecycle
On start, the HAL walks the driver list from config. Empty configuration logs a warning and loads mock fallback so development can proceed. Each driver is connected; failures can fall back to a mock per entry when not in global mock mode.
3. Intent dispatch
execute switches on action and delegates to private helpers—e.g. _action_move resolves a motor driver, maps direction to left/right channel speeds, optionally sleeps for duration then stops. Sequences recurse; parallel uses asyncio.gather. The same dictionary shape is used whether the intent originated from NLU or from skill YAML.
stop_all.4. Observability
status aggregates per-driver telemetry; list_drivers and get_driver support diagnostics and the HTTP API’s motor views where wired.
References
[1] voxyn voxyn/hardware/hal.py, voxyn/hardware/registry.py, voxyn/hardware/base.py.