Final draft

- added all examples (and tested)
- added API

Author: karlsoderby

content/micropython/00.first-steps/03.runtime-package/assets/connect-device.png

@@ -1,12 +1,12 @@
 ---
-title: 'Arduino Style MicroPython'
-description: 'Learn how to use the runtime package, which allows you to write MicroPython code, Arduino style.'
-author: 'Karl Söderby'
+title: "Arduino MicroPython Runtime"
+description: "Learn how to use the Arduino MicroPython runtime package, which allows you to write MicroPython code in a familiar Arduino style."
+author: "Karl Söderby"
 tags: [MicroPython, Runtime]
 micropython_type: test
 ---
 
-The [Arduino Runtime Package]() is a MicroPython package that allows you to write and program your board using the classic `setup()` and `loop()` constructs.
+The [Arduino Runtime Package](https://github.com/arduino/arduino-runtime-mpy/tree/main) is a MicroPython package that allows you to write and program your board using the classic `setup()` and `loop()` constructs.
 
 The package was designed to make it easier to create programs, particularly for those familiar with the Arduino C++ environment.
 
@@ -28,19 +28,19 @@ To follow this tutorial, you will need to have the following requirements ticked
 
 ## Installation
 
-To use the runtime library, we will need to install it first.
+To use the runtime package, we will need to install it first.
 
-1. Download and install the [Arduino MicroPython Package Installer](https://labs.arduino.cc/en/labs/micropython-package-installer). 
+1. Download and install the [Arduino MicroPython Package Installer](https://labs.arduino.cc/en/labs/micropython-package-installer).
 2. Connect your board to your computer.
 3. Run the tool. In the tool, you should now see your board connected.
 
-    ![Board connected.]()
+   ![Board connected.](assets/connect-device.png)
 
 4. After verifying that your board is connected, click on the search field, and search for **runtime**. Install the package.
 
-    ![Install the package.]()
+   ![Install the package.](assets/install-package.png)
 
-5. When the installation is complete, we are ready to use the library.
+5. When the installation is complete, we are ready to use the package.
 
 ## Basic Example
 
@@ -64,6 +64,7 @@ start(setup, loop)
 ```
 
 This program has two main functions: `setup()` and `loop()`. If you are unfamiliar with this concept, here's how it works:
+
 - `setup()` - this function will run just once, at the start of a program. Like in this example, we use `print('starting my program')`.
 - `loop()` - this function will continue to run, until you disrupt the program by disconnecting the board or stopping the script.
 
@@ -75,16 +76,23 @@ At the bottom of the program, we have something called `start()`. This function
 
 Arduino Runtime was created to simplify the code creation when programming in MicroPython, providing a more user-friendly syntax that allows you to understand the programs you create a bit better.
 
-Now that we have everything installed, and our basic example tested out, let's take a look at some of the more common examples. 
+Now that we have everything installed, and our basic example tested out, let's take a look at some of the more common examples.
 
-***A list of commands are listed [later in this article](). You can also view the [source code on Github]() for further understanding.***
+***The API is listed at [the end of this article](#runtime-api). You can also view the [source code on GitHub](https://github.com/arduino/arduino-runtime-mpy/tree/main) for further understanding.***
 
 ### Pin Mode
 
 - `pin_mode(pin, mode)`
 
 Configures a pin as an input or an output.
 
+```python
+pin = "D6"
+
+def setup():
+  pin_mode(pin, OUTPUT)
+```
+
 ### Analog Read
 
 - `analog_read(pin)`
@@ -113,7 +121,7 @@ To write an analog signal (using PWM), we can use the `analog_write()` method. T
 The example below sets the pin to "half capacity", and if you connect an LED to this pin, it will shine at half brightness.
 
 ```python
-pin = "D6"
+pin = "LED_BUILTIN"
 brightness = 127 #half brightness
 
 def setup():
@@ -132,11 +140,13 @@ start(setup, loop)
 Reads a digital pin and returns a HIGH (1) or LOW (0) value.
 
 ```python
+pin = "D2"
+
 def setup():
     print("Digital Read Example")
 
 def loop():
-    value = digital_read("D2")
+    value = digital_read(pin)
     print(value)
 
 start(setup, loop)
@@ -146,15 +156,16 @@ start(setup, loop)
 
 - `digital_write(pin)`
 
-Writes a HIGH (1) or LOW (0) value to a digital pin.
+Writes a **HIGH (1)** or **LOW (0)** value to a digital pin.
 
 ```python
+pin = "LED_BUILTIN"
+
 def setup():
     print("Digital Write Example")
 
 def loop():
-    digital_write("D2")
-    
+    digital_write(pin, HIGH)
 
 start(setup, loop)
 ```
@@ -163,12 +174,12 @@ start(setup, loop)
 
 - `delay(time)`
 
-Freezes the program for the duration specified in *microseconds*.
+Freezes the program for the duration specified in _microseconds_.
 
 Below is a demonstration of the classic blink example:
 
 ```python
-led = "D13"
+led = "LED_BUILTIN"
 
 def setup():
     print("Delay Example")
@@ -179,21 +190,178 @@ def loop():
     delay(1000)
     digital_write(led, LOW)
     delay(1000)
-    
+
 start(setup, loop)
 ```
 
-## Runtime Specific Examples
+## Runtime API
+
+The API for the runtime package can be found below. See the table for a quick overview:
+
+| Function            | Description                                    | Parameters                                                    | Returns                  | Alias            |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------------- | ------------------------ | ---------------- |
+| `start`             | Begins main loop with hooks                    | `preload`, `setup`, `loop`, `cleanup`                         | None                     | None             |
+| `map_float`         | Maps a value from one range to another (float) | `x`, `in_min`, `in_max`, `out_min`, `out_max`                 | Mapped value (float/int) | None             |
+| `map_int`           | Maps a value from one range to another (int)   | Same as `map_float`                                           | Mapped value (int)       | None             |
+| `random`            | Generates a pseudo-random integer              | `low`, `high` (optional)                                      | Random integer           | None             |
+| `constrain`         | Clamps value within min and max                | `val`, `min_val`, `max_val`                                   | Clamped value            | None             |
+| `lerp`              | Linear interpolation between two values        | `start`, `stop`, `amount`                                     | Interpolated value       | None             |
+| `pin_mode`          | Sets GPIO pin mode                             | `pin`, `mode`                                                 | Configured `Pin` object  | `pinMode()`      |
+| `digital_write`     | Writes digital value to a pin                  | `pin`, `state`                                                | None                     | `digitalWrite()` |
+| `digital_read`      | Reads digital state from a pin                 | `pin`                                                         | `0` or `1`               | `digitalRead()`  |
+| `analog_read`       | Reads analog value from a pin                  | `pin`                                                         | 0–65535                  | `analogRead()`   |
+| `analog_write`      | Writes PWM duty cycle to a pin                 | `pin`, `duty_cycle` (0–255)                                   | None                     | `analogWrite()`  |
+| `delay`             | Pauses execution in milliseconds               | `ms`                                                          | None                     | None             |
+| `get_template_path` | Gets path to default sketch template           | None                                                          | Template path (string)   | None             |
+| `create_sketch`     | Creates new sketch from template               | `sketch_name`, `destination_path`, `overwrite`, `source_path` | Created sketch path      | None             |
+| `copy_sketch`       | Copies existing sketch to new location         | `source_path`, `destination_path`, `name`, `overwrite`        | Copied sketch path       | None             |
+
+### start(setup=None, loop=None, cleanup=None, preload=None)
+
+Begins the main execution loop, calling user-defined hooks.
+
+- **Parameters:**
+  - `preload`: Function run once before setup.
+  - `setup`: Initialization function.
+  - `loop`: Function called repeatedly in a loop.
+  - `cleanup`: Function called on exception or interrupt.
+- **Returns:** None.
+- **Alias:** None.
+
+### map_float(x, in_min, in_max, out_min, out_max)
+
+Maps a numeric value from one range to another, allowing floating-point output.
+
+- **Parameters:**
+  - `x`: Input value to map.
+  - `in_min`: Lower bound of input range.
+  - `in_max`: Upper bound of input range.
+  - `out_min`: Lower bound of output range.
+  - `out_max`: Upper bound of output range.
+- **Returns:** The mapped value (float or int).
+- **Alias:** None.
+
+### map_int(x, in_min, in_max, out_min, out_max)
+
+Maps a numeric value from one range to another and returns an integer.
+
+- **Parameters:** same as `map_float`.
+- **Returns:** The mapped value as int.
+- **Alias:** None.
+
+### random(low, high=None)
+
+Generates a pseudo-random integer within a specified range.
+
+- **Parameters:**
+  - `low`: If `high` is `None`, acts as upper bound (exclusive); otherwise, lower bound (inclusive).
+  - `high` (optional): Upper bound (exclusive).
+- **Returns:** A random integer in the computed range.
+- **Alias:** None.
+
+### constrain(val, min_val, max_val)
+
+Clamps a value to lie within a specified minimum and maximum.
+
+- **Parameters:**
+  - `val`: Value to clamp.
+  - `min_val`: Minimum allowable value.
+  - `max_val`: Maximum allowable value.
+- **Returns:** The clamped value.
+- **Alias:** None.
+
+### lerp(start, stop, amount)
+
+Performs linear interpolation between two numeric values.
+
+- **Parameters:**
+  - `start`: Start value.
+  - `stop`: End value.
+  - `amount`: Interpolation factor (0.0 = `start`, 1.0 = `stop`).
+- **Returns:** The interpolated value.
+- **Alias:** None.
+
+### pin_mode(pin, mode)
+
+Configures a GPIO pin mode.
+
+- **Parameters:**
+  - `pin`: Pin identifier or number.
+  - `mode`: `INPUT` or `OUTPUT`.
+- **Returns:** Configured `Pin` object.
+- **Alias:** `pinMode()`.
+
+### digital_write(pin, state)
+
+Writes a digital state to a pin configured as output.
+
+- **Parameters:**
+  - `pin`: Pin number.
+  - `state`: `HIGH` or `LOW`.
+- **Returns:** None.
+- **Alias:** `digitalWrite()`.
+
+### digital_read(pin)
+
+Reads a digital state from a pin configured as input.
+
+- **Parameters:**
+  - `pin`: Pin number.
+- **Returns:** `0` or `1`.
+- **Alias:** `digitalRead()`.
+
+### analog_read(pin)
+
+Reads a 16-bit ADC value from a pin.
+
+- **Parameters:**
+  - `pin`: Pin number.
+- **Returns:** Integer between 0 and 65535.
+- **Alias:** `analogRead()`.
+
+### analog_write(pin, duty_cycle)
+
+Writes a PWM duty cycle (0–255) to a pin.
+
+- **Parameters:**
+  - `pin`: Pin number.
+  - `duty_cycle`: 0–255 duty value.
+- **Returns:** None.
+- **Alias:** `analogWrite()`.
+
+### delay(ms)
+
+Pauses execution for a specified number of milliseconds.
+
+- **Parameters:**
+  - `ms`: Milliseconds to sleep.
+- **Returns:** None.
+- **Alias:** None.
+
+### get_template_path()
+
+Retrieves the filesystem path to the default sketch template.
 
-Below are some methods that are introduced with the runtime package.
+- **Parameters:** none.
+- **Returns:** Template file path (string).
+- **Alias:** None.
 
-### Start
+### create_sketch(sketch_name=None, destination_path='.', overwrite=False, source_path=None)
 
-- `start(setup, loop, cleanup)`
+Generates a new sketch file from a template.
 
-Starts the program, first by running the `setup()` function, the `loop()` function and finally the `cleanup()` function. 
+- **Parameters:**
+  - `sketch_name` (optional): Desired filename without extension.
+  - `destination_path` (optional): Directory to create the sketch in.
+  - `overwrite` (optional): Overwrite existing file if `True`.
+  - `source_path` (optional): Custom template path.
+- **Returns:** Path to the created sketch file.
+- **Alias:** None.
 
-The `cleanup()` function is optional.
+### copy_sketch(source_path='', destination_path='.', name=None, overwrite=False)
 
-### Cleanup
+Duplicates an existing sketch file to a new location/name.
 
+- **Parameters:** same as `create_sketch` except uses existing source file.
+- **Returns:** Path to the copied sketch.
+- **Alias:** None.