Example Projects

Twelve complete applications ship in the HORUS repository under examples/. Each one is a real project — a horus.toml, a main.rs, main.py or src/main.cpp, a robot description under robots/, and for seven of them a worlds/ scene — not a snippet. They are what to reach for when you know what you want to build and would rather see it built once first.

ℹ️These are projects; the language pages are snippets

Rust Examples, Python Examples and C++ Examples show individual API patterns inside this documentation. The twelve below are checked-out, runnable applications with their own manifests. A CI job (shipped-examples-build in .github/workflows/docs-contract.yml) runs horus build in every project under examples/ on each pull request, and a failure blocks the merge through the required Docs Contract Success check — so a break is caught on the pull request that caused it, not a day later.

Start here

Example	Language	What it teaches
differential_drive	Rust	Nodes, topics, messages, scheduler basics — the smallest complete robot
python_robot	Python	The same robot in Python; the starting point if you are not writing Rust
differential_drive_cpp	C++	The same robot again in C++; a `horus.toml` project that `horus build` drives through cmake

Core robotics

Example	Language	What it teaches
robot_arm	Rust	6-DOF joint control, services, and frame transforms with `TransformFrame`
sensor_navigation	Rust	LiDAR + IMU, multi-rate scheduling, reactive obstacle avoidance
sensor_navigation_py	Python	The same LiDAR + IMU navigation in Python
camera_perception	Rust	A CV pipeline: camera capture, object detection, IoU/SORT tracking

Advanced

Example	Language	What it teaches
multi_robot	Rust	Namespaced topics, launch files, fleet coordination
quadruped	Rust	Real-time nodes: 12-DOF gait with budgets, deadlines and IMU feedback
pick_and_place	Rust	Actions — goal lifecycle, feedback, cancellation

Production

Example	Language	What it teaches
driver_integration	Rust	Hardware drivers from the manifest, Terra HAL, custom driver nodes
record_replay	Rust	Session recording, blackbox forensics, deterministic replay

Coming from ROS 2

If you know the ROS 2 tutorial you would have followed, this is its counterpart:

ROS 2 workflow	HORUS example
Publisher/subscriber tutorial	`differential_drive` or `python_robot`
tf2 and frame transforms	`robot_arm`
nav2 sensor pipeline	`sensor_navigation`
darknet_ros / YOLO detection	`camera_perception`
Multi-robot swarm	`multi_robot`
`ros2_control` hardware	`driver_integration`
MoveIt pick-and-place	`pick_and_place`
`rosbag2` record/play	`record_replay`
Legged robot control	`quadruped`

See also Migrating from ROS 2 for the API mapping, and the ROS 2 bridge recipe for running both at once.

Running one

Every example is an ordinary HORUS project, so it runs the way yours does:

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

Python is the same command:

cd horus/examples/python_robot
horus run main.py

The simulator is optional — the examples publish and subscribe without it. To see the robot move, start sim3d in another terminal first:

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

Five of the twelve — camera_perception, driver_integration, pick_and_place, python_robot and record_replay — ship no worlds/ directory. Start sim3d without --world for those, or point --world at a scene from another example.

While one is running, the usual introspection applies:

horus topic list
horus topic echo cmd_vel
horus node list
horus monitor

Turning one into your project

horus new <name> --from <example> is the one step: it copies the shipped example, renames the package to <name>, and leaves the build output behind.

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

Pass a name that does not exist — horus new my_robot --from list — and the error is the list of available examples. The language comes from the example, so the language and layout flags do not apply alongside --from and are rejected rather than ignored: --python, --rust, --cpp, --macro, --workspace and --lib.

The examples are read out of the HORUS source tree, the same one horus build already needs for its path dependencies — a checkout, an installer cache, or wherever HORUS_SOURCE points. Nothing is copied that belongs to that tree: .horus/, target/, build/, __pycache__/, .git/ and the tool caches are all skipped, so the new project carries no build output and no path dependency on someone else's checkout.

Copying the directory by hand still works if you would rather:

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

Rename the package in the manifest — two projects that keep the same [package] name build binaries that collide in a shared target directory and register the same node names at runtime. horus build regenerates .horus/Cargo.toml from horus.toml on every build, so the manifest is the only file holding the name. Delete the copied .horus/ directory if one came along; it is a build cache.

💡Copy the manifest, not just the code

horus.toml is where an example's dependencies, [hardware] entries and scripts live — driver_integration's driver table and robot_arm's horus-tf dependency are both in the manifest, not in src/main.rs. Copying only the source file is the usual reason a copied example stops compiling.

C++ examples

One C++ example is a full project like the rest: examples/differential_drive_cpp has a horus.toml and builds with horus build, which generates a CMakeLists.txt into .horus/ and links libhorus_cpp.a for you. It is in the Start here table above.

The remaining C++ examples live under horus_cpp/examples/ rather than examples/, because they are standalone translation units built directly with CMake against the C++ bindings rather than through horus build:

Example	What it teaches
`pub_sub_demo.cpp`	Topics, the loan/publish pattern, send-by-copy
`multi_node.cpp`	Several nodes in one scheduler — rates, budgets, `on_miss`
`obstacle_avoidance.cpp`	Reactive control from a `LaserScan`
`camera_publisher.cpp`	Publishing sensor data at a fixed rate
`transform_frames.cpp`	Coordinate frames from C++
`params_demo.cpp`	Runtime parameters

cargo build -p horus_cpp                      # produces libhorus_cpp.a
cmake -S horus_cpp/examples -B build/cpp-examples
cmake --build build/cpp-examples

CMake finds the library under target/ automatically in a checkout; pass -DHORUS_CPP_LIB=... to point it elsewhere.