softmata/horus

HORUS – Real‑time Distributed Middleware

What it is – HORUS is a low‑latency, lock‑free middleware that lets programs written in Rust, Python, or C++ share data through shared‑memory ring buffers. It is positioned as a drop‑in replacement for DDS‑based systems like ROS 2, targeting domains where deterministic timing and safety matter (robotics, autonomous vehicles, industrial automation, high‑frequency trading, game engines, etc.).

Core concepts

• Node – a unit of work that implements a tick() (Rust) or a callback (Python/C++). Nodes are scheduled by a built‑in deterministic scheduler.
• Topic – a typed publish/subscribe channel backed by a lock‑free ring buffer. Messages are POD structs, so they can be transferred without copying.
• Scheduler – runs nodes at a configurable tick rate, supports five execution classes (real‑time, thread‑pool, event‑driven, async‑IO, best‑effort) and enforces budgets, deadlines, and watchdog policies.
• Safety monitor – graduated watchdog, safe‑state hooks, black‑box flight recorder, and per‑node fault‑tolerance policies.
• Zero‑copy AI pipeline – image, point‑cloud, and tensor types live in a shared‑memory pool; Python can obtain a NumPy view without a copy.

Languages & bindings

• Rust – primary implementation; crates are not published on crates.io but are fetched via the HORUS installer.
• Python – pip install "horus-robotics>=0.4.1" (or install from the cached source until a newer PyPI release appears).
• C++ – link against libhorus_cpp and include <horus/horus.hpp>.

Quick start (Rust)

use horus::prelude::*;

message! { SensorReading { position: f64, velocity: f64 } MotorCommand { voltage: f64 } }

fn main() -> Result<()> {
    let mut sched = Scheduler::new().tick_rate(1000_hz());
    // sensor node
    sched.add(Sensor::new()?).order(0).build()?;
    // controller node
    sched.add(Controller::new()?).order(1).rate(1000_hz()).on_miss(Miss::SafeMode).build()?;
    sched.run()
}

A similar 8‑line example exists for Python and a comparable snippet for C++.

Key features

Feature	What you get
Deterministic scheduling	Five execution classes, per‑node budgets/deadlines, automatic RT thread handling.
Safety monitor	Watchdog that throttles, isolates, or kills misbehaving nodes; safe‑state callbacks; black‑box logging.
Zero‑copy messaging	Shared‑memory ring buffers; NumPy views for image/tensor data; no serialization overhead for POD messages.
Rich message library	40+ built‑in POD message types (IMU, CmdVel, Detection, Image, PointCloud, etc.) plus services, actions, and transforms.
Hardware drivers	30+ drivers (Dynamixel, RealSense, RPLiDAR, CAN, EtherCAT, …) declarable via horus.toml.
CLI tooling	horus new, horus run, topic inspection (horus topic list/echo), system dashboard (horus monitor), remote deployment, health checks, self‑update.
Cross‑language interoperability	All three languages share the same shared‑memory segment, so a Rust node can publish to a Python subscriber without extra glue.

Performance highlights (measured on an Intel i9‑14900K)

• Cross‑process one‑way latency: 171 ns (≈30× faster than ROS 2’s ~5 µs DDS default).
• Same‑process send: 91 ns.
• Throughput: 37.8 M messages / s (vs. 3 M / s for iceoryx2).
• Bulk payloads (e.g., 1920×1080 mono image) stay ~284 ns one‑way because only a 224‑byte descriptor travels; the actual buffer is shared‑memory.

Installation

# One‑liner installer (downloads pre‑built CLI + cached source)
curl -fsSL https://github.com/softmata/horus/raw/main/install.sh | bash
horus new my_robot && cd my_robot && horus run

• The installer caches the exact source tree used to build the CLI, guaranteeing ABI compatibility.
• Manual install: git clone https://github.com/softmata/horus.git && ./install.sh.
• Requirements: Rust ≥ 1.90, Python ≥ 3.9, CMake ≥ 3.20 + C++17 compiler.

Typical use case

1. Define topics (e.g., camera, detections, motor.cmd).
2. Write nodes in any supported language that publish/subscribe to those topics.
3. Configure a horus.toml with driver settings and scheduler policies.
4. Run horus run – the scheduler launches the nodes, enforces real‑time constraints, and records a black‑box log for post‑mortem analysis.

Where it shines

• Tight control loops where sub‑200 ns IPC is required (high‑frequency motor control, sensor fusion).
• Multi‑language pipelines that need to pass large tensors or images without copying.
• Safety‑critical systems that benefit from built‑in watchdogs and deterministic execution classes.

Documentation & community

• Full docs: https://docs.horusrobotics.dev
• Quick‑start guide, benchmark methodology, migration guide from ROS 2, and extensive API reference.
• Discord community for support and discussion.

---

Bottom line – HORUS is a purpose‑built, real‑time middleware offering nanosecond‑scale IPC, deterministic scheduling, and cross‑language zero‑copy data sharing. It targets robotics and other latency‑critical domains as a high‑performance alternative to ROS 2 and traditional DDS solutions.