1.. _arduino_portenta_h7_board:
2
3Arduino Portenta H7
4###################
5
6Overview
7********
8
9The Portenta H7 enables a wide diversity of applications taking benefit
10from Computer Vision, PLCs, Robotics controller, High-end industrial machinery
11and high-speed booting computation (ms).
12
13The board includes an STM32H747XI SoC with a high-performance DSP, Arm Cortex-M7 + Cortex-M4 MCU,
14with 2MBytes of Flash memory, 1MB RAM, 480 MHz CPU, Art Accelerator, L1 cache, external memory interface,
15large set of peripherals, SMPS, and MIPI-DSI.
16
17Additionally, the board features:
18
19- USB OTG FS
20- 3 color user LEDs
21
22.. image:: img/arduino_portenta_h7.jpeg
23     :width: 500px
24     :align: center
25     :height: 325px
26     :alt: ARDUINO_PORTENTA_H7
27
28More information about the board can be found at the `ARDUINO_PORTENTA_H7 website`_.
29More information about STM32H747XIH6 can be found here:
30
31- `STM32H747XI on www.st.com`_
32- `STM32H747xx reference manual`_
33- `STM32H747xx datasheet`_
34
35Supported Features
36==================
37
38The current Zephyr arduino_portenta_h7 board configuration supports the following hardware features:
39
40+-----------+------------+-------------------------------------+
41| Interface | Controller | Driver/Component                    |
42+===========+============+=====================================+
43| NVIC      | on-chip    | nested vector interrupt controller  |
44+-----------+------------+-------------------------------------+
45| UART      | on-chip    | serial port-polling;                |
46|           |            | serial port-interrupt               |
47+-----------+------------+-------------------------------------+
48| PINMUX    | on-chip    | pinmux                              |
49+-----------+------------+-------------------------------------+
50| GPIO      | on-chip    | gpio                                |
51+-----------+------------+-------------------------------------+
52| FLASH     | on-chip    | flash memory                        |
53+-----------+------------+-------------------------------------+
54| RNG       | on-chip    | True Random number generator        |
55+-----------+------------+-------------------------------------+
56| SPI       | on-chip    | spi                                 |
57+-----------+------------+-------------------------------------+
58| IPM       | on-chip    | virtual mailbox based on HSEM       |
59+-----------+------------+-------------------------------------+
60| EXTFLASH  | on-chip    | qspi                                |
61+-----------+------------+-------------------------------------+
62| SDRAM     | on-chip    | sdram                               |
63+-----------+------------+-------------------------------------+
64| USB       | on-board   | usb-hs                              |
65+-----------+------------+-------------------------------------+
66| ETHERNET  | on-board   | eth                                 |
67+-----------+------------+-------------------------------------+
68
69Other hardware features are not yet supported on Zephyr porting.
70
71The high precision low speed external (LSE) clock is only fully supported on
72boards with hardware revision 4.10 or greater. By default the internal source
73is used; to enable the use of the external oscillator, manually specify the
74hardware revision at build time (see :ref:`application_board_version` for
75information on how to build for specific revisions of the board).
76
77Resources sharing
78=================
79
80The dual core nature of STM32H747 SoC requires sharing HW resources between the
81two cores. This is done in 3 ways:
82
83- **Compilation**: Clock configuration is only accessible to M7 core. M4 core only
84  has access to bus clock activation and deactivation.
85- **Static pre-compilation assignment**: Peripherals such as a UART are assigned in
86  devicetree before compilation. The user must ensure peripherals are not assigned
87  to both cores at the same time.
88- **Run time protection**: Interrupt-controller and GPIO configurations could be
89  accessed by both cores at run time. Accesses are protected by a hardware semaphore
90  to avoid potential concurrent access issues.
91
92Building and Flashing
93*************************
94
95Applications for the ``arduino_portenta_h7`` board should be built per core target,
96using either ``arduino_portenta_h7_m7`` or ``arduino_portenta_h7_m4`` as the target.
97See :ref:`build_an_application` for more information about application builds.
98
99
100Flashing
101========
102
103Installing dfu-util
104-------------------
105
106This board requires dfu-utils for flashing. It is recommended to use at least
107v0.8 of `dfu-util`_. The package available in debian/ubuntu can be quite old, so you might
108have to build dfu-util from source.
109
110Flashing an application to STM32H747I M7 Core
111---------------------------------------------
112
113First, connect the Arduino Portenta H7 board to your host computer using
114the USB port to prepare it for flashing. Double tap the button to put the board
115into the Arduino Bootloader mode. Then build and flash your application.
116
117Here is an example for the :zephyr:code-sample:`hello_world` application.
118
119.. zephyr-app-commands::
120   :zephyr-app: samples/hello_world
121   :board: arduino_portenta_h7/stm32h747xx/m7
122   :goals: build flash
123
124Run a serial host program to connect with your board:
125
126.. code-block:: console
127
128   $ minicom -D /dev/ttyACM0
129
130You should see the following message on the console:
131
132.. code-block:: console
133
134   Hello World! arduino_portenta_h7
135
136Similarly, you can build and flash samples on the M4 target. For this, please
137take care of the resource sharing (UART port used for console for instance).
138
139Here is an example for the :zephyr:code-sample:`blinky` application on M4 core.
140
141.. zephyr-app-commands::
142   :zephyr-app: samples/basic/blinky
143   :board: arduino_portenta_h7/stm32h747xx/m4
144   :goals: build flash
145
146.. _ARDUINO_PORTENTA_H7 website:
147   https://docs.arduino.cc/hardware/portenta-h7
148
149.. _STM32H747XI on www.st.com:
150   https://www.st.com/content/st_com/en/products/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32h7-series/stm32h747-757/stm32h747xi.html
151
152.. _STM32H747xx reference manual:
153   https://www.st.com/resource/en/reference_manual/dm00176879.pdf
154
155.. _STM32H747xx datasheet:
156   https://www.st.com/resource/en/datasheet/stm32h747xi.pdf
157
158.. _dfu-util:
159   http://dfu-util.sourceforge.net/build.html
160