upkie 0.5.0

Python module to control Upkie wheeled bipeds.

Upkie wheeled biped

Main repository to build and control Upkie wheeled bipeds. Made for Linux 🐧

Questions about using the code, contributing, or balancing robots in general are welcome in the Discussions forum or on the Chat.

Quick test

Run a simulated Upkie right away from the command line, no installation required:

$ git clone https://github.com/tasts-robots/upkie.git
$ cd upkie
$ ./start_test_balancer.sh

Connect a USB controller to move the robot around 🎮

Example

import gym
import loop_rate_limiters
import upkie.envs

upkie.envs.register()

with gym.make("UpkieWheelsEnv-v2") as env:
    observation = env.reset()
    action = 0.0 * env.action_space.sample()
    rate = loop_rate_limiters.RateLimiter(frequency=200.0)
    for step in range(1_000_000):
        observation, reward, done, _ = env.step(action)
        if done:
            observation = env.reset()
        pitch = observation[0]
        action[0] = 10.0 * pitch
        rate.sleep()

Installation

PyPI

$ pip install upkie

Code overview

This repository uses Bazel for building and testing. One benefit of this choice is that there is no dependency to install: Bazel builds everything locally in a local cache. Compilation will only take a while the first time.

Locomotion code is organized into spines, which communicate with the simulator or actuators using Vulp, and agents, the main programs that implement behaviors in Python. In the example above we ran the test balancer. We could also start the Bullet spine independently, and let it run waiting for agents to connect:

$ ./tools/bazelisk run -c opt //spines:bullet -- --show

The -c opt argument to Bazel makes sure we compile optimized code, while the --show argument to the spine displays the Bullet visualization.

Agents

Test balancer

A baseline agent designed to check out Upkie's physical capabilities. It balances the robot using PD feedback from the head's pitch and wheel odometry to wheel velocities, plus a feedforward non-minimum phase trick for smoother transitions from standing to rolling.

Pink balancer

A more capable agent that combines wheeled balancing with inverse kinematics computed by Pink. This is the controller that runs in the first two videos of Upkie.

PPO balancer

An agent trained by reinforcement learning to balance with straight legs. Training uses the UpkieWheelsEnv gym environment and the PPO implementation from Stable Baselines3.

Environments

UpkieServosEnv

Upkie with full observation and joint position-velocity-torque actions.

UpkieWheelsEnv

Upkie with full observation but only wheel velocity actions.

Environments are single-threaded rather than vectorized. In return, they run as-is on the real robot.

Observers

Floor contact

Detect contact between the wheels and the floor. The Pink and test balancers use contact as a reset flag for their integrators, to avoid over-spinning the wheels while the robot is in the air.

Wheel contact

Detect contact between a given wheel and the floor.

Wheel odometry

Measure the relative motion of the floating base with respect to the floor. Wheel odometry is part of their secondary task (after keeping the head straight), which is to stay around the same spot on the floor.

Spines

Bullet

Spawn Upkie in a Bullet simulation. Resetting this spine moves the robot back to its initial configuration in this world.

pi3hat

Spine is made to be called from a Raspberry Pi with an onboard mjbots pi3hat. Servos are stopped when the spine is stopped, and switch to position mode (which is a position-velocity-torque controller) when the spine idles. Check out the spine state machine for details.

See also

• Project page on Hackaday