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 File Reference

Audio/pose adapter and zero-copy snapshot API for the EAR backend. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "usher_protocol.h"
#include "capture_timing.h"
#include "modules/ear_cam/earcam_core.h"
Include dependency graph for ear_cam_pipe.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

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.
bool ear_cam_pipe_set_device (const char *device)
 Copy a startup ALSA PCM name into bounded adapter-owned storage.
bool ear_cam_pipe_set_settings (const char *settings)
 Copy an assignment path before the microphone supervisor starts.
void ear_cam_pipe_update_pose (void)
 Retry bounded pending audio windows when the serial owner receives new poses.
bool ear_cam_pipe_begin_session (uint32_t session_id)
 Begin/reset active collection without solving or waiting for log I/O.
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.
struct ear_session_snapshot * ear_cam_pipe_detach_session (void)
 Transfer active storage to an immutable worker snapshot without copying samples.
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.
int32_t ear_cam_pipe_snapshot_number (const struct ear_session_snapshot *snapshot)
 Read the last request number from immutable evidence.
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.
void ear_cam_pipe_snapshot_release (struct ear_session_snapshot *snapshot)
 Return detached storage to admission after all snapshot access has ended.
int ear_cam_pipe_init (const char *unused)
 Start EARcam sampling or its deterministic simulated-source replacement.
void ear_cam_pipe_deinit (void)
 Stop EARcam activity and release its process and descriptors.
bool ear_cam_pipe_ready (void)
 Report readiness of the configured live or simulated measurement source.
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.
void ear_cam_pipe_set_band (double low_cut_hz, double high_cut_hz)
 Set the live EARcam tone-search band.
int ear_cam_pipe_record (const union dc_shot_union *shot)
 Associate the newest sound window with one flight-controller shot pose.
int ear_cam_pipe_finish (struct ear_loudest_spot *result)
 Fuse the session into its final loudest-spot result and clear stored samples.
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.
int32_t ear_cam_pipe_last_shot_nr (void)
 Get the shot number associated with the newest stored acoustic sample.

Detailed Description

Audio/pose adapter and zero-copy snapshot API for the EAR backend.

Configuration and active-session functions belong to USHER's serial owner. Only snapshot solve/number/render/release are intended for the finalizer. Configure before initialization; drain detached workers before deinitialization.

Definition in file ear_cam_pipe.h.

Function Documentation

◆ ear_cam_pipe_begin_session()

bool ear_cam_pipe_begin_session ( uint32_t session_id)

Begin/reset active collection without solving or waiting for log I/O.

Parameters
session_idToken retained in audit rows; backend admission validates it before this call.
Returns
False when no active or free buffer exists; true after resetting active counts.

Does not evict worker-owned snapshots. The active buffer is serial-owner-only.

Definition at line 1054 of file ear_cam_pipe.c.

◆ ear_cam_pipe_deinit()

void ear_cam_pipe_deinit ( void )

Stop EARcam activity and release its process and descriptors.

Safe after a partially successful initialization. Call this after the final render or solve because it discards unfinalized session samples.

Stop EARcam activity and release its process and descriptors.

Definition at line 909 of file ear_cam_pipe.c.

◆ ear_cam_pipe_detach_session()

struct ear_session_snapshot * ear_cam_pipe_detach_session ( void )

Transfer active storage to an immutable worker snapshot without copying samples.

Returns
Owned snapshot, or NULL if no active buffer exists.

Serial-owner-only. Pending pose windows are resolved/fallback-committed before freezing count; active collection stays disabled until the next successful begin.

Warning
Caller must eventually release exactly once, after all readers stop using it.

Definition at line 1078 of file ear_cam_pipe.c.

◆ ear_cam_pipe_finish()

int ear_cam_pipe_finish ( struct ear_loudest_spot * result)

Fuse the session into its final loudest-spot result and clear stored samples.

Parameters
resultDestination for the solved or invalid result.
Returns
Core solver status: 0 for an estimate, -1 for insufficient evidence or invalid arguments.

Finalization consumes the session so the next survey cannot accidentally mix old and new flight legs. This legacy synchronous call solves committed samples and joins the log writer; it is not suitable for a latency-sensitive UART callback. Resolve pending poses first (ear_cam_pipe_solve() forces their fallback), and render before clearing samples. Prefer detach/solve/render/release for asynchronous sessions.

Fuse the session into its final loudest-spot result and clear stored samples.

Definition at line 1259 of file ear_cam_pipe.c.

◆ ear_cam_pipe_init()

int ear_cam_pipe_init ( const char * unused)

Start EARcam sampling or its deterministic simulated-source replacement.

Parameters
unusedReserved for the common camera-backend initialization signature; ignored.
Returns
0 when supervision is started (not hardware readiness); -1 for setup failure.

A missing microphone is deliberately not fatal. The optical pipeline can continue operating while an independent supervisor retries the server. Configure the simulated source and frequency band before calling this function.

Start EARcam sampling or its deterministic simulated-source replacement.

Returns
-1 only for unrecoverable setup errors; missing hardware stays retryable.

Definition at line 871 of file ear_cam_pipe.c.

◆ ear_cam_pipe_last_shot_nr()

int32_t ear_cam_pipe_last_shot_nr ( void )

Get the shot number associated with the newest stored acoustic sample.

Returns
The newest shot number, or 0 when the session is empty.

Definition at line 1049 of file ear_cam_pipe.c.

◆ ear_cam_pipe_log_result()

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.

Parameters
session_idToken identifying the completed snapshot, not necessarily the current session.
resultBorrowed estimate, copied into a row before return; NULL is ignored.

Only the log worker accesses its FILE. A dropped audit row is not a lost point completion.

Definition at line 1247 of file ear_cam_pipe.c.

◆ ear_cam_pipe_ready()

bool ear_cam_pipe_ready ( void )

Report readiness of the configured live or simulated measurement source.

Returns
True after the live handshake or simulated initialization; false after teardown/lost readiness.

Ready does not guarantee a fresh sample or prove live hardware is present; simulated mode intentionally has no microphone process and also reports ready.

Report readiness of the configured live or simulated measurement source.

Definition at line 925 of file ear_cam_pipe.c.

◆ ear_cam_pipe_record()

int ear_cam_pipe_record ( const union dc_shot_union * shot)

Associate the newest sound window with one flight-controller shot pose.

Parameters
shotFlight pose and shot number received from USHER transport.
Returns
0 when evidence is committed or admitted to the bounded pose queue; -1 for invalid input, unavailable/stale data or duplicate timed windows.

Timed windows await pose evidence in a fixed queue for at most 200 ms; unresolved or legacy measurements retain their labelled request-pose fallback. Only the newest live measurement is read at each request, not every audio window. Capacity pressure retains the newest half of active samples, never a worker snapshot. Server recovery and CSV I/O run independently. This call never waits for them.

Definition at line 1018 of file ear_cam_pipe.c.

◆ ear_cam_pipe_render()

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.

Parameters
resultSolved loudest-spot estimate to mark on the image.
filenameDestination buffer receiving the JPEG path.
filename_sizeCapacity of filename.
simulatedTrue when rendering NPS/desk simulated data.
Returns
0 on success; -1 if inputs, session data, or output creation fail.

Must be called before ear_cam_pipe_finish() clears the session. The JPEG and sidecar preserve the sampled field and final estimate for post-flight review.

Definition at line 1214 of file ear_cam_pipe.c.

◆ ear_cam_pipe_set_band()

void ear_cam_pipe_set_band ( double low_cut_hz,
double high_cut_hz )

Set the live EARcam tone-search band.

Parameters
low_cut_hzLower cutoff in hertz, or zero to retain EARcam's default.
high_cut_hzUpper cutoff in hertz, or zero to retain EARcam's default.

Must be called before ear_cam_pipe_init() because the values become arguments of the persistent external process. Invalid ordering is rejected by the caller's CLI path.

Set the live EARcam tone-search band.

Definition at line 254 of file ear_cam_pipe.c.

◆ ear_cam_pipe_set_device()

bool ear_cam_pipe_set_device ( const char * device)

Copy a startup ALSA PCM name into bounded adapter-owned storage.

Parameters
deviceNonempty name; must fit including its terminating NUL.
Returns
True when copied; false for NULL/empty/oversized input or running capture threads.

No shell is involved. Every child retry receives the same owned name.

Definition at line 224 of file ear_cam_pipe.c.

◆ ear_cam_pipe_set_pose_lookup()

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.

Parameters
lookupBorrowed callback with host lifetime; NULL selects request-pose fallback.

Never invoked by the audio reader or finalizer; shared navigation state stays owner-local.

Definition at line 219 of file ear_cam_pipe.c.

◆ ear_cam_pipe_set_settings()

bool ear_cam_pipe_set_settings ( const char * settings)

Copy an assignment path before the microphone supervisor starts.

Parameters
settingsNonempty path forwarded to every server retry without shell expansion.
Returns
True for a complete bounded copy; false while supervision is active or input is invalid.

Definition at line 165 of file ear_cam_pipe.c.

◆ ear_cam_pipe_set_simulated_source()

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.

Parameters
lat_degSource latitude in degrees.
lon_degSource longitude in degrees.
level_db_at_1mSound level at one metre in decibels.

Must be called before ear_cam_pipe_init(). Simulation avoids ALSA and the external EARcam process while preserving the same geotagging and fusion interface.

Replace microphone input with a virtual fixed loudspeaker for NPS or desk tests.

Must precede initialization so no microphone child is launched.

Definition at line 241 of file ear_cam_pipe.c.

◆ ear_cam_pipe_snapshot_number()

int32_t ear_cam_pipe_snapshot_number ( const struct ear_session_snapshot * snapshot)

Read the last request number from immutable evidence.

Parameters
snapshotBorrowed unreleased snapshot, or NULL.
Returns
Newest stored request number, or zero for NULL/empty evidence.

Definition at line 1102 of file ear_cam_pipe.c.

◆ ear_cam_pipe_snapshot_release()

void ear_cam_pipe_snapshot_release ( struct ear_session_snapshot * snapshot)

Return detached storage to admission after all snapshot access has ended.

Parameters
snapshotPreviously detached owned snapshot; NULL is a no-op.
Warning
The pointer and sample contents must not be used after release, even if the backing array still exists. A new serial-owner session may overwrite it.

Definition at line 1107 of file ear_cam_pipe.c.

◆ ear_cam_pipe_snapshot_render()

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.

Parameters
snapshotBorrowed owned snapshot; remains immutable and unreleased during I/O.
session_idRequired nonzero correlation token for file naming and CSV provenance.
resultRequired borrowed estimate; an invalid estimate may still produce evidence.
filenameDestination path buffer; cleared by the renderer on handled creation failure.
filename_sizeCapacity of filename including its terminating NUL.
simulatedSelect the simulated-image prefix, not a different rendering algorithm.
Returns
0 for decorated JPEG success, -1 for invalid arguments or primary rendering failure.

Worker-safe. CSV, undecorated field and .geo errors are reported separately; JPEG success does not guarantee all evidence products or power-loss durability.

Definition at line 1221 of file ear_cam_pipe.c.

◆ ear_cam_pipe_snapshot_solve()

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.

Parameters
snapshotBorrowed owned snapshot, which must remain unreleased throughout this call.
resultRequired estimate destination, cleared before invoking the core.
Returns
Core solver status: 0 for an estimate, -1 for invalid/insufficient evidence or arguments.

Worker-safe; shared core workspace serializes concurrent solves. No ownership transfer.

Definition at line 1095 of file ear_cam_pipe.c.

◆ ear_cam_pipe_solve()

int ear_cam_pipe_solve ( struct ear_loudest_spot * result)

Solve the accumulated session without clearing it.

Parameters
resultDestination for the current estimate.
Returns
Core solver status: 0 for an estimate, -1 for insufficient evidence or invalid arguments.

Use for refinement decisions. Unlike ear_cam_pipe_finish(), subsequent records remain part of the same survey session. Serial-owner-only; pending poses are forced to their bounded fallback before this synchronous solve.

Solve the accumulated session without clearing it.

Definition at line 1231 of file ear_cam_pipe.c.

◆ ear_cam_pipe_update_pose()

void ear_cam_pipe_update_pose ( void )

Retry bounded pending audio windows when the serial owner receives new poses.

Definition at line 1012 of file ear_cam_pipe.c.