Skip to content

pogorelov-ss/esp32_monorepo

BranchesTags

Repository files navigation

ESP32 Polilith Workspace

A Polilith-inspired project structure specifically designed for ESP32 development using ESP-IDF with Nx monorepo tooling. This workspace enables modular organization with reusable components, shared libraries, and multiple project configurations for efficient development and code reuse across different ESP32 applications.

Directory Structure

<workspace-root>/               # Your current project root
├── .vscode/                    # VSCode workspace configuration
│   ├── settings.json          # PlatformIO and ESP-IDF settings
│   ├── tasks.json             # Build, flash, and monitor tasks
│   └── launch.json            # Debug configurations
├── bases/                      # Reusable base implementations
├── components/                 # Shared component libraries
├── projects/                   # Individual ESP32 projects
│   └── <project-name>/        # Each project has its own configuration
│       ├── project.json       # Nx project configuration
│       ├── platformio.ini     # PlatformIO configuration
│       ├── CMakeLists.txt     # ESP-IDF build configuration
│       └── main/              # Main application code
├── development/               # Development and testing
│   └── templates/             # Templates for components, bases, projects
│       ├── base-template/
│       ├── component-template/
│       └── project-template/
├── tools/                     # Build and utility scripts
│   ├── create-project.py      # Project creation script
│   ├── create-component.py    # Component creation script
│   ├── create-base.py         # Base creation script
│   └── build-all.py          # Multi-project build script
├── nx.json                    # Nx workspace configuration
├── project.json              # Root workspace project configuration
├── package.json              # Node.js dependencies and scripts
├── workspace.code-workspace   # VSCode workspace file
├── CMakeLists.txt            # Root CMake configuration
└── README.md                 # This documentation

Core Concepts

Bases

Reusable base implementations that provide common functionality across multiple ESP32 projects. Bases contain hardware abstractions, utility functions, and foundational code that can be shared without modification.

Components

Shared component libraries that implement specific functionality modules. Components are designed to be modular, testable, and reusable across different projects with proper dependency management.

Projects

Individual ESP32 applications that combine bases and components to create complete firmware solutions. Each project has its own configuration and can target different ESP32 variants.

Getting Started

Prerequisites

Installation

  1. Clone this repository
  2. Install Node.js dependencies: 
    npm install
  3. Install PlatformIO Core: 
    pip install -U platformio
  4. (Optional) Open the workspace in VSCode: 
    code workspace.code-workspace

Note: ESP-IDF framework (v5.5.0) is automatically installed by PlatformIO on first build.

Usage Examples

Creating a New Project

# Create a new ESP32 project for standard ESP32 board
python tools/create-project.py my_sensor_project --board esp32dev

# Create project for M5Stack Core ESP32
python tools/create-project.py m5stack_app --board m5stack-core-esp32

# Create project for ESP32-S3
python tools/create-project.py iot_device --board esp32-s3-devkitc-1

This creates a new project in projects/<project-name>/ with:

  • PlatformIO configuration (platformio.ini)
  • ESP-IDF build files (CMakeLists.txt)
  • Main application template (main/main.cpp)
  • Nx task configuration (project.json)
  • Symlinks to shared components/ and bases/

Creating a New Component

# Create a new shared component
python tools/create-component.py wifi-manager

# The component will be created in components/wifi-manager/

Components include:

  • ESP-IDF component structure
  • CMakeLists.txt and component.mk files
  • Header and source file templates
  • Proper include directories

Creating a New Base

# Create a new base implementation
python tools/create-base.py sensor-base

# The base will be created in bases/sensor-base/

Bases provide:

  • Hardware abstraction interfaces
  • Common initialization routines
  • Reusable utility functions
  • Standard ESP32 peripheral access

Build System

The workspace uses a custom build system that combines PlatformIO, ESP-IDF, and Nx for efficient firmware compilation and flashing.

How It Works

  1. CMake Configuration: PlatformIO configures the ESP-IDF CMake build system
  2. Ninja Build: Direct invocation of ninja compiles 1000+ source files in parallel
  3. Custom Wrappers: Scripts bypass PlatformIO's target detection issues
  4. Nx Orchestration: Nx manages task dependencies and caching

Building Projects

# Build a specific project (compiles ~1015 files)
nx build my_sensor_project

# Build generates ELF executable in:
# projects/<name>/.pio/build/<board>/<name>.elf

# Clean build artifacts
nx clean my_sensor_project

First build downloads ESP-IDF toolchain (~2GB) and takes several minutes. Subsequent builds use Nx caching.

Flashing Firmware

# Flash firmware to connected ESP32 (auto-detects serial port)
nx flash my_sensor_project

# The flash script automatically:
# - Generates binary files from ELF
# - Detects /dev/ttyUSB* or /dev/ttyACM* ports
# - Flashes bootloader, partition table, and application
# - Uses 921600 baud for fast uploads

Monitoring Serial Output

# Open serial monitor
nx monitor my_sensor_project

# Press Ctrl+C to exit monitor

Complete Development Workflow

# 1. Create a new project
python tools/create-project.py temperature_sensor --board esp32dev

# 2. Edit the application code
# projects/temperature_sensor/main/main.cpp

# 3. Build the firmware
nx build temperature_sensor

# 4. Flash to ESP32 hardware
nx flash temperature_sensor

# 5. View serial output
nx monitor temperature_sensor

Project Configuration

PlatformIO Configuration

Each project's platformio.ini includes shared component directories:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = espidf
lib_extra_dirs = ../../components, ../../bases
build_flags = 
    -I../../components
    -I../../bases
monitor_speed = 115200

ESP-IDF Integration

The workspace uses ESP-IDF 5.5.0 via PlatformIO. ESP-IDF components are available in all projects:

// Standard ESP-IDF headers work out of the box
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "nvs_flash.h"

Note: Direct idf.py commands are not supported. Use nx build/flash/monitor commands instead.

Component Dependencies

Components declare dependencies in their CMakeLists.txt:

idf_component_register(
    SRCS "src/wifi_manager.c"
    INCLUDE_DIRS "include"
    REQUIRES freertos esp_wifi esp_event
    PRIV_REQUIRES nvs_flash
)

Development Environment

VSCode Integration

The workspace includes pre-configured VSCode settings for:

  • PlatformIO extension integration
  • ESP-IDF IntelliSense support
  • Build and debug tasks
  • Serial monitor integration

Available Tasks

Access tasks through VSCode Command Palette (Ctrl+Shift+P):

  • Build Project: Compile the current project
  • Flash Project: Upload firmware to ESP32
  • Monitor Serial: View serial output
  • Clean Project: Clean build artifacts

Debugging

Debug configurations are pre-configured for:

  • Hardware debugging with ESP-PROG
  • Software debugging with GDB
  • Serial output monitoring

Advanced Usage

Custom Templates

Modify templates in development/templates/ to customize:

  • Component structure and boilerplate code
  • Project initialization settings
  • Base implementation patterns

Build Optimization

Nx provides intelligent caching and dependency tracking:

  • Only rebuilds changed components
  • Caches build artifacts
  • Parallelizes independent builds

Multi-Target Support

Support multiple ESP32 variants by:

  • Creating target-specific project configurations
  • Using conditional compilation in components
  • Maintaining separate build environments

Troubleshooting

Common Issues

Build Errors

  • Ensure all component dependencies are declared in main/CMakeLists.txt
  • For ESP-IDF 5.x, use nvs_flash, esp_system (not esp_common)
  • First build downloads toolchain - requires internet connection

Flash Errors

  • Check ESP32 is connected via USB
  • Verify serial port permissions: sudo usermod -a -G dialout $USER (Linux)
  • Try unplugging and reconnecting the device
  • Check /dev/ttyUSB* or /dev/ttyACM* exists

Serial Monitor Issues

  • Ensure baud rate matches (default: 115200)
  • Close other programs using the serial port
  • Reset the ESP32 if monitor shows no output

Component Not Found

  • Verify symlinks exist: ls -la projects/<name>/components
  • Check component is in components/ or bases/ directory
  • Add to REQUIRES list in main/CMakeLists.txt

Getting Help

Contributing

  1. Create components and bases following the established templates
  2. Test new projects with existing components
  3. Update documentation when adding new features
  4. Follow ESP-IDF coding standards and conventions

About

experemental monorepository for esp32 projects with polilith

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages