Bounded camera-independent capture admission, coverage and timing evidence. More...
#include "capture_arbiter.h"#include "boot_id.h"#include "camera_profile.h"#include "motion_compensation.h"#include <errno.h>#include <fcntl.h>#include <math.h>#include <pthread.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <sys/stat.h>#include <time.h>#include <unistd.h>#include "exifite.h"#include "sensor_capture.h"
Go to the source code of this file.
Data Structures | |
| struct | capture_intent |
| One camera's intent; acquired means pixels are owned, not yet durable. More... | |
| struct | capture_pose |
| FC pose and bounded local clock mapping, rather than a precise exposure claim. More... | |
Macros | |
| #define | _POSIX_C_SOURCE 200809L |
| #define | ARBITER_COUNT(array) |
Functions | |
| static uint64_t | monotonic_us (void) |
| Read the local clock used for capture deadlines and pose alignment. | |
| static bool | random_session (uint32_t *token) |
| Obtain a nonzero token for a new survey session. | |
| static void | report (const struct capture_intent *intent, unsigned camera_id, uint32_t outcome) |
| Record a terminal outcome without allowing telemetry backlog to block camera release. | |
| static void | expire (struct capture_intent *intent, uint32_t outcome) |
| Retire an intention and record its terminal outcome. | |
| static bool | fresh_scope (uint64_t now_us) |
| Check whether the active survey scope is still current. | |
| static bool | project (const union dc_shot_union *shot, unsigned camera_id, double uncertainty, struct coverage_candidate *candidate) |
| Convert FC units and estimate geometric detail using this camera's calibration. | |
| static double | angle_delta (int32_t first, int32_t second) |
| Take the short arc across heading wrap, using widened subtraction before conversion. | |
| static bool | predict (uint64_t time_us, union dc_shot_union *shot, double *uncertainty) |
| Forecast a short continuation only when mapped motion is suitably well behaved. | |
| bool | capture_arbiter_load_camera (const char *filename) |
| Load one camera's measured profile without guessing geometry from its ID. | |
| void | capture_arbiter_set_enforce (bool enabled) |
| Enable coverage-based suppression and limited delay, or observe decisions only. | |
| bool | capture_arbiter_set_overlap (double overlap) |
| Set the overlap floor for deliberate predictive delay, not FC shot spacing. | |
| bool | capture_arbiter_set_camera_capacity (unsigned camera_id, unsigned limit) |
| Set admission from a backend's actual capacity, independent of camera ID. | |
| 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_offer (const union usher_capture_arbiter_shoot_union *request, uint64_t now_us) |
| Split a survey request into bounded per-camera intentions. | |
| static bool | take_locked (uint32_t ready_mask, uint64_t now_us, union dc_shot_union *shot, uint8_t *mask) |
| Make one admission decision while guard is held; no callbacks or dynamic allocation. | |
| 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_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_result (union usher_capture_arbiter_result_union *result, uint32_t ready_mask) |
| Pop a bounded best-effort result for UART transmission. | |
| bool | capture_arbiter_pending (void) |
| Check whether waiting or active survey work remains. | |
| bool | capture_arbiter_owns (int32_t number) |
| Identify a shot whose active survey ownership must not be superseded. | |
| 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_stop (void) |
| Cancel waiting intentions, retaining active-image ownership and saved coverage. | |
| void | capture_arbiter_pose_invalidate (void) |
| Forget pose history when synchronization is lost; keep saved coverage. | |
| 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. | |
| static int32_t | interpolate (int32_t first, int32_t second, double fraction) |
| Interpolate a scalar fixed-point pose field. | |
| static bool | pose_at (uint64_t time_us, uint64_t time_error_us, union dc_shot_union *shot, double *uncertainty_m, struct capture_observation *observation) |
| Interpolate a qualified pose from bounded sample history. | |
| 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_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_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_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. | |
Variables | |
| static pthread_mutex_t | guard = PTHREAD_MUTEX_INITIALIZER |
| static struct coverage_state | coverage_ledger |
| static struct coverage_state * | covered |
| static struct coverage_camera | cameras [COVERAGE_CAMERAS] |
| static bool | calibrated [COVERAGE_CAMERAS] |
| static struct capture_intent | waiting [COVERAGE_CANDIDATES *COVERAGE_CAMERAS] |
| static struct capture_intent | active [2 *COVERAGE_CAMERAS] |
| static unsigned | capacity [COVERAGE_CAMERAS] = {1, 1, 1} |
| static union usher_capture_arbiter_result_union | results [64] |
| static size_t | result_head |
| static size_t | result_count |
| static uint32_t | session |
| static uint32_t | scope_mask |
| static uint32_t | saved_count |
| static uint64_t | scope_us |
| static bool | scope_active |
| static bool | enforce |
| static bool | origin_set |
| static double | latitude |
| static double | longitude |
| static uint64_t | service_us [COVERAGE_CAMERAS] = {1000000, 1000000, 1000000} |
| static struct coverage_candidate | last_saved [COVERAGE_CAMERAS] |
| static bool | have_saved [COVERAGE_CAMERAS] |
| static double | minimum_overlap = 0.3 |
| static const uint64_t | scope_lifetime_us = 750000 |
| static const uint64_t | intent_lifetime_us = 2000000 |
| static struct capture_pose | poses [512] |
| static size_t | pose_head |
| static size_t | pose_count |
| static uint32_t | gps_week |
| static uint32_t | gps_tow_ms |
| static uint64_t | gps_changed_us |
Detailed Description
Bounded camera-independent capture admission, coverage and timing evidence.
The serial owner offers intentions; camera workers report acquired and published images. Public state access uses guard, and internal state helpers require that lock. No camera callback runs under it. File parsing happens before taking the lock so an invalid profile or sidecar cannot retain camera admission. An intention is not an image: only verified publication may credit coverage.
Definition in file capture_arbiter.c.
Macro Definition Documentation
◆ _POSIX_C_SOURCE
| #define _POSIX_C_SOURCE 200809L |
Definition at line 18 of file capture_arbiter.c.
◆ ARBITER_COUNT
| #define ARBITER_COUNT | ( | array | ) |
Definition at line 47 of file capture_arbiter.c.
Function Documentation
◆ angle_delta()
|
static |
Take the short arc across heading wrap, using widened subtraction before conversion.
Definition at line 200 of file capture_arbiter.c.
◆ capture_arbiter_acquired()
| void capture_arbiter_acquired | ( | int32_t | number, |
| unsigned | camera_id, | ||
| uint64_t | now_us ) |
Learn acquisition latency separately from slower JPEG publication.
- Parameters
-
number Original FC shot number. camera_id Backend that now owns the selected pixels. now_us Acquisition-complete time in MORA's monotonic domain.
The first plausible receipt updates service time; publication still owes capture_arbiter_complete() and no coverage is credited at this point.
Definition at line 536 of file capture_arbiter.c.
◆ capture_arbiter_complete()
| 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.
- Parameters
-
shot Matching request number, with exposure pose when valid. camera_id Camera completing this observation. saved Original and required metadata were successfully published. exposure_pose_valid Pose is backed by frame timing, not just trigger time. uncertainty_m Nonnegative position margin associated with that pose. now_us Completion time; used for fallback service-time estimation.
Call on startup and metadata failures too, or that camera remains busy. Unknown pose still permits a SAVED result but never trusted coverage credit.
Definition at line 459 of file capture_arbiter.c.
◆ capture_arbiter_frame_pose()
| 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.
- Parameters
-
filename Published JPEG path, exclusively owned during inspection. camera_id Sensor identity; configured profile dimensions must match the JPEG and record. request Original request; its number is retained in the returned exposure record. [out] exposure Pose estimate at the frame's bounded observation time. [out] uncertainty_m Ground-position margin carried into coverage accounting.
- Returns
- False when evidence is missing, stale, inconsistent or outside supported bounds.
- Warning
- Identity checks prevent accidental mismatches, not hostile file replacement. Do not recycle or edit capture paths concurrently. Failure must not discard the JPEG.
Definition at line 795 of file capture_arbiter.c.
◆ capture_arbiter_frame_timing()
| 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.
frame_bound may be true while kind remains UNKNOWN. Profiles are optional; when configured their dimensions must match. Call before the EXIF inode replacement.
Definition at line 739 of file capture_arbiter.c.
◆ capture_arbiter_load_camera()
| bool capture_arbiter_load_camera | ( | const char * | filename | ) |
Load one camera's measured profile without guessing geometry from its ID.
- Parameters
-
filename Bounded PANGEA_CAMERA_V1 flat key=value file; prefix c/a/l identifies the sensor.
- Returns
- True on acceptance; false with a diagnostic on invalid input or allocation failure.
The first valid profile allocates the fixed ledger and random peer session. Replacing calibration is a startup operation, not a way to reinterpret existing coverage. Input is a nonempty regular file of at most 1 KiB containing one key=value per line. Blank lines and # comments are allowed; duplicate/unknown keys and invalid decimal fields are rejected without allocation. Invalid input leaves existing calibration and session state intact.
Definition at line 238 of file capture_arbiter.c.
◆ capture_arbiter_observation_pose()
| 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.
Definition at line 712 of file capture_arbiter.c.
◆ capture_arbiter_offer()
| 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.
- Parameters
-
request Session-tagged shot and camera mask from the FC. now_us Receipt time used for intent age and scope freshness.
- Returns
- True when handled, including expiry or no image-camera bits; not a saved-photo ACK. False indicates an invalid request/session. Overflow replaces only the same camera's oldest waiting record, so another sensor's backlog cannot be evicted by this one.
Definition at line 334 of file capture_arbiter.c.
◆ capture_arbiter_owns()
| bool capture_arbiter_owns | ( | int32_t | number | ) |
Identify a shot whose active survey ownership must not be superseded.
- Parameters
-
number FC shot number to look up across image cameras.
- Returns
- True if any active camera owns this number; not evidence of publication.
Definition at line 526 of file capture_arbiter.c.
◆ capture_arbiter_pending()
| bool capture_arbiter_pending | ( | void | ) |
Check whether waiting or active survey work remains.
- Returns
- A synchronized snapshot, not a wait primitive or a readiness guarantee.
Definition at line 516 of file capture_arbiter.c.
◆ capture_arbiter_pose_at()
| 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.
- Parameters
-
time_us Desired observation time in MORA's monotonic domain. time_error_us Observation-time uncertainty in microseconds. [out] shot Interpolated raw FC pose; caller must restore the observation's shot number. [out] uncertainty_m Conservative ground-position margin in metres.
- Returns
- True when all timing, motion and uncertainty checks pass. Ignore outputs on false.
Definition at line 707 of file capture_arbiter.c.
◆ capture_arbiter_pose_invalidate()
| void capture_arbiter_pose_invalidate | ( | void | ) |
Forget pose history when synchronization is lost; keep saved coverage.
Definition at line 562 of file capture_arbiter.c.
◆ capture_arbiter_pose_sample()
| 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.
- Parameters
-
sample FC pose/GPS evidence, including raw fixed-point shot fields. earliest_us Earliest possible local sample time. latest_us Latest possible local sample time.
Invalid evidence clears interpolation history rather than bridging a clock discontinuity with seemingly precise coordinates.
Definition at line 571 of file capture_arbiter.c.
◆ capture_arbiter_result()
| bool capture_arbiter_result | ( | union usher_capture_arbiter_result_union * | result, |
| uint32_t | ready_mask ) |
Pop a bounded best-effort result for UART transmission.
- Parameters
-
[out] result Result whose storage is independent of the internal queue. ready_mask Current readiness snapshot to attach.
- Returns
- True if a record was popped; false when empty or result is NULL.
- Note
- Retain the popped record locally if UART transmission must be retried.
Definition at line 501 of file capture_arbiter.c.
◆ capture_arbiter_session_id()
| uint32_t capture_arbiter_session_id | ( | void | ) |
Return the peer-session token, or zero when survey mode is not configured.
- Returns
- Random nonzero token after successful profile initialization; not an authentication key.
Definition at line 304 of file capture_arbiter.c.
◆ capture_arbiter_set_camera_capacity()
| bool capture_arbiter_set_camera_capacity | ( | unsigned | camera_id, |
| unsigned | capacity ) |
Set admission from a backend's actual capacity, independent of camera ID.
- Parameters
-
camera_id One-based image-camera identity. capacity Maximum active captures, 1..2.
- Returns
- False for invalid input. Lowering capacity does not cancel active captures.
Definition at line 295 of file capture_arbiter.c.
◆ capture_arbiter_set_enforce()
| void capture_arbiter_set_enforce | ( | bool | enforce | ) |
Enable coverage-based suppression and limited delay, or observe decisions only.
- Parameters
-
enforce True permits conservative enforcement; false is the default.
- Note
- Observation still uses bounded admission and expiry, not the legacy queue policy.
Definition at line 279 of file capture_arbiter.c.
◆ capture_arbiter_set_overlap()
| bool capture_arbiter_set_overlap | ( | double | overlap | ) |
Set the overlap floor for deliberate predictive delay, not FC shot spacing.
- Parameters
-
overlap Fraction within 0..0.9.
- Returns
- False for invalid input, leaving the previous setting intact.
Definition at line 286 of file capture_arbiter.c.
◆ capture_arbiter_set_scope()
| 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.
- Parameters
-
scope Validated wire structure; wrong sessions and malformed values are ignored. now_us Local receipt time, not a remote FC timestamp.
A stop or removed mask bit affects waiting intentions only. An acquired original still deserves to be saved even when the survey has just ended.
Definition at line 312 of file capture_arbiter.c.
◆ capture_arbiter_stop()
| void capture_arbiter_stop | ( | void | ) |
Cancel waiting intentions, retaining active-image ownership and saved coverage.
Definition at line 553 of file capture_arbiter.c.
◆ capture_arbiter_take()
| 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.
- Parameters
-
ready_mask Backend readiness snapshot; active-capacity limits are also enforced here. now_us Current local time for expiry and short-horizon prediction. [out] shot Original FC request, not the predicted future exposure pose. [out] mask Image camera admitted for this shot.
- Returns
- True when the caller must dispatch work and eventually call capture_arbiter_complete(). False means no admission; expiry or redundancy results may still have been queued.
Definition at line 450 of file capture_arbiter.c.
◆ expire()
|
static |
Retire an intention and record its terminal outcome.
- Parameters
-
[in,out] intent Owned entry to clear. outcome Result code to report to each camera in the intent mask.
Report per camera before clearing the slot. The caller holds the arbiter lock, and result queue overflow must not prevent retirement.
Definition at line 153 of file capture_arbiter.c.
◆ fresh_scope()
|
static |
Check whether the active survey scope is still current.
- Parameters
-
now_us Current local monotonic time in microseconds.
- Returns
- True for an active session with in-window scope evidence.
Check ordering before subtracting unsigned times; a timestamp later than the query is not evidence that the scope is fresh.
Definition at line 167 of file capture_arbiter.c.
◆ interpolate()
|
static |
Interpolate a scalar fixed-point pose field.
- Parameters
-
first Value at the earlier sample. second Value at the later sample. fraction Position between the endpoints, from zero to one.
- Returns
- Nearest representable value in the original fixed-point units.
Widen before subtracting to accommodate opposite signed endpoints. Use wrapped angular deltas instead for headings and attitude.
Definition at line 639 of file capture_arbiter.c.
◆ monotonic_us()
|
static |
Read the local clock used for capture deadlines and pose alignment.
- Returns
- Monotonic microseconds, or zero when the clock read fails.
Use the same time base for age and ordering checks so wall-clock corrections do not make old evidence appear fresh.
Definition at line 99 of file capture_arbiter.c.
◆ pose_at()
|
static |
Interpolate a qualified pose from bounded sample history.
- Parameters
-
time_us Query time in local monotonic microseconds. time_error_us Timing uncertainty around the query, in microseconds. [out] shot Interpolated pose; use only on success. [out] uncertainty_m Estimated position uncertainty in metres; use only on success. [in,out] observation Optional destination for navigation provenance on success.
- Returns
- True if the query is bracketed and passes motion and uncertainty checks.
Do not extrapolate beyond recorded pose samples. Reject discontinuous or widely spaced pairs before interpolating scalars and wrapped angles. Combine timing, navigation accuracy, and attitude change as a conservative operational check, not a surveyed accuracy guarantee.
Definition at line 657 of file capture_arbiter.c.
◆ predict()
|
static |
Forecast a short continuation only when mapped motion is suitably well behaved.
Definition at line 206 of file capture_arbiter.c.
◆ project()
|
static |
Convert FC units and estimate geometric detail using this camera's calibration.
Definition at line 173 of file capture_arbiter.c.
◆ random_session()
|
static |
Obtain a nonzero token for a new survey session.
- Parameters
-
[out] token Destination; use only on success.
- Returns
- True for a complete, nonzero token and successful descriptor close.
Accumulate short reads and retry interruptions instead of accepting a partial token. Zero is reserved for inactive session state.
Definition at line 113 of file capture_arbiter.c.
◆ report()
|
static |
Record a terminal outcome without allowing telemetry backlog to block camera release.
Definition at line 129 of file capture_arbiter.c.
◆ take_locked()
|
static |
Make one admission decision while guard is held; no callbacks or dynamic allocation.
Definition at line 374 of file capture_arbiter.c.
Variable Documentation
◆ active
|
static |
Definition at line 74 of file capture_arbiter.c.
◆ calibrated
|
static |
Definition at line 71 of file capture_arbiter.c.
◆ cameras
|
static |
Definition at line 70 of file capture_arbiter.c.
◆ capacity
|
static |
Definition at line 75 of file capture_arbiter.c.
◆ coverage_ledger
|
static |
Definition at line 68 of file capture_arbiter.c.
◆ covered
|
static |
Definition at line 69 of file capture_arbiter.c.
◆ enforce
|
static |
Definition at line 80 of file capture_arbiter.c.
◆ gps_changed_us
|
static |
Definition at line 91 of file capture_arbiter.c.
◆ gps_tow_ms
|
static |
Definition at line 90 of file capture_arbiter.c.
◆ gps_week
|
static |
Definition at line 90 of file capture_arbiter.c.
◆ guard
|
static |
Definition at line 66 of file capture_arbiter.c.
◆ have_saved
|
static |
Definition at line 84 of file capture_arbiter.c.
◆ intent_lifetime_us
|
static |
Definition at line 87 of file capture_arbiter.c.
◆ last_saved
|
static |
Definition at line 83 of file capture_arbiter.c.
◆ latitude
|
static |
Definition at line 81 of file capture_arbiter.c.
◆ longitude
|
static |
Definition at line 81 of file capture_arbiter.c.
◆ minimum_overlap
|
static |
Definition at line 85 of file capture_arbiter.c.
◆ origin_set
|
static |
Definition at line 80 of file capture_arbiter.c.
◆ pose_count
|
static |
Definition at line 89 of file capture_arbiter.c.
◆ pose_head
|
static |
Definition at line 89 of file capture_arbiter.c.
◆ poses
|
static |
Definition at line 88 of file capture_arbiter.c.
◆ result_count
|
static |
Definition at line 77 of file capture_arbiter.c.
◆ result_head
|
static |
Definition at line 77 of file capture_arbiter.c.
◆ results
|
static |
Definition at line 76 of file capture_arbiter.c.
◆ saved_count
|
static |
Definition at line 78 of file capture_arbiter.c.
◆ scope_active
|
static |
Definition at line 80 of file capture_arbiter.c.
◆ scope_lifetime_us
|
static |
Definition at line 86 of file capture_arbiter.c.
◆ scope_mask
|
static |
Definition at line 78 of file capture_arbiter.c.
◆ scope_us
|
static |
Definition at line 79 of file capture_arbiter.c.
◆ service_us
|
static |
Definition at line 82 of file capture_arbiter.c.
◆ session
|
static |
Definition at line 78 of file capture_arbiter.c.
◆ waiting
|
static |
Definition at line 73 of file capture_arbiter.c.