From 159353c9e51d57a2ce55e45505a2d1c4a59f8f43 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Mar 2024 03:29:10 -0800 Subject: [PATCH 1/3] Add instructions for selecting debug probe from "Programmer" menu in IDE 2.x debugger tutorials A major reworking of the debugger configuration system was released in Arduino IDE 2.3.0. One of the user facing changes is the ability to configure the IDE for the debug probe hardware in use via the "Tools > Programmer" menu selection. As a side effect of that change, it is now mandatory for the user to make the appropriate selection from that menu in order to use the debugger. If no selection is made, the IDE disables the "Start Debugging" button. For this reason, it will be important for the debugger tutorials to include this. Arduino IDE versions prior to 2.3.0 did not use the "Programmer" selection for configuration of the debugger. Although selecting a programmer before starting the debugger is not mandatory for users of older versions of the IDE, it also will not cause any harm and that menu was present in those versions of the IDE as well. So the inclusion of a "Programmer" menu selection step in the tutorials does not break their compatibility with previous versions of Arduino IDE 2.x. --- .../tutorials/atmel-ice/using-an-atmel-ice-with-the-ide-v2.md | 2 ++ .../mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md | 2 ++ .../zero/tutorials/debugging-with-zero/debugging-with-zero.md | 4 +++- 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/atmel-ice/using-an-atmel-ice-with-the-ide-v2.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/atmel-ice/using-an-atmel-ice-with-the-ide-v2.md index a9d78e7347..09a4b1b43b 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/atmel-ice/using-an-atmel-ice-with-the-ide-v2.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/atmel-ice/using-an-atmel-ice-with-the-ide-v2.md @@ -115,6 +115,8 @@ Let's start by opening the Arduino IDE 2 and connecting our MKR WiFi 1010 board ![The board and port recognized by the Arduino IDE 2.](assets/ide_v2_t1_img05.png) +Select **Tools > Programmer > Atmel-ICE** from the Arduino IDE menus. + ### 2. Creating the Test Code Let's try the example code show below, it is a simple program that blinks the onboard LED of our board and changes the value of variables `x` and `y` while running. Open a new sketch, copy and paste the code show below: 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 2acac434ed..530b65d625 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,6 +67,8 @@ 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. +Select **Tools > Programmer > Segger J-Link** from the Arduino IDE menus. + 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 diff --git a/content/hardware/02.hero/boards/zero/tutorials/debugging-with-zero/debugging-with-zero.md b/content/hardware/02.hero/boards/zero/tutorials/debugging-with-zero/debugging-with-zero.md index bca402ecbd..4593c05609 100644 --- a/content/hardware/02.hero/boards/zero/tutorials/debugging-with-zero/debugging-with-zero.md +++ b/content/hardware/02.hero/boards/zero/tutorials/debugging-with-zero/debugging-with-zero.md @@ -22,7 +22,9 @@ For this this tutorial we will be using the Arduino Zero's built-in debugger int ***Important: You should connect the Arduino Zero through its programming USB port.*** -**2.** Select the board from the board/port list. When we select the Arduino Zero, the debugger icon close to the upload button will also become more visible. +**2.** Select the board from the board/port list. + +**3.** Select **Tools > Programmer > Atmel EDBG**. The debugger icon close to the upload button will now become more visible. ![Debugger icon available if board is supported.](assets/icon-available.png) From 6c9911404c1a466e8c74e2fd33a569403bae650c Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Mar 2024 03:53:41 -0800 Subject: [PATCH 2/3] Update IDE 2.x J-Link tutorial for new debug_custom.json data format A major reworking of the Arduino IDE 2.x debugger configuration system was released in Arduino IDE 2.3.0. This included a breaking change to the data structure of the debug_custom.json file that allows the user to adjust the debugger configuration. The tutorial for using the Arduino IDE 2.x debugger with a J-Link debug probe requires the use of the debug_custom.json feature. The change to the file's data structure rendered that part of the tutorial outdated. It is hereby updated to use the new data structure. Including instructions for the different debug_custom.json structure that would be required for users of versions of Arduino IDE 2.x older than 2.3.0 would have added significant complexity to an already dense tutorial, making it significantly less approachable to the reader and prone to misinterpretation. For this reason, the decision was made to specify a requirement of Arduino IDE 2.3.0 as the minimum for the tutorial. --- .../tutorials/mkr-jlink-setup/mkr-jlink.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 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 530b65d625..c3f7f7e345 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 @@ -9,7 +9,7 @@ description: This tutorial teaches you how to set up a MKR board with the Segger This tutorial will show you how to debug an Arduino sketch using an Arduino MKR board and the Segger J-Link probe. It will go through how to connect these and use the Arduino IDE 2 to then debug a sketch. ### Required Hardware and Software -- [Arduino IDE 2](https://www.arduino.cc/en/software) +- [Arduino IDE](https://www.arduino.cc/en/software) version 2.3.0 or higher - Segger J-link device ([EDU](https://store.arduino.cc/products/j-link-edu) or [BASE](https://store.arduino.cc/products/j-link-base-compact)) - [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) (other boards from the MKR family works as well). - Soldering equipment @@ -72,14 +72,19 @@ Select **Tools > Programmer > Segger J-Link** from the Arduino IDE menus. 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/JLinkGDBServerCL" -} +[ + { + "configId": "arduino:samd:mkrwifi1010:programmer=jlink", + "servertype": "jlink", + "device": "ATSAMD21G18", + "interface": "SWD", + "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL" + } +] ``` +If you are using a board other than the **MKR WiFi 1010**, you will need to adjust the `arduino:samd:mkrwifi1010` part of the `configId` field. Hover the mouse pointer over the board selection in the Arduino IDE toolbar in order to learn the correct identifier for the board you are using. + 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` From e9ebf1b149f4e6f4fb50e3d353f02502fdae3e17 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Mar 2024 03:55:40 -0800 Subject: [PATCH 3/3] Add alternative fields to J-Link debug_custom.json to workaround tutorial breaking IDE bug The tutorial for using the Arduino IDE 2.x debugger with a J-Link debug probe requires the use of a debug_custom.json file to adjust the debugger configuration in order to allow it to be used with the J-Link. A regression was introduced in Arduino IDE 2.3.0 that causes the configuration defined in certain fields of debug_custom.json to no longer have an effect, causing the tutorial to no longer be usable. A fix for the bug is now in progress, but it will likely be some time before this can be shipped in a new Arduino IDE release. For this reason, it will be worth adjusting the contents of the debug_custom.json file provided in the tutorial to work around the bug, allowing it to work with the current versions of Arduino IDE. Once a new release of Arduino IDE is made with the bug fixed, this commit should be reverted and the minimum IDE version specified in the tutorial bumped. However the workaround is applied in a manner that will not cause any harm even when present in the debug_custom.json file while a fixed version of Arduino IDE is in use. --- .../mkr-wifi-1010/tutorials/mkr-jlink-setup/mkr-jlink.md | 2 ++ 1 file changed, 2 insertions(+) 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 c3f7f7e345..0bc1b2820a 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 @@ -75,9 +75,11 @@ Now go to the folder where the sketch is located. Add a `.json` file in the same [ { "configId": "arduino:samd:mkrwifi1010:programmer=jlink", + "server": "jlink", "servertype": "jlink", "device": "ATSAMD21G18", "interface": "SWD", + "serverPath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL", "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL" } ]