From f99e8b80370650fb2c5e48430480ecfdcc52bd72 Mon Sep 17 00:00:00 2001 From: jasondaming Date: Wed, 8 Oct 2025 16:39:04 -0500 Subject: [PATCH 1/2] Document common causes of loop overruns 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 #2315 --- .../debugging-robot-program.rst | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/source/docs/software/vscode-overview/debugging-robot-program.rst b/source/docs/software/vscode-overview/debugging-robot-program.rst index 0904a41327..b03990929d 100644 --- a/source/docs/software/vscode-overview/debugging-robot-program.rst +++ b/source/docs/software/vscode-overview/debugging-robot-program.rst @@ -46,6 +46,42 @@ Another way to debug your program is to use print statements in your code and vi :doc:`NetworkTables ` can be used to share robot information with your debugging computer. :term:`NetworkTables` can be viewed with your favorite Dashboard or :ref:`OutlineViewer `. One advantage of NetworkTables is that tools like :doc:`Shuffleboard ` can be used to graphically analyze the data. These same tools can then be used with same data to later provide an operator interface for your drivers. +## 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: + +### Blocking Operations + +- **Thread.sleep() or wait()**: Never use blocking sleep or wait calls in periodic methods +- **Synchronous I/O**: Reading files, network operations, or other blocking I/O operations +- **Busy-wait loops**: Loops that repeatedly check a condition without yielding (e.g., ``while(!sensor.isReady()) {}``) + +### Excessive Computation + +- **Complex calculations in periodic methods**: Move expensive calculations to separate threads or spread them across multiple loop iterations +- **Large data structure operations**: Sorting, searching, or iterating over large arrays or lists +- **Unoptimized algorithms**: O(n²) or worse algorithms running on large datasets + +### 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 +- **Excessive Shuffleboard updates**: Sending large amounts of data to the dashboard + +### 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 +- **USB device enumeration**: Plugging/unplugging USB devices during operation + +### Tips to Avoid Loop Overruns + +- Use :doc:`Notifier ` for operations that need precise timing independent of the main loop +- 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 + ## Learn More - To learn more about debugging with VS Code see this [link](https://code.visualstudio.com/docs/editor/debugging). From 3dc7788ecbfbfddb6d2a09e3414a493c26adddc2 Mon Sep 17 00:00:00 2001 From: jasondaming Date: Wed, 8 Oct 2025 21:39:25 -0500 Subject: [PATCH 2/2] Address review feedback: add warning example, clarify NT data retrieval, expand DS log interpretation --- .../software/vscode-overview/debugging-robot-program.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/docs/software/vscode-overview/debugging-robot-program.rst b/source/docs/software/vscode-overview/debugging-robot-program.rst index b03990929d..d8896b5ef2 100644 --- a/source/docs/software/vscode-overview/debugging-robot-program.rst +++ b/source/docs/software/vscode-overview/debugging-robot-program.rst @@ -48,7 +48,7 @@ Another way to debug your program is to use print statements in your code and vi ## 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: +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 like ``Loop time of 0.03s overrun`` and the robot code may behave unpredictably. Here are common causes: ### Blocking Operations @@ -65,7 +65,7 @@ Loop overruns occur when the robot's periodic methods (``robotPeriodic()``, ``te ### 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 +- **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 ### Hardware/Sensor Issues @@ -80,7 +80,7 @@ Loop overruns occur when the robot's periodic methods (``robotPeriodic()``, ``te - 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 +- **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. ## Learn More