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
sensor_capture.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/** @file sensor_capture.h
19 * @brief Exact bounded SENSOR02 capture evidence, independent of TIFF byte order.
20 * @details See docs/exif.md for byte offsets. Structural validity does not qualify
21 * exposure timing; the arbiter checks current boot, JPEG dimensions and freshness. */
22#ifndef USHER_SENSOR_CAPTURE_H
23#define USHER_SENSOR_CAPTURE_H
24
25#include <stdbool.h>
26#include <stddef.h>
27#include <stdint.h>
28#include <string.h>
29
30#define SENSOR_CAPTURE_BYTES 104U
31#define SENSOR_CAPTURE_TAG 0xc7a1U
32
39
40/**
41 * @brief Write a fixed-width little-endian integer.
42 * @param[out] data Writable storage for @p bytes octets.
43 * @param value Integer whose least significant bytes are written.
44 * @param bytes Field width from 1 to 8, validated by the caller.
45 * @details Explicit byte offsets keep the record independent of alignment and
46 * host byte order.
47 */
48static inline void sensor_capture_put(unsigned char *data, uint64_t value, size_t bytes)
49{
50 for (size_t index = 0; index < bytes; ++index) data[index] = (unsigned char)(value >> (index * 8));
51}
52
53/**
54 * @brief Read a fixed-width little-endian integer.
55 * @param data Readable storage of at least @p bytes octets.
56 * @param bytes Field width from 1 to 8, validated by the caller.
57 * @return The value zero-extended to 64 bits.
58 * @details Assemble bytes rather than loading a native integer, since fields
59 * can start at unaligned offsets.
60 */
61static inline uint64_t sensor_capture_get(const unsigned char *data, size_t bytes)
62{
63 uint64_t value = 0;
64 for (size_t index = 0; index < bytes; ++index) value |= (uint64_t)data[index] << (index * 8);
65 return value;
66}
67
68/**
69 * @brief Interpret a 64-bit wire field as a signed two's-complement value.
70 * @param value Decoded unsigned bit pattern.
71 * @return Signed value represented by the same bits.
72 * @details For negative values, convert the complement first so the cast never
73 * receives a value outside the signed range.
74 */
75static inline int64_t sensor_capture_signed(uint64_t value)
76{
77 return value <= INT64_MAX ? (int64_t)value : -1 - (int64_t)(UINT64_MAX - value);
78}
79
80/**
81 * @brief Check the structural constraints shared by the wire encoder and decoder.
82 * @param record Nullable capture record.
83 * @return True for JPEG-sized dimensions and a terminated lowercase UUID-shaped boot ID.
84 * @details This checks syntax and dimensions, not whether the boot ID and timing
85 * actually belong to the current capture.
86 */
87static inline bool sensor_capture_valid(const struct sensor_capture *record)
88{
89 if (!record || record->boot_id[36] || record->width < 2 || record->width > 65535
90 || record->height < 2 || record->height > 65535) return false;
91 for (size_t index = 0; index < 36; ++index) {
92 const char character = record->boot_id[index];
93 if (index == 8 || index == 13 || index == 18 || index == 23) {
94 if (character != '-') return false;
95 } else if (!((character >= '0' && character <= '9') || (character >= 'a' && character <= 'f'))) return false;
96 }
97 return true;
98}
99
100/**
101 * @brief Encode a SENSOR02 record in the fixed on-disk layout.
102 * @param record Validated source record; must not overlap @p data.
103 * @param[out] data Destination byte buffer.
104 * @param capacity Available bytes in @p data.
105 * @return True on success; false leaves the destination unchanged.
106 * @details Validate before the first write, then emit the magic and fields at
107 * fixed offsets without copying struct padding.
108 */
109static inline bool sensor_capture_encode(const struct sensor_capture *record, unsigned char *data, size_t capacity)
110{
111 if (!data || capacity < SENSOR_CAPTURE_BYTES || !sensor_capture_valid(record)) return false;
112 const unsigned char magic[8] = {'S','E','N','S','O','R','0','2'};
113 for (size_t index = 0; index < 8; ++index) data[index] = magic[index];
114 for (size_t index = 0; index < 36; ++index) data[8 + index] = (unsigned char)record->boot_id[index];
115 sensor_capture_put(data + 44, record->width, 4);
116 sensor_capture_put(data + 48, record->height, 4);
117 sensor_capture_put(data + 52, record->sequence, 8);
118 sensor_capture_put(data + 60, record->sensor_timestamp_ns, 8);
119 sensor_capture_put(data + 68, record->monotonic_us, 8);
120 sensor_capture_put(data + 76, record->time_error_us, 8);
121 sensor_capture_put(data + 84, (uint64_t)record->exposure_us, 8);
122 sensor_capture_put(data + 92, (uint64_t)record->frame_duration_us, 8);
123 sensor_capture_put(data + 100, record->process_id, 4);
124 return true;
125}
126
127/**
128 * @brief Decode a complete SENSOR02 record.
129 * @param[out] record Destination for the decoded fields.
130 * @param data Serialized source record.
131 * @param size Exact source length in bytes.
132 * @return True on success; false leaves the destination unchanged.
133 * @details Check version and length before indexing the data, then validate a
134 * temporary record before assigning it to the caller's destination.
135 */
136static inline bool sensor_capture_decode(struct sensor_capture *record, const unsigned char *data, size_t size)
137{
138 if (!record || !data || size != SENSOR_CAPTURE_BYTES || memcmp(data, "SENSOR02", 8)) return false;
139 struct sensor_capture decoded;
140 for (size_t index = 0; index < 36; ++index) decoded.boot_id[index] = (char)data[8 + index];
141 decoded.boot_id[36] = '\0';
142 decoded.width = (uint32_t)sensor_capture_get(data + 44, 4);
143 decoded.height = (uint32_t)sensor_capture_get(data + 48, 4);
144 decoded.sequence = sensor_capture_get(data + 52, 8);
145 decoded.sensor_timestamp_ns = sensor_capture_get(data + 60, 8);
146 decoded.monotonic_us = sensor_capture_get(data + 68, 8);
147 decoded.time_error_us = sensor_capture_get(data + 76, 8);
150 decoded.process_id = (uint32_t)sensor_capture_get(data + 100, 4);
151 if (!sensor_capture_valid(&decoded)) return false;
152 *record = decoded;
153 return true;
154}
155
156#endif
static unsigned capacity[COVERAGE_CAMERAS]
size_t size
Definition chdk_pipe.c:143
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
static bool sensor_capture_decode(struct sensor_capture *record, const unsigned char *data, size_t size)
Decode a complete SENSOR02 record.
#define SENSOR_CAPTURE_BYTES
static bool sensor_capture_encode(const struct sensor_capture *record, unsigned char *data, size_t capacity)
Encode a SENSOR02 record in the fixed on-disk layout.
static uint64_t sensor_capture_get(const unsigned char *data, size_t bytes)
Read a fixed-width little-endian integer.
static int64_t sensor_capture_signed(uint64_t value)
Interpret a 64-bit wire field as a signed two's-complement value.
static void sensor_capture_put(unsigned char *data, uint64_t value, size_t bytes)
Write a fixed-width little-endian integer.
static bool sensor_capture_valid(const struct sensor_capture *record)
Check the structural constraints shared by the wire encoder and decoder.
uint64_t monotonic_us
uint64_t sensor_timestamp_ns
int64_t frame_duration_us
uint32_t process_id
uint64_t time_error_us