1.. _arduino_opta_m4_board:
2
3Arduino OPTA
4############
5
6Overview
7********
8
9The Arduino™ Opta® is a secure micro Programmable Logic Controller (PLC)
10with Industrial Internet of Things (IoT) capabilities.
11
12Developed in partnership with Finder®, this device supports both the Arduino
13programming language and standard IEC-61131-3 PLC programming languages,
14such as Ladder Diagram (LD), Sequential Function Chart (SFC),
15Function Block Diagram (FBD), Structured Text (ST), and Instruction List (IL),
16making it an ideal device for automation engineers.
17
18For Zephyr RTOS, both cores are supported. It is also possible to run only on
19the M4 making the M7 run the PLC tasks while the M4 core under Zephyr acts as
20a coprocessor.
21
22Additionally, the device features:
23
24- Ethernet compliant with IEEE802.3-2002
25- 16MB QSPI Flash
26- 4 x green color status LEDs
27- 1 x green or red led over the reset push-button
28- 1 x blue led over the user push-button (Opta Advanced only)
29- 1 x user push-button
30- 1 x reset push-button accessible via pinhole
31- 8 x analog inputs
32- 4 x isolated relay outputs
33
34.. image:: img/arduino_opta.jpeg
35     :align: center
36     :alt: ARDUINO-OPTA
37
38More information about the board can be found at the `ARDUINO-OPTA website`_.
39More information about STM32H747XIH6 can be found here:
40
41- `STM32H747XI on www.st.com`_
42- `STM32H747xx reference manual`_
43- `STM32H747xx datasheet`_
44
45Supported Features
46==================
47
48The ``arduino_opta/stm32h747xx/m7`` board target
49supports the following hardware features:
50
51+-----------+------------+-------------------------------------+
52| Interface | Controller | Driver/Component                    |
53+===========+============+=====================================+
54| NVIC      | on-chip    | nested vector interrupt controller  |
55+-----------+------------+-------------------------------------+
56| PINMUX    | on-chip    | pinmux                              |
57+-----------+------------+-------------------------------------+
58| GPIO      | on-chip    | gpio                                |
59+-----------+------------+-------------------------------------+
60| FLASH     | on-chip    | flash memory                        |
61+-----------+------------+-------------------------------------+
62| RNG       | on-chip    | True Random number generator        |
63+-----------+------------+-------------------------------------+
64| IPM       | on-chip    | virtual mailbox based on HSEM       |
65+-----------+------------+-------------------------------------+
66| USB       | on-board   | usb-fs                              |
67+-----------+------------+-------------------------------------+
68| ETHERNET  | on-board   | eth                                 |
69+-----------+------------+-------------------------------------+
70| RS485     | on-board   | uart                                |
71+-----------+------------+-------------------------------------+
72
73The ``arduino_opta/stm32h747xx/m4`` board target
74supports the following hardware features:
75
76+-----------+------------+-------------------------------------+
77| Interface | Controller | Driver/Component                    |
78+===========+============+=====================================+
79| NVIC      | on-chip    | nested vector interrupt controller  |
80+-----------+------------+-------------------------------------+
81| PINMUX    | on-chip    | pinmux                              |
82+-----------+------------+-------------------------------------+
83| GPIO      | on-chip    | gpio                                |
84+-----------+------------+-------------------------------------+
85| FLASH     | on-chip    | flash memory                        |
86+-----------+------------+-------------------------------------+
87| RNG       | on-chip    | True Random number generator        |
88+-----------+------------+-------------------------------------+
89| IPM       | on-chip    | virtual mailbox based on HSEM       |
90+-----------+------------+-------------------------------------+
91
92Other hardware features are not yet supported on Zephyr porting.
93
94The default configuration per core can be found in the defconfig files:
95:zephyr_file:`boards/arduino/opta/arduino_opta_stm32h747xx_m4_defconfig` and
96:zephyr_file:`boards/arduino/opta/arduino_opta_stm32h747xx_m7_defconfig`.
97
98Pin Mapping
99===========
100
101Both the M7 and M4 cores have access to the 9 GPIO controllers. These
102controllers are responsible for pin muxing, input/output, pull-up, etc.
103
104For more details please refer to `ARDUINO-OPTA website`_.
105
106Default Zephyr Peripheral Mapping
107---------------------------------
108
109- Status LED1: PI0
110- Status LED2: PI1
111- Status LED3: PI3
112- Status LED4: PH15
113- Green "reset" LED: PH12
114- Red "reset" LED: PH11
115- Blue LED: PE5
116- User button: PE4
117- Input 1 : PA0
118- Input 2 : PC2
119- Input 3 : PF12
120- Input 4 : PB0
121- Input 5 : PF10
122- Input 6 : PF8
123- Input 7 : PF6
124- Input 8 : PF4
125- Relay 1: PI6
126- Relay 2: PI5
127- Relay 3: PI7
128- Relay 4: PI4
129
130System Clock
131============
132
133The STM32H747I System Clock can be driven by an internal or external oscillator,
134as well as by the main PLL clock. By default, the CPU2 (Cortex-M4) System clock
135is driven at 240MHz. PLL clock is fed by a 25MHz high speed external clock. The
136M7 clock is driven at 400MHz.
137
138Resources sharing
139=================
140
141The dual core nature of STM32H747 SoC requires sharing HW resources between the
142two cores. This is done in 3 ways:
143
144- **Compilation**: Clock configuration is only accessible to M7 core. M4 core only
145  has access to bus clock activation and deactivation.
146- **Static pre-compilation assignment**: Peripherals such as a UART are assigned in
147  devicetree before compilation. The user must ensure peripherals are not assigned
148  to both cores at the same time.
149- **Run time protection**: Interrupt-controller and GPIO configurations could be
150  accessed by both cores at run time. Accesses are protected by a hardware semaphore
151  to avoid potential concurrent access issues.
152
153Programming and Debugging
154*************************
155
156Applications for the ``arduino_opta`` use the regular Zephyr build commands.
157See :ref:`build_an_application` for more information about application builds.
158
159Flashing
160========
161
162Flashing operation will depend on the target to be flashed and the SoC
163option bytes configuration. The OPTA has a DFU capable bootloader which
164can be accessed by connecting the device to the USB, and then pressing
165the RESET button shortly twice, the RESET-LED on the board will fade
166indicating the board is in bootloader mode.
167
168By default:
169
170  - CPU1 (Cortex-M7) boot address is set to 0x08040000
171  - CPU2 (Cortex-M4) boot address is set to 0x08180000
172
173Zephyr flash configuration has been set to be compatible with the
174"Flash split: 1.5MB M7 + 0.5MB M4" option in the Arduino IDE. The flash is
175partitioned as follows:
176
177  - 0x08000000-0x0803FFFF (256k) Arduino MCUboot-derived bootloader
178  - 0x08040000-0x080FFFFF (768k) M7 application
179  - 0x08180000-0x081FFFFF (512k) M4 application
180
181
182Flashing an application to ARDUINO OPTA M7
183------------------------------------------
184
185First, connect the device to your host computer using
186the USB port to prepare it for flashing. Then build and flash your application.
187
188Here is an example for the :zephyr:code-sample:`blinky` application on M7 core.
189
190.. zephyr-app-commands::
191   :zephyr-app: samples/basic/blinky
192   :board: arduino_opta/stm32h747xx/m7
193   :goals: build flash
194
195Flashing an application to ARDUINO OPTA M4
196------------------------------------------
197
198First, connect the device to your host computer using
199the USB port to prepare it for flashing. Then build and flash your application.
200
201Here is an example for the :zephyr:code-sample:`blinky` application on M4 core.
202
203.. zephyr-app-commands::
204   :zephyr-app: samples/basic/blinky
205   :board: arduino_opta/stm32h747xx/m4
206   :goals: build flash
207
208Starting the application on the ARDUINO OPTA M4
209-----------------------------------------------
210
211If you also flashed an application to M7 the M4 processor is started at boot.
212If not you will need to start the processor from an Arduino sketch.
213
214Make sure the option bytes are set to prevent the M4 from auto-starting, and
215that the M7 side starts the M4 at the correct Flash address.
216
217This can be done by selecting in the Arduino IDE's "Tools" / "Flash Split"
218menu the "1.5MB M7 + 0.5MB M4" option, and loading a sketch that contains
219at least the following code:
220
221 .. code-block:: cpp
222
223    #include <RPC.h>
224
225    void setup() {
226        RPC.begin();
227    }
228
229    void loop() { }
230
231Debugging
232=========
233
234The debug port does not have an easy access but it is possible to open the
235case and solder a standard 10-pin SWD connector to the board. After that
236both flashing and debugging are available via ST-LINK (M7 core only).
237
238.. _ARDUINO-OPTA website:
239   https://docs.arduino.cc/hardware/opta
240
241.. _STM32H747XI on www.st.com:
242   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
243
244.. _STM32H747xx reference manual:
245   https://www.st.com/resource/en/reference_manual/dm00176879.pdf
246
247.. _STM32H747xx datasheet:
248   https://www.st.com/resource/en/datasheet/stm32h747xi.pdf
249