upkie 3.4.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 go off-road or negotiate uneven terrains. Upkies are designed to be buildable at home with tools and components ordered online, like mjbots actuators. Motion control runs onboard the robot's Raspberry Pi.

This repository contains all the software and instructions required to build and animate an Upkie. Development can be done in Python or C++, on Linux or macOS. Questions are welcome in the Chat and Discussions forum.

Installation

To code for Upkie in Python, just install:

pip install upkie

This Python interface is already fast enough for real-time control. If later on you want to optimize parts of your code, you can move them to C++ spines.

Demo

You can try a demo right from your command line:

git clone https://github.com/upkie/upkie.git
cd upkie
./try_pid_balancer.sh

Click on the robot in the simulator window to apply external forces. If you have a gaming controller connected to your computer, steer its joysticks to move the robot around 🎮

Example

You can develop your own agent using the Gymnasium environments distributed in upkie.envs. For example, here is a simple proportional-feedback balancer:

import gymnasium as gym
import upkie.envs

upkie.envs.register()

with gym.make("UpkieGroundVelocity-v3", frequency=200.0) as env:
    observation, _ = env.reset()
    action = 0.0 * env.action_space.sample()
    for step in range(1_000_000):
        observation, reward, terminated, truncated, _ = env.step(action)
        if terminated or truncated:
            observation, _ = env.reset()
        pitch = observation[0]
        action[0] = 10.0 * pitch

To run this agent, you will first need to start a simulation:

./start_simulation.sh

Then execute the Python code above. To run the agent on the robot, do the same but running the pi3hat spine instead of the simulation.

Agents

The demo agent simply balances in place by PID control. There are more advanced Upkie agents distributed in their own repositories. Check out the ones you are interested in:

• MPC balancer: balance in place using model predictive control.
• Pink balancer: an extended PID balancer than can crouch and lift its legs.
• PPO balancer: balance in place with a policy trained by reinforcement learning.

Head over to the new_agent template to create your own.

To go further

• Build your own Upkie 🧰
• Examples
• Project log on Hackaday.io
• Software documentation