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
camera_backend.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 camera_backend.h
20 * @brief Shared capability and lifecycle contract for USHER camera backends.
21 * @details USHER owns scheduling, UART admission, and common photo completion;
22 * a backend owns only its device/process work and advertises optional behavior
23 * through capabilities. Keeping this boundary explicit prevents a camera
24 * adapter from silently taking over unrelated backends' capture semantics.
25 */
26#ifndef USHER_CAMERA_BACKEND_H
27#define USHER_CAMERA_BACKEND_H
28
29#include <signal.h>
30#include "camera_capture.h"
31#include "capture_timing.h"
32
34
35/** @brief Backend features and shared completion ownership.
36 * @details CAMERA_CAP_PRIVATE_IMAGE returns paths from usher_prepare_photo.
37 * Shared completion publishes them only after all metadata writes succeed.
38 * Direct capture callers must likewise complete or retain those private files. */
49
51 uint32_t session_id;
52 bool valid;
54};
55
57 bool (*start)(uint32_t session_id);
58 bool (*stop)(uint32_t session_id);
59 bool (*listening)(void);
60 int (*completion_fd)(void);
62 void (*drain)(void);
63};
64
65/** @brief Repeated correlated point updates from saved photos or non-image work.
66 * @details Result session_id is the positive FC photo number for this stream;
67 * the transport uses its explicit frame_number field, not a session token. */
69 /** Initialize optional analysis independently of lazy sensor acquisition. */
70 int (*init)(void);
72 void (*drain)(void);
73 bool (*start)(uint32_t session_id);
74 bool (*stop)(uint32_t session_id);
75 bool (*enabled)(void);
76 int (*completion_fd)(void);
77};
78
80 /** @brief Borrowed shutdown flag; backend workers must stop when it clears. */
81 const volatile sig_atomic_t *running;
82 /** @brief Bounded pose lookup supplied by USHER's shared timing owner. */
83 bool (*pose_lookup)(struct capture_observation *observation, uint64_t maximum_age_us);
84 /** @brief Queue optional analysis after image ownership has been established. */
85 void (*queue_analysis)(const char *filename, const union dc_shot_union *shot, int camera_id);
86};
87
88/**
89 * @brief Function table describing one backend's owned camera operations.
90 * @details Required capture hooks are selected by the advertised capability
91 * bits. Optional sessions, point streams, controls, and analysis hooks remain
92 * backend-owned; USHER does not infer support from a camera ID or name.
93 */
95 /** @brief Stable backend name used for logs and diagnostics. */
96 const char *name;
97 /** @brief Initialize backend resources; optional mock image path is borrowed. */
98 int (*init)(const char *source_image);
99 /** @brief Trigger one photo and return the backend's owned staging path. */
100 int (*shoot)(char *filename, size_t filename_size, int image_number);
101 /** @brief Release backend resources and reap owned children. */
102 void (*deinit)(void);
103 /** @brief Optional SODA application name for this backend's saved files. */
104 const char *soda_application;
105 /** @brief Optional split-phase capture lifecycle. */
107 uint8_t camera_id;
108 char prefix;
109 /** Backend-owned geometry and namespace for shared simulation capture. */
110 struct {
111 size_t width, height;
112 const char *filename_marker;
114 unsigned capabilities;
115 const char *soda_option;
116 int (*init_cancelable)(const char *source_image, const volatile sig_atomic_t *running);
117 int (*record)(const union dc_shot_union *shot);
119 void (*configure)(const struct camera_backend_host *host);
120 void (*pose_updated)(void);
121 double (*capture_delay)(void);
122 struct capture_timing(*capture_timing)(void);
123 int (*geolocate)(char *filename);
124 bool (*bind_frame)(uint64_t sequence, uint64_t sensor_timestamp_ns);
125 void (*detection_summary)(char *buffer, size_t size);
126 void (*save_detection_copy)(const char *filename);
127 const char *photo_directory;
128 /** Optional post-publication hook; may enqueue work but must not wait for inference. */
129 void (*image_saved)(const char *filename, const union dc_shot_union *shot);
130 /** @brief Optional repeated point stream, independent of start/stop sessions. */
132 /** @brief Bitset of controls supported by this backend; zero means none. */
134 /** @brief Initialize control-only ownership without forcing photo capture setup. */
135 int (*control_init)(void);
136 /** @brief Execute one validated control and return command-specific evidence. */
137 uint8_t (*control)(uint8_t command, uint8_t value, uint8_t *observed, uint8_t *evidence);
138};
139
140#endif
camera_capability
Backend features and shared completion ownership.
@ 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
Optional split-phase capture contract for USHER image backends.
Sensor observation times, aligned poses, and optional frame-arrival evidence.
size_t size
Definition chdk_pipe.c:143
static char source_image[PATH_MAX]
Definition local_pipe.c:53
static const volatile sig_atomic_t * running
char evidence[8192]
Definition lwir_image.c:66
void(* queue_analysis)(const char *filename, const union dc_shot_union *shot, int camera_id)
Queue optional analysis after image ownership has been established.
bool(* pose_lookup)(struct capture_observation *observation, uint64_t maximum_age_us)
Bounded pose lookup supplied by USHER's shared timing owner.
const volatile sig_atomic_t * running
Borrowed shutdown flag; backend workers must stop when it clears.
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)
int(* init_cancelable)(const char *source_image, const volatile sig_atomic_t *running)
struct capture_timing(* capture_timing)(void)
unsigned capabilities
double(* capture_delay)(void)
const struct camera_capture_ops * capture_ops
Optional split-phase capture lifecycle.
const char * photo_directory
const char * soda_application
Optional SODA application name for this backend's saved files.
const char * filename_marker
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.
struct camera_backend::@243120217343377347337244154071360217343172026241 mock
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.
int(* control_init)(void)
Initialize control-only ownership without forcing photo capture setup.
void(* configure)(const struct camera_backend_host *host)
const char * soda_option
const struct camera_point_stream_ops * point_stream
Optional repeated point stream, independent of start/stop sessions.
uint32_t control_capabilities
Bitset of controls supported by this backend; zero means none.
const char * name
Stable backend name used for logs and diagnostics.
void(* pose_updated)(void)
uint8_t(* control)(uint8_t command, uint8_t value, uint8_t *observed, uint8_t *evidence)
Execute one validated control and return command-specific evidence.
Driver capabilities whose table must outlive every pending image.
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)
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534