From 6ae1c5bd65b71e9a46449839a6c06dd3502f8a1b Mon Sep 17 00:00:00 2001 From: sciencewhiz Date: Tue, 31 Dec 2024 21:52:50 -0800 Subject: [PATCH] Update API docs to release (#2894) --- .../networking-utilities/portforwarding.rst | 2 +- .../controllers/bang-bang.rst | 2 +- .../combining-feedforward-feedback.rst | 2 +- .../controllers/feedforward.rst | 8 ++-- .../controllers/pidcontroller.rst | 2 +- .../controllers/profiled-pidcontroller.rst | 2 +- .../controllers/trapezoidal-profiles.rst | 6 +-- .../advanced-controls/filters/debouncer.rst | 2 +- .../filters/linear-filter.rst | 2 +- .../filters/median-filter.rst | 2 +- .../filters/slew-rate-limiter.rst | 2 +- .../advanced-controls/geometry/pose.rst | 6 +-- .../geometry/transformations.rst | 2 +- .../trajectories/ramsete.rst | 2 +- .../trajectories/trajectory-generation.rst | 2 +- .../basic-programming/alliancecolor.rst | 2 +- .../software/basic-programming/java-units.rst | 8 ++-- .../basic-programming/robot-preferences.rst | 2 +- .../software/can-devices/pneumatic-hub.rst | 2 +- .../can-devices/pneumatics-control-module.rst | 2 +- .../can-devices/power-distribution-module.rst | 2 +- .../binding-commands-to-triggers.rst | 8 ++-- .../commandbased/command-compositions.rst | 36 ++++++++-------- .../commandbased/command-scheduler.rst | 14 +++---- .../docs/software/commandbased/commands.rst | 42 +++++++++---------- .../profile-subsystems-commands.rst | 2 +- .../docs/software/commandbased/subsystems.rst | 6 +-- .../commandbased/what-is-command-based.rst | 2 +- .../shuffleboard-tuning-pid.rst | 2 +- .../pid-tuning-with-smartdashboard.rst | 2 +- .../driver-station-errors-warnings.rst | 2 +- .../motors/wpi-drive-classes.rst | 2 +- .../hardware-apis/pneumatics/pressure.rst | 2 +- .../hardware-apis/pneumatics/solenoids.rst | 4 +- .../sensors/accelerometers-software.rst | 12 +++--- .../sensors/analog-inputs-software.rst | 2 +- .../analog-potentiometers-software.rst | 2 +- .../hardware-apis/sensors/counters.rst | 2 +- .../sensors/digital-inputs-software.rst | 4 +- .../sensors/encoders-software.rst | 6 +-- .../hardware-apis/sensors/gyros-software.rst | 8 ++-- .../sensors/ultrasonics-software.rst | 2 +- .../intro-and-chassis-speeds.rst | 2 +- source/docs/software/networktables/index.rst | 2 +- .../networktables/multiple-instances.rst | 2 +- .../networktables/networktables-intro.rst | 2 +- .../networktables/publish-and-subscribe.rst | 12 +++--- .../networktables/tables-and-topics.rst | 6 +-- .../creating-following-trajectory.rst | 14 +++---- .../software/telemetry/datalog-download.rst | 2 +- source/docs/software/telemetry/datalog.rst | 4 +- .../software/telemetry/persistent-alerts.rst | 2 +- .../robot-telemetry-with-annotations.rst | 2 +- .../robot-telemetry-with-sendable.rst | 2 +- .../telemetry/writing-sendable-classes.rst | 2 +- .../creating-robot-program.rst | 16 +++---- source/docs/software/what-is-wpilib.rst | 4 +- source/index.rst | 8 ++-- source/stubs/api-docs-stub.rst | 4 +- 59 files changed, 155 insertions(+), 155 deletions(-) diff --git a/source/docs/networking/networking-utilities/portforwarding.rst b/source/docs/networking/networking-utilities/portforwarding.rst index 4e9810d59c..18197ac176 100644 --- a/source/docs/networking/networking-utilities/portforwarding.rst +++ b/source/docs/networking/networking-utilities/portforwarding.rst @@ -4,7 +4,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/net/PortForwarder.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classwpi_1_1_port_forwarder.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/net/PortForwarder.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_port_forwarder.html)) 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)``. .. tab-set-code:: diff --git a/source/docs/software/advanced-controls/controllers/bang-bang.rst b/source/docs/software/advanced-controls/controllers/bang-bang.rst index 2d85acc59d..2b9f0bae10 100644 --- a/source/docs/software/advanced-controls/controllers/bang-bang.rst +++ b/source/docs/software/advanced-controls/controllers/bang-bang.rst @@ -6,7 +6,7 @@ This may initially seem like a poor control strategy, as PID loops are known to However, when controlling the velocity of high-inertia mechanisms under varying loads (like a shooter flywheel), a bang-bang controller can yield faster recovery time and thus better/more consistent performance than a proportional controller. Unlike an ordinary P loop, a bang-bang controller is *asymmetric* - that is, the controller turns on when the process variable is below the setpoint, and does nothing otherwise. This allows the control effort in the forward direction to be made as large as possible without risking destructive oscillations as the control loop tries to correct a resulting overshoot. -Asymmetric bang-bang control is provided in WPILib by the BangBangController class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/BangBangController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_bang_bang_controller.html), :external:py:class:`Python `). +Asymmetric bang-bang control is provided in WPILib by the BangBangController class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/BangBangController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_bang_bang_controller.html), :external:py:class:`Python `). ## Constructing a BangBangController 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 108c5cd64a..34cdf69246 100644 --- a/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst +++ b/source/docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst @@ -33,7 +33,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/motorcontrol/MotorController.html#setVoltage(double)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_motor_controller.html#a613c23a3336e103876e433bcb8b5ad3e), :external:py:meth:`Python `) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/motorcontrol/MotorController.html#setVoltage(double)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_motor_controller.html#a613c23a3336e103876e433bcb8b5ad3e), :external:py:meth:`Python `) 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 8e66e14ab1..b2fcf731ac 100644 --- a/source/docs/software/advanced-controls/controllers/feedforward.rst +++ b/source/docs/software/advanced-controls/controllers/feedforward.rst @@ -16,9 +16,9 @@ The WPILib feedforward classes closely match the available mechanism characteriz WPILib currently provides the following three helper classes for feedforward control: -* `SimpleMotorFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/SimpleMotorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_simple_motor_feedforward.html), :external:py:class:`Python `) -* `ArmFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/ArmFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_arm_feedforward.html), :external:py:class:`Python `) -* `ElevatorFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/ElevatorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_elevator_feedforward.html), :external:py:class:`Python `) +* `SimpleMotorFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/SimpleMotorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_simple_motor_feedforward.html), :external:py:class:`Python `) +* `ArmFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/ArmFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_arm_feedforward.html), :external:py:class:`Python `) +* `ElevatorFeedforward`_ (Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/ElevatorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_elevator_feedforward.html), :external:py:class:`Python `) ## SimpleMotorFeedforward @@ -200,7 +200,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/motorcontrol/MotorController.html#setVoltage(double)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_motor_controller.html#a613c23a3336e103876e433bcb8b5ad3e), :external:py:meth:`Python `) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/motorcontrol/MotorController.html#setVoltage(double)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_motor_controller.html#a613c23a3336e103876e433bcb8b5ad3e), :external:py:meth:`Python `) 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 adda28cba7..9db0a9b238 100644 --- a/source/docs/software/advanced-controls/controllers/pidcontroller.rst +++ b/source/docs/software/advanced-controls/controllers/pidcontroller.rst @@ -4,7 +4,7 @@ .. note:: For a guide on implementing PID control through the :ref:`command-based framework `, see :ref:`docs/software/commandbased/pid-subsystems-commands:PID Control in Command-based`. -WPILib supports PID control of mechanisms through the ``PIDController`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_p_i_d_controller.html), :external:py:class:`Python `). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html), :external:py:class:`Python `). 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 3cb7307793..67925e40a3 100644 --- a/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst +++ b/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst @@ -4,7 +4,7 @@ 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/ProfiledPIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_profiled_p_i_d_controller.html), :external:py:class:`Python `) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/ProfiledPIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_profiled_p_i_d_controller.html), :external:py:class:`Python `) 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 00d12681a9..3e232877a7 100644 --- a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst +++ b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst @@ -10,7 +10,7 @@ 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/trajectory/TrapezoidProfile.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_trapezoid_profile.html), :external:py:class:`Python `). +To help users do this, WPILib provides a ``TrapezoidProfile`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/TrapezoidProfile.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trapezoid_profile.html), :external:py:class:`Python `). ## Creating a TrapezoidProfile @@ -20,7 +20,7 @@ To help users do this, WPILib provides a ``TrapezoidProfile`` class ([Java](http .. 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/trajectory/TrapezoidProfile.Constraints.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_trapezoid_profile_1_1_constraints.html), :external:py:class:`Python `): +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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/TrapezoidProfile.Constraints.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trapezoid_profile_1_1_constraints.html), :external:py:class:`Python `): .. tab-set-code:: @@ -48,7 +48,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/trajectory/TrapezoidProfile.State.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_trapezoid_profile_1_1_state.html), :external:py:class:`Python `). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/TrapezoidProfile.State.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trapezoid_profile_1_1_state.html), :external:py:class:`Python `). Each state has a position and a velocity: .. tab-set-code:: diff --git a/source/docs/software/advanced-controls/filters/debouncer.rst b/source/docs/software/advanced-controls/filters/debouncer.rst index 2640ab3a8e..7c08004003 100644 --- a/source/docs/software/advanced-controls/filters/debouncer.rst +++ b/source/docs/software/advanced-controls/filters/debouncer.rst @@ -2,7 +2,7 @@ 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/filter/Debouncer.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_debouncer.html), :external:py:class:`Python `), 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/filter/Debouncer.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_debouncer.html), :external:py:class:`Python `), 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 89670dde5f..44e5952fb0 100644 --- a/source/docs/software/advanced-controls/filters/linear-filter.rst +++ b/source/docs/software/advanced-controls/filters/linear-filter.rst @@ -10,7 +10,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/filter/LinearFilter.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_linear_filter.html), , :external:py:class:`Python `). +Linear filters are supported in WPILib through the ``LinearFilter`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/filter/LinearFilter.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_linear_filter.html), , :external:py:class:`Python `). ## 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 69ea251aaf..a4ba7928e2 100644 --- a/source/docs/software/advanced-controls/filters/median-filter.rst +++ b/source/docs/software/advanced-controls/filters/median-filter.rst @@ -7,7 +7,7 @@ A `statistically robust` alternative to the :ref:`moving-average filter `). +The median filter is supported in WPILib through the ``MedianFilter`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/filter/MedianFilter.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_median_filter.html), , :external:py:class:`Python `). ## 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 2b091adaf2..4c75fddb6a 100644 --- a/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst +++ b/source/docs/software/advanced-controls/filters/slew-rate-limiter.rst @@ -6,7 +6,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/filter/SlewRateLimiter.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_slew_rate_limiter.html), :external:py:class:`Python `). +Slew rate limiting is supported in WPILib through the ``SlewRateLimiter`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/filter/SlewRateLimiter.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_slew_rate_limiter.html), :external:py:class:`Python `). ## Creating a SlewRateLimiter diff --git a/source/docs/software/advanced-controls/geometry/pose.rst b/source/docs/software/advanced-controls/geometry/pose.rst index 65a1a055dc..5016139aa9 100644 --- a/source/docs/software/advanced-controls/geometry/pose.rst +++ b/source/docs/software/advanced-controls/geometry/pose.rst @@ -2,7 +2,7 @@ ## Translation -Translation in 2 dimensions is represented by WPILib's ``Translation2d`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/geometry/Translation2d.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_translation2d.html), :external:py:class:`Python `). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/geometry/Translation2d.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_translation2d.html), :external:py:class:`Python `). 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. @@ -10,7 +10,7 @@ You can get the distance to another ``Translation2d`` object by using the ``getD ## Rotation -Rotation in 2 dimensions is represented by WPILib's ``Rotation2d`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/geometry/Rotation2d.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_rotation2d.html), :external:py:class:`Python `). 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 represented by WPILib's ``Rotation2d`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/geometry/Rotation2d.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_rotation2d.html), :external:py:class:`Python `). 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 constructor in Java/Python 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. @@ -18,4 +18,4 @@ Rotation in 2 dimensions is represented by WPILib's ``Rotation2d`` class ([Java] ## Pose -Pose is a combination of both translation and rotation and is represented by the ``Pose2d`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/geometry/Pose2d.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_pose2d.html), :external:py:class:`Python `). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/geometry/Pose2d.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_pose2d.html), :external:py:class:`Python `). 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 9d81d61d12..8139279528 100644 --- a/source/docs/software/advanced-controls/geometry/transformations.rst +++ b/source/docs/software/advanced-controls/geometry/transformations.rst @@ -22,7 +22,7 @@ Transformations for ``Rotation2d`` are just arithmetic operations on the angle m ## Transform2d and Twist2d -WPILib provides 2 classes, ``Transform2d`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/geometry/Transform2d.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_transform2d.html), :external:py:class:`Python `), which represents a transformation to a pose, and ``Twist2d`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/geometry/Twist2d.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/structfrc_1_1_twist2d.html), :external:py:class:`Python `) which represents a movement along an arc. ``Transform2d`` and ``Twist2d`` all have x, y and :math:`\theta` components. +WPILib provides 2 classes, ``Transform2d`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/geometry/Transform2d.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_transform2d.html), :external:py:class:`Python `), which represents a transformation to a pose, and ``Twist2d`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/geometry/Twist2d.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/structfrc_1_1_twist2d.html), :external:py:class:`Python `) 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 9f54540b6e..53072f9c6f 100644 --- a/source/docs/software/advanced-controls/trajectories/ramsete.rst +++ b/source/docs/software/advanced-controls/trajectories/ramsete.rst @@ -88,7 +88,7 @@ The returned adjusted speeds can be converted to usable speeds using the kinemat right = wheelSpeeds.right ``` -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++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_p_i_d_controller.html), [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html), :external:py:class:`Python `) 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++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html), [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), :external:py:class:`Python `) 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 For the sake of ease for users, a ``RamseteCommand`` class is built in to WPILib. For a full tutorial on implementing a path-following autonomous using RamseteCommand, see :ref:`docs/software/pathplanning/trajectory-tutorial/index:Trajectory Tutorial`. diff --git a/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst b/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst index 532189ca7f..62e9f69c85 100644 --- a/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst +++ b/source/docs/software/advanced-controls/trajectories/trajectory-generation.rst @@ -61,7 +61,7 @@ Here is an example of generating a trajectory using clamped cubic splines for th :language: python :lines: 5-20 -.. note:: The Java code utilizes the [Units](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/util/Units.html) utility, for easy unit conversions. +.. note:: The Java code utilizes the [Units](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/util/Units.html) 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 in the ``Robot`` constructor. diff --git a/source/docs/software/basic-programming/alliancecolor.rst b/source/docs/software/basic-programming/alliancecolor.rst index 87ea884f42..79cf815a77 100644 --- a/source/docs/software/basic-programming/alliancecolor.rst +++ b/source/docs/software/basic-programming/alliancecolor.rst @@ -1,6 +1,6 @@ # Get Alliance Color -The ``DriverStation`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DriverStation.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_driver_station.html), :py:class:`Python `) has many useful features for getting data from the Driver Station computer. One of the most important features is ``getAlliance`` (Java & Python) / ``GetAlliance`` (C++). +The ``DriverStation`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DriverStation.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_driver_station.html), :py:class:`Python `) has many useful features for getting data from the Driver Station computer. One of the most important features is ``getAlliance`` (Java & Python) / ``GetAlliance`` (C++). Note that there are three cases: red, blue, and no color yet. It is important that code handles the third case correctly because the alliance color will not be available until the Driver Station connects. In particular, code should not assume that the alliance color will be available during constructor methods or `robotInit`, but it should be available by the time `autoInit` or `teleopInit` is called. FMS will set the alliance color automatically; when not connected to FMS, the alliance color can be set from the Driver Station (see :ref:`"Team Station" on the Operation Tab `). diff --git a/source/docs/software/basic-programming/java-units.rst b/source/docs/software/basic-programming/java-units.rst index 865dde2528..6166d5b54a 100644 --- a/source/docs/software/basic-programming/java-units.rst +++ b/source/docs/software/basic-programming/java-units.rst @@ -29,9 +29,9 @@ These concepts are used within the Units Library. For example, the **measure** * The Java units library is available in the ``edu.wpi.first.units`` package. The most relevant classes are: -- The various classes for predefined dimensions, such as [DistanceUnit](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/DistanceUnit.html) and [TimeUnit](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/TimeUnit.html) -- [Units](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/Units.html), which contains a set of predefined units. Take a look a the [Units javadoc](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/Units.html) to browse the available units and their types. -- [Measure](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/Measure.html), which is used to tag a value with a unit, and the dimension-specific implementations like [Distance](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/measure/Distance.html) and [Time](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/measure/Time.html) +- The various classes for predefined dimensions, such as [DistanceUnit](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/DistanceUnit.html) and [TimeUnit](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/TimeUnit.html) +- [Units](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/Units.html), which contains a set of predefined units. Take a look a the [Units javadoc](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/Units.html) to browse the available units and their types. +- [Measure](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/Measure.html), which is used to tag a value with a unit, and the dimension-specific implementations like [Distance](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/measure/Distance.html) and [Time](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/measure/Time.html) .. note:: It is recommended to static import ``edu.wpi.first.units.Units.*`` to get full access to all the predefined units. @@ -140,7 +140,7 @@ To reduce the number of object instances you create, and reduce memory usage, a ``MutableMeasure`` allows the internal state of the object to be updated, such as with the results of arithmetic operations, to avoid allocating new objects. Special care needs to be taken when mutating a measure because it will change the value every place that instance is referenced. If the object will be exposed as part of a public method, have that method return a regular ``Measure`` in its signature to prevent the caller from modifying your internal state. Extra methods are available on ``MutableMeasure`` for updating the internal value. Note that these methods all begin with the ``mut_`` prefix - this is to make it obvious that these methods will be mutating the object and are potentially unsafe! -For the full list of methods and API documentation, see [the MutableMeasure API documentation](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/units/MutableMeasure.html) +For the full list of methods and API documentation, see [the MutableMeasure API documentation](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/units/MutableMeasure.html) +-------------------------------+--------------------------------------------------------------------------------------------------+ | ``mut_plus(double, Unit)`` | Increments the internal value by an amount in another unit. The internal unit will stay the same | diff --git a/source/docs/software/basic-programming/robot-preferences.rst b/source/docs/software/basic-programming/robot-preferences.rst index fb96823b6b..c1a77875e9 100644 --- a/source/docs/software/basic-programming/robot-preferences.rst +++ b/source/docs/software/basic-programming/robot-preferences.rst @@ -1,6 +1,6 @@ # Setting Robot Preferences -The Robot Preferences ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Preferences.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_preferences.html)) 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, setpoints, etc. that you would like to change without having to rebuild the program. The values can be viewed on SmartDashboard or Shuffleboard and read and written by the robot program. +The Robot Preferences ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Preferences.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_preferences.html)) 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, setpoints, etc. that you would like to change without having to rebuild the program. The values can be viewed on SmartDashboard or Shuffleboard and read and written by the robot program. This example shows how to utilize Preferences to change the setpoint of a PID controller and the P constant. The code examples are adapted from the Arm Simulation example ([Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/armsimulation/Robot.java), [C++](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibcExamples/src/main/cpp/examples/ArmSimulation/cpp/Robot.cpp)). You can run the Arm Simulation example in the Robot Simulator to see how to use the preference class and interact with it using the dashboards without needing a robot. diff --git a/source/docs/software/can-devices/pneumatic-hub.rst b/source/docs/software/can-devices/pneumatic-hub.rst index e3ad57047e..d90aead1af 100644 --- a/source/docs/software/can-devices/pneumatic-hub.rst +++ b/source/docs/software/can-devices/pneumatic-hub.rst @@ -6,7 +6,7 @@ The Pneumatic Hub (:term:`PH`) is a :term:`CAN`-based device that provides complete control over the compressor and up to 16 solenoids per module. The PH 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Compressor.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_compressor.html), :external:py:class:`Python `), and the Solenoids are handled by the :code:`Solenoid` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Solenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_solenoid.html), :external:py:class:`Python `) and :code:`DoubleSolenoid` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DoubleSolenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_double_solenoid.html), :external:py:class:`Python `) classes. +The closed loop control of the Compressor and Pressure switch is handled by the :code:`Compressor` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Compressor.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_compressor.html), :external:py:class:`Python `), and the Solenoids are handled by the :code:`Solenoid` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Solenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_solenoid.html), :external:py:class:`Python `) and :code:`DoubleSolenoid` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DoubleSolenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_double_solenoid.html), :external:py:class:`Python `) classes. An additional PH module can be used where the module's 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/pneumatics-control-module.rst b/source/docs/software/can-devices/pneumatics-control-module.rst index 23d2e827ae..207c2dda91 100644 --- a/source/docs/software/can-devices/pneumatics-control-module.rst +++ b/source/docs/software/can-devices/pneumatics-control-module.rst @@ -6,7 +6,7 @@ The Pneumatics Control Module (:term:`PCM`) is a :term:`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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Compressor.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_compressor.html), :external:py:class:`Python `), and the Solenoids are handled by the :code:`Solenoid` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Solenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_solenoid.html), :external:py:class:`Python `) and :code:`DoubleSolenoid` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DoubleSolenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_double_solenoid.html), :external:py:class:`Python `) classes. +The closed loop control of the Compressor and Pressure switch is handled by the :code:`Compressor` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Compressor.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_compressor.html), :external:py:class:`Python `), and the Solenoids are handled by the :code:`Solenoid` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Solenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_solenoid.html), :external:py:class:`Python `) and :code:`DoubleSolenoid` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DoubleSolenoid.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_double_solenoid.html), :external:py:class:`Python `) classes. An additional PCM module can be used where the module's 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 af43be0391..c141fa4cf0 100644 --- a/source/docs/software/can-devices/power-distribution-module.rst +++ b/source/docs/software/can-devices/power-distribution-module.rst @@ -4,7 +4,7 @@ The CTRE Power Distribution Panel (:term:`PDP`) and Rev Power Distribution Hub ( ## Creating a Power Distribution Object -To use the either Power Distribution module, create an instance of the :code:`PowerDistribution` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/PowerDistribution.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_power_distribution.html), :external:py:class:`Python `). With no arguments, the Power Distribution object will be detected, and must use CAN ID of 0 for CTRE or 1 for REV. If the CAN ID is non-default, additional constructors are available to specify the CAN ID and type. +To use the either Power Distribution module, create an instance of the :code:`PowerDistribution` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/PowerDistribution.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_power_distribution.html), :external:py:class:`Python `). With no arguments, the Power Distribution object will be detected, and must use CAN ID of 0 for CTRE or 1 for REV. If the CAN ID is non-default, additional constructors are available to specify the CAN ID and type. .. tab-set-code:: diff --git a/source/docs/software/commandbased/binding-commands-to-triggers.rst b/source/docs/software/commandbased/binding-commands-to-triggers.rst index 65486766c9..a4d4c7da95 100644 --- a/source/docs/software/commandbased/binding-commands-to-triggers.rst +++ b/source/docs/software/commandbased/binding-commands-to-triggers.rst @@ -4,7 +4,7 @@ Apart from autonomous commands, which are scheduled at the start of the autonomo As mentioned earlier, command-based is a :term:`declarative programming` 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/Trigger.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_trigger.html)). +Command binding is done through the ``Trigger`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/Trigger.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_trigger.html)). ## Getting a Trigger Instance @@ -12,7 +12,7 @@ To bind commands to conditions, we need a ``Trigger`` object. There are three wa ### HID Factories -The command-based HID classes contain factory methods returning a ``Trigger`` for a given button. ``CommandGenericHID`` has an index-based ``button(int)`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/CommandGenericHID.html#button(int)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_generic_h_i_d.html#a661f49794a913615c94fba927e1072a8)), and its subclasses ``CommandXboxController`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/CommandXboxController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_xbox_controller.html)), ``CommandPS4Controller`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/CommandPS4Controller.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_p_s4_controller.html)), and ``CommandJoystick`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/CommandJoystick.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_joystick.html)) have named factory methods for each button. +The command-based HID classes contain factory methods returning a ``Trigger`` for a given button. ``CommandGenericHID`` has an index-based ``button(int)`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/CommandGenericHID.html#button(int)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_generic_h_i_d.html#a661f49794a913615c94fba927e1072a8)), and its subclasses ``CommandXboxController`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/CommandXboxController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_xbox_controller.html)), ``CommandPS4Controller`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/CommandPS4Controller.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_p_s4_controller.html)), and ``CommandJoystick`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/CommandJoystick.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_joystick.html)) have named factory methods for each button. .. tab-set-code:: @@ -28,7 +28,7 @@ The command-based HID classes contain factory methods returning a ``Trigger`` fo ### JoystickButton -Alternatively, the :ref:`regular HID classes ` can be used and passed to create an instance of ``JoystickButton`` [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/button/JoystickButton.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_joystick_button.html)), a constructor-only subclass of ``Trigger``: +Alternatively, the :ref:`regular HID classes ` can be used and passed to create an instance of ``JoystickButton`` [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/button/JoystickButton.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_joystick_button.html)), a constructor-only subclass of ``Trigger``: .. tab-set-code:: @@ -108,7 +108,7 @@ The ``whileFalse`` binding is identical, only that it schedules on ``false`` and ### toggleOnTrue -This binding toggles a command, scheduling it when a trigger changes from ``false`` to ``true`` (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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/StartEndCommand.html) or a [ConditionalCommand](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ConditionalCommand.html) 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 ``false`` to ``true`` (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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/StartEndCommand.html) or a [ConditionalCommand](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ConditionalCommand.html) is a good way to specify the commands that you want to be want to be toggled between. .. tab-set-code:: diff --git a/source/docs/software/commandbased/command-compositions.rst b/source/docs/software/commandbased/command-compositions.rst index f182c03f1f..a351ccd8f6 100644 --- a/source/docs/software/commandbased/command-compositions.rst +++ b/source/docs/software/commandbased/command-compositions.rst @@ -35,7 +35,7 @@ The command-based library includes various composition types. All of them can be ### Repeating -The ``repeatedly()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#repeatedly()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#acc156a5299699110729918c3aa2b2694), :external:py:meth:`Python `), backed by the ``RepeatCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/RepeatCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_repeat_command.html), :external:py:class:`Python `) restarts the command each time it ends, so that it runs until interrupted. +The ``repeatedly()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#repeatedly()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#acc156a5299699110729918c3aa2b2694), :external:py:meth:`Python `), backed by the ``RepeatCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RepeatCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_repeat_command.html), :external:py:class:`Python `) restarts the command each time it ends, so that it runs until interrupted. .. tab-set-code:: @@ -56,9 +56,9 @@ The ``repeatedly()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/ ### Sequence -The ``Sequence`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#sequence(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#ac588bdc52a86a4683b89c28dcadea458), :external:py:func:`Python `), backed by the ``SequentialCommandGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/SequentialCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_sequential_command_group.html), :external:py:class:`Python `), 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!). +The ``Sequence`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#sequence(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ac588bdc52a86a4683b89c28dcadea458), :external:py:func:`Python `), backed by the ``SequentialCommandGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SequentialCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_sequential_command_group.html), :external:py:class:`Python `), 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!). -The ``andThen()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#andThen(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a4ea952f52baf9fb157bb42801be602c0), :external:py:meth:`Python `) and ``beforeStarting()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#beforeStarting(edu.wpi.first.wpilibj2.command.Command)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a61e9a735d7b48dafd4b7499af8ff0c23), :external:py:meth:`Python `) decorators can be used to construct a sequence composition with infix syntax. +The ``andThen()`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#andThen(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a4ea952f52baf9fb157bb42801be602c0), :external:py:meth:`Python `) and ``beforeStarting()`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#beforeStarting(edu.wpi.first.wpilibj2.command.Command)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a61e9a735d7b48dafd4b7499af8ff0c23), :external:py:meth:`Python `) decorators can be used to construct a sequence composition with infix syntax. .. tab-set-code:: @@ -76,15 +76,15 @@ The ``andThen()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/j ### Repeating Sequence -As it's a fairly common combination, the ``RepeatingSequence`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#repeatingSequence(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#ac6b82e1b867c16264aa4e4bd79724d8c), :external:py:func:`Python `) creates a `Repeating`_ `Sequence`_ that runs until interrupted, restarting from the first command each time the last command finishes. +As it's a fairly common combination, the ``RepeatingSequence`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#repeatingSequence(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ac6b82e1b867c16264aa4e4bd79724d8c), :external:py:func:`Python `) creates a `Repeating`_ `Sequence`_ that runs until interrupted, restarting from the first command each time the last command finishes. ### Parallel There are three types of parallel compositions, differing based on when the composition finishes: -- The ``Parallel`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#parallel(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#ac98ed0faaf370bde01be52bd631dc4e8), :external:py:func:`Python `), backed by the ``ParallelCommandGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ParallelCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_parallel_command_group.html), :external:py:class:`Python `), constructs a parallel composition that finishes when all members finish. The ``alongWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#alongWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a6b9700cd25277a3ac558d63301985f40), :external:py:meth:`Python `) does the same in infix notation. -- The ``Race`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#race(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#a5253e241cf1e19eddfb79e2311068ac5), :external:py:func:`Python `), backed by the ``ParallelRaceGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ParallelRaceGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_parallel_race_group.html), :external:py:class:`Python `), constructs a parallel composition that finishes as soon as any member finishes; all other members are interrupted at that point. The ``raceWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#raceWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a4d6c1761cef10bb79a727e43e89643d0), :external:py:meth:`Python `) does the same in infix notation. -- The ``Deadline`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#deadline(edu.wpi.first.wpilibj2.command.Command,edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#a91073d40910a70f1e2d02c7ce320196a), :external:py:func:`Python `), ``ParallelDeadlineGroup`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ParallelDeadlineGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_parallel_deadline_group.html), :external:py:class:`Python `) finishes when a specific command (the "deadline") ends; all other members still running at that point are interrupted. The ``deadlineWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#deadlineWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#afafe81bf1624eb0ef78b30232087b4bf), :external:py:meth:`Python `) does the same in infix notation; the command the decorator was called on is the deadline. +- The ``Parallel`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#parallel(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ac98ed0faaf370bde01be52bd631dc4e8), :external:py:func:`Python `), backed by the ``ParallelCommandGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ParallelCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_parallel_command_group.html), :external:py:class:`Python `), constructs a parallel composition that finishes when all members finish. The ``alongWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#alongWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a6b9700cd25277a3ac558d63301985f40), :external:py:meth:`Python `) does the same in infix notation. +- The ``Race`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#race(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a5253e241cf1e19eddfb79e2311068ac5), :external:py:func:`Python `), backed by the ``ParallelRaceGroup`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ParallelRaceGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_parallel_race_group.html), :external:py:class:`Python `), constructs a parallel composition that finishes as soon as any member finishes; all other members are interrupted at that point. The ``raceWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#raceWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a4d6c1761cef10bb79a727e43e89643d0), :external:py:meth:`Python `) does the same in infix notation. +- The ``Deadline`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#deadline(edu.wpi.first.wpilibj2.command.Command,edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a91073d40910a70f1e2d02c7ce320196a), :external:py:func:`Python `), ``ParallelDeadlineGroup`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ParallelDeadlineGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_parallel_deadline_group.html), :external:py:class:`Python `) finishes when a specific command (the "deadline") ends; all other members still running at that point are interrupted. The ``deadlineWith`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#deadlineWith(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#afafe81bf1624eb0ef78b30232087b4bf), :external:py:meth:`Python `) does the same in infix notation; the command the decorator was called on is the deadline. .. tab-set-code:: @@ -117,7 +117,7 @@ There are three types of parallel compositions, differing based on when the comp ### Adding Command End Conditions -The ``until()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#until(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a4ffddf195a71e71d80e62df95fffdfcf), :external:py:meth:`Python `) decorator composes the command with an additional end condition. Note that the command the decorator was called on will see this end condition as an interruption. +The ``until()`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#until(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a4ffddf195a71e71d80e62df95fffdfcf), :external:py:meth:`Python `) decorator composes the command with an additional end condition. Note that the command the decorator was called on will see this end condition as an interruption. .. tab-set-code:: @@ -136,7 +136,7 @@ The ``until()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/jav button.onTrue(commands2.cmd.until(limitSwitch.get)) ``` -The ``withTimeout()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#withTimeout(double)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#ac6b2e1e4f55ed905ec7d189b9288e3d0), :external:py:meth:`Python `) is a specialization of ``until`` that uses a timeout as the additional end condition. +The ``withTimeout()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#withTimeout(double)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#ac6b2e1e4f55ed905ec7d189b9288e3d0), :external:py:meth:`Python `) is a specialization of ``until`` that uses a timeout as the additional end condition. .. tab-set-code:: @@ -157,15 +157,15 @@ The ``withTimeout()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs ### Adding End Behavior -The ``finallyDo()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#finallyDo(edu.wpi.first.util.function.BooleanConsumer)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#abd0ae6c855d7cf1f1a33cda5575a7b8f), :external:py:meth:`Python `) decorator composes the command with an a lambda that will be called after the command's ``end()`` method, with the same boolean parameter indicating whether the command finished or was interrupted. +The ``finallyDo()`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#finallyDo(edu.wpi.first.util.function.BooleanConsumer)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#abd0ae6c855d7cf1f1a33cda5575a7b8f), :external:py:meth:`Python `) decorator composes the command with an a lambda that will be called after the command's ``end()`` method, with the same boolean parameter indicating whether the command finished or was interrupted. -The ``handleInterrupt()`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#handleInterrupt(java.lang.Runnable)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a2a5580e71dfe356d2b261efe213f7c67), :external:py:meth:`Python `) decorator composes the command with an a lambda that will be called only when the command is interrupted. +The ``handleInterrupt()`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#handleInterrupt(java.lang.Runnable)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a2a5580e71dfe356d2b261efe213f7c67), :external:py:meth:`Python `) decorator composes the command with an a lambda that will be called only when the command is interrupted. ### Selecting Compositions Sometimes it's desired to run a command out of a few options based on sensor feedback or other data known only at runtime. This can be useful for determining an auto routine, or running a different command based on whether a game piece is present or not, and so on. -The ``Select`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#select(java.util.Map,java.util.function.Supplier)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#ae9a028777063223108f78c7a0c4e8746), :external:py:func:`Python `), backed by the ``SelectCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/SelectCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_select_command.html), :external:py:class:`Python `), executes one command from a map, based on a selector function called when scheduled. +The ``Select`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#select(java.util.Map,java.util.function.Supplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ae9a028777063223108f78c7a0c4e8746), :external:py:func:`Python `), backed by the ``SelectCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SelectCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_select_command.html), :external:py:class:`Python `), executes one command from a map, based on a selector function called when scheduled. .. tab-set:: @@ -185,7 +185,7 @@ The ``Select`` factory ([Java](https://github.wpilib.org/allwpilib/docs/developm :lines: 26-43 :lineno-match: -The ``Either`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Commands.html#either(edu.wpi.first.wpilibj2.command.Command,edu.wpi.first.wpilibj2.command.Command,java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/namespacefrc2_1_1cmd.html#a389d1d0055c3be03a852bfc88aaa2ee5), :external:py:func:`Python `), backed by the ``ConditionalCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ConditionalCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_conditional_command.html), :external:py:class:`Python `), is a specialization accepting two commands and a boolean selector function. +The ``Either`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#either(edu.wpi.first.wpilibj2.command.Command,edu.wpi.first.wpilibj2.command.Command,java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a389d1d0055c3be03a852bfc88aaa2ee5), :external:py:func:`Python `), backed by the ``ConditionalCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ConditionalCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_conditional_command.html), :external:py:class:`Python `), is a specialization accepting two commands and a boolean selector function. .. tab-set-code:: @@ -204,7 +204,7 @@ The ``Either`` factory ([Java](https://github.wpilib.org/allwpilib/docs/developm ConditionalCommand(commandOnTrue, commandOnFalse, limitSwitch.get) ``` -The ``unless()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#unless(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#a2be7f65d40f68581104ab1f6a1ba5e93), :external:py:meth:`Python `) composes a command with a condition that will prevent it from running. +The ``unless()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#unless(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a2be7f65d40f68581104ab1f6a1ba5e93), :external:py:meth:`Python `) composes a command with a condition that will prevent it from running. .. tab-set-code:: @@ -223,16 +223,16 @@ The ``unless()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/deve button.onTrue(command.unless(lambda: not intake.isDeployed())) ``` -``ProxyCommand`` described below also has a constructor overload ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python `) that calls a command-returning lambda at schedule-time and runs the returned command by proxy. +``ProxyCommand`` described below also has a constructor overload ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python `) that calls a command-returning lambda at schedule-time and runs the returned command by proxy. ### Scheduling Other Commands By default, composition members are run through the command composition, and are never themselves seen by the scheduler. Accordingly, their requirements are added to the composition's requirements. While this is usually fine, sometimes it is undesirable for the entire command composition to gain the requirements of a single command. A good solution is to "fork off" from the command composition and schedule that command separately. However, this requires synchronization between the composition and the individually-scheduled command. -``ProxyCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python `), also creatable using the ``.asProxy()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#asProxy()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_ptr.html#aa45784053431393e3277e5bc5ae7f751), :external:py:meth:`Python `), schedules a command "by proxy": the command is scheduled when the proxy is scheduled, and the proxy finishes when the command finishes. In the case of "forking off" from a command composition, this allows the composition to track the command's progress without it being in the composition. +``ProxyCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python `), also creatable using the ``.asProxy()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#asProxy()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#aa45784053431393e3277e5bc5ae7f751), :external:py:meth:`Python `), schedules a command "by proxy": the command is scheduled when the proxy is scheduled, and the proxy finishes when the command finishes. In the case of "forking off" from a command composition, this allows the composition to track the command's progress without it being in the composition. -Command compositions inherit the union of their compoments' requirements and requirements are immutable. Therefore, a ``SequentialCommandGroup`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/SequentialCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_sequential_command_group.html), :external:py:class:`Python `) that intakes a game piece, indexes it, aims a shooter, and shoots it would reserve all three subsystems (the intake, indexer, and shooter), precluding any of those subsystems from performing other operations in their "downtime". If this is not desired, the subsystems that should only be reserved for the composition while they are actively being used by it should have their commands proxied. +Command compositions inherit the union of their compoments' requirements and requirements are immutable. Therefore, a ``SequentialCommandGroup`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SequentialCommandGroup.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_sequential_command_group.html), :external:py:class:`Python `) that intakes a game piece, indexes it, aims a shooter, and shoots it would reserve all three subsystems (the intake, indexer, and shooter), precluding any of those subsystems from performing other operations in their "downtime". If this is not desired, the subsystems that should only be reserved for the composition while they are actively being used by it should have their commands proxied. .. warning:: Do not use ``ProxyCommand`` unless you are sure of what you are doing and there is no other way to accomplish your need! Proxying is only intended for use as an escape hatch from command composition requirement unions. @@ -267,7 +267,7 @@ Command compositions inherit the union of their compoments' requirements and req ) ``` -For cases that don't need to track the proxied command, ``ScheduleCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/ScheduleCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_schedule_command.html), :external:py:class:`Python `) schedules a specified command and ends instantly. +For cases that don't need to track the proxied command, ``ScheduleCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ScheduleCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_schedule_command.html), :external:py:class:`Python `) schedules a specified command and ends instantly. .. tab-set-code:: diff --git a/source/docs/software/commandbased/command-scheduler.rst b/source/docs/software/commandbased/command-scheduler.rst index 03c641a523..716e2d6344 100644 --- a/source/docs/software/commandbased/command-scheduler.rst +++ b/source/docs/software/commandbased/command-scheduler.rst @@ -1,6 +1,6 @@ # The Command Scheduler -The ``CommandScheduler`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html)) 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``. @@ -14,7 +14,7 @@ However, there is one exception: users *must* call ``CommandScheduler.getInstanc ## The ``schedule()`` Method -To schedule a command, users call the ``schedule()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#schedule(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#a9f3f7bb5c1a3cf57592fe5cfadb6a57d)). This method takes a command, 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#schedule(edu.wpi.first.wpilibj2.command.Command...)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#a9f3f7bb5c1a3cf57592fe5cfadb6a57d)). This method takes a command, 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. This method walks through the following steps: @@ -53,7 +53,7 @@ This method walks through the following steps: .. note:: The ``initialize()`` method of each ``Command`` is called when the command is scheduled, which is not necessarily when the scheduler runs (unless that command is bound to a button). -What does a single iteration of the scheduler's ``run()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#run()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#aa5000fa52e320da7ba72c196f34aa0f5)) actually do? The following section walks through the logic of a scheduler iteration. For the full implementation, see the source code ([Java](https://github.com/wpilibsuite/allwpilib/blob/v2024.3.2/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandScheduler.java#L252-L331), [C++](https://github.com/wpilibsuite/allwpilib/blob/v2024.3.2/wpilibNewCommands/src/main/native/cpp/frc2/command/CommandScheduler.cpp#L173-L253)). +What does a single iteration of the scheduler's ``run()`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#run()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#aa5000fa52e320da7ba72c196f34aa0f5)) actually do? The following section walks through the logic of a scheduler iteration. For the full implementation, see the source code ([Java](https://github.com/wpilibsuite/allwpilib/blob/v2024.3.2/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandScheduler.java#L252-L331), [C++](https://github.com/wpilibsuite/allwpilib/blob/v2024.3.2/wpilibNewCommands/src/main/native/cpp/frc2/command/CommandScheduler.cpp#L173-L253)). ### Step 1: Run Subsystem Periodic Methods @@ -159,13 +159,13 @@ The scheduler may be re-enabled by calling ``CommandScheduler.getInstance().enab Occasionally, it is desirable to have the scheduler execute a custom action whenever a certain command event (initialization, execution, or ending) occurs. This can be done with the following methods: -- ``onCommandInitialize`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandInitialize(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#a5f983f0e45b0500c96eebe52780324d4)) runs a specified action whenever a command is initialized. +- ``onCommandInitialize`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandInitialize(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#a5f983f0e45b0500c96eebe52780324d4)) runs a specified action whenever a command is initialized. -- ``onCommandExecute`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandExecute(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#a58c538f4b8dd95e266e4a99167aa7f99)) runs a specified action whenever a command is executed. +- ``onCommandExecute`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandExecute(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#a58c538f4b8dd95e266e4a99167aa7f99)) runs a specified action whenever a command is executed. -- ``onCommandFinish`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandFinish(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#a068e61446afe2341cc0651f0dfd2a55f)) runs a specified action whenever a command finishes normally (i.e. the ``isFinished()`` method returned true). +- ``onCommandFinish`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandFinish(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#a068e61446afe2341cc0651f0dfd2a55f)) runs a specified action whenever a command finishes normally (i.e. the ``isFinished()`` method returned true). -- ``onCommandInterrupt`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandInterrupt(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html#ab5ba99a542aa778a76726d7c68461bf0)) 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). +- ``onCommandInterrupt`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html#onCommandInterrupt(java.util.function.Consumer)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html#ab5ba99a542aa778a76726d7c68461bf0)) 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 following code from the HatchbotInlined example project ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/hatchbotinlined), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/HatchbotInlined)): diff --git a/source/docs/software/commandbased/commands.rst b/source/docs/software/commandbased/commands.rst index 271f4cbcf1..d1fdaedc9e 100644 --- a/source/docs/software/commandbased/commands.rst +++ b/source/docs/software/commandbased/commands.rst @@ -1,6 +1,6 @@ # Commands -**Commands** represent actions the robot can take. Commands run when scheduled, until they are interrupted or their end condition is met. Commands are represented in the command-based library by the ``Command`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html)) or the ``Command`` class in ``commands2`` library (:external:py:class:`Python `). +**Commands** represent actions the robot can take. Commands run when scheduled, until they are interrupted or their end condition is met. Commands are represented in the command-based library by the ``Command`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html)) or the ``Command`` class in ``commands2`` library (:external:py:class:`Python `). ## The Structure of a Command @@ -8,19 +8,19 @@ Commands specify what the command will do in each of its possible states. This i ### Initialization -The ``initialize()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#initialize()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#ad3f1971a1b44ecdd4683d766f831bccd), :external:py:meth:`Python `) marks the command start, and is called exactly once per time a command is scheduled. The ``initialize()`` method should be used to place the command in a known starting state for execution. Command objects may be reused and scheduled multiple times, so any state or resources needed for the command's functionality should be initialized or opened in ``initialize`` (which will be called at the start of each use) rather than the constructor (which is invoked only once on object allocation). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#initialize()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#ad3f1971a1b44ecdd4683d766f831bccd), :external:py:meth:`Python `) marks the command start, and is called exactly once per time a command is scheduled. The ``initialize()`` method should be used to place the command in a known starting state for execution. Command objects may be reused and scheduled multiple times, so any state or resources needed for the command's functionality should be initialized or opened in ``initialize`` (which will be called at the start of each use) rather than the constructor (which is invoked only once on object allocation). 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#execute()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#a7d7ea1271f7dcc65c0ba3221d179b510), :external:py:meth:`Python `) is called repeatedly while the command is scheduled; this is when 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#execute()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#a7d7ea1271f7dcc65c0ba3221d179b510), :external:py:meth:`Python `) is called repeatedly while the command is scheduled; this is when 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(bool interrupted)`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#end(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#a134eda3756f00c667bb5415b23ee920c), :external:py:meth:`Python `) 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. Any state or resources initialized in ``initialize()`` should be closed in ``end()``. +The ``end(bool interrupted)`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#end(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#a134eda3756f00c667bb5415b23ee920c), :external:py:meth:`Python `) 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. Any state or resources initialized in ``initialize()`` should be closed in ``end()``. ### Specifying end conditions -The ``isFinished()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#end(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#af5e8c12152d195a4f3c06789366aac88), :external:py:meth:`Python `) 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 ends. The ``isFinished()`` method is called after the ``execute()`` method, so the command will execute once on the same iteration that it ends. +The ``isFinished()`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#end(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#af5e8c12152d195a4f3c06789366aac88), :external:py:meth:`Python `) 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 ends. The ``isFinished()`` method is called after the ``execute()`` method, so the command will execute once on the same iteration that it ends. ## Command Properties @@ -50,11 +50,11 @@ As a rule, command compositions require all subsystems their components require. ### runsWhenDisabled -The ``runsWhenDisabled()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#runsWhenDisabled()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#a5113cbf3655ce8679dd48bf22700b2f4), :external:py:meth:`Python `) returns a ``boolean``/``bool`` specifying whether the command may run when the robot is disabled. With the default of returning ``false``, the command will be canceled when the robot is disabled and attempts to schedule it will do nothing. Returning ``true`` will allow the command to run and be scheduled when the robot is disabled. +The ``runsWhenDisabled()`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#runsWhenDisabled()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#a5113cbf3655ce8679dd48bf22700b2f4), :external:py:meth:`Python `) returns a ``boolean``/``bool`` specifying whether the command may run when the robot is disabled. With the default of returning ``false``, the command will be canceled when the robot is disabled and attempts to schedule it will do nothing. Returning ``true`` will allow the command to run and be scheduled when the robot is disabled. .. important:: When the robot is disabled, :term:`PWM` outputs are disabled and CAN motor controllers may not apply voltage, regardless of ``runsWhenDisabled``! -This property can be set either by overriding the ``runsWhenDisabled()`` method in the relevant command class, or by using the ``ignoringDisable`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#ignoringDisable(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#acc67b15e71a66aafb7523ccdd0a7a834), :external:py:meth:`Python `): +This property can be set either by overriding the ``runsWhenDisabled()`` method in the relevant command class, or by using the ``ignoringDisable`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#ignoringDisable(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#acc67b15e71a66aafb7523ccdd0a7a834), :external:py:meth:`Python `): .. tab-set-code:: @@ -74,11 +74,11 @@ As a rule, command compositions may run when disabled if all their component com ### getInterruptionBehavior -The ``getInterruptionBehavior()`` method ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#getInterruptionBehavior()), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#ab1e027e86fc5c9132914ca566a9845a8), :external:py:meth:`Python `) defines what happens if another command sharing a requirement is scheduled while this one is running. In the default behavior, ``kCancelSelf``, the current command will be canceled and the incoming command will be scheduled successfully. If ``kCancelIncoming`` is returned, the incoming command's scheduling will be aborted and this command will continue running. Note that ``getInterruptionBehavior`` only affects resolution of requirement conflicts: all commands can be canceled, regardless of ``getInterruptionBehavior``. +The ``getInterruptionBehavior()`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#getInterruptionBehavior()), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#ab1e027e86fc5c9132914ca566a9845a8), :external:py:meth:`Python `) defines what happens if another command sharing a requirement is scheduled while this one is running. In the default behavior, ``kCancelSelf``, the current command will be canceled and the incoming command will be scheduled successfully. If ``kCancelIncoming`` is returned, the incoming command's scheduling will be aborted and this command will continue running. Note that ``getInterruptionBehavior`` only affects resolution of requirement conflicts: all commands can be canceled, regardless of ``getInterruptionBehavior``. .. note:: This was previously controlled by the ``interruptible`` parameter passed when scheduling a command, and is now a property of the command object. -This property can be set either by overriding the ``getInterruptionBehavior`` method in the relevant command class, or by using the `withInterruptBehavior()` decorator ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html#withInterruptBehavior(edu.wpi.first.wpilibj2.command.Command.InterruptionBehavior)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html#a6583f966509478a29e7764a72c4bf177), :external:py:meth:`Python `) +This property can be set either by overriding the ``getInterruptionBehavior`` method in the relevant command class, or by using the `withInterruptBehavior()` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#withInterruptBehavior(edu.wpi.first.wpilibj2.command.Command.InterruptionBehavior)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html#a6583f966509478a29e7764a72c4bf177), :external:py:meth:`Python `) .. tab-set-code:: @@ -104,7 +104,7 @@ The command-based library includes many pre-written command types. Through the u The most basic commands are actions the robot takes: setting voltage to a motor, changing a solenoid's direction, etc. For these commands, which typically consist of a method call or two, the command-based library offers several factories to be construct commands inline with one or more lambdas to be executed. -The ``runOnce`` factory, backed by the ``InstantCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/InstantCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_instant_command.html), :external:py:class:`Python `) class, creates a command that calls a lambda once, and then finishes. +The ``runOnce`` factory, backed by the ``InstantCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/InstantCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_instant_command.html), :external:py:class:`Python `) class, creates a command that calls a lambda once, and then finishes. .. tab-set:: @@ -140,7 +140,7 @@ The ``runOnce`` factory, backed by the ``InstantCommand`` ([Java](https://github :lines: 24-34 :lineno-match: -The ``run`` factory, backed by the ``RunCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/RunCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_run_command.html), :external:py:class:`Python `) class, creates a command that calls a lambda repeatedly, until interrupted. +The ``run`` factory, backed by the ``RunCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RunCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_run_command.html), :external:py:class:`Python `) class, creates a command that calls a lambda repeatedly, until interrupted. .. tab-set-code:: @@ -174,7 +174,7 @@ The ``run`` factory, backed by the ``RunCommand`` ([Java](https://github.wpilib. robot_drive) ``` -The ``startEnd`` factory, backed by the ``StartEndCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/StartEndCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_start_end_command.html), :external:py:class:`Python `) class, calls one lambda when scheduled, and then a second lambda when interrupted. +The ``startEnd`` factory, backed by the ``StartEndCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/StartEndCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_start_end_command.html), :external:py:class:`Python `) class, calls one lambda when scheduled, and then a second lambda when interrupted. .. tab-set-code:: @@ -210,7 +210,7 @@ The ``startEnd`` factory, backed by the ``StartEndCommand`` ([Java](https://gith shooter) ``` -``FunctionalCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/FunctionalCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_functional_command.html), :external:py:class:`Python `) accepts four lambdas that constitute the four command lifecycle methods: a ``Runnable``/``std::function/Callable`` for each of ``initialize()`` and ``execute()``, a ``BooleanConsumer``/``std::function/Callable[bool,[]]`` for ``end()``, and a ``BooleanSupplier``/``std::function/Callable[[],bool]`` for ``isFinished()``. +``FunctionalCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/FunctionalCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_functional_command.html), :external:py:class:`Python `) accepts four lambdas that constitute the four command lifecycle methods: a ``Runnable``/``std::function/Callable`` for each of ``initialize()`` and ``execute()``, a ``BooleanConsumer``/``std::function/Callable[bool,[]]`` for ``end()``, and a ``BooleanSupplier``/``std::function/Callable[[],bool]`` for ``isFinished()``. .. tab-set-code:: @@ -256,13 +256,13 @@ The ``startEnd`` factory, backed by the ``StartEndCommand`` ([Java](https://gith robot_drive) ``` -To print a string and ending immediately, the library offers the ``Commands.print(String)``/``frc2::cmd::Print(std::string_view)``/``commands2.cmd.print(String)`` factory, backed by the ``PrintCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/PrintCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_print_command.html), :external:py:class:`Python `) subclass of ``InstantCommand``. +To print a string and ending immediately, the library offers the ``Commands.print(String)``/``frc2::cmd::Print(std::string_view)``/``commands2.cmd.print(String)`` factory, backed by the ``PrintCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/PrintCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_print_command.html), :external:py:class:`Python `) subclass of ``InstantCommand``. ### Waiting Waiting for a certain condition to happen or adding a delay can be useful to synchronize between different commands in a command composition or between other robot actions. -To wait and end after a specified period of time elapses, the library offers the ``Commands.waitSeconds(double)``/``frc2::cmd::Wait(units::second_t)``/``commands2.cmd.wait(float)`` factory, backed by the ``WaitCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/WaitCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_wait_command.html), :external:py:class:`Python `) class. +To wait and end after a specified period of time elapses, the library offers the ``Commands.waitSeconds(double)``/``frc2::cmd::Wait(units::second_t)``/``commands2.cmd.wait(float)`` factory, backed by the ``WaitCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/WaitCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_wait_command.html), :external:py:class:`Python `) class. .. tab-set-code:: @@ -281,7 +281,7 @@ To wait and end after a specified period of time elapses, the library offers the commands2.cmd.wait(5.0) ``` -To wait until a certain condition becomes ``true``, the library offers the ``Commands.waitUntil(BooleanSupplier)``/``frc2::cmd::WaitUntil(std::function)`` factory, backed by the ``WaitUntilCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/WaitUntilCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_wait_until_command.html), :external:py:class:`Python `). +To wait until a certain condition becomes ``true``, the library offers the ``Commands.waitUntil(BooleanSupplier)``/``frc2::cmd::WaitUntil(std::function)`` factory, backed by the ``WaitUntilCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/WaitUntilCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_wait_until_command.html), :external:py:class:`Python `). .. tab-set-code:: @@ -306,19 +306,19 @@ There are commands for various control setups: - ``TrapezoidProfile`` tracks a trapezoid motion profile. For more info, see :doc:`/docs/software/commandbased/profile-subsystems-commands`. -- ``MecanumControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/MecanumControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_mecanum_controller_command.html)) is useful for controlling mecanum drivetrains. See API docs and the **MecanumControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/mecanumcontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/MecanumControllerCommand)) example project for more info. +- ``MecanumControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/MecanumControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_mecanum_controller_command.html)) is useful for controlling mecanum drivetrains. See API docs and the **MecanumControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/mecanumcontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/MecanumControllerCommand)) example project for more info. -- ``SwerveControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/SwerveControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_swerve_controller_command.html)) is useful for controlling swerve drivetrains. See API docs and the **SwerveControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/swervecontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/SwerveControllerCommand)) example project for more info. +- ``SwerveControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SwerveControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_swerve_controller_command.html)) is useful for controlling swerve drivetrains. See API docs and the **SwerveControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/swervecontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/SwerveControllerCommand)) example project for more info. -- ``RamseteCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_ramsete_command.html)) is useful for path following with differential drivetrains ("tank drive"). See API docs and the :ref:`Trajectory Tutorial` for more info. +- ``RamseteCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_ramsete_command.html)) is useful for path following with differential drivetrains ("tank drive"). See API docs and the :ref:`Trajectory Tutorial` for more info. ## Custom Command Classes Users may also write custom command classes. As this is significantly more verbose, it's recommended to use the more concise factories mentioned above. -.. note:: In the C++ API, a :term:`CRTP` is used to allow certain Command methods to work with the object ownership model. Users should always extend the ``CommandHelper`` [class](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_helper.html) when defining their own command classes, as is shown below. +.. note:: In the C++ API, a :term:`CRTP` is used to allow certain Command methods to work with the object ownership model. Users should always extend the ``CommandHelper`` [class](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_helper.html) when defining their own command classes, as is shown below. -To write a custom command class, subclass the abstract ``Command`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Command.html)) or ``CommandHelper`` ([C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command.html)), as seen in the command-based template ([Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/templates/commandbased/commands/ExampleCommand.java), [C++](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibcExamples/src/main/cpp/templates/commandbased/include/commands/ExampleCommand.h)): +To write a custom command class, subclass the abstract ``Command`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html)) or ``CommandHelper`` ([C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command.html)), as seen in the command-based template ([Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/templates/commandbased/commands/ExampleCommand.java), [C++](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibcExamples/src/main/cpp/templates/commandbased/include/commands/ExampleCommand.h)): .. tab-set-code:: diff --git a/source/docs/software/commandbased/profile-subsystems-commands.rst b/source/docs/software/commandbased/profile-subsystems-commands.rst index e25dc37573..ace9fd76b3 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 in Command-based .. note:: The ``TrapezoidProfile`` class, used on its own, is most useful when composed with external controllers, such as a "smart" motor controller with a built-in PID functionality. 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/trajectory/TrapezoidProfile.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_trapezoid_profile.html)). +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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/TrapezoidProfile.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trapezoid_profile.html)). .. note:: In C++, the ``TrapezoidProfile`` 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`. diff --git a/source/docs/software/commandbased/subsystems.rst b/source/docs/software/commandbased/subsystems.rst index 4b1f5dd86f..7971c20690 100644 --- a/source/docs/software/commandbased/subsystems.rst +++ b/source/docs/software/commandbased/subsystems.rst @@ -4,11 +4,11 @@ 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 or be ignored, based on the running command's :ref:`Interruption Behavior `. -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 "background" actions such as controlling the robot drive, keeping an arm held at a setpoint, or stopping motors when the subsystem isn't used. 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. Subsystems are represented in the command-based library by the ``Subsystem`` interface ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Subsystem.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_subsystem.html), :external:py:class:`Python `). +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 "background" actions such as controlling the robot drive, keeping an arm held at a setpoint, or stopping motors when the subsystem isn't used. 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. Subsystems are represented in the command-based library by the ``Subsystem`` interface ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Subsystem.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_subsystem.html), :external:py:class:`Python `). ## Creating a Subsystem -The recommended method to create a subsystem for most users is to subclass the abstract ``SubsystemBase`` class in ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/SubsystemBase.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_subsystem_base.html)), as seen in the command-based template ([Java](https://github.com/wpilibsuite/allwpilib/blob/3eb372c25ad6079d6edfbdb4bb099a7bc00e4350/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/templates/commandbased/subsystems/ExampleSubsystem.java), [C++](https://github.com/wpilibsuite/allwpilib/blob/3eb372c25ad6079d6edfbdb4bb099a7bc00e4350/wpilibcExamples/src/main/cpp/templates/commandbased/include/subsystems/ExampleSubsystem.h)). In Python, because Python does not have interfaces, the ``Subsystem`` class is a concrete class that can be subclassed directly (:external:py:class:`Python `). The following example demonstrates how to create a simple subsystem in each of the supported languages: +The recommended method to create a subsystem for most users is to subclass the abstract ``SubsystemBase`` class in ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SubsystemBase.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_subsystem_base.html)), as seen in the command-based template ([Java](https://github.com/wpilibsuite/allwpilib/blob/3eb372c25ad6079d6edfbdb4bb099a7bc00e4350/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/templates/commandbased/subsystems/ExampleSubsystem.java), [C++](https://github.com/wpilibsuite/allwpilib/blob/3eb372c25ad6079d6edfbdb4bb099a7bc00e4350/wpilibcExamples/src/main/cpp/templates/commandbased/include/subsystems/ExampleSubsystem.h)). In Python, because Python does not have interfaces, the ``Subsystem`` class is a concrete class that can be subclassed directly (:external:py:class:`Python `). The following example demonstrates how to create a simple subsystem in each of the supported languages: .. tab-set:: @@ -142,7 +142,7 @@ Alternatively, instead of writing ``void`` public methods that are called from c :lineno-match: -Note the qualification of the ``RunOnce`` factory used here: this isn't the static factory in ``Commands``! Subsystems have similar instance factories that return commands requiring ``this`` (Java/C++) or ``self`` (Python) subsystem. Here, the ``Subsystem.runOnce(Runnable)`` factory ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/Subsystem.html#runOnce(java.lang.Runnable)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_subsystem.html#a6b8b3b7dab6f54fb8635e335dad448fe), :external:py:meth:`Python `) is used. +Note the qualification of the ``RunOnce`` factory used here: this isn't the static factory in ``Commands``! Subsystems have similar instance factories that return commands requiring ``this`` (Java/C++) or ``self`` (Python) subsystem. Here, the ``Subsystem.runOnce(Runnable)`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Subsystem.html#runOnce(java.lang.Runnable)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_subsystem.html#a6b8b3b7dab6f54fb8635e335dad448fe), :external:py:meth:`Python `) is used. For a comparison between these options, see :ref:`docs/software/commandbased/organizing-command-based:Instance Command Factory Methods`. diff --git a/source/docs/software/commandbased/what-is-command-based.rst b/source/docs/software/commandbased/what-is-command-based.rst index 76438aacac..3c7eb1f500 100644 --- a/source/docs/software/commandbased/what-is-command-based.rst +++ b/source/docs/software/commandbased/what-is-command-based.rst @@ -70,7 +70,7 @@ The command-based pattern is based around two core abstractions: **commands**, a .. note:: For a more detailed explanation, see :doc:`command-scheduler`. -Commands are run by the ``CommandScheduler`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_command_scheduler.html), :external:py:class:`Python `) singleton, which polls triggers (such as buttons) for commands to schedule, preventing resource conflicts, and executing scheduled commands. The scheduler's ``run()`` method must be called; 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/CommandScheduler.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_scheduler.html), :external:py:class:`Python `) singleton, which polls triggers (such as buttons) for commands to schedule, preventing resource conflicts, and executing scheduled commands. The scheduler's ``run()`` method must be called; 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 specify which subsystems they interact with, and the scheduler will ensure that no more more than one command requiring a given subsystem is scheduled 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. 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 a4d0e44922..a0e45e75f5 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 @@ -29,7 +29,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html) introduced in 2020, as the controller is updated every robot loop. See the example below on how to retain this functionality. +.. important:: The enable option does not affect the [PIDController](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html) introduced in 2020, as the controller is updated every robot loop. See the example below on how to retain this functionality. ## Enable Functionality in the New PIDController 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 eec6b238f9..cb6c1b7701 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 @@ -16,7 +16,7 @@ Create a PID Subsystem for each mechanism with feedback. The PID Subsystems cont 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html) introduced in 2020, as the controller is updated every robot loop. See the example :ref:`here ` on how to retain this functionality. +.. important:: The enable option does not affect the [PIDController](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html) introduced in 2020, as the controller is updated every robot loop. See the example :ref:`here ` on how to retain this functionality. ## Tuning the PIDController diff --git a/source/docs/software/driverstation/driver-station-errors-warnings.rst b/source/docs/software/driverstation/driver-station-errors-warnings.rst index b31be5cac8..edba971346 100644 --- a/source/docs/software/driverstation/driver-station-errors-warnings.rst +++ b/source/docs/software/driverstation/driver-station-errors-warnings.rst @@ -12,7 +12,7 @@ FRC: A joystick was disconnected while the robot was enabled. This error is triggered when a Joystick is unplugged. Contrary to the message text this error will be printed even if the robot is not enabled, or even connected to the DS. You will see a single instance of this message occur each time the Driver Station is started, even if Joysticks are properly connected and functioning. -.. note:: Joystick Unplugged warnings can be silenced by calling ``DriverStation.silenceJoystickConnectionWarning(true)`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DriverStation.html#silenceJoystickConnectionWarning(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_driver_station.html#ad92dee0301f96316ffd2a28a22ab9e54)) +.. note:: Joystick Unplugged warnings can be silenced by calling ``DriverStation.silenceJoystickConnectionWarning(true)`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DriverStation.html#silenceJoystickConnectionWarning(boolean)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_driver_station.html#ad92dee0301f96316ffd2a28a22ab9e54)) ## Lost Communication diff --git a/source/docs/software/hardware-apis/motors/wpi-drive-classes.rst b/source/docs/software/hardware-apis/motors/wpi-drive-classes.rst index 0eb728feff..e42eadd2ea 100644 --- a/source/docs/software/hardware-apis/motors/wpi-drive-classes.rst +++ b/source/docs/software/hardware-apis/motors/wpi-drive-classes.rst @@ -146,7 +146,7 @@ DifferentialDrive is a method provided for the control of "skid-steer" or "West ### Multi-Motor DifferentialDrive -Many FRC\ |reg| drivetrains have more than 1 motor on each side. Classes derived from ``PWMMotorController`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/motorcontrol/PWMMotorController.html) / [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_p_w_m_motor_controller.html) / :external:py:class:`Python `) have an ``addFollower`` method so that multiple follower motor controllers can be updated when the leader motor controller is commanded. CAN motor controllers have similar features, review the vendor's documentation to see how to use them. The examples below show a 4 motor (2 per side) drivetrain. To extend to more motors, simply create the additional controllers and use additional ``addFollower`` calls. +Many FRC\ |reg| drivetrains have more than 1 motor on each side. Classes derived from ``PWMMotorController`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/motorcontrol/PWMMotorController.html) / [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_w_m_motor_controller.html) / :external:py:class:`Python `) have an ``addFollower`` method so that multiple follower motor controllers can be updated when the leader motor controller is commanded. CAN motor controllers have similar features, review the vendor's documentation to see how to use them. The examples below show a 4 motor (2 per side) drivetrain. To extend to more motors, simply create the additional controllers and use additional ``addFollower`` calls. .. tab-set:: diff --git a/source/docs/software/hardware-apis/pneumatics/pressure.rst b/source/docs/software/hardware-apis/pneumatics/pressure.rst index bbab0f1ab6..2ba4d50a2a 100644 --- a/source/docs/software/hardware-apis/pneumatics/pressure.rst +++ b/source/docs/software/hardware-apis/pneumatics/pressure.rst @@ -1,6 +1,6 @@ # Generating and Storing Pressure -Pressure is created using a pneumatic compressor and stored in pneumatic tanks. The compressor must be on the robot and powered by the robot's pneumatics module. The "Closed Loop" mode on the Compressor is enabled by default, and it is *not* recommended that teams change this setting. When closed loop control is enabled the pneumatic module will automatically turn the compressor on when the digital pressure switch is closed (below the pressure threshold) and turn it off when the pressure switch is open (~120PSI). When closed loop control is disabled the compressor will not be turned on. Using the ``Compressor`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Compressor.html) / [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_compressor.html)) class, users can query the status of the compressor. The state (currently on or off), pressure switch state, and compressor current can all be queried from the Compressor object, as shown by the following code from the Solenoid example project ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/solenoid), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/Solenoid)): +Pressure is created using a pneumatic compressor and stored in pneumatic tanks. The compressor must be on the robot and powered by the robot's pneumatics module. The "Closed Loop" mode on the Compressor is enabled by default, and it is *not* recommended that teams change this setting. When closed loop control is enabled the pneumatic module will automatically turn the compressor on when the digital pressure switch is closed (below the pressure threshold) and turn it off when the pressure switch is open (~120PSI). When closed loop control is disabled the compressor will not be turned on. Using the ``Compressor`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Compressor.html) / [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_compressor.html)) class, users can query the status of the compressor. The state (currently on or off), pressure switch state, and compressor current can all be queried from the Compressor object, as shown by the following code from the Solenoid example project ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/solenoid), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/Solenoid)): .. note:: The Compressor object is only needed if you want the ability to turn off the compressor, change the pressure sensor (PH only), or query compressor status. diff --git a/source/docs/software/hardware-apis/pneumatics/solenoids.rst b/source/docs/software/hardware-apis/pneumatics/solenoids.rst index 5f0dd31e29..737f2dbed6 100644 --- a/source/docs/software/hardware-apis/pneumatics/solenoids.rst +++ b/source/docs/software/hardware-apis/pneumatics/solenoids.rst @@ -8,7 +8,7 @@ Single acting solenoids apply or vent pressure from a single output port. They a ## Single Solenoids in WPILib -Single solenoids in WPILib are controlled using the ``Solenoid`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Solenoid.html) / [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_solenoid.html)). To construct a Solenoid object, simply pass the desired port number (assumes default CAN ID) and pneumatics module type or CAN ID, pneumatics module type, and port number to the constructor. To set the value of the solenoid call ``set(true)`` to enable or ``set(false)`` to disable the solenoid output. +Single solenoids in WPILib are controlled using the ``Solenoid`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Solenoid.html) / [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_solenoid.html)). To construct a Solenoid object, simply pass the desired port number (assumes default CAN ID) and pneumatics module type or CAN ID, pneumatics module type, and port number to the constructor. To set the value of the solenoid call ``set(true)`` to enable or ``set(false)`` to disable the solenoid output. .. tab-set:: @@ -43,7 +43,7 @@ Single solenoids in WPILib are controlled using the ``Solenoid`` class ([Java](h ## Double Solenoids in WPILib -Double solenoids are controlled by the ``DoubleSolenoid`` class in WPILib ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DoubleSolenoid.html) / [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_double_solenoid.html)). These are constructed similarly to the single solenoid but there are now two port numbers to pass to the constructor, a forward channel (first) and a reverse channel (second). The state of the valve can then be set to ``kOff`` (neither output activated), ``kForward`` (forward channel enabled) or ``kReverse`` (reverse channel enabled). Additionally, the CAN ID can be passed to the DoubleSolenoid if teams have a non-default CAN ID. +Double solenoids are controlled by the ``DoubleSolenoid`` class in WPILib ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DoubleSolenoid.html) / [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_double_solenoid.html)). These are constructed similarly to the single solenoid but there are now two port numbers to pass to the constructor, a forward channel (first) and a reverse channel (second). The state of the valve can then be set to ``kOff`` (neither output activated), ``kForward`` (forward channel enabled) or ``kReverse`` (reverse channel enabled). Additionally, the CAN ID can be passed to the DoubleSolenoid if teams have a non-default CAN ID. .. tab-set:: diff --git a/source/docs/software/hardware-apis/sensors/accelerometers-software.rst b/source/docs/software/hardware-apis/sensors/accelerometers-software.rst index 3d6c3885f2..bfe1993ece 100644 --- a/source/docs/software/hardware-apis/sensors/accelerometers-software.rst +++ b/source/docs/software/hardware-apis/sensors/accelerometers-software.rst @@ -19,7 +19,7 @@ Three-axis accelerometers often require more complicated communications protocol ## AnalogAccelerometer -The :code:`AnalogAccelerometer` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogAccelerometer.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_accelerometer.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogAccelerometer.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_accelerometer.html)) allows users to read values from a single-axis accelerometer that is connected to one of the roboRIO's analog inputs. .. tab-set-code:: @@ -63,7 +63,7 @@ There are getters for the acceleration along each cardinal direction (x, y, and ### ADXL345_I2C -The :code:`ADXL345_I2C` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADXL345_I2C.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_x_l345___i2_c.html)) provides support for the ADXL345 accelerometer over the I2C communications bus. +The :code:`ADXL345_I2C` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADXL345_I2C.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_x_l345___i2_c.html)) provides support for the ADXL345 accelerometer over the I2C communications bus. .. tab-set-code:: @@ -81,7 +81,7 @@ The :code:`ADXL345_I2C` class ([Java](https://github.wpilib.org/allwpilib/docs/d ### ADXL345_SPI -The :code:`ADXL345_SPI` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADXL345_SPI.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_x_l345___s_p_i.html)) provides support for the ADXL345 accelerometer over the SPI communications bus. +The :code:`ADXL345_SPI` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADXL345_SPI.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_x_l345___s_p_i.html)) provides support for the ADXL345 accelerometer over the SPI communications bus. .. tab-set-code:: @@ -99,7 +99,7 @@ The :code:`ADXL345_SPI` class ([Java](https://github.wpilib.org/allwpilib/docs/d ### ADXL362 -The :code:`ADXL362` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADXL362.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_x_l362.html)) provides support for the ADXL362 accelerometer over the SPI communications bus. +The :code:`ADXL362` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADXL362.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_x_l362.html)) provides support for the ADXL362 accelerometer over the SPI communications bus. .. tab-set-code:: @@ -117,7 +117,7 @@ The :code:`ADXL362` class ([Java](https://github.wpilib.org/allwpilib/docs/devel ### BuiltInAccelerometer -The :code:`BuiltInAccelerometer` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/BuiltInAccelerometer.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_built_in_accelerometer.html)) provides access to the roboRIO's own built-in accelerometer: +The :code:`BuiltInAccelerometer` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/BuiltInAccelerometer.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_built_in_accelerometer.html)) provides access to the roboRIO's own built-in accelerometer: .. tab-set-code:: @@ -182,7 +182,7 @@ For detecting collisions, it is often more robust to measure the jerk than the a } ``` -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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/filter/LinearFilter.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_linear_filter.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/filter/LinearFilter.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_linear_filter.html)) to reduce the noise: .. tab-set-code:: 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 9b50b4f83f..470ee590e7 100644 --- a/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst +++ b/source/docs/software/hardware-apis/sensors/analog-inputs-software.rst @@ -10,7 +10,7 @@ Analog inputs from the FPGA by default return a 12-bit integer proportional to t .. 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogInput.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_input.html)). +Support for reading the voltages on the FPGA analog inputs is provided through the :code:`AnalogInput` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogInput.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_input.html)). ### 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 457d90e83e..585de522d2 100644 --- a/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst +++ b/source/docs/software/hardware-apis/sensors/analog-potentiometers-software.rst @@ -4,7 +4,7 @@ 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogPotentiometer.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_potentiometer.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogPotentiometer.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_potentiometer.html)) 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 880a03468c..a016117690 100644 --- a/source/docs/software/hardware-apis/sensors/counters.rst +++ b/source/docs/software/hardware-apis/sensors/counters.rst @@ -3,7 +3,7 @@ .. image:: images/counters/counters.png :alt: IO Diagram showing the up/down pulses the counter is counting. -The :code:`Counter` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Counter.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_counter.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Counter.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_counter.html)) 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 8738e7131c..88ab50e943 100644 --- a/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst +++ b/source/docs/software/hardware-apis/sensors/digital-inputs-software.rst @@ -6,7 +6,7 @@ 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 :term:`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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DigitalInput.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_digital_input.html)). +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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DigitalInput.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_digital_input.html)). ## The DigitalInput class @@ -44,7 +44,7 @@ The state of the :code:`DigitalInput` can be polled with the :code:`get` method: .. 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogTrigger.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_trigger.html)). +Sometimes, it is desirable to use an analog input as a digital input. This can be easily achieved using the :code:`AnalogTrigger` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogTrigger.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_trigger.html)). 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 9f34c2e208..665a919193 100644 --- a/source/docs/software/hardware-apis/sensors/encoders-software.rst +++ b/source/docs/software/hardware-apis/sensors/encoders-software.rst @@ -10,7 +10,7 @@ Encoders are devices used to measure motion (usually, the rotation of a shaft). ## Quadrature Encoders - The :code:`Encoder` Class -WPILib provides support for quadrature encoders through the :code:`Encoder` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Encoder.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_encoder.html)). This class provides a simple API for configuring and reading data from encoders. +WPILib provides support for quadrature encoders through the :code:`Encoder` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Encoder.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_encoder.html)). This class provides a simple API for configuring and reading data from encoders. .. image:: images/encoders-software/encoding-direction.png :alt: Quadrature Encoders determine direction by observing which pulse channel (A or B) receives a pulse first. @@ -219,7 +219,7 @@ To reset a quadrature encoder to a distance reading of zero, call the :code:`res ## Duty Cycle Encoders - The :code:`DutyCycleEncoder` class -WPILib provides support for duty cycle (also marketed as :term:`PWM`) encoders through the :code:`DutyCycleEncoder` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DutyCycleEncoder.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_duty_cycle_encoder.html)). This class provides a simple API for configuring and reading data from duty cycle encoders. +WPILib provides support for duty cycle (also marketed as :term:`PWM`) encoders through the :code:`DutyCycleEncoder` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DutyCycleEncoder.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_duty_cycle_encoder.html)). This class provides a simple API for configuring and reading data from duty cycle encoders. The roboRIO's FPGA handles duty cycle encoders automatically. @@ -325,7 +325,7 @@ To reset an encoder so the current distance is 0, call the :code:`reset()` metho ## Analog Encoders - The :code:`AnalogEncoder` Class -WPILib provides support for analog absolute encoders through the :code:`AnalogEncoder` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogEncoder.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_encoder.html)). This class provides a simple API for configuring and reading data from duty cycle encoders. +WPILib provides support for analog absolute encoders through the :code:`AnalogEncoder` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogEncoder.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_encoder.html)). This class provides a simple API for configuring and reading data from duty cycle encoders. Examples of analog encoders: diff --git a/source/docs/software/hardware-apis/sensors/gyros-software.rst b/source/docs/software/hardware-apis/sensors/gyros-software.rst index de84492a06..0853f01d27 100644 --- a/source/docs/software/hardware-apis/sensors/gyros-software.rst +++ b/source/docs/software/hardware-apis/sensors/gyros-software.rst @@ -12,7 +12,7 @@ There are getters the current angular rate and heading and functions for zeroing ## ADIS16448 -The ADIS16448 uses the :code:`ADIS16448_IMU` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADIS16448_IMU.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_i_s16448___i_m_u.html), :external:py:class:`Python `). See the [Analog Devices ADIS16448 documentation](https://wiki.analog.com/first/adis16448_imu_frc) for additional information and examples. +The ADIS16448 uses the :code:`ADIS16448_IMU` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADIS16448_IMU.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_i_s16448___i_m_u.html), :external:py:class:`Python `). See the [Analog Devices ADIS16448 documentation](https://wiki.analog.com/first/adis16448_imu_frc) for additional information and examples. .. warning:: The Analog Devices documentation linked above contains outdated instructions for software installation as the ADIS16448 is now built into WPILib. @@ -36,7 +36,7 @@ The ADIS16448 uses the :code:`ADIS16448_IMU` class ([Java](https://github.wpilib ## ADIS16470 -The ADIS16470 uses the :code:`ADIS16470_IMU` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADIS16470_IMU.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_i_s16470___i_m_u.html), :external:py:class:`Python `). See the [Analog Devices ADIS16470 documentation](https://wiki.analog.com/first/adis16470_imu_frc) for additional information and examples. +The ADIS16470 uses the :code:`ADIS16470_IMU` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADIS16470_IMU.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_i_s16470___i_m_u.html), :external:py:class:`Python `). See the [Analog Devices ADIS16470 documentation](https://wiki.analog.com/first/adis16470_imu_frc) for additional information and examples. .. warning:: The Analog Devices documentation linked above contains outdated instructions for software installation as the ADIS16470 is now built into WPILib. @@ -59,7 +59,7 @@ The ADIS16470 uses the :code:`ADIS16470_IMU` class ([Java](https://github.wpilib ## ADXRS450_Gyro -The :code:`ADXRS450_Gyro` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/ADXRS450_Gyro.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_a_d_x_r_s450___gyro.html), :external:py:class:`Python `) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/ADXRS450_Gyro.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_a_d_x_r_s450___gyro.html), :external:py:class:`Python `) 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. @@ -82,7 +82,7 @@ The :code:`ADXRS450_Gyro` class ([Java](https://github.wpilib.org/allwpilib/docs ## AnalogGyro -The :code:`AnalogGyro` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/AnalogGyro.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_analog_gyro.html), :external:py:class:`Python `) provides support for any single-axis gyro with an analog output. +The :code:`AnalogGyro` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/AnalogGyro.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_analog_gyro.html), :external:py:class:`Python `) 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 476dc131f3..3fbed4e685 100644 --- a/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst +++ b/source/docs/software/hardware-apis/sensors/ultrasonics-software.rst @@ -11,7 +11,7 @@ There are two primary types of ultrasonics supported natively by WPILib: ## Ping-response ultrasonics -The :code:`Ultrasonic` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Ultrasonic.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_ultrasonic.html)) provides support for ping-response ultrasonics. As ping-response ultrasonics (per the name) require separate pins for both sending 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Ultrasonic.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_ultrasonic.html)) provides support for ping-response ultrasonics. As ping-response ultrasonics (per the name) require separate pins for both sending the ping and measuring the response, users must specify DIO pin numbers for both output and input when constructing an :code:`Ultrasonic` instance: .. tab-set:: diff --git a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst b/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst index 902974f060..e96551569c 100644 --- a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst +++ b/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst @@ -4,7 +4,7 @@ ## What is kinematics? -The kinematics suite contains classes for differential drive, swerve drive, and mecanum drive kinematics and odometry. The kinematics classes help convert between a universal ``ChassisSpeeds`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/kinematics/ChassisSpeeds.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/structfrc_1_1_chassis_speeds.html), :external:py:class:`Python `)object, containing linear and angular velocities for a robot to usable speeds for each individual type of drivetrain i.e. left and right wheel speeds for a differential drive, four wheel speeds for a mecanum drive, or individual module states (speed and angle) for a swerve drive. +The kinematics suite contains classes for differential drive, swerve drive, and mecanum drive kinematics and odometry. The kinematics classes help convert between a universal ``ChassisSpeeds`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/kinematics/ChassisSpeeds.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/structfrc_1_1_chassis_speeds.html), :external:py:class:`Python `)object, containing linear and angular velocities for a robot to usable speeds for each individual type of drivetrain i.e. left and right wheel speeds for a differential drive, four wheel speeds for a mecanum drive, or individual module states (speed and angle) for a swerve drive. ## What is odometry? Odometry involves using sensors on the robot to create an estimate of the position of the robot on the field. In FRC, these sensors are typically several encoders (the exact number depends on the drive type) and a gyroscope to measure robot angle. The odometry classes utilize the kinematics classes along with periodic user inputs about speeds (and angles in the case of swerve) to create an estimate of the robot's location on the field. diff --git a/source/docs/software/networktables/index.rst b/source/docs/software/networktables/index.rst index 9fee1747c0..faccb87420 100644 --- a/source/docs/software/networktables/index.rst +++ b/source/docs/software/networktables/index.rst @@ -2,7 +2,7 @@ This section outlines the details of using the NetworkTables (v4) API to communicate information across the robot network. -.. important:: The code examples in this section are not intended for the user to copy-paste. Ensure that the following documentation is thoroughly read and the API ([Java](https://github.wpilib.org/allwpilib/docs/development/java/index.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/index.html), :ref:`Python `) is consulted when necessary. +.. important:: The code examples in this section are not intended for the user to copy-paste. Ensure that the following documentation is thoroughly read and the API ([Java](https://github.wpilib.org/allwpilib/docs/release/java/index.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/index.html), :ref:`Python `) is consulted when necessary. .. toctree:: :maxdepth: 1 diff --git a/source/docs/software/networktables/multiple-instances.rst b/source/docs/software/networktables/multiple-instances.rst index 614b7fb2e6..3a825bae74 100644 --- a/source/docs/software/networktables/multiple-instances.rst +++ b/source/docs/software/networktables/multiple-instances.rst @@ -6,7 +6,7 @@ For most general usage, you should use the "default" instance, as all current da However, if you wanted to do unit testing of your robot program's NetworkTables communications, you could set up your unit tests such that they create a separate client instance (still within the same program) and have it connect to the server instance that the main robot code is running. -The ``NetworkTableInstance`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/NetworkTableInstance.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_network_table_instance.html), :external:py:class:`Python `) class provides the API abstraction for instances. The number of instances that can be simultaneously created is limited to 16 (including the default instance), so when using multiple instances in cases such as unit testing code, it's important to destroy instances that are no longer needed. +The ``NetworkTableInstance`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/NetworkTableInstance.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_network_table_instance.html), :external:py:class:`Python `) class provides the API abstraction for instances. The number of instances that can be simultaneously created is limited to 16 (including the default instance), so when using multiple instances in cases such as unit testing code, it's important to destroy instances that are no longer needed. Destroying a NetworkTableInstance frees all resources related to the instance. All classes or handles that reference the instance (e.g. Topics, Publishers, and Subscribers) are invalidated and may result in unexpected behavior if used after the instance is destroyed--in particular, instance handles are reused so it's possible for a handle "left over" from a previously destroyed instance to refer to an unexpected resource in a newly created instance. diff --git a/source/docs/software/networktables/networktables-intro.rst b/source/docs/software/networktables/networktables-intro.rst index 4bb06916ef..87da6c4f1c 100644 --- a/source/docs/software/networktables/networktables-intro.rst +++ b/source/docs/software/networktables/networktables-intro.rst @@ -52,7 +52,7 @@ Because of this, two timestamps are visible through the API: a server timestamp ## NetworkTables Organization -Data is organized in NetworkTables in a hierarchy much like a filesystem's folders and files. There can be multiple subtables (folders) and topics (files) that may be nested in whatever way fits the data organization desired. At the top level (``NetworkTableInstance``: [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/NetworkTableInstance.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_network_table_instance.html), :external:py:class:`Python `), topic names are handled similar to absolute paths in a filesystem: subtables are represented as a long topic name with slashes ("/") separating the nested subtable and value names. A ``NetworkTable`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/NetworkTable.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_network_table.html), :external:py:class:`Python `) object represents a single subtable (folder), so topic names are relative to the NetworkTable's base path: e.g. for a root table called "SmartDashboard" with a topic named "xValue", the same topic can be accessed via ``NetworkTableInstance`` as a topic named "/SmartDashboard/xValue". However, unlike a filesystem, subtables don't really exist in the same way folders do, as there is no way to represent an empty subtable on the network--a subtable "appears" only as long as there are topics published within it. +Data is organized in NetworkTables in a hierarchy much like a filesystem's folders and files. There can be multiple subtables (folders) and topics (files) that may be nested in whatever way fits the data organization desired. At the top level (``NetworkTableInstance``: [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/NetworkTableInstance.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_network_table_instance.html), :external:py:class:`Python `), topic names are handled similar to absolute paths in a filesystem: subtables are represented as a long topic name with slashes ("/") separating the nested subtable and value names. A ``NetworkTable`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/NetworkTable.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_network_table.html), :external:py:class:`Python `) object represents a single subtable (folder), so topic names are relative to the NetworkTable's base path: e.g. for a root table called "SmartDashboard" with a topic named "xValue", the same topic can be accessed via ``NetworkTableInstance`` as a topic named "/SmartDashboard/xValue". However, unlike a filesystem, subtables don't really exist in the same way folders do, as there is no way to represent an empty subtable on the network--a subtable "appears" only as long as there are topics published within it. :ref:`docs/software/wpilib-tools/outlineviewer/index:outlineviewer` is a utility for exploring the values stored in NetworkTables, and can show either a flat view (topics with absolute paths) or a nested view (subtables and topics). diff --git a/source/docs/software/networktables/publish-and-subscribe.rst b/source/docs/software/networktables/publish-and-subscribe.rst index f0b4514ca8..35f0f5d006 100644 --- a/source/docs/software/networktables/publish-and-subscribe.rst +++ b/source/docs/software/networktables/publish-and-subscribe.rst @@ -4,7 +4,7 @@ In order to create a :term:`topic` and publish values to it, it's necessary to create a :term:`publisher`. -NetworkTable publishers are represented as type-specific Publisher objects (e.g. ``BooleanPublisher``: [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/BooleanPublisher.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_boolean_publisher.html), :external:py:class:`Python `). Publishers are only active as long as the Publisher object exists. Typically you want to keep publishing longer than the local scope of a function, so it's necessary to store the Publisher object somewhere longer term, e.g. in an instance variable. In Java, the ``close()`` method needs be called to stop publishing; in C++ this is handled by the destructor. C++ publishers are moveable and non-copyable. In Python the ``close()`` method should be called to stop publishing, but it will also be closed when the object is garbage collected. +NetworkTable publishers are represented as type-specific Publisher objects (e.g. ``BooleanPublisher``: [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/BooleanPublisher.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_boolean_publisher.html), :external:py:class:`Python `). Publishers are only active as long as the Publisher object exists. Typically you want to keep publishing longer than the local scope of a function, so it's necessary to store the Publisher object somewhere longer term, e.g. in an instance variable. In Java, the ``close()`` method needs be called to stop publishing; in C++ this is handled by the destructor. C++ publishers are moveable and non-copyable. In Python the ``close()`` method should be called to stop publishing, but it will also be closed when the object is garbage collected. In the handle-based APIs, there is only the non-type-specific ``NT_Publisher`` handle; the user is responsible for keeping track of the type of the publisher and using the correct type-specific set methods. @@ -197,7 +197,7 @@ Publishing values is done via a ``set()`` operation. By default, this operation ## Subscribing to a Topic -A :term:`subscriber` receives value updates made to a topic. Similar to publishers, NetworkTable subscribers are represented as type-specific Subscriber classes (e.g. ``BooleanSubscriber``: [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/BooleanSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_boolean_subscriber.html), :external:py:class:`Python `) that must be stored somewhere to continue subscribing. +A :term:`subscriber` receives value updates made to a topic. Similar to publishers, NetworkTable subscribers are represented as type-specific Subscriber classes (e.g. ``BooleanSubscriber``: [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/BooleanSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_boolean_subscriber.html), :external:py:class:`Python `) that must be stored somewhere to continue subscribing. Subscribers have a range of different ways to read received values. It's possible to just read the most recent value using ``get()``, read the most recent value, along with its timestamp, using ``getAtomic()``, or get an array of all value changes since the last call using ``readQueue()`` or ``readQueueValues()``. @@ -392,7 +392,7 @@ Subscribers have a range of different ways to read received values. It's possibl ## Using Entry to Both Subscribe and Publish -An :term:`entry` is a combined publisher and subscriber. The subscriber is always active, but the publisher is not created until a publish operation is performed (e.g. a value is "set", aka published, on the entry). This may be more convenient than maintaining a separate publisher and subscriber. Similar to publishers and subscribers, NetworkTable entries are represented as type-specific Entry classes (e.g. ``BooleanEntry``: [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/BooleanEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_boolean_entry.html), :external:py:class:`Python `) that must be retained to continue subscribing (and publishing). +An :term:`entry` is a combined publisher and subscriber. The subscriber is always active, but the publisher is not created until a publish operation is performed (e.g. a value is "set", aka published, on the entry). This may be more convenient than maintaining a separate publisher and subscriber. Similar to publishers and subscribers, NetworkTable entries are represented as type-specific Entry classes (e.g. ``BooleanEntry``: [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/BooleanEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_boolean_entry.html), :external:py:class:`Python `) that must be retained to continue subscribing (and publishing). .. tab-set:: @@ -615,7 +615,7 @@ An :term:`entry` is a combined publisher and subscriber. The subscriber is alway ## Using GenericEntry, GenericPublisher, and GenericSubscriber -For the most robust code, using the type-specific Publisher, Subscriber, and Entry classes is recommended, but in some cases it may be easier to write code that uses type-specific get and set function calls instead of having the NetworkTables type be exposed via the class (object) type. The ``GenericPublisher`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/GenericPublisher.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_generic_publisher.html), :external:py:class:`Python `), ``GenericSubscriber`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/GenericSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_generic_subscriber.html), :external:py:class:`Python`), and ``GenericEntry`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/GenericEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_generic_entry.html), :external:py:class:`Python `) classes enable this approach. +For the most robust code, using the type-specific Publisher, Subscriber, and Entry classes is recommended, but in some cases it may be easier to write code that uses type-specific get and set function calls instead of having the NetworkTables type be exposed via the class (object) type. The ``GenericPublisher`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/GenericPublisher.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_generic_publisher.html), :external:py:class:`Python `), ``GenericSubscriber`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/GenericSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_generic_subscriber.html), :external:py:class:`Python`), and ``GenericEntry`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/GenericEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_generic_entry.html), :external:py:class:`Python `) classes enable this approach. .. tab-set:: @@ -807,7 +807,7 @@ For the most robust code, using the type-specific Publisher, Subscriber, and Ent ## Subscribing to Multiple Topics -While in most cases it's only necessary to subscribe to individual topics, it is sometimes useful (e.g. in dashboard applications) to subscribe and get value updates for changes to multiple topics. Listeners (see :ref:`docs/software/networktables/listening-for-change:listening for changes`) can be used directly, but creating a ``MultiSubscriber`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/MultiSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_multi_subscriber.html)) allows specifying subscription options and reusing the same subscriber for multiple listeners. +While in most cases it's only necessary to subscribe to individual topics, it is sometimes useful (e.g. in dashboard applications) to subscribe and get value updates for changes to multiple topics. Listeners (see :ref:`docs/software/networktables/listening-for-change:listening for changes`) can be used directly, but creating a ``MultiSubscriber`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/MultiSubscriber.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_multi_subscriber.html)) allows specifying subscription options and reusing the same subscriber for multiple listeners. .. tab-set:: @@ -1018,6 +1018,6 @@ Entry options: ## NetworkTableEntry -``NetworkTableEntry`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/NetworkTableEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_network_table_entry.html), :external:py:class:`Python `) is a class that exists for backwards compatibility. New code should prefer using type-specific Publisher and Subscriber classes, or GenericEntry if non-type-specific access is needed. +``NetworkTableEntry`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/NetworkTableEntry.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_network_table_entry.html), :external:py:class:`Python `) is a class that exists for backwards compatibility. New code should prefer using type-specific Publisher and Subscriber classes, or GenericEntry if non-type-specific access is needed. It is similar to ``GenericEntry`` in that it supports both publishing and subscribing in a single object. However, unlike ``GenericEntry``, ``NetworkTableEntry`` is not released (e.g. unsubscribes/unpublishes) if ``close()`` is called (in Java) or the object is destroyed (in C++); instead, it operates similar to ``Topic``, in that only a single ``NetworkTableEntry`` exists for each topic and it lasts for the lifetime of the instance. diff --git a/source/docs/software/networktables/tables-and-topics.rst b/source/docs/software/networktables/tables-and-topics.rst index a44c78a632..a0c9cfbbce 100644 --- a/source/docs/software/networktables/tables-and-topics.rst +++ b/source/docs/software/networktables/tables-and-topics.rst @@ -2,13 +2,13 @@ ## Using the NetworkTable Class -The ``NetworkTable`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/NetworkTable.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_network_table.html), :external:py:class:`Python `) class is an API abstraction that represents a single "folder" (or "table") of topics as described in :ref:`docs/software/networktables/networktables-intro:networktables organization`. The NetworkTable class stores the base path to the table and provides functions to get topics within the table, automatically prepending the table path. +The ``NetworkTable`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/NetworkTable.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_network_table.html), :external:py:class:`Python `) class is an API abstraction that represents a single "folder" (or "table") of topics as described in :ref:`docs/software/networktables/networktables-intro:networktables organization`. The NetworkTable class stores the base path to the table and provides functions to get topics within the table, automatically prepending the table path. ## Getting a Topic -A ``Topic`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/Topic.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_topic.html), :external:py:class:`Python `) object (or ``NT_Topic`` handle) represents a :term:`topic`. This has a 1:1 correspondence with the topic's name, and will not change as long as the instance exists. Unlike publishers and subscribers, it is not necessary to store a Topic object. +A ``Topic`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/Topic.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_topic.html), :external:py:class:`Python `) object (or ``NT_Topic`` handle) represents a :term:`topic`. This has a 1:1 correspondence with the topic's name, and will not change as long as the instance exists. Unlike publishers and subscribers, it is not necessary to store a Topic object. -Having a Topic object or handle does not mean the topic exists or is of the correct type. For convenience when creating publishers and subscribers, there are type-specific Topic classes (e.g. ``BooleanTopic``: [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/networktables/BooleanTopic.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classnt_1_1_boolean_topic.html), :external:py:class:`Python `), but there is no check at the Topic level to ensure that the topic's type actually matches. The preferred method to get a type-specific topic to call the appropriate type-specific getter, but it's also possible to directly convert a generic Topic into a type-specific Topic class. Note: the handle-based API does not have a concept of type-specific classes. +Having a Topic object or handle does not mean the topic exists or is of the correct type. For convenience when creating publishers and subscribers, there are type-specific Topic classes (e.g. ``BooleanTopic``: [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/networktables/BooleanTopic.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classnt_1_1_boolean_topic.html), :external:py:class:`Python `), but there is no check at the Topic level to ensure that the topic's type actually matches. The preferred method to get a type-specific topic to call the appropriate type-specific getter, but it's also possible to directly convert a generic Topic into a type-specific Topic class. Note: the handle-based API does not have a concept of type-specific classes. .. tab-set:: 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 d0ec93d086..914c2d1d0f 100644 --- a/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst +++ b/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst @@ -127,9 +127,9 @@ We will first reset our robot's pose to the starting pose of the trajectory. Thi :lineno-match: -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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/trajectory/Trajectory.html#transformBy(edu.wpi.first.math.geometry.Transform2d)), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_trajectory.html#a8edfbd82347bbf32ddfb092679336cd8)). 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/Trajectory.html#transformBy(edu.wpi.first.math.geometry.Transform2d)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trajectory.html#a8edfbd82347bbf32ddfb092679336cd8)). 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc2_1_1_ramsete_command.html)) +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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_ramsete_command.html)) .. tab-set:: @@ -155,12 +155,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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/RamseteController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_ramsete_controller.html)) 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/SimpleMotorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_simple_motor_feedforward.html)) that will automatically perform the correct feedforward calculation with the feedforward gains (``kS``, ``kV``, and ``kA``) that we obtained from the drive identification tool. -5. The drive kinematics: This is the ``DifferentialDriveKinematics`` object ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/kinematics/DifferentialDriveKinematics.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_differential_drive_kinematics.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/RamseteController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_ramsete_controller.html)) 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](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/SimpleMotorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_simple_motor_feedforward.html)) that will automatically perform the correct feedforward calculation with the feedforward gains (``kS``, ``kV``, and ``kA``) that we obtained from the drive identification tool. +5. The drive kinematics: This is the ``DifferentialDriveKinematics`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/kinematics/DifferentialDriveKinematics.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_differential_drive_kinematics.html)) 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the left-side wheel speed setpoint, using the P gain that we obtained from the drive identification tool. -8. The right-side PIDController: This is the ``PIDController`` object ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the right-side wheel speed setpoint, using the P gain that we obtained from the drive identification tool. +7. The left-side PIDController: This is the ``PIDController`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the left-side wheel speed setpoint, using the P gain that we obtained from the drive identification tool. +8. The right-side PIDController: This is the ``PIDController`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the right-side wheel speed setpoint, using the P gain that we obtained from the drive identification 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/telemetry/datalog-download.rst b/source/docs/software/telemetry/datalog-download.rst index c0f5e4616f..339a52ec52 100644 --- a/source/docs/software/telemetry/datalog-download.rst +++ b/source/docs/software/telemetry/datalog-download.rst @@ -75,6 +75,6 @@ The Driver Station software can download WPILogs. Click on the gear icon and sel ## Custom Processing of Data Logs -For more advanced processing of data logs (e.g. for processing of binary values that can't be converted to CSV), WPILib provides a ``DataLogReader`` class for reading data logs in [Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/util/datalog/DataLogReader.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classwpi_1_1log_1_1_data_log_reader.html), or :external:py:class:`Python `. There is also a pure python datalog reader ([datalog.py](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/datalog.py)). For other languages, the [data log format](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/datalog.adoc) is also documented. +For more advanced processing of data logs (e.g. for processing of binary values that can't be converted to CSV), WPILib provides a ``DataLogReader`` class for reading data logs in [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLogReader.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log_reader.html), or :external:py:class:`Python `. There is also a pure python datalog reader ([datalog.py](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/datalog.py)). For other languages, the [data log format](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/datalog.adoc) is also documented. DataLogReader provides a low-level view of a data log, in that it supports iterating over a data log's control and data records and decoding of common data types, but does not provide any higher level abstractions such as a NetworkTables-like map of entries. The printlog example in [Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/src/printlog/java/printlog/PrintLog.java) and [C++](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/printlog.cpp) (and the Python ``datalog.py``) demonstrates basic usage. diff --git a/source/docs/software/telemetry/datalog.rst b/source/docs/software/telemetry/datalog.rst index b164ce9db8..6bd78ca9b4 100644 --- a/source/docs/software/telemetry/datalog.rst +++ b/source/docs/software/telemetry/datalog.rst @@ -12,7 +12,7 @@ Data logs consist of a series of timestamped records. Control records allow sta ## Standard Data Logging using DataLogManager -The ``DataLogManager`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/DataLogManager.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_data_log_manager.html), :external:py:class:`Python `) provides a centralized data log that provides automatic data log file management. It automatically cleans up old files when disk space is low and renames the file based either on current date/time or (if available) competition match number. The data file will be saved to a USB flash drive in a folder called ``logs`` if one is attached, or to ``/home/lvuser/logs`` otherwise. +The ``DataLogManager`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DataLogManager.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_data_log_manager.html), :external:py:class:`Python `) provides a centralized data log that provides automatic data log file management. It automatically cleans up old files when disk space is low and renames the file based either on current date/time or (if available) competition match number. The data file will be saved to a USB flash drive in a folder called ``logs`` if one is attached, or to ``/home/lvuser/logs`` otherwise. .. note:: USB flash drives need to be formatted as FAT32 to work with the roboRIO. NTFS or exFAT formatted drives will not work. Flash drives of 32GB or smaller are recommended, as Windows doesn't format drives larger then 32GB with FAT32. @@ -87,7 +87,7 @@ DataLogManager by default does not record joystick data. The ``DriverStation`` ## Custom Data Logging using DataLog -The ``DataLog`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/util/datalog/DataLog.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classwpi_1_1log_1_1_data_log.html), :external:py:class:`Python `) and its associated LogEntry classes (e.g. ``BooleanLogEntry``, ``DoubleLogEntry``, etc) provides low-level access for writing data logs. +The ``DataLog`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLog.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log.html), :external:py:class:`Python `) and its associated LogEntry classes (e.g. ``BooleanLogEntry``, ``DoubleLogEntry``, etc) provides low-level access for writing data logs. .. note:: Unlike NetworkTables, there is no change checking performed. **Every** call to a ``LogEntry.append()`` function will result in a record being written to the data log. Checking for changes and only appending to the log when necessary is the responsibility of the caller. diff --git a/source/docs/software/telemetry/persistent-alerts.rst b/source/docs/software/telemetry/persistent-alerts.rst index 214525b978..70e02265cc 100644 --- a/source/docs/software/telemetry/persistent-alerts.rst +++ b/source/docs/software/telemetry/persistent-alerts.rst @@ -2,7 +2,7 @@ Robots encounter a variety of fault conditions: disconnected sensors/motors, invalid mechanism states, initialization failures, etc. While the FRC Driver Station provides a :ref:`console interface ` for instantaneous alerts, the risk of missing important messages makes it poorly suited to communicate faults that persist over time. -Instead, the ``Alert`` class ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Alert.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_alert.html)) can be used for managing persistent alerts published via Network Tables. Alerts are assigned a priority (*error*, *warning*, or *info*) and can be *activated* or *deactivated* in robot code. The set of active alerts can be displayed on a dashboard, as shown below in Shuffleboard. +Instead, the ``Alert`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Alert.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_alert.html)) can be used for managing persistent alerts published via Network Tables. Alerts are assigned a priority (*error*, *warning*, or *info*) and can be *activated* or *deactivated* in robot code. The set of active alerts can be displayed on a dashboard, as shown below in Shuffleboard. .. image:: images/alerts.png :alt: A screenshot of the alerts widget in Shuffleboard, with several active alerts. diff --git a/source/docs/software/telemetry/robot-telemetry-with-annotations.rst b/source/docs/software/telemetry/robot-telemetry-with-annotations.rst index bd090f69f0..dfc901ddb6 100644 --- a/source/docs/software/telemetry/robot-telemetry-with-annotations.rst +++ b/source/docs/software/telemetry/robot-telemetry-with-annotations.rst @@ -254,7 +254,7 @@ Logging Third-Party Data A large part of the Java ecosystem is its access to third-party libraries that provide extra functionality, such as vendor libraries for interacting with custom hardware like motor controllers and sensors. If those vendors do not use logging annotations in their libraries, then you can still log them by writing a custom logger class! These classes are actually what the WPILib annotations will generate; you just write a custom one because third-party code cannot be annotated. -Custom loggers can be declared in any package, and only need to have the ``@CustomLoggerFor`` annotation present to be able to be detected and used. They must extend from ``ClassSpecificLogger`` ([Javadoc](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/epilogue/logging/ClassSpecificLogger.html)) and must have a public no-argument constructor - failing to declare one will result in a compilation error - and must pass the type they log to the superclass constructor. +Custom loggers can be declared in any package, and only need to have the ``@CustomLoggerFor`` annotation present to be able to be detected and used. They must extend from ``ClassSpecificLogger`` ([Javadoc](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/epilogue/logging/ClassSpecificLogger.html)) and must have a public no-argument constructor - failing to declare one will result in a compilation error - and must pass the type they log to the superclass constructor. .. note:: Only one custom logger may be defined for a single type. Custom loggers will only be detected and used if they are defined in the robot project; custom loggers defined in third-party libraries cannot be detected. diff --git a/source/docs/software/telemetry/robot-telemetry-with-sendable.rst b/source/docs/software/telemetry/robot-telemetry-with-sendable.rst index bf25a6d560..abed76cc28 100644 --- a/source/docs/software/telemetry/robot-telemetry-with-sendable.rst +++ b/source/docs/software/telemetry/robot-telemetry-with-sendable.rst @@ -8,7 +8,7 @@ WPILib provides this functionality with the ``Sendable`` interface. Classes tha ## What is Sendable? -``Sendable`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/util/sendable/Sendable.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classwpi_1_1_sendable.html), :external:py:class:`Python `) is an interface provided by WPILib to facilitate robot telemetry. Classes that implement ``Sendable`` can declaratively send their state to the dashboard - once declared, WPILib will automatically send the telemetry values every robot loop. This removes the need for teams to handle the iteration-to-iteration logic of sending and receiving values from the dashboard, and also allows teams to separate their telemetry code from their robot logic. +``Sendable`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/Sendable.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable.html), :external:py:class:`Python `) is an interface provided by WPILib to facilitate robot telemetry. Classes that implement ``Sendable`` can declaratively send their state to the dashboard - once declared, WPILib will automatically send the telemetry values every robot loop. This removes the need for teams to handle the iteration-to-iteration logic of sending and receiving values from the dashboard, and also allows teams to separate their telemetry code from their robot logic. Many WPILib classes (such as :ref:`Commands `) already implement ``Sendable``, and so can be sent to the dashboard without any user modification. Users are also able to easily extend their own classes to implement ``Sendable``. diff --git a/source/docs/software/telemetry/writing-sendable-classes.rst b/source/docs/software/telemetry/writing-sendable-classes.rst index 0e79645cc0..049f149cc3 100644 --- a/source/docs/software/telemetry/writing-sendable-classes.rst +++ b/source/docs/software/telemetry/writing-sendable-classes.rst @@ -20,7 +20,7 @@ To enable the automatic updating of values by WPILib "in the background", ``Send ## The SendableBuilder Class -As seen above, the ``initSendable`` method takes a single parameter, ``builder``, of type ``SendableBuilder`` ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/util/sendable/SendableBuilder.html), [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classwpi_1_1_sendable_builder.html), :external:py:class:`Python `). This builder exposes methods that allow binding of getters and setters to dashboard names, as well as methods for safely ensuring that values consumed *from* the dashboard do not cause unsafe robot behavior. +As seen above, the ``initSendable`` method takes a single parameter, ``builder``, of type ``SendableBuilder`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/SendableBuilder.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable_builder.html), :external:py:class:`Python `). This builder exposes methods that allow binding of getters and setters to dashboard names, as well as methods for safely ensuring that values consumed *from* the dashboard do not cause unsafe robot behavior. ### Databinding with addProperty Methods diff --git a/source/docs/software/vscode-overview/creating-robot-program.rst b/source/docs/software/vscode-overview/creating-robot-program.rst index 96479edf0d..a351141e07 100644 --- a/source/docs/software/vscode-overview/creating-robot-program.rst +++ b/source/docs/software/vscode-overview/creating-robot-program.rst @@ -9,14 +9,14 @@ To start a project using one of the WPILib robot program templates, users must f ### TimedRobot Documentation: -[Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/TimedRobot.html) -- [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_timed_robot.html) +[Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/TimedRobot.html) +- [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_timed_robot.html) Source: [Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibj/src/main/java/edu/wpi/first/wpilibj/TimedRobot.java) - [C++](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibc/src/main/native/cpp/TimedRobot.cpp) -The :code:`TimedRobot` class is 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). During these calls, your code typically polls each input device and acts according to the data it receives. For instance, you would typically determine the position of the joystick and state of the joystick buttons on each call and act accordingly. The ``TimedRobot`` class also provides an example of retrieving autonomous routines through SendableChooser ([Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/smartdashboard/SendableChooser.html)/ [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_sendable_chooser.html)) +The :code:`TimedRobot` class is 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). During these calls, your code typically polls each input device and acts according to the data it receives. For instance, you would typically determine the position of the joystick and state of the joystick buttons on each call and act accordingly. The ``TimedRobot`` class also provides an example of retrieving autonomous routines through SendableChooser ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/smartdashboard/SendableChooser.html)/ [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_sendable_chooser.html)) .. 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`. @@ -34,7 +34,7 @@ The :code:`TimedRobot` class is the base class recommended for most users. It p 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](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/Notifier.html) to schedule methods at a custom rate. +.. danger:: Changing your robot rate can cause some unintended behavior (loop overruns). Teams can also use [Notifiers](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/Notifier.html) to schedule methods at a custom rate. .. tab-set-code:: @@ -51,8 +51,8 @@ Periodic methods are called every 20 ms by default. This can be changed by calli ### Timeslice Robot Documentation: -[Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/TimesliceRobot.html) -- [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_timeslice_robot.html#details) +[Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/TimesliceRobot.html) +- [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_timeslice_robot.html#details) Source: [Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibj/src/main/java/edu/wpi/first/wpilibj/TimesliceRobot.java) @@ -66,8 +66,8 @@ The :code:`TimesliceRobot` class extends the :code:`TimedRobot` framework to pro ### RobotBase Documentation: -[Java](https://github.wpilib.org/allwpilib/docs/development/java/edu/wpi/first/wpilibj/RobotBase.html) -- [C++](https://github.wpilib.org/allwpilib/docs/development/cpp/classfrc_1_1_robot_base.html) +[Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/RobotBase.html) +- [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_robot_base.html) Source: [Java](https://github.com/wpilibsuite/allwpilib/blob/main/wpilibj/src/main/java/edu/wpi/first/wpilibj/RobotBase.java) diff --git a/source/docs/software/what-is-wpilib.rst b/source/docs/software/what-is-wpilib.rst index bb26968fa5..e4ecbce3c4 100644 --- a/source/docs/software/what-is-wpilib.rst +++ b/source/docs/software/what-is-wpilib.rst @@ -24,8 +24,8 @@ 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 and RobotPy: - - [Java documentation](https://github.wpilib.org/allwpilib/docs/development/java/) + - [Java documentation](https://github.wpilib.org/allwpilib/docs/release/java/) - - [C++ documentation](https://github.wpilib.org/allwpilib/docs/development/cpp/) + - [C++ documentation](https://github.wpilib.org/allwpilib/docs/release/cpp/) - [Python documentation](https://robotpy.readthedocs.io/projects/robotpy/en/stable/) diff --git a/source/index.rst b/source/index.rst index aaf07892a2..736e172a32 100644 --- a/source/index.rst +++ b/source/index.rst @@ -219,7 +219,7 @@ Community translations can be found in a variety of languages in the bottom-left Java, C++, and Python class documentation. - .. button-link:: https://github.wpilib.org/allwpilib/docs/development/java/index.html + .. button-link:: https://github.wpilib.org/allwpilib/docs/release/java/index.html :color: primary :shadow: :align: center @@ -228,7 +228,7 @@ Community translations can be found in a variety of languages in the bottom-left Java - .. button-link:: https://github.wpilib.org/allwpilib/docs/development/cpp/index.html + .. button-link:: https://github.wpilib.org/allwpilib/docs/release/cpp/index.html :color: primary :shadow: :align: center @@ -369,8 +369,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 WPILib Python API Docs .. toctree:: diff --git a/source/stubs/api-docs-stub.rst b/source/stubs/api-docs-stub.rst index 7606761cd8..d56f9aa6a4 100644 --- a/source/stubs/api-docs-stub.rst +++ b/source/stubs/api-docs-stub.rst @@ -8,6 +8,6 @@ Java and CSS class documentation. :maxdepth: 1 :hidden: - WPILib Java API Docs - WPILib C++ API Docs + WPILib Java API Docs + WPILib C++ API Docs WPILib Python API Docs