Open Perception Kit CLI quick start

The Open Perception Kit is aimed at Arm Linux developers, providing a fast path for early application development including vision inference without needing to build your perception stack from scratch by combining:

• GStreamer-based media pipeline integration.
• Reusable processing steps for preparing images for inference, running models, and interpreting their outputs.
• Schema-defined inference results that can be displayed, used to track objects, or shared with other applications.

It uses a container-based workflow with a packaged pipeline, browser viewer, model controls, debug signals, and output paths you can adapt for your own application.

Quick start: first inference on Raspberry Pi 5

What to expect

Plan for around 45 minutes to get to first inference after meeting all prerequisites.

In this quick start, you will:

• Connect to and confirm the target Pi.
• Clone the repository onto the target Pi.
• Build and start the container.
• Build the kit inside the container.
• Run the first pipeline.
• Open the browser viewer and confirm inference.

The Open Perception Kit is hardware agnostic. The table below lists the configurations validated so far; other devices and operating systems have not been validated.

Component	Validated configuration
Device	Raspberry Pi (at least 8GB RAM)
Operating system	Raspberry Pi OS 64-bit (Trixie)
Container platform	Linux ARM64
CSI camera	Raspberry Pi Camera Module 3
USB webcam	UVC (USB Video Class) webcam

Starting prerequisites

Host machine:

• Windows, macOS or Linux machine.
• Network access to the target Pi.

Target (Raspberry Pi 5)

• SSH enabled, with a username and password you can use from the host machine.
• Known target Pi hostname or IP address.
• Permission to run sudo.
• Internet access to GitHub, package repositories, and container or source locations used during the first container build.

1. Connect to the target Pi

1.1 Start the SSH session

Open a terminal on the host machine, then run:

ssh <raspberry-pi-username>@<raspberry-pi-hostname-or-ip>

Use raspberrypi.local if it resolves to the target Pi you prepared. Otherwise, use the target Pi IP address.

Expected outcome: the host machine opens a shell on the target Pi.

1.2 Clone the repository

In the Raspberry Pi 5 terminal run:

The latest_release tag points to the latest successfully completed release. The detached HEAD message is expected when checking out a release tag.

git clone --branch latest_release https://github.com/arm/open-perception-kit.git
cd open-perception-kit

2. Install prerequisites, build and start the Docker Container

We are working on providing access to a set of demo videos. Until they are available, please use your own input videos.

Enter the open-perception-kit folder in the terminal and run:

./scripts/quick_start.sh

The standard OPK models are public and download without a Hugging Face account or token. For your own private or gated models, see Bring your model.

Failed model downloads are logged and skipped. Check the build output if a pipeline fails to start because a model is missing.

For VGF inference on the CPU, configure the MLWL CPU quickstart before building the container.

3. Enter the container command line

./scripts/enter_cli.sh

Expected outcome: The prompt shows dev

4. Build OPK inside the Container

From the container shell, run:

./scripts/build.sh

Expected outcome: setup and kit build complete without a blocking error, and the terminal prints:

Pipeline launcher is ready at /work/tools/opk-menu
Run it with:
  ./scripts/run.sh

5. Run your first pipeline and confirm inference

5.1 Start the inference pipeline inside the Container

./scripts/run.sh

Keep this terminal running. The command starts your first pipeline and runs until you stop it with Ctrl+C.

Expected outcome: the terminal prints the generated gst-launch-1.0 command and the pipeline keeps running.

The target Pi serves the WebRTC inference viewer on port 9999. Open it from the host machine while the pipeline terminal keeps running.

5.2 Open the WebRTC viewer

On the host machine, open:

http://<raspberry-pi-ip-address>:9999

You can use the hostname instead if it resolves reliably on your network: http://<raspberry-pi-hostname>:9999.

Expected outcome: the viewer loads and shows the sample video stream, connection status, controls, the Model Selector panel, and the debug log.

5.3 Check YOLO26n-320

In the WebRTC browser viewer, find Object detection in the Model Selector panel, with model YOLO26n INT8 (320x320). It is enabled by default; enable it if you previously turned it off.

Expected outcome: YOLO26n-320 identifies objects in the stock video stream by drawing detection overlays in the viewer.

Congratulations, you have run your first Open Perception Kit pipeline!

Platform-specific setup

We recommend you start with the Raspberry Pi 5 guide above, however the following guides are available for other platforms or VS Code setup:

• Raspberry Pi 5
• Windows
• Mac
• Linux

After first success

Pick your next step.

Goal	What it does
Use your own input or output path	Keep the known pipeline and change the input or output.
Use live camera input	Move from packaged media to a USB or Raspberry Pi camera.
Use a binary release	Integrate the packaged GStreamer plugins without an OPK loader wrapper.
Add or adapt a model and OpChain	Change the model after the source and output path work.
Coming Soon: Feed inference into an application	Capture inference output for downstream logic.
Understanding the repository structure	How to get started with new components
Pipeline basics	Learn about inference pipeline principles
Custom postprocessing	Inference result postprocessing
Python script Op	Stateful scripting with FrameResults and tensors
Performance Measurement	Measure the pipeline performance with Performix

If something goes wrong

Symptom	Do this first
SSH fails from the host machine	Check the target Pi hostname or IP address, then retry with the IP address.
docker info fails	Confirm Docker Engine is installed and running from Docker's Debian installation guide. If it reports a permissions error, run sudo usermod -aG docker "$USER", reconnect, and try again.
Docker Compose cannot find the service	Rerun ./scripts/quick_start.sh to regenerate the container configuration.
Build fails	Fix the first missing package, permission, or container error shown in the build output.
Pipeline exits immediately	Rerun ./scripts/run.sh yolo26n-320 and inspect the first missing plugin, model, or file.
Viewer does not load	Keep the pipeline terminal running, use the target Pi IP address, and check port 9999.
A model produces no overlay	Confirm the model and any upstream dependencies are enabled, then check the debug log or model state in the viewer.

Advanced

The quick-start scripts are the recommended first path. Use the workflows below when you need direct deployment control or remote deployment with Topo.

Build a deployment container directly with Docker Compose

Download models through quick start first. Export your read-only Hugging Face token when private or gated models are needed:

# Optional: export HF_TOKEN="hf_your_token_here"
./scripts/quick_start.sh
./scripts/quick-start/cleanup-container.sh
docker compose up --build

Quick start downloads models into config/models. The deployment container mounts that directory read-only; its image contains descriptors but no model binaries. Stopping the quick-start container frees the container name and ports while preserving the downloaded files in the checkout.

Deploy with Topo

Install Topo on your development machine, then check that the target is ready:

topo health --target <raspberry-pi-ip-address>

On the target, use the same OPK source revision and run quick start with your Hugging Face access, then stop its container as above. In the host's compose.yaml, set the model volume's source to the absolute target path containing those downloaded models, for example:

- /home/<target-user>/open-perception-kit/config/models:/work/config/models:ro

Deploy from the repository root on the host:

topo deploy --target <raspberry-pi-ip-address>

The deployment uses the target's model files. Hugging Face credentials are used by quick start and are not forwarded to the deployment image or container.

When the deployment has started, open:

http://<raspberry-pi-ip-address>:9999

For a Raspberry Pi camera, connect the camera and restart the Pi before deploying:

OPK_PICAMERA=enabled OPK_PIPELINE=full-onnx-raspicam \
  topo deploy --target <raspberry-pi-ip-address>

For a USB camera exposed as /dev/video0 on the target:

OPK_PIPELINE=full-onnx-usb-cam \
  topo deploy --target <raspberry-pi-ip-address>

Copyright

Copyright 2025-2026 Arm Limited and/or its affiliates.

Licence

Open Perception Kit is licensed under the Apache License, Version 2.0, except where individual files or accompanying notices state otherwise. See Licensing for the licence and notice locations.

Third-party components retain their own licences. These include FlatBuffers (Apache-2.0), ONNX Runtime (MIT), ExecuTorch (BSD-3-Clause), ML Workload Library for Vulkan (Apache-2.0), Lucide icons (ISC/MIT), and the Lato (OFL-1.1) and Cousine (Apache-2.0) fonts supplied by Wafer. Their original notices accompany the distributed files; Wafer CSS retains its Arm copyright notice.

The maintained third-party component inventory lists versions, licence labels and origins. It was initialized from the supplied Black Duck scan.