Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
ear_camera_backend.c File Reference

EAR-owned survey admission, finalization and generic point completions. More...

#include "ear_camera_backend.h"
#include "ear_cam_pipe.h"
#include "image_exif.h"
#include <errno.h>
#include <limits.h>
#include <math.h>
#include <pthread.h>
#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
#include <unistd.h>
Include dependency graph for ear_camera_backend.c:

Go to the source code of this file.

Data Structures

struct  ear_finalize_job
 One reservation progressing through snapshot -> point -> evidence completion. More...

Macros

#define USHER_SODA   "./bin/soda"
#define EAR_FINALIZE_JOB_COUNT   2
#define EAR_COMPLETION_ENDPOINT_COUNT   2
#define EAR_COMPLETION_DRAIN_BYTES   16
#define EAR_EVIDENCE_PATH_CAPACITY   512
#define EAR_LATITUDE_LIMIT_DEG   90
#define EAR_LONGITUDE_LIMIT_DEG   180
#define EAR_COORDINATE_UNITS_PER_DEG   1e7
#define EAR_MILLIMETERS_PER_METER   1000.0
#define EAR_QUALITY_UNITS_PER_SCORE   1000.0
#define EAR_METRIC_UNITS_PER_DB   100.0
#define EAR_SHOT_AGL_UNITS_PER_METER   256.0

Functions

static bool ear_point_valid (const struct ear_loudest_spot *spot)
 Guard finite values and integer conversion ranges before marking a wire point valid.
static void wake_ear_result_owner (void)
 Notify the serial owner without blocking; mailbox flags remain authoritative if full.
static void * finalize_ear_sessions (void *unused)
 Drain stopped sessions in admission order until shutdown has no work left.
static bool ear_poll_result (struct camera_point_result *result)
 Consume one completion on the serial owner and convert physical units once.
static bool ear_start (uint32_t session_id)
 Reserve both finalizer capacity and adapter storage before listening.
static bool ear_stop (uint32_t session_id)
 Validate the active token before a zero-copy snapshot handoff.
static void ear_drain (void)
 Close admission and join all admitted stopped-session evidence work.
static bool ear_listening (void)
 Whether the serial owner should admit EAR samples for the current session.
static int ear_completion_fd (void)
 Nonblocking completion descriptor, or -1 before start/after drain.
static void ear_configure (const struct camera_backend_host *host)
 Copy startup-only host callbacks; worker-side queue_analysis must be thread-safe.
static int ear_init (const char *source)
 Initialize supervision, not microphone readiness; hard setup failure stays latched.
static void ear_deinit (void)
 Drain before tearing down audio/storage, then reset quiescent finalizer state.
bool ear_camera_backend_set_device (const char *device)
 Copy an ALSA PCM name before initialization or worker startup.
void ear_camera_backend_set_simulated_source (double lat_deg, double lon_deg, double level_db_at_1m)
 Select deterministic synthetic audio before initialization, bypassing ALSA.
void ear_camera_backend_set_band (double low_cut_hz, double high_cut_hz)
 Forward startup tone-band selection to the audio adapter.
struct camera_backend ear_camera_backend_get (void)
 Return the EAR backend descriptor by value; its session hook table has static lifetime.

Variables

static struct camera_backend_host ear_host
static bool earcam_active
static bool earcam_unavailable
static bool earcam_session_active
static bool earcam_simulated
static struct ear_finalize_job ear_finalize_jobs [EAR_FINALIZE_JOB_COUNT]
static struct ear_finalize_job * current_ear_job
static uint64_t ear_finalize_order
static pthread_mutex_t ear_finalize_mutex = PTHREAD_MUTEX_INITIALIZER
static pthread_cond_t ear_finalize_available = PTHREAD_COND_INITIALIZER
static pthread_t ear_finalize_thread
static bool ear_finalize_started
static bool ear_finalize_stopping
static int ear_finalize_wake [EAR_COMPLETION_ENDPOINT_COUNT] = {-1, -1}

Detailed Description

EAR-owned survey admission, finalization and generic point completions.

USHER's serial owner calls lifecycle/configuration/poll hooks. One joinable worker solves immutable snapshots and writes evidence; it never owns UART or live pose lookup. A small wake channel signals mailbox state, not data.

Definition in file ear_camera_backend.c.

Macro Definition Documentation

◆ EAR_COMPLETION_DRAIN_BYTES

#define EAR_COMPLETION_DRAIN_BYTES   16

Definition at line 45 of file ear_camera_backend.c.

◆ EAR_COMPLETION_ENDPOINT_COUNT

#define EAR_COMPLETION_ENDPOINT_COUNT   2

Definition at line 44 of file ear_camera_backend.c.

◆ EAR_COORDINATE_UNITS_PER_DEG

#define EAR_COORDINATE_UNITS_PER_DEG   1e7

Definition at line 49 of file ear_camera_backend.c.

◆ EAR_EVIDENCE_PATH_CAPACITY

#define EAR_EVIDENCE_PATH_CAPACITY   512

Definition at line 46 of file ear_camera_backend.c.

◆ EAR_FINALIZE_JOB_COUNT

#define EAR_FINALIZE_JOB_COUNT   2

Two jobs match the adapter's two buffers: stopped evidence is never evicted.

Definition at line 43 of file ear_camera_backend.c.

◆ EAR_LATITUDE_LIMIT_DEG

#define EAR_LATITUDE_LIMIT_DEG   90

Definition at line 47 of file ear_camera_backend.c.

◆ EAR_LONGITUDE_LIMIT_DEG

#define EAR_LONGITUDE_LIMIT_DEG   180

Definition at line 48 of file ear_camera_backend.c.

◆ EAR_METRIC_UNITS_PER_DB

#define EAR_METRIC_UNITS_PER_DB   100.0

Definition at line 52 of file ear_camera_backend.c.

◆ EAR_MILLIMETERS_PER_METER

#define EAR_MILLIMETERS_PER_METER   1000.0

Definition at line 50 of file ear_camera_backend.c.

◆ EAR_QUALITY_UNITS_PER_SCORE

#define EAR_QUALITY_UNITS_PER_SCORE   1000.0

Definition at line 51 of file ear_camera_backend.c.

◆ EAR_SHOT_AGL_UNITS_PER_METER

#define EAR_SHOT_AGL_UNITS_PER_METER   256.0

Legacy dc_shot groundalt carries AGL in Q8 metres, unlike CAM_POINT_RESULT millimetres.

Definition at line 54 of file ear_camera_backend.c.

◆ USHER_SODA

#define USHER_SODA   "./bin/soda"

Definition at line 39 of file ear_camera_backend.c.

Function Documentation

◆ ear_camera_backend_get()

struct camera_backend ear_camera_backend_get ( void )

Return the EAR backend descriptor by value; its session hook table has static lifetime.

Returns
Descriptor advertising point-session capability, not optical still capture.

Definition at line 344 of file ear_camera_backend.c.

◆ ear_camera_backend_set_band()

void ear_camera_backend_set_band ( double low_cut_hz,
double high_cut_hz )

Forward startup tone-band selection to the audio adapter.

Parameters
low_cut_hzLower band edge, hertz.
high_cut_hzUpper band edge, hertz; valid ordering is the CLI caller's responsibility.

Definition at line 342 of file ear_camera_backend.c.

◆ ear_camera_backend_set_device()

bool ear_camera_backend_set_device ( const char * device)

Copy an ALSA PCM name before initialization or worker startup.

Parameters
deviceNonempty bounded ALSA name, such as default or plughw:CARD=USB,DEV=0.
Returns
True when copied; false for invalid input or active lifecycle state.

Caller memory may be released on return. Simulation is selected separately.

Definition at line 332 of file ear_camera_backend.c.

◆ ear_camera_backend_set_simulated_source()

void ear_camera_backend_set_simulated_source ( double lat_deg,
double lon_deg,
double level_db_at_1m )

Select deterministic synthetic audio before initialization, bypassing ALSA.

Parameters
lat_degFixed source latitude, degrees.
lon_degFixed source longitude, degrees.
level_db_at_1mSimulated level at one metre; a test model, not measured calibration.

Definition at line 337 of file ear_camera_backend.c.

◆ ear_completion_fd()

int ear_completion_fd ( void )
static

Nonblocking completion descriptor, or -1 before start/after drain.

Definition at line 298 of file ear_camera_backend.c.

◆ ear_configure()

void ear_configure ( const struct camera_backend_host * host)
static

Copy startup-only host callbacks; worker-side queue_analysis must be thread-safe.

Definition at line 300 of file ear_camera_backend.c.

◆ ear_deinit()

void ear_deinit ( void )
static

Drain before tearing down audio/storage, then reset quiescent finalizer state.

Definition at line 317 of file ear_camera_backend.c.

◆ ear_drain()

void ear_drain ( void )
static

Close admission and join all admitted stopped-session evidence work.

Completed point mailboxes remain pollable after the wake channel closes. This is orderly draining, not a hard filesystem-I/O deadline or power-loss guarantee.

Definition at line 280 of file ear_camera_backend.c.

◆ ear_init()

int ear_init ( const char * source)
static

Initialize supervision, not microphone readiness; hard setup failure stays latched.

Definition at line 307 of file ear_camera_backend.c.

◆ ear_listening()

bool ear_listening ( void )
static

Whether the serial owner should admit EAR samples for the current session.

Definition at line 296 of file ear_camera_backend.c.

◆ ear_point_valid()

bool ear_point_valid ( const struct ear_loudest_spot * spot)
static

Guard finite values and integer conversion ranges before marking a wire point valid.

Definition at line 82 of file ear_camera_backend.c.

◆ ear_poll_result()

bool ear_poll_result ( struct camera_point_result * result)
static

Consume one completion on the serial owner and convert physical units once.

Returns
True when result receives a correlated valid or invalid point.

Wake bytes may coalesce; scan mailbox flags even after draining the socket. USHER retains responsibility for token correlation and actual UART delivery.

Definition at line 168 of file ear_camera_backend.c.

◆ ear_start()

bool ear_start ( uint32_t session_id)
static

Reserve both finalizer capacity and adapter storage before listening.

Returns
False for zero token, shutdown, exhausted capacity or worker/buffer failure.

Replacing an unfinished active session releases only its reservation; stopped snapshots stay admitted. Generic USHER routing handles duplicate tokens.

Definition at line 210 of file ear_camera_backend.c.

◆ ear_stop()

bool ear_stop ( uint32_t session_id)
static

Validate the active token before a zero-copy snapshot handoff.

Returns
True only when an immutable session was queued for the worker.

Failed detach releases the reservation; a wrong token cannot stop listening.

Definition at line 259 of file ear_camera_backend.c.

◆ finalize_ear_sessions()

void * finalize_ear_sessions ( void * unused)
static

Drain stopped sessions in admission order until shutdown has no work left.

The point mailbox is published before potentially slow CSV/JPEG/EXIF and optional SODA submission. Never perform UART sends or live pose lookups here.

Definition at line 110 of file ear_camera_backend.c.

◆ wake_ear_result_owner()

void wake_ear_result_owner ( void )
static

Notify the serial owner without blocking; mailbox flags remain authoritative if full.

Definition at line 96 of file ear_camera_backend.c.

Variable Documentation

◆ current_ear_job

struct ear_finalize_job* current_ear_job
static

Definition at line 73 of file ear_camera_backend.c.

◆ ear_finalize_available

pthread_cond_t ear_finalize_available = PTHREAD_COND_INITIALIZER
static

Definition at line 76 of file ear_camera_backend.c.

◆ ear_finalize_jobs

struct ear_finalize_job ear_finalize_jobs[EAR_FINALIZE_JOB_COUNT]
static

◆ ear_finalize_mutex

pthread_mutex_t ear_finalize_mutex = PTHREAD_MUTEX_INITIALIZER
static

Definition at line 75 of file ear_camera_backend.c.

◆ ear_finalize_order

uint64_t ear_finalize_order
static

Definition at line 74 of file ear_camera_backend.c.

◆ ear_finalize_started

bool ear_finalize_started
static

Definition at line 78 of file ear_camera_backend.c.

◆ ear_finalize_stopping

bool ear_finalize_stopping
static

Definition at line 78 of file ear_camera_backend.c.

◆ ear_finalize_thread

pthread_t ear_finalize_thread
static

Definition at line 77 of file ear_camera_backend.c.

◆ ear_finalize_wake

int ear_finalize_wake[EAR_COMPLETION_ENDPOINT_COUNT] = {-1, -1}
static

Definition at line 79 of file ear_camera_backend.c.

◆ ear_host

struct camera_backend_host ear_host
static

Definition at line 58 of file ear_camera_backend.c.

◆ earcam_active

bool earcam_active
static

Definition at line 59 of file ear_camera_backend.c.

◆ earcam_session_active

bool earcam_session_active
static

Definition at line 59 of file ear_camera_backend.c.

◆ earcam_simulated

bool earcam_simulated
static

Definition at line 59 of file ear_camera_backend.c.

◆ earcam_unavailable

bool earcam_unavailable
static

Definition at line 59 of file ear_camera_backend.c.