UCS-VSM protocol example¶
Sample scenario¶
This sample demonstrates UCS-VSM protocol in action.
Scenario description¶
We use sample vehicle with the following features:
“mypilot” autopilot on quad frame
It reports gps coordinates, icao code and flight mode in telemetry
It supports camera_trigger, “return_to_home”, “mission_upload”, takeoff and “auto” as standalone commands.
It supports camera_trigger, waypoint and takeoff as mission items
Demonstrate vehicle registration, telemetry, mission upload and responses to requests.
Protocol control flow¶
UCS establishes connection with VSM.
VSM sends VSM notification message and waits for UCS notification message before sending anything into this connection.
UCS sends UCS notification message.
Main purpose is to tell VSM the UCS ID which VSM will use to detect duplicate connections from the same UCS instance. It is a Vsm_message with register_peer payload. VSM notes the UCS id and if this is the first connection from ucs then it will start communicating. If VSM already has a connection with this id it will keep the connection idle and use it only if other connection breaks.
VSM sends Vehicle registration message for each already connected vehicle.
VSM detects new vehicle. VSM sends Vehicle registration message to all connected servers.
VSM starts sending telemetry packets from vehicle. See Telemetry message.
VSM reports command availability to UCS via Command availability message.
User issues Camera trigger command for vehicle.
VSM sends successful command completion via Camera trigger response.
User uploads mission to the vehicle. VSM receives Mission upload command.
Mission consists of takeoff command and two waypoints.
VSM fails mission with Mission upload response.
VSM uses custom error reporting feature to send error description.
Sample messages¶
UCS notification message¶
Vsm_message from UCS to VSM:
device_id: 0
register_peer {
peer_id: 341235662
}
VSM notification message¶
Vsm_message from VSM to UCS:
device_id: 0
register_peer {
peer_id: 3337720787
}
Vehicle registration message¶
Vsm_message from VSM to UCS:
device_id: 131
register_device {
begin_of_epoch: 1471529736786
properties {
name: "system_id"
value {
int_value: 1133413007
}
}
register_vehicle {
vehicle_serial: "MC13"
vehicle_name: "MyCopter"
frame_type: "generic_quad_x"
port_name: "tcp:127.0.0.1:14556"
vehicle_type: VEHICLE_TYPE_FIXED_WING
register_flight_controller {
autopilot_type: "mypilot"
autopilot_serial: "123456"
telemetry_fields {
name: "native_flight_mode"
field_id: 5
semantic: FIELD_SEMANTIC_ENUM
enumeration {
id: 3
description: "Auto"
}
enumeration {
id: 2
description: "Loiter"
}
enumeration {
id: 1
description: "Guided"
}
enumeration {
id: 0
description: "Stabilize"
}
}
telemetry_fields {
name: "latitude"
field_id: 19
semantic: FIELD_SEMANTIC_LATITUDE
}
telemetry_fields {
name: "longitude"
field_id: 20
semantic: FIELD_SEMANTIC_LONGITUDE
}
telemetry_fields {
name: "altitude_raw"
field_id: 13
semantic: FIELD_SEMANTIC_ALTITUDE_RAW
}
commands {
name: "takeoff"
id: 49
available_in_mission: true
available_as_command: true
}
commands {
name: "auto"
id: 28
available_in_mission: false
available_as_command: true
}
commands {
name: "rth"
id: 48
available_in_mission: false
available_as_command: true
}
commands {
name: "waypoint"
id: 50
parameters {
name: "ground_elevation"
field_id: 59
semantic: FIELD_SEMANTIC_GROUND_ELEVATION
}
parameters {
name: "heading"
field_id: 58
semantic: FIELD_SEMANTIC_HEADING
}
parameters {
name: "vertical_speed"
field_id: 57
semantic: FIELD_SEMANTIC_VERTICAL_SPEED
}
parameters {
name: "ground_speed"
field_id: 56
semantic: FIELD_SEMANTIC_GROUND_SPEED
}
parameters {
name: "altitude_origin"
field_id: 55
semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
}
parameters {
name: "acceptance_radius"
field_id: 54
semantic: FIELD_SEMANTIC_ACCEPTANCE_RADIUS
}
parameters {
name: "altitude_amsl"
field_id: 53
semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
}
parameters {
name: "longitude"
field_id: 52
semantic: FIELD_SEMANTIC_LONGITUDE
}
parameters {
name: "latitude"
field_id: 51
semantic: FIELD_SEMANTIC_LATITUDE
}
available_in_mission: true
available_as_command: true
}
commands {
name: "mission_upload"
id: 40
parameters {
name: "low_battery_action"
field_id: 45
semantic: FIELD_SEMANTIC_ENUM
}
parameters {
name: "gps_loss_action"
field_id: 44
semantic: FIELD_SEMANTIC_ENUM
}
parameters {
name: "rc_loss_action"
field_id: 43
semantic: FIELD_SEMANTIC_ENUM
}
parameters {
name: "safe_altitude"
field_id: 42
semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
}
parameters {
name: "altitude_origin"
field_id: 41
semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
}
available_in_mission: false
available_as_command: true
}
}
register_camera {
commands {
name: "camera_trigger"
id: 116
parameters {
name: "state"
field_id: 117
semantic: FIELD_SEMANTIC_ENUM
enumeration {
id: 2
description: "single_photo"
}
enumeration {
id: 3
description: "serial_photo"
}
enumeration {
id: 0
description: "on"
}
enumeration {
id: 1
description: "off"
}
}
available_in_mission: true
available_as_command: true
}
}
}
}
Telemetry message¶
Vsm_message from VSM to UCS:
device_id: 131
device_status {
telemetry_fields {
field_id: 13
ms_since_epoch: 3404
value {
float_value: 0
}
}
telemetry_fields {
field_id: 19
ms_since_epoch: 3404
value {
double_value: 0.99443216383835942
}
}
telemetry_fields {
field_id: 20
ms_since_epoch: 3404
value {
double_value: 0.4201642634865152
}
}
}
Command availability message¶
Vsm_message from VSM to UCS:
device_id: 131
device_status {
command_availability {
id: 50
is_available: true
is_enabled: true
}
command_availability {
id: 28
is_available: true
is_enabled: true
}
}
Camera trigger command¶
Vsm_message from UCS to VSM:
device_id: 131
message_id: 112
response_required: true
device_commands {
command_id: 1126
parameters {
field_id: 117
value {
int_value: 2
}
}
}
Camera trigger response¶
Vsm_message from VSM to UCS:
device_id: 131
message_id: 112
device_response {
code: STATUS_INVALID_OK
status: "Camera triggered"
}
Mission upload command¶
Vsm_message from UCS to VSM:
device_id: 131
message_id: 1111
response_required: true
device_commands {
command_id: 40
parameters {
field_id: 41
value {
float_value: 134.13
}
}
sub_commands {
command_id: 49
}
sub_commands {
command_id: 50
parameters {
field_id: 51
value {
double_value: 1.2
}
}
parameters {
field_id: 52
value {
double_value: 0.2
}
}
parameters {
field_id: 53
value {
float_value: 154.13
}
}
}
sub_commands {
command_id: 50
parameters {
field_id: 51
value {
double_value: 1.2
}
}
parameters {
field_id: 52
value {
double_value: 22.2
}
}
parameters {
field_id: 53
value {
float_value: 154.13
}
}
}
}
Mission upload response¶
Vsm_message from VSM to UCS:
device_id: 131
message_id: 1111
device_response {
code: STATUS_INVALID_PARAMETER
arguments: "Bad waypoint"
arguments: "2"
status: "longitude must be in range 0..2Pi"
}