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
camera_control.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 camera_control.h
20 * @brief Fixed-size camera-control wire codec and FC-side ticket state.
21 * @details Control tickets are distinct from photo numbers and shot requests.
22 * Eight per-camera slots keep the flight-controller footprint bounded; a ticket
23 * is consumed only after its complete UART frame is admitted. Commands are not
24 * replayed after timeout because the camera may already have acted.
25 */
26#ifndef USHER_CAMERA_CONTROL_H
27#define USHER_CAMERA_CONTROL_H
28
29#include <stddef.h>
30#include "usher_protocol.h"
31
32#define USHER_CONTROL_TIMEOUT_US UINT32_C(70000000)
33#define USHER_CONTROL_LEASE_US UINT32_C(6000000)
34
35/** @brief One addressed command request shared with the companion protocol. */
37 /** @brief Nonzero negotiated companion session and request ticket. */
39 /** @brief Camera selection mask, command identifier, and command value. */
41};
42
43/** @brief Result evidence for one camera selected by a request mask. */
45 /** @brief Correlated request identity; never substitute a shot number here. */
47 /** @brief One-based camera ID, terminal status, observed value, and evidence. */
49};
50
51/** @brief Fixed pending/result slot retained for one addressable camera. */
53 /** @brief Request ticket and monotonic send timestamp in microseconds. */
55 /** @brief Original command plus returned observation/status/evidence. */
57};
58
59/**
60 * @brief Handshake, capability cache, and eight-camera ticket state.
61 * @details Contains no heap-owned data or background jobs. Keep the compile-time
62 * size limit: this object resides in flight-controller memory.
63 */
72
73#ifdef __cplusplus
74static_assert(sizeof(struct usher_control_client) <= 256, "FC control state exceeds 256 bytes");
75extern "C" {
76#else
77_Static_assert(sizeof(struct usher_control_client) <= 256, "FC control state exceeds 256 bytes");
78#endif
79
80/** @brief Encode a 32-bit value as four little-endian protocol bytes.
81 * @param[out] bytes Destination payload buffer.
82 * @param[in] size Total buffer size.
83 * @param[in] offset Byte offset for the field.
84 * @param[in] value Value to encode.
85 * @return True if the field fits and the buffer is non-null.
86 */
87bool usher_control_put_u32(uint8_t *bytes, size_t size, size_t offset, uint32_t value);
88/** @brief Decode a bounded four-byte little-endian protocol value.
89 * @param[in] bytes Source payload buffer.
90 * @param[in] size Total buffer size.
91 * @param[in] offset Byte offset for the field.
92 * @param[out] value Receives the decoded value.
93 * @return True if the field fits and both pointers are valid.
94 */
95bool usher_control_get_u32(const uint8_t *bytes, size_t size, size_t offset, uint32_t *value);
96/** @brief Encode one command payload with the fixed wire size and field order.
97 * @param[out] bytes Destination payload buffer.
98 * @param[in] size Payload size; must equal USHER_CONTROL_COMMAND_SIZE.
99 * @param[in] request Session, ticket, camera mask, command, and value.
100 * @return True only for valid required fields and exact payload size.
101 */
102bool usher_control_encode_request(uint8_t *bytes, size_t size, const struct usher_control_request *request);
103/** @brief Validate and decode one fixed-size command payload.
104 * @param[in] bytes Received payload.
105 * @param[in] size Payload size; must equal USHER_CONTROL_COMMAND_SIZE.
106 * @param[out] request Receives decoded fields on success.
107 * @return True only when version, mask, command, session, and ticket are valid.
108 */
109bool usher_control_decode_request(const uint8_t *bytes, size_t size, struct usher_control_request *request);
110/** @brief Encode one camera's correlated control result.
111 * @param[out] bytes Destination payload buffer.
112 * @param[in] size Payload size; must equal USHER_CONTROL_RESULT_SIZE.
113 * @param[in] result Result status and evidence for one camera.
114 * @return True only when camera, request, status, and evidence fields are valid.
115 */
116bool usher_control_encode_result(uint8_t *bytes, size_t size, const struct usher_control_result *result);
117/** @brief Validate and decode one camera result payload.
118 * @param[in] bytes Received payload.
119 * @param[in] size Payload size; must equal USHER_CONTROL_RESULT_SIZE.
120 * @param[out] result Receives decoded fields on success.
121 * @return True only when version, identity, status, and evidence are valid.
122 */
123bool usher_control_decode_result(const uint8_t *bytes, size_t size, struct usher_control_result *result);
124/** @brief Validate the command-specific legal value range.
125 * @param[in] command Control command ID.
126 * @param[in] value Command value.
127 * @return True for a supported value, false before any ticket is reserved otherwise.
128 */
129bool usher_control_value_valid(uint8_t command, uint8_t value);
130/** @brief Reset session state and invalidate outstanding tickets without replay.
131 * @param[in,out] client Client state to reset.
132 * @param[in] nonce New handshake nonce; zero is normalized to one.
133 */
134void usher_control_client_reset(struct usher_control_client *client, uint32_t nonce);
135/** @brief Accept only a HELLO matching the current nonce-bound negotiation.
136 * @param[in,out] client Handshake and capability state.
137 * @param[in] bytes HELLO payload.
138 * @param[in] size Payload size; must equal USHER_CONTROL_HELLO_SIZE.
139 * @param[in] now_us Current monotonic time in microseconds.
140 * @return True if the reply is structurally valid and belongs to this negotiation.
141 */
142bool usher_control_client_hello(struct usher_control_client *client, const uint8_t *bytes, size_t size, uint32_t now_us);
143/** @brief Check confirmed-session readiness and the bounded HELLO lease.
144 * @param[in] client Client state.
145 * @param[in] now_us Current monotonic time in microseconds.
146 * @return True only while the negotiated session is fresh and confirmed.
147 */
148bool usher_control_client_ready(const struct usher_control_client *client, uint32_t now_us);
149/** @brief Mark expired pending commands UNKNOWN; never resubmit them.
150 * @param[in,out] client Client state to update.
151 * @param[in] now_us Current monotonic time in microseconds.
152 */
153void usher_control_client_expire(struct usher_control_client *client, uint32_t now_us);
154/** @brief Prepare a request without consuming its ticket before UART admission.
155 * @param[in,out] client Session state and pending slots.
156 * @param[in] mask Eight-bit camera selection mask.
157 * @param[in] command Command identifier.
158 * @param[in] value Command-specific value.
159 * @param[in] now_us Current monotonic time in microseconds.
160 * @param[out] request Receives the tentative request on success.
161 * @return True only if the session is ready, values are legal, and selected slots are free.
162 * @note Call @ref usher_control_client_commit only after the complete frame is admitted.
163 */
164bool usher_control_client_prepare(struct usher_control_client *client, uint8_t mask, uint8_t command,
165 uint8_t value, uint32_t now_us, struct usher_control_request *request);
166/** @brief Commit a prepared request after full-frame UART admission.
167 * @param[in,out] client Client state whose ticket and selected slots are updated.
168 * @param[in] request Request previously returned by @ref usher_control_client_prepare.
169 * @param[in] now_us Monotonic send time in microseconds.
170 */
172 uint32_t now_us);
173/** @brief Accept a result only when session, ticket, camera, and evidence correlate.
174 * @param[in,out] client Client state containing pending requests.
175 * @param[in] bytes Received result payload.
176 * @param[in] size Payload length.
177 * @param[in] now_us Current monotonic time in microseconds.
178 * @return True when the result belongs to a pending request and its evidence is valid.
179 */
180bool usher_control_client_receive(struct usher_control_client *client, const uint8_t *bytes, size_t size,
181 uint32_t now_us);
182/** @brief Aggregate per-camera results for one group ticket.
183 * @param[in] client Client result slots.
184 * @param[in] ticket Request ID; zero means NOT_SENT.
185 * @return UNKNOWN if evidence is missing, PENDING if any selected camera is pending,
186 * PARTIAL for mixed terminal outcomes, or the common terminal status.
187 */
188uint8_t usher_control_client_result(const struct usher_control_client *client, uint32_t ticket);
189/** @brief Read one camera's status for a group request.
190 * @param[in] client Client result slots.
191 * @param[in] ticket Request ID; zero means NOT_SENT.
192 * @param[in] camera_id One-based camera slot from 1 through 8.
193 * @return Matching result status, UNKNOWN for absent/replaced tickets, or NOT_SENT.
194 */
195uint8_t usher_control_client_camera_result(const struct usher_control_client *client, uint32_t ticket, uint8_t camera_id);
196
197#ifdef __cplusplus
198}
199#endif
200
201#endif
bool usher_control_client_hello(struct usher_control_client *client, const uint8_t *bytes, size_t size, uint32_t now_us)
Accept only a HELLO matching the current nonce-bound negotiation.
bool usher_control_encode_request(uint8_t *bytes, size_t size, const struct usher_control_request *request)
Encode one command payload with the fixed wire size and field order.
uint8_t usher_control_client_result(const struct usher_control_client *client, uint32_t ticket)
Aggregate per-camera results for one group ticket.
bool usher_control_client_ready(const struct usher_control_client *client, uint32_t now_us)
Check confirmed-session readiness and the bounded HELLO lease.
bool usher_control_encode_result(uint8_t *bytes, size_t size, const struct usher_control_result *result)
Encode one camera's correlated control result.
bool usher_control_decode_result(const uint8_t *bytes, size_t size, struct usher_control_result *result)
Validate and decode one camera result payload.
void usher_control_client_reset(struct usher_control_client *client, uint32_t nonce)
Reset session state and invalidate outstanding tickets without replay.
uint8_t usher_control_client_camera_result(const struct usher_control_client *client, uint32_t ticket, uint8_t camera_id)
Read one camera's status for a group request.
void usher_control_client_expire(struct usher_control_client *client, uint32_t now_us)
Mark expired pending commands UNKNOWN; never resubmit them.
bool usher_control_put_u32(uint8_t *bytes, size_t size, size_t offset, uint32_t value)
Encode a 32-bit value as four little-endian protocol bytes.
bool usher_control_get_u32(const uint8_t *bytes, size_t size, size_t offset, uint32_t *value)
Decode a bounded four-byte little-endian protocol value.
bool usher_control_value_valid(uint8_t command, uint8_t value)
Validate the command-specific legal value range.
void usher_control_client_commit(struct usher_control_client *client, const struct usher_control_request *request, uint32_t now_us)
Commit a prepared request after full-frame UART admission.
bool usher_control_client_prepare(struct usher_control_client *client, uint8_t mask, uint8_t command, uint8_t value, uint32_t now_us, struct usher_control_request *request)
Prepare a request without consuming its ticket before UART admission.
bool usher_control_client_receive(struct usher_control_client *client, const uint8_t *bytes, size_t size, uint32_t now_us)
Accept a result only when session, ticket, camera, and evidence correlate.
bool usher_control_decode_request(const uint8_t *bytes, size_t size, struct usher_control_request *request)
Validate and decode one fixed-size command payload.
size_t size
Definition chdk_pipe.c:143
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
union dc_shot_union request
Handshake, capability cache, and eight-camera ticket state.
struct usher_control_slot slots[8]
One addressed command request shared with the companion protocol.
uint32_t session
Nonzero negotiated companion session and request ticket.
uint8_t camera_mask
Camera selection mask, command identifier, and command value.
Result evidence for one camera selected by a request mask.
uint8_t camera_id
One-based camera ID, terminal status, observed value, and evidence.
struct usher_control_request request
Correlated request identity; never substitute a shot number here.
Fixed pending/result slot retained for one addressable camera.
uint8_t camera_mask
Original command plus returned observation/status/evidence.
uint32_t request_id
Request ticket and monotonic send timestamp in microseconds.
struct usher_control_result result
Definition usher.c:377
Shared FC/MORA byte-stream UART framing, messages and payload layouts.