upkie

Open-source wheeled biped robots

Science Score: 54.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
✓
Committers with academic emails
3 of 12 committers (25.0%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.7%) to scientific vocabulary

Keywords

legged-robotics legged-robots locomotion model-predictive-control pid-control python reinforcement-learning robotics simulation wheeled-biped

Keywords from Contributors

neutronics mesh interpretability simulations hydrology benchmarking gym-environment sequences projection interactive

Last synced: 6 months ago · JSON representation ·

Repository

Open-source wheeled biped robots

Basic Info

Host: GitHub
Owner: upkie
License: apache-2.0
Language: C++
Default Branch: main
Homepage:
Size: 5.62 MB

Statistics

Stars: 278
Watchers: 9
Forks: 39
Open Issues: 4
Releases: 0

Topics

legged-robotics legged-robots locomotion model-predictive-control pid-control python reinforcement-learning robotics simulation wheeled-biped

Created almost 4 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog Contributing License Citation

Upkie wheeled biped robots

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.

This repository contains all the materials needed to build and control an Upkie. Questions are welcome in the discussions forum or in the chat room.

Building your own Upkie

Step by step instructions to build a new Upkie from scratch are available in the 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:

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(1000000): 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 page of the documentation.

Going further

Examples

There are smaller standalone examples in the 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.

| 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. You can make your own agents by forking this repository or using the new_agent template to get started.

Contributing

Contributions are welcome to both the hardware and software of Upkies! Check out the contribution guidelines.

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.

cff-version: 1.2.0
message: "If you find this code helpful, please cite it as below."
title: "Upkie open source wheeled biped robot"
version: 9.0.0
date-released: 2025-08-14
url: "https://github.com/upkie/upkie"
license: "Apache-2.0"
authors:
- family-names: "Caron"
  given-names: "Stéphane"
  orcid: "https://orcid.org/0000-0003-2906-692X"
- family-names: "Perrin-Gilbert"
  given-names: "Nicolas"
  orcid: "https://orcid.org/0000-0001-8626-1938"
- family-names: "Ledoux"
  given-names: "Viviane"
- family-names: "Gökbakan"
  given-names: "Umit Bora"
- family-names: "Raverdy"
  given-names: "Pierre-Guillaume"
  orcid: "https://orcid.org/0000-0003-2239-5026"
- family-names: "Raffin"
  given-names: "Antonin"
  orcid: "https://orcid.org/0000-0001-6036-6950"
- family-names: "Tordjman--Levavasseur"
  given-names: "Valentin"

GitHub Events

Total

Create event: 32
Release event: 5
Issues event: 20
Watch event: 107
Delete event: 30
Issue comment event: 57
Push event: 353
Pull request review comment event: 31
Pull request review event: 21
Gollum event: 8
Pull request event: 57
Fork event: 11

Last Year

Create event: 32
Release event: 5
Issues event: 20
Watch event: 107
Delete event: 30
Issue comment event: 57
Push event: 353
Pull request review comment event: 31
Pull request review event: 21
Gollum event: 8
Pull request event: 57
Fork event: 11

Committers

Last synced: 9 months ago

All Time

Total Commits: 2,788
Total Committers: 12
Avg Commits per committer: 232.333
Development Distribution Score (DDS): 0.089

Past Year

Commits: 1,022
Committers: 6
Avg Commits per committer: 170.333
Development Distribution Score (DDS): 0.126

Top Committers

Name	Email	Commits
Stéphane Caron	s**n@n**g	2,541
Tordjx	v**r@e**r	103
pgraverdy	p**y@g**m	45
boragokbakan	b**n@g**m	38
perrin-isir	n**n@s**r	24
dependabot[bot]	4****]	18
Valentin Tordjman--Levavasseur	v**a@p**r	11
Viviane Ledoux	v**x@i**r	3
Antonin RAFFIN	a**n@e**g	2
shaoanlu	s**u@g**m	1
=	=	1
Stéphane Caron	s**e@s**o	1

Committer Domains (Top 20 + Academic)

scaron.info: 1 ensta.org: 1 inria.fr: 1 ptb-02009426.paris.inria.fr: 1 sorbonne-universite.fr: 1 ensae.fr: 1 normalesup.org: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 28
Total pull requests: 80
Average time to close issues: 4 months
Average time to close pull requests: 4 days
Total issue authors: 8
Total pull request authors: 7
Average comments per issue: 1.46
Average comments per pull request: 1.14
Merged pull requests: 73
Bot issues: 0
Bot pull requests: 2

Past Year

Issues: 9
Pull requests: 37
Average time to close issues: 3 days
Average time to close pull requests: 4 days
Issue authors: 5
Pull request authors: 3
Average comments per issue: 1.0
Average comments per pull request: 1.11
Merged pull requests: 31
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

stephane-caron (28)
ubgk (2)
itazap (2)
mariogpascual (2)
perrin-isir (2)
pgraverdy (2)
one-for-all (1)
FEIPNG (1)
Wyzard1004 (1)
Wyzard2025 (1)

Pull Request Authors

stephane-caron (153)
ubgk (8)
Tordjx (8)
dependabot[bot] (7)
pgraverdy (3)
shaoanlu (2)
marlinlm (1)
araffin (1)
perrin-isir (1)
vivianeledoux (1)

Top Labels

Issue Labels

bug (16) enhancement (15)

Pull Request Labels

dependencies (7) no changelog (5)

Packages

Total packages: 1
Total downloads:
- pypi 285 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 30
Total maintainers: 1

pypi.org: upkie

Python module to control Upkie wheeled bipeds.

Homepage: https://hackaday.io/project/185729-upkie-wheeled-biped-robots
Documentation: https://upkie.github.io/upkie/
License: Apache Software License
Latest release: 9.0.0
published 6 months ago

Versions: 30
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 285 Last month

Rankings

Dependent packages count: 7.2%

Downloads: 17.2%

Average: 22.0%

Dependent repos count: 41.5%

Maintainers (1)

stephane-caron

Last synced: 6 months ago

upkie

Science Score: 54.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Upkie wheeled biped robots

Building your own Upkie

Getting started

Creating your own behaviors

Going further

Examples

Tasks

Contributing

Citation

See also

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: upkie

Rankings

Maintainers (1)