HORUS

https://docs.horusrobotics.dev
Admin
HORUS is an ultra-low-latency, memory-safe robotics middleware and runtime framework for building...
Tokens:729,766
Snippets:5,214
Trust Score:2.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### horus install examples

Source: https://docs.horusrobotics.dev/package-management/package-management

Examples of installing packages from the HORUS registry and from crates.io (auto-detected). Shows version pinning with @version and default latest.

```bash
# From HORUS registry
horus install pid-controller
horus install motion-planner@2.0.1

# From crates.io (auto-detected)
horus install serde
horus install tokio@1.35.0
horus install clap
```

--------------------------------

### Install hardware drivers with horus install

Source: https://docs.horusrobotics.dev/development/cli-reference

Example commands for installing hardware drivers by package name.

```bash
horus install realsense-driver
horus install rplidar-driver

```

--------------------------------

### Quick start: apply RtConfig and create Topic

Source: https://docs.horusrobotics.dev/advanced/rt-config

Quick start example that builds an RtConfig with the same settings as the previous snippet and applies it with the ? operator. After applying, it creates a Topic for the cmd_vel channel, assuming RT guarantees are active.

```rust
use horus::prelude::*;

// Apply hard real-time configuration
let config = RtConfig::builder()
    .memory_locked(true)
    .scheduler(RtScheduler::Fifo)
    .priority(80)
    .cpu_affinity(&[2, 3])  // Pin to cores 2, 3
    .build();
config.apply()?;

// Now all HORUS operations run with RT guarantees
let link: Topic<CmdVel> = Topic::new("cmd_vel")?;  // see Performance Impact below

```

--------------------------------

### Install components for autonomous robot

Source: https://docs.horusrobotics.dev/package-management/using-prebuilt-nodes

Installs the required packages for the autonomous robot example. Run these commands to set up the necessary drivers and components.

```bash
horus install lidar-driver
horus install obstacle-detector
horus install path-planner
horus install differential-drive
horus install emergency-stop
```

--------------------------------

### Full scheduler example

Source: https://docs.horusrobotics.dev/cpp/api/duration

Complete scheduler setup with three nodes at different rates and miss policies. Shows how to configure rate, budget, deadline, miss policy, core pinning, priority, order, and tick callback.

```cpp
#include <horus/horus.hpp>
using namespace horus::literals;

int main() {
    horus::Scheduler sched;
    sched.tick_rate(1000_hz);

    // Hard RT: motor control at 1 kHz, enters safe state on overrun
    sched.add("motor_ctrl")
        .rate(1000_hz)
        .budget(800_us)
        .deadline(950_us)
        .on_miss(horus::Miss::SafeMode)
        .pin_core(2)
        .priority(90)
        .order(0)
        .tick([&] { /* PID loop */ })
        .build();

    // Soft RT: state estimation at 200 Hz, skips on overrun
    sched.add("estimator")
        .rate(200_hz)
        .budget(4_ms)
        .deadline(4500_us)
        .on_miss(horus::Miss::Skip)
        .order(10)
        .tick([&] { /* EKF update */ })
        .build();

    // Best effort: logging at 10 Hz, warns on overrun
    sched.add("logger")
        .rate(10_hz)
        .budget(50_ms)
        .on_miss(horus::Miss::Warn)
        .order(100)
        .tick([&] { /* write logs */ })
        .build();

    sched.spin();
}

```

--------------------------------

### Run application and start monitor

Source: https://docs.horusrobotics.dev/troubleshooting

Run the application in one terminal and start the monitor in another. If the monitor reports "The monitor plugin is not installed", install it with `horus install horus-monitor`.

```bash
horus run
```

```bash
horus monitor
```

--------------------------------

### Install common packages with horus install

Source: https://docs.horusrobotics.dev/development/cli-reference

Example commands for installing common packages, including version pinning with `@`.

```bash
horus install kalman-filter
horus install pid-controller@2.0.0

```

--------------------------------

### Install simulator and run with --sim

Source: https://docs.horusrobotics.dev/getting-started/installation

Installs the simulator plugin and runs with `--sim` to swap hardware entries marked `sim = true` for stub nodes. `--sim` auto-launches the simulator plugin (sim3d by default, or `[robot].simulator`); if the plugin is not installed, `horus run --sim` refuses to start.

```bash
horus install horus-sim3d   # one-time: the simulator plugin `--sim` launches
horus run --sim             # swaps every [hardware] entry marked `sim = true`
                            # for a stub node
```

--------------------------------

### Install Horus with curl and check help

Source: https://docs.horusrobotics.dev/getting-started/installation

Downloads and runs the official install script, then verifies installation by displaying the help command. If help output appears, installation is complete.

```bash
curl -fsSL https://github.com/softmata/horus/raw/main/install.sh | bash
horus --help

```

--------------------------------

### horus new Rust with macro example

Source: https://docs.horusrobotics.dev/development/cli-reference

Example of starting a new Rust project with the `node!` macro, changing into the project directory, and running it with `horus run`.

```bash
horus new temperature_monitor --macro
cd temperature_monitor
horus run
```

--------------------------------

### Start sim3d visual simulator

Source: https://docs.horusrobotics.dev/examples

Start the sim3d simulator in visual mode with a robot and world file. Optional for examples that publish and subscribe without it.

```bash
sim3d --mode visual --robot robots/<robot>.urdf --world worlds/<world>.yaml

```

--------------------------------

### Full robot setup with transforms, params, and scheduler

Source: https://docs.horusrobotics.dev/tutorials/03-full-robot-python

Sets up coordinate frames, runtime parameters, and a scheduler with nodes in execution order. The scheduler runs at 200 Hz and nodes are added with implicit order values. The example prints the node count and names before running.

```python
# ── Main ────────────────────────────────────────────────────────────────
# Coordinate transforms: lidar sits 20 cm forward and 30 cm up on the base.
tf = horus.TransformFrame()
tf.register_frame("world")
tf.register_frame("base_link", parent="world")
tf.register_frame("lidar", parent="base_link")
tf.update_transform("lidar", horus.Transform(translation=[0.2, 0.0, 0.3]))

# Runtime parameters, tunable while the robot runs.
params = horus.Params()
params["max_speed"] = 0.3
params["safe_distance"] = 0.5

sched = horus.Scheduler(tick_rate=200, name="full_robot")

# Add nodes in execution order.
sched.add(ImuDriver())              # 200 Hz, order 0
sched.add(LidarDriver())            # 10 Hz,  order 1
sched.add(SafetyMonitor())          # 50 Hz,  order 2  — critical
sched.add(Controller(params))       # 100 Hz, order 10
sched.add(MotorDriver())            # 100 Hz, order 20
sched.add(Telemetry())              # 1 Hz,   order 100

print(f"Robot ready: {sched.get_node_count()} nodes")
for n in sched.get_node_names():
    print(f"  - {n}")

sched.run()
```

--------------------------------

### Usage example: node definition and scheduler setup

Source: https://docs.horusrobotics.dev/rust/api/macros

Shows how to define a node, register it with `Scheduler`, set tick rate via `.rate()`, and run. A `rate` section inside `node!` is a compile error; rate is set on the builder.

```rust
use horus::prelude::*;

node! {
    MyNode {
        pub { output: f32 -> "data" }
        tick {
            self.output.send(42.0);
        }
    }
}

fn main() -> Result<()> {
    let mut scheduler = Scheduler::new();
    scheduler.add(MyNode::new()).order(0).rate(100_u64.hz()).done();
    scheduler.run()
}
```

--------------------------------

### README template for HORUS package

Source: https://docs.horusrobotics.dev/package-management/package-management

A complete README template for a HORUS package, including features, installation, usage, examples, and license. Use it as a starting point when documenting your own packages.

```markdown
# PID Controller

Production-ready PID controller for HORUS robotics framework.

## Features
- Anti-windup protection
- Derivative filtering
- Output clamping

## Installation
```bash
horus install pid-controller
```

## Usage
```rust
use pid_controller::PIDController;

let mut pid = PIDController::new(1.0, 0.1, 0.01);
let output = pid.update(error);
```

## Examples
See `examples/` directory for complete examples.

## License
MIT
```

--------------------------------

### Create a new project from an example

Source: https://docs.horusrobotics.dev/examples

Use `horus new my_robot --from differential_drive` to copy an example and rename the package, then run it.

```bash
horus new my_robot --from differential_drive
cd my_robot
horus run main.rs

```

--------------------------------

### First time setup: horus auth login

Source: https://docs.horusrobotics.dev/development/cli-reference

Logs in with GitHub via browser. Use this for first-time setup.

```bash
horus auth login
# Opens browser for GitHub login

```

--------------------------------

### Manually copy an example directory

Source: https://docs.horusrobotics.dev/examples

Copy the example directory by hand, edit the manifest name, and run. Note that the manifest is the only file holding the package name.

```bash
cp -r horus/examples/differential_drive my_robot
cd my_robot
# edit horus.toml: change `name = "differential_drive"` to `name = "my_robot"`
horus run main.rs

```

--------------------------------

### Frequency::deadline_default() usage example

Source: https://docs.horusrobotics.dev/cpp/api/duration

Example of using deadline_default() to get the default deadline.

```cpp
auto rate = 100_hz;
auto deadline = rate.deadline_default();  // 9,500 us = 9.5 ms (95% of 10 ms)

```

--------------------------------

### Frequency::period() usage example

Source: https://docs.horusrobotics.dev/cpp/api/duration

Example of using period() to get the period in microseconds.

```cpp
auto rate = 100_hz;
auto p = rate.period();    // 10,000 us = 10 ms

```

--------------------------------

### Install and use a CLI plugin

Source: https://docs.horusrobotics.dev/plugins

Shows the basic workflow for installing a plugin, using it as a native command, and listing installed plugins. The commands are `horus install --plugin horus-sim3d`, `horus sim3d --robot kuka_iiwa`, and `horus list`.

```bash
# Install a plugin
horus install --plugin horus-sim3d

# Use it as a native command
horus sim3d --robot kuka_iiwa

# List installed plugins
horus list

```

--------------------------------

### First-time HORUS project setup

Source: https://docs.horusrobotics.dev/development/cli-reference

First-time workflow: create a new project with the --macro flag, run it in release mode, and monitor it in a separate terminal. The --macro flag is required for macro support.

```bash
# Create a project
horus new my_first_app --macro
cd my_first_app

# Run it
horus run --release

# Monitor it (new terminal)
horus monitor
```

--------------------------------

### Frequency::value() usage example

Source: https://docs.horusrobotics.dev/cpp/api/duration

Example of using value() to get the frequency in Hz.

```cpp
auto rate = 100_hz;
double hz = rate.value();  // 100.0

```

--------------------------------

### Frequency::budget_default() usage example

Source: https://docs.horusrobotics.dev/cpp/api/duration

Example of using budget_default() to get the default compute budget.

```cpp
auto rate = 100_hz;
auto budget = rate.budget_default();  // 8,000 us = 8 ms (80% of 10 ms)

```

--------------------------------

### Search and install a plugin

Source: https://docs.horusrobotics.dev/development/cli-reference

Searches for a plugin and installs it from the registry.

```bash
horus search visualizer
horus install horus-visualizer
```

--------------------------------

### Generic topic import (Python)

Source: https://docs.horusrobotics.dev/concepts/multi-language

Starts the generic topic example by importing the Topic class. The full example is not shown on the page.

```python
from horus import Topic

```

--------------------------------

### Install HORUS and create a project

Source: https://docs.horusrobotics.dev/getting-started/installation

Installs HORUS and creates a new project. A new project declares no [hardware], so a bare `horus run` does not touch any device.

```bash
# 1. Install HORUS normally (no hardware packages needed)
curl -fsSL https://github.com/softmata/horus/raw/main/install.sh | bash

# 2. Create and run your project
horus new my_robot
cd my_robot
horus run   # Builds and runs your nodes. A new project declares no
            # [hardware], so nothing here touches a device.
```

--------------------------------

### Get package info with horus info

Source: https://docs.horusrobotics.dev/development/cli-reference

Get details about one package: version, description, owner and dependency information, whether or not it is installed.

```bash
horus info rplidar
horus info rplidar --json

```

--------------------------------

### Create the full_robot project with horus new

Source: https://docs.horusrobotics.dev/tutorials/03-full-robot-rust

Initializes a new Horus project and moves into its directory.

```bash
horus new full_robot
cd full_robot
```

--------------------------------

### Complete horus publish example

Source: https://docs.horusrobotics.dev/package-management/package-management

Complete example of publishing a package with `horus publish`, including the interactive prompts for documentation and source repository, and the final output.

```text
$ cd my-sensor-package
$ horus publish

 Detected horus.toml manifest
 Publishing my-sensor-package v1.0.0...

Package Metadata (optional)
   Help users discover and use your package by adding:

Documentation
    Found local /docs folder with markdown files
   Add documentation? (y/n): y

   Documentation options:
     1. External URL - Link to online documentation
     2. Local /docs - Bundle markdown files in a /docs folder

   [i] Your /docs folder should contain .md files organized as:
      /docs/README.md          (main documentation)
      /docs/getting-started.md (guides)
      /docs/api.md             (API reference)

   Choose option (1/2/skip): 2
    Will bundle local /docs folder with package

Source Repository
    Auto-detected: https://github.com/robotics-lab/my-sensor-package
   Add source repository? (y/n): y
   Use detected URL? (y/n): y
    Source repository: https://github.com/robotics-lab/my-sensor-package

 Uploaded to registry

Published: my-sensor-package@1.0.0
   View at: https://registry.example.com/packages/my-sensor-package

```

--------------------------------

### Use installed package in Rust code

Source: https://docs.horusrobotics.dev/concepts/goals

Shows how to use an installed HORUS package in Rust code. The example adds a CartographerNode to the scheduler with order 2.

```rust
use slam_cartographer::CartographerNode;

scheduler.add(CartographerNode::new()?).order(2).done();

```

--------------------------------

### horus init existing code example

Source: https://docs.horusrobotics.dev/development/cli-reference

Example of initializing existing code as a HORUS project. After changing to the project directory, `horus init` creates `horus.toml` with the project configuration.

```bash
cd ~/my-robot-code
horus init
# Creates horus.toml with project configuration
```

--------------------------------

### Complete example: Nodes, scheduler, and statistics in Python

Source: https://docs.horusrobotics.dev/python/api/python-bindings

Sets up three nodes for sensor reading, control, and logging at different rates with order ranking. Schedules them on a node for a 5-second run. It creates a node and checks its total ticks.

```python
import horus

def sensor_tick(node):
    """High-frequency sensor (100Hz)"""
    # The publisher stamps the message — nothing stamps it for you
    imu = {"accel_x": 1.0, "accel_y": 0.0, "accel_z": 9.8,
           "timestamp_ns": horus.timestamp_ns()}
    node.send("imu_data", imu)
    node.log_info("Published IMU")

def control_tick(node):
    """Medium-frequency control (50Hz)"""
    if node.has_msg("imu_data"):
        imu = node.recv("imu_data")

        # Check for stale data
        age = (horus.timestamp_ns() - imu["timestamp_ns"]) / 1e9
        if age > 0.05:
            node.log_warning("Stale IMU data!")
            return

        cmd = {"linear": 1.0, "angular": 0.0, "timestamp_ns": horus.timestamp_ns()}
        node.send("cmd_vel", cmd)

def logger_tick(node):
    """Low-frequency logging (10Hz)"""
    if node.has_msg("cmd_vel"):
        msg = node.recv("cmd_vel")
        latency = (horus.timestamp_ns() - msg["timestamp_ns"]) / 1e6
        node.log_info(f"Command latency: {latency:.1f}ms")

# Create nodes — rate and execution order live on the constructor
sensor = horus.Node(name="imu", pubs="imu_data", tick=sensor_tick, order=0, rate=100)
controller = horus.Node(name="ctrl", subs="imu_data", pubs="cmd_vel", tick=control_tick, order=1, rate=50)
logger = horus.Node(name="log", subs="cmd_vel", tick=logger_tick, order=2, rate=10)

# add() takes the node and nothing else, and returns the scheduler so calls chain
scheduler = horus.Scheduler()
scheduler.add(sensor).add(controller).add(logger)

scheduler.run(duration=5.0)

# Check statistics
stats = scheduler.get_node_stats("imu")
print(f"Sensor: {stats['total_ticks']} ticks in 5 seconds")

```

--------------------------------

### init() Setup: Hardware, Buffers, State

Source: https://docs.horusrobotics.dev/concepts/core-concepts-nodes

Shows what to include in the init() method, which runs once when the node starts. Use it to set up hardware connections, pre-allocate buffers, initialize hardware state, and set initial values before tick() begins. The example opens a serial port, allocates a command buffer, sends an init sequence, and sets initial state.

```rust
fn init(&mut self) -> Result<()> {
    hlog!(info, "Initializing MyMotorNode");

    // 1. Open hardware connections
    self.serial_port = serialport::new("/dev/ttyUSB0", 115200)
        .open()
        .map_err(|e| Error::node("MyMotorNode", format!("Failed to open serial: {}", e)))?;

    // 2. Pre-allocate buffers (avoid allocation in tick)
    self.command_buffer = vec![0u8; 256];

    // 3. Initialize hardware state
    self.send_init_sequence()?;

    // 4. Set initial values
    self.velocity = 0.0;
    self.is_armed = false;

    hlog!(info, "MyMotorNode initialized successfully");
    Ok(())
}

```

--------------------------------

### horus install target examples

Source: https://docs.horusrobotics.dev/package-management/environment-management

Shows how the -t/--target flag changes where horus install places packages: global cache by default, or a specific workspace.

```bash
# No target: installs into the global cache ~/.cache/horus/
horus install serde

# With a target: installs into that workspace's .horus/packages/
horus install serde -t my_robot_project
```

--------------------------------

### Create a Horus library project with horus new --lib

Source: https://docs.horusrobotics.dev/package-management/package-management

Use to create a new Horus library project, configure it as a lib in horus.toml, implement modules in src/lib.rs, add an example, test it with horus run, and publish with horus auth login and horus publish.

```bash
# 1. Create new project as library
horus new my-sensor-lib --rust --lib

# 2. Update horus.toml
# [package]
# name = "my-sensor-lib"
# version = "0.1.0"
# type = "lib"

# 3. Implement in src/lib.rs
# pub mod drivers;
# pub mod calibration;

# 4. Add examples
mkdir examples
# Create examples/demo.rs

# 5. Test
horus run examples/demo.rs

# 6. Publish
horus auth login
horus publish

```

--------------------------------

### Using an installed package in Rust

Source: https://docs.horusrobotics.dev/package-management/package-management

Example of using an installed package (pid-controller) in a Rust application. It imports the PIDNode and horus prelude, creates a scheduler, adds the PID node, and runs it.

```rust
// In your main.rs or any file
use pid_controller::PIDNode;
use horus::prelude::*;

fn main() {
    let mut scheduler = Scheduler::new();

    // Use the installed package
    let pid = PIDNode::new(1.0, 0.1, 0.01);
    scheduler.add(pid).order(5).done();

    scheduler.run().expect("Scheduler failed");
}
```

--------------------------------

### Example usage and run command

Source: https://docs.horusrobotics.dev/package-management/package-management

Example usage of the node in a demo program and the command to run it.

```rust
// examples/demo.rs
use my_package::MyControllerNode;
use horus::prelude::*;

fn main() {
    let mut scheduler = Scheduler::new();

    let controller = MyControllerNode::new(2.5);
    scheduler.add(controller).order(5).done();

    scheduler.run().expect("Scheduler failed");
}
```

```bash
horus run examples/demo.rs --release
```

--------------------------------

### horus doctor -v: missing tool output

Source: https://docs.horusrobotics.dev/development/cli-reference

Example line from `horus doctor -v` showing a missing tool and its install command. `-v` lists every tool, its version, and the command that installs missing ones.

```text
a C++ compiler: not found (g++, clang++ or MSVC — cmake picks one) - install: sudo apt install build-essential

```

--------------------------------

### version examples

Source: https://docs.horusrobotics.dev/package-management/configuration

Examples of semantic version strings for the version key.

```toml
version = "0.1.0"    # Initial development
version = "1.0.0"    # First stable release
version = "2.3.1"    # Mature project

```

--------------------------------

### Install a plugin with horus install (auto-detection and --plugin)

Source: https://docs.horusrobotics.dev/plugins/managing-plugins

Shows how horus install auto-detects plugin packages and registers their commands. The first command installs horus-sim3d globally without needing --plugin. The second explicitly uses --plugin, but registration still depends on the package's own plugin metadata; otherwise you get "Package installed but no CLI plugin detected" and no command is registered.

```bash
# Auto-detects as a plugin and installs globally
horus install horus-sim3d

# Take the plugin install path explicitly (registration still depends on the
# package's own plugin metadata — without it you get "Package installed but no
# CLI plugin detected" and no command is registered)
horus install my-tool --plugin
```

--------------------------------

### Install PID Controller via Registry

Source: https://docs.horusrobotics.dev/package-management/using-prebuilt-nodes

Before you can use a pre-built node, install it with the `horus install` command. Note: this requires a registry; if none is configured, use path or git dependencies in horus.toml.

```shell
# Install from registry
horus install pid-controller
```

--------------------------------

### Recording session directory structure

Source: https://docs.horusrobotics.dev/development/testing

Example directory structure of a recording session. Each node gets its own recording file, and the scheduler execution order is stored separately.

```text
~/.local/share/horus/recordings/my_session/
├── sensor_node@abc123.horus       # Node recording
├── control_node@def456.horus      # Node recording
└── scheduler@main789.horus        # Scheduler execution order
```

--------------------------------

### Running multi-process HORUS with horus run and manual start

Source: https://docs.horusrobotics.dev/tutorials/08-multi-process-rust

Builds and runs the three binaries (lidar, controller, safety) with `horus run`, then shows how to start them manually in any order and monitor topics, nodes, and services. Rust binaries link HORUS statically, so no `LD_LIBRARY_PATH` is needed.

```bash
# Build all three binaries in one cargo invocation and spawn one process each
horus run nodes/lidar.rs nodes/controller.rs nodes/safety.rs

# That run leaves the binaries behind, so you can also start them by hand
# afterwards (order does not matter — start them in any order)
.horus/target/debug/controller &
.horus/target/debug/lidar &
.horus/target/debug/safety &

# Monitor from any terminal
horus topic list      # shows lidar.scan, cmd_vel, estop.request
horus node list       # shows lidar, controller, safety (separate PIDs)
horus service list    # shows estop

```

--------------------------------

### Version mismatch error output

Source: https://docs.horusrobotics.dev/development/cli-reference

Example error message that can occur when the horus CLI version is out of sync with the installed horus_core. Using --clean fixes this mismatch.

```text
error: the package `horus` depends on `horus_core 0.1.0`,
but `horus_core 0.1.3` is installed
```

--------------------------------

### Clone and run a Rust example

Source: https://docs.horusrobotics.dev/examples

Clone the HORUS repository and run the differential_drive example with `horus run main.rs`.

```bash
git clone https://github.com/softmata/horus.git
cd horus/examples/differential_drive
horus run main.rs

```
Tokens:
Raw