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_state.h File Reference

Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for lwir_state.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  lwir_state_value
 Raw result of one mailbox query, kept verbatim as evidence. More...
struct  lwir_device_state
 One post-capture snapshot of all lwir_state_field values. More...
struct  lwir_state_io
 Transport and clock callbacks driving the mailbox protocol. More...
struct  lwir_control_request
 One requested setting change; validate with lwir_control_valid(). More...
struct  lwir_control_result
 Outcome of lwir_state_control() or lwir_state_control_read(). More...

Macros

#define LWIR_STATE_BUDGET_MS   250U
 Wall-time budget for one whole lwir_state_read() snapshot, in milliseconds.

Enumerations

enum  lwir_state_field {
  LWIR_STATE_GAIN , LWIR_STATE_FW_BUILD , LWIR_STATE_FW_DATE , LWIR_STATE_CHIP ,
  LWIR_STATE_SHUTTER , LWIR_STATE_DISTANCE , LWIR_STATE_REFLECTED_K , LWIR_STATE_AMBIENT_K ,
  LWIR_STATE_EMISSIVITY , LWIR_STATE_TRANSMITTANCE , LWIR_STATE_TNR , LWIR_STATE_SNR ,
  LWIR_STATE_DDE , LWIR_STATE_BRIGHTNESS , LWIR_STATE_CONTRAST , LWIR_STATE_AGC_MODE ,
  LWIR_STATE_AGC_MAX_GAIN , LWIR_STATE_AGC_BOS , LWIR_STATE_AGC_ENABLE , LWIR_STATE_MIRROR_FLIP ,
  LWIR_STATE_FIELDS
}
 Index of each queried device-state field; also the read order. More...
enum  lwir_state_status {
  LWIR_STATE_NOT_REQUESTED , LWIR_STATE_OK , LWIR_STATE_UNSUPPORTED , LWIR_STATE_TIMEOUT ,
  LWIR_STATE_IO_ERROR , LWIR_STATE_INVALID , LWIR_STATE_BUSY , LWIR_STATE_SKIPPED ,
  LWIR_STATE_CANCELLED
}
 Outcome of one field read or one control operation. More...
enum  lwir_control_kind {
  LWIR_CONTROL_GAIN , LWIR_CONTROL_EMISSIVITY , LWIR_CONTROL_AGC_MODE , LWIR_CONTROL_AGC_ENABLE ,
  LWIR_CONTROL_FFC
}
 Settings that lwir_state_control() may change. More...

Functions

bool lwir_control_valid (const struct lwir_control_request *request)
 Check a control request against the vendor value ranges.
bool lwir_state_control_read (const struct lwir_state_io *io, enum lwir_control_kind kind, struct lwir_control_result *result)
 Read one controllable setting without writing anything.
bool lwir_state_control (const struct lwir_state_io *io, const struct lwir_control_request *request, struct lwir_control_result *result)
 Apply one setting or trigger FFC, then confirm it.
void lwir_state_read (const struct lwir_state_io *io, struct lwir_device_state *state)
 Take a best-effort, read-only snapshot of all device-state fields.
bool lwir_state_u16 (const struct lwir_device_state *state, enum lwir_state_field field, uint16_t *value)
 Decode a validated two-byte big-endian field.
size_t lwir_state_format (const struct lwir_device_state *state, char *output, size_t capacity)
 Render a snapshot as key=value evidence lines for the JPEG APP14 segment.

Detailed Description

Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls.

The Tiny1-C exposes a command mailbox through a small register window:

  • status byte at 0x0200: 0 = idle/done, bit0 = busy, bits 0xfc = error class (0x08/0x10 unsupported, 0x14 invalid, anything else I/O error);
  • standard 8-byte command header written at 0x1d00 (the write executes it);
  • extended 16-byte header: bytes 0..7 written to 0x9d00 are only held, bytes 8..15 written to 0x1d08 trigger execution;
  • reply read at 0x1d00 + header length (0x1d08 standard, 0x1d10 extended).

This module implements only that protocol. Transport is injected through struct lwir_state_io: the native driver backs it with Linux USBFS control transfers, host tests back it with fakes. No heap, no memcpy, no global state.

Two independent entry families exist:

Value ranges and units come from the vendor headers; they describe what the device accepts, not measured radiometric accuracy.

Definition in file lwir_state.h.

Macro Definition Documentation

◆ LWIR_STATE_BUDGET_MS

#define LWIR_STATE_BUDGET_MS   250U

Wall-time budget for one whole lwir_state_read() snapshot, in milliseconds.

Keeps post-capture latency bounded. On real hardware all fields do not always fit: later fields (AGC, mirror/flip) may time out or stay skipped.

Definition at line 58 of file lwir_state.h.

Enumeration Type Documentation

◆ lwir_control_kind

Settings that lwir_state_control() may change.

Enumerator
LWIR_CONTROL_GAIN 
LWIR_CONTROL_EMISSIVITY 
LWIR_CONTROL_AGC_MODE 
LWIR_CONTROL_AGC_ENABLE 
LWIR_CONTROL_FFC 

Definition at line 175 of file lwir_state.h.

◆ lwir_state_field

Index of each queried device-state field; also the read order.

Fields are read in this order, so earlier entries are the most likely to complete within LWIR_STATE_BUDGET_MS. Two-byte values are big-endian; ranges below are those accepted by lwir_state_read() validation.

Enumerator
LWIR_STATE_GAIN 
LWIR_STATE_FW_BUILD 
LWIR_STATE_FW_DATE 
LWIR_STATE_CHIP 
LWIR_STATE_SHUTTER 
LWIR_STATE_DISTANCE 
LWIR_STATE_REFLECTED_K 
LWIR_STATE_AMBIENT_K 
LWIR_STATE_EMISSIVITY 
LWIR_STATE_TRANSMITTANCE 
LWIR_STATE_TNR 
LWIR_STATE_SNR 
LWIR_STATE_DDE 
LWIR_STATE_BRIGHTNESS 
LWIR_STATE_CONTRAST 
LWIR_STATE_AGC_MODE 
LWIR_STATE_AGC_MAX_GAIN 
LWIR_STATE_AGC_BOS 
LWIR_STATE_AGC_ENABLE 
LWIR_STATE_MIRROR_FLIP 
LWIR_STATE_FIELDS 

Definition at line 87 of file lwir_state.h.

◆ lwir_state_status

Outcome of one field read or one control operation.

The numeric order is part of the evidence format: lwir_state_format() maps it to text by index.

Enumerator
LWIR_STATE_NOT_REQUESTED 
LWIR_STATE_OK 
LWIR_STATE_UNSUPPORTED 
LWIR_STATE_TIMEOUT 
LWIR_STATE_IO_ERROR 
LWIR_STATE_INVALID 
LWIR_STATE_BUSY 
LWIR_STATE_SKIPPED 
LWIR_STATE_CANCELLED 

Definition at line 115 of file lwir_state.h.

Function Documentation

◆ lwir_control_valid()

bool lwir_control_valid ( const struct lwir_control_request * request)

Check a control request against the vendor value ranges.

Parameters
requestRequest to check; NULL is rejected.
Returns
True if the kind is known and the value is in range (FFC requires 0).

Check a control request against the vendor value ranges.

Returns
True for a known kind with an in-range value; FFC accepts only 0.

Definition at line 231 of file lwir_state.c.

◆ lwir_state_control()

bool lwir_state_control ( const struct lwir_state_io * io,
const struct lwir_control_request * request,
struct lwir_control_result * result )

Apply one setting or trigger FFC, then confirm it.

Setters write the value and verify it by exact read-back within 1 s (gain: 5 s). FFC waits 3 s and an idle mailbox within 5 s, and reports acknowledgement only.

Parameters
ioTransport; all callbacks required.
requestValidated with lwir_control_valid().
resultAlways reset when non-NULL; see struct lwir_control_result.
Returns
True when completed (and verified for setters). False otherwise; check result->submitted before deciding anything about device state.
Warning
Never retry blindly after a false return with submitted set.

Apply one setting or trigger FFC, then confirm it.

Returns
True when the setter was verified or FFC was acknowledged. False on invalid input, budget overflow or any failed step; result->submitted tells whether the device may already have acted.
  • Budget: 1 s; gain and FFC 5 s (gain may involve internal correction).
  • Always wait for an idle mailbox first so a pending command is not overwritten.
  • FFC: standard command 0d c1 02 (OOC+B combined update, not shutter open/close) at 0x1d00, then a fixed 3 s wait (300 x 10 ms) mirroring the vendor's special 3000 ms poll delay, then an idle check. Result is an acknowledgement only; verified stays false.
  • Setters: SET subcommand = getter + 0x40 (0x83->0xc3 image, 0x85->0xc5 TPD), value big-endian in header bytes 6..7 (verified against vendor reference source). Held half to 0x9d00, trigger half to 0x1d08, wait idle, read back, and mark verified only on an exact match.
    Warning
    After a false return with submitted set, never replay the command; read the setting back to learn the device state.

Definition at line 366 of file lwir_state.c.

◆ lwir_state_control_read()

bool lwir_state_control_read ( const struct lwir_state_io * io,
enum lwir_control_kind kind,
struct lwir_control_result * result )

Read one controllable setting without writing anything.

Waits for idle, sends one extended getter and reads the 2-byte reply, all within a 1 s budget.

Parameters
ioTransport; all callbacks required.
kindSetting to read; LWIR_CONTROL_FFC has no value and is rejected.
resultAlways reset when non-NULL; on success readback holds the value.
Returns
True with verified set on success; false with reply.status describing the failure (LWIR_STATE_INVALID for bad arguments or out-of-range values).

Read one controllable setting without writing anything.

Returns
True with verified and readback set; false on bad arguments or any failed step (see result->reply).

Budget 1 s: wait idle, then control_readback(). Only the getter header is written, so submitted stays false.

Definition at line 331 of file lwir_state.c.

◆ lwir_state_format()

size_t lwir_state_format ( const struct lwir_device_state * state,
char * output,
size_t capacity )

Render a snapshot as key=value evidence lines for the JPEG APP14 segment.

Parameters
stateSnapshot; NULL (e.g. synthetic imagery) yields a not_requested header only.
outputDestination; NUL-terminated on success.
capacityBytes available in output.
Returns
Characters written excluding the NUL, or 0 on overflow, NULL/zero-sized output or a corrupt snapshot; output may then hold a truncated prefix.

Render a snapshot as key=value evidence lines for the JPEG APP14 segment.

Returns
Bytes written excluding the NUL; 0 on NULL/zero-sized output, overflow, or a corrupt status/length (output may then hold a truncated prefix).

A fixed header records provenance and two constant caveats: device_state_bench=unverified and device_state_frame_atomic=0. For a requested snapshot, each field adds three lines: status name, reply hex ("unknown" unless OK) and "transport_error,device_status" so failures stay diagnosable.

Note
Returning 0 rather than truncating lets the caller refuse incomplete evidence.

Definition at line 430 of file lwir_state.c.

◆ lwir_state_read()

void lwir_state_read ( const struct lwir_state_io * io,
struct lwir_device_state * state )

Take a best-effort, read-only snapshot of all device-state fields.

Total time is bounded by LWIR_STATE_BUDGET_MS. Unsupported or invalid fields are recorded and the next field is tried; timeout, I/O error or cancellation stops the snapshot and leaves the rest LWIR_STATE_SKIPPED.

Parameters
ioTransport; an unusable table marks field 0 LWIR_STATE_INVALID.
stateFully overwritten; NULL is ignored.
Note
Not frame-atomic: values are read after the frame and may differ from those in effect at exposure.
Warning
An aborted command may leave the mailbox busy, so the next snapshot can report LWIR_STATE_BUSY.

Take a best-effort, read-only snapshot of all device-state fields.

Algorithm:

  1. Zero the state, mark it requested and every field skipped.
  2. Refuse to start unless the mailbox status is idle (0), so a command still running from an earlier aborted snapshot is not clobbered.
  3. For each field in table order: write the command header (standard at 0x1d00, or extended as held half at 0x9d00 plus trigger half at 0x1d08), poll 0x0200 up to 32 times at <= 10 ms intervals until idle, read the reply at 0x1d00 + header length and validate it. Unsupported/invalid fields continue with the next field because the device is still responsive; timeout, I/O error and cancellation stop the snapshot since further transfers would only burn budget or hit a busy mailbox.
    Note
    Failures are reported only through state; field 0 carries LWIR_STATE_INVALID for an unusable io or LWIR_STATE_BUSY for a busy mailbox.

Definition at line 159 of file lwir_state.c.

◆ lwir_state_u16()

bool lwir_state_u16 ( const struct lwir_device_state * state,
enum lwir_state_field field,
uint16_t * value )

Decode a validated two-byte big-endian field.

Parameters
stateSnapshot to read.
fieldField index.
valueOutput, written only on success.
Returns
False for NULL arguments, an out-of-range field, a non-OK status or a non-two-byte (string) field.

Decode a validated two-byte big-endian field.

Returns
False for NULL arguments, invalid index, non-OK status or a string field.

Definition at line 412 of file lwir_state.c.