Difference between revisions of "J-Link RTT Viewer"

From SEGGER Wiki
Jump to: navigation, search
(Added "Using Timestamps" paragraph)
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[File:RTTViewer_MainWIndow.PNG | thumb | 400px | right | J-Link RTT Viewer main window]]
+
[[File:RTTViewer_MainWIndow.PNG | thumb | 400px | right | J-Link RTT Viewer]]
J-Link RTT Viewer is a GUI application available for Windows, MacOS and Linux.
+
J-Link RTT Viewer is a GUI application available for Windows, MacOS and Linux and can be downloaded as part of the [[J-Link Software and Documentation Pack]].
 
It enables you to use all features of RTT in one application.
 
It enables you to use all features of RTT in one application.
 
It supports:
 
It supports:
Line 9: Line 9:
 
* Logging terminal data into a file.
 
* Logging terminal data into a file.
 
* Logging data on Channel 1.
 
* Logging data on Channel 1.
 
This article is still under construction.
 
For more information about J-Link RTT Viewer please refer to the [https://www.segger.com/downloads/jlink/UM08001 J-Link user manual (UM08001)]
 
   
 
<div class="toclimit-2">
 
<div class="toclimit-2">
Line 17: Line 14:
 
</div>
 
</div>
   
= J-Link RTT Viewer Startup =
+
== J-Link RTT Viewer Startup ==
 
Make sure J-Link and target device are connected and powered up.<br>
 
Make sure J-Link and target device are connected and powered up.<br>
 
Start J-Link RTT Viewer by opening the executable (JLinkRTTViewer.exe/JLinkRTTViewerExe) from the installation folder of the J-Link Software or the start menu.
 
Start J-Link RTT Viewer by opening the executable (JLinkRTTViewer.exe/JLinkRTTViewerExe) from the installation folder of the J-Link Software or the start menu.
Line 24: Line 21:
 
The connection settings and all in app configuration will be saved for the next start of J-Link RTT Viewer.
 
The connection settings and all in app configuration will be saved for the next start of J-Link RTT Viewer.
   
= J-Link RTT Viewer Configuration dialog =
+
== J-Link RTT Viewer Configuration dialog ==
 
The J-Link RTT Viewer Configuration dialog is used to set all necessary device specifics to successfully connect and read/send RTT data from/to the target device.
 
The J-Link RTT Viewer Configuration dialog is used to set all necessary device specifics to successfully connect and read/send RTT data from/to the target device.
 
[[File:RTTViewer_ConfigDialog.PNG | frame | right | J-Link RTT Viewer Config dialog]]
 
[[File:RTTViewer_ConfigDialog.PNG | frame | right | J-Link RTT Viewer Config dialog]]
   
== Connection Settings ==
+
=== Connection Settings ===
 
J-Link RTT Viewer can be used in two modes:
 
J-Link RTT Viewer can be used in two modes:
 
* [[#Stand-alone | Stand-alone]], opening an own connection to J-Link and target.
 
* [[#Stand-alone | Stand-alone]], opening an own connection to J-Link and target.
 
* In [[#Attach mode | attach mode]], connecting to an existing J-Link connection of a debugger.
 
* In [[#Attach mode | attach mode]], connecting to an existing J-Link connection of a debugger.
   
=== Stand-alone ===
+
==== Stand-alone ====
 
In stand-alone mode J-Link RTT Viewer needs to know some settings of J-Link and target device:
 
In stand-alone mode J-Link RTT Viewer needs to know some settings of J-Link and target device:
 
# Select USB or TCP/IP as the connection to J-Link.
 
# Select USB or TCP/IP as the connection to J-Link.
Line 43: Line 40:
 
## Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.<br>In such a case, the address, or RAM range has to be specified by the user.
 
## Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.<br>In such a case, the address, or RAM range has to be specified by the user.
   
=== Attach mode ===
+
==== Attach mode ====
In attach mode J-Link RTT Viewer does not need any settings.
+
By selecting ''Connection to J-Link:'' > ''Existing Session'' RTT Viewer is started in attach mode.
  +
In attach mode J-Link RTT Viewer does usually not require any additional settings, however RTT Control Block Address or Search Ranges can still be selected if required.
Select Existing Session.
 
  +
 
For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply [[J-Link Commander]].
 
For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply [[J-Link Commander]].
   
  +
The attach mode is especially useful when using a third party debugger or IDE working with a J-Link (e.g. Eclipse).
= The Terminal Tabs =
 
  +
  +
== The Terminal Tabs ==
 
J-Link RTT Viewer allows displaying the output of Channel 0 in different "virtual" Terminals.
 
J-Link RTT Viewer allows displaying the output of Channel 0 in different "virtual" Terminals.
 
The target application can switch between terminals with SEGGER_RTT_SetTerminal() and SEGGER_RTT_TerminalOut(). <!--- TBD: Add links here when available --->
 
The target application can switch between terminals with SEGGER_RTT_SetTerminal() and SEGGER_RTT_TerminalOut(). <!--- TBD: Add links here when available --->
Line 55: Line 55:
 
<br clear=all>
 
<br clear=all>
   
== All Terminals ==
+
=== All Terminals ===
 
The All Terminals tab displays the complete output of RTT Channel 0 and can display the user input (Check Input -> Echo input... -> Echo to "All Terminals").\n
 
The All Terminals tab displays the complete output of RTT Channel 0 and can display the user input (Check Input -> Echo input... -> Echo to "All Terminals").\n
 
Each output line is prefixed by the Terminal it has been sent to.
 
Each output line is prefixed by the Terminal it has been sent to.
 
Additionally, output on Terminal 1 is shown in red, output on Terminals 2 - 15 in gray.
 
Additionally, output on Terminal 1 is shown in red, output on Terminals 2 - 15 in gray.
   
== Terminal 0 - 15 ==
+
=== Terminal 0 - 15 ===
 
Each tab Terminal 0 - Terminal 15 displays the output which has been sent to this Terminal.
 
Each tab Terminal 0 - Terminal 15 displays the output which has been sent to this Terminal.
 
The Terminal tabs interpret and display Text Control Codes as sent by the application to show colored text or erase the screen.<br>
 
The Terminal tabs interpret and display Text Control Codes as sent by the application to show colored text or erase the screen.<br>
Line 67: Line 67:
 
Each Terminal tab can be shown or hidden via the menu Terminals -> Terminals... or their respective shortcuts as described below.
 
Each Terminal tab can be shown or hidden via the menu Terminals -> Terminals... or their respective shortcuts as described below.
   
= Sending Input =
+
== Sending Input ==
[[File: RTTViewer_SendingInput.png | thumb | right | Sending input dialog]]
+
[[File: RTTViewer_SendingInput.png | thumb | right | J-Link RTT Viewer "Sending input" dialog]]
 
J-Link RTT Viewer supports sending user input to RTT Down Channel 0 which can be read by the target application with SEGGER_RTT_GetKey() and SEGGER_RTT_Read().<br>
 
J-Link RTT Viewer supports sending user input to RTT Down Channel 0 which can be read by the target application with SEGGER_RTT_GetKey() and SEGGER_RTT_Read().<br>
 
Input can be entered in the text box below the Terminal Tabs.<br>
 
Input can be entered in the text box below the Terminal Tabs.<br>
Line 76: Line 76:
 
<br clear=all>
 
<br clear=all>
   
= Logging output =
+
== Logging output ==
 
The output of Channel 0 and Channel 1 can be logged into a text file.
 
The output of Channel 0 and Channel 1 can be logged into a text file.
   
== Terminal output (Channel 0) ==
+
=== Terminal output (Channel 0) ===
 
The format is the same as used in the All Terminals tab.<br>
 
The format is the same as used in the All Terminals tab.<br>
 
Terminal Logging can be started via Logging -> Start Terminal Logging...
 
Terminal Logging can be started via Logging -> Start Terminal Logging...
   
== Data output (Channel 1) ==
+
=== Data output (Channel 1) ===
 
Channel 1 logging can for example be used to sent instrumented event tracing data.
 
Channel 1 logging can for example be used to sent instrumented event tracing data.
 
The data log file contains header and footer and the binary data as received from the application.<br>
 
The data log file contains header and footer and the binary data as received from the application.<br>
Line 90: Line 90:
 
'''NOTE:''' Data Logging is only available in stand-alone mode.
 
'''NOTE:''' Data Logging is only available in stand-alone mode.
   
= Command line options =
+
== Command line options ==
 
J-Link RTT Viewer can be configured via command line parameters.
 
J-Link RTT Viewer can be configured via command line parameters.
 
In the following, the command line options which are available for J-Link RTT Viewer are explained.
 
In the following, the command line options which are available for J-Link RTT Viewer are explained.
Line 98: Line 98:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Command line option !! Description
+
! Command line option !! Description
 
|-
 
|-
| [[#--bright | -b, --bright]] || Bright theme for GUI
+
| [[#--bright | -b, --bright]] || Bright theme for GUI
 
|-
 
|-
| [[#--device | -d, --device]] || Select the connected target device
+
| [[#--device | -d, --device]] || Select the connected target device
 
|-
 
|-
| [[#--connection | -ct, --connection]] || Sets the connection type
+
| [[#--connection | -ct, --connection]] || Sets the connection type
 
|-
 
|-
| [[#--interface | -if, --interface]] || Sets the interface type
+
| [[#--interface | -if, --interface]] || Sets the interface type
 
|-
 
|-
| [[#--host | -ip, --host]] || The IP address of the J-Link
+
| [[#--host | -ip, --host]] || The IP address of the J-Link
 
|-
 
|-
| [[#--speed | -s, --speed]] || Interface speed in kHz
+
| [[#--speed | -s, --speed]] || Interface speed in kHz
 
|-
 
|-
| [[#--scriptfile | -sf, --scriptfile]] || Executes a command script on start up
+
| [[#--scriptfile | -sf, --scriptfile]] || Executes a command script on start up
 
|-
 
|-
| [[#--serialnumber | -sn, --serialnumber]] || Select the J-Link with a specific S/N
+
| [[#--serialnumber | -sn, --serialnumber]] || Select the J-Link with a specific S/N
 
|-
 
|-
| [[#--rttaddr | -ra, --rttaddr]] || Sets the address of the RTT control block
+
| [[#--rttaddr | -ra, --rttaddr]] || Sets the address of the RTT control block
 
|-
 
|-
| [[#--rttrange | -rr, --rttrange]] || Specify RTT search range
+
| [[#--rttrange | -rr, --rttrange]] || Specify RTT search range
 
|-
 
|-
| [[#--autoconnect | -a, --autoconnect]] || Automatically connect to target, suppress settings dialog
+
| [[#--autoconnect | -a, --autoconnect]] || Automatically connect to target, suppress settings dialog
  +
|-
  +
| [[#--terminalindex | -ti, --terminalindex]] || Opens the specified terminal application start
 
|-
 
|-
 
|}
 
|}
   
== --bright ==
+
=== --bright ===
 
Starts the RTT Viewer in bright theme.
 
Starts the RTT Viewer in bright theme.
   
Line 133: Line 135:
 
JLinkRTTViewer.exe --bright
 
JLinkRTTViewer.exe --bright
   
== --device ==
+
=== --device ===
 
Selects the device J-Link RTT Viewer shall connect to.
 
Selects the device J-Link RTT Viewer shall connect to.
   
Line 142: Line 144:
 
JLinkRTTViewer.exe --device STM32F103ZE
 
JLinkRTTViewer.exe --device STM32F103ZE
   
== --connection ==
+
=== --connection ===
 
Sets the connection type.
 
Sets the connection type.
 
The connection to the J-Link can either be made directly over USB, IP or using an existing running session (e.g. the IDE's debug session).
 
The connection to the J-Link can either be made directly over USB, IP or using an existing running session (e.g. the IDE's debug session).
Line 153: Line 155:
 
JLinkRTTViewer.exe --connection ip
 
JLinkRTTViewer.exe --connection ip
   
== --interface ==
+
=== --interface ===
 
Sets the interface J-Link shall use to connect to the target.
 
Sets the interface J-Link shall use to connect to the target.
 
As interface types FINE, JTAG and SWD are supported.
 
As interface types FINE, JTAG and SWD are supported.
Line 163: Line 165:
 
JLinkRTTViewer.exe --interface swd
 
JLinkRTTViewer.exe --interface swd
   
== --host ==
+
=== --host ===
 
Enter the IP address or hostname of the J-Link.
 
Enter the IP address or hostname of the J-Link.
 
This option only applies, if connection type IP is used.
 
This option only applies, if connection type IP is used.
Line 174: Line 176:
 
JLinkRTTViewer.exe --host 192.168.1.17
 
JLinkRTTViewer.exe --host 192.168.1.17
   
== --speed ==
+
=== --speed ===
 
Sets the interface speed in kHz for target communication.
 
Sets the interface speed in kHz for target communication.
   
Line 183: Line 185:
 
JLinkRTTViewer.exe --speed 4000
 
JLinkRTTViewer.exe --speed 4000
   
== --scriptfile ==
+
=== --scriptfile ===
 
Executes a JLink command script on startup, setting options in advance (e.g. Device = AT91SAM7S256)
 
Executes a JLink command script on startup, setting options in advance (e.g. Device = AT91SAM7S256)
   
Line 192: Line 194:
 
JLinkRTTViewer.exe --scriptfile C:\\tmp\\<Scriptfilename>
 
JLinkRTTViewer.exe --scriptfile C:\\tmp\\<Scriptfilename>
   
== --serialnumber ==
+
=== --serialnumber ===
 
Connect to a J-Link with a specific serial number via USB.
 
Connect to a J-Link with a specific serial number via USB.
 
Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link RTT Viewer shall run and each connects to another J-Link.
 
Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link RTT Viewer shall run and each connects to another J-Link.
Line 202: Line 204:
 
JLinkRTTViewer.exe --serialnumber 580011111
 
JLinkRTTViewer.exe --serialnumber 580011111
   
== --rttaddr ==
+
=== --rttaddr ===
 
Sets a fixed address as location of the RTT control block.
 
Sets a fixed address as location of the RTT control block.
 
Automatic searching for the RTT control block is disabled.
 
Automatic searching for the RTT control block is disabled.
Line 210: Line 212:
   
 
'''Example'''
 
'''Example'''
JLinkRTTViewer.exe -rttaddr 0x20000000
+
JLinkRTTViewer.exe --rttaddr 0x20000000
   
== --rttrange ==
+
=== --rttrange ===
 
Sets one or more memory ranges, where the J-Link DLL shall search for the RTT control block.
 
Sets one or more memory ranges, where the J-Link DLL shall search for the RTT control block.
   
Line 219: Line 221:
   
 
'''Example'''
 
'''Example'''
JLinkRTTViewer.exe -rttrange "20000000 400"
+
JLinkRTTViewer.exe --rttrange "20000000 400"
   
== --autoconnect ==
+
=== --autoconnect ===
 
Let J-Link RTT Viewer connect automatically to the target without showing the Connection Settings (see [[#Connection Settings | Connection Settings]]).
 
Let J-Link RTT Viewer connect automatically to the target without showing the Connection Settings (see [[#Connection Settings | Connection Settings]]).
   
Line 230: Line 232:
 
JLinkRTTViewer.exe --autoconnect
 
JLinkRTTViewer.exe --autoconnect
   
  +
=== --terminalindex ===
= Menus and Shortcuts =
 
  +
Opens the terminal with the specified index on application start<br>
  +
The value of index can be [0:16], with 0 == ''All Terminals'', 1 == ''Terminal 0'' ... 16 == ''Terminal 15''
  +
  +
'''Syntax'''
  +
--terminalindex <Index>
  +
  +
'''Example'''
  +
JLinkRTTViewer.exe --terminalindex 7
  +
  +
== Menus and Shortcuts ==
 
The J-Link RTT Viewer has a range of options available in the menu bar.
 
The J-Link RTT Viewer has a range of options available in the menu bar.
   
== File menu elements ==
+
=== File menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 246: Line 258:
 
|}
 
|}
   
== Terminals menu elements ==
+
=== Terminals menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 267: Line 279:
 
|}
 
|}
   
== Input menu elements ==
+
=== Input menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 294: Line 306:
 
|}
 
|}
   
== Logging menu elements ==
+
=== Logging menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 311: Line 323:
 
|}
 
|}
   
== Help menu elements ==
+
=== Help menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 324: Line 336:
 
|}
 
|}
   
== Tab context menu elements ==
+
=== Tab context menu elements ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 335: Line 347:
 
|}
 
|}
   
= Using "virtual" Terminals in RTT =
+
== Using "virtual" Terminals in RTT ==
 
For virtual Terminals the target application needs only Up Channel 0.
 
For virtual Terminals the target application needs only Up Channel 0.
 
This is especially important on targets with low RAM.<br>
 
This is especially important on targets with low RAM.<br>
Line 344: Line 356:
 
* The sequences sent to change the Terminal are interpreted by J-Link RTT Viewer. Other applications like a Telnet Client will ignore them.
 
* The sequences sent to change the Terminal are interpreted by J-Link RTT Viewer. Other applications like a Telnet Client will ignore them.
   
= Using Text Control Codes =
+
== Using Text Control Codes ==
 
RTT allows using Text Control Codes (ANSI escape codes) to configure the display of text.
 
RTT allows using Text Control Codes (ANSI escape codes) to configure the display of text.
 
J-Link RTT Viewer supports changing the text color and background color and can erase the Terminal.
 
J-Link RTT Viewer supports changing the text color and background color and can erase the Terminal.
 
These Control Codes are pre-defined in the RTT application and can easily be used in the application.
 
These Control Codes are pre-defined in the RTT application and can easily be used in the application.
   
== Examples ==
+
=== Examples ===
 
Please refer to the following examples for the correct implementation of the ANSI escape codes in combination with RTT.
 
Please refer to the following examples for the correct implementation of the ANSI escape codes in combination with RTT.
   
=== Example 1 ===
+
==== Example 1 ====
 
SEGGER_RTT_WriteString(0,
 
SEGGER_RTT_WriteString(0,
 
RTT_CTRL_RESET"Red: " \
 
RTT_CTRL_RESET"Red: " \
Line 361: Line 373:
 
);
 
);
   
=== Example 2 ===
+
==== Example 2 ====
 
SEGGER_RTT_printf(0, "%sTime:%s%s %.7d\n",
 
SEGGER_RTT_printf(0, "%sTime:%s%s %.7d\n",
 
RTT_CTRL_RESET,
 
RTT_CTRL_RESET,
Line 381: Line 393:
 
);
 
);
   
  +
== Using Timestamps ==
= Troubleshooting =
 
  +
The J-Link RTT Viewer does '''not''' provide functionality to show host PC sided timestamps, because of the following reasons:
Under some circumstances, the RTT Control Block cannot be detected automatically.<br>
 
  +
* Timestamps created on host PC side (HS) do not represent the actual time the data was written to the RTT buffer on device side (DS), but the time when the data was received by the J-Link RTT Viewer.
This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.<br>
 
In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section ''RTT Control Block''.
+
* The delay between writing data to the RTT buffer (DS) and receiving it via the RTT Viewer (HS) is not constant but varying.
  +
* In case data is written very fast to the RTT buffer (DS), multiple messages that were originally intended as single messages would be presented with one single timestamp, when received with a single data read (HS).
  +
* In case data is already present in the RTT buffer (DS) before the RTT Viewer connects to it, all this data would have one timestamp (HS), even when they were not written to the buffer at the same time originally.
  +
'''Connclusion:''' The correct way to implement timestamps for RTT is '''on target side''', as PC sided timestamps do not represent the real, on target behavior.
  +
  +
=== Example ===
  +
To create timestamps for all log messages reliably, a wrapper function can be used:
  +
<source lang="c">/*********************************************************************
  +
*
  +
* _WriteStringWTS()
  +
*
  +
* Function description
  +
* Example wrapper function for SEGGER_RTT_WriteString(), adding a Timestamp.
  +
*/
  +
static unsigned _WriteStringWTS(unsigned BufferIndex, const char* s) {
  +
const char* sTimestamp;
  +
  +
sTimestamp = _GetTimestamp(); // Creates a timestamp string of desired format (e.g. "MM:ss.SSSS - ", since program start)
  +
SEGGER_RTT_WriteString(BufferIndex, sTimestamp); // Write current timestamp
  +
return SEGGER_RTT_WriteString(BufferIndex, s); // Write actual data
  +
}
  +
</source>
  +
  +
== Troubleshooting ==
  +
# Under some circumstances, the RTT Control Block cannot be detected automatically.<br>This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.<br>In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section ''RTT Control Block''.
  +
# If the control block is found, but the data is still not shown in the RTT Viewer, please make sure that you use '''channel 0''' for all transmissions, as only channel 0 is supported for the terminal view.<br>'''Channel 0''' is not equal to '''Terminal 0''' (see information provided in this article).
  +
# For additional troubleshooting please refer to [[RTT#Troubleshooting | RTT Troubleshooting]] article.

Revision as of 16:29, 4 November 2021

J-Link RTT Viewer

J-Link RTT Viewer is a GUI application available for Windows, MacOS and Linux and can be downloaded as part of the J-Link Software and Documentation Pack. It enables you to use all features of RTT in one application. It supports:

  • Displaying terminal output of Channel 0.
  • Up to 16 virtual Terminals on Channel 0.
  • Sending text input to Channel 0.
  • Interpreting text control codes for colored text and controlling the Terminal.
  • Logging terminal data into a file.
  • Logging data on Channel 1.

J-Link RTT Viewer Startup

Make sure J-Link and target device are connected and powered up.
Start J-Link RTT Viewer by opening the executable (JLinkRTTViewer.exe/JLinkRTTViewerExe) from the installation folder of the J-Link Software or the start menu. Unless the command line parameter --autoconnect is set, the Configuration Dialog will pop up.
Configure the Connection Settings as described below and click OK.
The connection settings and all in app configuration will be saved for the next start of J-Link RTT Viewer.

J-Link RTT Viewer Configuration dialog

The J-Link RTT Viewer Configuration dialog is used to set all necessary device specifics to successfully connect and read/send RTT data from/to the target device.

J-Link RTT Viewer Config dialog

Connection Settings

J-Link RTT Viewer can be used in two modes:

  • Stand-alone, opening an own connection to J-Link and target.
  • In attach mode, connecting to an existing J-Link connection of a debugger.

Stand-alone

In stand-alone mode J-Link RTT Viewer needs to know some settings of J-Link and target device:

  1. Select USB or TCP/IP as the connection to J-Link.
    1. For USB a specific J-Link serial number can optionally be entered
    2. For TCP/IP the IP or hostname of the J-Link has to be entered.
  2. Select the target device to connect to. This allows J-Link to search in the known RAM of the target.
  3. Select the target interface and interface speed.
  4. The RTT Control Block can be searched for fully automatically, it can be set to a fixed address or it can be searched for in one or more specific memory ranges.
    1. Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.
      In such a case, the address, or RAM range has to be specified by the user.

Attach mode

By selecting Connection to J-Link: > Existing Session RTT Viewer is started in attach mode. In attach mode J-Link RTT Viewer does usually not require any additional settings, however RTT Control Block Address or Search Ranges can still be selected if required.

For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply J-Link Commander.

The attach mode is especially useful when using a third party debugger or IDE working with a J-Link (e.g. Eclipse).

The Terminal Tabs

J-Link RTT Viewer allows displaying the output of Channel 0 in different "virtual" Terminals. The target application can switch between terminals with SEGGER_RTT_SetTerminal() and SEGGER_RTT_TerminalOut(). J-Link RTT Viewer displays the Terminals in different tabs.

J-Link RTT Viewer example in-/output


All Terminals

The All Terminals tab displays the complete output of RTT Channel 0 and can display the user input (Check Input -> Echo input... -> Echo to "All Terminals").\n Each output line is prefixed by the Terminal it has been sent to. Additionally, output on Terminal 1 is shown in red, output on Terminals 2 - 15 in gray.

Terminal 0 - 15

Each tab Terminal 0 - Terminal 15 displays the output which has been sent to this Terminal. The Terminal tabs interpret and display Text Control Codes as sent by the application to show colored text or erase the screen.
By default, if the RTT application does not set a Terminal Id, the output is displayed in Terminal 0.
The Terminal 0 tab can additionally display the user input. (Check Input -> Echo input... -> Echo to "Terminal 0")
Each Terminal tab can be shown or hidden via the menu Terminals -> Terminals... or their respective shortcuts as described below.

Sending Input

J-Link RTT Viewer "Sending input" dialog

J-Link RTT Viewer supports sending user input to RTT Down Channel 0 which can be read by the target application with SEGGER_RTT_GetKey() and SEGGER_RTT_Read().
Input can be entered in the text box below the Terminal Tabs.
J-Link RTT Viewer can be configured to directly send each character while typing or buffer it until Enter is pressed (Menu Input -> Sending...).
In stand-alone mode J-Link RTT Viewer can retry to send input, in case the target input buffer is full, until all data could be sent to the target via Input -> Sending... -> Block if FIFO full.

Logging output

The output of Channel 0 and Channel 1 can be logged into a text file.

Terminal output (Channel 0)

The format is the same as used in the All Terminals tab.
Terminal Logging can be started via Logging -> Start Terminal Logging...

Data output (Channel 1)

Channel 1 logging can for example be used to sent instrumented event tracing data. The data log file contains header and footer and the binary data as received from the application.
Data Logging can be started via Logging -> Start Data Logging...

NOTE: Data Logging is only available in stand-alone mode.

Command line options

J-Link RTT Viewer can be configured via command line parameters. In the following, the command line options which are available for J-Link RTT Viewer are explained. All command line options are case insensitive. Short and long command names have the same syntax.

Command line option Description
-b, --bright Bright theme for GUI
-d, --device Select the connected target device
-ct, --connection Sets the connection type
-if, --interface Sets the interface type
-ip, --host The IP address of the J-Link
-s, --speed Interface speed in kHz
-sf, --scriptfile Executes a command script on start up
-sn, --serialnumber Select the J-Link with a specific S/N
-ra, --rttaddr Sets the address of the RTT control block
-rr, --rttrange Specify RTT search range
-a, --autoconnect Automatically connect to target, suppress settings dialog
-ti, --terminalindex Opens the specified terminal application start

--bright

Starts the RTT Viewer in bright theme.

Syntax

--bright

Example

JLinkRTTViewer.exe --bright

--device

Selects the device J-Link RTT Viewer shall connect to.

Syntax

--device <DeviceName>

Example

JLinkRTTViewer.exe --device STM32F103ZE

--connection

Sets the connection type. The connection to the J-Link can either be made directly over USB, IP or using an existing running session (e.g. the IDE's debug session). In case of using an existing session, no further configuration options are required.

Syntax

--connection <usb|ip|sess>

Example

JLinkRTTViewer.exe --connection ip

--interface

Sets the interface J-Link shall use to connect to the target. As interface types FINE, JTAG and SWD are supported.

Syntax

--interface <fine|jtag|swd>

Example

JLinkRTTViewer.exe --interface swd

--host

Enter the IP address or hostname of the J-Link. This option only applies, if connection type IP is used. Use * as <IPAddr> for a list of available J-Links in the local subnet.

Syntax

--host <IPAddr>

Example

JLinkRTTViewer.exe --host 192.168.1.17

--speed

Sets the interface speed in kHz for target communication.

Syntax

--speed <speed>

Example

JLinkRTTViewer.exe --speed 4000

--scriptfile

Executes a JLink command script on startup, setting options in advance (e.g. Device = AT91SAM7S256)

Syntax

--scriptfile <FilePath>

Example

JLinkRTTViewer.exe --scriptfile C:\\tmp\\<Scriptfilename>

--serialnumber

Connect to a J-Link with a specific serial number via USB. Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link RTT Viewer shall run and each connects to another J-Link.

Syntax

--serialnumber <SerialNo>

Example

JLinkRTTViewer.exe --serialnumber 580011111

--rttaddr

Sets a fixed address as location of the RTT control block. Automatic searching for the RTT control block is disabled.

Syntax

--rttaddr <RTTCBAddr>

Example

JLinkRTTViewer.exe --rttaddr 0x20000000

--rttrange

Sets one or more memory ranges, where the J-Link DLL shall search for the RTT control block.

Syntax

--rttrange <RangeStart[Hex]> <RangeSize >[, <Range1Start [Hex]> <Range1Size>]>

Example

JLinkRTTViewer.exe --rttrange "20000000 400"

--autoconnect

Let J-Link RTT Viewer connect automatically to the target without showing the Connection Settings (see Connection Settings).

Syntax

--autoconnect

Example

JLinkRTTViewer.exe --autoconnect

--terminalindex

Opens the terminal with the specified index on application start
The value of index can be [0:16], with 0 == All Terminals, 1 == Terminal 0 ... 16 == Terminal 15

Syntax

--terminalindex <Index>

Example

JLinkRTTViewer.exe --terminalindex 7

Menus and Shortcuts

The J-Link RTT Viewer has a range of options available in the menu bar.

File menu elements

Menu entry Contents Shortcut
-> Connect... Opens the connect dialog and connects to the targets F2
-> Disconnect Disconnects from the target F3
-> Exit Closes connection and exit RTT Viewer. Alt-F4

Terminals menu elements

Menu entry Contents Shortcut
-> Add next terminal Opens the next available Terminal Tab. Alt-A
-> Clear active terminal Clears the currently selected terminal tab. Alt-R
-> Close active terminal Closes the active Terminal Tab. Alt-W
-> Open Terminal on output If selected, a terminal is automatically created, if data for this terminal is received. None
-> Edit font size Opens the font size selection dialog. None
Terminals -> Terminals...
-> Terminal 0 - 15 Opens or closes the Terminal Tab. Alt-Shift-0, ..., Alt-Shift-F

Input menu elements

Menu entry Contents Shortcut
-> Clear input field Clears the input field without sending entered data. Button "Clear"
Input -> Sending...
-> Send on Input If selected, entered input will be sent directly to the target while typing. None
-> Send on Enter If selected, entered input will be sent when pressing Enter. None
-> Block if FIFO full If checked, RTT Viewer will retry to send all input to the target when the target buffer is full. None
Input -> End of line...
-> Windows format (CR+LF)
-> Unix format (LF)
-> Mac format (CR)
-> None
Selects the end of line character to be sent on Enter. None
Input -> Echo input...
-> Echo to "All Terminals" If checked, sent input will be displayed in the All Terminals Tab. None
-> Echo to "Terminal 0" If checked, sent input will be displayed in the Terminal Tab 0. None

Logging menu elements

Menu entry Contents Shortcut
-> Start Terminal logging... Starts logging terminal data to a file. F5
-> Stop Terminal logging Stops logging terminal data and closes the file. Shift-F5
-> Start Data logging... Starts logging data of Channel 1 to a file. F6
-> Stop Data logging Stops logging data and closes the file. Shift-F6
-> Channel infos... Displays information about all available RTT channels. F8

Help menu elements

Menu entry Contents Shortcut
-> About... Shows version info of RTT Viewer. F12
-> J-Link Manual... Opens the J-Link Manual PDF file. F11
-> RTT Webpage... Opens the RTT webpage. F10

Tab context menu elements

Menu entry Contents Shortcut
-> Close Terminal Closes this Terminal Tab Alt-W
-> Clear Terminal Clears the displayed output of this Terminal Tab. Alt-R

Using "virtual" Terminals in RTT

For virtual Terminals the target application needs only Up Channel 0. This is especially important on targets with low RAM.
Notes

  • If no terminal is specified, all data is sent to Terminal 0.
  • The Terminal to show all following Write, WriteString or printf outputs can be set with SEGGER_RTT_SetTerminal().
  • Output of only one string via a specific Terminal can be done with SEGGER_RTT_TerminalOut().
  • The sequences sent to change the Terminal are interpreted by J-Link RTT Viewer. Other applications like a Telnet Client will ignore them.

Using Text Control Codes

RTT allows using Text Control Codes (ANSI escape codes) to configure the display of text. J-Link RTT Viewer supports changing the text color and background color and can erase the Terminal. These Control Codes are pre-defined in the RTT application and can easily be used in the application.

Examples

Please refer to the following examples for the correct implementation of the ANSI escape codes in combination with RTT.

Example 1

SEGGER_RTT_WriteString(0,
                       RTT_CTRL_RESET"Red: " \
                       RTT_CTRL_TEXT_BRIGHT_RED"This text is red. " \
                       RTT_CTRL_TEXT_BLACK"" \
                       RTT_CTRL_BG_BRIGHT_RED"This background is red. " \
                       RTT_CTRL_RESET"Normal text again."
                      );

Example 2

SEGGER_RTT_printf(0, "%sTime:%s%s %.7d\n",
                      RTT_CTRL_RESET,
                      RTT_CTRL_BG_BRIGHT_RED,
                      RTT_CTRL_TEXT_BRIGHT_WHITE,
                      1111111
                 );
//
// Clear the terminal.
// The first line will not be shown after this command.
//
SEGGER_RTT_WriteString(0, RTT_CTRL_CLEAR);

SEGGER_RTT_printf(0, "%sTime: %s%s%.7d\n",
                      RTT_CTRL_RESET,
                      RTT_CTRL_BG_BRIGHT_RED,
                      RTT_CTRL_TEXT_BRIGHT_WHITE,
                      2222222
                 );

Using Timestamps

The J-Link RTT Viewer does not provide functionality to show host PC sided timestamps, because of the following reasons:

  • Timestamps created on host PC side (HS) do not represent the actual time the data was written to the RTT buffer on device side (DS), but the time when the data was received by the J-Link RTT Viewer.
  • The delay between writing data to the RTT buffer (DS) and receiving it via the RTT Viewer (HS) is not constant but varying.
  • In case data is written very fast to the RTT buffer (DS), multiple messages that were originally intended as single messages would be presented with one single timestamp, when received with a single data read (HS).
  • In case data is already present in the RTT buffer (DS) before the RTT Viewer connects to it, all this data would have one timestamp (HS), even when they were not written to the buffer at the same time originally.

Connclusion: The correct way to implement timestamps for RTT is on target side, as PC sided timestamps do not represent the real, on target behavior.

Example

To create timestamps for all log messages reliably, a wrapper function can be used:

/*********************************************************************
*
*       _WriteStringWTS()
*
*  Function description
*    Example wrapper function for SEGGER_RTT_WriteString(), adding a Timestamp.
*/
static unsigned _WriteStringWTS(unsigned BufferIndex, const char* s) {
  const char* sTimestamp;

  sTimestamp = _GetTimestamp();                    // Creates a timestamp string of desired format (e.g. "MM:ss.SSSS - ", since program start)
  SEGGER_RTT_WriteString(BufferIndex, sTimestamp); // Write current timestamp
  return SEGGER_RTT_WriteString(BufferIndex, s);   // Write actual data
}

Troubleshooting

  1. Under some circumstances, the RTT Control Block cannot be detected automatically.
    This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.
    In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section RTT Control Block.
  2. If the control block is found, but the data is still not shown in the RTT Viewer, please make sure that you use channel 0 for all transmissions, as only channel 0 is supported for the terminal view.
    Channel 0 is not equal to Terminal 0 (see information provided in this article).
  3. For additional troubleshooting please refer to RTT Troubleshooting article.