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
dipla_camera_backend.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/** @file dipla_camera_backend.c
19 * @brief Nonblocking USHER-to-Diplacam process admission and reply supervision.
20 * @details Only the native worker owns field truth, GP state and inference.
21 * This adapter keeps the UART owner responsive by sending bounded local packets
22 * and publishing correlated completed replies, never waiting for a new plan. */
25#include <errno.h>
26#include <poll.h>
27#include <spawn.h>
28#include <stdio.h>
29#include <string.h>
30#include <sys/socket.h>
31#include <sys/wait.h>
32#include <time.h>
33#include <unistd.h>
34
35extern char **environ; /**< Inherited environment; executable/configuration remain explicit argv. */
36enum {
46};
47static char config_path[configuration_path_capacity]; /**< Owned configuration path, immutable while a worker is acquired. */
48static int descriptor = -1; /**< One private packet socket; minus one means no process channel. */
49static pid_t child = -1; /**< Sole child reaped by this owner, not by unrelated camera backends. */
50static uint32_t active_session, pending_number; /**< Distinct sortie and observation correlation tokens. */
51static uint32_t admitted_number, assimilated_number; /**< One unassimilated measurement credit, separate from point retrieval. */
53static bool reply_received;
54static uint64_t pending_since; /**< Monotonic admission time, not a worker/FC wall-clock timestamp. */
55static bool survey_lost; /**< Worker loss requires STOP before another survey can establish a geographic frame. */
56
57/** @brief Read elapsed-time evidence unaffected by changes to civil time.
58 * @return Monotonic milliseconds, or zero when a valid deadline cannot be formed. */
59static uint64_t milliseconds(void)
60{
61 struct timespec now;
62 if (clock_gettime(CLOCK_MONOTONIC, &now) != 0) return 0;
63 return (uint64_t)now.tv_sec * milliseconds_per_second + (uint64_t)now.tv_nsec / nanoseconds_per_millisecond;
64}
65
66bool dipla_camera_backend_setup(const char *configuration)
67{
68 const size_t length = configuration ? strnlen(configuration, sizeof(config_path)) : 0;
69 if (!length || length >= sizeof(config_path) || descriptor >= 0 || child > 0) return false;
70 for (size_t index = 0; index <= length; ++index) config_path[index] = configuration[index];
71 return true;
72}
73
74/** @brief Report explicit opt-in independently of process or model readiness. */
75static bool enabled(void) { return config_path[0] != '\0'; }
76/** @brief Expose only completion readiness to USHER's existing event poll. */
77static int completion_fd(void) { return descriptor; }
78/** @brief Admit one whole packet without blocking the UART owner.
79 * @param request Immutable stack-owned packet; no pointer survives this call.
80 * @return False on backpressure, a missing channel or an incomplete send.
81 * @details SOCK_SEQPACKET preserves boundaries, so a failed packet is not retried
82 * as an unsafely reconstructed suffix. The caller keeps session ownership. */
83static bool transmit(const struct dipla_request *request)
84{
85 if (descriptor < 0) return false;
86 ssize_t sent;
87 do { sent = send(descriptor, request, sizeof(*request), MSG_DONTWAIT | MSG_NOSIGNAL); } while (sent < 0 && errno == EINTR);
88 return sent == sizeof(*request);
89}
90
91/** @brief Invalidate requests before escalating worker shutdown and reaping it.
92 * @details Closing the channel prevents a late completion from reaching a new
93 * session. The polling grace permits ordinary teardown; SIGKILL contains a
94 * worker that does not respond. This is supervision, not a real-time guarantee. */
95static bool reap_child(unsigned timeout_ms)
96{
97 if (child <= 0) return true;
98 const uint64_t started = milliseconds();
99 for (;;) {
100 int status = 0;
101 const pid_t result = waitpid(child, &status, WNOHANG);
102 if (result == child || (result < 0 && errno == ECHILD)) { child = -1; return true; }
103 if (result < 0 && errno != EINTR) return false;
104 const uint64_t now = milliseconds();
105 if (!started || !now || now < started || now - started >= timeout_ms) return false;
106 if (poll(NULL, 0, shutdown_poll_ms) < 0 && errno != EINTR) return false;
107 }
108}
109
110/** @brief Close the planner channel, reset session state, and stop the child.
111 * @details Retain ownership if the child cannot be reaped even after
112 * escalation, so another planner cannot be launched over the old one. */
113static void deinit(void)
114{
115 if (descriptor >= 0) close(descriptor);
116 descriptor = -1;
119 reply_received = false;
120 survey_lost = false;
121 if (child > 0 && !reap_child(0)) {
122 kill(child, SIGTERM);
124 kill(child, SIGKILL);
126 fprintf(stderr, "USHER:\tdiplacam has not exited after SIGKILL; retaining child ownership\n");
127 }
128}
129
130/** @brief Spawn one native planner with a private, close-on-exec packet socket.
131 * @return Zero for an existing/started channel or a disabled backend; minus one on failure.
132 * @details The deliberately reserved child descriptor makes argv independent of
133 * the parent's transient descriptor numbers. Duplication clears CLOEXEC only
134 * for the endpoint the worker must retain; the parent's other endpoint is closed. */
135static int initialize(void)
136{
137 if (!enabled()) return 0;
138 if (survey_lost) return -1;
139 if (descriptor >= 0) return 0;
140 if (!reap_child(0)) return -1;
141 int channel[2];
142 if (socketpair(AF_UNIX, SOCK_SEQPACKET | SOCK_CLOEXEC, 0, channel) != 0) return -1;
143 posix_spawn_file_actions_t actions;
144 int result = posix_spawn_file_actions_init(&actions);
145 if (result) { close(channel[0]); close(channel[1]); return -1; }
146 const int worker_fd = worker_descriptor;
147 result = posix_spawn_file_actions_adddup2(&actions, channel[1], worker_fd);
148 if (!result && channel[0] != worker_fd) result = posix_spawn_file_actions_addclose(&actions, channel[0]);
149 if (!result && channel[1] != worker_fd) result = posix_spawn_file_actions_addclose(&actions, channel[1]);
150 char application[] = "./bin/diplacam", config_option[] = "--config", fd_option[] = "--ipc-fd";
151 char fd_text[sizeof("-2147483648")];
152 const int written = snprintf(fd_text, sizeof(fd_text), "%d", worker_fd);
153 if (written < 0 || (size_t)written >= sizeof(fd_text)) result = EINVAL;
154 char *arguments[] = {application, config_option, config_path, fd_option, fd_text, NULL};
155 if (!result) result = posix_spawn(&child, application, &actions, NULL, arguments, environ);
156 posix_spawn_file_actions_destroy(&actions);
157 close(channel[1]);
158 if (result) {
159 close(channel[0]); child = -1;
160 fprintf(stderr, "USHER:\tdiplacam start failed: %s\n", strerror(result));
161 return -1;
162 }
163 descriptor = channel[0];
164 return 0;
165}
166
167/** @brief Admit a nonzero session and discard correlation from the previous one.
168 * @param session Owner-selected session token, not a photo number.
169 * @return True for packet admission; it does not mean a plan is ready. */
170static bool start(uint32_t session)
171{
172 if (!session || !enabled()) return false;
173 if (survey_lost) { active_session = session; return false; }
174 if (initialize() != 0) return false;
175 const struct dipla_request request = {.version = DIPLA_IPC_VERSION, .operation = DIPLA_IPC_START, .session = session};
176 if (!transmit(&request)) return false;
178 pending_number = 0;
180 reply_received = false;
181 return true;
182}
183
184/** @brief End only the matching session, even if its stop packet cannot be sent.
185 * @param session Token returned to the owner at start admission.
186 * @return Whether the stop packet was admitted, or a lost survey was ended locally.
187 * @details Local invalidation is unconditional after the match so a lost stop
188 * cannot leave old replies eligible for a later sortie. */
189static bool stop(uint32_t session)
190{
191 if (!session || session != active_session) return false;
192 if (survey_lost) { survey_lost = false; active_session = pending_number = 0; return true; }
193 const struct dipla_request request = {.version = DIPLA_IPC_VERSION, .operation = DIPLA_IPC_STOP, .session = session};
194 const bool sent = transmit(&request);
195 deinit();
196 return sent;
197}
198
199/** @brief Retrieve a point and admit a new observation only when its credit is free.
200 * @param shot Immutable FC request; groundalt carries Q8 height above ground.
201 * @return Zero on packet admission, minus one while busy/disabled or on invalid input.
202 * @details One unassimilated measurement credit bounds evidence admission in
203 * addition to point-reply correlation. While it is occupied, point-only requests
204 * can read the retained route without admitting another measurement.
205 * A successful send does not imply ONNX finished or a navigation point exists. */
206static int record(const union dc_shot_union *shot)
207{
208 const uint64_t now = milliseconds();
209 if (!shot || shot->data.nr <= 0 || !active_session || survey_lost || !now) return -1;
210 if (pending_number && now - pending_since <= DIPLA_CYCLE_TIMEOUT_MS) return -1;
211 const bool observation_busy = admitted_number != assimilated_number;
212 const struct dipla_request request = {
213 .version = DIPLA_IPC_VERSION,
214 .operation = observation_busy ? DIPLA_IPC_POINT : DIPLA_IPC_CREDIT_SHOT, .session = active_session,
215 .number = (uint32_t)shot->data.nr, .lat = shot->data.lat, .lon = shot->data.lon,
216 .alt_mm = shot->data.alt, .agl_q8 = shot->data.groundalt
217 };
218 if (!transmit(&request)) return -1;
219 if (!observation_busy && request.number > admitted_number) admitted_number = request.number;
220 pending_number = request.number;
221 pending_since = now;
222 reply_received = false;
223 return 0;
224}
225
226/** @brief Drain a bounded reply batch and publish only the active request's result.
227 * @param point Destination changed only for a complete correlated reply.
228 * @return True for a completed valid or invalid point, false for no eligible reply.
229 * @details MSG_TRUNC detects oversized packets instead of accepting their prefix.
230 * The sixteen-packet work limit prevents stale traffic monopolizing the event
231 * loop. Credit and point packets may arrive in either order. Point completion
232 * does not wait for assimilation, and credits never become FC camera results. Quality 1000 denotes
233 * a valid computation, not physical accuracy. */
235{
236 if (!point || descriptor < 0) return false;
237 for (unsigned attempt = 0; attempt < reply_batch_limit; ++attempt) {
238 struct dipla_reply reply;
239 const ssize_t count = recv(descriptor, &reply, sizeof(reply), MSG_DONTWAIT | MSG_TRUNC);
240 if (count < 0 && (errno == EAGAIN || errno == EWOULDBLOCK)) break;
241 if (count < 0 && errno == EINTR) continue;
242 if (count != sizeof(reply) || reply.version != DIPLA_IPC_VERSION || reply.valid > 1) {
243 const uint32_t lost_session = active_session;
244 deinit();
245 if (lost_session) {
246 active_session = lost_session;
247 survey_lost = true;
248 fprintf(stderr, "USHER:\tdiplacam survey lost; STOP required before a new anchor\n");
249 }
250 return false;
251 }
252 if (reply.session == active_session && reply.number == admitted_number && !reply.valid &&
255 continue;
256 }
257 if (reply.session != active_session || reply.number != pending_number) continue;
258 pending_reply = reply;
259 reply_received = true;
260 }
261 if (!reply_received) return false;
262 const struct dipla_reply reply = pending_reply;
263 const uint64_t now = milliseconds();
264 const bool valid = reply.valid && now && now - pending_since <= DIPLA_CYCLE_TIMEOUT_MS && reply.metric >= (int32_t)DIPLA_WAYPOINT_COUNT &&
265 reply.lat >= -DIPLA_LATITUDE_LIMIT && reply.lat <= DIPLA_LATITUDE_LIMIT &&
266 reply.lon >= -DIPLA_LONGITUDE_LIMIT && reply.lon <= DIPLA_LONGITUDE_LIMIT &&
268 pending_number = 0;
269 reply_received = false;
270 *point = (struct camera_point_result) {
271 .session_id = reply.number, .valid = valid,
272 .lat = reply.lat, .lon = reply.lon, .alt_mm = reply.alt_mm, .agl_mm = reply.agl_mm,
273 .quality = valid ? computational_validity_quality : 0, .metric = reply.metric
274 };
275 return true;
276}
277
278/** @brief Stop the selected session and reap the worker during owner shutdown. */
279static void drain(void) { if (active_session) stop(active_session); deinit(); }
280/** @brief Acquire the worker without opening any optical camera.
281 * @param source Unused image-source argument from the common backend interface.
282 * @return Result of local worker acquisition. */
283static int init(const char *source) { (void)source; return initialize(); }
284
286{
287 static const struct camera_point_stream_ops stream = {
288 .init = initialize, .poll_result = poll_result, .drain = drain,
289 .start = start, .stop = stop, .enabled = enabled, .completion_fd = completion_fd
290 };
291 return (struct camera_backend) {
292 .name = "diplacam", .camera_id = DIPLA_CAMERA_ID, .capabilities = CAMERA_CAP_POINT_STREAM,
293 .record = record, .init = init, .deinit = deinit, .point_stream = &stream
294 };
295}
char ** environ
@ CAMERA_CAP_POINT_STREAM
static uint32_t session
int descriptor
Definition chdk_pipe.c:142
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
static char config_path[configuration_path_capacity]
static bool poll_result(struct camera_point_result *point)
Drain a bounded reply batch and publish only the active request's result.
static bool start(uint32_t session)
Admit a nonzero session and discard correlation from the previous one.
static int initialize(void)
Spawn one native planner with a private, close-on-exec packet socket.
static void deinit(void)
Close the planner channel, reset session state, and stop the child.
static int init(const char *source)
Acquire the worker without opening any optical camera.
static uint64_t milliseconds(void)
Read elapsed-time evidence unaffected by changes to civil time.
static uint32_t active_session
static bool reap_child(unsigned timeout_ms)
Invalidate requests before escalating worker shutdown and reaping it.
@ worker_descriptor
@ shutdown_kill_grace_ms
@ milliseconds_per_second
@ reply_batch_limit
@ shutdown_term_grace_ms
@ configuration_path_capacity
@ shutdown_poll_ms
@ nanoseconds_per_millisecond
@ computational_validity_quality
static int completion_fd(void)
Expose only completion readiness to USHER's existing event poll.
static bool transmit(const struct dipla_request *request)
Admit one whole packet without blocking the UART owner.
static struct dipla_reply pending_reply
static pid_t child
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
static void drain(void)
Stop the selected session and reap the worker during owner shutdown.
static bool reply_received
bool dipla_camera_backend_setup(const char *configuration)
Select the worker experiment before acquiring its process.
static uint32_t pending_number
static bool enabled(void)
Report explicit opt-in independently of process or model readiness.
static uint64_t pending_since
static uint32_t admitted_number
static uint32_t assimilated_number
struct camera_backend dipla_camera_backend_get(void)
Describe camera slot five without starting work.
static bool survey_lost
static bool stop(uint32_t session)
End only the matching session, even if its stop packet cannot be sent.
Optional non-image camera adapter for the native Diplacam worker.
#define DIPLA_FLIGHT_HEIGHT_MAX_MM
#define DIPLA_WAYPOINT_COUNT
#define DIPLA_LATITUDE_LIMIT
#define DIPLA_FLIGHT_HEIGHT_MIN_MM
#define DIPLA_LONGITUDE_LIMIT
Private local worker messages; not a flight-controller wire protocol.
#define DIPLA_IPC_CREDIT_SHOT
Definition dipla_ipc.h:32
#define DIPLA_IPC_POINT
Definition dipla_ipc.h:33
#define DIPLA_IPC_VERSION
Definition dipla_ipc.h:27
#define DIPLA_CAMERA_ID
Definition dipla_ipc.h:35
#define DIPLA_IPC_ASSIMILATED_METRIC
Definition dipla_ipc.h:34
#define DIPLA_IPC_START
Definition dipla_ipc.h:28
#define DIPLA_IPC_STOP
Definition dipla_ipc.h:29
#define DIPLA_CYCLE_TIMEOUT_MS
Definition dipla_ipc.h:38
union dc_shot_union request
static bool started
static size_t count
Definition pose_log.c:79
Function table describing one backend's owned camera operations.
Repeated correlated point updates from saved photos or non-image work.
Legacy one-point retrieval from a generation pinned across eight slots.
Definition dipla_ipc.h:59
uint32_t number
Exact observation echo; a retry must not consume another slot.
Definition dipla_ipc.h:66
uint32_t valid
Definition dipla_ipc.h:66
int32_t agl_mm
Configured physical flight height in millimetres; default 2000.
Definition dipla_ipc.h:75
int32_t lon
Proposed geographic longitude in degrees times 1e7.
Definition dipla_ipc.h:75
int32_t lat
Proposed geographic latitude in degrees times 1e7.
Definition dipla_ipc.h:75
int32_t alt_mm
Unchanged owner-supplied FC altitude in millimetres, not predicted model Z.
Definition dipla_ipc.h:75
int32_t metric
Definition dipla_ipc.h:75
uint32_t session
Exact session echo; prevents accepting a previous sortie's completion.
Definition dipla_ipc.h:66
uint32_t version
Reply layout version, checked before accepting any result.
Definition dipla_ipc.h:66
Pose/control request; session and observation number have separate lifetimes.
Definition dipla_ipc.h:42
One timestamped geographic position for a replay annotation.
bool valid
Definition usher.c:537
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534