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
lwir_device.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#ifndef SENSORAIA_LWIR_DEVICE_H
19#define SENSORAIA_LWIR_DEVICE_H
20/** @file
21 * @brief Tiny1C/TDK acquisition and Tiny1C state, without image or mission logic.
22 *
23 * @details
24 * This interface is the only boundary between LWIRcam and the camera hardware.
25 * It delivers raw camera-layout frames plus timing evidence; image conversion,
26 * calibration, geolocation and mission policy live elsewhere.
27 *
28 * @par Supported cameras
29 * - Tiny1-C (USB 0bda:5840): combined YUYV transport of 256x384 pixels, i.e.
30 * a 256x192 image plane followed by a 256x192 temperature plane holding
31 * Kelvin*64 little-endian values; 196608 bytes per frame at about 25 fps.
32 * Its separate 256x192 image-only UVC mode is not combined data and is not used.
33 * - TDK (USB 5474:5411): 640x512 image-only YUYV; no temperature plane.
34 *
35 * @par Backend
36 * Capture runs in lwir_device_v4l2.c directly on the Linux uvcvideo kernel
37 * driver with V4L2 MMAP buffers and usbfs control requests for Tiny1-C state.
38 *
39 * @par Ownership model
40 * Every object is caller-owned storage; the backend performs no heap
41 * allocation. A session owns one V4L2 descriptor (held under an exclusive
42 * flock) and up to #LWIR_VIDEO_BUFFERS kernel buffers mapped into the process.
43 * Mapped buffers are only borrowed between dequeue and requeue; callers never
44 * see their addresses and receive copies instead.
45 *
46 * @par Threading
47 * A session is not thread-safe: one thread must own all calls on it. The only
48 * cross-context input is the borrowed sig_atomic_t cancellation flag, which
49 * may be set from a signal handler or another thread and is polled at least
50 * every 25 ms while waiting.
51 *
52 * @par Lifecycle invariants
53 * - Zero-initialize, lwir_device_open(), acquire/discard/state calls, then
54 * lwir_device_close(). Close before reopening.
55 * - A fatal kernel or protocol error poisons the session (EIO) until it is
56 * closed and reopened; no partial recovery is attempted.
57 * - The eight-frame startup qualification runs once per USB power instance,
58 * remembered across reopen and process restart, and is never repeated for
59 * later requests, gaps, invalid frames or reconnection of the same instance.
60 */
61#include "lwir_frame.h"
62#include "lwir_state.h"
63#include <signal.h>
64
65/** @brief Number of V4L2 MMAP buffers requested from uvcvideo.
66 * @details Four keeps one buffer in user space for inspection while the
67 * kernel still has spare buffers to fill, so a short inspection does not drop
68 * the next frame. The driver may grant fewer; at least two are required.
69 */
70#define LWIR_VIDEO_BUFFERS 4U
71
72/** @brief One kernel capture buffer mapped into this process. */
74 void *address; /**< Start of the shared mapping; only valid while @c mapped. */
75 size_t length; /**< Mapped length reported by VIDIOC_QUERYBUF; needed for munmap. */
76 /** @brief Ownership flag for the mapping.
77 * @details Stays true after a failed munmap so a later close can retry and
78 * a reopen is refused instead of leaking or double-mapping memory.
79 */
80 bool mapped;
81};
82
83#ifdef __cplusplus
84extern "C" {
85#endif
86
87/** @brief Bounded camera policy; Tiny1C requires full 256x192 image and temperature planes.
88 * @details Zero dimensions select native geometry; Tiny1C's 256x192 image-only UVC mode is not combined data.
89 * The same structure is used for open and for each acquisition: open writes
90 * the negotiated geometry and layout back, and acquisition requires them to
91 * still match the session.
92 */
94 /** Optional USB serial string that must match exactly; NULL accepts any serial.
95 * Must fit in lwir_device::serial including its terminator. */
96 const char *serial;
97 /** Optional explicit V4L2 node (for example /dev/video2). NULL scans
98 * /dev/video0..63 and fails with EEXIST when more than one camera matches. */
99 const char *device_path;
100 /** @c width / @c height: per-plane native geometry, or zero for "native"
101 * before open; written on open success.
102 * @c warmup_ms: extra delay after the request starts, applied only on the
103 * first startup of a USB power instance; must be below @c timeout_ms.
104 * @c timeout_ms: whole-call budget in milliseconds, 1..120000. */
106 /** @c scene_check: also require lwir_frame_plausible(); combined layout only,
107 * so enabling it for image-only sessions rejects every frame.
108 * @c settle: require consecutive frames to agree per lwir_frame_settled()
109 * before accepting, at the cost of at least one extra frame period. */
111 /** Optional measurement region validated against the native geometry at open; NULL skips it. */
113 /** Borrowed cancellation flag; non-zero aborts waits with EINTR. NULL disables cancellation. */
114 const volatile sig_atomic_t *cancelled;
115 /** Output of open: the detected camera's frame layout. */
117 /** Fail open with ENOTSUP when only an image-only camera is present. */
119};
120
121/** @brief Caller-owned session, initialized to zero before opening.
122 * @details Handles belong only to the driver. Keeping their storage here avoids
123 * a Sensoraia allocation; callers use the functions below, not backend handles directly.
124 */
126 const volatile sig_atomic_t *cancelled; /**< Borrowed from the options at open; may be NULL. */
127 char serial[64]; /**< USB serial read from sysfs, empty when the device reports none. */
128 enum lwir_frame_layout layout; /**< Combined Tiny1-C or image-only TDK, fixed by USB identity. */
129 int video_fd; /**< V4L2 descriptor holding the exclusive flock; -1 once closed. */
130 /** @c video_streaming is set just before STREAMON so close always issues
131 * STREAMOFF, even after a partially failed start. @c video_have_sequence
132 * says whether @c video_last_sequence holds a real kernel sequence yet. */
134 /** Sticky poison after a fatal kernel/protocol error; every later call
135 * fails with EIO until close and reopen. */
137 /** @c video_count: buffers granted by REQBUFS (2..#LWIR_VIDEO_BUFFERS).
138 * @c video_width / @c video_height: per-plane geometry, not transport height. */
140 uint32_t video_last_sequence; /**< Last raw 32-bit V4L2 sequence number seen. */
141 /** 64-bit extension of the kernel sequence; skipped kernel numbers also
142 * advance it, so gaps stay visible to consumers. */
144 uint64_t video_good_arrival_us; /**< Host MONOTONIC arrival of the last qualifying frame. */
145 /** Consecutive good frames, saturating at eight. Once eight is reached it
146 * latches for the rest of the USB power instance. */
148 /** True when this USB power instance already completed startup
149 * qualification, either now or according to the runtime marker. */
151 /** "bootid:sysfs-inode:busnum:devnum"; changes whenever the camera
152 * re-enumerates, which is the only observable power boundary on Linux. */
154 char video_power_port[64]; /**< Physical USB port name (for example 1-1.2) used to name the marker. */
155 /** USB bus and address used to reach the same device through usbfs for
156 * vendor state/control requests. */
158 size_t video_bytes; /**< Expected bytesused per frame (sizeimage) for the layout. */
159 struct lwir_video_buffer video_buffers[LWIR_VIDEO_BUFFERS]; /**< Mappings; only the first @c video_count are used. */
160};
161
162/** @brief Host observation plus optional kernel clock evidence, never automatic exposure qualification. */
164 /** @c sequence: session-extended frame sequence (see lwir_device::video_sequence).
165 * @c arrival_us: host CLOCK_MONOTONIC time when the frame was dequeued, in
166 * microseconds; it includes USB delivery delay after the sensor frame start. */
168 /** Kernel buffer timestamp in CLOCK_MONOTONIC microseconds (uvcvideo takes
169 * it at start of frame); zero when the buffer clock is not MONOTONIC. */
171 /** Raw V4L2 timestamp type and source flags, so consumers can judge what
172 * @c kernel_monotonic_us actually measures. */
174};
175
176/** @brief Open/start a bounded camera-specific combined or image-only YUY2 stream.
177 * @param options Requested policy; native dimensions are written on success.
178 * @param device Empty caller-owned session, closed on failure.
179 * @return True on success; errno describes failure. Close before reopening.
180 * @par Errors
181 * EINVAL invalid options; EBUSY session still owns a descriptor or mapping;
182 * ENODEV no matching camera; EEXIST more than one matching camera during a
183 * scan; EWOULDBLOCK another process holds the camera; ENOTSUP unsupported
184 * format or image-only camera when thermal data is required; ETIMEDOUT or
185 * EINTR deadline or cancellation; other values come from the kernel.
186 */
187bool lwir_device_open(struct lwir_device_options *options, struct lwir_device *device);
188/** @brief Copy a qualified, fresh camera-layout frame into caller-owned storage.
189 * @param device Open session with an optional borrowed cancellation flag.
190 * @param options Native geometry, warmup and qualification policy.
191 * @param destination Writable frame buffer, retained through the call.
192 * @param capacity Accessible bytes; at least lwir_frame_bytes(width, height).
193 * @param observation Sequence and host arrival, written only on success.
194 * @return True on acceptance; ignore destination on failure and never auto-retry publication.
195 * @details Native image/observation buffers must not alias each other, the session
196 * or mapped camera buffers. Fatal kernel ownership failures require close/reopen.
197 * Startup qualification is retained for the USB instance across reopen/restart;
198 * no subsequent request, gap or invalid frame imposes another eight-frame wait.
199 * Freshness: when the kernel timestamp is CLOCK_MONOTONIC, the accepted frame
200 * started at or after this call began, so it never predates the trigger.
201 * @par Errors
202 * EINVAL bad arguments or aliasing; EIO poisoned session; ETIMEDOUT deadline;
203 * EINTR cancellation; EPROTO/EOVERFLOW inconsistent kernel data or clock.
204 */
205bool lwir_device_acquire(struct lwir_device *device, const struct lwir_device_options *options,
206 uint8_t *destination, size_t capacity, struct lwir_device_observation *observation);
207/** @brief Drain one pending frame without retaining the borrowed UVC buffer.
208 * @param device Open session.
209 * @param received Whether a frame was present, written on success.
210 * @return True on successful polling, even when no frame is present.
211 * @details Non-blocking. A drained frame still counts toward startup
212 * qualification, so idle draining can complete it before the first request.
213 */
214bool lwir_device_discard(struct lwir_device *device, bool *received);
215/** @brief Read bounded optional state after acquisition, never writing device settings.
216 * @param device Open session with its cancellation flag.
217 * @param state Caller-owned result with per-field failure statuses.
218 * @details The snapshot is not frame-atomic and cannot establish gain at exposure.
219 * Image-only TDK sessions return a not-requested snapshot without USB commands.
220 */
221void lwir_device_read_state(struct lwir_device *device, struct lwir_device_state *state);
222/** @brief Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation.
223 * @param device Open combined-layout session; image-only cameras fail with ENOTSUP.
224 * @param request Validated control kind and value.
225 * @param result Caller-owned reply, always initialized.
226 * @return True when the camera acknowledged the request.
227 * @details Uses vendor control transfers through usbfs while uvcvideo keeps
228 * streaming. Normal capture never calls this.
229 * @warning The write is submitted once and never replayed automatically. A
230 * failure (including a close error after submission) does not prove the
231 * camera ignored it; read the value back rather than blindly retrying.
232 * @par Errors
233 * EINVAL invalid request; ENOTSUP image-only camera; ENODEV identity changed;
234 * EINTR cancelled; ETIMEDOUT camera did not answer; EIO other failures.
235 */
236bool lwir_device_control(struct lwir_device *device, const struct lwir_control_request *request,
238/** @brief Read the current value of one Tiny1-C control without writing it.
239 * @param device Open combined-layout session.
240 * @param kind Control to read; LWIR_CONTROL_FFC is an action and is rejected (EINVAL).
241 * @param result Caller-owned reply, always initialized.
242 * @return True when the value was read; errors as for lwir_device_control().
243 */
244bool lwir_device_control_read(struct lwir_device *device, enum lwir_control_kind kind,
246/** @brief Close an initialized session; safe repeatedly and preserves errno.
247 * @details Native failed unmaps remain owned for a subsequent close and prevent
248 * reopening. Linux descriptor-close errors are never retried on a reused number.
249 */
250void lwir_device_close(struct lwir_device *device);
251
252#ifdef __cplusplus
253}
254#endif
255#endif
static unsigned capacity[COVERAGE_CAMERAS]
union dc_shot_union request
bool lwir_device_discard(struct lwir_device *device, bool *received)
Drain one pending frame without retaining the borrowed UVC buffer.
void lwir_device_read_state(struct lwir_device *device, struct lwir_device_state *state)
Read bounded optional state after acquisition, never writing device settings.
bool lwir_device_acquire(struct lwir_device *device, const struct lwir_device_options *options, uint8_t *destination, size_t capacity, struct lwir_device_observation *observation)
Copy a qualified, fresh camera-layout frame into caller-owned storage.
bool lwir_device_open(struct lwir_device_options *options, struct lwir_device *device)
Open/start a bounded camera-specific combined or image-only YUY2 stream.
bool lwir_device_control(struct lwir_device *device, const struct lwir_control_request *request, struct lwir_control_result *result)
Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation.
#define LWIR_VIDEO_BUFFERS
Number of V4L2 MMAP buffers requested from uvcvideo.
Definition lwir_device.h:70
bool lwir_device_control_read(struct lwir_device *device, enum lwir_control_kind kind, struct lwir_control_result *result)
Read the current value of one Tiny1-C control without writing it.
void lwir_device_close(struct lwir_device *device)
Close an initialized session; safe repeatedly and preserves errno.
Native frame arithmetic and camera measurements; no codec or flight dependencies.
lwir_frame_layout
Buffer content kinds: full image+thermal frame, or the YUYV image plane alone.
Definition lwir_frame.h:54
Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls.
lwir_control_kind
Settings that lwir_state_control() may change.
Definition lwir_state.h:175
One requested setting change; validate with lwir_control_valid().
Definition lwir_state.h:181
Outcome of lwir_state_control() or lwir_state_control_read().
Definition lwir_state.h:195
Host observation plus optional kernel clock evidence, never automatic exposure qualification.
Bounded camera policy; Tiny1C requires full 256x192 image and temperature planes.
Definition lwir_device.h:93
const struct lwir_measurement * measurement
const char * device_path
Definition lwir_device.h:99
enum lwir_frame_layout layout
const volatile sig_atomic_t * cancelled
const char * serial
Definition lwir_device.h:96
One post-capture snapshot of all lwir_state_field values.
Definition lwir_state.h:135
Caller-owned session, initialized to zero before opening.
unsigned video_width
char serial[64]
char video_power_port[64]
uint32_t video_last_sequence
uint64_t video_good_arrival_us
bool video_have_sequence
unsigned video_height
enum lwir_frame_layout layout
const volatile sig_atomic_t * cancelled
unsigned video_usb_bus
struct lwir_video_buffer video_buffers[LWIR_VIDEO_BUFFERS]
unsigned video_count
bool video_failed
size_t video_bytes
unsigned video_good_frames
bool video_streaming
bool video_power_ready
uint64_t video_sequence
unsigned video_usb_address
char video_power_key[160]
One native-coordinate measurement request.
Definition lwir_frame.h:76
One kernel capture buffer mapped into this process.
Definition lwir_device.h:73
bool mapped
Ownership flag for the mapping.
Definition lwir_device.h:80
Validated capture and reporting policy, fixed before the sample loop.
Definition earcam.c:137
struct usher_control_result result
Definition usher.c:377