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
ear_cam_pipe.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 ear_cam_pipe.h
20 * @brief Audio/pose adapter and zero-copy snapshot API for the EAR backend.
21 * @details Configuration and active-session functions belong to USHER's serial
22 * owner. Only snapshot solve/number/render/release are intended for the finalizer.
23 * Configure before initialization; drain detached workers before deinitialization.
24 */
25#ifndef USHER_EAR_CAM_PIPE_H
26#define USHER_EAR_CAM_PIPE_H
27
28#include <stdbool.h>
29#include <stddef.h>
30#include <stdint.h>
31
32#include "usher_protocol.h"
33#include "capture_timing.h"
35
36/**
37 * @brief Set the startup-only pose callback, later called without waiting on the serial owner.
38 * @param lookup Borrowed callback with host lifetime; NULL selects request-pose fallback.
39 * @details Never invoked by the audio reader or finalizer; shared navigation state stays owner-local.
40 */
41void ear_cam_pipe_set_pose_lookup(bool (*lookup)(struct capture_observation *, uint64_t));
42/**
43 * @brief Copy a startup ALSA PCM name into bounded adapter-owned storage.
44 * @param device Nonempty name; must fit including its terminating NUL.
45 * @return True when copied; false for NULL/empty/oversized input or running capture threads.
46 * @details No shell is involved. Every child retry receives the same owned name.
47 */
48bool ear_cam_pipe_set_device(const char *device);
49/** @brief Copy an assignment path before the microphone supervisor starts.
50 * @param settings Nonempty path forwarded to every server retry without shell expansion.
51 * @return True for a complete bounded copy; false while supervision is active or input is invalid. */
52bool ear_cam_pipe_set_settings(const char *settings);
53/** @brief Retry bounded pending audio windows when the serial owner receives new poses. */
55
57struct ear_loudest_spot;
58
59/**
60 * @brief Begin/reset active collection without solving or waiting for log I/O.
61 * @param session_id Token retained in audit rows; backend admission validates it before this call.
62 * @return False when no active or free buffer exists; true after resetting active counts.
63 * @details Does not evict worker-owned snapshots. The active buffer is serial-owner-only.
64 */
65bool ear_cam_pipe_begin_session(uint32_t session_id);
66/**
67 * @brief Best-effort enqueue of a correlated result row on the serial owner.
68 * @param session_id Token identifying the completed snapshot, not necessarily the current session.
69 * @param result Borrowed estimate, copied into a row before return; NULL is ignored.
70 * @details Only the log worker accesses its FILE. A dropped audit row is not a lost point completion.
71 */
72void ear_cam_pipe_log_result(uint32_t session_id, const struct ear_loudest_spot *result);
73/**
74 * @brief Transfer active storage to an immutable worker snapshot without copying samples.
75 * @return Owned snapshot, or NULL if no active buffer exists.
76 * @details Serial-owner-only. Pending pose windows are resolved/fallback-committed
77 * before freezing count; active collection stays disabled until the next successful begin.
78 * @warning Caller must eventually release exactly once, after all readers stop using it.
79 */
81/**
82 * @brief Solve immutable detached evidence without touching current-session state.
83 * @param snapshot Borrowed owned snapshot, which must remain unreleased throughout this call.
84 * @param result Required estimate destination, cleared before invoking the core.
85 * @return Core solver status: 0 for an estimate, -1 for invalid/insufficient evidence or arguments.
86 * @details Worker-safe; shared core workspace serializes concurrent solves. No ownership transfer.
87 */
89/**
90 * @brief Read the last request number from immutable evidence.
91 * @param snapshot Borrowed unreleased snapshot, or NULL.
92 * @return Newest stored request number, or zero for NULL/empty evidence.
93 */
94int32_t ear_cam_pipe_snapshot_number(const struct ear_session_snapshot *snapshot);
95/**
96 * @brief Render detached evidence using collision-safe session-tagged JPEG/CSV names.
97 * @param snapshot Borrowed owned snapshot; remains immutable and unreleased during I/O.
98 * @param session_id Required nonzero correlation token for file naming and CSV provenance.
99 * @param result Required borrowed estimate; an invalid estimate may still produce evidence.
100 * @param filename Destination path buffer; cleared by the renderer on handled creation failure.
101 * @param filename_size Capacity of filename including its terminating NUL.
102 * @param simulated Select the simulated-image prefix, not a different rendering algorithm.
103 * @return 0 for decorated JPEG success, -1 for invalid arguments or primary rendering failure.
104 * @details Worker-safe. CSV, undecorated field and .geo errors are reported separately;
105 * JPEG success does not guarantee all evidence products or power-loss durability.
106 */
107int ear_cam_pipe_snapshot_render(const struct ear_session_snapshot *snapshot, uint32_t session_id,
108 const struct ear_loudest_spot *result, char *filename,
109 size_t filename_size, bool simulated);
110/**
111 * @brief Return detached storage to admission after all snapshot access has ended.
112 * @param snapshot Previously detached owned snapshot; NULL is a no-op.
113 * @warning The pointer and sample contents must not be used after release, even
114 * if the backing array still exists. A new serial-owner session may overwrite it.
115 */
117
118/**
119 * @brief Start EARcam sampling or its deterministic simulated-source replacement.
120 * @param unused Reserved for the common camera-backend initialization signature; ignored.
121 * @return 0 when supervision is started (not hardware readiness); -1 for setup failure.
122 * @details A missing microphone is deliberately not fatal. The optical pipeline can continue
123 * operating while an independent supervisor retries the server. Configure the
124 * simulated source and frequency band before calling this function.
125 */
126int ear_cam_pipe_init(const char *unused);
127
128/**
129 * @brief Stop EARcam activity and release its process and descriptors.
130 * @details Safe after a partially successful initialization. Call this after the final render
131 * or solve because it discards unfinalized session samples.
132 */
133void ear_cam_pipe_deinit(void);
134
135/**
136 * @brief Report readiness of the configured live or simulated measurement source.
137 * @return True after the live handshake or simulated initialization; false after teardown/lost readiness.
138 * @details Ready does not guarantee a fresh sample or prove live hardware is present;
139 * simulated mode intentionally has no microphone process and also reports ready.
140 */
141bool ear_cam_pipe_ready(void);
142
143/**
144 * @brief Replace microphone input with a virtual fixed loudspeaker for NPS or desk tests.
145 * @param lat_deg Source latitude in degrees.
146 * @param lon_deg Source longitude in degrees.
147 * @param level_db_at_1m Sound level at one metre in decibels.
148 * @details Must be called before @c ear_cam_pipe_init(). Simulation avoids ALSA and the
149 * external EARcam process while preserving the same geotagging and fusion interface.
150 */
151void ear_cam_pipe_set_simulated_source(double lat_deg, double lon_deg, double level_db_at_1m);
152
153/**
154 * @brief Set the live EARcam tone-search band.
155 * @param low_cut_hz Lower cutoff in hertz, or zero to retain EARcam's default.
156 * @param high_cut_hz Upper cutoff in hertz, or zero to retain EARcam's default.
157 * @details Must be called before @c ear_cam_pipe_init() because the values become arguments
158 * of the persistent external process. Invalid ordering is rejected by the caller's CLI path.
159 */
160void ear_cam_pipe_set_band(double low_cut_hz, double high_cut_hz);
161
162/**
163 * @brief Associate the newest sound window with one flight-controller shot pose.
164 * @param shot Flight pose and shot number received from USHER transport.
165 * @return 0 when evidence is committed or admitted to the bounded pose queue;
166 * -1 for invalid input, unavailable/stale data or duplicate timed windows.
167 * @details Timed windows await pose evidence in a fixed queue for at most 200 ms;
168 * unresolved or legacy measurements retain their labelled request-pose fallback.
169 * Only the newest live measurement is read at each request, not every audio window.
170 * Capacity pressure retains the newest half of active samples, never a worker snapshot.
171 * Server recovery and CSV I/O run independently. This call never waits for them.
172 */
173int ear_cam_pipe_record(const union dc_shot_union *shot);
174
175/**
176 * @brief Fuse the session into its final loudest-spot result and clear stored samples.
177 * @param result Destination for the solved or invalid result.
178 * @return Core solver status: 0 for an estimate, -1 for insufficient evidence or invalid arguments.
179 * @details Finalization consumes the session so the next survey cannot accidentally mix old
180 * and new flight legs. This legacy synchronous call solves committed samples and
181 * joins the log writer; it is not suitable for a latency-sensitive UART callback.
182 * Resolve pending poses first (ear_cam_pipe_solve() forces their fallback), and render
183 * before clearing samples. Prefer detach/solve/render/release for asynchronous sessions.
184 */
186
187/**
188 * @brief Solve the accumulated session without clearing it.
189 * @param result Destination for the current estimate.
190 * @return Core solver status: 0 for an estimate, -1 for insufficient evidence or invalid arguments.
191 * @details Use for refinement decisions. Unlike @c ear_cam_pipe_finish(), subsequent records
192 * remain part of the same survey session. Serial-owner-only; pending poses are
193 * forced to their bounded fallback before this synchronous solve.
194 */
196
197/**
198 * @brief Render the current session as a north-up acoustic evidence JPEG.
199 * @param result Solved loudest-spot estimate to mark on the image.
200 * @param filename Destination buffer receiving the JPEG path.
201 * @param filename_size Capacity of @p filename.
202 * @param simulated True when rendering NPS/desk simulated data.
203 * @return 0 on success; -1 if inputs, session data, or output creation fail.
204 * @details Must be called before @c ear_cam_pipe_finish() clears the session. The JPEG and
205 * sidecar preserve the sampled field and final estimate for post-flight review.
206 */
207int ear_cam_pipe_render(const struct ear_loudest_spot *result, char *filename, size_t filename_size,
208 bool simulated);
209
210/**
211 * @brief Get the shot number associated with the newest stored acoustic sample.
212 * @return The newest shot number, or 0 when the session is empty.
213 */
214int32_t ear_cam_pipe_last_shot_nr(void);
215
216#endif
Sensor observation times, aligned poses, and optional frame-arrival evidence.
static bool simulated
bool ear_cam_pipe_set_settings(const char *settings)
Copy an assignment path before the microphone supervisor starts.
bool ear_cam_pipe_set_device(const char *device)
Copy a startup ALSA PCM name into bounded adapter-owned storage.
int ear_cam_pipe_snapshot_solve(const struct ear_session_snapshot *snapshot, struct ear_loudest_spot *result)
Solve immutable detached evidence without touching current-session state.
bool ear_cam_pipe_ready(void)
Report readiness of the configured live or simulated measurement source.
int ear_cam_pipe_init(const char *unused)
Start EARcam sampling or its deterministic simulated-source replacement.
int ear_cam_pipe_snapshot_render(const struct ear_session_snapshot *snapshot, uint32_t session_id, const struct ear_loudest_spot *result, char *filename, size_t filename_size, bool simulated)
Render detached evidence using collision-safe session-tagged JPEG/CSV names.
int32_t ear_cam_pipe_snapshot_number(const struct ear_session_snapshot *snapshot)
Read the last request number from immutable evidence.
void ear_cam_pipe_set_pose_lookup(bool(*lookup)(struct capture_observation *, uint64_t))
Set the startup-only pose callback, later called without waiting on the serial owner.
void ear_cam_pipe_log_result(uint32_t session_id, const struct ear_loudest_spot *result)
Best-effort enqueue of a correlated result row on the serial owner.
int ear_cam_pipe_finish(struct ear_loudest_spot *result)
Fuse the session into its final loudest-spot result and clear stored samples.
void ear_cam_pipe_deinit(void)
Stop EARcam activity and release its process and descriptors.
struct ear_session_snapshot * ear_cam_pipe_detach_session(void)
Transfer active storage to an immutable worker snapshot without copying samples.
bool ear_cam_pipe_begin_session(uint32_t session_id)
Begin/reset active collection without solving or waiting for log I/O.
int ear_cam_pipe_solve(struct ear_loudest_spot *result)
Solve the accumulated session without clearing it.
int ear_cam_pipe_render(const struct ear_loudest_spot *result, char *filename, size_t filename_size, bool simulated)
Render the current session as a north-up acoustic evidence JPEG.
void ear_cam_pipe_update_pose(void)
Retry bounded pending audio windows when the serial owner receives new poses.
int ear_cam_pipe_record(const union dc_shot_union *shot)
Associate the newest sound window with one flight-controller shot pose.
void ear_cam_pipe_set_band(double low_cut_hz, double high_cut_hz)
Set the live EARcam tone-search band.
void ear_cam_pipe_snapshot_release(struct ear_session_snapshot *snapshot)
Return detached storage to admission after all snapshot access has ended.
int32_t ear_cam_pipe_last_shot_nr(void)
Get the shot number associated with the newest stored acoustic sample.
void ear_cam_pipe_set_simulated_source(double lat_deg, double lon_deg, double level_db_at_1m)
Replace microphone input with a virtual fixed loudspeaker for NPS or desk tests.
Sensor-independent acoustic samples and ground-source estimates.
Estimated ground source, not a surveyed target or guaranteed alarm detection.
Definition earcam_core.h:37
Statically reserved sample buffer with a single active or detached owner.
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534
Shared FC/MORA byte-stream UART framing, messages and payload layouts.