Skip to content
GitHub
Specification version v0.1

rpi-camera

tested on simulator

Tier Tier 1
Protocol libcamera through picamera2
Covers Raspberry Pi Camera Module 1, 2 and 3, Raspberry Pi High Quality and Global Shutter cameras, Raspberry Pi AI Camera, third-party CSI modules with libcamera support
Hazard default low
Conformance core
Tested with fake Picamera2 class built from the picamera2 manual, untested on a real Pi until the hardware plan is run

Estimated reach. Tens of camera modules. The official Raspberry Pi camera range is about eight modules, and libcamera supports a few dozen more third-party sensors on the CSI connector. Every one that libcamera can open works through picamera2 the same way, so the driver covers the whole set without per-model code. USB cameras on a Pi use the uvc driver instead.

The rpi-camera driver captures JPEG frames from Raspberry Pi CSI camera modules through picamera2 and libcamera, and reads per-frame metadata such as light level and exposure time. The driver is read-only and never changes camera controls.

The driver is tested only against a fake Picamera2 class, since picamera2 installs only on Raspberry Pi OS. docs/hardware-tests/rpi-camera.md lists the checks for a real Pi.

Supports

  • image reads, one JPEG frame each.
  • Number reads from the libcamera metadata fields Lux, ExposureTime, AnalogueGain, DigitalGain, ColourTemperature, SensorTemperature, FrameDuration, FocusFoM and LensPosition.
  • discover() and identify() list attached modules without opening any.

Setup

picamera2 needs the system libcamera bindings, so picamera2 comes from apt on Raspberry Pi OS Bookworm or later and there is no rpi-camera pip extra.

sudo apt install -y python3-picamera2
uv venv --system-site-packages
uv pip install -e .
rpicam-hello --list-cameras

If rpicam-hello --list-cameras doesn't list the module, check the ribbon cable and, on older images, camera_auto_detect=1 in /boot/firmware/config.txt.

ParameterDefaultMeaning
camera0Number from rpicam-hello --list-cameras, or auto for the first. rpi-camera: 0 is shorthand
configurationstillstill is full resolution and slow, video smaller and faster
width, heightfrom the configurationMain stream size, both or neither
jpeg_quality851 to 100
warmup1 sSettle time for autoexposure and white balance
timeout10 sCamera start and capture deadline

Channels

read:
  frame: { type: image }
  light: { unit: lux, map: { metadata: Lux } }
  exposure: { unit: ms, map: { metadata: ExposureTime } }

Metadata reads arrive in libcamera's units, lux, us for times, K, degC and dimensionless for gains and figures of merit. The kernel converts to the channel unit, so exposure above reads in ms.

Behavior

The camera starts once on connect and keeps running, so each capture takes one frame time. One process can hold a camera, so a second hub or a running rpicam-* app fails the connect with "Device or resource busy". A failed capture marks the camera failed, and the hub reopens the camera after the next heartbeat.

Example

openhal/drivers/rpi_camera/examples/camera-module-3.hal.yaml captures 1920x1080 frames from a Camera Module 3 and reads light level, exposure and sensor temperature.

Errors

  • Missing picamera2 raises DriverError with the apt command.
  • A missing camera number, no module, a busy camera, a failed capture and non-JPEG bytes raise DriverError. No frame within timeout raises TimeoutError.
  • A metadata field the sensor lacks raises DriverError listing the available fields.

Limitations

  • No camera controls such as exposure, gain, focus or white balance, and no video recording.
  • One capture at a time per camera.

Hazard default and safe state

Low with no write channels, so safe_state_support is none. Frames can show people and private spaces, so point cameras with care.

Sources

OpenHAL is an open protocol, released under Apache 2.0.

OpenHAL is not affiliated with Anthropic or MHS.

Source on GitHub

Specification v0.1