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
pose_log.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/**
19 * @file pose_log.h
20 * @brief Non-blocking pose-evidence CSV logging API. */
21#ifndef USHER_POSE_LOG_H
22#define USHER_POSE_LOG_H
23
24#include <stddef.h>
25#include <stdint.h>
26#include "clock_alignment.h"
27
28/** @brief Optional token-bound evidence mapping a controller pose interval to MORA time. */
30 union usher_clock_request_union token; /**< Request token joining this pose to one clock exchange. */
31 struct clock_interval sample_time; /**< Conservative monotonic interval covering the FC sample. */
32 uint64_t probe_sent_us; /**< Host monotonic send time for the matching request. */
33 uint64_t probe_received_us; /**< Host monotonic receive time for the matching response. */
34 uint32_t probe_receive_fc_us; /**< Flight-controller receive timestamp from the exchange. */
35 uint32_t probe_transmit_fc_us; /**< Flight-controller transmit timestamp from the exchange. */
36 bool mapped; /**< True only when token and interval passed clock-alignment validation. */
37};
38
39/** @brief Snapshot counters for accepted, flushed, dropped, and rejected pose records. */
41 uint64_t accepted; /**< Records admitted to the in-memory queue. */
42 uint64_t synced; /**< Records in batches successfully fdatasync'ed. */
43 uint64_t dropped; /**< Valid records discarded due to lock/capacity/I/O pressure. */
44 uint64_t rejected; /**< Invalid payloads or clock evidence not admitted. */
45 int error; /**< First writer/startup errno-style failure, or zero. */
46};
47
48/** @brief Start a durable asynchronous CSV session, or disable logging when directory is empty.
49 * @param directory Writable destination directory, optionally using `~` shorthand.
50 * @return 0 on active/disabled success, otherwise -1. */
51int pose_log_start(const char *directory);
52/** @brief Validate and enqueue a raw pose payload without clock mapping evidence.
53 * @return 1 when queued, 0 when intentionally dropped due to contention/capacity, or -1 when invalid. */
54int pose_log_record(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us);
55/** @brief Validate and enqueue a pose payload with optional mapped timing provenance.
56 * @details Trylock protects capture latency: logging is best-effort evidence, never a reason
57 * to block the real-time UART path. */
58int pose_log_record_clocked(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us,
59 const struct pose_clock_evidence *evidence);
60/** @brief Return a synchronized snapshot of logging health and loss counters. */
62/** @brief Flush queued records, join the writer, and close the CSV file.
63 * @return 0 after durable orderly shutdown, or -1 if a pending I/O error exists. */
64int pose_log_stop(void);
65
66#endif
Bounded mapping between flight-controller microseconds and USHER monotonic time.
char evidence[8192]
Definition lwir_image.c:66
struct pose_log_stats pose_log_status(void)
Return a synchronized snapshot of logging health and loss counters.
Definition pose_log.c:365
int pose_log_record(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us)
Validate and enqueue a raw pose payload without clock mapping evidence.
Definition pose_log.c:296
int pose_log_record_clocked(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us, const struct pose_clock_evidence *evidence)
Validate and enqueue a pose payload with optional mapped timing provenance.
Definition pose_log.c:307
int pose_log_start(const char *directory)
Start a durable asynchronous CSV session, or disable logging when directory is empty.
Definition pose_log.c:197
int pose_log_stop(void)
Flush queued records, join the writer, and close the CSV file.
Definition pose_log.c:375
Inclusive USHER monotonic-time bounds for a mapped controller timestamp.
Optional token-bound evidence mapping a controller pose interval to MORA time.
Definition pose_log.h:29
union usher_clock_request_union token
Definition pose_log.h:30
uint64_t probe_sent_us
Definition pose_log.h:32
uint32_t probe_transmit_fc_us
Definition pose_log.h:35
uint64_t probe_received_us
Definition pose_log.h:33
struct clock_interval sample_time
Definition pose_log.h:31
uint32_t probe_receive_fc_us
Definition pose_log.h:34
Snapshot counters for accepted, flushed, dropped, and rejected pose records.
Definition pose_log.h:40
uint64_t accepted
Definition pose_log.h:41
uint64_t dropped
Definition pose_log.h:43
uint64_t rejected
Definition pose_log.h:44
uint64_t synced
Definition pose_log.h:42