From a10d6cb8ecd3c6c80f26218f59d85121649b4b62 Mon Sep 17 00:00:00 2001 From: Merge Stack Date: Sun, 20 Sep 2026 00:50:07 -0700 Subject: [PATCH 1/3] docs: stop advertising Terra in the public tree Terra's repository is private and not ready to be public, so horus should not point users at it. Removed: - the link to github.com/softmata/terra and the "Terra HAL" name from the README, examples/README.md and the driver_integration docs and comments - the driver examples now use the unified `use = "..."` source key - the stale "Call register!() or terra_horus::register_all() first" hint (that function is not part of horus); the docs page that quotes the message is updated separately in horus-docs - Terra-named prose in horus_core/horus_manager comments Kept deliberately: the legacy `terra = "..."` manifest key still parses (DriverTableConfig::terra and horus_core's fallback chain) with its tests, because existing horus.toml files use it. Its schema/doc descriptions now read "legacy driver shortname" instead of naming Terra. --- README.md | 4 ++-- examples/README.md | 2 +- examples/driver_integration/README.md | 22 +++++++++++----------- examples/driver_integration/horus.toml | 8 ++++---- examples/driver_integration/main.rs | 12 ++++++------ horus_core/src/drivers/mod.rs | 2 +- horus_manager/src/cargo_gen.rs | 8 ++++---- horus_manager/src/commands/pkg.rs | 2 +- horus_manager/src/commands/run/features.rs | 2 +- horus_manager/src/manifest.rs | 18 +++++++++--------- horus_manager/src/native_sync.rs | 4 ++-- 11 files changed, 42 insertions(+), 42 deletions(-) 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..0f525d450 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() { From 65f7d44d869e3b30f6fd9baa0ebd9cac5d145a4b Mon Sep 17 00:00:00 2001 From: Merge Stack Date: Sun, 20 Sep 2026 01:10:19 -0700 Subject: [PATCH 2/3] ci(docs-contract): pin horus-docs at ad08246 (the no-Terra docs merge) The live tier compares `horus schema`'s output against the pinned docs tree, and this branch changes the manifest doc comments, so the pin has to move to the docs commit that republished the schema. ad08246 is the merge of horus-docs#19; verified from this tree: docs_contract 14, docs_cli_contract 7, docs_manifest 17 (--include-ignored). --- .github/workflows/docs-contract.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) 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 ──────────────────────────────────────────────────────────────── From 38d8f1ce9f5001f82e612c0c534943401600d7dd Mon Sep 17 00:00:00 2001 From: Merge Stack Date: Sun, 20 Sep 2026 03:03:57 -0700 Subject: [PATCH 3/3] fix(drivers): show register_driver!'s shape in the empty-registry hint The hint named the macro but wrote it as register_driver!(), which reads as a zero-argument call. The macro takes the driver type and its factory; say so. The docs page that quotes the message is updated separately (horus-docs#20). --- horus_core/src/drivers/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/horus_core/src/drivers/mod.rs b/horus_core/src/drivers/mod.rs index 0f525d450..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