kachaka-api (gRPC)¶

日本語 · README

The simulator serves the kachaka-api gRPC API on port 26400, like the real robot. Install the official client on the host (no ROS needed) and connect to the simulator:

pip install kachaka-api

from kachaka_api import KachakaApiClient

client = KachakaApiClient("127.0.0.1:26400")
print(client.get_robot_pose())
client.update_resolver()
client.speak("hello")
client.move_to_location("L01")
client.move_shelf("S01", "L01")
client.return_shelf("S01")
client.return_home()

Commands and the locations need the ROS 2 side (slam.launch.py nav:=true or navigation.launch.py), since command_server runs them. The robot pose is in the map frame of slam_toolbox or AMCL. AMCL starts at the map frame's origin, the spawn pose on the saved maps; give it another start on /initialpose (RViz's 2D Pose Estimate).

Every RPC of the KachakaApi service (kachaka-api 3.17.5.0) is implemented. The client methods are the RPC names in snake_case (GetRobotPose → get_robot_pose). Where the simulator differs from the robot:

All StartCommand commands of kachaka-api 3.17.5.0 are implemented (see Commands). DEPART_FROM_CHARGER is newer than that release, so it can be sent only through the ROS 2 action (command_type: 23) until a kachaka-api release includes it.

Simulator error codes, shown by get_robot_error_code like the robot's own:

asyncio client¶

The asyncio client (kachaka_api.aio.KachakaApiClient) works too. Create it inside the event loop. Commands wait for completion unless wait_for_completion=False, and the streams yield while a command runs:

import asyncio
from kachaka_api.aio import KachakaApiClient

async def main():
    client = KachakaApiClient("127.0.0.1:26400")
    await client.update_resolver()

    async def watch():
        async for pose in client.robot_pose.stream():
            print(pose.x, pose.y, pose.theta)

    watcher = asyncio.create_task(watch())
    print(await client.move_to_location("L01"))
    watcher.cancel()

asyncio.run(main())

scripts/aio_demo.py does this with the command state as well.

The stamps (stamp_nsec) are wall clock time, as on the robot, where the demo notebooks compare them with time.time(). The ROS topics keep simulation time (/clock). The server converts each stamp with the offset between wall clock and simulation time at the /clock tick at or before it (kachaka_isaac_sim/wall_clock.py), so one sim time gives one wall time in every stream, and stamps keep their order. When the simulation runs slower than real time, stamps fall behind the wall clock and jump forward at each tick.

All of the client's streams work against the simulator: robot_pose, ros_odometry, ros_wheel_odometry, ros_imu, ros_laser_scan, front_camera_ros_image, front_camera_ros_compressed_image, object_detection, object_detection_features, png_map, command_state, last_command_result, shelves, moving_shelf_id, locations, map_list, current_map_id, history_list, auto_homing_enabled, manual_control_enabled, error. They follow the server's cursor long-poll:

• The sensor streams and the pose yield at the publishing rate.
• png_map yields whenever slam_toolbox publishes the map.
• The others yield their current value first, then again on a change. shelves and locations change only with the layout, not when a shelf is towed; use moving_shelf_id or get_shelves() for that.

The set_*_callback form works too. With kachaka-api 3.17.5.0, set_*_callback(None) stops it but then logs one TypeError: 'NoneType' object is not callable from the client library ("Task exception was never retrieved"). It is harmless. Setting a new callback right after stopping one leaves the old loop running too, so the callback runs twice per value; wait for the next value before setting it again. Both are client-side bugs (still in kachaka-api 3.18.1).

Maps¶

Maps are Nav2 map pairs in maps/ (mounted at /maps in the containers): <id>.yaml plus its <id>.pgm, as map_saver_cli writes them. The id is the file name. The yaml may also hold name (shown by get_map_list) and charger_pose: [x, y, yaw] (the default pose after switch_map).

• Under SLAM the current map is sim, slam_toolbox's live /map. Export it to keep it: export_map("sim", "slam.zip") then import_map("slam.zip") writes maps/slam.yaml. The id sim is never given to a saved map.
• Under navigation.launch.py the current map is the one it was started with; get_map_list lists the files in maps/ and switch_map loads another one into map_server and sets the initial pose.
• export_map writes a zip of the two files, which import_map reads back. import_image_as_map takes a PNG (Kachaka's palette, or any image: dark is occupied, light free, mid gray unknown) with the origin at its bottom-left corner.

Web dashboard¶

A small web page that shows the robot on the map and sends commands. It is a separate process on the host that only talks kachaka-api, so it needs no ROS and works with a real Kachaka too. It is off by default; start it next to the simulator:

uv run --no-project --with kachaka-api==3.17.5.0 python scripts/dashboard.py
# then open http://127.0.0.1:8080/
# options: --target <robot>:26400 (default 127.0.0.1:26400), --host 0.0.0.0 to reach it
# from other machines, --port 8080

• Map: the robot's map (GetPngMap, reloaded every 10 s so a SLAM map grows), the robot, the shelves (dark while towed), the charger and the locations. Wheel to zoom, drag to pan. kachaka-api has no path RPC, so the blue line is the trail of poses the page has seen, not the planned path.
• State: battery and charging, pose, the towed shelf, the running command, the last result and the active errors, with their titles from get_robot_error_code; the command history below.
• Commands: move to a location, move a shelf to a location, return the shelf, undock it, return home, "Goal on map" (click a point and drag to set the heading, sent as move_to_pose) and cancel. They need the ROS 2 side with Nav2, as for any kachaka-api client.

There is no login: anyone who can open the page can drive the robot, so keep the default --host 127.0.0.1 unless the network is trusted.

Demo notebooks¶

The demo notebooks of kachaka-api (python/demos/*.ipynb in pf-robotics/kachaka-api) run against the simulator. scripts/demo_notebooks.sh runs them headless: it starts the simulator, saves a SLAM map, restarts Nav2 on it, and runs each notebook in a fresh kernel with its client pointed at 127.0.0.1:26400 (the notebooks default to the robot's own address). It takes about 10 min and needs the ROS 2 image and uv:

scripts/demo_notebooks.sh                    # all of them
scripts/demo_notebooks.sh speak robot_pose   # some

The executed notebooks are written to build/demo_notebooks/. Notebooks that loop forever (camera, scan and error streams) are stopped after a while and pass if they showed something; the HTTP server notebooks are sent requests while they serve. With kachaka-api 3.17.5.0:

To run your own detector in the simulator: save images and features with save_object_detection_features, train with kachaka-transfer-learning and put its predictor.onnx next to run_custom_object_detection. The notebook scales the boxes for a 1280×720 image, presumably the robot's camera (scale_h = 720.0 / 224, scale_w = 1280.0 / 398); the simulated camera is 640×480, so use 480.0 / 224 and 640.0 / 398. The check above uses a stand-in model (stand_in_predictor in tests/demo_notebooks_check.py) that only proves the features fit the official inputs.

The same notebooks in a live JupyterLab, driven by scripts/record_demo.sh notebooks sensors|control|map|detection (the recorder clicks the buttons and the plot, and turns or drives the robot during the sensor streams):

The map that get_png_map returns is grayscale, so plot_map_robot_lidar draws it in matplotlib's default colormap (yellow); the real robot's PNG format is not checked here.