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_camera_backend.c
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_camera_backend.c
20 * @brief EAR-owned survey admission, finalization and generic point completions.
21 * @details USHER's serial owner calls lifecycle/configuration/poll hooks. One
22 * joinable worker solves immutable snapshots and writes evidence; it never owns
23 * UART or live pose lookup. A small wake channel signals mailbox state, not data.
24 */
25#include "ear_camera_backend.h"
26#include "ear_cam_pipe.h"
27#include "image_exif.h"
28
29#include <errno.h>
30#include <limits.h>
31#include <math.h>
32#include <pthread.h>
33#include <stdio.h>
34#include <string.h>
35#include <sys/socket.h>
36#include <unistd.h>
37
38#ifndef USHER_SODA
39 #define USHER_SODA "./bin/soda"
40#endif
41
42/** Two jobs match the adapter's two buffers: stopped evidence is never evicted. */
43#define EAR_FINALIZE_JOB_COUNT 2
44#define EAR_COMPLETION_ENDPOINT_COUNT 2
45#define EAR_COMPLETION_DRAIN_BYTES 16
46#define EAR_EVIDENCE_PATH_CAPACITY 512
47#define EAR_LATITUDE_LIMIT_DEG 90
48#define EAR_LONGITUDE_LIMIT_DEG 180
49#define EAR_COORDINATE_UNITS_PER_DEG 1e7
50#define EAR_MILLIMETERS_PER_METER 1000.0
51#define EAR_QUALITY_UNITS_PER_SCORE 1000.0
52#define EAR_METRIC_UNITS_PER_DB 100.0
53/** Legacy dc_shot groundalt carries AGL in Q8 metres, unlike CAM_POINT_RESULT millimetres. */
54#define EAR_SHOT_AGL_UNITS_PER_METER 256.0
55
56/* Serial-owner state is separate from the mutex-protected worker mailbox. Do
57 * not call start/stop/poll/configure concurrently from additional owner threads. */
60/**
61 * @brief One reservation progressing through snapshot -> point -> evidence completion.
62 * @details Start reserves a slot before collecting audio. Stop attaches an owned
63 * immutable snapshot. Poll consumes the point, but the slot remains occupied
64 * until evidence work finishes, preventing reuse while the worker still uses it.
65 */
74static uint64_t ear_finalize_order;
75static pthread_mutex_t ear_finalize_mutex = PTHREAD_MUTEX_INITIALIZER;
76static pthread_cond_t ear_finalize_available = PTHREAD_COND_INITIALIZER;
77static pthread_t ear_finalize_thread;
80
81/** @brief Guard finite values and integer conversion ranges before marking a wire point valid. */
82static bool ear_point_valid(const struct ear_loudest_spot *spot)
83{
84 return spot && spot->valid && isfinite(spot->lat_deg) && isfinite(spot->lon_deg)
86 && (spot->lat_deg != 0 || spot->lon_deg != 0)
87 && isfinite(spot->agl_m) && spot->agl_m >= 0 && spot->agl_m <= INT32_MAX / EAR_MILLIMETERS_PER_METER
88 && isfinite(spot->alt_m) && spot->alt_m >= INT32_MIN / EAR_MILLIMETERS_PER_METER
89 && spot->alt_m <= INT32_MAX / EAR_MILLIMETERS_PER_METER
90 && isfinite(spot->confidence) && spot->confidence >= 0 && spot->confidence <= 1
91 && isfinite(spot->level_db) && spot->level_db >= INT32_MIN / EAR_METRIC_UNITS_PER_DB
92 && spot->level_db <= INT32_MAX / EAR_METRIC_UNITS_PER_DB;
93}
94
95/** @brief Notify the serial owner without blocking; mailbox flags remain authoritative if full. */
96static void wake_ear_result_owner(void)
97{
98 const char notification = 1;
99 ssize_t result;
100 do { result = write(ear_finalize_wake[1], &notification, sizeof(notification)); } while (result < 0 && errno == EINTR);
101 if (result < 0 && errno != EAGAIN && errno != EWOULDBLOCK)
102 fprintf(stderr, "USHER:\tEAR completion wake failed: %s\n", strerror(errno));
103}
104
105/**
106 * @brief Drain stopped sessions in admission order until shutdown has no work left.
107 * @details The point mailbox is published before potentially slow CSV/JPEG/EXIF
108 * and optional SODA submission. Never perform UART sends or live pose lookups here.
109 */
110static void *finalize_ear_sessions(void *unused)
111{
112 (void)unused;
113 for (;;) {
114 pthread_mutex_lock(&ear_finalize_mutex);
115 struct ear_finalize_job *job = NULL;
116 for (;;) {
117 for (size_t slot = 0; slot < EAR_FINALIZE_JOB_COUNT; ++slot) {
118 struct ear_finalize_job *candidate = &ear_finalize_jobs[slot];
119 if (candidate->in_use && candidate->snapshot && !candidate->taken
120 && (!job || candidate->order < job->order)) job = candidate;
121 }
122 if (job || ear_finalize_stopping) break;
123 pthread_cond_wait(&ear_finalize_available, &ear_finalize_mutex);
124 }
125 if (!job) { pthread_mutex_unlock(&ear_finalize_mutex); return NULL; }
126 job->taken = true;
127 pthread_mutex_unlock(&ear_finalize_mutex);
128 struct ear_loudest_spot spot = {0};
129 if (ear_cam_pipe_snapshot_solve(job->snapshot, &spot) != 0) spot.valid = false;
130 spot.valid = ear_point_valid(&spot);
131 pthread_mutex_lock(&ear_finalize_mutex);
132 job->spot = spot;
133 job->point_ready = true;
134 pthread_mutex_unlock(&ear_finalize_mutex);
136
137 char sound_picture[EAR_EVIDENCE_PATH_CAPACITY];
138 if (ear_cam_pipe_snapshot_render(job->snapshot, job->session_id, &spot,
139 sound_picture, sizeof(sound_picture), job->simulated) == 0) {
140 union dc_shot_union picture_shot = {0};
141 picture_shot.data.nr = ear_cam_pipe_snapshot_number(job->snapshot);
142 if (spot.valid) {
143 picture_shot.data.lat = (int32_t)llround(spot.lat_deg * EAR_COORDINATE_UNITS_PER_DEG);
144 picture_shot.data.lon = (int32_t)llround(spot.lon_deg * EAR_COORDINATE_UNITS_PER_DEG);
145 picture_shot.data.alt = (int32_t)llround(spot.alt_m * EAR_MILLIMETERS_PER_METER);
146 picture_shot.data.groundalt = (int32_t)llround(spot.agl_m * EAR_SHOT_AGL_UNITS_PER_METER);
147 }
148 if (image_exif_write(sound_picture, &picture_shot) == 0) {
149 printf("USHER:\tEAR session %u sound picture %s\n", job->session_id, sound_picture);
150 printf("Photo take %d\n", picture_shot.data.nr);
151 if (ear_host.queue_analysis) ear_host.queue_analysis(sound_picture, &picture_shot, USHER_CAMERA_EARCAM);
152 } else fprintf(stderr, "USHER:\tEAR session %u EXIF failed; image retained: %s\n", job->session_id, sound_picture);
153 } else fprintf(stderr, "USHER:\tEAR session %u sound-picture rendering failed\n", job->session_id);
155 pthread_mutex_lock(&ear_finalize_mutex);
156 job->evidence_done = true;
157 pthread_mutex_unlock(&ear_finalize_mutex);
159 }
160}
161
162/**
163 * @brief Consume one completion on the serial owner and convert physical units once.
164 * @return True when result receives a correlated valid or invalid point.
165 * @details Wake bytes may coalesce; scan mailbox flags even after draining the
166 * socket. USHER retains responsibility for token correlation and actual UART delivery.
167 */
169{
170 if (!result) return false;
171 if (ear_finalize_wake[0] >= 0) {
172 char notifications[EAR_COMPLETION_DRAIN_BYTES];
173 ssize_t count;
174 do { count = read(ear_finalize_wake[0], notifications, sizeof(notifications)); }
175 while (count > 0 || (count < 0 && errno == EINTR));
176 }
177 for (size_t slot = 0; slot < EAR_FINALIZE_JOB_COUNT; ++slot) {
178 pthread_mutex_lock(&ear_finalize_mutex);
179 struct ear_finalize_job *job = &ear_finalize_jobs[slot];
180 const bool ready = job->in_use && job->point_ready;
181 const uint32_t session_id = job->session_id;
182 const struct ear_loudest_spot spot = job->spot;
183 job->point_ready = false;
184 if (job->in_use && job->evidence_done) *job = (struct ear_finalize_job) {0};
185 pthread_mutex_unlock(&ear_finalize_mutex);
186 if (!ready) continue;
187 ear_cam_pipe_log_result(session_id, &spot);
188 printf("USHER:\tEAR session %u result valid=%d lat=%.7f lon=%.7f conf=%.3f samples=%u/%u\n",
189 session_id, spot.valid, spot.lat_deg, spot.lon_deg, spot.confidence, spot.used_count, spot.sample_count);
190 *result = (struct camera_point_result) {.session_id = session_id, .valid = ear_point_valid(&spot)};
191 if (result->valid) {
192 result->lat = (int32_t)llround(spot.lat_deg * EAR_COORDINATE_UNITS_PER_DEG);
193 result->lon = (int32_t)llround(spot.lon_deg * EAR_COORDINATE_UNITS_PER_DEG);
194 result->alt_mm = (int32_t)llround(spot.alt_m * EAR_MILLIMETERS_PER_METER);
195 result->agl_mm = (int32_t)llround(spot.agl_m * EAR_MILLIMETERS_PER_METER);
196 result->quality = (int32_t)llround(spot.confidence * EAR_QUALITY_UNITS_PER_SCORE);
197 result->metric = (int32_t)llround(spot.level_db * EAR_METRIC_UNITS_PER_DB);
198 }
199 return true;
200 }
201 return false;
202}
203
204/**
205 * @brief Reserve both finalizer capacity and adapter storage before listening.
206 * @return False for zero token, shutdown, exhausted capacity or worker/buffer failure.
207 * @details Replacing an unfinished active session releases only its reservation;
208 * stopped snapshots stay admitted. Generic USHER routing handles duplicate tokens.
209 */
210static bool ear_start(uint32_t session_id)
211{
212 if (!session_id) return false;
213 earcam_session_active = false;
214 if (!earcam_active || !ear_host.running || !capture_running(ear_host.running)) return false;
215 pthread_mutex_lock(&ear_finalize_mutex);
216 if (current_ear_job) { *current_ear_job = (struct ear_finalize_job) {0}; current_ear_job = NULL; }
217 if (ear_finalize_stopping || ear_finalize_order == UINT64_MAX) { pthread_mutex_unlock(&ear_finalize_mutex); return false; }
219 if (socketpair(AF_UNIX, SOCK_STREAM | SOCK_NONBLOCK | SOCK_CLOEXEC, 0, ear_finalize_wake) != 0) {
221 pthread_mutex_unlock(&ear_finalize_mutex);
222 fprintf(stderr, "USHER:\tEAR finalizer completion channel unavailable: %s\n", strerror(errno));
223 return false;
224 }
225 int result = pthread_create(&ear_finalize_thread, NULL, finalize_ear_sessions, NULL);
226 if (result != 0) {
229 pthread_mutex_unlock(&ear_finalize_mutex);
230 fprintf(stderr, "USHER:\tEAR finalizer unavailable: %s\n", strerror(result));
231 return false;
232 }
234 }
235 for (size_t slot = 0; slot < EAR_FINALIZE_JOB_COUNT; ++slot) {
236 if (!ear_finalize_jobs[slot].in_use) {
239 .session_id = session_id,
240 .order = ++ear_finalize_order, .in_use = true, .simulated = earcam_simulated
241 };
242 break;
243 }
244 }
245 pthread_mutex_unlock(&ear_finalize_mutex);
246 if (!current_ear_job) return false;
247 if (ear_cam_pipe_begin_session(session_id)) { earcam_session_active = true; return true; }
248 pthread_mutex_lock(&ear_finalize_mutex);
249 *current_ear_job = (struct ear_finalize_job) {0}; current_ear_job = NULL;
250 pthread_mutex_unlock(&ear_finalize_mutex);
251 return false;
252}
253
254/**
255 * @brief Validate the active token before a zero-copy snapshot handoff.
256 * @return True only when an immutable session was queued for the worker.
257 * @details Failed detach releases the reservation; a wrong token cannot stop listening.
258 */
259static bool ear_stop(uint32_t session_id)
260{
261 const bool finalize = earcam_active && earcam_session_active && current_ear_job
262 && current_ear_job->session_id == session_id;
263 if (!finalize) return false;
264 earcam_session_active = false;
266 pthread_mutex_lock(&ear_finalize_mutex);
267 if (snapshot) current_ear_job->snapshot = snapshot;
268 else *current_ear_job = (struct ear_finalize_job) {0};
269 current_ear_job = NULL;
270 pthread_cond_signal(&ear_finalize_available);
271 pthread_mutex_unlock(&ear_finalize_mutex);
272 return snapshot != NULL;
273}
274
275/**
276 * @brief Close admission and join all admitted stopped-session evidence work.
277 * @details Completed point mailboxes remain pollable after the wake channel closes.
278 * This is orderly draining, not a hard filesystem-I/O deadline or power-loss guarantee.
279 */
280static void ear_drain(void)
281{
282 earcam_session_active = false;
283 pthread_mutex_lock(&ear_finalize_mutex);
285 pthread_cond_signal(&ear_finalize_available);
286 pthread_mutex_unlock(&ear_finalize_mutex);
287 if (ear_finalize_started) pthread_join(ear_finalize_thread, NULL);
288 ear_finalize_started = false;
289 for (size_t index = 0; index < EAR_COMPLETION_ENDPOINT_COUNT; ++index) {
290 if (ear_finalize_wake[index] >= 0) close(ear_finalize_wake[index]);
291 ear_finalize_wake[index] = -1;
292 }
293}
294
295/** @brief Whether the serial owner should admit EAR samples for the current session. */
296static bool ear_listening(void) { return earcam_active && earcam_session_active; }
297/** @brief Nonblocking completion descriptor, or -1 before start/after drain. */
298static int ear_completion_fd(void) { return ear_finalize_wake[0]; }
299/** @brief Copy startup-only host callbacks; worker-side queue_analysis must be thread-safe. */
300static void ear_configure(const struct camera_backend_host *host)
301{
302 if (!host || earcam_active || ear_finalize_started) return;
303 ear_host = *host;
305}
306/** @brief Initialize supervision, not microphone readiness; hard setup failure stays latched. */
307static int ear_init(const char *source)
308{
309 if (earcam_active) return 0;
310 if (earcam_unavailable) return -1;
311 if (ear_cam_pipe_init(source) != 0) { earcam_unavailable = true; return -1; }
312 earcam_active = true;
313 printf("USHER:\tacoustic backend: earcam\n");
314 return 0;
315}
316/** @brief Drain before tearing down audio/storage, then reset quiescent finalizer state. */
317static void ear_deinit(void)
318{
319 ear_drain();
320 struct camera_point_result discarded;
321 while (ear_poll_result(&discarded)) {}
323 pthread_mutex_lock(&ear_finalize_mutex);
324 for (size_t slot = 0; slot < EAR_FINALIZE_JOB_COUNT; ++slot) ear_finalize_jobs[slot] = (struct ear_finalize_job) {0};
325 current_ear_job = NULL;
327 ear_finalize_stopping = false;
328 pthread_mutex_unlock(&ear_finalize_mutex);
330}
331
332bool ear_camera_backend_set_device(const char *device)
333{
335}
336
337void ear_camera_backend_set_simulated_source(double lat_deg, double lon_deg, double level_db_at_1m)
338{
339 earcam_simulated = true;
340 ear_cam_pipe_set_simulated_source(lat_deg, lon_deg, level_db_at_1m);
341}
342void ear_camera_backend_set_band(double low_cut_hz, double high_cut_hz) { ear_cam_pipe_set_band(low_cut_hz, high_cut_hz); }
343
345{
346 static const struct camera_session_ops session = {
347 .start = ear_start, .stop = ear_stop, .listening = ear_listening,
348 .completion_fd = ear_completion_fd, .poll_result = ear_poll_result, .drain = ear_drain
349 };
350 return (struct camera_backend) {
351 .name = "earcam", .init = ear_init, .deinit = ear_deinit,
352 .soda_application = USHER_SODA, .camera_id = USHER_CAMERA_EARCAM, .prefix = 'e',
353 .capabilities = CAMERA_CAP_POINT_SESSION, .soda_option = "--earcam", .record = ear_cam_pipe_record,
354 .session = &session, .configure = ear_configure, .pose_updated = ear_cam_pipe_update_pose
355 };
356}
@ CAMERA_CAP_POINT_SESSION
#define USHER_SODA
static bool capture_running(const volatile sig_atomic_t *running)
Atomically poll a borrowed cancellation flag; NULL means no cancellation.
static uint32_t session
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
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.
int ear_cam_pipe_init(const char *unused)
Reset session storage and start or configure the acoustic backend.
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.
void ear_cam_pipe_deinit(void)
Stop the child and clear all bounded session state.
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.
#define EAR_COORDINATE_UNITS_PER_DEG
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 detector band forwarded to a subsequently spawned EARcam child.
void ear_cam_pipe_snapshot_release(struct ear_session_snapshot *snapshot)
Return detached storage to admission after all snapshot access has ended.
void ear_cam_pipe_set_simulated_source(double lat_deg, double lon_deg, double level_db_at_1m)
Select deterministic virtual acoustic measurements for simulation.
Audio/pose adapter and zero-copy snapshot API for the EAR backend.
static void * finalize_ear_sessions(void *unused)
Drain stopped sessions in admission order until shutdown has no work left.
static bool ear_finalize_stopping
static bool ear_stop(uint32_t session_id)
Validate the active token before a zero-copy snapshot handoff.
static struct camera_backend_host ear_host
static bool earcam_unavailable
#define EAR_LATITUDE_LIMIT_DEG
#define EAR_FINALIZE_JOB_COUNT
#define EAR_METRIC_UNITS_PER_DB
static int ear_finalize_wake[EAR_COMPLETION_ENDPOINT_COUNT]
#define EAR_MILLIMETERS_PER_METER
static void wake_ear_result_owner(void)
Notify the serial owner without blocking; mailbox flags remain authoritative if full.
static pthread_t ear_finalize_thread
#define EAR_QUALITY_UNITS_PER_SCORE
static struct ear_finalize_job * current_ear_job
static pthread_cond_t ear_finalize_available
static bool ear_finalize_started
static bool ear_poll_result(struct camera_point_result *result)
Consume one completion on the serial owner and convert physical units once.
void ear_camera_backend_set_band(double low_cut_hz, double high_cut_hz)
Forward startup tone-band selection to the audio adapter.
bool ear_camera_backend_set_device(const char *device)
Copy an ALSA PCM name before initialization or worker startup.
void ear_camera_backend_set_simulated_source(double lat_deg, double lon_deg, double level_db_at_1m)
Select deterministic synthetic audio before initialization, bypassing ALSA.
static void ear_configure(const struct camera_backend_host *host)
Copy startup-only host callbacks; worker-side queue_analysis must be thread-safe.
#define EAR_LONGITUDE_LIMIT_DEG
static void ear_deinit(void)
Drain before tearing down audio/storage, then reset quiescent finalizer state.
static bool earcam_active
#define EAR_COMPLETION_DRAIN_BYTES
static int ear_completion_fd(void)
Nonblocking completion descriptor, or -1 before start/after drain.
static uint64_t ear_finalize_order
static bool ear_point_valid(const struct ear_loudest_spot *spot)
Guard finite values and integer conversion ranges before marking a wire point valid.
#define EAR_EVIDENCE_PATH_CAPACITY
static void ear_drain(void)
Close admission and join all admitted stopped-session evidence work.
static bool ear_listening(void)
Whether the serial owner should admit EAR samples for the current session.
static bool earcam_session_active
static struct ear_finalize_job ear_finalize_jobs[EAR_FINALIZE_JOB_COUNT]
static pthread_mutex_t ear_finalize_mutex
static bool ear_start(uint32_t session_id)
Reserve both finalizer capacity and adapter storage before listening.
struct camera_backend ear_camera_backend_get(void)
Return the EAR backend descriptor by value; its session hook table has static lifetime.
static bool earcam_simulated
#define EAR_COMPLETION_ENDPOINT_COUNT
static int ear_init(const char *source)
Initialize supervision, not microphone readiness; hard setup failure stays latched.
#define EAR_SHOT_AGL_UNITS_PER_METER
EAR-specific startup configuration behind USHER's generic backend interface.
static bool ready
int image_exif_write(const char *filename, const union dc_shot_union *shot)
Add standard USHER flight metadata to a JPEG.
Definition image_exif.c:408
Flight, timing, and thermal-analysis metadata writing for captured JPEGs.
static size_t count
Definition pose_log.c:79
bool(* pose_lookup)(struct capture_observation *observation, uint64_t maximum_age_us)
Bounded pose lookup supplied by USHER's shared timing owner.
Function table describing one backend's owned camera operations.
One reservation progressing through snapshot -> point -> evidence completion.
struct ear_loudest_spot spot
struct ear_session_snapshot * snapshot
Estimated ground source, not a surveyed target or guaranteed alarm detection.
Definition earcam_core.h:37
uint32_t sample_count
Definition earcam_core.h:45
uint32_t used_count
Definition earcam_core.h:46
Statically reserved sample buffer with a single active or detached owner.
struct dc_shot_union::@351207206061007345226276304225222200157171312155 data
struct usher_control_result result
Definition usher.c:377
struct capture_job job
Definition usher.c:370
#define USHER_CAMERA_EARCAM