diff --git a/content/micropython/00.first-steps/03.runtime-package/assets/connect-device.png b/content/micropython/00.first-steps/03.runtime-package/assets/connect-device.png new file mode 100644 index 0000000000..5047c4e0e7 Binary files /dev/null and b/content/micropython/00.first-steps/03.runtime-package/assets/connect-device.png differ diff --git a/content/micropython/00.first-steps/03.runtime-package/assets/install-package.png b/content/micropython/00.first-steps/03.runtime-package/assets/install-package.png new file mode 100644 index 0000000000..c3cc07673e Binary files /dev/null and b/content/micropython/00.first-steps/03.runtime-package/assets/install-package.png differ diff --git a/content/micropython/00.first-steps/03.runtime-package/runtime-package.md b/content/micropython/00.first-steps/03.runtime-package/runtime-package.md new file mode 100644 index 0000000000..a2ce4d2683 --- /dev/null +++ b/content/micropython/00.first-steps/03.runtime-package/runtime-package.md @@ -0,0 +1,367 @@ +--- +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](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. + +In this tutorial, you will learn how the package works, along with a set of examples that will get you started. + +## Requirements + +To follow this tutorial, you will need to have the following requirements ticked: + +### Hardware Requirements + +- [A MicroPython compatible board](/micropython/first-steps/install-guide/#micropython-compatible-arduino-boards) (in this tutorial, we will be using an [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32)) +- MicroPython installed on your board (see [installation instructions for MicroPython](/micropython/first-steps/install-guide/)). + +### Software Requirements + +- [Arduino Lab for Micropython](https://labs.arduino.cc/en/labs/micropython) - an editor where we can create and run MicroPython scripts on an Arduino board. +- [Arduino MicroPython Package Installer](https://labs.arduino.cc/en/labs/micropython-package-installer) - for installing **MicroPython packages** on an Arduino board. + +## Installation + +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). +2. Connect your board to your computer. +3. Run the tool. In the tool, you should now see your 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.](assets/install-package.png) + +5. When the installation is complete, we are ready to use the package. + +## Basic Example + +We will begin by one of the most known example: blinking an LED. Let's take a look at the code example below: + +```python +from arduino import * + +led = 'LED_BUILTIN' +def setup(): + print('starting my program') + +def loop(): + print('loopy loop') + digital_write(led, HIGH) + delay(500) + digital_write(led, LOW) + delay(500) + +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. + +Inside of the functions, you can see that we are using `digital_write(led, HIGH)`. This is a function that will enable a pin on the board, and write it high (or low). Since we configured it at the top as `'LED_BUILTIN'`, we will control that LED on the board. + +At the bottom of the program, we have something called `start()`. This function will launch the program and concurrently run the `loop()` function. + +## Common Examples + +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. + +***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)` + +Analog read is a classic example where you read the voltage from an analog pin. + +```python +pin = "A0" + +def setup(): + print("Analog Read Example") + +def loop(): + value = analog_read(pin) + print(value) + +start(setup, loop) +``` + +### Analog Write (PWM) + +- `analog_write(pin, duty_cycle)` + +To write an analog signal (using PWM), we can use the `analog_write()` method. This function takes a `pin` and the `duty_cycle` (0-255) as input. + +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 = "LED_BUILTIN" +brightness = 127 #half brightness + +def setup(): + print("Analog Write Example") + +def loop(): + analog_write(pin, brightness) + +start(setup, loop) +``` + +### Digital Read + +- `digital_read(pin)` + +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(pin) + print(value) + +start(setup, loop) +``` + +### Digital Write + +- `digital_write(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(pin, HIGH) + +start(setup, loop) +``` + +### Delay + +- `delay(time)` + +Freezes the program for the duration specified in _microseconds_. + +Below is a demonstration of the classic blink example: + +```python +led = "LED_BUILTIN" + +def setup(): + print("Delay Example") + pin_mode(led, OUTPUT) + +def loop(): + digital_write(led, HIGH) + delay(1000) + digital_write(led, LOW) + delay(1000) + +start(setup, loop) +``` + +## 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. + +- **Parameters:** none. +- **Returns:** Template file path (string). +- **Alias:** None. + +### create_sketch(sketch_name=None, destination_path='.', overwrite=False, source_path=None) + +Generates a new sketch file from a template. + +- **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. + +### copy_sketch(source_path='', destination_path='.', name=None, overwrite=False) + +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. \ No newline at end of file