uavOrbitFollower

Orbit location of interest using a UAV

Description

The uavOrbitFollower object is a 3-D path follower for unmanned aerial vehicles (UAVs) to follow circular paths that is based on a lookahead distance. Given the circle center, radius, and the pose, the orbit follower computes a desired yaw and course to follow a lookahead point on the path. The object also computes the cross-track error from the UAV pose to the path and tracks how many times the circular orbit has been completed.

Tune the lookaheadDistance input to help improve path tracking. Decreasing the distance can improve tracking, but may lead to oscillations in the path.

To orbit a location using a UAV:

1. Create the uavOrbitFollower 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

orbit = uavOrbitFollower

orbit = uavOrbitFollower(Name,Value)

Description

orbit = uavOrbitFollower returns an orbit follower object with default property values.

orbit = uavOrbitFollower(Name,Value) creates an orbit follower 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.

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.

UAV type — Type of UAV

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

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

OrbitCenter — Center of orbit

[x y z] vector

Center of orbit, specified as an [x y z] vector. [x y z] is the orbit center position in NED-coordinates (north-east-down) specified in meters.

Example: [5,5,-10]

Data Types: single | double

OrbitRadius — Radius of orbit

positive scalar

Radius of orbit, specified as a positive scalar in meters.

Example: 5

Data Types: single | double

TurnDirection — Direction of orbit

scalar

Direction of orbit, specified as a scalar. Positive values indicate a clockwise turn as viewed from above. Negative values indicate a counter-clockwise turn. A value of 0 automatically determines the value based on the input Pose.

Example: -1

Data Types: single | double

MinOrbitRadius — Minimum orbit radius

1 (default) | positive numeric scalar

Minimum orbit radius, specified as a positive numeric scalar in meters.

Data Types: single | double

MinLookaheadDistance — Minimum lookahead distance

0.1 (default) | positive numeric scalar

Minimum lookahead distance, specified as a positive numeric scalar in meters.

Data Types: single | double

Usage

Syntax

[lookaheadPoint,desiredCourse,desiredYaw,orbitRadiusFlag,lookaheadDistFlag,crossTrackError,numTurns] = orbit(currentPose,lookaheadDistance)

Description

[lookaheadPoint,desiredCourse,desiredYaw,orbitRadiusFlag,lookaheadDistFlag,crossTrackError,numTurns] = orbit(currentPose,lookaheadDistance) follows the set of waypoints specified in the waypoint follower object. The object takes the current position and lookahead distance to compute the lookahead point on the path. The desired course, yaw, and cross track error are also based on this lookahead point compared to the current position. status returns zero until the UAV has navigated all the waypoints.

Input Arguments

currentPose — Current UAV pose

[x y z course] vector

Current UAV pose, specified as a [x y z course] vector. This pose is used to calculate the lookahead point based on the input LookaheadDistance. [x y z] is the current position in meters. course is the current course in radians. The UAV course is the angle of direction of the velocity vector relative to north measured in radians.

Data Types: single | double

lookaheadDistance — Lookahead distance

positive numeric scalar

Lookahead distance along the path, specified as a positive numeric scalar in meters.

Data Types: single | double

Output Arguments

lookaheadPoint — Lookahead point on path

[x y z] position vector

Lookahead point on path, returned as an [x y z] position vector in meters.

Data Types: double

desiredCourse — Desired course

numeric scalar

Desired course, returned as numeric scalar in radians in the range of [-pi, pi]. The UAV course is the angle of direction of the velocity vector relative to north measured in radians. For fixed-wing type UAV, the values of desired course and desired yaw are equal.

Data Types: double

desiredYaw — Desired yaw

numeric scalar

Desired yaw, returned as numeric scalar in radians in the range of [-pi, pi]. The UAV yaw is the forward direction of the UAV regardless of the velocity vector relative to north measured in radians. For fixed-wing type UAV, the values of desired course and desired yaw are equal.

Data Types: double

orbitRadiusFlag — Orbit radius flag

0 (default) | 1

Orbit radius flag, returned as 0 or 1. 0 indicates orbit radius is not saturated, 1 indicates orbit radius is saturated to minimum orbit radius value specified.

Data Types: uint8

lookaheadDistFlag — Lookahead distance flag

0 (default) | 1

Lookahead distance flag, returned as 0 or 1. 0 indicates lookahead distance is not saturated, 1 indicates lookahead distance is saturated to minimum lookahead distance value specified.

Data Types: uint8

crossTrackError — Cross track error from UAV position to path

positive numeric scalar

Cross track error from UAV position to path, returned as a positive numeric scalar in meters. The error measures the perpendicular distance from the UAV position to the closest point on the path.

Data Types: double

numTurns — Number of times the UAV has completed the orbit

numeric scalar

Number of times the UAV has completed the orbit, specified as a numeric scalar. As the UAV circles the center point, this value increases or decreases based on the specified Turn Direction property. Decimal values indicate partial completion of a circle. If the UAV cross track error exceeds the lookahead distance, the number of turns is not updated.

NumTurns is reset whenever Center, Radius, or TurnDirection properties are changed.

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

Examples

Generate Control Commands for Orbit Following

This example shows how to use the uavOrbitFollower to generate course and yaw commands for orbiting a location of interest with a UAV.

Create the orbit follower. Set the center of the location of interest and the radius of orbit. Set a TurnDirection of 1 for counter-clockwise rotation around the location.

orbFollower = uavOrbitFollower;

orbFollower.OrbitCenter = [1 1 5]';
orbFollower.OrbitRadius = 2.5;
orbFollower.TurnDirection = 1;

Specify the pose of the UAV and the lookahead distance for tracking the path.

pose = [0;0;5;0];
lookaheadDistance = 2;

Call the orbFollower object with the pose and lookahead distance. The object returns a lookahead point on the path, the desired course, and yaw. You can use the desired course and yaw to generate control commands for the UAV.

[lookaheadPoint,desiredCourse,desiredYaw,~,~] = orbFollower(pose,lookaheadDistance);

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2019a