fix core EC

README.md

@@ -1,83 +1,116 @@
-# Electronic Cats Arduino Core for mbed enabled devices
+# Arduino Core for mbed enabled devices
 
 The repository contains the Arduino APIs and IDE integration files targeting a generic mbed-enabled board
 
-## Features Electronic Cats version Vs Arduino Original version
+## FAQ
+### Source-Code Level Debugging
+**Question**: "I want to debug my ArduinoCore-mbed based sketch using traditional debugging tools, i.e. gdb via SWD interface. However, the debugger is unable to locate the sources for all files, particular the mbed-os files."
 
-- Support for [Adafruit Bootloader UF2](https://github.com/ElectronicCats/Adafruit_nRF52_Bootloader) only MBR Bootloader (Unsupport SoftDevice)
-- Upload firmware via [adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil)
+**Answer**: This is due to the fact that we pre-compile the mbed-os code into a static library `libmbed.a`. Information on how to recompile `libmbed.a` for source code debugging can be found [here](#recompiling-libmbed-with-source-level-debug-support). The [Arduino Documentation](https://docs.arduino.cc/) also contains articles explaining how to debug via [Segger J-Link](https://docs.arduino.cc/tutorials/portenta-breakout/breakout-jlink-setup) and [Lauterbach TRACE32](https://docs.arduino.cc/tutorials/portenta-h7/lauterbach-debugger).
 
-## Nice features from Arduino
+## Installation
 
-- Based in Arduino mbedOS
-- Support library [ArduinoBLE](https://github.com/arduino-libraries/ArduinoBLE)
-- Support Library Arduino Tensorflow Lite
+### Clone the repository in `$sketchbook/hardware/arduino-git`
 
-##  Easy Install
+```bash
+mkdir -p $sketchbook/hardware/arduino-git
+cd $sketchbook/hardware/arduino-git
+git clone [email protected]:arduino/ArduinoCore-mbed mbed
+```
+
+### Clone https://github.com/arduino/ArduinoCore-API into a directory of your choice.
 
-To add board support for our products, start Arduino and open the Preferences window (**File** > **Preferences**). Now copy and paste the following URL into the 'Additional Boards Manager URLs' input field:
+```bash
+git clone [email protected]:arduino/ArduinoCore-API
+```
 
-	https://electroniccats.github.io/Arduino_Boards_Index/package_electroniccats_index.json
+### Update the `api` symlink
 
+Create a symlink to `ArduinoCore-API/api` in `$sketchbook/hardware/arduino-git/mbed/cores/arduino`.
 
-- If there is already an URL from another manufacturer in that field, click the button at the right end of the field. This will open an editing window allowing you to paste the above URL onto a new line.
+### Test things out
 
-- Press the "OK" button.
-- Open the "boards manager" that is in tools --> Board --> board manager.
-- Now write "Electronic Cats" (without quotes) in the search bar.
-- Click in install, jus wait to finish to install and only close the window. 
+Open the Arduino IDE.
 
+You should now see three new targets under the `MBED boards` label.
 
-## Manual Installation
+*This procedure does not automatically install the required ARM compiler toolchain.*
 
-Clone the repository in `$sketchbook/hardware/arduino`
+If the toolchain is missing, you'll see errors like this when you try to build for an mbed-os enabled board.:
 
-```bash
-mkdir -p $sketchbook/hardware/arduino
-cd $sketchbook/hardware/arduino
-git clone [email protected]:arduino/ArduinoCore-mbed mbed
 ```
+fork/exec /bin/arm-none-eabi-g++: no such file or directory
+```
+To install ARM build tools, use the `Boards Manager` option in the Arduino IDE to add the `Arduino mbed-enabled Boards` package.
 
-Then clone https://github.com/arduino/ArduinoCore-API in a directory at your choice. Checkout `namespace_arduino` branch.
+## mbed-os-to-arduino script
 
-```bash
-git clone [email protected]:arduino/ArduinoCore-API -b namespace_arduino
+The backbone of the packaging process is the https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino script. It basically compiles a blank Mbed OS project for any supported target board, recovering the files that will be needed at compile time and copying them to the right location.
+
+It can be used for a variety of tasks including:
+
+### Recompiling libmbed with source level debug support
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+./mbed-os-to-arduino -a -g PORTENTA_H7_M7:PORTENTA_H7_M7
 ```
 
-Remove the symlink to `api` you can find in  `$sketchbook/hardware/arduino/mbed/cores/arduino` and replace it with a symlink to `ArduinoCore-API/api`
+In this case `-a` applies all the patches from `patches` folder into a mainline `mbed-os` tree, and `-g` restores the debug info.
 
-Open Arduino IDE; you should now see three new targets under `MBED boards` label
+### Selecting a different optimization profile
 
-## Supported boards
+```
+cd $sketchbook/hardware/arduino-git/mbed
+PROFILE=release ./mbed-os-to-arduino -a NANO_RP2040_CONNECT:NANO_RP2040_CONNECT
+```
 
- * [BastBLE low cost development board](https://www.electroniccats.com)
- * [Arduino Nano 33 BLE ](https://store.arduino.cc/usa/nano-33-ble-sense)
+The `PROFILE` environment variable tunes the compilation profiles (defaults to `DEVELOP`). Other available profiles are `DEBUG` and `RELEASE`.
 
-## Adding an mbed target
+### Selecting a different Mbed OS tree
 
-Adding a target is a mostly automatic procedure that involves running https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino after setting `BOARDNAME` and `ARDUINOCORE` env variables.
-Actions marked as TODO must be executed manually.
+```
+cd $sketchbook/hardware/arduino-git/mbed
+./mbed-os-to-arduino -r /path/to/my/mbed-os-fork NICLA_VISION:NICLA_VISION
+```
+
+`-r` flag allows using a custom `mbed-os` fork in place of the mainline one; useful during new target development.
+
+### Adding a new target ([core variant](https://arduino.github.io/arduino-cli/latest/platform-specification/#core-variants))
 
-**Minimum Example**: `./mbed-os-to-arduino -r /home/alex/projects/arduino/cores/mbed-os-h747 ENVIE_M7:ENVIE_M7`
+Adding a target is a mostly automatic procedure.
 
-### How to build a debug version of the Arduino mbed libraries
-* Modify `mbed-os-to-arduino `
-```diff
-mbed_compile () {
--       PROFILE_FLAG=""
-        if [ x"$PROFILE" != x ]; then
-                PROFILE_FLAG=--profile="$ARDUINOVARIANT"/conf/profile/$PROFILE.json
-                export PROFILE=-${PROFILE^^}
-+       else
-+               export PROFILE="-DEBUG"
-+               PROFILE_FLAG="--profile=debug"
-        fi
+For boards already supported by Mbed OS, the bare minimum is:
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$ALREADY_SUPPORTED_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino $ALREADY_SUPPORTED_BOARD_NAME:$ALREADY_SUPPORTED_BOARD_NAME
+# for example, to create a core for LPC546XX
+# mkdir -p variants/LPC546XX/{libs,conf}
+# ./mbed-os-to-arduino LPC546XX:LPC546XX
 ```
 
+This will produce almost all the files needed. To complete the port, add the board specifications to [`boards.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt) (giving it a unique ID) and provide `pins_arduino.h` and `variants.cpp` in `variants/$ALREADY_SUPPORTED_BOARD_NAME` folder.
+Feel free to take inspirations from the existing variants :)
+
+For boards not supported by mainline Mbed OS, the same applies but you should provide the path of your Mbed OS fork
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$BRAND_NEW_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino -r /path/to/mbed-os/fork/that/supports/new/board $BRAND_NEW_BOARD_NAME:$BRAND_NEW_BOARD_NAME
+```
+
+### Customizing Mbed OS build without modifying the code
+
+Most Mbed OS defines can be tuned using a project file called `mbed_app.json` . In case you need to tune a build you can add that file to your variant's `conf` folder. One example is https://github.com/arduino/ArduinoCore-mbed/blob/master/variants/PORTENTA_H7_M7/conf/mbed_app.json .
+Providing an invalid json or replacing a non-existing property will make the build fail silently, so it's always better to validate that file with a standard Mbed OS project.
+
+
 ## Using this core as an mbed library
 
 You can use this core as a standard mbed library; all APIs are under `arduino` namespace (so they must be called like `arduino::digitalWrite()` )
 
 The opposite is working as well; from any sketch you can call mbed APIs by prepending `mbed::` namespace.
 
-