Merge branch 'content/micropython/micropython-revamp' of https://github.com/arduino/docs-content into content/micropython/micropython-revamp

Author: pedromsousalima

content/micropython/03.micropython/02.enviroment/02.file-system/file-system.md

@@ -0,0 +1,134 @@
+---
+title: 'File System'
+description: 'Learn how to use the File Sytem in MicroPython.'
+author: 'Pedro Lima'
+tags: [MicroPython, REPL]
+---
+
+
+When working with MicroPython, we’re not limited to a single program like in traditional Arduino sketches. Instead, MicroPython provides a file system, enabling us to store and manage multiple files on our microcontroller. This opens up powerful capabilities for organizing code, managing assets, and creating modular projects.
+
+In this article, we’ll explore how the MicroPython file system works, how to organize files effectively, and the typical structure of MicroPython projects.
+
+## The MicroPython File System: Key Differences
+
+In traditional Arduino programming, we upload a single compiled file directly to the microcontroller, where it runs immediately. With MicroPython, however, we work within a file system that can store multiple files. This file system allows us to:
+
+- **Upload and Download Files**: We can save individual scripts, libraries, and assets directly on the device.
+- **Organize Project Files**: Create folders, save multiple scripts, and organize files for a modular approach.
+- **Edit Files Directly on the Device**: Modify files without needing to overwrite everything, making adjustments faster and more flexible.
+
+## Accessing the MicroPython File System
+
+To interact with the MicroPython file system, we’ll use Arduino Labs for MicroPython, which provides tools to manage and view files directly on our device. Here’s how to get started:
+
+1. **Connect to Your Device**: Open Arduino Labs for MicroPython and establish a connection to our microcontroller.
+2. **Upload and Download Files**: Use the file manager to upload files from our computer to the microcontroller or download files back to our computer.
+3. **Organize Files**: We can create folders and store multiple files, making it easy to organize our project.
+
+## Basic MicroPython File Structure
+
+A typical MicroPython project includes a main file, boot script, libraries, and any supporting files our project needs. Here’s a standard layout:
+
+```
+/ (Root Directory)
+├── boot.py
+├── main.py
+```
+
+### Key Files
+
+- **`boot.py`**: Runs once at startup, before `main.py`, and is typically used for system configurations that need to be set when the device first powers on.
+- **`main.py`**: This is the primary script, similar to the `setup()` and `loop()` structure in Arduino. It runs automatically after `boot.py` finishes.
+
+## Example: Switching Execution from `main.py` to `favorite_things.py`
+
+Let’s say we’re creating a project where `main.py` runs and, at a certain point, hands off control to `favorite_things.py` to perform a specific task. Here’s how we might organize it.
+
+1. **Write the Main Script** (`main.py`): This script runs some initial code and then switches to executing `favorite_things.py`.
+2.Create the file "favourite_things.py".
+3. **Add Content to `favorite_things.py`**: In this case, we’ll simply print a message from `favorite_things.py`.
+
+### Sample `main.py` Code
+
+Here’s how `main.py` might look, printing an introductory message and then executing `favorite_things.py`:
+
+```python
+def main():
+    print("Getting the list of my favourite things...")
+    
+    # Now execute favorite_things.py
+    print("Switch to favorite_things.py...")
+    try:
+        with open("favorite_things.py") as f:
+            exec(f.read())
+    except OSError:
+        print("Error: Could not open favorite_things.py")
+
+if __name__ == "__main__":
+    main()
+```
+
+### Sample `favorite_things.py` Code
+
+In `favorite_things.py`, we’ll keep it simple with a message:
+
+```python
+# favorite_things.py
+print("Bears. Beets. Battlestar Galactica.")
+```
+
+### Explanation
+
+- **Switching Execution**: `main.py` starts by printing an introductory message, and then uses `exec(f.read())` to read and run the content of `favorite_things.py`.
+- **Running Another Script**: The `exec()` function allows `main.py` to execute `favorite_things.py` as if it were part of `main.py`, printing “Bears. Beets. Battlestar Galactica.” directly.
+
+### Expected Output
+
+When you run `main.py`, the output should look like this:
+
+```
+Getting the list of my favourite things...
+Switch to favorite_things.py...
+Bears. Beets. Battlestar Galactica.
+```
+
+This setup demonstrates how to use MicroPython’s file system to organize and execute multiple scripts, allowing for modular and readable code.
+
+## Organizing Code with Modules and Libraries
+
+When you start importing custom modules or libraries, MicroPython will automatically create a `/lib` folder to store them. This helps keep external libraries or reusable functions separate from your main code. You can use this structure to further organize your project, making it easy to manage larger codebases.
+
+For example:
+
+```
+/ (Root Directory)
+├── boot.py
+├── main.py
+├── /lib
+│   ├── my_custom_library.py
+```
+
+### Using Libraries in `main.py`
+
+After placing reusable code in `/lib`, you can import it directly in `main.py`:
+
+```python
+from lib.my_custom_library import some_function
+
+some_function()
+```
+
+This structure allows for cleaner, more modular code that’s easy to scale as your project grows.
+
+## Conclusion
+
+MicroPython’s file system brings flexibility and structure to embedded programming, enabling a more organized and modular approach. By understanding the typical file structure and how to manage files, we’ll be able to create more complex and maintainable projects.
+
+**Tips for Organizing Our MicroPython Projects**
+
+- **Modularize Code with Additional Scripts**: Store reusable or specific tasks in separate files, making `main.py` clean and focused on high-level logic.
+- **Leverage the `/lib` Folder**: Use the automatically created `/lib` folder to keep libraries organized and separate from your main application code.
+- **Edit and Manage Files Easily**: Arduino Labs for MicroPython’s file management tools make it easy to upload, download, and modify files on the device.
+
+With a well-organized file system, we can streamline our development process and unlock new possibilities with MicroPython!

content/micropython/03.micropython/02.enviroment/03.modules/assets/microPythonLabsFiles.png

@@ -0,0 +1,112 @@
+---
+title: 'Modules'
+description: 'Understanding Modules and how to use them.'
+author: 'Pedro Lima'
+tags: [MicroPython, Modules]
+---
+
+
+In this article, we’ll cover how modules work in MicroPython, explore a few built-in modules, and demonstrate how to install an external package like Modulino to extend our MicroPython project’s functionality.
+
+## What Are Modules?
+
+Modules are collections of functions, classes, and variables organized into separate files, which we can import and use in our main program. Modules allow us to:
+
+- **Reuse Code**: We can import useful functionality instead of writing everything from scratch.
+- **Organize Code**: Breaking code into modules makes projects more readable and maintainable.
+- **Access Special Functionality**: Some tasks require advanced functions (e.g., time delays or hardware communication) that are available only through modules.
+
+## Built-in Modules
+
+MicroPython comes with a set of built-in modules that provide essential functions for programming tasks. For instance:
+
+- **`time`**: This module allows us to add time delays, get timestamps, and measure durations in code.
+- **`os`**: Provides functions to manage the file system, such as creating files or listing directories.
+- **`machine`**: A module designed for hardware interaction, allowing us to control pins, I2C, and more.
+
+We can access built-in modules directly without any installation. Here’s a quick example using the `time` module to add a delay:
+
+```python
+import time
+
+print("Starting countdown...")
+time.sleep(3)  # Pauses the program for 3 seconds
+print("Countdown complete!")
+```
+
+In this example, `time.sleep()` introduces a delay. Built-in modules like `time` are pre-installed with MicroPython, so we don’t need to install anything extra to use them.
+
+## External Modules
+
+Some modules aren’t included with the default MicroPython installation and need to be installed separately. External modules, often provided by the community or specific hardware packages, extend MicroPython’s functionality. For example, the **Modulino** library is an external module that provides tools for working with Arduino Modulinos.
+
+To demonstrate how to use external modules, we’ll go through the steps to install the Modulino package on an Arduino board.
+
+### Step 1: Install MicroPython on Your Board
+
+Before we can install external modules, we need to have MicroPython running on our board. Use the [MicroPython Installer](https://labs.arduino.cc/en/labs/micropython-installer) to install it:
+
+- Open the installer.
+- Connect the board to your computer.
+- Press the "Refresh" button if the board does not appear.
+- Click "**Install MicroPython**" and wait for the installation to complete.
+
+### Step 2: Install the Modulino Package
+
+To install the Modulino package, we’ll use `mpremote`, a tool that allows us to install MicroPython packages directly onto our board from the command line.
+
+1. **Install `mpremote`**: Make sure Python is installed on your computer, then open a terminal and type:
+
+   ```bash
+   pip install mpremote 
+   ```
+
+2. **Connect to Your Board**: Find your board’s serial port by running:
+
+   ```bash
+   mpremote connect list
+   ```
+
+   This command should return something like:
+
+   ```bash
+   /dev/cu.usbmodem101 ecda3b60a4dccb3f 2341:056b Arduino Nano ESP32
+   ```
+
+   - Copy the port, e.g., `/dev/cu.usbmodem101`.
+
+3. **Install the Modulino Package**: Use the following command to install the Modulino package, replacing `<PORT>` with your board’s port:
+
+   ```bash
+   mpremote connect <PORT> mip install github:arduino/arduino-modulino-mpy
+   ```
+
+4. **Verify Installation**: After installation, check Arduino Labs for MicroPython. You should see a `/lib` folder with the Modulino library inside, indicating a successful installation.
+
+   ![MicroPython Lab Files](./assets/microPythonLabsFiles.png)
+
+## Organizing and Using Modules
+
+With the Modulino package installed, we’ll see a `/lib` folder in Arduino Labs, where MicroPython automatically stores external modules. This directory structure is commonly used for organizing additional libraries, making it easy to import and use custom functions in our main program.
+
+### Using an External Module
+
+To use a function from the Modulino library, simply import it in `main.py`:
+
+```python
+from modulino import distance_sensor  # Example function
+
+# Example usage
+distance = distance_sensor.read_distance()
+print("Distance:", distance)
+```
+
+This setup keeps `main.py` clean and makes it easy to incorporate external functionality without crowding the main script.
+
+## Conclusion
+
+MicroPython modules—whether built-in or external—allow us to keep our code organized, reduce duplication, and add powerful functionality to our projects. Some modules, like `time`, are included by default, while others, like the Modulino library, require installation.
+
+- **Built-in Modules**: Modules like `time` and `machine` are part of MicroPython and need no installation.
+- **External Modules**: Packages like Modulino must be installed separately, typically into the `/lib` folder.
+- **Using Modules**: Once installed, we can import modules into our main program to extend functionality and keep our code modular.

content/micropython/03.micropython/02.enviroment/03.modules/modules.md

@@ -0,0 +1,4 @@
+---
+title: Test
+description: Test
+---

content/micropython/03.micropython/micropython.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Distance](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/02.modulino-distance/modulino-distance.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Pixels](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/03.modulino-pixels/modulino-pixels.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Buzzer](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/04.modulino-buzzer/modulino-buzzer.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Buttons](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/05.modulino-buttons/modulino-buttons.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Knob](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/06.modulino-knob/modulino-knob.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Thermo](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software:

content/micropython/03.micropython/modulinos/07.modulino-thermo/modulino-thermo.md

@@ -20,7 +20,6 @@ The goals of this tutorial are:
 
 For this tutorial, we will need the following hardware:
 - [Modulino Movement](https://store.arduino.cc/products/plug-and-make-kit)
-- [Arduino Nano to QWIIC Connector Carrier]()
 - [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32?queryID=undefined) or [Arduino Nano RP2040 Connect](https://store.arduino.cc/en-se/products/arduino-nano-rp2040-connect)
 
 We will also need the following software: