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
usher.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file usher.c
20 * @brief Main USHER daemon coordinating flight-controller triggers and camera backends.
21 * @details The event loop receives validated UART frames, queues bounded capture jobs,
22 * dispatches backend work on detached workers, records metadata, and returns status.
23 * It deliberately keeps serial I/O separate from slow camera processes so one capture
24 * cannot block command reception. Backend failure is isolated per camera wherever
25 * possible; systemd owns whole-daemon restart for irrecoverable transport failures.
26 *
27 * @par Ownership at a glance
28 * The event loop owns protocol dispatch and survey admission. Optical tickets
29 * serialize CHDK/AIcam access; live LWIR has a separate worker and recovery lock.
30 * A split-phase image retains its backend completion table after the optical lane
31 * is released. Live SODA uses a separate single worker and owns filenames only.
32 * Keep these boundaries distinct: accepting a trigger, owning pixels and saving a
33 * geotagged original are three different events.
34 * @warning Bounded workers prevent software backlog growth; they do not isolate
35 * shared power, storage, kernel stalls or the whole board's memory consumption.
36 */
37#include <stdio.h>
38#include <stdlib.h>
39#include <pthread.h>
40#include <errno.h>
41#include <fcntl.h>
42#include "version.h"
43#include <math.h>
44#include <poll.h>
45#include <signal.h>
46#include <spawn.h>
47#include <stddef.h>
48#include <stdbool.h>
49#include <string.h>
50#include <sys/resource.h>
51#include <sys/socket.h>
52#include <sys/stat.h>
53#include <sys/types.h>
54#include <sys/un.h>
55#include <sys/wait.h>
56#include <time.h>
57#include <unistd.h>
58
59#include "ai_cam_pipe.h"
60#include "spotter_cam_pipe.h"
61#include "lwir_spotter.h"
62#include "camera_speedtest.h"
63#include "ear_camera_backend.h"
64#include "ear_cam_pipe.h"
65#include "loom_camera_backend.h"
68#include "chdk_camera_backend.h"
70#include "lwir_cam_pipe.h"
71#include "serial.h"
72#include "serial_tx.h"
73#include "image_exif.h"
75#include "image_lens.h"
76#include "local_pipe.h"
77#include "usher_protocol.h"
78#include "camera_control.h"
79#include <sys/random.h>
80#include "pose_log.h"
81#include "capture_arbiter.h"
82#include "camera_profile.h"
83#include "socket.h"
84#include "path_utils.h"
85
86#define MAX_FILENAME 512
87#define MAX_PROCESSING_THREADS 8
88#define USHER_MAX_ARGUMENTS 128
89#define USHER_MAX_PARSED_ARGUMENTS (USHER_MAX_ARGUMENTS * 2 + 1)
90#ifndef USHER_SODA_TIMEOUT_MS
91 #define USHER_SODA_TIMEOUT_MS 120000
92#endif
93#ifndef USHER_SODA_IDLE_MS
94 #define USHER_SODA_IDLE_MS 2000
95#endif
96#ifndef USHER_SODA_RETRY_MS
97 #define USHER_SODA_RETRY_MS 5000
98#endif
99#ifndef SODA_BACKLOG_CAPACITY
100 #define SODA_BACKLOG_CAPACITY 1024
101#endif
102#define MAX_IMAGE_BUFFERS 25
103#define IMAGE_SIZE 70
104// Search&Rescue Onboard Detection Application
105#define SODA "./bin/soda"
106#define ANGLE_BFP_SCALE 4096.0
107#define SPEED_BFP_SCALE 524288.0
108#define POSITION_BFP_SCALE 256.0
109#define RAD_TO_DEG 57.29577951308232
110#define DEBUG_HEARTBEAT_SECONDS 5
111#define SERIAL_READ_BUFFER_SIZE 256
112#define EVENT_LOOP_TIMEOUT_MS 1000
113#define EVENT_LOOP_ACTIVE_TIMEOUT_MS 20
114#define MAX_BACKEND_RESULTS_PER_PASS 16
115#define SODA_SHUTDOWN_GRACE_MS 2000
116#define SODA_WAIT_INTERVAL_US 10000
117#ifndef LWIR_RETRY_COOLDOWN_US
118 #define LWIR_RETRY_COOLDOWN_US 30000000U
119#endif
120#define LWIR_RETRY_POLL_US 100000
121
122#ifndef USHER_SERIAL_DEVICE
123 #define USHER_SERIAL_DEVICE "/dev/ttySAC0"
124#endif
125
126#ifndef USHER_LOCAL_SIM_DEVICE
127 #define USHER_LOCAL_SIM_DEVICE "/tmp/usher-sim"
128#endif
129
130struct option_alias {
131 const char *name;
132 char option[3];
134};
135
136/** @brief Translate supported long options into the short-option parser's input.
137 * @param argc Original argument count.
138 * @param argv Original argument vector.
139 * @param[out] normalized Output vector borrowing strings from @p argv and @p aliases.
140 * @param capacity Number of pointer slots including room for the terminator.
141 * @param aliases Accepted long names, short spellings and operand rules.
142 * @param alias_count Number of entries in @p aliases.
143 * @return Normalized count, or -1 on invalid input or insufficient capacity.
144 * @details Split inline operands without copying their text and preserve
145 * arguments after the option terminator. Keep both input tables alive. */
146static int normalize_long_options(int argc, char *const argv[], char *normalized[],
147 size_t capacity, const struct option_alias aliases[],
148 size_t alias_count)
149{
150 if (argc < 1 || argc > USHER_MAX_ARGUMENTS || capacity == 0) {
151 return -1;
152 }
153 size_t output_count = 0;
154 normalized[output_count++] = argv[0];
155 for (int index = 1; index < argc; ++index) {
156 const char *argument = argv[index];
157 if (strcmp(argument, "--") == 0) {
158 if (output_count >= capacity) {
159 return -1;
160 }
161 normalized[output_count++] = argv[index];
162 for (++index; index < argc; ++index) {
163 if (output_count >= capacity) {
164 return -1;
165 }
166 normalized[output_count++] = argv[index];
167 }
168 break;
169 }
170 if (strncmp(argument, "--", 2) != 0 || argument[2] == '\0') {
171 if (output_count >= capacity) {
172 return -1;
173 }
174 normalized[output_count++] = argv[index];
175 continue;
176 }
177 const char *name = argument + 2;
178 size_t name_length = strcspn(name, "=");
179 const char *inline_value = name[name_length] == '=' ? name + name_length + 1 : NULL;
180 const struct option_alias *alias = NULL;
181 for (size_t alias_index = 0; alias_index < alias_count; ++alias_index) {
182 if (strlen(aliases[alias_index].name) == name_length
183 && strncmp(name, aliases[alias_index].name, name_length) == 0) {
184 alias = &aliases[alias_index];
185 break;
186 }
187 }
188 if (alias == NULL || (!alias->requires_argument && inline_value != NULL)
189 || output_count >= capacity) {
190 return -1;
191 }
192 normalized[output_count++] = (char *)alias->option;
193 if (alias->requires_argument) {
194 if (inline_value == NULL) {
195 if (++index >= argc) {
196 return -1;
197 }
198 inline_value = argv[index];
199 }
200 if (output_count >= capacity) {
201 return -1;
202 }
203 normalized[output_count++] = (char *)inline_value;
204 }
205 }
206 if (output_count >= capacity) {
207 return -1;
208 }
209 normalized[output_count] = NULL;
210 return (int)output_count;
211}
212
213#ifndef USHER_LOCAL_APP_DEVICE
214 #define USHER_LOCAL_APP_DEVICE "/tmp/usher-app"
215#endif
216
217#ifndef USHER_LOCAL_LOCK_FILE
218 #define USHER_LOCAL_LOCK_FILE "/tmp/usher-local.lock"
219#endif
220
221#ifndef USHER_MOCK_IMAGE
222 #define USHER_MOCK_IMAGE "resources/mock_image_01.jpg"
223#endif
224
225#ifndef USHER_CHDK_PHOTO_DIR
226 #define USHER_CHDK_PHOTO_DIR "~/Pictures/sensoraia"
227#endif
228
229#ifndef USHER_AI_CAM_PHOTO_DIR
230 #define USHER_AI_CAM_PHOTO_DIR "~/Pictures/sensoraia"
231#endif
232
233#ifndef USHER_SPOTTERCAM_PHOTO_DIR
234 #define USHER_SPOTTERCAM_PHOTO_DIR USHER_AI_CAM_PHOTO_DIR
235#endif
236
237#ifndef USHER_LWIR_CAM_PHOTO_DIR
238 #define USHER_LWIR_CAM_PHOTO_DIR "~/Pictures/sensoraia"
239#endif
240
241#ifndef USHER_SODA
242 #define USHER_SODA "./bin/soda"
243#endif
244
245#ifndef USHER_LOCAL_PHOTO_DIR
246 #define USHER_LOCAL_PHOTO_DIR "~/Pictures/sensoraia"
247#endif
248
249/** @brief Pool-owned worker request; ownership transfers only after thread creation succeeds. */
252 uint32_t request_id;
253 uint8_t camera_mask;
254 uint64_t ticket; /**< Optical ordering token, not a physical exposure sequence. */
255 uint64_t received_us; /**< Local receipt time for queue age, never an exposure timestamp. */
256 bool arbiter_owned; /**< Protect admitted survey ownership from legacy newest-waiting replacement. */
258};
259
260/** @brief Per-image handoff from acquisition to publication, EXIF and optional analysis.
261 * @details filename may still be empty while pending owns pixels. Keep the original
262 * backend hooks with the image: another camera may have been selected by finish time.
263 */
272 bool exposure_pose_valid; /**< Only validated frame evidence permits replacing request-time geotags. */
274};
275
276/** @brief Saved-file analysis job; retaining pixels here would multiply decoder memory.
277 * @details source binds the queued pose to the original file. The ledger is
278 * session-only, and a retry may repeat partially completed analysis side effects.
279 */
290
291static void *handle_msg_shoot(void *ptr);
292static bool capture_image(const union dc_shot_union *shoot, struct captured_image *image,
293 int camera_id, const struct camera_backend *backend);
294static bool finish_image(const union dc_shot_union *shoot, struct captured_image *image);
295static void handle_received_message(void);
296static void start_shoot_worker(const union dc_shot_union *shoot, uint8_t camera_mask, uint32_t request_id);
297static void start_lwir_worker(const union dc_shot_union *shoot, uint32_t request_id, uint64_t received_us);
298static void service_capture_arbiter(uint64_t now_us);
299static void capture_arbiter_failed(const union dc_shot_union *shoot, uint8_t mask);
300static void handle_targeted_stop(uint32_t camera_id, uint32_t session_id);
301static void handle_targeted_start(uint32_t camera_id, uint32_t session_id);
302static bool prepare_session_backend(unsigned camera_id);
303static bool camera_point_valid(const struct camera_point_result *point);
304static void send_msg_cam_point(uint32_t camera_id, uint32_t session_id, const struct camera_point_result *point);
305static void flush_cam_points(void);
306static void service_camera_backends(void);
307static void drain_camera_backends(void);
308static void send_msg_cam_point_update(uint32_t camera_id, const struct camera_point_result *point);
309static void flush_cam_point_updates(void);
310static bool loomcam_enabled;
316static int run_soda(const char *filename, const union dc_shot_union *shoot, int camera_id);
317static void defer_soda(const char *filename, const union dc_shot_union *shoot, int camera_id);
318static void defer_saved_analysis(const char *filename, const union dc_shot_union *shoot, int camera_id,
319 const struct capture_timing *timing);
320static void stop_soda_backlog(void);
321static void start_pangea(void);
322static void stop_pangea(void);
323static void release_worker_slot(void);
324static struct capture_job *capture_job_acquire_locked(void);
325static void capture_job_release_locked(struct capture_job *job);
326static void capture_job_release(struct capture_job *job);
327static inline void send_msg_image_buffer(void);
328static inline void send_msg_status(void);
329static void print_usage(const char *program);
330static int lock_local_instance(void);
331static pid_t start_local_serial_bridge(void);
332static int wait_for_path(const char *path);
333static void stop_local_serial_bridge(void);
334static void handle_signal(int signal_number);
335static void notify_systemd_ready(void);
336static int camera_backend_select(enum camera_backend_type type, bool test_mode);
339static void camera_close_owner(unsigned camera_id);
340static int camera_register_stream(const struct camera_backend *backend);
342static int camera_prepare(int camera_id);
343static bool lwir_ready_or_start_recovery(void);
344static void lwir_mark_backoff(void);
345static void cameras_deinit(void);
346static int local_backend_shoot(char *filename, size_t filename_size, int image_number);
347
350static pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
351static pthread_mutex_t shot_result_mutex = PTHREAD_MUTEX_INITIALIZER;
352#define SHOT_RESULT_CAPACITY 128
355static uint64_t shot_result_dropped;
356/* mut protects scheduling transitions, not slow camera operations. LWIR's lock
357 * also covers geolocation because its backend exposes one last-capture record. */
358static pthread_mutex_t lwir_camera_mutex = PTHREAD_MUTEX_INITIALIZER;
359static pthread_cond_t camera_available = PTHREAD_COND_INITIALIZER;
360static pthread_cond_t workers_finished = PTHREAD_COND_INITIALIZER;
362#define CAPTURE_JOB_CAPACITY (MAX_PROCESSING_THREADS + 1)
368/* Second CHDK stage: EXIF and publication run here so the next capture can start meanwhile. */
369static struct {
374static bool chdk_async_capture_enabled = true;
376static struct {
378 bool dirty;
382static uint64_t control_negotiated_us;
383static void handle_control_message(void);
384static void flush_control_results(void);
385static uint64_t chdk_retry_after_us;
386#ifndef CHDK_RETRY_COOLDOWN_US
387#define CHDK_RETRY_COOLDOWN_US UINT64_C(5000000)
388#endif
389static pthread_mutex_t live_soda_mutex = PTHREAD_MUTEX_INITIALIZER;
393static uint64_t last_photo_request_us;
395static pthread_t soda_backlog_thread;
396static pthread_cond_t soda_available = PTHREAD_COND_INITIALIZER;
399static int event_wake_reader = -1;
400static volatile sig_atomic_t event_wake_writer = -1;
401
402/** @brief Prompt the event loop to recheck shared state.
403 * @details The nonblocking self-pipe is a hint, not a counted event queue:
404 * if it is full, an unread byte already makes it readable. Preserve errno
405 * because a signal may interrupt code that is about to inspect it. */
406static void wake_event_loop(void)
407{
408 const int error = errno;
409 const uint8_t notification = 1;
410 if (event_wake_writer >= 0) {
411 ssize_t written;
412 do { written = write(event_wake_writer, &notification, sizeof(notification)); } while (written < 0 && errno == EINTR);
413 }
414 errno = error;
415}
416
417/** @brief Set up the self-pipe before installing its producers.
418 * @return Zero on success, or -1 with errno on failure.
419 * @details Set both ends nonblocking and close-on-exec before publishing
420 * either descriptor so workers cannot see a partly configured pipe. */
421static int event_wake_init(void)
422{
423 if (event_wake_reader >= 0 || event_wake_writer >= 0) { errno = EBUSY; return -1; }
424 int descriptors[2];
425 if (pipe(descriptors) != 0) return -1;
426 for (size_t index = 0; index < 2; ++index) {
427 const int flags = fcntl(descriptors[index], F_GETFL);
428 if (flags < 0 || fcntl(descriptors[index], F_SETFL, flags | O_NONBLOCK) < 0
429 || fcntl(descriptors[index], F_SETFD, FD_CLOEXEC) < 0) {
430 const int error = errno;
431 close(descriptors[0]);
432 close(descriptors[1]);
433 errno = error;
434 return -1;
435 }
436 }
437 event_wake_reader = descriptors[0];
438 event_wake_writer = descriptors[1];
439 return 0;
440}
441
442/** @brief Consume pending wake hints without monopolizing the event loop.
443 * @details Cap the drain work; if writers refill the pipe, the remaining
444 * bytes will make the next poll readable. */
445static void drain_event_wake(void)
446{
447 uint8_t notifications[64];
448 for (unsigned attempt = 0; attempt < 4; ++attempt)
449 if (read(event_wake_reader, notifications, sizeof(notifications)) <= 0) break;
450}
451
452/** @brief Withdraw the wake descriptors and close the self-pipe.
453 * @details Invalidate the published writer first so later notifications
454 * can skip the write. Call after ordinary worker producers are quiescent. */
455static void event_wake_close(void)
456{
457 const int writer = event_wake_writer;
459 if (writer >= 0) close(writer);
462}
463
464/** @brief Hand one camera's terminal shot result to the serial owner.
465 * @param request_id Correlation ID; zero denotes a legacy request without an acknowledgement.
466 * @param number Flight-controller photo number.
467 * @param camera_id Camera that owns the outcome.
468 * @param status Wire result code.
469 * @details Do not block a capture worker on UART backpressure. Count drops
470 * if the bounded queue fills, and wake the loop even for legacy work. */
471static void queue_shot_result(uint32_t request_id, int32_t number, unsigned camera_id, uint32_t status)
472{
473 if (!request_id) { wake_event_loop(); return; }
474 pthread_mutex_lock(&shot_result_mutex);
476 else {
479 }
480 pthread_mutex_unlock(&shot_result_mutex);
482}
483
484/** @brief Report a shared outcome separately for each addressed image camera.
485 * @param request_id Correlation ID, or zero for a legacy request.
486 * @param number Flight-controller photo number.
487 * @param camera_mask Bitmask indexed by camera ID minus one.
488 * @param status Outcome to report for each selected camera.
489 * @details Expand only image-camera bits so a shared admission failure
490 * retains per-camera correlation without generating terminal results for
491 * non-image backends. */
492static void queue_image_results(uint32_t request_id, int32_t number, uint8_t camera_mask, uint32_t status)
493{
494 for (unsigned camera_id = USHER_CAMERA_CHDK; camera_id <= USHER_CAMERA_LWIRCAM; ++camera_id)
495 if (camera_mask & (1U << (camera_id - 1))) queue_shot_result(request_id, number, camera_id, status);
496}
497
498/** @brief Transfer a bounded batch of shot results to the UART transmit queue.
499 * @details The event loop is the only consumer. Leave the head queued until
500 * transmit admission succeeds, and release the result lock around that call
501 * so a worker can append without waiting on the UART path. */
502static void flush_shot_results(void)
503{
504 for (unsigned sent = 0; sent < 16; ++sent) {
505 pthread_mutex_lock(&shot_result_mutex);
506 if (!shot_result_count) {
507 pthread_mutex_unlock(&shot_result_mutex);
508 return;
509 }
511 pthread_mutex_unlock(&shot_result_mutex);
512 if (serial_tx_send(USHER_SHOT_RESULT, result.bin, sizeof(result.bin)) != 0) return;
513 pthread_mutex_lock(&shot_result_mutex);
516 pthread_mutex_unlock(&shot_result_mutex);
517 }
518}
519static bool local_mode;
521static struct camera_backend camera;
524static bool camera_unavailable[4];
525static bool camera_warned[4];
526/** Tiny1-C server startup can take tens of seconds. Recovery runs outside the ordered
527 * optical capture lane and is rate-limited so a broken USB link cannot stall AIcam. */
528static uint64_t lwir_retry_after_us;
533static struct {
535 uint32_t request_id;
536 uint64_t received_us;
537 bool valid;
539#define LWIR_WAIT_MAX_US UINT64_C(2000000)
543/** True when --spottercam was selected: camera id USHER_CAMERA_AICAM still means "the
544 * AI camera" on the wire (unchanged for the flight controller/NPS), but camera_prepare()
545 * and cameras_deinit() route it to the object-detection backend instead of plain
546 * ai_cam_pipe capture. Plain --aicam behavior is completely unaffected. */
547static const char *camera_source_image;
550static volatile sig_atomic_t keep_running = 1;
551
552/** @brief Read service cancellation state through the capture flag accessor.
553 * @return True while the service is running.
554 * @details Use the same accessor as the workers so the main loop and
555 * subprocess supervisors observe the same shutdown flag. */
556static bool usher_running(void)
557{
559}
560static pid_t socat_pid = -1;
561static int local_lock_fd = -1;
562static const char *mock_image = USHER_MOCK_IMAGE;
565static const char *mock_map_cache = "~/.local/share/paparazzi/pprzgcs/map";
566static double mock_map_horizontal_fov = 60.0;
567static double mock_map_vertical_fov = 45.0;
568static const char *mock_lens_profile;
569static const char *pangea_directory;
570static const char *pangea_camera_profile;
571static const char *pangea_pause_file;
572static pid_t pangea_pid = -1;
573static bool debug_enabled;
576static struct {
577 uint32_t id;
586#ifndef USHER_POSE_LOG_DIR
587 #define USHER_POSE_LOG_DIR NULL
588#endif
589static const char *pose_log_dir = USHER_POSE_LOG_DIR;
591static struct {
593 bool valid;
596/** Optional analysis ownership is separate from lazy sensor acquisition. */
600
601/** @brief Read USHER's monotonic clock for local latency and event ordering.
602 * @return Microseconds since an arbitrary monotonic origin, or zero on clock failure. */
603static uint64_t monotonic_time_us(void)
604{
605 struct timespec now;
606 return clock_gettime(CLOCK_MONOTONIC, &now) == 0
607 ? (uint64_t)now.tv_sec * 1000000U + (uint64_t)now.tv_nsec / 1000U : 0;
608}
609
610/** @brief Select the next event-loop polling budget.
611 * @return Active or idle timeout, in milliseconds.
612 * @details Keep the shorter timeout while work may need servicing even
613 * without another UART input. Read capture/control state and shot results
614 * under their respective locks instead of nesting them. */
615static int event_loop_timeout_ms(void)
616{
618 pthread_mutex_lock(&mut);
621 for (size_t index = 0; index < CAMERA_BACKEND_MAX_ID; ++index)
622 if (point_sessions[index].id || point_sessions[index].pending || point_update_pending[index]) pending = true;
623 for (size_t index = 0; index < 8; ++index)
624 if (control_results[index].dirty) pending = true;
625 pthread_mutex_unlock(&mut);
626 pthread_mutex_lock(&shot_result_mutex);
628 pthread_mutex_unlock(&shot_result_mutex);
630}
631
632/** @brief Pause for an interval using nanosleep's remaining-time result.
633 * @param microseconds Requested interval in microseconds.
634 * @details On signal interruption, resume only the unfinished portion. */
635static void sleep_microseconds(uint64_t microseconds)
636{
637 struct timespec delay = {
638 .tv_sec = (time_t)(microseconds / 1000000U),
639 .tv_nsec = (long)(microseconds % 1000000U) * 1000L
640 };
641 while (nanosleep(&delay, &delay) != 0 && errno == EINTR) continue;
642}
643
644/** @brief Install a camera's calibrated exposure-to-delivery delay bounds.
645 * @param camera_id Supported image camera identifier.
646 * @param value Comma-separated minimum and maximum delays in milliseconds.
647 * @return True if both bounds were accepted; false leaves the setting unchanged.
648 * @details Round outward when converting to integer microseconds so unit
649 * conversion never narrows the supplied uncertainty interval. */
650static bool set_exposure_latency(unsigned camera_id, const char *value)
651{
652 double minimum_ms, maximum_ms;
653 char extra;
654 if (camera_id < USHER_CAMERA_CHDK || camera_id > USHER_CAMERA_LWIRCAM || !value
655 || sscanf(value, "%lf,%lf%c", &minimum_ms, &maximum_ms, &extra) != 2
656 || !isfinite(minimum_ms) || !isfinite(maximum_ms)
657 || minimum_ms < 0 || maximum_ms < minimum_ms || maximum_ms > 2000) return false;
658 exposure_latency[camera_id].minimum_us = (uint64_t)floor(minimum_ms * 1000);
659 exposure_latency[camera_id].maximum_us = (uint64_t)ceil(maximum_ms * 1000);
660 exposure_latency[camera_id].valid = true;
661 return true;
662}
663
664/** @brief Opportunistically send a low-priority flight-controller clock probe.
665 * @details Probes are rate-limited to one per second and sent only on an idle UART so
666 * alignment evidence cannot delay capture/status traffic. */
667static void send_clock_probe(uint64_t now_us)
668{
669 if (!clock_probes_enabled || now_us == 0 || now_us < next_clock_probe_us
670 || now_us > UINT64_MAX - 1000000) return;
671 next_clock_probe_us = now_us + 1000000;
672 union usher_clock_request_union token = {.data = {
673 .token_low = (uint32_t)now_us,
674 .token_high = (uint32_t)(now_us >> 32) ^ (uint32_t)getpid() ^ (uint32_t)(clock_probe_count + 1)
675 }
676 };
677 const uint64_t sent_us = monotonic_time_us();
678 if (!clock_alignment_request(&fc_clock, token, sent_us)) return;
679 if (serial_tx_send_if_idle(USHER_CLOCK_REQUEST, token.bin, sizeof(token.bin)) != 0) {
680 fc_clock.pending = false;
681 return;
682 }
684}
685
686/** @brief Feed one acoustic sample from the pose stream while a listening session is open.
687 * @details Sampling follows the ordinary pose stream, so a specialized camera needs no
688 * capture commands of its own. Without that stream the session collects nothing. */
689static void camera_record_pose(const uint8_t *payload, uint16_t length)
690{
691 if (length != USHER_POSE_SAMPLE_MSG_SIZE) return;
692 union usher_pose_sample_union sample;
693 for (size_t index = 0; index < sizeof(sample.bin); ++index) sample.bin[index] = payload[index];
694 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
695 const struct camera_backend *owner = &camera_owners[camera_id];
696 if (owner->session && owner->session->listening && owner->session->listening() && owner->record)
697 owner->record(&sample.data.shot);
698 }
699}
700
701/** @brief Validate and enqueue a token-bound pose sample with clock evidence.
702 * @details Mapping failure does not discard the pose: the log records it as unmapped,
703 * preserving raw diagnostic evidence without claiming false time precision. */
704static void record_clocked_pose(void)
705{
706 if (usher_protocol.payload_len != USHER_POSE_CLOCKED_MSG_SIZE) {
708 return;
709 }
710 union usher_pose_clocked_union message;
711 for (size_t index = 0; index < sizeof(message.bin); ++index) message.bin[index] = usher_protocol.payload[index];
712 struct pose_clock_evidence evidence = {.token = message.data.request};
713 struct clock_interval begin, end;
718 evidence.sample_time = (struct clock_interval) {begin.earliest_us, end.latest_us};
719 evidence.probe_sent_us = fc_clock.mapped_sent_us;
720 evidence.probe_received_us = fc_clock.received_us;
721 evidence.probe_receive_fc_us = fc_clock.receive_fc_us;
722 evidence.probe_transmit_fc_us = fc_clock.anchor_fc_us;
723 evidence.mapped = true;
725 } else {
727 }
728 pose_log_record_clocked(message.data.sample.bin, sizeof(message.data.sample.bin),
730 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id)
731 if (camera_owners[camera_id].pose_updated) camera_owners[camera_id].pose_updated();
732 camera_record_pose(message.data.sample.bin, sizeof(message.data.sample.bin));
733}
734
735extern char **environ;
736
737/** @brief Configure USHER and run its multiplexed UART/local-UDP event loop.
738 * @return Process status suitable for systemd restart policy.
739 * @details After argument validation, startup claims the fixed local payload endpoint
740 * before touching shared UART or camera resources. This rejects a second process early
741 * when the systemd service is already active. USHER then validates selected backends,
742 * starts optional persistent services, initializes non-blocking transport, and drains
743 * serial bytes into the protocol parser. Shutdown wakes and drains detached workers
744 * before releasing backend resources. */
745int main(int argc, char *argv[])
746{
748 perror("USHER: cannot enter executable directory");
749 return 1;
750 }
751 const char *serial_device = USHER_SERIAL_DEVICE;
752 bool serial_was_selected = false;
753 bool mock_image_was_selected = false;
754 bool mock_map_option_selected = false;
755 static char resolved_mock_map_cache[PATH_MAX];
756 static char resolved_mock_lens_profile[PATH_MAX];
757 static char resolved_pangea_profile[PATH_MAX];
758 bool test_mode = false;
759 bool speedtest_enabled = false;
760 bool native_photo_selected = false;
761 bool earcam_option_selected = false;
762 bool earcam_device_selected = false;
763 bool earcam_sim_selected = false;
764 bool pose_log_selected = false;
765 bool clock_align_selected = false;
766 bool clock_align_disabled = false;
767 bool lwir_raw_selected = false;
768 bool lwir_calibration_selected = false;
769 bool lwir_config_selected = false;
770 bool spotter_settings_selected = false;
771 bool lwir_spotter_geometry_selected = false;
772 bool motion_compensation_selected = false;
773 bool capture_arbiter_enforce_selected = false;
774 uint64_t serial_byte_count = 0;
775 uint64_t valid_frame_count = 0;
776 uint64_t rejected_frame_count = 0;
777 time_t next_debug_heartbeat = 0;
778 unsigned char serial_buffer[SERIAL_READ_BUFFER_SIZE];
779 int option;
780
781 static const struct option_alias long_options[] = {
782 {"serial", "-s", true},
783 {"local", "-l", false},
784 {"chdk", "-c", false},
785 {"aicam", "-a", false},
786 {"spottercam", "-b", false},
787 {"native-photo", "-n", false},
788 {"spottercam-settings", "-I", true},
789 {"spottercam-targets", "-4", true},
790 {"lwir-spotter-settings", "-1", true},
791 {"lwir-spotter-profile", "-2", true},
792 {"lwir-spotter-limits", "-3", true},
793 {"loomcam", "-H", false},
794 {"loomcam-reference-dir", "-R", true},
795 {"loomcam-model", "-T", true},
796 {"loomcam-settings", "-Y", true},
797 {"lwircam", "-w", false},
798 {"lwir-config", "-Z", true},
799 {"earcam", "-e", false},
800 {"diplacam-config", "-J", true},
801 {"earcam-device", "-A", true},
802 {"earcam-settings", "-W", true},
803 {"earcam-sim", "-E", true},
804 {"earcam-band", "-B", true},
805 {"test", "-t", false},
806 {"mocktransform", "-f", false},
807 {"debug", "-d", false},
808 {"mock-image", "-i", true},
809 {"mock-map", "-M", false},
810 {"mock-map-cache", "-C", true},
811 {"mock-map-fov", "-F", true},
812 {"mock-lens", "-L", true},
813 {"pangea", "-P", true},
814 {"pangea-camera", "-G", true},
815 {"pangea-pause-file", "-U", true},
816 {"survey-camera", "-Q", true},
817 {"survey-enforce", "-N", false},
818 {"survey-overlap", "-O", true},
819 {"pose-log", "-p", true},
820 {"clock-align", "-k", false},
821 {"no-clock-align", "-K", false},
822 {"lwir-latency-ms", "-j", true},
823 {"chdk-latency-ms", "-q", true},
824 {"lwir-raw", "-r", false},
825 {"lwir-calibration", "-y", true},
826 {"lwir-motion-compensation", "-m", false},
827 {"help", "-h", false},
828 {"version", "-V", false},
829 {"speedtest", "-S", false}
830 };
831 char *normalized_argv[USHER_MAX_PARSED_ARGUMENTS];
832 int normalized_argc = normalize_long_options(argc, argv, normalized_argv,
833 USHER_MAX_PARSED_ARGUMENTS, long_options,
834 sizeof(long_options) / sizeof(long_options[0]));
835 if (normalized_argc < 0) {
836 fprintf(stderr, "USHER:\tinvalid or excessive command-line arguments\n");
837 return 2;
838 }
839 optind = 1;
840 while ((option = getopt(normalized_argc, normalized_argv,
841 "s:lcabnweA:E:B:tfdi:p:kKj:q:ry:mhMC:F:L:P:G:U:g:u:Q:NO:VSHR:T:Z:J:I:Y:W:1:2:3:4:")) != -1) {
842 switch (option) {
843 case '4':
845 fprintf(stderr, "USHER:\t--spottercam-targets requires a valid AIcam PANGEA_CAMERA_V1 profile\n");
846 return 2;
847 }
848 break;
849 case '1':
850 if (!lwir_spotter_settings(optarg)) return 2;
851 break;
852 case '2':
853 if (!lwir_spotter_profile(optarg)) return 2;
854 lwir_spotter_geometry_selected = true;
855 break;
856 case '3':
857 if (!lwir_spotter_limits(optarg)) return 2;
858 lwir_spotter_geometry_selected = true;
859 break;
860 case 'I':
861 if (spotter_cam_pipe_set_settings(optarg)) return 2;
862 spotter_settings_selected = true;
863 break;
864 case 'W':
865 if (!ear_cam_pipe_set_settings(optarg)) return 2;
866 break;
867 case 'Y':
868 if (loom_camera_backend_set_settings(optarg)) return 2;
869 loomcam_enabled = true;
870 break;
871 case 'J':
872 if (!dipla_camera_backend_setup(optarg)) return 2;
873 break;
874 case 'H':
875 loomcam_enabled = true;
876 break;
877 case 'R':
878 if (!*optarg) return 2;
879 loomcam_references = optarg;
880 loomcam_enabled = true;
881 break;
882 case 'T':
883 if (!*optarg) return 2;
884 loomcam_model = optarg;
885 loomcam_enabled = true;
886 break;
887 case 'Q':
888 if (!capture_arbiter_load_camera(optarg)) return 2;
890 break;
891 case 'N':
893 capture_arbiter_enforce_selected = true;
894 break;
895 case 'O': {
896 char *end = NULL;
897 const double overlap = strtod(optarg, &end);
898 if (!end || end == optarg || *end || !capture_arbiter_set_overlap(overlap)) {
899 fprintf(stderr, "USHER:\t--survey-overlap expects a fraction from 0 to 0.9\n");
900 return 2;
901 }
902 break;
903 }
904 case 's':
905 serial_device = optarg;
906 serial_was_selected = true;
907 break;
908 case 'l':
909 local_mode = true;
911 break;
912 case 'c':
914 fprintf(stderr, "USHER:\tonly one camera backend may be selected\n");
915 return 2;
916 }
918 break;
919 case 'a':
921 fprintf(stderr, "USHER:\tonly one camera backend may be selected\n");
922 return 2;
923 }
925 break;
926 case 'b':
928 fprintf(stderr, "USHER:\tonly one camera backend may be selected\n");
929 return 2;
930 }
932 break;
933 case 'n':
934 native_photo_selected = true;
935 break;
936 case 'w':
938 fprintf(stderr, "USHER:\tonly one camera backend may be selected\n");
939 return 2;
940 }
942 break;
943 case 'e':
944 earcam_requested = true;
945 earcam_option_selected = true;
946 break;
947 case 'A':
948 if (!ear_camera_backend_set_device(optarg)) {
949 fprintf(stderr, "USHER:\t--earcam-device expects a nonempty ALSA PCM name of at most 255 bytes\n");
950 return 2;
951 }
952 earcam_requested = true;
953 earcam_option_selected = true;
954 earcam_device_selected = true;
955 break;
956 case 'E': {
957 double sim_lat = 0.0;
958 double sim_lon = 0.0;
959 double sim_level = 95.0;
960 int fields = sscanf(optarg, "%lf,%lf,%lf", &sim_lat, &sim_lon, &sim_level);
961 if (fields < 2 || sim_lat < -90.0 || sim_lat > 90.0 || sim_lon < -180.0 || sim_lon > 180.0) {
962 fprintf(stderr, "USHER:\t--earcam-sim expects LAT,LON[,LEVEL_DB_AT_1M]\n");
963 return 2;
964 }
965 ear_camera_backend_set_simulated_source(sim_lat, sim_lon, sim_level);
966 earcam_sim_selected = true;
967 earcam_requested = true;
968 earcam_option_selected = true;
969 break;
970 }
971 case 'B': {
972 double low_hz = 0.0;
973 double high_hz = 0.0;
974 if (sscanf(optarg, "%lf,%lf", &low_hz, &high_hz) != 2 || low_hz < 100.0 || high_hz <= low_hz
975 || high_hz > 20000.0) {
976 fprintf(stderr, "USHER:\t--earcam-band expects LOW_HZ,HIGH_HZ\n");
977 return 2;
978 }
979 ear_camera_backend_set_band(low_hz, high_hz);
980 earcam_option_selected = true;
981 break;
982 }
983 case 't':
984 test_mode = true;
985 break;
986 case 'f':
988 break;
989 case 'd':
990 debug_enabled = true;
991 break;
992 case 'i':
993 mock_image = optarg;
994 mock_image_was_selected = true;
995 break;
996 case 'p':
997 if (optarg[0] == '\0') {
998 fprintf(stderr, "USHER:\t--pose-log expects a directory\n");
999 return 2;
1000 }
1001 pose_log_dir = optarg;
1002 pose_log_selected = true;
1003 break;
1004 case 'M':
1005 mock_map_enabled = true;
1006 break;
1007 case 'C':
1008 mock_map_cache = optarg;
1009 mock_map_option_selected = true;
1010 break;
1011 case 'L':
1012 mock_lens_profile = optarg;
1013 break;
1014 case 'P':
1015 pangea_directory = optarg;
1016 break;
1017 case 'G':
1018 pangea_camera_profile = optarg;
1019 break;
1020 case 'U':
1021 pangea_pause_file = optarg;
1022 break;
1023 case 'F': {
1024 char extra;
1025 if (sscanf(optarg, "%lf,%lf%c", &mock_map_horizontal_fov, &mock_map_vertical_fov, &extra) != 2
1026 || !isfinite(mock_map_horizontal_fov) || !isfinite(mock_map_vertical_fov)
1029 fprintf(stderr, "USHER:\t--mock-map-fov expects HORIZONTAL,VERTICAL degrees between 0 and 179\n");
1030 return 2;
1031 }
1032 mock_map_option_selected = true;
1033 break;
1034 }
1035 case 'k':
1036 clock_probes_enabled = true;
1037 clock_align_selected = true;
1038 clock_align_disabled = false;
1039 break;
1040 case 'K':
1041 clock_probes_enabled = false;
1042 clock_align_disabled = true;
1043 break;
1044 case 'j':
1045 case 'q':
1047 fprintf(stderr, "USHER:\tlatency expects measured MIN,MAX milliseconds within 0..2000\n");
1048 return 2;
1049 }
1050 break;
1051 case 'r':
1053 lwir_raw_selected = true;
1054 break;
1055 case 'y':
1056 if (lwir_cam_pipe_set_calibration(optarg) != 0) {
1057 fprintf(stderr, "USHER:\t--lwir-calibration expects a camera YAML file\n");
1058 return 2;
1059 }
1060 lwir_calibration_selected = true;
1061 break;
1062 case 'Z':
1063 if (lwir_cam_pipe_set_config(optarg) != 0) return 2;
1064 lwir_config_selected = true;
1065 break;
1066 case 'm':
1068 motion_compensation_selected = true;
1069 break;
1070 case 'V':
1071 puts(USHER_BUILD_VERSION);
1072 return 0;
1073 case 'S':
1074 speedtest_enabled = true;
1075 break;
1076 case 'h':
1077 print_usage(argv[0]);
1078 return 0;
1079 default:
1080 print_usage(argv[0]);
1081 return 2;
1082 }
1083 }
1084
1085 if (optind != normalized_argc) {
1086 print_usage(argv[0]);
1087 return 2;
1088 }
1089 if (lwir_config_selected && requested_camera_backend != CAMERA_BACKEND_LWIR_CAM) {
1090 fprintf(stderr, "USHER:\t--lwir-config requires --lwircam\n"); return 2;
1091 }
1093 || test_mode || local_mode || mock_map_enabled || mock_transform_enabled || speedtest_enabled)) {
1094 fprintf(stderr, "USHER:\tLWIR spotting requires real --lwircam capture without test/effects/speedtest\n");
1095 return 2;
1096 }
1097 if (lwir_spotter_geometry_selected && !lwir_spotter_enabled()) {
1098 fprintf(stderr, "USHER:\tLWIR spotting geometry requires --lwir-spotter-settings\n");
1099 return 2;
1100 }
1101
1102 if (earcam_device_selected && earcam_sim_selected) {
1103 fprintf(stderr, "USHER:\t--earcam-device cannot be combined with --earcam-sim\n");
1104 return 2;
1105 }
1106
1107 if (loomcam_enabled) {
1110 fprintf(stderr, "USHER:\t--loomcam owns the AI camera and cannot be combined with another camera backend\n");
1111 return 2;
1112 }
1114 }
1115 if (native_photo_selected) {
1117 || test_mode || mock_map_enabled || mock_image_was_selected || mock_transform_enabled
1118 || spotter_settings_selected) {
1119 fprintf(stderr, "USHER:\t--native-photo requires real --aicam or --spottercam without model settings\n");
1120 return 2;
1121 }
1123 if (ai_cam_pipe_set_native(true)) return 2;
1124 } else if (spotter_cam_pipe_set_photo_only(true)) return 2;
1125 }
1126
1130 || native_photo_selected || speedtest_enabled)) {
1131 fprintf(stderr, "USHER:\t--spottercam-targets requires --spottercam detection mode\n");
1132 return 2;
1133 }
1134 if (mock_map_option_selected && !mock_map_enabled) {
1135 fprintf(stderr, "USHER:\t--mock-map-cache and --mock-map-fov require --mock-map\n");
1136 return 2;
1137 }
1138 if ((pangea_camera_profile != NULL || pangea_pause_file != NULL) && pangea_directory == NULL) {
1139 fprintf(stderr, "USHER:\tPANGEA options require --pangea DIR\n");
1140 return 2;
1141 }
1142 if (pangea_directory != NULL) {
1143 const bool real_camera = pangea_camera_profile != NULL;
1144 if (pangea_directory[0] == '\0' || speedtest_enabled
1145 || (pangea_pause_file != NULL && pangea_pause_file[0] == '\0')
1146 || (!real_camera && (!local_mode || !mock_map_enabled))
1147 || (real_camera && (local_mode || mock_map_enabled || mock_transform_enabled || test_mode
1148 || mock_image_was_selected || mock_lens_profile != NULL
1151 fprintf(stderr,
1152 "USHER:\t--pangea needs local MIMIC or --pangea-camera with an explicit real --aicam, --spottercam, --chdk or --lwircam backend; no test/effects/speedtest in real mode\n");
1153 return 2;
1154 }
1155 if (real_camera) {
1156 struct stat profile_status;
1157 if (realpath(pangea_camera_profile, resolved_pangea_profile) == NULL
1158 || stat(resolved_pangea_profile, &profile_status) != 0 || !S_ISREG(profile_status.st_mode)
1159 || profile_status.st_size <= 0 || profile_status.st_size > CAMERA_PROFILE_MAX_BYTES || access(resolved_pangea_profile, R_OK) != 0) {
1160 fprintf(stderr, "USHER:\t--pangea-camera requires a readable PANGEA camera profile\n");
1161 return 2;
1162 }
1163 pangea_camera_profile = resolved_pangea_profile;
1164 }
1165 }
1166 if (mock_lens_profile != NULL) {
1167 struct stat profile_status;
1168 if (!mock_map_enabled || !local_mode || realpath(mock_lens_profile, resolved_mock_lens_profile) == NULL
1169 || stat(resolved_mock_lens_profile, &profile_status) != 0 || !S_ISREG(profile_status.st_mode)
1170 || profile_status.st_size <= 0 || profile_status.st_size > 16384
1171 || access(resolved_mock_lens_profile, R_OK) != 0) {
1172 fprintf(stderr, "USHER:\t--mock-lens needs --local --mock-map and a readable profile file\n");
1173 return 2;
1174 }
1175 if (access("./bin/camera_lens", X_OK) != 0) {
1176 fprintf(stderr, "USHER:\t--mock-lens needs the native renderer; run make camera-lens\n");
1177 return 2;
1178 }
1179 mock_lens_profile = resolved_mock_lens_profile;
1180 }
1181 if (mock_map_enabled) {
1182 if (!local_mode || mock_image_was_selected || mock_transform_enabled
1183 || (requested_camera_backend == CAMERA_BACKEND_SPOTTER_CAM && !spotter_settings_selected)) {
1184 fprintf(stderr, "USHER:\t--mock-map requires --local; incompatible with --mock-image, "
1185 "--mocktransform and --spottercam\n");
1186 return 2;
1187 }
1188 mock_map_cache = usher_resolve_path(mock_map_cache, resolved_mock_map_cache,
1189 sizeof(resolved_mock_map_cache));
1190 char tile_cache[PATH_MAX];
1191 int length = snprintf(tile_cache, sizeof(tile_cache), "%s/GOOGLE/18", mock_map_cache);
1192 struct stat status;
1193 if (mock_map_cache[0] == '\0' || length < 0 || (size_t)length >= sizeof(tile_cache)
1194 || stat(tile_cache, &status) != 0 || !S_ISDIR(status.st_mode) || access(tile_cache, R_OK | X_OK) != 0) {
1195 fprintf(stderr, "USHER:\t--mock-map needs zoom-18 XYZ JPEGs in the pprzgcs GOOGLE/18 cache layout\n");
1196 return 2;
1197 }
1198 test_mode = true;
1199 }
1200 if (mock_image_was_selected && !test_mode
1202 fprintf(stderr, "USHER:\t--mock-image requires --test or --local without a camera backend\n");
1203 return 2;
1204 }
1205 if (mock_transform_enabled && !test_mode) {
1206 fprintf(stderr, "USHER:\t--mocktransform requires --test\n");
1207 return 2;
1208 }
1209 if (capture_arbiter_enforce_selected && !capture_arbiter_session_id()) {
1210 fprintf(stderr, "USHER:\tsurvey controls require at least one --survey-camera profile\n");
1211 return 2;
1212 }
1213 if (capture_arbiter_session_id() && (speedtest_enabled || test_mode || mock_map_enabled || mock_transform_enabled)) {
1214 fprintf(stderr, "USHER:\tsurvey mode is for real survey captures, not speedtest or mock operation\n");
1215 return 2;
1216 }
1217 if (setenv("USHER_FRAME_TIMING", "1", 1) != 0) return 1;
1218 if (speedtest_enabled) {
1220 fprintf(stderr, "USHER:\t--speedtest requires --chdk, --aicam, --spottercam, or --lwircam\n");
1221 return 2;
1222 }
1223 if (serial_was_selected || local_mode || test_mode || mock_image_was_selected
1224 || mock_transform_enabled || debug_enabled || earcam_option_selected || pose_log_selected
1225 || clock_align_selected || lwir_raw_selected || lwir_calibration_selected
1226 || motion_compensation_selected || clock_align_disabled || loomcam_enabled
1228 fprintf(stderr, "USHER:\t--speedtest cannot be combined with daemon, mock, EARcam, pose, or LWIR processing options\n");
1229 return 2;
1230 }
1231 }
1232
1233 if (debug_enabled) {
1234 setvbuf(stdout, NULL, _IOLBF, 0);
1235 setvbuf(stderr, NULL, _IOLBF, 0);
1236 }
1237
1238 /* The fixed loopback payload endpoint is also the physical-mode instance
1239 * claim. Acquire it before opening UART or camera resources so a foreground
1240 * invocation cannot compete with the systemd-managed USHER service. */
1241 if (socket_init(1) != 0) {
1242 return 1;
1243 }
1244
1245 if (!local_mode && !serial_was_selected && access(USHER_SERIAL_DEVICE, R_OK | W_OK) != 0
1246 && access(USHER_LOCAL_SIM_DEVICE, F_OK) == 0 && access(USHER_LOCAL_APP_DEVICE, F_OK) == 0) {
1247 local_mode = true;
1248 serial_device = USHER_LOCAL_APP_DEVICE;
1249 printf("USHER:\tauto-detected existing local serial bridge\n");
1250 }
1251
1252 if (local_mode) {
1253 if (serial_was_selected) {
1254 fprintf(stderr, "USHER:\t--serial cannot be combined with --local\n");
1255 return 2;
1256 }
1258 if (lock_local_instance() != 0) {
1259 return 1;
1260 }
1262 if (socat_pid < 0) {
1263 return 1;
1264 }
1265 local_bridge_owned = true;
1266 }
1267 serial_device = USHER_LOCAL_APP_DEVICE;
1268 }
1269
1270 enum camera_backend_type selected_camera_backend = requested_camera_backend;
1271 if (selected_camera_backend == CAMERA_BACKEND_UNSELECTED) {
1272 selected_camera_backend = local_mode ? CAMERA_BACKEND_LOCAL : CAMERA_BACKEND_SPOTTER_CAM;
1273 }
1275 configured_camera_backend = selected_camera_backend;
1276 if (camera_backend_select(selected_camera_backend, test_mode) != 0) {
1278 return 2;
1279 }
1280 test_capture_enabled = test_mode;
1281
1282 optical_camera_id = camera.camera_id;
1283
1284 if (speedtest_enabled) {
1285 if (!(camera.capabilities & CAMERA_CAP_IMAGE) || !camera.prefix || !camera.photo_directory) return 2;
1286 const char *photo_root = camera.photo_directory;
1287 const char filename_prefix = camera.prefix;
1288 char speedtest_directory[PATH_MAX];
1289 if (camera_speedtest_create_output_directory(photo_root, speedtest_directory,
1290 sizeof(speedtest_directory)) != 0) {
1291 fprintf(stderr, "USHER SPEEDTEST:\tunable to create isolated output directory: %s\n",
1292 strerror(errno));
1293 return 1;
1294 }
1295 chdk_camera_backend_set_photo_directory(speedtest_directory);
1296 ai_cam_pipe_set_photo_directory(speedtest_directory);
1297 spotter_cam_pipe_set_photo_directory(speedtest_directory);
1298 lwir_cam_pipe_set_photo_directory(speedtest_directory);
1299 struct camera_speedtest_config speedtest = {
1300 .backend_name = camera.name,
1301 .photo_directory = speedtest_directory,
1302 .filename_prefix = filename_prefix,
1303 .private_output = (camera.capabilities & CAMERA_CAP_PRIVATE_IMAGE) != 0,
1304 .shoot = camera.shoot,
1305 .keep_running = &keep_running
1306 };
1307 int first_image;
1308 if (camera_speedtest_find_image_block(&speedtest, &first_image) != 0) {
1309 fprintf(stderr, "USHER SPEEDTEST:\tunable to reserve an unused image-number block: %s\n",
1310 strerror(errno));
1311 return 1;
1312 }
1313 signal(SIGPIPE, SIG_IGN);
1314 signal(SIGINT, handle_signal);
1315 signal(SIGTERM, handle_signal);
1316 printf("USHER:\tStarting Camera Speed Test\n");
1317 printf("USHER:\tcamera backend: %s\n", camera.name);
1318 uint64_t initialization_started_us = monotonic_time_us();
1319 int prepare_result = camera_prepare(optical_camera_id);
1320 uint64_t initialization_completed_us = monotonic_time_us();
1321 if (prepare_result != 0 || initialization_started_us == 0
1322 || initialization_completed_us < initialization_started_us) {
1323 fprintf(stderr, "USHER SPEEDTEST:\tcamera initialization failed\n");
1325 return 1;
1326 }
1327 printf("USHER SPEEDTEST:\tinitialization: %.3f ms (excluded from capture rate)\n",
1328 (initialization_completed_us - initialization_started_us) / 1000.0);
1329 int speedtest_result = camera_speedtest_run(&speedtest, first_image);
1331 printf("USHER:\tSpeed test shutdown\n");
1332 return speedtest_result == 0 ? 0 : 1;
1333 }
1334
1335 // Initialization
1336 printf("USHER:\tStarting camera service\n");
1337 printf("USHER:\tserial device: %s\n", serial_device);
1338 printf("USHER:\tcamera backend: %s\n", camera.name);
1339 if (debug_enabled) {
1340 printf("USHER DEBUG:\tenabled\n");
1341 }
1342 if (test_mode) {
1343 if (mock_map_enabled) {
1344 printf("USHER:\tMIMIC: XYZ zoom 18 from %s; FOV %.2fx%.2f degrees (simulation model)\n",
1346 } else if (mock_image_was_selected) {
1347 printf("USHER:\tcamera test mode: mock image %s\n", mock_image);
1348 } else {
1349 printf("USHER:\tcamera test mode: random image from testphotos when available\n");
1350 }
1351 printf("USHER:\tmock attitude transform: %s\n", mock_transform_enabled ? "enabled" : "disabled");
1352 }
1353 if (local_mode) {
1354 printf("USHER:\tlocal simulator device: %s\n", USHER_LOCAL_SIM_DEVICE);
1355 }
1356 camera_source_image = NULL;
1357 if (selected_camera_backend == CAMERA_BACKEND_LOCAL && !test_mode) {
1358 printf("USHER:\tmock camera image: %s\n", mock_image);
1360 } else if (test_mode) {
1361 camera_source_image = mock_image_was_selected ? mock_image : NULL;
1362 }
1363 signal(SIGPIPE, SIG_IGN);
1364 if ((test_mode || selected_camera_backend == CAMERA_BACKEND_LOCAL)
1365 && camera.init(camera_source_image) != 0) {
1366 camera.deinit();
1368 return 1;
1369 }
1370 local_capture_only = selected_camera_backend == CAMERA_BACKEND_LOCAL && !test_mode;
1371 if (clock_align_disabled) clock_probes_enabled = false;
1372 else if (!test_mode && !local_capture_only) clock_probes_enabled = true;
1375 if (earcam_requested) {
1377 }
1378 int ret = serial_init(serial_device);
1379 if (ret < 0) {
1383 return -1;
1384 }
1385 if (serial_tx_start(fd) != 0) {
1386 fprintf(stderr, "USHER:\tunable to initialize nonblocking UART output: %s\n", strerror(errno));
1387 close(fd);
1391 return 1;
1392 }
1393 if (event_wake_init() != 0) {
1394 fprintf(stderr, "USHER:\tunable to initialize event wakeup: %s\n", strerror(errno));
1396 close(fd);
1400 return 1;
1401 }
1402 fc_clock = (struct clock_alignment) {0};
1404 if (pose_log_start(pose_log_dir) != 0) {
1405 fprintf(stderr, "USHER POSE:\tlog unavailable: %s; capture continues\n", strerror(errno));
1406 }
1407 signal(SIGINT, handle_signal);
1408 signal(SIGTERM, handle_signal);
1409
1410 if (pangea_directory != NULL) start_pangea();
1412
1413 // Initial settings
1414 is_shooting = 0;
1415 usher_protocol.status = 0;
1416 image_idx = 0;
1417 image_count = 0;
1418 shooting_count = 0;
1420
1421 puts(USHER_BUILD_VERSION);
1422 printf("Started OK\n");
1424 if (!test_mode && !local_mode && selected_camera_backend == CAMERA_BACKEND_LWIR_CAM) {
1426 }
1427 if (debug_enabled) {
1428 next_debug_heartbeat = time(NULL) + DEBUG_HEARTBEAT_SECONDS;
1429 printf("USHER DEBUG:\twaiting for USHER camera messages on %s\n", serial_device);
1430 }
1431
1432 struct pollfd event_sources[3 + 2 * CAMERA_BACKEND_MAX_ID] = {
1433 {.fd = fd, .events = POLLIN, .revents = 0},
1434 {.fd = socket_get_fd(), .events = POLLIN, .revents = 0},
1435 [2 + 2 * CAMERA_BACKEND_MAX_ID] = {.fd = event_wake_reader, .events = POLLIN}
1436 };
1437
1438 // MAIN loop
1439 while (usher_running()) {
1440 if (pangea_pid > 0) {
1441 int pangea_status = 0;
1442 if (waitpid(pangea_pid, &pangea_status, WNOHANG) == pangea_pid) {
1443 fprintf(stderr, "USHER:\tPANGEA exited (status %d); capture continues, saved photos can be replayed\n", pangea_status);
1444 pangea_pid = -1;
1445 }
1446 }
1454 event_sources[0].events = POLLIN | (serial_tx_pending() ? POLLOUT : 0);
1455 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
1456 const struct camera_session_ops *ops = camera_owners[camera_id].session;
1457 const struct camera_point_stream_ops *stream = camera_owners[camera_id].point_stream;
1458 event_sources[2 * camera_id] = (struct pollfd) {
1459 .fd = ops && ops->completion_fd ? ops->completion_fd() : -1, .events = POLLIN
1460 };
1461 event_sources[2 * camera_id + 1] = (struct pollfd) {
1462 .fd = stream && stream->completion_fd ? stream->completion_fd() : -1, .events = POLLIN
1463 };
1464 }
1465 int poll_result;
1466 do {
1467 poll_result = poll(event_sources, sizeof(event_sources) / sizeof(event_sources[0]), event_loop_timeout_ms());
1468 } while (poll_result < 0 && errno == EINTR && usher_running());
1469 if (poll_result < 0) {
1470 fprintf(stderr, "USHER:\tevent poll failed: %s\n", strerror(errno));
1471 break;
1472 }
1473 if (event_sources[2 + 2 * CAMERA_BACKEND_MAX_ID].revents & POLLIN) drain_event_wake();
1474 if ((event_sources[0].revents & (POLLERR | POLLHUP | POLLNVAL)) != 0) {
1475 fprintf(stderr, "USHER:\tserial device disconnected\n");
1476 break;
1477 }
1478 if ((event_sources[0].revents & POLLOUT) != 0 && serial_tx_flush() != 0) {
1479 fprintf(stderr, "USHER:\tUART output failed: %s\n", strerror(errno));
1480 break;
1481 }
1482
1483 // Drain available serial data in one syscall and process frames in order.
1484 ssize_t bytes_read = 0;
1485 if ((event_sources[0].revents & POLLIN) != 0) {
1486 bytes_read = read(fd, serial_buffer, sizeof(serial_buffer));
1488 }
1489 if (bytes_read > 0) {
1490 for (ssize_t index = 0; index < bytes_read; index++) {
1491 serial_byte_count++;
1492 uint8_t parser_errors_before = usher_protocol.error;
1493 if (debug_enabled && serial_buffer[index] == STX) {
1494 printf("USHER DEBUG:\treceived USHER frame start at serial byte %llu\n",
1495 (unsigned long long)serial_byte_count);
1496 }
1497 parse_usher(&usher_protocol, serial_buffer[index]);
1498 if (usher_protocol.error != parser_errors_before) {
1499 rejected_frame_count++;
1500 if (debug_enabled) {
1501 printf("USHER DEBUG:\trejected USHER frame at serial byte %llu (total rejected: %llu)\n",
1502 (unsigned long long)serial_byte_count,
1503 (unsigned long long)rejected_frame_count);
1504 }
1505 }
1506 if (usher_protocol.msg_received) {
1507 valid_frame_count++;
1508 if (debug_enabled) {
1509 printf("USHER DEBUG:\taccepted USHER message id %u with %u payload bytes "
1510 "(frame %llu)\n",
1511 usher_protocol.msg_id, usher_protocol.payload_len,
1512 (unsigned long long)valid_frame_count);
1513 }
1515 }
1516 }
1517 } else if (bytes_read < 0 && errno != EAGAIN && errno != EWOULDBLOCK && errno != EINTR) {
1518 fprintf(stderr, "USHER:\tserial read failed: %s\n", strerror(errno));
1519 }
1520
1521 if (debug_enabled && time(NULL) >= next_debug_heartbeat) {
1522 pthread_mutex_lock(&shot_result_mutex);
1523 printf("USHER SHOT RESULTS:\tpending=%zu dropped=%" PRIu64 "\n", shot_result_count, shot_result_dropped);
1524 pthread_mutex_unlock(&shot_result_mutex);
1525 printf("USHER DEBUG:\twaiting for USHER data: %llu bytes, %llu valid frames, "
1526 "%llu rejected frames\n",
1527 (unsigned long long)serial_byte_count,
1528 (unsigned long long)valid_frame_count,
1529 (unsigned long long)rejected_frame_count);
1530 struct pose_log_stats pose_status = pose_log_status();
1531 printf("USHER POSE:\taccepted=%" PRIu64 " synced=%" PRIu64 " dropped=%" PRIu64
1532 " rejected=%" PRIu64 " error=%d\n", pose_status.accepted, pose_status.synced,
1533 pose_status.dropped, pose_status.rejected, pose_status.error);
1534 next_debug_heartbeat = time(NULL) + DEBUG_HEARTBEAT_SECONDS;
1536 printf("USHER CLOCK:\tprobes=%" PRIu64 " accepted=%" PRIu64 " rejected=%" PRIu64 "\n",
1538 }
1539 pthread_mutex_lock(&mut);
1540 printf("USHER SODA:\tpending=%zu active=%d deferred=%" PRIu64 " completed=%" PRIu64
1541 " failed=%" PRIu64 " unavailable/full=%" PRIu64 "\n",
1544 pthread_mutex_unlock(&mut);
1545 }
1546
1547 // Read the socket
1548 if ((event_sources[1].revents & POLLIN) != 0
1551
1553 image_count++;
1554 }
1555 }
1556
1557 }
1558
1559 // Close
1564 stop_pangea();
1565 socket_deinit();
1567 close(fd);
1568 pthread_mutex_lock(&mut);
1569 pthread_cond_broadcast(&camera_available);
1572 pthread_cond_wait(&workers_finished, &mut);
1573 }
1574 pthread_mutex_unlock(&mut);
1575 pthread_mutex_lock(&shot_result_mutex);
1576 fprintf(stderr, "USHER SHOT RESULTS:\tundelivered=%zu dropped=%" PRIu64 "\n",
1578 pthread_mutex_unlock(&shot_result_mutex);
1581
1582 if (pose_log_stop() != 0) fprintf(stderr, "USHER POSE:\tlog incomplete: %s\n", strerror(errno));
1583 struct pose_log_stats pose_status = pose_log_status();
1584 fprintf(stderr, "USHER POSE:\tfinal accepted=%" PRIu64 " synced=%" PRIu64
1585 " dropped=%" PRIu64 " rejected=%" PRIu64 " error=%d\n",
1586 pose_status.accepted, pose_status.synced, pose_status.dropped, pose_status.rejected, pose_status.error);
1588 printf("USHER:\tShutdown\n");
1589 return 0;
1590}
1591
1592/** @brief Send READY=1 to systemd when launched with a notify socket.
1593 * @details Failure is diagnostic only: USHER also supports direct/manual execution. */
1594static void notify_systemd_ready(void)
1595{
1596 const char *socket_path = getenv("NOTIFY_SOCKET");
1597 if (socket_path == NULL || socket_path[0] == '\0') {
1598 return;
1599 }
1600
1601 struct sockaddr_un address = {.sun_family = AF_UNIX};
1602 size_t path_length = strlen(socket_path);
1603 if (path_length >= sizeof(address.sun_path)) {
1604 fprintf(stderr, "USHER:\tsystemd notification socket path is too long\n");
1605 return;
1606 }
1607
1608 for (size_t index = 0; index <= path_length; index++) {
1609 address.sun_path[index] = socket_path[index];
1610 }
1611 bool abstract_socket = address.sun_path[0] == '@';
1612 if (abstract_socket) {
1613 address.sun_path[0] = '\0';
1614 }
1615
1616 int notify_fd = socket(AF_UNIX, SOCK_DGRAM, 0);
1617 if (notify_fd < 0) {
1618 fprintf(stderr, "USHER:\tfailed to create systemd notification socket: %s\n",
1619 strerror(errno));
1620 return;
1621 }
1622 if (fcntl(notify_fd, F_SETFD, FD_CLOEXEC) != 0) {
1623 close(notify_fd);
1624 return;
1625 }
1626
1627 static const char ready_message[] = "READY=1\nSTATUS=MORA serial ready; camera selected on shoot command";
1628 socklen_t address_length = (socklen_t)(offsetof(struct sockaddr_un, sun_path)
1629 + path_length + (abstract_socket ? 0 : 1));
1630 if (sendto(notify_fd, ready_message, sizeof(ready_message) - 1, MSG_NOSIGNAL,
1631 (const struct sockaddr *)&address, address_length) < 0) {
1632 fprintf(stderr, "USHER:\tfailed to notify systemd that startup completed: %s\n",
1633 strerror(errno));
1634 }
1635 close(notify_fd);
1636}
1637
1638/** @brief Consume one optical ticket, then finish images outside the lane where safe.
1639 * @param ptr Pool-owned capture_job, released on every worker exit.
1640 * @return NULL, as required by pthread entry points.
1641 * @details The worker slot and camera lane have different lifetimes: publication
1642 * may still own a bounded worker slot after the next acquisition has started.
1643 */
1644static void *handle_msg_shoot(void *ptr)
1645{
1646 struct capture_job *job = ptr;
1647
1648 pthread_mutex_lock(&mut);
1649 while (job->ticket != next_capture_ticket && usher_running()) {
1650 pthread_cond_wait(&camera_available, &mut);
1651 }
1652 if (!usher_running()) {
1653 if (waiting_capture == job) waiting_capture = NULL;
1654 pthread_mutex_unlock(&mut);
1655 capture_arbiter_failed(&job->shot, job->camera_mask);
1656 queue_image_results(job->request_id, job->shot.data.nr, job->camera_mask, USHER_SHOT_FAILED);
1659 return NULL;
1660 }
1661
1662 is_shooting = 1;
1663 if (!job->shot_counted) shooting_count++;
1664 if (waiting_capture == job) waiting_capture = NULL;
1665 if (debug_enabled) {
1666 uint64_t now_us = monotonic_time_us();
1667 printf("USHER-%d DEBUG:\tqueue age %.3f s, superseded live triggers %" PRIu64 "\n",
1668 job->shot.data.nr, now_us >= job->received_us ? (now_us - job->received_us) / 1e6 : 0,
1670 }
1671 pthread_mutex_unlock(&mut);
1672
1673 /* Acquisition holds the camera lane; ordinary optical publication and EXIF can
1674 * finish after it is released. Live SODA is always submitted elsewhere. LWIR is finished
1675 * inside the slot because its geolocation reads the backend's last-capture state;
1676 * --spottercam has the same hazard (spotter_cam_pipe's last-detection state is
1677 * likewise a single static slot, not part of `image`), so it is finished inside too. */
1678 const bool separate_lwir = lwir_async_recovery_enabled
1680 struct captured_image images[USHER_CAMERA_LWIRCAM];
1681 int image_count_ready = 0;
1682 const int ordered_camera_max = separate_lwir ? USHER_CAMERA_AICAM : USHER_CAMERA_LWIRCAM;
1683 for (int camera_id = USHER_CAMERA_CHDK; camera_id <= ordered_camera_max && usher_running(); ++camera_id) {
1684 if ((job->camera_mask & (1U << (camera_id - 1))) != 0) {
1685 if (camera_prepare(camera_id) != 0) {
1686 capture_arbiter_complete(&job->shot, camera_id, false, false, 0, monotonic_time_us());
1687 queue_shot_result(job->request_id, job->shot.data.nr, camera_id, USHER_SHOT_FAILED);
1688 continue;
1689 }
1690 struct captured_image *image = &images[image_count_ready];
1691 if (!capture_image(&job->shot, image, camera_id, &camera)) {
1692 queue_shot_result(job->request_id, job->shot.data.nr, camera_id, USHER_SHOT_FAILED);
1693 continue;
1694 }
1695 bool finish_in_slot = (image->backend.capabilities & CAMERA_CAP_FINISH_OWNED) != 0;
1696 if (finish_in_slot)
1697 queue_shot_result(job->request_id, job->shot.data.nr, camera_id,
1699 else ++image_count_ready;
1700 }
1701 }
1702
1703 pthread_mutex_lock(&mut);
1704 is_shooting = 0;
1706 pthread_cond_broadcast(&camera_available);
1707 pthread_mutex_unlock(&mut);
1708 for (int index = 0; index < image_count_ready; ++index) {
1709 queue_shot_result(job->request_id, job->shot.data.nr, images[index].camera_id,
1710 finish_image(&job->shot, &images[index]) ? USHER_SHOT_SAVED : USHER_SHOT_FAILED);
1711 }
1714 return NULL;
1715}
1716
1717/** @brief Acquire pixels or a completed file for a single camera.
1718 * @param shoot Original pose-tagged request; not automatically exposure-time pose.
1719 * @param[out] image Per-image state passed to finish_image() on success.
1720 * @param camera_id Sensor identity used for metadata and independent survey accounting.
1721 * @param backend Driver selected under the caller's camera ownership.
1722 * @return True when finish_image() is owed, including pending split-phase captures.
1723 * @note A negative acquire result must not fall through to a second exposure.
1724 * Only the driver's explicit positive fallback result allows synchronous shooting.
1725 */
1726static bool capture_image(const union dc_shot_union *shoot, struct captured_image *image,
1727 int camera_id, const struct camera_backend *backend)
1728{
1729 if (!shoot || !image || !backend || !(backend->capabilities & CAMERA_CAP_IMAGE)
1730 || !backend->shoot || !backend->deinit
1735 char *filename = image->filename;
1736 image->backend = *backend;
1738 image->backend.capabilities &= ~CAMERA_CAP_PRIVATE_IMAGE;
1739 const struct camera_backend identity = camera_identity_get(camera_id);
1740 image->backend.camera_id = camera_id;
1741 image->backend.prefix = identity.prefix;
1742 image->backend.mock = identity.mock;
1743 image->backend.soda_option = identity.soda_option;
1744 filename[0] = '\0';
1745 image->camera_id = camera_id;
1746 image->exposure_pose_valid = false;
1747 image->pose_uncertainty_m = 0;
1748 image->pending = (struct camera_pending) {0};
1749 image->capture_delay = -1;
1750 image->capture_times = (struct capture_timing) {0};
1752 && image->backend.capture_ops && image->backend.capture_ops->acquire && image->backend.capture_ops->finish) {
1753 const int acquired = image->backend.capture_ops->acquire(&image->pending, shoot->data.nr);
1754 if (acquired == 0) {
1755 capture_arbiter_acquired(shoot->data.nr, camera_id, monotonic_time_us());
1756 return true;
1757 }
1758 if (acquired < 0) {
1759 capture_arbiter_failed(shoot, 1U << (camera_id - 1));
1760 return false;
1761 }
1762 }
1763 printf("USHER-%d:\tShooting: start\n", shoot->data.nr);
1764 if (debug_enabled) {
1766 printf("USHER-%d DEBUG:\trequesting test image for selected %s backend\n",
1767 shoot->data.nr, backend->name);
1768 } else {
1769 printf("USHER-%d DEBUG:\trequesting image from %s backend\n", shoot->data.nr, backend->name);
1770 }
1771 }
1772 uint64_t capture_started_us = monotonic_time_us();
1774 ? local_pipe_map_shoot(filename, sizeof(image->filename), shoot, &image->backend,
1776 : backend->shoot(filename, sizeof(image->filename), shoot->data.nr);
1777 const uint64_t capture_finished_us = monotonic_time_us();
1778 if (debug_enabled) {
1779 printf("USHER-%d TIMING:\tcamera=%d capture_ms=%.3f result=%d\n",
1780 shoot->data.nr, camera_id, (monotonic_time_us() - capture_started_us) / 1000.0,
1782 }
1783 if (capture_result != 0) {
1784 capture_arbiter_complete(shoot, camera_id, false, false, 0, monotonic_time_us());
1785 fprintf(stderr, "USHER-%d:\t%s camera capture failed\n", shoot->data.nr, backend->name);
1786 if (!mock_map_enabled) {
1787 if (!(camera_id == USHER_CAMERA_CHDK && chdk_async_capture_enabled
1789 if (camera_id == USHER_CAMERA_LWIRCAM) lwir_mark_backoff();
1790 }
1791 filename[0] = '\0';
1792 }
1793 printf("USHER-%d:\tShooting: got image %s\n", shoot->data.nr, filename);
1794 if (filename[0] != '\0' && mock_transform_enabled) {
1795 int transform_result = image_mock_transform(filename, shoot);
1796 if (transform_result < 0) {
1797 fprintf(stderr, "USHER-%d:\tfailed to apply mock attitude transform to %s\n",
1798 shoot->data.nr, filename);
1799 filename[0] = '\0';
1800 } else if (transform_result == IMAGE_MOCK_TRANSFORM_SKIPPED) {
1801 printf("USHER-%d:\tShooting: mock attitude transform skipped; source image retained\n",
1802 shoot->data.nr);
1803 } else {
1804 printf("USHER-%d:\tShooting: mock attitude transform applied\n", shoot->data.nr);
1805 }
1806 }
1807 if (filename[0] != '\0' && test_capture_enabled && !mock_map_enabled
1808 && camera_id == USHER_CAMERA_LWIRCAM
1809 && lwir_cam_pipe_process_mock(filename) != 0) {
1810 fprintf(stderr, "USHER-%d:\tLWIR mock processing failed\n", shoot->data.nr);
1811 filename[0] = '\0';
1812 }
1813 if (filename[0] && (test_capture_enabled || local_capture_only || mock_map_enabled)) {
1814 if (image->backend.name && !strcmp(image->backend.name, "spottercam") &&
1815 spotter_cam_pipe_analyze(filename, shoot->data.nr))
1816 fprintf(stderr, "USHER:\tONNX object analysis failed; retaining photograph\n");
1817 }
1818 const bool live_lwir = image->backend.capture_timing && !(image->backend.capabilities & CAMERA_CAP_MOCK);
1819 image->capture_delay = live_lwir && image->backend.capture_delay ? image->backend.capture_delay() : -1;
1820 image->capture_times = live_lwir ? image->backend.capture_timing() : (struct capture_timing) {0};
1821 if (live_lwir && capture_timing_valid(&image->capture_times)) {
1822 struct capture_observation *observation = &image->capture_times.observation;
1823 observation->earliest_us = observation->latest_us = image->capture_times.arrival_monotonic_us;
1824 observation->sequence = image->capture_times.callback_sequence;
1825 observation->kind = CAPTURE_TIME_FRAME_ARRIVAL;
1826 if (exposure_latency[camera_id].valid)
1827 capture_observation_latency(observation, image->capture_times.arrival_monotonic_us,
1828 exposure_latency[camera_id].minimum_us, exposure_latency[camera_id].maximum_us);
1829 } else if (camera_id == USHER_CAMERA_CHDK && !test_capture_enabled && !local_capture_only) {
1830 struct capture_observation *observation = &image->capture_times.observation;
1831 observation->earliest_us = capture_started_us;
1832 observation->latest_us = capture_finished_us;
1833 observation->kind = CAPTURE_TIME_SHUTTER_WINDOW;
1834 if (exposure_latency[camera_id].valid && capture_finished_us >= capture_started_us
1835 && exposure_latency[camera_id].maximum_us <= capture_finished_us - capture_started_us) {
1836 observation->earliest_us += exposure_latency[camera_id].minimum_us;
1837 observation->latest_us = capture_started_us + exposure_latency[camera_id].maximum_us;
1839 }
1840 }
1841 return filename[0] != '\0';
1842}
1843
1844/** @brief Resolve live pose evidence associated with an acquired image.
1845 * @param request Original trigger whose photo number is retained.
1846 * @param[in,out] image Image and timing evidence to qualify.
1847 * @details Prefer frame-bound timing when available. Wait briefly for a pose
1848 * bracket, but promote the aligned pose to exposure pose only when the time
1849 * evidence represents exposure, not merely frame delivery. */
1851{
1853 struct capture_observation frame = {0};
1854 if (capture_arbiter_frame_timing(image->filename, image->camera_id, &frame)) image->capture_times.observation = frame;
1855 struct capture_observation *observation = &image->capture_times.observation;
1856 image->exposure_pose_valid = false;
1857 if (!capture_arbiter_observation_pose(observation, 200000)) return;
1858 observation->pose.data.nr = request->data.nr;
1859 if (capture_observation_exposure(observation)) {
1860 image->exposure_shot = observation->pose;
1861 image->pose_uncertainty_m = observation->pose_uncertainty_m;
1862 image->exposure_pose_valid = true;
1863 }
1864}
1865
1866/** @brief Complete publication and metadata before releasing survey ownership.
1867 * @param shoot Original request, retained as provenance if exposure pose is available.
1868 * @param[in,out] image Acquired image and its original driver's completion hooks.
1869 * @details Native completion can wait for a JPEG here without holding the optical
1870 * lane. Metadata-dependent drivers still call this under their capture ownership.
1871 * Live analysis is submitted only after saving; local/test callers retain the
1872 * synchronous behavior expected by their tools and regression fixtures.
1873 */
1874static bool finish_image(const union dc_shot_union *shoot, struct captured_image *image)
1875{
1876 if (image->pending.acquired) {
1877 if (!image->backend.capture_ops || !image->backend.capture_ops->finish
1878 || image->backend.capture_ops->finish(&image->pending, image->filename, sizeof(image->filename), &keep_running) != 0) {
1879 capture_arbiter_failed(shoot, 1U << (image->camera_id - 1));
1880 return false;
1881 }
1882 }
1884 const union dc_shot_union *request = image->exposure_pose_valid ? shoot : NULL;
1885 /* Keep both records. Replacing request pose with an exposure estimate must not
1886 * erase the original evidence or apply the old latency correction a second time. */
1887 if (image->exposure_pose_valid) shoot = &image->exposure_shot;
1888 char detection_summary[256];
1889 const bool object_metadata = (image->backend.capabilities & CAMERA_CAP_DETECTION) != 0;
1890 if (object_metadata)
1891 image->backend.bind_frame(image->capture_times.observation.sequence,
1892 image->capture_times.observation.frame_bound
1893 ? image->capture_times.observation.sensor_timestamp_ns : 0);
1894 if (object_metadata) image->backend.detection_summary(detection_summary, sizeof(detection_summary));
1895 uint64_t metadata_started_us = monotonic_time_us();
1896 char *filename = image->filename;
1897 bool image_ready = false;
1898 {
1899 if (debug_enabled) {
1900 printf("USHER-%d DEBUG:\twriting flight metadata to captured JPEG\n", shoot->data.nr);
1901 }
1902 const int compensate = motion_compensation_enabled && !image->exposure_pose_valid;
1903 if (image_exif_write_complete(filename, shoot, image->capture_delay, compensate,
1904 &image->capture_times, request, image->pose_uncertainty_m,
1905 object_metadata ? detection_summary : NULL) == 0) {
1906 image_ready = true;
1907 printf("USHER-%d:\tShooting: EXIF metadata added\n", shoot->data.nr);
1908 if (image->backend.capabilities & CAMERA_CAP_GEOLOCATION) {
1909 if (mock_map_enabled) {
1910 if (image_exif_write_hotspots(filename,
1911 "status=unsupported_mock_map; visible_map_texture=true; coordinates_omitted=true") != 0) {
1912 fprintf(stderr, "USHER-%d:\tfailed to record map mock provenance\n", shoot->data.nr);
1913 }
1914 } else if (mock_transform_enabled) {
1915 if (image_exif_write_hotspots(filename, "status=unsupported_mock_transform; coordinates_omitted=true") != 0) {
1916 fprintf(stderr, "USHER-%d:\tfailed to record unsupported thermal transform\n", shoot->data.nr);
1917 }
1918 } else if (image->backend.geolocate(filename) != 0) {
1919 fprintf(stderr, "USHER-%d:\tLWIR hotspot geolocation failed; photo retained\n", shoot->data.nr);
1921 if (image_exif_write_hotspots(filename, "status=analysis_failed; coordinates_omitted=true") != 0) {
1922 fprintf(stderr, "USHER-%d:\tfailed to record hotspot analysis failure\n", shoot->data.nr);
1923 }
1924 }
1925 } else if (object_metadata) {
1926 /* The detector's result was captured above and included in the
1927 * same EXIF rewrite. Do not add a second detection-only rewrite here. */
1928 if (debug_enabled) {
1929 printf("USHER-%d DEBUG:\tobject detection: %s\n", shoot->data.nr, detection_summary);
1930 }
1931 }
1933 mock_map_vertical_fov) != 0) {
1934 fprintf(stderr, "USHER-%d:\tfailed to record mock map geometry\n", shoot->data.nr);
1935 image_ready = false;
1936 }
1937 if (image_ready && mock_map_enabled && mock_lens_profile &&
1938 image->camera_id == USHER_CAMERA_AICAM) {
1939 char derivative[MAX_FILENAME];
1940 if (!image_lens_emulate("./bin/camera_lens", filename, mock_lens_profile, mock_map_cache,
1941 derivative, sizeof(derivative), &keep_running)) {
1942 fprintf(stderr, "USHER-%d:\tlens emulation failed; clean photo retained, LOOM/SODA skipped\n",
1943 shoot->data.nr);
1944 image_ready = false;
1945 } else {
1946 const size_t length = strlen(derivative);
1947 for (size_t index = 0; index <= length; ++index) filename[index] = derivative[index];
1948 printf("USHER-%d:\tlens-emulated analysis input %s\n", shoot->data.nr, filename);
1949 }
1950 }
1951 if (image_ready && (image->backend.capabilities & CAMERA_CAP_PRIVATE_IMAGE)) {
1952 const int publication = usher_complete_photo(filename, sizeof(image->filename));
1953 if (publication < 0) {
1954 fprintf(stderr, "USHER-%d:\tphoto publication failed; private capture retained at %s: %s\n",
1955 shoot->data.nr, filename, strerror(errno));
1956 image_ready = false;
1957 } else if (publication > 0) {
1958 fprintf(stderr, "USHER-%d:\tphoto published; directory sync or private alias cleanup incomplete: %s\n",
1959 shoot->data.nr, strerror(errno));
1960 }
1961 }
1962 if (image_ready) {
1963 printf("Photo take %d\n", shoot->data.nr);
1964 }
1965 } else {
1966 fprintf(stderr, "USHER-%d:\tfailed to add EXIF metadata to %s\n", shoot->data.nr, filename);
1967 }
1968 }
1969
1970 if (debug_enabled) {
1971 printf("USHER-%d TIMING:\tcamera=%d metadata_ms=%.3f ready=%d\n",
1972 shoot->data.nr, image->camera_id,
1973 (monotonic_time_us() - metadata_started_us) / 1000.0, image_ready);
1974 }
1975 capture_arbiter_complete(shoot, image->camera_id, image_ready, image->exposure_pose_valid,
1976 image->pose_uncertainty_m, monotonic_time_us());
1977 if (image_ready) {
1978 if (object_metadata) image->backend.save_detection_copy(filename);
1979 if (image->backend.image_saved) image->backend.image_saved(filename, shoot);
1981 if (live_capture || (lwir_spotter_enabled() && image->camera_id == USHER_CAMERA_LWIRCAM)) {
1982 defer_saved_analysis(filename, shoot, image->camera_id, &image->capture_times);
1983 } else {
1984 uint64_t analysis_started_us = monotonic_time_us();
1985 int soda_result = run_soda(filename, shoot, image->camera_id);
1986 printf("USHER-%d:\tShooting: soda return %d of image %s\n",
1987 shoot->data.nr, soda_result, filename);
1988 if (debug_enabled) {
1989 printf("USHER-%d TIMING:\tcamera=%d soda_ms=%.3f result=%d\n",
1990 shoot->data.nr, image->camera_id,
1991 (monotonic_time_us() - analysis_started_us) / 1000.0, soda_result);
1992 }
1993 }
1994 }
1995 return image_ready;
1996}
1997
1998/** @brief Dispatch one complete UART frame without running slow camera work inline.
1999 * @details The serial event-loop owner calls this once per parsed message. Camera
2000 * masks are split into independent backend work; EARcam receipt-time tagging is
2001 * separate from photographic queueing. New protocols must validate lengths and
2002 * session ownership before causing camera or service side effects.
2003 */
2005{
2006 usher_protocol.msg_received = false;
2009 return;
2010 }
2011
2014 if (usher_protocol.payload_len == sizeof(message.bin)) {
2015 for (size_t index = 0; index < sizeof(message.bin); ++index) message.bin[index] = usher_protocol.payload[index];
2017 }
2018 return;
2019 }
2022 if (usher_protocol.payload_len != sizeof(message.bin)) return;
2023 for (size_t index = 0; index < sizeof(message.bin); ++index) message.bin[index] = usher_protocol.payload[index];
2024 if (message.data.session != capture_arbiter_session_id() || !message.data.session
2025 || message.data.camera_mask > USHER_CAMERA_MASK_ALL) return;
2026 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
2027 if ((message.data.camera_mask & (1U << (camera_id - 1))) && prepare_session_backend(camera_id))
2028 camera_owners[camera_id].record(&message.data.shot);
2029 }
2031 pthread_mutex_lock(&mut);
2033 pthread_mutex_unlock(&mut);
2034 return;
2035 }
2036
2037 if (usher_protocol.msg_id == USHER_CLOCK_REPLY) {
2041 else ++clock_rejected_count;
2042 }
2043 return;
2044 }
2045 if (usher_protocol.msg_id == USHER_POSE_CLOCKED) {
2047 return;
2048 }
2049 if (usher_protocol.msg_id == USHER_POSE_SAMPLE) {
2050 fc_clock.valid = false;
2053 camera_record_pose(usher_protocol.payload, usher_protocol.payload_len);
2054 return;
2055 }
2056 if (usher_protocol.msg_id == USHER_SHOOT_MASK) {
2057 if (debug_enabled) {
2058 printf("USHER DEBUG:\tphoto trigger received; decoding shot payload\n");
2059 }
2060 union dc_shot_mask_union message;
2061 if (usher_protocol.payload_len != sizeof(message.bin)) {
2062 fprintf(stderr, "USHER:\tinvalid USHER shot payload length %u\n", usher_protocol.payload_len);
2063 return;
2064 }
2065 for (size_t index = 0; index < sizeof(message.bin); ++index) message.bin[index] = usher_protocol.payload[index];
2066 const union dc_shot_union *shoot = &message.data.shot;
2067 if (!message.data.request_id || shoot->data.nr <= 0) return;
2068 uint32_t camera_mask = message.data.camera_mask;
2069 if (camera_mask > USHER_CAMERA_MASK_ALL) {
2070 fprintf(stderr, "USHER:\tinvalid camera mask %" PRIu32 "\n", camera_mask);
2071 return;
2072 }
2073 if (camera_mask == USHER_CAMERA_MASK_NONE) return;
2074 for (unsigned camera_id = 6; camera_id <= 8; ++camera_id) {
2075 if (camera_mask & (1U << (camera_id - 1)))
2076 queue_shot_result(message.data.request_id, shoot->data.nr, camera_id, USHER_SHOT_UNSUPPORTED);
2077 }
2078 camera_mask &= USHER_CAMERA_MASK_SUPPORTED;
2079 if (!camera_mask) return;
2080 printf("USHER:\tSHOT %d mask 0x%02" PRIx32 " | lat %.7f lon %.7f | MSL %.1f m AGL %.1f m | "
2081 "roll %.1f pitch %.1f yaw %.1f deg | speed %.1f m/s course %.1f deg\n",
2082 shoot->data.nr, camera_mask,
2083 shoot->data.lat / 1e7,
2084 shoot->data.lon / 1e7,
2085 shoot->data.alt / 1000.0,
2090 shoot->data.vground / SPEED_BFP_SCALE,
2092
2093 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
2094 const struct camera_backend backend = camera_identity_get(camera_id);
2095 if ((camera_mask & (1U << (camera_id - 1))) && (backend.capabilities & CAMERA_CAP_POINT_STREAM)) {
2096 const struct camera_backend *owner = &camera_owners[camera_id];
2097 const bool recorded = camera_stream_states[camera_id] == CAMERA_STREAM_ACTIVE && owner->record && owner->record(shoot) == 0;
2098 queue_shot_result(message.data.request_id, shoot->data.nr, camera_id,
2100 continue;
2101 }
2102 if (!(camera_mask & (1U << (camera_id - 1))) || !(backend.capabilities & CAMERA_CAP_POINT_SESSION)) continue;
2103 bool recorded = false;
2105 const struct camera_backend *owner = &camera_owners[camera_id];
2106 recorded = owner->session->listening() && owner->record(shoot) == 0;
2107 }
2108 queue_shot_result(message.data.request_id, shoot->data.nr, camera_id,
2110 }
2112 start_shoot_worker(shoot, (uint8_t)camera_mask, message.data.request_id);
2113 }
2114 } else if (usher_protocol.msg_id == USHER_STOP_TARGETED || usher_protocol.msg_id == USHER_START_TARGETED) {
2115 if (usher_protocol.payload_len != USHER_STOP_TARGETED_MSG_SIZE) {
2116 fprintf(stderr, "USHER:\tinvalid USHER session payload length %u\n", usher_protocol.payload_len);
2117 return;
2118 }
2119 union usher_camera_session_union command;
2120 for (size_t index = 0; index < sizeof(command.bin); ++index) {
2121 command.bin[index] = usher_protocol.payload[index];
2122 }
2123 if (command.data.camera_id > CAMERA_BACKEND_MAX_ID || !command.data.session_id) return;
2124 if (usher_protocol.msg_id == USHER_START_TARGETED) {
2126 } else {
2128 }
2129 } else if (usher_protocol.msg_id == USHER_BUFFER_EMPTY) {
2131 }
2132}
2133
2134/** @brief Ensure a point-session backend has a registered owner.
2135 * @param camera_id Protocol camera ID.
2136 * @return True once a complete session backend is initialized.
2137 * @details Check all lifecycle hooks before initialization and reuse an
2138 * existing owner rather than reopening a session-capable device. */
2140{
2142 const struct camera_backend backend = camera_identity_get(camera_id);
2143 const struct camera_session_ops *ops = backend.session;
2144 if (!(backend.capabilities & CAMERA_CAP_POINT_SESSION) || !ops || !ops->start || !ops->stop
2145 || !ops->listening || !ops->completion_fd || !ops->poll_result || !ops->drain
2146 || !backend.init || !backend.deinit || !backend.record) return false;
2147 if (camera_initialized[camera_id]) return true;
2148 const struct camera_backend_host host = {.running = &keep_running,
2149 .pose_lookup = capture_arbiter_observation_pose, .queue_analysis = defer_soda
2150 };
2151 if (backend.configure) backend.configure(&host);
2152 if (backend.init(NULL) != 0) {
2153 backend.deinit();
2154 fprintf(stderr, "USHER:\t%s not available; other cameras remain active\n", backend.name);
2155 return false;
2156 }
2157 camera_owners[camera_id] = backend;
2158 camera_initialized[camera_id] = true;
2159 return true;
2160}
2161
2162/** @brief Resolve runtime routing without mutating the global selected backend.
2163 * @param camera_id Protocol camera identity.
2164 * @return Driver type, including configured AI detection and local overrides.
2165 */
2170
2171/** @brief Select and lazily initialize a backend under the caller's camera ownership.
2172 * @param camera_id Image-camera identity, not a mask.
2173 * @return Zero when ready, negative on invalid input, shutdown or backend failure.
2174 * @details A failed optional camera must not stop the other bits of a mixed request.
2175 */
2176static int camera_prepare(int camera_id)
2177{
2178 if (!usher_running() || camera_id < USHER_CAMERA_CHDK || camera_id > USHER_CAMERA_LWIRCAM) return -1;
2179 const enum camera_backend_type type = camera_type_for_id(camera_id);
2180 if (camera_backend_select(type, test_capture_enabled) != 0) return -1;
2181 optical_camera_id = camera_id;
2182 if (camera_initialized[camera_id]) {
2183 const struct camera_backend *owner = &camera_owners[camera_id];
2184 if (owner->init != camera.init || owner->shoot != camera.shoot || owner->deinit != camera.deinit
2185 || owner->capture_ops != camera.capture_ops || owner->capabilities != camera.capabilities
2186 || owner->point_stream != camera.point_stream || owner->image_saved != camera.image_saved
2187 || owner->prefix != camera.prefix) {
2188 fprintf(stderr, "USHER:\tcamera id %d backend change requires completed teardown\n", camera_id);
2189 return -1;
2190 }
2191 camera = *owner;
2192 return 0;
2193 }
2195 uint64_t now_us = monotonic_time_us();
2196 if (now_us == 0 || now_us < lwir_retry_after_us) return -1;
2198 printf("USHER:\tretrying LWIR camera after unavailable cooldown\n");
2199 }
2200 if (camera_register_stream(&camera) != 0) return -1;
2201 const struct camera_backend_host host = {.running = &keep_running,
2202 .pose_lookup = capture_arbiter_observation_pose, .queue_analysis = defer_soda};
2203 if (camera.configure) camera.configure(&host);
2204 if (camera.init(camera_source_image) != 0) {
2205 camera.deinit();
2206 if (camera_id == USHER_CAMERA_LWIRCAM) lwir_mark_backoff();
2207 if (!camera_warned[camera_id]) {
2208 camera_warned[camera_id] = true;
2209 fprintf(stderr, "USHER:\t%s (camera id %d) not available; continuing without it\n",
2210 camera.name, camera_id);
2211 } else if (debug_enabled) {
2212 printf("USHER DEBUG:\t%s (camera id %d) still not available\n", camera.name, camera_id);
2213 }
2214 return -1;
2215 }
2216 camera_warned[camera_id] = false;
2217 if (camera_id == USHER_CAMERA_LWIRCAM) {
2218 camera_unavailable[camera_id] = false;
2220 }
2221 if (!camera.point_stream) camera_owners[camera_id] = camera;
2222 camera_initialized[camera_id] = true;
2223 printf("USHER:\tactive camera backend: %s (id %d)\n", camera.name, optical_camera_id);
2224 return 0;
2225}
2226
2227/** @brief Rate-limit thermal recovery so a missing USB camera does not consume every request. */
2228static void lwir_mark_backoff(void)
2229{
2230 uint64_t now_us = monotonic_time_us();
2231 pthread_mutex_lock(&mut);
2234 lwir_retry_after_us = now_us == 0 || now_us > UINT64_MAX - LWIR_RETRY_COOLDOWN_US
2235 ? UINT64_MAX : now_us + LWIR_RETRY_COOLDOWN_US;
2236 pthread_mutex_unlock(&mut);
2237}
2238
2239/** @brief Retry thermal startup outside both UART reception and the optical lane.
2240 * @param unused Unused pthread argument.
2241 * @return NULL after recovery or shutdown; completion state is signalled under mut.
2242 */
2243static void *recover_lwir_camera(void *unused)
2244{
2245 (void)unused;
2246 bool retrying = false;
2247 while (usher_running()) {
2248 pthread_mutex_lock(&mut);
2249 uint64_t now_us = monotonic_time_us();
2250 bool cooling_down = camera_unavailable[USHER_CAMERA_LWIRCAM]
2251 && (now_us == 0 || now_us < lwir_retry_after_us);
2252 pthread_mutex_unlock(&mut);
2253 if (cooling_down) {
2255 continue;
2256 }
2257 if (retrying) printf("USHER:\tretrying LWIR camera after unavailable cooldown\n");
2258
2259 pthread_mutex_lock(&lwir_camera_mutex);
2260 if (!usher_running()) {
2261 pthread_mutex_unlock(&lwir_camera_mutex);
2262 break;
2263 }
2265 int result = backend.init_cancelable(NULL, &keep_running);
2266 if (result == 0 && !usher_running()) result = -1;
2267 if (result != 0) backend.deinit();
2268 pthread_mutex_unlock(&lwir_camera_mutex);
2269
2270 pthread_mutex_lock(&mut);
2271 if (result == 0) {
2278 printf("USHER:\tactive camera backend: lwircam (id %d)\n", USHER_CAMERA_LWIRCAM);
2279 pthread_cond_broadcast(&workers_finished);
2280 pthread_mutex_unlock(&mut);
2281 return NULL;
2282 }
2285 now_us = monotonic_time_us();
2286 lwir_retry_after_us = now_us == 0 || now_us > UINT64_MAX - LWIR_RETRY_COOLDOWN_US
2287 ? UINT64_MAX : now_us + LWIR_RETRY_COOLDOWN_US;
2290 fprintf(stderr, "USHER:\tlwircam (camera id %d) not available; AIcam remains active\n",
2292 }
2293 pthread_cond_broadcast(&workers_finished);
2294 pthread_mutex_unlock(&mut);
2295 retrying = true;
2296 }
2297
2298 pthread_mutex_lock(&mut);
2300 pthread_cond_broadcast(&workers_finished);
2301 pthread_mutex_unlock(&mut);
2302 return NULL;
2303}
2304
2305/** @brief Check thermal readiness or start at most one background recovery attempt.
2306 * @return True only when already initialized; false does not mean recovery is finished.
2307 */
2309{
2310 pthread_mutex_lock(&mut);
2312 pthread_mutex_unlock(&mut);
2313 return true;
2314 }
2316 pthread_mutex_unlock(&mut);
2317 return false;
2318 }
2320 pthread_mutex_unlock(&mut);
2321
2322 pthread_t recovery_thread;
2323 int thread_result = pthread_create(&recovery_thread, NULL, recover_lwir_camera, NULL);
2324 if (thread_result != 0) {
2325 pthread_mutex_lock(&mut);
2327 pthread_cond_broadcast(&workers_finished);
2328 pthread_mutex_unlock(&mut);
2329 fprintf(stderr, "USHER:\tfailed to start LWIR recovery: %s\n", strerror(thread_result));
2331 return false;
2332 }
2333 pthread_detach(recovery_thread);
2334 return false;
2335}
2336
2337/** @brief Admit an optional stream once per owner, without opening its sensor.
2338 * @details Failed optional startup is cleaned up once and does not disable photos.
2339 * Changing profiles requires teardown, even before the first sensor acquisition.
2340 */
2341static int camera_register_stream(const struct camera_backend *backend)
2342{
2343 if (!backend || backend->camera_id > CAMERA_BACKEND_MAX_ID) return -1;
2344 const unsigned camera_id = backend->camera_id;
2346 && camera_owners[camera_id].point_stream != backend->point_stream) return -1;
2347 if (!backend->point_stream) return 0;
2349 if (camera_initialized[camera_id] && camera_owners[camera_id].point_stream != backend->point_stream) return -1;
2351 camera_owners[camera_id] = *backend;
2352 const struct camera_point_stream_ops *stream = backend->point_stream;
2353 if (stream->init && stream->init() != 0) {
2355 if (stream->drain) stream->drain();
2356 } else camera_stream_states[camera_id] = CAMERA_STREAM_ACTIVE;
2357 return 0;
2358}
2359
2360/** @brief Withdraw one backend from service and release its resources.
2361 * @param camera_id Owner slot, including the default slot.
2362 * @details Clear dispatch state, drain an active point stream, then release
2363 * the initialized backend. Clear its result caches before the slot is reused. */
2364static void camera_close_owner(unsigned camera_id)
2365{
2366 if (camera_id > CAMERA_BACKEND_MAX_ID) return;
2367 const struct camera_backend owner = camera_owners[camera_id];
2368 const bool initialized = camera_initialized[camera_id];
2369 const bool stream_active = camera_stream_states[camera_id] == CAMERA_STREAM_ACTIVE;
2371 camera_owners[camera_id] = (struct camera_backend) {0};
2372 camera_initialized[camera_id] = false;
2373 if (stream_active && owner.point_stream && owner.point_stream->drain) owner.point_stream->drain();
2374 if (owner.point_stream && camera_id) {
2375 memset(&point_sessions[camera_id - 1], 0, sizeof(point_sessions[camera_id - 1]));
2376 point_update_pending[camera_id - 1] = false;
2377 }
2378 if (initialized && owner.deinit) owner.deinit();
2379}
2380
2381/** @brief Tear down registered cameras and independently owned analysis workers.
2382 * @details Walk the owner registry first, then stop auxiliary workers whose
2383 * lifetime is not completely represented by a registry slot. */
2384static void cameras_deinit(void)
2385{
2386 for (unsigned camera_id = USHER_CAMERA_ALL; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id)
2387 camera_close_owner(camera_id);
2390 const struct camera_backend loom_capture = loom_camera_backend_get(false);
2391 if (loom_capture.deinit) loom_capture.deinit();
2392}
2393
2394/** @brief Own thermal capture and its last-frame metadata independently of optical work.
2395 * @param pointer Pool-owned request, released after capture handling.
2396 * @return NULL after releasing the thermal in-progress flag.
2397 */
2398static void *handle_lwir_shoot(void *pointer)
2399{
2400 struct capture_job *job = pointer;
2401 pthread_mutex_lock(&lwir_camera_mutex);
2402 bool saved = false;
2403 if (usher_running()) {
2404 const struct camera_backend backend = camera_owners[USHER_CAMERA_LWIRCAM];
2405 struct captured_image image;
2407 saved = finish_image(&job->shot, &image);
2408 }
2410 }
2411 pthread_mutex_unlock(&lwir_camera_mutex);
2412 queue_shot_result(job->request_id, job->shot.data.nr, USHER_CAMERA_LWIRCAM,
2414 pthread_mutex_lock(&mut);
2417 const bool pending = waiting_lwir.valid;
2419 const union dc_shot_union next_shot = pending ? waiting_lwir.shot : (union dc_shot_union) {0};
2420 const uint32_t next_request_id = pending ? waiting_lwir.request_id : 0;
2421 const uint64_t received_us = pending ? waiting_lwir.received_us : 0;
2422 waiting_lwir.valid = false;
2423 pthread_cond_broadcast(&workers_finished);
2424 pthread_mutex_unlock(&mut);
2425 if (pending) {
2426 const uint64_t now_us = monotonic_time_us();
2427 if (usher_running() && now_us >= received_us && now_us - received_us <= LWIR_WAIT_MAX_US)
2428 start_lwir_worker(&next_shot, next_request_id, received_us);
2429 else {
2431 queue_shot_result(next_request_id, next_shot.data.nr, USHER_CAMERA_LWIRCAM, USHER_SHOT_FAILED);
2432 }
2433 pthread_mutex_lock(&mut);
2435 pthread_cond_broadcast(&workers_finished);
2436 pthread_mutex_unlock(&mut);
2437 }
2438 return NULL;
2439}
2440
2441/** @brief Dispatch a single-flight thermal request without waiting for USB recovery.
2442 * @param[in] shoot Request copied into worker-owned storage on admission.
2443 * @param[in] request_id Correlation ID returned to the flight controller; distinct from photo number.
2444 * @param[in] received_us Monotonic time when the request was admitted, used to reject stale queued work.
2445 * @details This function is called by the serial owner. Failed admission releases
2446 * matching survey ownership so a missing thermal camera cannot remain permanently busy.
2447 */
2448static void start_lwir_worker(const union dc_shot_union *shoot, uint32_t request_id, uint64_t received_us)
2449{
2450 pthread_mutex_lock(&mut);
2451 if (!usher_running()) {
2452 pthread_cond_broadcast(&workers_finished);
2453 pthread_mutex_unlock(&mut);
2456 return;
2457 }
2461 || (waiting_lwir.valid && waiting_lwir.received_us > received_us)) {
2462 pthread_mutex_unlock(&mut);
2465 return;
2466 }
2467 const bool replaced = waiting_lwir.valid;
2468 const union dc_shot_union old_shot = replaced ? waiting_lwir.shot : (union dc_shot_union) {0};
2469 const uint32_t old_request_id = replaced ? waiting_lwir.request_id : 0;
2470 waiting_lwir.shot = *shoot;
2471 waiting_lwir.request_id = request_id;
2472 waiting_lwir.received_us = received_us;
2473 waiting_lwir.valid = true;
2474 pthread_cond_broadcast(&workers_finished);
2475 pthread_mutex_unlock(&mut);
2476 if (replaced) {
2479 }
2480 return;
2481 }
2482 pthread_mutex_unlock(&mut);
2486 return;
2487 }
2488 pthread_mutex_lock(&mut);
2490 if (job == NULL) {
2491 pthread_mutex_unlock(&mut);
2492 fprintf(stderr, "USHER-%d:\tLWIR job pool is full\n", shoot->data.nr);
2495 return;
2496 }
2497 job->shot = *shoot;
2498 job->request_id = request_id;
2501 pthread_t worker;
2502 int result = pthread_create(&worker, NULL, handle_lwir_shoot, job);
2503 if (result != 0) {
2506 fprintf(stderr, "USHER-%d:\tfailed to start LWIR worker: %s\n", shoot->data.nr, strerror(result));
2507 } else {
2508 pthread_detach(worker);
2509 }
2510 pthread_mutex_unlock(&mut);
2511 if (result != 0) {
2514 }
2515}
2516
2517/** @brief Pause new CHDK attempts after a failed request; the caller holds mut. */
2519{
2520 const uint64_t now_us = monotonic_time_us();
2521 chdk_retry_after_us = now_us && now_us <= UINT64_MAX - CHDK_RETRY_COOLDOWN_US
2522 ? now_us + CHDK_RETRY_COOLDOWN_US : UINT64_MAX;
2523}
2524
2525/** @brief Write metadata for one captured CHDK image after the camera lane was released.
2526 * @param pointer Unused; the single-flight job lives in chdk_finish.
2527 * @return NULL after reporting the result and clearing the finisher flag. */
2528static void *handle_chdk_finish(void *pointer)
2529{
2530 (void)pointer;
2531 const bool saved = finish_image(&chdk_finish.job.shot, &chdk_finish.image);
2532 if (!saved && usher_running())
2533 fprintf(stderr, "USHER-%d: CHDK request failed; new CHDK attempts paused for %.3f s; other camera lanes remain independent\n",
2534 chdk_finish.job.shot.data.nr, CHDK_RETRY_COOLDOWN_US / 1e6);
2535 queue_shot_result(chdk_finish.job.request_id, chdk_finish.job.shot.data.nr, USHER_CAMERA_CHDK,
2537 pthread_mutex_lock(&mut);
2538 if (!saved) chdk_start_cooldown_locked();
2540 pthread_cond_broadcast(&workers_finished);
2541 pthread_mutex_unlock(&mut);
2542 return NULL;
2543}
2544
2545/** @brief Hand a captured image to the finisher, waiting if the previous one is still writing.
2546 * @return False when no finisher thread could start; the caller then finishes the image inline. */
2547static bool start_chdk_finish(const struct capture_job *job, const struct captured_image *image)
2548{
2549 pthread_mutex_lock(&mut);
2550 while (chdk_finish_in_progress) pthread_cond_wait(&workers_finished, &mut);
2551 chdk_finish.job = *job;
2552 chdk_finish.image = *image;
2554 pthread_attr_t attributes;
2555 int result = pthread_attr_init(&attributes);
2556 const bool attributes_ready = result == 0;
2557 if (!result) result = pthread_attr_setstacksize(&attributes, 256U * 1024U);
2558 if (!result) result = pthread_attr_setdetachstate(&attributes, PTHREAD_CREATE_DETACHED);
2559 pthread_t worker;
2560 if (!result) result = pthread_create(&worker, &attributes, handle_chdk_finish, NULL);
2561 if (attributes_ready) pthread_attr_destroy(&attributes);
2562 if (result) {
2564 pthread_cond_broadcast(&workers_finished);
2565 }
2566 pthread_mutex_unlock(&mut);
2567 if (result) fprintf(stderr, "USHER-%d: unable to start CHDK finisher: %s; finishing inline\n",
2568 job->shot.data.nr, strerror(result));
2569 return result == 0;
2570}
2571
2572/** @brief Capture one CHDK request and release the camera lane before metadata is written.
2573 * @param pointer Dedicated single-flight request storage, retained until the capture ends.
2574 * @return NULL after teardown and signalling worker completion.
2575 * @details A captured image moves to handle_chdk_finish(), which owns the shot result,
2576 * so EXIF and publication overlap the next camera operation. */
2577static void *handle_chdk_shoot(void *pointer)
2578{
2579 const struct capture_job *job = pointer;
2581 bool saved = false;
2582 bool handed_off = false;
2583 bool initialized = false;
2584 if (usher_running()) {
2585 const struct camera_backend_host host = {.running = &keep_running,
2586 .pose_lookup = capture_arbiter_observation_pose, .queue_analysis = defer_soda};
2587 if (backend.configure) backend.configure(&host);
2588 initialized = backend.init && backend.init(camera_source_image) == 0;
2589 if (initialized) {
2590 struct captured_image image;
2591 if (capture_image(&job->shot, &image, USHER_CAMERA_CHDK, &backend)) {
2592 handed_off = start_chdk_finish(job, &image);
2593 if (!handed_off) saved = finish_image(&job->shot, &image);
2594 }
2595 }
2596 }
2598 if (!initialized) capture_arbiter_failed(&job->shot, USHER_CAMERA_MASK_CHDK);
2599 if (!saved && !handed_off) {
2600 if (usher_running())
2601 fprintf(stderr, "USHER-%d: CHDK request failed; new CHDK attempts paused for %.3f s; other camera lanes remain independent\n",
2602 job->shot.data.nr, CHDK_RETRY_COOLDOWN_US / 1e6);
2603 queue_shot_result(job->request_id, job->shot.data.nr, USHER_CAMERA_CHDK, USHER_SHOT_FAILED);
2604 } else if (saved) {
2605 queue_shot_result(job->request_id, job->shot.data.nr, USHER_CAMERA_CHDK, USHER_SHOT_SAVED);
2606 }
2607 pthread_mutex_lock(&mut);
2608 if (saved || handed_off) chdk_retry_after_us = 0;
2611 pthread_cond_broadcast(&workers_finished);
2612 pthread_mutex_unlock(&mut);
2613 return NULL;
2614}
2615
2616/** @brief Resolve the currently advertised control capabilities.
2617 * @param camera_id Protocol camera ID.
2618 * @return Supported command bits, or zero when controls are unavailable.
2619 * @details Advertise physical lens operations only when the asynchronous
2620 * CHDK lane and its required hooks are available, never in mock capture modes. */
2622{
2624 || local_capture_only || mock_map_enabled) return 0;
2625 const struct camera_backend backend = camera_identity_get(camera_id);
2626 return backend.control && backend.control_init ? backend.control_capabilities : 0;
2627}
2628
2629/** @brief Stage a worker's result for serial transmission.
2630 * @param result Completion including its original request identity.
2631 * @details Update only a matching session and request slot so late work
2632 * cannot overwrite state from a renewed control session. */
2634{
2635 pthread_mutex_lock(&mut);
2636 if (result->request.session == control_session && result->camera_id >= 1 && result->camera_id <= 8) {
2637 const size_t index = result->camera_id - 1;
2638 if (control_results[index].result.request.request_id == result->request.request_id) {
2639 control_results[index].result = *result;
2640 control_results[index].dirty = true;
2641 }
2642 }
2643 pthread_mutex_unlock(&mut);
2645}
2646
2647/** @brief Pass dirty control receipts to the UART transmit queue.
2648 * @details Clear a slot's dirty flag only after successful queue admission;
2649 * preserve the cached receipt for duplicate requests. */
2650static void flush_control_results(void)
2651{
2652 pthread_mutex_lock(&mut);
2653 for (size_t index = 0; index < 8; ++index) {
2654 if (!control_results[index].dirty) continue;
2657 && serial_tx_send(USHER_CONTROL_RESULT, bytes, sizeof(bytes)) == 0) control_results[index].dirty = false;
2658 }
2659 pthread_mutex_unlock(&mut);
2660}
2661
2662/** @brief Execute an admitted lens command away from the serial owner.
2663 * @param pointer Address of the request in the reserved CHDK control slot.
2664 * @return NULL after releasing the CHDK lane.
2665 * @details Copy the job, execute under exclusive device ownership and report
2666 * observation evidence only for applied controls. An unsuccessful operation
2667 * sets a cooldown before another command or capture may use the lane. */
2668static void *handle_chdk_control(void *pointer)
2669{
2670 const struct usher_control_request request = *(const struct usher_control_request *)pointer;
2672 struct usher_control_result result = {.request = request, .camera_id = USHER_CAMERA_CHDK,
2673 .status = CAM_CONTROL_FAILED};
2674 if (usher_running()) {
2675 const struct camera_backend_host host = {.running = &keep_running};
2676 if (backend.configure) backend.configure(&host);
2677 if (backend.control_init && backend.control && backend.control_init() == 0)
2678 result.status = backend.control(request.command, request.value, &result.observed, &result.evidence);
2679 }
2680 if (backend.deinit) backend.deinit();
2683 pthread_mutex_lock(&mut);
2684 const uint64_t now = monotonic_time_us();
2685 chdk_retry_after_us = result.status == CAM_CONTROL_APPLIED ? 0 : now && now <= UINT64_MAX - CHDK_RETRY_COOLDOWN_US
2686 ? now + CHDK_RETRY_COOLDOWN_US : UINT64_MAX;
2688 pthread_cond_broadcast(&workers_finished);
2689 pthread_mutex_unlock(&mut);
2690 return NULL;
2691}
2692
2693/** @brief Admit a control into the exclusive CHDK lane under @c mut.
2694 * @param request Validated command to copy into the reserved slot.
2695 * @param now Current local monotonic time in microseconds.
2696 * @return False for busy, cooldown, or shutdown; true if handled, even if worker creation fails.
2697 * @details Claim the same lane used by CHDK capture. If spawn fails, release
2698 * the lane and stage a failure receipt rather than leaving a pending request. */
2699static bool admit_chdk_control_locked(const struct usher_control_request *request, uint64_t now)
2700{
2701 if (!usher_running() || chdk_capture_in_progress || now < chdk_retry_after_us) return false;
2704 pthread_attr_t attributes;
2705 int error = pthread_attr_init(&attributes);
2706 bool initialized = error == 0;
2707 if (!error) error = pthread_attr_setstacksize(&attributes, 256U * 1024U);
2708 if (!error) error = pthread_attr_setdetachstate(&attributes, PTHREAD_CREATE_DETACHED);
2709 pthread_t worker;
2710 if (!error) error = pthread_create(&worker, &attributes, handle_chdk_control, &chdk_control_job);
2711 if (initialized) pthread_attr_destroy(&attributes);
2712 if (error) {
2714 control_results[0].result.status = CAM_CONTROL_FAILED;
2715 control_results[0].dirty = true;
2716 pthread_cond_broadcast(&workers_finished);
2717 }
2718 return true;
2719}
2720
2721/** @brief Establish or renew a camera-control lease from the current UART message.
2722 * @details Pair a fresh session with the peer's nonce, report available
2723 * capabilities, and require a timely matching echo before accepting commands.
2724 * Replacing the session clears old receipt and ordering state. */
2726{
2727 const uint8_t *bytes = usher_protocol.payload;
2728 uint32_t nonce, requested_session;
2730 || !usher_control_get_u32(bytes, usher_protocol.payload_len, 1, &nonce) || !nonce
2731 || !usher_control_get_u32(bytes, usher_protocol.payload_len, 5, &requested_session)) return;
2732 const uint64_t now = monotonic_time_us();
2733 if (!now) return;
2734 pthread_mutex_lock(&mut);
2735 if (!requested_session) {
2736 uint32_t fresh = 0;
2737 ssize_t count = getrandom(&fresh, sizeof(fresh), GRND_NONBLOCK);
2738 if (count != (ssize_t)sizeof(fresh) || !fresh || fresh == control_session) {
2739 pthread_mutex_unlock(&mut);
2740 return;
2741 }
2742 control_session = fresh;
2743 control_confirmed = false;
2744 control_nonce = nonce;
2746 for (size_t index = 0; index < 8; ++index) {
2747 control_results[index].result = (struct usher_control_result){0};
2748 control_results[index].dirty = false;
2749 }
2750 }
2751 if (!control_session || nonce != control_nonce) { pthread_mutex_unlock(&mut); return; }
2752 if (requested_session == control_session && now - control_negotiated_us < USHER_CONTROL_LEASE_US)
2753 control_confirmed = true;
2754 else if (requested_session == control_session) { pthread_mutex_unlock(&mut); return; }
2755 if (!requested_session || requested_session == control_session) control_negotiated_us = now;
2757 usher_control_put_u32(hello, sizeof(hello), 1, nonce);
2758 usher_control_put_u32(hello, sizeof(hello), 5, control_session);
2759 for (uint8_t camera_id = 1; camera_id <= 8; ++camera_id)
2760 usher_control_put_u32(hello, sizeof(hello), 9 + 4 * (camera_id - 1), camera_control_capabilities(camera_id));
2761 serial_tx_send(USHER_CONTROL_HELLO, hello, sizeof(hello));
2762 pthread_mutex_unlock(&mut);
2763}
2764
2765/** @brief Process negotiation or dispatch an addressed control request.
2766 * @details Require an active confirmed lease. A request at or below the
2767 * session high-water mark cannot run again: report the matching cached
2768 * result when available, or report an unknown outcome. */
2769static void handle_control_message(void)
2770{
2773 if (!usher_control_decode_request(usher_protocol.payload, usher_protocol.payload_len, &request)) return;
2774 const uint64_t now = monotonic_time_us();
2775 pthread_mutex_lock(&mut);
2776 if (!usher_running() || !control_confirmed || !now || request.session != control_session
2777 || now - control_negotiated_us >= USHER_CONTROL_LEASE_US) { pthread_mutex_unlock(&mut); return; }
2778 const bool duplicate = request.request_id <= control_high_water;
2779 if (!duplicate) control_high_water = request.request_id;
2780 for (uint8_t camera_id = 1; camera_id <= 8; ++camera_id) {
2781 if (!(request.camera_mask & (1U << (camera_id - 1)))) continue;
2782 const size_t index = camera_id - 1;
2783 if (duplicate) {
2784 const struct usher_control_result *cached = &control_results[index].result;
2785 if (cached->request.request_id == request.request_id && cached->request.command == request.command
2786 && cached->request.value == request.value && cached->request.camera_mask == request.camera_mask) {
2787 if (cached->status != CAM_CONTROL_PENDING) control_results[index].dirty = true;
2788 } else {
2789 const struct usher_control_result unknown = {.request = request, .camera_id = camera_id,
2790 .status = CAM_CONTROL_UNKNOWN};
2793 }
2794 continue;
2795 }
2796 if (control_results[index].result.status == CAM_CONTROL_PENDING) {
2797 const struct usher_control_result busy = {.request = request, .camera_id = camera_id, .status = CAM_CONTROL_BUSY};
2800 continue;
2801 }
2802 control_results[index].result = (struct usher_control_result){.request = request, .camera_id = camera_id,
2803 .status = CAM_CONTROL_UNSUPPORTED};
2804 control_results[index].dirty = true;
2805 const uint32_t capabilities = camera_control_capabilities(camera_id);
2806 if (request.command >= 32 || !(capabilities & CAM_CONTROL_CAP(request.command))) continue;
2807 if (!usher_control_value_valid(request.command, request.value)) {
2808 control_results[index].result.status = CAM_CONTROL_INVALID_VALUE;
2809 continue;
2810 }
2812 if (control_results[index].result.status != CAM_CONTROL_FAILED) {
2813 control_results[index].result.status = CAM_CONTROL_PENDING;
2814 control_results[index].dirty = false;
2815 }
2816 } else control_results[index].result.status = CAM_CONTROL_BUSY;
2817 }
2818 pthread_mutex_unlock(&mut);
2819}
2820
2821/** @brief Schedule a shot on CHDK's independent capture lane.
2822 * @param shoot Trigger copied into the lane's single job slot.
2823 * @param request_id Correlation ID, or zero for an unacknowledged request.
2824 * @return True when the detached worker was started.
2825 * @details Share admission with lens control. Release survey admission and
2826 * report failure if shutdown, cooldown, contention, or thread setup prevents a shot. */
2827static bool start_chdk_worker(const union dc_shot_union *shoot, uint32_t request_id)
2828{
2829 pthread_mutex_lock(&mut);
2830 uint64_t now_us = monotonic_time_us();
2831 if (!usher_running() || chdk_capture_in_progress || !now_us || now_us < chdk_retry_after_us) {
2832 pthread_mutex_unlock(&mut);
2835 return false;
2836 }
2837 chdk_capture_job = (struct capture_job){.shot = *shoot, .request_id = request_id,
2838 .camera_mask = USHER_CAMERA_MASK_CHDK, .received_us = now_us};
2840 pthread_attr_t attributes;
2841 int result = pthread_attr_init(&attributes);
2842 bool attributes_ready = result == 0;
2843 if (!result) result = pthread_attr_setstacksize(&attributes, 256U * 1024U);
2844 if (!result) result = pthread_attr_setdetachstate(&attributes, PTHREAD_CREATE_DETACHED);
2845 pthread_t worker;
2846 if (!result) result = pthread_create(&worker, &attributes, handle_chdk_shoot, &chdk_capture_job);
2847 if (attributes_ready) pthread_attr_destroy(&attributes);
2848 if (result) {
2850 pthread_cond_broadcast(&workers_finished);
2851 }
2852 pthread_mutex_unlock(&mut);
2853 if (result) {
2854 fprintf(stderr, "USHER: unable to start CHDK worker: %s; other cameras remain active\n", strerror(result));
2857 }
2858 return result == 0;
2859}
2860
2861/** @brief Dispatch admitted image bits while preserving bounded legacy/local policies.
2862 * @param shoot Request to copy; the caller need not retain its storage.
2863 * @param camera_mask Selected image cameras; live CHDK and LWIR have independent lanes.
2864 * @param request_id Per-request reply identity, distinct from the photo number.
2865 * @details Survey jobs retain their ledger ownership; local/test jobs stay FIFO. */
2866static void start_shoot_worker(const union dc_shot_union *shoot, uint8_t camera_mask, uint32_t request_id)
2867{
2868 pthread_mutex_lock(&mut);
2870 pthread_mutex_unlock(&mut);
2872 bool chdk_admitted = false;
2874 if (camera_mask & USHER_CAMERA_MASK_CHDK) chdk_admitted = start_chdk_worker(shoot, request_id);
2875 camera_mask &= ~USHER_CAMERA_MASK_CHDK;
2876 }
2877 if (chdk_admitted) {
2878 pthread_mutex_lock(&mut);
2880 pthread_mutex_unlock(&mut);
2881 }
2882 if (live_capture) {
2883 if ((camera_mask & USHER_CAMERA_MASK_LWIR) != 0) start_lwir_worker(shoot, request_id, monotonic_time_us());
2884 camera_mask &= ~USHER_CAMERA_MASK_LWIR;
2885 }
2887 if (chdk_admitted) send_msg_status();
2888 return;
2889 }
2890 pthread_mutex_lock(&mut);
2891 if (!usher_running()) {
2892 pthread_mutex_unlock(&mut);
2893 capture_arbiter_failed(shoot, camera_mask);
2895 return;
2896 }
2897 if (live_capture && waiting_capture != NULL && !waiting_capture->arbiter_owned) {
2898 /* Replace the whole request, not just its number: old pose with a new image
2899 * would be harder to detect than an explicitly superseded trigger. */
2900 const union dc_shot_union replaced = waiting_capture->shot;
2901 const uint32_t replaced_id = waiting_capture->request_id;
2902 const uint8_t replaced_mask = waiting_capture->camera_mask;
2903 waiting_capture->shot = *shoot;
2904 waiting_capture->request_id = request_id;
2905 waiting_capture->camera_mask = camera_mask;
2906 waiting_capture->received_us = monotonic_time_us();
2907 waiting_capture->shot_counted = chdk_admitted;
2909 pthread_mutex_unlock(&mut);
2910 queue_image_results(replaced_id, replaced.data.nr, replaced_mask, USHER_SHOT_SUPERSEDED);
2911 return;
2912 }
2914 pthread_mutex_unlock(&mut);
2915 fprintf(stderr, "USHER-%d:\tprocessing queue is full\n", shoot->data.nr);
2916 capture_arbiter_failed(shoot, camera_mask);
2918 return;
2919 }
2921 if (job == NULL) {
2922 pthread_mutex_unlock(&mut);
2923 fprintf(stderr, "USHER-%d:\tcapture job pool is full\n", shoot->data.nr);
2926 return;
2927 }
2928 job->shot = *shoot;
2929 job->request_id = request_id;
2930 job->camera_mask = camera_mask;
2931 job->received_us = monotonic_time_us();
2932 job->arbiter_owned = capture_arbiter_owns(shoot->data.nr);
2933 job->shot_counted = chdk_admitted;
2935 job->ticket = next_job_ticket;
2936
2937 pthread_t shooting_thread;
2938 int thread_result = pthread_create(&shooting_thread, NULL, handle_msg_shoot, job);
2939 if (thread_result != 0) {
2941 pthread_mutex_unlock(&mut);
2942 fprintf(stderr, "USHER-%d:\tfailed to start shooting thread: %s\n",
2943 shoot->data.nr, strerror(thread_result));
2947 return;
2948 }
2950 if (live_capture) waiting_capture = job;
2951 pthread_mutex_unlock(&mut);
2952 pthread_detach(shooting_thread);
2954}
2955
2956/** @brief Release per-camera survey admission on a failure before normal completion.
2957 * @param shoot Original request identifying active entries.
2958 * @param mask Only the camera bits that failed; other sensors may still succeed.
2959 */
2960static void capture_arbiter_failed(const union dc_shot_union *shoot, uint8_t mask)
2961{
2962 for (unsigned camera_id = 1; camera_id <= COVERAGE_CAMERAS; ++camera_id)
2963 if (mask & (1U << (camera_id - 1))) capture_arbiter_complete(shoot, camera_id, false, false, 0, monotonic_time_us());
2964}
2965
2966/** @brief Reserve a zeroed slot in the bounded job pool.
2967 * @return Slot owned by the caller, or NULL if the pool is full.
2968 * @details The caller holds @c mut. A static pool makes overload explicit
2969 * rather than allocating more jobs as capture latency grows. */
2971{
2972 for (size_t index = 0; index < CAPTURE_JOB_CAPACITY; ++index) {
2973 if (capture_job_used[index]) continue;
2974 capture_job_used[index] = true;
2975 capture_jobs[index] = (struct capture_job) {0};
2976 return &capture_jobs[index];
2977 }
2978 return NULL;
2979}
2980
2981/** @brief Return a job slot while the caller owns the pool mutex.
2982 * @param job Previously reserved slot; non-pool pointers are ignored.
2983 * @details Clear the job before marking the slot available so the next
2984 * owner cannot inherit request or camera state. */
2986{
2987 for (size_t index = 0; index < CAPTURE_JOB_CAPACITY; ++index) {
2988 if (job != &capture_jobs[index]) continue;
2989 capture_jobs[index] = (struct capture_job) {0};
2990 capture_job_used[index] = false;
2991 return;
2992 }
2993}
2994
2995/** @brief Return a job slot from a worker that does not hold the pool lock.
2996 * @param job Previously reserved slot, no longer in use by the caller.
2997 * @details Take @c mut around pool bookkeeping; callers already holding
2998 * it must use capture_job_release_locked() instead. */
3000{
3001 pthread_mutex_lock(&mut);
3003 pthread_mutex_unlock(&mut);
3004}
3005
3006/** @brief Bridge survey decisions to current backend readiness from the serial event loop.
3007 * @param now_us Current MORA monotonic time in microseconds.
3008 * @details Readiness is a snapshot, not a reservation. Dispatch still checks driver
3009 * admission. Retain one popped result across a full UART TX queue rather than
3010 * discarding it merely because the wire was briefly busy.
3011 */
3012static void service_capture_arbiter(uint64_t now_us)
3013{
3014 const uint32_t session = capture_arbiter_session_id();
3015 if (!session) return;
3016 static uint64_t hello_us;
3017 if (!hello_us || now_us < hello_us || now_us - hello_us >= 500000) {
3019 if (serial_tx_send(USHER_CAPTURE_ARBITER_HELLO, hello.bin, sizeof(hello.bin)) == 0) hello_us = now_us;
3020 }
3021 pthread_mutex_lock(&mut);
3027 }
3029 pthread_mutex_unlock(&mut);
3030 for (unsigned camera_id = 1; camera_id <= COVERAGE_CAMERAS; ++camera_id) {
3032 const struct camera_capture_ops *ops = test_capture_enabled ? NULL : backend.capture_ops;
3033 /* Live CHDK publishes one image while the next is captured. */
3034 const bool chdk_pipelined = camera_id == USHER_CAMERA_CHDK && chdk_async_capture_enabled
3036 const unsigned limit = ops ? ops->max_in_flight : chdk_pipelined ? 2 : 1;
3037 if (!capture_arbiter_set_camera_capacity(camera_id, limit)
3038 || (ops && ops->has_capacity && !ops->has_capacity())) ready &= ~(1U << (camera_id - 1));
3039 }
3041 static bool result_pending;
3042 if (!result_pending) result_pending = capture_arbiter_result(&result, ready);
3043 if (result_pending
3044 && serial_tx_send(USHER_CAPTURE_ARBITER_RESULT, result.bin, sizeof(result.bin)) == 0) result_pending = false;
3045 union dc_shot_union shot;
3046 uint8_t mask;
3047 if (usher_running() && capture_arbiter_take(ready, now_us, &shot, &mask)) start_shoot_worker(&shot, mask, 0);
3049}
3050
3051/** @brief Collect stream updates and completed point-session results.
3052 * @details Bound the work per backend to preserve UART service latency.
3053 * Stream updates and stopped-session results use separate caches; reject
3054 * session completions not matching the current stopped session. */
3056{
3058 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
3059 const struct camera_point_stream_ops *stream = camera_owners[camera_id].point_stream;
3060 if (stream && stream->poll_result
3062 || camera_stream_states[camera_id] == CAMERA_STREAM_DRAINED)) {
3063 struct camera_point_result update;
3064 unsigned received = 0;
3065 for (; received < MAX_BACKEND_RESULTS_PER_PASS && stream->poll_result(&update); ++received)
3066 send_msg_cam_point_update(camera_id, &update);
3068 }
3069 const struct camera_session_ops *ops = camera_owners[camera_id].session;
3070 if (!ops || !ops->poll_result) continue;
3072 unsigned received = 0;
3073 for (; received < MAX_BACKEND_RESULTS_PER_PASS && ops->poll_result(&point); ++received) {
3074 if (point.session_id && point_sessions[camera_id - 1].id == point.session_id
3075 && point_sessions[camera_id - 1].stop_requested
3076 && point_sessions[camera_id - 1].result.data.session_id != point.session_id)
3077 send_msg_cam_point(camera_id, point.session_id, &point);
3078 }
3080 }
3081}
3082
3083/** @brief Ask active streams and sessions to drain, then service remaining results.
3084 * @details Mark streams drained before invoking callbacks. The service pass
3085 * still permits already-available results from drained streams. */
3086static void drain_camera_backends(void)
3087{
3088 for (unsigned camera_id = 1; camera_id <= CAMERA_BACKEND_MAX_ID; ++camera_id) {
3089 const struct camera_point_stream_ops *stream = camera_owners[camera_id].point_stream;
3090 if (stream && camera_stream_states[camera_id] == CAMERA_STREAM_ACTIVE) {
3092 if (stream->drain) stream->drain();
3093 }
3094 const struct camera_session_ops *ops = camera_owners[camera_id].session;
3095 if (ops && ops->drain) ops->drain();
3096 }
3098}
3099
3100/** @brief Start a point session for the addressed backend or backends.
3101 * @param camera_id Camera ID, or USHER_CAMERA_ALL for broadcast.
3102 * @param session_id Nonzero session identifier from the caller.
3103 * @details Treat a duplicate START as idempotent and clear old result state
3104 * only for a new ID. Prefer the configured point stream when present. */
3105static void handle_targeted_start(uint32_t camera_id, uint32_t session_id)
3106{
3107 if (camera_id > CAMERA_BACKEND_MAX_ID || !session_id) return;
3109 printf("USHER:\tSTART cam %u session %u\n", camera_id, session_id);
3110 for (size_t slot = 0; slot < CAMERA_BACKEND_MAX_ID; ++slot) {
3111 if (camera_id != USHER_CAMERA_ALL && slot != camera_id - 1) continue;
3112 if (point_sessions[slot].id == session_id) continue;
3113 point_sessions[slot].id = session_id;
3114 point_sessions[slot].result = (union usher_cam_point_result_union) {0};
3115 point_sessions[slot].pending = false;
3116 point_sessions[slot].stop_requested = false;
3117 if (!camera_owners[slot + 1].point_stream) {
3118 const struct camera_backend backend = camera_backend_get(camera_type_for_id(slot + 1));
3119 if (backend.point_stream) camera_register_stream(&backend);
3120 }
3121 const struct camera_point_stream_ops *stream = camera_owners[slot + 1].point_stream;
3122 if (stream) {
3123 if (camera_stream_states[slot + 1] == CAMERA_STREAM_ACTIVE && stream->start
3124 && (!stream->enabled || stream->enabled()) && !stream->start(session_id))
3125 fprintf(stderr, "USHER:\tphoto point stream not enabled\n");
3126 continue;
3127 }
3128 if (prepare_session_backend(slot + 1) && !camera_owners[slot + 1].session->start(session_id))
3129 fprintf(stderr, "USHER:\t%s session %u unavailable/full; stopped evidence retained\n",
3130 camera_owners[slot + 1].name, session_id);
3131 }
3132}
3133
3134/** @brief Request the stop phase for a matching point session.
3135 * @param camera_id Camera ID, or USHER_CAMERA_ALL for broadcast.
3136 * @param session_id Nonzero session identifier.
3137 * @details Ignore a stale session. For a repeated STOP, resend a cached
3138 * result when available instead of rerunning the stop transition. */
3139static void handle_targeted_stop(uint32_t camera_id, uint32_t session_id)
3140{
3141 if (camera_id > CAMERA_BACKEND_MAX_ID || !session_id) return;
3142 if (camera_id == USHER_CAMERA_ALL) {
3143 for (uint32_t selected = 1; selected <= CAMERA_BACKEND_MAX_ID; ++selected) handle_targeted_stop(selected, session_id);
3144 return;
3145 }
3146 const size_t slot = camera_id - 1;
3147 if (point_sessions[slot].id != session_id) return;
3148 if (point_sessions[slot].result.data.session_id == session_id) {
3149 point_sessions[slot].pending = true;
3151 return;
3152 }
3153 if (point_sessions[slot].stop_requested) return;
3154 point_sessions[slot].stop_requested = true;
3155 printf("USHER:\tSTOP cam %u session %u\n", camera_id, session_id);
3156 const struct camera_point_stream_ops *stream = camera_owners[camera_id].point_stream;
3157 if (stream) {
3158 if (camera_stream_states[camera_id] == CAMERA_STREAM_ACTIVE && stream->stop
3159 && (!stream->enabled || stream->enabled()) && !stream->stop(session_id))
3160 fprintf(stderr, "USHER:\tphoto point return phase unavailable\n");
3161 return;
3162 }
3163 const struct camera_session_ops *ops = camera_owners[camera_id].session;
3164 if (!ops || !ops->stop || !ops->stop(session_id)) send_msg_cam_point(camera_id, session_id, NULL);
3165}
3166
3167/** @brief Check whether a backend result is suitable for the point wire format.
3168 * @param point Nullable candidate point.
3169 * @return True when marked valid and within the coordinate, height, and quality bounds.
3170 * @details Reject the all-zero geographic placeholder; passing this check
3171 * does not establish survey accuracy. */
3173{
3174 return point && point->valid && point->lat >= -900000000 && point->lat <= 900000000
3175 && point->lon >= -1800000000 && point->lon <= 1800000000
3176 && (point->lat != 0 || point->lon != 0) && point->agl_mm >= 0
3177 && point->quality >= 0 && point->quality <= 1000;
3178}
3179
3180/** @brief Cache and attempt to queue a terminal point-session result.
3181 * @param camera_id Concrete backend ID.
3182 * @param session_id Nonzero identifier for the session being completed.
3183 * @param point Backend result, or NULL for no valid point.
3184 * @details Keep the result after successful transmission so a repeated STOP
3185 * can recover it. Invalid points carry status but no coordinates. */
3186static void send_msg_cam_point(uint32_t camera_id, uint32_t session_id, const struct camera_point_result *point)
3187{
3188 if (camera_id < 1 || camera_id > CAMERA_BACKEND_MAX_ID || !session_id) return;
3190 memset(&result, 0, sizeof(result));
3191 result.data.camera_id = camera_id;
3192 result.data.session_id = session_id;
3193 const bool valid = camera_point_valid(point);
3195 if (point && valid) {
3196 result.data.lat = point->lat;
3197 result.data.lon = point->lon;
3198 result.data.agl_mm = point->agl_mm;
3199 result.data.alt_mm = point->alt_mm;
3200 result.data.metric = point->metric;
3201 result.data.quality = point->quality;
3202 }
3203
3204 point_sessions[camera_id - 1].result = result;
3205 point_sessions[camera_id - 1].pending = true;
3207}
3208
3209/** @brief Keep only the newest stream result per camera across UART backpressure. */
3211{
3212 if (!point || !point->session_id || camera_id < 1 || camera_id > CAMERA_BACKEND_MAX_ID) return;
3213 union usher_cam_point_update_union update = {.data = {
3214 .camera_id = camera_id, .frame_number = point->session_id,
3216 }
3217 };
3218 if (update.data.status == USHER_CAM_POINT_VALID) {
3219 update.data.lat = point->lat; update.data.lon = point->lon;
3220 update.data.alt_mm = point->alt_mm; update.data.agl_mm = point->agl_mm;
3221 update.data.quality = point->quality; update.data.metric = point->metric;
3222 }
3223 point_updates[camera_id - 1] = update;
3224 point_update_pending[camera_id - 1] = true;
3225}
3226
3227/** @brief Publish fresh stream mailboxes without changing stopped-session result caches. */
3229{
3230 for (size_t slot = 0; slot < CAMERA_BACKEND_MAX_ID; ++slot) {
3231 if (!point_update_pending[slot]) continue;
3232 if (serial_tx_send(USHER_CAM_POINT_UPDATE, point_updates[slot].bin, sizeof(point_updates[slot].bin)) != 0) return;
3233 point_update_pending[slot] = false;
3234 }
3235}
3236
3237/** @brief Submit unsent point-session results to the UART transmit queue.
3238 * @details Clear only the pending flag on success. A full transmit queue
3239 * leaves the receipt pending for the next event-loop pass. */
3240static void flush_cam_points(void)
3241{
3242 for (size_t slot = 0; slot < CAMERA_BACKEND_MAX_ID; ++slot) {
3243 if (!point_sessions[slot].pending) continue;
3244 const union usher_cam_point_result_union *result = &point_sessions[slot].result;
3245 if (serial_tx_send(USHER_CAM_POINT_RESULT, result->bin, sizeof(result->bin)) != 0) return;
3246 point_sessions[slot].pending = false;
3247 }
3248}
3249
3250/** @brief Launch optional mapping as a separate process with no inherited UART descriptors.
3251 * @details A map worker consumes saved originals, not capture slots. Failure to
3252 * start it is reported but never grounds the photo pipeline.
3253 */
3254static void start_pangea(void)
3255{
3256 char executable[PATH_MAX], photos[PATH_MAX], map_dir[PATH_MAX], pause_path[PATH_MAX], parent[32], since[32];
3257 ssize_t length = readlink("/proc/self/exe", executable, sizeof(executable) - 1);
3258 if (length <= 0 || (size_t)length >= sizeof(executable) - 1) {
3259 fprintf(stderr, "USHER:\tPANGEA path unavailable; capture continues\n");
3260 return;
3261 }
3262 executable[length] = '\0';
3263 char *base = strrchr(executable, '/');
3264 if (base == NULL || (size_t)(base - executable) + sizeof("/bin/pangea") > sizeof(executable)) return;
3265 snprintf(base, sizeof(executable) - (size_t)(base - executable), "/bin/pangea");
3266 const char *photo_root = USHER_LOCAL_PHOTO_DIR;
3267 if (pangea_camera_profile != NULL) {
3268 if (!camera.photo_directory) return;
3269 photo_root = camera.photo_directory;
3270 }
3271 const char *photo_directory = usher_resolve_path(photo_root, photos, sizeof(photos));
3272 const char *output_directory = usher_resolve_path(pangea_directory, map_dir, sizeof(map_dir));
3273 if (photo_directory == NULL || output_directory == NULL || output_directory[0] == '\0') return;
3274 snprintf(parent, sizeof(parent), "%ld", (long)getpid());
3275 snprintf(since, sizeof(since), "%lld", (long long)time(NULL));
3276 char *arguments[15] = {executable, "--input", (char *)photo_directory, "--output", (char *)output_directory,
3277 "--watch", "--parent-pid", parent, "--since", since
3278 };
3279 size_t argument_count = 10;
3280 if (pangea_camera_profile != NULL) {
3281 arguments[argument_count++] = "--camera-profile";
3282 arguments[argument_count++] = (char *)pangea_camera_profile;
3283 }
3284 if (pangea_pause_file != NULL) {
3285 const char *resolved_pause = usher_resolve_path(pangea_pause_file, pause_path, sizeof(pause_path));
3286 if (resolved_pause == NULL || resolved_pause[0] == '\0') return;
3287 arguments[argument_count++] = "--pause-file";
3288 arguments[argument_count++] = (char *)resolved_pause;
3289 }
3290 arguments[argument_count] = NULL;
3291 int result = posix_spawn(&pangea_pid, executable, NULL, NULL, arguments, environ);
3292 if (result != 0) {
3293 pangea_pid = -1;
3294 fprintf(stderr, "USHER:\tPANGEA unavailable: %s; capture continues\n", strerror(result));
3295 } else {
3296 printf("USHER:\tPANGEA background watcher pid %ld, map directory %s\n", (long)pangea_pid, output_directory);
3297 }
3298}
3299
3300/** @brief Poll an owned subprocess for exit.
3301 * @param[in,out] child Positive child PID, reset to -1 when ownership ends.
3302 * @param timeout_ms Polling budget in milliseconds.
3303 * @return True if reaped or no longer a child; false on deadline or wait error.
3304 * @details Retain the PID on failure so later cleanup still knows which
3305 * child it owns. */
3306static bool wait_owned_child(pid_t *child, unsigned timeout_ms)
3307{
3308 const uint64_t started_us = monotonic_time_us();
3309 for (;;) {
3310 int status = 0;
3311 const pid_t result = waitpid(*child, &status, WNOHANG);
3312 if (result == *child || (result < 0 && errno == ECHILD)) { *child = -1; return true; }
3313 if (result < 0 && errno != EINTR) return false;
3314 const uint64_t now_us = monotonic_time_us();
3315 if (!started_us || !now_us || now_us < started_us
3316 || now_us - started_us >= (uint64_t)timeout_ms * 1000) return false;
3317 if (poll(NULL, 0, 10) < 0 && errno != EINTR) return false;
3318 }
3319}
3320
3321/** @brief Bound optional map-worker shutdown rather than waiting for its input backlog. */
3322static void stop_pangea(void)
3323{
3324 if (pangea_pid <= 0 || wait_owned_child(&pangea_pid, 0)) return;
3325 kill(pangea_pid, SIGTERM);
3326 if (wait_owned_child(&pangea_pid, 100)) return;
3327 kill(pangea_pid, SIGKILL);
3328 if (!wait_owned_child(&pangea_pid, 1500))
3329 fprintf(stderr, "USHER:\tPANGEA has not exited after SIGKILL; retaining child ownership\n");
3330}
3331
3332/** @brief Run saved-file analysis with fresh priority and idle catch-up.
3333 * @param unused Unused pthread argument.
3334 * @return NULL when stopped; pending filenames remain on disk, not in a durable job queue.
3335 * @details One lower-priority worker limits concurrent decoding. It never owns a
3336 * camera slot. An already running analysis is not preempted when a trigger arrives.
3337 */
3338static void *handle_soda_backlog(void *unused)
3339{
3340 (void)unused;
3341 if (setpriority(PRIO_PROCESS, 0, 10) != 0) {
3342 fprintf(stderr, "USHER:\tcannot lower SODA backlog priority: %s\n", strerror(errno));
3343 }
3344 for (;;) {
3345 pthread_mutex_lock(&mut);
3346 while (soda_backlog_count == 0 && !soda_backlog_stop && usher_running()) {
3347 pthread_cond_wait(&soda_available, &mut);
3348 }
3349 if (soda_backlog_stop || !usher_running()) {
3350 pthread_mutex_unlock(&mut);
3351 return NULL;
3352 }
3353 uint64_t now_us = monotonic_time_us();
3355 bool fresh = soda_backlog[selected].attempts == 0 && now_us != 0
3356 && now_us >= soda_backlog[selected].queued_us
3357 && now_us - soda_backlog[selected].queued_us < (uint64_t)USHER_SODA_IDLE_MS * 1000;
3358 bool quiet = now_us != 0 && now_us >= last_photo_request_us
3359 && now_us - last_photo_request_us >= (uint64_t)USHER_SODA_IDLE_MS * 1000;
3360 if (!fresh && quiet) {
3361 /* A retry in cooldown must not block other ready originals. Rotate at
3362 * most the current queue length, preserving bounded work even if all wait. */
3363 for (size_t scanned = 0; scanned < soda_backlog_count; ++scanned) {
3364 if (soda_backlog[soda_backlog_head].retry_after_us <= now_us) break;
3368 }
3369 selected = soda_backlog_head;
3370 }
3371 if ((!fresh && (!quiet || shooting_thread_count != 0 || lwir_capture_in_progress))
3372 || soda_backlog[selected].retry_after_us > now_us
3373 || pthread_mutex_trylock(&live_soda_mutex) != 0) {
3374 pthread_mutex_unlock(&mut);
3375 poll(NULL, 0, 50);
3376 continue;
3377 }
3378 struct soda_job job = soda_backlog[selected];
3381 soda_backlog_active = true;
3382 pthread_mutex_unlock(&mut);
3383
3384 /* Stat identity catches ordinary replacement between enqueue and replay.
3385 * Do not apply old pose to a new file with a familiar name; this is not a
3386 * security boundary against concurrent hostile file modification. */
3387 struct stat source;
3388 bool same_source = lstat(job.filename, &source) == 0 && S_ISREG(source.st_mode)
3389 && source.st_dev == job.source.st_dev && source.st_ino == job.source.st_ino
3390 && source.st_size == job.source.st_size
3391 && source.st_mtim.tv_sec == job.source.st_mtim.tv_sec
3392 && source.st_mtim.tv_nsec == job.source.st_mtim.tv_nsec;
3393 uint64_t analysis_started_us = monotonic_time_us();
3394 if (same_source && !job.spotting_done && job.camera_id == USHER_CAMERA_LWIRCAM && lwir_spotter_enabled()) {
3395 const int spotting = lwir_spotter_analyze(job.filename, &job.shot, &job.timing, &keep_running);
3396 job.spotting_done = true;
3397 fprintf(stderr, "USHER-%d:\tLWIR spotting %s; original and capture timing retained\n",
3398 job.shot.data.nr, spotting == 0 ? "complete" : "failed");
3399 same_source = lstat(job.filename, &source) == 0 && S_ISREG(source.st_mode)
3400 && source.st_dev == job.source.st_dev && source.st_ino == job.source.st_ino
3401 && source.st_size == job.source.st_size && source.st_mtim.tv_sec == job.source.st_mtim.tv_sec
3402 && source.st_mtim.tv_nsec == job.source.st_mtim.tv_nsec;
3403 }
3404 int result = same_source ? run_soda(job.filename, &job.shot, job.camera_id) : -1;
3405 if (debug_enabled) {
3406 printf("USHER-%d TIMING:\tcamera=%d soda_ms=%.3f mode=%s result=%d\n",
3407 job.shot.data.nr, job.camera_id,
3408 (monotonic_time_us() - analysis_started_us) / 1000.0,
3409 fresh ? "fresh" : "idle", result);
3410 }
3411 if (!same_source) {
3412 fprintf(stderr, "USHER-%d:\tSODA backlog source missing/changed; old pose not applied: %s\n",
3413 job.shot.data.nr, job.filename);
3414 }
3415 pthread_mutex_unlock(&live_soda_mutex);
3416 pthread_mutex_lock(&mut);
3417 /* One retry allows transient output failures without a poisoned image
3418 * monopolizing the worker. Partial CSV/crop side effects are not exactly-once. */
3419 if (result != 0 && same_source && ++job.attempts < 2 && usher_running()
3421 job.retry_after_us = monotonic_time_us() + (uint64_t)USHER_SODA_RETRY_MS * 1000;
3423 soda_backlog[tail] = job;
3425 } else if (result == 0) ++soda_backlog_completed;
3426 else ++soda_backlog_failed;
3427 soda_backlog_active = false;
3428 size_t pending = soda_backlog_count;
3429 pthread_cond_broadcast(&workers_finished);
3430 pthread_mutex_unlock(&mut);
3431 printf("USHER-%d:\tSODA backlog mode=%s result=%d pending=%zu, original retained: %s\n",
3432 job.shot.data.nr, fresh ? "fresh" : "idle", result, pending, job.filename);
3433 }
3434}
3435
3436/** @brief Queue analysis of a saved original without retaining camera or pixel buffers.
3437 * @param filename Nonempty regular image file, unchanged while queued.
3438 * @param shoot Pose/number associated with that saved image, copied into the job.
3439 * @param camera_id Sensor-specific SODA route.
3440 * @details Overflow keeps existing queued work and leaves the new original on disk.
3441 * Worker-creation failure retains the job so a later submission can retry startup.
3442 */
3443static void defer_soda(const char *filename, const union dc_shot_union *shoot, int camera_id)
3444{
3445 defer_saved_analysis(filename, shoot, camera_id, NULL);
3446}
3447
3448/** @brief Submit a published image to the bounded saved-analysis backlog.
3449 * @param filename Path of the nonempty original JPEG.
3450 * @param shoot Trigger evidence copied into the job.
3451 * @param camera_id Camera identity used to route the analysis.
3452 * @param timing Optional capture timing copied into the job.
3453 * @details Save file identity with the job so the worker can detect a
3454 * later replacement. If the backlog is unavailable, preserve the original
3455 * for offline processing rather than blocking capture. */
3456static void defer_saved_analysis(const char *filename, const union dc_shot_union *shoot, int camera_id,
3457 const struct capture_timing *timing)
3458{
3459 if (!filename || !filename[0] || !shoot) return;
3460 const struct camera_backend backend = camera_identity_get(camera_id);
3461 if (!backend.name || !backend.soda_application || !backend.soda_option) return;
3462 size_t length = strnlen(filename, MAX_FILENAME);
3463 struct stat source;
3464 bool source_valid = lstat(filename, &source) == 0 && S_ISREG(source.st_mode) && source.st_size > 0;
3465 pthread_mutex_lock(&mut);
3466 if (soda_backlog_stop || !usher_running() || !source_valid || length >= MAX_FILENAME
3469 pthread_mutex_unlock(&mut);
3470 fprintf(stderr,
3471 "USHER-%d:\tSODA backlog unavailable/full; original and flight EXIF retained for offline analysis: %s\n",
3472 shoot->data.nr, filename);
3473 return;
3474 }
3476 struct soda_job *job = &soda_backlog[tail];
3477 for (size_t index = 0; index <= length; ++index) job->filename[index] = filename[index];
3478 job->shot = *shoot;
3479 job->timing = timing ? *timing : (struct capture_timing) {0};
3480 job->spotting_done = false;
3481 job->camera_id = camera_id;
3482 job->source = source;
3483 job->queued_us = monotonic_time_us();
3484 job->retry_after_us = 0;
3485 job->attempts = 0;
3486 bool busy = soda_backlog_active || soda_backlog_count != 0;
3487 if (busy) ++soda_busy_deferred_count;
3488 size_t pending = ++soda_backlog_count;
3489 if (!soda_backlog_started) {
3490 int result = pthread_create(&soda_backlog_thread, NULL, handle_soda_backlog, NULL);
3492 if (result != 0) {
3493 fprintf(stderr, "USHER:\tSODA backlog worker unavailable: %s; photos continue\n", strerror(result));
3494 }
3495 }
3496 pthread_cond_signal(&soda_available);
3497 pthread_mutex_unlock(&mut);
3498 printf("USHER-%d:\tSODA %s pending=%zu: %s\n",
3499 shoot->data.nr, busy ? "deferred" : "submitted", pending, filename);
3500}
3501
3502/** @brief Join the analysis worker without draining session-only pending jobs.
3503 * @pre Set keep_running to zero first so an active run_soda() follows its shutdown deadline.
3504 * @details Joining ensures analysis no longer touches state that camera cleanup
3505 * may release. Originals survive; pending analysis is not automatically persisted.
3506 */
3507static void stop_soda_backlog(void)
3508{
3509 pthread_mutex_lock(&mut);
3510 soda_backlog_stop = true;
3511 pthread_cond_broadcast(&soda_available);
3512 pthread_mutex_unlock(&mut);
3513 if (soda_backlog_started) pthread_join(soda_backlog_thread, NULL);
3514 pthread_mutex_lock(&mut);
3515 soda_backlog_started = false;
3516 fprintf(stderr, "USHER SODA:\tcompleted=%" PRIu64 " failed=%" PRIu64
3517 " pending=%zu unavailable/full=%" PRIu64 "; original photos retained\n",
3519 pthread_mutex_unlock(&mut);
3520}
3521
3522/** @brief Run one analysis child directly with bounded runtime and termination grace.
3523 * @param filename Saved original to analyze, never deleted by this function.
3524 * @param shoot Immutable image-associated pose used to form arguments.
3525 * @param camera_id Sensor route selecting the SODA option.
3526 * @return Child exit status, or -1 for spawn/wait/cancellation/deadline failure.
3527 * @note Direct argv avoids shell interpretation. Successful exit means processing
3528 * completed, not that an object was detected or that each side effect is unique.
3529 */
3530static int run_soda(const char *filename, const union dc_shot_union *shoot, int camera_id)
3531{
3532 if (!filename || !filename[0] || !shoot) return -1;
3533 const struct camera_backend backend = camera_identity_get(camera_id);
3534 if (!backend.name) {
3535 fprintf(stderr, "USHER:\tinvalid SODA camera id %d\n", camera_id);
3536 return -1;
3537 }
3538 const char *soda_application = test_capture_enabled || local_capture_only ? USHER_SODA : backend.soda_application;
3539 const char *camera_option = backend.soda_option;
3540 if (!soda_application || !soda_application[0] || !camera_option) return -1;
3541 char values[10][16];
3542 const int32_t fields[10] = {
3543 shoot->data.nr, shoot->data.lat, shoot->data.lon, shoot->data.alt,
3544 shoot->data.phi, shoot->data.theta, shoot->data.psi, shoot->data.vground,
3545 shoot->data.course, shoot->data.groundalt
3546 };
3547 for (size_t index = 0; index < 10; index++) {
3548 int length = snprintf(values[index], sizeof(values[index]), "%d", fields[index]);
3549 if (length < 0 || (size_t)length >= sizeof(values[index])) {
3550 return -1;
3551 }
3552 }
3553
3554 char *arguments[19] = {
3555 (char *)soda_application, (char *)filename,
3556 values[0], values[1], values[2], values[3], values[4],
3557 values[5], values[6], values[7], values[8], values[9], NULL, NULL, NULL
3558 };
3559 size_t argument_count = 12;
3560 if (camera_option != NULL) arguments[argument_count++] = (char *)camera_option;
3561 if (local_mode) arguments[argument_count++] = (char *)"--local";
3562 arguments[argument_count] = NULL;
3563 if (debug_enabled) {
3564 printf("USHER-%d DEBUG:\tstarting SODA directly: %s\n",
3565 shoot->data.nr, soda_application);
3566 }
3567
3568 pid_t soda_pid;
3569 posix_spawnattr_t attributes;
3570 int spawn_result = posix_spawnattr_init(&attributes);
3571 if (spawn_result) return -1;
3572 sigset_t mask, defaults;
3573 sigemptyset(&mask);
3574 sigemptyset(&defaults);
3575 sigaddset(&defaults, SIGINT);
3576 sigaddset(&defaults, SIGTERM);
3577 spawn_result = posix_spawnattr_setsigmask(&attributes, &mask);
3578 if (!spawn_result) spawn_result = posix_spawnattr_setsigdefault(&attributes, &defaults);
3579 if (!spawn_result) spawn_result = posix_spawnattr_setpgroup(&attributes, 0);
3580 if (!spawn_result) spawn_result = posix_spawnattr_setflags(&attributes,
3581 POSIX_SPAWN_SETSIGMASK | POSIX_SPAWN_SETSIGDEF | POSIX_SPAWN_SETPGROUP);
3582 if (!spawn_result) spawn_result = posix_spawnp(&soda_pid, soda_application, NULL, &attributes,
3583 arguments, environ);
3584 posix_spawnattr_destroy(&attributes);
3585 if (spawn_result != 0) {
3586 fprintf(stderr, "USHER-%d:\tfailed to start SODA: %s\n",
3587 shoot->data.nr, strerror(spawn_result));
3588 return -1;
3589 }
3590
3591 int status = 0;
3592 const uint64_t started_us = monotonic_time_us();
3593 uint64_t termination_us = 0;
3594 bool terminating = false;
3595 for (;;) {
3596 pid_t wait_result = waitpid(soda_pid, &status, WNOHANG);
3597 if (wait_result == soda_pid) {
3598 break;
3599 }
3600 if (wait_result < 0 && errno != EINTR) {
3601 return -1;
3602 }
3603 const uint64_t now_us = monotonic_time_us();
3604 if (!terminating && (!usher_running() || now_us == 0 || started_us == 0
3605 || now_us - started_us >= (uint64_t)USHER_SODA_TIMEOUT_MS * 1000)) {
3606 fprintf(stderr, "USHER-%d:\tSODA %s; stopping analysis, original photo retained\n",
3607 shoot->data.nr, usher_running() ? "runtime deadline reached" : "shutdown");
3608 kill(-soda_pid, SIGTERM);
3609 kill(soda_pid, SIGTERM);
3610 termination_us = now_us;
3611 terminating = true;
3612 } else if (terminating && (now_us == 0
3613 || now_us - termination_us >= (uint64_t)SODA_SHUTDOWN_GRACE_MS * 1000)) {
3614 kill(-soda_pid, SIGKILL);
3615 kill(soda_pid, SIGKILL);
3616 }
3618 }
3619 return !terminating && WIFEXITED(status) ? WEXITSTATUS(status) : -1;
3620}
3621
3622/** @brief End worker ownership after publication, distinct from releasing the capture ticket. */
3623static void release_worker_slot(void)
3624{
3625 pthread_mutex_lock(&mut);
3628 pthread_cond_broadcast(&workers_finished);
3629 pthread_mutex_unlock(&mut);
3630}
3631
3632/** @brief Consume the newest buffered payload for a legacy image request.
3633 * @details This compatibility path consumes the entry before queueing
3634 * transmission; if queue admission fails, the entry is not retried. */
3635static inline void send_msg_image_buffer(void)
3636{
3637 // Check if image is available
3638 if (image_count > 0) {
3639 printf("USHER:\thandle_msg_buffer: Send %d\n", image_idx);
3640 // Send the image
3642 image_count--;
3643
3644 if (serial_tx_send(USHER_PAYLOAD, (const uint8_t *)image_buffer[image_idx], IMAGE_SIZE) != 0) {
3645 fprintf(stderr, "USHER:\timage UART send failed: %s\n", strerror(errno));
3646 }
3647 }
3648}
3649
3650/** @brief Queue a snapshot of USHER's capture counters.
3651 * @details Copy shared counters under the mutex, then release it before
3652 * UART admission so capture workers need not wait on the transport path. */
3653static inline void send_msg_status(void)
3654{
3655 union usher_status_union status_msg = {0};
3656
3657 pthread_mutex_lock(&mut);
3658 status_msg.data.cpu = 0;
3660 status_msg.data.shots = shooting_count;
3661 status_msg.data.extra = 0;
3662 pthread_mutex_unlock(&mut);
3663
3664 if (serial_tx_send(USHER_STATUS, status_msg.bin, sizeof(status_msg.bin)) != 0) {
3665 fprintf(stderr, "USHER:\tstatus UART send failed: %s\n", strerror(errno));
3666 }
3667}
3668
3669/** @brief Print the invocation modes and build-specific defaults.
3670 * @param program Executable spelling to use in examples.
3671 * @details Report compiled endpoint values rather than assuming the same
3672 * defaults for native and board builds. */
3673static void print_usage(const char *program)
3674{
3675 puts(USHER_BUILD_VERSION);
3676 printf("Usage: %s [--serial DEVICE | --local] [--chdk | --aicam | --spottercam | --lwircam | --loomcam] [--earcam] [--test] [OPTIONS]\n",
3677 program);
3678 printf(" %s (--chdk | --aicam | --spottercam | --lwircam) --speedtest\n", program);
3679 printf(" --serial DEVICE serial endpoint (default: %s)\n", USHER_SERIAL_DEVICE);
3680 printf(" --local create local serial bridge %s <-> %s\n",
3682 printf(" --chdk use the CHDK camera backend\n");
3683 printf(" --aicam use system-installed rpicam-still (plain capture, no detection)\n");
3684 printf(" --spottercam use native IMX500 vehicle detection (camera id 2; default outside local mode)\n");
3685 printf(" --native-photo use native libcamera photos without inference with --aicam or --spottercam\n");
3686 printf(" --lwir-spotter-settings FILE analyze saved LWIR JPEGs with a separate ONNX model\n");
3687 printf(" --lwir-spotter-profile FILE measured native 256x192 LWIR PANGEA camera profile\n");
3688 printf(" --lwir-spotter-limits US,M maximum exposure interval and pose uncertainty (5000,1)\n");
3689 printf(" --spottercam-settings FILE select detector model/backend settings\n");
3690 printf(" --spottercam-targets FILE project detected vehicles onto UART target slots 0..4\n");
3691 printf(" --loomcam-settings FILE select LOOM model/backend settings\n");
3692 printf(" --earcam-settings FILE select acoustic model/backend settings\n");
3693 printf(" --loomcam enable LOOM_cam visual-return framework on AIcam (camera id 2)\n");
3694 printf(" --loomcam-model FILE IMX500 RPK uploaded by loomcam (default: %s)\n", USHER_LOOMCAM_MODEL);
3695 printf(" --loomcam-reference-dir DIR outbound references, same filesystem as photos (default: %s)\n",
3697 printf(" --lwircam use the Tiny 1-C LWIR camera backend\n");
3698 printf(" --lwir-config FILE load LWIR rendering/correction policy\n");
3699 printf(" --earcam also run the acoustic earcam backend (camera id 4)\n");
3700 printf(" --diplacam-config FILE enable native file-backed XY planning (camera id 5; no photographs)\n");
3701 printf(" --earcam-device PCM enable real EARcam with this ALSA input (e.g. default or plughw:CARD=Device,DEV=0)\n");
3702 printf(" --earcam-sim LAT,LON[,DB] earcam backend with a virtual loudspeaker instead of a microphone\n");
3703 printf(" --earcam-band LOW,HIGH tone search band in Hz (default earcam 1800,3200; motionSCOUT K-T-R: 2400,3200)\n");
3704 printf(" --test process a mock image for any camera backend\n");
3705 printf(" randomly selects testphotos/*.jpg beside this executable\n");
3706 printf(" --mocktransform transform test image using shot roll, pitch, and yaw\n");
3707 printf(" --debug show serial, USHER frame, trigger, and capture diagnostics\n");
3708 printf(" --mock-image FILE image used by local or test capture (default: %s)\n", USHER_MOCK_IMAGE);
3709 printf(" --mock-map MIMIC: Map-tile Imagerie Modeling in Interactive Camera-sim\n");
3710 printf(" local map-based mock captures (implies --test; requires --local)\n");
3711 printf(" --mock-map-cache DIR pprzgcs XYZ cache root (legacy tile path: GOOGLE/18)\n");
3712 printf(" --mock-map-fov H,V horizontal,vertical FOV degrees (default model: 60,45; fixed nadir mount)\n");
3713 printf(" --mock-lens FILE AIcam/LOOM saved-photo lens profile, before neural inference; requires --local --mock-map\n");
3714 printf(" --pangea DIR optional idle photo-map worker; local MIMIC or real camera profile\n");
3715 printf(" --pangea-camera FILE real JPEG mapping geometry; no test images or simulated effects\n");
3716 printf(" --pangea-pause-file FILE defer map work while FILE exists; capture/detection unchanged\n");
3717 printf(" --survey-camera FILE calibrated PANGEA_CAMERA_V1 key=value profile; repeat per camera\n");
3718 printf(" --survey-enforce enable conservative redundant-photo suppression and bounded lookahead\n");
3719 printf(" --survey-overlap RATIO minimum overlap for predictive delay (0..0.9, default 0.3)\n");
3720 printf(" --pose-log DIR record flight pose samples as CSV in DIR (default: off)\n");
3721 printf(" --clock-align bound FC-to-MORA time offset (automatic for live cameras)\n");
3722 printf(" --no-clock-align disable clock probes and negotiated pose streaming\n");
3723 printf(" --lwir-latency-ms MIN,MAX measured exposure-to-callback bounds, not JPEG latency\n");
3724 printf(" --chdk-latency-ms MIN,MAX measured command-to-exposure bounds\n");
3725 printf(" --lwir-calibration FILE camera YAML used to turn LWIR hotspots into coordinates\n");
3726 printf(" --lwir-raw keep the full sensor frame as photos/lNNNNNN.jpg.raw instead of\n");
3727 printf(" storing the temperatures inside the JPEG\n");
3728 printf(" --lwir-motion-compensation advance LWIR GPS over the measured capture delay\n");
3729 printf(" --speedtest capture one warm-up plus %d timed photos, report photos/s and time/photo, and exit\n",
3731 printf(" --help show this help\n");
3732 printf(" --version show application version and build Git revision\n");
3733}
3734
3735/** @brief Return an immutable capability description without selecting or opening a camera.
3736 * @param type Resolved runtime backend type.
3737 * @return Descriptor with static hook lifetimes, or a zero descriptor for an invalid type.
3738 */
3740{
3742 if (type == CAMERA_BACKEND_LOCAL) backend.shoot = local_backend_shoot;
3743 return backend;
3744}
3745
3746/** @brief Resolve metadata and hooks for a concrete protocol camera identity.
3747 * @param camera_id Protocol camera ID.
3748 * @return Registry entry for the current routing mode.
3749 * @details Keep identity lookup separate from selecting the global backend
3750 * so a second sensor's result does not change capture configuration. */
3756
3757/** @brief Install the startup backend, optionally with local test hooks.
3758 * @param type Requested registry backend.
3759 * @param test_mode True to replace hardware capture with simulation.
3760 * @return Zero on selection, or -1 if the registry has no such backend.
3761 * @details Preserve the selected camera identity in test mode while removing
3762 * native capture operations so a mock job cannot acquire the hardware. */
3763static int camera_backend_select(enum camera_backend_type type, bool test_mode)
3764{
3765 struct camera_backend selected = camera_backend_registry_get(type, test_mode || mock_map_enabled);
3766 if (type == CAMERA_BACKEND_LOCAL) selected.shoot = local_backend_shoot;
3767 if (!selected.name) {
3768 fprintf(stderr, "USHER:\tinvalid camera backend\n");
3769 return -1;
3770 }
3771 camera = selected;
3772
3773 if (test_mode) {
3776 camera.deinit = local_pipe_deinit;
3777 camera.soda_application = USHER_SODA;
3778 camera.capture_ops = NULL;
3779 camera.capabilities |= CAMERA_CAP_MOCK;
3780 }
3781 return 0;
3782}
3783
3784/** @brief Capture a local fixture under the selected optical camera identity.
3785 * @param[out] filename Output path; use only on success.
3786 * @param filename_size Capacity including the terminator.
3787 * @param image_number Photo number.
3788 * @return Zero on capture, or -1 on invalid identity or capture failure.
3789 * @details Supply the concrete camera identity so the fixture uses the
3790 * appropriate prefix while remaining distinct from a physical capture. */
3791static int local_backend_shoot(char *filename, size_t filename_size, int image_number)
3792{
3793 const struct camera_backend identity = camera_identity_get(optical_camera_id);
3795 return -1;
3796 }
3797 return local_pipe_shoot(filename, filename_size, image_number, &identity);
3798}
3799
3800/** @brief Reserve the shared local serial endpoint namespace.
3801 * @return Zero on exclusive reservation, or -1 when it cannot be acquired.
3802 * @details Keep the advisory lock descriptor open until teardown to stop
3803 * another local instance from replacing the active endpoint links. */
3804static int lock_local_instance(void)
3805{
3806 local_lock_fd = open(USHER_LOCAL_LOCK_FILE, O_RDWR | O_CREAT | O_CLOEXEC, 0644);
3807 if (local_lock_fd < 0) {
3808 fprintf(stderr, "USHER:\tfailed to open local instance lock %s: %s\n",
3809 USHER_LOCAL_LOCK_FILE, strerror(errno));
3810 return -1;
3811 }
3812 struct flock lock = {
3813 .l_type = F_WRLCK,
3814 .l_whence = SEEK_SET,
3815 .l_start = 0,
3816 .l_len = 0
3817 };
3818 if (fcntl(local_lock_fd, F_SETLK, &lock) != 0) {
3819 fprintf(stderr, "USHER:\tlocal mode is already running; stop it before starting another instance\n");
3821 local_lock_fd = -1;
3822 return -1;
3823 }
3824 return 0;
3825}
3826
3827/** @brief Launch the PTY bridge for a hardware-free session.
3828 * @return Owned child PID once both links appear, or -1 on failure.
3829 * @details Call with the local instance lock held. Remove stale links
3830 * before launch and clean up the child and links if startup fails. */
3832{
3833 unlink(USHER_LOCAL_SIM_DEVICE);
3834 unlink(USHER_LOCAL_APP_DEVICE);
3835
3836 pid_t child = fork();
3837 if (child < 0) {
3838 perror("USHER: failed to fork socat");
3839 return -1;
3840 }
3841 if (child == 0) {
3842 char sim_endpoint[256];
3843 char app_endpoint[256];
3844 snprintf(sim_endpoint, sizeof(sim_endpoint), "pty,raw,echo=0,link=%s", USHER_LOCAL_SIM_DEVICE);
3845 snprintf(app_endpoint, sizeof(app_endpoint), "pty,raw,echo=0,link=%s", USHER_LOCAL_APP_DEVICE);
3846 execlp("socat", "socat", sim_endpoint, app_endpoint, (char *)NULL);
3847 perror("USHER: failed to start socat");
3848 _exit(127);
3849 }
3850
3852 fprintf(stderr, "USHER:\tsocat did not create the local serial endpoints\n");
3853 kill(child, SIGTERM);
3854 waitpid(child, NULL, 0);
3855 unlink(USHER_LOCAL_SIM_DEVICE);
3856 unlink(USHER_LOCAL_APP_DEVICE);
3857 return -1;
3858 }
3859 return child;
3860}
3861
3862/** @brief Give the new serial bridge time to publish one endpoint.
3863 * @param path Endpoint path to check.
3864 * @return Zero if found during polling, or -1 if it never appears.
3865 * @details Poll with a fixed attempt limit so failure to create a link
3866 * is detected rather than waiting indefinitely for readiness. */
3867static int wait_for_path(const char *path)
3868{
3869 for (int attempt = 0; attempt < 100; attempt++) {
3870 if (access(path, F_OK) == 0) {
3871 return 0;
3872 }
3873 sleep_microseconds(10000);
3874 }
3875 return -1;
3876}
3877
3878/** @brief Stop the owned simulator bridge and release the local lock.
3879 * @details Preserve child and endpoint ownership if termination cannot
3880 * be confirmed. Links owned elsewhere are not removed. */
3882{
3883 if (local_bridge_owned && socat_pid > 0) {
3884 kill(socat_pid, SIGTERM);
3885 if (!wait_owned_child(&socat_pid, 100)) {
3886 kill(socat_pid, SIGKILL);
3887 if (!wait_owned_child(&socat_pid, 1500)) {
3888 fprintf(stderr, "USHER:\tlocal serial bridge has not exited; retaining child ownership\n");
3889 return;
3890 }
3891 }
3892 }
3893 if (local_bridge_owned) {
3894 unlink(USHER_LOCAL_SIM_DEVICE);
3895 unlink(USHER_LOCAL_APP_DEVICE);
3896 local_bridge_owned = false;
3897 }
3898 if (local_lock_fd >= 0) {
3900 local_lock_fd = -1;
3901 }
3902}
3903
3904/** @brief Request service shutdown from a signal handler.
3905 * @param signal_number Signal delivered by the OS; all installed cases request shutdown.
3906 * @details Notify the event loop rather than closing camera or UART state in
3907 * the handler. Owners perform teardown in ordinary execution context. */
3908static void handle_signal(int signal_number)
3909{
3910 (void)signal_number;
3913}
static const char * photo_directory
Definition ai_cam_pipe.c:85
char ** environ
capture_result
Definition ai_cam_pipe.c:78
void ai_cam_pipe_set_photo_directory(const char *directory)
Select a borrowed directory before initialization.
int ai_cam_pipe_set_native(bool enabled)
Select native or system-camera capture before startup.
Parent-side contract for stock and native Raspberry Pi camera capture.
@ CAMERA_CAP_MOCK
@ CAMERA_CAP_GEOLOCATION
@ CAMERA_CAP_FINISH_OWNED
@ CAMERA_CAP_IMAGE
@ CAMERA_CAP_PRIVATE_IMAGE
@ CAMERA_CAP_DETECTION
@ CAMERA_CAP_POINT_STREAM
@ CAMERA_CAP_POINT_SESSION
@ CAMERA_BACKEND_MAX_ID
#define USHER_SODA
struct camera_backend camera_backend_registry_identity(int camera_id, enum camera_backend_type preferred, bool mock)
Resolve naming/metadata identity from the profile used for acquisition.
struct camera_backend camera_backend_registry_get(enum camera_backend_type type, bool mock)
Return a descriptor without selecting, configuring or opening hardware.
enum camera_backend_type camera_backend_registry_route(int camera_id, enum camera_backend_type preferred, bool local_only)
Resolve a physical ID, preferring its configured logical profile.
Backend definitions and physical-camera routing.
@ CAMERA_BACKEND_LOCAL
@ CAMERA_BACKEND_CHDK
@ CAMERA_BACKEND_AI_CAM
@ CAMERA_BACKEND_UNSELECTED
@ CAMERA_BACKEND_LOOM_CAM
@ CAMERA_BACKEND_LWIR_CAM
@ CAMERA_BACKEND_SPOTTER_CAM
static void capture_set_running(volatile sig_atomic_t *running, bool active)
Update cancellation without locks; this flag does not publish other shared state.
static bool capture_running(const volatile sig_atomic_t *running)
Atomically poll a borrowed cancellation flag; NULL means no cancellation.
bool usher_control_encode_result(uint8_t *bytes, size_t size, const struct usher_control_result *result)
Encode one camera's correlated control result.
bool usher_control_put_u32(uint8_t *bytes, size_t size, size_t offset, uint32_t value)
Encode a 32-bit value as four little-endian protocol bytes.
bool usher_control_get_u32(const uint8_t *bytes, size_t size, size_t offset, uint32_t *value)
Decode a bounded four-byte little-endian protocol value.
bool usher_control_value_valid(uint8_t command, uint8_t value)
Validate the command-specific legal value range.
bool usher_control_decode_request(const uint8_t *bytes, size_t size, struct usher_control_request *request)
Validate and decode one fixed-size command payload.
Fixed-size camera-control wire codec and FC-side ticket state.
#define USHER_CONTROL_LEASE_US
Public C API for reading PANGEA camera calibration profiles.
#define CAMERA_PROFILE_MAX_BYTES
int camera_speedtest_create_output_directory(const char *base_directory, char *output, size_t output_size)
Atomically create a private directory for one benchmark run.
int camera_speedtest_run(const struct camera_speedtest_config *config, int first_image)
Capture one untimed warm-up image and ten timed images sequentially.
int camera_speedtest_find_image_block(const struct camera_speedtest_config *config, int *first_image)
Find an unused consecutive image-number block for warm-up and samples.
Standalone, backend-neutral still-camera throughput benchmark.
#define CAMERA_SPEEDTEST_SAMPLE_COUNT
bool capture_arbiter_set_overlap(double overlap)
Set the overlap floor for deliberate predictive delay, not FC shot spacing.
void capture_arbiter_pose_invalidate(void)
Forget pose history when synchronization is lost; keep saved coverage.
void capture_arbiter_set_enforce(bool enabled)
Enable coverage-based suppression and limited delay, or observe decisions only.
bool capture_arbiter_pending(void)
Check whether waiting or active survey work remains.
void capture_arbiter_pose_sample(const union usher_pose_sample_union *sample, uint64_t earliest_us, uint64_t latest_us)
Add a pose only after the caller has established bounded clock alignment.
bool capture_arbiter_frame_timing(const char *filename, unsigned camera_id, struct capture_observation *observation)
Read embedded capture identity from a stable JPEG; true need not qualify timing.
bool capture_arbiter_take(uint32_t ready_mask, uint64_t now_us, union dc_shot_union *shot, uint8_t *mask)
Admit the oldest ready camera intention after optional coverage evaluation.
bool capture_arbiter_owns(int32_t number)
Identify a shot whose active survey ownership must not be superseded.
static unsigned capacity[COVERAGE_CAMERAS]
uint32_t capture_arbiter_session_id(void)
Return the peer-session token, or zero when survey mode is not configured.
void capture_arbiter_set_scope(const union usher_capture_arbiter_state_union *scope, uint64_t now_us)
Refresh survey authorization or cancel waiting work when scope is withdrawn.
bool capture_arbiter_set_camera_capacity(unsigned camera_id, unsigned limit)
Set admission from a backend's actual capacity, independent of camera ID.
bool capture_arbiter_result(union usher_capture_arbiter_result_union *result, uint32_t ready_mask)
Pop a bounded best-effort result for UART transmission.
void capture_arbiter_complete(const union dc_shot_union *shot, unsigned camera_id, bool saved, bool exposure_pose_valid, double uncertainty_m, uint64_t now_us)
Release admission and optionally credit verified saved coverage.
static uint32_t session
bool capture_arbiter_observation_pose(struct capture_observation *observation, uint64_t wait_us)
Resolve one bounded observation; wait_us is 0 on the serial thread, at most 200000 in workers.
bool capture_arbiter_load_camera(const char *filename)
Load one camera's measured profile without guessing geometry from its ID.
void capture_arbiter_stop(void)
Cancel waiting intentions, retaining active-image ownership and saved coverage.
bool capture_arbiter_offer(const union usher_capture_arbiter_shoot_union *request, uint64_t now_us)
Split a survey request into bounded per-camera intentions.
Session-scoped survey admission and saved-image evidence for USHER.
static bool capture_timing_valid(const struct capture_timing *timing)
Check whether timing evidence is internally consistent and recent.
@ CAPTURE_TIME_SHUTTER_WINDOW
@ CAPTURE_TIME_CALIBRATED_EXPOSURE
static bool capture_observation_exposure(const struct capture_observation *observation)
Distinguish exposure evidence from other valid observation times.
void chdk_camera_backend_set_photo_directory(const char *directory)
CHDK-owned download and photo publication.
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
int(* open)(const struct usbfs_device *, struct usbfs_handle *)
Definition chdkbridge.c:56
bool clock_alignment_reply(struct clock_alignment *clock, const uint8_t *payload, size_t length, uint64_t received_us)
Validate a flight-controller clock reply and establish a mapping anchor.
bool clock_alignment_request(struct clock_alignment *clock, union usher_clock_request_union token, uint64_t sent_us)
Register a newly transmitted clock probe.
bool clock_alignment_map(const struct clock_alignment *clock, union usher_clock_request_union token, uint32_t fc_us, uint64_t now_us, struct clock_interval *interval)
Project a controller timestamp into a conservative USHER time interval.
#define COVERAGE_CAMERAS
static bool poll_result(struct camera_point_result *point)
Drain a bounded reply batch and publish only the active request's result.
static pid_t child
bool dipla_camera_backend_setup(const char *configuration)
Select the worker experiment before acquiring its process.
Optional non-image camera adapter for the native Diplacam worker.
bool ear_cam_pipe_set_settings(const char *settings)
Copy an assignment path before the microphone supervisor starts.
union dc_shot_union request
#define ANGLE_BFP_SCALE
#define POSITION_BFP_SCALE
Audio/pose adapter and zero-copy snapshot API for the EAR backend.
void ear_camera_backend_set_band(double low_cut_hz, double high_cut_hz)
Forward startup tone-band selection to the audio adapter.
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.
EAR-specific startup configuration behind USHER's generic backend interface.
#define RAD_TO_DEG
Definition ear_fusion.c:35
static bool pending
static bool ready
static volatile sig_atomic_t keep_running
Definition earcam.c:181
static void handle_signal(int signal_number)
Request orderly capture-loop termination from a signal handler.
Definition earcam.c:294
int image_exif_write_hotspots(const char *filename, const char *information)
Append structured thermal hotspot/geolocation evidence to JPEG EXIF.
Definition image_exif.c:372
#define SPEED_BFP_SCALE
Definition image_exif.c:49
int image_exif_write_complete(const char *filename, const union dc_shot_union *shot, double capture_delay_s, int compensate, const struct capture_timing *timing, const union dc_shot_union *request, double uncertainty_m, const char *objects)
Write flight provenance and an available object-detection result in one metadata transaction.
Definition image_exif.c:473
int image_exif_write_mock_map(const char *filename, double horizontal_fov, double vertical_fov)
Label a synthetic map fixture with its geometry and provider-neutral XYZ tile scheme.
Definition image_exif.c:382
Flight, timing, and thermal-analysis metadata writing for captured JPEGs.
bool image_lens_emulate(const char *application, const char *input, const char *profile, const char *cache, char *output, size_t capacity, const volatile sig_atomic_t *running)
Definition image_lens.c:29
int image_mock_transform(const char *filename, const union dc_shot_union *shot)
Rewrite a local test JPEG to simulate the shot attitude.
Local-simulation JPEG attitude transform API.
#define IMAGE_MOCK_TRANSFORM_SKIPPED
Successful result: transform was intentionally skipped for a near-horizon attitude.
int local_pipe_map_shoot(char *filename, size_t filename_size, const union dc_shot_union *shot, const struct camera_backend *identity, const char *cache_directory, double horizontal_fov_deg, double vertical_fov_deg)
Render a map-backed capture using the trigger's camera geometry.
Definition local_pipe.c:179
int local_pipe_test_init(const char *mock_image)
Initialize test mode with a supplied JPEG or a random fixture beside USHER.
Definition local_pipe.c:87
#define USHER_LOCAL_PHOTO_DIR
Definition local_pipe.c:42
void local_pipe_deinit(void)
Forget selected local fixture sources.
Definition local_pipe.c:295
int local_pipe_shoot(char *filename, size_t filename_size, int image_number, const struct camera_backend *identity)
Create a mock capture file for a shot.
Definition local_pipe.c:193
#define USHER_MOCK_IMAGE
Definition local_pipe.c:46
int local_pipe_map_init(const char *source)
Prepare output storage for map-backed simulation.
Definition local_pipe.c:171
Local mock-camera backend API for simulator and desk testing.
struct camera_backend loom_camera_backend_get(bool mock)
Return LOOM's descriptor without opening a sensor or starting a thread.
void loom_camera_backend_configure(const char *references, const char *model)
Configure the LOOM plugin before selecting or initializing its owner.
int loom_camera_backend_set_settings(const char *settings)
Choose one LOOM assignment before acquiring either worker.
LOOM-owned capture specialization and stream lifecycle.
#define USHER_LOOMCAM_MODEL
Expected RPK path; the framework does not fabricate a trained model.
#define USHER_LOOMCAM_REFERENCE_DIR
Default outbound archive; use independent reference storage per sortie.
int lwir_cam_pipe_process_mock(char *filename)
Process a mock thermal image for hardware-free local testing.
void lwir_cam_pipe_set_native_raw(int enabled)
Select whether successful captures keep an explicit .raw companion.
void lwir_cam_pipe_set_photo_directory(const char *directory)
Override the output directory for an isolated standalone benchmark.
int lwir_cam_pipe_set_calibration(const char *path)
Set the optional calibration file used by server-side geolocation.
int lwir_cam_pipe_set_config(const char *path)
Apply a bounded worker configuration before starting the capture server.
Parent-side protocol for USHER's persistent Tiny1-C LWIR capture server.
char evidence[8192]
Definition lwir_image.c:66
struct jpeg_error_mgr error
Definition lwir_image.c:60
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
void lwir_spotter_stop(void)
Stop the exclusively owned model worker.
bool lwir_spotter_profile(const char *filename)
Load a native LWIR intrinsics and mount profile.
int lwir_spotter_analyze(const char *filename, const union dc_shot_union *shot, const struct capture_timing *timing, const volatile sig_atomic_t *running)
Analyse one immutable image with copied capture evidence; no camera is acquired.
bool lwir_spotter_enabled(void)
Test whether saved-LWIR analysis was explicitly selected.
bool lwir_spotter_settings(const char *settings)
Select a separate ONNX detector assignment.
bool lwir_spotter_limits(const char *limits)
Set the timing and pose uncertainty limits for projection.
Serialized saved-LWIR object analysis with immutable frame and exposure evidence.
constexpr const char * backend
Definition compat.hpp:270
Small path and writable-directory helpers shared by USHER backends.
static int usher_complete_photo(char *filename, size_t capacity)
Publish a staged photo and return its immutable public path.
Definition path_utils.h:216
static int usher_enter_executable_directory(void)
Change to the directory containing the running USHER executable.
Definition path_utils.h:46
static const char * usher_resolve_path(const char *path, char *buffer, size_t buffer_size)
Expand a leading home-directory shorthand without allocating memory.
Definition path_utils.h:74
#define PATH_MAX
Definition path_utils.h:39
int pose_log_record(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us)
Validate and enqueue a raw pose payload without clock mapping evidence.
Definition pose_log.c:296
int pose_log_record_clocked(const uint8_t *payload, size_t length, uint64_t receive_monotonic_us, const struct pose_clock_evidence *evidence)
Validate and enqueue a pose payload with optional mapped timing provenance.
Definition pose_log.c:307
int pose_log_start(const char *directory)
Start a durable asynchronous CSV session, or disable logging when directory is empty.
Definition pose_log.c:197
int pose_log_stop(void)
Flush queued records, join the writer, and close the CSV file.
Definition pose_log.c:375
static size_t count
Definition pose_log.c:79
static pthread_t writer
Definition pose_log.c:76
struct pose_log_stats pose_log_status(void)
Return a synchronized snapshot of logging health and loss counters.
Definition pose_log.c:365
Non-blocking pose-evidence CSV logging API.
int fd
Definition serial.c:39
int serial_init(const char *port_name)
Configure the shared non-blocking USHER UART descriptor.
Definition serial.c:41
UART descriptor setup and byte-oriented compatibility helpers.
int serial_tx_start(int descriptor)
Attach an already-open non-blocking UART descriptor.
Definition serial_tx.c:71
int serial_tx_send(uint8_t message, const uint8_t *payload, size_t length)
Queue and opportunistically flush one complete USHER frame.
Definition serial_tx.c:156
void serial_tx_stop(void)
Discard pending output and detach the UART during shutdown/restart.
Definition serial_tx.c:92
int serial_tx_flush(void)
Continue writing queued bytes after POLLOUT reports readiness.
Definition serial_tx.c:166
int serial_tx_send_if_idle(uint8_t message, const uint8_t *payload, size_t length)
Send only when no earlier frame is queued, for low-priority probes.
Definition serial_tx.c:161
bool serial_tx_pending(void)
Report queued data or a latched output error needing event-loop handling.
Definition serial_tx.c:174
Thread-safe, non-blocking framed UART transmission for USHER.
int socket_get_fd(void)
Return the active UDP descriptor for polling.
Definition socket.c:102
int socket_recv(char *buffer, int len)
Receive one datagram without blocking.
Definition socket.c:107
int socket_init(int is_server)
Create the loopback UDP endpoint and, for a server, claim USHER ownership.
Definition socket.c:44
void socket_deinit(void)
Close the owned UDP endpoint; repeated calls are harmless.
Definition socket.c:96
Local non-blocking UDP channel used by USHER's development pipeline.
void spotter_cam_pipe_deinit(void)
Stop the native camera process and clear detector-specific configuration.
int spotter_cam_pipe_set_settings(const char *settings)
Select the detector assignment before either capture or saved-picture analysis starts.
int spotter_cam_pipe_analyze(const char *filename, unsigned number)
Analyze a saved simulation/private picture and bind results to its source hash and request.
void spotter_cam_pipe_set_photo_directory(const char *directory)
Set the borrowed output directory before backend initialization.
int spotter_cam_pipe_set_photo_only(bool enabled)
Select or inspect the model-free capture mode before worker startup.
Native USHER adapter for on-sensor detection or photo-only capture.
bool spotter_camera_backend_targets_enabled(void)
True when native Spottercam UART target projection is configured and active.
bool spotter_camera_backend_set_targets_profile(const char *filename)
Configure pinhole camera calibration for projecting Spottercam boxes to UART points.
Spottercam backend descriptor and optional native UART target projection.
Compile-time build identity strings for USHER executables.
#define USHER_BUILD_VERSION
Definition version.h:72
Function table describing one backend's owned camera operations.
void(* image_saved)(const char *filename, const union dc_shot_union *shot)
void(* detection_summary)(char *buffer, size_t size)
unsigned capabilities
const struct camera_capture_ops * capture_ops
Optional split-phase capture lifecycle.
const char * soda_application
Optional SODA application name for this backend's saved files.
void(* save_detection_copy)(const char *filename)
const struct camera_session_ops * session
bool(* bind_frame)(uint64_t sequence, uint64_t sensor_timestamp_ns)
int(* record)(const union dc_shot_union *shot)
int(* geolocate)(char *filename)
int(* init)(const char *source_image)
Initialize backend resources; optional mock image path is borrowed.
void(* deinit)(void)
Release backend resources and reap owned children.
int(* shoot)(char *filename, size_t filename_size, int image_number)
Trigger one photo and return the backend's owned staging path.
const struct camera_point_stream_ops * point_stream
Optional repeated point stream, independent of start/stop sessions.
const char * name
Stable backend name used for logs and diagnostics.
Driver capabilities whose table must outlive every pending image.
bool(* has_capacity)(void)
Nonblocking capacity snapshot; acquisition remains the admission authority.
Per-image ownership record, kept alive until the matching finish call.
Repeated correlated point updates from saved photos or non-image work.
bool(* poll_result)(struct camera_point_result *result)
bool(* stop)(uint32_t session_id)
bool(* start)(uint32_t session_id)
bool(* listening)(void)
int(* completion_fd)(void)
bool(* poll_result)(struct camera_point_result *result)
bool(* start)(uint32_t session_id)
void(* drain)(void)
bool(* stop)(uint32_t session_id)
Immutable dependencies for one selected and initialized camera backend.
int(* shoot)(char *filename, size_t filename_size, int image_number)
Pool-owned worker request; ownership transfers only after thread creation succeeds.
Definition usher.c:250
uint8_t camera_mask
Definition usher.c:253
union dc_shot_union shot
Definition usher.c:251
bool shot_counted
Definition usher.c:257
uint64_t received_us
Definition usher.c:255
uint32_t request_id
Definition usher.c:252
uint64_t ticket
Definition usher.c:254
bool arbiter_owned
Definition usher.c:256
enum capture_time_kind kind
union dc_shot_union pose
Shared observation evidence with optional LWIR request/frame-delivery timing.
Per-image handoff from acquisition to publication, EXIF and optional analysis.
Definition usher.c:264
struct camera_backend backend
Definition usher.c:265
double pose_uncertainty_m
Definition usher.c:271
union dc_shot_union exposure_shot
Definition usher.c:270
int camera_id
Definition usher.c:267
struct capture_timing capture_times
Definition usher.c:269
bool exposure_pose_valid
Definition usher.c:272
char filename[MAX_FILENAME]
Definition usher.c:266
struct camera_pending pending
Definition usher.c:273
double capture_delay
Definition usher.c:268
Stateful evidence for at most one pending and one accepted clock probe.
Inclusive USHER monotonic-time bounds for a mapped controller timestamp.
Long-to-short option mapping; borrowed values are passed to standard getopt.
Definition earcam.c:213
char option[SHORT_OPTION_STORAGE]
Definition earcam.c:215
const char * name
Definition earcam.c:214
bool requires_argument
Definition earcam.c:216
One timestamped geographic position for a replay annotation.
Optional token-bound evidence mapping a controller pose interval to MORA time.
Definition pose_log.h:29
Snapshot counters for accepted, flushed, dropped, and rejected pose records.
Definition pose_log.h:40
uint64_t accepted
Definition pose_log.h:41
uint64_t dropped
Definition pose_log.h:43
uint64_t rejected
Definition pose_log.h:44
uint64_t synced
Definition pose_log.h:42
Saved-file analysis job; retaining pixels here would multiply decoder memory.
Definition usher.c:280
char filename[MAX_FILENAME]
Definition usher.c:281
uint64_t queued_us
Definition usher.c:287
uint64_t retry_after_us
Definition usher.c:287
bool spotting_done
Definition usher.c:284
union dc_shot_union shot
Definition usher.c:282
unsigned int attempts
Definition usher.c:288
struct stat source
Definition usher.c:286
int camera_id
Definition usher.c:285
struct capture_timing timing
Definition usher.c:283
One addressed command request shared with the companion protocol.
uint8_t camera_mask
Camera selection mask, command identifier, and command value.
Result evidence for one camera selected by a request mask.
uint8_t camera_id
One-based camera ID, terminal status, observed value, and evidence.
struct usher_control_request request
Correlated request identity; never substitute a shot number here.
union dc_shot_union shot
uint8_t bin[USHER_SHOOT_MASK_MSG_SIZE]
struct dc_shot_mask_union::@111210153017120377071246320077003270260354205063 data
struct dc_shot_union::@351207206061007345226276304225222200157171312155 data
struct usher_cam_point_update_union::@102362040132143036341157267241205145176054226171 data
uint8_t bin[USHER_CAM_POINT_UPDATE_MSG_SIZE]
uint8_t bin[USHER_START_TARGETED_MSG_SIZE]
struct usher_camera_session_union::@143240012115064153304013213117135060274266136035 data
USHER-to-FC capability advertisement.
uint8_t bin[USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE]
Best-effort USHER-to-FC terminal result for one camera and shot number.
FC-to-USHER spatial observation request, not a physical shutter acknowledgement.
uint8_t bin[USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE]
struct usher_capture_arbiter_shoot_union::@051263346153071110145344217246151166245325226104 data
FC-to-USHER survey authorization, independent of individual shot requests.
uint8_t bin[USHER_CAPTURE_ARBITER_STATE_MSG_SIZE]
uint8_t bin[USHER_CLOCK_REQUEST_MSG_SIZE]
union usher_pose_sample_union sample
union usher_clock_request_union request
struct usher_pose_clocked_union::@034256305167013222206020157154353370243343140130 data
uint8_t bin[USHER_POSE_CLOCKED_MSG_SIZE]
uint8_t bin[USHER_POSE_SAMPLE_MSG_SIZE]
union dc_shot_union shot
struct usher_pose_sample_union::@042015206147200076364072004013147106310343341221 data
uint8_t bin[USHER_STATUS_MSG_SIZE]
struct usher_status_union::usher_status_struct data
static bool start_chdk_finish(const struct capture_job *job, const struct captured_image *image)
Hand a captured image to the finisher, waiting if the previous one is still writing.
Definition usher.c:2547
static size_t shot_result_count
Definition usher.c:354
#define IMAGE_SIZE
Definition usher.c:103
static uint64_t soda_backlog_completed
Definition usher.c:394
static bool capture_job_used[CAPTURE_JOB_CAPACITY]
Definition usher.c:364
static void queue_shot_result(uint32_t request_id, int32_t number, unsigned camera_id, uint32_t status)
Hand one camera's terminal shot result to the serial owner.
Definition usher.c:471
static int camera_prepare(int camera_id)
Select and lazily initialize a backend under the caller's camera ownership.
Definition usher.c:2176
static pthread_t soda_backlog_thread
Definition usher.c:395
#define USHER_MAX_ARGUMENTS
Definition usher.c:88
static void handle_targeted_start(uint32_t camera_id, uint32_t session_id)
Start a point session for the addressed backend or backends.
Definition usher.c:3105
static struct camera_backend camera_backend_get(enum camera_backend_type type)
Return an immutable capability description without selecting or opening a camera.
Definition usher.c:3739
static int wait_for_path(const char *path)
Give the new serial bridge time to publish one endpoint.
Definition usher.c:3867
#define EVENT_LOOP_ACTIVE_TIMEOUT_MS
Definition usher.c:113
int main(int argc, char *argv[])
Configure USHER and run its multiplexed UART/local-UDP event loop.
Definition usher.c:745
static struct camera_backend camera
Definition usher.c:521
static bool camera_warned[4]
Definition usher.c:525
static uint64_t clock_rejected_count
Definition usher.c:599
static void stop_local_serial_bridge(void)
Stop the owned simulator bridge and release the local lock.
Definition usher.c:3881
static uint64_t serial_receive_monotonic_us
Definition usher.c:583
static size_t soda_backlog_head
Definition usher.c:392
static void send_msg_cam_point(uint32_t camera_id, uint32_t session_id, const struct camera_point_result *point)
Cache and attempt to queue a terminal point-session result.
Definition usher.c:3186
#define LWIR_RETRY_POLL_US
Definition usher.c:120
static uint32_t control_high_water
Definition usher.c:380
static const char * pangea_directory
Definition usher.c:569
static void chdk_start_cooldown_locked(void)
Pause new CHDK attempts after a failed request; the caller holds mut.
Definition usher.c:2518
static bool set_exposure_latency(unsigned camera_id, const char *value)
Install a camera's calibrated exposure-to-delivery delay bounds.
Definition usher.c:650
static void event_wake_close(void)
Withdraw the wake descriptors and close the self-pipe.
Definition usher.c:455
static void start_pangea(void)
Launch optional mapping as a separate process with no inherited UART descriptors.
Definition usher.c:3254
static bool mock_map_enabled
Definition usher.c:564
static enum camera_stream_state camera_stream_states[CAMERA_BACKEND_MAX_ID+1]
Definition usher.c:598
static void drain_camera_backends(void)
Ask active streams and sessions to drain, then service remaining results.
Definition usher.c:3086
static void * recover_lwir_camera(void *unused)
Retry thermal startup outside both UART reception and the optical lane.
Definition usher.c:2243
static bool lwir_ready_or_start_recovery(void)
Check thermal readiness or start at most one background recovery attempt.
Definition usher.c:2308
static const char * pangea_camera_profile
Definition usher.c:570
static void handle_targeted_stop(uint32_t camera_id, uint32_t session_id)
Request the stop phase for a matching point session.
Definition usher.c:3139
static void drain_event_wake(void)
Consume pending wake hints without monopolizing the event loop.
Definition usher.c:445
#define SODA_BACKLOG_CAPACITY
Definition usher.c:100
static bool usher_running(void)
Read service cancellation state through the capture flag accessor.
Definition usher.c:556
static void * handle_lwir_shoot(void *pointer)
Own thermal capture and its last-frame metadata independently of optical work.
Definition usher.c:2398
static const char * mock_image
Definition usher.c:562
bool valid
Definition usher.c:537
static struct @340071115233262330352306106172115236376133177017 waiting_lwir
static bool earcam_requested
Definition usher.c:575
static uint64_t chdk_retry_after_us
Definition usher.c:385
static const char * pose_log_dir
Definition usher.c:589
static void stop_soda_backlog(void)
Join the analysis worker without draining session-only pending jobs.
Definition usher.c:3507
static bool lwir_handoff_in_progress
Definition usher.c:531
#define USHER_POSE_LOG_DIR
Definition usher.c:587
static bool start_chdk_worker(const union dc_shot_union *shoot, uint32_t request_id)
Schedule a shot on CHDK's independent capture lane.
Definition usher.c:2827
static int optical_camera_id
Definition usher.c:582
static bool prepare_session_backend(unsigned camera_id)
Ensure a point-session backend has a registered owner.
Definition usher.c:2139
static uint32_t control_nonce
Definition usher.c:380
static void * handle_chdk_finish(void *pointer)
Write metadata for one captured CHDK image after the camera lane was released.
Definition usher.c:2528
struct usher_control_result result
Definition usher.c:377
#define USHER_SODA_IDLE_MS
Definition usher.c:94
static volatile sig_atomic_t event_wake_writer
Definition usher.c:400
static int normalize_long_options(int argc, char *const argv[], char *normalized[], size_t capacity, const struct option_alias aliases[], size_t alias_count)
Translate supported long options into the short-option parser's input.
Definition usher.c:146
#define MAX_BACKEND_RESULTS_PER_PASS
Definition usher.c:114
static uint64_t clock_probe_count
Definition usher.c:599
#define USHER_SERIAL_DEVICE
Definition usher.c:123
static int event_wake_init(void)
Set up the self-pipe before installing its producers.
Definition usher.c:421
static void cameras_deinit(void)
Tear down registered cameras and independently owned analysis workers.
Definition usher.c:2384
static uint64_t shot_result_dropped
Definition usher.c:355
static uint32_t control_session
Definition usher.c:380
static void flush_control_results(void)
Pass dirty control receipts to the UART transmit queue.
Definition usher.c:2650
static volatile int image_idx
Definition usher.c:348
static int camera_register_stream(const struct camera_backend *backend)
Admit an optional stream once per owner, without opening its sensor.
Definition usher.c:2341
static void record_clocked_pose(void)
Validate and enqueue a token-bound pose sample with clock evidence.
Definition usher.c:704
static int event_wake_reader
Definition usher.c:399
static bool backend_service_pending
Definition usher.c:315
static const char * loomcam_references
Definition usher.c:311
static bool local_capture_only
Definition usher.c:542
static void lwir_mark_backoff(void)
Rate-limit thermal recovery so a missing USB camera does not consume every request.
Definition usher.c:2228
static uint64_t control_negotiated_us
Definition usher.c:382
static bool chdk_capture_in_progress
Definition usher.c:367
static pid_t pangea_pid
Definition usher.c:572
#define SERIAL_READ_BUFFER_SIZE
Definition usher.c:111
static pthread_cond_t camera_available
Definition usher.c:359
static int local_backend_shoot(char *filename, size_t filename_size, int image_number)
Capture a local fixture under the selected optical camera identity.
Definition usher.c:3791
static bool clock_probes_enabled
Definition usher.c:585
static bool soda_backlog_active
Definition usher.c:397
static void handle_control_message(void)
Process negotiation or dispatch an addressed control request.
Definition usher.c:2769
static pthread_mutex_t lwir_camera_mutex
Definition usher.c:358
static struct @222245117367130011346353214305367134373362342261 chdk_finish
static union usher_cam_point_update_union point_updates[CAMERA_BACKEND_MAX_ID]
Definition usher.c:313
static void sleep_microseconds(uint64_t microseconds)
Pause for an interval using nanosleep's remaining-time result.
Definition usher.c:635
static uint64_t soda_backlog_failed
Definition usher.c:394
static void flush_cam_points(void)
Submit unsent point-session results to the UART transmit queue.
Definition usher.c:3240
uint64_t received_us
Definition usher.c:536
static bool lwir_capture_in_progress
Definition usher.c:530
static pthread_mutex_t mut
Definition usher.c:350
uint64_t maximum_us
Definition usher.c:592
static const char * mock_map_cache
Definition usher.c:565
#define USHER_LOCAL_APP_DEVICE
Definition usher.c:214
static void defer_saved_analysis(const char *filename, const union dc_shot_union *shoot, int camera_id, const struct capture_timing *timing)
Submit a published image to the bounded saved-analysis backlog.
Definition usher.c:3456
static struct @124304315067051034320156230025020026251250036072 point_sessions[CAMERA_BACKEND_MAX_ID]
static void resolve_capture_pose(const union dc_shot_union *request, struct captured_image *image)
Resolve live pose evidence associated with an acquired image.
Definition usher.c:1850
static uint64_t monotonic_time_us(void)
Read USHER's monotonic clock for local latency and event ordering.
Definition usher.c:603
bool stop_requested
Definition usher.c:580
static void negotiate_camera_controls(void)
Establish or renew a camera-control lease from the current UART message.
Definition usher.c:2725
static bool camera_initialized[CAMERA_BACKEND_MAX_ID+1]
Definition usher.c:522
static bool admit_chdk_control_locked(const struct usher_control_request *request, uint64_t now)
Admit a control into the exclusive CHDK lane under mut.
Definition usher.c:2699
static void queue_control_result(const struct usher_control_result *result)
Stage a worker's result for serial transmission.
Definition usher.c:2633
static void send_clock_probe(uint64_t now_us)
Opportunistically send a low-priority flight-controller clock probe.
Definition usher.c:667
static bool chdk_finish_in_progress
Definition usher.c:373
static double mock_map_vertical_fov
Definition usher.c:567
static char image_buffer[MAX_IMAGE_BUFFERS][IMAGE_SIZE]
Definition usher.c:349
static const char * camera_source_image
Definition usher.c:547
static const char * pangea_pause_file
Definition usher.c:571
#define USHER_SODA_TIMEOUT_MS
Definition usher.c:91
static bool local_bridge_owned
Definition usher.c:549
#define USHER_MAX_PARSED_ARGUMENTS
Definition usher.c:89
static uint64_t next_job_ticket
Definition usher.c:361
static bool lwir_async_recovery_enabled
Definition usher.c:540
static volatile int shooting_thread_count
Definition usher.c:348
struct capture_job job
Definition usher.c:370
static uint64_t superseded_capture_count
Definition usher.c:398
static bool loomcam_enabled
Definition usher.c:310
#define MAX_IMAGE_BUFFERS
Definition usher.c:102
static void capture_job_release_locked(struct capture_job *job)
Return a job slot while the caller owns the pool mutex.
Definition usher.c:2985
static struct @207237136054161047266202115162153170331345340123 control_results[8]
static pthread_cond_t soda_available
Definition usher.c:396
static struct usher_control_request chdk_control_job
Definition usher.c:375
static bool point_update_pending[CAMERA_BACKEND_MAX_ID]
Definition usher.c:314
static void queue_image_results(uint32_t request_id, int32_t number, uint8_t camera_mask, uint32_t status)
Report a shared outcome separately for each addressed image camera.
Definition usher.c:492
#define SHOT_RESULT_CAPACITY
Definition usher.c:352
static void capture_arbiter_failed(const union dc_shot_union *shoot, uint8_t mask)
Release per-camera survey admission on a failure before normal completion.
Definition usher.c:2960
static struct soda_job soda_backlog[SODA_BACKLOG_CAPACITY]
Definition usher.c:391
static void * handle_msg_shoot(void *ptr)
Consume one optical ticket, then finish images outside the lane where safe.
Definition usher.c:1644
static bool camera_unavailable[4]
Definition usher.c:524
static int camera_backend_select(enum camera_backend_type type, bool test_mode)
Install the startup backend, optionally with local test hooks.
Definition usher.c:3763
static struct @072350163320177310065006100132072134337021011155 exposure_latency[4]
static void release_worker_slot(void)
End worker ownership after publication, distinct from releasing the capture ticket.
Definition usher.c:3623
static void handle_received_message(void)
Dispatch one complete UART frame without running slow camera work inline.
Definition usher.c:2004
static bool soda_backlog_stop
Definition usher.c:397
static bool chdk_async_capture_enabled
Definition usher.c:374
static uint64_t soda_busy_deferred_count
Definition usher.c:390
static size_t soda_backlog_count
Definition usher.c:392
static const char * loomcam_model
Definition usher.c:312
static void wake_event_loop(void)
Prompt the event loop to recheck shared state.
Definition usher.c:406
static void flush_shot_results(void)
Transfer a bounded batch of shot results to the UART transmit queue.
Definition usher.c:502
static void * handle_chdk_shoot(void *pointer)
Capture one CHDK request and release the camera lane before metadata is written.
Definition usher.c:2577
static bool mock_transform_enabled
Definition usher.c:563
uint32_t request_id
Definition usher.c:535
static bool lwir_recovery_in_progress
Definition usher.c:529
static void flush_cam_point_updates(void)
Publish fresh stream mailboxes without changing stopped-session result caches.
Definition usher.c:3228
static void notify_systemd_ready(void)
Send READY=1 to systemd when launched with a notify socket.
Definition usher.c:1594
static bool local_bridge_requested
Definition usher.c:548
static bool debug_enabled
Definition usher.c:573
#define USHER_LOCAL_LOCK_FILE
Definition usher.c:218
static int run_soda(const char *filename, const union dc_shot_union *shoot, int camera_id)
Run one analysis child directly with bounded runtime and termination grace.
Definition usher.c:3530
static double mock_map_horizontal_fov
Definition usher.c:566
#define USHER_SODA_RETRY_MS
Definition usher.c:97
#define DEBUG_HEARTBEAT_SECONDS
Definition usher.c:110
static struct camera_backend camera_owners[CAMERA_BACKEND_MAX_ID+1]
Definition usher.c:523
static void * handle_soda_backlog(void *unused)
Run saved-file analysis with fresh priority and idle catch-up.
Definition usher.c:3338
static uint64_t next_capture_ticket
Definition usher.c:361
static uint64_t clock_reply_count
Definition usher.c:599
#define CHDK_RETRY_COOLDOWN_US
Definition usher.c:387
static void send_msg_image_buffer(void)
Consume the newest buffered payload for a legacy image request.
Definition usher.c:3635
static volatile int image_count
Definition usher.c:348
static void print_usage(const char *program)
Print the invocation modes and build-specific defaults.
Definition usher.c:3673
static int local_lock_fd
Definition usher.c:561
#define SODA_SHUTDOWN_GRACE_MS
Definition usher.c:115
static pid_t socat_pid
Definition usher.c:560
static void * handle_chdk_control(void *pointer)
Execute an admitted lens command away from the serial owner.
Definition usher.c:2668
camera_stream_state
Definition usher.c:597
@ CAMERA_STREAM_DRAINED
Definition usher.c:597
@ CAMERA_STREAM_UNAVAILABLE
Definition usher.c:597
@ CAMERA_STREAM_CLOSED
Definition usher.c:597
@ CAMERA_STREAM_ACTIVE
Definition usher.c:597
static volatile int is_shooting
Definition usher.c:348
#define LWIR_WAIT_MAX_US
Definition usher.c:539
static enum camera_backend_type requested_camera_backend
Definition usher.c:520
uint64_t minimum_us
Definition usher.c:592
uint32_t id
Definition usher.c:577
static void defer_soda(const char *filename, const union dc_shot_union *shoot, int camera_id)
Queue analysis of a saved original without retaining camera or pixel buffers.
Definition usher.c:3443
#define EVENT_LOOP_TIMEOUT_MS
Definition usher.c:112
#define MAX_FILENAME
Definition usher.c:86
static size_t shot_result_head
Definition usher.c:354
static void send_msg_status(void)
Queue a snapshot of USHER's capture counters.
Definition usher.c:3653
static void send_msg_cam_point_update(uint32_t camera_id, const struct camera_point_result *point)
Keep only the newest stream result per camera across UART backpressure.
Definition usher.c:3210
static pthread_mutex_t shot_result_mutex
Definition usher.c:351
static pthread_mutex_t live_soda_mutex
Definition usher.c:389
static uint64_t lwir_busy_skipped_count
Definition usher.c:541
#define SODA_WAIT_INTERVAL_US
Definition usher.c:116
static void capture_job_release(struct capture_job *job)
Return a job slot from a worker that does not hold the pool lock.
Definition usher.c:2999
static void service_capture_arbiter(uint64_t now_us)
Bridge survey decisions to current backend readiness from the serial event loop.
Definition usher.c:3012
static struct clock_alignment fc_clock
Definition usher.c:584
static union usher_shot_result_union shot_results[SHOT_RESULT_CAPACITY]
Definition usher.c:353
static void camera_record_pose(const uint8_t *payload, uint16_t length)
Feed one acoustic sample from the pose stream while a listening session is open.
Definition usher.c:689
static void start_lwir_worker(const union dc_shot_union *shoot, uint32_t request_id, uint64_t received_us)
Dispatch a single-flight thermal request without waiting for USB recovery.
Definition usher.c:2448
static int lock_local_instance(void)
Reserve the shared local serial endpoint namespace.
Definition usher.c:3804
static bool camera_point_valid(const struct camera_point_result *point)
Check whether a backend result is suitable for the point wire format.
Definition usher.c:3172
#define CAPTURE_JOB_CAPACITY
Definition usher.c:362
static enum camera_backend_type configured_camera_backend
Definition usher.c:595
static uint64_t lwir_retry_after_us
Definition usher.c:528
bool dirty
Definition usher.c:378
#define USHER_LOCAL_SIM_DEVICE
Definition usher.c:127
static void start_shoot_worker(const union dc_shot_union *shoot, uint8_t camera_mask, uint32_t request_id)
Dispatch admitted image bits while preserving bounded legacy/local policies.
Definition usher.c:2866
static struct capture_job * capture_job_acquire_locked(void)
Reserve a zeroed slot in the bounded job pool.
Definition usher.c:2970
static enum camera_backend_type camera_type_for_id(int camera_id)
Resolve runtime routing without mutating the global selected backend.
Definition usher.c:2166
static bool test_capture_enabled
Definition usher.c:574
static uint64_t next_clock_probe_us
Definition usher.c:599
static pid_t start_local_serial_bridge(void)
Launch the PTY bridge for a hardware-free session.
Definition usher.c:3831
static struct capture_job capture_jobs[CAPTURE_JOB_CAPACITY]
Definition usher.c:363
static bool control_confirmed
Definition usher.c:381
#define MAX_PROCESSING_THREADS
Definition usher.c:87
static bool capture_image(const union dc_shot_union *shoot, struct captured_image *image, int camera_id, const struct camera_backend *backend)
Acquire pixels or a completed file for a single camera.
Definition usher.c:1726
static void camera_close_owner(unsigned camera_id)
Withdraw one backend from service and release its resources.
Definition usher.c:2364
static pthread_cond_t workers_finished
Definition usher.c:360
#define LWIR_RETRY_COOLDOWN_US
Definition usher.c:118
static const char * mock_lens_profile
Definition usher.c:568
static uint64_t last_photo_request_us
Definition usher.c:393
struct captured_image image
Definition usher.c:371
static bool motion_compensation_enabled
Definition usher.c:590
static uint64_t lwir_active_received_us
Definition usher.c:532
static void service_camera_backends(void)
Collect stream updates and completed point-session results.
Definition usher.c:3055
union dc_shot_union shot
Definition usher.c:534
static bool finish_image(const union dc_shot_union *shoot, struct captured_image *image)
Complete publication and metadata before releasing survey ownership.
Definition usher.c:1874
static int event_loop_timeout_ms(void)
Select the next event-loop polling budget.
Definition usher.c:615
static uint64_t soda_backlog_overflow
Definition usher.c:394
static uint32_t camera_control_capabilities(uint8_t camera_id)
Resolve the currently advertised control capabilities.
Definition usher.c:2621
static bool soda_backlog_started
Definition usher.c:397
static struct capture_job chdk_capture_job
Definition usher.c:366
static bool local_mode
Definition usher.c:519
static void stop_pangea(void)
Bound optional map-worker shutdown rather than waiting for its input backlog.
Definition usher.c:3322
static volatile int shooting_count
Definition usher.c:348
static bool wait_owned_child(pid_t *child, unsigned timeout_ms)
Poll an owned subprocess for exit.
Definition usher.c:3306
static struct capture_job * waiting_capture
Definition usher.c:365
static void handle_signal(int signal_number)
Request service shutdown from a signal handler.
Definition usher.c:3908
static struct camera_backend camera_identity_get(int camera_id)
Resolve metadata and hooks for a concrete protocol camera identity.
Definition usher.c:3751
struct usher_transport usher_protocol
void parse_usher(struct usher_transport *t, uint8_t c)
Consume one UART byte and advance a USHER transport parser. The public parameter and lifetime contrac...
Shared FC/MORA byte-stream UART framing, messages and payload layouts.
#define USHER_CAMERA_MASK_SUPPORTED
#define USHER_CAPTURE_ARBITER_STATE
#define USHER_CONTROL_HELLO_SIZE
#define USHER_STATUS
#define USHER_CAMERA_ALL
#define CAM_CONTROL_UNSUPPORTED
#define USHER_CAMERA_EARCAM
#define USHER_SHOT_FAILED
#define USHER_CLOCK_REPLY
#define USHER_CONTROL_COMMAND
#define USHER_STOP_TARGETED
#define USHER_CONTROL_VERSION
#define USHER_CAMERA_AICAM
#define USHER_SHOOT_MASK
#define CAM_CONTROL_FAILED
#define USHER_CLOCK_REQUEST
#define CAM_CONTROL_BUSY
#define USHER_CAPTURE_ARBITER_SHOOT
#define USHER_POSE_CLOCKED_MSG_SIZE
#define USHER_CONTROL_RESULT
#define USHER_CONTROL_HELLO
#define USHER_START_TARGETED
#define USHER_POSE_SAMPLE
#define USHER_PAYLOAD
#define USHER_CAMERA_MASK_NONE
#define CAM_CONTROL_EVIDENCE_NONE
#define USHER_CAPTURE_ARBITER_HELLO
#define USHER_CAM_POINT_RESULT
#define CAM_CONTROL_UNKNOWN
#define USHER_CAMERA_MASK_LWIR
#define USHER_STOP_TARGETED_MSG_SIZE
#define USHER_CAMERA_MASK_AICAM
#define CAM_CONTROL_INVALID_VALUE
#define USHER_SHOT_RECORDED
#define USHER_BUFFER_EMPTY
#define USHER_CAMERA_LWIRCAM
#define CAM_CONTROL_PENDING
#define STX
#define USHER_SHOT_SAVED
#define USHER_SHOT_UNSUPPORTED
#define CAM_CONTROL_CAP(command)
#define USHER_CONTROL_NEGOTIATE_SIZE
#define USHER_CAPTURE_ARBITER_RESULT
#define USHER_CAMERA_MASK_ALL
#define USHER_CAM_POINT_UPDATE
#define CAM_CONTROL_APPLIED
#define USHER_CONTROL_NEGOTIATE
#define USHER_CONTROL_RESULT_SIZE
#define USHER_CAM_POINT_VALID
#define USHER_POSE_CLOCKED
#define USHER_SHOT_SUPERSEDED
#define USHER_CAPTURE_ARBITER_VERSION
#define USHER_CAM_POINT_INVALID
#define USHER_CAMERA_CHDK
#define USHER_SHOT_RESULT
#define USHER_POSE_SAMPLE_MSG_SIZE
#define USHER_CAMERA_MASK_CHDK