1.. zephyr:board:: twr_ke18f
2
3Overview
4********
5
6The TWR-KE18F is a development board for NXP Kinetis KE1xF 32-bit
7MCU-based platforms. The onboard OpenSDAv2 serial and debug adapter,
8running an open source bootloader, offers options for serial
9communication, flash programming, and run-control debugging.
10
11Hardware
12********
13
14- MKE18F512VLL16 MCU (up to 168 MHz, 512 KB flash memory, 64 KB RAM,
15  and 100 Low profile Quad Flat Package (LQFP))
16- 3.3 V or 5 V MCU operation
17- 6-axis FXOS8700CQ digital accelerometer and magnetometer
18- RGB LED
19- Four user LEDs
20- Two user push-buttons
21- Potentiometer
22- Thermistor
23- Infrared port (IrDA)
24- CAN pin header
25- Flex I/O pin header
26
27For more information about the KE1xF SoC and the TWR-KE18F board, see
28these NXP reference documents:
29
30- `KE1xF Website`_
31- `KE1xF Datasheet`_
32- `KE1xF Reference Manual`_
33- `TWR-KE18F Website`_
34- `TWR-KE18F User Guide`_
35- `TWR-KE18F Schematics`_
36
37Supported Features
38==================
39
40The twr_ke18f board configuration supports the following hardware
41features:
42
43+-----------+------------+-------------------------------------+
44| Interface | Controller | Driver/Component                    |
45+===========+============+=====================================+
46| NVIC      | on-chip    | nested vector interrupt controller  |
47+-----------+------------+-------------------------------------+
48| SYSTICK   | on-chip    | systick                             |
49+-----------+------------+-------------------------------------+
50| PINMUX    | on-chip    | pinmux                              |
51+-----------+------------+-------------------------------------+
52| GPIO      | on-chip    | gpio                                |
53+-----------+------------+-------------------------------------+
54| UART      | on-chip    | serial port-polling;                |
55|           |            | serial port-interrupt               |
56+-----------+------------+-------------------------------------+
57| FLASH     | on-chip    | soc flash                           |
58+-----------+------------+-------------------------------------+
59| RTC       | on-chip    | rtc                                 |
60+-----------+------------+-------------------------------------+
61| I2C(M)    | on-chip    | i2c                                 |
62+-----------+------------+-------------------------------------+
63| SENSOR    | off-chip   | fxos8700 polling;                   |
64|           |            | trigger supported with H/W mods     |
65|           |            | explained below;                    |
66+-----------+------------+-------------------------------------+
67| SPI(M)    | on-chip    | spi                                 |
68+-----------+------------+-------------------------------------+
69| ADC       | on-chip    | adc                                 |
70+-----------+------------+-------------------------------------+
71| CAN       | on-chip    | can                                 |
72+-----------+------------+-------------------------------------+
73| WDT       | on-chip    | watchdog                            |
74+-----------+------------+-------------------------------------+
75| PWM       | on-chip    | pwm                                 |
76+-----------+------------+-------------------------------------+
77| DAC       | on-chip    | dac                                 |
78+-----------+------------+-------------------------------------+
79| ACMP      | on-chip    | sensor                              |
80+-----------+------------+-------------------------------------+
81
82The default configuration can be found in the defconfig file:
83:zephyr_file:`boards/nxp/twr_ke18f/twr_ke18f_defconfig`.
84
85Other hardware features are not currently supported by the port.
86
87System Clock
88============
89
90The KE18 SoC is configured to use the 8 MHz external oscillator on the
91board with the on-chip PLL to generate a 120 MHz system clock.
92
93Serial Port
94===========
95
96The KE18 SoC has three UARTs. UART0 is configured for the console. The
97remaining UARTs are not used.
98
99Accelerometer and magnetometer
100==============================
101
102The TWR-KE18F board by default only supports polling the FXOS8700
103accelerometer and magnetometer for sensor values
104(``CONFIG_FXOS8700_TRIGGER_NONE=y``).
105
106In order to support FXOS8700 triggers (interrupts) the 0 ohm resistors
107``R47`` and ``R57`` must be mounted on the TWR-KE18F board. The
108devicetree must also be modified to describe the FXOS8700 interrupt
109GPIOs:
110
111.. code-block:: devicetree
112
113  /dts-v1/;
114
115  &fxos8700 {
116          int1-gpios = <&gpioa 14 0>;
117          int2-gpios = <&gpioc 17 0>;
118  };
119
120Finally, a trigger option must be enabled in Kconfig (either
121``FXOS8700_TRIGGER_GLOBAL_THREAD=y`` or
122``FXOS8700_TRIGGER_OWN_THREAD=y``).
123
124Programming and Debugging
125*************************
126
127Build and flash applications as usual (see :ref:`build_an_application` and
128:ref:`application_run` for more details).
129
130Configuring a Debug Probe
131=========================
132
133A debug probe is used for both flashing and debugging the board. This board is
134configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`.
135
136Early versions of this board have an outdated version of the OpenSDA bootloader
137and require an update. Please see the `DAPLink Bootloader Update`_ page for
138instructions to update from the CMSIS-DAP bootloader to the DAPLink bootloader.
139
140Option 1: :ref:`opensda-daplink-onboard-debug-probe` (Recommended)
141------------------------------------------------------------------
142
143Install the :ref:`pyocd-debug-host-tools` and make sure they are in your search
144path.
145
146Follow the instructions in :ref:`opensda-daplink-onboard-debug-probe` to program
147the `OpenSDA DAPLink TWR-KE18F Firmware`_.
148
149Option 2: :ref:`opensda-jlink-onboard-debug-probe`
150--------------------------------------------------
151
152Install the :ref:`jlink-debug-host-tools` and make sure they are in your search
153path.
154
155Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program
156the `OpenSDA J-Link Firmware for TWR-KE18F`_.
157
158Add the arguments ``-DBOARD_FLASH_RUNNER=jlink`` and
159``-DBOARD_DEBUG_RUNNER=jlink`` when you invoke ``west build`` to override the
160default runner from pyOCD to J-Link:
161
162.. zephyr-app-commands::
163   :zephyr-app: samples/hello_world
164   :board: twr_ke18f
165   :gen-args: -DBOARD_FLASH_RUNNER=jlink -DBOARD_DEBUG_RUNNER=jlink
166   :goals: build
167
168Configuring a Console
169=====================
170
171Regardless of your choice in debug probe, we will use the OpenSDA
172microcontroller as a usb-to-serial adapter for the serial console.
173
174Connect a USB cable from your PC to J2.
175
176Use the following settings with your serial terminal of choice (minicom, putty,
177etc.):
178
179- Speed: 115200
180- Data: 8 bits
181- Parity: None
182- Stop bits: 1
183
184Flashing
185========
186
187Here is an example for the :zephyr:code-sample:`hello_world` application.
188
189.. zephyr-app-commands::
190   :zephyr-app: samples/hello_world
191   :board: twr_ke18f
192   :goals: flash
193
194Open a serial terminal, reset the board (press the SW1 button), and you should
195see the following message in the terminal:
196
197.. code-block:: console
198
199   ***** Booting Zephyr OS v1.14.0-xxx-gxxxxxxxxxxxx *****
200   Hello World! twr_ke18f
201
202Debugging
203=========
204
205Here is an example for the :zephyr:code-sample:`hello_world` application.
206
207.. zephyr-app-commands::
208   :zephyr-app: samples/hello_world
209   :board: twr_ke18f
210   :goals: debug
211
212Open a serial terminal, step through the application in your debugger, and you
213should see the following message in the terminal:
214
215.. code-block:: console
216
217   ***** Booting Zephyr OS v1.14.0-xxx-gxxxxxxxxxxxx *****
218   Hello World! twr_ke18f
219
220.. _TWR-KE18F Website:
221   https://www.nxp.com/TWR-KE18F
222
223.. _TWR-KE18F User Guide:
224   https://www.nxp.com/docs/en/user-guide/TWRKE18FUG.pdf
225
226.. _TWR-KE18F Schematics:
227   https://www.nxp.com/webapp/Download?colCode=TWR-KE18F-SCH-DESIGNFILES
228
229.. _KE1xF Website:
230   https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/kinetis-cortex-m-mcus/e-series5v-robustm0-plus-m4/kinetis-ke1xf-168mhz-performance-with-can-5v-microcontrollers-based-on-arm-cortex-m4:KE1xF
231
232.. _KE1xF Datasheet:
233   https://www.nxp.com/docs/en/data-sheet/KE1xFP100M168SF0.pdf
234
235.. _KE1xF Reference Manual:
236   https://www.nxp.com/docs/en/reference-manual/KE1xFP100M168SF0RM.pdf
237
238.. _DAPLink Bootloader Update:
239   https://os.mbed.com/blog/entry/DAPLink-bootloader-update/
240
241.. _OpenSDA DAPLink TWR-KE18F Firmware:
242   https://www.nxp.com/support/developer-resources/run-time-software/kinetis-developer-resources/ides-for-kinetis-mcus/opensda-serial-and-debug-adapter:OPENSDA#TWR-KE18F
243
244.. _OpenSDA J-Link Firmware for TWR-KE18F:
245   https://www.segger.com/downloads/jlink/OpenSDA_TWR-KE18F
246