Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls. More...
#include <stdbool.h>#include <stddef.h>#include <stdint.h>

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. | |
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:
- lwir_state_read(): read-only evidence snapshot taken after a capture, bounded by LWIR_STATE_BUDGET_MS and explicitly not frame-atomic;
- lwir_state_control() / lwir_state_control_read(): one targeted write or read with read-back verification and a submitted-versus-verified result.
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
| enum lwir_control_kind |
Settings that lwir_state_control() may change.
- LWIR_CONTROL_GAIN: gain select, value 0 (low) or 1 (high); 5 s budget because the camera may run internal correction after switching.
- LWIR_CONTROL_EMISSIVITY: emissivity in 1/128, value 1..128.
- LWIR_CONTROL_AGC_MODE: AGC mode, value 0..5.
- LWIR_CONTROL_AGC_ENABLE: AGC enable, value 0 or 1.
- LWIR_CONTROL_FFC: flat-field correction (vendor OOC+B combined update, not a shutter open/close); value must be 0; acknowledgement only, never verified.
| 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
| enum 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.
- LWIR_STATE_GAIN: gain select, 0 = low, 1 = high (TPD params, cmd 0x14/0x85 #5).
- LWIR_STATE_FW_BUILD: firmware build, 64-byte device-info string (0x05/0x84 #5).
- LWIR_STATE_FW_DATE: firmware date, 64-byte device-info string (0x05/0x84 #1).
- LWIR_STATE_CHIP: chip identification, 64-byte device-info string (0x05/0x84 #0).
- LWIR_STATE_SHUTTER: shutter status, two bytes each 0 or 1 (0x0c/0x83).
- LWIR_STATE_DISTANCE: target distance, 128 units per metre, 0..32767 (TPD #0).
- LWIR_STATE_REFLECTED_K: reflected temperature in kelvin, 230..900 (TPD #1).
- LWIR_STATE_AMBIENT_K: ambient temperature in kelvin, 230..900 (TPD #2).
- LWIR_STATE_EMISSIVITY: emissivity in 1/128, 1..128 (TPD #3).
- LWIR_STATE_TRANSMITTANCE: atmospheric transmittance in 1/128, 1..128 (TPD #4).
- LWIR_STATE_TNR: temporal noise reduction level, 0..3 (image params 0x14/0x83 #0).
- LWIR_STATE_SNR: spatial noise reduction level, 0..3 (image #1).
- LWIR_STATE_DDE: digital detail enhancement level, 0..6 (image #2).
- LWIR_STATE_BRIGHTNESS: display brightness, 0..255 (image #3).
- LWIR_STATE_CONTRAST: display contrast, 0..255 (image #4).
- LWIR_STATE_AGC_MODE: automatic gain control mode, 0..5 (image #5).
- LWIR_STATE_AGC_MAX_GAIN: AGC maximum gain, 0..255 (image #6).
- LWIR_STATE_AGC_BOS: AGC brightness offset, 0..255 (image #7).
- LWIR_STATE_AGC_ENABLE: AGC enable, 0 or 1 (image #8).
- LWIR_STATE_MIRROR_FLIP: mirror/flip combination, 0..3 (image #9).
- LWIR_STATE_FIELDS: number of fields, not a field.
Definition at line 87 of file lwir_state.h.
◆ lwir_state_status
| enum 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.
- LWIR_STATE_NOT_REQUESTED: zero value; nothing was attempted.
- LWIR_STATE_OK: reply received and validated (or setting verified).
- LWIR_STATE_UNSUPPORTED: device status error class 0x08 or 0x10.
- LWIR_STATE_TIMEOUT: transfer returned -7, the budget ran out, or polling never saw the mailbox go idle.
- LWIR_STATE_IO_ERROR: other negative or short transfer, or any other device error class.
- LWIR_STATE_INVALID: device error class 0x14, implausible/out-of-range reply, unusable arguments/callbacks, or a control read-back mismatch.
- LWIR_STATE_BUSY: the mailbox was not idle when a snapshot started; reported on the first field only, nothing was sent.
- LWIR_STATE_SKIPPED: the snapshot stopped before reaching this field.
- LWIR_STATE_CANCELLED: transfer returned -10 or the pause callback refused.
| 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
-
request Request 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
-
io Transport; all callbacks required. request Validated with lwir_control_valid(). result Always 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
-
io Transport; all callbacks required. kind Setting to read; LWIR_CONTROL_FFC has no value and is rejected. result Always 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
-
state Snapshot; NULL (e.g. synthetic imagery) yields a not_requested header only. output Destination; NUL-terminated on success. capacity Bytes 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
-
io Transport; an unusable table marks field 0 LWIR_STATE_INVALID. state Fully 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:
- Zero the state, mark it requested and every field skipped.
- Refuse to start unless the mailbox status is idle (0), so a command still running from an earlier aborted snapshot is not clobbered.
- 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 unusableioor 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
-
state Snapshot to read. field Field index. value Output, 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.