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