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"

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_id Token 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
-
result Destination 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
-
unused Reserved 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_id Token identifying the completed snapshot, not necessarily the current session. result Borrowed 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
-
shot Flight 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
-
result Solved loudest-spot estimate to mark on the image. filename Destination buffer receiving the JPEG path. filename_size Capacity of filename.simulated True 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_hz Lower cutoff in hertz, or zero to retain EARcam's default. high_cut_hz Upper 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
-
device Nonempty 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
-
lookup Borrowed 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
-
settings Nonempty 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_deg Source latitude in degrees. lon_deg Source longitude in degrees. level_db_at_1m Sound 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
-
snapshot Borrowed 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
-
snapshot Previously 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
-
snapshot Borrowed owned snapshot; remains immutable and unreleased during I/O. session_id Required nonzero correlation token for file naming and CSV provenance. result Required borrowed estimate; an invalid estimate may still produce evidence. filename Destination path buffer; cleared by the renderer on handled creation failure. filename_size Capacity of filename including its terminating NUL. simulated Select 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
-
snapshot Borrowed owned snapshot, which must remain unreleased throughout this call. result Required 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
-
result Destination 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.