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

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>
Include dependency graph for ear_cam_pipe.c:

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...

Macros

#define USHER_EAR_CAM_COMMAND   "./bin/earcam"
#define USHER_EAR_CAM_DEVICE   "auto"
#define USHER_EAR_CAM_LOG_DIR   "earlogs"
#define USHER_EAR_CAM_PHOTO_DIR   "~/Pictures/sensoraia"
#define EAR_READY_TIMEOUT_MS   15000
#define EAR_RESTART_INTERVAL_MS   3000U
#define EAR_WARNING_INTERVAL_MS   1000U
#define EAR_SAMPLE_STALE_MS   500U
#define EAR_LINE_MAX   512U
#define ANGLE_BFP_SCALE   4096.0
#define POSITION_BFP_SCALE   256.0
#define EARTH_RADIUS_M   6378137.0
#define DEG_TO_RAD   0.017453292519943295
#define RAD_TO_DEG   57.29577951308232
#define EAR_SESSION_BUFFER_COUNT   2
#define EAR_MICROPHONE_NAME_CAPACITY   256
#define EAR_LOG_PATH_CAPACITY   512
#define EAR_LOG_ROW_CAPACITY   512
#define EAR_LOG_QUEUE_ROWS   128
#define EAR_LOG_BATCH_ROWS   16
#define EAR_SESSION_MARKER_CAPACITY   128
#define EAR_PENDING_AUDIO_WINDOWS   16
#define EAR_BAND_ARGUMENT_CAPACITY   32
#define EAR_READER_CHUNK_BYTES   256
#define EAR_READER_POLL_MS   200
#define EAR_POSE_WAIT_MS   200
#define EAR_SAMPLE_FUTURE_SLACK_MS   1
#define EAR_CHILD_REAP_ATTEMPTS   25
#define EAR_CHILD_TERM_ATTEMPT   10
#define EAR_CHILD_KILL_ATTEMPT   20
#define EAR_SUPERVISOR_TICK_MS   20
#define EAR_LOG_FILENAME_ATTEMPTS   128
#define EAR_EVIDENCE_FILENAME_ATTEMPTS   32
#define EAR_LOG_FILE_MODE   0644
#define EAR_EVIDENCE_FILE_MODE   0600
#define EAR_TM_YEAR_ORIGIN   1900
#define EAR_JPEG_SUFFIX_LENGTH   4
#define EAR_MS_PER_SECOND   1000U
#define EAR_NS_PER_MS   1000000U
#define EAR_SLEEP_NS_PER_MS   1000000L
#define EAR_US_PER_MS   1000
#define EAR_COORDINATE_UNITS_PER_DEG   1e7
#define EAR_ALTITUDE_UNITS_PER_METER   1000.0
#define EAR_AUDIO_WINDOW_LIMIT_US   1000000
#define EAR_AUDIO_TIMING_ERROR_LIMIT_US   100000
#define EAR_AUDIO_FUTURE_SLACK_US   1000
#define EAR_SAMPLE_PREFIX_LENGTH   7
#define EAR_READY_PREFIX_LENGTH   12
#define EAR_ERROR_PREFIX_LENGTH   12
#define EAR_STOPPED_PREFIX_LENGTH   14
#define EAR_SIM_NOISE_INITIAL_STATE   0x2545F491U
#define EAR_SIM_XORSHIFT_LEFT_FIRST   13
#define EAR_SIM_XORSHIFT_RIGHT   17
#define EAR_SIM_XORSHIFT_LEFT_LAST   5
#define EAR_SIM_NOISE_STEPS   30001U
#define EAR_SIM_NOISE_STEPS_PER_DB   10000.0
#define EAR_SIM_NOISE_HALF_RANGE_DB   1.5
#define EAR_SIM_REFERENCE_DISTANCE_M   1.0
#define EAR_SIM_DISTANCE_DB_PER_DECADE   20.0
#define EAR_SIM_CONTRAST_DB   6.0
#define EAR_SIM_FREQUENCY_HZ   2700.0

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.

Variables

char ** environ
static pid_t server_pid = -1
static int server_input = -1
static int server_output = -1
static pthread_t reader_thread
static bool reader_running
static atomic_bool reader_stop
static pthread_t supervisor_thread
static bool supervisor_running
static char microphone_device [EAR_MICROPHONE_NAME_CAPACITY] = USHER_EAR_CAM_DEVICE
static char ear_settings [PATH_MAX]
static atomic_bool supervisor_stop
static pthread_mutex_t ear_mutex = PTHREAD_MUTEX_INITIALIZER
static struct latest_measurement latest
static bool server_ready
static uint64_t server_error_count
static uint64_t server_started_ms
static uint64_t last_warning_ms
static struct ear_session_snapshot session_buffers [EAR_SESSION_BUFFER_COUNT] = {{.owned = true}, {.owned = false}}
static struct ear_session_snapshot * active_session = &session_buffers[0]
static struct ear_sample * session = session_buffers[0].samples
static size_t session_count
static uint32_t log_session_id
static FILE * session_log
static char session_log_path [EAR_LOG_PATH_CAPACITY]
static char log_queue [EAR_LOG_QUEUE_ROWS][EAR_LOG_ROW_CAPACITY]
static size_t log_head
static size_t log_count
static pthread_mutex_t log_mutex = PTHREAD_MUTEX_INITIALIZER
static pthread_cond_t log_available = PTHREAD_COND_INITIALIZER
static pthread_t log_thread
static bool log_running
static bool log_stopping
static atomic_uint_fast64_t log_dropped
static const char session_log_header []
struct { 
   struct latest_measurement   measurement 
   union dc_shot_union   request 
   uint64_t   queued_ms 
} pending_audio [EAR_PENDING_AUDIO_WINDOWS]
static size_t pending_head
static size_t pending_count
static uint64_t last_window_end
static bool(* pose_lookup )(struct capture_observation *, uint64_t)
static bool simulated
static double simulated_lat_deg
static double simulated_lon_deg
static double simulated_level_db_at_1m
static uint32_t simulated_noise_state = EAR_SIM_NOISE_INITIAL_STATE
static char band_low_arg [EAR_BAND_ARGUMENT_CAPACITY]
static char band_high_arg [EAR_BAND_ARGUMENT_CAPACITY]
static bool band_set

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()

int add_inherited_descriptor_closes ( posix_spawn_file_actions_t * actions,
const int command_pipe[2],
const int response_pipe[2] )
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()

void close_session_log ( void )
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()

void commit_audio_sample ( const union dc_shot_union * request,
const struct latest_measurement * measurement )
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_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 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_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 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
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 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
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 )

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
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 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()

void flush_pending_audio ( bool force)
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()

int format_session_row ( const struct ear_sample * sample,
uint32_t session_id,
char * line,
size_t size )
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()

void handle_server_line ( const char * 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()

uint64_t monotonic_ms ( void )
static

Return monotonic milliseconds for server freshness and retry decisions.

Definition at line 306 of file ear_cam_pipe.c.

◆ open_session_log()

int open_session_log ( void )
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()

int parse_field ( const char * line,
const char * key,
double * value )
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()

bool parse_unsigned_field ( const char * line,
const char * key,
uint64_t * value )
static

Parse exact unsigned timing/sequence evidence without rounding through double.

Definition at line 355 of file ear_cam_pipe.c.

◆ queue_session_log()

void queue_session_log ( const char * line)
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()

void * reader_main ( void * unused)
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()

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 )
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()

struct latest_measurement simulated_measurement ( const union dc_shot_union * shot,
uint64_t now )
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()

double simulated_noise_db ( void )
static

Produce reproducible bounded simulation noise without shared libc PRNG state.

Definition at line 266 of file ear_cam_pipe.c.

◆ sleep_ms()

void sleep_ms ( unsigned int milliseconds)
static

Sleep through signal interruption for bounded lifecycle polling.

Definition at line 314 of file ear_cam_pipe.c.

◆ start_server()

int start_server ( void )
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()

void stop_server ( void )
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()

void * supervise_server ( void * unused)
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()

bool warning_due ( uint64_t now)
static

Rate-limit repeated unavailable/stale microphone diagnostics.

Definition at line 860 of file ear_cam_pipe.c.

◆ write_session_log()

void * write_session_log ( void * unused)
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

struct ear_session_snapshot* active_session = &session_buffers[0]
static

Definition at line 193 of file ear_cam_pipe.c.

◆ band_high_arg

char band_high_arg[EAR_BAND_ARGUMENT_CAPACITY]
static

Definition at line 250 of file ear_cam_pipe.c.

◆ band_low_arg

char band_low_arg[EAR_BAND_ARGUMENT_CAPACITY]
static

Definition at line 249 of file ear_cam_pipe.c.

◆ band_set

bool band_set
static

Definition at line 251 of file ear_cam_pipe.c.

◆ ear_mutex

pthread_mutex_t ear_mutex = PTHREAD_MUTEX_INITIALIZER
static

Definition at line 174 of file ear_cam_pipe.c.

◆ ear_settings

char ear_settings[PATH_MAX]
static

Definition at line 163 of file ear_cam_pipe.c.

◆ environ

char** environ
extern

◆ last_warning_ms

uint64_t last_warning_ms
static

Definition at line 179 of file ear_cam_pipe.c.

◆ last_window_end

uint64_t last_window_end
static

Definition at line 215 of file ear_cam_pipe.c.

◆ latest

struct latest_measurement latest
static

Definition at line 175 of file ear_cam_pipe.c.

◆ log_available

pthread_cond_t log_available = PTHREAD_COND_INITIALIZER
static

Definition at line 202 of file ear_cam_pipe.c.

◆ log_count

size_t log_count
static

Definition at line 200 of file ear_cam_pipe.c.

◆ log_dropped

atomic_uint_fast64_t log_dropped
static

Definition at line 205 of file ear_cam_pipe.c.

◆ log_head

size_t log_head
static

Definition at line 200 of file ear_cam_pipe.c.

◆ log_mutex

pthread_mutex_t log_mutex = PTHREAD_MUTEX_INITIALIZER
static

Definition at line 201 of file ear_cam_pipe.c.

◆ log_queue

char log_queue[EAR_LOG_QUEUE_ROWS][EAR_LOG_ROW_CAPACITY]
static

Definition at line 199 of file ear_cam_pipe.c.

◆ log_running

bool log_running
static

Definition at line 204 of file ear_cam_pipe.c.

◆ log_session_id

uint32_t log_session_id
static

Definition at line 196 of file ear_cam_pipe.c.

◆ log_stopping

bool log_stopping
static

Definition at line 204 of file ear_cam_pipe.c.

◆ log_thread

pthread_t 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

char microphone_device[EAR_MICROPHONE_NAME_CAPACITY] = USHER_EAR_CAM_DEVICE
static

Definition at line 162 of file ear_cam_pipe.c.

◆ [struct]

struct { ... } pending_audio[EAR_PENDING_AUDIO_WINDOWS]

◆ pending_count

size_t pending_count
static

Definition at line 214 of file ear_cam_pipe.c.

◆ pending_head

size_t pending_head
static

Definition at line 214 of file ear_cam_pipe.c.

◆ pose_lookup

bool(* pose_lookup) (struct capture_observation *, uint64_t) ( struct capture_observation * ,
uint64_t  )
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

bool reader_running
static

Definition at line 158 of file ear_cam_pipe.c.

◆ reader_stop

atomic_bool reader_stop
static

Definition at line 159 of file ear_cam_pipe.c.

◆ reader_thread

pthread_t 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

uint64_t server_error_count
static

Definition at line 177 of file ear_cam_pipe.c.

◆ server_input

int server_input = -1
static

Definition at line 155 of file ear_cam_pipe.c.

◆ server_output

int server_output = -1
static

Definition at line 156 of file ear_cam_pipe.c.

◆ server_pid

pid_t server_pid = -1
static

Definition at line 154 of file ear_cam_pipe.c.

◆ server_ready

bool server_ready
static

Definition at line 176 of file ear_cam_pipe.c.

◆ server_started_ms

uint64_t server_started_ms
static

Definition at line 178 of file ear_cam_pipe.c.

◆ session

struct ear_sample* session = session_buffers[0].samples
static

Definition at line 194 of file ear_cam_pipe.c.

◆ session_buffers

struct ear_session_snapshot session_buffers[EAR_SESSION_BUFFER_COUNT] = {{.owned = true}, {.owned = false}}
static

Definition at line 192 of file ear_cam_pipe.c.

◆ session_count

size_t session_count
static

Definition at line 195 of file ear_cam_pipe.c.

◆ session_log

FILE* session_log
static

Definition at line 197 of file ear_cam_pipe.c.

◆ session_log_header

const char session_log_header[]
static
Initial value:
=
"t_ms,shot,lat_deg,lon_deg,agl_m,alt_m,level_db,trend_db,contrast_db,freq_hz,alarm,clip,"
"pose_aligned,pose_uncertainty_m,window_earliest_us,window_latest_us,sequence,request_lat_deg,request_lon_deg,session_id,detector_kind,classification_score,classification_class\n"

Definition at line 206 of file ear_cam_pipe.c.

◆ session_log_path

char session_log_path[EAR_LOG_PATH_CAPACITY]
static

Definition at line 198 of file ear_cam_pipe.c.

◆ simulated

bool simulated
static

Definition at line 233 of file ear_cam_pipe.c.

◆ simulated_lat_deg

double simulated_lat_deg
static

Definition at line 234 of file ear_cam_pipe.c.

◆ simulated_level_db_at_1m

double simulated_level_db_at_1m
static

Definition at line 236 of file ear_cam_pipe.c.

◆ simulated_lon_deg

double simulated_lon_deg
static

Definition at line 235 of file ear_cam_pipe.c.

◆ simulated_noise_state

uint32_t simulated_noise_state = EAR_SIM_NOISE_INITIAL_STATE
static

Definition at line 237 of file ear_cam_pipe.c.

◆ supervisor_running

bool supervisor_running
static

Definition at line 161 of file ear_cam_pipe.c.

◆ supervisor_stop

atomic_bool supervisor_stop
static

Definition at line 173 of file ear_cam_pipe.c.

◆ supervisor_thread

pthread_t supervisor_thread
static

Definition at line 160 of file ear_cam_pipe.c.