From 7f2aeea857059977186269282f115f66db1113e3 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Sat, 30 Apr 2022 00:01:47 -0400 Subject: [PATCH 1/9] Add common field problems article --- .../troubleshooting/common-field-problems.rst | 45 +++++++++++++++++++ .../docs/software/troubleshooting/index.rst | 9 ++++ 2 files changed, 54 insertions(+) create mode 100644 source/docs/software/troubleshooting/common-field-problems.rst create mode 100644 source/docs/software/troubleshooting/index.rst diff --git a/source/docs/software/troubleshooting/common-field-problems.rst b/source/docs/software/troubleshooting/common-field-problems.rst new file mode 100644 index 0000000000..a188dffac4 --- /dev/null +++ b/source/docs/software/troubleshooting/common-field-problems.rst @@ -0,0 +1,45 @@ +Common Field Problems +===================== + +This article details some of the common problems that can plague your robot when it's on the field. It can be extremely frustrating and stressful when your robot breaks down. This article hopes to inform and instruct on what you can do to find the problem, and it's resolution. + +.. important:: Remember to never eliminate any possibility! It never hurts to double or even triple check that everything is working properly. + +Robot is stuttering and the RSL lights are dimming +-------------------------------------------------- + +Whenever your robot seems to give jerking motions and the RSL lights are dimming, this is usually a sign of :doc:`brownouts `. One of the first steps you can take to resolving a brownout is identify when it occurred and any notable correlating events. Did you go into a match with your battery too low? Are you drawing too much current somehow? Can you reproduce this in the pit? + +One of the most useful tools for identifying brownout causes is the :doc:`driver station log viewer `. + +.. todo:: add examples showcasing a brownout + +Joystick inputs seem to be dropping +----------------------------------- + +One of the characteristics of lost joystick inputs is when you press buttons or an axis and nothing happens! This can happen from a variety of reasons, so it's important to analyze which one is likely to your situation. + +.. todo:: looking at the driverstation log and identifying if lost joysticks is a code related .. error:: text + +.. todo:: Make some mention of the I2C issue + +Let's begin by asking a question. Can you reliably reproduce this issue at home or in the pits? + +Unable to connect to your robot? +-------------------------------- + +Setting up the driver station in the short few seconds before the match should be utilized to do a quick connectivity and joystick check. Assuming your robot is turned on and has been turned on for ~30-60 seconds, you might realize a problem has happened. Below are a list of common reasons you are unable to connect to your robot. + +- Disconnected ethernet connection on the driver station + - Is the ethernet port on the driver station functional? +- Disconnected ethernet connection on the robot + - Perhaps the rio <-> radio connection came unplugged + - Perhaps the ethernet cord is bad (can be identified by looking at the light indicators on the Rio/Radio for network activity) +- Is the firewall disabled? + - It is recommended that the firewall is always disabled when at an events + +.. todo:: add more and maybe some images + +You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. + +.. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. diff --git a/source/docs/software/troubleshooting/index.rst b/source/docs/software/troubleshooting/index.rst new file mode 100644 index 0000000000..e748178143 --- /dev/null +++ b/source/docs/software/troubleshooting/index.rst @@ -0,0 +1,9 @@ +Common Robot Troubleshooting +============================ + +This section details a variety of articles that may cover some problems you face when you actually go to get your robot up and moving. + +.. toctree:: + :maxdepth: 1 + + common-field-problems From 893735d8f0ad4a866a0bd5058e1d2097dac56891 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Sat, 30 Apr 2022 00:02:20 -0400 Subject: [PATCH 2/9] add to root toc --- source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/index.rst b/source/index.rst index ef3bc696e1..038ddd7b87 100644 --- a/source/index.rst +++ b/source/index.rst @@ -289,6 +289,7 @@ Community translations can be found in a variety of languages in the bottom-left docs/software/can-devices/index docs/software/basic-programming/index docs/software/support/support-resources + docs/software/troubleshooting/index docs/software/frc-glossary .. toctree:: From 9051fdcd161f0feefbef71e1bf3a16902bac748f Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Sat, 30 Apr 2022 00:09:42 -0400 Subject: [PATCH 3/9] Fix trailing whitespace --- source/docs/software/troubleshooting/common-field-problems.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/software/troubleshooting/common-field-problems.rst b/source/docs/software/troubleshooting/common-field-problems.rst index a188dffac4..e2cb04b800 100644 --- a/source/docs/software/troubleshooting/common-field-problems.rst +++ b/source/docs/software/troubleshooting/common-field-problems.rst @@ -40,6 +40,6 @@ Setting up the driver station in the short few seconds before the match should b .. todo:: add more and maybe some images -You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. +You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. .. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. From bcb78cb396f81f5c8d733fe35a037d8bc7eea635 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Tue, 16 Aug 2022 02:40:03 -0400 Subject: [PATCH 4/9] Add additional information --- .../troubleshooting/common-field-problems.rst | 27 ++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/source/docs/software/troubleshooting/common-field-problems.rst b/source/docs/software/troubleshooting/common-field-problems.rst index e2cb04b800..6c1c3e43ec 100644 --- a/source/docs/software/troubleshooting/common-field-problems.rst +++ b/source/docs/software/troubleshooting/common-field-problems.rst @@ -12,7 +12,9 @@ Whenever your robot seems to give jerking motions and the RSL lights are dimming One of the most useful tools for identifying brownout causes is the :doc:`driver station log viewer `. -.. todo:: add examples showcasing a brownout +.. image:: /docs/software/roborio-info/images/identifying-brownouts.png + +In the above image, you can see the brownout indicated by the highlighted orange line. The orange line represents dips (or lack of a straight line) in robot voltage. Joystick inputs seem to be dropping ----------------------------------- @@ -21,9 +23,28 @@ One of the characteristics of lost joystick inputs is when you press buttons or .. todo:: looking at the driverstation log and identifying if lost joysticks is a code related .. error:: text -.. todo:: Make some mention of the I2C issue +.. important:: There is a current :ref:`known issue ` where I2C reads can take a long time or lock up the roboRIO. + +Let's begin by asking a question. Can you reliably reproduce this issue at home or in the pits? This step is critical and assumptions *must not* be made. + +Yes, I can +^^^^^^^^^^ + +This eliminates bandwidth or connectivity issues to the FMS. Some areas to explore are: + +- Are joysticks working properly? + - Sometimes the issue can be as simple as a flakey USB cable or joystick. + +- Is the computer running slow or sluggish? Try restarting + - High CPU or Disk Utilization can be indicators the Driver Station itself is sending inputs late. + +- Is the code doing any long computation or loops? (Misuse of `for` and `while` loops can be common problems) + - In most cases, the use of any loops in FRC robot code can be avoided except in rare circumstances. + +No, I cannot +^^^^^^^^^^^^ -Let's begin by asking a question. Can you reliably reproduce this issue at home or in the pits? +This is likely a bandwidth or IP configuration issue. Try setting your IP configurations to :ref:`DHCP ` or :ref:`Static `. Another potential problem could be excessive bandwidth utilization. Try :ref:`measuring your bandwidth utilization `. Unable to connect to your robot? -------------------------------- From af9945eec4bf7d41b5a12ea3d0401bc81ff67698 Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Sun, 21 Aug 2022 11:31:34 -0500 Subject: [PATCH 5/9] troubleshooting skeleton --- .../docs/software/troubleshooting/can-bus.rst | 10 +++++ .../software/troubleshooting/code-build.rst | 36 ++++++++++++++++++ .../troubleshooting/gathering-information.rst | 10 +++++ .../bad-gradlew-project.png | Bin .../cpp_div_zero_stacktrace.png | Bin .../cpp_null_stacktrace.png | Bin .../cpp_vscode_dbg_tab.png | Bin .../software/troubleshooting/introduction.rst | 19 +++++++++ .../troubleshooting/loop-overruns.rst | 13 +++++++ .../software/troubleshooting/networking.rst | 15 ++++++++ .../reading-stacktraces.rst | 30 --------------- .../using-test-mode.rst | 0 12 files changed, 103 insertions(+), 30 deletions(-) create mode 100644 source/docs/software/troubleshooting/can-bus.rst create mode 100644 source/docs/software/troubleshooting/code-build.rst create mode 100644 source/docs/software/troubleshooting/gathering-information.rst rename source/docs/software/{basic-programming => troubleshooting}/images/reading-stacktraces/bad-gradlew-project.png (100%) rename source/docs/software/{basic-programming => troubleshooting}/images/reading-stacktraces/cpp_div_zero_stacktrace.png (100%) rename source/docs/software/{basic-programming => troubleshooting}/images/reading-stacktraces/cpp_null_stacktrace.png (100%) rename source/docs/software/{basic-programming => troubleshooting}/images/reading-stacktraces/cpp_vscode_dbg_tab.png (100%) create mode 100644 source/docs/software/troubleshooting/introduction.rst create mode 100644 source/docs/software/troubleshooting/loop-overruns.rst create mode 100644 source/docs/software/troubleshooting/networking.rst rename source/docs/software/{basic-programming => troubleshooting}/reading-stacktraces.rst (94%) rename source/docs/software/{basic-programming => troubleshooting}/using-test-mode.rst (100%) diff --git a/source/docs/software/troubleshooting/can-bus.rst b/source/docs/software/troubleshooting/can-bus.rst new file mode 100644 index 0000000000..9cc6cb8730 --- /dev/null +++ b/source/docs/software/troubleshooting/can-bus.rst @@ -0,0 +1,10 @@ +Debugging CAN-Related Problems +============================== + +Usual symptoms + +wiring + +termination + + diff --git a/source/docs/software/troubleshooting/code-build.rst b/source/docs/software/troubleshooting/code-build.rst new file mode 100644 index 0000000000..94d8a0b0ee --- /dev/null +++ b/source/docs/software/troubleshooting/code-build.rst @@ -0,0 +1,36 @@ +Debugging Issues while Building Code +==================================== + +Common Symptoms +--------------- + + +gradlew is not recognized... +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``gradlew is not recognized as an internal or external command`` is a common error that can occur when the project or directory that you are currently in does not contain a ``gradlew`` file. This usually occurs when you open the wrong directory. + +.. image:: images/reading-stacktraces/bad-gradlew-project.png + :alt: Image containing that the left-hand VS Code sidebar does not contain gradlew + +In the above screenshot, you can see that the left-hand sidebar does not contain many files. At a minimum, VS Code needs a couple of files to properly build and deploy your project. + +- ``gradlew`` +- ``build.gradle`` +- ``gradlew.bat`` + +If you do not see any one of the above files in your project directory, then you have two possible causes. + +- A corrupt or bad project. +- You are in the wrong directory. + +Fixing gradlew is not recognized... +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``gradlew is not recognized...`` is a fairly easy problem to fix. First identify the problem source: + +**Are you in the wrong directory?** +- Verify that the project directory is the correct directory and open this. + +**Is your project missing essential files?** +- This issue is more complex to solve. The recommended solution is to :ref:`recreate your project ` and manually copy necessary code in. diff --git a/source/docs/software/troubleshooting/gathering-information.rst b/source/docs/software/troubleshooting/gathering-information.rst new file mode 100644 index 0000000000..2c4523064d --- /dev/null +++ b/source/docs/software/troubleshooting/gathering-information.rst @@ -0,0 +1,10 @@ +Gathering Debug Information +=========================== + +Key driver station indicators + +rioLog + +using `ping` + +Manufacturer-specific interfaces \ No newline at end of file diff --git a/source/docs/software/basic-programming/images/reading-stacktraces/bad-gradlew-project.png b/source/docs/software/troubleshooting/images/reading-stacktraces/bad-gradlew-project.png similarity index 100% rename from source/docs/software/basic-programming/images/reading-stacktraces/bad-gradlew-project.png rename to source/docs/software/troubleshooting/images/reading-stacktraces/bad-gradlew-project.png diff --git a/source/docs/software/basic-programming/images/reading-stacktraces/cpp_div_zero_stacktrace.png b/source/docs/software/troubleshooting/images/reading-stacktraces/cpp_div_zero_stacktrace.png similarity index 100% rename from source/docs/software/basic-programming/images/reading-stacktraces/cpp_div_zero_stacktrace.png rename to source/docs/software/troubleshooting/images/reading-stacktraces/cpp_div_zero_stacktrace.png diff --git a/source/docs/software/basic-programming/images/reading-stacktraces/cpp_null_stacktrace.png b/source/docs/software/troubleshooting/images/reading-stacktraces/cpp_null_stacktrace.png similarity index 100% rename from source/docs/software/basic-programming/images/reading-stacktraces/cpp_null_stacktrace.png rename to source/docs/software/troubleshooting/images/reading-stacktraces/cpp_null_stacktrace.png diff --git a/source/docs/software/basic-programming/images/reading-stacktraces/cpp_vscode_dbg_tab.png b/source/docs/software/troubleshooting/images/reading-stacktraces/cpp_vscode_dbg_tab.png similarity index 100% rename from source/docs/software/basic-programming/images/reading-stacktraces/cpp_vscode_dbg_tab.png rename to source/docs/software/troubleshooting/images/reading-stacktraces/cpp_vscode_dbg_tab.png diff --git a/source/docs/software/troubleshooting/introduction.rst b/source/docs/software/troubleshooting/introduction.rst new file mode 100644 index 0000000000..b359cc8599 --- /dev/null +++ b/source/docs/software/troubleshooting/introduction.rst @@ -0,0 +1,19 @@ +Introduction to Troubleshooting +=============================== + +Issues will happen + +working methodically + +change one variable at a time + +Be careful and targeted with assumptions + +Be egoless + +Start by assuming single failure, be mindful of multiple failures + +Practice practice practice + +Symptom vs. Root Cause + diff --git a/source/docs/software/troubleshooting/loop-overruns.rst b/source/docs/software/troubleshooting/loop-overruns.rst new file mode 100644 index 0000000000..324cbfb783 --- /dev/null +++ b/source/docs/software/troubleshooting/loop-overruns.rst @@ -0,0 +1,13 @@ +Mitigating Loop Overruns +======================== + +Usual symptoms + +Soft real time system + +Periodic nature of execution + +Measuring execution time + +using the watchdog and epochs + diff --git a/source/docs/software/troubleshooting/networking.rst b/source/docs/software/troubleshooting/networking.rst new file mode 100644 index 0000000000..5f0d62b46a --- /dev/null +++ b/source/docs/software/troubleshooting/networking.rst @@ -0,0 +1,15 @@ +Debugging Network-Related Problems +================================== + +Usual symptoms + +Checking physical connections + +Checking wifi connections & interference + +Check power supply to radio or switch (resets) + +Check Firewall + +Try different ethernet port + diff --git a/source/docs/software/basic-programming/reading-stacktraces.rst b/source/docs/software/troubleshooting/reading-stacktraces.rst similarity index 94% rename from source/docs/software/basic-programming/reading-stacktraces.rst rename to source/docs/software/troubleshooting/reading-stacktraces.rst index 4980a9197f..0375522dd6 100644 --- a/source/docs/software/basic-programming/reading-stacktraces.rst +++ b/source/docs/software/troubleshooting/reading-stacktraces.rst @@ -598,33 +598,3 @@ In the example, the left motor controllers are plugged into PWM ports ``0`` and frc::PWMVictorSPX m_rearLeftMotor{1}; }; - -gradlew is not recognized... -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``gradlew is not recognized as an internal or external command`` is a common error that can occur when the project or directory that you are currently in does not contain a ``gradlew`` file. This usually occurs when you open the wrong directory. - -.. image:: images/reading-stacktraces/bad-gradlew-project.png - :alt: Image containing that the left-hand VS Code sidebar does not contain gradlew - -In the above screenshot, you can see that the left-hand sidebar does not contain many files. At a minimum, VS Code needs a couple of files to properly build and deploy your project. - -- ``gradlew`` -- ``build.gradle`` -- ``gradlew.bat`` - -If you do not see any one of the above files in your project directory, then you have two possible causes. - -- A corrupt or bad project. -- You are in the wrong directory. - -Fixing gradlew is not recognized... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``gradlew is not recognized...`` is a fairly easy problem to fix. First identify the problem source: - -**Are you in the wrong directory?** -- Verify that the project directory is the correct directory and open this. - -**Is your project missing essential files?** -- This issue is more complex to solve. The recommended solution is to :ref:`recreate your project ` and manually copy necessary code in. diff --git a/source/docs/software/basic-programming/using-test-mode.rst b/source/docs/software/troubleshooting/using-test-mode.rst similarity index 100% rename from source/docs/software/basic-programming/using-test-mode.rst rename to source/docs/software/troubleshooting/using-test-mode.rst From f75904521b815bf39bb1130a08c6ecec4b993ef4 Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Sun, 21 Aug 2022 12:23:31 -0500 Subject: [PATCH 6/9] more wip troubleshooting --- .../docs/software/basic-programming/index.rst | 4 +- .../software/driverstation/driver-station.rst | 2 +- .../docs/software/troubleshooting/index.rst | 14 ++++ .../software/troubleshooting/introduction.rst | 72 ++++++++++++++++--- source/index.rst | 1 + 5 files changed, 81 insertions(+), 12 deletions(-) create mode 100644 source/docs/software/troubleshooting/index.rst diff --git a/source/docs/software/basic-programming/index.rst b/source/docs/software/basic-programming/index.rst index 56a8d48105..2fb75f462c 100644 --- a/source/docs/software/basic-programming/index.rst +++ b/source/docs/software/basic-programming/index.rst @@ -7,6 +7,4 @@ Basic Programming git-getting-started.rst cpp-units joystick - robot-preferences - using-test-mode - reading-stacktraces + robot-preferences \ No newline at end of file diff --git a/source/docs/software/driverstation/driver-station.rst b/source/docs/software/driverstation/driver-station.rst index e2769d450f..182ef4ce07 100644 --- a/source/docs/software/driverstation/driver-station.rst +++ b/source/docs/software/driverstation/driver-station.rst @@ -65,7 +65,7 @@ The Operations Tab is used to control the mode of the robot and provide addition - 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 ` is an additional mode where test code that doesn't run in a regular match can be tested. + - :doc:`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. diff --git a/source/docs/software/troubleshooting/index.rst b/source/docs/software/troubleshooting/index.rst new file mode 100644 index 0000000000..95f258fcc9 --- /dev/null +++ b/source/docs/software/troubleshooting/index.rst @@ -0,0 +1,14 @@ +Troubleshooting +=============== + +.. toctree:: + :maxdepth: 1 + + introduction.rst + gathering-information.rst + code-build.rst + reading-stacktraces.rst + using-test-mode.rst + loop-overruns.rst + can-bus.rst + networking.rst diff --git a/source/docs/software/troubleshooting/introduction.rst b/source/docs/software/troubleshooting/introduction.rst index b359cc8599..3c0ba3a45e 100644 --- a/source/docs/software/troubleshooting/introduction.rst +++ b/source/docs/software/troubleshooting/introduction.rst @@ -1,19 +1,75 @@ Introduction to Troubleshooting =============================== -Issues will happen +*Troubleshooting* is the art of identifying the causes of problems, and using the cause to iterate a better solution. -working methodically +Issues Will Happen +------------------ -change one variable at a time +Every robot will experience problems. These can be frustrating! Rest assured, fixing these issues is something every team goes through in a season. -Be careful and targeted with assumptions +This section of the docs is designed to help teams identify and fix common robot issues which have control-system root causes. While not an exhaustive list of all possible issues, the hope is to provide general guidance and specific examples to reduce the most common pain points. -Be egoless +Symptom vs. Root Cause +---------------------- -Start by assuming single failure, be mindful of multiple failures +When troubleshooting, be sure to separate *Symptom* and *Root Cause*. -Practice practice practice +The *Symptom* is the behavior you actually observe, which is not correct. For example, a robot which can only turn in place (and cannot drive straight) is a *symptom* a team might observe. -Symptom vs. Root Cause +The *Root Cause* is the incorrect software, electrical hookup, or mechanical fault which actually caused the symptom to occur. + +When troubleshooting effectively, a team will work backward from the observed symptom, to the root cause. Ideally, the root cause gets fixed, and in turn the symptom stops manifesting. + +Sometimes, resource constraints might make a team "patch over" a symptom without identifying or fixing root cause. Teams should tread cautiously here, as patches are prone to break or cause more issues later on. + +On Working Methodically +----------------------- + +Effective troubleshooting requires teams to work methodically. + +The Scientific Process, in Real-Time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The core of all troubleshooting strategies is the same as the scientific process. Namely: + + . Observe the world around you + . Propose a hypothesis + . Design and execute a test of that hypothesis + . Observe and interpret the results + . Repeat + +In the case of most FRC robot troubleshooting, the hypothesis will be relatively small. A valid hypothesis could simply be "If I add a `* -1` to line 354 of my code, it should fix the motor that's running backward". The experiment would then be to make the change, upload the code, and attempt to reproduce the backward motor issue. If the motor is now running the correct direction, it is reasonable to assume the hypothesis was correct, and no further action is needed. However, if the issue persists, one could assume the hypothesis was not entirely correct, and the process must be repeated with a new hypothesis. + +Change One Variable at a Time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When interpreting the results of an experiment, it is critical that the experiment has controlled for all but one variable. Having only one changing variable is what allows experiment results to be interpreted to a single root cause. + +If many variables change, and the problem goes away, you will not know which variable actually fixed the root cause. + +While it may be tempting to change a lot of things hoping one of them fixes the issue, this will likely lead to a lot of things changed unnecessarily. + +Be Targeted with Assumptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A naïve approach to troubleshooting will start by assuming *anything* could be the root cause, and + +Be Egoless +^^^^^^^^^^ + +Single vs. Multiple Points of Failure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +Undirected Guess and Check is Ineffective +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Practice, Practice, Practice +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Troubleshooting is a learned skill. While there are few concrete facts and figures to memorize, seeing examples of failures and their root causes over and over again is the best way to get better at isolating root causes from symptoms. + +One will often see more experienced mentors or students look at an issue and quickly state a root cause. And, often, they'll be correct. Rest assured, this ability isn't magical or genetic - it's learned. Folks who are good at troubleshooting will *still* go through all the steps and processes these docs describe. However, they draw from a broader set of exposure to recognize patterns faster, and eliminate unlikely possibilities. +Be intentional about spending time practicing troubleshooting, and try not to worry if it takes longer than others. diff --git a/source/index.rst b/source/index.rst index ef3bc696e1..9122351756 100644 --- a/source/index.rst +++ b/source/index.rst @@ -288,6 +288,7 @@ Community translations can be found in a variety of languages in the bottom-left docs/software/hardware-apis/index docs/software/can-devices/index docs/software/basic-programming/index + docs/software/troubleshooting/index docs/software/support/support-resources docs/software/frc-glossary From 8b95e33d07729836c6abafe6ad2a856e9401ef8c Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Mon, 22 Aug 2022 08:21:05 -0500 Subject: [PATCH 7/9] Merge Cleanup --- .../troubleshooting/common-field-problems.rst | 16 +------------- .../software/troubleshooting/networking.rst | 22 +++++++++++++++++++ 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/source/docs/software/troubleshooting/common-field-problems.rst b/source/docs/software/troubleshooting/common-field-problems.rst index 6c1c3e43ec..0948fb71d7 100644 --- a/source/docs/software/troubleshooting/common-field-problems.rst +++ b/source/docs/software/troubleshooting/common-field-problems.rst @@ -49,18 +49,4 @@ This is likely a bandwidth or IP configuration issue. Try setting your IP config Unable to connect to your robot? -------------------------------- -Setting up the driver station in the short few seconds before the match should be utilized to do a quick connectivity and joystick check. Assuming your robot is turned on and has been turned on for ~30-60 seconds, you might realize a problem has happened. Below are a list of common reasons you are unable to connect to your robot. - -- Disconnected ethernet connection on the driver station - - Is the ethernet port on the driver station functional? -- Disconnected ethernet connection on the robot - - Perhaps the rio <-> radio connection came unplugged - - Perhaps the ethernet cord is bad (can be identified by looking at the light indicators on the Rio/Radio for network activity) -- Is the firewall disabled? - - It is recommended that the firewall is always disabled when at an events - -.. todo:: add more and maybe some images - -You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. - -.. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. +See :ref:`networking:Usual symptoms` \ No newline at end of file diff --git a/source/docs/software/troubleshooting/networking.rst b/source/docs/software/troubleshooting/networking.rst index 5f0d62b46a..86b710ef95 100644 --- a/source/docs/software/troubleshooting/networking.rst +++ b/source/docs/software/troubleshooting/networking.rst @@ -2,14 +2,36 @@ Debugging Network-Related Problems ================================== Usual symptoms +-------------- + +Setting up the driver station in the short few seconds before the match should be utilized to do a quick connectivity and joystick check. Assuming your robot is turned on and has been turned on for ~30-60 seconds, you might realize a problem has happened. Below are a list of common reasons you are unable to connect to your robot. + +- Disconnected ethernet connection on the driver station + - Is the ethernet port on the driver station functional? +- Disconnected ethernet connection on the robot + - Perhaps the rio <-> radio connection came unplugged + - Perhaps the ethernet cord is bad (can be identified by looking at the light indicators on the Rio/Radio for network activity) +- Is the firewall disabled? + - It is recommended that the firewall is always disabled when at an events + +.. todo:: add more and maybe some images + +You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. + +.. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. Checking physical connections +------------------------------ Checking wifi connections & interference +---------------------------------------- Check power supply to radio or switch (resets) +---------------------------------------------- Check Firewall +-------------- Try different ethernet port +--------------------------- From 56acbe72240aa85e78a117c7c51cac60d172a096 Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Mon, 22 Aug 2022 18:21:18 -0500 Subject: [PATCH 8/9] more wip --- .../software/troubleshooting/code-build.rst | 4 + .../troubleshooting/gathering-information.rst | 98 ++++++++++++++++++- .../software/troubleshooting/introduction.rst | 18 +++- .../troubleshooting/loop-overruns.rst | 35 ++++++- .../software/troubleshooting/networking.rst | 13 ++- 5 files changed, 150 insertions(+), 18 deletions(-) diff --git a/source/docs/software/troubleshooting/code-build.rst b/source/docs/software/troubleshooting/code-build.rst index 94d8a0b0ee..6d5b88023a 100644 --- a/source/docs/software/troubleshooting/code-build.rst +++ b/source/docs/software/troubleshooting/code-build.rst @@ -34,3 +34,7 @@ Fixing gradlew is not recognized... **Is your project missing essential files?** - This issue is more complex to solve. The recommended solution is to :ref:`recreate your project ` and manually copy necessary code in. + + +Driving toward Root Cause +------------------------- \ No newline at end of file diff --git a/source/docs/software/troubleshooting/gathering-information.rst b/source/docs/software/troubleshooting/gathering-information.rst index 2c4523064d..288aa14d8a 100644 --- a/source/docs/software/troubleshooting/gathering-information.rst +++ b/source/docs/software/troubleshooting/gathering-information.rst @@ -1,10 +1,102 @@ Gathering Debug Information =========================== -Key driver station indicators +During the cycle of troubleshooting, a key step is to gather data. A large amount of the behavior of a robot's control system is *hidden* from view, and requires special tools to observe. While not exhaustive, the following is a list of common tools that robot software developers should be familiar with. + +Driver Station +-------------- + +The National Instruments DriverStation is the first place to check when robot does not behave as expected. + +Key Indicators +^^^^^^^^^^^^^^ + +TODO + +Timeseries Logs +^^^^^^^^^^^^^^^ + +TODO rioLog +------ + +rioLog is a utility built into the WPILib suite and vsCode. It allows you to remotely view all of the `stdout` and `stderr` messages from your robot program. This includes all warnings, error messages, and print statements that your robot program generates. You can write your own software to generate these messages, as well as read the messages produced by WPILib or a 3rd party. + +It is also mirrored into the console of the DriverStation. + +Command Line Utilities +---------------------- + +The Windows command prompt has a number of useful tools for troubleshooting. + +The Windows command prompt may be accessed from the start menu. It is named `cmd.exe`. The commands we describe here should be typed into the command prompt. + +Using `ping` +^^^^^^^^^^^^ + +`ping` is a utility built into Windows which allows for a basic network connection check between two points. It confirms basic functionality of both the physical layer (wiring or wireless), and a small portion of software. + +It can be invoked by typing `ping`, followed by a space, followed by the IP address to be checked, followed by Enter. For example, checking the IP address `10.12.34.1`: + +.. code-block:: console + + C:\Users\YOUR_USER>ping 10.12.34.1 + + Pinging 10.12.34.1 with 32 bytes of data: + Reply from 10.12.34.1: bytes=32 time=3ms TTL=128 + Reply from 10.12.34.1: bytes=32 time=3ms TTL=128 + Reply from 10.12.34.1: bytes=32 time=3ms TTL=128 + Reply from 10.12.34.1: bytes=32 time=3ms TTL=128 + + Ping statistics for 10.12.34.1: + Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), + Approximate round trip times in milli-seconds: + Minimum = 3ms, Maximum = 3ms, Average = 3ms + +This shows four test "pings" being sent, and the device with IP address `10.12.34.1` responding with a "Yup, I hear ya!" message within three milliseconds. + +If None of the pings are responded to, it would likely indicate some total failure which prevents communication - perhaps a cable is unplugged, or the device is turned off, or doesn't have the expected IP address. + +If only some of the packets come back, it would indicate a partial failure preventing some communication. Perhaps a cable is loose, the wifi network is being rate limited or interfered with. + +Using `ipconfig` +^^^^^^^^^^^^^^^^ + +`ipconfig` is a utility built into Windows which summarizes the configuration of the network interfaces on the device. It can help confirm your computer is actually attached to a robot network, and should be capable of communicating with robot components. + +It is invoked simply by typing `ipconfig` and hitting Enter. + +Here is an example of running it on a computer with one wireless (wifi) network interface and one wired (ethernet) interface, but with neither connected. + +.. code-block:: console + + C:\Users\YOUR_USER>ipconfig + + Windows IP Configuration + + + Wireless LAN adapter Local Area Connection* 1: + + Media State . . . . . . . . . . . : Media disconnected + Connection-specific DNS Suffix . : + + Wireless LAN adapter Wi-Fi: + + Media State . . . . . . . . . . . : Media disconnected + Connection-specific DNS Suffix . : + +Here is another example with the wifi network properly connected to a robot: + +.. code-block:: console + + C:\Users\YOUR_USER>ipconfig + + TODO + +Manufacturer-Specific Interfaces +-------------------------------- + +REV Robotics, Cross the Road Electronics, and Playing with Fusion all supply additional utilities for configuring and troubleshooting their hardware. -using `ping` -Manufacturer-specific interfaces \ No newline at end of file diff --git a/source/docs/software/troubleshooting/introduction.rst b/source/docs/software/troubleshooting/introduction.rst index 3c0ba3a45e..68471c6cb4 100644 --- a/source/docs/software/troubleshooting/introduction.rst +++ b/source/docs/software/troubleshooting/introduction.rst @@ -50,20 +50,28 @@ If many variables change, and the problem goes away, you will not know which var While it may be tempting to change a lot of things hoping one of them fixes the issue, this will likely lead to a lot of things changed unnecessarily. -Be Targeted with Assumptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Undirected Guess and Check is Ineffective +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A naïve approach to troubleshooting will start by assuming *anything* could be the root cause, and pursue each option one by one. However, in a large and complex system (like a robot), the number of possibilities can be too large to effectively test each one, one by one. + +From this perspective, it is best to start by making a few assumptions about what root causes are *most likely*, and test those first. As you get more experience doing troubleshooting, you'll gain a better intuition for where to start looking for problems. -A naïve approach to troubleshooting will start by assuming *anything* could be the root cause, and +However, keep in mind that these are *assumptions*. They're educated guesses as to where the problem *likely is not*, not exhaustive proof that a problem doesn't exist. Always be ready to go back and undo your assumptions if needed. Be Egoless ^^^^^^^^^^ +When troubleshooting, emotions can often start flying, as it sometimes appears blame is being placed. People can get defensive when their component or their design is called into question. + +It's important to keep in mind that everyone is on the same team, working toward the same goal. Be careful to choose words and descriptions which describe and judge ideas, not people. Furthermore, try not to let your own ego and biases get in the way of considering possible faults in the systems you are responsible for. + Single vs. Multiple Points of Failure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The most effective way to troubleshoot is to start by assuming that a *single point of failure* has triggered the symptom. For well designed, simple systems, this is usually the case. -Undirected Guess and Check is Ineffective -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +However, as systems get larger and more complex, it's very possible multiple failures might exist. While this should always be a *secondary* assumption, be careful not to ignore the fact a symptom may be caused by multiple, interacting failures. Practice, Practice, Practice ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/docs/software/troubleshooting/loop-overruns.rst b/source/docs/software/troubleshooting/loop-overruns.rst index 324cbfb783..80d73ccf5e 100644 --- a/source/docs/software/troubleshooting/loop-overruns.rst +++ b/source/docs/software/troubleshooting/loop-overruns.rst @@ -1,13 +1,38 @@ Mitigating Loop Overruns ======================== -Usual symptoms +A *loop overrun* is a common occurrence when teams scale up their codebases. It occurs when a piece of code takes too long to execute, "starving" other code of the time it needs to run. -Soft real time system +Real-Time System +---------------- -Periodic nature of execution +Our robots are *real-time systems*. Code must execute in a way that the time between reading inputs, performing calculations, and assigning outputs is bounded and deterministic. In doing so, the code establishes the relationship of how outputs change in response to inputs. -Measuring execution time +When code runs too slowly, that input-output relationship is no longer maintained, causing complex and unexpected behaviors. -using the watchdog and epochs +Common Symptoms +-------------- + +One key symptom is seeing this message frequently in RIOLog: + +.. code-block:: text + TODO + +The the bigger the TODO number is, the more sever the loop overrun is. + +In extreme cases, the robot may move in a "jerky" or uncontrollable manner, not responding promptly to inputs or sensor value changes. + + +Driving toward Root Cause +------------------------- + +A common first step is to simply inspect the codebase. Misuse of `for` or `while` loops can increase processing time very rapidly. Using `.sleep()` methods or lots of `print()` statements can do similar things. Less likely but also possible, a function which calls itself can act like a loop. + +If a simple code inspection does not work, execution time can be measured with a few built-in WPILib methods. + +`Timer.getFPGATimestamp()` will return the current number of seconds since the RIO booted, to a high decimal precision. By reading the time before and after code executes and subtracting them, you can calculate how long a certain piece of code takes to execute. By doing this in many spots, you can start to identify which pieces of code take longer than others to run. + +WPILib also provides a `Watchdog` class (Link me). By creating a watchdog and adding Epochs, you can generate nice reports of how long it takes to execute through certain pieces of code. + +TODO Watchdog and Epochs. diff --git a/source/docs/software/troubleshooting/networking.rst b/source/docs/software/troubleshooting/networking.rst index 86b710ef95..b73aa7e71e 100644 --- a/source/docs/software/troubleshooting/networking.rst +++ b/source/docs/software/troubleshooting/networking.rst @@ -20,18 +20,21 @@ You should immediately notify the FTA that there is a connectivity issue for the .. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. +Driving toward Root Cause +------------------------- + Checking physical connections ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Checking wifi connections & interference ----------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check power supply to radio or switch (resets) ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check Firewall --------------- +^^^^^^^^ Try different ethernet port ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 29c5b83bbf269189ce1f3bc728602ba236597ca9 Mon Sep 17 00:00:00 2001 From: Chris Gerth Date: Sat, 27 Aug 2022 10:36:42 -0500 Subject: [PATCH 9/9] more WIP on troubleshooting docs --- .../driver-station-log-viewer.rst | 2 +- source/docs/software/driverstation/index.rst | 1 - .../troubleshooting/common-field-problems.rst | 2 +- .../driver-station-errors-warnings.rst | 0 .../troubleshooting/gathering-information.rst | 50 +++++++------ .../docs/software/troubleshooting/index.rst | 2 + .../troubleshooting/loop-overruns.rst | 72 ++++++++++++++++--- .../software/troubleshooting/networking.rst | 8 +-- source/redirects.txt | 2 + 9 files changed, 104 insertions(+), 35 deletions(-) rename source/docs/software/{driverstation => troubleshooting}/driver-station-errors-warnings.rst (100%) diff --git a/source/docs/software/driverstation/driver-station-log-viewer.rst b/source/docs/software/driverstation/driver-station-log-viewer.rst index 728f1743e2..0249561b62 100644 --- a/source/docs/software/driverstation/driver-station-log-viewer.rst +++ b/source/docs/software/driverstation/driver-station-log-viewer.rst @@ -82,7 +82,7 @@ When diagnosing robot issues, there is no substitute for thorough knowledge of t .. note:: Note that all log files shown in this section have been scaled to match length using the Match Length button and then scrolling to the beginning of the autonomous mode. Also, many of the logs do not contain battery voltage information, the platform used for log capture was not properly wired for reporting the battery voltage. -.. tip:: Some error messages that are found in the Log Viewer are show below and more are detailed in the :doc:`driver-station-errors-warnings` article. +.. tip:: Some error messages that are found in the Log Viewer are show below and more are detailed in the :doc:`docs/software/troubleshooting/driver-station-errors-warnings` article. "Normal" Log ~~~~~~~~~~~~ diff --git a/source/docs/software/driverstation/index.rst b/source/docs/software/driverstation/index.rst index 4590b170c3..cb4003323a 100644 --- a/source/docs/software/driverstation/index.rst +++ b/source/docs/software/driverstation/index.rst @@ -7,7 +7,6 @@ Driver Station driver-station driver-station-best-practices driver-station-log-viewer - driver-station-errors-warnings programming-radios-for-fms-offseason imaging-your-classmate manually-setting-the-driver-station-to-start-custom-dashboard diff --git a/source/docs/software/troubleshooting/common-field-problems.rst b/source/docs/software/troubleshooting/common-field-problems.rst index 0948fb71d7..5585abc9f4 100644 --- a/source/docs/software/troubleshooting/common-field-problems.rst +++ b/source/docs/software/troubleshooting/common-field-problems.rst @@ -49,4 +49,4 @@ This is likely a bandwidth or IP configuration issue. Try setting your IP config Unable to connect to your robot? -------------------------------- -See :ref:`networking:Usual symptoms` \ No newline at end of file +See :ref:`docs/software/troubleshooting/networking:Usual Symptoms` \ No newline at end of file diff --git a/source/docs/software/driverstation/driver-station-errors-warnings.rst b/source/docs/software/troubleshooting/driver-station-errors-warnings.rst similarity index 100% rename from source/docs/software/driverstation/driver-station-errors-warnings.rst rename to source/docs/software/troubleshooting/driver-station-errors-warnings.rst diff --git a/source/docs/software/troubleshooting/gathering-information.rst b/source/docs/software/troubleshooting/gathering-information.rst index 288aa14d8a..d0c6447d79 100644 --- a/source/docs/software/troubleshooting/gathering-information.rst +++ b/source/docs/software/troubleshooting/gathering-information.rst @@ -8,36 +8,30 @@ Driver Station The National Instruments DriverStation is the first place to check when robot does not behave as expected. -Key Indicators -^^^^^^^^^^^^^^ +In particular, the :ref:`Diagnostics Tab ` and :ref:`Messages Tab ` frequently contain the minimum info needed to start driving toward root cause on a problem. -TODO - -Timeseries Logs -^^^^^^^^^^^^^^^ - -TODO +Additionally, the :ref:`Log File Viewer ` for more info. Command Line Utilities ---------------------- The Windows command prompt has a number of useful tools for troubleshooting. -The Windows command prompt may be accessed from the start menu. It is named `cmd.exe`. The commands we describe here should be typed into the command prompt. +The Windows command prompt may be accessed from the start menu. It is named :code:`cmd.exe`. The commands we describe here should be typed into the command prompt. Using `ping` ^^^^^^^^^^^^ -`ping` is a utility built into Windows which allows for a basic network connection check between two points. It confirms basic functionality of both the physical layer (wiring or wireless), and a small portion of software. +:code:`ping` is a utility built into Windows which allows for a basic network connection check between two points. It confirms basic functionality of both the physical layer (wiring or wireless), and a small portion of software. -It can be invoked by typing `ping`, followed by a space, followed by the IP address to be checked, followed by Enter. For example, checking the IP address `10.12.34.1`: +It can be invoked by typing :code:`ping`, followed by a space, followed by the IP address to be checked, followed by Enter. For example, checking the IP address :code:`10.12.34.1`: .. code-block:: console @@ -54,18 +48,18 @@ It can be invoked by typing `ping`, followed by a space, followed by the IP addr Approximate round trip times in milli-seconds: Minimum = 3ms, Maximum = 3ms, Average = 3ms -This shows four test "pings" being sent, and the device with IP address `10.12.34.1` responding with a "Yup, I hear ya!" message within three milliseconds. +This shows four test "pings" being sent, and the device with IP address :code:`10.12.34.1` responding with a "Yup, I hear ya!" message within three milliseconds. If None of the pings are responded to, it would likely indicate some total failure which prevents communication - perhaps a cable is unplugged, or the device is turned off, or doesn't have the expected IP address. If only some of the packets come back, it would indicate a partial failure preventing some communication. Perhaps a cable is loose, the wifi network is being rate limited or interfered with. -Using `ipconfig` -^^^^^^^^^^^^^^^^ +Using :code:`ipconfig` +^^^^^^^^^^^^^^^^^^^^^^ -`ipconfig` is a utility built into Windows which summarizes the configuration of the network interfaces on the device. It can help confirm your computer is actually attached to a robot network, and should be capable of communicating with robot components. +:code:`ipconfig` is a utility built into Windows which summarizes the configuration of the network interfaces on the device. It can help confirm your computer is actually attached to a robot network, and should be capable of communicating with robot components. -It is invoked simply by typing `ipconfig` and hitting Enter. +It is invoked simply by typing :code:`ipconfig` and hitting Enter. Here is an example of running it on a computer with one wireless (wifi) network interface and one wired (ethernet) interface, but with neither connected. @@ -86,17 +80,33 @@ Here is an example of running it on a computer with one wireless (wifi) network Media State . . . . . . . . . . . : Media disconnected Connection-specific DNS Suffix . : -Here is another example with the wifi network properly connected to a robot: +Here is another example with the wifi network properly connected to team 1234's robot over wifi: .. code-block:: console C:\Users\YOUR_USER>ipconfig + + Windows IP Configuration + + + Wireless LAN adapter Wi-Fi: + + Connection-specific DNS Suffix . : localdomain + Link-local IPv6 Address . . . . . : fe80::890d:bbae:d81c:d416%7 + IPv4 Address. . . . . . . . . . . : 10.12.34.210 + Subnet Mask . . . . . . . . . . . : 255.255.255.0 + Default Gateway . . . . . . . . . : 10.12.34.1 - TODO Manufacturer-Specific Interfaces -------------------------------- +3rd party manufacturers support custom interfaces to help address problems that are specific to their hardware. These include: + + * `REV Robotics Hardware Client `__ + * `Cross the Road Electronics Pheonix Framework `__ + * `Playing with Fusion's Web-Based Configuration `__ + REV Robotics, Cross the Road Electronics, and Playing with Fusion all supply additional utilities for configuring and troubleshooting their hardware. diff --git a/source/docs/software/troubleshooting/index.rst b/source/docs/software/troubleshooting/index.rst index 95f258fcc9..570086e504 100644 --- a/source/docs/software/troubleshooting/index.rst +++ b/source/docs/software/troubleshooting/index.rst @@ -7,6 +7,8 @@ Troubleshooting introduction.rst gathering-information.rst code-build.rst + driver-station-errors-warnings.rst + common-field-problems.rst reading-stacktraces.rst using-test-mode.rst loop-overruns.rst diff --git a/source/docs/software/troubleshooting/loop-overruns.rst b/source/docs/software/troubleshooting/loop-overruns.rst index 80d73ccf5e..c186607ef1 100644 --- a/source/docs/software/troubleshooting/loop-overruns.rst +++ b/source/docs/software/troubleshooting/loop-overruns.rst @@ -11,14 +11,25 @@ Our robots are *real-time systems*. Code must execute in a way that the time bet When code runs too slowly, that input-output relationship is no longer maintained, causing complex and unexpected behaviors. Common Symptoms --------------- +--------------- -One key symptom is seeing this message frequently in RIOLog: +One key symptom is seeing a message like this frequently in RIOLog: .. code-block:: text - TODO + + Warning 1 Loop time of 0.02s overrun + edu.wpi.first.wpilibj.IterativeRobotBase.printLoopOverrunMessage(IterativeRobotBase.java:359) + Warning at edu.wpi.first.wpilibj.IterativeRobotBase.printLoopOverrunMessage(IterativeRobotBase.java:359): Loop time of 0.02s overrun + Warning 1 SmartDashboard.updateValues(): 0.000361s + disabledInit(): 0.000475s + robotPeriodic(): 0.310620s + LiveWindow.updateValues(): 0.202739s + Shuffleboard.update(): 0.000896s + disabledPeriodic(): 0.001021s + edu.wpi.first.wpilibj.Tracer.lambda$printEpochs$0(Tracer.java:63) -The the bigger the TODO number is, the more sever the loop overrun is. + +The the bigger the numbers after each step are, the more sever the loop overrun is. For example, the main problem here is that the :code:`robotPeriodic()` method took :code:`0.31062s` to complete. This is much larger than the 0.02s (20 ms) update rate the robot is supposed to be running at. In extreme cases, the robot may move in a "jerky" or uncontrollable manner, not responding promptly to inputs or sensor value changes. @@ -26,13 +37,58 @@ In extreme cases, the robot may move in a "jerky" or uncontrollable manner, not Driving toward Root Cause ------------------------- -A common first step is to simply inspect the codebase. Misuse of `for` or `while` loops can increase processing time very rapidly. Using `.sleep()` methods or lots of `print()` statements can do similar things. Less likely but also possible, a function which calls itself can act like a loop. +A common first step is to simply inspect the codebase. Misuse of :code:`for` or :code:`while` loops can increase processing time very rapidly. Using :code:`.sleep()` methods or lots of :code:`print()` statements can do similar things. Less likely but also possible, a function which calls itself can act like a loop. If a simple code inspection does not work, execution time can be measured with a few built-in WPILib methods. -`Timer.getFPGATimestamp()` will return the current number of seconds since the RIO booted, to a high decimal precision. By reading the time before and after code executes and subtracting them, you can calculate how long a certain piece of code takes to execute. By doing this in many spots, you can start to identify which pieces of code take longer than others to run. +:code:`Timer.getFPGATimestamp()` will return the current number of seconds since the RIO booted, to a high decimal precision. By reading the time before and after code executes and subtracting them, you can calculate how long a certain piece of code takes to execute. By doing this in many spots, you can start to identify which pieces of code take longer than others to run. + +WPILib also provides a `Tracer class `. By creating a Tracer and adding Epochs, you can generate nice reports of how long it takes to execute through certain pieces of code. + +.. tabs:: + .. group-tab:: Java + + .. code-block:: java + + import edu.wpi.first.wpilibj.Tracer; + + public class YourCode { + private Tracer t; + + public YourCode() { + t = new Tracer(); + } + + public void periodicUpdate() { + t.clearEpochs(); + + // Some code + + t.addEpoch("First Epoch"); + + // Some more code + + t.addEpoch("Another Epoch"); + + // Even more code + + t.addEpoch("Yet Another Epoch"); + + t.printEpochs(); + } + + } + + .. group-tab:: C++ (Header) + + .. code-block:: cpp + + //coming soon! + + .. group-tab:: C++ (Source) -WPILib also provides a `Watchdog` class (Link me). By creating a watchdog and adding Epochs, you can generate nice reports of how long it takes to execute through certain pieces of code. + .. code-block:: cpp -TODO Watchdog and Epochs. + //coming soon! +when :code:`printEpochs()` is called, a print statement will be generated listing out the duration that each period defined by `addEpoch()` took. By carefully placing your epochs, you can identify which pieces of code take longer than others, to know where you need to optimize your code. \ No newline at end of file diff --git a/source/docs/software/troubleshooting/networking.rst b/source/docs/software/troubleshooting/networking.rst index b73aa7e71e..88e1a6cab1 100644 --- a/source/docs/software/troubleshooting/networking.rst +++ b/source/docs/software/troubleshooting/networking.rst @@ -1,7 +1,7 @@ Debugging Network-Related Problems ================================== -Usual symptoms +Usual Symptoms -------------- Setting up the driver station in the short few seconds before the match should be utilized to do a quick connectivity and joystick check. Assuming your robot is turned on and has been turned on for ~30-60 seconds, you might realize a problem has happened. Below are a list of common reasons you are unable to connect to your robot. @@ -16,9 +16,9 @@ Setting up the driver station in the short few seconds before the match should b .. todo:: add more and maybe some images -You should immediately notify the FTA that there is a connectivity issue for the quickest resolution. +If on the field, you should immediately notify the FTA that there is a connectivity issue for the quickest resolution. -.. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot. +.. important:: While rare, it has been shown that the robot radio can sometimes take a large amount of time to boot - 90 seconds or more. Driving toward Root Cause ------------------------- @@ -33,7 +33,7 @@ Check power supply to radio or switch (resets) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check Firewall -^^^^^^^^ +^^^^^^^^^^^^^^ Try different ethernet port ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/redirects.txt b/source/redirects.txt index 7e2253c4e8..b68b9e47ed 100644 --- a/source/redirects.txt +++ b/source/redirects.txt @@ -265,3 +265,5 @@ "docs/software/pathplanning/pathweaver/creating-path-groups.rst" "docs/software/pathplanning/pathweaver/creating-autonomous-routines.rst" "docs/software/dashboards/smartdashboard/setting-robot-preferences-from-smartdashboard.rst" "docs/software/basic-programming/robot-preferences.rst" "docs/software/advanced-controls/introduction/tuning-pid-controller.rst" "docs/software/advanced-controls/introduction/tuning-flywheel.rst" +"docs/software/driverstation/driver-station-errors-warnings.rst" "docs/software/troubleshooting/driver-station-errors-warnings.rst" +"docs/software/basic-programming/using-test-mode.rst" "docs/software/troubleshooting/using-test-mode.rst" \ No newline at end of file