VSM C++ SDK
Vehicle Specific Modules SDK
ucs_vsm.proto

Protobuf definition files

Protobuf Message definitions

1 package ugcs.vsm.proto;
2 
3 option java_package = "com.ugcs.ucs.vsm.proto";
4 option java_outer_classname = "VsmMessagesProto";
5 
6 import "ucs_vsm_defs.proto";
7 
8 // VSM-UCS Transport protocol wire format definition
9 //
10 // Frame wire format:
11 // <length><data>
12 // length Size of data in bytes encoded as LEB128 (https://en.wikipedia.org/wiki/LEB128)
13 // data Message data of type Vsm_message
14 //
15 // Having only one message type allows us to avoid sending message ID on the wire with each message.
16 
17 // Generic message
18 message Vsm_message {
19 
20  // Uniquely identifies the connected device. Exception is register_peer payload when this field is zero.
21  // This id is generated when Register_device message is created.
22  // It defines the context (session) for all subsequent communications with the device (in both directions).
23  required uint32 device_id = 1;
24 
25  // Unique message id. This will be put into response if response is required. Can be omitted if response is not required.
26  // Request message_id if this message is a response to particular request.
27  optional uint32 message_id = 2;
28 
29  // Indicates that peer will wait for response on this command.
30  optional bool response_required = 3;
31 
32  // Used to detect duplicate connections between ucs ans vsm.
33  // This must be the first message sent from ucs and VSM on new connection.
34  // In this case device_id==0 which means this message is for peer application not device.
35  // No device specific payloads can be present if device_id==0.
36  optional Register_peer register_peer = 4;
37 
38  optional Register_device register_device = 5;
39 
40  optional Unregister_device unregister_device = 6;
41 
42  repeated Device_command device_commands = 7;
43 
44  // If this field is present then this is a response to previously sent request.
45  // If message_id is present, too then it contains the message_id from the corresponding request.
46  optional Device_response device_response = 8;
47 
48  // Device can send this message any time it wants to report some info to ucs.
49  optional Device_status device_status = 9;
50 }
51 
52 // Used to tell the unique application ID to detect concurrent connections.
53 message Register_peer {
54 
55  required uint32 peer_id = 1;
56 }
57 
58 // Register various kinds of devices.
59 message Register_device {
60 
61  // begin_of_epoch is used to optimize space used for timestamp in each telemetry field.
62  // the absolute time is calculated as begin_of_epoch + timestamp.
63  // Milliseconds since 1970-01-01 00:00:00 UTC.
64  // This value is vehicle registration time. Thus UCS
65  // could show a warning about out of sync time between ucs and VSM if the value
66  // differs from current time a lot.
67  required uint64 begin_of_epoch = 1;
68 
69  // User defineable key-value pairs
70  repeated Property_field properties = 2;
71 
72  // Registers vehicle with its commands, telemetry, etc...
73  optional Register_vehicle register_vehicle = 3;
74 
75  // Used by adsb receiver to report data about detected aircrafts
76  optional Register_adsb_aircraft register_adsb_aircraft = 4;
77 }
78 
79 // Invalidates the specified Vsm_message.device_id
80 // Presence of this payload means that device has disconnected and all its state should be dropped.
81 // Use this to drop any context established via Register_device message.
82 // Important: Automatically unregisters all subdevices registered under this device.
83 message Unregister_device {
84 }
85 
86 message Device_status {
87 
88  // place to put raw data received from vehicle or debug messages from VSM.
89  repeated string status_messages = 1;
90 
91  // Device telemetry
92  repeated Telemetry_field telemetry_fields = 2;
93 
94  // current command availability
95  repeated Command_availability command_availability = 3;
96 }
97 
98 message Device_response {
99 
100  // Response code. on previously sent request.
101  required Status_code code = 1;
102 
103  // array of values to create localized error string for given Status_code.
104  repeated string arguments = 2;
105 
106  // place to put raw data received from vehicle or debug messages from VSM.
107  optional string status = 3;
108 
109  // VSM generated mission ID which is later reported in telemetry as current_mission_id
110  // It is used to tell the server the validity of mission_command_map.
111  // Server should drop the mission map as soon as VSM reports different current_mission_id.
112  // Server must ignore the reported curent_command values until it gets a valid current_mission_id.
113  optional uint32 mission_id = 4;
114 
115  // Command mapping between mission uploaded to the vehicle and mission received by server.
116  // Server must keep this map tied to specific vehicle instance until vehicle
117  // explicitly reports current_mission_id different from this one.
118  // Server should use this map to map reported current_command only while VSM reports the same current_mission_id.
119  // I.e. server should keep the map but not use it if VSM reports current_mission_id==N/A.
120  repeated Mission_command_map mission_command_map = 5;
121 }
122 
123 message Mission_command_map {
124 
125  // Current command ID reported by the VSM as current_command telemetry field.
126  required uint32 vehicle_command_id = 1;
127 
128  // Corresponding command index in mission_upload sub_commands array. 1-based.
129  required uint32 mission_command_idx = 2;
130 }
131 
132 // VSM must send this message before any other device specific payloads can be sent.
133 message Register_vehicle {
134 
135  // User specified identification string of the vehicle
136  optional string vehicle_serial = 1;
137 
138  // User specified identification string of the vehicle
139  optional string vehicle_name = 2;
140 
141  // Frame identificator (if applicable)
142  optional string frame_type = 3;
143 
144  // Connection name (Eg. "COM11" or "tcp:1.2.3.4:12345")
145  optional string port_name = 4;
146 
147  // copter, plane, rover, boat
148  required Vehicle_type vehicle_type = 5;
149 
150  repeated Register_flight_controller register_flight_controller = 6;
151 
152  repeated Register_gimbal register_gimbal = 7;
153 
154  repeated Register_camera register_camera = 8;
155 
156  repeated Register_adsb_transponder register_adsb_transponder = 9;
157 
158  repeated Register_winch register_winch = 10;
159 }
160 
161 message Device_command {
162 
163  // Command id (Must be from previously registered commands)
164  required uint32 command_id = 1;
165 
166  // list of command parameters.
167  repeated Parameter_field parameters = 2;
168 
169  // List of subcommands (E.g. mission items)
170  repeated Device_command sub_commands = 3;
171 }
172 
173 message Telemetry_field {
174 
175  // Session wide unique field id defined via Register_field message
176  required uint32 field_id = 1;
177 
178  // Time in ms this value was gathered since begin_of_epoch which set in Register_vehicle message.
179  // NOTE: this value is calculated using system_clock and must not be assumed monotonic.
180  // It can have negative values if system_clock is turned back while VSM is running.
181  required sint64 ms_since_epoch = 2;
182 
183  required Field_value value = 3;
184 }
185 
186 message Parameter_field {
187 
188  // Unique field id defined via Register_field message
189  required uint32 field_id = 1;
190 
191  required Field_value value = 2;
192 }
193 
194 message Property_field {
195 
196  // parameter name used to send some value without registering first.
197  required string name = 1;
198 
199  required Field_value value = 2;
200 }
201 
202 message Field_value {
203 
204  // If this is present field value is one of supported "meta" values: na, unknown, invalid
205  optional Meta_value meta_value = 1;
206 
207  // value holders for various regular field types.
208  optional sint64 int_value = 2;
209 
210  optional float float_value = 3;
211 
212  optional double double_value = 4;
213 
214  optional string string_value = 5;
215 
216  optional bool bool_value = 6;
217 }
218 
219 // VSM can enable/disable specific command at runtime
220 message Command_availability {
221 
222  // command_id
223  required uint32 id = 1;
224 
225  // capability is supported by vehicle
226  optional bool is_available = 2;
227 
228  // capability can be used on the vehicle, currently
229  optional bool is_enabled = 3;
230 }
231 
232 // VSM must send this message before it can be used or Command_availability can be sent.
233 message Register_command {
234 
235  // Name of command
236  required string name = 1;
237 
238  // Session specific id for name.
239  required uint32 id = 2;
240 
241  // parameters supported by command.
242  repeated Register_field parameters = 3;
243 
244  // this command is available as mission item
245  optional bool available_in_mission = 4;
246 
247  // this command can be issued as seperate command
248  optional bool available_as_command = 5;
249 }
250 
251 message Register_flight_controller {
252 
253  // Autopilot identificator
254  required string autopilot_type = 2;
255 
256  // Autopilot serial number if available
257  optional string autopilot_serial = 3;
258 
259  // Telemetry fields supported by device
260  repeated Register_field telemetry_fields = 8;
261 
262  // Commands supported by the payload
263  repeated Register_command commands = 9;
264 }
265 
266 message Register_camera {
267 
268  // Camera name if available
269  optional string name = 1;
270 
271  // Telemetry fields supported by device
272  repeated Register_field telemetry_fields = 2;
273 
274  // Commands supported by the payload
275  repeated Register_command commands = 3;
276 }
277 
278 message Register_gimbal {
279 
280  // Gimbal name if available
281  optional string name = 1;
282 
283  // Telemetry fields supported by device
284  repeated Register_field telemetry_fields = 2;
285 
286  // Commands supported by the payload
287  repeated Register_command commands = 3;
288 }
289 
290 message Register_adsb_transponder {
291 
292  // Transponder name if available
293  optional string name = 1;
294 
295  // Telemetry fields supported by device
296  repeated Register_field telemetry_fields = 2;
297 
298  // Commands supported by the payload
299  repeated Register_command commands = 3;
300 }
301 
302 message Register_winch {
303 
304  // Winch name if available
305  optional string name = 1;
306 
307  // Telemetry fields supported by device
308  repeated Register_field telemetry_fields = 2;
309 
310  // Commands supported by the payload
311  repeated Register_command commands = 3;
312 }
313 
314 message Register_adsb_aircraft {
315 
316  // 24bit integer uniquely identifying the aircaft
317  required uint32 icao = 1;
318 
319  // Telemetry fields supported by device
320  repeated Register_field telemetry_fields = 5;
321 }
322 
323 // Used to send definitions of vehicle supported parameters and telemetry fields to UCS
324 message Register_field {
325 
326  // Name of telemetry field.
327  required string name = 1;
328 
329  // Session specific field id.
330  required uint32 field_id = 2;
331 
332  // Required for any defined field. Specifies the value type.
333  required Field_semantic semantic = 3;
334 
335  // Default value to show in client.
336  // If min_value == max_value it means that parameter is not user chengeable and should be set to default_value.
337  optional Field_value default_value = 4;
338 
339  // Minimum value of field
340  optional Field_value min_value = 5;
341 
342  // Maximum value of field
343  optional Field_value max_value = 6;
344 
345  // User defined enumreation when field_semantic == FIELD_SEMANTIC_ENUM.
346  repeated Field_enumeration enumeration = 7;
347 }
348 
349 // Used to send definitions of user-defined enumerations used in telemetry and parameters.
350 message Field_enumeration {
351 
352  // Value of enum field
353  // The value of id must be constant for the field it is defined for.
354  // I.e. it cannot be session specific. These values are saved directly in telemetry database.
355  required int32 id = 1;
356 
357  // Description of the value
358  required string description = 2;
359 }
360 

Protobuf enumerations

1 package ugcs.vsm.proto;
2 
3 option java_package = "com.ugcs.ucs.vsm.proto";
4 option java_outer_classname = "VsmDefinitionsProto";
5 
6 // Response code sent by VSM tu UCS
7 enum Status_code {
8  STATUS_OK = 0;
9  // Generic error
10  STATUS_FAILED = 1;
11  // Command is not supported
12  STATUS_INVALID_COMMAND = 2;
13  // Command parameters are invalid
14  // Cannot use STATUS_INVALID_PARAMETER because it clashes with define in winnt.h
15  STATUS_INVALID_PARAM = 3;
16  // Invalid session id
17  STATUS_INVALID_SESSION_ID = 4;
18 }
19 
20 enum Vehicle_type {
21  VEHICLE_TYPE_GROUND = 0;
22  VEHICLE_TYPE_FIXED_WING = 1;
23  VEHICLE_TYPE_MULTICOPTER = 2;
24  VEHICLE_TYPE_HELICOPTER = 3;
25 }
26 
27 enum Meta_value {
28  META_VALUE_NA = 0;
29 }
30 
31 // Built in telemetry enums
32 
33 enum Gps_fix_type {
34  GPS_FIX_TYPE_NONE = 0;
35  GPS_FIX_TYPE_2D = 1;
36  GPS_FIX_TYPE_3D = 2;
37  GPS_FIX_TYPE_DIFF = 3;
38  GPS_FIX_TYPE_RTK = 4;
39 }
40 
41 enum Control_mode {
42  CONTROL_MODE_MANUAL = 0;
43  CONTROL_MODE_AUTO = 1;
44  CONTROL_MODE_CLICK_GO = 2;
45  CONTROL_MODE_JOYSTICK = 3;
46 }
47 
48 enum Flight_mode {
49  FLIGHT_MODE_WAYPOINTS = 0; // Vehicle is navigating mission waypoints
50  FLIGHT_MODE_RTH = 1; // Vehicle is returning home
51  FLIGHT_MODE_LAND = 2; // Vehicle is landing
52  FLIGHT_MODE_TAKEOFF = 3; // Vehicle is taking off
53  FLIGHT_MODE_HOLD = 4; // Vehicle is holding position.
54 }
55 
56 // Built in command parameter enums
57 
58 enum Adsb_mode {
59  ADSB_MODE_OFF = 0;
60  ADSB_MODE_STBY = 1;
61  ADSB_MODE_ON = 2;
62  ADSB_MODE_ALT = 3;
63 }
64 
65 enum Failsafe_action {
66  FAILSAFE_ACTION_RTH = 0;
67  FAILSAFE_ACTION_LAND = 1;
68  FAILSAFE_ACTION_WAIT = 2;
69  FAILSAFE_ACTION_CONTINUE = 3;
70 }
71 
72 enum Camera_power_state {
73  CAMERA_POWER_STATE_ON = 0;
74  CAMERA_POWER_STATE_OFF = 1;
75  CAMERA_POWER_STATE_TOGGLE = 2;
76 }
77 
78 enum Camera_video_source {
79  CAMERA_VIDEO_SOURCE_PRIMARY = 0;
80  CAMERA_VIDEO_SOURCE_SECONDARY = 1;
81 }
82 
83 enum Camera_command_trigger_state {
84  CAMERA_COMMAND_TRIGGER_STATE_SINGLE_SHOT = 0;
85  CAMERA_COMMAND_TRIGGER_STATE_VIDEO_START = 1;
86  CAMERA_COMMAND_TRIGGER_STATE_VIDEO_STOP = 2;
87  CAMERA_COMMAND_TRIGGER_STATE_VIDEO_TOGGLE = 3;
88 }
89 
90 enum Camera_mission_trigger_state {
91  CAMERA_MISSION_TRIGGER_STATE_ON = 0;
92  CAMERA_MISSION_TRIGGER_STATE_OFF = 1;
93  CAMERA_MISSION_TRIGGER_STATE_SINGLE_PHOTO = 2;
94  CAMERA_MISSION_TRIGGER_STATE_SERIAL_PHOTO = 3;
95 }
96 
97 enum Panorama_mode {
98  PANORAMA_MODE_PHOTO = 0;
99  PANORAMA_MODE_VIDEO = 1;
100 }
101 
102 enum Turn_type {
103  TURN_TYPE_STOP_AND_TURN = 0;
104  TURN_TYPE_STRAIGHT = 1;
105  TURN_TYPE_SPLINE = 2;
106  TURN_TYPE_BANK_TURN = 3;
107 }
108 
109 // Field/parameter type (semantic)
110 enum Field_semantic {
111 
112  // Used internally.
113  FIELD_SEMANTIC_DEFAULT = 0;
114  // Description, Units, Data type, Range, Origin, Positive direction
115 
116  // Geodetic latitude, radians, double, -Pi/2..Pi/2, equator, north
117  FIELD_SEMANTIC_LATITUDE = 1;
118 
119  // Geodetic longitude, radians, double, -Pi..Pi, Greenwich meridian, East
120  FIELD_SEMANTIC_LONGITUDE = 2;
121 
122  // WGS84 altitude, meters, numeric
123  FIELD_SEMANTIC_ALTITUDE_AMSL = 3;
124 
125  // Altitude AGL, meters, numeric
126  FIELD_SEMANTIC_ALTITUDE_AGL = 4;
127 
128  // Raw altitude reading from vehicle. Typically above home location., meters, numeric
129  FIELD_SEMANTIC_ALTITUDE_RAW = 5;
130 
131  // Vehicle nose angle, radians, numeric, 0..2Pi, North, East
132  FIELD_SEMANTIC_HEADING = 6;
133 
134  // Battery voltage, volts, numeric
135  FIELD_SEMANTIC_VOLTAGE = 8;
136 
137  // Air speed, m/s, numeric
138  FIELD_SEMANTIC_AIR_SPEED = 9;
139 
140  // Ground speed, m/s, numeric
141  FIELD_SEMANTIC_GROUND_SPEED = 10;
142 
143  // Climb speed, m/s, numeric
144  FIELD_SEMANTIC_VERTICAL_SPEED = 11;
145 
146  // GNSS satellite count, numeric
147  FIELD_SEMANTIC_SATELLITE_COUNT = 12;
148 
149  // Fix type, numeric, enum Gps_fix_type
150  FIELD_SEMANTIC_GPS_FIX_TYPE = 13;
151 
152  // Roll angle, radians, numeric, -Pi..Pi, Horizon, right
153  FIELD_SEMANTIC_ROLL = 14;
154 
155  // Pitch angle, radians, numeric, -Pi..Pi, Horizon, up
156  FIELD_SEMANTIC_PITCH = 15;
157 
158  // Yaw angle, radians, numeric, 0..2Pi, unspecified, East
159  FIELD_SEMANTIC_YAW = 16;
160 
161  // RC link quality, , numeric, [0..1]
162  FIELD_SEMANTIC_RC_LINK_QUALITY = 17;
163 
164  // Battery current, amperes, numeric
165  FIELD_SEMANTIC_CURRENT = 18;
166 
167  // Groundstation datalink quality, , numeric, [0..1]
168  FIELD_SEMANTIC_GCS_LINK_QUALITY = 19;
169 
170  // Camera Field-of-view horizontal angle, radians, numeric, 0..Pi
171  FIELD_SEMANTIC_FOV_H = 23;
172 
173  // Camera Field-of-view veritcal angle, radians, numeric, 0..Pi
174  FIELD_SEMANTIC_FOV_V = 24;
175 
176  // Current control mode, int, enum Control_mode
177  FIELD_SEMANTIC_CONTROL_MODE = 26;
178 
179  // Terrain elevation AMSL, meters, numeric
180  FIELD_SEMANTIC_GROUND_ELEVATION = 27;
181 
182  // Waypoint acceptance radius, meters, numeric
183  FIELD_SEMANTIC_ACCEPTANCE_RADIUS = 28;
184 
185  // Waypoint loiter radius, meters, numeric
186  FIELD_SEMANTIC_LOITER_RADIUS = 29;
187 
188  // ADSB icao code, 24 bits, numeric, represented as hex
189  FIELD_SEMANTIC_ICAO = 30;
190 
191  // ADSB transponder mode, enum, Adsb_mode, numeric
192  FIELD_SEMANTIC_ADSB_MODE = 31;
193 
194  // ADSB squawk code, 12 bits, numeric, represented as octal
195  FIELD_SEMANTIC_SQUAWK = 32;
196 
197  // Time interval, milliseconds, numeric, represented as time
198  FIELD_SEMANTIC_MILLISECONDS = 33;
199 
200  // Battery capacity percentage, numeric, [0..1]
201  FIELD_SEMANTIC_CAPACITY_LEVEL = 34;
202 
203  // Vehicle flight mode, enum, Flight_mode
204  FIELD_SEMANTIC_FLIGHT_MODE = 35;
205 
206  // Generic types used for user-defined telemetry fields.
207 
208  // Generic number type. Exact type (float, int, etc...) will be detected automatically
209  FIELD_SEMANTIC_NUMERIC = 101;
210 
211  // boolean
212  FIELD_SEMANTIC_BOOL = 104;
213 
214  // utf8 string
215  FIELD_SEMANTIC_STRING = 105;
216 
217  // enum. Possible values defined via Register_enumeration message.
218  FIELD_SEMANTIC_ENUM = 106;
219 }