Update SysId docs for 2024 (#2492)

* move sysid to advanced controls

* remove images and add redirects

* remove unneeded pages and rename analysis page

* refer to the application as "SysId"

* remove json converter docs

* routine creation page

* add binding instructions to creation page

* running routine page

* revse accleration r^2 range

* move feedforward gains to analysis page

* Loading data text

* select the right analysis type

* add loading images

* add sysid image to software page

* correct sysid image path

* correct unit scaling image path

* add redirects and lint

* change robot-characterization redirects

* kill project configuration redirects

* no redirect errors

* grammar

* elaborate on loggers, kA

* undo redirects edits

* whitespace

* Add multi-routine warning

* remove drivetrain references and correcct spelling

* remove drivetrain from introduction

* new images

* remove trailing whitespace

source/docs/controls-overviews/control-system-software.rst

@@ -138,10 +138,10 @@ PathWeaver allows teams to quickly generate and configure paths for advanced aut
 System Identification
 ----------------------
 
-.. image:: /docs/software/pathplanning/system-identification/images/analysis-type.png
-   :alt: System Identification new project screen.
+.. image:: images/control-system-software/sysid.png
+   :alt: SysId UI showing diagnostics and analysis for a flywheel.
 
-This tool helps teams automatically calculate constants that can be used to describe the physical properties of your robot for use in features like robot simulation, trajectory following, and PID control.  For more information see the :ref:`System Identification section <docs/software/pathplanning/system-identification/introduction:Introduction to System Identification>`.
+This tool helps teams automatically calculate constants that can be used to describe the physical properties of your robot for use in features like robot simulation, trajectory following, and PID control.  For more information see the :ref:`System Identification section <docs/software/advanced-controls/system-identification/introduction:Introduction to System Identification>`.
 
 OutlineViewer
 -------------

source/docs/software/advanced-controls/controllers/feedforward.rst

@@ -14,7 +14,7 @@ The WPILib Feedforward Classes
 
 WPILib provides a number of classes to help users implement accurate feedforward control for their mechanisms.  In many ways, an accurate feedforward is more important than feedback to effective control of a mechanism.  Since most FRC\ |reg| mechanisms closely obey well-understood system equations, starting with an accurate feedforward is both easy and hugely beneficial to accurate and robust mechanism control.
 
-The WPILib feedforward classes closely match the available mechanism characterization tools available in the :ref:`SysId toolsuite <docs/software/pathplanning/system-identification/introduction:Introduction to System Identification>`.  The system identification toolsuite can be used to quickly and effectively determine the correct gains for each type of feedforward.  If you are unable to empirically characterize your mechanism (due to space and/or time constraints), reasonable estimates of ``kG``, ``kV``, and ``kA`` can be obtained by fairly simple computation, and are also available from `ReCalc <https://www.reca.lc/>`__.  ``kS`` is nearly impossible to model, and must be measured empirically.
+The WPILib feedforward classes closely match the available mechanism characterization tools available in the :ref:`SysId toolsuite <docs/software/advanced-controls/system-identification/introduction:Introduction to System Identification>`.  The system identification toolsuite can be used to quickly and effectively determine the correct gains for each type of feedforward.  If you are unable to empirically characterize your mechanism (due to space and/or time constraints), reasonable estimates of ``kG``, ``kV``, and ``kA`` can be obtained by fairly simple computation, and are also available from `ReCalc <https://www.reca.lc/>`__.  ``kS`` is nearly impossible to model, and must be measured empirically.
 
 WPILib currently provides the following three helper classes for feedforward control:
 

source/docs/software/advanced-controls/index.rst

@@ -10,6 +10,7 @@ This section covers advanced control features in WPILib, such as various feedbac
    introduction/index
    filters/index
    geometry/index
+   system-identification/index
    controllers/index
    trajectories/index
    state-space/index

source/docs/software/advanced-controls/introduction/introduction-to-feedforward.rst

@@ -55,7 +55,7 @@ where :math:`V` is the applied voltage, :math:`\theta` is the angular displaceme
 Using the Feedforward
 ---------------------
 
-In order to use the feedforward, we need to plug in values for each unknown in the above voltage-balance equation *other than the voltage*.  As mentioned :ref:`earlier <docs/software/advanced-controls/introduction/picking-control-strategy:Obtaining Models for Your Mechanisms>`, the values of the gains :math:`K_g`, :math:`K_v`, :math:`K_a` can be obtained through theoretical modeling with `ReCalc <https://www.reca.lc/>`__. Explicit measurement with :doc:`SysId </docs/software/pathplanning/system-identification/introduction>` will yield the aforementioned gains in addition to :math:`K_s`. That leaves us needing values for velocity, acceleration, and (in the case of the arm feedforward) position.
+In order to use the feedforward, we need to plug in values for each unknown in the above voltage-balance equation *other than the voltage*.  As mentioned :ref:`earlier <docs/software/advanced-controls/introduction/picking-control-strategy:Obtaining Models for Your Mechanisms>`, the values of the gains :math:`K_g`, :math:`K_v`, :math:`K_a` can be obtained through theoretical modeling with `ReCalc <https://www.reca.lc/>`__. Explicit measurement with :doc:`SysId </docs/software/advanced-controls/system-identification/introduction>` will yield the aforementioned gains in addition to :math:`K_s`. That leaves us needing values for velocity, acceleration, and (in the case of the arm feedforward) position.
 
 Typically, these come from our setpoints - remember that with feedforward we are making a "guess" as to the output we need based on where we want the system to be.
 

source/docs/software/advanced-controls/introduction/picking-control-strategy.rst

@@ -99,7 +99,7 @@ Theoretical Modeling
 
 `ReCalc is an online calculator <https://www.reca.lc/>`__ which estimates physical parameters for a number of common FRC mechanisms.  Importantly, it can generate estimate the ``kV``, ``kA``, and ``kG`` gains for the WPILib feedforward classes.
 
-The :doc:`WPILib system identification tool </docs/software/pathplanning/system-identification/introduction>` supports a "theoretical mode" that can be used to determine PID gains for feedback control from the ``kV`` and ``kA`` gains from ReCalc, enabling (in theory) full tuning of a control loop without running any test routines.
+The :doc:`WPILib system identification tool </docs/software/advanced-controls/system-identification/introduction>` supports a "theoretical mode" that can be used to determine PID gains for feedback control from the ``kV`` and ``kA`` gains from ReCalc, enabling (in theory) full tuning of a control loop without running any test routines.
 
 Remember, however, that theory is not reality and purely theoretical gains are not guaranteed to work well.  There is *never* a substitute for testing.
 
@@ -108,7 +108,7 @@ System Identification
 
 A good way to improve the accuracy of a simple physics model is to perform experiments on the real mechanism, record data, and use the data to *derive* the constants associated with different parts of the model. This is very useful for physical quantities which are difficult or impossible to predict, but easy to measure (ex: friction in a gearbox).
 
-:doc:`WPILib's system identification tool </docs/software/pathplanning/system-identification/introduction>` supports some common FRC mechanisms, including drivetrain. It deploys its own code to the robot to exercise the mechanism, record data, and derive gains for both feedforward and feedback control schemes.
+:doc:`WPILib's system identification tool </docs/software/advanced-controls/system-identification/introduction>` supports some common FRC mechanisms, including drivetrain. It deploys its own code to the robot to exercise the mechanism, record data, and derive gains for both feedforward and feedback control schemes.
 
 Manual Tuning: What to Do with No Explicit Model
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

source/docs/software/advanced-controls/introduction/tuning-vertical-arm.rst

@@ -179,4 +179,4 @@ A Note on Feedforward and Static Friction
 
 For the sake of simplicity, the simulations above omit the :math:`K_s` term from the WPILib SimpleMotorFeedforward equation.  On actual mechanisms, however, this can be important - especially if there's a lot of friction in the mechanism gearing.
 
-In the case of a vertical arm or elevator, :math:`K_s` can be somewhat tedious to estimate separately from :math:`K_g`.  If your arm or elevator has enough friction for :math:`K_s` to be important, it is recommended that you use the :doc:`WPILib system identification tool </docs/software/pathplanning/system-identification/introduction>` to determine your system gains.
+In the case of a vertical arm or elevator, :math:`K_s` can be somewhat tedious to estimate separately from :math:`K_g`.  If your arm or elevator has enough friction for :math:`K_s` to be important, it is recommended that you use the :doc:`WPILib system identification tool </docs/software/advanced-controls/system-identification/introduction>` to determine your system gains.

source/docs/software/pathplanning/system-identification/additional-utils.rst → source/docs/software/advanced-controls/system-identification/additional-utils.rst

@@ -3,20 +3,6 @@ Additional Utilities and Tools
 
 This page mainly covers useful information about additional functionality that this tool provides.
 
-
-JSON Converters
----------------
-
-There are a two JSON Utility tools that can be used in the :guilabel:`JSON Converters` tab: FRC-Char Converter and JSON to CSV Converter.
-
-.. image:: images/json-converters.png
-   :alt: Picture of the json converters
-
-The FRC-Char Converter reads in an FRC-Char JSON and converts it into a SysId JSON that the tool can read.
-
-The JSON to CSV Converter takes a SysId JSON and outputs a CSV file. If the JSON had Drivetrain Mechanism data, the columns are: ``Timestamp (s)``, ``Test``, ``Left Volts (V)`` , ``Right Volts (V)``, ``Left Position ({0})``, ``Right Position ({units})``, ``Left Velocity ({units}/s)``, ``Right Velocity ({units}/s)``, ``Gyro Position (deg)``, ``Gyro Rate (deg/s)``.
-If the JSON had General Mechanism data, the CSV has the following columns: ``Timestamp (s)``, ``Test``, ``Volts (V)``, ``Position({units})``, ``Velocity ({units}/s)``.
-
 ImGui Tips
 ----------
 

source/docs/software/pathplanning/system-identification/analyzing-feedback.rst → source/docs/software/advanced-controls/system-identification/analyzing-gains.rst

@@ -1,7 +1,27 @@
 .. include:: <isonum.txt>
 
+Analyzing Data
+===============
+
+Feedforward Analysis
+----------------------------
+
+.. note:: For information on what the calculated feedback gains mean, see :ref:`docs/software/advanced-controls/introduction/introduction-to-feedforward:The Permanent-Magnet DC Motor Feedforward Equation`.  For information on using the calculated feedback gains in code, see :ref:`feedforward control <docs/software/advanced-controls/controllers/feedforward:Feedforward Control in WPILib>`.
+
+Click the dropdown arrow on the :guilabel:`Feedforward` Section.
+
+.. note:: If you would like to change units, you will have to press the :guilabel:`Override Units` button and fill out the information on the popup.
+
+.. image:: images/feedback-analysis.png
+   :alt: Analyzing data for feedforward
+
+The computed mechanism system parameters will then be displayed.
+
+.. image:: images/feedforward-values.png
+   :alt: Analysis coefficient results
+
 Feedback Analysis
-=================
+-----------------
 
 .. important:: These gains are, in effect, "educated guesses" - they are not guaranteed to be perfect, and should be viewed as a "starting point" for further tuning.
 

source/docs/software/advanced-controls/system-identification/creating-routine.rst

@@ -0,0 +1,75 @@
+Creating an Identification Routine
+==================================
+
+Types of Tests
+--------------
+
+A standard motor identification routine consists of two types of tests:
+
+- **Quasistatic:** In this test, the mechanism is gradually sped-up such that the voltage corresponding to acceleration is negligible (hence, "as if static").
+- **Dynamic:** In this test, a constant 'step voltage' is given to the mechanism, so that the behavior while accelerating can be determined.
+
+Each test type is run both forwards and backwards, for four tests in total. The tests can be run in any order, but running a "backwards" test directly after a "forwards" test is generally advisable (as it will more or less reset the mechanism to its original position). ``SysIdRoutine`` provides command factories that may be used to run the tests, for example as part of an autonomous routine. Previous versions of SysId used a project generator to create and deploy robot code to run these tests, but it proved to be very fragile and difficult to maintain. The user code-based workflow enables teams to use mechanism code they already know works, including soft and hard limits.
+
+User Code Setup
+---------------
+
+.. note:: Some familiarity with your language's units library is recommended and knowing how to use Consumers is required. Ths page assumes you are using the Commands framework.
+
+To assist in creating SysId-compatible identification routines, WPILib provides the ``SysIdRoutine`` class. Users should create a ``SysIdRoutine`` object, which take both a ``Config`` object describing the test settings and a ``Mechanism`` object describing how the routine will control the relevant motors and log the measurements needed to perform the fit.
+
+Routine Config
+^^^^^^^^^^^^^^
+
+The ``Config`` object takes in a a voltage ramp rate for use in Quasistatic tests, a steady state step voltage for use in Dynamic tests, a time to use as the maximum test duration for safety reasons, and a callback method that accepts the current test state (such as "dynamic-forward") for use by a 3rd party logging solution. The constructor may be left blank to default the ramp rate to 1 volt per second and the step voltage to 7 volts.
+
+.. note:: Not all 3rd party loggers will interact with SysIdRoutine directly. CTRE users who do not wish to use SysIdRoutine directly for logging should use the `SignalLogger <https://pro.docs.ctr-electronics.com/en/latest/docs/api-reference/api-usage/signal-logging.html>`__ API and use Tuner X to convert to wpilog. REV users may use Team 6328's `Unofficial REV-Compatible Logger (URCL) <https://github.com/Mechanical-Advantage/AdvantageScope/blob/main/docs/REV-LOGGING.md>`__. In both cases the log callback should be set to ``null``. Once the log file is in hand, it may be used with SysId just like any other.
+
+The timeout and state callback are optional and defaulted to 10 seconds and null (which will log the data to a normal WPILog file) respectively.
+
+Declaring the Mechanism
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``Mechanism`` object takes a voltage consumer, a log consumer, the subsystem being characterized, and the name of the mechanism (to record in the log). The drive callback takes in the routine-generated voltage command and passes it to the relevant motors. The log callback reads the motor voltage, position, and velocity for each relevant motor and adds it to the running log. The subsystem is required so that it may be added to the requirements of the routine commands. The name is optional and will be defaulted to the string returned by getName().
+
+The callbacks can either be created in-place via Lambda expressions or can be their own standalone functions and be passed in via method references. Best practice is to create the routine and callbacks inside the subsystem, to prevent leakage.
+
+.. tab-set-code::
+
+  .. code-block:: java
+
+    // Creates a SysIdRoutine
+    SysIdRoutine routine = new SysIdRoutine(
+        new SysIdRoutine.Config(),
+        new SysIdRoutine.Mechanism(this::voltageDrive, this::logMotors, this)
+    );
+
+Mechanism Callbacks
+^^^^^^^^^^^^^^^^^^^
+
+The ``Mechanism`` callbacks are essentially just plumbing between the routine and your motors and sensors.
+
+The ``drive`` callback exists so that you can pass the requested voltage directly to your motor controller(s).
+
+The ``log`` callback reads sensors so that the routine can log the voltage, position, and velocity at each timestep.
+
+See the SysIdRoutine (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/sysid>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/SysId>`__) example project for example callbacks.
+
+Test Factories
+^^^^^^^^^^^^^^^^^
+
+To be able to run the tests, SysIdRoutine exposes test "factories", or functions that each return a command that will execute a given test.
+
+.. tab-set-code::
+
+  .. code-block:: java
+
+    public Command sysIdQuasistatic(SysIdRoutine.Direction direction) {
+      return m_sysIdRoutine.quasistatic(direction);
+    }
+
+    public Command sysIdDynamic(SysIdRoutine.Direction direction) {
+      return m_sysIdRoutine.dynamic(direction);
+    }
+
+Either bind the factory methods to either controller buttons or an create an autonomous routine with them. It is recommended to bind them to buttons that the user must hold down for the duration of the test so that the user can stop the routine quickly if it exceeds safe limits.

source/docs/software/pathplanning/system-identification/index.rst → source/docs/software/advanced-controls/system-identification/index.rst

@@ -5,10 +5,9 @@ System Identification
    :maxdepth: 1
 
    introduction
-   configuring-project
-   identification-routine
-   analyzing-data
+   creating-routine
+   running-routine
+   loading-data
    viewing-diagnostics
-   analyzing-feedback
+   analyzing-gains
    additional-utils
-