RBgrid library Installation

Repository cloning, adding as project component. CMakeLists.txt configuration and project structure setup.

Introduction

The RBgrid library based on ESP-IDF components (Espressif IoT Development Framework) is the official development framework for ESP32 microcontrollers. The RBgrid library is fully compatible with ESP-IDF and can be integrated as a project component. This guide describes the installation and configuration process.

Requirements

Software Versions

VScode: MS Visual Studio code IDE latest version
ESP-IDF: version 5.0 or higher (5.4.x recommended)
Python: 3.8 or higher
CMake: 3.16 or higher
Git: latest version
Arduino ESP32 core: version 3.0.x (as ESP-IDF component)

Supported Platforms

Windows 10/11
macOS 10.15+
Ubuntu 20.04+
Other Linux distributions

Step 1: Installing ESP-IDF

Windows

Download ESP-IDF Tools Installer from official website
Run the installer and select ESP-IDF version 5.4.x
Install to recommended directory
Add environment variables automatically through installer

Linux/macOS

bash

# Clone ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone -b v5.1.2 --recursive https://github.com/espressif/esp-idf.git

# Install tools
cd ~/esp/esp-idf
./install.sh esp32

# Set environment variables
. ~/esp/esp-idf/export.sh

Verify Installation

bash

idf.py --version
# Should output: ESP-IDF v5.1.2

Step 2: Creating Project Structure

Basic ESP-IDF Project Structure

python

my_RBgrid_project/
├── CMakeLists.txt           # Main build file
├── sdkconfig                # Project configuration
├── sdkconfig.defaults       # Default settings
├── partitions.csv           # Partition table (optional)
├── main/
│   ├── CMakeLists.txt      # CMake for main component
│   ├── idf_component.yml    # Dependencies manifest
│   └── main.cpp             # Main application file
└── components/              # Local components
    └── RBgrid/             # RBgrid library

Creating the Project

bash

# Create project directory
mkdir my_RBgrid_project
cd my_RBgrid_project

# Create main directories
mkdir main
mkdir components

Step 3: Configuring CMakeLists.txt

Main CMakeLists.txt (project root)

cmake

# my_RBgrid_project/CMakeLists.txt
cmake_minimum_required(VERSION 3.16)

# Specify additional component directories
set(EXTRA_COMPONENT_DIRS components)

# Include ESP-IDF build system
include($ENV{IDF_PATH}/tools/cmake/project.cmake)

# Optional: minimal build to save time
idf_build_set_property(MINIMAL_BUILD ON)

# Project name
project(RBgrid_app)

CMakeLists.txt for main component

cmake

# main/CMakeLists.txt
idf_component_register(
    SRCS "main.cpp"
    INCLUDE_DIRS "."
    REQUIRES 
        RBgrid 
        arduino-esp32
        esp_timer
        nvs_flash
        driver
)

Step 4: Adding RBgrid as Component

Option 1: Clone Repository

bash

cd components
git clone https://github.com/yourusername/RBgrid.git
cd ..

Option 2: Add as Submodule

bash

git submodule add https://github.com/yourusername/RBgrid.git components/RBgrid
git submodule update --init --recursive

Option 3: Using IDF Component Manager

Create file main/idf_component.yml:

yaml

# main/idf_component.yml
dependencies:
  # Arduino-ESP32 as dependency
  espressif/arduino-esp32:
    version: "^3.0.0"
    pre_release: true

  # Additional components
  joltwallet/littlefs: "==1.14.0"
  espressif/esp-dsp: "^1.4.0"

  # Local RBgrid library
  RBgrid:
    path: "../components/RBgrid"

Step 5: Project Configuration

Creating sdkconfig.defaults

ini

# sdkconfig.defaults

# Configuration for RBgrid
CONFIG_RBHAL_4_CHANNELS=y
CONFIG_RBHAL_AC_50HZ=y
CONFIG_RBHAL_ADC_ATTEN_DB_12=y
CONFIG_RBHAL_ADC_WIDTH_12BIT=y
CONFIG_RBHAL_ENABLE_AUTO_CALIBRATION=y

# Arduino settings
CONFIG_ARDUINO_RUNNING_CORE=0
CONFIG_ARDUINO_EVENT_RUNNING_CORE=0
CONFIG_ARDUINO_UDP_RUNNING_CORE=1
CONFIG_ARDUINO_LOOP_STACK_SIZE=8192

# Performance optimization
CONFIG_COMPILER_OPTIMIZATION_PERF=y
CONFIG_ESP32_DEFAULT_CPU_FREQ_240=y
CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ=240

# FreeRTOS settings
CONFIG_FREERTOS_HZ=1000
CONFIG_FREERTOS_UNICORE=n

# Task stack sizes
CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
CONFIG_ESP_TIMER_TASK_STACK_SIZE=4096

# NVS for calibration storage
CONFIG_NVS_ENCRYPTION=n
CONFIG_NVS_ASSERT_ERROR_CHECK=y

# Logging
CONFIG_LOG_DEFAULT_LEVEL_INFO=y
CONFIG_LOG_MAXIMUM_LEVEL_VERBOSE=y
CONFIG_LOG_COLORS=y

# WiFi (if used)
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM=10
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM=32
CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM=32

Configuration via menuconfig

bash

# Open interactive configurator
idf.py menuconfig

Navigation in menuconfig:
- Component config → RBgrid Configuration - library settings
- Component config → Arduino Configuration - Arduino settings
- Component config → FreeRTOS - RTOS settings
- Serial flasher config - flash parameters

Step 6: Partition Table (Optional)

Creating partitions.csv

csv

# Name,   Type, SubType,  Offset,   Size,  Flags
nvs,      data, nvs,      0x9000,   0x6000,
phy_init, data, phy,      0xf000,   0x1000,
factory,  app,  factory,  0x10000,  1536K,   
ota_0,    app,  ota_0,    0x190000, 1536K,   
coredump, data, coredump, 0x310000, 64K,

Activating Custom Partition Table

Add to sdkconfig.defaults:

ini

CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"

Step 7: Configuring RBgrid Component

CMakeLists.txt for RBgrid

cmake

# components/RBgrid/CMakeLists.txt
idf_component_register(
    SRCS 
        "src/RBgrid.cpp"
        "src/RBgrid_adc.cpp"
        "src/RBgrid_dma.cpp"
        "src/RBgrid_calc.cpp"
        "src/rbgrid.cpp"
        "src/rbgrid_config_api.cpp"
    INCLUDE_DIRS 
        "include"
    PRIV_INCLUDE_DIRS 
        "src"
    REQUIRES 
        arduino-esp32
        driver
        esp_adc
        esp_timer
        nvs_flash
        esp_dsp
    PRIV_REQUIRES
        esp_system
        esp_rom
)

# Compile with optimization
target_compile_options(${COMPONENT_LIB} PRIVATE -O3)

# Place critical code in IRAM
target_compile_definitions(${COMPONENT_LIB} PUBLIC 
    IRAM_ATTR=IRAM_ATTR
    RBPOWER_USE_IRAM=1
)

idf_component.yml for RBgrid

yaml

# components/RBgrid/idf_component.yml
description: RB-POWER detection library for ESP32
version: 1.0.0
url: https://github.com/yourusername/RBgrid
dependencies:
  espressif/arduino-esp32:
    version: "^3.0.0"
    pre_release: true
  espressif/esp-dsp:
    version: "^1.4.0"
tags:
  - power
  - energy
  - monitoring
  - esp32

Step 8: Main File Example

cpp

// main/main.cpp
#include 
#include "rbgrid.h"
#include "rbgrid_config_api.h"
#include "esp_log.h"

static const char* TAG = "MAIN";

extern "C" void app_main(void) {
    // Initialize Arduino
    initArduino();

    ESP_LOGI(TAG, "Starting RBgrid application");

    // Create configuration
    rbgrid_config_handle_t config = rbgrid_config_create("Test", "Location");

    // Configure sensors
    rbgrid_config_add_adc_sensor(config, GPIO_NUM_35, RBSENSOR_TYPE_VOLTAGE_ZMPT107_1);
    rbgrid_config_add_adc_sensor(config, GPIO_NUM_34, RBSENSOR_TYPE_CURRENT_SCT013_10A);

    // Initialize system
    rbgrid_init_system();

    // Main loop
    while(1) {
        // Your code here
        delay(1000);
    }
}

Step 9: Build and Flash

Build Commands

bash

# Full clean (if needed)
idf.py fullclean

# Set target platform
idf.py set-target esp32

# Build project
idf.py build

# Flash and monitor
idf.py -p COM3 flash monitor

# Monitor only
idf.py -p COM3 monitor

Flash Speed Configuration

bash

# Fast flash (921600 baud)
idf.py -p COM3 -b 921600 flash

# Standard speed (115200 baud)
idf.py -p COM3 -b 115200 flash

Step 10: Compiler Optimization

Compilation Flags for Maximum Performance

In component's CMakeLists.txt:

cmake

# Speed optimization
target_compile_options(${COMPONENT_LIB} PRIVATE 
    -O3                    # Maximum optimization
    -ffast-math           # Fast math
    -funroll-loops        # Loop unrolling
    -ftree-vectorize      # Vectorization
)

# For debugging
target_compile_options(${COMPONENT_LIB} PRIVATE 
    -Og                   # Debug optimization
    -g3                   # Maximum debug info
    -DDEBUG_BUILD
)

Linker Configuration

cmake

# Place functions in IRAM for speed
target_link_libraries(${COMPONENT_LIB} INTERFACE 
    "-Wl,--wrap=malloc"
    "-Wl,--wrap=free"
)

Troubleshooting

Common Errors and Solutions

1. Error: "Arduino.h not found"

Solution: Ensure arduino-esp32 is added to dependencies:

yaml

dependencies:
  espressif/arduino-esp32:
    version: "^3.0.0"

2. Error: "undefined reference to setup/loop"

Solution: Use app_main instead of setup/loop or enable Arduino via initArduino().

3. Error: "Region IRAM overflow"

Solution: Reduce number of IRAM_ATTR functions or increase IRAM size in menuconfig.

4. Warning: "Component not found"

Solution: Check path in EXTRA_COMPONENT_DIRS and presence of CMakeLists.txt in component.

Useful Debug Commands

bash

# Binary size
idf.py size

# Component sizes
idf.py size-components

# Clear CMake cache
rm -rf build
idf.py reconfigure

# Verbose build
idf.py -v build

# Check configuration
idf.py confserver

VS Code Integration

Installing ESP-IDF Extension

Install "Espressif IDF" extension from VS Code marketplace
Configure ESP-IDF path: Ctrl+Shift+P → "ESP-IDF: Configure ESP-IDF Extension"
Select ESP-IDF version and installation path

Settings File .vscode/settings.json

json

{
    "idf.espIdfPath": "~/esp/esp-idf",
    "idf.pythonBinPath": "~/esp/.espressif/python_env/idf5.1_py3.8_env/bin/python",
    "idf.toolsPath": "~/esp/.espressif",
    "idf.customExtraPaths": "",
    "idf.port": "/dev/ttyUSB0",
    "idf.baudRate": "115200",
    "idf.flashType": "UART",
    "idf.enableCCache": true,
    "idf.enableIdfComponentManager": true,
    "C_Cpp.intelliSenseEngine": "default",
    "files.associations": {
        "*.ino": "cpp",
        "*.hpp": "cpp"
    }
}

Tasks File .vscode/tasks.json

json

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build",
            "type": "shell",
            "command": "idf.py build",
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Flash",
            "type": "shell",
            "command": "idf.py -p ${config:idf.port} flash",
            "dependsOn": "Build"
        },
        {
            "label": "Monitor",
            "type": "shell",
            "command": "idf.py -p ${config:idf.port} monitor"
        },
        {
            "label": "Clean",
            "type": "shell",
            "command": "idf.py fullclean"
        }
    ]
}

Using with Docker

Dockerfile for Building

dockerfile

FROM espressif/idf:v5.1.2

WORKDIR /project

# Copy project
COPY . .

# Install dependencies
RUN pip install --upgrade idf-component-manager

# Build project
RUN idf.py build

# Default command
CMD ["/bin/bash"]

Building in Docker

bash

# Create image
docker build -t RBgrid-build .

# Run container
docker run -it --device=/dev/ttyUSB0 RBgrid-build

# Flash from container
docker run -it --device=/dev/ttyUSB0 RBgrid-build idf.py flash

Continuous Integration

GitHub Actions Example

yaml

# .github/workflows/build.yml
name: Build RBgrid

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
      with:
        submodules: recursive

    - name: Setup ESP-IDF
      uses: espressif/esp-idf-ci-action@v1
      with:
        esp_idf_version: v5.1.2
        target: esp32

    - name: Build project
      run: |
        idf.py build

    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: RBgrid-firmware
        path: build/*.bin

Conclusion

ESP-IDF provides a powerful and flexible development environment for RBgrid. Proper project setup ensures:

Maximum performance
Convenient debugging
Easy integration with other components
Support for modern development tools

Overview

Web App

RBgrid library Installation

Introduction

Requirements

Software Versions

Supported Platforms

Step 1: Installing ESP-IDF

Windows

Linux/macOS

Verify Installation

Step 2: Creating Project Structure

Basic ESP-IDF Project Structure

Creating the Project

Step 3: Configuring CMakeLists.txt

Main CMakeLists.txt (project root)

CMakeLists.txt for main component

Step 4: Adding RBgrid as Component

Option 1: Clone Repository

Option 2: Add as Submodule

Option 3: Using IDF Component Manager

Step 5: Project Configuration

Creating sdkconfig.defaults

Configuration via menuconfig

Step 6: Partition Table (Optional)

Creating partitions.csv

Activating Custom Partition Table

Step 7: Configuring RBgrid Component

CMakeLists.txt for RBgrid

idf_component.yml for RBgrid

Step 8: Main File Example

Step 9: Build and Flash

Build Commands

Flash Speed Configuration

Step 10: Compiler Optimization

Compilation Flags for Maximum Performance

Linker Configuration

Troubleshooting

Common Errors and Solutions

1. Error: "Arduino.h not found"

2. Error: "undefined reference to setup/loop"

3. Error: "Region IRAM overflow"

4. Warning: "Component not found"

Useful Debug Commands

VS Code Integration

Installing ESP-IDF Extension

Settings File .vscode/settings.json

Tasks File .vscode/tasks.json

Using with Docker

Dockerfile for Building

Building in Docker

Continuous Integration

GitHub Actions Example

Conclusion