uavPathManager

Compute and execute a UAV autonomous mission

Since R2020b

Description

The uavPathManager System object™ computes mission parameters for an unmanned aerial vehicle (UAV) by sequentially switching between the mission points specified in the MissionData property. The MissionCmd property changes the execution order at runtime. The object supports both multirotor and fixed-wing UAV types.

To compute mission parameters:

1. Create the uavPathManager object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

pathManagerObj = uavPathManager

pathManagerObj = uavPathManager(Name,Value)

Description

pathManagerObj = uavPathManager creates a UAV path manager System object with default property values.

pathManagerObj = uavPathManager(Name,Value) creates a UAV path manager object with additional options specified by one or more Name,Value pair arguments.

Name is a property name and Value is the corresponding value. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: uavPathManager('UAVType','fixed-wing')

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

UAVType — Type of UAV

'multirotor' (default) | 'fixed-wing'

Type of UAV, specified as either 'multirotor' or 'fixed-wing'.

Data Types: string

LoiterRadius — Loiter radius for fixed-wing UAV

25 (default) | positive numeric scalar

Loiter radius for the fixed-wing UAV, specified as a positive numeric scalar in meters.

Dependencies: To enable this parameter, set the UAV type property to 'fixed-wing'.

Data Types: single | double

MissionData — UAV mission data

n-by-1 array of structures

UAV mission data, specified as an n-by-1 array of structures. n is the number of mission points. The fields of each structure are:

• mode — Mode of the mission point, specified as an 8-bit unsigned integer between 1 and 6.

• position — Position of the mission point, specified as a three-element column vector of [x;y;z]. x, y, and z is the position in north-east-down (NED) coordinates specified in meters.

• params — Parameters of the mission point, specified as a four-element column vector.

This table describes types of mode and the corresponding values for the position and params fields in a mission point structure.

mode	position	params	Mode description
uint8(1)	[x;y;z]	[p1;p2;p3;p4]	Takeoff — Take off from the ground and travel towards the specified position
uint8(2)	[x;y;z]	[yaw;radius;p3;p4] yaw — Yaw angle in radians in the range [-pi, pi] radius — Transition radius in meters	Waypoint — Navigate to waypoint
uint8(3)	[x;y;z] x, y, and z is the center of the circular orbit in NED coordinates specified in meters	[radius;turnDir;numTurns;p4] radius — Radius of the orbit in meters turnDir — Turn direction, specified as one of these: 1 — Clockwise turn —1 — Counter-clockwise turn 0 — Automatic selection of turn direction numTurns — Number of turns	Orbit — Orbit along the circumference of a circle defined by the parameters
uint8(4)	[x;y;z]	[p1;p2;p3;p4]	Land — Land at the specified position
uint8(5)	[x;y;z] The launch position is specified in the Home property	[p1;p2;p3;p4]	RTL — Return to launch position
uint8(6)	[x;y;z]	[p1;p2;p3;p4] p1, p2, p3, and p4 are user-specified parameters corresponding to the custom mission point	Custom — Custom mission point

Note

p1, p2, p3, and p4 are user-specified parameters.

Example: [struct('mode',uint8(1),'position',[0;0;100],'params',[0;0;0;0])]

Tunable: Yes

IsModeDone — Determine if mission point was executed

false (default) | true

Determine if the mission point was executed, specified as true (1) or false (0).

Tunable: Yes

Data Types: logical

MissionCmd — Command to change mission

uint8(0) (default) | 8-bit unsigned integer between 0 and 3

Command to change mission at runtime, specified as an 8-bit unsigned integer between 0 and 3.

This table describes the possible mission commands.

Mission Command	Description
uint8(0)	Default — Execute the mission from first to the last mission point in the sequence
uint8(1)	Hold — Hold at the current mission point Loiter around the current position for fixed-wing, and hover at the current position for multirotor UAVs
uint8(2)	Repeat — Repeat the mission after reaching the last mission point
uint8(3)	RTL — Execute return to launch (RTL) mode After RTL, the mission resumes if the MissionCmd property is changed to Default or Repeat

Tunable: Yes

Data Types: uint8

Home — UAV home location

three-element column vector

UAV home location, specified as a three-element column vector of [x;y;z]. x, y, and z is the position in north-east-down (NED) coordinates specified in meters.

Tunable: Yes

Data Types: single | double

Usage

Syntax

missionParams = pathManagerObj(pose)

Description

missionParams = pathManagerObj(pose)

Input Arguments

pose — Current UAV pose

four-element column vector

Current UAV pose, specified as a four-element column vector of [x;y;z;courseAngle]. x, y, and z is the current position in north-east-down (NED) coordinates specified in meters. courseAngle specifies the course angle in radians in the range [-pi, pi].

Data Types: single | double

Output Arguments

missionParams — UAV mission parameters

2-by-1 array of structures

UAV mission parameters, returned as a 2-by-1 array of structures. The first row of the array contains the structure of the current mission point, and the second row of the array contains the structure of the previous mission point. The fields of each structure are:

• mode — Mode of the mission point, returned as an 8-bit unsigned integer between 0 and 7.

• position — Position of the mission point based on the mode, returned as a three-element column vector of [x;y;z]. x, y, and z is the position in north-east-down (NED) coordinates specified in meters.

• params — Parameters of the mission point based on the mode, returned as a four-element column vector.

At start of simulation, the previous mission point is set to the Armed mode.

struct('mode',uint8(0),'position',[x;y;z],'params',[-1;-1;-1;-1])

Note

The Armed mode cannot be configured by the user.

Set the end mission point to RTL or Land mode, else the end mission point is automatically set to Hold mode.

• Multirotor UAVs hover at the current position.

  struct('mode',uint8(7),'position',[x;y;z],'params',[-1;-1;-1;-1])

• Fixed-wing UAVs loiter around the current position.

  struct('mode',uint8(7),'position',[x;y;z],'params',[radius;turnDir;-1;-1])

Note

The Hold mode cannot be configured by the user.

This table describes the output mission parameters depending on the mission mode.

Current Mission Mode	Output Mission Parameters
	Mission Points	mode	position	params
Takeoff	Row 1: Current	uint8(1)	[x;y;z]	[p1;p2;p3;p4]
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point
Waypoint	Row 1: Current	uint8(2)	[x;y;z]	[yaw;radius;p3;p4] yaw — Yaw angle in radians in the range [-pi, pi] radius — Transition radius in meters
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	[yaw;radius;p3;p4] if the previous mission point was Takeoff [courseAngle;25;p3;p4] otherwise courseAngle — Angle of the line segment between the previous and the current position, specified in radians in the range [-pi, pi]
Orbit	Row 1: Current	uint8(3)	[x;y;z] x, y, and z is the center of the circular orbit in NED coordinates specified in meters	[radius;turnDir;numTurns;p4] radius — Radius of the orbit in meters turnDir — Turn direction, specified as one of these: 1 — Clockwise turn —1 — Counter-clockwise turn 0 — Automatic selection of turn direction numTurns — Number of turns
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point
Land	Row 1: Current	uint8(4)	[x;y;z]	[p1;p2;p3;p4]
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point
RTL	Row 1: Current	uint8(5)	[x;y;z] The launch position is specified in the Home property	[p1;p2;p3;p4]
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point
Custom	Row 1: Current	uint8(6)	[x;y;z]	[p1;p2;p3;p4] p1, p2, p3, and p4 are user-specified parameters corresponding to the custom mission point
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point

Note

p1, p2, p3, and p4 are user-specified parameters.

This table describes the output mission parameters when the input to the MissionCmd property is set to Hold mode.

UAV Type	Output Mission Parameters
	Mission Points	mode	position	params
Multirotor	Row 1: Current	uint8(7)	[x;y;z]	[-1;-1;-1;-1]
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point
Fixed-Wing	Row 1: Current	uint8(7)	[x;y;z] x, y, and z is the center of the circular orbit in NED coordinates specified in meters	[radius;turnDir;-1;-1] radius — Loiter radius is specified in the LoiterRadius property turnDir — Turn direction is specified as 0 for automatic selection of turn direction
	Row 2: Previous	mode of the previous mission point	position of the previous mission point	params of the previous mission point

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Version History

Introduced in R2020b