USHER-side audio supervision, pose association and immutable EAR snapshots. More...
#include "ear_cam_pipe.h"#include "modules/ear_cam/ear_heatmap.h"#include "path_utils.h"#include <errno.h>#include <fcntl.h>#include <limits.h>#include <math.h>#include <poll.h>#include <pthread.h>#include <signal.h>#include <spawn.h>#include <stdatomic.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <sys/stat.h>#include <sys/types.h>#include <sys/wait.h>#include <time.h>#include <unistd.h>
Go to the source code of this file.
Data Structures | |
| struct | latest_measurement |
| Latest parsed window plus optional producer timing; published under ear_mutex. More... | |
| struct | ear_session_snapshot |
| Statically reserved sample buffer with a single active or detached owner. More... | |
Functions | |
| bool | ear_cam_pipe_set_settings (const char *settings) |
| Copy an assignment path before the microphone supervisor starts. | |
| static void | flush_pending_audio (bool force) |
| Retry pose lookup without waiting; bound unresolved evidence by count and age. | |
| 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. | |
| 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. | |
| 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. | |
| static double | simulated_noise_db (void) |
| Produce reproducible bounded simulation noise without shared libc PRNG state. | |
| static struct latest_measurement | simulated_measurement (const union dc_shot_union *shot, uint64_t now) |
| Model a virtual point source using free-field inverse-distance attenuation. | |
| static uint64_t | monotonic_ms (void) |
| Return monotonic milliseconds for server freshness and retry decisions. | |
| static void | sleep_ms (unsigned int milliseconds) |
| Sleep through signal interruption for bounded lifecycle polling. | |
| static int | parse_field (const char *line, const char *key, double *value) |
| Parse one named numeric field from an EARcam server line. | |
| static bool | parse_unsigned_field (const char *line, const char *key, uint64_t *value) |
| Parse exact unsigned timing/sequence evidence without rounding through double. | |
| static void | handle_server_line (const char *line) |
| Interpret one complete server output line and atomically update shared state. | |
| static void * | reader_main (void *unused) |
| Read and frame EARcam output in a dedicated thread. | |
| static void | stop_server (void) |
| Request child shutdown, join its reader, and reap the owned process. | |
| static int | open_session_log (void) |
| Create the CSV audit log lazily on the first accepted acoustic sample. | |
| static void * | write_session_log (void *unused) |
| Drain bounded row batches; this worker alone opens/writes/flushes/closes the log. | |
| static void | queue_session_log (const char *line) |
| Best-effort serial-owner enqueue with copied rows and no filesystem wait. | |
| static void | close_session_log (void) |
| Join the log writer after queued rows drain; not a hard filesystem deadline. | |
| static int | add_inherited_descriptor_closes (posix_spawn_file_actions_t *actions, const int command_pipe[2], const int response_pipe[2]) |
| Prevent the audio child from inheriting unrelated USHER descriptors. | |
| static int | start_server (void) |
| Spawn earcam --server and its asynchronous line reader. | |
| static void * | supervise_server (void *unused) |
| Retry missing/disconnected capture independently of optical operation. | |
| static bool | warning_due (uint64_t now) |
| Rate-limit repeated unavailable/stale microphone diagnostics. | |
| int | ear_cam_pipe_init (const char *unused) |
| Reset session storage and start or configure the acoustic backend. | |
| void | ear_cam_pipe_deinit (void) |
| Stop the child and clear all bounded session state. | |
| bool | ear_cam_pipe_ready (void) |
| Report whether an actual or simulated measurement source is ready. | |
| static int | format_session_row (const struct ear_sample *sample, uint32_t session_id, char *line, size_t size) |
| Format one evidence row with both chosen pose and original request provenance. | |
| static void | commit_audio_sample (const union dc_shot_union *request, const struct latest_measurement *measurement) |
| Append on the serial owner using aligned pose when available, labelled request pose otherwise. | |
| 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. | |
| int32_t | ear_cam_pipe_last_shot_nr (void) |
| Get the shot number associated with the newest stored acoustic sample. | |
| bool | ear_cam_pipe_begin_session (uint32_t session_id) |
| Begin/reset active collection without solving or waiting for log I/O. | |
| 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. | |
| void | ear_cam_pipe_snapshot_release (struct ear_session_snapshot *snapshot) |
| Return detached storage to admission after all snapshot access has ended. | |
| static int | render_session (const struct ear_sample *samples, size_t count, int32_t number, uint32_t session_id, const struct ear_loudest_spot *result, char *filename, size_t filename_size, bool simulated) |
| Write evidence from borrowed active or immutable snapshot samples. | |
| 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. | |
| 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. | |
| int | ear_cam_pipe_solve (struct ear_loudest_spot *result) |
| Solve the current session without consuming it, for intermediate mission feedback. | |
| 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) |
| Solve and close the current session, clearing accumulated samples afterward. | |
Detailed Description
USHER-side audio supervision, pose association and immutable EAR snapshots.
A persistent EARcam child produces newline-delimited acoustic measurements. A reader thread retains only the latest measurement while USHER geotags it at shots; the bounded session can be detached without copying for the backend's finalizer. Numerical fusion and JPEG rendering live in the standalone EAR core, not USHER's serial loop. Missing microphones remain nonfatal and are retried. Thread ownership: the supervisor owns child lifecycle, the reader publishes latest under ear_mutex, the serial owner handles sessions/pending poses/log enqueue, and the log worker alone accesses its FILE. The finalizer borrows detached snapshots until release; it must not touch active-session APIs.
Definition in file ear_cam_pipe.c.
Macro Definition Documentation
◆ ANGLE_BFP_SCALE
| #define ANGLE_BFP_SCALE 4096.0 |
Definition at line 78 of file ear_cam_pipe.c.
◆ DEG_TO_RAD
| #define DEG_TO_RAD 0.017453292519943295 |
Definition at line 81 of file ear_cam_pipe.c.
◆ EAR_ALTITUDE_UNITS_PER_METER
| #define EAR_ALTITUDE_UNITS_PER_METER 1000.0 |
Definition at line 114 of file ear_cam_pipe.c.
◆ EAR_AUDIO_FUTURE_SLACK_US
| #define EAR_AUDIO_FUTURE_SLACK_US 1000 |
Definition at line 118 of file ear_cam_pipe.c.
◆ EAR_AUDIO_TIMING_ERROR_LIMIT_US
| #define EAR_AUDIO_TIMING_ERROR_LIMIT_US 100000 |
Definition at line 117 of file ear_cam_pipe.c.
◆ EAR_AUDIO_WINDOW_LIMIT_US
| #define EAR_AUDIO_WINDOW_LIMIT_US 1000000 |
Plausibility limits for producer capture windows, not clock synchronization guarantees.
Definition at line 116 of file ear_cam_pipe.c.
◆ EAR_BAND_ARGUMENT_CAPACITY
| #define EAR_BAND_ARGUMENT_CAPACITY 32 |
Definition at line 93 of file ear_cam_pipe.c.
◆ EAR_CHILD_KILL_ATTEMPT
| #define EAR_CHILD_KILL_ATTEMPT 20 |
Definition at line 101 of file ear_cam_pipe.c.
◆ EAR_CHILD_REAP_ATTEMPTS
| #define EAR_CHILD_REAP_ATTEMPTS 25 |
The shutdown loop escalates QUIT -> SIGTERM -> SIGKILL; it does not block waitpid.
Definition at line 99 of file ear_cam_pipe.c.
◆ EAR_CHILD_TERM_ATTEMPT
| #define EAR_CHILD_TERM_ATTEMPT 10 |
Definition at line 100 of file ear_cam_pipe.c.
◆ EAR_COORDINATE_UNITS_PER_DEG
| #define EAR_COORDINATE_UNITS_PER_DEG 1e7 |
Definition at line 113 of file ear_cam_pipe.c.
◆ EAR_ERROR_PREFIX_LENGTH
| #define EAR_ERROR_PREFIX_LENGTH 12 |
Definition at line 121 of file ear_cam_pipe.c.
◆ EAR_EVIDENCE_FILE_MODE
| #define EAR_EVIDENCE_FILE_MODE 0600 |
Definition at line 106 of file ear_cam_pipe.c.
◆ EAR_EVIDENCE_FILENAME_ATTEMPTS
| #define EAR_EVIDENCE_FILENAME_ATTEMPTS 32 |
Definition at line 104 of file ear_cam_pipe.c.
◆ EAR_JPEG_SUFFIX_LENGTH
| #define EAR_JPEG_SUFFIX_LENGTH 4 |
Definition at line 108 of file ear_cam_pipe.c.
◆ EAR_LINE_MAX
| #define EAR_LINE_MAX 512U |
Definition at line 77 of file ear_cam_pipe.c.
◆ EAR_LOG_BATCH_ROWS
| #define EAR_LOG_BATCH_ROWS 16 |
Definition at line 90 of file ear_cam_pipe.c.
◆ EAR_LOG_FILE_MODE
| #define EAR_LOG_FILE_MODE 0644 |
Definition at line 105 of file ear_cam_pipe.c.
◆ EAR_LOG_FILENAME_ATTEMPTS
| #define EAR_LOG_FILENAME_ATTEMPTS 128 |
Definition at line 103 of file ear_cam_pipe.c.
◆ EAR_LOG_PATH_CAPACITY
| #define EAR_LOG_PATH_CAPACITY 512 |
Definition at line 87 of file ear_cam_pipe.c.
◆ EAR_LOG_QUEUE_ROWS
| #define EAR_LOG_QUEUE_ROWS 128 |
Definition at line 89 of file ear_cam_pipe.c.
◆ EAR_LOG_ROW_CAPACITY
| #define EAR_LOG_ROW_CAPACITY 512 |
Definition at line 88 of file ear_cam_pipe.c.
◆ EAR_MICROPHONE_NAME_CAPACITY
| #define EAR_MICROPHONE_NAME_CAPACITY 256 |
Definition at line 86 of file ear_cam_pipe.c.
◆ EAR_MS_PER_SECOND
| #define EAR_MS_PER_SECOND 1000U |
Definition at line 109 of file ear_cam_pipe.c.
◆ EAR_NS_PER_MS
| #define EAR_NS_PER_MS 1000000U |
Definition at line 110 of file ear_cam_pipe.c.
◆ EAR_PENDING_AUDIO_WINDOWS
| #define EAR_PENDING_AUDIO_WINDOWS 16 |
Definition at line 92 of file ear_cam_pipe.c.
◆ EAR_POSE_WAIT_MS
| #define EAR_POSE_WAIT_MS 200 |
Definition at line 96 of file ear_cam_pipe.c.
◆ EAR_READER_CHUNK_BYTES
| #define EAR_READER_CHUNK_BYTES 256 |
Definition at line 94 of file ear_cam_pipe.c.
◆ EAR_READER_POLL_MS
| #define EAR_READER_POLL_MS 200 |
Definition at line 95 of file ear_cam_pipe.c.
◆ EAR_READY_PREFIX_LENGTH
| #define EAR_READY_PREFIX_LENGTH 12 |
Definition at line 120 of file ear_cam_pipe.c.
◆ EAR_READY_TIMEOUT_MS
| #define EAR_READY_TIMEOUT_MS 15000 |
Definition at line 70 of file ear_cam_pipe.c.
◆ EAR_RESTART_INTERVAL_MS
| #define EAR_RESTART_INTERVAL_MS 3000U |
Definition at line 73 of file ear_cam_pipe.c.
◆ EAR_SAMPLE_FUTURE_SLACK_MS
| #define EAR_SAMPLE_FUTURE_SLACK_MS 1 |
Definition at line 97 of file ear_cam_pipe.c.
◆ EAR_SAMPLE_PREFIX_LENGTH
| #define EAR_SAMPLE_PREFIX_LENGTH 7 |
Definition at line 119 of file ear_cam_pipe.c.
◆ EAR_SAMPLE_STALE_MS
| #define EAR_SAMPLE_STALE_MS 500U |
Definition at line 76 of file ear_cam_pipe.c.
◆ EAR_SESSION_BUFFER_COUNT
| #define EAR_SESSION_BUFFER_COUNT 2 |
Storage/admission policies; two snapshots match the backend's two finalizer jobs.
Definition at line 85 of file ear_cam_pipe.c.
◆ EAR_SESSION_MARKER_CAPACITY
| #define EAR_SESSION_MARKER_CAPACITY 128 |
Definition at line 91 of file ear_cam_pipe.c.
◆ EAR_SIM_CONTRAST_DB
| #define EAR_SIM_CONTRAST_DB 6.0 |
Definition at line 133 of file ear_cam_pipe.c.
◆ EAR_SIM_DISTANCE_DB_PER_DECADE
| #define EAR_SIM_DISTANCE_DB_PER_DECADE 20.0 |
Definition at line 132 of file ear_cam_pipe.c.
◆ EAR_SIM_FREQUENCY_HZ
| #define EAR_SIM_FREQUENCY_HZ 2700.0 |
Definition at line 134 of file ear_cam_pipe.c.
◆ EAR_SIM_NOISE_HALF_RANGE_DB
| #define EAR_SIM_NOISE_HALF_RANGE_DB 1.5 |
Definition at line 130 of file ear_cam_pipe.c.
◆ EAR_SIM_NOISE_INITIAL_STATE
| #define EAR_SIM_NOISE_INITIAL_STATE 0x2545F491U |
xorshift32 parameters are algorithm invariants; the nonzero seed is process-local.
Definition at line 124 of file ear_cam_pipe.c.
◆ EAR_SIM_NOISE_STEPS
| #define EAR_SIM_NOISE_STEPS 30001U |
Definition at line 128 of file ear_cam_pipe.c.
◆ EAR_SIM_NOISE_STEPS_PER_DB
| #define EAR_SIM_NOISE_STEPS_PER_DB 10000.0 |
Definition at line 129 of file ear_cam_pipe.c.
◆ EAR_SIM_REFERENCE_DISTANCE_M
| #define EAR_SIM_REFERENCE_DISTANCE_M 1.0 |
Definition at line 131 of file ear_cam_pipe.c.
◆ EAR_SIM_XORSHIFT_LEFT_FIRST
| #define EAR_SIM_XORSHIFT_LEFT_FIRST 13 |
Definition at line 125 of file ear_cam_pipe.c.
◆ EAR_SIM_XORSHIFT_LEFT_LAST
| #define EAR_SIM_XORSHIFT_LEFT_LAST 5 |
Definition at line 127 of file ear_cam_pipe.c.
◆ EAR_SIM_XORSHIFT_RIGHT
| #define EAR_SIM_XORSHIFT_RIGHT 17 |
Definition at line 126 of file ear_cam_pipe.c.
◆ EAR_SLEEP_NS_PER_MS
| #define EAR_SLEEP_NS_PER_MS 1000000L |
Definition at line 111 of file ear_cam_pipe.c.
◆ EAR_STOPPED_PREFIX_LENGTH
| #define EAR_STOPPED_PREFIX_LENGTH 14 |
Definition at line 122 of file ear_cam_pipe.c.
◆ EAR_SUPERVISOR_TICK_MS
| #define EAR_SUPERVISOR_TICK_MS 20 |
Definition at line 102 of file ear_cam_pipe.c.
◆ EAR_TM_YEAR_ORIGIN
| #define EAR_TM_YEAR_ORIGIN 1900 |
Definition at line 107 of file ear_cam_pipe.c.
◆ EAR_US_PER_MS
| #define EAR_US_PER_MS 1000 |
Definition at line 112 of file ear_cam_pipe.c.
◆ EAR_WARNING_INTERVAL_MS
| #define EAR_WARNING_INTERVAL_MS 1000U |
Definition at line 75 of file ear_cam_pipe.c.
◆ EARTH_RADIUS_M
| #define EARTH_RADIUS_M 6378137.0 |
Definition at line 80 of file ear_cam_pipe.c.
◆ POSITION_BFP_SCALE
| #define POSITION_BFP_SCALE 256.0 |
Definition at line 79 of file ear_cam_pipe.c.
◆ RAD_TO_DEG
| #define RAD_TO_DEG 57.29577951308232 |
Definition at line 82 of file ear_cam_pipe.c.
◆ USHER_EAR_CAM_COMMAND
| #define USHER_EAR_CAM_COMMAND "./bin/earcam" |
Definition at line 54 of file ear_cam_pipe.c.
◆ USHER_EAR_CAM_DEVICE
| #define USHER_EAR_CAM_DEVICE "auto" |
Definition at line 58 of file ear_cam_pipe.c.
◆ USHER_EAR_CAM_LOG_DIR
| #define USHER_EAR_CAM_LOG_DIR "earlogs" |
Definition at line 62 of file ear_cam_pipe.c.
◆ USHER_EAR_CAM_PHOTO_DIR
| #define USHER_EAR_CAM_PHOTO_DIR "~/Pictures/sensoraia" |
Definition at line 66 of file ear_cam_pipe.c.
Function Documentation
◆ add_inherited_descriptor_closes()
|
static |
Prevent the audio child from inheriting unrelated USHER descriptors.
Only intended stdin/stdout pipes survive setup; leaked UART/SODA FDs could keep channels alive after their real owners close them. Supervisor-only.
Definition at line 679 of file ear_cam_pipe.c.
◆ close_session_log()
|
static |
Join the log writer after queued rows drain; not a hard filesystem deadline.
Definition at line 661 of file ear_cam_pipe.c.
◆ commit_audio_sample()
|
static |
Append on the serial owner using aligned pose when available, labelled request pose otherwise.
At capacity keep the newest half of active evidence. This cannot overwrite a detached snapshot; admission must acquire its own buffer first.
Definition at line 953 of file ear_cam_pipe.c.
◆ 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 the child and clear all bounded session state.
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 | ) |
Solve and close the current session, clearing accumulated samples afterward.
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 | ) |
Reset session storage and start or configure the acoustic backend.
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 whether an actual or simulated measurement source is 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 detector band forwarded to a subsequently spawned EARcam child.
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 ) |
Select deterministic virtual acoustic measurements for simulation.
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 current session without consuming it, for intermediate mission feedback.
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.
◆ flush_pending_audio()
|
static |
Retry pose lookup without waiting; bound unresolved evidence by count and age.
FIFO ordering keeps window provenance stable. Stop/full-queue forces request-pose fallback rather than waiting for poses or losing admitted audio.
Definition at line 998 of file ear_cam_pipe.c.
◆ format_session_row()
|
static |
Format one evidence row with both chosen pose and original request provenance.
Definition at line 934 of file ear_cam_pipe.c.
◆ handle_server_line()
|
static |
Interpret one complete server output line and atomically update shared state.
Malformed samples are ignored rather than poisoning the latest valid reading.
Definition at line 382 of file ear_cam_pipe.c.
◆ monotonic_ms()
|
static |
Return monotonic milliseconds for server freshness and retry decisions.
Definition at line 306 of file ear_cam_pipe.c.
◆ open_session_log()
|
static |
Create the CSV audit log lazily on the first accepted acoustic sample.
Definition at line 558 of file ear_cam_pipe.c.
◆ parse_field()
|
static |
Parse one named numeric field from an EARcam server line.
- Returns
- 0 on one finite complete value, otherwise -1.
Field-boundary checks prevent a short key from matching a suffix of another key.
Definition at line 328 of file ear_cam_pipe.c.
◆ parse_unsigned_field()
|
static |
Parse exact unsigned timing/sequence evidence without rounding through double.
Definition at line 355 of file ear_cam_pipe.c.
◆ queue_session_log()
|
static |
Best-effort serial-owner enqueue with copied rows and no filesystem wait.
A busy/full queue drops an audit row rather than delaying UART/audio; snapshot CSV is written separately from immutable samples at stop.
Definition at line 633 of file ear_cam_pipe.c.
◆ reader_main()
|
static |
Read and frame EARcam output in a dedicated thread.
Chunked reads avoid per-byte syscalls; only the latest measurement is retained because USHER correlates a shot to current acoustic evidence, not a delayed backlog.
Definition at line 459 of file ear_cam_pipe.c.
◆ render_session()
|
static |
Write evidence from borrowed active or immutable snapshot samples.
Nonzero session IDs reserve JPEG and CSV names together with O_EXCL; old evidence is never silently overwritten. Snapshot CSV failure and optional field/.geo failure are reported separately from decorated JPEG success.
Definition at line 1118 of file ear_cam_pipe.c.
◆ simulated_measurement()
|
static |
Model a virtual point source using free-field inverse-distance attenuation.
This fixture includes height and bounded noise, not terrain, directivity, aircraft noise, microphone calibration or physical alarm validation.
Definition at line 281 of file ear_cam_pipe.c.
◆ simulated_noise_db()
|
static |
Produce reproducible bounded simulation noise without shared libc PRNG state.
Definition at line 266 of file ear_cam_pipe.c.
◆ sleep_ms()
|
static |
Sleep through signal interruption for bounded lifecycle polling.
Definition at line 314 of file ear_cam_pipe.c.
◆ start_server()
|
static |
Spawn earcam --server and its asynchronous line reader.
- Returns
- 0 after ownership is established, otherwise -1 with all partial resources closed.
Readiness is observed asynchronously so process spawn cannot block USHER's startup indefinitely on a missing microphone.
Definition at line 714 of file ear_cam_pipe.c.
◆ stop_server()
|
static |
Request child shutdown, join its reader, and reap the owned process.
Joining precedes descriptor teardown so the reader cannot race reused state.
Definition at line 515 of file ear_cam_pipe.c.
◆ supervise_server()
|
static |
Retry missing/disconnected capture independently of optical operation.
Error, lost readiness or startup timeout triggers owned teardown before another spawn. The retry delay checks shutdown in small polling ticks.
Definition at line 833 of file ear_cam_pipe.c.
◆ warning_due()
|
static |
Rate-limit repeated unavailable/stale microphone diagnostics.
Definition at line 860 of file ear_cam_pipe.c.
◆ write_session_log()
|
static |
Drain bounded row batches; this worker alone opens/writes/flushes/closes the log.
Release log_mutex before filesystem I/O. A latched write failure counts lost rows without repeatedly blocking capture on an already failed destination.
Definition at line 597 of file ear_cam_pipe.c.
Variable Documentation
◆ active_session
|
static |
Definition at line 193 of file ear_cam_pipe.c.
◆ band_high_arg
|
static |
Definition at line 250 of file ear_cam_pipe.c.
◆ band_low_arg
|
static |
Definition at line 249 of file ear_cam_pipe.c.
◆ band_set
|
static |
Definition at line 251 of file ear_cam_pipe.c.
◆ ear_mutex
|
static |
Definition at line 174 of file ear_cam_pipe.c.
◆ ear_settings
|
static |
Definition at line 163 of file ear_cam_pipe.c.
◆ environ
|
extern |
◆ last_warning_ms
|
static |
Definition at line 179 of file ear_cam_pipe.c.
◆ last_window_end
|
static |
Definition at line 215 of file ear_cam_pipe.c.
◆ latest
|
static |
Definition at line 175 of file ear_cam_pipe.c.
◆ log_available
|
static |
Definition at line 202 of file ear_cam_pipe.c.
◆ log_count
|
static |
Definition at line 200 of file ear_cam_pipe.c.
◆ log_dropped
|
static |
Definition at line 205 of file ear_cam_pipe.c.
◆ log_head
|
static |
Definition at line 200 of file ear_cam_pipe.c.
◆ log_mutex
|
static |
Definition at line 201 of file ear_cam_pipe.c.
◆ log_queue
|
static |
Definition at line 199 of file ear_cam_pipe.c.
◆ log_running
|
static |
Definition at line 204 of file ear_cam_pipe.c.
◆ log_session_id
|
static |
Definition at line 196 of file ear_cam_pipe.c.
◆ log_stopping
|
static |
Definition at line 204 of file ear_cam_pipe.c.
◆ log_thread
|
static |
Definition at line 203 of file ear_cam_pipe.c.
◆ measurement
| struct latest_measurement measurement |
Definition at line 210 of file ear_cam_pipe.c.
◆ microphone_device
|
static |
Definition at line 162 of file ear_cam_pipe.c.
◆ [struct]
| struct { ... } pending_audio[EAR_PENDING_AUDIO_WINDOWS] |
◆ pending_count
|
static |
Definition at line 214 of file ear_cam_pipe.c.
◆ pending_head
|
static |
Definition at line 214 of file ear_cam_pipe.c.
◆ pose_lookup
|
static |
Definition at line 216 of file ear_cam_pipe.c.
◆ queued_ms
| uint64_t queued_ms |
Definition at line 212 of file ear_cam_pipe.c.
◆ reader_running
|
static |
Definition at line 158 of file ear_cam_pipe.c.
◆ reader_stop
|
static |
Definition at line 159 of file ear_cam_pipe.c.
◆ reader_thread
|
static |
Definition at line 157 of file ear_cam_pipe.c.
◆ request
| union dc_shot_union request |
Definition at line 211 of file ear_cam_pipe.c.
◆ server_error_count
|
static |
Definition at line 177 of file ear_cam_pipe.c.
◆ server_input
|
static |
Definition at line 155 of file ear_cam_pipe.c.
◆ server_output
|
static |
Definition at line 156 of file ear_cam_pipe.c.
◆ server_pid
|
static |
Definition at line 154 of file ear_cam_pipe.c.
◆ server_ready
|
static |
Definition at line 176 of file ear_cam_pipe.c.
◆ server_started_ms
|
static |
Definition at line 178 of file ear_cam_pipe.c.
◆ session
|
static |
Definition at line 194 of file ear_cam_pipe.c.
◆ session_buffers
|
static |
Definition at line 192 of file ear_cam_pipe.c.
◆ session_count
|
static |
Definition at line 195 of file ear_cam_pipe.c.
◆ session_log
|
static |
Definition at line 197 of file ear_cam_pipe.c.
◆ session_log_header
|
static |
Definition at line 206 of file ear_cam_pipe.c.
◆ session_log_path
|
static |
Definition at line 198 of file ear_cam_pipe.c.
◆ simulated
|
static |
Definition at line 233 of file ear_cam_pipe.c.
◆ simulated_lat_deg
|
static |
Definition at line 234 of file ear_cam_pipe.c.
◆ simulated_level_db_at_1m
|
static |
Definition at line 236 of file ear_cam_pipe.c.
◆ simulated_lon_deg
|
static |
Definition at line 235 of file ear_cam_pipe.c.
◆ simulated_noise_state
|
static |
Definition at line 237 of file ear_cam_pipe.c.
◆ supervisor_running
|
static |
Definition at line 161 of file ear_cam_pipe.c.
◆ supervisor_stop
|
static |
Definition at line 173 of file ear_cam_pipe.c.
◆ supervisor_thread
|
static |
Definition at line 160 of file ear_cam_pipe.c.