# `BB.Camera.Libcamera`
[🔗](https://github.com/beam-bots/bb_camera_libcamera/blob/main/lib/bb/camera/libcamera.ex#L5)

A Raspberry Pi camera, captured from libcamera through `rpicam-vid`.

Declared like any other sensor:

    topology do
      link :head do
        sensor :eye, {BB.Camera.Libcamera, camera: 0, width: 1280, height: 720}
      end
    end

Consumers never talk to this module. They go through `BB.Camera`, which
refcounts them and asks the driver to start capturing when the first one
arrives and to stop when the last one leaves. Two browser tabs on the same
camera produce one `rpicam-vid`, not two.

## More than one camera

A Pi 5 has two camera connectors, and a Compute Module carrier may have
more. Declare one sensor per camera, each naming its own:

    link :head do
      sensor :left_eye, {BB.Camera.Libcamera,
        camera: "/base/axi/pcie@1000120000/rp1/i2c@88000/imx219@10"}
      sensor :right_eye, {BB.Camera.Libcamera,
        camera: "/base/axi/pcie@1000120000/rp1/i2c@80000/imx219@10"}
    end

`:camera` is an index or a libcamera camera id, both as
`BB.Camera.Libcamera.Devices.list/1` reports them. Prefer the id when there
is more than one camera: it names the connector, while an index is a
position in a list that shifts when a camera fails to probe. An id is
resolved to an index by listing the cameras afresh at the start of each
capture, which takes about a tenth of a second.

Each camera is captured by its own `rpicam-vid`, and each allocates its frame
buffers from the kernel's contiguous memory (CMA). A board with little of it
- 64 MiB is common - can run out with two cameras at 720p, and the second
capture then fails with `dmaHeap allocation failure` on the console. Either
give the kernel more CMA, or lower `:buffer_count`; see `options_schema/0`.

## What it captures

JPEG, encoded in software by `rpicam-vid`. A Pi camera produces raw Bayer
data, the Pi's ISP turns it into YUV, and `rpicam-vid` encodes that with
libjpeg, so every frame costs CPU in proportion to its size. `:quality`
trades size for fidelity.

## What it reports

Capture is confirmed to the hub on the **first whole image**, not when
`rpicam-vid` starts. A camera that is missing, busy, or cannot get buffers
would otherwise announce `BeginCapture` a moment before failing.

Dimensions come from the `SOF` marker of each frame, which is what was
actually encoded, and `BB.Camera.stream_info/2` reports those once capture
has produced something.

The frame rate in `stream_info` is the one that was **requested**. libcamera
is asked for it, and chooses a sensor mode that can deliver it, but this
driver does not read back what it got. What the frames actually did is
measured by `BB.Camera.Hub` and reported separately in
`BB.Message.Camera.CaptureState`.

## Frames do not go on pubsub

A robot's pubsub carries capture lifecycle only:
`BB.Message.Camera.BeginCapture` and `EndCapture`, published by the hub.
Frame bytes travel over `BB.Camera`'s bounded media interface, and never
appear in an event or an error.

## Options

See `options_schema/0`. Any of them can be filled from a parameter with
`param/1`, and changing that parameter while the robot runs reconfigures the
camera - see `handle_options/2`.

## Limitations

- **Raspberry Pi only**, in practice: `rpicam-vid` is built for the Pi's
  camera stack.
- **Timestamps are arrival times.** The MJPEG stream on `rpicam-vid`'s
  stdout carries no timestamps, so a frame is stamped when the read
  completing it reached the BEAM. See `BB.Camera.FFmpeg.Capture` for what
  that does and does not mean.
- **A failed capture is not retried.** The failure is reported and capture
  ends; reopening the camera is the consumer's decision, taken by
  subscribing again.
- **Changing an option that reaches `rpicam-vid` restarts it.** Capture ends
  and begins again around the change, with the events to match.
- **`rpicam-vid`'s diagnostics go to the VM's console**, not into the error.

# `handle_options`

Take up options that changed while the robot was running.

Reached when a `param/1` reference in the camera's DSL options resolves to a
new value. Only a change that alters the `rpicam-vid` invocation restarts
capture: libcamera configures the camera once, when it starts, so a new size
or rate means a new `rpicam-vid`. Capture stops and starts again around the
change; it is not a seamless transition and does not pretend to be. An
option that doesn't reach the command line - a framer bound, say - takes
effect without disturbing the stream.

**New options this driver cannot use stop the camera.** `handle_options/2`
has no way to refuse a change and stay running, so a value that satisfies
the parameter's declared type but not this driver - a width of `-1` against
a `:pos_integer` - takes the sensor down, and down again on each restart,
because the parameter was stored before anyone was asked about it. Declare
parameters with bounds that match the options they feed.

# `stream_info`

The format this camera is declared to produce.

Pure: it is called during discovery against robots that are not running, so
it reads the options and nothing else. Options that still hold unresolved
parameter references cannot imply a format, and produce an error rather than
a guess.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
