Skip to content

Commit e33ab59

Browse files
facchinmfacchinm
committed
New readmes
1 parent f66efa8 commit e33ab59

File tree

4 files changed

+149
-37
lines changed

4 files changed

+149
-37
lines changed

Diff for: ‎README.gsoc.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# GSoC 2022 Project: Arduino Core API module for Zephyr
2+
3+
![](https://dhruvag2000.github.io/Blog-GSoC22/assets/images/website_header.png)
4+
5+
The **Arduino Core API** module for zephyr leverages the power of Zephyr under an Arduino-C++ style abtraction layer thus helping zephyr new-comers to start using it without worrying about learning about new APIs and libraries. See the project documentation folder for detailed documentation on these topics:
6+
7+
* [Using external Arduino Libraries](/documentation/arduino_libs.md)
8+
* [Adding custom boards/ variants](/documentation/variants.md)
9+
10+
## Adding Arduino Core API to Zephyr
11+
12+
* **Pre requisites:** It is assumed that you have zephyrproject configured and installed on your system as per the official [Get Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). The recommended path to install is `~/zephyrproject` as specified in the guide. If you have zephyr installed in a custom path you may need to make changes to the CMakeLists.txt file in the sample code directory when building these samples.
13+
14+
* Add following entry to `west.yml` file in `manifest/projects` subtree of Zephyr:
15+
```
16+
# Arduino API repository.
17+
- name: Arduino-Core-Zephyr
18+
path: modules/lib/Arduino-Zephyr-API
19+
revision: main
20+
url: https://github.com/zephyrproject-rtos/gsoc-2022-arduino-core
21+
```
22+
23+
* Then, clone the repository by running
24+
25+
```sh
26+
west update
27+
```
28+
29+
* **Note:** For ***Linux users only*** there exists an ``install.sh`` script in this project that can be run to quickly link the ArduinoCore-API to this module.
30+
If you are able to run that script successfully then you can skip the next steps.
31+
32+
* To "complete" the core you need to copy or symlink the api folder from the [ArduinoCore-API](https://github.com/arduino/ArduinoCore-API.git) repo to the target's ``cores/arduino`` folder:
33+
```sh
34+
$ git clone [email protected]:arduino/ArduinoCore-API # Any location
35+
$ ln -s /<your>/<location>/ArduinoCore-API/api cores/arduino/.
36+
```
37+
The `cores` folder can be found at `~/zephyrproject/modules/lib/Arduino-Zephyr-API/cores`.
38+
39+
**Known Bug(s):**
40+
41+
__NOTE:__ You can skip this step as well if you ran ``install.sh``.
42+
43+
**Maintainers**:
44+
- [DhruvaG2000](https://github.com/DhruvaG2000)
45+
- [soburi](https://github.com/soburi)
46+
- [szczys](https://github.com/szczys)
47+
- [beriberikix](https://github.com/beriberikix)
48+
- [alvarowolfx](https://github.com/alvarowolfx)
49+
50+
## License
51+
Please note that the current license is Apache 2. Previously it was LGPL 2.1 but after careful review it was determined that no LGPL code or derivates was used and the more permissive license was chosen.
52+
53+
**Additional Links**
54+
* [Official Project Blog](https://dhruvag2000.github.io/Blog-GSoC22/)
55+
* Golioth's Article: [Zephyr + Arduino: a Google Summer of Code story](https://blog.golioth.io/zephyr-arduino-a-google-summer-of-code-story/)

Diff for: ‎README.md

+89-37
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,107 @@
1-
# GSoC 2022 Project: Arduino Core API module for Zephyr
1+
# Arduino Core for Zephyr BETA
22

3-
![](https://dhruvag2000.github.io/Blog-GSoC22/assets/images/website_header.png)
3+
This repository contains the official implementation of **Arduino Core** for Zephyr based board.
44

5-
The **Arduino Core API** module for zephyr leverages the power of Zephyr under an Arduino-C++ style abtraction layer thus helping zephyr new-comers to start using it without worrying about learning about new APIs and libraries. See the project documentation folder for detailed documentation on these topics:
5+
Easily install the core and its toolchains via Board Manager using this URL: https://downloads.arduino.cc/packages/package_zephyr_index.json
66

7-
* [Using external Arduino Libraries](/documentation/arduino_libs.md)
8-
* [Adding custom boards/ variants](/documentation/variants.md)
7+
## Theory of operation
98

10-
## Adding Arduino Core API to Zephyr
9+
Unlike every other Arduino implementation (where the final compilation step is a standalone binary, eventually loaded by a bootloader), this one creates a freestanding elf file that can be dynamically loaded by a static (precompiled) Zephyr firmware.
1110

12-
* **Pre requisites:** It is assumed that you have zephyrproject configured and installed on your system as per the official [Get Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). The recommended path to install is `~/zephyrproject` as specified in the guide. If you have zephyr installed in a custom path you may need to make changes to the CMakeLists.txt file in the sample code directory when building these samples.
11+
The most important parts of this project are:
1312

14-
* Add following entry to `west.yml` file in `manifest/projects` subtree of Zephyr:
13+
* [Zephyr based loader](/loader)
14+
* [LLEXT](https://docs.zephyrproject.org/latest/services/llext/index.html)
15+
* [Actual core](/cores/arduino) with [variants](/variants) and the usual `{platform,boards}.txt`
16+
* [ArduinoCore-API](https://github.com/arduino/ArduinoCore-API)
17+
* [post_build_tool](/extra/post_build_tool)
18+
19+
The `loader` project should be kept generic and any modification required for a given board should be added to its dts overlay or a special `fixup` file (with the proper guards).
20+
The loader changes its behaviour based on the `Mode` menu.
21+
`Standard` means that the sketch is loaded automatically, while `Debug` requires the user to type `sketch` in Zephyr's shell (exposed over the default UART).
22+
23+
For the end user, installing the `loader` only requires running `Burn Bootloader` while the board is in bootloader mode (double clicking the RESET button should be do the trick). Due to Arduino IDE limitiations, you must select a bogus programmer from `Programmers` menu.
24+
25+
Loading the first sketch also requires the board to be placed forcefully in bootloader mode. From then on, the usual "autoload" method will kick in.
26+
27+
## Setup the environment
28+
29+
We provide some shell scripts to ease installation (Windows not supported ATM)
30+
On a new terminal, run
1531
```
16-
# Arduino API repository.
17-
- name: Arduino-Core-Zephyr
18-
path: modules/lib/Arduino-Zephyr-API
19-
revision: main
20-
url: https://github.com/zephyrproject-rtos/gsoc-2022-arduino-core
32+
mkdir my_new_zephyr_folder && cd my_new_zephyr_folder
33+
git clone https://github.com/arduino/ArduinoCore-zephyr
34+
cd ArduinoCore-zephyr
35+
./extra/bootstrap.sh
2136
```
2237

23-
* Then, clone the repository by running
38+
Then you need to download and install the Zephyr SDK for your OS from https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.8
2439

25-
```sh
26-
west update
40+
To build a loader, run
41+
```
42+
export ZEPHYR_SDK_INSTALL_DIR=$folder_where_you_installed_the_sdk
43+
./extra/build.sh $zephyr_board_name $arduino_variant_board_name
44+
# eg: ./extra/build.sh arduino_portenta_h7//m7 arduino_portenta_h7
2745
```
46+
The firmwares will be copied to [firmwares](/firmwares) folder.
2847

29-
* **Note:** For ***Linux users only*** there exists an ``install.sh`` script in this project that can be run to quickly link the ArduinoCore-API to this module.
30-
If you are able to run that script successfully then you can skip the next steps.
48+
If the board is fully supported by Zephyr, they can also be directly falshed with `west flash`
3149

32-
* To "complete" the core you need to copy or symlink the api folder from the [ArduinoCore-API](https://github.com/arduino/ArduinoCore-API.git) repo to the target's ``cores/arduino`` folder:
33-
```sh
34-
$ git clone [email protected]:arduino/ArduinoCore-API # Any location
35-
$ ln -s /<your>/<location>/ArduinoCore-API/api cores/arduino/.
36-
```
37-
The `cores` folder can be found at `~/zephyrproject/modules/lib/Arduino-Zephyr-API/cores`.
50+
## Use the core in Arduino environment
51+
52+
After runnign the `bootstrap` script, you should be able to symlink the core to `$sketchbook/hardware/arduino-git/zephyr` and it will appear in the IDE/CLI. Boards FQBN will then become `arduino-git:zephyr:name_from_boards_txt`
53+
54+
## Toubleshooting
55+
56+
**Q: My Sketch doesn't start (Serial doen't appear)**
57+
58+
**A:** Connect a USB-to-UART adapter to the default UART (eg. TX0/RX0 on Giga, TX,RX on Nano) and read the error message
59+
60+
**Q: I did it and I get a `<err> llext: Undefined symbol with no entry in symbol table ...`**
61+
62+
**A:** This means you are trying to use a Zephyr function which has not yet been exported. Open `llext_exports.c`, add the function you need and recompile/upload the loader.
63+
64+
**Q: I want to use a Zephyr subsystem which is not compiled in**
65+
66+
**A:** Open the `.conf` file for your board, add the required `CONFIG_`, recompile/upload the loader.
67+
68+
**Q: I get an OS crash**
69+
70+
**A:** This is usally do to some buffer overflow/coding error in the user's own code. However, since the project is still in Beta, a [good bug report](#bug-reporting) could help identifying an issue in our code.
71+
72+
**Q: I get an out of memory error**
73+
74+
**A:** Since at this point in time collecting bug reports is very important, we are keeping Zephyr's shell enabled and able to load a full sketch (so its stack is very big). Tune your board's `.conf` to reduce that size if your platform down't have enough RAM
75+
76+
## Bug Reporting
77+
78+
To report a bug, open the [issues](/issues) and follow the instructions. Any issue opened without the needed information will be discarded.
79+
80+
## TODO
3881

39-
**Known Bug(s):**
82+
- [ ] Unify overlay in [loader](/loader/boards) with the one provided in [variant](/variant) for interoperability with GSoC project
83+
- [ ] Autogenerate `defines.txt`, `includes.txt`, `cflags.txt` from `llext-edk` output
84+
- [ ] Network: support UDP and TLS
85+
- [ ] USB: switch to USB_DEVICE_STACK_NEXT to support PluggableUSB
86+
- [ ] Relocate RODATA in flash to accomodate sketches with large assets
87+
- [ ] Provide better error reporting for failed llext operations
88+
- [ ] Replace [llext_exports.c](/loader/llext_exports.c) with proper symbols generation (via inclues)
89+
- [ ] Provide better usability for `Debug` builds (eg. shell over USB)
90+
- [ ] Fix corner cases with `std::` includes (like `<iterator>`)
4091

41-
__NOTE:__ You can skip this step as well if you ran ``install.sh``.
92+
## ADVANCED: Add a new target board
4293

43-
**Maintainers**:
44-
- [DhruvaG2000](https://github.com/DhruvaG2000)
45-
- [soburi](https://github.com/soburi)
46-
- [szczys](https://github.com/szczys)
47-
- [beriberikix](https://github.com/beriberikix)
48-
- [alvarowolfx](https://github.com/alvarowolfx)
94+
* To add a new board (already supported by mainline Zephyr), you'll first need to create its `dts overlay` and `.conf` in [loader](/loader/boards).
95+
The overlay MUST contains:
96+
* A flash partition called `user_sketch`, usually near the end of the flash
97+
* A `zephyr,user` section containing the description for GPIOs, Analog, UART, SPI and I2C devices. Feel free to leave some fields empty in case Zephyr support is missing. This will result in some APIs not being available at runtime (eg. `analogWrite` if PWM section is empty)
98+
* Run `./extra.build.sh $your_board $your_board` and start debugging the errors :grin:
99+
* Add an entry in `boards.txt` for your board, manually filling the required fields
100+
* If your boards supports `1200pbs touch` method, implement `_on_1200_bps` in a file inside `variant/your_board` folder
101+
* Temporary: create `includes.txt` based on `llext-edk/Makefile.cflags`, taking inspiration for other variants
102+
* Temporary: amend `your_board.compiler.zephyr.*` with information from `llext-edk/Makefile.cflags`
103+
* Profit!
49104

50-
## License
51-
Please note that the current license is Apache 2. Previously it was LGPL 2.1 but after careful review it was determined that no LGPL code or derivates was used and the more permissive license was chosen.
105+
## Acknowledgments
52106

53-
**Additional Links**
54-
* [Official Project Blog](https://dhruvag2000.github.io/Blog-GSoC22/)
55-
* Golioth's Article: [Zephyr + Arduino: a Google Summer of Code story](https://blog.golioth.io/zephyr-arduino-a-google-summer-of-code-story/)
107+
This effort would have been very hard without the [GSoC project](/README.gsoc.md) and in general the Zephyr community.

Diff for: ‎extra/bootstrap.sh

+1
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ source venv/bin/activate
1010
pip install west
1111
west init -l .
1212
west update
13+
pip install -r ../zephyr/scripts/requirements-base.txt
1314
# download slim toolchain from https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.8

Diff for: ‎extra/build.sh

+4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1+
if [ $ZEPHYR_SDK_INSTALL_DIR == "" ]; then
12
export ZEPHYR_SDK_INSTALL_DIR=/ssd/zephyr-sdk-0.16.8/
3+
fi
24

35
set -e
46

@@ -10,6 +12,8 @@ board=arduino_giga_r1//m7
1012
variant=arduino_giga_r1_m7
1113
fi
1214

15+
source venv/bin/activate
16+
1317
(west build loader -b $board -p && west build -t llext-edk)
1418
(tar xvfp build/zephyr/llext-edk.tar.xz --directory variants/$variant/)
1519
(cp build/zephyr/zephyr.elf firmwares/zephyr-$variant.elf)

0 commit comments

Comments
 (0)