Skip to content

Commit 1ea62c1

Browse files
kbumsikfpistm
kbumsik
authored and
fpistm
committed
[STM32MP157_DK] Add README.md about the variant
1 parent 5580e23 commit 1ea62c1

File tree

1 file changed

+133
-0
lines changed

1 file changed

+133
-0
lines changed

‎variants/STM32MP157_DK/README.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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 corprocessor is not a stand-alone microcontroller: the Arduino firmware for the coprocessor must be managed by the host Linux (Cortex-A side).__
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` kernel configuration on boot time. See [ST Wiki page on boot mode] for more detail.
17+
18+
## How to use
19+
20+
After Verify and Upload, you will see a message simillar 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:
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 excuted 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+
## Pin mapping
59+
60+
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.
61+
62+
Note that PWM N channel (e.g. TIM1_CH3N) outputs negative output to the corresponding channel, meaning it outputs inverted duty cycle.
63+
64+
| Feature | ST | Arduino | | Arduino | ST | Feature | PWM |
65+
|-----------|-------|:-------:|:-:|:-------:|-------|-----------|-----------|
66+
| | | | | SCL | PA_11 | I2C5-SCL | TIM1_CH4 |
67+
| | | | | SDA | PA_12 | I2C5-SDA | |
68+
| | | | | Varef | | | |
69+
| | | NC | | 13 | PE_12 | SPI4-SCK | TIM1_CH3N |
70+
| | | 5V | | 12 | PE_13 | SPI4-MISO | TIM1_CH3 |
71+
| | | RST | | 11 | PE_14 | SPI4-MOSI | TIM1_CH4 |
72+
| | | 3.3V | | 10 | PE_11 | SPI4-SS | TIM1_CH2 |
73+
| | | 5V | | 9 | PH_6 | | TIM12_CH1 |
74+
| | | GND | | 8 | PG_3 | | |
75+
| | | GND | | | | | |
76+
| | | Vin | | 7 | PD_1 | | |
77+
| | | | | 6 | PE_9 | | TIM1_CH1 |
78+
| ADC1_IN0 | PF_14 | A0 | | 5 | PD_15 | | TIM4_CH4 |
79+
| ADC1_IN1 | PF_13 | A1 | | 4 | PE_10 | | TIM1_CH2N |
80+
| ADC1_IN6 | ANA_0 | A2 | | 3 | PD_14 | | TIM4_CH3 |
81+
| ADC1_IN2 | ANA_1 | A3 | | 2 | PE_1 | | |
82+
| ADC1_IN13 | PC_3 | A4 | | 1 | PE_8 | UART7-TX | TIM1_CH1N |
83+
| ADC1_IN14 | PF_12 | A5 | | 0 | PE_7 | UART7-RX | |
84+
85+
There are additional pins for LEDs and buttons.
86+
87+
| ST | Arduino | Arduino | Comment |
88+
|-------|-------------------------------|----------------------|--------------------------------------------------|
89+
| PA_14 | 16 / LED_GREEN | USER1_BTN / USER_BTN | Active Low, LED LD5, also connected to B3 button |
90+
| PA_13 | 17 / LED_RED | USER2_BTN | Active Low, LED LD6, also connected to B4 button |
91+
| PH_7 | 18 / LED_ORANGE / LED_BUILTIN | | Active High, LED LD7 |
92+
93+
[`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 pinout.
94+
95+
## Uploading
96+
97+
As mentioned above `run_arduino.sh` file should be uploaded manually in order to work. There are many ways to upload the file.
98+
99+
### Over Network
100+
101+
* **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:
102+
```
103+
host: (Varies. Search online to learn how to figure it out.)
104+
username: root
105+
password: (none by default)
106+
```
107+
108+
### Over Serial
109+
110+
* **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.
111+
112+
## Limitations
113+
114+
* 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 maually modify [Linux Device tree to enable `usart3` and recompile it](usart3).
115+
* 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.
116+
* [Early firmware loading from U-Boot stage] is not supported. Only firmware loading on Linux boot stage by systemd supported. The binary itself may support it but there is no out-of-box tool to configure U-Boot to load the firmware in this project yet.
117+
* 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.
118+
119+
120+
121+
[STM32MP157A-DK1]: https://www.st.com/en/evaluation-tools/stm32mp157a-dk1.html
122+
[STM32MP157C-DK2]: https://www.st.com/en/evaluation-tools/stm32mp157c-dk2.html
123+
124+
[STM32MP15 Starter Package]: https://wiki.st.com/stm32mpu/wiki/STM32MP15_Discovery_kits_-_Starter_Package
125+
[STM32 MPU OpenSTLinux Distribution]: https://wiki.st.com/stm32mpu/wiki/STM32MP1_Distribution_Package
126+
[Balena OS]: https://github.com/kbumsik/balena-st-stm32mp
127+
[ST Wiki page on boot mode]: https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_Package#Getting_started_with_STM32CubeMP1_Package
128+
129+
[The ST Wiki page on C-Kermit]: https://wiki.st.com/stm32mpu/wiki/How_to_transfer_a_file_over_serial_console
130+
[a bug in OpenSTLinux]: https://community.st.com/s/question/0D50X0000B9vHa4/cannot-get-download-a-file-using-kermit
131+
132+
[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
133+
[Early firmware loading from U-Boot stage]: https://wiki.st.com/stm32mpu/wiki/How_to_start_the_coprocessor_from_the_bootloader

0 commit comments

Comments
 (0)