diff --git a/source/docs/networking/networking-utilities/portforwarding.rst b/source/docs/networking/networking-utilities/portforwarding.rst index 0834a785626..2f188188d15 100644 --- a/source/docs/networking/networking-utilities/portforwarding.rst +++ b/source/docs/networking/networking-utilities/portforwarding.rst @@ -6,7 +6,7 @@ This class provides an easy way to forward local ports to another host/port. Thi Forwarding a Remote Port ------------------------ -Often teams may wish to connect directly to the roboRIO for controlling their robot. The PortForwarding class (`Java `__, `C++ `__) can be used to forward the Raspberry Pi connection for usage during these times. The PortForwarding class establishes a bridge between the remote and the client. To forward a port in Java, simply do ``PortForwarder.add(int port, String remoteName, int remotePort)``. +Often teams may wish to connect directly to the roboRIO for controlling their robot. The PortForwarding class (`Java `__, `C++ `__) can be used to forward the Raspberry Pi connection for usage during these times. The PortForwarding class establishes a bridge between the remote and the client. To forward a port in Java, simply do ``PortForwarder.add(int port, String remoteName, int remotePort)``. .. tabs:: diff --git a/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst b/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst index d01d8a83194..7fbf8a9d1f7 100644 --- a/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst +++ b/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst @@ -31,7 +31,7 @@ Moreover, feedforward is a separate feature entirely from feedback, and thus has Using Feedforward Components with PID ------------------------------------- -.. note:: Since feedforward voltages are physically meaningful, it is best to use the ``setVoltage()`` (`Java `__, `C++ `__) method when applying them to motors to compensate for "voltage sag" from the battery. +.. note:: Since feedforward voltages are physically meaningful, it is best to use the ``setVoltage()`` (`Java `__, `C++ `__) method when applying them to motors to compensate for "voltage sag" from the battery. What might a more complete example of combined feedforward/PID control look like? Consider the :ref:`drive example ` from the feedforward page. We can easily modify this to include feedback control (with a ``SimpleMotorFeedforward`` component): diff --git a/source/docs/software/advanced-controls/controllers/feedforward.rst b/source/docs/software/advanced-controls/controllers/feedforward.rst index 5bb5de54437..50d21ae1d72 100644 --- a/source/docs/software/advanced-controls/controllers/feedforward.rst +++ b/source/docs/software/advanced-controls/controllers/feedforward.rst @@ -15,9 +15,9 @@ WPILib provides a number of classes to help users implement accurate feedforward WPILib currently provides the following three helper classes for feedforward control: -* `SimpleMotorFeedforward`_ (`Java `__, `C++ `__) -* `ArmFeedforward`_ (`Java `__, `C++ `__) -* `ElevatorFeedforward`_ (`Java `__, `C++ `__) +* `SimpleMotorFeedforward`_ (`Java `__, `C++ `__) +* `ArmFeedforward`_ (`Java `__, `C++ `__) +* `ElevatorFeedforward`_ (`Java `__, `C++ `__) SimpleMotorFeedforward ---------------------- @@ -157,7 +157,7 @@ To calculate the feedforward, simply call the ``calculate()`` method with the de Using Feedforward to Control Mechanisms --------------------------------------- -.. note:: Since feedforward voltages are physically meaningful, it is best to use the ``setVoltage()`` (`Java `__, `C++ `__) method when applying them to motors to compensate for "voltage sag" from the battery. +.. note:: Since feedforward voltages are physically meaningful, it is best to use the ``setVoltage()`` (`Java `__, `C++ `__) method when applying them to motors to compensate for "voltage sag" from the battery. Feedforward control can be used entirely on its own, without a feedback controller. This is known as "open-loop" control, and for many mechanisms (especially robot drives) can be perfectly satisfactory. A ``SimpleMotorFeedforward`` might be employed to control a robot drive as follows: diff --git a/source/docs/software/advanced-controls/controllers/pidcontroller.rst b/source/docs/software/advanced-controls/controllers/pidcontroller.rst index fc5d3aadcf9..94d25ed7fa2 100644 --- a/source/docs/software/advanced-controls/controllers/pidcontroller.rst +++ b/source/docs/software/advanced-controls/controllers/pidcontroller.rst @@ -7,7 +7,7 @@ PID Control in WPILib .. note:: For a guide on implementing PID control through the :ref:`command-based framework `, see :ref:`docs/software/commandbased/pid-subsystems-commands:PID Control through PIDSubsystems and PIDCommands`. -WPILib supports PID control of mechanisms through the ``PIDController`` class (`Java `__, `C++ `__). This class handles the feedback loop calculation for the user, as well as offering methods for returning the error, setting tolerances, and checking if the control loop has reached its setpoint within the specified tolerances. +WPILib supports PID control of mechanisms through the ``PIDController`` class (`Java `__, `C++ `__). This class handles the feedback loop calculation for the user, as well as offering methods for returning the error, setting tolerances, and checking if the control loop has reached its setpoint within the specified tolerances. Using the PIDController Class ----------------------------- diff --git a/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst b/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst index a249e89de31..fa4aa34e0d2 100644 --- a/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst +++ b/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst @@ -5,7 +5,7 @@ Combining Motion Profiling and PID Control with ProfiledPIDController In the previous article, we saw how to use the ``TrapezoidProfile`` class to create and use a trapezoidal motion profile. The example code from that article demonstrates manually composing the ``TrapezoidProfile`` class with the external PID control feature of a "smart" motor controller. -This combination of functionality (a motion profile for generating setpoints combined with a PID controller for following them) is extremely common. To facilitate this, WPILib comes with a ``ProfiledPIDController`` class (`Java `__, `C++ `__) that does most of the work of combining these two functionalities. The API of the ``ProfiledPIDController`` is very similar to that of the ``PIDController``, allowing users to add motion profiling to a PID-controlled mechanism with very few changes to their code. +This combination of functionality (a motion profile for generating setpoints combined with a PID controller for following them) is extremely common. To facilitate this, WPILib comes with a ``ProfiledPIDController`` class (`Java `__, `C++ `__) that does most of the work of combining these two functionalities. The API of the ``ProfiledPIDController`` is very similar to that of the ``PIDController``, allowing users to add motion profiling to a PID-controlled mechanism with very few changes to their code. Using the ProfiledPIDController class ------------------------------------- diff --git a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst index 875d8a05fbe..9919945bae0 100644 --- a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst +++ b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst @@ -11,7 +11,7 @@ Trapezoidal Motion Profiles in WPILib While feedforward and feedback control offer convenient ways to achieve a given setpoint, we are often still faced with the problem of generating setpoints for our mechanisms. While the naive approach of immediately commanding a mechanism to its desired state may work, it is often suboptimal. To improve the handling of our mechanisms, we often wish to command mechanisms to a *sequence* of setpoints that smoothly interpolate between its current state, and its desired goal state. -To help users do this, WPILib provides a ``TrapezoidProfile`` class (`Java `__, `C++ `__). +To help users do this, WPILib provides a ``TrapezoidProfile`` class (`Java `__, `C++ `__). Creating a TrapezoidProfile --------------------------- @@ -23,7 +23,7 @@ Constraints .. note:: The various :ref:`feedforward helper classes ` provide methods for calculating the maximum simultaneously-achievable velocity and acceleration of a mechanism. These can be very useful for calculating appropriate motion constraints for your ``TrapezoidProfile``. -In order to create a trapezoidal motion profile, we must first impose some constraints on the desired motion. Namely, we must specify a maximum velocity and acceleration that the mechanism will be expected to achieve during the motion. To do this, we create an instance of the ``TrapezoidProfile.Constraints`` class (`Java `__, `C++ `__): +In order to create a trapezoidal motion profile, we must first impose some constraints on the desired motion. Namely, we must specify a maximum velocity and acceleration that the mechanism will be expected to achieve during the motion. To do this, we create an instance of the ``TrapezoidProfile.Constraints`` class (`Java `__, `C++ `__): .. tabs:: @@ -44,7 +44,7 @@ In order to create a trapezoidal motion profile, we must first impose some const Start and End States ^^^^^^^^^^^^^^^^^^^^ -Next, we must specify the desired starting and ending states for our mechanisms using the ``TrapezoidProfile.State`` class (`Java `__, `C++ `__). Each state has a position and a velocity: +Next, we must specify the desired starting and ending states for our mechanisms using the ``TrapezoidProfile.State`` class (`Java `__, `C++ `__). Each state has a position and a velocity: .. tabs:: diff --git a/source/docs/software/advanced-controls/filters/debouncer.rst b/source/docs/software/advanced-controls/filters/debouncer.rst index 137946fdf6a..50ae15a745f 100644 --- a/source/docs/software/advanced-controls/filters/debouncer.rst +++ b/source/docs/software/advanced-controls/filters/debouncer.rst @@ -3,7 +3,7 @@ Debouncer A debouncer is a filter used to eliminate unwanted quick on/off cycles (termed "bounces," originally from the physical vibrations of a switch as it is thrown). These cycles are usually due to a sensor error like noise or reflections and not the actual event the sensor is trying to record. -Debouncing is implemented in WPILib by the ``Debouncer`` class (`Java `__, `C++ `__), which filters a boolean stream so that the output only changes if the input sustains a change for some nominal time period. +Debouncing is implemented in WPILib by the ``Debouncer`` class (`Java `__, `C++ `__), which filters a boolean stream so that the output only changes if the input sustains a change for some nominal time period. Modes ----- diff --git a/source/docs/software/advanced-controls/filters/linear-filter.rst b/source/docs/software/advanced-controls/filters/linear-filter.rst index 71b97888ab6..17a0d2bb762 100644 --- a/source/docs/software/advanced-controls/filters/linear-filter.rst +++ b/source/docs/software/advanced-controls/filters/linear-filter.rst @@ -11,7 +11,7 @@ Infinite impulse responses have infinite "support" - that is, they are nonzero o Finite impulse responses have finite "support" - that is, they are nonzero on a bounded region. The "archetypical" FIR filter is a flat moving average - that is, simply setting the output equal to the average of the past n inputs. FIR filters tend to have more-desirable properties than IIR filters, but are more costly to compute. -Linear filters are supported in WPILib through the ``LinearFilter`` class (`Java `__, `C++ `__). +Linear filters are supported in WPILib through the ``LinearFilter`` class (`Java `__, `C++ `__). Creating a LinearFilter ----------------------- diff --git a/source/docs/software/advanced-controls/filters/median-filter.rst b/source/docs/software/advanced-controls/filters/median-filter.rst index 53690c3d200..d25e3b03149 100644 --- a/source/docs/software/advanced-controls/filters/median-filter.rst +++ b/source/docs/software/advanced-controls/filters/median-filter.rst @@ -8,7 +8,7 @@ A `robust `__ alternative to th The median filter is most-useful for removing occasional outliers from an input stream. This makes it particularly well-suited to filtering inputs from distance sensors, which are prone to occasional interference. Unlike a moving average, the median filter will remain completely unaffected by small numbers of outliers, no matter how extreme. -The median filter is supported in WPILib through the ``MedianFilter`` class (`Java `__, `C++ `__). +The median filter is supported in WPILib through the ``MedianFilter`` class (`Java `__, `C++ `__). Creating a MedianFilter ----------------------- diff --git a/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst b/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst index 33ee9650cc1..d51c01fb8b9 100644 --- a/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst +++ b/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst @@ -7,7 +7,7 @@ A common use for filters in FRC\ |reg| is to soften the behavior of control inpu A slew rate limiter can be thought of as a sort of primitive motion profile. In fact, the slew rate limiter is the first-order equivalent of the :ref:`Trapezoidal Motion Profile ` supported by WPILib - it is precisely the limiting case of trapezoidal motion when the acceleration constraint is allowed to tend to infinity. Accordingly, the slew rate limiter is a good choice for applying a de-facto motion profile to a stream of velocity setpoints (or voltages, which are usually approximately proportional to velocity). For input streams that control positions, it is usually better to use a proper trapezoidal profile. -Slew rate limiting is supported in WPILib through the ``SlewRateLimiter`` class (`Java `__, `C++ `__). +Slew rate limiting is supported in WPILib through the ``SlewRateLimiter`` class (`Java `__, `C++ `__). Creating a SlewRateLimiter -------------------------- diff --git a/source/docs/software/advanced-controls/geometry/pose.rst b/source/docs/software/advanced-controls/geometry/pose.rst index 76cd4e1607b..079d9a22ce4 100644 --- a/source/docs/software/advanced-controls/geometry/pose.rst +++ b/source/docs/software/advanced-controls/geometry/pose.rst @@ -4,7 +4,7 @@ Translation, Rotation, and Pose Translation ----------- -Translation in 2 dimensions is represented by WPILib's ``Translation2d`` class (`Java `__, `C++ `__). This class has an x and y component, representing the point :math:`(x, y)` or the vector :math:`\begin{bmatrix}x \\ y \end{bmatrix}` on a 2-dimensional coordinate system. +Translation in 2 dimensions is represented by WPILib's ``Translation2d`` class (`Java `__, `C++ `__). This class has an x and y component, representing the point :math:`(x, y)` or the vector :math:`\begin{bmatrix}x \\ y \end{bmatrix}` on a 2-dimensional coordinate system. You can get the distance to another ``Translation2d`` object by using the ``getDistance(Translation2d other)``, which returns the distance to another Translation2d by using the Pythagorean theorem. @@ -13,11 +13,11 @@ You can get the distance to another ``Translation2d`` object by using the ``getD Rotation -------- -Rotation in 2 dimensions is representated by WPILib's ``Rotation2d`` class (`Java `__, `C++ `__). This class has an angle component, which represents the robot's rotation relative to an axis on a 2-dimensional coordinate system. Positive rotations are counterclockwise. +Rotation in 2 dimensions is representated by WPILib's ``Rotation2d`` class (`Java `__, `C++ `__). This class has an angle component, which represents the robot's rotation relative to an axis on a 2-dimensional coordinate system. Positive rotations are counterclockwise. .. note:: ``Rotation2d`` uses the C++ Units library. The contructor in Java accepts either the angle in radians, or the sine and cosine of the angle, but the ``fromDegrees`` method will construct a ``Rotation2d`` object from degrees. Pose ---- -Pose is a combination of both translation and rotation and is represented by the ``Pose2d`` class (`Java `__, `C++ `__). It can be used to describe the pose of your robot in the field coordinate system, or the pose of objects, such as vision targets, relative to your robot in the robot coordinate system. ``Pose2d`` can also represent the vector :math:`\begin{bmatrix}x \\ y \\ \theta\end{bmatrix}`. +Pose is a combination of both translation and rotation and is represented by the ``Pose2d`` class (`Java `__, `C++ `__). It can be used to describe the pose of your robot in the field coordinate system, or the pose of objects, such as vision targets, relative to your robot in the robot coordinate system. ``Pose2d`` can also represent the vector :math:`\begin{bmatrix}x \\ y \\ \theta\end{bmatrix}`. diff --git a/source/docs/software/advanced-controls/geometry/transformations.rst b/source/docs/software/advanced-controls/geometry/transformations.rst index 1c3f30b472b..c035d2dd219 100644 --- a/source/docs/software/advanced-controls/geometry/transformations.rst +++ b/source/docs/software/advanced-controls/geometry/transformations.rst @@ -26,7 +26,7 @@ Transformations for ``Rotation2d`` are just arithmetic operations on the angle m Transform2d and Twist2d ----------------------- -WPILib provides 2 classes, ``Transform2d`` (`Java `__, `C++ `__), which represents a transformation to a pose, and ``Twist2d`` (`Java `__, `C++ `__) which represents a movement along an arc. ``Transform2d`` and ``Twist2d`` all have x, y and :math:`\theta` components. +WPILib provides 2 classes, ``Transform2d`` (`Java `__, `C++ `__), which represents a transformation to a pose, and ``Twist2d`` (`Java `__, `C++ `__) which represents a movement along an arc. ``Transform2d`` and ``Twist2d`` all have x, y and :math:`\theta` components. ``Transform2d`` represents a **relative** transformation. It has an translation and a rotation component. Transforming a ``Pose2d`` by a ``Transform2d`` rotates the translation component of the transform by the rotation of the pose, and then adds the rotated translation component and the rotation component to the pose. In other words, ``Pose2d.plus(Transform2d)`` returns :math:`\begin{bmatrix} x_p \\ y_p \\ \theta_p \end{bmatrix}+\begin{bmatrix} cos\theta_p & -sin\theta_p & 0 \\ sin\theta_p & cos\theta_p & 0 \\ 0 & 0 & 1 \end{bmatrix}\begin{bmatrix}x_t \\ y_t \\ \theta_t \end{bmatrix}` diff --git a/source/docs/software/advanced-controls/trajectories/ramsete.rst b/source/docs/software/advanced-controls/trajectories/ramsete.rst index 60cf703b027..7c3932d047c 100644 --- a/source/docs/software/advanced-controls/trajectories/ramsete.rst +++ b/source/docs/software/advanced-controls/trajectories/ramsete.rst @@ -73,7 +73,7 @@ The returned adjusted speeds can be converted to usable speeds using the kinemat DifferentialDriveWheelSpeeds wheelSpeeds = kinematics.ToWheelSpeeds(adjustedSpeeds); auto [left, right] = kinematics.ToWheelSpeeds(adjustedSpeeds); -Because these new left and right velocities are still speeds and not voltages, two PID Controllers, one for each side may be used to track these velocities. Either the WPILib PIDController (`C++ `_, `Java `_) can be used, or the Velocity PID feature on smart motor controllers such as the TalonSRX and the SPARK MAX can be used. +Because these new left and right velocities are still speeds and not voltages, two PID Controllers, one for each side may be used to track these velocities. Either the WPILib PIDController (`C++ `_, `Java `_) can be used, or the Velocity PID feature on smart motor controllers such as the TalonSRX and the SPARK MAX can be used. Ramsete in the Command-Based Framework -------------------------------------- diff --git a/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst b/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst index 300e5164d26..d6b244b0133 100644 --- a/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst +++ b/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst @@ -59,7 +59,7 @@ Here is an example of generating a trajectory using clamped cubic splines for th :language: cpp :lines: 8-22 -.. note:: The Java code utilizes the `Units `_ utility, for easy unit conversions. +.. note:: The Java code utilizes the `Units `_ utility, for easy unit conversions. .. note:: Generating a typical trajectory takes about 10 ms to 25 ms. This isn't long, but it's still highly recommended to generate all trajectories on startup (``robotInit``). diff --git a/source/docs/software/can-devices/pneumatics-control-module.rst b/source/docs/software/can-devices/pneumatics-control-module.rst index a0270e0a73f..8e99aeb6c77 100644 --- a/source/docs/software/can-devices/pneumatics-control-module.rst +++ b/source/docs/software/can-devices/pneumatics-control-module.rst @@ -3,7 +3,7 @@ Pneumatics Control Module The Pneumatics Control Module (PCM) is a CAN-based device that provides complete control over the compressor and up to 8 solenoids per module. The PCM is integrated into WPILib through a series of classes that make it simple to use. -The closed loop control of the Compressor and Pressure switch is handled by the :code:`Compressor` class (`Java `__, `C++ `__), and the Solenoids are handled by the :code:`Solenoid` (`Java `__, `C++ `__) and :code:`DoubleSolenoid` (`Java `__, `C++ `__) classes. +The closed loop control of the Compressor and Pressure switch is handled by the :code:`Compressor` class (`Java `__, `C++ `__), and the Solenoids are handled by the :code:`Solenoid` (`Java `__, `C++ `__) and :code:`DoubleSolenoid` (`Java `__, `C++ `__) classes. An additional PCM module can be used where the modules corresponding solenoids are differentiated by the module number in the constructors of the Solenoid and Compressor classes. diff --git a/source/docs/software/can-devices/power-distribution-module.rst b/source/docs/software/can-devices/power-distribution-module.rst index 6da8e8a42a1..e1f41f83e65 100644 --- a/source/docs/software/can-devices/power-distribution-module.rst +++ b/source/docs/software/can-devices/power-distribution-module.rst @@ -6,7 +6,7 @@ The CTRE Power Distribution Panel (PDP) and Rev Power Distribution Hub can use t Creating a Power Distribution Object ------------------------------------ -To use the either Power Distribution module, create an instance of the :code:`PowerDistribution` class (`Java `__, `C++ `__): +To use the either Power Distribution module, create an instance of the :code:`PowerDistribution` class (`Java `__, `C++ `__): .. tabs:: diff --git a/source/docs/software/commandbased/binding-commands-to-triggers.rst b/source/docs/software/commandbased/binding-commands-to-triggers.rst index 50555386f94..b1bc3036ad5 100644 --- a/source/docs/software/commandbased/binding-commands-to-triggers.rst +++ b/source/docs/software/commandbased/binding-commands-to-triggers.rst @@ -5,7 +5,7 @@ Apart from autonomous commands, which are scheduled at the start of the autonomo As mentioned earlier, command-based is a `declarative `__ paradigm. Accordingly, binding buttons to commands is done declaratively; the association of a button and a command is "declared" once, during robot initialization. The library then does all the hard work of checking the button state and scheduling (or canceling) the command as needed, behind-the-scenes. Users only need to worry about designing their desired UI setup - not about implementing it! -Command binding is done through the ``Trigger`` class (`Java `__, `C++ `__) and its various ``Button`` subclasses (`Java `__, `C++ `__). +Command binding is done through the ``Trigger`` class (`Java `__, `C++ `__) and its various ``Button`` subclasses (`Java `__, `C++ `__). Trigger/Button Bindings ----------------------- @@ -37,7 +37,7 @@ This binding schedules a command when a trigger changes from active to inactive toggleWhenActive/toggleWhenPressed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This binding toggles a command, scheduling it when a trigger changes from inactive to active (or a button is initially pressed), and canceling it under the same condition if the command is currently running. Note that while this functionality is supported, toggles are not a highly-recommended option for user control, as they require the driver to keep track of the robot state. The preferred method is to use two buttons; one to turn on and another to turn off. Using a `StartEndCommand `__ or a `ConditionalCommand `__ is a good way to specify the commands that you want to be want to be toggled between. +This binding toggles a command, scheduling it when a trigger changes from inactive to active (or a button is initially pressed), and canceling it under the same condition if the command is currently running. Note that while this functionality is supported, toggles are not a highly-recommended option for user control, as they require the driver to keep track of the robot state. The preferred method is to use two buttons; one to turn on and another to turn off. Using a `StartEndCommand `__ or a `ConditionalCommand `__ is a good way to specify the commands that you want to be want to be toggled between. .. tabs:: @@ -66,7 +66,7 @@ The most-common way to trigger a command is to bind a command to a button on a j Creating a JoystickButton ^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to create a ``JoystickButton``, we first need a Joystick. All types of joysticks (including gamepads) are represented in code by the ``GenericHID`` class (`Java `__, `C++ `__), or one of its subclasses: +In order to create a ``JoystickButton``, we first need a Joystick. All types of joysticks (including gamepads) are represented in code by the ``GenericHID`` class (`Java `__, `C++ `__), or one of its subclasses: .. tabs:: @@ -80,9 +80,9 @@ In order to create a ``JoystickButton``, we first need a Joystick. All types of frc::Joystick exampleStick{1}; // Creates a joystick on port 1 frc::XBoxController exampleController{2} // Creates an XboxController on port 2 -.. note:: When creating a ``JoystickButton`` with an XboxController, it is usually a good idea to use the button enum (`Java `__, `C++ `__) to get the button number corresponding to a given button. +.. note:: When creating a ``JoystickButton`` with an XboxController, it is usually a good idea to use the button enum (`Java `__, `C++ `__) to get the button number corresponding to a given button. -After the joystick is instantiated, users can then pass it to a ``JoystickButton`` object (`Java `__, `C++ `__): +After the joystick is instantiated, users can then pass it to a ``JoystickButton`` object (`Java `__, `C++ `__): .. tabs:: diff --git a/source/docs/software/commandbased/command-based-changes.rst b/source/docs/software/commandbased/command-based-changes.rst index 232ceb956ed..c035fb86905 100644 --- a/source/docs/software/commandbased/command-based-changes.rst +++ b/source/docs/software/commandbased/command-based-changes.rst @@ -1,7 +1,7 @@ 2020 Command-Based Rewrite: What Changed? ========================================= -This article provides a summary of changes from the original command-based framework to the 2020 rewrite. This summary is not necessarily comprehensive - for rigorous documentation, as always, refer to the API docs (`Java `__, `C++ `__). +This article provides a summary of changes from the original command-based framework to the 2020 rewrite. This summary is not necessarily comprehensive - for rigorous documentation, as always, refer to the API docs (`Java `__, `C++ `__). Package Location ---------------- @@ -16,7 +16,7 @@ The overall structure of the command-based framework has remained largely the sa Commands and Subsystems as Interfaces ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``Command`` (`Java `__, `C++ `__) and ``Subsystem`` (`Java `__, `C++ `__) are both now interfaces as opposed to abstract classes, allowing advanced users more potential flexibility. ``CommandBase`` and ``SubsystemBase`` abstract base classes are still provided for convenience, but are not required. For more information, see :doc:`commands` and :doc:`subsystems`. +``Command`` (`Java `__, `C++ `__) and ``Subsystem`` (`Java `__, `C++ `__) are both now interfaces as opposed to abstract classes, allowing advanced users more potential flexibility. ``CommandBase`` and ``SubsystemBase`` abstract base classes are still provided for convenience, but are not required. For more information, see :doc:`commands` and :doc:`subsystems`. Multiple Command Group Classes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -45,7 +45,7 @@ Transfer of ownership is done using `perfect forwarding `__, `C++ `__). +* ``Scheduler`` has been renamed to ``CommandScheduler`` (`Java `__, `C++ `__). * Interruptibility of commands is now the responsibility of the scheduler, not the commands, and can be specified during the call to ``schedule``. * Users can now pass actions to the scheduler which are taken whenever a command is scheduled, interrupted, or ends normally. This is highly useful for cases such as event logging. @@ -54,7 +54,7 @@ Changes to Subsystem .. note:: For more information on subsystems, see :doc:`subsystems`. -* As noted earlier, ``Subsystem`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Subsystem`` is the new ``SubsystemBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. +* As noted earlier, ``Subsystem`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Subsystem`` is the new ``SubsystemBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. * ``initDefaultCommand`` has been removed; subsystems no longer need to "know about" their default commands, which are instead registered directly with the ``CommandScheduler``. The new ``setDefaultCommand`` method simply wraps the ``CommandScheduler`` call. * Subsystems no longer "know about" the commands currently requiring them; this is handled exclusively by the ``CommandScheduler``. A convenience wrapper on the ``CommandScheduler`` method is provided, however. @@ -63,7 +63,7 @@ Changes to Command .. note:: For more information on commands, see :doc:`commands`. -* As noted earlier, ``Command`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Command`` is the new ``CommandBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. +* As noted earlier, ``Command`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Command`` is the new ``CommandBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. * Commands no longer handle their own scheduling state; this is now the responsibility of the scheduler. * The ``interrupted()`` method has been rolled into the ``end()`` method, which now takes a parameter specifying whether the command was interrupted (``false`` if it ended normally). * The ``requires()`` method has been renamed to ``addRequirement()``. diff --git a/source/docs/software/commandbased/command-groups.rst b/source/docs/software/commandbased/command-groups.rst index 342b651067c..58ca94a9980 100644 --- a/source/docs/software/commandbased/command-groups.rst +++ b/source/docs/software/commandbased/command-groups.rst @@ -17,22 +17,22 @@ The command-based library supports four basic types of command groups: ``Sequent SequentialCommandGroup ^^^^^^^^^^^^^^^^^^^^^^ -A ``SequentialCommandGroup`` (`Java `__, `C++ `__) runs a list of commands in sequence - the first command will be executed, then the second, then the third, and so on until the list finishes. The sequential group finishes after the last command in the sequence finishes. It is therefore usually important to ensure that each command in the sequence does actually finish (if a given command does not finish, the next command will never start!). +A ``SequentialCommandGroup`` (`Java `__, `C++ `__) runs a list of commands in sequence - the first command will be executed, then the second, then the third, and so on until the list finishes. The sequential group finishes after the last command in the sequence finishes. It is therefore usually important to ensure that each command in the sequence does actually finish (if a given command does not finish, the next command will never start!). ParallelCommandGroup ^^^^^^^^^^^^^^^^^^^^ -A ``ParallelCommandGroup`` (`Java `__, `C++ `__) runs a set of commands concurrently - all commands will execute at the same time. The parallel group will end when all commands have finished. +A ``ParallelCommandGroup`` (`Java `__, `C++ `__) runs a set of commands concurrently - all commands will execute at the same time. The parallel group will end when all commands have finished. ParallelRaceGroup ^^^^^^^^^^^^^^^^^ -A ``ParallelRaceGroup`` (`Java `__, `C++ `__) is much like a ``ParallelCommandgroup``, in that it runs a set of commands concurrently. However, the race group ends as soon as any command in the group ends - all other commands are interrupted at that point. +A ``ParallelRaceGroup`` (`Java `__, `C++ `__) is much like a ``ParallelCommandgroup``, in that it runs a set of commands concurrently. However, the race group ends as soon as any command in the group ends - all other commands are interrupted at that point. ParallelDeadlineGroup ^^^^^^^^^^^^^^^^^^^^^ -A ``ParallelDeadlineGroup`` (`Java `__, `C++ `__) also runs a set of commands concurrently. However, the deadline group ends when a *specific* command (the "deadline") ends, interrupting all other commands in the group that are still running at that point. +A ``ParallelDeadlineGroup`` (`Java `__, `C++ `__) also runs a set of commands concurrently. However, the deadline group ends when a *specific* command (the "deadline") ends, interrupting all other commands in the group that are still running at that point. Creating Command Groups ----------------------- @@ -70,7 +70,7 @@ The ``addCommands()`` method adds commands to the group, and is present in all f Inline Command Groups --------------------- -.. note:: Due to the verbosity of Java's ``new`` syntax, the Java ``CommandGroupBase`` object offers a factory method for each of the four command-group types: `sequence `__, `parallel `__, `race `__, and `deadline `__. +.. note:: Due to the verbosity of Java's ``new`` syntax, the Java ``CommandGroupBase`` object offers a factory method for each of the four command-group types: `sequence `__, `parallel `__, `race `__, and `deadline `__. Command groups can be used without subclassing at all: one can simply pass in the desired commands through the constructor: @@ -130,7 +130,7 @@ As command groups are commands, they also must declare their requirements. Howev Additionally, requirements are enforced within all three types of parallel groups - a parallel group may *not* contain multiple commands that require the same subsystem. -Some advanced users may find this overly-restrictive - for said users, the library offers a ``ScheduleCommand`` class (`Java `__, `C++ `__) that can be used to independently "branch off" from command groups to provide finer granularity in requirement management. +Some advanced users may find this overly-restrictive - for said users, the library offers a ``ScheduleCommand`` class (`Java `__, `C++ `__) that can be used to independently "branch off" from command groups to provide finer granularity in requirement management. Restrictions on Command Group Components ---------------------------------------- @@ -141,4 +141,4 @@ Since command group components are run through their encapsulating command group For this reason, command instances that have been added to a command group cannot be independently scheduled or added to a second command group. Attempting to do so will throw an exception and crash the user program. -Advanced users who wish to re-use a command instance and are *certain* that it is safe to do so may bypass this restriction with the ``clearGroupedCommand()`` `method `__ in the ``CommandGroupBase`` class. +Advanced users who wish to re-use a command instance and are *certain* that it is safe to do so may bypass this restriction with the ``clearGroupedCommand()`` `method `__ in the ``CommandGroupBase`` class. diff --git a/source/docs/software/commandbased/command-scheduler.rst b/source/docs/software/commandbased/command-scheduler.rst index bd28c417047..80552423fe2 100644 --- a/source/docs/software/commandbased/command-scheduler.rst +++ b/source/docs/software/commandbased/command-scheduler.rst @@ -1,7 +1,7 @@ The Command Scheduler ===================== -The ``CommandScheduler`` (`Java `__, `C++ `__) is the class responsible for actually running commands. Each iteration (ordinarily once per 20ms), the scheduler polls all registered buttons, schedules commands for execution accordingly, runs the command bodies of all scheduled commands, and ends those commands that have finished or are interrupted. +The ``CommandScheduler`` (`Java `__, `C++ `__) is the class responsible for actually running commands. Each iteration (ordinarily once per 20ms), the scheduler polls all registered buttons, schedules commands for execution accordingly, runs the command bodies of all scheduled commands, and ends those commands that have finished or are interrupted. The ``CommandScheduler`` also runs the ``periodic()`` method of each registered ``Subsystem``. @@ -20,7 +20,7 @@ The ``schedule()`` Method .. image:: diagrams/scheduler.drawio.svg :alt: Flow diagram showing how a scheduled command is evaluated to be run. -To schedule a command, users call the ``schedule()`` method (`Java `__, `C++ `__. This method takes a command (and, optionally, a specification as to whether that command is interruptible), and attempts to add it to list of currently-running commands, pending whether it is already running or whether its requirements are available. If it is added, its ``initialize()`` method is called. +To schedule a command, users call the ``schedule()`` method (`Java `__, `C++ `__. This method takes a command (and, optionally, a specification as to whether that command is interruptible), and attempts to add it to list of currently-running commands, pending whether it is already running or whether its requirements are available. If it is added, its ``initialize()`` method is called. The Scheduler Run Sequence -------------------------- @@ -30,7 +30,7 @@ The Scheduler Run Sequence .. image:: diagrams/scheduler-run-sequence.drawio.svg :alt: Flow diagram that show the sequence of each individual command. -What does a single iteration of the scheduler's ``run()`` method (`Java `__, `C++ `__) actually do? The following section walks through the logic of a scheduler iteration. +What does a single iteration of the scheduler's ``run()`` method (`Java `__, `C++ `__) actually do? The following section walks through the logic of a scheduler iteration. Step 1: Run Subsystem Periodic Methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -71,22 +71,22 @@ Occasionally, it is desirable to have the scheduler execute a custom action when onCommandInitialize ^^^^^^^^^^^^^^^^^^^ -The ``onCommandInitialize`` method (`Java `__, `C++ `__) runs a specified action whenever a command is initialized. +The ``onCommandInitialize`` method (`Java `__, `C++ `__) runs a specified action whenever a command is initialized. onCommandExecute ^^^^^^^^^^^^^^^^ -The ``onCommandExecute`` method (`Java `__, `C++ `__) runs a specified action whenever a command is executed. +The ``onCommandExecute`` method (`Java `__, `C++ `__) runs a specified action whenever a command is executed. onCommandFinish ^^^^^^^^^^^^^^^ -The ``onCommandFinish`` method (`Java `__, `C++ `__) runs a specified action whenever a command finishes normally (i.e. the ``isFinished()`` method returned true). +The ``onCommandFinish`` method (`Java `__, `C++ `__) runs a specified action whenever a command finishes normally (i.e. the ``isFinished()`` method returned true). onCommandInterrupt ^^^^^^^^^^^^^^^^^^ -The ``onCommandInterrupt`` method (`Java `__, `C++ `__) runs a specified action whenever a command is interrupted (i.e. by being explicitly canceled or by another command that shares one of its requirements). +The ``onCommandInterrupt`` method (`Java `__, `C++ `__) runs a specified action whenever a command is interrupted (i.e. by being explicitly canceled or by another command that shares one of its requirements). A typical use-case for these methods is adding markers in an event log whenever a command scheduling event takes place, as demonstrated in the SchedulerEventLogging example project (`Java `__, `C++ `__): diff --git a/source/docs/software/commandbased/commands.rst b/source/docs/software/commandbased/commands.rst index 3f55771781b..882f3b66041 100644 --- a/source/docs/software/commandbased/commands.rst +++ b/source/docs/software/commandbased/commands.rst @@ -1,14 +1,14 @@ Commands ======== -Commands are simple state machines that perform high-level robot functions using the methods defined by subsystems. Commands can be either idle, in which they do nothing, or scheduled, in which the scheduler will execute a specific set of the command’s code depending on the state of the command. The ``CommandScheduler`` recognizes scheduled commands as being in one of three states: initializing, executing, or ending. Commands specify what is done in each of these states through the ``initialize()``, ``execute()`` and ``end()`` methods. Commands are represented in the command-based library by the ``Command`` interface (`Java `__, `C++ `__). +Commands are simple state machines that perform high-level robot functions using the methods defined by subsystems. Commands can be either idle, in which they do nothing, or scheduled, in which the scheduler will execute a specific set of the command’s code depending on the state of the command. The ``CommandScheduler`` recognizes scheduled commands as being in one of three states: initializing, executing, or ending. Commands specify what is done in each of these states through the ``initialize()``, ``execute()`` and ``end()`` methods. Commands are represented in the command-based library by the ``Command`` interface (`Java `__, `C++ `__). Creating Commands ----------------- .. note:: In the C++ API, a `CRTP `__ is used to allow certain Command methods to work with the object ownership model. Users should *always* extend the ``CommandHelper`` `class `__ when defining their own command classes, as is shown below. -Similarly to subsystems, the recommended method for most users to create a command is to subclass the abstract ``CommandBase`` class (`Java `__, `C++ `__), as seen in the command-based template (`Java `__, `C++ `__): +Similarly to subsystems, the recommended method for most users to create a command is to subclass the abstract ``CommandBase`` class (`Java `__, `C++ `__), as seen in the command-based template (`Java `__, `C++ `__): .. tabs:: @@ -41,22 +41,22 @@ While subsystems are fairly freeform, and may generally look like whatever the u Initialization ^^^^^^^^^^^^^^ -The ``initialize()`` method (`Java `__, `C++ `__) is run exactly once per time a command is scheduled, as part of the scheduler’s ``schedule()`` method. The scheduler’s ``run()`` method does not need to be called for the ``initialize()`` method to run. The initialize block should be used to place the command in a known starting state for execution. It is also useful for performing tasks that only need to be performed once per time scheduled, such as setting motors to run at a constant speed or setting the state of a solenoid actuator. +The ``initialize()`` method (`Java `__, `C++ `__) is run exactly once per time a command is scheduled, as part of the scheduler’s ``schedule()`` method. The scheduler’s ``run()`` method does not need to be called for the ``initialize()`` method to run. The initialize block should be used to place the command in a known starting state for execution. It is also useful for performing tasks that only need to be performed once per time scheduled, such as setting motors to run at a constant speed or setting the state of a solenoid actuator. Execution ^^^^^^^^^ -The ``execute()`` method (`Java `__, `C++ `__) is called repeatedly while the command is scheduled, whenever the scheduler’s ``run()`` method is called (this is generally done in the main robot periodic method, which runs every 20ms by default). The execute block should be used for any task that needs to be done continually while the command is scheduled, such as updating motor outputs to match joystick inputs, or using the output of a control loop. +The ``execute()`` method (`Java `__, `C++ `__) is called repeatedly while the command is scheduled, whenever the scheduler’s ``run()`` method is called (this is generally done in the main robot periodic method, which runs every 20ms by default). The execute block should be used for any task that needs to be done continually while the command is scheduled, such as updating motor outputs to match joystick inputs, or using the output of a control loop. Ending ^^^^^^ -The ``end()`` method (`Java `__, `C++ `__) is called once when the command ends, whether it finishes normally (i.e. ``isFinished()`` returned true) or it was interrupted (either by another command or by being explicitly canceled). The method argument specifies the manner in which the command ended; users can use this to differentiate the behavior of their command end accordingly. The end block should be used to "wrap up" command state in a neat way, such as setting motors back to zero or reverting a solenoid actuator to a "default" state. +The ``end()`` method (`Java `__, `C++ `__) is called once when the command ends, whether it finishes normally (i.e. ``isFinished()`` returned true) or it was interrupted (either by another command or by being explicitly canceled). The method argument specifies the manner in which the command ended; users can use this to differentiate the behavior of their command end accordingly. The end block should be used to "wrap up" command state in a neat way, such as setting motors back to zero or reverting a solenoid actuator to a "default" state. Specifying end conditions ^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``isFinished()`` method (`Java `__, `C++ `__) is called repeatedly while the command is scheduled, whenever the scheduler’s ``run()`` method is called. As soon as it returns true, the command’s ``end()`` method is called and it is un-scheduled. The ``isFinished()`` method is called *after* the ``execute()`` method, so the command *will* execute once on the same iteration that it is un-scheduled. +The ``isFinished()`` method (`Java `__, `C++ `__) is called repeatedly while the command is scheduled, whenever the scheduler’s ``run()`` method is called. As soon as it returns true, the command’s ``end()`` method is called and it is un-scheduled. The ``isFinished()`` method is called *after* the ``execute()`` method, so the command *will* execute once on the same iteration that it is un-scheduled. Simple Command Example ---------------------- diff --git a/source/docs/software/commandbased/convenience-features.rst b/source/docs/software/commandbased/convenience-features.rst index ea49a0ce402..0a952a5a683 100644 --- a/source/docs/software/commandbased/convenience-features.rst +++ b/source/docs/software/commandbased/convenience-features.rst @@ -68,12 +68,12 @@ Instead of wastefully writing separate ``GrabHatch`` and ``ReleaseHatch`` comman Included Command Types ---------------------- -The command-based library includes a variety of pre-written commands for commonly-encountered use cases. Many of these commands are intended to be used "out-of-the-box" via `inlining <#inline-command-definitions>`_, however they may be subclassed, as well. A list of the included pre-made commands can be found below, along with brief examples of each - for more rigorous documentation, see the API docs (`Java `__, `C++ `__). +The command-based library includes a variety of pre-written commands for commonly-encountered use cases. Many of these commands are intended to be used "out-of-the-box" via `inlining <#inline-command-definitions>`_, however they may be subclassed, as well. A list of the included pre-made commands can be found below, along with brief examples of each - for more rigorous documentation, see the API docs (`Java `__, `C++ `__). ConditionalCommand ^^^^^^^^^^^^^^^^^^ -The ``ConditionalCommand`` class (`Java `__, `C++ `__) runs one of two commands when executed, depending on a user-specified true-or-false condition: +The ``ConditionalCommand`` class (`Java `__, `C++ `__) runs one of two commands when executed, depending on a user-specified true-or-false condition: .. tabs:: @@ -94,7 +94,7 @@ SelectCommand .. note:: An alternate version of SelectCommand simply takes a method that supplies the command to be run - this can be very succinct, but makes inferring the command's requirements impossible, and so leaves the user responsible for manually adding the requirements to the SelectCommand. -The ``SelectCommand`` class (`Java `__, `C++ `__) is a generalization of the ``ConditionalCommand`` class that runs one of a selection of commands based on the value of a user-specified selector. The following example code is taken from the SelectCommand example project (`Java `__, `C++ `__): +The ``SelectCommand`` class (`Java `__, `C++ `__) is a generalization of the ``ConditionalCommand`` class that runs one of a selection of commands based on the value of a user-specified selector. The following example code is taken from the SelectCommand example project (`Java `__, `C++ `__): .. tabs:: @@ -117,7 +117,7 @@ The ``SelectCommand`` class (`Java `__, `C++ `__) executes a single action on initialization, and then ends immediately: +The ``InstantCommand`` class (`Java `__, `C++ `__) executes a single action on initialization, and then ends immediately: .. tabs:: @@ -134,7 +134,7 @@ The ``InstantCommand`` class (`Java `__, `C++ `__) runs a specified method repeatedly in its ``execute()`` block. It does not have end conditions by default; users can either subclass it, or `decorate <#command-decorator-methods>`_ it to add them. +The ``RunCommand`` class (`Java `__, `C++ `__) runs a specified method repeatedly in its ``execute()`` block. It does not have end conditions by default; users can either subclass it, or `decorate <#command-decorator-methods>`_ it to add them. .. tabs:: @@ -162,7 +162,7 @@ The ``RunCommand`` class (`Java `__, `C++ `__) executes an action when starting, and a second one when ending. It does not have end conditions by default; users can either subclass it, or `decorate <#command-decorator-methods>`_ an inlined command to add them. +The ``StartEndCommand`` class (`Java `__, `C++ `__) executes an action when starting, and a second one when ending. It does not have end conditions by default; users can either subclass it, or `decorate <#command-decorator-methods>`_ an inlined command to add them. .. tabs:: @@ -191,7 +191,7 @@ The ``StartEndCommand`` class (`Java `__, `C++ `__) allows all four ``Command`` methods to be passed in as method references or lambdas: +The ``FunctionalCommand`` class (`Java `__, `C++ `__) allows all four ``Command`` methods to be passed in as method references or lambdas: .. tabs:: @@ -228,7 +228,7 @@ The ``FunctionalCommand`` class (`Java `__, `C++ `__) prints a given string. +The ``PrintCommand`` class (`Java `__, `C++ `__) prints a given string. .. tabs:: @@ -243,7 +243,7 @@ The ``PrintCommand`` class (`Java `__, `C++ `__) schedules a specified command, and ends instantly: +The ``ScheduleCommand`` class (`Java `__, `C++ `__) schedules a specified command, and ends instantly: .. tabs:: @@ -262,7 +262,7 @@ This is often useful for "forking off" from command groups: by default, commands ProxyScheduleCommand ^^^^^^^^^^^^^^^^^^^^ -The ``ProxyScheduleCommand`` class (`Java `__, `C++ `__) schedules a specified command, and does not end until that command ends: +The ``ProxyScheduleCommand`` class (`Java `__, `C++ `__) schedules a specified command, and does not end until that command ends: .. tabs:: @@ -281,7 +281,7 @@ This is often useful for "forking off" from command groups: by default, commands WaitCommand ^^^^^^^^^^^ -The ``WaitCommand`` class (`Java `__, `C++ `__) does nothing, and ends after a specified period of time elapses after its initial scheduling: +The ``WaitCommand`` class (`Java `__, `C++ `__) does nothing, and ends after a specified period of time elapses after its initial scheduling: .. tabs:: @@ -304,7 +304,7 @@ WaitUntilCommand .. warning:: The match timer used by WaitUntilCommand does *not* provide an official match time! While it is fairly accurate, use of this timer can *not* guarantee the legality of your robot's actions. -The ``WaitUntilCommand`` class (`Java `__, `C++ `__) does nothing, and ends once a specified condition becomes true, or until a specified match time passes. +The ``WaitUntilCommand`` class (`Java `__, `C++ `__) does nothing, and ends once a specified condition becomes true, or until a specified match time passes. .. tabs:: @@ -327,7 +327,7 @@ The ``WaitUntilCommand`` class (`Java `__, `C++ `__) runs a given command with its end condition removed, so that it runs forever (unless externally interrupted): +The ``PerpetualCommand`` class (`Java `__, `C++ `__) runs a given command with its end condition removed, so that it runs forever (unless externally interrupted): .. tabs:: @@ -350,12 +350,12 @@ commands. A "decorator" method is a method that takes an object (in this case, a command) and returns an object of the same type (i.e. a command) with some additional functionality added to it. A list of the included decorator methods with brief examples is included below - for rigorous -documentation, see the API docs (`Java `__, `C++ `__). +documentation, see the API docs (`Java `__, `C++ `__). withTimeout ^^^^^^^^^^^ -The ``withTimeout()`` decorator (`Java `__, `C++ `__) adds a timeout to a command. The +The ``withTimeout()`` decorator (`Java `__, `C++ `__) adds a timeout to a command. The decorated command will be interrupted if the timeout expires: .. tabs:: @@ -373,7 +373,7 @@ decorated command will be interrupted if the timeout expires: withInterrupt ^^^^^^^^^^^^^ -The ``withInterrupt()`` (`Java `__, `C++ `__) decorator adds a condition on which the command will be interrupted: +The ``withInterrupt()`` (`Java `__, `C++ `__) decorator adds a condition on which the command will be interrupted: .. tabs:: @@ -390,7 +390,7 @@ The ``withInterrupt()`` (`Java `__, `C++ `__) adds a method to be executed after the command ends: +The ``andThen()`` decorator (`Java `__, `C++ `__) adds a method to be executed after the command ends: .. tabs:: @@ -407,7 +407,7 @@ The ``andThen()`` decorator (`Java `__, `C++ `__) adds a method to be executed before the command starts: +The ``beforeStarting()`` decorator (`Java `__, `C++ `__) adds a method to be executed before the command starts: .. tabs:: @@ -426,7 +426,7 @@ alongWith (Java only) .. note:: This decorator is not supported in C++ due to technical constraints - users should simply construct a parallel command group the ordinary way instead. -The ``alongWith()`` `decorator `__ returns a :ref:`parallel command group `. All commands will execute at the same time and each will end independently of each other: +The ``alongWith()`` `decorator `__ returns a :ref:`parallel command group `. All commands will execute at the same time and each will end independently of each other: .. code-block:: java @@ -438,7 +438,7 @@ raceWith (Java only) .. note:: This decorator is not supported in C++ due to technical constraints - users should simply construct a parallel race group the ordinary way instead. -The ``raceWith()`` `decorator `__ returns a :ref:`parallel race group ` that ends as soon as the first command ends. At this point all others are interrupted. It doesn't matter which command is the calling command: +The ``raceWith()`` `decorator `__ returns a :ref:`parallel race group ` that ends as soon as the first command ends. At this point all others are interrupted. It doesn't matter which command is the calling command: .. code-block:: java @@ -450,7 +450,7 @@ deadlineWith (Java only) .. note:: This decorator is not supported in C++ due to technical constraints - users should simply construct a parallel deadline group the ordinary way instead. -The ``deadlineWith()`` `decorator `__ returns a :ref:`parallel deadline group ` with the calling command being the deadline. When this deadline command ends it will interrupt any others that are not finished: +The ``deadlineWith()`` `decorator `__ returns a :ref:`parallel deadline group ` with the calling command being the deadline. When this deadline command ends it will interrupt any others that are not finished: .. code-block:: java @@ -462,7 +462,7 @@ withName (Java only) .. note:: This decorator is not supported in C++ due to technical constraints - users should set the name of the command inside their command class instead. -The ``withName()`` `decorator `__ adds a name to a command. This name will appear on a dashboard when the command is sent via the `sendable interface `__. +The ``withName()`` `decorator `__ adds a name to a command. This name will appear on a dashboard when the command is sent via the `sendable interface `__. .. code-block:: java @@ -472,7 +472,7 @@ The ``withName()`` `decorator `__, `C++ `__) removes the end condition of a command, so that it runs forever. +The ``perpetually()`` decorator (`Java `__, `C++ `__) removes the end condition of a command, so that it runs forever. .. tabs:: @@ -501,7 +501,7 @@ Static Factory Methods for Command Groups (Java only) .. note:: These factory methods are not included in the C++ command library, as the reduction in verbosity would be minimal - C++ commands should be stack-allocated, removing the need for the ``new`` keyword. -If users do not wish to use the ``andThen``, ``alongWith``, ``raceWith``, and ``deadlineWith`` decorators for declaring command groups, but still wish to reduce verbosity compared to calling the constructors, the ``CommandGroupBase`` `class `__ contains four static factory methods for declaring command groups: ``sequence()``, ``parallel()``, ``race()``, and ``deadline()``. When used from within a command group subclass or in combination with ``import static``, these become extremely concise and greatly aid in command composition: +If users do not wish to use the ``andThen``, ``alongWith``, ``raceWith``, and ``deadlineWith`` decorators for declaring command groups, but still wish to reduce verbosity compared to calling the constructors, the ``CommandGroupBase`` `class `__ contains four static factory methods for declaring command groups: ``sequence()``, ``parallel()``, ``race()``, and ``deadline()``. When used from within a command group subclass or in combination with ``import static``, these become extremely concise and greatly aid in command composition: .. code-block:: java diff --git a/source/docs/software/commandbased/pid-subsystems-commands.rst b/source/docs/software/commandbased/pid-subsystems-commands.rst index 75db9d044c0..b2e471c577e 100644 --- a/source/docs/software/commandbased/pid-subsystems-commands.rst +++ b/source/docs/software/commandbased/pid-subsystems-commands.rst @@ -12,7 +12,7 @@ One of the most common control algorithms used in FRC\ |reg| is the `PID control PIDSubsystems ------------- -The ``PIDSubsystem`` class (`Java `__, `C++ `__) allows users to conveniently create a subsystem with a built-in ``PIDController``. In order to use the ``PIDSubsystem`` class, users must create a subclass of it. +The ``PIDSubsystem`` class (`Java `__, `C++ `__) allows users to conveniently create a subsystem with a built-in ``PIDController``. In order to use the ``PIDSubsystem`` class, users must create a subclass of it. Creating a PIDSubsystem ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/docs/software/commandbased/profile-subsystems-commands.rst b/source/docs/software/commandbased/profile-subsystems-commands.rst index fb41eb25fb9..cd91cf70b8e 100644 --- a/source/docs/software/commandbased/profile-subsystems-commands.rst +++ b/source/docs/software/commandbased/profile-subsystems-commands.rst @@ -5,7 +5,7 @@ Motion Profiling through TrapezoidProfileSubsystems and TrapezoidProfileCommands .. note:: The ``TrapezoidProfile`` command wrappers are generally intended for composition with custom or external controllers. For combining trapezoidal motion profiling with WPILib's ``PIDController``, see :doc:`profilepid-subsystems-commands`. -When controlling a mechanism, is often desirable to move it smoothly between two positions, rather than to abruptly change its setpoint. This is called "motion-profiling," and is supported in WPILib through the ``TrapezoidProfile`` class (`Java `__, `C++ `__). +When controlling a mechanism, is often desirable to move it smoothly between two positions, rather than to abruptly change its setpoint. This is called "motion-profiling," and is supported in WPILib through the ``TrapezoidProfile`` class (`Java `__, `C++ `__). To further help teams integrate motion profiling into their command-based robot projects, WPILib includes two convenience wrappers for the ``TrapezoidProfile`` class: ``TrapezoidProfileSubsystem``, which automatically generates and executes motion profiles in its ``periodic()`` method, and the ``TrapezoidProfileCommand``, which executes a single user-provided ``TrapezoidProfile``. @@ -14,7 +14,7 @@ TrapezoidProfileSubsystem .. note:: In C++, the ``TrapezoidProfileSubsystem`` class is templated on the unit type used for distance measurements, which may be angular or linear. The passed-in values *must* have units consistent with the distance units, or a compile-time error will be thrown. For more information on C++ units, see :ref:`docs/software/basic-programming/cpp-units:The C++ Units Library`. -The ``TrapezoidProfileSubsystem`` class (`Java `__, `C++ `__) will automatically create and execute trapezoidal motion profiles to reach the user-provided goal state. To use the ``TrapezoidProfileSubsystem`` class, users must create a subclass of it. +The ``TrapezoidProfileSubsystem`` class (`Java `__, `C++ `__) will automatically create and execute trapezoidal motion profiles to reach the user-provided goal state. To use the ``TrapezoidProfileSubsystem`` class, users must create a subclass of it. Creating a TrapezoidProfileSubsystem ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -130,7 +130,7 @@ TrapezoidProfileCommand .. note:: In C++, the ``TrapezoidProfileCommand`` class is templated on the unit type used for distance measurements, which may be angular or linear. The passed-in values *must* have units consistent with the distance units, or a compile-time error will be thrown. For more information on C++ units, see :ref:`docs/software/basic-programming/cpp-units:The C++ Units Library`. -The ``TrapezoidProfileCommand`` class (`Java `__, `C++ `__) allows users to create a command that will execute a single ``TrapezoidProfile``, passing its current state at each iteration to a user-defined function. +The ``TrapezoidProfileCommand`` class (`Java `__, `C++ `__) allows users to create a command that will execute a single ``TrapezoidProfile``, passing its current state at each iteration to a user-defined function. As with ``TrapezoidProfileSubsystem``, users can create a ``TrapezoidProfileCommand`` by subclassing the ``TrapezoidProfileCommand`` class. However, as with many of the other command classes in the command-based library, users may want to save code by defining a ``TrapezoidProfileCommand`` :ref:`inline `. diff --git a/source/docs/software/commandbased/profilepid-subsystems-commands.rst b/source/docs/software/commandbased/profilepid-subsystems-commands.rst index 50e5bfa1abc..affd106a7cf 100644 --- a/source/docs/software/commandbased/profilepid-subsystems-commands.rst +++ b/source/docs/software/commandbased/profilepid-subsystems-commands.rst @@ -14,7 +14,7 @@ ProfiledPIDSubsystem .. note:: In C++, the ``ProfiledPIDSubsystem`` class is templated on the unit type used for distance measurements, which may be angular or linear. The passed-in values *must* have units consistent with the distance units, or a compile-time error will be thrown. For more information on C++ units, see :ref:`docs/software/basic-programming/cpp-units:The C++ Units Library`. -The ``ProfiledPIDSubsystem`` class (`Java `__, `C++ `__) allows users to conveniently create a subsystem with a built-in PIDController. In order to use the ``ProfiledPIDSubsystem`` class, users must create a subclass of it. +The ``ProfiledPIDSubsystem`` class (`Java `__, `C++ `__) allows users to conveniently create a subsystem with a built-in PIDController. In order to use the ``ProfiledPIDSubsystem`` class, users must create a subclass of it. Creating a ProfiledPIDSubsystem ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -150,7 +150,7 @@ ProfiledPIDCommand .. note:: In C++, the ``ProfiledPIDCommand`` class is templated on the unit type used for distance measurements, which may be angular or linear. The passed-in values *must* have units consistent with the distance units, or a compile-time error will be thrown. For more information on C++ units, see :ref:`docs/software/basic-programming/cpp-units:The C++ Units Library`. -The ``ProfiledPIDCommand`` class (`Java `__, `C++ `__) allows users to easily create commands with a built-in ProfiledPIDController. As with ``ProfiledPIDSubsystem``, users can create a ``ProfiledPIDCommmand`` by subclassing the ``ProfiledPIDCommand`` class. However, as with many of the other command classes in the command-based library, users may want to save code by defining it :ref:`inline `. +The ``ProfiledPIDCommand`` class (`Java `__, `C++ `__) allows users to easily create commands with a built-in ProfiledPIDController. As with ``ProfiledPIDSubsystem``, users can create a ``ProfiledPIDCommmand`` by subclassing the ``ProfiledPIDCommand`` class. However, as with many of the other command classes in the command-based library, users may want to save code by defining it :ref:`inline `. Creating a PIDCommand ^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/docs/software/commandbased/subsystems.rst b/source/docs/software/commandbased/subsystems.rst index 10a08669041..5815574c62e 100644 --- a/source/docs/software/commandbased/subsystems.rst +++ b/source/docs/software/commandbased/subsystems.rst @@ -5,12 +5,12 @@ Subsystems are the basic unit of robot organization in the command-based paradig Subsystems also serve as the backbone of the ``CommandScheduler``\ ’s resource management system. Commands may declare resource requirements by specifying which subsystems they interact with; the scheduler will never concurrently schedule more than one command that requires a given subsystem. An attempt to schedule a command that requires a subsystem that is already-in-use will either interrupt the currently-running command (if the command has been scheduled as interruptible), or else be ignored. -Subsystems can be associated with "default commands" that will be automatically scheduled when no other command is currently using the subsystem. This is useful for continuous "background" actions such as controlling the robot drive, or keeping an arm held at a setpoint. Similar functionality can be achieved in the subsystem’s ``periodic()`` method, which is run once per run of the scheduler; teams should try to be consistent within their codebase about which functionality is achieved through either of these methods. There is also a ``simulationPeriodic()`` method that is similar to ``periodic()`` except that it is only run during :doc:`Simulation ` and can be used to update the state of the robot. Subsystems are represented in the command-based library by the Subsystem interface (`Java `__, `C++ `__). +Subsystems can be associated with "default commands" that will be automatically scheduled when no other command is currently using the subsystem. This is useful for continuous "background" actions such as controlling the robot drive, or keeping an arm held at a setpoint. Similar functionality can be achieved in the subsystem’s ``periodic()`` method, which is run once per run of the scheduler; teams should try to be consistent within their codebase about which functionality is achieved through either of these methods. There is also a ``simulationPeriodic()`` method that is similar to ``periodic()`` except that it is only run during :doc:`Simulation ` and can be used to update the state of the robot. Subsystems are represented in the command-based library by the Subsystem interface (`Java `__, `C++ `__). Creating a Subsystem -------------------- -The recommended method to create a subsystem for most users is to subclass the abstract ``SubsystemBase`` class (`Java `__, `C++ `__), as seen in the command-based template (`Java `__, `C++ `__): +The recommended method to create a subsystem for most users is to subclass the abstract ``SubsystemBase`` class (`Java `__, `C++ `__), as seen in the command-based template (`Java `__, `C++ `__): .. tabs:: diff --git a/source/docs/software/commandbased/what-is-command-based.rst b/source/docs/software/commandbased/what-is-command-based.rst index bdce2ad0c4c..2456018435c 100644 --- a/source/docs/software/commandbased/what-is-command-based.rst +++ b/source/docs/software/commandbased/what-is-command-based.rst @@ -60,7 +60,7 @@ How Commands Are Run .. note:: For a more detailed explanation, see :doc:`command-scheduler`. -Commands are run by the ``CommandScheduler`` (`Java `__, `C++ `__), a singleton class that is at the core of the command-based library. The ``CommandScheduler`` is in charge of polling buttons for new commands to schedule, checking the resources required by those commands to avoid conflicts, executing currently-scheduled commands, and removing commands that have finished or been interrupted. The scheduler’s ``run()`` method may be called from any place in the user’s code; it is generally recommended to call it from the ``robotPeriodic()`` method of the ``Robot`` class, which is run at a default frequency of 50Hz (once every 20ms). +Commands are run by the ``CommandScheduler`` (`Java `__, `C++ `__), a singleton class that is at the core of the command-based library. The ``CommandScheduler`` is in charge of polling buttons for new commands to schedule, checking the resources required by those commands to avoid conflicts, executing currently-scheduled commands, and removing commands that have finished or been interrupted. The scheduler’s ``run()`` method may be called from any place in the user’s code; it is generally recommended to call it from the ``robotPeriodic()`` method of the ``Robot`` class, which is run at a default frequency of 50Hz (once every 20ms). Multiple commands can run concurrently, as long as they do not require the same resources on the robot. Resource management is handled on a per-subsystem basis: commands may specify which subsystems they interact with, and the scheduler will never schedule more than one command requiring a given subsystem at a time. This ensures that, for example, users will not end up with two different pieces of code attempting to set the same motor controller to different output values. If a new command is scheduled that requires a subsystem that is already in use, it will either interrupt the currently-running command that requires that subsystem (if the command has been scheduled as interruptible), or else it will not be scheduled. diff --git a/source/docs/software/dashboards/shuffleboard/advanced-usage/shuffleboard-tuning-pid.rst b/source/docs/software/dashboards/shuffleboard/advanced-usage/shuffleboard-tuning-pid.rst index 41913f36778..26bde2aad07 100644 --- a/source/docs/software/dashboards/shuffleboard/advanced-usage/shuffleboard-tuning-pid.rst +++ b/source/docs/software/dashboards/shuffleboard/advanced-usage/shuffleboard-tuning-pid.rst @@ -31,7 +31,7 @@ This is the test mode picture of a wrist subsystem that has a potentiometer as t Try various PID gains to get the desired motor performance. You can look at the video linked to at the beginning of this article or other sources on the internet to get the desired performance. -.. important:: The enable option does not affect the `PIDController `__ introduced in 2020, as the controller is updated every robot loop. See the example below on how to retain this fuctionality. +.. important:: The enable option does not affect the `PIDController `__ introduced in 2020, as the controller is updated every robot loop. See the example below on how to retain this fuctionality. Enable Functionality in the New PIDController --------------------------------------------- diff --git a/source/docs/software/dashboards/smartdashboard/setting-robot-preferences-from-smartdashboard.rst b/source/docs/software/dashboards/smartdashboard/setting-robot-preferences-from-smartdashboard.rst index 17aed84cae2..b043e241722 100644 --- a/source/docs/software/dashboards/smartdashboard/setting-robot-preferences-from-smartdashboard.rst +++ b/source/docs/software/dashboards/smartdashboard/setting-robot-preferences-from-smartdashboard.rst @@ -1,7 +1,7 @@ Setting Robot Preferences ========================= -The Robot Preferences (`Java `__, `C++ `__) class is used to store values in the flash memory on the roboRIO. The values might be for remembering preferences on the robot such as calibration settings for potentiometers, PID values, etc. that you would like to change without having to rebuild the program. The values can be viewed on the SmartDashboard and read and written by the robot program. +The Robot Preferences (`Java `__, `C++ `__) class is used to store values in the flash memory on the roboRIO. The values might be for remembering preferences on the robot such as calibration settings for potentiometers, PID values, etc. that you would like to change without having to rebuild the program. The values can be viewed on the SmartDashboard and read and written by the robot program. Reading and Writing Preferences ------------------------------- diff --git a/source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/pid-tuning-with-smartdashboard.rst b/source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/pid-tuning-with-smartdashboard.rst index 8abfeeaa66c..24493033db9 100644 --- a/source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/pid-tuning-with-smartdashboard.rst +++ b/source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/pid-tuning-with-smartdashboard.rst @@ -19,7 +19,7 @@ Viewing the PIDController in LiveWindow In Test mode, the PID Subsystems display their P, I, and D parameters that are set in the code. The P, I, and D values are the weights applied to the computed error (P), sum of errors over time (I), and the rate of change of errors (D). Each of those terms is multiplied by the weights and added together to form the motor value. Choosing the optimal P, I, and D values can be difficult and requires some amount of experimentation. The Test mode on the robot allows the values to be modified, and the mechanism response observed. -.. important:: The enable option does not affect the `PIDController `__ introduced in 2020, as the controller is updated every robot loop. See the example :ref:`here ` on how to retain this fuctionality. +.. important:: The enable option does not affect the `PIDController `__ introduced in 2020, as the controller is updated every robot loop. See the example :ref:`here ` on how to retain this fuctionality. Tuning the PIDController ------------------------ diff --git a/source/docs/software/hardware-apis/sensors/accelerometers-software.rst b/source/docs/software/hardware-apis/sensors/accelerometers-software.rst index 63169214676..b8dc87199b7 100644 --- a/source/docs/software/hardware-apis/sensors/accelerometers-software.rst +++ b/source/docs/software/hardware-apis/sensors/accelerometers-software.rst @@ -21,7 +21,7 @@ Three-axis accelerometers often require more complicated communications protocol AnalogAccelerometer ------------------- -The :code:`AnalogAccelerometer` class (`Java `__, `C++ `__) allows users to read values from a single-axis accelerometer that is connected to one of the roboRIO's analog inputs. +The :code:`AnalogAccelerometer` class (`Java `__, `C++ `__) allows users to read values from a single-axis accelerometer that is connected to one of the roboRIO's analog inputs. .. tabs:: @@ -59,7 +59,7 @@ If users have a 3-axis analog accelerometer, they can use three instances of thi The Accelerometer interface --------------------------- -All 3-axis accelerometers in WPILib implement the :code:`Accelerometer` interface (`Java `__, `C++ `__). This interface defines functionality and settings common to all supported 3-axis accelerometers. +All 3-axis accelerometers in WPILib implement the :code:`Accelerometer` interface (`Java `__, `C++ `__). This interface defines functionality and settings common to all supported 3-axis accelerometers. The :code:`Accelerometer` interface contains getters for the acceleration along each cardinal direction (x, y, and z), as well as a setter for the range of accelerations the accelerometer will measure. @@ -80,7 +80,7 @@ The :code:`Accelerometer` interface contains getters for the acceleration along ADXL345_I2C ^^^^^^^^^^^ -The :code:`ADXL345_I2C` class (`Java `__, `C++ `__) provides support for the ADXL345 accelerometer over the I2C communications bus. +The :code:`ADXL345_I2C` class (`Java `__, `C++ `__) provides support for the ADXL345 accelerometer over the I2C communications bus. .. tabs:: @@ -99,7 +99,7 @@ The :code:`ADXL345_I2C` class (`Java `__, `C++ `__) provides support for the ADXL345 accelerometer over the SPI communications bus. +The :code:`ADXL345_SPI` class (`Java `__, `C++ `__) provides support for the ADXL345 accelerometer over the SPI communications bus. .. tabs:: @@ -118,7 +118,7 @@ The :code:`ADXL345_SPI` class (`Java `__, `C++ `__) provides support for the ADXL362 accelerometer over the SPI communications bus. +The :code:`ADXL362` class (`Java `__, `C++ `__) provides support for the ADXL362 accelerometer over the SPI communications bus. .. tabs:: @@ -137,7 +137,7 @@ The :code:`ADXL362` class (`Java `__, `C++ `__) provides access to the roboRIO's own built-in accelerometer: +The :code:`BuiltInAccelerometer` class (`Java `__, `C++ `__) provides access to the roboRIO's own built-in accelerometer: .. tabs:: @@ -212,7 +212,7 @@ For detecting collisions, it is often more robust to measure the jerk than the a prevYAccel = yAccel; } -Most accelerometers legal for FRC use are quite noisy, and it is often a good idea to combine them with the :code:`LinearFilter` class (`Java `__, `C++ `__) to reduce the noise: +Most accelerometers legal for FRC use are quite noisy, and it is often a good idea to combine them with the :code:`LinearFilter` class (`Java `__, `C++ `__) to reduce the noise: .. tabs:: diff --git a/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst b/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst index c68ee08875d..68d81761bd1 100644 --- a/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst +++ b/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst @@ -12,7 +12,7 @@ The AnalogInput class .. note:: It is often more convenient to use the :doc:`Analog Potentiometers ` wrapper class than to use :code:`AnalogInput` directly, as it supports scaling to meaningful units. -Support for reading the voltages on the FPGA analog inputs is provided through the :code:`AnalogInput` class (`Java `__, `C++ `__). +Support for reading the voltages on the FPGA analog inputs is provided through the :code:`AnalogInput` class (`Java `__, `C++ `__). Initializing an AnalogInput ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst b/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst index cf1550423bd..f1feca95718 100644 --- a/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst +++ b/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst @@ -5,7 +5,7 @@ Analog Potentiometers - Software Potentiometers are variable resistors that allow information about position to be converted into an analog voltage signal. This signal can be read by the roboRIO to control whatever device is attached to the potentiometer. -While it is possible to read information from a potentiometer directly with an :doc:`analog-inputs-software`, WPILib provides an :code:`AnalogPotentiometer` class (`Java `__, `C++ `__) that handles re-scaling the values into meaningful units for the user. It is strongly encouraged to use this class. +While it is possible to read information from a potentiometer directly with an :doc:`analog-inputs-software`, WPILib provides an :code:`AnalogPotentiometer` class (`Java `__, `C++ `__) that handles re-scaling the values into meaningful units for the user. It is strongly encouraged to use this class. In fact, the :code:`AnalogPotentiometer` name is something of a misnomer - this class should be used for the vast majority of sensors that return their signal as a simple, linearly-scaled analog voltage. diff --git a/source/docs/software/hardware-apis/sensors/counters.rst b/source/docs/software/hardware-apis/sensors/counters.rst index de167209c66..858c35d2de0 100644 --- a/source/docs/software/hardware-apis/sensors/counters.rst +++ b/source/docs/software/hardware-apis/sensors/counters.rst @@ -4,7 +4,7 @@ Counters .. image:: images/counters/counters.png :alt: IO Diagram showing the up/down pulses the counter is counting. -The :code:`Counter` class (`Java `__, `C++ `__) is a versatile class that allows the counting of pulse edges on a digital input. :code:`Counter` is used as a component in several more-complicated WPILib classes (such as :ref:`Encoder ` and :ref:`Ultrasonic `), but is also quite useful on its own. +The :code:`Counter` class (`Java `__, `C++ `__) is a versatile class that allows the counting of pulse edges on a digital input. :code:`Counter` is used as a component in several more-complicated WPILib classes (such as :ref:`Encoder ` and :ref:`Ultrasonic `), but is also quite useful on its own. .. note:: There are a total of 8 counter units in the roboRIO FPGA, meaning no more than 8 :code:`Counter` objects may be instantiated at any one time, including those contained as resources in other WPILib objects. For detailed information on when a :code:`Counter` may be used by another object, refer to the official API documentation. diff --git a/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst b/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst index 4af4a402d9f..e8b8e01fa0f 100644 --- a/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst +++ b/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst @@ -7,7 +7,7 @@ Digital Inputs - Software The roboRIO's FPGA supports up to 26 digital inputs. 10 of these are made available through the built-in DIO ports on the RIO itself, while the other 16 are available through the MXP breakout port. -Digital inputs read one of two states - "high" or "low." By default, the built-in ports on the RIO will read "high" due to internal pull-up resistors (for more information, see :ref:`docs/hardware/sensors/digital-inputs-hardware:Digital Inputs - Hardware`). Accordingly, digital inputs are most-commonly used with switches of some sort. Support for this usage is provided through the :code:`DigitalInput` class (`Java `__, `C++ `__). +Digital inputs read one of two states - "high" or "low." By default, the built-in ports on the RIO will read "high" due to internal pull-up resistors (for more information, see :ref:`docs/hardware/sensors/digital-inputs-hardware:Digital Inputs - Hardware`). Accordingly, digital inputs are most-commonly used with switches of some sort. Support for this usage is provided through the :code:`DigitalInput` class (`Java `__, `C++ `__). The DigitalInput class ---------------------- @@ -48,7 +48,7 @@ Creating a DigitalInput from an AnalogInput .. note:: An :code:`AnalogTrigger` constructed with a port number argument can share that analog port with a separate :code:`AnalogInput`, but two `AnalogInput` objects may not share the same port. -Sometimes, it is desirable to use an analog input as a digital input. This can be easily achieved using the :code:`AnalogTrigger` class (`Java `__, `C++ `__). +Sometimes, it is desirable to use an analog input as a digital input. This can be easily achieved using the :code:`AnalogTrigger` class (`Java `__, `C++ `__). An :code:`AnalogTrigger` may be initialized as follows. As with :code:`AnalogPotentiometer`, an :code:`AnalogInput` may be passed explicitly if the user wishes to customize the sampling settings: diff --git a/source/docs/software/hardware-apis/sensors/encoders-software.rst b/source/docs/software/hardware-apis/sensors/encoders-software.rst index 2fdb3fd0671..73e9e10b891 100644 --- a/source/docs/software/hardware-apis/sensors/encoders-software.rst +++ b/source/docs/software/hardware-apis/sensors/encoders-software.rst @@ -18,7 +18,7 @@ The FPGA handles encoders either through a counter module or an encoder module, The Encoder class ----------------- -WPILib provides support for encoders through the :code:`Encoder` class (`Java `__, `C++ `__). This class provides a simple API for configuring and reading data from encoders. +WPILib provides support for encoders through the :code:`Encoder` class (`Java `__, `C++ `__). This class provides a simple API for configuring and reading data from encoders. .. important:: The ``Encoder`` class is only used for encoders that are plugged directly into the roboRIO! Please reference the appropriate vendors' documentation for using encoders plugged into motor controllers. diff --git a/source/docs/software/hardware-apis/sensors/gyros-software.rst b/source/docs/software/hardware-apis/sensors/gyros-software.rst index c4b746e1a78..9fda4a1a40c 100644 --- a/source/docs/software/hardware-apis/sensors/gyros-software.rst +++ b/source/docs/software/hardware-apis/sensors/gyros-software.rst @@ -10,7 +10,7 @@ A gyroscope, or "gyro," is an angular rate sensor typically used in robotics to The Gyro interface ------------------ -All natively-supported gyro objects in WPILib implement the :code:`Gyro` interface (`Java `__, `C++ `__). This interface provides methods for getting the current angular rate and heading, zeroing the current heading, and calibrating the gyro. +All natively-supported gyro objects in WPILib implement the :code:`Gyro` interface (`Java `__, `C++ `__). This interface provides methods for getting the current angular rate and heading, zeroing the current heading, and calibrating the gyro. .. note:: It is crucial that the robot remain stationary while calibrating a gyro. @@ -51,7 +51,7 @@ The ADIS16470 uses the :code:`ADIS16470_IMU` class and implements the :code:`Gyr ADXRS450_Gyro ^^^^^^^^^^^^^ -The :code:`ADXRS450_Gyro` class (`Java `__, `C++ `__) provides support for the Analog Devices ADXRS450 gyro available in the kit of parts, which connects over the SPI bus. +The :code:`ADXRS450_Gyro` class (`Java `__, `C++ `__) provides support for the Analog Devices ADXRS450 gyro available in the kit of parts, which connects over the SPI bus. .. note:: ADXRS450 Gyro accumulation is handled through special circuitry in the FPGA; accordingly only a single instance of :code:`ADXRS450_Gyro` may be used. @@ -70,7 +70,7 @@ The :code:`ADXRS450_Gyro` class (`Java `__, `C++ `__) provides support for any single-axis gyro with an analog output. +The :code:`AnalogGyro` class (`Java `__, `C++ `__) provides support for any single-axis gyro with an analog output. .. note:: Gyro accumulation is handled through special circuitry in the FPGA; accordingly, :code:`AnalogGyro`\`s may only be used on analog ports 0 and 1. diff --git a/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst b/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst index 5826b78e42c..8837877d74e 100644 --- a/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst +++ b/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst @@ -13,7 +13,7 @@ There are two primary types of ultrasonics supported natively by WPILib: Ping-response ultrasonics ------------------------- -The :code:`Ultrasonic` class (`Java `__, `C++ `__) provides support for ping-response ultrasonics. As ping-response ultrasonics (per the: name) require separate pins for both spending the ping and measuring the response, users must specify DIO pin numbers for both output and input when constructing an :code:`Ultrasonic` instance: +The :code:`Ultrasonic` class (`Java `__, `C++ `__) provides support for ping-response ultrasonics. As ping-response ultrasonics (per the: name) require separate pins for both spending the ping and measuring the response, users must specify DIO pin numbers for both output and input when constructing an :code:`Ultrasonic` instance: .. tabs:: diff --git a/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst b/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst index ad578239d30..8a94b394fd1 100644 --- a/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst +++ b/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst @@ -125,9 +125,9 @@ We will first reset our robot's pose to the starting pose of the trajectory. Thi :lineno-start: 86 -It is very important that the initial robot pose match the first pose in the trajectory. For the purposes of our example, the robot will be reliably starting at a position of ``(0,0)`` with a heading of ``0``. In actual use, however, it is probably not desirable to base your coordinate system on the robot position, and so the starting position for both the robot and the trajectory should be set to some other value. If you wish to use a trajectory that has been defined in robot-centric coordinates in such a situation, you can transform it to be relative to the robot's current pose using the ``transformBy`` method (`Java `_, `C++ `_). For more information about transforming trajectories, see :ref:`docs/software/advanced-controls/trajectories/transforming-trajectories:Transforming Trajectories`. +It is very important that the initial robot pose match the first pose in the trajectory. For the purposes of our example, the robot will be reliably starting at a position of ``(0,0)`` with a heading of ``0``. In actual use, however, it is probably not desirable to base your coordinate system on the robot position, and so the starting position for both the robot and the trajectory should be set to some other value. If you wish to use a trajectory that has been defined in robot-centric coordinates in such a situation, you can transform it to be relative to the robot's current pose using the ``transformBy`` method (`Java `_, `C++ `_). For more information about transforming trajectories, see :ref:`docs/software/advanced-controls/trajectories/transforming-trajectories:Transforming Trajectories`. -Now that we have a trajectory, we can create a command that, when executed, will follow that trajectory. To do this, we use the ``RamseteCommand`` class (`Java `__, `C++ `__) +Now that we have a trajectory, we can create a command that, when executed, will follow that trajectory. To do this, we use the ``RamseteCommand`` class (`Java `__, `C++ `__) .. tabs:: @@ -151,12 +151,12 @@ This declaration is fairly substantial, so we'll go through it argument-by-argum 1. The trajectory: This is the trajectory to be followed; accordingly, we pass the command the trajectory we just constructed in our earlier steps. 2. The pose supplier: This is a method reference (or lambda) to the :ref:`drive subsystem method that returns the pose `. The RAMSETE controller needs the current pose measurement to determine the required wheel outputs. -3. The RAMSETE controller: This is the ``RamseteController`` object (`Java `__, `C++ `__) that will perform the path-following computation that translates the current measured pose and trajectory state into a chassis speed setpoint. -4. The drive feedforward: This is a ``SimpleMotorFeedforward`` object (`Java `__, `C++ `__) that will automatically perform the correct feedforward calculation with the feedforward gains (``kS``, ``kV``, and ``kA``) that we obtained from the drive characterization tool. -5. The drive kinematics: This is the ``DifferentialDriveKinematics`` object (`Java `__, `C++ `__) that we constructed earlier in our constants file, and will be used to convert chassis speeds to wheel speeds. +3. The RAMSETE controller: This is the ``RamseteController`` object (`Java `__, `C++ `__) that will perform the path-following computation that translates the current measured pose and trajectory state into a chassis speed setpoint. +4. The drive feedforward: This is a ``SimpleMotorFeedforward`` object (`Java `__, `C++ `__) that will automatically perform the correct feedforward calculation with the feedforward gains (``kS``, ``kV``, and ``kA``) that we obtained from the drive characterization tool. +5. The drive kinematics: This is the ``DifferentialDriveKinematics`` object (`Java `__, `C++ `__) that we constructed earlier in our constants file, and will be used to convert chassis speeds to wheel speeds. 6. The wheel speed supplier: This is a method reference (or lambda) to the :ref:`drive subsystem method that returns the wheel speeds ` -7. The left-side PIDController: This is the ``PIDController`` object (`Java `__, `C++ `__) that will track the left-side wheel speed setpoint, using the P gain that we obtained from the drive characterization tool. -8. The right-side PIDController: This is the ``PIDController`` object (`Java `__, `C++ `__) that will track the right-side wheel speed setpoint, using the P gain that we obtained from the drive characterization tool. +7. The left-side PIDController: This is the ``PIDController`` object (`Java `__, `C++ `__) that will track the left-side wheel speed setpoint, using the P gain that we obtained from the drive characterization tool. +8. The right-side PIDController: This is the ``PIDController`` object (`Java `__, `C++ `__) that will track the right-side wheel speed setpoint, using the P gain that we obtained from the drive characterization tool. 9. The output consumer: This is a method reference (or lambda) to the :ref:`drive subsystem method that passes the voltage outputs to the drive motors `. 10. The robot drive: This is the drive subsystem itself, included to ensure the command does not operate on the drive at the same time as any other command that uses the drive. diff --git a/source/docs/software/vscode-overview/creating-robot-program.rst b/source/docs/software/vscode-overview/creating-robot-program.rst index b0110cebc7f..742d879b40a 100644 --- a/source/docs/software/vscode-overview/creating-robot-program.rst +++ b/source/docs/software/vscode-overview/creating-robot-program.rst @@ -12,14 +12,14 @@ TimedRobot ^^^^^^^^^^ Documentation: -`Java `__ -- `C++ `__ +`Java `__ +- `C++ `__ Source: `Java `__ - `C++ `__ -The :code:`TimedRobot` class is the the base class recommended for most users. It provides control of the robot program through a collection of :code:`init()`, :code:`periodic()`, and :code:`exit()` methods, which are called by WPILib during specific robot states (e.g. autonomous or teleoperated). The ``TimedRobot`` class also provides an example of retrieving autonomous routines through SendableChooser (`Java `__/ `C++ `__ +The :code:`TimedRobot` class is the the base class recommended for most users. It provides control of the robot program through a collection of :code:`init()`, :code:`periodic()`, and :code:`exit()` methods, which are called by WPILib during specific robot states (e.g. autonomous or teleoperated). The ``TimedRobot`` class also provides an example of retrieving autonomous routines through SendableChooser (`Java `__/ `C++ `__ .. note:: A `TimedRobot Skeleton` template is available that removes some informative comments and the autonomous example. You can use this if you're already familiar with `TimedRobot`. The example shown below is of `TimedRobot Skeleton`. @@ -91,7 +91,7 @@ The :code:`TimedRobot` class is the the base class recommended for most users. Periodic methods are called every 20 ms by default. This can be changed by calling the superclass constructor with the new desired update rate. -.. danger:: Changing your robot rate can cause some unintended behavior (loop overruns). Teams can also use `Notifiers `__ to schedule methods at a custom rate. +.. danger:: Changing your robot rate can cause some unintended behavior (loop overruns). Teams can also use `Notifiers `__ to schedule methods at a custom rate. .. tabs:: @@ -109,8 +109,8 @@ RobotBase ^^^^^^^^^ Documentation: -`Java `__ -- `C++ `__ +`Java `__ +- `C++ `__ Source: `Java `__ diff --git a/source/docs/software/what-is-wpilib.rst b/source/docs/software/what-is-wpilib.rst index c987ac7b68f..ea6ea3f4c4b 100644 --- a/source/docs/software/what-is-wpilib.rst +++ b/source/docs/software/what-is-wpilib.rst @@ -27,6 +27,6 @@ The Java and C++ source code can be found in the WPILibJ and WPILibC source dire While users are strongly encouraged to read the source code to resolve detailed questions about library functionality, more-concise documentation can be found on the official documentation pages for WPILibJ and WPILibC: - - `Java documentation `__ + - `Java documentation `__ - - `C++ documentation `__ + - `C++ documentation `__ diff --git a/source/docs/yearly-overview/yearly-changelog.rst b/source/docs/yearly-overview/yearly-changelog.rst index cc38a0c33d6..a19dae81d9f 100644 --- a/source/docs/yearly-overview/yearly-changelog.rst +++ b/source/docs/yearly-overview/yearly-changelog.rst @@ -31,7 +31,7 @@ General Library - Added C++ TankDrive example - Added ``PS4Controller`` controller class - Added better message for when an I2C port is out of range -- Added ``Debouncer`` (`Java `__, `C++ `__) class. This helps with filtering rising and falling edges when dealing with boolean values +- Added ``Debouncer`` (`Java `__, `C++ `__) class. This helps with filtering rising and falling edges when dealing with boolean values - Added ``PneumaticHub`` class for use with the REV Pneumatic Hub - GenericHID has been updated to static functions to use for non-defined controller types. - ``XboxController`` has migrated away from taking arguments in functions and instead has functions with no arguments. An example conversion is below: @@ -40,7 +40,7 @@ General Library - ``getInstance()`` functions in ``CameraServer``, ``DriverStation``, ``LiveWindow``, ``Preferences``, ``SendableRegistry``, have been deprecated and replaced with static functions - ``Timer::HasPeriodPassed()`` and ``Timer.hasPeriodPassed()`` have been deprecated. Use ``AdvanceIfElapsed()`` instead -- Several new classes have been added to enable simpler access to ``Counter``: ``ExternalDirectionCounter`` (`Java `__/ `C++ `__), ``Tachometer`` (`Java `__/ `C++ `__), and ``UpDownCounter`` (`Java `__/ `C++ `__) +- Several new classes have been added to enable simpler access to ``Counter``: ``ExternalDirectionCounter`` (`Java `__/ `C++ `__), ``Tachometer`` (`Java `__/ `C++ `__), and ``UpDownCounter`` (`Java `__/ `C++ `__) - ``DutyCycleEncoder``: add support for setting duty cycle range - Added ``ADIS16448_IMU`` and ``ADIS16470_IMU`` classes. diff --git a/source/index.rst b/source/index.rst index 4beab3262bb..fb951aa8d89 100644 --- a/source/index.rst +++ b/source/index.rst @@ -167,14 +167,14 @@ Community translations can be found in a variety of languages in the bottom-left .. div:: col-sm pl-1 pr-1 - .. link-button:: https://first.wpi.edu/wpilib/allwpilib/docs/development/java/index.html + .. link-button:: https://first.wpi.edu/wpilib/allwpilib/docs/release/java/index.html :type: url :text: Java :classes: btn-outline-primary btn-block .. div:: col-sm pl-1 pr-1 - .. link-button:: https://first.wpi.edu/wpilib/allwpilib/docs/development/cpp/index.html + .. link-button:: https://first.wpi.edu/wpilib/allwpilib/docs/release/cpp/index.html :type: url :text: C++ :classes: btn-outline-primary btn-block @@ -280,8 +280,8 @@ Community translations can be found in a variety of languages in the bottom-left :caption: API Docs :hidden: - WPILib Java API Docs - WPILib C++ API Docs + WPILib Java API Docs + WPILib C++ API Docs .. toctree:: :maxdepth: 1 diff --git a/source/stubs/api-docs-stub.rst b/source/stubs/api-docs-stub.rst index 1e66088d1e4..e88f7c86214 100644 --- a/source/stubs/api-docs-stub.rst +++ b/source/stubs/api-docs-stub.rst @@ -9,5 +9,5 @@ Java and CSS class documentation. :maxdepth: 1 :hidden: - WPILib Java API Docs - WPILib C++ API Docs + WPILib Java API Docs + WPILib C++ API Docs