raccoon-cli

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

Python PyPI Platform

📖 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 new project (runs the hardware wizard automatically)
raccoon create project MyRobot
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

Project management

Command	Description
`raccoon create project <name>`	Scaffold a new project and run the hardware wizard
`raccoon create mission <name>`	Add a new mission to the current project
`raccoon list projects`	List all projects in the current directory
`raccoon list missions`	List missions in the current project
`raccoon remove mission <name>`	Remove a mission
`raccoon reorder`	Interactively reorder missions

Hardware & code generation

Command	Description
`raccoon wizard`	Re-run the interactive hardware configuration
`raccoon codegen`	Regenerate `src/hardware/defs.py` and `src/hardware/robot.py` from config
`raccoon calibrate ticks`	Measure encoder ticks per revolution
`raccoon calibrate autotune`	Run motor autotune
`raccoon calibrate servos`	Interactively calibrate servo offsets

Remote development

Command	Description
`raccoon connect <address>`	Connect to a Pi server
`raccoon disconnect`	Disconnect from the current Pi
`raccoon status`	Show connection status
`raccoon sync`	Sync changed files to the Pi (uses content hashing)
`raccoon sync --force`	Re-upload all files
`raccoon run`	Regenerate code, sync, and run on the Pi

Debugging

Command	Description
`raccoon lcm spy`	Live-inspect LCM messages on the bus
`raccoon lcm record <file>`	Record LCM traffic to a file
`raccoon checkpoint list`	List saved checkpoints
`raccoon checkpoint restore <id>`	Restore project to a checkpoint

Tooling

Command	Description
`raccoon update`	Update raccoon-cli to the latest version
`raccoon completion`	Install shell tab-completion
`raccoon web`	Launch the web IDE

Project structure

raccoon create project generates:

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 or re-run raccoon wizard to change hardware config - never edit the generated files directly.

Configuration

raccoon create project generates 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

Repository	What it is
raccoon-lib	Core robotics library
raccoon-example	Reference robot -- start here if you're new
raccoon-transport	LCM messaging layer
documentation	Full platform docs

Contributing

See CONTRIBUTING.md for how to get started contributing

License

Metadata

Release files for raccoon-cli 0.1.169

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for raccoon-cli 0.1.169
File	Interpreter	ABI	Platform	Reset
raccoon_cli-0.1.169-py3-none-any.whl 2.0 MB Jul 13, 2026	Python 3	none	any	Details

Release files / raccoon_cli-0.1.169-py3-none-any.whl

Download URL	raccoon_cli-0.1.169-py3-none-any.whl
Size	2.0 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`ac0f3e3d4e53a21e0471ea9eaa93e67c86c690f5887fda8fd761831941458547`
BLAKE2b-256 checksum How to use checksums	`7d442f672858d5c32ba451d0c0fa404933dcf368982804ecbca6c543c7338edc`
Upload date	Jul 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/htl-stp-ecer/raccoon-cli
Publishing commit: github.com/htl-stp-ecer/raccoon-cli/tree/24aae0fef458097a8b0adcc78173ee8e65a5b724

Workflow

Publishing configuration: github.com/htl-stp-ecer/raccoon-cli/blob/24aae0fef458097a8b0adcc78173ee8e65a5b724/.github/workflows/build-release.yml
Publishing logs: github.com/htl-stp-ecer/raccoon-cli/actions/runs/29282299287/attempts/1

Artifact

Subject: raccoon_cli-0.1.169-py3-none-any.whl
SHA-256 checksum: ac0f3e3d4e53a21e0471ea9eaa93e67c86c690f5887fda8fd761831941458547 Verifying attestations