1.. _xiao_ble:
2
3XIAO BLE (Sense)
4################
5
6Overview
7********
8
9The Seeed XIAO BLE (Sense) is a tiny (21 mm x 17.5 mm) Nordic Semiconductor
10nRF52840 ARM Cortex-M4F development board with onboard LEDs, USB port, QSPI
11flash, battery charger, and range of I/O broken out into 14 pins.
12
13.. figure:: img/xiao_ble.jpg
14     :align: center
15     :alt: XIAO BLE
16
17Hardware
18********
19
20- Nordic nRF52840 Cortex-M4F processor at 64MHz
21- 2MB QSPI Flash
22- RGB LED
23- USB Type-C Connector, nRF52840 acting as USB device
24- Battery charger BQ25101
25- Reset button
26- Bluetooth antenna
27- LSM6DS3TR-C 6D IMU (3D accelerometer and 3D gyroscope) (XIAO BLE Sense only)
28- PDM microphone (XIAO BLE Sense only)
29
30Supported Features
31==================
32
33The xiao_ble board configuration supports the following hardware features:
34
35+-----------+------------+----------------------+
36| Interface | Controller | Driver/Component     |
37+===========+============+======================+
38| ADC       | on-chip    | adc                  |
39+-----------+------------+----------------------+
40| CLOCK     | on-chip    | clock_control        |
41+-----------+------------+----------------------+
42| FLASH     | on-chip    | flash, QSPI flash    |
43+-----------+------------+----------------------+
44| GPIO      | on-chip    | gpio                 |
45+-----------+------------+----------------------+
46| I2C(M)    | on-chip    | i2c                  |
47+-----------+------------+----------------------+
48| MPU       | on-chip    | arch/arm             |
49+-----------+------------+----------------------+
50| NVIC      | on-chip    | arch/arm             |
51+-----------+------------+----------------------+
52| PWM       | on-chip    | pwm                  |
53+-----------+------------+----------------------+
54| RADIO     | on-chip    | Bluetooth,           |
55|           |            | ieee802154           |
56+-----------+------------+----------------------+
57| RTC       | on-chip    | system clock         |
58+-----------+------------+----------------------+
59| SPI(M/S)  | on-chip    | spi                  |
60+-----------+------------+----------------------+
61| UART      | on-chip    | serial               |
62+-----------+------------+----------------------+
63| USB       | on-chip    | usb                  |
64+-----------+------------+----------------------+
65| WDT       | on-chip    | watchdog             |
66+-----------+------------+----------------------+
67
68Other hardware features have not been enabled yet for this board.
69
70Connections and IOs
71===================
72
73The `XIAO BLE wiki`_ has detailed information about the board including
74`pinouts`_ and the `schematic`_.
75
76LED
77---
78
79* LED1 (red) = P0.26
80* LED2 (green) = P0.30
81* LED3 (blue) = P0.06
82
83Programming and Debugging
84*************************
85
86The XIAO BLE ships with the `Adafruit nRF52 Bootloader`_ which supports flashing
87using `UF2`_. Doing so allows easy flashing of new images, but does not support
88debugging the device. For debugging please use `External Debugger`_.
89
90UF2 Flashing
91============
92
93To enter the bootloader, connect the USB port of the XIAO BLE to your host, and
94double tap the reset botton to the left of the USB connector. A mass storage
95device named `XIAO BLE` should appear on the host. Using the command line, or
96your file manager copy the `zephyr/zephyr.uf2` file from your build to the base
97of the `XIAO BLE` mass storage device. The XIAO BLE will automatically reset
98and launch the newly flashed application.
99
100External Debugger
101=================
102
103In order to support debugging the device, instead of using the bootloader, you
104can use an :ref:`External Debug Probe <debug-probes>`. To flash and debug Zephyr
105applications you need to use `Seeeduino XIAO Expansion Board`_ or solder an SWD
106header onto the back side of the board.
107
108For Segger J-Link debug probes, follow the instructions in the
109:ref:`jlink-external-debug-probe` page to install and configure all the
110necessary software.
111
112Flashing
113--------
114
115Follow the instructions in the :ref:`jlink-external-debug-probe` page to install
116and configure all the necessary software. Then build and flash applications as
117usual (see :ref:`build_an_application` and :ref:`application_run` for more
118details).
119
120Here is an example for the :ref:`hello_world` application.
121
122First, run your favorite terminal program to listen for output.
123
124.. code-block:: console
125
126   $ minicom -D <tty_device> -b 115200
127
128Replace :code:`<tty_device>` with the port where the board XIAO BLE
129can be found. For example, under Linux, :code:`/dev/ttyACM0`.
130
131Then build and flash the application in the usual way. Just add
132``CONFIG_BOOT_DELAY=5000`` to the configuration, so that USB CDC ACM is
133initialized before any text is printed, as below:
134
135.. tabs::
136
137   .. group-tab:: XIAO BLE
138
139      .. zephyr-app-commands::
140         :zephyr-app: samples/hello_world
141         :board: xiao_ble
142         :goals: build flash
143         :gen-args: -DCONFIG_BOOT_DELAY=5000
144
145   .. group-tab:: XIAO BLE Sense
146
147      .. zephyr-app-commands::
148         :zephyr-app: samples/hello_world
149         :board: xiao_ble_sense
150         :goals: build flash
151         :gen-args: -DCONFIG_BOOT_DELAY=5000
152
153Debugging
154---------
155
156Refer to the :ref:`jlink-external-debug-probe` page to learn about debugging
157boards with a Segger IC.
158
159Testing the LEDs in the XIAO BLE (Sense)
160****************************************
161
162There is a sample that allows to test that LEDs on the board are working
163properly with Zephyr:
164
165.. tabs::
166
167   .. group-tab:: XIAO BLE
168
169      .. zephyr-app-commands::
170         :zephyr-app: samples/basic/blinky
171         :board: xiao_ble
172         :goals: build flash
173
174   .. group-tab:: XIAO BLE Sense
175
176      .. zephyr-app-commands::
177         :zephyr-app: samples/basic/blinky
178         :board: xiao_ble_sense
179         :goals: build flash
180
181You can build and flash the examples to make sure Zephyr is running correctly on
182your board. The LED definitions can be found in
183:zephyr_file:`boards/arm/xiao_ble/xiao_ble_common.dtsi`.
184
185Testing shell over USB in the XIAO BLE (Sense)
186**********************************************
187
188There is a sample that allows to test shell interface over USB CDC ACM interface
189with Zephyr:
190
191.. tabs::
192
193   .. group-tab:: XIAO BLE
194
195      .. zephyr-app-commands::
196         :zephyr-app: samples/subsys/shell/shell_module
197         :board: xiao_ble
198         :goals: build flash
199
200   .. group-tab:: XIAO BLE Sense
201
202      .. zephyr-app-commands::
203         :zephyr-app: samples/subsys/shell/shell_module
204         :board: xiao_ble_sense
205         :goals: build flash
206
207References
208**********
209
210.. target-notes::
211
212.. _XIAO BLE wiki: https://wiki.seeedstudio.com/XIAO_BLE/
213.. _pinouts: https://wiki.seeedstudio.com/XIAO_BLE/#hardware-overview
214.. _schematic: https://wiki.seeedstudio.com/XIAO_BLE/#resources
215.. _Seeeduino XIAO Expansion Board: https://wiki.seeedstudio.com/Seeeduino-XIAO-Expansion-Board/
216.. _Adafruit nRF52 Bootloader: https://github.com/adafruit/Adafruit_nRF52_Bootloader
217.. _UF2: https://github.com/microsoft/uf2
218