VSM C++ SDK
Vehicle Specific Modules SDK
Vehicle registration with UCS

Overview

Upon detecting a vehicle VSM sends Vsm_message with Register_vehicle payload. This request serves for several purposes:

  • Associate Vehicle name and tailnumber with ID which will be used to reference this vehicle instance during the session.
  • Define time origin for subsequent telemetry messages
  • Tell server the telemetry fields supported by vehicle
  • Tell server the mission items supported by vehicle
  • Tell server the commands supported by vehicle

Register_device message

Field nameTypeDescription
begin_of_epochuint64, millisecondsStart of epoch since 1970-01-01 00:00:00 UTC. All timestamps in telemetry fields will be relative to this value.
propertiesProperty_field User defined list of key-value pairs used to tell ucs additional information about vehicle.
register_vehicle Register_vehicle
register_adsb_aircraft Register_adsb_aircraft

UgCS server will use value pair vehicle_name + vehicle_tail_number to uniquely identify the vehicle system wide and across multiple sessions.

Register_vehicle message

Field nameTypeDescription
vehicle_serialUTF8 string (Preferrably unique) tail number of the vehicle. User configurable or generated by VSM.
autopilot_typeUTF8 string Value from Autopilot names or user defined value
autopilot_serialUTF8 string Autopilot serial number
port_name UTF8 string Connection name (Eg. "COM11" or "tcp:1.2.3.4:12345")
frame_typeUTF8 stringvalue from Vehicle frames or user defined value
begin_of_epochuint64, millisecondsStart of epoch since 1970-01-01 00:00:00 UTC. All timestamps in telemetry fields will be relative to this value.
propertiesProperty_field User defined list of key-value pairs used to tell ucs additional information about vehicle.
telemetry_fieldsRegister_field List of telemetry fields sent by the VSM. See Telemetry protocol for details.
commandsRegister_command List of available commands and mission items accepted by Vehicle. See vehicle_commands and mission_items for details

UgCS server will use value pair vehicle_name + vehicle_tail_number to uniquely identify the vehicle system wide and across multiple sessions.

Register_command message

Register_command message is used to register feature supported by vehicle with UgCS. Later VSM can dynamically enable/disable all previously registered commands via Command_availability message.

Field name Field typeDescription
namestring Name of command. Either telemetry field or mission item or vehicle command.
iduint32 Session specific ID mapped to this command.
parametersRegister_fieldList of parameters supported by given command. (See also Register_field message)
available_in_missionbool this command is available as part of mission
available_as_commandbool this command is available standalone command

Formal definition is found in Register_command message in ucs_vsm.proto file.


Autopilot names

List of autopilots which can be reported by VSM in Register_vehicle.autopilot_type field and UgCS will know how to display them.

NameDescription
ardupilot ArdupilotMega, Ardupilot on Pixhawk
px4 PX4
ardrone Parrot ArDrone
dji_a2 DJI A2
dji_a3 DJI A3
dji_wkm DJI Wookong
dji_naza DJI NAZA V2
dji_phantom2DJI Phantom2
dji_phantom2_vpDJI Phantom2 Vision Plus
dji_phantom3DJI Phantom3
dji_phantom4DJI Phantom4
dji_phantom4_proDJI Phantom4 Pro
dji_inspire1DJI Inspire1
dji_inspire2DJI Inspire2
dji_matrice100DJI Matrice 100
dji_matrice600DJI Matrice 600
dji_aceDJI ACE
dji_mavicDJI Mavic
dji_n3DJI N3
microdrones Microdrones MD200, MD1000
mikrokopter Mikrokopter
micropilot Micropilot
kestrel Kestrel
emulator Built in vehicle emulator

VSM can report other values here. In that case user will need to select the vehicle profile manually.

Vehicle frames

VSM should tell the frame type uppon vehicle registration. This helps UgCS to render the vehicle on client screen correctly. VSM can report any string as frame name. If non built in values are reporthed then user will need to select the frame avatar for the vehicle manually. List of built-in frame names which can be reported by VSM Register_vehicle.frame_type field and UgCS will know how to display them.

NameDescription
generic_fixed_wing Plane
generic_heli Classic heli frame
generic_tri_y Three leg (Y type) frame with two legs in front
generic_quad_i Four leg frame with one leg in front
generic_quad_x Four leg frame with two legs in front
generic_hexa_i Six leg frame with one leg in front
generic_hexa_v Six leg frame with two legs in front
generic_hexa_y Three leg (Y type) frame with double rotors two legs in front
generic_hexa_yi Three leg (Y type) frame with double rotors one leg in front
generic_octa_x Four leg (X type) frame with double rotors two legs in front
generic_octa_xi Four leg (+ type) frame with double rotors one leg in front
generic_octa_i Eight leg frame with one leg in front
generic_octa_v Eight leg frame with two legs in front
3dr_iris 3DR Iris frame (quad)
dji_phantom DJI Phantom2/3/4
dji_matrice DJI Matrice 100
dji_inspire DJI Inspire1
ardrone ArDRone