Main Content

uavPathManager

Compute and execute a UAV autonomous mission

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

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

expand all

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.

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

Data Types: string

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

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.

modepositionparamsMode description
uint8(1)[x;y;z][0;0;0;0]

Takeoff — Take off from the ground and travel towards the specified position

uint8(2)[x;y;z]

[yaw;radius;0;0]

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;0]

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][0;0;0;0]

Land — Land at the specified position

uint8(5)

[x;y;z]

The launch position is specified in the Home property

[0;0;0;0]

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

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

Tunable: Yes

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

Tunable: Yes

Data Types: logical

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 CommandDescription
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

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

Description

missionParams = pathManagerObj(pose)

Input Arguments

expand all

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

expand all

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 ModeOutput Mission Parameters
Mission Pointsmodepositionparams

Takeoff

Row 1: Current

uint8(1)[x;y;z][0;0;0;0]

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;0;0]

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;0;0] if the previous mission point was Takeoff

  • [courseAngle;radius;0;0] 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;0]

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][0;0;0;0]

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

[0;0;0;0]

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

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

UAV TypeOutput Mission Parameters
Mission Pointsmodepositionparams

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)

expand all

stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
Introduced in R2020b