1.. _nrf52840dongle_nrf52840:
2
3nRF52840 Dongle
4###############
5
6Overview
7********
8
9The nRF52840 Dongle (PCA10059) hardware provides support for the Nordic
10Semiconductor nRF52840 ARM Cortex-M4F CPU and the following devices:
11
12* :abbr:`ADC (Analog to Digital Converter)`
13* CLOCK
14* FLASH
15* :abbr:`GPIO (General Purpose Input Output)`
16* :abbr:`I2C (Inter-Integrated Circuit)`
17* :abbr:`MPU (Memory Protection Unit)`
18* :abbr:`NVIC (Nested Vectored Interrupt Controller)`
19* :abbr:`PWM (Pulse Width Modulation)`
20* RADIO (Bluetooth Low Energy and 802.15.4)
21* :abbr:`RTC (nRF RTC System Clock)`
22* :abbr:`SPI (Serial Peripheral Interface)`
23* :abbr:`UART (Universal asynchronous receiver-transmitter)`
24* :abbr:`USB (Universal Serial Bus)`
25* :abbr:`WDT (Watchdog Timer)`
26
27.. figure:: img/nrf52840dongle_nrf52840.jpg
28     :align: center
29     :alt: nRF52840 Dongle
30
31     nRF52840 Dongle
32
33More information about the board can be found at the
34`nRF52840 Dongle website`_. The `Nordic Semiconductor Infocenter`_
35contains the processor's information and the datasheet.
36
37
38Hardware
39********
40
41The ``nrf52840dongle_nrf52840`` has two external oscillators. The frequency of
42the slow clock is 32.768 kHz. The frequency of the main clock
43is 32 MHz.
44
45Supported Features
46==================
47
48The ``nrf52840dongle_nrf52840`` board configuration supports the following
49hardware features:
50
51+-----------+------------+----------------------+
52| Interface | Controller | Driver/Component     |
53+===========+============+======================+
54| ADC       | on-chip    | adc                  |
55+-----------+------------+----------------------+
56| CLOCK     | on-chip    | clock_control        |
57+-----------+------------+----------------------+
58| FLASH     | on-chip    | flash                |
59+-----------+------------+----------------------+
60| GPIO      | on-chip    | gpio                 |
61+-----------+------------+----------------------+
62| I2C(M)    | on-chip    | i2c                  |
63+-----------+------------+----------------------+
64| MPU       | on-chip    | arch/arm             |
65+-----------+------------+----------------------+
66| NVIC      | on-chip    | arch/arm             |
67+-----------+------------+----------------------+
68| PWM       | on-chip    | pwm                  |
69+-----------+------------+----------------------+
70| RADIO     | on-chip    | Bluetooth,           |
71|           |            | ieee802154           |
72+-----------+------------+----------------------+
73| RTC       | on-chip    | system clock         |
74+-----------+------------+----------------------+
75| SPI(M/S)  | on-chip    | spi                  |
76+-----------+------------+----------------------+
77| UART      | on-chip    | serial               |
78+-----------+------------+----------------------+
79| USB       | on-chip    | usb                  |
80+-----------+------------+----------------------+
81| WDT       | on-chip    | watchdog             |
82+-----------+------------+----------------------+
83
84Other hardware features have not been enabled yet for this board.
85See `nRF52840 Dongle website`_ and `Nordic Semiconductor Infocenter`_
86for a complete list of nRF52840 Dongle board hardware features.
87
88Connections and IOs
89===================
90
91LED
92---
93
94* LED0 (green) = P0.6
95* LED1 (red)   = P0.8
96* LED1 (green) = P1.9
97* LED1 (blue)  = P0.12
98
99Push buttons
100------------
101
102* BUTTON1 = SW1 = P1.6
103* RESET   = SW2 = P0.18
104
105Programming and Debugging
106*************************
107
108Applications for the ``nrf52840dongle_nrf52840`` board configuration can be
109built in the usual way (see :ref:`build_an_application` for more details).
110
111Flashing
112========
113
114The board supports the following programming options:
115
1161. Using the built-in bootloader only
1172. Using MCUboot in serial recovery mode
1183. Using an external :ref:`debug probe <debug-probes>`
119
120These instructions use the :ref:`west <west>` tool and assume you are in the
121root directory of your :term:`west installation`.
122
123Option 1: Using the Built-In Bootloader Only
124--------------------------------------------
125
126The board is factory-programmed with Nordic's bootloader from Nordic's nRF5
127SDK. With this option, you'll use Nordic's `nrfutil`_ program to create
128firmware packages supported by this bootloader and flash them to the
129device. Make sure ``nrfutil`` is installed before proceeding.
130
131#. Reset the board into the Nordic bootloader by pressing the RESET button.
132
133   The push button is on the far side of the board from the USB connector. Note
134   that the button does not face up. You will have to push it from the outside
135   in, towards the USB connector:
136
137   .. image:: img/nRF52840_dongle_press_reset.svg
138      :alt: Location of RESET button and direction of push
139
140   The red LED should start a fade pattern, signalling the bootloader is
141   running.
142
143#. Compile a Zephyr application; we'll use :zephyr:code-sample:`blinky`.
144
145   .. zephyr-app-commands::
146      :app: zephyr/samples/basic/blinky
147      :board: nrf52840dongle_nrf52840
148      :goals: build
149
150#. Package the application for the bootloader using ``nrfutil``:
151
152   .. code-block:: console
153
154      nrfutil pkg generate --hw-version 52 --sd-req=0x00 \
155              --application build/zephyr/zephyr.hex \
156              --application-version 1 blinky.zip
157
158#. Flash it onto the board. Note :file:`/dev/ttyACM0` is for Linux; it will be
159   something like ``COMx`` on Windows, and something else on macOS.
160
161   .. code-block:: console
162
163      nrfutil dfu usb-serial -pkg blinky.zip -p /dev/ttyACM0
164
165   When this command exits, observe the green LED on the board blinking,
166   instead of the red LED used by the bootloader.
167
168For more information, see `Nordic Semiconductor USB DFU`_.
169
170Option 2: Using MCUboot in Serial Recovery Mode
171-----------------------------------------------
172
173It is also possible to use the MCUboot bootloader with this board to flash
174Zephyr applications. You need to do some one-time set-up to build and flash
175MCUboot on your board. From that point on, you can build and flash other Zephyr
176applications using MCUboot's serial recovery mode. This process does not
177overwrite the built-in Nordic bootloader, so you can always go back to using
178Option 1 later.
179
180Install `nrfutil`_ and `mcumgr`_ first, and make sure MCUboot's ``imgtool`` is
181available for signing your binary for MCUboot as described on :ref:`west-sign`.
182
183Next, do the **one-time setup** to flash MCUboot. We'll assume you've cloned
184the `MCUboot`_ repository into the directory ``mcuboot``, and that it is next
185to the zephyr repository on your computer.
186
187#. Reset the board into the Nordic bootloader as described above.
188
189#. Compile MCUboot as a Zephyr application.
190
191   .. zephyr-app-commands::
192      :app: mcuboot/boot/zephyr
193      :board: nrf52840dongle_nrf52840
194      :build-dir: mcuboot
195      :goals: build
196
197#. Package the application for the bootloader using ``nrfutil``:
198
199   .. code-block:: console
200
201      nrfutil pkg generate --hw-version 52 --sd-req=0x00 \
202              --application build/mcuboot/zephyr/zephyr.hex \
203              --application-version 1 mcuboot.zip
204
205#. Flash it onto the board. Note :file:`/dev/ttyACM0` is for Linux; it will be
206   something like ``COMx`` on Windows, and something else on macOS.
207
208   .. code-block:: console
209
210      nrfutil dfu usb-serial -pkg mcuboot.zip -p /dev/ttyACM0
211
212You can now flash a Zephyr application to the board using MCUboot's serial
213recovery mode. We'll use the :zephyr:code-sample:`smp-svr` sample since it's ready to be
214compiled for chain-loading by MCUboot (and itself supports firmware updates
215over Bluetooth).
216
217#. Boot into MCUboot serial recovery mode by plugging the board in with the SW1
218   button pressed down. See above for a picture showing where SW1 is.
219
220   **Do not press RESET**; that will run the Nordic bootloader, which is
221   different than MCUboot.
222
223   A serial port will enumerate on your board. On Windows, "MCUBOOT" should
224   appear under "Other Devices" in the Device Manager (in addition to the usual
225   ``COMx`` device). On Linux, something like
226   :file:`/dev/serial/by-id/usb-ZEPHYR_MCUBOOT_0.01-if00` should be created.
227
228   If no serial port appears, try plugging it in again, making sure SW1 is
229   pressed. If it still doesn't appear, retry the one-time MCUboot setup.
230
231#. Compile ``smp_svr``.
232
233   .. zephyr-app-commands::
234      :app: zephyr/samples/subsys/mgmt/mcumgr/smp_svr
235      :board: nrf52840dongle_nrf52840
236      :build-dir: smp_svr
237      :goals: build
238
239#. Sign ``smp_svr`` for chain-loading by MCUboot.
240
241   .. code-block:: console
242
243      west sign -t imgtool --bin --no-hex -d build/smp_svr \
244                -B smp_svr.signed.bin -- --key mcuboot/root-rsa-2048.pem
245
246#. Flash the application to the MCUboot serial port using ``mcumgr``:
247
248   .. code-block:: console
249
250      mcumgr --conntype=serial --connstring='dev=/dev/ttyACM0,baud=115200' \
251             image upload -e smp_svr.signed.bin
252
253#. Reset the device:
254
255   .. code-block:: console
256
257      mcumgr --conntype=serial --connstring='dev=/dev/ttyACM0,baud=115200' reset
258
259You should now be able to scan for Bluetooth devices using a smartphone or
260computer. The device you just flashed will be listed with ``Zephyr`` in its
261name.
262
263.. note::
264
265   This board supports building other Zephyr applications for flashing with
266   MCUboot in this way also. Just make sure :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`
267   is set when building your application. For example, to compile blinky for
268   loading by MCUboot, use this:
269
270   .. zephyr-app-commands::
271      :app: zephyr/samples/basic/blinky
272      :board: nrf52840dongle_nrf52840
273      :build-dir: blinky
274      :goals: build
275      :gen-args: -DCONFIG_BOOTLOADER_MCUBOOT=y
276
277   You can then sign and flash it using the steps above.
278
279Option 3: Using an External Debug Probe
280---------------------------------------
281
282If you have one, you can also use an external :ref:`debug probe <debug-probes>`
283to flash and debug Zephyr applications, but you need to solder an SWD header
284onto the back side of the board.
285
286For Segger J-Link debug probes, follow the instructions in the
287:ref:`nordic_segger` page to install and configure all the necessary
288software. Further information can be found in :ref:`nordic_segger_flashing`.
289
290Locate the DTS file for the board under: boards/arm/nrf52840dongle_nrf52840.
291This file requires a small modification to use a different partition table.
292Edit the include directive to include "fstab-debugger" instead of "fstab-stock".
293
294In addition, the Kconfig file in the same directory must be modified by setting
295``BOARD_HAS_NRF5_BOOTLOADER`` to be default ``n``, otherwise the code will be
296flashed with an offset.
297
298Then build and flash applications as usual (see :ref:`build_an_application` and
299:ref:`application_run` for more details).
300
301Here is an example for the :zephyr:code-sample:`blinky` application.
302
303.. zephyr-app-commands::
304   :zephyr-app: samples/basic/blinky
305   :board: nrf52840dongle_nrf52840
306   :goals: build flash
307
308Observe the LED on the board blinking.
309
310Debugging
311=========
312
313The ``nrf52840dongle_nrf52840`` board does not have an on-board J-Link debug IC
314as some nRF5x development boards, however, instructions from the
315:ref:`nordic_segger` page also apply to this board, with the additional step
316of connecting an external debugger.
317
318Testing the LEDs and buttons on the nRF52840 Dongle
319***************************************************
320
321There are 2 samples that allow you to test that the buttons (switches) and LEDs on
322the board are working properly with Zephyr:
323
324* :zephyr:code-sample:`blinky`
325
326You can build and program the examples to make sure Zephyr is running correctly
327on your board.
328
329
330References
331**********
332
333.. target-notes::
334
335.. _nRF52840 Dongle website:
336   https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle
337.. _Nordic Semiconductor Infocenter:
338   https://infocenter.nordicsemi.com
339.. _J-Link Software and documentation pack:
340   https://www.segger.com/jlink-software.html
341.. _Nordic Semiconductor USB DFU:
342   https://infocenter.nordicsemi.com/index.jsp?topic=%2Fcom.nordic.infocenter.sdk5.v15.2.0%2Fsdk_app_serial_dfu_bootloader.html
343.. _nrfutil:
344   https://github.com/NordicSemiconductor/pc-nrfutil
345.. _MCUboot:
346   https://github.com/JuulLabs-OSS/mcuboot
347.. _mcumgr:
348   https://github.com/apache/mynewt-mcumgr-cli
349