YAMS
Yet Another Mechanism System
Loading...
Searching...
No Matches
yams::math::ADRCConfig Class Reference

#include <ADRCConfig.hpp>

Public Types

enum class  SystemOrder {
  FIRST = 1 , FLYWHEEL = 1 , SECOND = 2 , THIRD = 3 ,
  FOURTH = 4 , POSITION = 100 , ARM = 100 , PIVOT = 100 ,
  ELEVATOR = 101
}

Public Member Functions

 ADRCConfig ()
 ADRCConfig (const ADRCConfig &other)
ADRCConfig & operator= (const ADRCConfig &other)
 ~ADRCConfig ()
ADRCConfig & WithSystemOrder (SystemOrder order)
ADRCConfig & WithSettlingTime (wpi::units::second_t settlingTime)
ADRCConfig & WithBandwidthScale (double bandwidthScale)
ADRCConfig & WithB0 (double b0)
ADRCConfig & WithInputDelay (wpi::units::second_t inputDelay)
ADRCConfig & WithCascaded (bool cascaded)
ADRCConfig & WithBackEmfModel (bool backEmfModel)
ADRCConfig & WithTrackingDifferentiator (TrackingDifferentiator::Method method, std::vector< double > params={})
ADRCConfig & WithoutTrackingDifferentiator ()
std::optional< SystemOrder > GetSystemOrder () const
std::optional< wpi::units::second_t > GetSettlingTime () const
std::optional< double > GetBandwidthScale () const
std::optional< double > GetB0 () const
std::optional< wpi::units::second_t > GetInputDelay () const
bool IsCascaded () const
bool IsBackEmfModeled () const
std::optional< wpi::units::second_t > GetModeledBackEmfTimeConstant () const
std::optional< TrackingDifferentiator::Method > GetTdMethod () const
std::vector< double > GetTdParams () const
double ResolveB0 (const wpi::math::DCMotor &motor, const motorcontrollers::SmartMotorControllerConfig &config) const
void ReportRejected (std::optional< std::string > reason)

Static Public Member Functions

static constexpr int GetOrder (SystemOrder order)
static constexpr bool IsChosenWhenBuilt (SystemOrder order)
static constexpr bool RequiresLinearClosedLoop (SystemOrder order)
static ADRCController BuildController (const std::shared_ptr< ADRCConfig > &self, const wpi::math::DCMotor &motor, const motorcontrollers::SmartMotorControllerConfig &config, wpi::units::second_t period)

Static Public Attributes

static constexpr double kSpeedPerVoltTimeConstantPeriods = 2.0
static constexpr wpi::units::second_t kDefaultSettlingTime {0.2}
static constexpr double kDefaultBandwidthScale {1.0}
static constexpr wpi::units::second_t kDefaultInputDelay {0.0}

Friends

class ADRCController

Detailed Description

Configuration for an active disturbance rejection controller.

Written by FRC Team 8331, who contributed active disturbance rejection control to YAMS.

An active disturbance rejection controller lumps everything the mechanism model does not capture (friction, back-EMF, game-piece loads, dropped battery voltage, unmodeled dynamics) into a single "total disturbance" and estimates it live with an extended state observer. The estimate is cancelled out of the control law, so the closed loop behaves like a clean chain of integrators that settles in the time you ask for. There is no proportional, integral or derivative gain to tune: you describe the plant (order and input gain) and the response you want (settling time), and the controller derives its own gains.

This is the drop-in equivalent of a PID: pass it to SmartMotorControllerConfig::WithADRCController and the motor controller runs the controller on its closed loop thread.

config.WithADRCController(yams::math::ADRCConfig{}
.WithSettlingTime(200_ms));
Definition ADRCConfig.hpp:82
ADRCConfig & WithSystemOrder(SystemOrder order)
@ FIRST
First order: the loop commands and measures velocity, such as a flywheel.
Definition ADRCConfig.hpp:90
ADRCConfig & WithSettlingTime(wpi::units::second_t settlingTime)

The output limit and ramp come from the motor config, as for every closed loop controller: WithClosedLoopMaxVoltage limits the output, and WithClosedLoopRampRate limits how quickly it changes.

Every value starts empty. The getters return that empty optional, and the controller fills it with the default documented on the With method. The system order has no default: BuildController throws until it is set.

The With methods only accept values the controller can use: anything else throws std::invalid_argument and leaves the config as it was. The controller reads its settings from this config every step instead of keeping copies, so the config never holds a value it cannot run.

Once a controller is built from it, the config also holds what the controller needs that the settings do not give: the control period, the b0 used while it is unset, and the gains worked out from them. The config works the gains out again whenever its settling time, bandwidth scale or b0 changes, so every live-tunable value takes effect on the controller's next step. The system order, input delay and tracking differentiator only take effect when a controller is built, and a built config refuses a different system order.

Copies are deep: a copy has its own settings, built values and gains, and raises its own alerts. Every method is safe to call while the controller's thread runs.

Member Enumeration Documentation

◆ SystemOrder

Plant order: how many integrators sit between the motor voltage and the measured output. Velocity loops on a DC motor are FIRST. For a position loop, POSITION and its aliases choose between first and second order when the controller is built, from the motor, gearing and inertia.

Enumerator
FIRST 

First order: the loop commands and measures velocity, such as a flywheel.

FLYWHEEL 

A flywheel's velocity loop; the same as FIRST.

SECOND 

Second order: a position loop whose inertia sets how fast it moves. POSITION chooses for you.

THIRD 

Third order: the measurement sits two integrations behind the voltage. Rare.

FOURTH 

Fourth order: three integrations between the voltage and the measurement. Rare.

POSITION 

A position loop whose form is chosen when the controller is built from a motor config, from the motor's back-EMF time constant at the mechanism, J * R / (G^2 * Kt * Ke). Under kSpeedPerVoltTimeConstantPeriods control periods, the motor's back-EMF, more than the mechanism's inertia, sets how fast it moves, so its position is first order with its speed per volt as b0. Otherwise it is second order with its acceleration per volt as b0. Both are in the loop's units. It needs the mechanism's moment of inertia.

ARM 

An arm's position loop; the same as POSITION.

PIVOT 

A pivot's or turret's position loop; the same as POSITION.

ELEVATOR 

An elevator's position loop, in a linear closed loop: POSITION in meters. Without a moment of inertia, it is first order with its speed per volt as b0, since an elevator's speed is nearly always set by its motor's back-EMF. The motor config must use a linear closed loop.

Constructor & Destructor Documentation

◆ ADRCConfig() [1/2]

yams::math::ADRCConfig::ADRCConfig ( )

Create a configuration. It belongs to the motor controller it is given to, whose telemetry name its errors use.

◆ ADRCConfig() [2/2]

yams::math::ADRCConfig::ADRCConfig ( const ADRCConfig & other)

Copy a configuration deeply: its settings, the values given when a controller was built from it, and its own copy of the gains. The copy raises its own alerts.

Parameters
otherConfiguration to copy.

◆ ~ADRCConfig()

yams::math::ADRCConfig::~ADRCConfig ( )

Member Function Documentation

◆ BuildController()

ADRCController yams::math::ADRCConfig::BuildController ( const std::shared_ptr< ADRCConfig > & self,
const wpi::math::DCMotor & motor,
const motorcontrollers::SmartMotorControllerConfig & config,
wpi::units::second_t period )
static

Build an initialized controller that reads this config, giving the config the period and b0 it needs. The controller does not limit or ramp its output: the motor controller does, with WithClosedLoopMaxVoltage and WithClosedLoopRampRate. The motor controller calls this; you only need it to use the controller yourself.

Parameters
selfThis config, shared with the controller, which reads it every step.
motorMotor model, for deriving b0 and the nominal voltage fallback.
configMotor config with the gearing, inertia, circumference and closed loop voltage limit.
periodClosed loop control period.
Returns
The initialized controller.
Exceptions
exceptions::SmartMotorControllerConfigurationExceptionif the order is missing or b0 cannot be derived.
std::invalid_argumentif the controller rejects the derived b0, the motor config's limit or the tracking differentiator.

◆ GetB0()

std::optional< double > yams::math::ADRCConfig::GetB0 ( ) const
Returns
The input gain, or empty when it should be derived.

◆ GetBandwidthScale()

std::optional< double > yams::math::ADRCConfig::GetBandwidthScale ( ) const
Returns
The bandwidth scale, or empty for kDefaultBandwidthScale.

◆ GetInputDelay()

std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetInputDelay ( ) const
Returns
The input delay, or empty for kDefaultInputDelay.

◆ GetModeledBackEmfTimeConstant()

std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetModeledBackEmfTimeConstant ( ) const
Returns
The back-EMF time constant the built controller's observer models, or empty when the back-EMF is left in the disturbance: it was turned off, the plant does not model it, or no controller has been built.

◆ GetOrder()

constexpr int yams::math::ADRCConfig::GetOrder ( SystemOrder order)
inlinestaticconstexpr

Get a system order as an integer.

Parameters
orderSystem order.
Returns
Plant order, 1 through 4, or 0 for a position loop whose order is chosen when the controller is built.

◆ GetSettlingTime()

std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetSettlingTime ( ) const
Returns
The settling time, or empty for kDefaultSettlingTime.

◆ GetSystemOrder()

std::optional< SystemOrder > yams::math::ADRCConfig::GetSystemOrder ( ) const
Returns
The plant order, or empty when it has not been set.

◆ GetTdMethod()

std::optional< TrackingDifferentiator::Method > yams::math::ADRCConfig::GetTdMethod ( ) const
Returns
The tracking differentiator method, or empty when it is off.

◆ GetTdParams()

std::vector< double > yams::math::ADRCConfig::GetTdParams ( ) const
Returns
The tracking differentiator parameters; empty for the method defaults.

◆ IsBackEmfModeled()

bool yams::math::ADRCConfig::IsBackEmfModeled ( ) const
Returns
Whether the observer may model the motor's back-EMF: true unless it was turned off.

◆ IsCascaded()

bool yams::math::ADRCConfig::IsCascaded ( ) const
Returns
Whether the cascaded observer is on.

◆ IsChosenWhenBuilt()

constexpr bool yams::math::ADRCConfig::IsChosenWhenBuilt ( SystemOrder order)
inlinestaticconstexpr

Whether the order and the kind of b0 are chosen when the controller is built.

Parameters
orderSystem order.
Returns
True for POSITION, ARM, PIVOT and ELEVATOR.

◆ operator=()

ADRCConfig & yams::math::ADRCConfig::operator= ( const ADRCConfig & other)

Copy a configuration deeply, as the copy constructor does.

Parameters
otherConfiguration to copy.
Returns
This config.

◆ ReportRejected()

void yams::math::ADRCConfig::ReportRejected ( std::optional< std::string > reason)

Report a value this config refused, as live tuning does when a tuned value throws. The alert lives on the config, so it outlasts a controller rebuilt from it.

Parameters
reasonWhy the value was refused, or empty once a tuned value is accepted.

◆ RequiresLinearClosedLoop()

constexpr bool yams::math::ADRCConfig::RequiresLinearClosedLoop ( SystemOrder order)
inlinestaticconstexpr

Whether the motor config must use a linear closed loop.

Parameters
orderSystem order.
Returns
True for ELEVATOR.

◆ ResolveB0()

double yams::math::ADRCConfig::ResolveB0 ( const wpi::math::DCMotor & motor,
const motorcontrollers::SmartMotorControllerConfig & config ) const

Resolve the input gain the controller will use: the one set, or one derived in the loop's units. For an ELEVATOR it is the speed per volt, from the motor, gearing and mechanism circumference. Otherwise it is the acceleration per volt, from the motor, the gearing and the mechanism's moment of inertia, only when the mechanism set that inertia.

Parameters
motorMotor model.
configMotor config with the gearing, inertia and circumference.
Returns
Input gain in mechanism units per second squared per volt.
Exceptions
exceptions::SmartMotorControllerConfigurationExceptionif the order is ELEVATOR and the closed loop is not linear, or b0 is not set and cannot be derived.

◆ WithB0()

ADRCConfig & yams::math::ADRCConfig::WithB0 ( double b0)

Set the input gain instead of deriving it.

Parameters
b0Input gain in mechanism units per second squared per volt; must be finite and non-zero.
Returns
This config for chaining.
Exceptions
std::invalid_argumentif b0 is not finite or is zero.

◆ WithBackEmfModel()

ADRCConfig & yams::math::ADRCConfig::WithBackEmfModel ( bool backEmfModel)

Choose whether the observer models the motor's back-EMF. On by default.

A motor's back-EMF brakes the mechanism in proportion to its speed. Left out of the observer's model, it is lumped into the disturbance the observer estimates, which then changes as fast as the speed does: the observer lags it whenever the mechanism speeds up or slows down, and a mechanism following a motion profile overshoots. Modeled, the disturbance only holds what the model misses, such as gravity and friction.

It applies to a position loop that chose second order when built from a motor config (see SystemOrder::POSITION), whose back-EMF time constant comes from the motor, the gearing and the moment of inertia. A first order position loop's b0, a speed per volt, already includes the back-EMF. A FLYWHEEL still lumps it into the disturbance. FIRST to FOURTH leave the model to you. To cancel the modeled back-EMF, the control law pushes with the observer's estimated speed, which cancels the damping the back-EMF gives the motor, so a loop whose timing is far from what it was built for can be better off without it. Changing it on a built config works the gains out again.

Parameters
backEmfModelWhether to model the back-EMF.
Returns
This config for chaining.

◆ WithBandwidthScale()

ADRCConfig & yams::math::ADRCConfig::WithBandwidthScale ( double bandwidthScale)

Set the closed-loop bandwidth scale. Defaults to kDefaultBandwidthScale.

Parameters
bandwidthScaleBandwidth scale; must be finite and positive. Larger is more aggressive.
Returns
This config for chaining.
Exceptions
std::invalid_argumentif the bandwidth scale is not finite and positive.

◆ WithCascaded()

ADRCConfig & yams::math::ADRCConfig::WithCascaded ( bool cascaded)

Select the cascaded extended state observer: a second observer, fed the first one's estimate of the measurement, supplies the disturbance the control law cancels. Off by default.

Parameters
cascadedWhether to run the cascaded observer.
Returns
This config for chaining.

◆ WithInputDelay()

ADRCConfig & yams::math::ADRCConfig::WithInputDelay ( wpi::units::second_t inputDelay)

Set the input delay, rounded to whole control periods. Defaults to kDefaultInputDelay, which turns it off.

Parameters
inputDelayInput delay; must be finite and not negative.
Returns
This config for chaining.
Exceptions
std::invalid_argumentif the delay is not finite or is negative.

◆ WithoutTrackingDifferentiator()

ADRCConfig & yams::math::ADRCConfig::WithoutTrackingDifferentiator ( )

Turn the tracking differentiator off.

Returns
This config for chaining.

◆ WithSettlingTime()

ADRCConfig & yams::math::ADRCConfig::WithSettlingTime ( wpi::units::second_t settlingTime)

Set the desired closed-loop settling time. Defaults to kDefaultSettlingTime.

Parameters
settlingTimeSettling time; must be finite and positive.
Returns
This config for chaining.
Exceptions
std::invalid_argumentif the settling time is not finite and positive.

◆ WithSystemOrder()

ADRCConfig & yams::math::ADRCConfig::WithSystemOrder ( SystemOrder order)

Set the plant order. There is no default; the controller cannot be built without it.

Parameters
orderPlant order.
Returns
This config for chaining.
Exceptions
std::logic_errorif a controller was built from this config with a different order.

◆ WithTrackingDifferentiator()

ADRCConfig & yams::math::ADRCConfig::WithTrackingDifferentiator ( TrackingDifferentiator::Method method,
std::vector< double > params = {} )

Smooth the reference with a tracking differentiator. Off by default. Its parameters are checked when the controller is built, as some depend on the period. A motion profile on the motor config also shapes the setpoint, so a config with both is refused when the controller is built.

Parameters
methodDifferentiation method.
paramsMethod parameters in order; empty for the method defaults.
Returns
This config for chaining.

◆ ADRCController

friend class ADRCController
friend

Member Data Documentation

◆ kDefaultBandwidthScale

double yams::math::ADRCConfig::kDefaultBandwidthScale {1.0}
staticconstexpr

Bandwidth scale used when none is set.

◆ kDefaultInputDelay

wpi::units::second_t yams::math::ADRCConfig::kDefaultInputDelay {0.0}
staticconstexpr

Input delay used when none is set; zero turns it off.

◆ kDefaultSettlingTime

wpi::units::second_t yams::math::ADRCConfig::kDefaultSettlingTime {0.2}
staticconstexpr

Closed-loop settling time used when none is set.

◆ kSpeedPerVoltTimeConstantPeriods

double yams::math::ADRCConfig::kSpeedPerVoltTimeConstantPeriods = 2.0
staticconstexpr

A position loop's back-EMF time constant below which it is first order with its speed per volt, in periods.


The documentation for this class was generated from the following file:
  • /home/runner/work/YAMS/YAMS/yams/cpp/include/yams/math/ADRCConfig.hpp