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.c
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.c
20 * @brief Serialize camera-control payloads and track bounded FC-side tickets.
21 * @details The request counter advances only after the caller confirms that the
22 * entire UART frame was admitted. This avoids phantom pending controls when a
23 * frame is rejected locally and prevents unsafe replay after ambiguous delivery.
24 */
25#include "camera_control.h"
26
27bool usher_control_put_u32(uint8_t *bytes, size_t size, size_t offset, uint32_t value)
28{
29 if (!bytes || offset > size || size - offset < 4) return false;
30 for (size_t index = 0; index < 4; ++index) bytes[offset + index] = (uint8_t)(value >> (8 * index));
31 return true;
32}
33
34bool usher_control_get_u32(const uint8_t *bytes, size_t size, size_t offset, uint32_t *value)
35{
36 if (!bytes || !value || offset > size || size - offset < 4) return false;
37 *value = 0;
38 for (size_t index = 0; index < 4; ++index) *value |= (uint32_t)bytes[offset + index] << (8 * index);
39 return true;
40}
41
42bool usher_control_value_valid(uint8_t command, uint8_t value)
43{
44 return command == CAM_CMD_ZOOM_ABSOLUTE || (command == CAM_CMD_LENS_RETRACT && value == 0)
45 || (command == CAM_CMD_KEEP_AWAKE && value <= 1);
46}
47
49{
50 if (!bytes || !request || size != USHER_CONTROL_COMMAND_SIZE || !request->camera_mask
51 || !request->session || !request->request_id || !request->command) return false;
53 bytes[1] = request->camera_mask;
55 usher_control_put_u32(bytes, size, 6, request->request_id);
56 bytes[10] = request->command;
57 bytes[11] = request->value;
58 return true;
59}
60
62{
64 || !bytes[1] || !bytes[10]) return false;
65 *request = (struct usher_control_request){.camera_mask = bytes[1], .command = bytes[10], .value = bytes[11]};
67 usher_control_get_u32(bytes, size, 6, &request->request_id);
68 return request->session && request->request_id;
69}
70
72{
73 if (!bytes || !result || size != USHER_CONTROL_RESULT_SIZE || result->camera_id < 1 || result->camera_id > 8
74 || !result->request.session || !result->request.request_id || !result->request.command
76 || result->evidence > CAM_CONTROL_EVIDENCE_PLAYBACK) return false;
78 bytes[1] = result->camera_id;
79 usher_control_put_u32(bytes, size, 2, result->request.session);
80 usher_control_put_u32(bytes, size, 6, result->request.request_id);
81 bytes[10] = result->request.command;
82 bytes[11] = result->observed;
83 bytes[12] = result->status;
84 bytes[13] = result->evidence;
85 return true;
86}
87
89{
91 || bytes[1] < 1 || bytes[1] > 8 || !bytes[10]
93 || bytes[13] > CAM_CONTROL_EVIDENCE_PLAYBACK) return false;
94 *result = (struct usher_control_result){.camera_id = bytes[1], .status = bytes[12],
95 .observed = bytes[11], .evidence = bytes[13], .request = {.command = bytes[10]}};
96 usher_control_get_u32(bytes, size, 2, &result->request.session);
97 usher_control_get_u32(bytes, size, 6, &result->request.request_id);
98 return result->request.session && result->request.request_id;
99}
100
101void usher_control_client_reset(struct usher_control_client *client, uint32_t nonce)
102{
103 client->session = 0;
104 client->negotiating_session = 0;
105 client->confirmed = false;
106 client->negotiating = false;
107 client->nonce = nonce ? nonce : 1;
108 /* Preserve the request counter but make prior-session results explicitly unknown. */
109 for (size_t index = 0; index < 8; ++index) {
110 client->capabilities[index] = 0;
111 if (client->slots[index].request_id) client->slots[index].status = CAM_CONTROL_UNKNOWN;
112 }
113}
114
115bool usher_control_client_hello(struct usher_control_client *client, const uint8_t *bytes, size_t size, uint32_t now_us)
116{
117 uint32_t nonce, session;
119 || !usher_control_get_u32(bytes, size, 1, &nonce) || nonce != client->nonce
120 || !usher_control_get_u32(bytes, size, 5, &session) || !session) return false;
121 if (client->session != session) {
122 for (size_t index = 0; index < 8; ++index)
123 if (client->slots[index].request_id) client->slots[index].status = CAM_CONTROL_UNKNOWN;
124 }
125 for (size_t index = 0; index < 8; ++index)
126 usher_control_get_u32(bytes, size, 9 + 4 * index, &client->capabilities[index]);
127 client->confirmed = client->session == session && client->negotiating_session == session;
128 client->session = session;
129 client->hello_us = now_us;
130 return true;
131}
132
133bool usher_control_client_ready(const struct usher_control_client *client, uint32_t now_us)
134{
135 return client->session && client->confirmed && (uint32_t)(now_us - client->hello_us) < USHER_CONTROL_LEASE_US;
136}
137
138void usher_control_client_expire(struct usher_control_client *client, uint32_t now_us)
139{
140 for (size_t index = 0; index < 8; ++index) {
141 struct usher_control_slot *slot = &client->slots[index];
142 if (slot->status == CAM_CONTROL_PENDING && (uint32_t)(now_us - slot->sent_us) >= USHER_CONTROL_TIMEOUT_US)
144 }
145}
146
147bool usher_control_client_prepare(struct usher_control_client *client, uint8_t mask, uint8_t command,
148 uint8_t value, uint32_t now_us, struct usher_control_request *request)
149{
150 usher_control_client_expire(client, now_us);
152 || !usher_control_client_ready(client, now_us) || client->next_request_id == UINT32_MAX) return false;
153 for (size_t index = 0; index < 8; ++index)
154 if ((mask & (1U << index)) && client->slots[index].status == CAM_CONTROL_PENDING) return false;
155 *request = (struct usher_control_request){.session = client->session, .request_id = client->next_request_id + 1,
156 .camera_mask = mask, .command = command, .value = value};
157 return true;
158}
159
161 uint32_t now_us)
162{
163 /* This is called after full-frame admission; prepare alone must not consume an ID. */
164 client->next_request_id = request->request_id;
165 for (size_t index = 0; index < 8; ++index) {
166 if (!(request->camera_mask & (1U << index))) continue;
167 client->slots[index] = (struct usher_control_slot){.request_id = request->request_id, .sent_us = now_us,
168 .camera_mask = request->camera_mask, .command = request->command, .value = request->value,
169 .status = CAM_CONTROL_PENDING};
170 }
171}
172
173bool usher_control_client_receive(struct usher_control_client *client, const uint8_t *bytes, size_t size,
174 uint32_t now_us)
175{
177 usher_control_client_expire(client, now_us);
179 || result.request.session != client->session) return false;
180 struct usher_control_slot *slot = &client->slots[result.camera_id - 1];
181 if (slot->status != CAM_CONTROL_PENDING || slot->request_id != result.request.request_id
182 || slot->command != result.request.command) return false;
183 if (result.status == CAM_CONTROL_APPLIED
185 || (slot->command != CAM_CMD_LENS_RETRACT && result.evidence != CAM_CONTROL_EVIDENCE_VALUE))) return false;
186 if (result.status != CAM_CONTROL_APPLIED && result.evidence != CAM_CONTROL_EVIDENCE_NONE) return false;
187 if (result.status == CAM_CONTROL_APPLIED
188 && ((slot->command == CAM_CMD_LENS_RETRACT && result.observed)
189 || (slot->command == CAM_CMD_KEEP_AWAKE && result.observed > 1))) return false;
190 slot->status = result.status;
191 slot->observed = result.observed;
192 slot->evidence = result.evidence;
193 return true;
194}
195
196uint8_t usher_control_client_camera_result(const struct usher_control_client *client, uint32_t ticket, uint8_t camera_id)
197{
198 if (!ticket) return CAM_CONTROL_NOT_SENT;
199 if (camera_id < 1 || camera_id > 8 || client->slots[camera_id - 1].request_id != ticket) return CAM_CONTROL_UNKNOWN;
200 return client->slots[camera_id - 1].status;
201}
202
203uint8_t usher_control_client_result(const struct usher_control_client *client, uint32_t ticket)
204{
205 if (!ticket) return CAM_CONTROL_NOT_SENT;
206 uint8_t mask = 0, status = 0;
207 bool mixed = false, pending = false;
208 for (size_t index = 0; index < 8; ++index)
209 if (client->slots[index].request_id == ticket) { mask = client->slots[index].camera_mask; break; }
210 if (!mask) return CAM_CONTROL_UNKNOWN;
211 /* Unknown evidence dominates; different terminal outcomes remain PARTIAL. */
212 for (size_t index = 0; index < 8; ++index) {
213 if (!(mask & (1U << index))) continue;
214 const uint8_t current = usher_control_client_camera_result(client, ticket, (uint8_t)(index + 1));
215 if (current == CAM_CONTROL_UNKNOWN) return current;
216 if (current == CAM_CONTROL_PENDING) { pending = true; continue; }
217 if (status && status != current) mixed = true;
218 status = current;
219 }
221}
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.
Fixed-size camera-control wire codec and FC-side ticket state.
#define USHER_CONTROL_TIMEOUT_US
#define USHER_CONTROL_LEASE_US
static uint32_t session
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
static bool pending
Handshake, capability cache, and eight-camera ticket state.
struct usher_control_slot slots[8]
One addressed command request shared with the companion protocol.
Result evidence for one camera selected by a request mask.
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
#define CAM_CONTROL_PARTIAL
#define USHER_CONTROL_HELLO_SIZE
#define CAM_CONTROL_EVIDENCE_VALUE
#define CAM_CMD_ZOOM_ABSOLUTE
#define USHER_CONTROL_VERSION
#define CAM_CONTROL_EVIDENCE_PLAYBACK
#define CAM_CONTROL_NOT_SENT
#define CAM_CMD_LENS_RETRACT
#define CAM_CONTROL_EVIDENCE_NONE
#define CAM_CONTROL_UNKNOWN
#define CAM_CMD_KEEP_AWAKE
#define CAM_CONTROL_PENDING
#define USHER_CONTROL_COMMAND_SIZE
#define CAM_CONTROL_APPLIED
#define USHER_CONTROL_RESULT_SIZE