1.. zephyr:board:: lora_e5_mini
2
3Overview
4********
5
6LoRa-E5 mini is a compacted-sized development board suitable for the rapid
7testing and building of small-sized LoRa device, exposing all capabilities of
8Seeed Studio LoRa-E5 STM32WLE5JC module.
9
10Hardware
11********
12
13The boards' LoRa-E5 Module packages a STM32WLE5JC SOC, a 32MHz TCXO,
14and a 32.768kHz crystal oscillator in a 28-pin SMD package.
15This STM32WLEJC SOC is powered by ARM Cortex-M4 core and integrates Semtech
16SX126X LoRa IP to support (G)FSK, BPSK, (G)MSK, and LoRa modulations.
17
18- LoRa-E5 STM32WLE5JC Module with STM32WLE5JC multiprotocol LPWAN single-core
19  32-bit microcontroller (Arm® Cortex®-M4 at 48 MHz) in 28-pin SMD package
20  featuring:
21
22  - Ultra-low-power MCU
23  - RF transceiver (150 MHz to 960 MHz frequency range) supporting LoRa®,
24    (G)FSK, (G)MSK, and BPSK modulations
25  - 256-Kbyte Flash memory and 64-Kbyte SRAM
26  - Hardware encryption AES256-bit and a True random number generator
27
28- 1 user LED
29- 2 serial communication (RX/TX) LEDs
30- 1 boot/user and 1 reset push-button
31- 32.768 kHz LSE crystal oscillator
32- 32 MHz HSE oscillator
33- Board connectors:
34
35  - USB Type-C connector
36  - +/- (battery) power input pins (3-5V)
37  - SMA-K and IPEX antenna connectors
38
39- Delivered with SMA antenna (per default IPEX connector is disconnected)
40- Flexible power-supply options: USB Type C or 3-5V battery soldered to +/- pins
41- Suitable for rapid prototyping of end nodes based on LoRaWAN, Sigfox, wM-Bus,
42  and many other proprietary protocols
43- All GPIOs led out from the LoRa-E5 STM32WLE5JC module
44- 4x M2 mounting holes
45
46More information about the board can be found at the `LoRa-E5 mini Wiki`_.
47
48More information about LoRa-E5 STM32WLE5JC Module can be found here:
49
50- `LoRa-E5 STM32WLE5JC Module Wiki`_
51- `LoRa-E5 STM32WLE5JC Module datasheet`_
52- `STM32WLE5JC datasheet`_
53- `STM32WLE5JC reference manual`_
54- `STM32WLE5JC on www.st.com`_
55
56Supported Features
57==================
58
59The Zephyr LoRa-E5 mini configuration supports the following hardware features:
60
61+-----------+------------+-------------------------------------+
62| Interface | Controller | Driver/Component                    |
63+===========+============+=====================================+
64| ADC       | on-chip    | adc                                 |
65+-----------+------------+-------------------------------------+
66| AES       | on-chip    | crypto                              |
67+-----------+------------+-------------------------------------+
68| COUNTER   | on-chip    | rtc                                 |
69+-----------+------------+-------------------------------------+
70| CLOCK     | on-chip    | reset and clock control             |
71+-----------+------------+-------------------------------------+
72| FLASH     | on-chip    | flash                               |
73+-----------+------------+-------------------------------------+
74| GPIO      | on-chip    | gpio                                |
75+-----------+------------+-------------------------------------+
76| I2C       | on-chip    | i2c                                 |
77+-----------+------------+-------------------------------------+
78| MPU       | on-chip    | arch/arm                            |
79+-----------+------------+-------------------------------------+
80| NVIC      | on-chip    | arch/arm                            |
81+-----------+------------+-------------------------------------+
82| PINMUX    | on-chip    | pinmux                              |
83+-----------+------------+-------------------------------------+
84| RADIO     | on-chip    | LoRa                                |
85+-----------+------------+-------------------------------------+
86| SPI       | on-chip    | spi                                 |
87+-----------+------------+-------------------------------------+
88| UART      | on-chip    | serial port-polling;                |
89|           |            | serial port-interrupt               |
90+-----------+------------+-------------------------------------+
91| WATCHDOG  | on-chip    | independent watchdog                |
92+-----------+------------+-------------------------------------+
93
94Other hardware features are not yet supported on this Zephyr port.
95
96The default configuration can be found in:
97
98- :zephyr_file:`boards/seeed/lora_e5_mini/lora_e5_mini_defconfig`
99- :zephyr_file:`boards/seeed/lora_e5_mini/lora_e5_mini.dts`
100
101
102Connections and IOs
103===================
104
105LoRa-E5 mini has 4 GPIO controllers. These controllers are responsible for pin
106muxing, input/output, pull-up, etc.
107
108Available pins:
109---------------
110
111.. image:: img/lora_e5_mini_pinout.jpg
112      :align: center
113      :alt: LoRa-E5 mini Pinout
114
115Default Zephyr Peripheral Mapping:
116----------------------------------
117
118- USART_1 TX  : PB6
119- USART_1 RX  : PB7
120- I2C_2_SCL   : PB15
121- I2C_2_SDA   : PA15
122- BOOT_PB     : PB13
123- LED_1       : PB5
124
125System Clock
126------------
127
128LoRa-E5 mini board System Clock could be driven by the low-power internal (MSI),
129High-speed internal (HSI) or High-speed external (HSE) oscillator, as well as
130main PLL clock. By default System clock is driven by the MSI clock at 48MHz.
131
132Programming and Debugging
133*************************
134
135Applications for the ``lora_e5_mini`` board configuration can be built the
136usual way (see :ref:`build_an_application`).
137
138In the factory the module is flashed with an DFU bootloader, an AT command
139firmware, and the read protection level 1 is enabled.
140So before you can program a Zephyr application to the module for the first time
141you have to reset the read protection to level 0.
142In case you use an st-link debugger you can use the STM32CubeProgrammer GUI to
143set the RDP option byte to ``AA``,
144or use the STM32_Programmer_CLI passing the ``--readunprotect`` command
145to perform this read protection regression.
146The RDP level 1 to RDP level 0 regression will erase the factory programmed AT
147firmware, from which seeed studio has neither released the source code nor a binary.
148Also, note that on the module the ``BOOT0`` pin of the SOC is not accessible,
149so the system bootloader will only be executed if configured in the option bytes.
150
151Flashing
152========
153
154The LoRa-E5 mini does not include a on-board debug probe.
155But the module can be debugged by connecting an external debug probe to the
1562.54mm header.
157Depending on the external probe used, ``openocd``, the ``stm32cubeprogrammer``,
158``pyocd``, ``blackmagic``, or ``jlink`` runner can be used to flash the board.
159Additional notes:
160
161- Pyocd: For STM32WL support Pyocd needs additional target information, which
162  can be installed by adding "pack" support with the following pyocd command:
163
164.. code-block:: console
165
166   $ pyocd pack --update
167   $ pyocd pack --install stm32wl
168
169Flashing an application to LoRa-E5 mini
170---------------------------------------
171
172Connect the LoRa-E5 to your host computer using the external debug probe.
173Then build and flash an application. Here is an example for the
174:zephyr:code-sample:`hello_world` application.
175
176Run a serial host program to connect with your board:
177Per default the console on ``usart1`` is available on the USB Type C connector
178via the built-in USB to UART converter.
179
180.. code-block:: console
181
182   $ picocom --baud 115200 /dev/ttyACM0
183
184Then build and flash the application.
185
186.. zephyr-app-commands::
187   :zephyr-app: samples/hello_world
188   :board: lora_e5_mini
189   :goals: build flash
190
191Debugging
192=========
193
194You can debug an application in the usual way. Here is an example for the
195:zephyr:code-sample:`blinky` application.
196
197.. zephyr-app-commands::
198   :zephyr-app: samples/basic/blinky
199   :board: lora_e5_mini
200   :maybe-skip-config:
201   :goals: debug
202
203.. _LoRa-E5 mini Wiki:
204   https://wiki.seeedstudio.com/LoRa_E5_mini/
205
206.. _LoRa-E5 STM32WLE5JC Module Wiki:
207   https://wiki.seeedstudio.com/LoRa-E5_STM32WLE5JC_Module/
208
209.. _LoRa-E5 STM32WLE5JC Module datasheet:
210    https://files.seeedstudio.com/products/317990687/res/LoRa-E5%20module%20datasheet_V1.0.pdf
211
212.. _STM32WLE5JC on www.st.com:
213   https://www.st.com/en/microcontrollers-microprocessors/stm32wle5jc.html
214
215.. _STM32WLE5JC datasheet:
216   https://www.st.com/resource/en/datasheet/stm32wle5jc.pdf
217
218.. _STM32WLE5JC reference manual:
219   https://www.st.com/resource/en/reference_manual/dm00530369-stm32wlex-advanced-armbased-32bit-mcus-with-subghz-radio-solution-stmicroelectronics.pdf
220