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