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
loom_cam.h
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 loom_cam.h
20 * @brief Bounded asynchronous saved-photo adapter for LOOM_cam.
21 * @details USHER's capture owner supplies immutable, EXIF-tagged AIcam photos.
22 * This adapter records outbound references or runs a saved-photo child; it does
23 * not own the sensor, transmit UART or mutate waypoints. One pending request and
24 * one completion mailbox prioritize freshness over processing every photograph.
25 * @details Each START creates a unique reference subdirectory, retaining only
26 * that sortie's links for its return phase. A per-sortie cap bounds directory
27 * growth without pruning evidence. Phase tokens select collection/return modes;
28 * FC photo numbers correlate individual results. Keeping those identities separate prevents old mode work
29 * from looking like a fresh candidate route point after START or STOP.
30 * @warning Accepted points require a declared return model and validated observation evidence.
31 */
32#ifndef USHER_LOOM_CAM_H
33#define USHER_LOOM_CAM_H
34
35#include "camera_backend.h"
36
37/** @brief LOOM photographs and outbound references use 'o', not AIcam's 'a'. */
38#define LOOM_IMAGE_PREFIX 'o'
39
40/**
41 * @brief Start one saved-photo worker; does not acquire another camera.
42 * @param references Optional outbound-photo directory, copied before return.
43 * @param model Optional native capture RPK path, copied before return.
44 * @return Zero on startup, -1 for invalid paths or worker setup failure.
45 * @details Starts in return mode; only the configured current-photo model vector
46 * is interpreted. Outbound references are retained but are not yet compared.
47 * NULL paths select empty configuration; overlong paths are rejected, not truncated.
48 * @pre Lifecycle calls are serialized by the owning USHER control thread.
49 */
50int loom_cam_init(const char *references, const char *model);
51/** @brief Select executable settings before starting the saved-photo worker.
52 * @param settings Copied path or NULL to restore executable discovery.
53 * @return Zero when accepted, minus one while running or for an invalid path. */
54int loom_cam_set_settings(const char *settings);
55/**
56 * @brief Report whether this optional stream is running and not stopping.
57 * @return True when phase callbacks may be admitted; false otherwise.
58 * @note Uses atomic lifecycle flags; no camera acquisition or mutex wait occurs.
59 */
60bool loom_cam_enabled(void);
61/** @brief Borrow the nonblocking completion descriptor; minus one when not initialized. */
63/**
64 * @brief Select outbound reference collection and discard old-phase mailbox work.
65 * @param session_id Admitted nonzero FC session token, not a photo number.
66 * @return True if accepted by a running worker; false for zero or shutdown.
67 * @details Advances a phase generation to suppress in-flight old-phase results.
68 * The original photo archive remains authoritative if reference work is dropped.
69 */
70bool loom_cam_start(uint32_t session_id);
71/**
72 * @brief Select return matching and discard old-phase mailbox work.
73 * @param session_id Nonzero token matching the most recently admitted START.
74 * @return True if the token is accepted; false if absent, mismatched or stopping.
75 * @note Acceptance changes local mode; it does not prove a neural match exists.
76 */
77bool loom_cam_stop(uint32_t session_id);
78/**
79 * @brief Copy the newest completed AIcam photo request into bounded worker storage.
80 * @param filename Immutable saved JPEG path, borrowed only for this call.
81 * @param shot Completed photo pose/request; its positive number correlates the update.
82 * @details Thread-safe and nonblocking; pending work is fresh-first, not an evidence archive.
83 * Busy admission, invalid input, overlong paths and duplicate/reversed photo
84 * numbers are dropped. The file itself must remain available to the worker.
85 */
86void loom_cam_image_saved(const char *filename, const union dc_shot_union *shot);
87/**
88 * @brief Consume a result on the serial owner; session_id carries the photo number for this stream.
89 * @param result Required destination in existing point units.
90 * @return True for a new matched or no-match result; false when absent/busy.
91 * @details Consumes the single mailbox entry. True means a completion exists,
92 * not that result->valid is true; FC navigation checks must still be applied.
93 */
95/**
96 * @brief Cancel pending work and join the worker before reusing adapter state.
97 * @details Wakes an idle worker or causes its child watchdog to terminate/reap
98 * the process. Unlike admission/polling, shutdown waits for the worker to exit.
99 * @pre Lifecycle calls are serialized; do not call from the worker itself.
100 */
101void loom_cam_deinit(void);
102
103#endif
Shared capability and lifecycle contract for USHER camera backends.
bool loom_cam_poll_result(struct camera_point_result *result)
Consume a result on the serial owner; session_id carries the photo number for this stream.
Definition loom_cam.c:685
bool loom_cam_start(uint32_t session_id)
Select outbound reference collection and discard old-phase mailbox work.
Definition loom_cam.c:621
bool loom_cam_stop(uint32_t session_id)
Select return matching and discard old-phase mailbox work.
Definition loom_cam.c:652
void loom_cam_deinit(void)
Cancel pending work and join the worker before reusing adapter state.
Definition loom_cam.c:695
int loom_cam_set_settings(const char *settings)
Select executable settings before starting the saved-photo worker.
Definition loom_cam.c:560
bool loom_cam_enabled(void)
Report whether this optional stream is running and not stopping.
Definition loom_cam.c:608
void loom_cam_image_saved(const char *filename, const union dc_shot_union *shot)
Copy the newest completed AIcam photo request into bounded worker storage.
Definition loom_cam.c:669
int loom_cam_completion_fd(void)
Borrow the nonblocking completion descriptor; minus one when not initialized.
Definition loom_cam.c:613
int loom_cam_init(const char *references, const char *model)
Start one saved-photo worker; does not acquire another camera.
Definition loom_cam.c:568
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534