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
imx500_pipe.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 imx500_pipe.c
19 * @brief Neutral native camera-worker supervision, independent of model results.
20 * @details Keep process transport separate from inference interpretation. The
21 * same READY/SHOT/OK exchange serves detector and LOOM owners without inventing
22 * object results for a feature-only capture. */
23#include "imx500_pipe.h"
24#include "camera_capture.h"
25#include "path_utils.h"
26
27#include <errno.h>
28#include <fcntl.h>
29#include <limits.h>
30#include <poll.h>
31#include <signal.h>
32#include <spawn.h>
33#include <stdio.h>
34#include <stdlib.h>
35#include <string.h>
36#include <sys/socket.h>
37#include <sys/stat.h>
38#include <sys/wait.h>
39#include <time.h>
40#include <unistd.h>
41
42/** @brief First-use RPK upload/warm-up needs more time than a warm still capture. */
43#define IMX500_STARTUP_TIMEOUT_MS 180000
44/** @brief Bound response waiting so an abandoned shot cannot block the owner indefinitely. */
45#define IMX500_SHOT_TIMEOUT_MS 15000
46/** @brief Fixed space for short protocol replies, never arbitrary child diagnostics. */
47#define IMX500_RESPONSE_BYTES 16
48#define IMX500_EXIT_GRACE_MS 2000
49#define IMX500_KILL_GRACE_MS 1000
50
51/** @brief Inherit the process environment; executable and model remain explicit argv. */
52extern char **environ;
53
54/** @brief Read elapsed-time evidence unaffected by wall-clock corrections.
55 * @return Monotonic milliseconds, or -1 if a deadline cannot be established. */
56static int64_t milliseconds(void)
57{
58 struct timespec now;
59 if (clock_gettime(CLOCK_MONOTONIC, &now) != 0) {
60 return -1;
61 }
62 return (int64_t)now.tv_sec * 1000 + now.tv_nsec / 1000000;
63}
64
65/** @brief Consume one exact line before an unchanged monotonic response deadline.
66 * @param[in,out] pipe State containing the nonblocking status descriptor.
67 * @param[in] expected Complete expected line, including its newline.
68 * @param[in] timeout Response allowance in milliseconds.
69 * @return Zero for an exact line, otherwise -1.
70 * @details Bytewise reads are cheap for these tiny replies and do not steal bytes
71 * belonging to a later exchange. EINTR retries retain the original deadline. */
72static int expect_response(struct imx500_pipe *pipe, const char *expected, int timeout)
73{
74 const int64_t start = milliseconds();
75 if (start < 0) {
76 return -1;
77 }
79 size_t length = 0;
80 while (length + 1 < sizeof(response)) {
81 if (!capture_running(pipe->running)) return -1;
82 const int64_t now = milliseconds();
83 if (now < start || now - start >= timeout) {
84 return -1;
85 }
86 struct pollfd descriptor = {.fd = pipe->socket, .events = POLLIN};
87 int wait_ms = timeout - (int)(now - start);
88 if (pipe->running && wait_ms > 100) wait_ms = 100;
89 const int ready = poll(&descriptor, 1, wait_ms);
90 if (ready < 0 && errno == EINTR) {
91 continue;
92 }
93 if (ready == 0) continue;
94 if (ready < 0) {
95 return -1;
96 }
97 const ssize_t bytes = read(pipe->socket, response + length, 1);
98 if (bytes < 0 && (errno == EINTR || errno == EAGAIN)) {
99 continue;
100 }
101 if (bytes != 1) {
102 return -1;
103 }
104 if (response[length++] == '\n') {
105 response[length] = '\0';
106 return strcmp(response, expected) == 0 ? 0 : -1;
107 }
108 }
109 return -1;
110}
111
112/** @brief Poll for exit of the camera child.
113 * @param[in,out] pipe Subprocess owner; clears the PID once ownership ends.
114 * @param timeout_ms Polling budget in milliseconds.
115 * @return True when no child remains owned.
116 * @details Leave the PID intact on timeout or hard wait errors so callers
117 * cannot launch another sensor owner while the previous child may be alive. */
118static bool reap_owned_camera(struct imx500_pipe *pipe, int timeout_ms)
119{
120 if (pipe->pid <= 0) return true;
121 const int64_t started = milliseconds();
122 for (;;) {
123 const pid_t result = waitpid(pipe->pid, NULL, WNOHANG);
124 if (result == pipe->pid || (result < 0 && errno == ECHILD)) { pipe->pid = -1; return true; }
125 if (result < 0 && errno != EINTR) return false;
126 const int64_t now = milliseconds();
127 if (started < 0 || now < started || now - started >= timeout_ms) return false;
128 if (poll(NULL, 0, 20) < 0 && errno != EINTR) return false;
129 }
130}
131
133{
134 if (!pipe) {
135 return;
136 }
137 if (pipe->socket >= 0) {
138 /* EOF is the healthy worker's shutdown request; close it before escalating. */
139 close(pipe->socket);
140 }
141 pipe->socket = -1;
143 kill(pipe->pid, SIGKILL);
145 fprintf(stderr, "IMX500_CAPTURE:\tkilled worker has not exited; retaining process ownership\n");
146 }
147}
148
150{
151 if (!pipe || !pipe->command || !pipe->command[0] ||
152 (pipe->photo_only && (pipe->analyze || pipe->settings || pipe->model)) ||
153 (!pipe->photo_only && ((!pipe->settings || !pipe->settings[0]) && (!pipe->model || !pipe->model[0]))) ||
154 (!pipe->analyze && (!pipe->directory || pipe->prefix < 'a' || pipe->prefix > 'z'))) {
155 return -1;
156 }
157 imx500_pipe_stop(pipe);
158 if (pipe->pid > 0 || !capture_running(pipe->running)) return -1;
159 /* A full-duplex private channel avoids shell quoting and shared stdout parsing. */
160 int sockets[2];
161 if (socketpair(AF_UNIX, SOCK_STREAM, 0, sockets) != 0) {
162 return -1;
163 }
164 for (size_t index = 0; index < 2; ++index) {
165 /* Keep endpoints above stdio before dup2, even when the parent had closed fd 0 or 1. */
166 const int descriptor = fcntl(sockets[index], F_DUPFD_CLOEXEC, 3);
167 close(sockets[index]);
168 sockets[index] = descriptor;
169 if (descriptor < 0) {
170 close(sockets[1 - index]);
171 return -1;
172 }
173 }
174 posix_spawn_file_actions_t actions;
175 int status = posix_spawn_file_actions_init(&actions);
176 if (status == 0) {
177 status = posix_spawn_file_actions_adddup2(&actions, sockets[1], STDIN_FILENO);
178 if (status == 0) {
179 status = posix_spawn_file_actions_adddup2(&actions, sockets[1], STDOUT_FILENO);
180 }
181 if (status == 0) {
182 status = posix_spawn_file_actions_addclose(&actions, sockets[0]);
183 }
184 if (status == 0) {
185 status = posix_spawn_file_actions_addclose(&actions, sockets[1]);
186 }
187 char *arguments[] = {(char *)pipe->command, "--serve", (char *)pipe->model,
189 char *configured[] = {(char *)pipe->command, pipe->analyze ? "--analyze-server" : "--serve",
190 "--settings", (char *)pipe->settings, pipe->analyze ? "--private-images" : USHER_AI_CAM_WIDTH,
191 pipe->analyze ? NULL : USHER_AI_CAM_HEIGHT, NULL};
192 char *photo_only[] = {(char *)pipe->command, "--photo-only", "--serve",
194 if (status == 0) {
195 pid_t spawned = -1;
196 status = posix_spawnp(&spawned, arguments[0], &actions, NULL,
197 pipe->photo_only ? photo_only : pipe->settings ? configured : arguments, environ);
198 if (!status) pipe->pid = spawned;
199 }
200 posix_spawn_file_actions_destroy(&actions);
201 }
202 close(sockets[1]);
203 pipe->socket = sockets[0];
204 /* Spawn success is not readiness: the child's selected processor must qualify a frame. */
205 if (status != 0 || fcntl(pipe->socket, F_SETFL, O_NONBLOCK) < 0
206 || expect_response(pipe, "READY\n", IMX500_STARTUP_TIMEOUT_MS) != 0) {
207 fprintf(stderr, "IMX500_CAPTURE:\tstartup failed: %s\n", pipe->command);
208 imx500_pipe_stop(pipe);
209 return -1;
210 }
211 return 0;
212}
213
214/** @brief Send one request before a single absolute deadline, including partial writes. */
215static bool send_request(struct imx500_pipe *pipe, const char *request, size_t length)
216{
217 const int64_t start = milliseconds();
218 if (start < 0) return false;
219 size_t sent = 0;
220 while (sent < length) {
221 if (!capture_running(pipe->running)) return false;
222 const int64_t now = milliseconds();
223 if (now < start || now - start >= 2000) return false;
224 struct pollfd descriptor = {.fd = pipe->socket, .events = POLLOUT};
225 int wait_ms = 2000 - (int)(now - start);
226 if (pipe->running && wait_ms > 100) wait_ms = 100;
227 const int ready = poll(&descriptor, 1, wait_ms);
228 if (ready < 0 && errno == EINTR) continue;
229 if (!ready) continue;
230 if (ready < 0 || (descriptor.revents & (POLLERR | POLLHUP | POLLNVAL))) return false;
231 const ssize_t bytes = send(pipe->socket, request + sent, length - sent, MSG_NOSIGNAL);
232 if (bytes < 0 && (errno == EINTR || errno == EAGAIN || errno == EWOULDBLOCK)) continue;
233 if (bytes <= 0) return false;
234 sent += (size_t)bytes;
235 }
236 return true;
237}
238
239int imx500_pipe_analyze(struct imx500_pipe *pipe, const char *filename, unsigned number)
240{
241 if (!pipe || !pipe->analyze || pipe->socket < 0 || !filename || !number ||
242 strchr(filename, '\n') || strchr(filename, '\r')) return -1;
243 char request[PATH_MAX + 64];
244 const int count = snprintf(request, sizeof(request), "ANALYZE %u %s\n", number, filename);
245 if (count < 0 || (size_t)count >= sizeof(request)) return -1;
246 if (send_request(pipe, request, (size_t)count) && expect_response(pipe, "OK\n", IMX500_SHOT_TIMEOUT_MS) == 0) return 0;
247 imx500_pipe_stop(pipe);
248 return -1;
249}
250
251int imx500_pipe_shoot(struct imx500_pipe *pipe, char *filename, size_t capacity, int number)
252{
253 if (!pipe || !filename || capacity == 0 || number < 0) {
254 return -1;
255 }
256 filename[0] = '\0';
257 char resolved[PATH_MAX];
258 const char *directory = usher_resolve_path(pipe->directory, resolved, sizeof(resolved));
259 if (usher_ensure_directory(directory) != 0) {
260 return -1;
261 }
262 char absolute[PATH_MAX];
263 /* Resolve the parent-selected directory once; the child receives no relative path policy. */
264 if (!realpath(directory, absolute)) {
265 return -1;
266 }
267 int length = snprintf(filename, capacity, "%s/%c%06d.jpg", absolute, pipe->prefix, number);
268 char request[PATH_MAX + 16];
269 if (length < 0 || (size_t)length >= capacity || strchr(filename, '\n') || strchr(filename, '\r')
270 || usher_prepare_photo(filename, capacity) != 0) {
271 filename[0] = '\0';
272 return -1;
273 }
274 length = snprintf(request, sizeof(request), "SHOT %s\n", filename);
275 if (length < 0 || (size_t)length >= sizeof(request)) {
276 filename[0] = '\0';
277 return -1;
278 }
279 if (pipe->socket < 0 && imx500_pipe_start(pipe) != 0) {
280 filename[0] = '\0';
281 return -1;
282 }
283 struct stat image;
284 /* A response alone cannot authorize publication. Keep the file check separate
285 * from model-specific metadata validation, which belongs above this supervisor. */
286 if (!send_request(pipe, request, (size_t)length) || expect_response(pipe, "OK\n", IMX500_SHOT_TIMEOUT_MS) != 0
287 || stat(filename, &image) != 0 || !S_ISREG(image.st_mode) || image.st_size <= 0) {
288 imx500_pipe_stop(pipe);
289 filename[0] = '\0';
290 return -1;
291 }
292 return 0;
293}
#define USHER_AI_CAM_HEIGHT
Definition ai_cam_pipe.c:60
static void wait_ms(int milliseconds)
Wait until a short polling interval elapses.
char ** environ
#define USHER_AI_CAM_WIDTH
Definition ai_cam_pipe.c:57
Optional split-phase capture contract for USHER image backends.
static bool capture_running(const volatile sig_atomic_t *running)
Atomically poll a borrowed cancellation flag; NULL means no cancellation.
static unsigned capacity[COVERAGE_CAMERAS]
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
int descriptor
Definition chdk_pipe.c:142
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
static bool start(uint32_t session)
Admit a nonzero session and discard correlation from the previous one.
union dc_shot_union request
static bool started
static bool ready
static bool send_request(struct imx500_pipe *pipe, const char *request, size_t length)
Send one request before a single absolute deadline, including partial writes.
#define IMX500_EXIT_GRACE_MS
Definition imx500_pipe.c:48
#define IMX500_STARTUP_TIMEOUT_MS
First-use RPK upload/warm-up needs more time than a warm still capture.
Definition imx500_pipe.c:43
void imx500_pipe_stop(struct imx500_pipe *pipe)
Close the channel, allow an exit grace period, then kill/reap if needed.
#define IMX500_SHOT_TIMEOUT_MS
Bound response waiting so an abandoned shot cannot block the owner indefinitely.
Definition imx500_pipe.c:45
static bool reap_owned_camera(struct imx500_pipe *pipe, int timeout_ms)
Poll for exit of the camera child.
#define IMX500_RESPONSE_BYTES
Fixed space for short protocol replies, never arbitrary child diagnostics.
Definition imx500_pipe.c:47
int imx500_pipe_shoot(struct imx500_pipe *pipe, char *filename, size_t capacity, int number)
Request one saved photograph and qualify its acknowledgement/file.
static int expect_response(struct imx500_pipe *pipe, const char *expected, int timeout)
Consume one exact line before an unchanged monotonic response deadline.
Definition imx500_pipe.c:72
int imx500_pipe_start(struct imx500_pipe *pipe)
Replace any owned worker and require its exact READY response.
int imx500_pipe_analyze(struct imx500_pipe *pipe, const char *filename, unsigned number)
Submit one saved-picture request to a warm analysis worker without recapturing pixels.
static int64_t milliseconds(void)
Read elapsed-time evidence unaffected by wall-clock corrections.
Definition imx500_pipe.c:56
#define IMX500_KILL_GRACE_MS
Definition imx500_pipe.c:49
READY/SHOT/OK process ownership without model-analysis semantics.
Small path and writable-directory helpers shared by USHER backends.
static int usher_prepare_photo(char *filename, size_t capacity)
Redirect an intended public photo into its same-filesystem private staging directory.
Definition path_utils.h:143
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
static int usher_ensure_directory(const char *path)
Create missing directory components and verify the final directory is writable.
Definition path_utils.h:97
static size_t count
Definition pose_log.c:79
One caller-serialized native worker and its borrowed configuration.
Definition imx500_pipe.h:35
const char * model
Definition imx500_pipe.h:37
const char * settings
Definition imx500_pipe.h:38
const char * command
Definition imx500_pipe.h:36
const volatile sig_atomic_t * running
Definition imx500_pipe.h:45
const char * directory
Definition imx500_pipe.h:41
bool photo_only
Definition imx500_pipe.h:40
Validated successful PTP response and optional data-phase length.
Definition chdkbridge.c:116
struct usher_control_result result
Definition usher.c:377
struct captured_image image
Definition usher.c:371