SCONS_BUILD_FIX

PlatformIO SCons Build Error Troubleshooting

Common Error: "UnboundLocalError: local variable 'dir' referenced before assignment"

This error occurs during PlatformIO's SCons build process when compiling painlessMeshSTA.cpp and similar files.

---

✅ FIXES APPLIED TO LIBRARY

The following fixes have been applied to the painlessMesh library itself:

0. Added Missing Header Include (CRITICAL)

// src/painlessmesh/mesh.hpp
#include <vector>  // Required for std::vector usage

Why: The mesh.hpp file uses std::vector but wasn't including the header, causing compilation errors.

1. Added Explicit Directory Specifications

{
  "srcDir": "src",
  "includeDir": "src"
}

Why: Tells PlatformIO exactly where source files are located.

2. Removed Conflicting Export Settings

Before:

{
  "export": {
    "include": "src"
  }
}

After: (Removed completely)

Why: The export.include conflicts with srcDir and causes path resolution issues in SCons.

3. Verified File Locations

• ✅ All .cpp files in src/ directory
• ✅ painlessMeshSTA.cpp at src/painlessMeshSTA.cpp
• ✅ No source files in root directory
• ✅ No duplicate library.json files

4. Fixed Header References

• ✅ library.properties references painlessMesh.h
• ✅ Both painlessMesh.h and AlteriomPainlessMesh.h available

---

🔧 FIXES FOR YOUR PROJECT

If you're still getting errors, apply these fixes in YOUR project:

Fix 1: Clean Build Cache

# Delete PlatformIO cache
pio run --target clean

# Or delete manually
rm -rf .pio
rm -rf .pioenvs
rm -rf .piolibdeps

Fix 2: Update Library from GitHub

Make sure you're pulling the latest fixes:

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = 
    ; Use the LATEST commit with fixes
    https://github.com/Alteriom/painlessMesh#copilot/start-phase-2-implementation

Fix 3: Force Library Re-download

# Remove cached library
rm -rf .pio/libdeps/*/AlteriomPainlessMesh

# Or use PlatformIO's update command
pio pkg update

Fix 4: Verify PlatformIO Version

# Check version
pio --version

# Update if needed (requires >= 6.0.0)
pip install -U platformio

Fix 5: Check for Conflicting Libraries

# List installed libraries
pio pkg list

# Remove any duplicate painlessMesh installations
pio pkg uninstall -g painlessMesh
pio pkg uninstall -g AlteriomPainlessMesh

---

🧪 TEST BUILD

Step 1: Create Test Project

mkdir test-painlessmesh
cd test-painlessmesh
pio init --board esp32dev

Step 2: Create platformio.ini

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

lib_deps = 
    https://github.com/Alteriom/painlessMesh#copilot/start-phase-2-implementation

Step 3: Create src/main.cpp

#include <Arduino.h>
#include <painlessMesh.h>

Scheduler userScheduler;
painlessMesh mesh;

void setup() {
  Serial.begin(115200);
  
  mesh.setDebugMsgTypes(ERROR | STARTUP);
  mesh.init("TestMesh", "password", &userScheduler, 5555);
  
  Serial.println("Mesh initialized!");
}

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

Step 4: Build

pio run

Expected Output:

Building .pio/build/esp32/src/main.cpp.o
Building .pio/build/esp32/.pio/libdeps/esp32/AlteriomPainlessMesh/...
Linking .pio/build/esp32/firmware.elf
Building .pio/build/esp32/firmware.bin
SUCCESS

---

🚨 IF STILL FAILING

Collect Diagnostic Information

# Get verbose build output
pio run -v > build.log 2>&1

# Check library structure
cd .pio/libdeps/esp32/AlteriomPainlessMesh
ls -la
cat library.json

Check for These Issues:

1. Verify srcDir in downloaded library:

cd .pio/libdeps/esp32/AlteriomPainlessMesh
cat library.json | grep srcDir
# Should show: "srcDir": "src",

2. Verify source files exist:

ls -la src/
# Should show: painlessMeshSTA.cpp, scheduler.cpp, wifi.cpp

3. Check for duplicate files:

find . -name "painlessMeshSTA.cpp"
# Should only show: ./src/painlessMeshSTA.cpp

4. Verify no export.include:

cat library.json | grep export
# Should show: (nothing) or not include "include": "src"

---

📋 CHECKLIST FOR SUCCESSFUL BUILD

• PlatformIO version >= 6.0.0
• Clean build cache (pio run --target clean)
• Remove .pio directory
• Update library.json has srcDir and includeDir
• No export.include in library.json
• All .cpp files in src/ directory
• Force library re-download from GitHub
• Test with minimal example
• Check verbose build log for actual error

---

🔍 UNDERSTANDING THE ERROR

What Causes "UnboundLocalError: dir"?

This error occurs in PlatformIO's SCons build system when:

1. Path resolution fails: SCons can't determine the source directory
2. Conflicting settings: Multiple directory specifications conflict
3. Cache corruption: Old cached metadata from previous builds
4. Missing metadata: No srcDir specified in library.json

The Fix (Applied):

{
  "name": "AlteriomPainlessMesh",
  "srcDir": "src",           // ← Explicit source directory
  "includeDir": "src"        // ← Explicit include directory
  // "export": {...}         // ← REMOVED (was causing conflicts)
}

---

📞 SUPPORT

If issues persist after trying all fixes:

1. Check your build log:

   pio run -v 2>&1 | tee build-verbose.log

2. Verify library was actually updated:

   cd .pio/libdeps/YOUR_ENV/AlteriomPainlessMesh
   git log -1 --oneline
   # Should show recent commit with fixes

3. Try a completely fresh project:

   • New directory
   • Fresh pio init
   • No existing .pio folder
   • Copy minimal example above

4. Report issue with:

   • PlatformIO version
   • Platform (espressif32/espressif8266)
   • Full build log
   • Contents of .pio/libdeps/*/AlteriomPainlessMesh/library.json

---

✅ VERIFICATION

After applying fixes, your build should succeed with output like:

Dependency Graph
|-- AlteriomPainlessMesh @ 1.7.0
|   |-- AsyncTCP @ 3.4.7
|   |-- ArduinoJson @ 7.4.2
|   |-- TaskScheduler @ 4.0.0
|   |-- WiFi @ 2.0.0
Building .pio/build/esp32/lib/.../painlessMeshSTA.cpp.o
...
SUCCESS

---

Last Updated: October 15, 2025
Library Version: 1.7.0
Branch: copilot/start-phase-2-implementation
Status: ✅ SCons build issues resolved