BB.Camera.Hub (bb_camera v0.1.1)

Copy Markdown View Source

The one capture a camera has, shared by everyone watching it.

One hub per camera, started and linked by the driver in its init/1. It registers itself in the robot's own Registry under {:camera, name}, so consumers find it the same way they find anything else in a robot.

What it is for

A camera has one physical capture no matter how many things want to watch it, and image data is large enough that the usual answer - publish and let subscribers sort it out - stops working. A 1080p MJPEG stream is tens of megabytes a second; put that through a fan-out registry with no backpressure and a single slow consumer becomes an unbounded mailbox and then a dead node. So frames do not go on BB.PubSub at all. They come through here, and here there are bounds at both ends:

  • Ingress - deliver/2 is a synchronous call. The driver blocks until the hub has taken the frame, so at most one frame per driver is ever in flight and the hub's mailbox cannot grow faster than it drains.
  • Buffer - the hub keeps exactly one frame, the latest. A new frame replaces the previous one whether or not anybody read it.
  • Egress - a consumer gets a frame only when it has asked for one, one at a time, and only one strictly newer than the last it received.

That last clause is what makes a next-in-a-loop consumer - an HTTP MJPEG route, say - run at the camera's frame rate rather than spinning: there is nothing to return until the camera produces something new.

The interface is deliberately source-agnostic. A driver reading a V4L2 device through a subprocess, one calling into a platform capture framework from a NIF, and one generating frames arithmetically all meet it the same way: they hand over a BB.Camera.Frame and wait for the hub to take it.

Lifecycle is driver-confirmed

The hub asks the driver to start capturing when the first consumer arrives and to stop when the last one leaves, but it does not assume either worked. A driver confirms with capture_started/2 or reports capture_failed/2, and only then is BB.Message.Camera.BeginCapture published. A camera whose device fails to open never claims to be capturing, and every consumer waiting on it is told rather than left on a stream that will not resume.

Because those confirmations are asynchronous, the hub tracks capture as a state machine - :idle, :starting, :capturing, :stopping - rather than a boolean. A consumer arriving while a stop is still in flight does not race it: the restart is held until the stop is confirmed, and the confirmation is attributed to the session it belongs to, so a new consumer is never told that a capture it was never part of has ended.

A capture failure is not retried automatically. Subscribers are told, and the hub returns to :idle; a driver whose device is missing would otherwise be restarted in a tight loop for as long as anyone was watching.

How fast it is really going

Every frame passes through deliver/2, so the hub is the one place that can measure a camera's real rate without each driver being asked to. While capture is running it counts frames over a window and publishes BB.Message.Camera.CaptureState at the end of each one, carrying what was asked for alongside what the frames actually did. The same pair is stamped onto every frame.

The window is counted, not smoothed, so a capture that has stalled reports 0.0 rather than the rate it used to manage.

Bounding what happens before the hub

deliver/2 bounds what crosses into bb_camera. It cannot bound what accumulates between an external source and the BEAM. An Erlang port offers no ingress flow control - Port.open's busy_limits_msgq does not provide one for port-to-owner data - and a native capture callback delivering frames into a process mailbox has the same problem. A driver has to bound that itself: a capped output rate, a drain-only owner process, hard buffer and frame-size caps, an explicit overload trip.

Nor does closing a port stop the program behind it. Neither Port.close/1, killing the port's owner, nor the owner crashing will end the spawned process; it is reparented and carries on. This usually goes unnoticed because the program dies of SIGPIPE on its next write to the closed pipe - which is exactly what does not happen to a camera that has wedged. A driver that spawns anything needs an explicit reaper; terminate/2 is not enough.

Summary

Functions

Report that capture failed.

Confirm that capture is running, optionally with the format it's really running at.

The hub's capture state: :idle, :starting, :capturing or :stopping.

Report that capture has stopped cleanly.

Whether the driver has confirmed capture is running.

Returns a specification to start this module under a supervisor.

Hand a frame over, blocking until the hub has taken it.

Start a hub for the camera the calling driver serves.

Replace the live stream format.

Functions

capture_failed(hub, error)

@spec capture_failed(GenServer.server(), struct()) :: :ok

Report that capture failed.

Publishes BB.Message.Camera.EndCapture with reason: :error and hands the error to every subscriber of the session that failed. The hub does not restart capture by itself afterwards.

capture_started(hub, stream_info \\ nil)

@spec capture_started(GenServer.server(), BB.Camera.StreamInfo.t() | nil) :: :ok

Confirm that capture is running, optionally with the format it's really running at.

Until this is called the camera is not capturing as far as anything else is concerned. Passing a StreamInfo is the same as calling update_stream_info/2 first, and is how a driver reports the geometry it negotiated rather than the one it asked for.

Each confirmation starts a new session: the frame counter returns to zero, every subscriber's idea of what it has already seen is cleared, and the hub forgets the sequence it last saw. That last part is what lets a driver choose

  • restart its sequence at zero for each session, or carry one counter across restarts because its capture backend does. Both are accepted; what the hub insists on is only that the sequence strictly increases within a session.

capture_state(hub)

@spec capture_state(GenServer.server()) :: :idle | :starting | :capturing | :stopping

The hub's capture state: :idle, :starting, :capturing or :stopping.

capture_stopped(hub, reason \\ :driver_stopped)

@spec capture_stopped(GenServer.server(), atom()) :: :ok

Report that capture has stopped cleanly.

When the hub was the one that asked - because the last consumer left - it uses its own reason for the published event rather than the one given here, so a driver never has to work out why it was asked to stop.

capturing?(hub)

@spec capturing?(GenServer.server()) :: boolean()

Whether the driver has confirmed capture is running.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

deliver(hub, frame, timeout \\ 5000)

@spec deliver(GenServer.server(), BB.Camera.Frame.t(), timeout()) ::
  :ok | {:error, struct()}

Hand a frame over, blocking until the hub has taken it.

Synchronous by design. This is the only ingress bound that exists, and wrapping it in a Task to "avoid blocking capture" reintroduces precisely the unbounded queue it is here to prevent. The hub does nothing with a frame beyond storing it and passing it to whoever has asked, so the call returns promptly; a timeout means the hub is wedged, which is a crash rather than a dropped frame.

Returns {:error, %BB.Error.Invalid.Camera.StaleFrame{}} if the sequence doesn't strictly increase, and {:error, %BB.Error.State.Camera.NotCapturing{}} if capture hasn't been confirmed started. Both are bugs in the driver, and neither takes the hub down with it.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Start a hub for the camera the calling driver serves.

Call this from the driver's init/1. The default :driver is the calling process, resolved here rather than in the hub's own init/1 - where self() would be the hub.

The hub links to the driver and monitors it. The link covers a crash; the monitor covers a clean exit, which a link would not propagate, and which would otherwise leave a hub registered for a camera that no longer exists.

Options

  • :bb (map/0) - Required. The %{robot:, path:} injected into the driver's options

  • :stream_info (struct of type BB.Camera.StreamInfo) - Required. What the camera is expected to produce

  • :driver (pid/0) - The process to drive capture, defaults to the process calling start_link/1

  • :publish_rate (term/0) - How often BB.Message.Camera.CaptureState is published, in hertz - a Localize.Unit or a plain number. Defaults to 1.
    :external instead of a rate means the hub closes no window of its own and publishes only when sent {:tick, monotonic_ns}, taking that timestamp as the end of the window. Hand it a real System.monotonic_time(:nanosecond) unless you mean to measure against something else.

update_stream_info(hub, stream_info)

@spec update_stream_info(GenServer.server(), BB.Camera.StreamInfo.t()) :: :ok

Replace the live stream format.

Call it when the first real frame reveals the actual geometry, or when a change to the camera's options alters it. Each subscriber is told as {:bb_camera, ref, {:stream_info, info}} immediately before the first frame the new format describes.

The buffered frame is discarded, because it was encoded under the old format and there is no longer an honest way to describe it: announcing the new format and then handing over the old frame would be worse than dropping one frame from a stream whose policy is already to drop frames.