https://github.com/htl-stp-ecer/raccoon-cli
Dev toolchain for RaccoonOS — scaffold projects, configure hardware, sync code, and run missions on the Wombat
https://github.com/htl-stp-ecer/raccoon-cli
botball cli code-generation python raccoon-os raspberry-pi robotics
Last synced: 2 months ago
JSON representation
Dev toolchain for RaccoonOS — scaffold projects, configure hardware, sync code, and run missions on the Wombat
- Host: GitHub
- URL: https://github.com/htl-stp-ecer/raccoon-cli
- Owner: htl-stp-ecer
- License: gpl-3.0
- Created: 2026-01-29T06:40:57.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T18:04:31.000Z (3 months ago)
- Last Synced: 2026-04-08T19:27:44.585Z (3 months ago)
- Topics: botball, cli, code-generation, python, raccoon-os, raspberry-pi, robotics
- Language: Python
- Homepage: https://raccoon-docs.pages.dev/
- Size: 1.33 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# raccoon-cli
**The dev toolchain for RaccoonOS — scaffold, configure, sync, and run Botball robots.**
[](https://github.com/htl-stp-ecer/raccoon-cli/actions/workflows/build-release.yml)
[](https://github.com/htl-stp-ecer/raccoon-cli/releases/latest)
[](COPYING)
> 📖 **Full documentation at [raccoon-docs.pages.dev](https://raccoon-docs.pages.dev/)**
---
`raccoon` is the command-line companion to [RaccoonLib](https://github.com/htl-stp-ecer/raccoon-lib). 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
```bash
pip install raccoon-cli
```
---
## Quick Start
```bash
# 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)
```bash
# 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 ` | Scaffold a new project and run the hardware wizard |
| `raccoon create mission ` | 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 ` | 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` | Two-phase calibration: measure encoder ticks/rev, then run autotune |
### Remote development
| Command | Description |
|:--------|:------------|
| `raccoon connect
` | 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 ` | Record LCM traffic to a file |
| `raccoon checkpoint list` | List saved checkpoints |
| `raccoon checkpoint restore ` | 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`
```yaml
name: MyRobot
uuid:
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
```yaml
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`
```yaml
left_motor:
type: Motor
port: 0
inverted: false
calibration:
ticks_to_rad: 0.00002 # set by raccoon calibrate
vel_lpf_alpha: 1.0
right_motor:
type: Motor
port: 1
inverted: true
calibration:
ticks_to_rad: 0.00002
vel_lpf_alpha: 1.0
```
### `config/connection.yml`
```yaml
pi_address: 192.168.4.1
pi_port: 8421
pi_user: pi
auto_connect: true
```
### `~/.raccoon/config.yml` (global)
```yaml
known_pis:
- hostname: raccoon-pi
address: 192.168.4.1
default_pi_user: pi
```
---
## Part of RaccoonOS
| Repository | What it is |
|:-----------|:-----------|
| [raccoon-lib](https://github.com/htl-stp-ecer/raccoon-lib) | Core robotics library |
| [raccoon-example](https://github.com/htl-stp-ecer/raccoon-example) | Reference robot -- start here if you're new |
| [raccoon-transport](https://github.com/htl-stp-ecer/raccoon-transport) | LCM messaging layer |
| [documentation](https://raccoon-docs.pages.dev/) | Full platform docs |
---
## Contributing
See [CONTRIBUTING.md](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](COPYING) for details.