upkie 5.2.0

Python module to control Upkie wheeled bipeds.

Upkie wheeled biped robot

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
  • Build instructions
  • Project log
• Software:
  • Installation
  • Getting started
  • Documentation
• Going further:
  • More agents
  • More examples

Questions are welcome in the Chat and Discussions forum.

Installation

From conda-forge

conda install -c conda-forge upkie

From PyPI

pip install upkie

Getting started

First, let's start a Bullet simulation spine:

./start_simulation.sh

Click on the robot in the simulator window to apply external forces. Once the simulation spine is running, we can interact with it using one of the Gymnasium environments. For example, here is a linear-feedback balancer for UpkieGroundVelocity:

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 running a simulation or real-robot spine. Head over to the examples directory for more examples.

Agents

This repository only distributes a PID balancer used for testing. Actual Upkie agents are distributed in their own repositories:

• MPC balancer: balance in place using model predictive control.
• Pink balancer: a more advanced agent that can crouch and stand up while balancing.
• PPO balancer: balance in place with a policy trained by reinforcement learning.

Head over to the new_agent template to create your own, and feel free to open a PR here to add your agents to the list above.

Citation

If you built an Upkie or use parts of this project in your works, please cite the project and its contributors:

@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 = {5.2.0},
  year = {2024}
}