Vehicle registration with UCS¶
Overview¶
Upon detecting a vehicle VSM sends Vsm_message with Register_device payload. This request serves for several purposes:
Associate Device with ID which will be used to reference this device instance during the session.
Define time origin for subsequent telemetry messages
Tell server the subsystems supported by device
Tell server the telemetry fields supported by device
Tell server the mission items supported by device
Tell server the commands supported by device
Vsm_message¶
Field name |
Field type |
Description |
|---|---|---|
device_id |
uint32 |
Uniquely identifies the connected device. Exception is register_peer payload when this field is zero. This id is generated when Register_device message is created. It defines the context (session) for all subsequent communications with the device (in both directions). |
message_id |
uint32 |
Unique message id. This will be put into response if response is required. Can be omitted if response is not required. Request message_id if this message is a response to particular request. |
response_required |
bool |
Indicates that peer will wait for response on this message. |
register_peer |
Register_peer |
Used to detect duplicate connections between ucs ans vsm. This must be the first message sent from ucs and VSM on new connection. In this case device_id==0 which means this message is for peer application not device. No device specific payloads can be present if device_id==0. |
register_device |
Register_device |
|
unregister_device |
Unregister_device |
|
device_command |
Device_command |
List of commands for device |
device_response |
device_response |
If this field is present then this is a response to previously sent request. If message_id is present, too then it contains the message_id from the corresponding request. |
device_status |
Device_status |
Device can send this message any time it wants to report some info to ucs. |
Register_device message¶
Field name |
Type |
Description |
|---|---|---|
begin_of_epoch |
uint64, milliseconds |
Start of epoch since 1970-01-01 00:00:00 UTC. All timestamps in telemetry fields will be relative to this value. |
type |
Device_type |
Type of device (Vehicle, ADSB receiver, etc…) |
properties |
Property_field |
User defined list of key-value pairs used to tell ucs additional information about vehicle. |
subsystems |
Register_subsystem message¶
Device is a set of subsystems of different types. Vehicle registration should register at least a flight controller (autopilot). Other subsystems are optional. There can be multiple instances of the same type (for example: two cameras).
Field name |
Type |
Description |
|---|---|---|
type |
Subsystem_type |
Value from |
properties |
Property_field |
key-value pairs for device specific information |
telemetry_fields |
Register_field |
List of telemetry fields sent by the VSM. See |
commands |
List of available commands and mission items accepted by device. See vehicle_commands and mission_items for details |
Subsystem types¶
Name |
Description |
|---|---|
SUBSYSTEM_TYPE_FLIGHT_CONTROLLER |
Flight controller |
SUBSYSTEM_TYPE_GIMBAL |
Gimbal |
SUBSYSTEM_TYPE_CAMERA |
Camera |
SUBSYSTEM_TYPE_ADSB_TRANSPONDER |
ADSB transponder |
SUBSYSTEM_TYPE_WINCH |
Winch |
SUBSYSTEM_TYPE_USER |
User defined subsystem. Used to register unspecified subsystem. |
Flight controller subsystem¶
There is one required property and one optional property for flight controller subsystem:
Subsystem property |
Type |
Required |
Description |
|---|---|---|---|
autopilot_type |
string |
yes |
Any user defined name. UgCS natively supports values from |
autopilot_serial |
string |
no |
Autopilot serial number if it can be read from autopilot |
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 type |
Description |
|---|---|---|
name |
string |
Name of command. Either telemetry field or mission item or command. |
id |
uint32 |
Session specific ID mapped to this command. |
parameters |
Register_field |
List of parameters supported by given command. (See also |
available_in_mission |
bool |
this command is available as part of mission |
available_as_command |
bool |
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 when registering subsystem of type SUBSYSTEM_TYPE_FLIGHT_CONTROLLER and UgCS will know how to display them.
Name |
Description |
|---|---|
ardupilot |
ArdupilotMega, Ardupilot on Pixhawk |
px4 |
PX4 |
dji_a2 |
DJI A2 |
dji_a3 |
DJI A3 |
dji_wkm |
DJI Wookong |
dji_naza |
DJI NAZA V2 |
dji_phantom2 |
DJI Phantom2 |
dji_phantom2_vp |
DJI Phantom2 Vision Plus |
dji_phantom3 |
DJI Phantom3 |
dji_phantom4 |
DJI Phantom4 |
dji_phantom4_pro |
DJI Phantom4 Pro |
dji_phantom4_pro_v2 |
DJI Phantom4 Pro V2.0 |
dji_inspire1 |
DJI Inspire1 |
dji_inspire2 |
DJI Inspire2 |
dji_matrice100 |
DJI Matrice 100 |
dji_matrice600 |
DJI Matrice 600 |
dji_ace |
DJI ACE |
dji_mavic |
DJI Mavic |
dji_spark |
DJI Spark |
dji_n3 |
DJI N3 |
microdrones |
Microdrones MD200, MD1000 |
mikrokopter |
Mikrokopter |
micropilot |
Micropilot |
kestrel |
Kestrel |
emulator |
Reserved for built-in vehicle emulators |
Vehicle frames¶
VSM should tell the frame type upon vehicle registration. 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. ================== ============================================================= Name Description ================== ============================================================= 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 generic_tilt_rotor Tilt rotor generic_vtol_duo VTOL plane with 2 rotors generic_vtol_quad VTOL plane with 4 rotors generic_vtol Generic VTOL capable vehicle 3dr_iris 3DR Iris frame (quad) dji_phantom DJI Phantom2/3/4 dji_matrice DJI Matrice 100 dji_inspire DJI Inspire1 yuneec_h520 Yuneec Typhoon H520 ================== =============================================================