Update Livewindow docs (#1674)

* Update SmartDashboard Livewindow / Test Mode docs

Fix code examples
Update screenshots
Rewrite Test Mode article to reference exiting LiveWindow Smartdashboard
docs, removing duplicated and conflicting information
Moves Test mode article from VS Code to Basic Programming
Add link to Test mode article from DS, and add other mode descriptions
Fixes #514

* Apply suggestions from code review

Co-authored-by: Dalton Smith <[email protected]>

* Fix AddLW usage

Co-authored-by: Dalton Smith <[email protected]>

Author: sciencewhiz

source/docs/software/basic-programming/index.rst

@@ -7,4 +7,5 @@ Basic Programming
    git-getting-started.rst
    cpp-units
    joystick
+   using-test-mode
    reading-stacktraces

source/docs/software/basic-programming/using-test-mode.rst

@@ -0,0 +1,26 @@
+Using Test Mode
+===============
+
+Test mode is designed to enable programmers to have a place to put code to verify that all systems on the robot are functioning. In each of the robot program templates there is a place to add test code to the robot.
+
+Enabling Test Mode
+------------------
+
+.. image:: /docs/software/dashboards/smartdashboard/test-mode-and-live-window/images/enabling-test-mode/setting-test-mode-driver-station.png
+   :alt: Selecting the "Test" button on the Driver Station and then "Enable".
+
+Test mode on the robot can be enabled from the Driver Station just like autonomous or teleop. To enable test mode in the Driver Station, select the "Test" button and enable the robot. The test mode code will then run.
+
+LiveWindow in Test Mode
+-----------------------
+
+With LiveWindow, all actuator's outputs can be controlled on the Dashboard and all sensor values can be seen. PID Controllers can also be tuned. The sensors and actuators are added automatically, no code is necessary. See :doc:`/docs/software/dashboards/smartdashboard/test-mode-and-live-window/index` for more details.
+
+Adding Test mode code to your robot code
+----------------------------------------
+
+When in test mode, the ``testInit`` method is run once, and the testPeriodic method is run once per tick, in addition to ``robotPeriodic``, similar to teleop and autonomous control modes.
+
+Adding test mode can be as painless as calling your already written Teleop methods from Test. Or you can write special code to try out a new feature that is only run in Test mode, before integrating it into your teleop or autonomous code. You could even write code to move all motors and check all sensors to help the pit crew!
+
+.. warning:: If you write your own test code, it may interfere with the LiveWindow code that can control actuators and is enabled automatically. You may need to call ``LiveWindow.getInstance().setEnabled(false)`` in your testInit method to avoid this.

source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/displaying-LiveWindow-values.rst

@@ -1,9 +1,7 @@
 Displaying LiveWindow Values
 ============================
 
-.. note:: LiveWindow will automatically add your sensors for you. There is no need to do it manually.
-
-LiveWindow values may also be displayed by writing the code yourself and adding it to your robot program. LiveWindow will display values grouped in subsystems. This is a convenient method of displaying whether they are actual command based program subsystems or just a grouping that you decide to use in your program.
+LiveWindow will automatically add your sensors and actuators for you. There is no need to do it manually. LiveWindow values may also be displayed by writing the code yourself and adding it to your robot program. This allows you to customize the names and group them in subsystems. This is a convenient method of displaying whether they are actual command based program subsystems or just a grouping that you decide to use in your program.
 
 Adding the Necessary Code to your Program
 -----------------------------------------
@@ -15,24 +13,50 @@ For each sensor or actuator that is created, set the subsystem name and display
     .. code-tab:: java
 
         Ultrasonic ultrasonic = new Ultrasonic(1, 2);
-        ultrasonic.setName("Arm", "Ultrasonic");
+        SendableRegistry.setName(ultrasonic, "Arm", "Ultrasonic");
+
+        Jaguar elbow = new Jaguar(1);
+        SendableRegistry.setName(elbow, "Arm", "Elbow");
+
+        Victor wrist = new Victor(2);
+        SendableRegistry.setName(wrist, "Arm", "Wrist");
+
+    .. code-tab:: cpp
+
+        frc::Ultrasonic ultrasonic{1, 2};
+        SendableRegistry::SetName(ultrasonic, "Arm", "Ultrasonic");
+
+        frc::Jaguar elbow{1};
+        SendableRegistry::SetName(elbow, "Arm", "Elbow");
+
+        frc::Victor wrist{2};
+        SendableRegistry::SetName(wrist, "Arm", "Wrist");
+
+If your objects are in a ``Subsystem``, this can be simplified using the addChild method of ``SubsystemBase``
+
+.. tabs::
+
+    .. code-tab:: java
+
+        Ultrasonic ultrasonic = new Ultrasonic(1, 2);
+        addChild("Ultrasonic", ultrasonic);
 
         Jaguar elbow = new Jaguar(1);
-        elbow.setName("Arm", "Elbow");
+        addChild("Elbow", elbow);
 
         Victor wrist = new Victor(2);
-        wrist.setName("Arm", "Wrist");
+        addChild("Wrist", wrist);
 
     .. code-tab:: cpp
 
         frc::Ultrasonic ultrasonic{1, 2};
-        ultrasonic.SetName("Arm", "Ultrasonic");
+        AddChild("Ultrasonic", ultrasonic);
 
         frc::Jaguar elbow{1};
-        elbow.SetName("Arm", "Elbow");
+        AddChild("Elbow", elbow);
 
         frc::Victor wrist{2};
-        wrist.SetName("Arm", "Wrist");
+        AddChild("Wrist", wrist);
 
 Viewing the Display in SmartDashboard
 -----------------------------------------

source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/enabling-test-mode.rst

@@ -14,15 +14,43 @@ Enable Test Mode in the Driver Station by clicking on the "Test" button and sett
 Explicitly vs. implicit test mode display
 -----------------------------------------
 
-.. image:: images/enabling-test-mode/explicit-test-mode-display.png
-   :alt: Highlights explicitly adding sensors to test in code.
+.. tabs::
 
-All sensors and actuators will automatically be displayed on the SmartDashboard in test mode and will be named using the object type (such as Jaguar, Analog, Victor, etc.) with the module number and channel number with which the object was created. In addition, the program can explicitly add sensors and actuators to the test mode display, in which case programmer-defined subsystem and object names can be specified making the program clearer. This example illustrates explicitly defining those sensors and actuators in the highlighted code.
+    .. code-tab:: java
+
+        PWMSparkMax leftDrive;
+        PWMSparkMax rightDrive;
+        PWMVictorSPX arm;
+        BuiltInAccelerometer accel;
+
+        @Override
+        public void robotInit() {
+          leftDrive = new PWMSparkMax(0);
+          rightDrive = new PWMSparkMax(1);
+          arm = new PWMVictorSPX(2);
+          accel = new BuiltInAccelerometer();
+          SendableRegistry.setName(arm, "SomeSubsystem", "Arm");
+          SendableRegistry.setName(accel, "SomeSubsystem", "Accelerometer");
+        }
+
+    .. code-tab:: cpp
+
+        frc::PWMSparkMax leftDrive{0};
+        frc::PWMSparkMax rigthDrive{1};
+        frc::BuiltInAccelerometer accel{};
+        frc::PWMVictorSPX arm{3};
+
+        void Robot::RobotInit() {
+          wpi::SendableRegistry::SetName(&arm, "SomeSubsystem", "Arm");
+          wpi::SendableRegistry::SetName(&accel, "SomeSubsystem", "Accelerometer");
+        }
+
+All sensors and actuators will automatically be displayed on the SmartDashboard in test mode and will be named using the object type (such as PWMSparkMax, PWMVictorSPX, BuiltInAccelerometer, etc.) with channel number with which the object was created. In addition, the program can explicitly add sensors and actuators to the test mode display, in which case programmer-defined subsystem and object names can be specified making the program clearer. This example illustrates explicitly defining those sensors and actuators.
 
 Understanding what is displayed in Test mode
 --------------------------------------------
 
 .. image:: images/enabling-test-mode/test-mode-display.png
    :alt: Highlights both ungrouped and subsystem motors displayed in test mode.
 
-This is the output in the SmartDashboard display when the robot is placed into test mode. In the display shown above the objects listed as Ungrouped were implicitly created by WPILib when the corresponding objects were created. These objects are contained in a subsystem group called "Ungrouped" **(1)** and are named with the device type (Analog, Jaguar in this case), and the module and channel numbers. The objects shown in the "SomeSubsystem" **(2)** group are explicitly created by the programmer from the code example in the previous section. These are named in the calls to ``LiveWindow.addActuator()`` and ``LiveWindow.AddSensor()``. Explicitly created sensors and actuators will be grouped by the specified subsystem.
+This is the output in the SmartDashboard display when the robot is placed into test mode. In the display shown above the objects listed as Ungrouped were implicitly created by WPILib when the corresponding objects were created. These objects are contained in a subsystem group called "Ungrouped" **(1)** and are named with the device type (PWMSparkMax in this case), and the channel numbers. The objects shown in the "SomeSubsystem" **(2)** group are explicitly created by the programmer from the code example in the previous section. These are named in the calls to ``SendableRegistry.setName()``. Explicitly created sensors and actuators will be grouped by the specified subsystem.

source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/images/enabling-test-mode/explicit-test-mode-display.png

@@ -48,7 +48,13 @@ Operation Tab
 
 The Operations Tab is used to control the mode of the robot and provide additional key status indicators while the robot is running.
 
-1. Robot Mode - This section controls the Robot Mode. Practice Mode causes the robot to cycle through the same transitions as an FRC match after the Enable button is pressed (timing for practice mode can be found on the setup tab).
+1. Robot Mode - This section controls the Robot Mode.
+
+  - Teleoperated Mode causes the robot to run the code in the Teleoperated portion of the match.
+  - Autonomous Mode causes the robot to run the code in the Autonomous portion of the match.
+  - Practice Mode causes the robot to cycle through the same transitions as an FRC match after the Enable button is pressed (timing for practice mode can be found on the setup tab).
+  - :doc:`Test Mode </docs/software/basic-programming/using-test-mode>` is an additional mode where test code that doesn't run in a regular match can be tested.
+
 2. Enable/Disable - These controls enable and disable the robot. See also `Driver Station Key Shortcuts`_
 3. Elapsed Time - Indicates the amount of time the robot has been enabled
 4. PC Battery - Indicates current state of DS PC battery and whether the PC is plugged in

source/docs/software/dashboards/smartdashboard/test-mode-and-live-window/images/enabling-test-mode/test-mode-display.png

@@ -12,4 +12,3 @@ VS Code Overview
    viewing-console-output
    debugging-robot-program
    importing-gradle-project
-   using-test-mode

source/docs/software/driverstation/driver-station.rst

@@ -247,3 +247,4 @@
 "docs/yearly-overview/2020-Game-Data.rst" "docs/yearly-overview/index.rst"
 "docs/software/labview/creating-robot-programs/creating-building-and-loading-your-benchtop-test-program.rst" "docs/zero-to-robot/step-4/creating-benchtop-test-program-labview.rst"
 "docs/software/labview/resources/talon-srx-can.rst" "docs/software/labview/resources/index.rst"
+"docs/software/vscode-overview/using-test-mode.rst" "docs/software/basic-programming/using-test-mode.rst"