raccoon-sim 1.0.143

Raccoon robotics library — compiled runtime + simulator (native bindings; formerly libstp)

RaccoonLib

The core robotics library powering RaccoonOS for Botball.

PID motion control · Kinematics · Odometry · Step-based missions · Python bindings

📖 Full documentation at raccoon-docs.pages.dev

---

RaccoonLib is the heart of RaccoonOS — a full robotics platform built for Botball competition. It gives your robot a solid foundation: reliable motion, clean sensor abstractions, and a step-based mission system that makes autonomous code readable and maintainable.

Built from years of competition experience at HTL St. Pölten, it's designed so that new teams don't have to start from zero.

---

What's Inside

Module	What it does
Motion Control	PID-controlled drive_forward, turn_right, drive_strafe with feedforward compensation
Calibration	Auto-tune feedforward (kS, kV, kA) and PID via relay-feedback — no guessing
Kinematics	Differential and mecanum drivetrains — forward & inverse
Odometry	Real-time position and heading from wheel encoders + IMU fusion
Step Framework	seq(), parallel(), .until() — write missions like a readable recipe
Sensors & Actuators	IR sensors, buttons, servos — clean, consistent API
Python Bindings	Full Python API via pybind11 — same power, less boilerplate

---

Getting Started

RaccoonLib runs on the KIPR Wombat controller (Raspberry Pi, ARM64). Local installs without a mock platform are not supported — deploy directly to the Pi.

1. Clone

git clone https://github.com/htl-stp-ecer/raccoon-lib.git --recurse-submodules
cd raccoon-lib

2. Build & deploy to your Pi in one step

RPI_HOST=<your-pi-ip> bash deploy.sh

This cross-compiles for ARM64 via Docker and installs the wheel on your Pi over SSH. No local toolchain setup needed.

Variable	Default	Description
RPI_HOST	(required)	Raspberry Pi IP address
RPI_USER	pi	SSH username
RPI_DIR	/home/pi/python-libs	Install directory
BUILD_TYPE	Release	CMake build type

Starting a new robot project? Use raccoon-cli — raccoon create project MyRobot runs a hardware wizard and generates your robot config, project structure, and deploy scripts automatically.

Installing from PyPI

RaccoonLib ships as two coordinated distributions:

Command	What you get	Use it for
pip install raccoon-library	Platform-independent Python/.pyi headers (py3-none-any). No compilation, no native code.	IDE type hints, type-checking, and the raccoon-cli toolchain codegen. Does not run the robot on its own.
pip install "raccoon-library[sim]"	The above plus the compiled raccoon-sim bindings + simulator + mock/wombat runtime bundle.	Actually running missions in the simulator, or on the Pi/Wombat.

The [sim] extra pulls in raccoon-sim, pinned to the exact same version, so the headers and the native bindings can never drift apart. import raccoon requires [sim] (or a locally deployed raccoon-sim wheel — see deploy.sh above).

---

How It Works

You write missions. RaccoonLib handles the math.

Missions are Python classes with a sequence() method — describe what the robot does step by step:

from libstp import *

class M01NavigateToZone(Mission):
    def sequence(self) -> Sequential:
        return seq([
            mark_heading_reference(),       # lock current heading as 0°

            parallel(
                drive_forward(cm=40),       # drive while lowering arm
                seq([
                    wait_until_distance(7),
                    Defs.arm_servo.hold(),
                ]),
            ),

            turn_right(degrees=90),

            # drive until both IR sensors see black tape
            drive_forward().until(
                on_black(Defs.front.left) & on_black(Defs.front.right)
            ),

            drive_backward(cm=3),
        ])

The robot hardware config (motors, sensors, PID gains) is generated by raccoon-cli's hardware wizard — see raccoon-example for a fully commented reference.

---

Architecture

---

Requirements

• CMake >= 3.15
• C++20 compatible compiler
• Python >= 3.11
• Docker (for ARM64 cross-compilation)

C++ dependencies: Eigen3 3.4.0 · LCM 1.5.0 · spdlog 1.14.1 · pybind11 2.13.6 Python dependencies: pyyaml · aiosqlite

---

Testing

# C++ tests
cmake -B build -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build

# Python tests
pytest tests/

---

Part of RaccoonOS

RaccoonLib is one piece of the full platform:

Repository	What it is
raccoon-cli	Dev toolchain — scaffolding, hardware wizard, raccoon run
raccoon-example	Reference robot — start here if you're new
raccoon-transport	LCM messaging layer (C++, Python, Dart)
documentation	Full platform docs

---

Contributing

See CONTRIBUTING.md for how to add modules, steps, run tests, and follow code style.

---

License

Copyright (C) 2026 Tobias Madlberger Licensed under the GNU General Public License v3.0 — see LICENSE for details.