Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
capture_arbiter.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef USHER_CAPTURE_ARBITER_H
19#define USHER_CAPTURE_ARBITER_H
20
21/**
22 * @file capture_arbiter.h
23 * @brief Session-scoped survey admission and saved-image evidence for USHER.
24 * @details The serial owner offers intentions and takes ready work; camera workers
25 * return acquisition and publication results. Public state access is mutex-protected.
26 * The implementation is C11 with pthread locking and explicit resource cleanup;
27 * the C linkage guards also permit existing C++ callers and regression fixtures.
28 * Configure profiles before starting workers. No function here operates a camera,
29 * changes FC distance rules, or assumes that a request contains recoverable pixels.
30 * @note Times are MORA CLOCK_MONOTONIC microseconds unless explicitly stated.
31 * Queues and coverage are session memory, not a restart-persistent mission database.
32 */
33
34#include "usher_protocol.h"
35#include "coverage_scheduler.h"
36#include "capture_timing.h"
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41/** @brief Load one camera's measured profile without guessing geometry from its ID.
42 * @param filename Bounded PANGEA_CAMERA_V1 flat key=value file; prefix c/a/l identifies the sensor.
43 * @return True on acceptance; false with a diagnostic on invalid input or allocation failure.
44 * @details The first valid profile allocates the fixed ledger and random peer session.
45 * Replacing calibration is a startup operation, not a way to reinterpret existing coverage.
46 * Input is a nonempty regular file of at most 1 KiB containing one key=value
47 * per line. Blank lines and # comments are allowed; duplicate/unknown keys and
48 * invalid decimal fields are rejected without allocation.
49 * Invalid input leaves existing calibration and session state intact.
50 */
51bool capture_arbiter_load_camera(const char *filename);
52/** @brief Enable coverage-based suppression and limited delay, or observe decisions only.
53 * @param enforce True permits conservative enforcement; false is the default.
54 * @note Observation still uses bounded admission and expiry, not the legacy queue policy.
55 */
57/** @brief Set the overlap floor for deliberate predictive delay, not FC shot spacing.
58 * @param overlap Fraction within 0..0.9.
59 * @return False for invalid input, leaving the previous setting intact.
60 */
61bool capture_arbiter_set_overlap(double overlap);
62/** @brief Set admission from a backend's actual capacity, independent of camera ID.
63 * @param camera_id One-based image-camera identity.
64 * @param capacity Maximum active captures, 1..2.
65 * @return False for invalid input. Lowering capacity does not cancel active captures.
66 */
67bool capture_arbiter_set_camera_capacity(unsigned camera_id, unsigned capacity);
68/** @brief Return the peer-session token, or zero when survey mode is not configured.
69 * @return Random nonzero token after successful profile initialization; not an authentication key.
70 */
71uint32_t capture_arbiter_session_id(void);
72/** @brief Refresh survey authorization or cancel waiting work when scope is withdrawn.
73 * @param scope Validated wire structure; wrong sessions and malformed values are ignored.
74 * @param now_us Local receipt time, not a remote FC timestamp.
75 * @details A stop or removed mask bit affects waiting intentions only. An acquired
76 * original still deserves to be saved even when the survey has just ended.
77 */
78void capture_arbiter_set_scope(const union usher_capture_arbiter_state_union *scope, uint64_t now_us);
79/** @brief Split a survey request into bounded per-camera intentions.
80 * @param request Session-tagged shot and camera mask from the FC.
81 * @param now_us Receipt time used for intent age and scope freshness.
82 * @return True when handled, including expiry or no image-camera bits; not a saved-photo ACK.
83 * False indicates an invalid request/session. Overflow replaces only the same camera's
84 * oldest waiting record, so another sensor's backlog cannot be evicted by this one.
85 */
86bool capture_arbiter_offer(const union usher_capture_arbiter_shoot_union *request, uint64_t now_us);
87/** @brief Admit the oldest ready camera intention after optional coverage evaluation.
88 * @param ready_mask Backend readiness snapshot; active-capacity limits are also enforced here.
89 * @param now_us Current local time for expiry and short-horizon prediction.
90 * @param[out] shot Original FC request, not the predicted future exposure pose.
91 * @param[out] mask Image camera admitted for this shot.
92 * @return True when the caller must dispatch work and eventually call capture_arbiter_complete().
93 * False means no admission; expiry or redundancy results may still have been queued.
94 */
95bool capture_arbiter_take(uint32_t ready_mask, uint64_t now_us, union dc_shot_union *shot, uint8_t *mask);
96/** @brief Release admission and optionally credit verified saved coverage.
97 * @param shot Matching request number, with exposure pose when valid.
98 * @param camera_id Camera completing this observation.
99 * @param saved Original and required metadata were successfully published.
100 * @param exposure_pose_valid Pose is backed by frame timing, not just trigger time.
101 * @param uncertainty_m Nonnegative position margin associated with that pose.
102 * @param now_us Completion time; used for fallback service-time estimation.
103 * @details Call on startup and metadata failures too, or that camera remains busy.
104 * Unknown pose still permits a SAVED result but never trusted coverage credit.
105 */
106void capture_arbiter_complete(const union dc_shot_union *shot, unsigned camera_id, bool saved,
107 bool exposure_pose_valid, double uncertainty_m, uint64_t now_us);
108/** @brief Pop a bounded best-effort result for UART transmission.
109 * @param[out] result Result whose storage is independent of the internal queue.
110 * @param ready_mask Current readiness snapshot to attach.
111 * @return True if a record was popped; false when empty or result is NULL.
112 * @note Retain the popped record locally if UART transmission must be retried.
113 */
115/** @brief Cancel waiting intentions, retaining active-image ownership and saved coverage. */
116void capture_arbiter_stop(void);
117/** @brief Check whether waiting or active survey work remains.
118 * @return A synchronized snapshot, not a wait primitive or a readiness guarantee.
119 */
120bool capture_arbiter_pending(void);
121/** @brief Identify a shot whose active survey ownership must not be superseded.
122 * @param number FC shot number to look up across image cameras.
123 * @return True if any active camera owns this number; not evidence of publication.
124 */
125bool capture_arbiter_owns(int32_t number);
126/** @brief Learn acquisition latency separately from slower JPEG publication.
127 * @param number Original FC shot number.
128 * @param camera_id Backend that now owns the selected pixels.
129 * @param now_us Acquisition-complete time in MORA's monotonic domain.
130 * @details The first plausible receipt updates service time; publication still
131 * owes capture_arbiter_complete() and no coverage is credited at this point.
132 */
133void capture_arbiter_acquired(int32_t number, unsigned camera_id, uint64_t now_us);
134/** @brief Add a pose only after the caller has established bounded clock alignment.
135 * @param sample FC pose/GPS evidence, including raw fixed-point shot fields.
136 * @param earliest_us Earliest possible local sample time.
137 * @param latest_us Latest possible local sample time.
138 * @details Invalid evidence clears interpolation history rather than bridging a
139 * clock discontinuity with seemingly precise coordinates.
140 */
141void capture_arbiter_pose_sample(const union usher_pose_sample_union *sample, uint64_t earliest_us, uint64_t latest_us);
142/** @brief Forget pose history when synchronization is lost; keep saved coverage. */
144/** @brief Interpolate within trusted nearby pose samples, never across a long gap.
145 * @param time_us Desired observation time in MORA's monotonic domain.
146 * @param time_error_us Observation-time uncertainty in microseconds.
147 * @param[out] shot Interpolated raw FC pose; caller must restore the observation's shot number.
148 * @param[out] uncertainty_m Conservative ground-position margin in metres.
149 * @return True when all timing, motion and uncertainty checks pass. Ignore outputs on false.
150 */
151bool capture_arbiter_pose_at(uint64_t time_us, uint64_t time_error_us, union dc_shot_union *shot,
152 double *uncertainty_m);
153/** @brief Resolve one bounded observation; wait_us is 0 on the serial thread, at most 200000 in workers. */
154bool capture_arbiter_observation_pose(struct capture_observation *observation, uint64_t wait_us);
155/** @brief Read embedded capture identity from a stable JPEG; true need not qualify timing.
156 * @details frame_bound may be true while kind remains UNKNOWN. Profiles are optional;
157 * when configured their dimensions must match. Call before the EXIF inode replacement. */
158bool capture_arbiter_frame_timing(const char *filename, unsigned camera_id, struct capture_observation *observation);
159/** @brief Associate embedded exposure evidence with this JPEG before geotagging.
160 * @param filename Published JPEG path, exclusively owned during inspection.
161 * @param camera_id Sensor identity; configured profile dimensions must match the JPEG and record.
162 * @param request Original request; its number is retained in the returned exposure record.
163 * @param[out] exposure Pose estimate at the frame's bounded observation time.
164 * @param[out] uncertainty_m Ground-position margin carried into coverage accounting.
165 * @return False when evidence is missing, stale, inconsistent or outside supported bounds.
166 * @warning Identity checks prevent accidental mismatches, not hostile file replacement.
167 * Do not recycle or edit capture paths concurrently. Failure must not discard the JPEG.
168 */
169bool capture_arbiter_frame_pose(const char *filename, unsigned camera_id, const union dc_shot_union *request,
170 union dc_shot_union *exposure, double *uncertainty_m);
171#ifdef __cplusplus
172}
173#endif
174
175#endif
static unsigned capacity[COVERAGE_CAMERAS]
static bool enforce
bool capture_arbiter_set_overlap(double overlap)
Set the overlap floor for deliberate predictive delay, not FC shot spacing.
void capture_arbiter_pose_invalidate(void)
Forget pose history when synchronization is lost; keep saved coverage.
bool capture_arbiter_pending(void)
Check whether waiting or active survey work remains.
void capture_arbiter_pose_sample(const union usher_pose_sample_union *sample, uint64_t earliest_us, uint64_t latest_us)
Add a pose only after the caller has established bounded clock alignment.
bool capture_arbiter_set_camera_capacity(unsigned camera_id, unsigned capacity)
Set admission from a backend's actual capacity, independent of camera ID.
bool capture_arbiter_frame_timing(const char *filename, unsigned camera_id, struct capture_observation *observation)
Read embedded capture identity from a stable JPEG; true need not qualify timing.
bool capture_arbiter_take(uint32_t ready_mask, uint64_t now_us, union dc_shot_union *shot, uint8_t *mask)
Admit the oldest ready camera intention after optional coverage evaluation.
void capture_arbiter_set_enforce(bool enforce)
Enable coverage-based suppression and limited delay, or observe decisions only.
bool capture_arbiter_owns(int32_t number)
Identify a shot whose active survey ownership must not be superseded.
bool capture_arbiter_frame_pose(const char *filename, unsigned camera_id, const union dc_shot_union *request, union dc_shot_union *exposure, double *uncertainty_m)
Associate embedded exposure evidence with this JPEG before geotagging.
uint32_t capture_arbiter_session_id(void)
Return the peer-session token, or zero when survey mode is not configured.
void capture_arbiter_set_scope(const union usher_capture_arbiter_state_union *scope, uint64_t now_us)
Refresh survey authorization or cancel waiting work when scope is withdrawn.
bool capture_arbiter_result(union usher_capture_arbiter_result_union *result, uint32_t ready_mask)
Pop a bounded best-effort result for UART transmission.
void capture_arbiter_acquired(int32_t number, unsigned camera_id, uint64_t now_us)
Learn acquisition latency separately from slower JPEG publication.
void capture_arbiter_complete(const union dc_shot_union *shot, unsigned camera_id, bool saved, bool exposure_pose_valid, double uncertainty_m, uint64_t now_us)
Release admission and optionally credit verified saved coverage.
bool capture_arbiter_observation_pose(struct capture_observation *observation, uint64_t wait_us)
Resolve one bounded observation; wait_us is 0 on the serial thread, at most 200000 in workers.
bool capture_arbiter_load_camera(const char *filename)
Load one camera's measured profile without guessing geometry from its ID.
void capture_arbiter_stop(void)
Cancel waiting intentions, retaining active-image ownership and saved coverage.
bool capture_arbiter_pose_at(uint64_t time_us, uint64_t time_error_us, union dc_shot_union *shot, double *uncertainty_m)
Interpolate within trusted nearby pose samples, never across a long gap.
bool capture_arbiter_offer(const union usher_capture_arbiter_shoot_union *request, uint64_t now_us)
Split a survey request into bounded per-camera intentions.
Sensor observation times, aligned poses, and optional frame-arrival evidence.
Fixed-memory geometric coverage accounting, independent of camera I/O.
union dc_shot_union request
Best-effort USHER-to-FC terminal result for one camera and shot number.
FC-to-USHER spatial observation request, not a physical shutter acknowledgement.
FC-to-USHER survey authorization, independent of individual shot requests.
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534
Shared FC/MORA byte-stream UART framing, messages and payload layouts.