|
YAMS
Yet Another Mechanism System
|
#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 |
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.
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.
|
strong |
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.
| yams::math::ADRCConfig::ADRCConfig | ( | ) |
Create a configuration. It belongs to the motor controller it is given to, whose telemetry name its errors use.
| 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.
| other | Configuration to copy. |
| yams::math::ADRCConfig::~ADRCConfig | ( | ) |
|
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.
| self | This config, shared with the controller, which reads it every step. |
| motor | Motor model, for deriving b0 and the nominal voltage fallback. |
| config | Motor config with the gearing, inertia, circumference and closed loop voltage limit. |
| period | Closed loop control period. |
| exceptions::SmartMotorControllerConfigurationException | if the order is missing or b0 cannot be derived. |
| std::invalid_argument | if the controller rejects the derived b0, the motor config's limit or the tracking differentiator. |
| std::optional< double > yams::math::ADRCConfig::GetB0 | ( | ) | const |
| std::optional< double > yams::math::ADRCConfig::GetBandwidthScale | ( | ) | const |
| std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetInputDelay | ( | ) | const |
| std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetModeledBackEmfTimeConstant | ( | ) | const |
|
inlinestaticconstexpr |
Get a system order as an integer.
| order | System order. |
| std::optional< wpi::units::second_t > yams::math::ADRCConfig::GetSettlingTime | ( | ) | const |
| std::optional< SystemOrder > yams::math::ADRCConfig::GetSystemOrder | ( | ) | const |
| std::optional< TrackingDifferentiator::Method > yams::math::ADRCConfig::GetTdMethod | ( | ) | const |
| std::vector< double > yams::math::ADRCConfig::GetTdParams | ( | ) | const |
| bool yams::math::ADRCConfig::IsBackEmfModeled | ( | ) | const |
| bool yams::math::ADRCConfig::IsCascaded | ( | ) | const |
|
inlinestaticconstexpr |
Whether the order and the kind of b0 are chosen when the controller is built.
| order | System order. |
| ADRCConfig & yams::math::ADRCConfig::operator= | ( | const ADRCConfig & | other | ) |
Copy a configuration deeply, as the copy constructor does.
| other | Configuration to copy. |
| 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.
| reason | Why the value was refused, or empty once a tuned value is accepted. |
|
inlinestaticconstexpr |
Whether the motor config must use a linear closed loop.
| order | System order. |
| 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.
| motor | Motor model. |
| config | Motor config with the gearing, inertia and circumference. |
| exceptions::SmartMotorControllerConfigurationException | if the order is ELEVATOR and the closed loop is not linear, or b0 is not set and cannot be derived. |
| ADRCConfig & yams::math::ADRCConfig::WithB0 | ( | double | b0 | ) |
Set the input gain instead of deriving it.
| b0 | Input gain in mechanism units per second squared per volt; must be finite and non-zero. |
| std::invalid_argument | if b0 is not finite or is zero. |
| 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.
| backEmfModel | Whether to model the back-EMF. |
| ADRCConfig & yams::math::ADRCConfig::WithBandwidthScale | ( | double | bandwidthScale | ) |
Set the closed-loop bandwidth scale. Defaults to kDefaultBandwidthScale.
| bandwidthScale | Bandwidth scale; must be finite and positive. Larger is more aggressive. |
| std::invalid_argument | if the bandwidth scale is not finite and positive. |
| 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.
| cascaded | Whether to run the cascaded observer. |
| 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.
| inputDelay | Input delay; must be finite and not negative. |
| std::invalid_argument | if the delay is not finite or is negative. |
| ADRCConfig & yams::math::ADRCConfig::WithoutTrackingDifferentiator | ( | ) |
Turn the tracking differentiator off.
| ADRCConfig & yams::math::ADRCConfig::WithSettlingTime | ( | wpi::units::second_t | settlingTime | ) |
Set the desired closed-loop settling time. Defaults to kDefaultSettlingTime.
| settlingTime | Settling time; must be finite and positive. |
| std::invalid_argument | if the settling time is not finite and positive. |
| ADRCConfig & yams::math::ADRCConfig::WithSystemOrder | ( | SystemOrder | order | ) |
Set the plant order. There is no default; the controller cannot be built without it.
| order | Plant order. |
| std::logic_error | if a controller was built from this config with a different order. |
| 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.
| method | Differentiation method. |
| params | Method parameters in order; empty for the method defaults. |
|
friend |
|
staticconstexpr |
Bandwidth scale used when none is set.
|
staticconstexpr |
Input delay used when none is set; zero turns it off.
|
staticconstexpr |
Closed-loop settling time used when none is set.
|
staticconstexpr |
A position loop's back-EMF time constant below which it is first order with its speed per volt, in periods.