Camera Control Queue

The CameraControlQueueFunctions class provides HTTP endpoints that allow external systems (the frontend, Admin API) to send camera control commands that get executed during the next orchestration cycle.

How It Works

Endpoints

All endpoints require a valid API key in the x-api-key header.

Endpoint	Method	Purpose
/api/queue-ptz	POST	Queue a pan/tilt/zoom command
/api/queue-home	POST	Queue a return-to-home command
/api/queue-position	POST	Queue a position query
/api/queue-status	POST	Queue a full status query
/api/queue-brightness	POST	Queue a brightness adjustment
/api/queue-focus	POST	Queue a focus adjustment

Command Queueing via Durable Entities

Commands are not executed immediately. Instead, they are queued on the camera's CameraState Durable Entity:

await client.Entities.SignalEntityAsync(
    entityId,           // @CameraState@{deviceId}
    "AddMoveCommand",   // Entity operation
    moveCommand         // Command payload
);

The orchestration loop checks the command queue at the top of each iteration (in BaseOrchestrationFunction). If commands are present, they are dequeued and executed as activity functions before image capture.

Why Queue Instead of Direct Execution?

1. Orchestration safety — Durable Functions orchestrations must be deterministic. Direct camera calls during an orchestration replay would cause incorrect behavior. Activity functions isolate I/O safely.
2. Command batching — Multiple PTZ commands sent in quick succession are queued and executed sequentially.
3. Mode awareness — In LEASED mode, the loop runs at a higher frequency so commands are picked up faster.

API Key Validation

All camera control endpoints validate the x-api-key header against the FunctionApiKeyOptions configuration. This is separate from the JWT authentication used by the Admin API — the camera control endpoints are designed for machine-to-machine communication.