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- USB OTG FS
19- 3 color user LEDs
20
21.. image:: img/arduino_portenta_h7.jpeg
22     :width: 500px
23     :align: center
24     :height: 325px
25     :alt: ARDUINO_PORTENTA_H7
26
27More information about the board can be found at the `ARDUINO_PORTENTA_H7 website`_.
28More information about STM32H747XIH6 can be found here:
29
30- `STM32H747XI on www.st.com`_
31- `STM32H747xx reference manual`_
32- `STM32H747xx datasheet`_
33
34Supported Features
35==================
36
37The current Zephyr arduino_portenta_h7 board configuration supports the following hardware features:
38
39+-----------+------------+-------------------------------------+
40| Interface | Controller | Driver/Component                    |
41+===========+============+=====================================+
42| NVIC      | on-chip    | nested vector interrupt controller  |
43+-----------+------------+-------------------------------------+
44| UART      | on-chip    | serial port-polling;                |
45|           |            | serial port-interrupt               |
46+-----------+------------+-------------------------------------+
47| PINMUX    | on-chip    | pinmux                              |
48+-----------+------------+-------------------------------------+
49| GPIO      | on-chip    | gpio                                |
50+-----------+------------+-------------------------------------+
51| FLASH     | on-chip    | flash memory                        |
52+-----------+------------+-------------------------------------+
53| RNG       | on-chip    | True Random number generator        |
54+-----------+------------+-------------------------------------+
55| SPI       | on-chip    | spi                                 |
56+-----------+------------+-------------------------------------+
57| IPM       | on-chip    | virtual mailbox based on HSEM       |
58+-----------+------------+-------------------------------------+
59
60Other hardware features are not yet supported on Zephyr porting.
61
62Resources sharing
63=================
64
65The dual core nature of STM32H747 SoC requires sharing HW resources between the
66two cores. This is done in 3 ways:
67
68- **Compilation**: Clock configuration is only accessible to M7 core. M4 core only
69  has access to bus clock activation and deactivation.
70- **Static pre-compilation assignment**: Peripherals such as a UART are assigned in
71  devicetree before compilation. The user must ensure peripherals are not assigned
72  to both cores at the same time.
73- **Run time protection**: Interrupt-controller and GPIO configurations could be
74  accessed by both cores at run time. Accesses are protected by a hardware semaphore
75  to avoid potential concurrent access issues.
76
77Building and Flashing
78*************************
79
80Applications for the ``arduino_portenta_h7`` board should be built per core target,
81using either ``arduino_portenta_h7_m7`` or ``arduino_portenta_h7_m4`` as the target.
82See :ref:`build_an_application` for more information about application builds.
83
84
85Flashing
86========
87
88Installing dfu-util
89-------------------
90
91This board requires dfu-utils for flashing. It is recommended to use at least
92v0.8 of `dfu-util`_. The package available in debian/ubuntu can be quite old, so you might
93have to build dfu-util from source.
94
95Flashing an application to STM32H747I M7 Core
96---------------------------------------------
97
98First, connect the Arduino Portenta H7 board to your host computer using
99the USB port to prepare it for flashing. Double tap the button to put the board
100into the Arduino Bootloader mode. Then build and flash your application.
101
102Here is an example for the :ref:`hello_world` application.
103
104.. zephyr-app-commands::
105   :zephyr-app: samples/hello_world
106   :board: arduino_portenta_h7_m7
107   :goals: build flash
108
109Run a serial host program to connect with your board:
110
111.. code-block:: console
112
113   $ minicom -D /dev/ttyACM0
114
115You should see the following message on the console:
116
117.. code-block:: console
118
119   Hello World! arduino_portenta_m7
120
121Similarly, you can build and flash samples on the M4 target. For this, please
122take care of the resource sharing (UART port used for console for instance).
123
124Here is an example for the :zephyr:code-sample:`blinky` application on M4 core.
125
126.. zephyr-app-commands::
127   :zephyr-app: samples/basic/blinky
128   :board: arduino_portenta_h7_m4
129   :goals: build flash
130
131.. _ARDUINO_PORTENTA_H7 website:
132   https://docs.arduino.cc/hardware/portenta-h7
133
134.. _STM32H747XI on www.st.com:
135   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
136
137.. _STM32H747xx reference manual:
138   https://www.st.com/resource/en/reference_manual/dm00176879.pdf
139
140.. _STM32H747xx datasheet:
141   https://www.st.com/resource/en/datasheet/stm32h747xi.pdf
142
143.. _dfu-util:
144   http://dfu-util.sourceforge.net/build.html
145