JaiaBot 3.0.0
JaiaBot micro-AUV software
Loading...
Searching...
No Matches
fleet_config.proto
Go to the documentation of this file.
1// Copyright 2025:
2// JaiaRobotics LLC
3// File authors:
4// Toby Schneider <toby@gobysoft.org>
5//
6//
7// This file is part of the JaiaBot Project Libraries
8// ("The Jaia Libraries").
9//
10// The Jaia Libraries are free software: you can redistribute them and/or modify
11// them under the terms of the GNU Lesser General Public License as published by
12// the Free Software Foundation, either version 2.1 of the License, or
13// (at your option) any later version.
14//
15// The Jaia Libraries are distributed in the hope that they will be useful,
16// but WITHOUT ANY WARRANTY; without even the implied warranty of
17// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18// GNU Lesser General Public License for more details.
19//
20// You should have received a copy of the GNU Lesser General Public License
21// along with the Jaia Libraries. If not, see <http://www.gnu.org/licenses/>.
22
23syntax = "proto2";
24import "jaiabot/messages/option_extensions.proto";
25
26package jaiabot.protobuf;
27
28// Fleet config contract version: see "Fleet configuration versioning" in
29// page091_major_upgrade.md. Bump it together with a migration in
30// jaia-fleet-config.py when the build-time contract check reports a breaking
31// change. Fields and enum values are never removed or renamed, only marked
32// [deprecated = true], so that every earlier version still parses.
33option (jaia.file).fleet_config_version = 2;
34
35// The bot/hub settings that debconf asks for on first boot and on
36// "dpkg-reconfigure jaiabot-embedded". debian/jaiabot-embedded.templates and
37// .config are generated from this message: fields are asked in declaration
38// order, grouped by (jaia.field).debconf.group, and enum values map to debconf
39// values by dropping the enum name prefix and lowercasing (BOT_TYPE_PAM -> pam).
40message NodeSettings
41{
42 option (jaia.msg).debconf = {
43 package: "jaiabot-embedded"
44 node_type_field: "type"
45 };
46
47 enum NodeType
48 {
49 NODE_TYPE_BOT = 0;
50 NODE_TYPE_HUB = 1;
51 }
52 optional NodeType type = 1 [(jaia.field).debconf = {
53 group: ALL
54 identity: true
55 description: "Is this a bot or a hub?"
56 extended_description: "This choice will determine which applications will be configured to launch with systemd."
57 }];
58
59 optional int32 fleet_id = 2 [default = 0, (jaia.field).debconf = {
60 group: ALL
61 identity: true
62 bounded_id: true
63 description: "Fleet identification number"
64 extended_description: "This is used to set the correct value in the jaiabot configuration.\nValid fleet ids are 0 to 4000, as reported by \"jaia admin bounds --fleet_id\";\nthose above 250 are addressed with IPv6 rather than IPv4.\nTo change in the future, run \"sudo dpkg-reconfigure jaiabot-embedded\""
65 }];
66
67 enum LedType
68 {
69 LED_TYPE_HUB_LED = 0;
70 LED_TYPE_NONE = 1;
71 }
72 optional LedType led_type = 3 [
73 default = LED_TYPE_NONE,
74 (jaia.field).debconf = {
75 group: ALL
76 description: "What type of leds does your system have?"
77 }
78 ];
79
80 optional int32 electronics_stack = 4 [
81 default = 0,
82 (jaia.field).debconf = {
83 group: ALL
84 choices: [ "0", "1", "2" ]
85 description: "What type of electronics stack do you have?"
86 }
87 ];
88
89 optional string rf_encryption_password = 5 [
90 default = "",
91 (jaia.field).debconf = {
92 group: ALL
93 description: "Encryption key for XBee radio: 128-bit value (up to 16 bytes) as hex"
94 }
95 ];
96
97 optional string dccl_encryption_password = 6 [
98 default = "",
99 (jaia.field).debconf = {
100 group: ALL
101 description: "Encryption passphrase for DCCL (intervehicle) messages: can be any string."
102 }
103 ];
104
105 enum CommsLink
106 {
107 COMMS_LINK_XBEE = 0;
108 COMMS_LINK_WIFI = 1;
109 COMMS_LINK_IRIDIUM = 2;
110 }
111 repeated CommsLink comms_links = 7 [(jaia.field).debconf = {
112 group: ALL
113 default: "xbee"
114 description: "Which comms links to activate?"
115 }];
116
117 enum Mode
118 {
119 MODE_RUNTIME = 0;
120 MODE_SIMULATION = 1;
121 }
122 optional Mode mode = 8 [
123 default = MODE_RUNTIME,
124 (jaia.field).debconf = {
125 group: ALL
126 identity: true
127 description: "Is this bot or hub to be run in runtime (operational) or simulation mode?"
128 extended_description: "This choice will determine which applications will be configured to launch with systemd."
129 }
130 ];
131
132 optional int32 warp = 9 [
133 default = 1,
134 (jaia.field).debconf = {
135 group: ALL
136 choices: [ "1", "2", "5", "10", "20", "30", "40", "50" ]
137 ask_if { field: "mode" equals: "simulation" }
138 description: "At what multiple of real speed should this simulation be run?"
139 extended_description: "A value of 1 is normal speed, 10 is 10x the real clock, etc."
140 }
141 ];
142
143 optional int32 bot_id = 10 [default = 0, (jaia.field).debconf = {
144 group: BOT
145 identity: true
146 bounded_id: true
147 description: "Bot identification number"
148 extended_description: "This is used to set the hostname of the computer and set the correct value in the jaiabot configuration.\nValid bot_ids are 0 to 150, as reported by \"jaia admin bounds --bot_id\".\nTo change in the future, run \"sudo dpkg-reconfigure jaiabot-embedded\""
149 }];
150
151 optional string bot_vin = 24 [
152 default = "",
153 (jaia.field).debconf = {
154 group: BOT
155 per_node: true
156 description: "Bot Vehicle Identification Number (VIN)"
157 extended_description: "Unique identifier for this physical bot.\nTo change in the future, run \"sudo dpkg-reconfigure jaiabot-embedded\""
158 }
159 ];
160
161 enum ArduinoType
162 {
163 ARDUINO_TYPE_SPI = 0;
164 ARDUINO_TYPE_USB = 1;
165 ARDUINO_TYPE_NONE = 2;
166 ARDUINO_TYPE_USB_OLD = 3 [deprecated = true, (jaia.ev).debconf.replaced_by = "usb"];
167 ARDUINO_TYPE_USB_NEW = 4 [deprecated = true, (jaia.ev).debconf.replaced_by = "usb"];
168 }
169 optional ArduinoType arduino_type = 11 [
170 default = ARDUINO_TYPE_NONE,
171 (jaia.field).debconf = {
172 group: BOT
173 description: "What type of Arduino connection does this bot have?"
174 }
175 ];
176
177 optional string tail_serial_number = 25 [
178 default = "",
179 (jaia.field).debconf = {
180 group: BOT
181 per_node: true
182 description: "What is the serial number of this bot's tail unit?"
183 }
184 ];
185
186 enum BotType
187 {
188 BOT_TYPE_HYDRO = 0;
189 BOT_TYPE_PAM = 1;
190 BOT_TYPE_BIO = 2;
191 BOT_TYPE_STORM = 5;
192 BOT_TYPE_NONE = 3;
193 BOT_TYPE_ECHO = 4 [deprecated = true, (jaia.ev).debconf.replaced_by = "pam"];
194 }
195 optional BotType bot_type = 12 [
196 default = BOT_TYPE_HYDRO,
197 (jaia.field).debconf = {
198 group: BOT
199 unasked_value: "none"
200 description: "What type of bot is your system?"
201 }
202 ];
203
204 enum PamConnectionType
205 {
206 PAM_CONNECTION_TYPE_UART = 0;
207 PAM_CONNECTION_TYPE_USB = 1;
208 PAM_CONNECTION_TYPE_NONE = 2;
209 }
210 optional PamConnectionType pam_connection_type = 13 [
211 default = PAM_CONNECTION_TYPE_NONE,
212 (jaia.field).debconf = {
213 group: BOT
214 ask_if { field: "bot_type" equals: "pam" }
215 unasked_value: "none"
216 description: "What type of PAM connection does this bot have?"
217 }
218 ];
219
220 enum ImuType
221 {
222 // No replaced_by: the hardware has to be swapped, so a fleet still on one
223 // is refused rather than migrated (see check-imu-type.yml)
224 IMU_TYPE_BNO055 = 0 [deprecated = true];
225 IMU_TYPE_BNO085 = 1;
226 IMU_TYPE_NONE = 2;
227 }
228 optional ImuType imu_type = 14 [
229 default = IMU_TYPE_BNO085,
230 (jaia.field).debconf = {
231 group: BOT
232 description: "What type of imu does your system have?"
233 }
234 ];
235
236 enum DataOffloadIgnoreType
237 {
238 DATA_OFFLOAD_IGNORE_TYPE_GOBY = 0;
239 DATA_OFFLOAD_IGNORE_TYPE_TASKPACKET = 1;
240 DATA_OFFLOAD_IGNORE_TYPE_NONE = 2;
241 }
242 optional DataOffloadIgnoreType data_offload_ignore_type = 15 [
243 default = DATA_OFFLOAD_IGNORE_TYPE_NONE,
244 (jaia.field).debconf = {
245 group: BOT
246 description: "What data types to ignore when sending data to the hub?"
247 }
248 ];
249
250 enum ImuInstallType
251 {
252 IMU_INSTALL_TYPE_EMBEDDED = 0;
253 IMU_INSTALL_TYPE_RETROFIT = 1;
254 IMU_INSTALL_TYPE_NONE = 2;
255 }
256 optional ImuInstallType imu_install_type = 16 [
257 default = IMU_INSTALL_TYPE_EMBEDDED,
258 (jaia.field).debconf = {
259 group: BOT
260 description: "What type of imu installation does your system have?"
261 }
262 ];
263
264 enum TemperatureSensorType
265 {
266 TEMPERATURE_SENSOR_TYPE_BAR02 = 0;
267 TEMPERATURE_SENSOR_TYPE_BAR30 = 1;
268 TEMPERATURE_SENSOR_TYPE_TSYS01 = 2;
269 TEMPERATURE_SENSOR_TYPE_NONE = 3;
270 }
271 optional TemperatureSensorType temperature_sensor_type = 17 [
272 default = TEMPERATURE_SENSOR_TYPE_BAR30,
273 (jaia.field).debconf = {
274 group: BOT
275 description: "What temperature sensor do you want to use?"
276 }
277 ];
278
279 enum PressureSensorType
280 {
281 PRESSURE_SENSOR_TYPE_BAR02 = 0;
282 PRESSURE_SENSOR_TYPE_BAR30 = 1;
283 PRESSURE_SENSOR_TYPE_NONE = 2;
284 }
285 optional PressureSensorType pressure_sensor_type = 18 [
286 default = PRESSURE_SENSOR_TYPE_BAR30,
287 (jaia.field).debconf = {
288 group: BOT
289 description: "What pressure sensor do you have?"
290 }
291 ];
292
293 enum MotorHarnessType
294 {
295 MOTOR_HARNESS_TYPE_RPM_AND_THERMISTOR = 0;
296 MOTOR_HARNESS_TYPE_NONE = 1;
297 }
298 optional MotorHarnessType motor_harness_type = 19 [
299 default = MOTOR_HARNESS_TYPE_NONE,
300 (jaia.field).debconf = {
301 group: BOT
302 description: "What type of motor harness does your bot have?"
303 }
304 ];
305
306 enum CameraPosition
307 {
308 CAMERA_POSITION_AFT = 0;
309 CAMERA_POSITION_FORE = 1;
310 CAMERA_POSITION_OUTWARD = 2;
311 CAMERA_POSITION_NONE = 3;
312 }
313 repeated CameraPosition camera_positions = 20 [(jaia.field).debconf = {
314 group: BOT
315 default: "none"
316 description: "Which camera positions?"
317 }];
318
319 enum AdditionalSensor
320 {
321 ADDITIONAL_SENSOR_TURNER_C_FLOUR = 0 [deprecated = true, (jaia.ev).debconf.replaced_by = "turner_c_fluor"];
322 ADDITIONAL_SENSOR_TURNER_C_FLUOR = 4;
323 ADDITIONAL_SENSOR_TURNER_C_FLUOR_2 = 5;
324 ADDITIONAL_SENSOR_AML = 1;
325 ADDITIONAL_SENSOR_PPK = 2;
326 ADDITIONAL_SENSOR_NONE = 3;
327 }
328 repeated AdditionalSensor additional_sensors = 21 [(jaia.field).debconf = {
329 group: BOT
330 default: "none"
331 description: "Which additional sensors?"
332 extended_description: "Select turner_c_fluor_2 only if a second fluorometer is physically installed:\nthe BIO payload board announces two fluorometer channels regardless of what is\nwired, so an unselected second channel is not read or reported."
333 }];
334
335 optional int32 hub_id = 22 [default = 0, (jaia.field).debconf = {
336 group: HUB
337 identity: true
338 bounded_id: true
339 description: "Hub identification number"
340 extended_description: "This is used to set the hostname of the computer and set the correct value in the jaiabot configuration.\nValid hub_ids are 0 to 30, as reported by \"jaia admin bounds --hub_id\".\nTo change in the future, run \"sudo dpkg-reconfigure jaiabot-embedded\""
341 }];
342
343 enum UserRole
344 {
345 USER_ROLE_USER = 0;
346 USER_ROLE_ADVANCED = 1;
347 USER_ROLE_DEVELOPER = 2;
348 }
349 optional UserRole user_role = 23 [
350 default = USER_ROLE_USER,
351 (jaia.field).debconf = {
352 group: HUB
353 description: "The user role to be set in the Upgrade UI (this sets which Ansible playbooks are visible to the user)."
354 }
355 ];
356}
357
358message FleetConfig
359{
360 // Version of the contract this file was written for; files that predate
361 // the field are version 1
362 optional uint32 version = 10 [default = 1];
363
364 required int32 fleet = 1;
365 repeated int32 hubs = 2;
366 repeated int32 bots = 3;
367
368 message SSHKeys
369 {
370 repeated string permanent_authorized_keys = 1;
371 message HubKey
372 {
373 required int32 id = 1;
374 // The Yubikey's key handle; empty for the CloudHub, whose key never leaves it
375 required string private_key = 2;
376 required string public_key = 3;
377 }
378 repeated HubKey hub = 2;
379 message VPNTempKey
380 {
381 required string private_key = 2;
382 required string public_key = 3;
383 }
384 optional VPNTempKey vpn_tmp = 3;
385 }
386 required SSHKeys ssh = 4;
387
388 // Settings common to every node in the fleet; identity fields (type, ids,
389 // mode) are supplied per node and must not be set here
390 optional NodeSettings settings = 12;
391
392 message NodeOverride
393 {
394 required DebconfOverride.NodeType type = 1;
395 required int32 id = 2;
396 // Fields set here replace the common value for this node
397 required NodeSettings settings = 3;
398 }
399 repeated NodeOverride override = 13;
400
401 // Version 1 form of settings and override, migrated to NodeSettings
402 message Debconf
403 {
404 enum DebconfType
405 {
406 SELECT = 0;
407 MULTISELECT = 1;
408 STRING = 2;
409 BOOLEAN = 3;
410 NOTE = 4;
411 TEXT = 5;
412 PASSWORD = 6;
413 }
414
415 required string key = 1;
416 optional DebconfType type = 2 [default = SELECT];
417 required string value = 3;
418 }
419 repeated Debconf debconf = 5 [deprecated = true];
420 required string wlan_password = 6;
421 required bool service_vpn_enabled = 7;
422
423 message DebconfOverride
424 {
425 enum NodeType
426 {
427 HUB = 0;
428 BOT = 1;
429 }
430
431 required NodeType type = 1;
432 required int32 id = 2;
433 repeated Debconf debconf = 3;
434 }
435 repeated DebconfOverride debconf_override = 8 [deprecated = true];
436
437
438 message Communications
439 {
440 message IridiumSBD
441 {
442 message BotToIMEI
443 {
444 required int32 id = 1;
445 required string imei = 2;
446 }
447 repeated BotToIMEI bot = 1;
448 // Matches enum in Goby driver
449 enum SBDType
450 {
451 SBD_DIRECTIP = 1;
452 SBD_ROCKBLOCK = 2;
453 }
454 required SBDType sbd_type = 2;
455 message RockBLOCKParams
456 {
457 required string username = 1;
458 required string password = 2;
459 }
460 optional RockBLOCKParams rockblock = 3;
461 }
462 optional IridiumSBD iridium_sbd = 1;
463 }
464 optional Communications comms = 9;
465
466 // 10 is version, at the top of the message
467
468 // What a CloudHub needs that cannot be asked of AWS afterwards. Region, VPC,
469 // subnets, security groups, account and the Elastic IP are all discoverable from
470 // the instance, so they are deliberately absent: a major upgrade rebuilds them
471 // rather than carrying cloud.env across the rootfs swap.
472 message CloudHub
473 {
474 // Authentication front end: Authelia behind Caddy
475 required string base_uri = 1;
476 required string admin_email = 2;
477 required string smtp_address = 3;
478
479 // S3 bucket holding the bot offload; unset means jaia--cloudhub-data--fleet<fleet>
480 optional string data_bucket = 4;
481
482 // Unset means noreply@auth.jaia.tech; it must be verified with the SMTP provider
483 optional string smtp_sender = 5;
484 // SSM SecureString (name or ARN) holding {"username": ..., "password": ...};
485 // unset means /jaia/cloudhub/smtp_credentials in the CloudHub's own account and region
486 optional string smtp_credentials_ssm_parameter = 6;
487 }
488 optional CloudHub cloudhub = 11;
489
490 // Value of the jaia_customer tag on every AWS resource the fleet owns
491 optional string customer = 14 [default = "jaia"];
492
493 // A simulation has no CloudHub to reach, so the rule requiring one applies
494 // only to real fleets. Inferring this from the absence of hub 30 would make
495 // a misconfigured real fleet indistinguishable from a VirtualFleet.
496 enum FleetType
497 {
498 FLEET_TYPE_REAL = 0;
499 FLEET_TYPE_SIMULATION = 1;
500 }
501 optional FleetType fleet_type = 15 [default = FLEET_TYPE_REAL];
502
503 // Stated rather than inferred, for the same reason: a real fleet built
504 // without one and a real fleet that has lost hub 30 by mistake look alike,
505 // and only one of them should pass validation. A simulation never has one,
506 // so this says nothing about it either way.
507 //
508 // Not has_cloudhub: protobuf already generates that accessor for the
509 // optional cloudhub field above, and the two would not compile together.
510 optional bool includes_cloudhub = 16 [default = true];
511}