Skip to content

Commit b36e553

Browse files
kbumsikkbumsik
committed
[STM32MP157_DK] Add README.md about the variant
1 parent a6d31e9 commit b36e553

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎variants/STM32MP157_DK/README.md

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Discovery kit with STM32MP157x MPU Series
2+
3+
This variant currently supports the following boards:
4+
5+
* [STM32MP157A-DK1]
6+
* [STM32MP157C-DK2]
7+
8+
This port targets the Cortex-M4 coprocessor. __Note that the coprocessor is not a stand-alone microcontroller: the Arduino firmware for the coprocessor must be managed by the host Linux (Cortex-A side).__ In other words, [Cortex-M4 Engineering mode] is not supported and only Production mode is supported.
9+
10+
Because every OS may have different software configurations (especially Device Tree) not all Linux distributions for these boards are supported. The currently supported distributions are the following:
11+
12+
* [STM32MP15 Starter Package]
13+
* [STM32 MPU OpenSTLinux Distribution]
14+
* [Balena OS]
15+
16+
Note that the first two OSes should select `stm32mp157c-dk2-m4-examples-sdcard` boot mode (or device tree configuration) on boot time. `stm32mp157c-dk2-sdcard` boot mode is also known to work but it is not guaranteed. See [ST Wiki page on boot mode] for more detail. If you are using it for your own OS, see the [Linux Device Tree considerations](#Linux-Device-Tree-considerations) section.
17+
18+
## How to use
19+
20+
After Verify and Upload, you will see a message similar to the following in Arduino IDE:
21+
22+
<Arduino build output path>/run_arduino.sh generated successfully.
23+
This file should be uploaded manually by SCP, SFTP, Kermit, or etc.
24+
Then run "sh ./run_arduino.sh start" command in the board's console.
25+
For detailed instructions, please visit:
26+
https://github.com/stm32duino/Arduino_Core_STM32/tree/master/variants/STM32MP157_DK/README.md
27+
28+
In this example, the user **must** upload `<Arduino build output path>/run_arduino.sh` file manually. Uploading instruction is described later in the [Uploading](#Uploading) section.
29+
30+
After uploading the user can use `sh run_arduino.sh start` in the console of host Linux via either SSH or Serial Console, to run the Arduino firmware.
31+
32+
Note: `sh run_arduino.sh start` is a one-shot command: the Arduino firmware only runs for the current boot. If you want to make it run after reboot, you need to use `sh run_arduino.sh install` command.
33+
34+
`run_arduino.sh` help page summary:
35+
36+
Usage: sh run_arduino.sh [start|stop|restart|generate|install|uninstall]
37+
38+
run_arduino.sh is a helper script that helps managing an Arduino binary
39+
file for the coprocessor using remoteproc framework.
40+
41+
sh run_arduino.sh start
42+
Upload the binary to the coprocessor then start it.
43+
This command must be executed while the script contains the binary
44+
after generate command is run.
45+
46+
sh run_arduino.sh install
47+
Run the binary on boot automatically by installing a systemd service.
48+
49+
sh run_arduino.sh uninstall
50+
Uninstall the autostart service.
51+
52+
sh run_arduino.sh stop
53+
Stop the coprocessor.
54+
55+
sh run_arduino.sh restart
56+
Restart the coprocessor.
57+
58+
See the source code for the full help page and the more details about [run_arduino.sh].
59+
60+
## Pin mapping
61+
62+
The boards have two pin headers: Raspberry Pi HAT headers and Arduino shield headers. This project currently supports Arduino Shield headers only, leaving RPi HAT headers for the Linux applications.
63+
64+
Note that PWM N channel (e.g. TIM1_CH3N) outputs negative output to the corresponding channel, meaning it outputs inverted duty cycle.
65+
66+
| Feature | ST | Arduino | | Arduino | ST | Feature | PWM |
67+
|-----------|-------|:-------:|:-:|:-------:|-------|-----------|-----------|
68+
| | | | | SCL | PA_11 | I2C5-SCL | TIM1_CH4 |
69+
| | | | | SDA | PA_12 | I2C5-SDA | |
70+
| | | | | Varef | | | |
71+
| | | NC | | 13 | PE_12 | SPI4-SCK | TIM1_CH3N |
72+
| | | 5V | | 12 | PE_13 | SPI4-MISO | TIM1_CH3 |
73+
| | | RST | | 11 | PE_14 | SPI4-MOSI | TIM1_CH4 |
74+
| | | 3.3V | | 10 | PE_11 | SPI4-SS | TIM1_CH2 |
75+
| | | 5V | | 9 | PH_6 | | TIM12_CH1 |
76+
| | | GND | | 8 | PG_3 | | |
77+
| | | GND | | | | | |
78+
| | | Vin | | 7 | PD_1 | | |
79+
| | | | | 6 | PE_9 | | TIM1_CH1 |
80+
| ADC1_IN0 | PF_14 | A0 | | 5 | PD_15 | | TIM4_CH4 |
81+
| ADC1_IN1 | PF_13 | A1 | | 4 | PE_10 | | TIM1_CH2N |
82+
| ADC1_IN6 | ANA_0 | A2 | | 3 | PD_14 | | TIM4_CH3 |
83+
| ADC1_IN2 | ANA_1 | A3 | | 2 | PE_1 | | |
84+
| ADC1_IN13 | PC_3 | A4 | | 1 | PE_8 | UART7-TX | TIM1_CH1N |
85+
| ADC1_IN14 | PF_12 | A5 | | 0 | PE_7 | UART7-RX | |
86+
87+
There are additional pins for LEDs and buttons.
88+
89+
| ST | Arduino | Arduino (cont.) | Comment |
90+
|-------|-------------------------------|----------------------|--------------------------------------------------|
91+
| PA_14 | 16 / LED_GREEN | USER1_BTN / USER_BTN | Active Low, LED LD5, also connected to B3 button |
92+
| PA_13 | 17 / LED_RED | USER2_BTN | Active Low, LED LD6, also connected to B4 button |
93+
| PH_7 | 18 / LED_ORANGE / LED_BUILTIN | | Active High, LED LD7 |
94+
95+
[`variant.h` of the board](https://github.com/stm32duino/Arduino_Core_STM32/tree/master/variants/STM32MP157_DK/variant.h) has the complete information about the pinouts.
96+
97+
## Uploading
98+
99+
As mentioned above `run_arduino.sh` file should be uploaded manually in order to work. There are many ways to upload the file.
100+
101+
### Over Network
102+
103+
* **SCP** and **SFTP** are good options to upload the file, since STM32MP1 board runs SSH server by default. There are a lot of online resources on how to use them on the internet. Here is the default SSH access information:
104+
```
105+
host: (Varies. Search online to learn how to figure it out.)
106+
username: root
107+
password: (none by default)
108+
```
109+
110+
### Over Serial
111+
112+
* **C-Kermit** is a combined network and serial communication software package that allows users to transfer files over serial connection. [The ST Wiki page on C-Kermit] describes how to use it.
113+
114+
## Linux Device Tree considerations
115+
116+
To use the Arduino firmware for a custom OS, the user need to take into account in the Linux Device Tree, since a peripheral cannot be shared between the Linux host and the Arduino firmware, and Arduino must occupy some peripherals.
117+
118+
For example, Arduino uses TIM1 for PWM `analogWrite()` implementation. The Device Tree must disable TIM1 for Linux usage like the following:
119+
```
120+
&timers1 {
121+
status = "disabled";
122+
};
123+
```
124+
125+
And then the Device Tree should enable TIM1 for the coprocessor, although this doesn't seems to be a strict requirement it is safer to do this:
126+
```
127+
&m4_timers1 {
128+
pinctrl-names = "rproc_default";
129+
pinctrl-0 = <&timer1_pins>;
130+
status = "okay";
131+
};
132+
```
133+
134+
[stm32mp157c-dk2-m4-examples.dts] is a great example to begin with. For the full list of peripherals used by the Arduino firmware, see [PeripheralPins.c](/variants/STM32MP157_DK/PeripheralPins.c) of the board.
135+
136+
## Limitations
137+
138+
* Ethernet and USB are not supported. Use them in the Linux host.
139+
* Currently there is no easy way for communication between the Linux host and Arduino coprocessor. There is ongoing work for virtual serial communications using OpenAMP rpmsg framework. Currently one possible way is to wire between UART7 (Arduino SCL/SDA pins) and USART3 (Linux RPi HAT GPIO14/GPIO15 pins), however, users should manually modify [Linux Device tree to enable `usart3` and recompile it](usart3).
140+
* I2C pins on Raspberry Pi HAT header (GPIO2 and GPIO3) are not available in Linux host. This is because the Discovery board shares I2C pins on Arduino header and those on the HAT header.
141+
* [Early firmware loading from U-Boot stage] is not supported. Only firmware loading on Linux boot stage by systemd supported. The binary itself may be loaded by U-Boot without any problems, but there is no out-of-box tool to configure U-Boot to load the firmware using Arduino IDE yet.
142+
* EEPROM library: Those devices do not have non-volatile memory. The emulation is done using RETRAM. Therefore data will be preserved *only* when VBAT is supplied (e.g. A coin battery is connected to CN3 on STM32MP157A_DK1) and the coprocessor is waken up from sleep. This implies that cold boot the board may cause data loss, even if VBAT is supplied. See [discussions on RETRAM] for more detail.
143+
144+
145+
146+
[STM32MP157A-DK1]: https://www.st.com/en/evaluation-tools/stm32mp157a-dk1.html
147+
[STM32MP157C-DK2]: https://www.st.com/en/evaluation-tools/stm32mp157c-dk2.html
148+
149+
[Cortex-M4 Engineering mode]: https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_development_guidelines
150+
[STM32MP15 Starter Package]: https://wiki.st.com/stm32mpu/wiki/STM32MP15_Discovery_kits_-_Starter_Package
151+
[STM32 MPU OpenSTLinux Distribution]: https://wiki.st.com/stm32mpu/wiki/STM32MP1_Distribution_Package
152+
[Balena OS]: https://github.com/kbumsik/balena-st-stm32mp
153+
[ST Wiki page on boot mode]: https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_Package#Getting_started_with_STM32CubeMP1_Package
154+
155+
[run_arduino.sh]: https://github.com/stm32duino/Arduino_Tools/blob/master/linux/run_arduino_gen.sh
156+
157+
[The ST Wiki page on C-Kermit]: https://wiki.st.com/stm32mpu/wiki/How_to_transfer_a_file_over_serial_console
158+
[a bug in OpenSTLinux]: https://community.st.com/s/question/0D50X0000B9vHa4/cannot-get-download-a-file-using-kermit
159+
160+
[stm32mp157c-dk2-m4-examples.dts]: https://github.com/STMicroelectronics/meta-st-stm32mp/blob/d8cbac759e1275b1a27d4ba38b64a0d83d0e8c9f/recipes-kernel/linux/linux-stm32mp/4.19/4.19.49/0029-ARM-stm32mp1-r2-DEVICETREE.patch#L4334
161+
162+
[usart3]: https://github.com/STMicroelectronics/meta-st-stm32mp/blob/d8cbac759e1275b1a27d4ba38b64a0d83d0e8c9f/recipes-kernel/linux/linux-stm32mp/4.19/4.19.49/0029-ARM-stm32mp1-r2-DEVICETREE.patch#L4274
163+
[Early firmware loading from U-Boot stage]: https://wiki.st.com/stm32mpu/wiki/How_to_start_the_coprocessor_from_the_bootloader
164+
[discussions on RETRAM]: https://community.st.com/s/question/0D50X0000B44pHUSQY/doesnt-the-mcu-coprocessor-have-nonvolatile-memory

0 commit comments

Comments
 (0)