softmata/horus

HORUS – Real‑time distributed middleware for robotics (Rust / Python / C++)

What it is – HORUS is a low‑latency, lock‑free inter‑process communication (IPC) layer that replaces the DDS stack used by ROS 2. It lets programs written in Rust, Python or C++ share data through a single shared‑memory ring buffer, giving deterministic scheduling and sub‑200 ns cross‑process latency.

Why it matters – For robotics, autonomous vehicles, industrial automation, or any safety‑critical system, predictable timing and minimal overhead are essential. HORUS claims deterministic execution classes, built‑in watchdogs, and zero‑copy pipelines for AI‑heavy perception workloads.

Core concepts (as shown in the README)

Concept	Role
Node	A unit of work that implements a `tick()` (Rust) / callback (Python) / `tick()` method (C++). Nodes are scheduled by the `Scheduler`.
Topic	Typed publish/subscribe channel backed by a lock‑free ring buffer. All languages use the same shared‑memory layout, so a Rust publisher can be read directly by a Python subscriber without copying.
Scheduler	Manages execution classes (real‑time, thread‑pool, event‑driven, async‑IO, best‑effort). You can set rate, budget, deadline, ordering, and miss‑handling policies per node.
Safety monitor	Graduated watchdog that escalates from warnings to rate reduction, isolation, and finally killing a misbehaving node. Nodes can define `enter_safe_state()` to put hardware in a known safe condition.
BlackBox	Ring‑buffer flight recorder for post‑mortem analysis.
TransformFrame	Fast lock‑free coordinate‑transform tree (10‑33× faster than ROS TF2).
Message types	40+ built‑in POD structs (e.g., `Imu`, `CmdVel`, `Detection`, `Image`, `PointCloud`). Large payloads (images, tensors) are stored in a shared‑memory pool and accessed zero‑copy from NumPy.
Drivers	Declarative HAL integration via `horus.toml` (30+ drivers from the Terra HAL project).

Quick‑start snippets (from the README)

Rust – a 1 kHz sensor‑controller pair in a single file, using `Topic::new`, `Scheduler::new().tick_rate(1000_hz())`, and optional policies like `.order()` and `.on_miss(Miss::SafeMode)`. Python – eight‑line equivalent using `horus.run` with `Node` objects, `node.send` / `node.recv`, and optional `rate` arguments. C++ – class‑based node inheriting from `horus::Node`, with `subscribe`/`advertise` helpers and the same scheduler configuration.

Main features

Deterministic real‑time scheduling – five execution classes, automatic RT when a node has a rate/budget/deadline.
Safety & fault tolerance – graduated watchdog, deadline enforcement, per‑node safe‑state hooks, BlackBox recorder, restart/back‑off policies.
Zero‑copy AI pipeline – shared‑memory pools let camera frames, point clouds, and tensors be turned into NumPy arrays without copying; only a small descriptor travels on the topic.
High performance – reported 171 ns one‑way cross‑process latency, 91 ns same‑process send, and up to 12.8× throughput over iceoryx2 for small messages.
Cross‑language interoperability – the same topics are visible to Rust, Python, and C++ processes.
Built‑in robotics primitives – messages, services, actions, transforms, and 30+ hardware drivers (Dynamixel, RealSense, CAN, EtherCAT, etc.).
CLI tooling – horus new, horus run, topic inspection (horus topic list/echo), system dashboard (horus monitor), remote deployment, health checks, and self‑update.

Installation & usage (as described)

One‑liner installer – curl …/install.sh | bash (or set HORUS_VERSION to pin a release). The script fetches a pre‑built CLI and caches the matching source tree under ~/.horus/cache/horus@<version>.
Language bindings
- Rust – add the local path dependency manually (cargo add horus points to the cached source). No crates.io publish yet.
- Python – pip install "horus-robotics>=0.4.1" for the older 0.1.x format, or build from the cached source with pip install ~/.horus/cache/horus@0.4.1/horus_py.
- C++ – link against libhorus_cpp and include <horus/horus.hpp>; requires CMake 3.20+ and a C++17 compiler.
Project scaffolding – horus new my_robot (choose language with --cpp / --python / default Rust) creates a starter package and a horus.toml for driver config.
Run – horus run builds the Rust code against the cached source and launches the scheduler.

Performance highlights (from the README)

Metric	Value	Context
Cross‑process one‑way latency	171 ns	Ring‑buffer send/receive, measured on Intel i9‑14900K.
Same‑process send latency	91 ns	Producer‑side `send()` only.
1 pub → 3 subs latency	80 ns	Producer‑side.
Comparison to ROS 2 DDS	~5 µs median (REP 2014) → ≈30× faster for the same cross‑process case.
vs iceoryx2 (8 B)	55 ns vs 416 ns (median) → 7.6× faster.
Throughput (same loop)	37.8 M msg/s vs 3.0 M msg/s (iceoryx2) → 12.8×.
Large image payload (1920×1080) one‑way p50	284 ns (descriptor only, zero‑copy)

Typical use‑cases

Low‑level motor control where sub‑microsecond jitter can cause instability.
Sensor‑fusion pipelines that combine camera frames, LiDAR point clouds, and IMU data in a single process while still exposing the data to Python AI models.
Safety‑critical robotics that need deterministic watchdogs and a guaranteed safe‑state transition.
High‑frequency trading or game‑engine subsystems that require ultra‑low IPC latency (the README mentions these domains as well).

Maturity & ecosystem

Version – v0.4.1 (latest tag at time of README). The Python package on PyPI is still at 0.1.9; the newer 0.4.x format must be built from source.
CI – GitHub Actions badge present; benchmarks are part of the repo.
Documentation – Hosted at https://docs.horusrobotics.dev with sections on quick‑start, scheduler configuration, safety monitor, and benchmarks.
Community – Discord server linked for support.
License – Apache‑2.0.

Bottom line

HORUS is a genuine, actively maintained middleware project aimed at real‑time robotics and other latency‑critical systems. It offers deterministic scheduling, safety monitors, and zero‑copy data paths across Rust, Python, and C++. If you need sub‑microsecond IPC and a tighter integration than ROS 2’s DDS layer provides, HORUS is worth evaluating.