Fresh-first saved-image requests to the standalone loomcam process. More...
#include "loom_cam.h"#include <dirent.h>#include "inference_settings.h"#include "../modules/loom_cam/loom_return.h"#include <math.h>#include "path_utils.h"#include <errno.h>#include <fcntl.h>#include <inttypes.h>#include <limits.h>#include <poll.h>#include <pthread.h>#include <signal.h>#include <spawn.h>#include <stdatomic.h>#include <stdio.h>#include <string.h>#include <sys/wait.h>#include <sys/eventfd.h>#include <time.h>#include <unistd.h>
Go to the source code of this file.
Macros | |
| #define | USHER_LOOMCAM_COMMAND "./bin/loomcam" |
| Saved-photo child executable; not another camera-acquisition process. | |
Bounded child-process policy | |
One monotonic deadline bounds reply handling independently of fragmentation and interrupted polls. A short exit grace permits a flushed reply before exit. | |
| #define | LOOM_RESULT_LINE_BYTES 384U |
| #define | LOOM_SEQUENCE_TEXT_BYTES 16U |
| #define | LOOM_WORKER_POLL_MS 50 |
| #define | LOOM_WORKER_TIMEOUT_MS 5000U |
| #define | LOOM_EXIT_GRACE_MS 200U |
| #define | LOOM_KILL_GRACE_MS 1000U |
| #define | LOOM_NS_PER_MS 1000000L |
| #define | LOOM_REFERENCE_PHOTO_LIMIT 256U |
| #define | LOOM_REFERENCE_SESSION_LIMIT 64U |
Saved-photo and wire-unit conventions | |
Geographic limits are degrees multiplied by 1e7; quality is in thousandths. The reference filename uses ten digits to cover every uint32_t photo number. | |
| #define | LOOM_LATITUDE_LIMIT_E7 INT32_C(900000000) |
| #define | LOOM_LONGITUDE_LIMIT_E7 INT32_C(1800000000) |
| #define | LOOM_QUALITY_MAX INT32_C(1000) |
| #define | LOOM_REFERENCE_SEQUENCE_DIGITS 10 |
| #define | LOOM_JPEG_EXTENSION ".jpg" |
| #define | LOOM_JPEG_EXTENSION_BYTES (sizeof(LOOM_JPEG_EXTENSION) - 1U) |
| #define | LOOM_DECIMAL_RADIX 10 |
Enumerations | |
| enum | loom_result_field { LOOM_FIELD_SEQUENCE , LOOM_FIELD_VALID , LOOM_FIELD_LATITUDE , LOOM_FIELD_LONGITUDE , LOOM_FIELD_ALTITUDE_MM , LOOM_FIELD_AGL_MM , LOOM_FIELD_QUALITY , LOOM_FIELD_METRIC , LOOM_RESULT_FIELD_COUNT } |
| Ordered fields of the strict LOOM_POINT_V1 text contract. More... | |
| enum | loom_wire_validity { LOOM_WIRE_INVALID = 0 , LOOM_WIRE_VALID = 1 } |
| The validity field accepts only these two numeric wire values. More... | |
| enum | loom_pipe_endpoint { LOOM_PIPE_READ , LOOM_PIPE_WRITE , LOOM_PIPE_ENDPOINT_COUNT } |
| POSIX pipe endpoints; names distinguish child output from parent input. More... | |
Functions | |
| static void | drain_notification (void) |
| Clear the completion event counter. | |
| static void | notify_completion (void) |
| Wake the event loop when completion state may have changed. | |
| static bool | copy_path (char *destination, size_t capacity, const char *source) |
| Copy a complete NUL-terminated path into owned, fixed-size storage. | |
| static bool | read_result_field (const char **cursor, const char *key, intmax_t *value) |
| Consume one exact field prefix followed by a signed decimal integer. | |
| static bool | parse_result (const char *line, uint32_t sequence, struct camera_point_result *result) |
| Validate and correlate one complete reply before publishing any fields. | |
| static uint64_t | loom_monotonic_ms (void) |
| Read the watchdog clock in milliseconds. | |
| static bool | reap_matcher (unsigned timeout_ms, int *status) |
| Wait up to a bounded time for the owned matcher to exit. | |
| static bool | matcher_phase_current (uint32_t phase) |
| Check whether an in-flight match still belongs to the active phase. | |
| static bool | run_matcher (const char *filename, const char *references, uint32_t sequence, struct camera_point_result *result, uint32_t phase) |
| Run the saved-photo matcher with bounded output and a watchdog. | |
| static bool | reference_directory_available (const char *directory) |
| Check whether a session reference directory has room for another entry. | |
| static bool | reference_root_available (const char *directory) |
| Check whether the archive root can admit another session. | |
| static bool | create_session_reference_directory (const char *base, uint32_t session_id, char *destination, size_t capacity) |
| Create an exclusive archive directory for a new session. | |
| static bool | record_reference (const char *filename, const char *directory, uint32_t sequence) |
| Archive a published outbound JPEG without copying its pixels. | |
| static bool | filter_return_point (struct camera_point_result *result) |
| Validate a return candidate in the persistent owner. | |
| static void * | loom_worker (void *unused) |
| Process the newest pending photo and suppress superseded completions. | |
| int | loom_cam_set_settings (const char *settings) |
| Select executable settings before starting the saved-photo worker. | |
| int | loom_cam_init (const char *references, const char *model) |
| Start one saved-photo worker; does not acquire another camera. | |
| bool | loom_cam_enabled (void) |
| Report whether this optional stream is running and not stopping. | |
| int | loom_cam_completion_fd (void) |
| Borrow the nonblocking completion descriptor; minus one when not initialized. | |
| bool | loom_cam_start (uint32_t session_id) |
| Select outbound reference collection and discard old-phase mailbox work. | |
| bool | loom_cam_stop (uint32_t session_id) |
| Select return matching and discard old-phase mailbox work. | |
| void | loom_cam_image_saved (const char *filename, const union dc_shot_union *shot) |
| Copy the newest completed AIcam photo request into bounded worker storage. | |
| bool | loom_cam_poll_result (struct camera_point_result *result) |
| Consume a result on the serial owner; session_id carries the photo number for this stream. | |
| void | loom_cam_deinit (void) |
| Cancel pending work and join the worker before reusing adapter state. | |
Variables | |
| char ** | environ |
| static pthread_mutex_t | loom_mutex = PTHREAD_MUTEX_INITIALIZER |
| static pthread_cond_t | loom_available = PTHREAD_COND_INITIALIZER |
| static pthread_t | loom_thread |
| static atomic_bool | loom_stopping |
| static atomic_bool | loom_running |
| static bool | loom_pending |
| The latest copied path awaits worker consumption; older pending work is replaceable. | |
| static bool | loom_ready |
| static uint32_t | loom_latest_sequence |
| static uint32_t | loom_session |
| START token used to admit the corresponding STOP, not a photo number. | |
| static uint32_t | loom_phase |
| static bool | loom_recording |
| static char | loom_filename [PATH_MAX] |
| Latest admitted immutable saved-photo path, copied into bounded storage. | |
| static char | loom_references [PATH_MAX] |
| Reference-directory configuration, fixed until the worker has been joined. | |
| static char | loom_session_references [PATH_MAX] |
| static char | loom_model [PATH_MAX] |
| static char | loom_settings [PATH_MAX] |
| static struct loom_return_options | loom_return_options |
| static struct loom_return_state | loom_return_state |
| static struct camera_point_result | loom_result |
| static pid_t | loom_matcher_pid = -1 |
| static int | loom_notification = -1 |
Detailed Description
Fresh-first saved-image requests to the standalone loomcam process.
The AI camera remains owned by its existing driver. This adapter owns only paths, one pending request, one joinable worker and one completion mailbox. It never sends UART or mutates flight waypoints. Return vectors are validated, but archived reference photographs are not yet compared against live images.
Definition in file loom_cam.c.
Macro Definition Documentation
◆ LOOM_DECIMAL_RADIX
| #define LOOM_DECIMAL_RADIX 10 |
Reply grammar accepts explicit decimal integers only.
Definition at line 78 of file loom_cam.c.
◆ LOOM_EXIT_GRACE_MS
| #define LOOM_EXIT_GRACE_MS 200U |
Allow a flushed reply to precede normal child exit.
Definition at line 61 of file loom_cam.c.
◆ LOOM_JPEG_EXTENSION
| #define LOOM_JPEG_EXTENSION ".jpg" |
Final suffix replaced when associating saved sidecars.
Definition at line 76 of file loom_cam.c.
◆ LOOM_JPEG_EXTENSION_BYTES
| #define LOOM_JPEG_EXTENSION_BYTES (sizeof(LOOM_JPEG_EXTENSION) - 1U) |
Exclude the string terminator.
Definition at line 77 of file loom_cam.c.
◆ LOOM_KILL_GRACE_MS
| #define LOOM_KILL_GRACE_MS 1000U |
Maximum wait for a killed owned child.
Definition at line 62 of file loom_cam.c.
◆ LOOM_LATITUDE_LIMIT_E7
| #define LOOM_LATITUDE_LIMIT_E7 INT32_C(900000000) |
Latitude range in degrees times 1e7.
Definition at line 72 of file loom_cam.c.
◆ LOOM_LONGITUDE_LIMIT_E7
| #define LOOM_LONGITUDE_LIMIT_E7 INT32_C(1800000000) |
Longitude range in the same wire units.
Definition at line 73 of file loom_cam.c.
◆ LOOM_NS_PER_MS
| #define LOOM_NS_PER_MS 1000000L |
Convert the poll interval for nanosleep.
Definition at line 63 of file loom_cam.c.
◆ LOOM_QUALITY_MAX
| #define LOOM_QUALITY_MAX INT32_C(1000) |
Quality uses thousandths, not an arbitrary float score.
Definition at line 74 of file loom_cam.c.
◆ LOOM_REFERENCE_PHOTO_LIMIT
| #define LOOM_REFERENCE_PHOTO_LIMIT 256U |
Bound hard links retained for one sortie.
Definition at line 64 of file loom_cam.c.
◆ LOOM_REFERENCE_SEQUENCE_DIGITS
| #define LOOM_REFERENCE_SEQUENCE_DIGITS 10 |
Fits every uint32 photo number in the archive basename.
Definition at line 75 of file loom_cam.c.
◆ LOOM_REFERENCE_SESSION_LIMIT
| #define LOOM_REFERENCE_SESSION_LIMIT 64U |
Bound retained sortie directories without pruning evidence.
Definition at line 65 of file loom_cam.c.
◆ LOOM_RESULT_LINE_BYTES
| #define LOOM_RESULT_LINE_BYTES 384U |
Fixed result storage bounds a child's reply.
Definition at line 57 of file loom_cam.c.
◆ LOOM_SEQUENCE_TEXT_BYTES
| #define LOOM_SEQUENCE_TEXT_BYTES 16U |
Decimal uint32 ID plus terminator, without truncation.
Definition at line 58 of file loom_cam.c.
◆ LOOM_WORKER_POLL_MS
| #define LOOM_WORKER_POLL_MS 50 |
Watchdog poll interval; shutdown is checked between polls.
Definition at line 59 of file loom_cam.c.
◆ LOOM_WORKER_TIMEOUT_MS
| #define LOOM_WORKER_TIMEOUT_MS 5000U |
Whole reply operation budget in monotonic milliseconds.
Definition at line 60 of file loom_cam.c.
◆ USHER_LOOMCAM_COMMAND
| #define USHER_LOOMCAM_COMMAND "./bin/loomcam" |
Saved-photo child executable; not another camera-acquisition process.
Definition at line 51 of file loom_cam.c.
Enumeration Type Documentation
◆ loom_pipe_endpoint
| enum loom_pipe_endpoint |
POSIX pipe endpoints; names distinguish child output from parent input.
| Enumerator | |
|---|---|
| LOOM_PIPE_READ | |
| LOOM_PIPE_WRITE | |
| LOOM_PIPE_ENDPOINT_COUNT | |
Definition at line 97 of file loom_cam.c.
◆ loom_result_field
| enum loom_result_field |
Ordered fields of the strict LOOM_POINT_V1 text contract.
| Enumerator | |
|---|---|
| LOOM_FIELD_SEQUENCE | |
| LOOM_FIELD_VALID | |
| LOOM_FIELD_LATITUDE | |
| LOOM_FIELD_LONGITUDE | |
| LOOM_FIELD_ALTITUDE_MM | |
| LOOM_FIELD_AGL_MM | |
| LOOM_FIELD_QUALITY | |
| LOOM_FIELD_METRIC | |
| LOOM_RESULT_FIELD_COUNT | |
Definition at line 82 of file loom_cam.c.
◆ loom_wire_validity
| enum loom_wire_validity |
The validity field accepts only these two numeric wire values.
| Enumerator | |
|---|---|
| LOOM_WIRE_INVALID | |
| LOOM_WIRE_VALID | |
Definition at line 95 of file loom_cam.c.
Function Documentation
◆ copy_path()
|
static |
Copy a complete NUL-terminated path into owned, fixed-size storage.
- Parameters
-
destination Writable buffer of capacitybytes.capacity Buffer size, including space for the terminator. source Borrowed path; NULL selects an empty optional configuration.
- Returns
- True on complete copy; false rather than silently truncating a path.
Definition at line 158 of file loom_cam.c.
◆ create_session_reference_directory()
|
static |
Create an exclusive archive directory for a new session.
- Parameters
-
base Archive root path. session_id Identifier formatted into the directory name. [out] destination Buffer for the formatted directory path. capacity Size of destination, including its terminator.
- Returns
- True only if a new directory was created.
Apply the root entry limit first and use exclusive directory creation so a reused session ID cannot silently inherit old references.
Definition at line 420 of file loom_cam.c.
◆ drain_notification()
|
static |
Clear the completion event counter.
The mailbox owns the result; the event counter only indicates that the event loop should inspect it under the stream's synchronization.
Definition at line 132 of file loom_cam.c.
◆ filter_return_point()
|
static |
Validate a return candidate in the persistent owner.
- Parameters
-
[in,out] result Candidate, updated if the configured filter accepts it.
- Returns
- True for an accepted candidate or an explicit no-point result.
Keep ordering state across matcher subprocesses. Apply confidence and reference checks before passing an eligible candidate to the estimator.
Definition at line 479 of file loom_cam.c.
◆ loom_cam_completion_fd()
| int loom_cam_completion_fd | ( | void | ) |
Borrow the nonblocking completion descriptor; minus one when not initialized.
Definition at line 613 of file loom_cam.c.
◆ loom_cam_deinit()
| void loom_cam_deinit | ( | void | ) |
Cancel pending work and join the worker before reusing adapter state.
Wakes an idle worker or causes its child watchdog to terminate/reap the process. Unlike admission/polling, shutdown waits for the worker to exit.
- Precondition
- Lifecycle calls are serialized; do not call from the worker itself.
Definition at line 695 of file loom_cam.c.
◆ loom_cam_enabled()
| bool loom_cam_enabled | ( | void | ) |
Report whether this optional stream is running and not stopping.
- Returns
- True when phase callbacks may be admitted; false otherwise.
- Note
- Uses atomic lifecycle flags; no camera acquisition or mutex wait occurs.
Definition at line 608 of file loom_cam.c.
◆ loom_cam_image_saved()
| void loom_cam_image_saved | ( | const char * | filename, |
| const union dc_shot_union * | shot ) |
Copy the newest completed AIcam photo request into bounded worker storage.
- Parameters
-
filename Immutable saved JPEG path, borrowed only for this call. shot Completed photo pose/request; its positive number correlates the update.
Thread-safe and nonblocking; pending work is fresh-first, not an evidence archive. Busy admission, invalid input, overlong paths and duplicate/reversed photo numbers are dropped. The file itself must remain available to the worker.
Definition at line 669 of file loom_cam.c.
◆ loom_cam_init()
| int loom_cam_init | ( | const char * | references, |
| const char * | model ) |
Start one saved-photo worker; does not acquire another camera.
- Parameters
-
references Optional outbound-photo directory, copied before return. model Optional native capture RPK path, copied before return.
- Returns
- Zero on startup, -1 for invalid paths or worker setup failure.
Starts in return mode; only the configured current-photo model vector is interpreted. Outbound references are retained but are not yet compared. NULL paths select empty configuration; overlong paths are rejected, not truncated.
- Precondition
- Lifecycle calls are serialized by the owning USHER control thread.
Definition at line 568 of file loom_cam.c.
◆ loom_cam_poll_result()
| bool loom_cam_poll_result | ( | struct camera_point_result * | result | ) |
Consume a result on the serial owner; session_id carries the photo number for this stream.
- Parameters
-
result Required destination in existing point units.
- Returns
- True for a new matched or no-match result; false when absent/busy.
Consumes the single mailbox entry. True means a completion exists, not that result->valid is true; FC navigation checks must still be applied.
Definition at line 685 of file loom_cam.c.
◆ loom_cam_set_settings()
| int loom_cam_set_settings | ( | const char * | settings | ) |
Select executable settings before starting the saved-photo worker.
- Parameters
-
settings Copied path or NULL to restore executable discovery.
- Returns
- Zero when accepted, minus one while running or for an invalid path.
Definition at line 560 of file loom_cam.c.
◆ loom_cam_start()
| bool loom_cam_start | ( | uint32_t | session_id | ) |
Select outbound reference collection and discard old-phase mailbox work.
- Parameters
-
session_id Admitted nonzero FC session token, not a photo number.
- Returns
- True if accepted by a running worker; false for zero or shutdown.
Advances a phase generation to suppress in-flight old-phase results. The original photo archive remains authoritative if reference work is dropped.
Definition at line 621 of file loom_cam.c.
◆ loom_cam_stop()
| bool loom_cam_stop | ( | uint32_t | session_id | ) |
Select return matching and discard old-phase mailbox work.
- Parameters
-
session_id Nonzero token matching the most recently admitted START.
- Returns
- True if the token is accepted; false if absent, mismatched or stopping.
- Note
- Acceptance changes local mode; it does not prove a neural match exists.
Definition at line 652 of file loom_cam.c.
◆ loom_monotonic_ms()
|
static |
Read the watchdog clock in milliseconds.
- Returns
- Monotonic milliseconds, or zero if the clock cannot be read.
Wall-clock corrections must not extend or shorten a matcher deadline.
Definition at line 235 of file loom_cam.c.
◆ loom_worker()
|
static |
Process the newest pending photo and suppress superseded completions.
- Parameters
-
unused Required pthread argument; no per-thread heap state is used.
- Returns
- NULL after shutdown.
Snapshot the pending work under the mutex and release it before filesystem or child I/O. The phase generation prevents work from a previous phase from publishing into the new one, even if a photo number is reused.
Definition at line 524 of file loom_cam.c.
◆ matcher_phase_current()
|
static |
Check whether an in-flight match still belongs to the active phase.
- Parameters
-
phase Generation saved when the photo was admitted.
- Returns
- True if that generation can still produce a result.
Consult shared phase state under the mutex; photo numbers alone cannot distinguish work across phase changes.
Definition at line 276 of file loom_cam.c.
◆ notify_completion()
|
static |
Wake the event loop when completion state may have changed.
The nonblocking event descriptor is not a result queue. A saturated counter already has the desired readable state.
Definition at line 143 of file loom_cam.c.
◆ parse_result()
|
static |
Validate and correlate one complete reply before publishing any fields.
- Parameters
-
line NUL-terminated reply; only one optional final newline is allowed. sequence Photo number that the child must echo exactly. [out] result Destination, changed only after the whole reply is accepted.
- Returns
- True for a well-formed matched or no-match reply.
A valid point must fit geographic and quality limits. An invalid reply may retain int32 diagnostics, but cannot authorize navigation. FC-side freshness, request eligibility and waypoint guards remain independent gates.
Definition at line 201 of file loom_cam.c.
◆ read_result_field()
|
static |
Consume one exact field prefix followed by a signed decimal integer.
- Parameters
-
[in,out] cursor Current parse position; advanced only after conversion. key Exact prefix, including the separator between fields. [out] value Parsed wide integer, before wire-range validation.
- Returns
- False for missing digits, prefix mismatch or integer overflow.
Reject leading whitespace and a plus sign instead of allowing strtoimax() to quietly accept a different producer grammar.
Definition at line 176 of file loom_cam.c.
◆ reap_matcher()
|
static |
Wait up to a bounded time for the owned matcher to exit.
- Parameters
-
timeout_ms Polling budget in milliseconds. [out] status Optional wait status, set when ownership is cleared.
- Returns
- True if no matcher remains owned; false on timeout or a wait error.
Use nonblocking waits to preserve the deadline. On failure retain the PID so a later cleanup attempt does not lose ownership.
Definition at line 250 of file loom_cam.c.
◆ record_reference()
|
static |
Archive a published outbound JPEG without copying its pixels.
- Parameters
-
filename Original saved JPEG. directory Existing session archive. sequence Photo number used in the reference basename.
- Returns
- True if the new reference was linked.
A hard link neither copies the image nor replaces an existing reference. The original must remain immutable and on the same filesystem.
Definition at line 438 of file loom_cam.c.
◆ reference_directory_available()
|
static |
Check whether a session reference directory has room for another entry.
- Parameters
-
directory Path of the existing session directory.
- Returns
- True if the directory could be read and is below its entry limit.
Count existing directory entries instead of relying on in-memory counters so pre-existing files still count against the archive bound.
Definition at line 391 of file loom_cam.c.
◆ reference_root_available()
|
static |
Check whether the archive root can admit another session.
- Parameters
-
directory Path of the archive root.
- Returns
- True if the directory could be read and is below its entry limit.
Stop scanning at the bound; old sessions remain on disk and consume capacity rather than being silently evicted.
Definition at line 455 of file loom_cam.c.
◆ run_matcher()
|
static |
Run the saved-photo matcher with bounded output and a watchdog.
- Parameters
-
filename Immutable saved JPEG to process, not another capture request. references Reference archive for this phase. sequence Photo number that the matcher must echo. phase Generation used to cancel superseded work. [out] result Accepted reply; unchanged on execution or parsing failure.
- Returns
- True only for a well-formed current reply and a successful child exit.
Pass arguments directly and collect the reply on a private stdout pipe. Monitor the deadline and phase while reading so slow or superseded work cannot indefinitely hold the worker.
Definition at line 296 of file loom_cam.c.
Variable Documentation
◆ environ
|
extern |
Borrowed POSIX environment passed to the explicit-argv child.
◆ loom_available
|
static |
Wakes the worker for pending work or shutdown.
Definition at line 104 of file loom_cam.c.
◆ loom_filename
|
static |
Latest admitted immutable saved-photo path, copied into bounded storage.
Definition at line 120 of file loom_cam.c.
◆ loom_latest_sequence
|
static |
Highest admitted FC photo number; rejects duplicates/reversed work.
Definition at line 111 of file loom_cam.c.
◆ loom_matcher_pid
|
static |
Definition at line 126 of file loom_cam.c.
◆ loom_model
|
static |
Owned model/configuration paths.
Definition at line 121 of file loom_cam.c.
◆ loom_mutex
|
static |
Protects admission, phase and mailbox state.
Definition at line 103 of file loom_cam.c.
◆ loom_notification
|
static |
Definition at line 127 of file loom_cam.c.
◆ loom_pending
|
static |
The latest copied path awaits worker consumption; older pending work is replaceable.
Definition at line 110 of file loom_cam.c.
◆ loom_phase
|
static |
Generation that invalidates results crossing a phase change.
Definition at line 114 of file loom_cam.c.
◆ loom_ready
|
static |
One completion mailbox is available for consumption.
Definition at line 110 of file loom_cam.c.
◆ loom_recording
|
static |
Outbound reference collection rather than return matching.
Definition at line 115 of file loom_cam.c.
◆ loom_references
|
static |
Reference-directory configuration, fixed until the worker has been joined.
Definition at line 120 of file loom_cam.c.
◆ loom_result
|
static |
Single correlated matched/no-match completion.
Definition at line 125 of file loom_cam.c.
◆ loom_return_options
|
static |
Definition at line 123 of file loom_cam.c.
◆ loom_return_state
|
static |
Definition at line 124 of file loom_cam.c.
◆ loom_running
|
static |
Lifecycle availability queried without taking the mutex.
Definition at line 107 of file loom_cam.c.
◆ loom_session
|
static |
START token used to admit the corresponding STOP, not a photo number.
Definition at line 114 of file loom_cam.c.
◆ loom_session_references
|
static |
Definition at line 120 of file loom_cam.c.
◆ loom_settings
|
static |
Selected assignment, immutable during worker lifetime.
Definition at line 122 of file loom_cam.c.
◆ loom_stopping
|
static |
Watchdog-visible shutdown flag outside slow I/O.
Definition at line 106 of file loom_cam.c.
◆ loom_thread
|
static |
Joinable saved-photo worker; no sensor ownership.
Definition at line 105 of file loom_cam.c.