# Upkie wheeled biped robots
<img src="https://github.com/upkie/upkie/assets/1189580/2fc5ee4a-81b0-425c-83df-558c7147cc59" align="right" width="250" />
[](https://github.com/upkie/upkie/actions/workflows/ci.yml)
[](https://upkie.github.io/upkie/)
[](https://coveralls.io/github/upkie/upkie?branch=main)
[](https://anaconda.org/conda-forge/upkie)
[](https://pypi.org/project/upkie/)
**Upkies** are open-source wheeled biped robots. They have wheels for balancing and legs to negotiate uneven terrains. Upkies are designed to be buildable with off-the-shelf tools and components, like mjbots actuators. You can develop in Python or C++, on Linux or macOS, then deploy your behaviors to the robot's Raspberry Pi. Here are some instances of [Upkies in action](https://www.youtube.com/@upkie).
This repository contains all the materials needed to build and control an Upkie. Questions are welcome in the [discussions forum](https://github.com/upkie/upkie/discussions) or in the [chat room](https://matrix.to/#/#upkie:matrix.org).
## Building your own Upkie
Step by step instructions to build a new Upkie from scratch are available in the [Wiki](https://github.com/upkie/upkie/wiki).
## Getting started
Upkies come with a model predictive controller that can balance and roam around. You can try it out in simulation by:
```console
./start_mpc_balancer.sh
```
Once the agent is running, you can direct your Upkie using a gamepad 🎮
- **Left joystick:** go forward right backward
- **Right joystick:** turn left or right
- **Directional pad:** down to crouch, up to stand up
- **Right button:** (B on an Xbox controller, red circle on a PS4 controller) emergency stop 🚨 all motors will turn off
Click on the robot in the simulator window to apply external forces and see how the robot reacts.
## Creating your own behaviors
Software for Upkies comes is packaged in an `upkie` Python library. You can install it:
- From conda-forge: `conda install -c conda-forge upkie`
- From PyPI: `pip install upkie`
When running on the real robot, your code will command the robot's actuators via another process called the *spine*. There are also simulation spines for testing before deploying to a robot. Let's start a Bullet simulation spine:
<img src="https://raw.githubusercontent.com/upkie/upkie/refs/heads/main/docs/images/bullet-spine.png" height="100" align="right" />
```console
./start_simulation.sh
```
Now that we have a spine is running, we can control the robot in Python. For example:
```python
import gymnasium as gym
import numpy as np
import upkie.envs
upkie.envs.register()
with gym.make("Upkie-Spine-Pendulum", frequency=200.0) as env:
observation, _ = env.reset()
gain = np.array([10.0, 1.0, 0.0, 0.1])
for step in range(1_000_000):
action = gain.dot(observation).reshape((1,))
observation, reward, terminated, truncated, _ = env.step(action)
if terminated or truncated:
observation, _ = env.reset()
```
Other Gymnasium environments provide various levels of absraction to control the robot. They are listed in the [Gym environments](https://upkie.github.io/upkie/gym-environments.html) page of the documentation.
## Going further
### Examples
There are smaller standalone examples in the [examples](https://github.com/upkie/upkie/tree/main/examples) directory. For instance:
- Domain randomization: shows how to add domain-randomization wrappers to an Upkie environment.
- Lying genuflection: genuflect while lying on a horizontal floor.
- Model predictive control: a self-contained MPC balancer
- PD balancer: balance by proportional-derivative feedback to wheel velocities.
Some examples have optional dependencies, like those for the Genesis and PyBullet simulators. You can activate a virtual environment and install them as optional dependencies, or use Pixi:
```console
pixi run --environment genesis ./examples/genesis_balancing.py
```
### Tasks
Upkies come with a set of default behaviors that you can executed as Pixi tasks. To get started, make sure you have [installed `pixi`](https://pixi.sh/latest/#installation).
| Name | Task |
|------------------------|----------------------------------------------------------|
| `rlb3-enjoy-genesis` | Evaluate the last policy trained in Genesis |
| `rlb3-enjoy-pybullet` | Evaluate the last policy trained in PyBullet |
| `rlb3-train-genesis` | Train a new policy by reinforcement learning in Genesis |
| `rlb3-train-pybullet` | Train a new policy by reinforcement learning in PyBullet |
| `try-genesis` | Run a balancing example in Genesis |
| `try-pybullet` | Run a balancing example in PyBullet |
| `upkie-mpc-balancer` | Run the MPC balancer |
You can execute a task by `pixi run <task-name>`, for instance:
```console
pixi run upkie-mpc-balancer
```
Tasks are available both on your machine and on your Upkie's Raspberry Pi (Pixi comes pre-installed on the SD card image). They are implemented by [agents](https://github.com/upkie/upkie/tree/main/agents). You can make your own agents by forking this repository or using the [new\_agent](https://github.com/upkie/new_agent) template to get started.
### Contributing
Contributions are welcome to both the hardware and software of Upkies! Check out the [contribution guidelines](CONTRIBUTING.md).
## Citation
If you built an Upkie or use parts of this project in your works, please cite the project and its contributors:
```bibtex
@software{upkie,
title = {{Upkie open source wheeled biped robot}},
author = {Caron, St\'{e}phane and Perrin-Gilbert, Nicolas and Ledoux, Viviane and G\"{o}kbakan, \"{U}mit Bora and Raverdy, Pierre-Guillaume and Raffin, Antonin and Tordjman--Levavasseur, Valentin},
url = {https://github.com/upkie/upkie},
license = {Apache-2.0},
version = {9.0.0},
year = {2025}
}
```
Don't forget to add yourself to the BibTeX above and to `CITATION.cff` if you contribute to the project.
## See also
- [Awesome Open Source Robots](https://github.com/stephane-caron/awesome-open-source-robots): Upkies are one among many open-source open-hardware robot initiative: check out the others!
- [Open Dynamic Robot Initiative](https://open-dynamic-robot-initiative.github.io/): An open torque-controlled modular robot architecture for legged locomotion research.
Raw data
{
"_id": null,
"home_page": null,
"name": "upkie",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "St\u00e9phane Caron <stephane.caron@normalesup.org>",
"keywords": "wheeled, biped, robot, balance, motion, control, robotics",
"author": null,
"author_email": "St\u00e9phane Caron <stephane.caron@normalesup.org>",
"download_url": "https://files.pythonhosted.org/packages/4c/d1/71f24147dbb40f07785a6d21f6b81b944d1ae684b4754b769a797cec82c9/upkie-9.0.0.tar.gz",
"platform": null,
"description": "# Upkie wheeled biped robots\n\n<img src=\"https://github.com/upkie/upkie/assets/1189580/2fc5ee4a-81b0-425c-83df-558c7147cc59\" align=\"right\" width=\"250\" />\n\n[](https://github.com/upkie/upkie/actions/workflows/ci.yml)\n[](https://upkie.github.io/upkie/)\n[](https://coveralls.io/github/upkie/upkie?branch=main)\n[](https://anaconda.org/conda-forge/upkie)\n[](https://pypi.org/project/upkie/)\n\n**Upkies** are open-source wheeled biped robots. They have wheels for balancing and legs to negotiate uneven terrains. Upkies are designed to be buildable with off-the-shelf tools and components, like mjbots actuators. You can develop in Python or C++, on Linux or macOS, then deploy your behaviors to the robot's Raspberry Pi. Here are some instances of [Upkies in action](https://www.youtube.com/@upkie).\n\nThis repository contains all the materials needed to build and control an Upkie. Questions are welcome in the [discussions forum](https://github.com/upkie/upkie/discussions) or in the [chat room](https://matrix.to/#/#upkie:matrix.org).\n\n## Building your own Upkie\n\nStep by step instructions to build a new Upkie from scratch are available in the [Wiki](https://github.com/upkie/upkie/wiki).\n\n## Getting started\n\nUpkies come with a model predictive controller that can balance and roam around. You can try it out in simulation by:\n\n```console\n./start_mpc_balancer.sh\n```\n\nOnce the agent is running, you can direct your Upkie using a gamepad \ud83c\udfae\n\n- **Left joystick:** go forward right backward\n- **Right joystick:** turn left or right\n- **Directional pad:** down to crouch, up to stand up\n- **Right button:** (B on an Xbox controller, red circle on a PS4 controller) emergency stop \ud83d\udea8 all motors will turn off\n\nClick on the robot in the simulator window to apply external forces and see how the robot reacts.\n\n## Creating your own behaviors\n\nSoftware for Upkies comes is packaged in an `upkie` Python library. You can install it:\n\n- From conda-forge: `conda install -c conda-forge upkie`\n- From PyPI: `pip install upkie`\n\nWhen running on the real robot, your code will command the robot's actuators via another process called the *spine*. There are also simulation spines for testing before deploying to a robot. Let's start a Bullet simulation spine:\n\n<img src=\"https://raw.githubusercontent.com/upkie/upkie/refs/heads/main/docs/images/bullet-spine.png\" height=\"100\" align=\"right\" />\n\n```console\n./start_simulation.sh\n```\n\nNow that we have a spine is running, we can control the robot in Python. For example:\n\n```python\nimport gymnasium as gym\nimport numpy as np\nimport upkie.envs\n\nupkie.envs.register()\n\nwith gym.make(\"Upkie-Spine-Pendulum\", frequency=200.0) as env:\n observation, _ = env.reset()\n gain = np.array([10.0, 1.0, 0.0, 0.1])\n for step in range(1_000_000):\n action = gain.dot(observation).reshape((1,))\n observation, reward, terminated, truncated, _ = env.step(action)\n if terminated or truncated:\n observation, _ = env.reset()\n```\n\nOther Gymnasium environments provide various levels of absraction to control the robot. They are listed in the [Gym environments](https://upkie.github.io/upkie/gym-environments.html) page of the documentation.\n\n## Going further\n\n### Examples\n\nThere are smaller standalone examples in the [examples](https://github.com/upkie/upkie/tree/main/examples) directory. For instance:\n\n- Domain randomization: shows how to add domain-randomization wrappers to an Upkie environment.\n- Lying genuflection: genuflect while lying on a horizontal floor.\n- Model predictive control: a self-contained MPC balancer\n- PD balancer: balance by proportional-derivative feedback to wheel velocities.\n\nSome examples have optional dependencies, like those for the Genesis and PyBullet simulators. You can activate a virtual environment and install them as optional dependencies, or use Pixi:\n\n```console\npixi run --environment genesis ./examples/genesis_balancing.py\n```\n\n### Tasks\n\nUpkies come with a set of default behaviors that you can executed as Pixi tasks. To get started, make sure you have [installed `pixi`](https://pixi.sh/latest/#installation).\n\n| Name | Task |\n|------------------------|----------------------------------------------------------|\n| `rlb3-enjoy-genesis` | Evaluate the last policy trained in Genesis |\n| `rlb3-enjoy-pybullet` | Evaluate the last policy trained in PyBullet |\n| `rlb3-train-genesis` | Train a new policy by reinforcement learning in Genesis |\n| `rlb3-train-pybullet` | Train a new policy by reinforcement learning in PyBullet |\n| `try-genesis` | Run a balancing example in Genesis |\n| `try-pybullet` | Run a balancing example in PyBullet |\n| `upkie-mpc-balancer` | Run the MPC balancer |\n\nYou can execute a task by `pixi run <task-name>`, for instance:\n\n```console\npixi run upkie-mpc-balancer\n```\n\nTasks are available both on your machine and on your Upkie's Raspberry Pi (Pixi comes pre-installed on the SD card image). They are implemented by [agents](https://github.com/upkie/upkie/tree/main/agents). You can make your own agents by forking this repository or using the [new\\_agent](https://github.com/upkie/new_agent) template to get started.\n\n### Contributing\n\nContributions are welcome to both the hardware and software of Upkies! Check out the [contribution guidelines](CONTRIBUTING.md).\n\n## Citation\n\nIf you built an Upkie or use parts of this project in your works, please cite the project and its contributors:\n\n```bibtex\n@software{upkie,\n title = {{Upkie open source wheeled biped robot}},\n author = {Caron, St\\'{e}phane and Perrin-Gilbert, Nicolas and Ledoux, Viviane and G\\\"{o}kbakan, \\\"{U}mit Bora and Raverdy, Pierre-Guillaume and Raffin, Antonin and Tordjman--Levavasseur, Valentin},\n url = {https://github.com/upkie/upkie},\n license = {Apache-2.0},\n version = {9.0.0},\n year = {2025}\n}\n```\n\nDon't forget to add yourself to the BibTeX above and to `CITATION.cff` if you contribute to the project.\n\n## See also\n\n- [Awesome Open Source Robots](https://github.com/stephane-caron/awesome-open-source-robots): Upkies are one among many open-source open-hardware robot initiative: check out the others!\n- [Open Dynamic Robot Initiative](https://open-dynamic-robot-initiative.github.io/): An open torque-controlled modular robot architecture for legged locomotion research.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python module to control Upkie wheeled bipeds.",
"version": "9.0.0",
"project_urls": {
"Changelog": "https://github.com/upkie/upkie/blob/main/CHANGELOG.md",
"Documentation": "https://upkie.github.io/upkie/",
"Homepage": "https://hackaday.io/project/185729-upkie-wheeled-biped-robots",
"Source": "https://github.com/upkie/upkie",
"Tracker": "https://github.com/upkie/upkie/issues"
},
"split_keywords": [
"wheeled",
" biped",
" robot",
" balance",
" motion",
" control",
" robotics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9d6c7af62790f06d449ec0c5e76da0382a6644be676b7b60c105ebe08f8e281",
"md5": "1cb2c37d0a822ca19f0d95e89a9fe7dd",
"sha256": "7a60d4a9d3b29884b9381f9ebf7a55188afe81428236ceae47de00acaa57877f"
},
"downloads": -1,
"filename": "upkie-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cb2c37d0a822ca19f0d95e89a9fe7dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 68415,
"upload_time": "2025-08-13T22:38:20",
"upload_time_iso_8601": "2025-08-13T22:38:20.615582Z",
"url": "https://files.pythonhosted.org/packages/b9/d6/c7af62790f06d449ec0c5e76da0382a6644be676b7b60c105ebe08f8e281/upkie-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4cd171f24147dbb40f07785a6d21f6b81b944d1ae684b4754b769a797cec82c9",
"md5": "dec165d0d3b44181ba140a29146ebd83",
"sha256": "1893ad2dda6e0fb6bc89813e6a250d749239b625552eefa4c97e1533f4f8e176"
},
"downloads": -1,
"filename": "upkie-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dec165d0d3b44181ba140a29146ebd83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 835957,
"upload_time": "2025-08-13T22:38:24",
"upload_time_iso_8601": "2025-08-13T22:38:24.314245Z",
"url": "https://files.pythonhosted.org/packages/4c/d1/71f24147dbb40f07785a6d21f6b81b944d1ae684b4754b769a797cec82c9/upkie-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 22:38:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "upkie",
"github_project": "upkie",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "upkie"
}
JSON
