diff --git a/.github/workflows/docs-contract.yml b/.github/workflows/docs-contract.yml index a60e1e678..c2f2051b4 100644 --- a/.github/workflows/docs-contract.yml +++ b/.github/workflows/docs-contract.yml @@ -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: @@ -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 ──────────────────────────────────────────────────────────────── diff --git a/README.md b/README.md index 7e9aeb31b..d4393338d 100644 --- a/README.md +++ b/README.md @@ -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 ``` diff --git a/examples/README.md b/examples/README.md index 600aad77f..590aa591b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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++ diff --git a/examples/driver_integration/README.md b/examples/driver_integration/README.md index 1a6d90761..aed12c54b 100644 --- a/examples/driver_integration/README.md +++ b/examples/driver_integration/README.md @@ -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) @@ -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 @@ -27,9 +27,9 @@ 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" } ``` @@ -37,9 +37,9 @@ gripper = { node = "GripperDriver" } | 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 | diff --git a/examples/driver_integration/horus.toml b/examples/driver_integration/horus.toml index d9fe63617..c215b2658 100644 --- a/examples/driver_integration/horus.toml +++ b/examples/driver_integration/horus.toml @@ -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" } diff --git a/examples/driver_integration/main.rs b/examples/driver_integration/main.rs index c1139183c..8aa43c566 100644 --- a/examples/driver_integration/main.rs +++ b/examples/driver_integration/main.rs @@ -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 /// @@ -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(()) } @@ -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 { @@ -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, ""); @@ -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()); diff --git a/horus_core/src/drivers/mod.rs b/horus_core/src/drivers/mod.rs index 23f6463dd..505c8d624 100644 --- a/horus_core/src/drivers/mod.rs +++ b/horus_core/src/drivers/mod.rs @@ -283,7 +283,7 @@ pub fn load_from>(path: P) -> HorusResult 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) @@ -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). @@ -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 diff --git a/horus_manager/src/commands/pkg.rs b/horus_manager/src/commands/pkg.rs index 3e5882056..c41304a73 100644 --- a/horus_manager/src/commands/pkg.rs +++ b/horus_manager/src/commands/pkg.rs @@ -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() diff --git a/horus_manager/src/commands/run/features.rs b/horus_manager/src/commands/run/features.rs index 14a4b19ab..3f5562937 100644 --- a/horus_manager/src/commands/run/features.rs +++ b/horus_manager/src/commands/run/features.rs @@ -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()); diff --git a/horus_manager/src/manifest.rs b/horus_manager/src/manifest.rs index 697f0dfca..c7bc19f6f 100644 --- a/horus_manager/src/manifest.rs +++ b/horus_manager/src/manifest.rs @@ -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) /// @@ -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), @@ -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] @@ -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, /// Simulation flag — when true, replaced by sim stub when `horus run --sim`. #[serde(default, skip_serializing_if = "Option::is_none")] pub sim: Option, - /// Terra driver shortname (legacy — use `use` instead). + /// Legacy driver shortname — use `use` instead. #[serde(default, skip_serializing_if = "Option::is_none")] pub terra: Option, /// Registry package name (e.g., `"horus-driver-ati-netft"`). diff --git a/horus_manager/src/native_sync.rs b/horus_manager/src/native_sync.rs index d24d470c3..b46f88e33 100644 --- a/horus_manager/src/native_sync.rs +++ b/horus_manager/src/native_sync.rs @@ -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 { let mut crates = Vec::new(); for driver_val in manifest.hardware_entries().into_values() {