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.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/** @file imx500_pipe.h
19 * @brief READY/SHOT/OK process ownership without model-analysis semantics.
20 * @details Each backend keeps its own state, rather than sharing a detector's
21 * process globals. This supervisor qualifies the command channel and saved file;
22 * exposure identity and analysis results are checked by their respective consumers. */
23#ifndef SENSORAIA_IMX500_PIPE_H
24#define SENSORAIA_IMX500_PIPE_H
25
26#include <stddef.h>
27#include <stdbool.h>
28#include <sys/types.h>
29#include <signal.h>
30
31/** @brief One caller-serialized native worker and its borrowed configuration.
32 * @details Initialize with IMX500_PIPE_INITIALIZER before the first lifecycle
33 * call. Keep path strings alive until shutdown; no field makes an owned copy.
34 * @warning Calls on one instance must be serialized by its backend owner. */
36 const char *command; /**< Native executable, passed to posix_spawnp without a shell. */
37 const char *model; /**< RPK selected by the application, not interpreted here. */
38 const char *settings; /**< Borrowed application_settings.ini path; NULL preserves the explicit RPK argument form. */
39 bool analyze; /**< Saved-picture requests rather than capture; this worker must never acquire the sensor. */
40 bool photo_only; /**< Live camera capture without a model or inference settings. */
41 const char *directory; /**< Photo destination resolved by the parent before each request. */
42 char prefix; /**< Backend-selected lowercase photo namespace, such as 'a' or 'o'. */
43 pid_t pid; /**< Owned child PID; -1 means no child remains to be reaped. */
44 int socket; /**< Parent command/status descriptor; -1 means the channel is closed. */
45 const volatile sig_atomic_t *running; /**< Optional borrowed USHER cancellation flag, alive until this owner stops. */
46};
47
48/** @brief Safe empty lifecycle state: descriptor zero must never mean uninitialized. */
49#define IMX500_PIPE_INITIALIZER {.pid = -1, .socket = -1}
50
51/** @brief Replace any owned worker and require its exact READY response.
52 * @param[in,out] pipe Initialized state with live command/model/directory strings.
53 * @return Zero after readiness, otherwise -1 with newly acquired resources closed.
54 * @details The child owns the camera. Readiness includes its model-specific
55 * warm-up, not just successful process creation. Existing owned work is stopped
56 * before spawning, preventing a second child from competing for the same sensor.
57 * @note No analysis sidecar or object/LOOM result is read by this interface. */
58int imx500_pipe_start(struct imx500_pipe *pipe);
59/** @brief Request one saved photograph and qualify its acknowledgement/file.
60 * @param[in,out] pipe Running worker owned by the calling backend.
61 * @param[out] filename Private .pending path; consume it only after successful return.
62 * @param[in] capacity Writable bytes in @p filename, including its terminator.
63 * @param[in] number Nonnegative photo number used in the backend's filename.
64 * @return Zero for an exact OK response and a nonempty regular file, otherwise -1.
65 * @details Absolute paths avoid dependence on the child's working directory.
66 * Newlines are rejected because the protocol is line-framed. A failed exchange
67 * closes/reaps the worker rather than pairing a late response with another shot.
68 * A later request starts a replacement worker only after the previous owner exits.
69 * The caller finishes metadata and calls usher_complete_photo before final-name publication.
70 * @warning This does not decode JPEG pixels, prove exposure timing, or establish
71 * valid inference. A failed shot is never automatically replayed. */
72int imx500_pipe_shoot(struct imx500_pipe *pipe, char *filename, size_t capacity, int number);
73/** @brief Close the channel, allow an exit grace period, then kill/reap if needed.
74 * @param[in,out] pipe Initialized state; NULL is ignored.
75 * @details Closing the command channel lets a healthy worker finish normally.
76 * Reaping keeps stale process state from being mistaken for an available camera.
77 * Monotonic grace periods bound polling; an unconfirmed exit retains PID ownership
78 * and prevents a replacement worker. Scheduling and kernel stalls are not preempted.
79 * @note Repeated stops are harmless once the PID and descriptor are cleared. */
80void imx500_pipe_stop(struct imx500_pipe *pipe);
81/** @brief Submit one saved-picture request to a warm analysis worker without recapturing pixels.
82 * @param pipe Running owner started with analyze=true and explicit settings.
83 * @param filename Immutable picture path, or a producer-owned private picture for private-image processing.
84 * @param number Positive increasing request number within this worker lifetime.
85 * @return Zero for an exact successful reply, otherwise minus one after closing/reaping the failed worker.
86 * @details A failed exchange is not retried, preventing a late reply from qualifying another picture. */
87int imx500_pipe_analyze(struct imx500_pipe *pipe, const char *filename, unsigned number);
88
89#endif
static unsigned capacity[COVERAGE_CAMERAS]
void imx500_pipe_stop(struct imx500_pipe *pipe)
Close the channel, allow an exit grace period, then kill/reap if needed.
int imx500_pipe_shoot(struct imx500_pipe *pipe, char *filename, size_t capacity, int number)
Request one saved photograph and qualify its acknowledgement/file.
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.
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