1.. _nrf9131ek_nrf9131:
2
3nRF9131 EK
4##########
5
6Overview
7********
8
9The nRF9131 EK (PCA10165) is a single-board evaluation kit for the nRF9131 SiP
10for DECT NR+ and LTE-M/NB-IoT with GNSS.
11The ``nrf9131ek/nrf9131`` board configuration provides support for the Nordic Semiconductor nRF9131 ARM
12Cortex-M33F CPU with ARMv8-M Security Extension and the following devices:
13
14* :abbr:`ADC (Analog to Digital Converter)`
15* CLOCK
16* FLASH
17* :abbr:`GPIO (General Purpose Input Output)`
18* :abbr:`I2C (Inter-Integrated Circuit)`
19* :abbr:`MPU (Memory Protection Unit)`
20* :abbr:`NVIC (Nested Vectored Interrupt Controller)`
21* :abbr:`PWM (Pulse Width Modulation)`
22* :abbr:`RTC (nRF RTC System Clock)`
23* Segger RTT (RTT Console)
24* :abbr:`SPI (Serial Peripheral Interface)`
25* :abbr:`UARTE (Universal asynchronous receiver-transmitter with EasyDMA)`
26* :abbr:`WDT (Watchdog Timer)`
27* :abbr:`IDAU (Implementation Defined Attribution Unit)`
28
29.. figure:: img/nrf9131ek_nrf9131.webp
30     :align: center
31     :alt: nRF9131 EK
32
33     nRF9131 EK (Credit: Nordic Semiconductor)
34
35The `Nordic Semiconductor TechDocs`_ will soon
36contain the processor's information and the datasheet.
37
38
39Hardware
40********
41
42nRF9131 EK has two external oscillators. The frequency of
43the slow clock is 32.768 kHz. The frequency of the main clock
44is 32 MHz.
45
46Supported Features
47==================
48
49The ``nrf9131ek/nrf9131`` board configuration supports the following
50hardware features:
51
52+-----------+------------+----------------------+
53| Interface | Controller | Driver/Component     |
54+===========+============+======================+
55| ADC       | on-chip    | adc                  |
56+-----------+------------+----------------------+
57| CLOCK     | on-chip    | clock_control        |
58+-----------+------------+----------------------+
59| FLASH     | on-chip    | flash                |
60+-----------+------------+----------------------+
61| GPIO      | on-chip    | gpio                 |
62+-----------+------------+----------------------+
63| I2C(M)    | on-chip    | i2c                  |
64+-----------+------------+----------------------+
65| MPU       | on-chip    | arch/arm             |
66+-----------+------------+----------------------+
67| NVIC      | on-chip    | arch/arm             |
68+-----------+------------+----------------------+
69| PWM       | on-chip    | pwm                  |
70+-----------+------------+----------------------+
71| RTC       | on-chip    | system clock         |
72+-----------+------------+----------------------+
73| RTT       | Segger     | console              |
74+-----------+------------+----------------------+
75| SPI(M/S)  | on-chip    | spi                  |
76+-----------+------------+----------------------+
77| SPU       | on-chip    | system protection    |
78+-----------+------------+----------------------+
79| UARTE     | on-chip    | serial               |
80+-----------+------------+----------------------+
81| WDT       | on-chip    | watchdog             |
82+-----------+------------+----------------------+
83
84Connections and IOs
85===================
86
87LED
88---
89
90* LED (red) = P0.29
91* LED (green) = P0.30
92* LED (blue) = P0.31
93
94Push buttons and Switches
95-------------------------
96
97* BUTTON = P0.28
98* RESET
99
100Security components
101===================
102
103- Implementation Defined Attribution Unit (`IDAU`_).  The IDAU is implemented
104  with the System Protection Unit and is used to define secure and non-secure
105  memory maps.  By default, all of the memory space  (Flash, SRAM, and
106  peripheral address space) is defined to be secure accessible only.
107- Secure boot.
108
109
110Programming and Debugging
111*************************
112
113``nrf9131ek/nrf9131`` supports the Armv8m Security Extension, and by default boots
114in the Secure state.
115
116Building Secure/Non-Secure Zephyr applications with Arm |reg| TrustZone |reg|
117=============================================================================
118
119Applications on the nRF9131 may contain a Secure and a Non-Secure firmware
120image. The Secure image can be built using either Zephyr or
121`Trusted Firmware M`_ (TF-M). Non-Secure firmware images are always built
122using Zephyr. The two alternatives are described below.
123
124.. note::
125
126   By default the Secure image for nRF9131 is built using TF-M.
127
128Building the Secure firmware using Zephyr
129-----------------------------------------
130
131The process requires the following steps:
132
1331. Build the Secure Zephyr application using ``-DBOARD=nrf9131ek/nrf9131`` and
134   ``CONFIG_TRUSTED_EXECUTION_SECURE=y`` in the application project configuration file.
1352. Build the Non-Secure Zephyr application using ``-DBOARD=nrf9131ek/nrf9131/ns``.
1363. Merge the two binaries together.
137
138Building the Secure firmware with TF-M
139--------------------------------------
140
141The process to build the Secure firmware image using TF-M and the Non-Secure
142firmware image using Zephyr requires the following action:
143
1441. Build the Non-Secure Zephyr application
145   using ``-DBOARD=nrf9131ek/nrf9131/ns``.
146   To invoke the building of TF-M the Zephyr build system requires the
147   Kconfig option ``BUILD_WITH_TFM`` to be enabled, which is done by
148   default when building Zephyr as a Non-Secure application.
149   The Zephyr build system will perform the following steps automatically:
150
151      * Build the Non-Secure firmware image as a regular Zephyr application
152      * Build a TF-M (secure) firmware image
153      * Merge the output binaries together
154      * Optionally build a bootloader image (MCUboot)
155
156.. note::
157
158   Depending on the TF-M configuration, an application DTS overlay may be
159   required, to adjust the Non-Secure image Flash and SRAM starting address
160   and sizes.
161
162When building a Secure/Non-Secure application, the Secure application will
163have to set the IDAU (SPU) configuration to allow Non-Secure access to all
164CPU resources utilized by the Non-Secure application firmware. SPU
165configuration shall take place before jumping to the Non-Secure application.
166
167Building a Secure only application
168==================================
169
170Build the Zephyr app in the usual way (see :ref:`build_an_application`
171and :ref:`application_run`), using ``-DBOARD=nrf9131ek/nrf9131``.
172
173
174Flashing
175========
176
177Follow the instructions in the :ref:`nordic_segger` page to install
178and configure all the necessary software. Further information can be
179found in :ref:`nordic_segger_flashing`. Then build and flash
180applications as usual (see :ref:`build_an_application` and
181:ref:`application_run` for more details).
182
183Here is an example for the :zephyr:code-sample:`hello_world` application.
184
185First, run your favorite terminal program to listen for output.
186
187.. code-block:: console
188
189   $ minicom -D <tty_device> -b 115200
190
191Replace :code:`<tty_device>` with the port where the nRF9131 EK
192can be found. For example, under Linux, :code:`/dev/ttyACM0`.
193
194Then build and flash the application in the usual way.
195
196.. zephyr-app-commands::
197   :zephyr-app: samples/hello_world
198   :board: nrf9131ek/nrf9131
199   :goals: build flash
200
201Debugging
202=========
203
204Refer to the :ref:`nordic_segger` page to learn about debugging Nordic boards with a
205Segger IC.
206
207
208Testing the LEDs and buttons in the nRF9131 EK
209**********************************************
210
211There are 2 samples that allow you to test that the button and LED on
212the board are working properly with Zephyr:
213
214* :zephyr:code-sample:`blinky`
215* :zephyr:code-sample:`button`
216
217You can build and flash the examples to make sure Zephyr is running correctly on
218your board. The button and LED definitions can be found in
219:zephyr_file:`boards/nordic/nrf9131ek/nrf9131ek_nrf9131_common.dtsi`.
220
221References
222**********
223
224.. target-notes::
225
226.. _IDAU:
227   https://developer.arm.com/docs/100690/latest/attribution-units-sau-and-idau
228.. _Nordic Semiconductor TechDocs: https://docs.nordicsemi.com/
229.. _Trusted Firmware M: https://www.trustedfirmware.org/projects/tf-m/
230