raccoon-cli

The dev toolchain for RaccoonOS — scaffold, configure, sync, and run Botball robots.

📖 Full documentation at raccoon-docs.pages.dev

raccoon is the command-line companion to RaccoonLib. It handles everything outside the robot code itself: creating projects, generating hardware boilerplate from a YAML config, syncing files to the Pi, and running your missions remotely.

Installation

pip install raccoon-cli

Quick Start

# 1. Create a project with the project helper script, then open it
cd MyRobot

# 2. Connect to your Pi
raccoon connect 192.168.4.1

# 3. Sync + run
raccoon run

That's it. raccoon run regenerates any stale code, syncs changed files to the Pi, and streams output back to your terminal.

How it works

raccoon uses a client-server architecture. Your laptop runs the CLI; the Pi runs a small FastAPI daemon (raccoon-server) that receives commands, manages execution, and streams logs back.

Pi setup (one time)

# On the Pi -- install raccoon-server as a systemd service
sudo raccoon-server install

After that, the server starts automatically on boot and raccoon connect can reach it.

Commands

Missions

Projects are git repos created with the project helper script; run raccoon from inside the project.

Hardware & code generation

Remote development

Debugging

Tooling

Project structure

A new project contains:

MyRobot/
├── raccoon.project.yml    # Hardware config -- motors, sensors, drivetrain, connection
├── src/
│   ├── main.py
│   ├── hardware/
│   │   ├── defs.py        # Generated -- do not edit by hand
│   │   └── robot.py       # Generated -- do not edit by hand
│   ├── missions/
│   │   ├── setup_mission.py
│   │   └── shutdown_mission.py
│   └── steps/
└── .raccoonignore         # match patterns excluded from sync

defs.py and robot.py are regenerated by raccoon codegen (and automatically on every raccoon run). Edit raccoon.project.yml to change the hardware config - never edit the generated files directly.

Configuration

A project uses a split config layout. The root file just glues things together:

raccoon.project.yml

name: MyRobot
uuid: <auto-generated>

robot:       !include 'config/robot.yml'
missions:    !include 'config/missions.yml'
definitions: !include 'config/hardware.yml'
connection:  !include 'config/connection.yml'

config/hardware.yml -- sensors, motors, servos

button:
  type: DigitalSensor
  port: 10
imu:
  type: IMU
front_left_ir_sensor:
  type: IRSensor
  port: 1
front_right_ir_sensor:
  type: IRSensor
  port: 2

_motors: !include-merge 'motors.yml'
_servos: !include-merge 'servos.yml'

config/motors.yml

left_motor:
  type: Motor
  port: 0
  inverted: false
  calibration:
    ticks_to_rad: 0.00002   # set by raccoon calibrate
    vel_lpf_alpha: 1.0
    # Optional: omit pid to use STM32 firmware defaults
    # pid: {kp: 1.22, ki: 0.045, kd: 0.0}
right_motor:
  type: Motor
  port: 1
  inverted: true
  calibration:
    ticks_to_rad: 0.00002
    vel_lpf_alpha: 1.0

config/connection.yml

pi_address: 192.168.4.1
pi_port: 8421
pi_user: pi
auto_connect: true

~/.raccoon/config.yml (global)

known_pis:
  - hostname: raccoon-pi
    address: 192.168.4.1
default_pi_user: pi

Part of RaccoonOS

Contributing

See CONTRIBUTING.md for how to get started contributing

License

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