Shared FC/MORA byte-stream UART framing, messages and payload layouts. More...
#include <inttypes.h>#include <stdbool.h>

Go to the source code of this file.
Data Structures | |
| union | dc_shot_union |
| union | usher_status_union |
| struct | usher_status_union::usher_status_struct |
| union | dc_shot_mask_union |
| union | usher_shot_result_union |
| union | usher_camera_session_union |
| union | usher_cam_point_result_union |
| union | usher_cam_point_update_union |
| union | usher_pose_sample_union |
| union | usher_clock_request_union |
| union | usher_clock_reply_union |
| union | usher_pose_clocked_union |
| union | usher_capture_arbiter_hello_union |
| USHER-to-FC capability advertisement. More... | |
| union | usher_capture_arbiter_state_union |
| FC-to-USHER survey authorization, independent of individual shot requests. More... | |
| union | usher_capture_arbiter_shoot_union |
| FC-to-USHER spatial observation request, not a physical shutter acknowledgement. More... | |
| union | usher_capture_arbiter_result_union |
| Best-effort USHER-to-FC terminal result for one camera and shot number. More... | |
| struct | usher_transport |
| Persistent state for incremental USHER UART frame parsing. More... | |
Functions | |
| static bool | usher_pose_flags_valid (uint32_t flags) |
| Check the structural consistency of pose-sample GPS flags. | |
| void | parse_usher (struct usher_transport *t, uint8_t c) |
| Consume one byte from a USHER UART stream. | |
Variables | |
| uint8_t | usher_ck_a |
| uint8_t | usher_ck_b |
| struct usher_transport | usher_protocol |
Detailed Description
Shared FC/MORA byte-stream UART framing, messages and payload layouts.
This is the shared FC/MORA contract: commands and replies cross only the UART datastream. Both peers compile these message IDs, payload sizes and layouts; camera implementation, storage and capture scheduling are not part of the wire API. Multi-byte fields use the shared native layout; both peers must be upgraded together. The unions are serialization storage, not portable network byte order. There is no protocol-wide version field; the separate MORA survey extension declares its own version but is not negotiated by the FC.
|STX|length|message ID|payload (length-5 bytes)|Checksum A|Checksum B|
Length counts the entire frame. The checksum covers length, message ID and payload:
Definition in file usher_protocol.h.
Macro Definition Documentation
◆ CAM_CMD_KEEP_AWAKE
| #define CAM_CMD_KEEP_AWAKE 3U |
Definition at line 217 of file usher_protocol.h.
◆ CAM_CMD_LENS_RETRACT
| #define CAM_CMD_LENS_RETRACT 2U |
Definition at line 216 of file usher_protocol.h.
◆ CAM_CMD_ZOOM_ABSOLUTE
| #define CAM_CMD_ZOOM_ABSOLUTE 1U |
Definition at line 215 of file usher_protocol.h.
◆ CAM_CONTROL_APPLIED
| #define CAM_CONTROL_APPLIED 2U |
Definition at line 222 of file usher_protocol.h.
◆ CAM_CONTROL_BUSY
| #define CAM_CONTROL_BUSY 3U |
Definition at line 223 of file usher_protocol.h.
◆ CAM_CONTROL_CAP
| #define CAM_CONTROL_CAP | ( | command | ) |
Definition at line 218 of file usher_protocol.h.
◆ CAM_CONTROL_EVIDENCE_NONE
| #define CAM_CONTROL_EVIDENCE_NONE 0U |
Definition at line 230 of file usher_protocol.h.
◆ CAM_CONTROL_EVIDENCE_PLAYBACK
| #define CAM_CONTROL_EVIDENCE_PLAYBACK 2U |
Definition at line 232 of file usher_protocol.h.
◆ CAM_CONTROL_EVIDENCE_VALUE
| #define CAM_CONTROL_EVIDENCE_VALUE 1U |
Definition at line 231 of file usher_protocol.h.
◆ CAM_CONTROL_FAILED
| #define CAM_CONTROL_FAILED 6U |
Definition at line 226 of file usher_protocol.h.
◆ CAM_CONTROL_INVALID_VALUE
| #define CAM_CONTROL_INVALID_VALUE 5U |
Definition at line 225 of file usher_protocol.h.
◆ CAM_CONTROL_NOT_SENT
| #define CAM_CONTROL_NOT_SENT 0U |
Definition at line 220 of file usher_protocol.h.
◆ CAM_CONTROL_PARTIAL
| #define CAM_CONTROL_PARTIAL 8U |
Definition at line 228 of file usher_protocol.h.
◆ CAM_CONTROL_PENDING
| #define CAM_CONTROL_PENDING 1U |
Definition at line 221 of file usher_protocol.h.
◆ CAM_CONTROL_UNKNOWN
| #define CAM_CONTROL_UNKNOWN 7U |
Definition at line 227 of file usher_protocol.h.
◆ CAM_CONTROL_UNSUPPORTED
| #define CAM_CONTROL_UNSUPPORTED 4U |
Definition at line 224 of file usher_protocol.h.
◆ STX
| #define STX 0x99 |
Definition at line 378 of file usher_protocol.h.
◆ USHER_BUFFER_EMPTY
| #define USHER_BUFFER_EMPTY 2 |
Definition at line 68 of file usher_protocol.h.
◆ USHER_CAM_POINT_INVALID
| #define USHER_CAM_POINT_INVALID 0 |
Definition at line 171 of file usher_protocol.h.
◆ USHER_CAM_POINT_RESULT
| #define USHER_CAM_POINT_RESULT 18 |
A geographic point one camera deduced from its own session, reported on stop. VALID means the camera produced an estimate, not that the estimate is accurate or that the object was identified. quality is the camera's own confidence and is not comparable between different camera types.
Definition at line 168 of file usher_protocol.h.
◆ USHER_CAM_POINT_RESULT_MSG_SIZE
| #define USHER_CAM_POINT_RESULT_MSG_SIZE (4*9) |
Definition at line 169 of file usher_protocol.h.
◆ USHER_CAM_POINT_UPDATE
| #define USHER_CAM_POINT_UPDATE 19 |
Repeated point from a saved photo (LOOM_cam uses AIcam ID 2). The positive FC photo number correlates the reply; this is NOT a stopped-session answer. Units/status/quality are the same as CAM_POINT_RESULT. A no-match update is INVALID and must never move a waypoint. Old firmware safely ignores ID 19.
Definition at line 193 of file usher_protocol.h.
◆ USHER_CAM_POINT_UPDATE_MSG_SIZE
| #define USHER_CAM_POINT_UPDATE_MSG_SIZE (4*9) |
Definition at line 194 of file usher_protocol.h.
◆ USHER_CAM_POINT_VALID
| #define USHER_CAM_POINT_VALID 1 |
Definition at line 172 of file usher_protocol.h.
◆ USHER_CAMERA_AICAM
| #define USHER_CAMERA_AICAM 2 |
Definition at line 97 of file usher_protocol.h.
◆ USHER_CAMERA_ALL
| #define USHER_CAMERA_ALL 0 |
Definition at line 95 of file usher_protocol.h.
◆ USHER_CAMERA_CHDK
| #define USHER_CAMERA_CHDK 1 |
Definition at line 96 of file usher_protocol.h.
◆ USHER_CAMERA_DIPLACAM
| #define USHER_CAMERA_DIPLACAM 5 |
Definition at line 100 of file usher_protocol.h.
◆ USHER_CAMERA_EARCAM
| #define USHER_CAMERA_EARCAM 4 |
Definition at line 99 of file usher_protocol.h.
◆ USHER_CAMERA_LWIRCAM
| #define USHER_CAMERA_LWIRCAM 3 |
Definition at line 98 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_AICAM
| #define USHER_CAMERA_MASK_AICAM 0x02U |
Definition at line 104 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_ALL
| #define USHER_CAMERA_MASK_ALL 0xFFU |
Definition at line 109 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_CHDK
| #define USHER_CAMERA_MASK_CHDK 0x01U |
Definition at line 103 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_DIPLA
| #define USHER_CAMERA_MASK_DIPLA 0x10U |
Definition at line 107 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_EAR
| #define USHER_CAMERA_MASK_EAR 0x08U |
Definition at line 106 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_LWIR
| #define USHER_CAMERA_MASK_LWIR 0x04U |
Definition at line 105 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_NONE
| #define USHER_CAMERA_MASK_NONE 0x00U |
Definition at line 102 of file usher_protocol.h.
◆ USHER_CAMERA_MASK_SUPPORTED
| #define USHER_CAMERA_MASK_SUPPORTED 0x1FU |
Definition at line 108 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_COVERED
| #define USHER_CAPTURE_ARBITER_COVERED 4U |
Suppressed using trusted same-camera coverage, not a new photo.
Definition at line 334 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_EXPIRED
| #define USHER_CAPTURE_ARBITER_EXPIRED 3U |
Intent or scope no longer current; no exposure is implied.
Definition at line 333 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_FAILED
| #define USHER_CAPTURE_ARBITER_FAILED 2U |
Capture/publication failed; other camera bits can still succeed.
Definition at line 332 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_HELLO
| #define USHER_CAPTURE_ARBITER_HELLO 13 |
Definition at line 323 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE
| #define USHER_CAPTURE_ARBITER_HELLO_MSG_SIZE 8 |
Definition at line 327 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_RESULT
| #define USHER_CAPTURE_ARBITER_RESULT 16 |
Definition at line 326 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_RESULT_MSG_SIZE
| #define USHER_CAPTURE_ARBITER_RESULT_MSG_SIZE 24 |
Definition at line 330 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_SAVED
| #define USHER_CAPTURE_ARBITER_SAVED 1U |
Original and required metadata published; not proof of an object detection.
Definition at line 331 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_SHOOT
| #define USHER_CAPTURE_ARBITER_SHOOT 15 |
Definition at line 325 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE
| #define USHER_CAPTURE_ARBITER_SHOOT_MSG_SIZE (USHER_SHOT_DATA_SIZE + 12) |
Definition at line 329 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_STATE
| #define USHER_CAPTURE_ARBITER_STATE 14 |
Definition at line 324 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_STATE_MSG_SIZE
| #define USHER_CAPTURE_ARBITER_STATE_MSG_SIZE 12 |
Definition at line 328 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_SUPERSEDED
| #define USHER_CAPTURE_ARBITER_SUPERSEDED 5U |
Waiting capacity reused within this camera; not successful recovery.
Definition at line 335 of file usher_protocol.h.
◆ USHER_CAPTURE_ARBITER_VERSION
| #define USHER_CAPTURE_ARBITER_VERSION 1U |
Definition at line 322 of file usher_protocol.h.
◆ USHER_CLOCK_REPLY
| #define USHER_CLOCK_REPLY 10 |
Definition at line 285 of file usher_protocol.h.
◆ USHER_CLOCK_REPLY_MSG_SIZE
| #define USHER_CLOCK_REPLY_MSG_SIZE 16 |
Definition at line 286 of file usher_protocol.h.
◆ USHER_CLOCK_REQUEST
| #define USHER_CLOCK_REQUEST 9 |
Definition at line 283 of file usher_protocol.h.
◆ USHER_CLOCK_REQUEST_MSG_SIZE
| #define USHER_CLOCK_REQUEST_MSG_SIZE 8 |
Definition at line 284 of file usher_protocol.h.
◆ USHER_CONTROL_COMMAND
| #define USHER_CONTROL_COMMAND 22 |
Definition at line 207 of file usher_protocol.h.
◆ USHER_CONTROL_COMMAND_SIZE
| #define USHER_CONTROL_COMMAND_SIZE 12U |
Definition at line 212 of file usher_protocol.h.
◆ USHER_CONTROL_HELLO
| #define USHER_CONTROL_HELLO 21 |
Definition at line 206 of file usher_protocol.h.
◆ USHER_CONTROL_HELLO_SIZE
| #define USHER_CONTROL_HELLO_SIZE 41U |
Definition at line 211 of file usher_protocol.h.
◆ USHER_CONTROL_NEGOTIATE
| #define USHER_CONTROL_NEGOTIATE 20 |
Definition at line 205 of file usher_protocol.h.
◆ USHER_CONTROL_NEGOTIATE_SIZE
| #define USHER_CONTROL_NEGOTIATE_SIZE 9U |
Definition at line 210 of file usher_protocol.h.
◆ USHER_CONTROL_RESULT
| #define USHER_CONTROL_RESULT 23 |
Definition at line 208 of file usher_protocol.h.
◆ USHER_CONTROL_RESULT_SIZE
| #define USHER_CONTROL_RESULT_SIZE 14U |
Definition at line 213 of file usher_protocol.h.
◆ USHER_CONTROL_VERSION
| #define USHER_CONTROL_VERSION 1U |
Definition at line 209 of file usher_protocol.h.
◆ USHER_PAYLOAD
| #define USHER_PAYLOAD 3 |
Definition at line 72 of file usher_protocol.h.
◆ USHER_PAYLOAD_MSG_SIZE
| #define USHER_PAYLOAD_MSG_SIZE 70 |
Definition at line 73 of file usher_protocol.h.
◆ USHER_POSE_CLOCKED
| #define USHER_POSE_CLOCKED 11 |
Definition at line 287 of file usher_protocol.h.
◆ USHER_POSE_CLOCKED_MSG_SIZE
| #define USHER_POSE_CLOCKED_MSG_SIZE (USHER_POSE_SAMPLE_MSG_SIZE + 8) |
Definition at line 288 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE
| #define USHER_POSE_SAMPLE 8 |
Definition at line 237 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_GPS_AGE_MASK
| #define USHER_POSE_SAMPLE_GPS_AGE_MASK UINT32_C(0xffffff00) |
Definition at line 243 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_GPS_AGE_SHIFT
| #define USHER_POSE_SAMPLE_GPS_AGE_SHIFT 8U |
Definition at line 242 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_GPS_AGE_VALID
| #define USHER_POSE_SAMPLE_GPS_AGE_VALID 4U |
Definition at line 241 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_GPS_HELD
| #define USHER_POSE_SAMPLE_GPS_HELD 2U |
Definition at line 240 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_GPS_PRESENT
| #define USHER_POSE_SAMPLE_GPS_PRESENT 1U |
Definition at line 239 of file usher_protocol.h.
◆ USHER_POSE_SAMPLE_MSG_SIZE
| #define USHER_POSE_SAMPLE_MSG_SIZE 100 |
Definition at line 238 of file usher_protocol.h.
◆ USHER_SHOOT_MASK
| #define USHER_SHOOT_MASK 12 |
Definition at line 111 of file usher_protocol.h.
◆ USHER_SHOOT_MASK_MSG_SIZE
| #define USHER_SHOOT_MASK_MSG_SIZE (USHER_SHOT_DATA_SIZE + 8) |
One trigger number for a mask of up to eight cameras. request_id correlates per-camera feedback and is not a photo filename, cryptographic token or GCS ID.
Definition at line 114 of file usher_protocol.h.
◆ USHER_SHOT_DATA_SIZE
| #define USHER_SHOT_DATA_SIZE (4*10) |
Definition at line 49 of file usher_protocol.h.
◆ USHER_SHOT_FAILED
| #define USHER_SHOT_FAILED 2U |
Definition at line 132 of file usher_protocol.h.
◆ USHER_SHOT_RECORDED
| #define USHER_SHOT_RECORDED 4U |
Definition at line 134 of file usher_protocol.h.
◆ USHER_SHOT_RESULT
| #define USHER_SHOT_RESULT 17 |
A terminal observation for one requested camera bit. SAVED means original plus required flight metadata were published, not that SODA found an object. RECORDED is accepted non-image work, not an image saved to disk or a valid point. Missing feedback is UNKNOWN: neither successful capture nor failure is proven.
Definition at line 129 of file usher_protocol.h.
◆ USHER_SHOT_RESULT_MSG_SIZE
| #define USHER_SHOT_RESULT_MSG_SIZE 16 |
Definition at line 130 of file usher_protocol.h.
◆ USHER_SHOT_SAVED
| #define USHER_SHOT_SAVED 1U |
Definition at line 131 of file usher_protocol.h.
◆ USHER_SHOT_SUPERSEDED
| #define USHER_SHOT_SUPERSEDED 3U |
Definition at line 133 of file usher_protocol.h.
◆ USHER_SHOT_UNSUPPORTED
| #define USHER_SHOT_UNSUPPORTED 5U |
Definition at line 135 of file usher_protocol.h.
◆ USHER_START_TARGETED
| #define USHER_START_TARGETED 7 |
Definition at line 153 of file usher_protocol.h.
◆ USHER_START_TARGETED_MSG_SIZE
| #define USHER_START_TARGETED_MSG_SIZE 8 |
Definition at line 154 of file usher_protocol.h.
◆ USHER_STATUS
| #define USHER_STATUS 4 |
Definition at line 78 of file usher_protocol.h.
◆ USHER_STATUS_MSG_SIZE
| #define USHER_STATUS_MSG_SIZE (4*2) |
Definition at line 79 of file usher_protocol.h.
◆ USHER_STOP_TARGETED
| #define USHER_STOP_TARGETED 6 |
Session control for one camera. A camera that accumulates evidence over time (acoustic listening, recording, mapping) samples between start and stop; a camera without a session ignores both. A nonzero session_id is allocated by the FC and echoed in the point result; start and stop use the same token.
Definition at line 151 of file usher_protocol.h.
◆ USHER_STOP_TARGETED_MSG_SIZE
| #define USHER_STOP_TARGETED_MSG_SIZE 8 |
Definition at line 152 of file usher_protocol.h.
◆ UsherHeader
| #define UsherHeader | ( | msg_id, | |
| payload_len ) |
Definition at line 388 of file usher_protocol.h.
◆ UsherPut1ByteByAddr
| #define UsherPut1ByteByAddr | ( | _byte | ) |
Definition at line 401 of file usher_protocol.h.
◆ UsherPutUint8
| #define UsherPutUint8 | ( | _byte | ) |
Definition at line 382 of file usher_protocol.h.
◆ UsherSizeOf
| #define UsherSizeOf | ( | _payload | ) |
Definition at line 380 of file usher_protocol.h.
◆ UsherTrailer
| #define UsherTrailer | ( | ) |
Definition at line 396 of file usher_protocol.h.
Function Documentation
◆ parse_usher()
| void parse_usher | ( | struct usher_transport * | t, |
| uint8_t | c ) |
Consume one byte from a USHER UART stream.
- Parameters
-
t Persistent parser state for that stream. c Newly received byte.
Frames may be arbitrarily split across calls. On a valid complete frame this sets t->msg_received and leaves the decoded bytes in t->payload. The caller must dispatch the message and clear that flag before supplying bytes for the next frame.
- Warning
- This function is not thread-safe. Serialize access to each
tinstance and do not alter its fields while a frame is in progress.
Consume one byte from a USHER UART stream.
Checksums cover the length, message ID, and payload bytes. A complete, valid frame sets t->msg_received; the caller must clear that flag after dispatching. Any framing or checksum error increments t->error and resets the state machine, avoiding a poisoned partial frame affecting later traffic.
- Warning
tmust remain valid and unchanged by another thread for the duration of a frame; this parser intentionally contains no synchronization.
Definition at line 54 of file usher_protocol.c.
◆ usher_pose_flags_valid()
|
inlinestatic |
Check the structural consistency of pose-sample GPS flags.
- Parameters
-
flags Received wire flags including the encoded age field.
- Returns
- True if all bits are known and the GPS presence and age dependencies hold.
Held GPS requires a present fix and valid age. Reject stray age bits rather than treating them as qualified timing evidence.
Definition at line 250 of file usher_protocol.h.
Variable Documentation
◆ usher_ck_a
|
extern |
Definition at line 31 of file usher_protocol.c.
◆ usher_ck_b
| uint8_t usher_ck_b |
Definition at line 376 of file usher_protocol.h.
◆ usher_protocol
|
extern |
Definition at line 42 of file usher_protocol.c.