ActcastOS 4 Migration Guide

This page was machine-translated. The Japanese page is the official version.

ActcastOS 4 is based on Raspberry Pi OS Bookworm, so application configuration files and code may need to be updated. This guide uses ImageNet Classification as an example of adapting an existing ActcastOS 3 application for ActcastOS 4.

See the complete example.

The main migration points from OS 3 to OS 4 are:

• Add Bookworm settings to the relevant configuration files.
• For CSI cameras, replace UnicamIspCapture, used with Raspberry Pi OS Bullseye, with LibcameraCapture, which is supported on Bookworm.
• ActcastOS 4 and later use a 64-bit environment. Rebuild any native libraries for 64-bit.
• Use rpi-lgpio instead of RPi.GPIO to control GPIO.

Prerequisites

This guide assumes that you already maintain an application on Actcast that runs on OS 3. You will update that application to also support Bookworm.

ActDK command

Confirm that you are using ActDK 1.54.0 or later:

$ actdk --version

actdk 1.54.0

Development device

To test an Act, use Developer Mode on a regular Actcast device. See Developer Mode.

In this example, the Actcast device is reachable at example.local and is registered as bookworm-dev:

$ actdk remote add bookworm-dev@example.local

Check the prerequisites

Run actdk build for the Actcast device in Developer Mode and confirm that it reports the following error.

If you see a different error, confirm that ActDK is version 1.54.0 or later and that Developer Mode is enabled on the device.

$ 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

Summary of required changes

1. Specify target_types in .actdk/setting.json and include raspberrypi-bookworm.
2. Add a raspberrypi-bookworm section to .actdk/dependencies.json.
3. Add a Bookworm manifesto under manifesto/.
4. If the application uses a CSI camera, switch to LibcameraCapture.
5. If the application controls GPIO, migrate from RPi.GPIO to rpi-lgpio and add the GPIO character device to the manifesto.

The following sections describe each change.

Update .actdk/setting.json

Add raspberrypi-bookworm as a supported firmware type by listing it in 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"]
  }

Update .actdk/dependencies.json

Add a section for each firmware type listed in .actdk/setting.json. Add the raspberrypi-bookworm section and update actfw-raspberrypi to version 3.3.1 or later. Add apt and pip dependencies as required by your application.

  {
    "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"
+     ]
+   }
  }

For more about dependencies and custom base images, see Package Dependencies.

Add a Bookworm manifesto

Add a file such as manifesto/bookworm.json. The filename is arbitrary, but make sure that target_type is unique.

See Application Schemas for details.

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

Migrate from RPi.GPIO to rpi-lgpio

RPi.GPIO does not work on ActcastOS 4. Applications that control GPIO should use rpi-lgpio, which supports the Linux GPIO character device.

rpi-lgpio provides an API compatible with RPi.GPIO, so imports and GPIO operations can usually remain unchanged. However, you must set the RPI_LGPIO_REVISION environment variable when starting the application, as described below.

from RPi import GPIO

Update dependencies

Add the apt package python3-rpi-lgpio to the raspberrypi-bookworm section of .actdk/dependencies.json.

If you support both OS 3 and OS 4, separate dependencies by target type as follows. If RPi.GPIO is listed in the common apt or pip section, move it to the raspberrypi-bullseye section.

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

If you support only OS 4, remove RPi.GPIO from the dependencies and add only python3-rpi-lgpio.

Add the GPIO character device

Add /dev/gpiochip0 to devices in the Bookworm manifesto so that rpi-lgpio can access the GPIO character device:

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

If the existing manifesto requires devices such as a camera, keep those entries and add the gpio entry to devices. Do not specify the same board in multiple manifestos for the same target_type. See Application Schemas for details.

Set the board revision

When using rpi-lgpio on ActcastOS 4, provide the Raspberry Pi board revision in the RPI_LGPIO_REVISION environment variable. For example, retrieve it from /proc/cpuinfo in the application startup script:

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

Run this on the Raspberry Pi before starting the Python application. The rpi-lgpio module reads this environment variable when it is imported, so start the application from the same script after setting it. See rpi-lgpio Pi Revision.

Update the application code

To use a CSI camera with Raspberry Pi OS Bookworm, use LibcameraCapture from actfw_core.libcamera_capture. For a USB camera, use V4LCameraCapture from actfw_core.capture.

The following diff shows an update to app/main for supporting both Bullseye and Bookworm:

    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)

Test the application

As with existing application development, use actdk build and actdk run to build and run the application.

Upload the application

As with existing application development, use actdk upload to upload the application.

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

One upload sends application images for both Bullseye and Bookworm to Actcast. In the Actcast console, you can confirm that the builds for both OS versions are uploaded under a single revision.

Other considerations

ActcastOS 3 used a 32-bit environment; ActcastOS 4 and later use a 64-bit environment. Keep the following in mind:

• If you build native libraries yourself, rebuild them for a 64-bit environment.
• Running actdk compile to build a model now generates app/libmodel_64bit.so. If your version control system ignores generated files, add libmodel_64bit.so to the ignore rules.