5) Motion control software

The prerequisites for this stage are:

• Local copy of the main upkie repository from 1) Getting started
• Electronics setup from 4) Electronics testing
• USB controller from the Bill of materials

5.1) Go to the main repository

Change directory to your local copy of the upkie repository:

$ cd upkie

In the following instructions, we will run everything from this directory.

_{Ask questions about this step in Software discussions.}

5.2) Install robot scripts

1. Copy robot scripts from this repository to the robot:

$ scp -r tools/ pi@upkie:tools

2. Log into the robot and move utility scripts somewhere in the PATH of the root administrator:

$ ssh pi@upkie
pi@upkie:~$ sudo mv tools/hard_rezero /usr/local/bin/
pi@upkie:~$ sudo mv tools/stop_servos /usr/local/bin/
pi@upkie:~$ sudo mv tools/upkie_tool /usr/local/bin/

_{Ask questions about this step in Software discussions.}

5.3) Configure servo limits

Go to the tools directory on the robot and run the servo configuration script:

pi@upkie:~$ cd tools/setup
pi@upkie:tools$ python python configure_servos.py

Check that the output lines are only OK or AOK.

_{Ask questions about this step in Software discussions.}

5.4) Build the PID balancer

In your local copy of upkie, build Raspberry Pi targets by:

$ make build

Running this for the first time requires an Internet connection.

_{Ask questions about this step in Software discussions.}

5.5) Upload and run the PID balancer

Connect to the robot's Wi-Fi network, then from the upkie directory run:

$ make upload UPKIE_NAME=your_robot_hostname

This will create a remote directory (also named upkie) on the Raspberry Pi with a copy of all the build files necessary to run the spine and balancer on the robot.

The UPKIE_NAME environment variable should contain the Raspberry Pi's hostname or IP address used in SSH commands. You can define it inline for a one-time use, as we did above, or add the following line to your shell configuration:

export UPKIE_NAME=your_robot_hostname

_{Ask questions about this step in Software discussions.}

5.6) Connect the USB controller

Make sure the USB controller is connected to the Raspberry Pi. The controller has two functions:

1. Communicate commands to the robot, for instance using the joysticks to move around.
2. Emergency stop: pressing the right button (red button 🔴 on an Xbox controller) shuts down all motors immediately.

Always keep the emergency stop around when you run a new agent on the robot, and don't hesitate to press it if the beast misbehaves 😉

_{Ask questions about this step in Software discussions.}

5.7) Start the pi3hat spine

Connect via SSH to the robot and start the pi3hat spine:

pi@upkie:~$ cd upkie
pi@upkie:upkie$ make run_pi3hat_spine

The spine is a fast program in charge of two-way communications between your agent's code (for us it will be the PID balancer here) and the robot's actuators.

_{Ask questions about this step in Software discussions.}

5.8) Run the PID balancer

Take the Raspberry Pi in your hand (only touching the sides of the board) and put it upside-down (as it will be when the assembled robot stands upright). In a separate shell on the robot, run the PID balancer:

pi@upkie:upkie$ make run_pid_balancer

Rotate the Raspberry Pi in your hands: the qdd100 servos should stay still while the two mj5208 servos turn in opposite directions.

_{Ask questions about this step in Software discussions.}

---

Next: 6) Assembly