Jul 8, 2022 · Jul 7, 2022
diff --git a/README.md b/README.md
 [![codecov](https://codecov.io/gh/arduino/ArduinoCore-API/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/ArduinoCore-API)
 [![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)

 This repository hosts the hardware independent layer of Arduino core.
 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.

 AllArduinoofficialcoresare being ported tothenew structure so they take advantage of this single repo.
 Having a single place where theArduinoAPI 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 othercoresutilise. This has the pleasant side effects that bugs fixed or features added withintheArduinoCore-API String implementation are automatically propagated to all cores utilizing ArduinoCore-API.

 Including this repo in your existing Arduino core will allow the language to grow and include new features.
 For backwards compatibility, every revision of this repo will increase the `ARDUINO_API_VERSION` define.
 As of now, the following official cores are utilising ArduinoCore-API:

 Some cores have been ported to the new structure, for example:
 * megaAVR (https://github.com/arduino/ArduinoCore-megaAVR)
 * nRF52-mbedos (https://github.com/arduino/ArduinoCore-nRF528x-mbedos)
 * classic AVR (https://github.com/arduino/ArduinoCore-avr/tree/api)
 * SAMD (https://github.com/arduino/ArduinoCore-samd)
 * [megaavr](https://github.com/arduino/ArduinoCore-megaAVR)
 * [mbed](https://github.com/arduino/ArduinoCore-mbed)
 * [samd](https://github.com/arduino/ArduinoCore-samd)

 These repositories **don't** containtheneeded `api` subfolder;to"complete" thecore you needtocopy or symlink the`api` folder fromthis repotothetarget's `cores/arduino` folder.
 There's an ongoing effort to porttheothers, while maintainers of third-party cores are strongly invitedtofollow thesame route in ordertostay up-to-date with thenew language features. For backwards compatibility, every revision ofthis repowill increasethe`ARDUINO_API_VERSION` define.

 ### Porting tips
 ## Documentation

 In the future, core APIs will be updated independently from the core, so all the compatible cores will seamlessly adopt new features.
 This requires support from all the IDEs, so in the meantime we suggest to release the core by copying a snapshot of this `api` folder.
 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.

 ## Support

 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).

 ## Development

 ### Bugs & Issues

 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:

 * If your issue is about a specific hardware platform, report it to its repository. This one is only about discussing the generic API.
 * Before posting, please check if the same problem has been already reported by someone else to avoid duplicates.
 * 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.

 ### Contributions

 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.

 ### Unit testing

 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.

 Please help us improve the coverage of the test suite!

 ### Implementing ArduinoCore-API

 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:

 The most elegant and effective solution is to develop the core with `api` symlinked and produce the distributable archive by telling `tar` to follow symlinks.
 Example command:
 ```
 tar --exclude='*.git*' -cjhvf $yourcore-$version.tar.bz2 $yourcore/
 ```

 ## Donations

 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.

 ## License and credits

 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).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,28 +4,59 @@
		[![codecov](https://codecov.io/gh/arduino/ArduinoCore-API/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/ArduinoCore-API)
		[![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)

		This repository hosts the hardware independent layer of Arduino core.
		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.

		AllArduinoofficialcoresare being ported tothenew structure so they take advantage of this single repo.
		Having a single place where theArduinoAPI 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 othercoresutilise. This has the pleasant side effects that bugs fixed or features added withintheArduinoCore-API String implementation are automatically propagated to all cores utilizing ArduinoCore-API.

		Including this repo in your existing Arduino core will allow the language to grow and include new features.
		For backwards compatibility, every revision of this repo will increase the `ARDUINO_API_VERSION` define.
		As of now, the following official cores are utilising ArduinoCore-API:

		Some cores have been ported to the new structure, for example:
		* megaAVR (https://github.com/arduino/ArduinoCore-megaAVR)
		* nRF52-mbedos (https://github.com/arduino/ArduinoCore-nRF528x-mbedos)
		* classic AVR (https://github.com/arduino/ArduinoCore-avr/tree/api)
		* SAMD (https://github.com/arduino/ArduinoCore-samd)
		* [megaavr](https://github.com/arduino/ArduinoCore-megaAVR)
		* [mbed](https://github.com/arduino/ArduinoCore-mbed)
		* [samd](https://github.com/arduino/ArduinoCore-samd)

		These repositories don't containtheneeded `api` subfolder;to"complete" thecore you needtocopy or symlink the`api` folder fromthis repotothetarget's `cores/arduino` folder.
		There's an ongoing effort to porttheothers, while maintainers of third-party cores are strongly invitedtofollow thesame route in ordertostay up-to-date with thenew language features. For backwards compatibility, every revision ofthis repowill increasethe`ARDUINO_API_VERSION` define.

		### Porting tips
		## Documentation

		In the future, core APIs will be updated independently from the core, so all the compatible cores will seamlessly adopt new features.
		This requires support from all the IDEs, so in the meantime we suggest to release the core by copying a snapshot of this `api` folder.
		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.

		## Support

		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).

		## Development

		### Bugs & Issues

		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:

		* If your issue is about a specific hardware platform, report it to its repository. This one is only about discussing the generic API.
		* Before posting, please check if the same problem has been already reported by someone else to avoid duplicates.
		* 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.

		### Contributions

		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.

		### Unit testing

		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.

		Please help us improve the coverage of the test suite!

		### Implementing ArduinoCore-API

		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:

		The most elegant and effective solution is to develop the core with `api` symlinked and produce the distributable archive by telling `tar` to follow symlinks.
		Example command:
		```
		tar --exclude='.git' -cjhvf $yourcore-$version.tar.bz2 $yourcore/
		```

		## Donations

		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.

		## License and credits

		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).