# Upkie wheeled biped robot
<img src="https://github.com/upkie/upkie/assets/1189580/2fc5ee4a-81b0-425c-83df-558c7147cc59" align="right" width="200" />
[](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/)
**Upkie** is a fully open source self-balancing wheeled biped robot. It has wheels for balancing and legs to negotiate uneven terrains. Upkies are designed to be buildable at home using only tools and components ordered online, like mjbots actuators. You can develop in Python or C++, on Linux or macOS, then deploy your software to the robot's Raspberry Pi.
This repository contains all the materials needed to build and animate an Upkie:
- Hardware:
- [Bill of materials](https://github.com/upkie/upkie/wiki/Bill-of-materials)
- [Build instructions](https://github.com/upkie/upkie/wiki)
- [Project log](https://hackaday.io/project/185729-upkie-wheeled-biped-robots)
- Software:
- [Installation](https://github.com/upkie/upkie#installation)
- [Getting started](https://github.com/upkie/upkie#getting-started)
- [Documentation](https://upkie.github.io/upkie/)
- Going further:
- [Examples](https://github.com/upkie/upkie/tree/main/examples)
- [Agents](https://github.com/upkie/upkie#agents)
Questions are welcome in the [Chat](https://app.element.io/#/room/#upkie:matrix.org) and [Discussions forum](https://github.com/upkie/upkie/discussions).
## Installation
### From conda-forge
```console
conda install -c conda-forge upkie
```
### From PyPI
```console
pip install upkie
```
## Getting started
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
```
Click on the robot in the simulator window to apply external forces. Once the simulation spine is running, we can control the robot using one of its Gymnasium environments, for instance:
```python
import gymnasium as gym
import numpy as np
import upkie.envs
upkie.envs.register()
with gym.make("UpkieGroundVelocity-v3", 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()
```
The Python code is the same whether we run in simulation or on a real Upkie. Head over to the [examples](https://github.com/upkie/upkie/tree/main/examples) directory for more use cases.
## Gymnasium environments
Upkie has environments compatible with the [Gymnasium API](https://gymnasium.farama.org/), for instance:
- `UpkieGroundVelocity`: keep legs straight and balance with the wheels.
- `UpkieServos`: control joint servos directly (position, velocity, torque)
- `UpkieServoPositions`: control joint positions.
- `UpkieServoTorques`: control joint torques.
Check out the full [list of environments](https://upkie.github.io/upkie/environments.html) for details.
## Agents
Larger Upkie agents have their own repositories:
- [MPC balancer](https://github.com/upkie/mpc_balancer): balance in place using model predictive control.
- [Pink balancer](https://github.com/upkie/pink_balancer): a more advanced agent that can crouch and stand up while balancing.
- [PPO balancer](https://github.com/upkie/ppo_balancer): balance in place with a policy trained by reinforcement learning.
- [PID balancer](https://github.com/upkie/pid_balancer): legacy agent used to test new Upkies with minimal dependencies.
Head over to the [new\_agent](https://github.com/upkie/new_agent) template to create your own, and feel free to open a PR here to add your agent to the list.
## How can I participate?
Contributions are welcome to both the hardware and software of Upkies! If you are a developer/maker with some robotics experience looking to hack on open source, check out the [contribution guidelines](CONTRIBUTING.md). On the software side, you can also report any bug you encounter in the [issue tracker](https://github.com/upkie/upkie/issues).
## 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, \"{Umit} Bora and Raverdy, Pierre-Guillaume and Raffin, Antonin and Tordjman--Levavasseur, Valentin},
url = {https://github.com/upkie/upkie},
license = {Apache-2.0},
version = {6.1.0},
year = {2024}
}
```
## 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.8",
"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/09/2f/cc233055a21d1d8dfd21a46d40b0f3f50031482a820d8d4c011e5e34ec9d/upkie-6.1.0.tar.gz",
"platform": null,
"description": "# Upkie wheeled biped robot\n\n<img src=\"https://github.com/upkie/upkie/assets/1189580/2fc5ee4a-81b0-425c-83df-558c7147cc59\" align=\"right\" width=\"200\" />\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**Upkie** is a fully open source self-balancing wheeled biped robot. It has wheels for balancing and legs to negotiate uneven terrains. Upkies are designed to be buildable at home using only tools and components ordered online, like mjbots actuators. You can develop in Python or C++, on Linux or macOS, then deploy your software to the robot's Raspberry Pi.\n\nThis repository contains all the materials needed to build and animate an Upkie:\n\n- Hardware:\n - [Bill of materials](https://github.com/upkie/upkie/wiki/Bill-of-materials)\n - [Build instructions](https://github.com/upkie/upkie/wiki)\n - [Project log](https://hackaday.io/project/185729-upkie-wheeled-biped-robots)\n- Software:\n - [Installation](https://github.com/upkie/upkie#installation)\n - [Getting started](https://github.com/upkie/upkie#getting-started)\n - [Documentation](https://upkie.github.io/upkie/)\n- Going further:\n - [Examples](https://github.com/upkie/upkie/tree/main/examples)\n - [Agents](https://github.com/upkie/upkie#agents)\n\nQuestions are welcome in the [Chat](https://app.element.io/#/room/#upkie:matrix.org) and [Discussions forum](https://github.com/upkie/upkie/discussions).\n\n## Installation\n\n### From conda-forge\n\n```console\nconda install -c conda-forge upkie\n```\n\n### From PyPI\n\n```console\npip install upkie\n```\n\n## Getting started\n\nLet'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\nClick on the robot in the simulator window to apply external forces. Once the simulation spine is running, we can control the robot using one of its Gymnasium environments, for instance:\n\n```python\nimport gymnasium as gym\nimport numpy as np\nimport upkie.envs\n\nupkie.envs.register()\n\nwith gym.make(\"UpkieGroundVelocity-v3\", 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\nThe Python code is the same whether we run in simulation or on a real Upkie. Head over to the [examples](https://github.com/upkie/upkie/tree/main/examples) directory for more use cases.\n\n## Gymnasium environments\n\nUpkie has environments compatible with the [Gymnasium API](https://gymnasium.farama.org/), for instance:\n\n- `UpkieGroundVelocity`: keep legs straight and balance with the wheels.\n- `UpkieServos`: control joint servos directly (position, velocity, torque)\n - `UpkieServoPositions`: control joint positions.\n - `UpkieServoTorques`: control joint torques.\n\nCheck out the full [list of environments](https://upkie.github.io/upkie/environments.html) for details.\n\n## Agents\n\nLarger Upkie agents have their own repositories:\n\n- [MPC balancer](https://github.com/upkie/mpc_balancer): balance in place using model predictive control.\n- [Pink balancer](https://github.com/upkie/pink_balancer): a more advanced agent that can crouch and stand up while balancing.\n- [PPO balancer](https://github.com/upkie/ppo_balancer): balance in place with a policy trained by reinforcement learning.\n- [PID balancer](https://github.com/upkie/pid_balancer): legacy agent used to test new Upkies with minimal dependencies.\n\nHead over to the [new\\_agent](https://github.com/upkie/new_agent) template to create your own, and feel free to open a PR here to add your agent to the list.\n\n## How can I participate?\n\nContributions are welcome to both the hardware and software of Upkies! If you are a developer/maker with some robotics experience looking to hack on open source, check out the [contribution guidelines](CONTRIBUTING.md). On the software side, you can also report any bug you encounter in the [issue tracker](https://github.com/upkie/upkie/issues).\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, \\\"{Umit} 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 = {6.1.0},\n year = {2024}\n}\n```\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": "6.1.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": "b9cf2718ff6cdb0e9caf66c0f3ca208880fc46a8c2c400b5b128af418559af90",
"md5": "fd9a33356844db08ab996f9c7c834024",
"sha256": "c840256e736ad499e3aa2fe27f43cce2ea75fc7b89430dfe43edc96df63af622"
},
"downloads": -1,
"filename": "upkie-6.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd9a33356844db08ab996f9c7c834024",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 52293,
"upload_time": "2024-12-12T23:32:08",
"upload_time_iso_8601": "2024-12-12T23:32:08.207214Z",
"url": "https://files.pythonhosted.org/packages/b9/cf/2718ff6cdb0e9caf66c0f3ca208880fc46a8c2c400b5b128af418559af90/upkie-6.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "092fcc233055a21d1d8dfd21a46d40b0f3f50031482a820d8d4c011e5e34ec9d",
"md5": "dcd9b75adfd960a5718a5309d90d89e0",
"sha256": "1d96c9258237a8c22ead4bf031036029ecbbb9e7d75b1ec0ac54c5cdf4a5eacd"
},
"downloads": -1,
"filename": "upkie-6.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dcd9b75adfd960a5718a5309d90d89e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 532771,
"upload_time": "2024-12-12T23:32:10",
"upload_time_iso_8601": "2024-12-12T23:32:10.836799Z",
"url": "https://files.pythonhosted.org/packages/09/2f/cc233055a21d1d8dfd21a46d40b0f3f50031482a820d8d4c011e5e34ec9d/upkie-6.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 23:32:10",
"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
