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
clock_alignment.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_CLOCK_ALIGNMENT_H
19#define USHER_CLOCK_ALIGNMENT_H
20
21/**
22 * @file clock_alignment.h
23 * @brief Bounded mapping between flight-controller microseconds and USHER monotonic time.
24 * @details The protocol exchanges a random token and controller receive/transmit times.
25 * The resulting interval is deliberately bounded, short-lived, and token-associated so
26 * stale replies or a wrapped 32-bit controller clock cannot geotag audio with false
27 * precision.
28 */
29
30#include <stddef.h>
31#include "usher_protocol.h"
32
33/** Maximum acceptable probe round trip; larger samples are not useful evidence. */
34#define CLOCK_ALIGNMENT_MAX_RTT_US UINT64_C(100000)
35/** Lifetime of a mapping before drift uncertainty makes it unsuitable for correlation. */
36#define CLOCK_ALIGNMENT_MAX_AGE_US UINT64_C(2000000)
37/** Conservative oscillator drift allowance used to widen projected intervals. */
38#define CLOCK_ALIGNMENT_DRIFT_PPM UINT64_C(1000)
39
40/** @brief Inclusive USHER monotonic-time bounds for a mapped controller timestamp. */
42 uint64_t earliest_us;
43 uint64_t latest_us;
44};
45
46/** @brief Stateful evidence for at most one pending and one accepted clock probe. */
59
60/** @brief Register a newly transmitted clock probe.
61 * @param clock Mutable synchronization state.
62 * @param token Nonzero random token carried on the wire.
63 * @param sent_us USHER monotonic timestamp at transmission.
64 * @return True if the probe is accepted as pending.
65 * @details Tokens must not repeat the pending or last accepted probe; this prevents a
66 * delayed reply from being mistaken for fresh timing evidence. */
67bool clock_alignment_request(struct clock_alignment *clock, union usher_clock_request_union token, uint64_t sent_us);
68/** @brief Validate a flight-controller clock reply and establish a mapping anchor.
69 * @param clock Mutable synchronization state.
70 * @param payload Exact reply payload bytes.
71 * @param length Payload length.
72 * @param received_us USHER monotonic receive timestamp.
73 * @return True only for a matching, bounded-latency reply.
74 * @details Rather than guessing a one-way delay, this stores an interval spanning the
75 * possible controller transmit instant, including bounded service time and clock drift. */
76bool clock_alignment_reply(struct clock_alignment *clock, const uint8_t *payload, size_t length, uint64_t received_us);
77/** @brief Project a controller timestamp into a conservative USHER time interval.
78 * @param clock Accepted alignment state.
79 * @param token Token proving the pose belongs to this probe epoch.
80 * @param fc_us 32-bit controller microsecond timestamp.
81 * @param now_us Current USHER monotonic time, used to reject stale/future projections.
82 * @param interval Receives inclusive projected bounds.
83 * @return True when @p interval contains a plausible mapping.
84 * @warning The result is an interval, not a claimed exact timestamp. */
85bool clock_alignment_map(const struct clock_alignment *clock, union usher_clock_request_union token,
86 uint32_t fc_us, uint64_t now_us, struct clock_interval *interval);
87
88#endif
bool clock_alignment_reply(struct clock_alignment *clock, const uint8_t *payload, size_t length, uint64_t received_us)
Validate a flight-controller clock reply and establish a mapping anchor.
bool clock_alignment_request(struct clock_alignment *clock, union usher_clock_request_union token, uint64_t sent_us)
Register a newly transmitted clock probe.
bool clock_alignment_map(const struct clock_alignment *clock, union usher_clock_request_union token, uint32_t fc_us, uint64_t now_us, struct clock_interval *interval)
Project a controller timestamp into a conservative USHER time interval.
Stateful evidence for at most one pending and one accepted clock probe.
uint64_t mapped_sent_us
union usher_clock_request_union pending_token
struct clock_interval anchor
union usher_clock_request_union mapped_token
Inclusive USHER monotonic-time bounds for a mapped controller timestamp.
uint64_t received_us
Definition usher.c:536
Shared FC/MORA byte-stream UART framing, messages and payload layouts.