Kibo-RPC 7 rules guide

Part 1 · The Rulebook

1. The challenge in one minute

You write a program for Int-Ball2 (IB2), a small free-flying camera robot that JAXA operates inside Kibo, Japan's module on the International Space Station. It flies around Kibo so astronauts spend less time holding cameras. Meet Int-Ball2 and Astrobee in 3D →

• The story: the pressure inside Kibo is dropping. IB2 visits the checkpoints where a leak is suspected and reads the AR marker at each one to find the cause.
• Preliminary round: held in each country or region. Your program runs in JAXA's web simulator. Some regions add their own judging rules, so check your local Kibo-RPC page.
• Final round: the winning teams' programs run on the real Int-Ball2 inside Kibo, in orbit.

Who can take part

• Regular Course (the main competition): any student, from school all the way to university and graduate school. Teams have 3 to 8 members.
• Beginner Course (new for the 7th edition): everyone on the team is junior high school age or younger (up to about age 15) and new to programming. It has fewer checkpoints and doesn't count the robot's orientation (roll and so on), so it's easier. There are prizes, but winners don't get to run their program on the ISS.
• Teams of high school students or younger give a guardian's or teacher's details. Rules can differ a little by country, so check your local organiser's announcements.

From the 7th Kibo-RPC Guidebook, sections 3.1, 3.2 and 3.4.

2. How a game runs

• The timer starts when undocking is complete and stops at the mission completion report. If the report doesn't happen within the time limit, you get no points for it.
• Anything IB2 does after the mission finishes doesn't count.

3. What you're told, and what you aren't

• There are 6 to 12 checkpoints; harder levels have more. You choose the level when you start a web simulation: Easy, Normal, Hard or Very Hard. The documents don't say how many checkpoints each level has, and which markers get one changes from run to run.
• Each checkpoint is a sphere placed relative to its AR marker.
• A microgravity module disturbs the robot in the simulator only, so IB2 won't always be exactly where you sent it.

Places are written as three numbers (x, y, z), and orientations as quaternions. If those are new to you, look at the Coordinates and rotations page first.

How does the robot know where everything is?

Each thing it needs comes from a different place:

The Rulebook only says the checkpoint positions and attitudes are "provided automatically"; the Programming Manual explains the API calls (sections 6.3.1 and 6.3.2). The 7th Kibo-RPC uses Int-Ball2, not NASA's Astrobee, which flew in earlier editions.

Where the markers are

4. Passing a checkpoint

At each checkpoint the judge looks at three things at once. Each one gets a level from Lv1 (just inside) to Lv3 (very close).

• The lowest level counts. All three must be inside a band, and the checkpoint scores the level of the worst one.
• Hold it for 1 second with the marker in view. Wobbling out of a band during that second fails the pass.
• Your program must ask for the judgement with /event/checkpoint_passed. Just arriving doesn't count.

These are the Rulebook's own examples (section 2.3.2).

One more example, step by step: the robot is 0.15 m from the checkpoint's centre, the marker is 8° from the middle of the picture, and the roll is 25° off.

1. Position: 0.15 m is within 0.2 but more than 0.1, so Lv2.
2. Centring: 8° is within 10°, so Lv3.
3. Roll: 25° is within 30° but more than 20°, so Lv1.
4. The lowest is Lv1, so the checkpoint passes at Lv1. Fix the roll and the level goes up!

5. Scoring

• Pass the checkpoints and reach the goal first, then get faster. A quick run that misses checkpoints scores less than a careful one.
• To pass at a high level you need more than the right position: aim the camera at the middle of the marker and match the roll.
• The Rulebook doesn't list how many points each level is worth. The sandbox's estimate uses its own assumed numbers.

Example (made-up numbers, just to show the idea): your checkpoints and goal earn 50 points, and finishing quickly gives a multiplier of 1.5. Then your score = 50 × 1.5 = 75.

6. Ten runs, one average

Example (made-up numbers): team A's program scores 80 nine times, but gets stuck once and scores 0. Average = (9 × 80 + 0) ÷ 10 = 72. Team B's program scores 75 every time: average 75. Team A loses because of one mistake! So your program needs to work reliably, every time.

7. Dates and submitting

• January 20, 2027, 12:00 JSTDeadline for questions. Later questions may get a late answer.
• January 20, 2027, 23:59 JSTLast moment to submit your program.
• January 21 – February 17, 2027The preliminary round.
• LaterThe final round on the ISS. Details are announced later.

1. Before the round, the web simulator gets a "Preliminary" simulator. Run your program in it.
2. On the RESULTS screen, pick a Preliminary run whose status is FINISHED and press SUBMIT.
3. To change your mind, press CANCEL and submit another one. Both buttons stop working at the deadline.

8. The final round on the ISS

• Safety review first. JAXA checks your code so it can't harm the real robot. You send the draft source code by email, then the final program and source through the website. Corrections are needed every year and there's little time, so keep your schedule free.
• One run only. On the real IB2 it can't be stopped or re-run. A re-run happens only if IB2 has a problem in orbit that wasn't caused by your program, and there's time left.
• 5 minutes, then the program shuts down. The run also ends early if IB2 gets stuck, loses track of where it is, or stops for a long time.
• You don't press start. JAXA installs your program on IB2 and ground operators start it. The runs are recorded beforehand and shown later at an event with expert commentary.
• Run order by tier. Teams go in tiers by preliminary rank (for example 1st–4th, 5th–8th, 9th–13th). Lower tiers may not get a turn if time runs out.

9. Words to know

Part 2 · The Programming Manual

Before you start: programming words, made simple

The Programming Manual uses lots of new words. Don't worry: most of them are like everyday things.

program

Step-by-step instructions for a computer, like a recipe. Kibo-RPC programs are written in Python or C++.

Ubuntu (Linux)

An operating system, like Windows. All the Kibo-RPC tools run on it; you can also run it inside Windows (with WSL).

terminal

A window where you type commands for the computer. For example, typing mkdir krpc and pressing Enter makes a folder called krpc.

ROS

The robot software's "post office": the robot's parts (camera, motors, your program) send each other messages through it.

service

Ask a question and wait for the answer, like asking a teacher. For example, "where are this run's checkpoints?"

action

A job that takes time, like sending someone to the shop: you can check how it's going, and cancel it if you need to. For example, "go to this place".

topic

A broadcast that never stops, like the radio: anyone can listen. For example, the robot always announces where it is now.

JSON

A way of writing labelled information, like filling in a form: { "name": "CP 1", "level": 3 } means the name is CP 1 and the level is 3.

API

The list of commands the robot gives your program, like the buttons on a remote control.

log

The program's diary: it writes down what happened while it ran. Very useful for finding mistakes.

template

A ready-made program from JAXA with one part (the USER EDIT AREA) for you to write.

10. The development loop

11. Setting up

• You always need Ubuntu. Even with only the web simulator, you need it to unpack the files and build the submission package. On Windows 11, install Ubuntu in WSL2: wsl --install -d Ubuntu-24.04, then check that wsl --list --verbose shows version 2.
• Docker only for the local simulator. If you only use the web simulator, skip Docker.
• Recommended tools: Git, and VSCode with the WSL extension. On Windows, open the folder inside Ubuntu ("Connect to WSL"), not from the Windows side.
• Don't update the fixed versions of tools and libraries on your own.

These are for running the local simulator. The simulator is built on GCC 7.5.0, C++14, Python 3.6.9 and ROS 1 Melodic, so write code that works with those versions.

Download KRPC7 Simulator Resources from the download page and unpack it:

mkdir -p ~/krpc
tar -xvf krpc7th-simulator.tar.gz -C ~/krpc

12. The project folder

krpc7th-simulator/
├── build.sh, simulation.sh, replay.sh   run these, don't edit
├── docker/  rootfs/  rviz/              simulator insides, don't edit
├── users/
│   ├── packing.sh                       makes your submission .tar.gz
│   └── catkin_ws/src/
│       ├── krpc_user/                   ★ YOUR CODE GOES HERE
│       │   ├── scripts/user_template.py     Python template
│       │   └── src/user_template_node.cpp   C++ template
│       ├── krpc_api_server/             provided, don't edit
│       └── krpc_ib2_msgs/               provided, don't edit
└── share/logs/<time>/                  results of each local run
    ├── cheat_sheet.json                 the checkpoint layout of that run
    ├── simulation.bag                   recording (play it with replay.sh)
    ├── judge_module_logs/               scoring logs
    └── user_programs_logs/              your program's output

When your changes are ready, make the package you upload:

cd ~/krpc/krpc7th-simulator/users
./packing.sh YourSourceCode      # makes YourSourceCode.tar.gz

13. Web and local simulators

Web simulator

1. Log in on the Kibo-RPC website and open SIMULATION.
2. Drop in YourSourceCode.tar.gz, choose the Simulator Level and Version, add a memo, and press START SIMULATION.
3. When the status says Finished, press VIEW RESULT. SIMULATOR VIEWER replays the run (copy the password it shows).

Local simulator

cd ~/krpc/krpc7th-simulator
bash ./build.sh          # once; add --arm64 to build for ARM like the real robot
bash ./simulation.sh     # one run; watch it at http://localhost, stop with Ctrl+C

14. Reading your results

• Final Score, Mission Time, Time Bonus, CheckPoints Passed, Goal Reached at the top.
• CheckPoint Detail lists each checkpoint as PASSED or FAIL with its level, the lowest of the three conditions. A failed checkpoint shows "-" for its level; N/A means that checkpoint wasn't judged.
• DOWNLOAD LOG FILES gives two files: the result JSON and your program's own log (what you printed with rospy.loginfo). System and sensor logs aren't provided; record what you need with rosbag on the local simulator.

{ "Illegal": false,                      // was the run treated as a violation?
  "JudgeReport": {
    "mission": { "started": true, "finished": true, "duration_sec": 295.33 },
    "checkpoint_detail": [
      { "checkpoint_id": 2, "success": true, "level": 3, "reason": "checkpoint validated" } ],
    "goal": { "success": true, "reason": "goal checkpoint previously passed" },
    "events": [ { "status": "Mission Start" }, { "status": "Mission Finish" } ] } }

Shortened from the example in the Programming Manual (timestamps removed).

15. How the template program runs

def __run_user_flow(self, msg):
    try:
        if not self.__notify_mission_start():
            return
        # USER EDIT AREA: define route planning and game-specific flow here.
        # ***********************************************
        checkpoint_target = self.__resolve_first_checkpoint_target()
        if not self.__move_to_checkpoint(checkpoint_target):
            return
        if not self.__notify_checkpoint_passed(checkpoint_target['checkpoint_id']):
            return
        # ***********************************************
        if not rospy.is_shutdown():
            self.__notify_mission_finished()
    except Exception as exc:
        rospy.logerr('user flow failed: %s', exc)

• The sample only visits the first checkpoint. Your job is to visit them all, in a good order, and finish at the goal.
• If getting the checkpoints fails, the template falls back to a target at the origin so it can still run end to end. That earns nothing; replace it with a retry or a clean stop.
• /mission/get_checkpoints returns JSON in its message. Each checkpoint has its checkpoint_id, position, marker_pose, score_bands and an attitude with its quaternion, centering_bands and roll_bands, plus the goalpoint_id.

{ "checkpoint_count": 8,
  "checkpoints": [ {
      "checkpoint_id": 1,
      "position": [1.442, -0.501, 0.665],
      "marker_pose": { "position": [1.451, -1.001, 0.6806], "quaternion": [-0.7071, 0, 0, 0.7071] },
      "score_bands": [ {"radius": 0.1, "level": 3}, {"radius": 0.2, "level": 2}, {"radius": 0.3, "level": 1} ],
      "attitude": { "quaternion": [0.706, -0.690, 0.123, -0.103],
                    "centering_bands": [ {"angle": 10, "level": 3}, ... ],
                    "roll_bands":      [ {"angle": 10, "level": 3}, ... ] } }, ... ],
  "goalpoint_id": 12 }

Shortened from the Programming Manual's example response.

16. The API at a glance

Services answer a request; actions are for slow jobs like moving (connect, send a goal, wait for the result); topics stream data. Always give actions a timeout and a way to cancel.

17. Moving the robot

Send a CtlCommandGoal with a target pose and a type to /ctl/command:

• The result is TERMINATE_SUCCESS (0) when the move worked. Otherwise it's ABORTED (1), TIME_OUT (2), INVALID_NAV (3) or INVALID_CMD (4). Check it every time.
• To change plans mid-move, call cancel_goal() and wait until it has really stopped before sending the next target.
• /ctl/status shows the state: after a move it changes to KEEP_POSE or STOP_MOVING.
• /ctl/wrench pushes the robot directly (force in N, torque in N·m, in the robot's own frame). It can be smoother but you must stop it yourself; mixing it with /ctl/command can surprise you.
• Plan the route inside the flyable area, leave room for the robot's size, and wait a moment after arriving before you judge.

18. Reading AR markers

• The markers: ArUco 4×4 dictionary, IDs 1 to 12, 2 cm (0.02 m) wide. Give the side length in metres, never in pixels.
• The camera: use K and D from /camera_main/camera_info. It's empty until the first message arrives, so check before using it. If you resize the picture, scale fx, fy, cx and cy too.
• The library: OpenCV 3.3.1's aruco module.

19. Writing a safe program

The Programming Manual spends a whole chapter on this because a stuck program loses the run, and on the ISS it could affect the robot.

• No endless loops: cap the number of tries and the time, and give every loop more than one way out.
• Expect failures: check return values, catch exceptions, use timeouts, and handle missing or odd sensor data.
• Watch the clock: note how long each step takes and keep an eye on the time left in the mission.
• Move carefully: confirm the target first, always check the result, limit retries, and wait after arriving.
• Use fresh data: check timestamps and say which units and frame each value is in.
• Log useful things: start and end, the plan, each API call and its result, target and actual poses, errors, retries and timings, at the right level (ERROR, WARN, INFO, DEBUG).

From the Programming Manual, chapter 5 and section 6.5.

Part 3

20. Practising in the sandbox

Finished the rules? The next step on the learning path is Using the sandbox; then try it yourself in the sandbox. The table shows where in the sandbox you can practise each rule.