Build Configuration

RadioMesh PlatformIO Configuration Guide

Overview

RadioMesh uses PlatformIO as its build system, with a modular configuration structure split across multiple files for better organization and reuse. The configuration files are organized in a hierarchical manner, with common settings inherited through PlatformIO's extends mechanism.

Configuration Structure

platformio.ini           # Main project configuration
pio-config/
  ├── common.ini        # Base settings for all targets
  ├── common-test.ini   # Common test configurations
  ├── esp32-base.ini    # ESP32 platform settings
  └── cubecell-base.ini # CubeCell platform settings

Configuration Inheritance

The project uses PlatformIO's inheritance system to build configurations. For example, here's how the heltec_wifi_lora_32_V3 target is constructed:

common.ini             # Base configuration
    ↓
esp32-base.ini        # ESP32 platform specifics
    ↓
platformio.ini        # Final target configuration

Common Base Configuration

common.ini defines the foundational settings used by all targets:

[common]
monitor_speed = 115200
lib_deps =
    [email protected]
    # ... other common libraries
build_flags =
    -std=gnu++17
    -I ./include
    -I ./src

This includes:

• Common library dependencies
• Compiler flags
• Include paths
• RadioLib optimizations

Platform-Specific Configurations

ESP32 Base Configuration

esp32-base.ini adds ESP32-specific settings:

[esp32_base]
extends = common
platform = espressif32
framework = arduino
lib_deps =
    ${common.lib_deps}
    # ESP32-specific libraries

Example Target Configuration

In platformio.ini, targets are defined using the platform base:

[env:heltec_wifi_lora_32_V3]
extends = esp32_base
board = heltec_wifi_lora_32_V3
lib_ldf_mode = chain+
lib_deps =
    ${esp32_base.lib_deps}

Building Projects

Using the Builder Tool

RadioMesh provides a simplified builder tool that wraps PlatformIO commands for easier usage.

Basic Commands

List available targets:

./tools/builder.py list-targets

Build for Heltec WiFi LoRa 32 V3:

./tools/builder.py build -t heltec_wifi_lora_32_V3

Build and deploy:

./tools/builder.py build -t heltec_wifi_lora_32_V3 --deploy

Clean build:

./tools/builder.py build -t heltec_wifi_lora_32_V3 --clean

Run tests:

./tools/builder.py test -t heltec_wifi_lora_32_V3

Run specific test suite:

./tools/builder.py test -t heltec_wifi_lora_32_V3 -s test_radio

Using PlatformIO Directly

For advanced users familiar with PlatformIO:

# Build
pio run -e heltec_wifi_lora_32_V3

# Upload
pio run -e heltec_wifi_lora_32_V3 -t upload

# Test
pio test -e heltec_wifi_lora_32_V3

# Clean
pio run -t clean

Test Configurations

For unit testing, additional settings are provided in common-test.ini:

[common_test]
extends = common
test_framework = unity
build_flags =
    ${common.build_flags}
    -DUNIT_TEST

Adding New Targets

Step-by-Step Guide

1. Choose Base Configuration First determine if your board is ESP32-based or CubeCell-based:

# For ESP32 boards
extends = esp32_base

# For CubeCell boards 
extends = cubecell_base

2. Add Target Configuration Add a new environment section to platformio.ini:

[env:your_board_name]
extends = esp32_base  # or cubecell_base
board = your_board_name
lib_ldf_mode = chain+
lib_deps =
    ${esp32_base.lib_deps}    # inherit ESP32 libraries
    # Add board-specific libraries here

build_flags =
    ${esp32_base.build_flags} # inherit ESP32 flags
    # Add board-specific flags here
    #-DRM_NO_DISPLAY          # example: disable display support

3. Add Test Configuration (Optional) If you need test support:

[env:test_your_board_name]
extends =
    esp32_base
    common_test
board = ${env:your_board_name.board}
lib_deps =
    ${esp32_base.lib_deps}

Example: Adding New ESP32 Board

[env:ttgo_t_beam_v1]
extends = esp32_base
board = ttgo-t-beam
lib_ldf_mode = chain+
lib_deps =
    ${esp32_base.lib_deps}
build_flags =
    ${esp32_base.build_flags}
    -DTTGO_T_BEAM_V1

Testing New Target

# Verify configuration
`./tools/builder.py list-targets`

# Test build
./tools/builder.py build -t your_board_name

# Run tests if configured
./tools/builder.py test -t test_your_board_name

Further Reading

• PlatformIO Configuration Documentation
• ESP32 Platform Documentation

This configuration structure allows for:

• Reusable common settings
• Platform-specific customization
• Easy addition of new targets
• Organized test configurations