doc/tools/nordic_segger.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 :orphan:

 .. _nordic_segger:

 Nordic nRF5x Segger J-Link
 ##########################

 Overview
 ********

 All Nordic nRF5x Development Kits, Preview Development Kits and Dongles are equipped
 with a Debug IC (Atmel ATSAM3U2C) which provides the following functionality:

 * Segger J-Link firmware and desktop tools
 * SWD debug for the nRF5x IC
 * Mass Storage device for drag-and-drop image flashing
 * USB CDC ACM Serial Port bridged to the nRF5x UART peripheral
 * Segger RTT Console
 * Segger Ozone Debugger

 Segger J-Link Software Installation
 ***********************************

 To install the J-Link Software and documentation pack, follow the steps below:

 #. Download the appropriate package from the `J-Link Software and documentation pack`_ website
 #. Depending on your platform, install the package or run the installer
 #. When connecting a J-Link-enabled board such as an nRF5x DK, PDK or dongle, a
    drive corresponding to a USB Mass Storage device as well as a serial port should come up

 nRF5x Command-Line Tools Installation
 *************************************

 The nRF5x command-line Tools allow you to control your nRF5x device from the command line,
 including resetting it, erasing or programming the flash memory and more.

 To install them, use the appropriate link for your operating system:

 * `nRF5x Command-Line Tools for Windows`_
 * `nRF5x Command-Line Tools for Linux 32-bit`_
 * `nRF5x Command-Line Tools for Linux 64-bit`_
 * `nRF5x Command-Line Tools for macOS`_

 After installing, make sure that ``nrfjprog`` is somewhere in your executable path
 to be able to invoke it from anywhere.

 .. _nordic_segger_flashing:

 Flashing
 ********

 To program the flash with a compiled Zephyr image after having followed the instructions
 to install the Segger J-Link Software and the nRF5x Command-Line Tools, follow the steps below:

 * Connect the micro-USB cable to the nRF5x board and to your computer
 * Erase the flash memory in the nRF5x IC:

 .. code-block:: console

    nrfjprog --eraseall -f nrf5<x>

 Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

 * Flash the Zephyr image from the sample folder of your choice:

 .. code-block:: console

    nrfjprog --program outdir/<board>/zephyr.hex -f nrf5<x>

 Where: ``<board>`` is the board name you used in the BOARD directive when building (for example nrf52_pca10040)
 and ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

 * Reset and start Zephyr:

 .. code-block:: console

    nrfjprog --reset -f nrf5<x>

 Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

 USB CDC ACM Serial Port Setup
 *****************************

 **Important note**: An issue with Segger J-Link firmware on the nRF5x boards might cause
 data loss and/or corruption on the USB CDC ACM Serial Port on some machines.
 To work around this disable the Mass Storage Device on your board as described in :ref:`nordic_segger_msd`.

 Windows
 =======

 The serial port will appear as ``COMxx``. Simply check the "Ports (COM & LPT)" section
 in the Device Manager.

 GNU/Linux
 =========

 The serial port will appear as ``/dev/ttyACMx``. By default the port is not accessible to all users.
 Type the command below to add your user to the dialout group to give it access to the serial port.
 Note that re-login is required for this to take effect.

 .. code-block:: bash

    sudo usermod -a -G dialout `whoami`

 Recent versions of `ModemManager send AT commands to TTY-like devices`_; this
 includes Nordic development kits. This will prevent you from using the serial
 port for a few seconds, and can make your application misbehave if it reads
 data from the UART. Before running your application, you might want to
 temporarily disable ModemManager by running these commands:

 .. code-block:: bash

    systemctl stop ModemManager.service
    systemctl disable ModemManager.service

 You can also `blacklist Segger devices by editing udev rules`_ so ModemManager
 ignores them, by running:

 .. code-block:: bash

    sudo sh -c 'echo "ATTRS{idVendor}==\"1366\", ENV{ID_MM_DEVICE_IGNORE}=\"1\" " \
      >> /etc/udev/rules.d/99-segger-modemmanager-blacklist.rules'
    sudo service udev restart

 A fix for this is expected in ModemManager 1.8 and new firmware for the Segger IMCUs.

 Apple macOS (OS X)
 ==================

 The serial port will appear as ``/dev/tty.usbmodemXXXX``.

 .. _nordic_segger_msd:

 Disabling the Mass Storage Device functionality
 ***********************************************

 Due to a known issue in Segger's J-Link firmware, depending on your operating system
 and version you might experience data corruption or drops if you use the USB CDC
 ACM Serial Port with packets larger than 64 bytes.
 This has been observed on both GNU/Linux and macOS (OS X).

 To avoid this, you can simply disable the Mass Storage Device by opening:

 * On GNU/Linux or macOS (OS X) JLinkExe from a terminal
 * On Microsoft Windows the "JLink Commander" application

 And then typing the following:

 .. code-block:: bat

    MSDDisable

 And finally unplugging and replugging the board. The Mass Storage Device should
 not appear anymore and you should now be able to send long packets over the virtual Serial Port.
 Further information from Segger can be found in the `Segger SAM3U Wiki`_.

 RTT Console
 ***********

 Segger's J-Link supports `Real-Time Tracing (RTT)`_, a technology that allows a terminal
 connection (both input and output) to be established between the target (nRF5x board)
 and the development computer for logging and input. Zephyr supports RTT on nRF5x targets,
 which can be very useful if the UART (through USB CDC ACM) is already being used for
 a purpose different than logging (such as HCI traffic in the hci_uart application).
 To use RTT, you will first need to enable it by adding the following lines in your ``.conf`` file:

 .. code-block:: text

    CONFIG_HAS_SEGGER_RTT=y
    CONFIG_RTT_CONSOLE=y

 If you get no RTT output you might need to disable other consoles which conflict
 with the RTT one if they are enabled by default in the particular sample or
 application you are running. For example, to disable the UART console,
 add this to your ``.conf`` file:

 .. code-block:: console

    CONFIG_UART_CONSOLE=n

 Once compiled and flashed with RTT enabled, you will be able to display RTT console
 messages by doing the following:

 Windows
 =======

 * Open the "J-Link RTT Viewer" application
 * Select the following options:

   * Connection: USB
   * Target Device: Select your IC from the list
   * Target Interface and Speed: SWD, 4000 KHz
   * RTT Control Block: Auto Detection

 GNU/Linux and macOS (OS X)
 ==========================

 * Open ``JLinkRTTLogger`` from a terminal
 * Select the following options:

   * Device Name: Use the fully qualified device name for your IC
   * Target Interface: SWD
   * Interface Speed: 4000 KHz
   * RTT Control Block address: auto-detection
   * RTT Channel name or index: 0
   * Output file: filename or ``/dev/stdout`` to display on the terminal directly

 Python viewer
 =============

 A Python RTT viewer tool can be found in the `pyrtt-viewer`_ GitHub repository.

 Segger Ozone
 ************

 Segger J-Link is compatible with `Segger Ozone`_, a visual debugger that can be obtained here:

 * `Segger Ozone Download`_

 Once downloaded you can install it and configure it like so:

 * Target Device: Select your IC from the list
 * Target Interface: SWD
 * Target Interface Speed: 4 MHz
 * Host Interface: USB

 Once configured, you can then use the File->Open menu to open the ``zephyr.elf``
 file that you can find in your build folder.

 References
 **********

 .. target-notes::

 .. _nRF5x Command-Line Tools for Windows: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Win32/33444
 .. _nRF5x Command-Line Tools for Linux 32-bit: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux32/52615
 .. _nRF5x Command-Line Tools for Linux 64-bit: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux64/51386
 .. _nRF5x Command-Line Tools for macOS: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-OSX/53402

 .. _Segger SAM3U Wiki: https://wiki.segger.com/index.php?title=J-Link-OB_SAM3U
 .. _Real-Time Tracing (RTT): https://www.segger.com/jlink-rtt.html
 .. _pyrtt-viewer: https://github.com/thomasstenersen/pyrtt-viewer
 .. _Segger Ozone: https://www.segger.com/ozone.html
 .. _Segger Ozone Download: https://www.segger.com/downloads/jlink#Ozone

 .. _ModemManager send AT commands to TTY-like devices: https://bugs.freedesktop.org/show_bug.cgi?id=85007
 .. _blacklist Segger devices by editing udev rules: http://www.at91.com/linux4sam/bin/view/Linux4SAM/SoftwareTools#Device_or_resource_busy_dev_ttyA

 .. _nRF52 DK website: http://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF52-DK
 .. _Nordic Semiconductor Infocenter: http://infocenter.nordicsemi.com/
 .. _J-Link Software and documentation pack: https://www.segger.com/jlink-software.html
	:orphan:

	.. _nordic_segger:

	Nordic nRF5x Segger J-Link
	##########################

	Overview
	********

	All Nordic nRF5x Development Kits, Preview Development Kits and Dongles are equipped
	with a Debug IC (Atmel ATSAM3U2C) which provides the following functionality:

	* Segger J-Link firmware and desktop tools
	* SWD debug for the nRF5x IC
	* Mass Storage device for drag-and-drop image flashing
	* USB CDC ACM Serial Port bridged to the nRF5x UART peripheral
	* Segger RTT Console
	* Segger Ozone Debugger

	Segger J-Link Software Installation
	***********************************

	To install the J-Link Software and documentation pack, follow the steps below:

	#. Download the appropriate package from the `J-Link Software and documentation pack`_ website
	#. Depending on your platform, install the package or run the installer
	#. When connecting a J-Link-enabled board such as an nRF5x DK, PDK or dongle, a
	drive corresponding to a USB Mass Storage device as well as a serial port should come up

	nRF5x Command-Line Tools Installation
	*************************************

	The nRF5x command-line Tools allow you to control your nRF5x device from the command line,
	including resetting it, erasing or programming the flash memory and more.

	To install them, use the appropriate link for your operating system:

	* `nRF5x Command-Line Tools for Windows`_
	* `nRF5x Command-Line Tools for Linux 32-bit`_
	* `nRF5x Command-Line Tools for Linux 64-bit`_
	* `nRF5x Command-Line Tools for macOS`_

	After installing, make sure that ``nrfjprog`` is somewhere in your executable path
	to be able to invoke it from anywhere.

	.. _nordic_segger_flashing:

	Flashing
	********

	To program the flash with a compiled Zephyr image after having followed the instructions
	to install the Segger J-Link Software and the nRF5x Command-Line Tools, follow the steps below:

	* Connect the micro-USB cable to the nRF5x board and to your computer
	* Erase the flash memory in the nRF5x IC:

	.. code-block:: console

	nrfjprog --eraseall -f nrf5<x>

	Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

	* Flash the Zephyr image from the sample folder of your choice:

	.. code-block:: console

	nrfjprog --program outdir/<board>/zephyr.hex -f nrf5<x>

	Where: ``<board>`` is the board name you used in the BOARD directive when building (for example nrf52_pca10040)
	and ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

	* Reset and start Zephyr:

	.. code-block:: console

	nrfjprog --reset -f nrf5<x>

	Where ``<x>`` is either 1 for nRF51-based boards or 2 for nRF52-based boards

	USB CDC ACM Serial Port Setup
	*****************************

	Important note: An issue with Segger J-Link firmware on the nRF5x boards might cause
	data loss and/or corruption on the USB CDC ACM Serial Port on some machines.
	To work around this disable the Mass Storage Device on your board as described in :ref:`nordic_segger_msd`.

	Windows
	=======

	The serial port will appear as ``COMxx``. Simply check the "Ports (COM & LPT)" section
	in the Device Manager.

	GNU/Linux
	=========

	The serial port will appear as ``/dev/ttyACMx``. By default the port is not accessible to all users.
	Type the command below to add your user to the dialout group to give it access to the serial port.
	Note that re-login is required for this to take effect.

	.. code-block:: bash

	sudo usermod -a -G dialout `whoami`

	Recent versions of `ModemManager send AT commands to TTY-like devices`_; this
	includes Nordic development kits. This will prevent you from using the serial
	port for a few seconds, and can make your application misbehave if it reads
	data from the UART. Before running your application, you might want to
	temporarily disable ModemManager by running these commands:

	.. code-block:: bash

	systemctl stop ModemManager.service
	systemctl disable ModemManager.service

	You can also `blacklist Segger devices by editing udev rules`_ so ModemManager
	ignores them, by running:

	.. code-block:: bash

	sudo sh -c 'echo "ATTRS{idVendor}==\"1366\", ENV{ID_MM_DEVICE_IGNORE}=\"1\" " \
	>> /etc/udev/rules.d/99-segger-modemmanager-blacklist.rules'
	sudo service udev restart

	A fix for this is expected in ModemManager 1.8 and new firmware for the Segger IMCUs.

	Apple macOS (OS X)
	==================

	The serial port will appear as ``/dev/tty.usbmodemXXXX``.

	.. _nordic_segger_msd:

	Disabling the Mass Storage Device functionality
	***********************************************

	Due to a known issue in Segger's J-Link firmware, depending on your operating system
	and version you might experience data corruption or drops if you use the USB CDC
	ACM Serial Port with packets larger than 64 bytes.
	This has been observed on both GNU/Linux and macOS (OS X).

	To avoid this, you can simply disable the Mass Storage Device by opening:

	* On GNU/Linux or macOS (OS X) JLinkExe from a terminal
	* On Microsoft Windows the "JLink Commander" application

	And then typing the following:

	.. code-block:: bat

	MSDDisable

	And finally unplugging and replugging the board. The Mass Storage Device should
	not appear anymore and you should now be able to send long packets over the virtual Serial Port.
	Further information from Segger can be found in the `Segger SAM3U Wiki`_.

	RTT Console
	***********

	Segger's J-Link supports `Real-Time Tracing (RTT)`_, a technology that allows a terminal
	connection (both input and output) to be established between the target (nRF5x board)
	and the development computer for logging and input. Zephyr supports RTT on nRF5x targets,
	which can be very useful if the UART (through USB CDC ACM) is already being used for
	a purpose different than logging (such as HCI traffic in the hci_uart application).
	To use RTT, you will first need to enable it by adding the following lines in your ``.conf`` file:

	.. code-block:: text

	CONFIG_HAS_SEGGER_RTT=y
	CONFIG_RTT_CONSOLE=y

	If you get no RTT output you might need to disable other consoles which conflict
	with the RTT one if they are enabled by default in the particular sample or
	application you are running. For example, to disable the UART console,
	add this to your ``.conf`` file:

	.. code-block:: console

	CONFIG_UART_CONSOLE=n

	Once compiled and flashed with RTT enabled, you will be able to display RTT console
	messages by doing the following:

	Windows
	=======

	* Open the "J-Link RTT Viewer" application
	* Select the following options:

	* Connection: USB
	* Target Device: Select your IC from the list
	* Target Interface and Speed: SWD, 4000 KHz
	* RTT Control Block: Auto Detection

	GNU/Linux and macOS (OS X)
	==========================

	* Open ``JLinkRTTLogger`` from a terminal
	* Select the following options:

	* Device Name: Use the fully qualified device name for your IC
	* Target Interface: SWD
	* Interface Speed: 4000 KHz
	* RTT Control Block address: auto-detection
	* RTT Channel name or index: 0
	* Output file: filename or ``/dev/stdout`` to display on the terminal directly

	Python viewer
	=============

	A Python RTT viewer tool can be found in the `pyrtt-viewer`_ GitHub repository.

	Segger Ozone
	************

	Segger J-Link is compatible with `Segger Ozone`_, a visual debugger that can be obtained here:

	* `Segger Ozone Download`_

	Once downloaded you can install it and configure it like so:

	* Target Device: Select your IC from the list
	* Target Interface: SWD
	* Target Interface Speed: 4 MHz
	* Host Interface: USB

	Once configured, you can then use the File->Open menu to open the ``zephyr.elf``
	file that you can find in your build folder.

	References
	**********

	.. target-notes::

	.. _nRF5x Command-Line Tools for Windows: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Win32/33444
	.. _nRF5x Command-Line Tools for Linux 32-bit: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux32/52615
	.. _nRF5x Command-Line Tools for Linux 64-bit: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-Linux64/51386
	.. _nRF5x Command-Line Tools for macOS: https://www.nordicsemi.com/eng/nordic/Products/nRF51822/nRF5x-Command-Line-Tools-OSX/53402

	.. _Segger SAM3U Wiki: https://wiki.segger.com/index.php?title=J-Link-OB_SAM3U
	.. _Real-Time Tracing (RTT): https://www.segger.com/jlink-rtt.html
	.. _pyrtt-viewer: https://github.com/thomasstenersen/pyrtt-viewer
	.. _Segger Ozone: https://www.segger.com/ozone.html
	.. _Segger Ozone Download: https://www.segger.com/downloads/jlink#Ozone

	.. _ModemManager send AT commands to TTY-like devices: https://bugs.freedesktop.org/show_bug.cgi?id=85007
	.. _blacklist Segger devices by editing udev rules: http://www.at91.com/linux4sam/bin/view/Linux4SAM/SoftwareTools#Device_or_resource_busy_dev_ttyA

	.. _nRF52 DK website: http://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF52-DK
	.. _Nordic Semiconductor Infocenter: http://infocenter.nordicsemi.com/
	.. _J-Link Software and documentation pack: https://www.segger.com/jlink-software.html