Spines

Upkie's code is organized into spines, which communicate with the simulation or mjbots actuators, and agents, the programs that implement robot behaviors. We use Bazel to build spines, both for simulation on your development computer or for running on the robot's Raspberry Pi. Bazel does not install anything on your system: it fetches dependencies with specific versions and builds them locally, making sure the code stays consistent over time. Check out this introduction for more details.

Bullet spine

The Bullet spine runs an agent in the Bullet 3 simulator. We can start this spine as a standalone process and let it run waiting for agents to connect:

./start_simulation.sh

This script is just an alias for a Bazel run command:

./tools/bazelisk run //spines:bullet_spine -- --show

Check out simulation options (fly like an eagle!) with the help flag -h.

pi3hat spine

The pi3hat spine is the one that runs on the real robot, where a pi3hat r4.5 is mounted on top of the onboard Raspberry Pi computer. To run this spine, we can either: download it from GitHub, or build it locally from source.

Download the latest release

To get the latest pi3hat spine from GitHub, download the latest pi3hat_spine binary from Continuous Integration build artifacts, then scp it to the robot. TODO: make this more user-friendly ;)

$ scp pi3hat_spine foo@robot
$ ssh foo@robot
foo@robot:~$ ./pi3hat_spine

Once the spine is running, you can run any agent in a separate shell on the robot, for example the wheel balancer:

foo@robot:upkie$ make run_pid_balancer

Build from source

To build the pi3hat locally from source, then upload it to Raspberry Pi, use the Makefile at the root of the repository:

make build
make upload UPKIE_NAME=your_upkie

Next, log into the Pi and run a pi3hat spine:

$ ssh foo@robot
foo@robot:~$ cd upkie
foo@robot:upkie$ make run_pi3hat_spine

Once the spine is running, you can run any agent in a separate shell on the robot, for example the wheel balancer:

foo@robot:upkie$ make run_pid_balancer

Mock spine

The mock spine is useful to run an agent on the robot without firing up the actuators. It works exactly as the pi3hat spine, replacing "pi3hat" with "mock" in all instructions above.