Quick Start (Python)

Prerequisites

• HORUS installed with horus --help working
• Python 3.9+ with HORUS bindings (python3 -c "import horus" works)
• A terminal and text editor

Installing the Python Bindings

Install the horus Python package from PyPI:

pip install horus-robotics

If you are building from source (e.g., developing HORUS itself or need unreleased features), use maturin instead:

cd horus_py
maturin develop --release

Verify the installation:

python3 -c "import horus; print('horus OK')"

What You'll Build

A temperature monitoring system with two nodes:

1. Sensor — generates temperature readings and publishes them
2. Monitor — subscribes to the readings and displays them

The nodes communicate through HORUS's shared-memory Topics — the same zero-copy IPC as Rust, accessible from Python.

Time estimate: ~10 minutes

Step 1: Create a New Project

horus new temperature-monitor -p
cd temperature-monitor

You should see three items in the project directory:

• src/main.py — your application code
• horus.toml — project configuration
• .horus/ — generated build files (managed automatically)

Step 2: Write the Code

Replace the contents of src/main.py with the following:

import horus

# ── Sensor Node ──────────────────────────────────────────────
# Publishes a simulated temperature reading every second.

def make_sensor():
    temp = [20.0]  # mutable state via closure

    def tick(node):
        temp[0] += 0.1
        node.send("temperature", temp[0])

    return horus.Node(name="TemperatureSensor", tick=tick, rate=1, order=0,
                      pubs=["temperature"])

# ── Monitor Node ─────────────────────────────────────────────
# Subscribes to temperature readings and prints them.

def monitor_tick(node):
    temp = node.recv("temperature")
    if temp is not None:
        print(f"Temperature: {temp:.1f}°C")

monitor = horus.Node(name="TemperatureMonitor", tick=monitor_tick, rate=1, order=1,
                     subs=["temperature"])

# ── Run ──────────────────────────────────────────────────────

print("Starting temperature monitoring system...\n")
horus.run(make_sensor(), monitor)

Step 3: Run It

horus run

You should see output like:

Starting temperature monitoring system...

Temperature: 20.1°C
Temperature: 20.2°C
Temperature: 20.3°C
Temperature: 20.4°C
...

Press Ctrl+C to stop.

Step 3.5: Inspect Your System

While your system is running (restart it with horus run in one terminal), open a second terminal in the same project directory and try these debugging tools:

# List all active topics
horus topic list

You should see temperature in the list — this is the shared memory topic your sensor is publishing to.

# Watch messages on a topic in real time
horus topic echo temperature

This prints every message as it's published. You'll see the temperature values streaming. Press Ctrl+C to stop.

# Measure the actual publish rate
horus topic hz temperature

This shows the real frequency of messages. Since your sensor runs at rate=1, you should see ~1.0 Hz.

Step 4: Understand the Key Patterns

You just used three core HORUS concepts:

Node — Component Definition

Each component is a horus.Node with a tick function:

def tick(node):
    node.send("temperature", value)

sensor = horus.Node(
    name="TemperatureSensor",
    tick=tick,
    rate=1,        # tick frequency in Hz
    order=0,       # execution priority (lower = runs first)
    pubs=["temperature"],  # declare published topics
)

The tick function receives the node instance and is called every cycle. State lives in the closure or as class attributes.

Topics — Communication

# Send data to a topic
node.send("temperature", value)

# Receive data from a topic (returns None if no messages)
temp = node.recv("temperature")

Both use the same topic name. HORUS manages shared memory automatically — same zero-copy IPC as Rust.

horus.run() — One-Liner Execution

horus.run(sensor, monitor)

Creates a scheduler, adds all nodes, and runs until Ctrl+C. For more control, use horus.Scheduler directly.

Troubleshooting

Key Takeaways

• Nodes are created with horus.Node(name, tick, rate, order, pubs, subs)
• node.send(topic, data) publishes data, node.recv(topic) subscribes (returns None if empty)
• horus.run(*nodes) is the one-liner to run everything
• State in tick functions lives in closures (lists for mutability) or class instances
• The Python API uses the same shared-memory Topics as Rust — no performance penalty for IPC

Next Steps

• Quick Start (Rust) — Build the same system in Rust
• Second Application (Python) — Build a 3-node pipeline with filtering and monitoring
• Choosing a Language — When to use Python vs Rust
• Common Mistakes (Python) — Avoid pitfalls specific to Python nodes

Beyond the Basics

You've seen Nodes, Topics, and horus.run(). HORUS has much more — here's what to explore next:

See Also

• Python API Reference — Full horus.Node, horus.run(), horus.Scheduler docs
• Nodes (Concept) — How nodes work under the hood
• Topic (Concept) — Shared memory architecture
• Python Examples — More sample applications