Skip to content
GitHub

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 camera modules on the CSI connector, through picamera2 and libcamera, and reads the per-frame metadata libcamera reports, such as light level and exposure time. The driver is read-only and never changes camera controls.

Because picamera2 installs only on Raspberry Pi OS, this driver has only been tested against a fake Picamera2 class, and docs/hardware-tests/rpi-camera.md lists what a person has to check on a real Pi.

What it supports

  • image read channels, one JPEG frame per read.
  • Number read channels from the libcamera metadata fields Lux, ExposureTime, AnalogueGain, DigitalGain, ColourTemperature, SensorTemperature, FrameDuration, FocusFoM and LensPosition.
  • Still or video configurations, with an optional frame size.
  • discover() and identify() list attached modules without opening them.

Setup

Because picamera2 needs the system libcamera bindings, picamera2 comes from apt on Raspberry Pi OS Bookworm or later rather than from pip, so 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

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

Parameters

ParameterDefaultMeaning
camera0Camera number from rpicam-hello --list-cameras, or auto for the first one. The shorthand rpi-camera: 0 sets it
configurationstillstill uses the full sensor resolution and captures slowly. video is smaller and faster
width, heightfrom the configurationMain stream size. Give both or neither
jpeg_quality85JPEG quality, 1 to 100
warmup1 sWait after starting the camera, so autoexposure and white balance settle
timeout10 sDeadline for starting the camera and for each capture

Channels

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

Metadata channels report the unit libcamera uses (lux, us for times, K, degC, dimensionless for gains and figures of merit). The kernel converts a reading into the channel's unit when the units differ, so exposure above reads in milliseconds.

How it works

The driver opens and starts the camera once on connect and keeps it running, so each capture takes one frame time rather than a full camera start. Only one process can hold a camera, so a second hub or a rpicam-* app running at the same time makes connect fail with "Device or resource busy". A capture or metadata request that fails marks the camera as failed, the next heartbeat reports the failure, and the hub reopens the camera.

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

  • picamera2 missing raises DriverError with the apt command above.
  • A missing camera number, no attached module, or a busy camera raises DriverError.
  • A capture that fails, or bytes that aren't a JPEG, raise DriverError. No frame within timeout raises TimeoutError.
  • A metadata field the sensor doesn't report raises DriverError listing the fields it does report.

Limitations

  • The driver has no camera controls (exposure, gain, focus, white balance) and no video recording.
  • The driver takes one capture at a time per camera.
  • The driver is only tested against the fake until the hardware test plan has been run.

Hazard default and safe state

The default hazard is low and the driver has 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