AprilCam Daemon Wire Protocol

aprilcamd is a long-running background process that owns all cameras, runs AprilTag/ArUco detection, and serves per-frame data to any number of clients. It exposes one gRPC control service plus on-demand length-prefixed protobuf stream sockets for bulk data (images, tag streams) — frame bytes never flow over the gRPC connection itself.

This page describes the wire-level contract for someone implementing a client in another language. If you are writing a robot program in Python, use the Robot Direct API client instead — it wraps everything below. For running and configuring the daemon itself, see Operating the Daemon; for the big picture, Overview. The authoritative schema is proto/aprilcam_v2.proto.

Endpoints and discovery

The control plane is the gRPC service aprilcam.v2.AprilCamV2, served on two transports simultaneously:

mDNS discovery. When (and only when) the TCP bind succeeds, the daemon registers a Bonjour/zeroconf service record:

• Service type: _aprilcam._tcp.local.
• Instance name: aprilcam-<hostname>._aprilcam._tcp.local.
• Port: the bound gRPC TCP port (5280 by default)
• TXT properties: version (the aprilcam package version) and host (the daemon’s socket.gethostname())

Clients browse that service type to build a daemon list. The host TXT key is load-bearing: the Python client compares it against its own hostname to drop the local daemon’s advertisement (the local daemon is found by probing the lock file and control.sock directly instead). Advertising itself is never load-bearing — a daemon whose multicast stack is broken still works over its sockets, and a direct connect (-d HOST, implied port 5280) never touches discovery at all.

Version handshake. GetStatus — the first RPC the Python client makes on any fresh connection — echoes protocol_version (currently 1, daemon.rpc.PROTOCOL_VERSION). The proto file only ever grows — existing fields are never removed or renumbered — so an older client keeps working against a newer daemon (unknown fields are ignored per protobuf rules), and protocol_version bumps only if that guarantee is ever broken. A responder that fails GetStatus with UNIMPLEMENTED and no aprilcam-error-type trailing metadata is not a v2 daemon. Note: grpcio-reflection is declared as a daemon dependency, but the server does not currently register the gRPC reflection service — use GetStatus (or the .proto file) rather than runtime reflection.

Camera addressing. Every camera request field accepts either form aprilcam camera list prints: an all-digits token resolves by persistent registry number, anything else by slug (slugs always contain a non-digit, so the forms can’t collide). There is no open/close RPC — the daemon opens a camera on first use and holds it.

Control service RPCs

All RPCs are unary. The two Get*Stream RPCs return a descriptor of a separate socket, never a gRPC stream.

Cameras and status

Tags

Playfields, config, calibration

Annotations, features, mobile tags, guides

Stream endpoints

Error mapping

The daemon’s typed errors cross the wire as a gRPC status code plus trailing metadata, so a client can reconstruct the same typed exception instead of parsing status text. Every error carries aprilcam-error-type (the exception class name); specific types add fields:

Key message schemas

A wire-wide convention: absence is meaningful. proto3 optional fields distinguish “not applicable” from a legitimate zero — an uncalibrated tag record has no world field, never a (0, 0) placeholder. Check HasField (or your language’s presence API) rather than testing for zero.

TagRecord / TagFrame

GetTags, GetTag, GetTagHistory, the tag stream, and the tags embed in GetFrameResponse all carry the same records:

TagFrame wraps repeated TagRecord tags with timestamp, frame_index, and calibration_stale. For a registered mobile tag, world/yaw_rad are already the robot’s pose — parallax/offset correction runs inside the daemon.

GetFrameResponse (frames)

One deskewed frame therefore carries everything needed to render a fully annotated view.

PlayfieldDefinition (playfield)

Each PlayfieldFeatureEntry: slug, x, y (world cm), optional id (tag sections only — the calibration ground truth), optional colour (rectangles/dots only), and height_cm above the field plane (plain field — 0.0 means on the plane). FindFeature answers with the more abstract FeatureMatch shape (slug, kind, position, optional colour, height_cm — no numeric id).

CameraConfig (config)

Calibration

Calibration: stale, calibrated_at, playfield, homography (the solved pixel→world 3×3 matrix as exactly 9 row-major doubles), matched_ids, optional reprojection_error_cm, and — when a lens model was estimated — camera_matrix (9 row-major doubles) and dist_coeffs (empty = no lens model). CalibrationResult (from Calibrate) reports succeeded, matched_ids, missing_ids (always the exact ids, never a count), and optional reason / intrinsics-estimation fields.

Stream sockets

GetImageStream and GetTagStream allocate — or reuse, one listener per (camera, deskewed) / camera key — a raw socket and return where to connect:

message StreamEndpoint {
  optional string socket_path = 1;  // unix socket, same-host clients
  optional int32  tcp_port    = 2;  // TCP on 0.0.0.0, OS-assigned ephemeral port
}

Unix stream sockets are bound at <socket_dir>/stream-<key>.sock (stream-images-raw-<camera>.sock, stream-images-deskewed-<camera>.sock, stream-tags-<camera>.sock). Either field may be absent if that transport failed to bind; the Python client prefers the unix path when the daemon is local and falls back to TCP.

Allocation is cheap and starts nothing: capture, deskew, and detection begin only when the first connection is accepted, and stop when the last subscriber disconnects. There is no unsubscribe RPC — closing your socket is the unsubscribe. Preconditions (unknown camera, deskewed stream on an uncalibrated camera) are checked at first connect, not at allocation: a bad request gets a socket that connects and then immediately closes without a single frame — treat “connected, then EOF with no frame” as a real error, not a hiccup.

Wire framing

Both stream types use the same framing (src/aprilcam/framing.py):

[4 bytes: big-endian uint32 length][<length> bytes: protobuf payload]

Read exactly 4 bytes, then exactly that many payload bytes, and parse with the appropriate message type. A short read means the daemon closed the stream.

Payloads

• Image stream — each message is a serialized GetFrameResponse, byte-for-byte identical to what the one-shot GetFrame RPC returns for the same frame (tags/px_per_cm/annotations embeds included). Published unconditionally at a steady cadence (~15 Hz), always JPEG.
• Tag stream — each message is a serialized TagFrame (the same shape as GetTagsResponse.tags; there is no oneof wrapper message in v2). Detection runs at ~30 Hz while subscribed; frames are published on meaningful change (0.5 cm world / 8 px uncalibrated, and always when a tag appears or disappears), rate-capped at 20 Hz, with an unchanged-frame heartbeat every 1 s. The rate is fixed server-side — requests carry no max_hz field.

Backpressure is silent drop. Each subscriber has its own bounded queue (depth 2); a slow reader loses frames rather than building a backlog — you always get the latest available frame. N subscribers to the same key share one producer: one capture, one warp, one detection per tick, fanned out.

The client-side reference implementation is src/aprilcam/client/streams.py (SocketImageStream / SocketTagStream); the daemon side is src/aprilcam/daemon/stream_transport.py and src/aprilcam/daemon/streaming.py.