readme update

Author: Your Name

README.md

@@ -14,3 +14,49 @@ This tool acts as a versatile wrapper for OpenOCD (Open On-Chip Debugger), allow
 ## License
 
 This project is licensed under the GPL3 license. See the LICENSE file for details.
+
+## ArduinoCore-Zephyr ecosystem  
+ArduinoCore-Zephyr acts as a wrapper for the Arduino API, implemented using the powerful and flexible APIs of the [Zephyr RTOS](https://www.zephyrproject.org/). This allows developers to write standard Arduino sketches that run on Zephyr-supported hardware.
+
+### How it Works ⚙️
+
+The core translates familiar Arduino functions into their Zephyr equivalents. This translation is resolved at **compile time** based on the selected hardware platform.
+
+For example, the standard Arduino `digitalWrite()` function is implemented using Zephyr's `gpio_pin_set_dt()`:
+
+```cpp
+// From: cores/arduino/zephyrCommon.cpp
+void digitalWrite(pin_size_t pinNumber, PinStatus status) {
+    gpio_pin_set_dt(&arduino_pins[pinNumber], status);
+}
+```
+In Zephyr a platform generally refers to the combination of hardware and architecture that Zephyr can run on.
+
+The `gpio_pin_set_dt` function is part of Zephyr's hardware abstraction layer and is configured specifically for the target board during the build process.
+
+
+### Platforms & Compilation 
+
+In the Zephyr ecosystem, a platform refers to the specific combination of hardware and architecture. This core uses the standard Arduino platform definition format.
+
+For example, the platform for an Arduino UNO Q board (running on an STM32U585xx) is defined as: `arduino:zephyr:unoq`
+
+
+You can compile a sketch for a specific platform using the arduino-cli:
+
+```bash
+arduino-cli compile YourSketch.ino -b arduino:zephyr:unoq
+```
+
+This command compiles the sketch, linking it against the correct Zephyr APIs for the specified board.
+
+### Uploading with remoteocd 
+Uploading the compiled binary to the microcontroller is handled by remoteocd. Instead of relying on hard-coded flash commands, it accepts an OpenOCD configuration file. This allows you to tailor the upload script to specific debugging or flashing requirements.
+ArduinoCore-Zephyr automatically installs remoteocd into the Arduino tools folder during setup.
+
+To upload your compiled sketch, use the following Arduino CLI command:
+
+```bash
+arduino-cli upload YourCompiledSketch -b arduino:zephyr:unoq
+```
+