1.. zephyr:board:: mr_canhubk3
2
3Overview
4********
5
6`NXP MR-CANHUBK3`_ is an evaluation board for mobile robotics applications such
7as autonomous mobile robots (AMR) and automated guided vehicles (AGV). It
8features an `NXP S32K344`_ general-purpose automotive microcontroller based on
9an Arm Cortex-M7 core (Lock-Step).
10
11Hardware
12********
13
14- NXP S32K344
15    - Arm Cortex-M7 (Lock-Step), 160 MHz (Max.)
16    - 4 MB of program flash, with ECC
17    - 320 KB RAM, with ECC
18    - Ethernet 100 Mbps, CAN FD, FlexIO, QSPI
19    - 12-bit 1 Msps ADC, 16-bit eMIOS timer
20
21- `NXP FS26 Safety System Basis Chip`_
22
23- Interfaces:
24    - Console UART
25    - 6x CAN FD
26    - 100Base-T1 Ethernet
27    - JST-GH connectors and I/O headers for I2C, SPI, GPIO,
28      PWM, etc.
29
30More information about the hardware and design resources can be found at
31`NXP MR-CANHUBK3`_ website.
32
33Supported Features
34==================
35
36The ``mr_canhubk3`` board configuration supports the following hardware features:
37
38============  ==========  ================================
39Interface     Controller  Driver/Component
40============  ==========  ================================
41SIUL2         on-chip     | pinctrl
42                          | gpio
43                          | external interrupt controller
44WKPU          on-chip     interrupt controller
45LPUART        on-chip     serial
46QSPI          on-chip     flash
47FLEXCAN       on-chip     can
48LPI2C         on-chip     i2c
49ADC SAR       on-chip     adc
50LPSPI         on-chip     spi
51WDT           FS26 SBC    watchdog
52SWT           on-chip     watchdog
53EMAC          on-chip     ethernet
54                          mdio
55eMIOS         on-chip     pwm
56EDMA          on-chip     dma
57FLEXIO PWM    on-chip     pwm
58STM           on-chip     counter
59============  ==========  ================================
60
61The default configuration can be found in the Kconfig file
62:zephyr_file:`boards/nxp/mr_canhubk3/mr_canhubk3_defconfig`.
63
64Connections and IOs
65===================
66
67Each GPIO port is divided into two banks: low bank, from pin 0 to 15, and high
68bank, from pin 16 to 31. For example, ``PTA2`` is the pin 2 of ``gpioa_l`` (low
69bank), and ``PTA20`` is the pin 4 of ``gpioa_h`` (high bank).
70
71The GPIO controller provides the option to route external input pad interrupts
72to either the SIUL2 EIRQ or WKPU interrupt controllers, as supported by the SoC.
73By default, GPIO interrupts are routed to SIUL2 EIRQ interrupt controller,
74unless they are explicity configured to be directed to the WKPU interrupt
75controller, as outlined in :zephyr_file:`dts/bindings/gpio/nxp,s32-gpio.yaml`.
76
77To find information about which GPIOs are compatible with each interrupt
78controller, refer to the device reference manual.
79
80.. note::
81
82   It is important to highlight that the current board configuration lacks
83   support for wake-up events and power-management features. WKPU functionality
84   is restricted solely to serving as an interrupt controller.
85
86LEDs
87----
88
89The MR-CANHUBK3 board has one user RGB LED:
90
91=======================  =====  =====  ===================================
92Devicetree node          Color  Pin    Pin Functions
93=======================  =====  =====  ===================================
94led0 / user_led1_red     Red    PTE14  FXIO D7 / EMIOS0 CH19
95led1 / user_led1_green   Green  PTA27  FXIO D5 / EMIOS1 CH10 / EMIOS2 CH10
96led2 / user_led1_blue    Blue   PTE12  FXIO D8 / EMIOS1 CH5
97=======================  =====  =====  ===================================
98
99In addition to the RGB LED, the MR-CANHUBK3 board has six red LEDs, each located
100next to one of the CAN connectors:
101
102=======================  =====  =====  ===================================
103Devicetree node          Color  Pin    Pin Functions
104=======================  =====  =====  ===================================
105can_led0                 Red    PTC18  FXIO D6 / FXIO D12 / EMIOS2 CH12
106can_led1                 Red    PTE5   FXIO D7 / EMIOS1 CH5 / EMIOS0 CH 19
107can_led2                 Red    PTD20  EMIOS1 CH17 / EMIOS2 CH0
108can_led3                 Red    PTB24  FXIO D5 / EMIOS1 CH20 / EMIOS2 CH20
109can_led4                 Red    PTB26  FXIO D7 / EMIOS1 CH22 / EMIOS2 CH22
110can_led5                 Red    PTD31  FXIO D6 / EMIOS2 CH22
111=======================  =====  =====  ===================================
112
113The user can control the LEDs in any way. An output of ``0`` illuminates the LED.
114
115Buttons
116-------
117
118The MR-CANHUBK3 board has two user buttons:
119
120=======================  =====  =====  ==============
121Devicetree node          Label  Pin    Pin Functions
122=======================  =====  =====  ==============
123sw0 / user_button_1      SW1    PTD15  EIRQ31
124sw0 / user_button_2      SW2    PTA25  EIRQ5 / WKPU34
125=======================  =====  =====  ==============
126
127System Clock
128============
129
130The Arm Cortex-M7 (Lock-Step) are configured to run at 160 MHz.
131
132Serial Console
133==============
134
135By default, the serial console is provided through ``lpuart2`` on the 7-pin
136DCD-LZ debug connector ``P6``.
137
138=========  =====  ============
139Connector  Pin    Pin Function
140=========  =====  ============
141P6.2       PTA9   LPUART2_TX
142P6.3       PTA8   LPUART2_RX
143=========  =====  ============
144
145CAN
146===
147
148CAN is provided through FLEXCAN interface with 6 instances.
149
150===============  =======  ===============  =============
151Devicetree node  Pin      Pin Function     Bus Connector
152===============  =======  ===============  =============
153flexcan0         | PTA6   | PTA6_CAN0_RX   P12/P13
154                 | PTA7   | PTA7_CAN0_TX
155flexcan1         | PTC9   | PTC9_CAN0_RX   P14/P15
156                 | PTC8   | PTC8_CAN0_TX
157flexcan2         | PTE25  | PTE25_CAN0_RX  P16/P17
158                 | PTE24  | PTE24_CAN0_TX
159flexcan3         | PTC29  | PTC29_CAN0_RX  P18/019
160                 | PTC28  | PTC28_CAN0_TX
161flexcan4         | PTC31  | PTC31_CAN0_RX  P20/P21
162                 | PTC30  | PTC30_CAN0_TX
163flexcan5         | PTC11  | PTC11_CAN0_RX  P22/P23
164                 | PTC10  | PTC10_CAN0_TX
165===============  =======  ===============  =============
166
167.. note::
168   There is limitation by HAL SDK, so CAN only has support maximum 64 message buffers (MBs)
169   and support maximum 32 message buffers for concurrent active instances with 8 bytes
170   payload. We need to pay attention to configuration options:
171
172   1. :kconfig:option:`CONFIG_CAN_MAX_MB` must be less or equal than the
173      maximum number of message buffers that is according to the table below.
174
175   2. :kconfig:option:`CONFIG_CAN_MAX_FILTER` must be less or equal than
176      :kconfig:option:`CONFIG_CAN_MAX_MB`.
177
178===============  ==========  ================  ================
179Devicetree node  Payload     Hardware support  Software support
180===============  ==========  ================  ================
181flexcan0         | 8 bytes   | 96 MBs          | 64 MBs
182                 | 16 bytes  | 63 MBs          | 42 MBs
183                 | 32 bytes  | 36 MBs          | 24 MBs
184                 | 64 bytes  | 21 MBs          | 14 MBs
185flexcan1         | 8 bytes   | 64 MBs          | 64 MBs
186                 | 16 bytes  | 42 MBs          | 42 MBs
187                 | 32 bytes  | 24 MBs          | 24 MBs
188                 | 64 bytes  | 14 MBs          | 14 MBs
189flexcan2         | 8 bytes   | 64 MBs          | 64 MBs
190                 | 16 bytes  | 42 MBs          | 42 MBs
191                 | 32 bytes  | 24 MBs          | 24 MBs
192                 | 64 bytes  | 14 MBs          | 14 MBs
193flexcan3         | 8 bytes   | 32 MBs          | 32 MBs
194                 | 16 bytes  | 21 MBs          | 21 MBs
195                 | 32 bytes  | 12 MBs          | 12 MBs
196                 | 64 bytes  | 7 MBs           | 7 MBs
197flexcan4         | 8 bytes   | 32 MBs          | 32 MBs
198                 | 16 bytes  | 21 MBs          | 21 MBs
199                 | 32 bytes  | 12 MBs          | 12 MBs
200                 | 64 bytes  | 7 MBs           | 7 MBs
201flexcan5         | 8 bytes   | 32 MBs          | 32 MBs
202                 | 16 bytes  | 21 MBs          | 21 MBs
203                 | 32 bytes  | 12 MBs          | 12 MBs
204                 | 64 bytes  | 7 MBs           | 7 MBs
205===============  ==========  ================  ================
206
207.. note::
208   A CAN bus usually requires 120 Ohm termination at both ends of the bus. This may be
209   accomplished using one of the included CAN termination boards. For more details, refer
210   to the section ``6.3 CAN Connectors`` in the Hardware User Manual of `NXP MR-CANHUBK3`_.
211
212I2C
213===
214
215I2C is provided through LPI2C interface with 2 instances ``lpi2c0`` and ``lpi2c1``
216on corresponding connectors ``P4``, ``P3``.
217
218=========  =====  ============
219Connector  Pin    Pin Function
220=========  =====  ============
221P3.2       PTD9   LPI2C1_SCL
222P3.3       PTD8   LPI2C1_SDA
223P4.3       PTD14  LPI2C0_SCL
224P4.4       PTD13  LPI2C0_SDA
225=========  =====  ============
226
227The accompanying display board can be connected to ``lpi2c0`` via connector ``P4``.
228
229ADC
230===
231
232ADC is provided through ADC SAR controller with 3 instances. ADC channels are divided into
2333 groups (precision, standard and external).
234
235.. note::
236   All channels of an instance only run on 1 group channel at the same time.
237
238FS26 SBC Watchdog
239=================
240
241On normal operation after the board is powered on, there is a window of 256 ms
242on which the FS26 watchdog must be serviced with a good token refresh, otherwise
243the watchdog will signal a reset to the MCU. This board configuration enables
244the FS26 watchdog driver that handles this initialization.
245
246.. note::
247
248   The FS26 can also be started in debug mode (watchdog disabled) following
249   these steps:
250
251   1. Power off the board.
252   2. Remove the jumper ``JP1`` (pins 1-2 open), which is connected by default.
253   3. Power on the board.
254   4. Reconnect the jumper ``JP1`` (pins 1-2 shorted).
255
256External Flash
257==============
258
259The on-board MX25L6433F 64M-bit multi-I/O Serial NOR Flash memory is connected
260to the QSPI controller port A1. This board configuration selects it as the
261default flash controller.
262
263Ethernet
264========
265
266This board has a single instance of Ethernet Media Access Controller (EMAC)
267interfacing with a `NXP TJA1103`_ 100Base-T1 Ethernet PHY. Currently, there is
268limited driver for this PHY that allows for overiding the default pin strapping configuration for
269the PHY (RMII, master, autonomous mode enabled, polarity correction enabled)
270to slave mode.
271
272The 100Base-T1 signals are available in connector ``P9`` and can be converted to
273100Base-T using a Ethernet media converter such as `RDDRONE-T1ADAPT`_.
274
275Programming and Debugging
276*************************
277
278Applications for the ``mr_canhubk3`` board can be built in the usual way as
279documented in :ref:`build_an_application`.
280
281This board configuration supports `Lauterbach TRACE32`_, `SEGGER J-Link`_ and `pyOCD`_
282West runners for flashing and debugging applications. Follow the steps described
283in :ref:`lauterbach-trace32-debug-host-tools`, :ref:`jlink-debug-host-tools` and
284:ref:`pyocd-debug-host-tools`,
285to setup the flash and debug host tools for these runners, respectively. The
286default runner is J-Link.
287
288Flashing
289========
290
291Run the ``west flash`` command to flash the application using SEGGER J-Link.
292Alternatively, run ``west flash -r trace32`` to use Lauterbach TRACE32, or
293``west flash -r pyocd``` to use pyOCD.
294
295The Lauterbach TRACE32 runner supports additional options that can be passed
296through command line:
297
298.. code-block:: console
299
300   west flash -r trace32 --startup-args elfFile=<elf_path> loadTo=<flash/sram>
301      eraseFlash=<yes/no> verifyFlash=<yes/no>
302
303Where:
304
305- ``<elf_path>`` is the path to the Zephyr application ELF in the output
306  directory
307- ``loadTo=flash`` loads the application to the SoC internal program flash
308  (:kconfig:option:`CONFIG_XIP` must be set), and ``loadTo=sram`` load the
309  application to SRAM. Default is ``flash``.
310- ``eraseFlash=yes`` erases the whole content of SoC internal flash before the
311  application is downloaded to either Flash or SRAM. This routine takes time to
312  execute. Default is ``no``.
313- ``verifyFlash=yes`` verify the SoC internal flash content after programming
314  (use together with ``loadTo=flash``). Default is ``no``.
315
316For example, to erase and verify flash content:
317
318.. code-block:: console
319
320   west flash -r trace32 --startup-args elfFile=build/zephyr/zephyr.elf loadTo=flash eraseFlash=yes verifyFlash=yes
321
322Debugging
323=========
324
325Run the ``west debug`` command to start a GDB session using SEGGER J-Link.
326Alternatively, run ``west debug -r trace32`` or ``west debug -r pyocd``
327to launch the Lauterbach TRACE32 or pyOCD software debugging interface respectively.
328
329References
330**********
331
332.. target-notes::
333
334.. _NXP MR-CANHUBK3:
335   https://www.nxp.com/design/development-boards/automotive-development-platforms/s32k-mcu-platforms/s32k344-evaluation-board-for-mobile-robotics-incorporating-100baset1-and-six-can-fd:MR-CANHUBK344
336
337.. _NXP S32K344:
338   https://www.nxp.com/products/processors-and-microcontrollers/s32-automotive-platform/s32k-auto-general-purpose-mcus/s32k3-microcontrollers-for-automotive-general-purpose:S32K3
339
340.. _NXP FS26 Safety System Basis Chip:
341   https://www.nxp.com/products/power-management/pmics-and-sbcs/safety-sbcs/safety-system-basis-chip-with-low-power-fit-for-asil-d:FS26
342
343.. _NXP TJA1103:
344   https://www.nxp.com/products/interfaces/ethernet-/automotive-ethernet-phys/asil-b-compliant-100base-t1-ethernet-phy:TJA1103
345
346.. _RDDRONE-T1ADAPT:
347   https://www.nxp.com/products/interfaces/ethernet-/automotive-ethernet-phys/ethernet-media-converter-for-drones-rovers-mobile-robotics-and-automotive:RDDRONE-T1ADAPT
348
349.. _Lauterbach TRACE32:
350   https://www.lauterbach.com
351
352.. _SEGGER J-Link:
353   https://wiki.segger.com/NXP_S32K3xx
354
355.. _pyOCD:
356   https://pyocd.io/
357