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 File Reference

Tiny1C/TDK acquisition and Tiny1C state, without image or mission logic. More...

#include "lwir_frame.h"
#include "lwir_state.h"
#include <signal.h>
Include dependency graph for lwir_device.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  lwir_video_buffer
 One kernel capture buffer mapped into this process. More...
struct  lwir_device_options
 Bounded camera policy; Tiny1C requires full 256x192 image and temperature planes. More...
struct  lwir_device
 Caller-owned session, initialized to zero before opening. More...
struct  lwir_device_observation
 Host observation plus optional kernel clock evidence, never automatic exposure qualification. More...

Macros

#define LWIR_VIDEO_BUFFERS   4U
 Number of V4L2 MMAP buffers requested from uvcvideo.

Functions

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_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_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_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.
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.

Detailed Description

Tiny1C/TDK acquisition and Tiny1C state, without image or mission logic.

This interface is the only boundary between LWIRcam and the camera hardware. It delivers raw camera-layout frames plus timing evidence; image conversion, calibration, geolocation and mission policy live elsewhere.

Supported cameras
  • Tiny1-C (USB 0bda:5840): combined YUYV transport of 256x384 pixels, i.e. a 256x192 image plane followed by a 256x192 temperature plane holding Kelvin*64 little-endian values; 196608 bytes per frame at about 25 fps. Its separate 256x192 image-only UVC mode is not combined data and is not used.
  • TDK (USB 5474:5411): 640x512 image-only YUYV; no temperature plane.
Backend
Capture runs in lwir_device_v4l2.c directly on the Linux uvcvideo kernel driver with V4L2 MMAP buffers and usbfs control requests for Tiny1-C state.
Ownership model
Every object is caller-owned storage; the backend performs no heap allocation. A session owns one V4L2 descriptor (held under an exclusive flock) and up to LWIR_VIDEO_BUFFERS kernel buffers mapped into the process. Mapped buffers are only borrowed between dequeue and requeue; callers never see their addresses and receive copies instead.
Threading
A session is not thread-safe: one thread must own all calls on it. The only cross-context input is the borrowed sig_atomic_t cancellation flag, which may be set from a signal handler or another thread and is polled at least every 25 ms while waiting.
Lifecycle invariants
  • Zero-initialize, lwir_device_open(), acquire/discard/state calls, then lwir_device_close(). Close before reopening.
  • A fatal kernel or protocol error poisons the session (EIO) until it is closed and reopened; no partial recovery is attempted.
  • The eight-frame startup qualification runs once per USB power instance, remembered across reopen and process restart, and is never repeated for later requests, gaps, invalid frames or reconnection of the same instance.

Definition in file lwir_device.h.

Macro Definition Documentation

◆ LWIR_VIDEO_BUFFERS

#define LWIR_VIDEO_BUFFERS   4U

Number of V4L2 MMAP buffers requested from uvcvideo.

Four keeps one buffer in user space for inspection while the kernel still has spare buffers to fill, so a short inspection does not drop the next frame. The driver may grant fewer; at least two are required.

Definition at line 70 of file lwir_device.h.

Function Documentation

◆ lwir_device_acquire()

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.

Parameters
deviceOpen session with an optional borrowed cancellation flag.
optionsNative geometry, warmup and qualification policy.
destinationWritable frame buffer, retained through the call.
capacityAccessible bytes; at least lwir_frame_bytes(width, height).
observationSequence and host arrival, written only on success.
Returns
True on acceptance; ignore destination on failure and never auto-retry publication.

Native image/observation buffers must not alias each other, the session or mapped camera buffers. Fatal kernel ownership failures require close/reopen. Startup qualification is retained for the USB instance across reopen/restart; no subsequent request, gap or invalid frame imposes another eight-frame wait. Freshness: when the kernel timestamp is CLOCK_MONOTONIC, the accepted frame started at or after this call began, so it never predates the trigger.

Errors
EINVAL bad arguments or aliasing; EIO poisoned session; ETIMEDOUT deadline; EINTR cancellation; EPROTO/EOVERFLOW inconsistent kernel data or clock.

Copy a qualified, fresh camera-layout frame into caller-owned storage.

Loop structure, each iteration bounded by a 25 ms poll() slice so that cancellation and the deadline are noticed promptly:

  1. poll() for a filled buffer; POLLERR/POLLHUP/POLLNVAL (for example an unplugged camera) poison the session.
  2. Dequeue one buffer and read the host clock immediately.
  3. Grade the frame in increasing strictness:
    • usable: structurally valid, recent, correct sequence; feeds the startup qualification counter even when it predates the request.
    • valid: additionally started at or after the request (freshness).
    • scene_valid: additionally passes the optional scene check.
  4. For non-MONOTONIC clocks freshness is unknowable, so the first good frame triggers a one-time drain of all already-queued buffers; the next frame is then certainly produced after the request.
  5. Accept when the instance is qualified (eight good frames), optional settling holds, and on first startup only, warmup_ms has elapsed.
  6. Copy what is needed and snapshot sequence/timestamp/flags, then requeue. The order matters: after QBUF the kernel may overwrite both pixels and metadata.
  7. Persist the startup marker once qualification and warmup are complete.

Settling uses destination as the previous-image store: the image plane of each scene-valid frame is copied there and the next frame is compared against it, so no extra buffer is needed. The temperature plane is copied only for the accepted frame.

Returns
True with a fresh frame in destination.
Errors
EINVAL arguments/aliasing; EIO poisoned session or poll error; ETIMEDOUT deadline, including completion that would land after it; EINTR cancelled; kernel errno from failed ioctls (session then poisoned).
Warning
On failure destination may contain partial or settling data and must be ignored.

Definition at line 963 of file lwir_device_v4l2.c.

◆ lwir_device_close()

void lwir_device_close ( struct lwir_device * device)

Close an initialized session; safe repeatedly and preserves errno.

Native failed unmaps remain owned for a subsequent close and prevent reopening. Linux descriptor-close errors are never retried on a reused number.

Close an initialized session; safe repeatedly and preserves errno.

  1. STREAMOFF returns all buffers from the driver queue to user space.
  2. munmap each mapping. A failed unmap keeps its entry marked as mapped and the session struct is not cleared, so a later close retries it and lwir_device_open() refuses with EBUSY rather than losing track of memory the process still maps.
  3. REQBUFS with count 0 frees the kernel buffers when the driver allows it.
  4. close() the descriptor exactly once. Its state is cleared first and a close error is only logged: Linux frees the number even on error, so retrying could close an unrelated descriptor opened by another thread.

Errors of STREAMOFF/REQBUFS are deliberately ignored; there is no better recovery than continuing teardown, and closing the descriptor ends the stream regardless.

Parameters
deviceSession to release; NULL and already-closed sessions are accepted.
Note
errno is preserved so callers can close on an error path without losing the original cause.

Definition at line 525 of file lwir_device_v4l2.c.

◆ lwir_device_control()

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.

Parameters
deviceOpen combined-layout session; image-only cameras fail with ENOTSUP.
requestValidated control kind and value.
resultCaller-owned reply, always initialized.
Returns
True when the camera acknowledged the request.

Uses vendor control transfers through usbfs while uvcvideo keeps streaming. Normal capture never calls this.

Warning
The write is submitted once and never replayed automatically. A failure (including a close error after submission) does not prove the camera ignored it; read the value back rather than blindly retrying.
Errors
EINVAL invalid request; ENOTSUP image-only camera; ENODEV identity changed; EINTR cancelled; ETIMEDOUT camera did not answer; EIO other failures.

Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation.

Returns
True when acknowledged.

Definition at line 1289 of file lwir_device_v4l2.c.

◆ lwir_device_control_read()

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.

Parameters
deviceOpen combined-layout session.
kindControl to read; LWIR_CONTROL_FFC is an action and is rejected (EINVAL).
resultCaller-owned reply, always initialized.
Returns
True when the value was read; errors as for lwir_device_control().

Read the current value of one Tiny1-C control without writing it.

Builds a request only so the shared validation path can be reused.

Returns
True when the value was read.

Definition at line 1300 of file lwir_device_v4l2.c.

◆ lwir_device_discard()

bool lwir_device_discard ( struct lwir_device * device,
bool * received )

Drain one pending frame without retaining the borrowed UVC buffer.

Parameters
deviceOpen session.
receivedWhether a frame was present, written on success.
Returns
True on successful polling, even when no frame is present.

Non-blocking. A drained frame still counts toward startup qualification, so idle draining can complete it before the first request.

Drain one pending frame without retaining the borrowed UVC buffer.

Used to empty the queue (for example the non-MONOTONIC drain in lwir_device_acquire()) and to keep the stream moving between requests. The frame still feeds startup qualification with the one-second recency window, and the marker is published as soon as eight good frames are seen; no warmup delay applies here because there is no request start to measure from.

Returns
True on success, including when no frame was pending.
Errors
EINVAL bad arguments or session; EIO poisoned; EINTR cancelled; kernel or clock errno (session then poisoned).

Definition at line 1090 of file lwir_device_v4l2.c.

◆ lwir_device_open()

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.

Parameters
optionsRequested policy; native dimensions are written on success.
deviceEmpty caller-owned session, closed on failure.
Returns
True on success; errno describes failure. Close before reopening.
Errors
EINVAL invalid options; EBUSY session still owns a descriptor or mapping; ENODEV no matching camera; EEXIST more than one matching camera during a scan; EWOULDBLOCK another process holds the camera; ENOTSUP unsupported format or image-only camera when thermal data is required; ETIMEDOUT or EINTR deadline or cancellation; other values come from the kernel.

Open/start a bounded camera-specific combined or image-only YUY2 stream.

  1. Validate options and refuse while the session still owns anything, including mappings kept after a failed munmap (EBUSY).
  2. Compute one absolute deadline covering discovery and setup.
  3. With an explicit device path, probe only that node. Otherwise probe /dev/video0..63. A second matching camera is an error (EEXIST) rather than "first wins": with two cameras attached the choice would depend on enumeration order, so the caller must disambiguate with a serial or path. Each match holds its own flock until the scan decides.
  4. Read the startup marker, then set up streaming.

Every failure after a successful probe closes the session, so the caller never has to clean up after a false return.

Returns
True when streaming; errno set otherwise (see lwir_device.h).

Definition at line 651 of file lwir_device_v4l2.c.

◆ lwir_device_read_state()

void lwir_device_read_state ( struct lwir_device * device,
struct lwir_device_state * state )

Read bounded optional state after acquisition, never writing device settings.

Parameters
deviceOpen session with its cancellation flag.
stateCaller-owned result with per-field failure statuses.

The snapshot is not frame-atomic and cannot establish gain at exposure. Image-only TDK sessions return a not-requested snapshot without USB commands.

Read bounded optional state after acquisition, never writing device settings.

All fields start as skipped and the first as an I/O error, so a failure to open usbfs is reported on a field instead of looking like an empty but successful read. lwir_state_read() overwrites what it reaches. The usbfs close result is ignored because nothing was written. Image-only sessions (or NULL) return a zero, not-requested snapshot without any USB traffic.

Note
errno is preserved; outcomes are reported only through state.
The snapshot is taken after the frame and is not frame-atomic.

Definition at line 1319 of file lwir_device_v4l2.c.