Kachaka API Introduction: Building a Cart Transport System with Raspberry Pi and Physical Buttons

What is Kachaka?

Kachaka is a small robot that can autonomously move to locations registered on a map and transport specialized furniture and carts.
The Kachaka Pro used in this article is a higher-end model of the home-use Kachaka, enhanced for professional use. Its maximum towing capacity has been increased from 20kg to 30kg, and it includes additional features designed for professional use, such as map import/export, background music playback while driving, and remote control via a dedicated button (Kachaka button).
The main functions of the clicker are as follows:

• Move to a registered location
• Docking to furniture/trolley
• Furniture/trolley transport
• Place the trolley at the destination.
• Return to the charging dock

While it's normally operated via a smartphone app, it can also be controlled from external programs using the Kachaka API.

What we will make in this article

This article focuses on the Kachaka Pro, which supports the Kachaka API, and describes how to create a simple transport terminal that controls the Kachaka Pro using physical buttons connected to a Raspberry Pi.

On the device you are creating, do the following:

• Green button: Trolleyshelf_1 oflocation_1Call to
• Black button: Dollyshelf_1 ofstorageReturn to
• Display the current status on the Raspberry Pi's DISPLAY.

The structure is as follows:

[Raspberry Pi]
    ├─ Pythonプログラム
    ├─ kachaka-api
    ├─ GPIOボタン
    │   ├─ 緑ボタン：台車呼出
    │   └─ 黒ボタン：台車返却
    └─ Tkinterによる状態表示
    
            ↓ API通信
    
    [カチャカプロ]
    ├─ 台車を搬送
    ├─ 台車を置く
    └─ 充電ドックへ戻る

Intended audience

This article is intended for the following people:

• For those using KachakaPro for the first time
• For those who want to learn the basics of the Kachaka app and Kachaka API
• For those who want to control Kachakapro from Raspberry Pi or Python.
• For those who want to prototype a transport system that works with physical buttons and external apps.

Reference: https://kachaka.life/posts/kachaka-api/

Equipment used

This article uses the following Raspberry Pi to execute the Kachaka API and control the physical buttons.

• Model: Raspberry Pi 5
• Memory: 8GB
• Storage: microSD card 32GB
• Usage:

  • Execution of the Kachaka API
  • Input detection of physical buttons connected to GPIO
  • Displaying the current state using Tkinter

The above is an example configuration used in this article.
Since executing the Kachaka API and controlling GPIO are relatively lightweight processes, they can run on even cheaper, lower-spec Raspberry Pis, depending on the application and configuration.
However, if you plan to display status information on DISPLAY or perform other processes simultaneously, please select a model that takes into account the necessary performance and storage capacity.

Prepare in advance using the Kachaka app.

Before you can control the Kachakapro from your Raspberry Pi, prepare the following using the smartphone app.

• 1. Connect the Kachakapro to Wi-Fi.
• 2. Create a map
• 3. Register your destination location.
• 4. Register the trolley to be transported.
• 5. Confirm that you can transport items manually from the app.
• 6. Enable the Kachaka API.

You can enable the Kachaka API from Settings > Kachaka API.

Even when operating via API, location and trolley registration are handled by the app.
First, manually ensure that the app is in a state where it can be transported correctly.

Register your location

To allow specifying a destination from the Raspberry Pi using the Kachaka API, register the location in the Kachaka app.
In this article, we will register the following two locations.

• storage
• location_1

storageThis is the storage place for the trolleys.location_1This is used as the location to call for the trolley.

Register furniture and dollies

Next, you register the furniture/trolley to be transported using the Kachaka app.
This article will discuss the trolley used for transport.shelf_1I will register under that name.

Location, screen of the Kachaka app after registering the trolley.

Environment required for API usage

This article assumes a configuration where the Kachaka API is called from a Raspberry Pi and the Kachaka Pro is operated using physical buttons.

Create a virtual environment for Python 3.12.

python3.12 -m venv .venv
source .venv/bin/activate
python --version

Install kachaka-api

pip install kachaka-api

To use the Kachaka API, you need to enable the Kachaka API in the smartphone app beforehand.
The IP address used for connection is the one that can be found in the app's "Settings" → "App Info".

Import and connect to the Kachaka API.

First, in order to use the Kachaka API from Python,KachakaApiClientImport it.

from kachaka_api import KachakaApiClient

In this sample, the connection destination, trolley name, and location name are not specified.config.pyLoading from...

from config import (
    CALL_LOCATION,
    COMMAND_WAIT_SEC,
    KACHAKA_TARGET,
    RETURN_LOCATION,
    SHELF_NAME,
)

config.pyLet's define it as follows:

KACHAKA_TARGET = "192.168.1.100:26400"
SHELF_NAME = "shelf_1"
CALL_LOCATION = "location_1"
RETURN_LOCATION = "storage"

The process of connecting to the clicker is as follows:create_client()It's all summarized here.

def create_client() -> KachakaApiClient:
    """カチャカAPIクライアントを作成し、名前解決情報を更新する。"""
    print(f"[INFO] カチャカへ接続します: {KACHAKA_TARGET}")
    client = KachakaApiClient(KACHAKA_TARGET)
    client.update_resolver()
    print("[OK] 接続完了")
    return client

KachakaApiClientConnection destinationKACHAKA_TARGETSpecify this and connect to Kachakapro.
The connection destination is192.168.1.100:26400Specify it including the IP address and port number, as shown above.
after that,client.update_resolver()This process allows the API to access location names and trolley names registered in the app.

For the green buttoncall_shelf()Implement

When you press the green button,call_shelf()trolleyshelf_1oflocation_1We will transport it to [destination].

def call_shelf() -> None:
    """緑ボタン相当: 台車呼出を実行する。"""
    try:
        client = create_client()

        print("[INFO] 台車呼出を開始します")
        client.move_shelf(SHELF_NAME, CALL_LOCATION)

        print("[INFO] 台車を切り離します")
        client.undock_shelf()

        print("[INFO] 充電ドックへ戻ります")
        client.return_home()

        print("[OK] 台車呼出が完了しました")

    except Exception as exc:
        print("[ERROR] 台車呼出中に例外が発生しました。")
        print(f"[ERROR] 例外詳細: {exc}")
        raise

call_shelf()Now, we will execute the process in the following order.

• 1. move_shelf(SHELF_NAME, CALL_LOCATION): Dollyshelf_1oflocation_1Transport to
• 2.undock_shelf(): Detach the trolley at the destination.
• 3. return_home(): Return the Kachakapro unit to the charging dock.

For black buttonsreturn_shelf_to_storage()Implement

When you press the black button,return_shelf_to_storage()trolleyshelf_1ofstorageI will return it to [location].

def return_shelf_to_storage() -> None:
    """黒ボタン相当: 台車返却を実行する。"""
    try:
        client = create_client()

        print("[INFO] 台車返却を開始します")
        client.move_shelf(SHELF_NAME, RETURN_LOCATION)

        print("[INFO] 台車を切り離します")
        client.undock_shelf()

        print("[INFO] 充電ドックへ戻ります")
        client.return_home()

        print("[OK] 台車返却が完了しました")

    except Exception as exc:
        print("[ERROR] 台車返却中に例外が発生しました。")
        print(f"[ERROR] 例外詳細: {exc}")
        raise

return_shelf_to_storage()Now, we will execute the process in the following order.

• 1. move_shelf(SHELF_NAME, RETURN_LOCATION): Dollyshelf_1ofstorageTransport to
• 2.undock_shelf()Detach the trolley at the return destination.
• 3. return_home(): Return the Kachakapro unit to the charging dock.

Assign to GPIO button

Created in the previous sectioncall_shelf()andreturn_shelf_to_storage()Assign this to a physical button connected to the Raspberry Pi's GPIO pins.

In this configuration, the following are used as the BCM numbers for the GPIOs:

GREEN_PIN = 5
BLACK_PIN = 6

When you press the green buttoncall_shelf()Execute, cartshelf_1oflocation_1We will transport it to [destination].
When you press the black buttonreturn_shelf_to_storage()Execute, cartshelf_1ofstorageI will return it to [location].
The process corresponding to button operations is as follows:

def main() -> None:

    command = sys.argv[1].strip().lower()
    try:
        if command == "green":
            call_shelf()
        elif command == "black":
            return_shelf_to_storage()
        else:
            print("使い方: python 実行スクリプト [green|black]")
    except Exception:
        print("[ERROR] コマンド実行に失敗しました。ログを確認してください。") 

This article will focus on explaining the calling part of the Kachaka API, so we will omit explanations of GPIO wiring and detailed event handling.

Display status on the Raspberry Pi's DISPLAY

This time, we'll use Tkinter to display the current state.

• Waiting
• Calling Trolley
• Returning the trolley

The screen displays the current status, such as "Cart being called" while the green button is pressed to initiate the cart call process, or "Cart being returned" while the black button is pressed to initiate the cart return process.

Let's actually try it out

Using what we've implemented so far, we'll control the Kachakapro from a button connected to the Raspberry Pi.
By pressing the button, you can see the actual machine in action as the Kachakapro transports the cart.
Additionally, you can check the command execution status from the Kachaka app.

*The clicker is actually working, and you can check the movement route and other information on the clicker app.

*The clicker is actually working, and you can check the movement route and other information on the clicker app.