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
usher_protocol.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 usher_protocol.h
20 * @brief Shared FC/MORA byte-stream UART framing, messages and payload layouts.
21 * @details This is the shared FC/MORA contract: commands and replies cross only the
22 * UART datastream. Both peers compile these message IDs, payload sizes and layouts;
23 * camera implementation, storage and capture scheduling are not part of the wire API.
24 * Multi-byte fields use the shared native layout; both peers must be upgraded
25 * together. The unions are serialization storage, not portable network byte
26 * order. There is no protocol-wide version field; the separate MORA survey
27 * extension declares its own version but is not negotiated by the FC.
28 *
29 * |STX|length|message ID|payload (length-5 bytes)|Checksum A|Checksum B|
30 *
31 * Length counts the entire frame. The checksum covers length, message ID and payload:
32 * @code
33 * usher_ck_a = usher_ck_b = length
34 * for each byte b in message ID followed by payload
35 * usher_ck_a += b;
36 * usher_ck_b += usher_ck_a;
37 * @endcode
38 */
39
40#ifndef USHER_TRANSPORT_H
41#define USHER_TRANSPORT_H
42
43#include <inttypes.h>
44#include <stdbool.h>
45
46/////////////////////////////////////////////////////////////////////
47// MESSAGES
48
49#define USHER_SHOT_DATA_SIZE (4*10)
50
52 struct {
53 int32_t nr;
54 int32_t lat;
55 int32_t lon;
56 int32_t alt;
57 int32_t phi;
58 int32_t theta;
59 int32_t psi;
60 int32_t vground;
61 int32_t course;
62 int32_t groundalt;
65 int32_t i[10];
66};
67
68#define USHER_BUFFER_EMPTY 2
69
70// 0 bytes payload: null
71
72#define USHER_PAYLOAD 3
73#define USHER_PAYLOAD_MSG_SIZE 70
74
75
76// 72 bytes
77
78#define USHER_STATUS 4
79#define USHER_STATUS_MSG_SIZE (4*2)
80
81// 4*2 bytes
84 uint16_t cpu;
85 uint16_t threads;
86 uint16_t shots;
87 uint16_t extra;
90};
91
92/////////////////////////////////////////////////////////////////////
93// CAMERA SELECTION
94
95#define USHER_CAMERA_ALL 0
96#define USHER_CAMERA_CHDK 1
97#define USHER_CAMERA_AICAM 2
98#define USHER_CAMERA_LWIRCAM 3
99#define USHER_CAMERA_EARCAM 4
100#define USHER_CAMERA_DIPLACAM 5
101
102#define USHER_CAMERA_MASK_NONE 0x00U
103#define USHER_CAMERA_MASK_CHDK 0x01U
104#define USHER_CAMERA_MASK_AICAM 0x02U
105#define USHER_CAMERA_MASK_LWIR 0x04U
106#define USHER_CAMERA_MASK_EAR 0x08U
107#define USHER_CAMERA_MASK_DIPLA 0x10U
108#define USHER_CAMERA_MASK_SUPPORTED 0x1FU
109#define USHER_CAMERA_MASK_ALL 0xFFU
110
111#define USHER_SHOOT_MASK 12
112/** One trigger number for a mask of up to eight cameras. request_id correlates
113 * per-camera feedback and is not a photo filename, cryptographic token or GCS ID. */
114#define USHER_SHOOT_MASK_MSG_SIZE (USHER_SHOT_DATA_SIZE + 8)
115
117 struct {
119 uint32_t camera_mask;
120 uint32_t request_id;
123};
124
125/** A terminal observation for one requested camera bit. SAVED means original
126 * plus required flight metadata were published, not that SODA found an object.
127 * RECORDED is accepted non-image work, not an image saved to disk or a valid point.
128 * Missing feedback is UNKNOWN: neither successful capture nor failure is proven. */
129#define USHER_SHOT_RESULT 17
130#define USHER_SHOT_RESULT_MSG_SIZE 16
131#define USHER_SHOT_SAVED 1U
132#define USHER_SHOT_FAILED 2U
133#define USHER_SHOT_SUPERSEDED 3U
134#define USHER_SHOT_RECORDED 4U
135#define USHER_SHOT_UNSUPPORTED 5U
136
138 struct {
139 uint32_t request_id;
140 int32_t number;
141 uint32_t camera_id;
142 uint32_t status;
145};
146
147/** Session control for one camera. A camera that accumulates evidence over time
148 * (acoustic listening, recording, mapping) samples between start and stop; a
149 * camera without a session ignores both. A nonzero session_id is allocated by
150 * the FC and echoed in the point result; start and stop use the same token. */
151#define USHER_STOP_TARGETED 6
152#define USHER_STOP_TARGETED_MSG_SIZE 8
153#define USHER_START_TARGETED 7
154#define USHER_START_TARGETED_MSG_SIZE 8
155
163
164/** A geographic point one camera deduced from its own session, reported on stop.
165 * VALID means the camera produced an estimate, not that the estimate is accurate
166 * or that the object was identified. quality is the camera's own confidence and
167 * is not comparable between different camera types. */
168#define USHER_CAM_POINT_RESULT 18
169#define USHER_CAM_POINT_RESULT_MSG_SIZE (4*9)
170
171#define USHER_CAM_POINT_INVALID 0
172#define USHER_CAM_POINT_VALID 1
173
175 struct {
176 uint32_t camera_id; // 1..8, the camera that deduced this point
177 uint32_t session_id;
178 uint32_t status; // USHER_CAM_POINT_VALID or USHER_CAM_POINT_INVALID
179 int32_t lat; // 1e7 deg
180 int32_t lon; // 1e7 deg
181 int32_t alt_mm; // ellipsoid altitude of the point, same reference as dc_shot alt
182 int32_t agl_mm; // observation height above the point
183 int32_t quality; // 0..1000, camera-defined confidence
184 int32_t metric; // camera-defined scalar (EARcam: loudest level in centi-dB)
187};
188
189/** Repeated point from a saved photo (LOOM_cam uses AIcam ID 2). The positive
190 * FC photo number correlates the reply; this is NOT a stopped-session answer.
191 * Units/status/quality are the same as CAM_POINT_RESULT. A no-match update is
192 * INVALID and must never move a waypoint. Old firmware safely ignores ID 19. */
193#define USHER_CAM_POINT_UPDATE 19
194#define USHER_CAM_POINT_UPDATE_MSG_SIZE (4*9)
204
205#define USHER_CONTROL_NEGOTIATE 20
206#define USHER_CONTROL_HELLO 21
207#define USHER_CONTROL_COMMAND 22
208#define USHER_CONTROL_RESULT 23
209#define USHER_CONTROL_VERSION 1U
210#define USHER_CONTROL_NEGOTIATE_SIZE 9U
211#define USHER_CONTROL_HELLO_SIZE 41U
212#define USHER_CONTROL_COMMAND_SIZE 12U
213#define USHER_CONTROL_RESULT_SIZE 14U
214
215#define CAM_CMD_ZOOM_ABSOLUTE 1U
216#define CAM_CMD_LENS_RETRACT 2U
217#define CAM_CMD_KEEP_AWAKE 3U
218#define CAM_CONTROL_CAP(command) (UINT32_C(1) << (command))
219
220#define CAM_CONTROL_NOT_SENT 0U
221#define CAM_CONTROL_PENDING 1U
222#define CAM_CONTROL_APPLIED 2U
223#define CAM_CONTROL_BUSY 3U
224#define CAM_CONTROL_UNSUPPORTED 4U
225#define CAM_CONTROL_INVALID_VALUE 5U
226#define CAM_CONTROL_FAILED 6U
227#define CAM_CONTROL_UNKNOWN 7U
228#define CAM_CONTROL_PARTIAL 8U
229
230#define CAM_CONTROL_EVIDENCE_NONE 0U
231#define CAM_CONTROL_EVIDENCE_VALUE 1U
232#define CAM_CONTROL_EVIDENCE_PLAYBACK 2U
233
234/////////////////////////////////////////////////////////////////////
235// SENDING
236
237#define USHER_POSE_SAMPLE 8
238#define USHER_POSE_SAMPLE_MSG_SIZE 100
239#define USHER_POSE_SAMPLE_GPS_PRESENT 1U
240#define USHER_POSE_SAMPLE_GPS_HELD 2U
241#define USHER_POSE_SAMPLE_GPS_AGE_VALID 4U
242#define USHER_POSE_SAMPLE_GPS_AGE_SHIFT 8U
243#define USHER_POSE_SAMPLE_GPS_AGE_MASK UINT32_C(0xffffff00)
244
245/** @brief Check the structural consistency of pose-sample GPS flags.
246 * @param flags Received wire flags including the encoded age field.
247 * @return True if all bits are known and the GPS presence and age dependencies hold.
248 * @details Held GPS requires a present fix and valid age. Reject stray age
249 * bits rather than treating them as qualified timing evidence. */
260
282
283#define USHER_CLOCK_REQUEST 9
284#define USHER_CLOCK_REQUEST_MSG_SIZE 8
285#define USHER_CLOCK_REPLY 10
286#define USHER_CLOCK_REPLY_MSG_SIZE 16
287#define USHER_POSE_CLOCKED 11
288#define USHER_POSE_CLOCKED_MSG_SIZE (USHER_POSE_SAMPLE_MSG_SIZE + 8)
289
291 struct {
292 uint32_t token_low;
293 uint32_t token_high;
296};
297
306
314
315/** @name Negotiated survey messages
316 * @brief Separate MORA survey extension; ordinary masked capture does not use it.
317 * @details A nonzero session token identifies the running USHER peer, not a
318 * persistent mission or an authenticated sender. The FC does not currently
319 * negotiate or emit this extension; ordinary masked shots use USHER_SHOT_RESULT
320 * for per-camera feedback. Preserve explicit sizes when extending structures.
321 * @{ */
322#define USHER_CAPTURE_ARBITER_VERSION 1U
323#define USHER_CAPTURE_ARBITER_HELLO 13
324#define USHER_CAPTURE_ARBITER_STATE 14
325#define USHER_CAPTURE_ARBITER_SHOOT 15
326#define USHER_CAPTURE_ARBITER_RESULT 16
327#define USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE 8
328#define USHER_CAPTURE_ARBITER_STATE_MSG_SIZE 12
329#define USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE (USHER_SHOT_DATA_SIZE + 12)
330#define USHER_CAPTURE_ARBITER_RESULT_MSG_SIZE 24
331#define USHER_CAPTURE_ARBITER_SAVED 1U /**< Original and required metadata published; not proof of an object detection. */
332#define USHER_CAPTURE_ARBITER_FAILED 2U /**< Capture/publication failed; other camera bits can still succeed. */
333#define USHER_CAPTURE_ARBITER_EXPIRED 3U /**< Intent or scope no longer current; no exposure is implied. */
334#define USHER_CAPTURE_ARBITER_COVERED 4U /**< Suppressed using trusted same-camera coverage, not a new photo. */
335#define USHER_CAPTURE_ARBITER_SUPERSEDED 5U /**< Waiting capacity reused within this camera; not successful recovery. */
336
337/** @brief USHER-to-FC capability advertisement.
338 * @details version selects this contract; session changes between configured
339 * USHER processes. Receipt renews the FC lease, not the lifetime of old intentions.
340 */
345/** @brief FC-to-USHER survey authorization, independent of individual shot requests.
346 * @details active is 0 or 1; camera_mask selects allowed sensors for this session.
347 * A stop withdraws waiting work without discarding pixels already being saved.
348 */
353/** @brief FC-to-USHER spatial observation request, not a physical shutter acknowledgement.
354 * @details shot retains the original FC number/pose, camera_mask may select several
355 * sensors, and fc_time_us is in the FC's wrapping clock domain. Never compare that
356 * timestamp directly with MORA monotonic time. Each camera completes independently.
357 */
362/** @brief Best-effort USHER-to-FC terminal result for one camera and shot number.
363 * @details ready_mask is a snapshot, not a reservation. saved_count is the aggregate
364 * successful image count in this USHER session, not a per-camera counter. A full
365 * queue or lost link may lose results; never equate absence of telemetry with
366 * absence of an original on disk, or treat this as an exactly-once event stream.
367 */
372/** @} */
373
374// Each platform supplies CameraLinkTransmit; this shared header stays OS-independent.
375
376extern uint8_t usher_ck_a, usher_ck_b;
377
378#define STX 0x99
379
380#define UsherSizeOf(_payload) (_payload+5)
381
382#define UsherPutUint8( _byte) { \
383 usher_ck_a += _byte; \
384 usher_ck_b += usher_ck_a; \
385 CameraLinkTransmit(_byte); \
386 }
387
388#define UsherHeader(msg_id, payload_len) { \
389 CameraLinkTransmit(STX); \
390 uint8_t msg_len = UsherSizeOf( payload_len); \
391 CameraLinkTransmit(msg_len); \
392 usher_ck_a = msg_len; usher_ck_b = msg_len; \
393 UsherPutUint8(msg_id); \
394 }
395
396#define UsherTrailer() { \
397 CameraLinkTransmit(usher_ck_a); \
398 CameraLinkTransmit(usher_ck_b); \
399 }
400
401#define UsherPut1ByteByAddr( _byte) { \
402 uint8_t _x = *(_byte); \
403 UsherPutUint8( _x); \
404 }
405
406/////////////////////////////////////////////////////////////////////
407// PARSING
408
409/**
410 * @brief Persistent state for incremental USHER UART frame parsing.
411 * @details One instance must remain associated with one ordered byte stream. A completed
412 * message remains in @c payload until its consumer clears @c msg_received; feeding later
413 * bytes before that acknowledgement is counted as an error to avoid silently overwriting it.
414 */
416 /** Storage for the validated payload of the most recently completed message. */
417 uint8_t payload[256];
418 /** Count of framing or checksum faults observed while consuming this stream. */
419 uint8_t error;
420 /** Message identifier from the current or most recently completed frame. */
421 uint8_t msg_id;
422 /** True when @c payload contains one complete validated message awaiting dispatch. */
424 /** Number of payload bytes expected in the current frame. */
425 uint8_t payload_len;
426 /** Internal parser state: the next expected position in the frame. */
427 uint8_t status;
428 /** Internal offset into @c payload while a frame is being assembled. */
429 uint8_t payload_idx;
430 /** Running Fletcher-style checksum accumulators for the in-progress frame. */
431 uint8_t ck_a, ck_b;
432};
433
434extern struct usher_transport usher_protocol;
435
436/**
437 * @brief Consume one byte from a USHER UART stream.
438 * @param t Persistent parser state for that stream.
439 * @param c Newly received byte.
440 * @details Frames may be arbitrarily split across calls. On a valid complete frame this sets
441 * @c t->msg_received and leaves the decoded bytes in @c t->payload. The caller must dispatch
442 * the message and clear that flag before supplying bytes for the next frame.
443 * @warning This function is not thread-safe. Serialize access to each @p t instance and do not
444 * alter its fields while a frame is in progress.
445 */
446void parse_usher(struct usher_transport *t, uint8_t c);
447
448#endif
449
Persistent state for incremental USHER UART frame parsing.
uint8_t payload[256]
union dc_shot_union shot
uint8_t bin[USHER_SHOOT_MASK_MSG_SIZE]
struct dc_shot_mask_union::@111210153017120377071246320077003270260354205063 data
struct dc_shot_union::@351207206061007345226276304225222200157171312155 data
int32_t i[10]
uint8_t bin[USHER_SHOT_DATA_SIZE]
struct usher_cam_point_result_union::@250302360075341121230107157174076317247301021274 data
uint8_t bin[USHER_CAM_POINT_RESULT_MSG_SIZE]
struct usher_cam_point_update_union::@102362040132143036341157267241205145176054226171 data
uint8_t bin[USHER_CAM_POINT_UPDATE_MSG_SIZE]
uint8_t bin[USHER_START_TARGETED_MSG_SIZE]
struct usher_camera_session_union::@143240012115064153304013213117135060274266136035 data
USHER-to-FC capability advertisement.
uint8_t bin[USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE]
struct usher_capture_arbiter_hello_union::@225333014064011316233343270044356234016246064344 data
Best-effort USHER-to-FC terminal result for one camera and shot number.
struct usher_capture_arbiter_result_union::@261203127050015377352053047074202002233334373102 data
uint8_t bin[USHER_CAPTURE_ARBITER_RESULT_MSG_SIZE]
FC-to-USHER spatial observation request, not a physical shutter acknowledgement.
uint8_t bin[USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE]
struct usher_capture_arbiter_shoot_union::@051263346153071110145344217246151166245325226104 data
FC-to-USHER survey authorization, independent of individual shot requests.
uint8_t bin[USHER_CAPTURE_ARBITER_STATE_MSG_SIZE]
struct usher_capture_arbiter_state_union::@064116166145364176124043337373233207372124166232 data
struct usher_clock_reply_union::@260221177250276350221210364003171064301345176114 data
union usher_clock_request_union request
uint8_t bin[USHER_CLOCK_REPLY_MSG_SIZE]
uint8_t bin[USHER_CLOCK_REQUEST_MSG_SIZE]
struct usher_clock_request_union::@124322121054031044024143305010352315355331137256 data
union usher_pose_sample_union sample
union usher_clock_request_union request
struct usher_pose_clocked_union::@034256305167013222206020157154353370243343140130 data
uint8_t bin[USHER_POSE_CLOCKED_MSG_SIZE]
uint8_t bin[USHER_POSE_SAMPLE_MSG_SIZE]
union dc_shot_union shot
struct usher_pose_sample_union::@042015206147200076364072004013147106310343341221 data
struct usher_shot_result_union::@105126163243364016207371343346127124162136357026 data
uint8_t bin[USHER_SHOT_RESULT_MSG_SIZE]
uint8_t bin[USHER_STATUS_MSG_SIZE]
struct usher_status_union::usher_status_struct data
struct usher_transport usher_protocol
uint8_t usher_ck_b
uint8_t usher_ck_a
#define USHER_SHOOT_MASK_MSG_SIZE
#define USHER_CAM_POINT_RESULT_MSG_SIZE
#define USHER_CAPTURE_ARBITER_STATE_MSG_SIZE
#define USHER_STATUS_MSG_SIZE
#define USHER_SHOT_DATA_SIZE
#define USHER_CLOCK_REPLY_MSG_SIZE
#define USHER_POSE_CLOCKED_MSG_SIZE
#define USHER_POSE_SAMPLE_GPS_HELD
#define USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE
#define USHER_POSE_SAMPLE_GPS_PRESENT
#define USHER_SHOT_RESULT_MSG_SIZE
#define USHER_CLOCK_REQUEST_MSG_SIZE
#define USHER_CAM_POINT_UPDATE_MSG_SIZE
#define USHER_POSE_SAMPLE_GPS_AGE_MASK
static bool usher_pose_flags_valid(uint32_t flags)
Check the structural consistency of pose-sample GPS flags.
#define USHER_POSE_SAMPLE_GPS_AGE_VALID
#define USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE
#define USHER_START_TARGETED_MSG_SIZE
void parse_usher(struct usher_transport *t, uint8_t c)
Consume one byte from a USHER UART stream.
#define USHER_CAPTURE_ARBITER_RESULT_MSG_SIZE
#define USHER_POSE_SAMPLE_MSG_SIZE