VSM C++ SDK
Vehicle Specific Modules SDK
UCS-VSM Commands

Command registration

Before commands can be issued to the vehicle VSM must inform UgCS about supported commands and mission items. This is done at the time of registering the vehicle with the system. Command registration includes description of supported parameters and their default values.

For each command vehicle supports it must send a Register_command message as part of Register_vehicle message before it can issue command via Device_command message.

Device_command message

Field nameTypeDescription
command_iduint32 Registered id for command. See Commands natively supported by UgCS
parameters Parameter_field List of command specific parameters
sub_commands Vsm_command List of sub commands for this command. Used when command is Mission upload

Commands natively supported by UgCS

Alphabetical list of supported vehicle commands available as subcommands for Mission upload command and as standalone commands

These are the commands natively supported by UgCS (commands with known semantic). By registering command from this list VSM notifies the UgCS that vehicle is capable to execute given command with given parameters.

Command Subsystem In Mission From UI Description
adsb_set_ident ASDB - + turn IDENT on
adsb_set_mode ASDB - + turn transponder on/off
arm FC - + ARM command is supported
auto FC - + Start mission flight
camera_power Camera - + Switch camera on/off
camera_trigger_by_distanceCamera + - Trigger camera by distance
camera_trigger_by_timeCamera + - Trigger camera by time
camera_trigger_command Camera - + Trigger camera shutter
camera_trigger_missionCamera + - Trigger camera shutter
direct_payload_control Gimbal - + Allows direct payload control from GS
direct_vehicle_control FC - + Direct vehicle control (Joystick mode)
disarm FC - + DISARM command is supported
emergency_land FC - + Emergency land (crash landing)
guided FC - + Enter Click&Go mode
joystick FC - + Enter joystick control mode
land_command FC - + Land command
land_missionFC + - Landing waypoint
manual FC - + Enable manual control mode
mission_pause FC - + Mission can be paused from client
mission_resume FC - + Mission can be resumed from client
mission_upload FC - + Vehicle supports mission flight. Can contain commands marked here as available in mission.
moveFC + - Specify next waypoint and start moving towards it
panoramaFC + - Do panorama
payload_controlCamera + - Camera control (tilt, roll, yaw, zoom)
repeat_servo FC + + Repeat servo movement back an forth
return_to_home FC - + Return to HOME position is supported
select_as_video_source Camera - + Select this camera as video source
set_fence FC - + Create cylindrical fence around home location
set_gear_state FC - + Retract or release gear
set_headingFC + - Set vehicle heading
set_homeFC + - Specify Home location
set_parameter FC, ADSB + + Vehicle configuration. Contains a list of parameter definitions which can be set for the vehicle.
set_poiFC + - Set Point Of Interest
set_position_offset FC - + Set position offset of vehicle (i.e. moving relatively to current position)
set_relative_heading FC - + Set heading of vehicle by turning relatively to current heading
set_servo FC + + Set servo to given PWM value
set_speedFC + - Set Ground speed
set_tension FC - + Select tension value for tethered drone
takeoff_command FC - + Takeoff command
takeoff_missionFC + - Specify Takeoff point.
trigger_calibrationFC - + Trigger sensor calibration
waitFC + - Wait for specified time before proceeding to next mission item
waypoint FC - + Enter Click&Go mode, specify waypoint and start moving towards it

Other commands can be defined by VSM via Register_vehicle.register_command message.


ADSB IDENT

Command ID: "adsb_set_ident"

Description: Turn on IDENT

Command has no parameters.

ADSB Set mode

Command ID: "adsb_set_mode"

Description: Turn ADSB transponder on/standby/off

Parameters

NameTypeDescription
modeFIELD_SEMANTIC_ADSB_MODE Desired transponder mode see Adsb_mode enum

Arm vehicle

Command ID: "arm"

Description: Arm the motors.

There are no parameters for this command.

Start mission

Command ID: "auto"

Description: Put vehicle in AUTO control mode. Vehicle will setart flying mission if present.

There are no parameters for this command.

Set camera power state

Command ID: "camera_power"

Description: Switch camera on/off

NameTypeDescription
power_stateFIELD_SEMANTIC_ENUM See Camera power states

Camera power states

NameValueDescription
on CAMERA_POWER_STATE_ON Power on
off CAMERA_POWER_STATE_OFF Power off
toggle CAMERA_POWER_STATE_TOGGLE Switch power

Trigger camera by distance

Mission item ID: "camera_trigger_by_distance"

Description: Initiate camera trigger on regular distance intervals sarting from current position.

Parameters

NameTypeDescription
countFIELD_SEMANTIC_INT Number of consecutive trigger actions to perform.
delayFIELD_SEMANTIC_NUMERIC Time in seconds to wait for the first trigger
distanceFIELD_SEMANTIC_NUMERIC Distance to travel in meters between consecutive triggers.

Trigger camera by time

Mission item ID: "camera_trigger_by_time"

Description: Initiate camera trigger on regular time intervals sarting from current position.

Parameters

NameTypeDescription
periodFIELD_SEMANTIC_NUMERIC Time inseconds to wait between triggers.
delayFIELD_SEMANTIC_NUMERIC Time in seconds to wait for the first trigger
countFIELD_SEMANTIC_INT Number of consecutive trigger actions to perform.

Trigger camera from user interface

Mission item ID: "camera_trigger_command"

Description: Initiate camera trigger at current WP

Parameters

NameTypeDescription
trigger_state FIELD_SEMANTIC_ENUM Camera trigger state

Camera trigger states

NameValueDescription
video_start CAMERA_COMMAND_TRIGGER_STATE_VIDEO_START Start recording
video_stop CAMERA_COMMAND_TRIGGER_STATE_VIDEO_STOP Stop recording or serial shooting
single_shot CAMERA_COMMAND_TRIGGER_STATE_SINGLE_SHOT Take a single photo
video_toggle CAMERA_COMMAND_TRIGGER_STATE_VIDEO_TOGGLE Switch video on/off

Trigger camera

Mission item ID: "camera_trigger_mission"

Description: Initiate camera trigger on regular time intervals sarting from current position.

Parameters

NameTypeDescription
state FIELD_SEMANTIC_ENUM Camera trigger state

Camera trigger state

NameValueDescription
on CAMERA_MISSION_TRIGGER_STATE_ON Start recording
off CAMERA_MISSION_TRIGGER_STATE_OFF Stop recording or serial shooting
single_photo CAMERA_MISSION_TRIGGER_STATE_SINGLE_PHOTO Take a single photo
serial_photo CAMERA_MISSION_TRIGGER_STATE_SERIAL_PHOTO Take a series of photos

Direct Payload Control

Command ID: "direct_payload_control"

Description: Issue direct payload control command to the vehicle. Used to send joystick values to the vehicle payload.

Parameters

NameTypeDescription
pitchFIELD_SEMANTIC_NUMERIC pitch value [-1 .. +1]
rollFIELD_SEMANTIC_NUMERIC roll value [-1 .. +1]
yawFIELD_SEMANTIC_NUMERIC yaw value [-1 .. +1]
zoomFIELD_SEMANTIC_NUMERIC zoom value [-1 .. +1]

Direct Vehicle Control

Command ID: "direct_vehicle_control"

Description: Issue direct vehicle control command to the vehicle. Used to send joystick values to the vehicle.

Parameters

NameTypeDescription
pitchFIELD_SEMANTIC_NUMERIC pitch value [-1 .. +1]
rollFIELD_SEMANTIC_NUMERIC roll value [-1 .. +1]
yawFIELD_SEMANTIC_NUMERIC yaw value [-1 .. +1]
trottleFIELD_SEMANTIC_NUMERIC trottle value [-1 .. +1]

Disarm vehicle

Command ID: "disarm"

Description: Disarm the motors.

There are no parameters for this command.

Emergency Land

Command ID: "emergency_land"

Description: Emergency Land. Immediately turn off motors.

There are no parameters for this command.

Guided (Click&Go) mode

Command ID: "guided"

Description: Put vehicle in Click&Go control mode. Vehicle can be controlled via Waypoint command command.

There are no parameters for this command.

Joystick

Command ID: "joystick"

Description: Enter Joystick control mode.

There are no parameters for this command.

Land

Command ID: "land_command"

Description: Land at current position

There are no parameters for this command.

Landing position

Mission item ID: "land_mission"

Description: Specify landing position of the vehicle.

Parameters

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL Altitude at which to begin descent.
descent_rateFIELD_SEMANTIC_VERTICAL_SPEED Descent speed in m/s
ground_elevationFIELD_SEMANTIC_GROUND_ELEVATION Ground elevation at landing position (optional)
acceptance_radiusFIELD_SEMANTIC_ACCEPTANCE_RADIUS When the sphere with the radius centered at the target position is hit by the vehicle the target position is considered reached.
headingFIELD_SEMANTIC_HEADING Vehicle heading at the WP

Manual control mode.

Command ID: "manual"

Description: Put vehicle in MANUAL control mode. Vehicle can be controlled via RC transmitter.

There are no parameters for this command.

Pause mission

Command ID: "mission_pause"

Description: Pause mission execution (HOLD). This will put vehicle in either Click&Go or Joystick mode depending on autopilot.

There are no parameters for this command.

Resume mission flight

Command ID: "mission_resume"

Description: Continue with mission.

There are no parameters for this command.

Mission upload

Command ID: "mission_upload"

Description: Uploads mission to the vehicle. All mission items are added to Device_command.sub_commands list. See also supported commands.

Supported parameters:

NameTypeDescription
altitude_origin FIELD_SEMANTIC_ALTITUDE_AMSL Altitude origin of the vehicle
safe_altitude FIELD_SEMANTIC_ALTITUDE_AMSL Safe altitude. used for RTH and failsafe actions
rc_loss_action FIELD_SEMANTIC_ENUM Failsafe action on RC loss. See Failsafe actions natively supported by UgCS
gps_loss_action FIELD_SEMANTIC_ENUM Failsafe action on GPS loss. See Failsafe actions natively supported by UgCS
low_battery_action FIELD_SEMANTIC_ENUM Failsafe action on low battery. See Failsafe actions natively supported by UgCS

Failsafe actions natively supported by UgCS

Action name Value Description
continueFAILSAFE_ACTION_CONTINUE Continue with mission. Effectively ignores the failsafe condition.
waitFAILSAFE_ACTION_WAIT Wait for failsafe condition to end and then continue with mission.
landFAILSAFE_ACTION_LAND Land immediately at current position.
rthFAILSAFE_ACTION_RTH Climb to safe atlitude defined by safe_altitude parameter and return to home position defined by Set home position mission item.

Move command

Mission item ID: "move"

Description: Specifies the next waypoint. Upon encountering this item vehicle starts navigating to given coordinates using current speed and heading settings. Next mission item will be executed when vehicle arrives at the waypoint.

Supported parameters:

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL
ground_elevationFIELD_SEMANTIC_GROUND_ELEVATION Elevation in meters (i.e. terrain height) underneath the position.
turn_typeFIELD_SEMANTIC_ENUM See Vehicle turn types for details
acceptance_radiusFIELD_SEMANTIC_ACCEPTANCE_RADIUS When the sphere with the radius centered at the target position is hit by the vehicle the target position is considered reached.
loiter_radiusFIELD_SEMANTIC_LOITER_RADIUS Radius of the point fly-by orbit in meters. Positive value stands for the CW direction, negative - CCW. Use 0 for no-braking pass through the target point.
wait_timeFIELD_SEMANTIC_NUMERIC Seconds to wait at WP before preceeding to next WP
headingFIELD_SEMANTIC_HEADING Vehicle heading at the WP

Vehicle turn types

NameValue
stop_and_turn TURN_TYPE_STOP_AND_TURN
straight TURN_TYPE_STRAIGHT
spline TURN_TYPE_SPLINE
bank_turn TURN_TYPE_BANK_TURN

Panorama

Mission item ID: "panorama"

Description: Do panorama action.

Parameters

NameTypeDescription
angleFIELD_SEMANTIC_NUMERIC Target panorama angle in a range [-2Pi, 2Pi]. If positive the rotation direction should be clockwise, if negative the rotation direction should be counter-clockwise. Set in radians.
modeFIELD_SEMANTIC_ENUM Camera mode. See Camera mode for panorama
step FIELD_SEMANTIC_NUMERIC Absolute value of a step angle in case of a discrete shooting. Zero stands for a continuous rotation. Set in radians.
delayFIELD_SEMANTIC_NUMERIC Wait time in seconds for each step.
speedFIELD_SEMANTIC_NUMERIC Angular speed in rad/sec.

Camera mode for panorama

NameValueDescription
photo PANORAMA_MODE_PHOTO Take a photo on each step
video PANORAMA_MODE_VIDEO Do not stop on each step

Set payload attitude

Mission item ID: "payload_control"

Description: Move payload to given angles and zoom level. This is replacement of previous MAV_CMD_DO_PAYLOAD_CONTROL command.

Parameters

NameTypeDescription
tiltFIELD_SEMANTIC_PITCH Camera tilt relative to vehicle horizontal plane. Positive is up.
rollFIELD_SEMANTIC_ROLL Camera roll relative to vehicle horizontal plane. Roll right is positive.
yawFIELD_SEMANTIC_YAW Camera way angle relative to vehicle nose. Positive is right.
zoom_levelFIELD_SEMANTIC_NUMERIC Device specific zoom value.

Repeat Servo

Mission item ID: "repeat_servo"

Description: Move servo to given position and back the specified amount of times. Set servo to given pwm, wait for delay, set servo to default position, wait for delay.
Repeat count sets how many times to execute the above sequence. It means that after sequence finishes servo is left at default position. Deafult position is autopilot specific and cannot be specified here.

Parameters

NameTypeDescription
servo_idFIELD_SEMANTIC_NUMERIC Vehicle specific servo ID
pwmFIELD_SEMANTIC_NUMERIC PWM rate in microseconds. Typical range is 1100..1900
delayFIELD_SEMANTIC_NUMERIC Delay in seconds
countFIELD_SEMANTIC_NUMERIC How many times to repeat the sequence

Return to Home

Command ID: "return_to_home"

Description: Return to Home position.

There are no parameters for this command.

Select camera as video source

Command ID: "select_as_video_source"

Description: Select this camera as source for video feed. Each camera which can be used as video source should register this command.

There are no parameters for this command.

Set Fence

Command ID: "set_fence"

Description: Create cylindrical fence around Home Location. RTH will be triggered if vehicle tries to leave specified limits.

Parameters

NameTypeDescription
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL Fence altitude in meters
altitude_originFIELD_SEMANTIC_ALTITUDE_AMSL Altitude origin in meters AMSL. Typically this should be the HL altitude.
radiusFIELD_SEMANTIC_NUMERIC FEnce radius in meters. Max ground distance from Home Location

Set Gear State

Command ID: "set_gear_state"

Description: Retract or release gear

Parameters

NameTypeDescription
releaseFIELD_SEMANTIC_BOOL true - release gear, false - retract gear

Heading

Mission item ID: "set_heading"

Description: Change the heading of vehicle. This makes sense only for copter style vehicles when heading does not specify direction of flight.

IMPORTANT: "heading" mission item overrides any heading changes which are implicitly specified by payload control mission items in case payload yaw is controlled by vehicle heading.

Parameters

NameTypeDescription
headingFIELD_SEMANTIC_HEADING Heading angle in radians from North

Set home position

Mission item ID: "set_home"

Description: Specify home position of the vehicle. This is the location the vehicle will return on Return_To_Home command or in case of failsafe event and when failsafe is set to return to home.

Parameters

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL Home position altitude
ground_elevationFIELD_SEMANTIC_GROUND_ELEVATION Ground elevation at home position (optional)

List of supported payload mission items with detailed description of each item in the following sections.

Set vehicle parameter

Mission item ID: "set_parameter"

Description: Set vehicle parameters.

Supported FC parameters:

NameTypeDescription
landing_flare_altitude FIELD_SEMANTIC_NUMERIC
landing_flare_time FIELD_SEMANTIC_NUMERIC
min_landing_pitch FIELD_SEMANTIC_NUMERIC
landing_flare_damp FIELD_SEMANTIC_NUMERIC
landing_approach_airspeed FIELD_SEMANTIC_NUMERIC
landing_speed_weighting FIELD_SEMANTIC_NUMERIC
max_auto_flight_pitch FIELD_SEMANTIC_NUMERIC
max_pitch FIELD_SEMANTIC_NUMERIC
min_throttle FIELD_SEMANTIC_NUMERIC
landing_sink_rate FIELD_SEMANTIC_NUMERIC
landing_rangefinder_enabled FIELD_SEMANTIC_NUMERIC
min_rangefinder_distance FIELD_SEMANTIC_NUMERIC

Supported ADSB parameters:

NameTypeDescription
adsb_icao FIELD_SEMANTIC_NUMERIC 24 bit integer
adsb_registration FIELD_SEMANTIC_STRING
adsb_flight_id FIELD_SEMANTIC_STRING
adsb_squawk FIELD_SEMANTIC_NUMERIC 12 bit integer

Point Of Interest

Mission item ID: "set_poi"

Description: Set Point Of Interest.

Parameters

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL Altitude AMSL
activeFIELD_SEMANTIC_BOOL true: start poi, false: end poi action.

Set Position Offset

Command ID: "set_position_offset"

Description: Issue vehicle to change it position relatively to current position in body frame.

Parameters

NameTypeDescription
xFIELD_SEMANTIC_NUMERIC offset in X-axis in meters (positive - forward)
yFIELD_SEMANTIC_NUMERIC offset in Y-axis in meters (positive - right)
zFIELD_SEMANTIC_NUMERIC offset in Z-axis in meters (positive - down)

Set Relative Heading

Command ID: "set_relative_heading"

Description: Issue vehicle to change it heading relatively to current heading.

Parameters

NameTypeDescription
relative_headingFIELD_SEMANTIC_NUMERIC turning around Z-Axis in radians relative to current heading (positive - CW)

Set Servo

Mission item ID: "set_servo"

Description: Move servo to given position and hold.

Parameters

NameTypeDescription
servo_idFIELD_SEMANTIC_NUMERIC Vehicle specific servo ID
pwmFIELD_SEMANTIC_NUMERIC PWM rate in microseconds. Typical range is 1100..1900

Set Speed

Mission item ID: "set_speed"

Description: Set the maximum ground speed which will be used by vehicle from now on. This is the horizontal component of speed.

Parameters

NameTypeDescription
ground_speedFIELD_SEMANTIC_GROUND_SPEED Ground speed in m/s
vertical_speedFIELD_SEMANTIC_VERTICAL_SPEED Climb speed in m/s

Set Tension

Command ID: "set_tension"

Description: Set tension value for the winch in newtons

Parameters

NameTypeDescription
tensionFIELD_SEMANTIC_NUMERIC tension value

Takeoff

Command ID: "takeoff_command"

Description: Takoff from current position

Parameters

NameTypeDescription
relative_altitudeFIELD_SEMANTIC_ALTITUDE_RAW, META_VALUE_NA relative altitude for takeoff

Takeoff position

Mission item ID: "takeoff_mission"

Description: Specify takeoff position of the vehicle.

Parameters

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL Takeoff target altitude. Vehicle will ascentd to this altitude before proceeding to next WP.
climb_rateFIELD_SEMANTIC_VERTICAL_SPEED Climb speed in m/s
ground_elevationFIELD_SEMANTIC_GROUND_ELEVATION Ground elevation at takeoff position (optional)
acceptance_radiusFIELD_SEMANTIC_ACCEPTANCE_RADIUS When the sphere with the radius centered at the target position is hit by the vehicle the target position is considered reached.
headingFIELD_SEMANTIC_HEADING Vehicle heading at the WP

Trigger sensor calibration

Mission item ID: "trigger_calibration"

Description: Starts vehicle sensor calibration sequence. Vehicle must be stationary in on the ground, disarmed.

Wait

Mission item ID: "wait"

Description: Wait for given number of seconds in current position before continuing with next mission item.

Parameters

NameTypeDescription
timeFIELD_SEMANTIC_NUMERIC Number of seconds to wait.

Waypoint command

Command ID: "waypoint"

Description: Specifies the single waypoint. Used while vehicle is in Click&Go control mode.

Supported parameters:

NameTypeDescription
latitudeFIELD_SEMANTIC_LATITUDE Geodetic latitude
longitudeFIELD_SEMANTIC_LONGITUDE Geodetic longitude
altitude_amslFIELD_SEMANTIC_ALTITUDE_AMSL
altitude_origin FIELD_SEMANTIC_ALTITUDE_AMSL Altitude origin of the vehicle
ground_speedFIELD_SEMANTIC_GROUND_SPEED Ground speed in m/s
vertical_speedFIELD_SEMANTIC_VERTICAL_SPEED Climb speed in m/s
acceptance_radiusFIELD_SEMANTIC_ACCEPTANCE_RADIUS When the sphere with the radius centered at the target position is hit by the vehicle the target position is considered reached.
headingFIELD_SEMANTIC_HEADING Vehicle heading at the WP