docs: Added pckg-install-local.py docs.

Signed-off-by: jaenrig-ifx <[email protected]>

Author: jaenrig-ifx

docs/scripts/pckg-install-local.rst

@@ -1,2 +1,179 @@
 pckg-install-local
-==================
+==================
+
+The ``pckg-install-local`` script is a Python utility that enables local installation and testing of Arduino core packages during development.
+
+It allows to install an Arduino core without publishing it to a remote repository, from a local directory. 
+The `arduino-cli` can only install cores which are hosted in a remote server.
+In CI/CD this is convenient for two use cases:
+
+- Working with the commit triggering the CI/CD pipeline for an Arduino core.
+- Prevent the CI/CD downloads to increase the download statistics of the core package by installing it from a published release, which will skew the real user download statistics.
+
+Overview
+--------
+
+When developing an Arduino core, you typically need to test your changes before publishing. This script automates the process of:
+
+1. Starting a local HTTP server to host your package files (as arduino-cli cannot install from a local directory)
+2. Creating a modified package index file with local URLs
+3. Uninstalling any existing version of the core
+4. Installing the core from your local development files
+5. Cleaning up temporary files
+
+This tool can be used for cores generated by the :doc:`arduino-packager` tool.
+
+Features
+--------
+
+- **Local HTTP server**: Automatically starts a local server on a random port (8000-8200 range)
+- **Package index modification**: Creates a local version of your package index with localhost URLs
+- **Clean installation**: Removes existing installations and staging files before installing
+- **Arduino CLI integration**: Uses Arduino CLI commands for proper core management
+- **Verbose logging**: Optional detailed output for debugging
+- **Cross-platform support**: Works on Linux, macOS, and Windows
+
+Usage
+-----
+
+Basic usage:
+
+.. code:: bash
+
+    python pckg-install-local.py
+
+With options:
+
+.. code:: bash
+
+    python pckg-install-local.py --pckg-dir /path/to/package --verbose
+
+Command line options
+^^^^^^^^^^^^^^^^^^^^
+
+``--pckg-dir <directory>``
+    Path to the package directory containing the Arduino core package files.
+    
+    **Default**: Current working directory
+    
+    **Example**: ``--pckg-dir ./build/``
+
+``--verbose``
+    Enable verbose logging output to see detailed information about the installation process.
+    
+    **Example**: ``--verbose``
+
+``-v, --version``
+    Display the version of the pckg-install-local tool.
+    
+    **Example**: ``--version``
+
+Package directory structure
+---------------------------
+
+The package directory must contain:
+
+1. **Package index file**: A ``.json`` file (e.g., ``package_mycore_index.json``)
+2. **Core archive**: A ``.zip`` file containing the Arduino core (e.g., ``arduino-core-mycore-1.0.0.zip``)
+
+Example directory structure:
+
+.. code:: text
+
+    package/
+    ├── package_mycore_index.json       # Package index manifest
+    └── arduino-core-mycore-1.0.0.zip   # Arduino core archive
+
+Installation process
+--------------------
+
+The script performs the following steps:
+
+1. **Server setup**
+   
+   - Starts a local HTTP server on a random port (8000-8200)
+   - Serves files from the specified package directory
+
+2. **Package index modification**
+   
+   - Locates the package index JSON file in the directory
+   - Creates a local copy with ``_local`` suffix (e.g., ``package_mycore_index_local.json``)
+   - Updates the package URL to point to the local server
+
+3. **Core cleanup**
+   
+   - Uninstalls any existing version of the core using ``arduino-cli core uninstall``
+   - Removes staging files from Arduino's installation directory
+   - Cleans up previous local package index files
+
+4. **Core installation**
+   
+   - Updates Arduino CLI core index
+   - Installs the core using the local package index URL
+   - Lists installed cores to verify installation
+
+Prerequisites
+-------------
+
+- **Python 3.x** installed on your system
+- **Arduino CLI** installed and available in your system PATH
+- **Package files** generated by the arduino-packager tool or manually created
+- **Network access** for Arduino CLI to update its index (internet connection)
+
+.. note::
+    The script requires Arduino CLI to be properly installed and configured. You can install it using the :doc:`arduino-cli-install` script.
+
+Examples
+--------
+
+**Install from current directory:**
+
+.. code:: bash
+
+    python pckg-install-local.py
+
+**Install with verbose output:**
+
+.. code:: bash
+
+    python pckg-install-local.py --verbose
+
+**Install from specific package directory:**
+
+.. code:: bash
+
+    python pckg-install-local.py --pckg-dir ./build/package --verbose
+
+**Check version:**
+
+.. code:: bash
+
+    python pckg-install-local.py --version
+
+Troubleshooting
+---------------
+
+**"Package index file not found" error:**
+    Ensure your package directory contains a ``.json`` file (package index manifest).
+
+**"Package archive file not found" error:**
+    Ensure your package directory contains a ``.zip`` file (Arduino core archive).
+
+**"Server could not start" error:**
+    The script tries random ports between 8000-8200. If all ports are busy, try closing other applications or restart your system.
+
+**Arduino CLI command fails:**
+    Verify that Arduino CLI is properly installed and accessible from the command line:
+    
+    .. code:: bash
+    
+        arduino-cli version
+
+**Core installation fails:**
+    Check that your package index file is valid JSON and contains the required Arduino core package structure.
+
+.. warning::
+    This script modifies Arduino CLI's core installations. Make sure to backup any important Arduino configurations before running it.
+
+.. tip::
+    Use the ``--verbose`` flag to see detailed logging output when troubleshooting installation issues.