From 1065764ce06616352811371d538a74ffd888952b Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 01:25:40 -0800 Subject: [PATCH 1/6] Update "J-Link GDB Server" path in IDE 2.x debugger tutorial Older versions of the "SEGGER J-Link GDB Server" were only available in a 32-bit package for Windows. For this reason, the path to the server in the tutorial's example debug_custom.json used the `C:\Program Files (x86)` path where the 32-bit package is installed by default on a 64-bit Windows machine. A 64-bit Windows package has been available starting with the 7.50 release (made on 2021-07-01). This package is installed under `C:\Program Files` by default (as is the 32-bit package on 32-bit Windows machines). Most users will have the file at this path. The tutorial will be most friendly to the reader if it uses the most common path in the example so it is hereby updated to that path. --- .../mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md index 30eb69afd3..6d088d93f4 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md @@ -74,7 +74,7 @@ Now go to the folder where the sketch is located. Add a `.json` file in the same "servertype": "jlink", "device": "ATSAMD21G18", "interface": "SWD", - "serverpath": "C:/Program Files (x86)/SEGGER/JLink/JLinkGDBServer" + "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServer" } ``` From ded60253473fe87e439a3073f24a73a764269405 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 05:06:43 -0800 Subject: [PATCH 2/6] Clean up formatting of example `debug_custom.json` file in IDE 2.x debugger tutorial --- .../tutorials/mkr-jlink-setup/mkr-jlink.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md index 6d088d93f4..d9fa217d03 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md @@ -67,14 +67,14 @@ Now we are ready to start debugging our sketch. Connect the power to the MKR boa Then create or open the sketch that you want to debug. If you don't already have a sketch in mind, feel free to use the example sketch found at the end of this tutorial. -Now go to the folder where the sketch is located. Add a `.json` file in the same folder as your sketch and name it `debug_custom.json`. The easiest way would be to create a text file and rename it `debug_custom.json`. In the `.json` file, add the following lines: +Now go to the folder where the sketch is located. Add a `.json` file in the same folder as your sketch and name it `debug_custom.json`. The easiest way would be to create a text file and rename it `debug_custom.json`. In the `.json` file, add the following lines: ```arduino { - "servertype": "jlink", - "device": "ATSAMD21G18", - "interface": "SWD", - "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServer" + "servertype": "jlink", + "device": "ATSAMD21G18", + "interface": "SWD", + "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServer" } ``` From 154c7132a3731c305875e9af62476cdc5e8b8d8e Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 09:09:28 -0800 Subject: [PATCH 3/6] Use command line version of "J-Link GDB Server" in example configuration file of IDE 2.x debugger tutorial Installation of the "SEGGER J-Link GDB Server" software is required in order to use a J-Link debug proble with the Arduino IDE integrated sketch debugger. This installation includes two variants of the "J-Link GDB Server" tool, each executable with a different filename: - GUI: `JLinkGDBServer.exe` (Windows) / `JLinkGDBServerExe` (Linux/macOS) - Command Line: `JLinkGDBServerCL.exe` (Windows) / `JLinkGDBServer` (Linux/macOS) The user must specify the path to the tool executable in the debug_custom.json configuration file. The Arduino IDE 2.x debugger tutorial includes a sample debug_custom.json file. Previously this example used the filename of the GUI variant. Although technically inappropriate for this application, this variant worked fine with the previous version of the debugger extension (0.3.10) used by Arduino IDE 2.0.2 and older, and also offered the advantage of having the same filename as Linux and macOS users will need (confusingly, `JLinkGDBServer` is the filename of the GUI variant on Windows, and of the command line variant on the other operating systems). I found that the newer version of the debugger extension (1.5.1) used by Arduino IDE 2.0.3 fails on startup when the GUI variant is used, while the command line variant works fine. For this reason, the filename used in the example debug_custom.json file must now be updated to use the command line variant. This should not impact anyone who is following the tutorial while using an Arduino IDE version 2.0.2 or older because the command line variant works fine with those versions as well. --- .../mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md index d9fa217d03..fc440f7462 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md @@ -74,7 +74,7 @@ Now go to the folder where the sketch is located. Add a `.json` file in the same "servertype": "jlink", "device": "ATSAMD21G18", "interface": "SWD", - "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServer" + "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL" } ``` From 90d1203d42ec157b8e3dd6b7e0e3e1503f2b3aca Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 09:56:52 -0800 Subject: [PATCH 4/6] Provide filename of "J-Link GDB Server" for each OS in IDE 2.x debugger J-Link tutorial Installation of the "SEGGER J-Link GDB Server" software is required in order to use a J-Link debug probe with the Arduino IDE integrated sketch debugger. The user must specify the path to the command line version of the "J-Link GDB Server" tool executable in their debug_custom.json configuration files. The Arduino IDE 2.x debugger tutorial includes a sample debug_custom.json file. This example shows the filename of the tool on Windows, which would likely be sufficient documentation for the readers using that operating system. However, this will not be terribly helpful for the readers using other operating systems, for the following reasons: This installation includes two variants of the "J-Link GDB Server" tool, each executable with a different filename: - GUI: `JLinkGDBServer.exe` (Windows) / `JLinkGDBServerExe` (Linux/macOS) - Command Line: `JLinkGDBServerCL.exe` (Windows) / `JLinkGDBServer` (Linux/macOS) Confusingly, `JLinkGDBServer` is the filename of the GUI variant on Windows, and of the command line variant on the other operating systems Although technically inappropriate for this application, either variant worked fine with the previous version of the debugger extension (0.3.10) used by Arduino IDE 2.0.2 and older. However, I found that the newer version of the debugger extension (1.5.1) used by Arduino IDE 2.0.3 fails on startup when the GUI variant is used (tested on Windows), while the command line variant works fine. For this reason, it is now especially important to clearly document the filename to be used in the configuration file for each operating system. --- .../mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md index fc440f7462..92b8257f05 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md @@ -78,7 +78,12 @@ Now go to the folder where the sketch is located. Add a `.json` file in the same } ``` -The `"serverpath"` needs to be changed to the location where you installed the J-link package in the previous step. When this is done, click on the debugging icon. +The `"serverpath"` field needs to be set to the path of the "J-Link GDB Server CL" tool executable file that is located under the folder of the J-Link package you installed in the previous step. The file is named: + +- **If you are using Windows:** `JLinkGDBServerCL.exe` +- **If you are using Linux or macOS:** `JLinkGDBServer` + +When you have finished creating the `debug_custom.json` file, click on the debugging icon. ![Start debug feature in Arduino IDE 2.0](assets/mkr_jlink_IDE_debugging_button.png) From c99daedfeb51acaf0fe4aec22af8de59918b7208 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 10:17:23 -0800 Subject: [PATCH 5/6] Correct line numbers referenced in breakpoint section of IDE 2.x debugger tutorial The screenshots included with the tutorial show breakpoints were placed at lines 33 and 35, yet the text is written as though the second breakpoint is at line 36. Since it is easier to update the text, and since line 35 is a more logical place for the breakpoint, the text is corrected. --- .../ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md b/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md index 1e28f5edcd..43b7ea3c03 100644 --- a/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md +++ b/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md @@ -102,14 +102,14 @@ Once your program has been uploaded, we can start using the debugger. Let's begin by creating something called a **breakpoint**. Breakpoints are used to stop the program execution at a specific line (or when a specific condition is verified). We can use multiple of these in a program (the number is variable depending on the processor). -In this example, we are going to set a breakpoint for **line 33** and **line 36**. These are set by clicking to the left of the line numbering in the editor. +In this example, we are going to set a breakpoint for **line 33** and **line 35**. These are set by clicking to the left of the line numbering in the editor. ![Navigating the Debugger.](assets/debugger-img03.png) We can now go through our code, step by step. The first (automatic) stop will be triggered by the **Debugger** itself, and it will be a standard entry-point, ignore that for now. -Let's continue, by clicking on the **Play/pause** button (**Continue**). The program will now run to the first breakpoint, line 33. If we click it again, it will jump to line 36 (the lines 34 and 35 will still be executed but we won't see that). Clicking the **Play/pause** button again will continue running the program which will pause at its next breakpoint, line 33. We're in the main loop, after all. +Let's continue, by clicking on the **Play/pause** button (**Continue**). The program will now run to the first breakpoint, line 33. If we click it again, it will jump to line 35 (line 34 will still be executed but we won't see that). Clicking the **Play/pause** button again will continue running the program which will pause at its next breakpoint, line 33. We're in the main loop, after all. ![Going between breakpoints.](assets/playpause.gif) From c9ede0e06ba2f298434c2376cb4b32f3f80a81e2 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 5 Dec 2022 10:21:36 -0800 Subject: [PATCH 6/6] Update breakpoints section of IDE 2.x debugger tutorial to reflect new behavior The version of the "Cortex-Debug" VS Code extension that provides the integrated sketch debugger for Arduino IDE 2.x was updated for the Arduino IDE 2.0.3 release. This update resulted in some changes in the behavior of the debugger. One of these changes is in how the debugger behaves when it is started: When started, the version of the debugger (0.3.10) used by Arduino IDE 2.0.2 and older would pause at some point at the start of the program (e.g., the `Reset_Handler` function in the cortex_handlers.c file of the "Arduino SAMD Boards (32-bits ARM Cortex-M0+)" platform). When started, the version of the debugger (1.5.1) used by Arduino IDE 2.0.3 and newer simply runs the sketch program, only automatically pausing if it reaches a breakpoint set by the user. The Arduino IDE 2.x debugger tutorial was written based on the previous behavior, and that information is not applicable to Arduino IDE 2.0.3 and newer. So the outdated information is hereby updated to be correct for the current IDE versions. This task was a bit challenging due to the tutorial being vague and inconsistent about the clicking of the "Start Debugging" button. It is not clear exactly when (or if!!!) the user will click this button: If they click it before adding the breakpoints, execution will pause at whichever breakpoint the execution reaches first. That will most likely be line 33, since there is only a 1 s time window when line 35 would be the next breakpoint, but it is not guaranteed. If they click it after adding the breakpoints, execution will pause at the first breakpoint at line 33. --- .../ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md b/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md index 43b7ea3c03..cf1f4500ff 100644 --- a/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md +++ b/content/software/ide-v2/tutorials/ide-v2-debugger/ide-v2-debugger.md @@ -107,9 +107,9 @@ In this example, we are going to set a breakpoint for **line 33** and **line 35* ![Navigating the Debugger.](assets/debugger-img03.png) We can now go through our code, step by step. -The first (automatic) stop will be triggered by the **Debugger** itself, and it will be a standard entry-point, ignore that for now. +The debugger will automatically stop at the first breakpoint it reached. -Let's continue, by clicking on the **Play/pause** button (**Continue**). The program will now run to the first breakpoint, line 33. If we click it again, it will jump to line 35 (line 34 will still be executed but we won't see that). Clicking the **Play/pause** button again will continue running the program which will pause at its next breakpoint, line 33. We're in the main loop, after all. +Let's continue, by clicking on the **Play/pause** button (**Continue**). The program will now run to the next breakpoint (e.g., line 35). If we click it again, it will jump to line 33 (the other lines in the program sequence will still be executed but we won't see that). Clicking the **Play/pause** button again will continue running the program which will pause at its next breakpoint, line 35. We're in the main loop, after all. ![Going between breakpoints.](assets/playpause.gif)