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 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:

python pckg-install-local.py

With options:

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:

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 arduino-cli-install script.

Examples

Install from current directory:

python pckg-install-local.py

Install with verbose output:

python pckg-install-local.py --verbose

Install from specific package directory:

python pckg-install-local.py --pckg-dir ./build/package --verbose

Check version:

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:

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.