rosie

Learn mobile robotics by reading the robot

Quick start · What you can learn · Documentation · Development

rosie is a complete robot stack (localization, planning, control, drives) for two-wheeled robots, written as short Python modules you can read, change and run on a simulated robot or a real one. It estimates where the robot is from its wheel encoders, plans routes around walls and furniture and trajectories along them, tracks them with feedback controllers, and lets you drive by hand from a browser or from Python.

It's made for learning and teaching robotics, from the control equations to the web page that drives the robot.

Quick start

rosie runs next to the robot, or next to a simulated one, and takes orders over a web API. There are several ways to use it: from a browser, from Python, from plain HTTP, or by changing rosie itself. Each one below starts with the simulated robot, so no hardware is needed.

In the browser

docker run -p 8080:8080 ghcr.io/pyforce/rosie

Open http://localhost:8080: WebRosie, with a simulated robot in a house. Click the map to send it somewhere, or drive it with the keyboard.

As a Python package

pip install "pyforce-rosie[robot]"
rosie start

This runs rosie's web API on port 5000, without the web interface. Flags or ROSIE_* environment variables pick another robot, map or port.

From a Python script or notebook

With rosie running (either way above), on the same computer or any other:

import time

from rosie.client import RosieClient  # pip install pyforce-rosie

robot = RosieClient("http://localhost:8080")  # 5000 with rosie start
print(robot.odometry())  # Position(x=0.0, y=0.0, theta=0.0)
robot.goto(1, 0.5, 0.3)  # to (1 m, 0.5 m) at 0.3 m/s
time.sleep(5)
print(robot.odometry())  # about Position(x=1.0, y=0.5, theta=0.46)

Over HTTP

The web API is plain HTTP and JSON, so any language or tool can drive the robot:

curl -X POST localhost:8080/goto -d '{"target": [1, 0.5], "speed": 0.3}'
curl localhost:8080/odometry

From the source

To change rosie itself, for example to try your own controller:

git clone https://github.com/PyForce/rosie
cd rosie
uv sync
uv run rosie start

Getting started covers each of these in more detail, plus configuration.

What you can learn

The simulated robot runs on a clock you control, so a script can simulate a 10-second movement in milliseconds, the same every time. Every planned movement can be recorded to CSV, one row per control step, ready for pandas.

Documentation

• Getting started: running, driving and configuring rosie.
• How rosie works: the control loop, and where everything lives.
• Motion control and Navigation: the algorithms, with their equations.
• Teaching with rosie: lab ideas.
• Robots and hardware, Web API and extensions, Python client.

Development

Setup, QA, docs and releases: DEVELOPMENT.md.

Contributing

Issues and pull requests are welcome; make qa must pass.

License

MIT: see LICENSE. rosie is a PyForce project, started in 2015: authors.

_{🚀 Project starter provided by Cookie Pyrate v1.1.0}