Arduino_manual_install - Alteriom/painlessMesh GitHub Wiki

Manual Arduino IDE Installation (ZIP Import)

This guide explains how to manually install painlessMesh in Arduino IDE using a ZIP file. This method is useful when:

The Arduino Library Manager hasn't indexed the latest version yet
You want to test unreleased versions from GitHub
You need a specific version that's not in the Library Manager

Quick Start

Method 1: Download Release ZIP

Download the latest release ZIP from:
- GitHub Releases
- Look for painlessMesh-vX.X.X.zip
Install in Arduino IDE:
- Open Arduino IDE
- Go to Sketch → Include Library → Add .ZIP Library...
- Select the downloaded painlessMesh-vX.X.X.zip file
- Wait for "Library installed" message
Install Dependencies:
- Go to Sketch → Include Library → Manage Libraries...
- Search and install:
  - ArduinoJson (v6.21.x or v7.x)
  - TaskScheduler (v3.7.0+)
Verify Installation:
- Go to File → Examples → painlessMesh
- Open any example (e.g., basic)
- Verify it compiles

Method 2: Create ZIP from Repository

If you need to create a ZIP file from the repository source:

# Clone the repository
git clone https://github.com/Alteriom/painlessMesh.git
cd painlessMesh

# Create Arduino IDE compatible ZIP
./scripts/create-arduino-zip.sh

This creates dist/painlessMesh-vX.X.X.zip ready for Arduino IDE import.

What's Included in the ZIP

The ZIP file contains:

✅ src/ - Complete library source code
✅ examples/ - All Arduino examples (19+ sketches)
✅ library.properties - Arduino library metadata
✅ README.md - Documentation
✅ LICENSE - LGPL-3.0 license
✅ CHANGELOG.md - Version history
✅ keywords.txt - Syntax highlighting

Directory Structure

After installation, the library will be in:

Windows: Documents\Arduino\libraries\painlessMesh\
macOS: ~/Documents/Arduino/libraries/painlessMesh/
Linux: ~/Arduino/libraries/painlessMesh/

painlessMesh/
├── src/                    # Library source files
│   ├── painlessMesh.h     # Main header
│   ├── painlessmesh/      # Core implementation
│   └── arduino/           # Arduino-specific code
├── examples/              # Example sketches
│   ├── basic/
│   ├── bridge/
│   ├── mqtt/
│   └── ...
├── library.properties     # Library metadata
├── README.md
├── LICENSE
└── keywords.txt

Creating ZIP Files

Automated Script

Use the provided script for consistent ZIP creation:

# From repository root
./scripts/create-arduino-zip.sh

Output: dist/painlessMesh-vX.X.X.zip

Features:

✅ Proper directory structure for Arduino IDE
✅ Includes all required files
✅ Excludes development files (.git, test/, .github/)
✅ Matches GitHub release format
✅ Version number from library.properties

Manual ZIP Creation

If you need to create a ZIP manually:

Create directory structure:

mkdir -p painlessMesh-package/painlessMesh
cd painlessMesh-package/painlessMesh

Copy required files:

# From your painlessMesh repository
cp -r src examples library.properties README.md LICENSE .

Optional additions:
```
cp CHANGELOG.md keywords.txt .
```

Create ZIP:

cd ..
zip -r painlessMesh-v1.8.3.zip painlessMesh/

Important: The ZIP must contain a folder named painlessMesh with the library files inside. Do NOT zip the files directly.

Verification

After installation, verify it works:

Test Compilation

#include "painlessMesh.h"

painlessMesh mesh;

void setup() {
    Serial.begin(115200);
    Serial.println("painlessMesh test");
    
    mesh.init("TestNetwork", "password", 5555);
    Serial.println("Initialized successfully!");
}

void loop() {
    mesh.update();
}

If this compiles without errors, installation is successful!

Check Examples

The examples should appear in: File → Examples → painlessMesh

Available examples:

basic - Simple mesh network
bridge - Internet bridge mode
startHere - Quick start template
namedMesh - Named mesh networks
And 15+ more examples

Troubleshooting

"Library not found" Error

Problem: Arduino IDE can't find the library after installation.

Solutions:

Restart Arduino IDE
Check installation directory:
- Windows: Documents\Arduino\libraries\
- macOS: ~/Documents/Arduino/libraries/
- Linux: ~/Arduino/libraries/
Verify folder name is exactly painlessMesh (case-sensitive on Linux/macOS)
Check that library.properties exists in the painlessMesh folder

"No such file or directory" Compilation Error

Problem: Missing dependency headers like ArduinoJson.h or TaskScheduler.h.

Solution: Install dependencies via Library Manager:

Sketch → Include Library → Manage Libraries...
Search for:
- ArduinoJson → Install version 6.21.x or 7.x
- TaskScheduler → Install version 3.7.0+

Version Mismatch

Problem: Old version still being used after installing new ZIP.

Solution:

Delete old version:
- Go to Arduino/libraries/ folder
- Delete painlessMesh folder
Restart Arduino IDE
Install new ZIP file

ZIP Structure Error

Problem: "Invalid library" error when importing ZIP.

Cause: Incorrect ZIP structure.

Solution: Ensure ZIP contains:

painlessMesh-v1.8.3.zip
└── painlessMesh/           ← Must have this folder
    ├── src/
    ├── examples/
    └── library.properties  ← Must have this file

Common mistake: Zipping files directly without the painlessMesh folder.

Comparing with Library Manager

Feature	Manual ZIP Install	Library Manager
Latest Version	✅ Immediate	⏱️ 24-48h delay
Pre-release Testing	✅ Yes	❌ No
Custom Versions	✅ Yes	❌ No
Ease of Use	⚠️ Manual	✅ Automatic
Updates	⚠️ Manual	✅ One-click
Dependencies	⚠️ Manual	✅ Auto-install

When to Use Each Method

Use Manual ZIP Installation When:

🔧 Testing unreleased features from GitHub
🚀 Need the absolute latest version immediately
🐛 Testing a bug fix before official release
📦 Library Manager hasn't indexed latest version
🔬 Developing or contributing to painlessMesh

Use Library Manager When:

📱 Installing for the first time
🔄 Need easy updates
👥 Stable production deployments
🎓 Learning or following tutorials
📚 Standard development workflow

Automated Releases

The repository automatically creates proper ZIP files on each release:

GitHub Actions workflow builds ZIP on every release
ZIP file uploaded to GitHub Releases page
Format matches Arduino IDE requirements exactly
Naming: painlessMesh-vX.X.X.zip

Download from: https://github.com/Alteriom/painlessMesh/releases

For Library Maintainers

Creating Release ZIPs

The release workflow automatically creates proper ZIP files:

# .github/workflows/release.yml
- name: Prepare library package
  run: |
    mkdir -p package/painlessMesh
    cp -r src examples library.properties README.md LICENSE package/painlessMesh/
    cd package
    zip -r ../painlessMesh-v${{ steps.version.outputs.version }}.zip painlessMesh/

Script Usage

For local testing before release:

# Create ZIP for current version
./scripts/create-arduino-zip.sh

# Output: dist/painlessMesh-vX.X.X.zip
# Ready for testing in Arduino IDE

Testing Installation

Before releasing:

Create ZIP with script
Install in fresh Arduino IDE
Test compilation of examples
Verify examples menu shows all sketches
Check dependency resolution