カチャカAPI入門：Raspberry Piと物理ボタンで台車搬送システムを作ってみる

カチャカとは

カチャカは、マップ上に登録した場所へ自律的に移動し、専用の家具や台車を搬送できる小型ロボットです。
本記事で使用するカチャカプロは、この家庭向けカチャカを業務用途向けに強化した上位モデルです。最大牽引重量が20kgから30kgへ引き上げられているほか、地図のインポート／エクスポート、走行中のBGM再生、専用ボタン（カチャカボタン）による遠隔操作など、業務利用を想定した機能が追加されています。
カチャカの主な機能は以下の通りです。

• 登録済みロケーションへの移動
• 家具／台車へのドッキング
• 家具／台車の搬送
• 搬送先で台車を置く
• 充電ドックへの帰還

通常はスマートフォンアプリから操作しますが、カチャカAPIを利用することで、外部プログラムからも操作できます。

本記事で作るもの

本記事では、カチャカAPIを利用できるカチャカプロを対象とし、Raspberry Piに接続した物理ボタンからカチャカプロを操作する簡易搬送端末を作成します。

作成する端末では、以下を行います。

• 緑ボタン：台車 shelf_1 を location_1 へ呼び出す
• 黒ボタン：台車 shelf_1 を storage へ返却する
• Raspberry Piのディスプレイに現在状態を表示する

構成は以下のとおりです。

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

想定読者

本記事は、以下のような方を対象としています。

• カチャカプロを初めて使う人
• カチャカアプリやカチャカAPIの基本を知りたい人
• Raspberry PiやPythonからカチャカプロを操作してみたい人
• 物理ボタンや外部アプリと連携した搬送システムを試作したい人

参考：https://kachaka.life/posts/kachaka-api/

使用機材

本記事では、カチャカAPIの実行と物理ボタンの制御に、以下のRaspberry Piを使用します。

• モデル：Raspberry Pi 5
• メモリ：8GB
• ストレージ：microSDカード 32GB
• 用途：

  • カチャカAPIの実行
  • GPIOに接続した物理ボタンの入力検出
  • Tkinterによる現在状態の表示

上記は本記事で使用した構成例です。
カチャカAPIの実行やGPIO制御は比較的軽量な処理であるため、用途や構成によっては、より安価で低スペックなRaspberry Piでも動作可能です。
ただし、ディスプレイへの状態表示やほかの処理を同時に実行する場合は、必要な性能やストレージ容量を考慮して機種を選定してください。

カチャカアプリで事前準備する

Raspberry Piからカチャカプロを操作する前に、スマートフォンアプリで以下を準備します。

• 1. カチャカプロをWi-Fiに接続する
• 2. マップを作成する
• 3. 移動先ロケーションを登録する
• 4. 搬送対象の台車を登録する
• 5. アプリから手動で搬送できることを確認する
• 6. カチャカAPIを有効化する

設定 > カチャカAPI  からカチャカAPIを有効化することができる

APIから操作する場合でも、ロケーションや台車の登録はアプリ側で行います。
まずはアプリから手動で正常に搬送できる状態にしておきます。

ロケーションを登録する

Raspberry PiからカチャカAPIで移動先を指定できるように、カチャカアプリでロケーションを登録します。
本記事では、以下の2つのロケーションを登録します。

• storage
• location_1

storageは台車の保管場所、location_1は台車を呼び出す場所として使用します。

家具・台車を登録する

次に、搬送対象となる家具／台車をカチャカアプリで登録します。
本記事では、搬送する台車を shelf_1 という名前で登録します。

ロケーション、台車登録後のカチャカアプリの画面

API利用に必要な環境

本記事では、Raspberry PiからカチャカAPIを呼び出し、物理ボタンでカチャカプロを操作する構成を前提とします。

Python 3.12の仮想環境を作成する

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

kachaka-apiをインストールする

pip install kachaka-api

カチャカAPIを利用するには、あらかじめスマートフォンアプリでカチャカAPIを有効化しておく必要があります。
接続先には、アプリの「設定」→「アプリ情報」で確認できるIPアドレスを使用します。

カチャカAPIをインポートして接続する

まず、PythonからカチャカAPIを使用するために、KachakaApiClient をインポートします。

from kachaka_api import KachakaApiClient

今回のサンプルでは、接続先や台車名、ロケーション名を config.py から読み込んでいます。

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

config.pyでは以下のように定義します。

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

カチャカへ接続する処理は、create_client() にまとめています。

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

KachakaApiClient に接続先 KACHAKA_TARGET を指定して、カチャカプロへ接続します。
接続先は 192.168.1.100:26400 のように、IPアドレスとポート番号を含めて指定します。
その後、client.update_resolver() を実行し、アプリで登録したロケーション名や台車名をAPIから扱えるようにしています。

緑ボタン用の call_shelf() を実装する

緑ボタンを押したときは、call_shelf() で台車 shelf_1 を location_1 へ搬送します。

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() では、以下の順に処理を実行します。

• 1. move_shelf(SHELF_NAME, CALL_LOCATION)：台車 shelf_1 を location_1 へ搬送する
• 2.undock_shelf()：搬送先で台車を切り離す
• 3. return_home()：カチャカプロ本体を充電ドックへ戻す

黒ボタン用の return_shelf_to_storage() を実装する

黒ボタンを押したときは、return_shelf_to_storage() で台車 shelf_1 を storage へ返却します。

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() では、以下の順に処理を実行します。

• 1. move_shelf(SHELF_NAME, RETURN_LOCATION)：台車 shelf_1 を storage へ搬送する
• 2.undock_shelf()：返却先で台車を切り離す
• 3. return_home()：カチャカプロ本体を充電ドックへ戻す

GPIOボタンに割り当てる

前節で作成した call_shelf() と return_shelf_to_storage() を、Raspberry PiのGPIOに接続した物理ボタンへ割り当てます。

本構成では、GPIOのBCM番号として以下を使用しています。

GREEN_PIN = 5
BLACK_PIN = 6

緑ボタンを押すと call_shelf() を実行し、台車 shelf_1 を location_1 へ搬送します。
黒ボタンを押すと return_shelf_to_storage() を実行し、台車 shelf_1 を storage へ返却します。
ボタン操作に対応する処理は、以下のようになっています。

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] コマンド実行に失敗しました。ログを確認してください。") 

本記事ではカチャカAPIの呼び出し部分を中心に説明するため、GPIOの配線や詳細なイベント処理の説明は省略します。

Raspberry Piのディスプレイに状態を表示する

今回は、Tkinterを使って現在状態を表示します。

• 待機中
• 台車呼出中
• 台車返却中

緑ボタンを押して台車呼出処理を実行している間は「台車呼出中」、黒ボタンを押して台車返却処理を実行している間は「台車返却中」のように、現在の状態を画面に表示します。

実際に動かしてみる

ここまで実装した内容を使って、Raspberry Piに接続したボタンからカチャカプロを操作します。
ボタンを押すと、カチャカプロが台車を搬送する様子を実機で確認できます。
また、カチャカアプリからもコマンドの実行状態を確認できます。

※実際にカチャカも動作しており、カチャカアプリ上では移動ルート等を確認することが可能

※実際にカチャカも動作しており、カチャカアプリ上では移動ルート等を確認することが可能