From a3f3fef175763518955bc53eefb8db2abfe06904 Mon Sep 17 00:00:00 2001 From: Martin Crossley Date: Sat, 28 Feb 2026 22:05:58 +0000 Subject: [PATCH 1/4] Add Segger RTT instructions for microcontrollers/debug-probe --- .../debug-probe/uart-connection.adoc | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc index fb8c64361..406d6347b 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc @@ -57,3 +57,78 @@ For terminal programs that support it, a description of the USB serial UART is a image::images/description.jpg[width="60%"] The unique serial number in this description means that on Windows your COM port numbering is "sticky" per device, and will allow you to write `udev` rules to associate a named device node with a particular Debug Probe. + +== Send stdio over SWD using RTT + +You can, if desired, avoid using a serial link and send your application's output directly over the SWD interface by using a mechanism called Segger Real-Time Transport (RTT), that is supported by both the C/C++ SDK and the Debug Probe. + +NOTE: you will only be able to see the output over SWD from a *debug build* of your application. + +Sending stdio over RTT requires two steps: enabling the driver when building your application, and connecting to it with the Debug Probe. + +=== Enabling RTT in your build + +The C/C++ SDK provides a stdio driver for RTT just like the ones for UART and USB (see https://www.raspberrypi.com/documentation/pico-sdk/runtime.html#group_pico_stdio_rtt[pico_stdio_rtt] in the API documentation). + +To use the driver you must enable it by including the following line in your `CmakeLists.txt` file (or some other means of linking with `pico_stdio_rtt`): + +[source,console] +---- +pico_enable_stdio_rtt(test_stdio_rtt 1) +---- + +After that you can just call `stdio_init_all()` and `printf()` and so on as normal. So with the exception of that change you can just use the `hello_serial` example program as described above. + +=== Connecting to RTT from VSCode + +RTT is supported by `openocd` and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension, both of which should have been set up as part of https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc#install-tools[installing the tools]. If preferred you can also control `openocd` manually via `gdb` as described in the following section. + +With Cortex-Debug, open *launch.json* in your project's `.vscode` folder and add the following section to the *"Pico Debug (Cortex-Debug)"* configuration: + +[source,console] +---- +"rttConfig": { + "enabled": true, + "address": "auto", + "decoders": [ + { + "label": "", + "port": 0, + "type": "console" + } + ] +} +---- + +Now connect the debug probe, launch your application with *"Pico Debug (Cortex-Debug)"* and open the *TERMINAL* tab in the lower pane of the VSCode window. In the list of terminals at the right you should now see one called `RTT Ch:0 console`. Select this to see any output that your application sends to the `pico_stdio_rtt` driver. + +For a list of all the `cortex-debug` attributes that can be included in *launch.json* see the https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md[documentation]. + +=== Connecting to RTT in a standalone debug session + +If you are using a standalone debug session as described in https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[Starting a Debug Session] then you can connect to RTT as follows. + +Build and upload your RTT-enabled application, then connect the Debug Probe and start `openocd` and `gdb` separate terminals https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[as described before]. + +At the `gdb` prompt enter the following commands: + +[source,console] +---- +(gdb) target remote localhost:3333 +(gdb) monitor reset init +(gdb) monitor rtt setup 0x20000000 2048 "SEGGER RTT" +(gdb) monitor rtt start +(gdb) monitor rtt server start 60000 +(gdb) continue +---- + +Note that `gdb` commands prefixed with `monitor` are passed through to `openocd`, so for details of the commands used here see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual. + +You should see messages as `rtt` searches for a control block on the target and then listens for connections to a local TCP socket on port 60000. + +Finally open a third window and connect to the local socket with a tool like `nc` (netcat) or equivalent to see the output from the application: + +[source,console] +---- +$ nc localhost 60000 +---- \ No newline at end of file From 33a41d52de3ba53da85a7e5b92fb148617954fae Mon Sep 17 00:00:00 2001 From: Martin Crossley Date: Sun, 1 Mar 2026 19:33:03 +0000 Subject: [PATCH 2/4] fix missing channel in 'rtt server start' and improve wording --- .../debug-probe/uart-connection.adoc | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc index 406d6347b..595970a9c 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc @@ -58,32 +58,33 @@ image::images/description.jpg[width="60%"] The unique serial number in this description means that on Windows your COM port numbering is "sticky" per device, and will allow you to write `udev` rules to associate a named device node with a particular Debug Probe. -== Send stdio over SWD using RTT +== RTT connections -You can, if desired, avoid using a serial link and send your application's output directly over the SWD interface by using a mechanism called Segger Real-Time Transport (RTT), that is supported by both the C/C++ SDK and the Debug Probe. +You can also, if desired, configure your application to send its output directly over the SWD interface without the need for a UART connection. +This use a mechanism called Segger Real-Time Transport (RTT). -NOTE: you will only be able to see the output over SWD from a *debug build* of your application. +NOTE: you will only be able to send output over SWD from a *debug build* of your application. -Sending stdio over RTT requires two steps: enabling the driver when building your application, and connecting to it with the Debug Probe. +To do this requires two steps: enabling the RTT stdio driver in your application, and connecting to RTT with the Debug Probe. -=== Enabling RTT in your build +=== Enabling the RTT stdio driver The C/C++ SDK provides a stdio driver for RTT just like the ones for UART and USB (see https://www.raspberrypi.com/documentation/pico-sdk/runtime.html#group_pico_stdio_rtt[pico_stdio_rtt] in the API documentation). -To use the driver you must enable it by including the following line in your `CmakeLists.txt` file (or some other means of linking with `pico_stdio_rtt`): +To enable the driver in your build include the following line in your *CMakeLists.txt* file (or link with *pico_stdio_rtt* which does the same thing): [source,console] ---- pico_enable_stdio_rtt(test_stdio_rtt 1) ---- -After that you can just call `stdio_init_all()` and `printf()` and so on as normal. So with the exception of that change you can just use the `hello_serial` example program as described above. +Your application can then call `stdio_init_all()` and output to `printf()` will be sent to RTT. If you want output to go to the UART as well then you can enable that too. === Connecting to RTT from VSCode -RTT is supported by `openocd` and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension, both of which should have been set up as part of https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc#install-tools[installing the tools]. If preferred you can also control `openocd` manually via `gdb` as described in the following section. +RTT is supported by `openocd` and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension, both of which should have been set up as part of https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc#install-tools[installing the tools]. To enable it you have to add a section to your debug launch configuration. -With Cortex-Debug, open *launch.json* in your project's `.vscode` folder and add the following section to the *"Pico Debug (Cortex-Debug)"* configuration: +Add the following lines to the *launch.json* file in your project's *.vscode* folder, putting them in the configuration section for *"Pico Debug (Cortex-Debug)"*: [source,console] ---- @@ -100,13 +101,15 @@ With Cortex-Debug, open *launch.json* in your project's `.vscode` folder and add } ---- -Now connect the debug probe, launch your application with *"Pico Debug (Cortex-Debug)"* and open the *TERMINAL* tab in the lower pane of the VSCode window. In the list of terminals at the right you should now see one called `RTT Ch:0 console`. Select this to see any output that your application sends to the `pico_stdio_rtt` driver. +_see https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md[cortex-debug launch attributes]_ + + +If you now launch a debug session on an RTT-enabled application and open the *TERMINAL* tab you should now see a list on the right that includes `RTT Ch:0 console`.Select this to see the output that your application sends via the `pico_stdio_rtt` driver. -For a list of all the `cortex-debug` attributes that can be included in *launch.json* see the https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md[documentation]. === Connecting to RTT in a standalone debug session -If you are using a standalone debug session as described in https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[Starting a Debug Session] then you can connect to RTT as follows. +If you are using a standalone debug session as described in https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[Starting a Debug Session] you can connect to RTT as follows. Build and upload your RTT-enabled application, then connect the Debug Probe and start `openocd` and `gdb` separate terminals https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[as described before]. @@ -118,15 +121,15 @@ At the `gdb` prompt enter the following commands: (gdb) monitor reset init (gdb) monitor rtt setup 0x20000000 2048 "SEGGER RTT" (gdb) monitor rtt start -(gdb) monitor rtt server start 60000 +(gdb) monitor rtt server start 60000 0 (gdb) continue ---- -Note that `gdb` commands prefixed with `monitor` are passed through to `openocd`, so for details of the commands used here see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual. +Note that `gdb` commands prefixed with `monitor` are passed through to `openocd`. For details of the commands used here see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual. -You should see messages as `rtt` searches for a control block on the target and then listens for connections to a local TCP socket on port 60000. +You should see `openocd` searching for an RTT control block on the target and then creating a local TCP socket on port 60000. -Finally open a third window and connect to the local socket with a tool like `nc` (netcat) or equivalent to see the output from the application: +Finally open a third window and connect to the local socket with a tool like `nc` (netcat) or equivalent to see the RTT output from your application: [source,console] ---- From 00d676592e4d6bb3ef829a2e500f630255e9b310 Mon Sep 17 00:00:00 2001 From: Martin Crossley Date: Sun, 1 Mar 2026 19:47:48 +0000 Subject: [PATCH 3/4] correct typo and adjust formatting --- .../debug-probe/uart-connection.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc index 595970a9c..64614fcdc 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc @@ -61,7 +61,7 @@ The unique serial number in this description means that on Windows your COM port == RTT connections You can also, if desired, configure your application to send its output directly over the SWD interface without the need for a UART connection. -This use a mechanism called Segger Real-Time Transport (RTT). +This uses a mechanism called Segger Real-Time Transport (RTT). NOTE: you will only be able to send output over SWD from a *debug build* of your application. @@ -75,16 +75,16 @@ To enable the driver in your build include the following line in your *CMakeList [source,console] ---- -pico_enable_stdio_rtt(test_stdio_rtt 1) +pico_enable_stdio_rtt( 1) ---- -Your application can then call `stdio_init_all()` and output to `printf()` will be sent to RTT. If you want output to go to the UART as well then you can enable that too. +After calling `stdio_init_all()` any output that your application sends with `printf()` will be sent to RTT. Note that if you want to copy your output to the UART as well then you can enable that too. === Connecting to RTT from VSCode -RTT is supported by `openocd` and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension, both of which should have been set up as part of https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc#install-tools[installing the tools]. To enable it you have to add a section to your debug launch configuration. +RTT is supported by `openocd` and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension, both of which should have been set up as part of https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc#install-tools[installing the tools]. -Add the following lines to the *launch.json* file in your project's *.vscode* folder, putting them in the configuration section for *"Pico Debug (Cortex-Debug)"*: +To enable RTT for a debug session add a section to its launch configuration. Open your project's *.vscode* folder and add the following lines to the *launch.json* file, putting them in the desired configuration section such as *"Pico Debug (Cortex-Debug)"*: [source,console] ---- @@ -125,7 +125,7 @@ At the `gdb` prompt enter the following commands: (gdb) continue ---- -Note that `gdb` commands prefixed with `monitor` are passed through to `openocd`. For details of the commands used here see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual. +_Note that `gdb` commands prefixed with `monitor` are passed through to `openocd`: for details of the commands used here see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual_ You should see `openocd` searching for an RTT control block on the target and then creating a local TCP socket on port 60000. From 5cc74456ebe4560a8384bd7ea2c21fa3210d326f Mon Sep 17 00:00:00 2001 From: Martin Crossley Date: Sun, 1 Mar 2026 19:51:55 +0000 Subject: [PATCH 4/4] more typos --- .../microcontrollers/debug-probe/uart-connection.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc index 64614fcdc..bd02da715 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc @@ -104,14 +104,14 @@ To enable RTT for a debug session add a section to its launch configuration. Ope _see https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md[cortex-debug launch attributes]_ -If you now launch a debug session on an RTT-enabled application and open the *TERMINAL* tab you should now see a list on the right that includes `RTT Ch:0 console`.Select this to see the output that your application sends via the `pico_stdio_rtt` driver. +If you now launch a debug session on an RTT-enabled application and open the *TERMINAL* tab you should see a list on the right that includes `RTT Ch:0 console`. Select this to see the output that your application sends to the `pico_stdio_rtt` driver. === Connecting to RTT in a standalone debug session If you are using a standalone debug session as described in https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[Starting a Debug Session] you can connect to RTT as follows. -Build and upload your RTT-enabled application, then connect the Debug Probe and start `openocd` and `gdb` separate terminals https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[as described before]. +Build and upload your RTT-enabled application, then connect the Debug Probe and start `openocd` and `gdb` in separate terminals https://github.com/raspberrypi/documentation/blob/master/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc#standalone-debug-session[as described before]. At the `gdb` prompt enter the following commands: