Document common causes of loop overruns #3132
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds comprehensive section explaining what loop overruns are and their common causes including blocking operations, excessive computation, excessive logging, and hardware issues. Includes tips for avoiding and diagnosing loop overruns. Fixes wpilibsuite#2315
sciencewhiz
reviewed
Oct 8, 2025
|
|
||
| ## Common Causes of Loop Overruns | ||
|
|
||
| Loop overruns occur when the robot's periodic methods (``robotPeriodic()``, ``teleopPeriodic()``, etc.) take longer than 20ms to complete. When this happens, the Driver Station will display a warning and the robot code may behave unpredictably. Here are common causes: |
There was a problem hiding this comment.
There should be an example of the warning so that people searching will find it.
| ### Excessive Logging or Print Statements | ||
|
|
||
| - **System.out.println() in loops**: Console output is slow, especially when called frequently | ||
| - **Verbose NetworkTables updates**: Updating many NetworkTables entries every loop iteration |
There was a problem hiding this comment.
Network tables updates should be fast. What might be slow is getting whatever data that is being put to NT
| - Profile your code to identify slow sections (see :ref:`docs/software/advanced-gradlerio/profiling-with-visualvm:profiling with visualvm`) | ||
| - Remove or reduce print statements, especially in frequently-called code | ||
| - Cache values that are expensive to compute rather than recalculating every loop | ||
| - Use the Driver Station log to identify which periodic method is causing overruns |
There was a problem hiding this comment.
Recommend going one level deeper on how to interpret the log in this case.
…al, expand DS log interpretation
katzuv
reviewed
Oct 9, 2025
|
|
||
| ### Blocking Operations | ||
|
|
||
| - **Thread.sleep() or wait()**: Never use blocking sleep or wait calls in periodic methods |
There was a problem hiding this comment.
Suggested change
| - **Thread.sleep() or wait()**: Never use blocking sleep or wait calls in periodic methods | |
| - **``Thread.sleep()`` or ``wait()``**: Never use blocking sleep or wait calls in periodic methods |
|
|
||
| ### Excessive Logging or Print Statements | ||
|
|
||
| - **System.out.println() in loops**: Console output is slow, especially when called frequently |
There was a problem hiding this comment.
Suggested change
| - **System.out.println() in loops**: Console output is slow, especially when called frequently | |
| - **Print statements (e.g. ``System.out.println``) in loops**: Console output is slow, especially when called frequently |
|
|
||
| ### Tips to Avoid Loop Overruns | ||
|
|
||
| - Use :doc:`Notifier </docs/software/convenience-features/scheduling-functions>` for operations that need precise timing independent of the main loop |
There was a problem hiding this comment.
Perhaps addPeriodic() is simpler?
| ### Hardware/Sensor Issues | ||
|
|
||
| - **Synchronous CAN calls**: Some motor controller methods may block waiting for a response | ||
| - **I2C or SPI timeouts**: Faulty sensors or loose connections can cause communication timeouts |
There was a problem hiding this comment.
Suggested change
| - **I2C or SPI timeouts**: Faulty sensors or loose connections can cause communication timeouts | |
| - **I²C or SPI timeouts**: Faulty sensors or loose connections can cause communication timeouts |
|
|
||
| - **System.out.println() in loops**: Console output is slow, especially when called frequently | ||
| - **Getting data to publish to NetworkTables**: While NetworkTables updates themselves are fast, retrieving complex data (e.g., vision processing results, large arrays) to publish can be slow | ||
| - **Excessive Shuffleboard updates**: Sending large amounts of data to the dashboard |
There was a problem hiding this comment.
Suggested change
| - **Excessive Shuffleboard updates**: Sending large amounts of data to the dashboard | |
| - **Excessive dashboard updates**: Sending large amounts of data to the dashboard (Shuffleboard, Elastic, etc.) |
| - Profile your code to identify slow sections (see :ref:`docs/software/advanced-gradlerio/profiling-with-visualvm:profiling with visualvm`) | ||
| - Remove or reduce print statements, especially in frequently-called code | ||
| - Cache values that are expensive to compute rather than recalculating every loop | ||
| - **Check the Driver Station log** to identify which periodic method is causing overruns. The log will show timestamps and which robot mode was active when the overrun occurred. Look for patterns - if overruns only happen during teleop, check ``teleopPeriodic()`` and subsystems used during teleop. If they occur consistently, check ``robotPeriodic()`` for code that runs regardless of mode. |
There was a problem hiding this comment.
Suggested change
| - **Check the Driver Station log** to identify which periodic method is causing overruns. The log will show timestamps and which robot mode was active when the overrun occurred. Look for patterns - if overruns only happen during teleop, check ``teleopPeriodic()`` and subsystems used during teleop. If they occur consistently, check ``robotPeriodic()`` for code that runs regardless of mode. | |
| - **Check the Driver Station log** to identify which periodic method is causing overruns. The log will show timestamps and which robot mode was active when the overrun occurred. Look for patterns - if overruns only happen during teleop, check ``teleopPeriodic()`` and subsystems used during teleop. If they occur consistently, check ``robotPeriodic()`` for code that runs regardless of mode. The log also shows the amount of time each subsystem's ``periodic()`` method ran, which can help pinpoint which code is causing the overruns. |
| - **USB device enumeration**: Plugging/unplugging USB devices during operation | ||
|
|
||
| ### Tips to Avoid Loop Overruns | ||
|
|
There was a problem hiding this comment.
Suggested change
| Use ``Trigger``s to check conditions without a loop. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds a comprehensive "Common Causes of Loop Overruns" section to the debugging documentation, explaining what loop overruns are, their symptoms, common causes, and how to avoid/diagnose them.
Changes
Fixes #2315