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_timing.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_TIMING_H
19#define USHER_CAPTURE_TIMING_H
20
21/**
22 * @file capture_timing.h
23 * @brief Sensor observation times, aligned poses, and optional frame-arrival evidence.
24 * @details Timing is deliberately represented with monotonic clocks only; wall-clock
25 * adjustments must never turn an otherwise valid capture into a negative duration.
26 */
27
28#include <stdbool.h>
29#include <stdint.h>
30#include "usher_protocol.h"
31
40
54
55/**
56 * @brief Check that an observation supplies a usable time interval.
57 * @param observation Nullable observation to check.
58 * @return True for a known timing kind with an ordered, nonzero-start interval
59 * spanning no more than 20 seconds.
60 * @details Check endpoint order before subtracting unsigned timestamps. This
61 * validates the interval only, not its pose, sequence, or frame association.
62 */
63static inline bool capture_observation_valid(const struct capture_observation *observation)
64{
65 return observation != 0 && observation->kind > CAPTURE_TIME_UNKNOWN
66 && observation->kind <= CAPTURE_TIME_AUDIO_WINDOW && observation->earliest_us > 0
67 && observation->latest_us >= observation->earliest_us
68 && observation->latest_us - observation->earliest_us <= UINT64_C(20000000);
69}
70
71/**
72 * @brief Distinguish exposure evidence from other valid observation times.
73 * @param observation Nullable observation to classify.
74 * @return True for a valid sensor, calibrated, or shutter-window interval.
75 * @details Downstream projection must not substitute frame delivery or audio
76 * timing for exposure, even if those intervals are structurally valid.
77 */
78static inline bool capture_observation_exposure(const struct capture_observation *observation)
79{
80 return capture_observation_valid(observation)
81 && observation->kind >= CAPTURE_TIME_SENSOR_EXPOSURE
82 && observation->kind <= CAPTURE_TIME_SHUTTER_WINDOW;
83}
84
85/**
86 * @brief Bound exposure time using calibrated frame delivery latency.
87 * @param[in,out] observation Record to update; existing pose validity is cleared.
88 * @param arrival_us Frame arrival in local monotonic microseconds.
89 * @param minimum_us Shortest calibrated exposure-to-arrival delay, in microseconds.
90 * @param maximum_us Longest calibrated exposure-to-arrival delay, in microseconds.
91 * @return True if the interval was written; false leaves the record unchanged.
92 * @details The longest delay gives the earliest plausible exposure. Reject bounds
93 * that would underflow or reach time zero, and require a fresh pose alignment after
94 * changing the interval.
95 */
96static inline bool capture_observation_latency(struct capture_observation *observation,
97 uint64_t arrival_us, uint64_t minimum_us, uint64_t maximum_us)
98{
99 if (observation == 0 || minimum_us > maximum_us || maximum_us > UINT64_C(2000000)
100 || arrival_us <= maximum_us) return false;
101 observation->earliest_us = arrival_us - maximum_us;
102 observation->latest_us = arrival_us - minimum_us;
104 observation->pose_valid = false;
105 return true;
106}
107
108/**
109 * @brief Get the text label used when recording observation timing.
110 * @param kind Source of the timing evidence.
111 * @return Borrowed static string, or @c unavailable for an unrecognized kind.
112 * @details Labels retain the distinction between an exposure estimate and frame
113 * delivery so that downstream log readers do not conflate the two.
114 */
115static inline const char *capture_time_name(enum capture_time_kind kind)
116{
117 switch (kind) {
118 case CAPTURE_TIME_SENSOR_EXPOSURE: return "sensor_exposure_interval";
119 case CAPTURE_TIME_CALIBRATED_EXPOSURE: return "calibrated_exposure_interval";
120 case CAPTURE_TIME_SHUTTER_WINDOW: return "command_to_download_interval";
121 case CAPTURE_TIME_FRAME_ARRIVAL: return "frame_arrival_not_exposure";
122 case CAPTURE_TIME_AUDIO_WINDOW: return "audio_window";
123 default: return "unavailable";
124 }
125}
126
127/**
128 * @brief Shared observation evidence with optional LWIR request/frame-delivery timing.
129 * @details A non-callback capture has no callback sequence evidence. A callback-backed
130 * capture must provide a strictly later arrival timestamp and a nonzero sequence number,
131 * so consumers can distinguish a fresh frame from a stale parser result.
132 */
134 /** Server request acceptance in monotonic microseconds. */
136 /** Monotonic microseconds when the selected frame arrived. */
138 /** Producer sequence number for callback delivery; zero for polling delivery. */
140 /** Callback frames dropped before this frame; must be lower than @c callback_sequence. */
142 /** True when arrival evidence originated from the asynchronous callback path. */
145};
146
147/**
148 * @brief Check whether timing evidence is internally consistent and recent.
149 * @param timing Evidence to inspect.
150 * @return True for a plausible request/arrival pair, false otherwise.
151 * @details The 20-second bound detects stale parser state without rejecting normal
152 * warmup/USB recovery behavior. Callback and polling modes have intentionally distinct
153 * sequence invariants, reflected in the final conditional.
154 */
155static inline bool capture_timing_valid(const struct capture_timing *timing)
156{
157 return timing != 0 && timing->request_monotonic_us > 0
158 && timing->arrival_monotonic_us >= timing->request_monotonic_us
159 && timing->arrival_monotonic_us - timing->request_monotonic_us <= UINT64_C(20000000)
160 && (timing->callback_arrival
161 ? timing->callback_sequence > 0 && timing->callback_drops < timing->callback_sequence
162 && timing->arrival_monotonic_us > timing->request_monotonic_us
163 : timing->callback_sequence == 0 && timing->callback_drops == 0);
164}
165
166#endif
static bool capture_observation_latency(struct capture_observation *observation, uint64_t arrival_us, uint64_t minimum_us, uint64_t maximum_us)
Bound exposure time using calibrated frame delivery latency.
static bool capture_timing_valid(const struct capture_timing *timing)
Check whether timing evidence is internally consistent and recent.
static bool capture_observation_valid(const struct capture_observation *observation)
Check that an observation supplies a usable time interval.
capture_time_kind
@ CAPTURE_TIME_UNKNOWN
@ CAPTURE_TIME_AUDIO_WINDOW
@ CAPTURE_TIME_SHUTTER_WINDOW
@ CAPTURE_TIME_SENSOR_EXPOSURE
@ CAPTURE_TIME_CALIBRATED_EXPOSURE
@ CAPTURE_TIME_FRAME_ARRIVAL
static const char * capture_time_name(enum capture_time_kind kind)
Get the text label used when recording observation timing.
static bool capture_observation_exposure(const struct capture_observation *observation)
Distinguish exposure evidence from other valid observation times.
enum capture_time_kind kind
union dc_shot_union pose
Shared observation evidence with optional LWIR request/frame-delivery timing.
uint64_t callback_drops
struct capture_observation observation
uint64_t request_monotonic_us
uint64_t arrival_monotonic_us
uint64_t callback_sequence
uint64_t maximum_us
Definition usher.c:592
uint64_t minimum_us
Definition usher.c:592
Shared FC/MORA byte-stream UART framing, messages and payload layouts.