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
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/**
19 * @file lwir_state.h
20 * @brief Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls.
21 * @details The Tiny1-C exposes a command mailbox through a small register window:
22 * - status byte at 0x0200: 0 = idle/done, bit0 = busy, bits 0xfc = error class
23 * (0x08/0x10 unsupported, 0x14 invalid, anything else I/O error);
24 * - standard 8-byte command header written at 0x1d00 (the write executes it);
25 * - extended 16-byte header: bytes 0..7 written to 0x9d00 are only held,
26 * bytes 8..15 written to 0x1d08 trigger execution;
27 * - reply read at 0x1d00 + header length (0x1d08 standard, 0x1d10 extended).
28 *
29 * This module implements only that protocol. Transport is injected through
30 * struct lwir_state_io: the native driver backs it with Linux USBFS control
31 * transfers, host tests back it with fakes. No heap, no memcpy, no global state.
32 *
33 * Two independent entry families exist:
34 * - lwir_state_read(): read-only evidence snapshot taken after a capture,
35 * bounded by #LWIR_STATE_BUDGET_MS and explicitly not frame-atomic;
36 * - lwir_state_control() / lwir_state_control_read(): one targeted write or
37 * read with read-back verification and a submitted-versus-verified result.
38 *
39 * Value ranges and units come from the vendor headers; they describe what the
40 * device accepts, not measured radiometric accuracy.
41 */
42#ifndef LWIRCAM_LWIR_STATE_H
43#define LWIRCAM_LWIR_STATE_H
44
45#include <stdbool.h>
46#include <stddef.h>
47#include <stdint.h>
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53/**
54 * @brief Wall-time budget for one whole lwir_state_read() snapshot, in milliseconds.
55 * @details Keeps post-capture latency bounded. On real hardware all fields do not
56 * always fit: later fields (AGC, mirror/flip) may time out or stay skipped.
57 */
58#define LWIR_STATE_BUDGET_MS 250U
59
60/**
61 * @brief Index of each queried device-state field; also the read order.
62 * @details Fields are read in this order, so earlier entries are the most likely
63 * to complete within #LWIR_STATE_BUDGET_MS. Two-byte values are big-endian;
64 * ranges below are those accepted by lwir_state_read() validation.
65 * - #LWIR_STATE_GAIN: gain select, 0 = low, 1 = high (TPD params, cmd 0x14/0x85 #5).
66 * - #LWIR_STATE_FW_BUILD: firmware build, 64-byte device-info string (0x05/0x84 #5).
67 * - #LWIR_STATE_FW_DATE: firmware date, 64-byte device-info string (0x05/0x84 #1).
68 * - #LWIR_STATE_CHIP: chip identification, 64-byte device-info string (0x05/0x84 #0).
69 * - #LWIR_STATE_SHUTTER: shutter status, two bytes each 0 or 1 (0x0c/0x83).
70 * - #LWIR_STATE_DISTANCE: target distance, 128 units per metre, 0..32767 (TPD #0).
71 * - #LWIR_STATE_REFLECTED_K: reflected temperature in kelvin, 230..900 (TPD #1).
72 * - #LWIR_STATE_AMBIENT_K: ambient temperature in kelvin, 230..900 (TPD #2).
73 * - #LWIR_STATE_EMISSIVITY: emissivity in 1/128, 1..128 (TPD #3).
74 * - #LWIR_STATE_TRANSMITTANCE: atmospheric transmittance in 1/128, 1..128 (TPD #4).
75 * - #LWIR_STATE_TNR: temporal noise reduction level, 0..3 (image params 0x14/0x83 #0).
76 * - #LWIR_STATE_SNR: spatial noise reduction level, 0..3 (image #1).
77 * - #LWIR_STATE_DDE: digital detail enhancement level, 0..6 (image #2).
78 * - #LWIR_STATE_BRIGHTNESS: display brightness, 0..255 (image #3).
79 * - #LWIR_STATE_CONTRAST: display contrast, 0..255 (image #4).
80 * - #LWIR_STATE_AGC_MODE: automatic gain control mode, 0..5 (image #5).
81 * - #LWIR_STATE_AGC_MAX_GAIN: AGC maximum gain, 0..255 (image #6).
82 * - #LWIR_STATE_AGC_BOS: AGC brightness offset, 0..255 (image #7).
83 * - #LWIR_STATE_AGC_ENABLE: AGC enable, 0 or 1 (image #8).
84 * - #LWIR_STATE_MIRROR_FLIP: mirror/flip combination, 0..3 (image #9).
85 * - #LWIR_STATE_FIELDS: number of fields, not a field.
86 */
96
97/**
98 * @brief Outcome of one field read or one control operation.
99 * @details The numeric order is part of the evidence format: lwir_state_format()
100 * maps it to text by index.
101 * - #LWIR_STATE_NOT_REQUESTED: zero value; nothing was attempted.
102 * - #LWIR_STATE_OK: reply received and validated (or setting verified).
103 * - #LWIR_STATE_UNSUPPORTED: device status error class 0x08 or 0x10.
104 * - #LWIR_STATE_TIMEOUT: transfer returned -7, the budget ran out, or polling
105 * never saw the mailbox go idle.
106 * - #LWIR_STATE_IO_ERROR: other negative or short transfer, or any other device
107 * error class.
108 * - #LWIR_STATE_INVALID: device error class 0x14, implausible/out-of-range reply,
109 * unusable arguments/callbacks, or a control read-back mismatch.
110 * - #LWIR_STATE_BUSY: the mailbox was not idle when a snapshot started; reported
111 * on the first field only, nothing was sent.
112 * - #LWIR_STATE_SKIPPED: the snapshot stopped before reaching this field.
113 * - #LWIR_STATE_CANCELLED: transfer returned -10 or the pause callback refused.
114 */
120
121/** @brief Raw result of one mailbox query, kept verbatim as evidence. */
123 enum lwir_state_status status; ///< Outcome; data is meaningful only for #LWIR_STATE_OK.
124 /** Reply bytes exactly as received: big-endian for two-byte values; 64-byte
125 * device-info strings are not guaranteed to be NUL-terminated. */
126 uint8_t data[64];
127 uint8_t length; ///< Valid bytes in data (2 or 64); 0 unless a reply was accepted.
128 uint8_t device_status; ///< Last status byte read from 0x0200; 0 if none was read.
129 /** Return value of the last failing transfer callback (negative code or short
130 * byte count); 0 when no transfer failed. */
132};
133
134/** @brief One post-capture snapshot of all #lwir_state_field values. */
136 struct lwir_state_value values[LWIR_STATE_FIELDS]; ///< Indexed by enum lwir_state_field.
137 uint64_t started_us; ///< now_us() before the first transfer; clock domain is the io provider's.
138 uint64_t finished_us; ///< now_us() after the last attempt; 0 if the io table was unusable.
139 bool requested; ///< True once lwir_state_read() ran; false means no device state exists.
140};
141
142/**
143 * @brief Transport and clock callbacks driving the mailbox protocol.
144 * @details All callbacks receive @c context unchanged. All three function
145 * pointers are required; a table with any NULL is rejected as invalid.
146 */
148 void *context; ///< Opaque provider state (USBFS session, test fake).
149 /**
150 * @brief Move @p length bytes between @p data and mailbox @p address.
151 * @param input True reads from the device into @p data; false writes @p data.
152 * @param timeout_ms Per-transfer limit, never 0 and at most 50 ms.
153 * @return Bytes transferred. Any value other than @p length is a failure:
154 * -7 means timeout, -10 means cancelled, anything else is an I/O error.
155 * @warning A failed or late write may still have reached the device.
156 */
157 int (*transfer)(void *context, bool input, uint16_t address, uint8_t *data,
158 unsigned length, unsigned timeout_ms);
159 /** @brief Current time in microseconds; must be monotonic for budgets to hold. */
160 uint64_t (*now_us)(void *context);
161 /** @brief Sleep about @p milliseconds; return false to cancel the whole operation. */
162 bool (*pause)(void *context, unsigned milliseconds);
163};
164
165/**
166 * @brief Settings that lwir_state_control() may change.
167 * - #LWIR_CONTROL_GAIN: gain select, value 0 (low) or 1 (high); 5 s budget because
168 * the camera may run internal correction after switching.
169 * - #LWIR_CONTROL_EMISSIVITY: emissivity in 1/128, value 1..128.
170 * - #LWIR_CONTROL_AGC_MODE: AGC mode, value 0..5.
171 * - #LWIR_CONTROL_AGC_ENABLE: AGC enable, value 0 or 1.
172 * - #LWIR_CONTROL_FFC: flat-field correction (vendor OOC+B combined update, not a
173 * shutter open/close); value must be 0; acknowledgement only, never verified.
174 */
179
180/** @brief One requested setting change; validate with lwir_control_valid(). */
182 enum lwir_control_kind kind; ///< Setting to change.
183 uint16_t value; ///< New value in the units of the matching #lwir_state_field.
184};
185
186/**
187 * @brief Outcome of lwir_state_control() or lwir_state_control_read().
188 * @details @c submitted and @c verified are deliberately separate:
189 * - @c submitted is set just before the executing (trigger) write. Once true, the
190 * device may have applied the command even if the call failed, so callers must
191 * never replay automatically; read the setting back instead.
192 * - @c verified is true only when an exact read-back matched (setters) or the
193 * read-back succeeded (control_read). FFC never sets it.
194 */
196 struct lwir_state_value reply; ///< Status/transport detail of the last step reached.
197 bool submitted, verified; ///< See struct description; both false after early rejection.
198 uint16_t readback; ///< Value read back; meaningful only once a read-back reply arrived.
199};
200
201/**
202 * @brief Check a control request against the vendor value ranges.
203 * @param request Request to check; NULL is rejected.
204 * @return True if the kind is known and the value is in range (FFC requires 0).
205 */
207/**
208 * @brief Read one controllable setting without writing anything.
209 * @details Waits for idle, sends one extended getter and reads the 2-byte reply,
210 * all within a 1 s budget.
211 * @param io Transport; all callbacks required.
212 * @param kind Setting to read; #LWIR_CONTROL_FFC has no value and is rejected.
213 * @param result Always reset when non-NULL; on success readback holds the value.
214 * @return True with verified set on success; false with reply.status describing
215 * the failure (#LWIR_STATE_INVALID for bad arguments or out-of-range values).
216 */
217bool lwir_state_control_read(const struct lwir_state_io *io, enum lwir_control_kind kind,
219/**
220 * @brief Apply one setting or trigger FFC, then confirm it.
221 * @details Setters write the value and verify it by exact read-back within 1 s
222 * (gain: 5 s). FFC waits 3 s and an idle mailbox within 5 s, and reports
223 * acknowledgement only.
224 * @param io Transport; all callbacks required.
225 * @param request Validated with lwir_control_valid().
226 * @param result Always reset when non-NULL; see struct lwir_control_result.
227 * @return True when completed (and verified for setters). False otherwise;
228 * check result->submitted before deciding anything about device state.
229 * @warning Never retry blindly after a false return with submitted set.
230 */
231bool lwir_state_control(const struct lwir_state_io *io, const struct lwir_control_request *request,
233/**
234 * @brief Take a best-effort, read-only snapshot of all device-state fields.
235 * @details Total time is bounded by #LWIR_STATE_BUDGET_MS. Unsupported or invalid
236 * fields are recorded and the next field is tried; timeout, I/O error or
237 * cancellation stops the snapshot and leaves the rest #LWIR_STATE_SKIPPED.
238 * @param io Transport; an unusable table marks field 0 #LWIR_STATE_INVALID.
239 * @param state Fully overwritten; NULL is ignored.
240 * @note Not frame-atomic: values are read after the frame and may differ from
241 * those in effect at exposure.
242 * @warning An aborted command may leave the mailbox busy, so the next snapshot
243 * can report #LWIR_STATE_BUSY.
244 */
245void lwir_state_read(const struct lwir_state_io *io, struct lwir_device_state *state);
246/**
247 * @brief Decode a validated two-byte big-endian field.
248 * @param state Snapshot to read.
249 * @param field Field index.
250 * @param value Output, written only on success.
251 * @return False for NULL arguments, an out-of-range field, a non-OK status or a
252 * non-two-byte (string) field.
253 */
254bool lwir_state_u16(const struct lwir_device_state *state, enum lwir_state_field field, uint16_t *value);
255/**
256 * @brief Render a snapshot as key=value evidence lines for the JPEG APP14 segment.
257 * @param state Snapshot; NULL (e.g. synthetic imagery) yields a not_requested header only.
258 * @param output Destination; NUL-terminated on success.
259 * @param capacity Bytes available in output.
260 * @return Characters written excluding the NUL, or 0 on overflow, NULL/zero-sized
261 * output or a corrupt snapshot; output may then hold a truncated prefix.
262 */
263size_t lwir_state_format(const struct lwir_device_state *state, char *output, size_t capacity);
264
265#ifdef __cplusplus
266}
267#endif
268#endif
static unsigned capacity[COVERAGE_CAMERAS]
static uint64_t milliseconds(void)
Read elapsed-time evidence unaffected by changes to civil time.
union dc_shot_union request
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.
Definition lwir_state.c:412
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.
Definition lwir_state.c:159
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.
Definition lwir_state.c:331
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.
Definition lwir_state.c:366
lwir_state_field
Index of each queried device-state field; also the read order.
Definition lwir_state.h:87
@ LWIR_STATE_REFLECTED_K
Definition lwir_state.h:89
@ LWIR_STATE_AGC_ENABLE
Definition lwir_state.h:93
@ LWIR_STATE_TRANSMITTANCE
Definition lwir_state.h:90
@ LWIR_STATE_AGC_MODE
Definition lwir_state.h:92
@ LWIR_STATE_GAIN
Definition lwir_state.h:88
@ LWIR_STATE_AMBIENT_K
Definition lwir_state.h:90
@ LWIR_STATE_EMISSIVITY
Definition lwir_state.h:90
@ LWIR_STATE_MIRROR_FLIP
Definition lwir_state.h:93
@ LWIR_STATE_SHUTTER
Definition lwir_state.h:89
@ LWIR_STATE_FW_BUILD
Definition lwir_state.h:88
@ LWIR_STATE_CHIP
Definition lwir_state.h:88
@ LWIR_STATE_FW_DATE
Definition lwir_state.h:88
@ LWIR_STATE_FIELDS
Definition lwir_state.h:94
@ LWIR_STATE_DISTANCE
Definition lwir_state.h:89
@ LWIR_STATE_SNR
Definition lwir_state.h:91
@ LWIR_STATE_DDE
Definition lwir_state.h:91
@ LWIR_STATE_AGC_MAX_GAIN
Definition lwir_state.h:92
@ LWIR_STATE_CONTRAST
Definition lwir_state.h:92
@ LWIR_STATE_TNR
Definition lwir_state.h:91
@ LWIR_STATE_BRIGHTNESS
Definition lwir_state.h:91
@ LWIR_STATE_AGC_BOS
Definition lwir_state.h:93
lwir_control_kind
Settings that lwir_state_control() may change.
Definition lwir_state.h:175
@ LWIR_CONTROL_GAIN
Definition lwir_state.h:176
@ LWIR_CONTROL_FFC
Definition lwir_state.h:177
@ LWIR_CONTROL_AGC_MODE
Definition lwir_state.h:176
@ LWIR_CONTROL_EMISSIVITY
Definition lwir_state.h:176
@ LWIR_CONTROL_AGC_ENABLE
Definition lwir_state.h:177
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.
Definition lwir_state.c:430
bool lwir_control_valid(const struct lwir_control_request *request)
Check a control request against the vendor value ranges.
Definition lwir_state.c:231
lwir_state_status
Outcome of one field read or one control operation.
Definition lwir_state.h:115
@ LWIR_STATE_NOT_REQUESTED
Definition lwir_state.h:116
@ LWIR_STATE_INVALID
Definition lwir_state.h:117
@ LWIR_STATE_OK
Definition lwir_state.h:116
@ LWIR_STATE_UNSUPPORTED
Definition lwir_state.h:116
@ LWIR_STATE_TIMEOUT
Definition lwir_state.h:117
@ LWIR_STATE_BUSY
Definition lwir_state.h:118
@ LWIR_STATE_SKIPPED
Definition lwir_state.h:118
@ LWIR_STATE_CANCELLED
Definition lwir_state.h:118
@ LWIR_STATE_IO_ERROR
Definition lwir_state.h:117
static FILE * output
Definition pose_log.c:77
One requested setting change; validate with lwir_control_valid().
Definition lwir_state.h:181
uint16_t value
New value in the units of the matching lwir_state_field.
Definition lwir_state.h:183
enum lwir_control_kind kind
Setting to change.
Definition lwir_state.h:182
Outcome of lwir_state_control() or lwir_state_control_read().
Definition lwir_state.h:195
bool verified
See struct description; both false after early rejection.
Definition lwir_state.h:197
uint16_t readback
Value read back; meaningful only once a read-back reply arrived.
Definition lwir_state.h:198
struct lwir_state_value reply
Status/transport detail of the last step reached.
Definition lwir_state.h:196
One post-capture snapshot of all lwir_state_field values.
Definition lwir_state.h:135
bool requested
True once lwir_state_read() ran; false means no device state exists.
Definition lwir_state.h:139
uint64_t started_us
now_us() before the first transfer; clock domain is the io provider's.
Definition lwir_state.h:137
struct lwir_state_value values[LWIR_STATE_FIELDS]
Indexed by enum lwir_state_field.
Definition lwir_state.h:136
uint64_t finished_us
now_us() after the last attempt; 0 if the io table was unusable.
Definition lwir_state.h:138
Transport and clock callbacks driving the mailbox protocol.
Definition lwir_state.h:147
int(* transfer)(void *context, bool input, uint16_t address, uint8_t *data, unsigned length, unsigned timeout_ms)
Move length bytes between data and mailbox address.
Definition lwir_state.h:157
void * context
Opaque provider state (USBFS session, test fake).
Definition lwir_state.h:148
bool(* pause)(void *context, unsigned milliseconds)
Sleep about milliseconds; return false to cancel the whole operation.
Definition lwir_state.h:162
uint64_t(* now_us)(void *context)
Current time in microseconds; must be monotonic for budgets to hold.
Definition lwir_state.h:160
Raw result of one mailbox query, kept verbatim as evidence.
Definition lwir_state.h:122
enum lwir_state_status status
Outcome; data is meaningful only for LWIR_STATE_OK.
Definition lwir_state.h:123
uint8_t data[64]
Definition lwir_state.h:126
uint8_t length
Valid bytes in data (2 or 64); 0 unless a reply was accepted.
Definition lwir_state.h:127
uint8_t device_status
Last status byte read from 0x0200; 0 if none was read.
Definition lwir_state.h:128
struct usher_control_result result
Definition usher.c:377