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
ai_cam_pipe.c File Reference

Supervise the selected system or native AI-camera owner and publish captured JPEGs. More...

#include "ai_cam_pipe.h"
#include "camera_backend.h"
#include "imx500_pipe.h"
#include "path_utils.h"
#include <errno.h>
#include <limits.h>
#include <poll.h>
#include <signal.h>
#include <spawn.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/inotify.h>
#include <sys/stat.h>
#include <sys/wait.h>
#include <time.h>
#include <unistd.h>
Include dependency graph for ai_cam_pipe.c:

Go to the source code of this file.

Macros

#define USHER_AI_CAM_COMMAND   "rpicam-still"
#define USHER_AI_CAM_NATIVE_COMMAND   "./bin/aicam"
#define USHER_AI_CAM_PHOTO_DIR   "~/Pictures/sensoraia"
#define USHER_AI_CAM_WIDTH   "2028"
#define USHER_AI_CAM_HEIGHT   "1520"
#define USHER_AI_CAM_PERSISTENT   1
#define USHER_AI_CAM_STARTUP_MS   3000
#define USHER_AI_CAM_SIGNAL_TIMEOUT_MS   4000
#define USHER_AI_CAM_TIMEOUT_SECONDS   30
#define USHER_AI_CAM_RETRY_MS   30000

Enumerations

enum  capture_result { CAPTURE_FAILED = -1 , CAPTURE_SAVED = 0 , CAPTURE_NOT_TRIGGERED = 1 }

Functions

static int64_t monotonic_ms (void)
 Read the child supervision clock.
static void wait_ms (int milliseconds)
 Wait until a short polling interval elapses.
static bool child_alive (int *status)
 Poll the owned child and reap it if it exited.
static bool wait_child (int milliseconds)
 Give the owned child a bounded interval to exit.
static bool stop_child (void)
 Request shutdown and escalate if the camera child does not exit.
static bool persistent_stop (void)
 Retire the subprocess and its directory watch.
static bool persistent_enabled (void)
 Resolve the default persistent capture policy against the one-shot override.
static bool zsl_enabled (void)
 Check whether the next persistent child may use zero shutter lag.
static bool new_session (const char *directory)
 Reserve a private filename prefix for a camera child.
static int spawn_camera (char *const arguments[])
 Launch the configured camera application and record ownership.
static int persistent_start (const char *directory)
 Start the signal-triggered camera application.
static int publish_image (const char *source, const char *destination)
 Publish a completed private JPEG at the caller's staging path.
static enum capture_result persistent_shoot (const char *destination)
 Request and collect one persistent-child capture.
static int oneshot_shoot (const char *directory, const char *destination)
 Capture using a fresh camera subprocess.
void ai_cam_pipe_set_photo_directory (const char *directory)
 Select a borrowed directory before initialization.
int ai_cam_pipe_set_native (bool enabled)
 Select native or system-camera capture before startup.
bool ai_cam_pipe_native (void)
 Report whether the selected AIcam mode uses native photo-only capture.
void ai_cam_pipe_configure (const struct camera_backend_host *host)
 Pass the shutdown flag to native worker supervision.
int ai_cam_pipe_init (const char *unused)
 Validate storage and start the selected camera owner.
int ai_cam_pipe_shoot (char *filename, size_t filename_size, int image_number)
 Capture one ordinary JPEG into private staging for metadata completion.
void ai_cam_pipe_deinit (void)
 Stop the native and system-camera subprocesses.

Variables

char ** environ
static const char * photo_directory = USHER_AI_CAM_PHOTO_DIR
static pid_t child_pid = -1
static int watch_fd = -1
static unsigned session_number
static int64_t ready_ms
static int64_t retry_ms
static unsigned failures
static bool signal_zsl
static bool zsl_failed
static bool timing_enabled
static bool native_enabled
static struct imx500_pipe native_capture = IMX500_PIPE_INITIALIZER
static char signal_directory [PATH_MAX]
static char signal_prefix [80]

Detailed Description

Supervise the selected system or native AI-camera owner and publish captured JPEGs.

Persistent capture uses private session filenames and an inotify completion event so an incomplete exposure is never visible under its final name. One-shot capture is allowed only when persistent mode proves no trigger was sent; ambiguous post-trigger failures are never replayed.

Definition in file ai_cam_pipe.c.

Macro Definition Documentation

◆ USHER_AI_CAM_COMMAND

#define USHER_AI_CAM_COMMAND   "rpicam-still"

Definition at line 48 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_HEIGHT

#define USHER_AI_CAM_HEIGHT   "1520"

Definition at line 60 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_NATIVE_COMMAND

#define USHER_AI_CAM_NATIVE_COMMAND   "./bin/aicam"

Definition at line 51 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_PERSISTENT

#define USHER_AI_CAM_PERSISTENT   1

Definition at line 63 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_PHOTO_DIR

#define USHER_AI_CAM_PHOTO_DIR   "~/Pictures/sensoraia"

Definition at line 54 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_RETRY_MS

#define USHER_AI_CAM_RETRY_MS   30000

Definition at line 75 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_SIGNAL_TIMEOUT_MS

#define USHER_AI_CAM_SIGNAL_TIMEOUT_MS   4000

Definition at line 69 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_STARTUP_MS

#define USHER_AI_CAM_STARTUP_MS   3000

Definition at line 66 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_TIMEOUT_SECONDS

#define USHER_AI_CAM_TIMEOUT_SECONDS   30

Definition at line 72 of file ai_cam_pipe.c.

◆ USHER_AI_CAM_WIDTH

#define USHER_AI_CAM_WIDTH   "2028"

Definition at line 57 of file ai_cam_pipe.c.

Enumeration Type Documentation

◆ capture_result

Enumerator
CAPTURE_FAILED 
CAPTURE_SAVED 
CAPTURE_NOT_TRIGGERED 

Definition at line 78 of file ai_cam_pipe.c.

Function Documentation

◆ ai_cam_pipe_configure()

void ai_cam_pipe_configure ( const struct camera_backend_host * host)

Pass the shutdown flag to native worker supervision.

Parameters
hostNullable backend host; its running flag must outlive the worker.

Retain only the borrowed flag, not the host structure. A null host clears the flag.

Definition at line 393 of file ai_cam_pipe.c.

◆ ai_cam_pipe_deinit()

void ai_cam_pipe_deinit ( void )

Stop the native and system-camera subprocesses.

Attempt bounded shutdown; an unreaped system-camera child retains ownership rather than allowing a second process to open the camera.

Definition at line 470 of file ai_cam_pipe.c.

◆ ai_cam_pipe_init()

int ai_cam_pipe_init ( const char * unused)

Validate storage and start the selected camera owner.

Parameters
[in]unusedReserved backend argument.
Returns
Zero for usable storage, otherwise -1.

All operations require the owning backend's serialization. Native startup waits for a valid frame; the system-camera path checks its child per shot.

Definition at line 398 of file ai_cam_pipe.c.

◆ ai_cam_pipe_native()

bool ai_cam_pipe_native ( void )

Report whether the selected AIcam mode uses native photo-only capture.

Returns
True for native mode.

Reports configuration, not whether the camera has started.

Definition at line 388 of file ai_cam_pipe.c.

◆ ai_cam_pipe_set_native()

int ai_cam_pipe_set_native ( bool enabled)

Select native or system-camera capture before startup.

Parameters
enabledTrue for native photo-only capture.
Returns
Zero on success, or -1 while either mode has an owned child.

Refuse to switch modes without releasing the previous owner.

Definition at line 381 of file ai_cam_pipe.c.

◆ ai_cam_pipe_set_photo_directory()

void ai_cam_pipe_set_photo_directory ( const char * directory)

Select a borrowed directory before initialization.

Parameters
[in]directoryCaller-owned path, or NULL for the compiled default.

Retain the pointer, not a copy; keep the path valid through capture.

Definition at line 376 of file ai_cam_pipe.c.

◆ ai_cam_pipe_shoot()

int ai_cam_pipe_shoot ( char * filename,
size_t filename_size,
int image_number )

Capture one ordinary JPEG into private staging for metadata completion.

Parameters
[out]filenameReceives the .pending path, empty on failure.
[in]filename_sizeBuffer capacity including NUL.
[in]image_numberUSHER shot number.
Returns
Zero for a nonempty regular image, otherwise -1.

A failure after triggering never replays the exposure. The system camera path does not supply Sensoraia's sensor evidence. The caller completes metadata before exposing the final filename.

Definition at line 430 of file ai_cam_pipe.c.

◆ child_alive()

bool child_alive ( int * status)
static

Poll the owned child and reap it if it exited.

Parameters
[out]statusOptional wait status; use only when waitpid reports exit.
Returns
True while the child remains owned.

Clear the PID only after reaping or ECHILD. Other wait errors leave ownership intact rather than allowing a second camera process.

Definition at line 128 of file ai_cam_pipe.c.

◆ monotonic_ms()

int64_t monotonic_ms ( void )
static

Read the child supervision clock.

Returns
Monotonic milliseconds, or zero on clock failure.

Use elapsed time rather than calendar time for startup and shutdown.

Definition at line 103 of file ai_cam_pipe.c.

◆ new_session()

bool new_session ( const char * directory)
static

Reserve a private filename prefix for a camera child.

Parameters
directoryExisting output directory.
Returns
True if both path components fit and the counter did not wrap.

Include both process ID and session counter so a late event from an earlier child is not accepted as a current capture.

Definition at line 205 of file ai_cam_pipe.c.

◆ oneshot_shoot()

int oneshot_shoot ( const char * directory,
const char * destination )
static

Capture using a fresh camera subprocess.

Parameters
directoryExisting directory for private output.
destinationNew staging path for the completed JPEG.
Returns
Zero after successful child exit and publication, or -1 on failure.

Do not launch until the previous child is reaped. Use an unused private path and publish only after the child exits successfully.

Definition at line 347 of file ai_cam_pipe.c.

◆ persistent_enabled()

bool persistent_enabled ( void )
static

Resolve the default persistent capture policy against the one-shot override.

Returns
True if the build enables persistence and the environment does not opt out.

An unset, empty, or zero one-shot override retains persistent mode.

Definition at line 184 of file ai_cam_pipe.c.

◆ persistent_shoot()

enum capture_result persistent_shoot ( const char * destination)
static

Request and collect one persistent-child capture.

Parameters
destinationNew staging path for the completed JPEG.
Returns
Saved, not triggered, or failed after a trigger may have been delivered.

Drain old notifications before signaling. Require a completed event with the current child's private prefix. Once signaled, an ambiguous outcome is terminal; replay could duplicate an exposure.

Definition at line 299 of file ai_cam_pipe.c.

◆ persistent_start()

int persistent_start ( const char * directory)
static

Start the signal-triggered camera application.

Parameters
directoryExisting output directory to watch and write.
Returns
Zero after launch, or -1 on ownership, watch, path, or spawn failure.

Attach the watch before launch to avoid missing completion events. Record a warmup deadline; the first trigger waits for it outside startup.

Definition at line 237 of file ai_cam_pipe.c.

◆ persistent_stop()

bool persistent_stop ( void )
static

Retire the subprocess and its directory watch.

Returns
True if subprocess ownership was released.

Close the watch even after a timeout; subsequent starts must still resolve the retained child PID before opening the camera.

Definition at line 173 of file ai_cam_pipe.c.

◆ publish_image()

int publish_image ( const char * source,
const char * destination )
static

Publish a completed private JPEG at the caller's staging path.

Parameters
sourcePrivate camera output, required to be nonempty and regular.
destinationNew sibling path; existing files are not replaced.
Returns
Zero if linked, even if private-name cleanup failed, or -1 if not linked.

A hard link makes the complete file visible without copying pixels or reopening the JPEG for writing.

Definition at line 283 of file ai_cam_pipe.c.

◆ spawn_camera()

int spawn_camera ( char *const arguments[])
static

Launch the configured camera application and record ownership.

Parameters
argumentsNull-terminated argument vector, including argv[0].
Returns
Zero on launch, or -1 on spawn failure.

Pass arguments directly rather than interpreting paths as shell input. A successful spawn does not prove that the camera is ready.

Definition at line 221 of file ai_cam_pipe.c.

◆ stop_child()

bool stop_child ( void )
static

Request shutdown and escalate if the camera child does not exit.

Returns
True when no child remains owned.

Use the persistent application's signal protocol when its watch is active. Retain the PID if even forced termination cannot be reaped.

Definition at line 158 of file ai_cam_pipe.c.

◆ wait_child()

bool wait_child ( int milliseconds)
static

Give the owned child a bounded interval to exit.

Parameters
millisecondsSupervision budget in milliseconds.
Returns
True once no child is owned; false on timeout.

Poll so a driver that does not return cannot block a waitpid call.

Definition at line 144 of file ai_cam_pipe.c.

◆ wait_ms()

void wait_ms ( int milliseconds)
static

Wait until a short polling interval elapses.

Parameters
millisecondsRequested wait in milliseconds.

After interruption, recompute the remaining budget instead of restarting the full delay.

Definition at line 114 of file ai_cam_pipe.c.

◆ zsl_enabled()

bool zsl_enabled ( void )
static

Check whether the next persistent child may use zero shutter lag.

Returns
True unless configuration or a previous ZSL failure disabled it.

Retain the failure latch across child restarts so recovery need not repeat the same launch mode.

Definition at line 194 of file ai_cam_pipe.c.

Variable Documentation

◆ child_pid

pid_t child_pid = -1
static

Definition at line 86 of file ai_cam_pipe.c.

◆ environ

char** environ
extern

◆ failures

unsigned failures
static

Definition at line 91 of file ai_cam_pipe.c.

◆ native_capture

struct imx500_pipe native_capture = IMX500_PIPE_INITIALIZER
static

Definition at line 96 of file ai_cam_pipe.c.

◆ native_enabled

bool native_enabled
static

Definition at line 95 of file ai_cam_pipe.c.

◆ photo_directory

const char* photo_directory = USHER_AI_CAM_PHOTO_DIR
static

Definition at line 85 of file ai_cam_pipe.c.

◆ ready_ms

int64_t ready_ms
static

Definition at line 89 of file ai_cam_pipe.c.

◆ retry_ms

int64_t retry_ms
static

Definition at line 90 of file ai_cam_pipe.c.

◆ session_number

unsigned session_number
static

Definition at line 88 of file ai_cam_pipe.c.

◆ signal_directory

char signal_directory[PATH_MAX]
static

Definition at line 97 of file ai_cam_pipe.c.

◆ signal_prefix

char signal_prefix[80]
static

Definition at line 98 of file ai_cam_pipe.c.

◆ signal_zsl

bool signal_zsl
static

Definition at line 92 of file ai_cam_pipe.c.

◆ timing_enabled

bool timing_enabled
static

Definition at line 94 of file ai_cam_pipe.c.

◆ watch_fd

int watch_fd = -1
static

Definition at line 87 of file ai_cam_pipe.c.

◆ zsl_failed

bool zsl_failed
static

Definition at line 93 of file ai_cam_pipe.c.