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/2is 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
@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.
@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.
@spec capture_state(GenServer.server()) :: :idle | :starting | :capturing | :stopping
The hub's capture state: :idle, :starting, :capturing or :stopping.
@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.
@spec capturing?(GenServer.server()) :: boolean()
Whether the driver has confirmed capture is running.
Returns a specification to start this module under a supervisor.
See Supervisor.
@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.
@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 typeBB.Camera.StreamInfo) - Required. What the camera is expected to produce:driver(pid/0) - The process to drive capture, defaults to the process callingstart_link/1:publish_rate(term/0) - How oftenBB.Message.Camera.CaptureStateis published, in hertz - aLocalize.Unitor a plain number. Defaults to1.:externalinstead 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 realSystem.monotonic_time(:nanosecond)unless you mean to measure against something else.
@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.