ActcastOS 4 Migration ガイド

ActcastOS 4 ではベース OS が Raspberry Pi OS Bookworm となっており、アプリの設定ファイルやコードの修正が必要になります。ここでは ImageNet Classification を例に、ActcastOS 3 上で動作する既存のアプリを ActcastOS 4 に対応する方法について説明します。

コード全体はこちらを参照してください。

OS 3 から OS 4 への移行で重要なポイントは以下のとおりです

各種設定ファイルに Bookworm 用の設定を追加する必要がある
CSI カメラを用いている場合、Raspberry Pi OS Bullseye で用いられていた UnicamIspCapture は Bookworm では利用できないため、LibcameraCapture を用いる必要がある
OS 4 以降は 64bit 環境となるため、ネイティブライブラリを利用している場合は 64bit 環境向けにビルドし直す必要がある
GPIO を制御する場合、RPi.GPIO ではなく rpi-lgpio を用いる必要がある

事前準備

既に Actcast 上で保守している OS 3 上で動作するアプリがあることを前提としています。

既存のアプリを Bookworm にも対応するための修正を行います。

ActDK コマンド

ActDK が 1.54.0 以上であることを確認してください。

$ actdk --version

actdk 1.54.0

開発デバイスについて

act の動作確認を行うためには、通常の Actcast デバイスで開発モードを利用します。詳細は開発モードを参照してください。

今回の例では example.local でアクセスできる Actcast デバイスに bookworm-dev という名前を付けています。

$ actdk remote add bookworm-dev@example.local

事前準備の確認

開発モードの Actcast デバイスに対して actdk build コマンドを実行し、以下のエラーが出ることを確認してください。

異なるエラーが出ている場合、ActDK コマンドのバージョンが 1.54.0 以上であることと、 Actcast デバイスの開発モードが有効になっていることを確認してください。

$ actdk build bookworm-dev

Error:
   0: Target type for remote `Raspberry Pi (bookworm)` is not set.

Location:
   src/workspace.rs:633

Suggestion: Try to add "raspberrypi-bookworm" to "target_types" in your .actdk/setting.json

修正箇所の概要

まずはじめに修正の必要な項目について列挙します。

.actdk/setting.json に target_types を明示し、 raspberrypi-bookworm を含める。
.actdk/dependencies.json ファイルに 1 で追加した raspberrypi-bookworm のセクションを含める。
manifesto/ に Bookworm 用のマニフェストファイルを追加する。
カメラデバイスとして CSI カメラを使う場合は LibcameraCapture を使うように変更を行う。
GPIO を制御する場合は RPi.GPIO から rpi-lgpio へ移行し、GPIO character device を manifesto に追加する。

以下ではそれぞれの修正方法を具体的に説明します。

`.actdk/setting.json` の修正

ファームウェアタイプとして raspberrypi-bookworm を新たにサポートするよう.actdk/setting.jsonを修正します。以下のように target_types をリストで指定してください。

  {
    "app_id": "imagenet-classification-for-raspi",
    "app_server_id": 1,
    "short_description": "1000 class ImageNet classification demo for raspi",
    "short_descriptions": {
      "ja": "ImageNet1000クラス分類デモ(for raspi)"
    },
-   "target_types": ["raspberrypi-bullseye"]
+   "target_types": ["raspberrypi-bullseye", "raspberrypi-bookworm"]
  }

`.actdk/dependencies.json` の修正

.actdk/setting.json に追加したファームウェアタイプごとのセクションを追加していきます。

raspberrypi-bookworm セクションを追加します。必要に応じて apt パッケージや pip の依存パッケージを追記してください。

また actfw-raspberrypi のバージョンを 3.3.1 以上にする必要があります。

  {
    "apt": [
      "libv4l-0",
      "libv4lconvert0",
      "python3-pil",
      "python3-numpy",
      "fonts-dejavu-core"
    ],
    "pip": [],
    "raspberrypi-bullseye": {
      "apt": [],
      "pip": [
-       "actfw-raspberrypi == 3.2.0"
+       "actfw-raspberrypi == 3.3.1"
      ]
    },
+   "raspberrypi-bookworm": {
+     "apt": [],
+     "pip": [
+       "actfw-raspberrypi == 3.3.1"
+     ]
+   }
  }

`manifesto` ファイルの修正および追加

新規に manifesto/bookworm.json ファイルを追加してください。

manifesto ディレクトリの下であればファイル名は不問です。ただし、 target_type が重複しないように注意してください。

詳細はアプリケーションの各種スキーマを参照してください。

+ {
+   "version": 2,
+   "target_type": "raspberrypi-bookworm",
+   "boards": [
+     "RSPi3B",
+     "RSPi3BPlus",
+     "RSPi3APlus",
+     "RSPi4B",
+     "RSPi5B"
+   ],
+   "devices": [
+     { "type": "camera" },
+     { "type": "videocore" },
+     {
+       "type": "framebuffer",
+       "device": [
+         "/dev/fb0"
+       ],
+       "required": false
+     }
+   ]
+ }

`RPi.GPIO` から `rpi-lgpio` への移行

ActcastOS 4 では RPi.GPIO は動作しません。GPIO を制御するアプリは、Linux の GPIO character device に対応した rpi-lgpio を使用してください。

rpi-lgpio は RPi.GPIO と互換性のある API を提供するため、次の import 文や GPIO を操作するコードは通常そのまま使用できます。ただし、アプリの起動処理には、後述する環境変数 RPI_LGPIO_REVISION の設定を追加する必要があります。

from RPi import GPIO

依存パッケージの変更

.actdk/dependencies.json の raspberrypi-bookworm セクションに、apt パッケージ python3-rpi-lgpio を追加します。

OS 3 と OS 4 の両方をサポートする場合は、次のようにターゲットごとに依存パッケージを分けてください。共通の apt または pip セクションに RPi.GPIO を記載している場合は、その記載を raspberrypi-bullseye セクションへ移動します。

{
  "apt": [],
  "pip": [],
  "raspberrypi-bullseye": {
    "apt": [],
    "pip": [
      "RPi.GPIO"
    ]
  },
  "raspberrypi-bookworm": {
    "apt": [
      "python3-rpi-lgpio"
    ],
    "pip": []
  }
}

OS 4 のみをサポートする場合は、RPi.GPIO を依存パッケージから削除し、python3-rpi-lgpio のみを追加してください。

重要

rpi-lgpio と RPi.GPIO はどちらも RPi.GPIO モジュールを提供するため、同じ Python 環境にインストールできません。

GPIO character device の追加

rpi-lgpio から GPIO character device へアクセスできるように、Bookworm 用の manifesto の devices に /dev/gpiochip0 を追加します。

{
  "type": "gpio",
  "device": [
    "/dev/gpiochip0"
  ]
}

既存の manifesto でカメラなどのデバイスを要求している場合は、それらを残したまま "gpio" の要素を devices に追加してください。同じ target_type について、複数の manifesto の boards に同じボードを指定することはできません。詳細はアプリケーションの各種スキーマを参照してください。

ボードのリビジョン情報の設定

ActcastOS 4 で rpi-lgpio を使用する場合は、Raspberry Pi のボードのリビジョン情報を環境変数 RPI_LGPIO_REVISION で渡す必要があります。例えば、アプリの起動スクリプトで次のように /proc/cpuinfo から取得して設定できます。

RPI_LGPIO_REVISION="$(awk -F ': ' '/^Revision/ {print $2}' /proc/cpuinfo)"
export RPI_LGPIO_REVISION

この処理は実行先の Raspberry Pi 上で、Python アプリを起動する前に行ってください。rpi-lgpio のモジュールを import する際にこの環境変数が参照されるため、設定後は同じ起動スクリプトからアプリを起動します。詳細は rpi-lgpio の Pi Revision を参照してください。

プログラムの修正

ここからはプログラムの修正を行います。

Raspberry Pi OS Bookworm で CSI カメラを使うには actfw_core.libcamera_capture モジュールの LibcameraCapture を利用します。USB カメラを使う場合には actfw_core.capture モジュールの V4LCameraCapture を利用します。

以下は Bullseye と Bookworm の両方に対応する場合の app/main に加えた差分です。

    if get_actcast_firmware_type() == "raspberrypi-bullseye" and not use_usb_camera:
        # Use UnicamIspCapture on Raspberry Pi OS Bullseye
        cap = UnicamIspCapture(unicam=device, size=(CAPTURE_WIDTH, CAPTURE_HEIGHT), framerate=framerate)

+   elif get_actcast_firmware_type() == "raspberrypi-bookworm" and not use_usb_camera:
+       import libcamera as libcam
+       from actfw_core.libcamera_capture import LibcameraCapture
+       cap = LibcameraCapture((CAPTURE_WIDTH, CAPTURE_HEIGHT), libcam.PixelFormat("BGR888"), framerate=framerate)
    else:
        # Use V4LCameraCapture on older firmware or use a USB camera
        cap = V4LCameraCapture(device, (CAPTURE_WIDTH, CAPTURE_HEIGHT), framerate, format_selector=V4LCameraCapture.FormatSelector.PROPER)

動作確認

従来のアプリ開発と同様に actdk build や actdk run でアプリのビルド、実行を行うことができます。

アプリのアップロード

従来のアプリ開発と同様に actdk upload でアプリのアップロードを行うことができます。

$ actdk upload
start uploading
Build Submission ID: XX
Build ID for Raspberry Pi: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

アップロードは１度行えば Bullseye と Bookworm それぞれのアプリイメージが Actcast へアップロードされます。

Actcast コンソールでアプリのビルド情報を確認すると１つのリビジョンで Bullseye と Bookworm それぞれのビルドがアップロードされていることが確認できます。

その他の注意点

ActcastOS 3 までは 32bit 環境でしたが、ActcastOS 4 以降は 64bit 環境となります。

そのため、以下のことに注意してください

独自にネイティブライブラリをビルドしている場合、64bit 環境向けにビルドし直す必要があります
actdk compileでモデルをビルドすると、app/libmodel_64bit.soというファイルが生成されるようになります
- git などのバージョン管理システムで自動生成されているファイルを無視している場合は、libmodel_64bit.soも無視するように設定を追加してください

最終更新日 2026/09/09