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.c File Reference

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"
Include dependency graph for capture_arbiter.c:

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)
Value:
(sizeof(array) / sizeof((array)[0]))

Definition at line 47 of file capture_arbiter.c.

Function Documentation

◆ angle_delta()

double angle_delta ( int32_t first,
int32_t second )
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
numberOriginal FC shot number.
camera_idBackend that now owns the selected pixels.
now_usAcquisition-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
shotMatching request number, with exposure pose when valid.
camera_idCamera completing this observation.
savedOriginal and required metadata were successfully published.
exposure_pose_validPose is backed by frame timing, not just trigger time.
uncertainty_mNonnegative position margin associated with that pose.
now_usCompletion 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
filenamePublished JPEG path, exclusively owned during inspection.
camera_idSensor identity; configured profile dimensions must match the JPEG and record.
requestOriginal request; its number is retained in the returned exposure record.
[out]exposurePose estimate at the frame's bounded observation time.
[out]uncertainty_mGround-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
filenameBounded 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
requestSession-tagged shot and camera mask from the FC.
now_usReceipt 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
numberFC 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_usDesired observation time in MORA's monotonic domain.
time_error_usObservation-time uncertainty in microseconds.
[out]shotInterpolated raw FC pose; caller must restore the observation's shot number.
[out]uncertainty_mConservative 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
sampleFC pose/GPS evidence, including raw fixed-point shot fields.
earliest_usEarliest possible local sample time.
latest_usLatest 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]resultResult whose storage is independent of the internal queue.
ready_maskCurrent 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_idOne-based image-camera identity.
capacityMaximum 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
enforceTrue 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
overlapFraction 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
scopeValidated wire structure; wrong sessions and malformed values are ignored.
now_usLocal 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_maskBackend readiness snapshot; active-capacity limits are also enforced here.
now_usCurrent local time for expiry and short-horizon prediction.
[out]shotOriginal FC request, not the predicted future exposure pose.
[out]maskImage 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()

void expire ( struct capture_intent * intent,
uint32_t outcome )
static

Retire an intention and record its terminal outcome.

Parameters
[in,out]intentOwned entry to clear.
outcomeResult 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()

bool fresh_scope ( uint64_t now_us)
static

Check whether the active survey scope is still current.

Parameters
now_usCurrent 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()

int32_t interpolate ( int32_t first,
int32_t second,
double fraction )
static

Interpolate a scalar fixed-point pose field.

Parameters
firstValue at the earlier sample.
secondValue at the later sample.
fractionPosition 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()

uint64_t monotonic_us ( void )
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()

bool pose_at ( uint64_t time_us,
uint64_t time_error_us,
union dc_shot_union * shot,
double * uncertainty_m,
struct capture_observation * observation )
static

Interpolate a qualified pose from bounded sample history.

Parameters
time_usQuery time in local monotonic microseconds.
time_error_usTiming uncertainty around the query, in microseconds.
[out]shotInterpolated pose; use only on success.
[out]uncertainty_mEstimated position uncertainty in metres; use only on success.
[in,out]observationOptional 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()

bool predict ( uint64_t time_us,
union dc_shot_union * shot,
double * uncertainty )
static

Forecast a short continuation only when mapped motion is suitably well behaved.

Definition at line 206 of file capture_arbiter.c.

◆ project()

bool project ( const union dc_shot_union * shot,
unsigned camera_id,
double uncertainty,
struct coverage_candidate * candidate )
static

Convert FC units and estimate geometric detail using this camera's calibration.

Definition at line 173 of file capture_arbiter.c.

◆ random_session()

bool random_session ( uint32_t * token)
static

Obtain a nonzero token for a new survey session.

Parameters
[out]tokenDestination; 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()

void report ( const struct capture_intent * intent,
unsigned camera_id,
uint32_t outcome )
static

Record a terminal outcome without allowing telemetry backlog to block camera release.

Definition at line 129 of file capture_arbiter.c.

◆ take_locked()

bool take_locked ( uint32_t ready_mask,
uint64_t now_us,
union dc_shot_union * shot,
uint8_t * mask )
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

struct capture_intent active[2 *COVERAGE_CAMERAS]
static

Definition at line 74 of file capture_arbiter.c.

◆ calibrated

bool calibrated[COVERAGE_CAMERAS]
static

Definition at line 71 of file capture_arbiter.c.

◆ cameras

struct coverage_camera cameras[COVERAGE_CAMERAS]
static

Definition at line 70 of file capture_arbiter.c.

◆ capacity

unsigned capacity[COVERAGE_CAMERAS] = {1, 1, 1}
static

Definition at line 75 of file capture_arbiter.c.

◆ coverage_ledger

struct coverage_state coverage_ledger
static

Definition at line 68 of file capture_arbiter.c.

◆ covered

struct coverage_state* covered
static

Definition at line 69 of file capture_arbiter.c.

◆ enforce

bool enforce
static

Definition at line 80 of file capture_arbiter.c.

◆ gps_changed_us

uint64_t gps_changed_us
static

Definition at line 91 of file capture_arbiter.c.

◆ gps_tow_ms

uint32_t gps_tow_ms
static

Definition at line 90 of file capture_arbiter.c.

◆ gps_week

uint32_t gps_week
static

Definition at line 90 of file capture_arbiter.c.

◆ guard

pthread_mutex_t guard = PTHREAD_MUTEX_INITIALIZER
static

Definition at line 66 of file capture_arbiter.c.

◆ have_saved

bool have_saved[COVERAGE_CAMERAS]
static

Definition at line 84 of file capture_arbiter.c.

◆ intent_lifetime_us

const uint64_t intent_lifetime_us = 2000000
static

Definition at line 87 of file capture_arbiter.c.

◆ last_saved

struct coverage_candidate last_saved[COVERAGE_CAMERAS]
static

Definition at line 83 of file capture_arbiter.c.

◆ latitude

double latitude
static

Definition at line 81 of file capture_arbiter.c.

◆ longitude

double longitude
static

Definition at line 81 of file capture_arbiter.c.

◆ minimum_overlap

double minimum_overlap = 0.3
static

Definition at line 85 of file capture_arbiter.c.

◆ origin_set

bool origin_set
static

Definition at line 80 of file capture_arbiter.c.

◆ pose_count

size_t pose_count
static

Definition at line 89 of file capture_arbiter.c.

◆ pose_head

size_t pose_head
static

Definition at line 89 of file capture_arbiter.c.

◆ poses

struct capture_pose poses[512]
static

Definition at line 88 of file capture_arbiter.c.

◆ result_count

size_t result_count
static

Definition at line 77 of file capture_arbiter.c.

◆ result_head

size_t result_head
static

Definition at line 77 of file capture_arbiter.c.

◆ results

union usher_capture_arbiter_result_union results[64]
static

Definition at line 76 of file capture_arbiter.c.

◆ saved_count

uint32_t saved_count
static

Definition at line 78 of file capture_arbiter.c.

◆ scope_active

bool scope_active
static

Definition at line 80 of file capture_arbiter.c.

◆ scope_lifetime_us

const uint64_t scope_lifetime_us = 750000
static

Definition at line 86 of file capture_arbiter.c.

◆ scope_mask

uint32_t scope_mask
static

Definition at line 78 of file capture_arbiter.c.

◆ scope_us

uint64_t scope_us
static

Definition at line 79 of file capture_arbiter.c.

◆ service_us

uint64_t service_us[COVERAGE_CAMERAS] = {1000000, 1000000, 1000000}
static

Definition at line 82 of file capture_arbiter.c.

◆ session

uint32_t session
static

Definition at line 78 of file capture_arbiter.c.

◆ waiting

Definition at line 73 of file capture_arbiter.c.