1.. zephyr:board:: arduino_nano_33_ble
2
3Overview
4********
5
6The Arduino Nano 33 BLE is designed around Nordic Semiconductor's
7nRF52840 ARM Cortex-M4F CPU. Arduino sells 2 variants of the board, the
8plain `BLE`_ type and the `BLE Sense`_ type. The "Sense" variant is distinguished by
9the inclusion of more sensors, but otherwise both variants are the same.
10
11Hardware
12********
13
14Supported Features
15==================
16
17.. zephyr:board-supported-hw::
18
19Connections and IOs
20===================
21
22The `schematic`_ will tell you everything
23you need to know about the pins.
24
25The I2C pull-ups are enabled by setting pin P1.00 high. This is automatically
26done at system init. The pin is specified in the ``zephyr,user`` Devicetree node
27as ``pull-up-gpios``.
28
29Programming and Debugging
30*************************
31
32This board requires the Arduino variant of bossac. You will not
33be able to flash with the bossac included with the zephyr-sdk, or
34using shumatech's mainline build.
35
36You can get this variant of bossac with one of two ways:
37
38#. Building the binary from the `Arduino source tree <https://github.com/arduino/BOSSA/tree/nrf>`_
39#. Downloading the Arduino IDE
40
41   #. Install the board support package within the IDE
42   #. Change your IDE preferences to provide verbose logging
43   #. Build and flash a sample application, and read the logs to figure out where Arduino stored bossac.
44   #. In most Linux based systems the path is ``$HOME/.arduino15/packages/arduino/tools/bossac/1.9.1-arduino2/bossac``.
45
46Once you have a path to bossac, you can pass it as an argument to west:
47
48.. code-block:: bash
49
50   west flash --bossac="<path to the arduino version of bossac>"
51
52For example
53
54.. code-block:: bash
55
56    west flash --bossac=$HOME/.arduino15/packages/arduino/tools/bossac/1.9.1-arduino2/bossac
57
58On Windows you need to use the :file:`bossac.exe` from the `Arduino IDE`_
59You will also need to specify the COM port using the --bossac-port argument:
60
61.. code-block:: bash
62
63    west flash --bossac=%USERPROFILE%\AppData\Local\Arduino15\packages\arduino\tools\bossac\1.9.1-arduino2\bossac.exe --bossac-port="COMx"
64
65Flashing
66========
67
68Attach the board to your computer using the USB cable, and then
69
70   .. zephyr-app-commands::
71      :zephyr-app: samples/basic/blinky
72      :board: arduino_nano_33_ble
73      :goals: build
74      :compact:
75
76Double-tap the RESET button on your board. Your board should disconnect, reconnect,
77and there should be a pulsing orange LED near the USB port.
78
79Then, you can flash the image using the above script.
80
81You should see the red LED blink.
82
83Debugging
84=========
85
86You can debug an application on the board with a debug adapter that supports
87CMSIS-DAP. This board has the SWD connector for debugging but exposes it as
88a test pad pattern (not a connector) on the back side of the PCB. So, It needs
89bit of difficult soldering. At a minimum, SWDIO and SWCLK need soldering (As
90shown in the picture). GND, 3.3V, and RESET are also available in the DIP
91connector, therefore it may be easier to connect using the DIP connector
92instead of soldering to them.
93
94.. image:: img/nano_33_ble_swd.jpg
95     :align: center
96     :alt: Nano 33 BLE SWD connecting
97
98After connecting the debug adapter, you can debug it the usual way.
99Type the following command will start debugging.
100
101.. zephyr-app-commands::
102   :zephyr-app: samples/basic/blinky
103   :board: arduino_nano_33_ble
104   :maybe-skip-config:
105   :goals: debug
106
107Debugging with TRACE32 (GDB Front-End)
108======================================
109
110Lauterbach provides `GDB Debug version TRACE32 for Arduino Nano 33 BLE`_.
111That license ties to Arduino Nano 33 BLE hardware serial number,
112it also works with the ZephyrRTOS.
113
114Follow the instruction of the tutorial for Arduino
115`Lauterbach TRACE32 GDB Front-End Debugger for Nano 33 BLE`_
116to install the TRACE32.
117
118After installing the TRACE32, You should set the environmental variable ``T32_DIR``.
119If you installed TRACE32 into the home directory, run the following command.
120(It is a good idea to put in the login script.)
121
122.. code-block:: bash
123
124    export T32_DIR="~/T32Arduino"
125
126
127The TRACE32 is `TRACE32 as GDB Front-End`_ version.
128Required to run the GDB server before launching TRACE32 with the following command.
129
130.. zephyr-app-commands::
131   :zephyr-app: samples/basic/blinky
132   :board: arduino_nano_33_ble
133   :goals: debugserver
134   :compact:
135
136Execute the following command after launching the GDB server to run the TRACE32
137and connect the GDB server.
138
139.. code-block:: bash
140
141    west debug --runner=trace32 -- gdbRemote=:3333
142
143The TRACE32 script handles arguments after the ``--`` sign.
144You can set the following options.
145
146========== ========== ==================================================================
147      Name Required?  Description
148---------- ---------- ------------------------------------------------------------------
149 gdbRemote  Required  | Set the GDB server address or device file of the serial port.
150                      | It can take <hostname>:<port> or <devicename>.
151                      | e.g.) ``gdbRemote=localhost:3333``, ``gdbRemote=/dev/ttyACM0``
152  terminal  Optional  | Set the device file of the serial port connected to the target console.
153                      | e.g.) ``terminal=/dev/ttyACM1``
154userScript  Optional  | Set user script that runs after system script execute done.
155                      | e.g.) ``userScript="./user.cmm"``
156========== ========== ==================================================================
157
158References
159**********
160
161.. target-notes::
162
163.. _BLE:
164    https://store.arduino.cc/products/arduino-nano-33-ble
165
166.. _BLE SENSE:
167    https://store.arduino.cc/products/arduino-nano-33-ble-sense
168
169.. _pinouts:
170    https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/pinouts
171
172.. _schematic:
173    https://content.arduino.cc/assets/NANO33BLE_V2.0_sch.pdf
174
175.. _GDB Debug version TRACE32 for Arduino Nano 33 BLE:
176    https://www.lauterbach.com/frames.html?register_arduino.php
177
178.. _Lauterbach TRACE32 GDB Front-End Debugger for Nano 33 BLE:
179    https://docs.arduino.cc/tutorials/nano-33-ble-sense/trace-32
180
181.. _TRACE32 as GDB Front-End:
182    https://www2.lauterbach.com/pdf/frontend_gdb.pdf
183
184.. _Arduino IDE:
185	https://www.arduino.cc/en/Main/Software
186