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

Tiny1-C vendor mailbox protocol: snapshot reads, controls and evidence text. More...

#include "lwir_state.h"
#include <stdio.h>
Include dependency graph for lwir_state.c:

Go to the source code of this file.

Data Structures

struct  state_query
 One mailbox getter, shared by snapshot reads and control read-back. More...

Functions

static unsigned remaining_ms (const struct lwir_state_io *io, uint64_t deadline)
 Time left before deadline, as a per-transfer timeout.
static bool transfer (const struct lwir_state_io *io, uint64_t deadline, bool input, uint16_t address, uint8_t *data, unsigned length, struct lwir_state_value *value)
 Perform one deadline-bounded mailbox transfer and classify failure.
static bool valid_value (enum lwir_state_field field, const uint8_t *data)
 Plausibility check of one snapshot reply.
void lwir_state_read (const struct lwir_state_io *io, struct lwir_device_state *state)
 Read all fields of struct lwir_device_state within LWIR_STATE_BUDGET_MS.
bool lwir_control_valid (const struct lwir_control_request *request)
 Range-check a control request (vendor-header limits).
static bool control_idle (const struct lwir_state_io *io, uint64_t deadline, struct lwir_state_value *reply)
 Poll the mailbox status until idle, an error class, or the deadline.
static const struct state_query * control_query (enum lwir_control_kind kind)
 Map a control to the getter row whose subcommand/parameter it writes.
static bool control_readback (const struct lwir_state_io *io, uint64_t deadline, const struct state_query *query, struct lwir_control_result *result)
 Read one extended two-byte setting back from the device.
bool lwir_state_control_read (const struct lwir_state_io *io, enum lwir_control_kind kind, struct lwir_control_result *result)
 Targeted read of one controllable setting; performs no setting writes.
bool lwir_state_control (const struct lwir_state_io *io, const struct lwir_control_request *request, struct lwir_control_result *result)
 Apply one setting with read-back verification, or trigger FFC.
bool lwir_state_u16 (const struct lwir_device_state *state, enum lwir_state_field field, uint16_t *value)
 Decode a validated big-endian two-byte snapshot field.
size_t lwir_state_format (const struct lwir_device_state *state, char *output, size_t capacity)
 Render snapshot evidence as key=value lines for the JPEG APP14 segment.

Variables

static const struct state_query queries [LWIR_STATE_FIELDS]
 Getter table indexed by enum lwir_state_field; names become evidence keys.

Detailed Description

Tiny1-C vendor mailbox protocol: snapshot reads, controls and evidence text.

Transport-agnostic implementation of the protocol summarised in lwir_state.h. Every operation is driven by an absolute deadline: each transfer timeout is the remaining budget capped at 50 ms, and every poll loop is bounded both by an iteration cap and by that deadline, so a stuck device cannot stall the capture path. Storage is caller-owned or on the stack; no heap, no memcpy.

Definition in file lwir_state.c.

Function Documentation

◆ control_idle()

bool control_idle ( const struct lwir_state_io * io,
uint64_t deadline,
struct lwir_state_value * reply )
static

Poll the mailbox status until idle, an error class, or the deadline.

Parameters
ioTransport.
deadlineAbsolute deadline in now_us() microseconds.
replyReceives device_status and the failure status.
Returns
True once status reads 0. False with LWIR_STATE_UNSUPPORTED, LWIR_STATE_INVALID or LWIR_STATE_IO_ERROR for an error class, LWIR_STATE_CANCELLED, or LWIR_STATE_TIMEOUT when the deadline or the 512-poll cap is reached; transfer failures keep transfer()'s status.

Pauses at most 10 ms between polls. The larger cap than the snapshot's 32 polls fits the 1-5 s control budgets.

Definition at line 255 of file lwir_state.c.

◆ control_query()

const struct state_query * control_query ( enum lwir_control_kind kind)
static

Map a control to the getter row whose subcommand/parameter it writes.

Parameters
kindControl kind.
Returns
Table row, or NULL for FFC/unknown kinds (no readable value).
Note
Reusing the snapshot table keeps getter, setter and range limits in one place.

Definition at line 283 of file lwir_state.c.

◆ control_readback()

bool control_readback ( const struct lwir_state_io * io,
uint64_t deadline,
const struct state_query * query,
struct lwir_control_result * result )
static

Read one extended two-byte setting back from the device.

Parameters
ioTransport.
deadlineAbsolute deadline in now_us() microseconds.
queryGetter row (extended command 0x14).
resultReceives reply bytes, length 2 and the decoded readback.
Returns
True for an in-range value. False with the failing step's status, or LWIR_STATE_INVALID when the value is outside the vendor range (readback is still stored for diagnostics).

Writes the held half (0x9d00), triggers with the second half (0x1d08, byte 15 = reply length 2), waits idle, then reads the big-endian reply at 0x1d10.

Precondition
The mailbox is idle.

Definition at line 307 of file lwir_state.c.

◆ lwir_control_valid()

bool lwir_control_valid ( const struct lwir_control_request * request)

Range-check a control request (vendor-header limits).

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 with read-back verification, or trigger FFC.

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 )

Targeted read of one controllable setting; performs no setting writes.

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 snapshot evidence as key=value lines for the JPEG APP14 segment.

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 )

Read all fields of struct lwir_device_state within LWIR_STATE_BUDGET_MS.

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 big-endian two-byte snapshot 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.

◆ remaining_ms()

unsigned remaining_ms ( const struct lwir_state_io * io,
uint64_t deadline )
static

Time left before deadline, as a per-transfer timeout.

Parameters
ioClock provider.
deadlineAbsolute deadline in now_us() microseconds.
Returns
Whole milliseconds remaining, capped at 50; 0 when less than 1 ms remains.
Note
The 50 ms cap keeps one slow transfer from consuming the whole budget.

Definition at line 81 of file lwir_state.c.

◆ transfer()

bool transfer ( const struct lwir_state_io * io,
uint64_t deadline,
bool input,
uint16_t address,
uint8_t * data,
unsigned length,
struct lwir_state_value * value )
static

Perform one deadline-bounded mailbox transfer and classify failure.

Parameters
ioTransport.
deadlineAbsolute deadline in now_us() microseconds.
inputTrue to read from the device, false to write.
addressMailbox register address.
dataSource or destination buffer of at least length bytes.
lengthExact number of bytes expected.
valueReceives status (and transport_error) on failure; untouched on success.
Returns
True only for a complete transfer that also finished before the deadline.
Warning
A complete transfer that ends after the deadline is reported as LWIR_STATE_TIMEOUT even though a write may have executed.

Definition at line 102 of file lwir_state.c.

◆ valid_value()

bool valid_value ( enum lwir_state_field field,
const uint8_t * data )
static

Plausibility check of one snapshot reply.

Parameters
fieldField the reply belongs to.
dataReply bytes, at least the field's query length.
Returns
True if acceptable as evidence.

64-byte strings must be neither all zero (no data) nor all 0xff (erased/unprogrammed); shutter bytes must each be 0 or 1; other fields are big-endian and must fall inside the vendor range.

Definition at line 127 of file lwir_state.c.

Variable Documentation

◆ queries

const struct state_query queries[LWIR_STATE_FIELDS]
static
Initial value:
= {
{"gain_select", 0x14, 0x85, 5, 2, 0, 1},
{"fw_build", 0x05, 0x84, 5, 64, 0, 0},
{"fw_date", 0x05, 0x84, 1, 64, 0, 0},
{"chip", 0x05, 0x84, 0, 64, 0, 0},
{"shutter", 0x0c, 0x83, 0, 2, 0, 0},
{"distance_128_per_m", 0x14, 0x85, 0, 2, 0, 32767},
{"reflected_k", 0x14, 0x85, 1, 2, 230, 900},
{"ambient_k", 0x14, 0x85, 2, 2, 230, 900},
{"emissivity_128", 0x14, 0x85, 3, 2, 1, 128},
{"transmittance_128", 0x14, 0x85, 4, 2, 1, 128},
{"tnr", 0x14, 0x83, 0, 2, 0, 3},
{"snr", 0x14, 0x83, 1, 2, 0, 3},
{"dde", 0x14, 0x83, 2, 2, 0, 6},
{"brightness", 0x14, 0x83, 3, 2, 0, 255},
{"contrast", 0x14, 0x83, 4, 2, 0, 255},
{"agc_mode", 0x14, 0x83, 5, 2, 0, 5},
{"agc_max_gain", 0x14, 0x83, 6, 2, 0, 255},
{"agc_bos", 0x14, 0x83, 7, 2, 0, 255},
{"agc_enable", 0x14, 0x83, 8, 2, 0, 1},
{"mirror_flip", 0x14, 0x83, 9, 2, 0, 3}
}

Getter table indexed by enum lwir_state_field; names become evidence keys.

Ranges come from the vendor headers. Order is read order, so the most important evidence (gain, firmware identity) is fetched while budget remains.

Definition at line 51 of file lwir_state.c.