TalonFXSSimState.hpp

Go to the documentation of this file.

/*
 * Copyright (C) Cross The Road Electronics.  All rights reserved.
 * License information can be found in CTRE_LICENSE.txt
 * For support and suggestions contact support@ctr-electronics.com or file
 * an issue tracker at https://github.com/CrossTheRoadElec/Phoenix-Releases
 */
#pragma once
 
#include "ctre/phoenix/StatusCodes.h"
#include "ctre/phoenix6/sim/ChassisReference.hpp"
#include <wpi/units/angle.hpp>
#include <wpi/units/angular_acceleration.hpp>
#include <wpi/units/angular_velocity.hpp>
#include <wpi/units/current.hpp>
#include <wpi/units/voltage.hpp>
 
namespace ctre {
namespace phoenix6 {
 
namespace hardware {
namespace core {
    /* forward proto */
    class CoreTalonFXS;
}
}
 
namespace sim {
 
    /**
     * \brief Class to control the state of a simulated hardware#TalonFXS.
     *
     * For simulated PID control and current limits to behave correctly,
     * #SetRawRotorPosition and #SetRotorVelocity must be updated
     * periodically. This is typically done by sending the motor output from
     * #GetMotorVoltage() or #GetTorqueCurrent() to a physics simulator
     * (such as WPILib's `DCMotorSim`), which then calculates the new motor
     * position and velocity.
     */
    class TalonFXSSimState
    {
    private:
        int _id;
 
    public:
        /**
         * \brief The orientation of the motor attached to the TalonFXS
         * relative to the robot chassis. This include the Commutation
         * sensor source.
         *
         * This value should not be changed based on the TalonFXS invert.
         * Rather, this value should be changed when the mechanical linkage
         * between the motor and the robot changes.
         */
        ChassisReference MotorOrientation;
 
        /**
         * \brief The orientation of an external sensor attached to the TalonFXS
         * relative to the robot chassis. This does NOT include the Commutation
         * sensor source.
         *
         * This value should not be changed based on the TalonFXS invert.
         * Rather, this value should be changed when the mechanical linkage
         * between the external sensor and the robot changes.
         */
        ChassisReference ExtSensorOrientation;
        /**
         * \brief The offset of an absolute external sensor attached to the Talon FXS 
         * relative to the robot chassis, in rotations. This offset is subtracted
         * from the Pulse Width position, allowing for a non-zero sensor offset
         * config to behave correctly in simulation.
         *
         * This value should not be changed after initialization unless the
         * mechanical linkage between the external sensor and the robot changes.
         */
        wpi::units::turn_t PulseWidthSensorOffset = 0_tr;
        /**
         * \brief The number of quadrature edges per sensor rotation for an
         * external quadrature sensor attached to the TalonFXS.
         */
        int QuadratureEdgesPerRotation = 4096;
 
        /**
         * \brief Creates an object to control the state of the given hardware#TalonFXS.
         *
         * \details This constructor defaults to a counter-clockwise positive motor and eternal
         *          sensor orientation relative to the robot chassis. Note the recommended method
         *          of accessing simulation features is to use hardware#TalonFXS#GetSimState.
         *
         * \param device Device to which this simulation state is attached
         */
        TalonFXSSimState(hardware::core::CoreTalonFXS const &device) :
            TalonFXSSimState{
                device,
                ChassisReference::CounterClockwise_Positive,
                ChassisReference::CounterClockwise_Positive
            }
        {}
        /**
         * \brief Creates an object to control the state of the given hardware#TalonFXS.
         *
         * \details Note the recommended method of accessing simulation features is to
         *          use hardware#TalonFXS#GetSimState.
         *
         * \param device Device to which this simulation state is attached
         * \param motorOrientation Orientation of the motor (and commutation sensor) relative to the robot chassis
         * \param extSensorOrientation Orientation of the external sensor relative to the robot chassis
         */
        TalonFXSSimState(
            hardware::core::CoreTalonFXS const &device,
            ChassisReference motorOrientation,
            ChassisReference extSensorOrientation
        );
        /* disallow copy, allow move */
        TalonFXSSimState(TalonFXSSimState const &) = delete;
        TalonFXSSimState(TalonFXSSimState &&) = default;
        TalonFXSSimState &operator=(TalonFXSSimState const &) = delete;
        TalonFXSSimState &operator=(TalonFXSSimState &&) = default;
 
        /**
         * \brief Gets the last status code generated by a simulation function.
         *
         * \details Not all functions return a status code but can potentially report errors.
         * This function can be used to retrieve those status codes.
         *
         * \returns Last status code generated by a simulation function
         */
        ctre::phoenix::StatusCode GetLastStatusCode() const;
 
        /**
         * \brief Gets the simulated output voltage of the motor.
         *
         * \returns Voltage applied to the motor in Volts
         */
        wpi::units::volt_t GetMotorVoltage() const;
        /**
         * \brief Gets the simulated output torque current of the motor.
         *
         * \details Phoenix 6 simulation automatically calculates current.
         * 
         * \returns Torque current applied to the motor in Amperes
         */
        wpi::units::ampere_t GetTorqueCurrent() const;
        /**
         * \brief Gets the simulated supply current of the TalonFXS.
         *
         * \details Phoenix 6 simulation automatically calculates current.
         *
         * \returns Supply current of the TalonFXS in Amperes
         */
        wpi::units::ampere_t GetSupplyCurrent() const;
        /**
         * \brief Gets the simulated analog voltage of the TalonFXS.
         *
         * \returns Voltage of the simulated analog input pin on the TalonFXS.
         */
        wpi::units::volt_t GetAnalogVoltage() const;
        /**
         * \brief Sets the simulated supply voltage of the TalonFXS.
         *
         * \details The minimum allowed supply voltage is 4 V - values below this
         * will be promoted to 4 V.
         *
         * \param volts The supply voltage in Volts
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetSupplyVoltage(wpi::units::volt_t volts);
 
        /**
         * \brief Sets the simulated forward limit switch of the TalonFXS.
         *
         * \param closed Whether the limit switch is closed
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetForwardLimit(bool closed);
        /**
         * \brief Sets the simulated reverse limit switch of the TalonFXS.
         *
         * \param closed Whether the limit switch is closed
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetReverseLimit(bool closed);
 
        /**
         * \brief Sets the simulated raw rotor position of the TalonFXS. This is the position
         * of the rotor (before gear ratio) used for the Commutation feedback source.
         *
         * Inputs to this function over time should be continuous, as user calls of hardware#TalonFXS#SetPosition will be accounted for in the callee.
         *
         * \details The TalonFXS integrates this to calculate the true reported rotor position.
         *
         * When using the WPI Sim GUI, you will notice a readonly `position` and settable `rawPositionInput`.
         * The readonly signal is the emulated position which will match self-test in Tuner and the hardware API.
         * Changes to `rawPositionInput` will be integrated into the emulated position.
         * This way a simulator can modify the position without overriding hardware API calls for home-ing the sensor.
         *
         * \param rotations The raw position in rotations
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetRawRotorPosition(wpi::units::turn_t rotations);
 
        /**
         * \brief Sets the simulated voltage of the analog input pin on the TalonFXS data port.
         * 
         * \param volts Voltage of the pin
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetAnalogVoltage(wpi::units::volt_t volts);
 
        /**
         * \brief Adds to the simulated rotor position of the TalonFXS. This adds to the position
         * of the rotor (before gear ratio) used for the Commutation feedback source.
         *
         * \param dRotations The change in position in rotations
         * \returns Status code
         */
        ctre::phoenix::StatusCode AddRotorPosition(wpi::units::turn_t dRotations);
        /**
         * \brief Sets the simulated rotor velocity of the TalonFXS. This is the velocity
         * of the rotor (before gear ratio) used for the Commutation feedback source.
         *
         * \param rps The new velocity in rotations per second
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetRotorVelocity(wpi::units::turns_per_second_t rps);
        /**
         * \brief Sets the simulated rotor acceleration of the TalonFXS. This is the acceleration
         * of the rotor (before gear ratio) used for the Commutation feedback source.
         *
         * \param rpss The new acceleration in rotations per second²
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetRotorAcceleration(wpi::units::turns_per_second_squared_t rpss);
 
        /**
         * \brief Sets the simulated raw quadrature position of the TalonFXS. This is the position
         * of an external quadrature encoder after any gear ratio between the rotor and the sensor.
         *
         * Inputs to this function over time should be continuous, as user calls of hardware#TalonFXS#SetPosition will be accounted for in the callee.
         *
         * \details The TalonFXS integrates this to calculate the true reported quadrature position.
         *
         * When using the WPI Sim GUI, you will notice a readonly `position` and settable `rawPositionInput`.
         * The readonly signal is the emulated position which will match self-test in Tuner and the hardware API.
         * Changes to `rawPositionInput` will be integrated into the emulated position.
         * This way a simulator can modify the position without overriding hardware API calls for home-ing the sensor.
         *
         * \param rotations The raw position in rotations
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetRawQuadraturePosition(wpi::units::turn_t rotations);
        /**
         * \brief Adds to the simulated quadrature position of the TalonFXS. This adds to the position
         * of an external quadrature encoder after any gear ratio between the rotor and the sensor.
         *
         * \param dRotations The change in position in rotations
         * \returns Status code
         */
        ctre::phoenix::StatusCode AddQuadraturePosition(wpi::units::turn_t dRotations);
        /**
         * \brief Sets the simulated quadrature velocity of the TalonFXS. This is the velocity
         * of an external quadrature encoder after any gear ratio between the rotor and the sensor.
         *
         * \param rps The new velocity in rotations per second
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetQuadratureVelocity(wpi::units::turns_per_second_t rps);
        /**
         * \brief Sets the simulated quadrature acceleration of the TalonFXS. This is the acceleration
         * of an external quadrature encoder after any gear ratio between the rotor and the sensor.
         *
         * \param rpss The new acceleration in rotations per second²
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetQuadratureAcceleration(wpi::units::turns_per_second_squared_t rpss);
 
        /**
         * \brief Sets the simulated pulse width position of the TalonFXS. This is the position
         * of an external PWM encoder after any gear ratio between the rotor and the sensor.
         *
         * \param rotations The new position in rotations
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetPulseWidthPosition(wpi::units::turn_t rotations);
        /**
         * \brief Sets the simulated pulse width velocity of the TalonFXS. This is the velocity
         * of an external PWM encoder after any gear ratio between the rotor and the sensor.
         *
         * \param rps The new velocity in rotations per second
         * \returns Status code
         */
        ctre::phoenix::StatusCode SetPulseWidthVelocity(wpi::units::turns_per_second_t rps);
    };
 
}
 
}
}