🔧 HardFOC ESP-IDF Project Tools

Scripts ESP-IDF Configuration

Development scripts for ESP-IDF projects with multiple applications

📋 Important: These tools are designed to be integrated into your ESP-IDF project, not used as standalone applications.

🌐 Live Documentation

🎯 What This Is

Development scripts that enhance ESP-IDF projects with:

  • Multi-application builds from a single project
  • YAML-based configuration management
  • Automated CI/CD integration patterns
  • Cross-platform port detection and flashing

🚀 Quick Start

Integration Methods

Choose the best method for your ESP-IDF project:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Navigate to your ESP-IDF project
cd your-esp-idf-project

# Add tools as submodule
git submodule add https://github.com/n3b3x/hf-espidf-project-tools.git scripts

# Your project structure:
# your-esp-idf-project/
# ├── CMakeLists.txt
# ├── app_config.yml
# ├── main/
# └── scripts/                    # Project tools
#     ├── build_app.sh
#     └── flash_app.sh

# Start building
./scripts/build_app.sh your_app Release

Method 2: Direct Clone Integration 

1
2
3
4
5
6
7
8

# Navigate to your ESP-IDF project
cd your-esp-idf-project

# Clone tools directly
git clone https://github.com/n3b3x/hf-espidf-project-tools.git scripts

# Start building
./scripts/build_app.sh your_app Release

Method 3: Shared Tools Directory 

1
2
3
4
5
6
7
8

# For multiple projects, use shared tools
mkdir -p ~/shared-esp32-tools
cd ~/shared-esp32-tools
git clone https://github.com/n3b3x/hf-espidf-project-tools.git .

# In each ESP-IDF project, use --project-path
cd your-esp-idf-project
~/shared-esp32-tools/build_app.sh --project-path . your_app Release

📁 Project Structure Concepts

Project Directory (project_dir)

  • Purpose: Points to your ESP-IDF project directory (contains CMakeLists.txt, app_config.yml)
  • Examples: examples/esp32, firmware/esp32-project, src/esp32-app

Tools Directory (project_tools_dir)

  • Purpose: Points to directory containing the build scripts (build_app.sh, generate_matrix.py, etc.)
  • Auto-detection: If not specified, looks for hf-espidf-project-tools subdirectory in project directory
  • Multi-Project Support: Can be shared across multiple projects since all scripts accept --project-path argument
  • Examples: examples/esp32/scripts, examples/esp32/hf-espidf-project-tools, tools/esp32-build-scripts, shared-tools

🔧 Common Integration Patterns 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Repository structure:
# your-repo/
# ├── examples/esp32/           # ESP-IDF project
# │   ├── CMakeLists.txt
# │   ├── app_config.yml
# │   └── hf-espidf-project-tools/  # Submodule containing project tools
# │       ├── build_app.sh
# │       └── generate_matrix.py

# CI/CD Usage:
jobs:
  build:
    uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
    with:
      project_dir: examples/esp32
      project_tools_dir: examples/esp32/hf-espidf-project-tools  # Points to submodule

Pattern 2: Direct Clone Setup 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Repository structure:
# your-repo/
# ├── examples/esp32/           # ESP-IDF project
# │   ├── CMakeLists.txt
# │   ├── app_config.yml
# │   └── hf-espidf-project-tools/  # Cloned directly
# │       ├── build_app.sh
# │       └── generate_matrix.py

# CI/CD Usage:
jobs:
  build:
    uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
    with:
      project_dir: examples/esp32
      # project_tools_dir not needed - auto-detects hf-espidf-project-tools

Pattern 3: Custom Tools Location 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Repository structure:
# your-repo/
# ├── firmware/esp32/           # ESP-IDF project
# │   ├── CMakeLists.txt
# │   └── app_config.yml
# └── build-tools/              # Custom tools location
#     ├── build_app.sh
#     └── generate_matrix.py

# CI/CD Usage:
jobs:
  build:
    uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
    with:
      project_dir: firmware/esp32
      project_tools_dir: build-tools

Pattern 4: Shared Tools for Multiple Projects 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Repository structure:
# your-repo/
# ├── projects/
# │   ├── project-a/            # ESP-IDF project A
# │   │   ├── CMakeLists.txt
# │   │   └── app_config.yml
# │   └── project-b/            # ESP-IDF project B
# │       ├── CMakeLists.txt
# │       └── app_config.yml
# └── shared-tools/             # Shared tools directory
#     ├── build_app.sh
#     └── generate_matrix.py

# CI/CD Usage:
jobs:
  build-project-a:
    uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
    with:
      project_dir: projects/project-a
      project_tools_dir: shared-tools  # Shared across all projects
      
  build-project-b:
    uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
    with:
      project_dir: projects/project-b
      project_tools_dir: shared-tools  # Same shared tools directory

🛠️ Core Scripts

Script Purpose Usage
build_app.sh Build applications ./scripts/build_app.sh app_name build_type
flash_app.sh Flash and monitor ./scripts/flash_app.sh flash_monitor app_name
generate_matrix.py CI matrix generation python3 scripts/generate_matrix.py
config_loader.sh Configuration utilities Source for other scripts

📊 Configuration

All scripts use app_config.yml for configuration:

1
2
3
4
5
6
7
8
9
10
11

metadata:
  idf_versions: ["release/v5.5", "release/v5.4"]
  build_types: [["Debug", "Release"], ["Debug", "Release"]]
  target: "esp32c6"

apps:
  gpio_test:
    ci_enabled: true
    description: "GPIO peripheral testing"
    idf_versions: ["release/v5.5"]
    build_types: [["Debug", "Release"]]

🔗 CI/CD Integration

Works with the ESP-IDF CI Tools for automated builds:

1
2
3
4
5

- name: Build ESP-IDF Applications
  uses: N3b3x/hf-espidf-ci-tools/.github/workflows/build.yml@v1
  with:
    project_dir: examples/esp32
    project_tools_dir: examples/esp32/scripts

📚 Documentation

🤝 Contributing

Contributions welcome! See our Contributing Guide for details.

📄 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.