Skip to content

Commit c757029

Browse files
Aymane-STAymane-ST
committed
ci: patch to update README with STM32duino integration information
Signed-off-by: Aymane Bahssain <aymane.bahssain@st.com>
1 parent 800f4e5 commit c757029

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎CI/update/patch/api/0001-docs-update-README-with-STM32duino-integration-infor.patch‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
From 7a2df83c9217c36aa3c871e604d31049f8ab88df Mon Sep 17 00:00:00 2001
2+
From: Aymane Bahssain <aymane.bahssain@st.com>
3+
Date: Fri, 23 Jan 2026 16:07:39 +0100
4+
Subject: [PATCH] docs: update README with STM32duino integration information
5+
6+
Signed-off-by: Aymane Bahssain <aymane.bahssain@st.com>
7+
---
8+
README.md | 123 ++++++++++++++++++++++++++++--------------------------
9+
1 file changed, 64 insertions(+), 59 deletions(-)
10+
11+
diff --git a/README.md b/README.md
12+
index 506569a..142260e 100644
13+
--- a/README.md
14+
+++ b/README.md
15+
@@ -1,95 +1,100 @@
16+
-# ArduinoCore-API
17+
+# 📚 ArduinoCore-API for STM32duino
18+
19+
-[![Unit Tests](https://github.com/arduino/ArduinoCore-API/workflows/Unit%20Tests/badge.svg)](https://github.com/arduino/ArduinoCore-API/actions?workflow=Unit+Tests)
20+
-[![codecov](https://codecov.io/gh/arduino/ArduinoCore-API/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/ArduinoCore-API)
21+
-[![Spell Check status](https://github.com/arduino/ArduinoCore-API/actions/workflows/spell-check.yml/badge.svg)](https://github.com/arduino/ArduinoCore-API/actions/workflows/spell-check.yml)
22+
+Fork of [`arduino/ArduinoCore-API`](https://github.com/arduino/ArduinoCore-API)
23+
+Designed to be used as a git submodule in [`stm32duino/Arduino_Core_STM32`](https://github.com/stm32duino/Arduino_Core_STM32)
24+
25+
-This repository hosts the hardware independent layer of Arduino core. In other words it contains the abstract definition of the Arduino core API, consisting of hardware-independent header files that are then included and implemented by the various platform-specific cores.
26+
+---
27+
28+
-Having a single place where the Arduino API is defined means that there is no longer a String implementation within every Arduino core (a String module within ArduinoCore-avr, a String module within ArduinoCore-samd, a String module within ArduinoCore-megaavr …) but rather one String implementation within ArduinoCore-API which all other cores utilise. This has the pleasant side effects that bugs fixed or features added within the ArduinoCore-API String implementation are automatically propagated to all cores utilizing ArduinoCore-API.
29+
+## 🎯 Purpose
30+
31+
-As of now, the following official cores are utilising ArduinoCore-API:
32+
+This repository is a fork which reworks the folder structure to contain only the official Arduino API and hardware‑independent code, in order to simplify Arduino API integration into STM32duino via a git submodule.
33+
34+
-* [megaavr](https://github.com/arduino/ArduinoCore-megaAVR)
35+
-* [mbed](https://github.com/arduino/ArduinoCore-mbed)
36+
-* [samd](https://github.com/arduino/ArduinoCore-samd)
37+
-* [renesas](https://github.com/arduino/ArduinoCore-renesas)
38+
+It will also contain some updates/changes/enhancements/fixes.
39+
40+
-There's an ongoing effort to port the others, while maintainers of third-party cores are strongly invited to follow the same route in order to stay up-to-date with the new language features. For backwards compatibility, every revision of this repo will increase the `ARDUINO_API_VERSION` define.
41+
+---
42+
43+
-## Documentation
44+
+## 📦 What's Included?
45+
46+
-The Arduino API is documented in the official [language reference](https://www.arduino.cc/reference/en/), whose sources are located in [this repository](https://github.com/arduino/reference-en) and are open to contributions from the community.
47+
+- ✅ Official Arduino API files (`api/` folder)
48+
+- ✅ some updates, changes, enhancements and fixes.
49+
50+
-## Support
51+
+---
52+
53+
-This repository is not directly usable by final users. If you need assistance with Arduino, see the [Help Center](https://support.arduino.cc/) and browse the [forum](https://forum.arduino.cc).
54+
+## 🚀 Submodule usage
55+
56+
-## Development
57+
+### 1️⃣ Add the Submodule
58+
59+
-### Bugs & Issues
60+
+In the `Arduino_Core_STM32` repository, run:
61+
62+
-If you want to report an issue with this core, you can submit it to the [issue tracker](https://github.com/arduino/ArduinoCore-API/issues) of this repository. Some rules apply:
63+
-
64+
-* If your issue is about a specific hardware platform, report it to its repository. This one is only about discussing the generic API.
65+
-* Before posting, please check if the same problem has been already reported by someone else to avoid duplicates.
66+
-* Remember to include as much detail as you can about your hardware set-up, code and steps for reproducing the issue. Make sure you're using an original Arduino board.
67+
-
68+
-### Contributions
69+
+```bash
70+
71+
-Contributions are always welcome! You can submit them directly to this repository as Pull Requests. Please provide a detailed description of the problem you're trying to solve. We also appreciate any help in testing issues and patches contributed by other users.
72+
+git submodule add https://github.com/stm32duino/ArduinoCore-API.git cores/arduino/api
73+
+```
74+
+### 2️⃣ Initialize and update
75+
+```bash
76+
+git submodule update --init
77+
+```
78+
79+
-### Unit testing
80+
+---
81+
82+
-This repository includes a test suite that covers most of the API and that is designed to run on generic hardware, thus not requiring a development board. We call this _host-based unit-testing_. In order to test the features that are only defined but not implemented in this repository, mock implementations are included.
83+
+## 🔗 Official Resources
84+
85+
-Please help us improve the coverage of the test suite!
86+
+| Resource | Link |
87+
+|----------|------|
88+
+| **Official ArduinoCore-API** | https://github.com/arduino/ArduinoCore-API |
89+
+| **STM32duino** | https://github.com/stm32duino/Arduino_Core_STM32 |
90+
91+
-#### To build and run unit tests
92+
+---
93+
94+
-The unit tests are automatically built by GitHub as part of pull request checks (in `.github/workflows/unit-tests.yml`).
95+
+## 📝 License
96+
97+
-To build and run locally:
98+
+This repository is a fork of `arduino/ArduinoCore-API` and maintains the **same license** (LGPL 2.1+).
99+
100+
-**Dependencies**
101+
+See the [LICENSE](License) file in the repository root for details.
102+
103+
-* [CMake](https://cmake.org/)
104+
-* [GCC](https://gcc.gnu.org/)
105+
+---
106+
107+
-On (Ubuntu) Linux run:
108+
+## 💡 Important Notes
109+
110+
-```bash
111+
-sudo apt-get install build-essential cmake
112+
-```
113+
+### ✅ Advantages of Using a Submodule
114+
115+
-From the project root:
116+
+- **Traceability**: Know exactly which version of the API you're using
117+
+- **Easy Updates**: Simple `git submodule update` to sync
118+
+- **Isolation**: API stays in its own code branch
119+
+- **Compatibility**: STM32-specific modifications remain separate
120+
121+
-```bash
122+
-cd test && mkdir build && cd build
123+
-cmake ..
124+
-make && bin/test-ArduinoCore-API
125+
-```
126+
+### ⚠️ Points to Consider
127+
128+
-### Implementing ArduinoCore-API
129+
+- After cloning **Arduino_Core_STM32**, run:
130+
+ ```bash
131+
+ git submodule update --init --recursive
132+
+ ```
133+
134+
-In order to compile a core which is implementing ArduinoCore-API you'll need to copy/symlink the `api` directory to the target's `cores/arduino` directory as part of your development and release workflow. The most elegant and effective solution is to develop your core with `api` symlinked and produce the distributable archive by telling `tar` to follow symlinks. Example:
135+
+---
136+
137+
-```bash
138+
-tar --exclude='*.git*' -cjhvf $yourcore-$version.tar.bz2 $yourcore/
139+
-```
140+
+## 📊 Project Information
141+
142+
-The API is coded to the C++11 standard and the core's compiler must be able to support that version of the language.
143+
+| Property | Value |
144+
+|----------|-------|
145+
+| **Type** | fork |
146+
+| **Use Case** | Submodule for STM32duino |
147+
+| **Language** | C/C++ |
148+
+| **License** | LGPL 2.1+ |
149+
+| **Original Repository** | https://github.com/arduino/ArduinoCore-API |
150+
+---
151+
152+
-Documentation for how to integrate with a Arduino core (which is necessary if you do not download the Arduino core via the Boards Manager) can be found here:
153+
-* [ArduinoCore-megaavr](https://github.com/arduino/ArduinoCore-megaavr#developing)
154+
-* [ArduinoCore-mbed](https://github.com/arduino/ArduinoCore-mbed#clone-the-repository-in-sketchbookhardwarearduino-git)
155+
-* [ArduinoCore-samd](https://github.com/arduino/ArduinoCore-samd/#developing)
156+
+## ✨ Quick Start
157+
158+
-## Donations
159+
+### Clone **Arduino_Core_STM32** with this submodule
160+
161+
-This open source code is maintained by Arduino with the help of the community. We invest a considerable amount of time in testing code, optimizing it and introducing new features. Please consider [donating](https://www.arduino.cc/en/donate/) or [sponsoring](https://github.com/sponsors/arduino) to support our work, as well as [buying original Arduino boards](https://store.arduino.cc) which is the best way to make sure our effort can continue in the long term.
162+
+```bash
163+
+git clone --recurse-submodules https://github.com/stm32duino/Arduino_Core_STM32.git
164+
+```
165+
166+
-## License and credits
167+
+### Update submodule
168+
169+
-This code is licensed under the terms of the GNU LGPL 2.1. If you have questions about licensing please contact us at [license@arduino.cc](mailto:license@arduino.cc).
170+
+```bash
171+
+git submodule update --remote
172+
+```
173+
174+
+---
175+
\ No newline at end of file
176+
--
177+
2.51.2.windows.1
178+

0 commit comments

Comments
 (0)