Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .github/workflows/docs-contract.yml
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,16 @@ env:
# Verifying a different docs commit means bumping this SHA in a PR, so the
# change is reviewed here before it runs here.
#
# Bumped from 9a1a0c1 to ad08246 (horus-docs main, the merge of
# horus-docs#19). That PR drops the private Terra project's name from the
# docs, describes the legacy `terra` key as a driver shortname rather than by
# product name, and regenerates public/schema/horus.toml.schema.json. The
# schema is why the pin must move with this branch: its doc comments feed
# `horus schema`, and the live tier compares that output against the pinned
# tree, so the two sides have to be the same commit's worth of text.
# Verified from this tree: docs_contract 14, docs_cli_contract 7, and
# docs_manifest 17 with --include-ignored.
#
# Bumped from 4a612b1 to 9a1a0c1 (horus-docs main, the merge of
# horus-docs#17). That PR is the documentation half of the same bidirectional
# audit this branch is the code half of, so the two belong at the same pin:
Expand All @@ -115,7 +125,7 @@ env:
# it: 14 passed, 0 failed. The bump is 7 commits, not 1 — horus-docs#18 is
# only the newest of them, and that suite result is what says the other six,
# written by other people for other reasons, are compatible with this branch.
DOCS_PINNED_REF: 9a1a0c107bc2e04b75cbdd08a04462e242285bce
DOCS_PINNED_REF: ad08246e4a5eeb7606ff71607fbef30a54caf405

jobs:
# ── Tier 1 ────────────────────────────────────────────────────────────────
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -342,11 +342,11 @@ action! { Navigate { goal { x: f64, y: f64 } feedback { dist: f64 } result { ok

### Hardware Drivers

Declare hardware in `horus.toml`, access typed handles in code. 30+ [Terra HAL](https://github.com/softmata/terra) drivers — Dynamixel, RPLiDAR, RealSense, CAN, EtherCAT, and more.
Declare hardware in `horus.toml`, access typed handles in code. 30+ drivers — Dynamixel, RPLiDAR, RealSense, CAN, EtherCAT, and more.

```toml
[drivers.arm]
terra = "dynamixel"
use = "dynamixel"
port = "/dev/ttyUSB0"
baudrate = 1000000
```
Expand Down
2 changes: 1 addition & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ build output behind. Pass a name that does not exist to see the full list.
### Production
| Example | Language | What you'll learn |
|-------------------------------------------|----------|--------------------------------------------------------------------|
| [driver_integration](driver_integration/) | Rust | Hardware drivers via `[drivers]` config, Terra HAL, custom drivers |
| [driver_integration](driver_integration/) | Rust | Hardware drivers via `[drivers]` config, custom driver nodes |
| [record_replay](record_replay/) | Rust | Session recording, blackbox forensics, deterministic replay |

## C++
Expand Down
22 changes: 11 additions & 11 deletions examples/driver_integration/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Driver Integration — Hardware Abstraction & Terra HAL
# Driver Integration — Hardware Abstraction

Demonstrates how to integrate real hardware into horus using the `[drivers]` configuration in `horus.toml` and the Terra Hardware Abstraction Layer.
Demonstrates how to integrate real hardware into horus using the `[drivers]` configuration in `horus.toml` and a hardware abstraction layer.

## Architecture

```
horus.toml [drivers]
├── motor = { terra = "dynamixel" } → SimMotorDriver (200Hz)
├── imu = { terra = "bno055" } → SimImuDriver (200Hz)
├── lidar = { terra = "rplidar" } → (not used in this example)
├── motor = { use = "dynamixel" } → SimMotorDriver (200Hz)
├── imu = { use = "bno055" } → SimImuDriver (200Hz)
├── lidar = { use = "rplidar" } → (not used in this example)
└── gripper = { node = "GripperDriver" } → SimGripperDriver (50Hz)
│
ArmController (50Hz)
Expand All @@ -18,7 +18,7 @@ horus.toml [drivers]
## What This Demonstrates

- **`[drivers]` in horus.toml**: Declarative hardware configuration
- **Terra drivers**: `dynamixel`, `bno055`, `rplidar` — standard robotics peripherals
- **Built-in drivers**: `dynamixel`, `bno055`, `rplidar` — standard robotics peripherals
- **Custom drivers**: `{ node = "GripperDriver" }` for non-standard hardware
- **Driver lifecycle**: `init()` connects hardware, `tick()` reads/writes, `shutdown()` disables
- **Simulated drivers**: Same API as real hardware, runs without physical devices
Expand All @@ -27,19 +27,19 @@ horus.toml [drivers]

```toml
[drivers]
motor = { terra = "dynamixel", port = "/dev/ttyUSB0", baudrate = "1000000" }
imu = { terra = "bno055", bus = "/dev/i2c-1", address = "0x28" }
lidar = { terra = "rplidar", port = "/dev/ttyUSB1", baudrate = "256000" }
motor = { use = "dynamixel", port = "/dev/ttyUSB0", baudrate = "1000000" }
imu = { use = "bno055", bus = "/dev/i2c-1", address = "0x28" }
lidar = { use = "rplidar", port = "/dev/ttyUSB1", baudrate = "256000" }
gripper = { node = "GripperDriver" }
```

## ROS2 Equivalent

| ROS2 | Horus |
|----------------------------------------|------------------------------------------------|
| `ros2_control` hardware_interface | `[drivers]` in horus.toml + Terra HAL |
| `ros2_control` hardware_interface | `[drivers]` in horus.toml + built-in drivers |
| `controller_manager` | `Scheduler` with driver nodes at high priority |
| `micro-ros-agent` | Terra serial/I2C/CAN drivers |
| `micro-ros-agent` | Built-in serial/I2C/CAN drivers |
| Custom `LifecycleNode` hardware driver | Node with `init()`/`tick()`/`shutdown()` |
| `robot_state_publisher` | Driver node publishes to topic directly |

Expand Down
8 changes: 4 additions & 4 deletions examples/driver_integration/horus.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ license = "Apache-2.0"
horus = "*"

[drivers]
# Motor controller via serial (Terra driver)
motor = { terra = "dynamixel", port = "/dev/ttyUSB0", baudrate = "1000000" }
# Motor controller via serial (built-in driver)
motor = { use = "dynamixel", port = "/dev/ttyUSB0", baudrate = "1000000" }

# IMU sensor via I2C
imu = { terra = "bno055", bus = "/dev/i2c-1", address = "0x28" }
imu = { use = "bno055", bus = "/dev/i2c-1", address = "0x28" }

# LiDAR via network
lidar = { terra = "rplidar", port = "/dev/ttyUSB1", baudrate = "256000" }
lidar = { use = "rplidar", port = "/dev/ttyUSB1", baudrate = "256000" }

# Custom Python driver (local implementation)
gripper = { node = "GripperDriver" }
12 changes: 6 additions & 6 deletions examples/driver_integration/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
///
/// Demonstrates how to wire real hardware into horus:
/// - Load drivers from horus.toml [drivers] configuration
/// - Use Terra HAL for standard peripherals (motors, IMU, LiDAR)
/// - Use built-in drivers for standard peripherals (motors, IMU, LiDAR)
/// - Create custom driver nodes for specialized hardware
/// - Bridge hardware data into the horus topic system
///
Expand Down Expand Up @@ -77,7 +77,7 @@ impl Node for SimMotorDriver {
// dxl.set_torque_enable(true)?;
hlog!(info, "Motor driver: initialized (simulated)");
hlog!(info, " Real driver would load from horus.toml [drivers.motor]");
hlog!(info, " terra = \"dynamixel\", port = \"/dev/ttyUSB0\"");
hlog!(info, " use = \"dynamixel\", port = \"/dev/ttyUSB0\"");
Ok(())
}

Expand Down Expand Up @@ -173,7 +173,7 @@ impl Node for SimImuDriver {
}

// ============================================================================
// Simulated Gripper Driver — custom hardware, not a Terra driver
// Simulated Gripper Driver — custom hardware, not a built-in driver
// ============================================================================

struct SimGripperDriver {
Expand Down Expand Up @@ -289,7 +289,7 @@ impl Node for ArmController {

fn main() -> Result<()> {
hlog!(info, "Driver Integration Example");
hlog!(info, " Demonstrates: hardware drivers, Terra HAL, custom drivers");
hlog!(info, " Demonstrates: hardware drivers, custom drivers");
hlog!(info, " Drivers configured in horus.toml [drivers] section");
hlog!(info, " All drivers SIMULATED — same patterns work with real hardware");
hlog!(info, "");
Expand All @@ -303,8 +303,8 @@ fn main() -> Result<()> {
//
// The drivers are configured in horus.toml:
// [drivers]
// motor = { terra = "dynamixel", port = "/dev/ttyUSB0" }
// imu = { terra = "bno055", bus = "/dev/i2c-1" }
// motor = { use = "dynamixel", port = "/dev/ttyUSB0" }
// imu = { use = "bno055", bus = "/dev/i2c-1" }

let mut scheduler = Scheduler::new().tick_rate(200_u64.hz());

Expand Down
2 changes: 1 addition & 1 deletion horus_core/src/drivers/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,7 @@ pub fn load_from<P: AsRef<Path>>(path: P) -> HorusResult<Vec<(String, Box<dyn No
// Check if it's a known name that hasn't been registered
let registered = registry::list_registered();
let suggestion = if registered.is_empty() {
"No node types are registered. Call register!() or terra_horus::register_all() first.".to_string()
"No node types are registered. Register your driver with register_driver!(Type, factory), or depend on a crate that registers its types.".to_string()
} else {
format!("Registered types: {}", registered.join(", "))
};
Expand Down
8 changes: 4 additions & 4 deletions horus_manager/src/cargo_gen.rs
Original file line number Diff line number Diff line change
Expand Up @@ -865,7 +865,7 @@ fn writable_by_horus(config_path: &Path) -> bool {
/// Write driver dependencies from `[drivers]` config tables.
///
/// For each `[drivers.NAME]` entry:
/// - `terra = "dynamixel"` → adds `terra-serial = { version = "0.2", features = ["dynamixel"] }`
/// - `use = "dynamixel"` → no dependency (the driver is resolved at runtime)
/// - `package = "horus-driver-x"` → adds `horus-driver-x = "*"`
/// - `node = "MyDriver"` → no dependency (local code)
/// - `camera = "opencv"` / `gps = true` → no dependency (legacy, handled by feature flags)
Expand All @@ -875,7 +875,7 @@ fn write_driver_deps(
) {
use crate::manifest::DriverValue;

// Track crates already added to avoid duplicates (e.g., two drivers using terra-serial).
// Track crates already added to avoid duplicates (e.g., two drivers naming the same crate).
// Value = (explicit version if the driver pinned one, features). A BTreeMap keeps the
// generated dependency lines in deterministic order (the old HashMap produced
// run-to-run line reshuffling → spurious diffs / non-reproducible Cargo.toml).
Expand All @@ -884,8 +884,8 @@ fn write_driver_deps(
for value in drivers.values() {
match *value {
DriverValue::Config(cfg) => {
// Terra drivers: no longer auto-resolved — user adds terra-horus
// as a normal dependency in [dependencies]. Skip terra entries.
// Shortname drivers are no longer auto-resolved to crates — the
// driver is resolved at runtime from the node registry. Skip them.
if let Some(package) = &cfg.package {
// Registry package — version resolved at install time, emit as "*".
added_crates
Expand Down
2 changes: 1 addition & 1 deletion horus_manager/src/commands/pkg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2378,7 +2378,7 @@ pub fn run_add(
}
}
other => {
// Try as terra driver name
// Try as a legacy driver shortname
DriverValue::Config(DriverTableConfig {
terra: Some(other.to_string()),
..DriverTableConfig::default()
Expand Down
2 changes: 1 addition & 1 deletion horus_manager/src/commands/run/features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ impl DriverConfig {
for (name, value) in &manifest.drivers {
match value {
DriverValue::Config(cfg) => {
// Config table — extract driver name from terra/package/node key
// Config table — extract the driver name from the source keys
config.drivers.push(name.clone());
if let Some(terra) = &cfg.terra {
config.backends.insert(name.clone(), terra.clone());
Expand Down
18 changes: 9 additions & 9 deletions horus_manager/src/manifest.rs
Original file line number Diff line number Diff line change
Expand Up @@ -850,7 +850,7 @@ impl DependencyValue {
/// Driver configuration value.
///
/// Three forms:
/// - Config table: `[drivers.arm]` with `terra`/`package`/`node` key + params
/// - Config table: `[drivers.arm]` with a source key (`use`/`package`/`node`) + params
/// - Simple string: `camera = "opencv"` (backend name → feature flags)
/// - Enable bool: `camera = true` (enable with default backend)
///
Expand All @@ -861,7 +861,7 @@ impl DependencyValue {
#[serde(untagged)]
#[allow(clippy::large_enum_variant)]
pub enum DriverValue {
/// Config table: `[drivers.arm]` with terra/package/node key + params.
/// Config table: `[drivers.arm]` with a source key + params.
Config(DriverTableConfig),
/// Backend name string, e.g., `"opencv"`.
Backend(String),
Expand All @@ -871,16 +871,16 @@ pub enum DriverValue {

/// Structured driver configuration from a `[drivers.NAME]` TOML table.
///
/// Exactly one of `terra`, `package`, or `node` should be present to identify
/// the driver source. All other keys are captured in `params` and passed to
/// the driver factory at runtime.
/// Use exactly one source key — `use` (the unified key), `package`, or `node`.
/// The legacy shortname key is read as a fallback for `use`. All other keys are
/// captured in `params` and passed to the driver factory at runtime.
///
/// # Examples
///
/// ```toml
/// # Terra driver (pre-built hardware support)
/// # Built-in driver (pre-installed hardware support)
/// [drivers.arm]
/// terra = "dynamixel"
/// use = "dynamixel"
/// port = "/dev/ttyUSB0"
/// baudrate = 1000000
/// servo_ids = [1, 2, 3, 4, 5, 6]
Expand All @@ -900,13 +900,13 @@ pub enum DriverValue {
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DriverTableConfig {
/// Node type name — the new unified source key (e.g., `"dynamixel"`, `"rplidar"`).
/// Replaces the 6 legacy keys (terra, package, node, crate, pip, exec).
/// Replaces the legacy source keys.
#[serde(default, skip_serializing_if = "Option::is_none", rename = "use")]
pub use_name: Option<String>,
/// Simulation flag — when true, replaced by sim stub when `horus run --sim`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub sim: Option<bool>,
/// Terra driver shortname (legacy — use `use` instead).
/// Legacy driver shortname — use `use` instead.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub terra: Option<String>,
/// Registry package name (e.g., `"horus-driver-ati-netft"`).
Expand Down
4 changes: 2 additions & 2 deletions horus_manager/src/native_sync.rs
Original file line number Diff line number Diff line change
Expand Up @@ -308,8 +308,8 @@ fn deps_equal(a: &DependencyValue, b: &DependencyValue) -> bool {

/// Collect crate names that are auto-generated from the `[hardware]`/`[drivers]` section.
///
/// Terra drivers no longer auto-resolve to crates — users add terra-horus as a
/// normal dependency. Only package drivers generate Cargo deps.
/// Shortname drivers no longer auto-resolve to crates. Only package drivers
/// generate Cargo deps.
fn collect_driver_crates(manifest: &HorusManifest) -> Vec<String> {
let mut crates = Vec::new();
for driver_val in manifest.hardware_entries().into_values() {
Expand Down
Loading