Python Basics for the Reachy Mini

Before you begin

This page assumes you have never used a Reachy Mini, a terminal, or Python. Start here even if some of it is familiar.

What you need

• Your Reachy Mini, already assembled and connected to your Wi-Fi. Pollen Robotics, the company that makes the robot, has a setup guide for this, and your mentor helps you with it in your first session.
• Your own computer (Windows or Mac) connected to the same Wi-Fi as the robot.
• Your robot's network name and password. You get these from the Reachy Mini app when you set up the robot, or from your mentor. Write them down and keep them somewhere safe.

Meet your robot

The Reachy Mini has a head that can move up and down, tilt side to side, and turn left and right; two antennas on top of the head; and a body that can turn. Inside are a camera, microphones, a speaker, and a small computer that runs everything. Your programs run on that small computer.

Words you will see on this page

Terminal

A window where you give a computer instructions by typing them. On Windows it is called PowerShell.

Command

One instruction you type into the terminal and send by pressing Enter.

Prompt

The text at the start of the line in the terminal, followed by a blinking cursor. It tells you which computer is listening and that it is ready for your next command.

Session

A live connection from your computer to the robot's computer. While it is open, the commands you type run on the robot.

SSH

The program that opens a session. It stands for Secure Shell.

Network name

The name your computer uses to find the robot on your Wi-Fi, such as reachy-mini.local.

Python

A programming language. The robot already has it installed, and its software is written in it.

Program (or script)

A file of Python instructions that the robot carries out from top to bottom.

File block

A block you paste into the terminal that creates a program file on the robot in one step. Section 02 explains it.

Package

Code someone else wrote that your program can borrow. Pollen's package for the robot is called reachy_mini.

Start a session with your robot

A session connects your computer to the robot's computer so the commands you type run on the robot. You start one at the beginning of each work period, and everything else on this page happens inside it.

1. Turn the robot on and wait for it to finish starting up, about two to three minutes. Partway through, every Reachy Mini plays a cuckoo sound, which means it is starting up normally. It can be ready a few seconds after the cuckoo, or it can take up to a minute. To check, say hello to the robot. When it answers, you can connect.
2. Check your Wi-Fi. Click the Wi-Fi symbol on your computer and make sure it is connected to the same network the robot was set up on.
3. Open a terminal.
   Windows Mac
   Press the Windows key, type PowerShell, and press Enter. A window opens with a line of text and a blinking cursor. That line is the prompt, and on Windows it looks like PS C:\Users\yourname>.
4. Practice once before connecting. If you have never used a terminal, type hostname and press Enter. The terminal answers with your own computer's name and shows the prompt again. Every command works this way: type it, press Enter, and read the answer. The commands on this page are safe to run. If you are unsure about any other command, ask your mentor before you press Enter.
5. Type the connection command exactly as shown below, using your robot's network name, and press Enter.
6. The first time only, the terminal asks Are you sure you want to continue connecting (yes/no)? Type yes and press Enter. This tells your computer to trust the robot from now on.
7. Type the robot's password and press Enter. The screen stays blank while you type a password, with no dots or stars. That is normal.
8. Check that you are in. A few lines of welcome text appear, starting with Linux reachy-mini. Then the prompt changes to show the robot's account and name: pollen@reachy-mini:~ $. From now on, every command you type runs on the robot. To leave, type exit and press Enter.

The connection command

ssh pollen@reachy-mini.local

What a robot's network name looks like

Every device on your Wi-Fi has a name that other devices use to find it. A new robot's name looks like reachy-mini.local. If someone renames the robot, the first part changes but the ending stays the same, for example rose.local. The .local ending means "a device on this network," so the name only works when your computer and the robot share the same Wi-Fi.

If it does not work

Run a program

With your session open, you write the program in a file on the robot and tell Python to run it.

1. Pause the conversation app so your program can move the head without competing with it. The robot goes quiet and stops listening until you restart it in the last step.

   curl -s -X POST http://localhost:8000/api/apps/stop-current-app

2. Create the program file. Each example on this page comes as one block. Click its Copy button, click inside the terminal, paste with Ctrl + V, and press Enter. That one paste creates the file on the robot with the program inside it. "How the file block works" below explains each line.
3. Check the file before you run it. Type cat head_tilt.py and press Enter. cat prints the file to the screen, so you can see whether everything saved.
4. Run the program and watch the robot. Type the command below and press Enter.

   /venvs/apps_venv/bin/python head_tilt.py

   If you see ModuleNotFoundError: No module named 'reachy_mini', you started the program with python3. Run it again with the full path above.
5. Start the conversation app again when you are finished, so the robot talks and listens as usual. It comes back within a few seconds.

   curl -s -X POST http://localhost:8000/api/apps/start-app/reachy_mini_conversation_app

   If it worked, the robot answers with a line of text that includes "state":"starting" and "error":null. The prompt appears at the end of that same line, which is normal. Wait a few seconds, and the robot is ready to talk.
6. End the session by typing exit.

If a command does not work

How the file block works

Every example starts with a line that names the file and ends with a line that says EOF. Everything between those two lines goes into the file. This kind of block is called a here-document.

cat > head_tilt.py << 'EOF'
from reachy_mini import ReachyMini
...the rest of the program...
EOF

• To change a program, edit the code in the block and paste the whole block again. The new file replaces the old one.
• Python reads the spaces at the start of each line to tell which lines belong together. The Copy buttons on this page copy those spaces exactly. If you copy code from somewhere else and see IndentationError: unexpected indent, extra spaces came along. Copy the block again from this page and paste it.
• Check the file after you paste it with cat and the file name, such as cat head_tilt.py.

Tested on Aiden, October 28, 2026: every program on this page was created this way.

Your first move: look up and tilt the head tested on Aiden

This program lifts the robot's head slightly and tilts it to one side over one second. It is the shortest complete program that makes a Reachy Mini move. It comes from Pollen Robotics' own documentation.

Hover over any underlined piece of code to see what it does. On a phone or tablet, tap it.

cat > head_tilt.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

with ReachyMini() as mini:
    # Look up and tilt head
    mini.goto_target(
        head=create_head_pose(z=10, roll=15, degrees=True, mm=True),
        duration=1.0
    )
EOF

Then run it:

/venvs/apps_venv/bin/python head_tilt.py

What you should see

Try it

Change roll=15 to roll=-15 and run it again. Predict which way the head will tilt before you run it.

Python you need tested on Aiden

Four ideas show up in almost every robot program: variables, loops, functions, and imports. Each one is shown here with the robot. Run each example the same way you ran your first move: copy the block, paste it into the terminal, and run the program with the command under it.

Variables: give a number a name

A variable is a name that holds a value. Here the tilt amount gets the name tilt, so you can change it in one place.

cat > tilt_variable.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

tilt = 20

with ReachyMini() as mini:
    mini.goto_target(head=create_head_pose(roll=tilt, degrees=True), duration=1.0)
EOF

Then run it:

/venvs/apps_venv/bin/python tilt_variable.py

Try it: change tilt = 20 to tilt = 5. Predict the difference before you run it.

Loops: repeat a move

A loop runs the same lines more than once. This program levels the head, then nods three times. Change the 3 to nod as many times as you like.

cat > nod_loop.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

with ReachyMini() as mini:
    # Start from a level head, facing straight ahead
    mini.goto_target(head=create_head_pose(), duration=1.0)

    # Nod three times
    for i in range(3):
        mini.goto_target(head=create_head_pose(pitch=15, degrees=True), duration=0.5)
        mini.goto_target(head=create_head_pose(pitch=0, degrees=True), duration=0.5)
EOF

Then run it:

/venvs/apps_venv/bin/python nod_loop.py

Start from a known position. The robot begins each program wherever the last one left its head. Without the first move, a nod that starts from a tilted head comes out at an angle, which looks like a bug. Begin every movement program by leveling the head.

Tested on Aiden, October 28, 2026: three separate nods, each one finishing before the next began.

Functions: give a move a name

A function packages several lines under one name, so you can use them again with one line.

cat > nod_function.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

def nod(mini, times):
    for i in range(times):
        mini.goto_target(head=create_head_pose(pitch=15, degrees=True), duration=0.5)
        mini.goto_target(head=create_head_pose(pitch=0, degrees=True), duration=0.5)

with ReachyMini() as mini:
    mini.goto_target(head=create_head_pose(), duration=1.0)
    nod(mini, 2)
EOF

Then run it:

/venvs/apps_venv/bin/python nod_function.py

Tested on Aiden, October 28, 2026: leveled the head, then nodded twice.

Imports: borrow code someone else wrote

An import brings in code from a package so you can use it. You have already used two from Pollen's reachy_mini package. Here is a third, NumPy, a package for working with numbers that the antenna examples in section 05 use.

cat > numpy_check.py << 'EOF'
import numpy as np
print(np.deg2rad(45))
EOF

Then run it:

/venvs/apps_venv/bin/python numpy_check.py

This one prints a number and does not move the robot, so it is a safe way to check that NumPy is available. You should see 0.7853981633974483, which is 45 degrees written in radians.

Making it move tested on Aiden

Every move uses goto_target, which slides the robot smoothly from where it is to where you tell it. It can move three things: the head, the antennas, and the body.

The head: four numbers to start with

create_head_pose takes these four numbers. One raises the head and three turn it. You can leave out any number you are not using, and it stays at zero.

The head can also slide forward and back (x) and side to side (y), but on a Reachy Mini those slides are small and hard to see, so this page leaves them out.

The robot's limits

Pollen Robotics built limits into the robot so it cannot bump into itself. If you ask for more than a limit allows, the robot moves as far as it safely can and stops there.

Antennas and body together

This example is based on one in Pollen Robotics' documentation, with a level start and a return to center added. In one two-second move, the head rises slightly, the body turns 30 degrees toward the robot's own left, and both antennas lean toward the robot's own left. Then everything comes back to center.

cat > full_move.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose
import numpy as np

with ReachyMini() as mini:
    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([0, 0]), body_yaw=0, duration=1.0)

    mini.goto_target(
        head=create_head_pose(z=10, mm=True),
        antennas=np.deg2rad([45, 45]),
        body_yaw=np.deg2rad(30),
        duration=2.0,
        method="minjerk"
    )

    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([0, 0]), body_yaw=0, duration=2.0)
EOF

Then run it:

/venvs/apps_venv/bin/python full_move.py

What you may notice: while the body turns to its left, the head shifts slightly to the robot's right, so from the front it can look like the robot is turning to face you. Watch the move once from the front and once from the side.

Tested on Aiden, October 28, 2026.

Antennas: lean together or spread apart

At rest, both antennas stand straight up and parallel. The two numbers in the list control them separately. When both numbers have the same sign, the antennas lean the same way. When the signs differ, they move in opposite directions: [-45, 45] spreads them into a wide V, and [45, -45] crosses them into an X.

cat > antennas_spread.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose
import numpy as np
import time

with ReachyMini() as mini:
    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([0, 0]), body_yaw=0, duration=1.0)

    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([-45, 45]), duration=2.0)
    time.sleep(2)
    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([0, 0]), duration=2.0)
EOF

Then run it:

/venvs/apps_venv/bin/python antennas_spread.py

Give every move the head position. A move that sets only the antennas can leave the head slightly off center. Including head=create_head_pose() in each move keeps the head where you expect it.

Tested on Aiden, October 28, 2026: the antennas spread into a wide V, held, and returned upright.

Reset everything

Paste this block once to create reset_all.py, then run it whenever the robot ends up in an odd position. It levels the head, stands the antennas up, and turns the body to face forward.

cat > reset_all.py << 'EOF'
from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose
import numpy as np

with ReachyMini() as mini:
    mini.goto_target(head=create_head_pose(), antennas=np.deg2rad([0, 0]), body_yaw=0, duration=2.0)
EOF

Then run it:

/venvs/apps_venv/bin/python reset_all.py

Tested on Aiden, October 28, 2026.

Watch the units: the head uses degrees=True and mm=True, while antennas and body need radians from np.deg2rad. Mixing them up is a common reason a move comes out far smaller or larger than expected.

Check and recover

When something goes wrong, start with the first fix and move down the list when a fix does not help.

Stop a program that is still running

Click inside the terminal window, then press Ctrl + C. The program stops right away, even in the middle of a move, and the head stays wherever it stopped. Run reset_all.py from section 05 to bring it back to center.

Tested on Aiden, October 28, 2026: stopped partway through a nod, with the head held halfway down.

See what the robot is running

curl -s http://localhost:8000/api/apps/current-app-status | python3 -m json.tool

Shows the app that is running, in a readable layout. If no app is running, it prints null. Tested on Aiden, October 28, 2026.

The recovery ladder

1. Start the conversation app. Use this when the robot is awake and silent.

   curl -s -X POST http://localhost:8000/api/apps/start-app/reachy_mini_conversation_app

2. Restart the robot's main software. Use this when the motors or sound act strangely. Afterward, run step 1 to bring the conversation app back.

   sudo systemctl restart reachy-mini-daemon

3. Restart the whole robot. Your session closes, which is expected: the terminal shows client_loop: send disconnect: Connection reset and returns to your computer's prompt. The robot plays a short sleepy sound and lowers its head, then about 20 seconds later lifts its head and plays the cuckoo. It can take another minute before it is ready to talk. Say hello; when it answers, it is ready. If it has not answered after two minutes, connect again and run step 1.

   sudo reboot

   Tested on Aiden, October 28, 2026.

Before you touch or move the robot by hand

Let the motors go limp first, so the head moves freely in your hand. Support the head with your hand, because it drops as the motors let go.

curl -s -X POST http://localhost:8000/api/motors/set_mode/disabled

Before you make the motors hold again, take your hands away and let the head rest on its own. When the motors switch back on, the head snaps back up to where it was in less than a second. That is fast enough to startle you or pinch a finger.

curl -s -X POST http://localhost:8000/api/motors/set_mode/enabled

Tested on Aiden, October 28, 2026: the head went limp, then snapped back upright in under a second when the motors switched on.

Turn the robot off safely

Check the prompt first. This command must run on the robot, so the prompt should read pollen@reachy-mini:~ $.

sudo shutdown -h now

The session closes with Connection reset. The robot plays its sleepy sound, lowers its head into its body, and folds its antennas back. When it stops moving, it is safe to use the power switch. Tested on Aiden, October 28, 2026.

Coding with an AI assistant

An AI assistant such as Claude can write robot code for you in seconds. It can also be wrong in ways that look right. Your job is to direct it and check its work. This is the same habit the AI-Epistemic Resilience course teaches, applied to code.

Write the program by hand first

Do sections 03 to 05 yourself before you ask an assistant for anything. You need to be able to read code to check it.

Ask with details

Tell the assistant what robot you have, what package to use, and what you want to happen. For example:

I have a Reachy Mini robot. Using Pollen Robotics' reachy_mini Python
package, write a short program that makes the robot look left, then
right, then back to center, one second per move. Use goto_target and
create_head_pose with degrees=True. Keep every angle within the
robot's limits: head turn (yaw) up to 180 degrees, and tilt and nod
up to 40 degrees. Explain each line in plain words.

Check before you run

1. Read every line. If you cannot say what a line does, ask the assistant to explain it, or ask your mentor.
2. Check the numbers. Are the angles inside the limits in section 05? Are the units right, degrees for the head and np.deg2rad for antennas and body? Is each duration long enough to be gentle, about half a second or more?
3. Check that it only uses what you asked for. If it imports packages you have not seen or does things you did not ask for, ask why before you run it.
4. Predict what the robot will do. Say it out loud or write it down.
5. Run it and compare. Did the robot do what you predicted?

When it does not work

Copy the exact error message from the terminal and paste it back to the assistant along with your code. Then read its fix the same way you read the first version. If the same error comes back twice, stop and ask your mentor.