1:orphan: 2 3.. _nordic_segger: 4 5Nordic nRF5x Segger J-Link 6########################## 7 8Overview 9******** 10 11All Nordic nRF5x Development Kits, Preview Development Kits and Dongles are equipped 12with a Debug IC (Atmel ATSAM3U2C) which provides the following functionality: 13 14* Segger J-Link firmware and desktop tools 15* SWD debug for the nRF5x IC 16* Mass Storage device for drag-and-drop image flashing 17* USB CDC ACM Serial Port bridged to the nRF5x UART peripheral 18* Segger RTT Console 19* Segger Ozone Debugger 20 21Segger J-Link Software Installation 22*********************************** 23 24To install the J-Link Software and documentation pack, follow the steps below: 25 26#. Download the appropriate package from the `J-Link Software and documentation pack`_ website 27#. Depending on your platform, install the package or run the installer 28#. When connecting a J-Link-enabled board such as an nRF5x DK, PDK or dongle, a 29 drive corresponding to a USB Mass Storage device as well as a serial port should come up 30 31nRF5x Command-Line Tools Installation 32************************************* 33 34The nRF5x command-line Tools allow you to control your nRF5x device from the command line, 35including resetting it, erasing or programming the flash memory and more. 36 37To install them, visit `nRF5x Command-Line Tools`_ and select your operating 38system. 39 40After installing, make sure that ``nrfjprog`` is somewhere in your executable path 41to be able to invoke it from anywhere. 42 43.. _nordic_segger_flashing: 44 45Flashing 46******** 47 48To program the flash with a compiled Zephyr image after having followed the instructions 49to install the Segger J-Link Software and the nRF5x Command-Line Tools, follow the steps below: 50 51* Connect the micro-USB cable to the nRF5x board and to your computer 52* Erase the flash memory in the nRF5x IC: 53 54.. code-block:: console 55 56 nrfjprog --eraseall -f nrf5<x> 57 58Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards 59 60* Flash the Zephyr image from the sample folder of your choice: 61 62.. code-block:: console 63 64 nrfjprog --program outdir/<board>/zephyr.hex -f nrf5<x> 65 66Where: ``<board>`` is the board name you used in the BOARD directive when building (for example nrf52dk/nrf52832) 67and ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards 68 69* Reset and start Zephyr: 70 71.. code-block:: console 72 73 nrfjprog --reset -f nrf5<x> 74 75Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards 76 77USB CDC ACM Serial Port Setup 78***************************** 79 80**Important note**: An issue with Segger J-Link firmware on the nRF5x boards might cause 81data loss and/or corruption on the USB CDC ACM Serial Port on some machines. 82To work around this disable the Mass Storage Device on your board as described in :ref:`nordic_segger_msd`. 83 84Windows 85======= 86 87The serial port will appear as ``COMxx``. Simply check the "Ports (COM & LPT)" section 88in the Device Manager. 89 90GNU/Linux 91========= 92 93The serial port will appear as ``/dev/ttyACMx``. By default the port is not accessible to all users. 94Type the command below to add your user to the dialout group to give it access to the serial port. 95Note that re-login is required for this to take effect. 96 97.. code-block:: bash 98 99 sudo usermod -a -G dialout `whoami` 100 101Recent versions of `ModemManager send AT commands to TTY-like devices`_; this 102includes Nordic development kits. This will prevent you from using the serial 103port for a few seconds, and can make your application misbehave if it reads 104data from the UART. Before running your application, you might want to 105temporarily disable ModemManager by running these commands: 106 107.. code-block:: bash 108 109 systemctl stop ModemManager.service 110 systemctl disable ModemManager.service 111 112You can also `blacklist Segger devices by editing udev rules`_ so ModemManager 113ignores them, by running: 114 115.. code-block:: bash 116 117 sudo sh -c 'echo "ATTRS{idVendor}==\"1366\", ENV{ID_MM_DEVICE_IGNORE}=\"1\" " \ 118 >> /etc/udev/rules.d/99-segger-modemmanager-blacklist.rules' 119 sudo service udev restart 120 121A fix for this is expected in ModemManager 1.8 and new firmware for the Segger IMCUs. 122 123Apple macOS (OS X) 124================== 125 126The serial port will appear as ``/dev/tty.usbmodemXXXX``. 127 128.. _nordic_segger_msd: 129 130Disabling the Mass Storage Device functionality 131*********************************************** 132 133Due to a known issue in Segger's J-Link firmware, depending on your operating system 134and version you might experience data corruption or drops if you use the USB CDC 135ACM Serial Port with packets larger than 64 bytes. 136This has been observed on both GNU/Linux and macOS (OS X). 137 138To avoid this, you can simply disable the Mass Storage Device by opening: 139 140* On GNU/Linux or macOS (OS X) JLinkExe from a terminal 141* On Microsoft Windows the "JLink Commander" application 142 143And then typing the following: 144 145.. code-block:: bat 146 147 MSDDisable 148 149And finally unplugging and replugging the board. The Mass Storage Device should 150not appear anymore and you should now be able to send long packets over the virtual Serial Port. 151Further information from Segger can be found in the `Segger SAM3U Wiki`_. 152 153RTT Console 154*********** 155 156Segger's J-Link supports `Real-Time Tracing (RTT)`_, a technology that allows a terminal 157connection (both input and output) to be established between the target (nRF5x board) 158and the development computer for logging and input. Zephyr supports RTT on nRF5x targets, 159which can be very useful if the UART (through USB CDC ACM) is already being used for 160a purpose different than logging (such as HCI traffic in the hci_uart application). 161To use RTT, you will first need to enable it by adding the following lines in your ``.conf`` file: 162 163.. code-block:: cfg 164 165 CONFIG_USE_SEGGER_RTT=y 166 CONFIG_RTT_CONSOLE=y 167 168.. warning:: 169 170 There is also a ``HAS_SEGGER_RTT`` symbol that indicates that the platform 171 supports SEGGER J-Link RTT. This symbol is set automatically by the SoC 172 Kconfig files. Do not confuse it with ``USE_SEGGER_RTT``. 173 174 ``USE_SEGGER_RTT`` depends on ``HAS_SEGGER_RTT``. 175 176If you get no RTT output you might need to disable other consoles which conflict 177with the RTT one if they are enabled by default in the particular sample or 178application you are running. For example, to disable the UART console, 179add this to your ``.conf`` file: 180 181.. code-block:: cfg 182 183 CONFIG_UART_CONSOLE=n 184 185Once compiled and flashed with RTT enabled, you will be able to display RTT console 186messages by doing the following: 187 188Windows 189======= 190 191* Open the "J-Link RTT Viewer" application 192* Select the following options: 193 194 * Connection: USB 195 * Target Device: Select your IC from the list 196 * Target Interface and Speed: SWD, 4000 KHz 197 * RTT Control Block: Auto Detection 198 199GNU/Linux and macOS (OS X) 200========================== 201 202* Open ``JLinkRTTLogger`` from a terminal 203* Select the following options: 204 205 * Device Name: Use the fully qualified device name for your IC 206 * Target Interface: SWD 207 * Interface Speed: 4000 KHz 208 * RTT Control Block address: auto-detection 209 * RTT Channel name or index: 0 210 * Output file: filename or ``/dev/stdout`` to display on the terminal directly 211 212Python viewer 213============= 214 215A Python RTT viewer tool can be found in the `pyrtt-viewer`_ GitHub repository. 216 217Segger Ozone 218************ 219 220Segger J-Link is compatible with `Segger Ozone`_, a visual debugger that can be obtained here: 221 222* `Segger Ozone Download`_ 223 224Once downloaded you can install it and configure it like so: 225 226* Target Device: Select your IC from the list 227* Target Interface: SWD 228* Target Interface Speed: 4 MHz 229* Host Interface: USB 230 231Once configured, you can then use the File->Open menu to open the ``zephyr.elf`` 232file that you can find in your build folder. 233 234References 235********** 236 237.. target-notes:: 238 239.. _nRF5x Command-Line Tools: https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools 240 241.. _Segger SAM3U Wiki: https://wiki.segger.com/index.php?title=J-Link-OB_SAM3U 242.. _Real-Time Tracing (RTT): https://www.segger.com/jlink-rtt.html 243.. _pyrtt-viewer: https://github.com/thomasstenersen/pyrtt-viewer 244.. _Segger Ozone: https://www.segger.com/ozone.html 245.. _Segger Ozone Download: https://www.segger.com/downloads/jlink#Ozone 246 247.. _ModemManager send AT commands to TTY-like devices: https://bugs.freedesktop.org/show_bug.cgi?id=85007 248.. _blacklist Segger devices by editing udev rules: http://www.at91.com/linux4sam/bin/view/Linux4SAM/SoftwareTools#Device_or_resource_busy_dev_ttyA 249 250.. _J-Link Software and documentation pack: https://www.segger.com/jlink-software.html 251
