jason-mao/gmf_board_manager

readme

# GMF Board Manager

This is a board management module developed by Espressif that focuses solely on the initialization of development board devices. It uses YAML files to describe the configuration of peripheral interfaces on the main controller and external functional devices, and automatically generates configuration code, greatly simplifying the process of adding new boards. It provides a unified device management interface, which not only improves the reusability of device initialization code, but also greatly facilitates application adaptation to various development boards.

## Features

* **YAML Configuration**: Declarative hardware configuration using YAML files for peripherals, devices, and board definitions
* **Flexible Board Management**: Provides a unified initialization process with support for user-defined customization
* **Unified API Interfaces**: Consistent APIs for accessing peripherals and devices across different board configurations
* **Code Generation**: Automatically generates C code from YAML configurations
* **Automatic Dependency Management**: Automatically updates `idf_component.yml` files based on peripheral and device dependencies
* **Multiple Board Support**: Supports easy configuration and switching between multiple customer boards using a modular architecture
* **Extensible Architecture**: Allows easy integration of new peripherals and devices, including support for different versions of existing components
* **Comprehensive Error Management**: Provides unified error codes and robust error handling with detailed messages
* **Low Memory Footprint**: Stores only essential runtime pointers in RAM; configuration data remains read-only in flash

## Project Structure

```
gmf_board_manager/
├── board_manager.h/c          # Main board manager API
├── board_periph.h/c           # Peripheral management
├── board_devices.h/c          # Device management
├── board_err.h/c              # Unified error management system
├── board_names.h              # Key characters
├── peripherals/               # Peripheral implementations
│   ├── periph_gpio.c/py/h     # GPIO peripheral
│   ├── ...
├── devices/                   # Device implementations
│   ├── dev_audio_codec/       # Audio codec device
│   ├── ...
├── boards/                    # Default board-specific configurations
│   ├── echoear_core_board_v1_0/
│   │   ├── board_peripherals.yaml
│   │   ├── board_devices.yaml
│   │   ├── board_info.yaml
│   │   └── Kconfig
│   └── ...
├── generators/                # Code generation system
├── gen_codes/                 # Generated files (auto-created)
│   └── Kconfig.in             # Unified Kconfig menu
├── user project components/gen_bmgr_codes/ # Generated board config files (auto-created)
│   ├── gen_board_periph_config.c
│   ├── gen_board_periph_handles.c
│   ├── gen_board_device_config.c
│   ├── gen_board_device_handles.c
│   ├── gen_board_info.c
│   ├── CMakeLists.txt
│   └── idf_component.yml
├── gen_config_codes.py        # Main code generation script
├── gen_kconfig.py             # Kconfig generation script
├── gmf_board_manager_ext.py   # IDF action extension
├── README.md                  # This file
└── README_CN.md               # Chinese version Readme
```

## Quick Start

### 1. Setup IDF Action Extension

The GMF Board Manager now supports IDF action extension, providing seamless integration with the ESP-IDF build system. Set the `IDF_EXTRA_ACTIONS_PATH` environment variable to include the GMF Board Manager directory:

```bash
export IDF_EXTRA_ACTIONS_PATH=/PATH/TO/YOUR_PATH/gmf_board_manager
```

If you add this component to your project's yml dependency, you can use the following path instead:

```bash
export IDF_EXTRA_ACTIONS_PATH=YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__gmf_board_manager
```

If you encounter any issues, please refer to the ## Troubleshooting section.

### 2. Scan Boards and select board

You can discover available boards using the `-l` option:

```bash
# List all available boards
idf.py gmf-gen-config -l

# Or use the standalone script
python YOUR_BOARD_MANAGER_PATH/gen_config_codes.py -l
```

Then select your target board:
```bash
idf.py gmf-gen-config -b YOUR_TARGET_BOARD
```

### 3. Use in Your Application

```c
#include <stdio.h>
#include "esp_log.h"
#include "esp_err.h"
#include "board_manager.h"
#include "board_periph.h"
#include "board_devices.h"
#include "dev_audio_codec.h"
#include "dev_display_lcd_spi.h"

static const char *TAG = "MAIN";

void app_main(void)
{
    // Initialize board manager
    ESP_LOGI(TAG, "Initializing board manager...");
    int ret = board_manager_init();
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize board manager");
        return;
    }

    // Get peripheral handle
    void *spi_handle;
    ret = board_manager_get_periph_handle("spi-1", &spi_handle);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to get SPI peripheral");
        return;
    }

    // Get device handle
    dev_display_lcd_spi_handles_t *lcd_handle;
    ret = board_manager_get_device_handle("lcd_display", &lcd_handle);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to get LCD device");
        return;
    }

    // Get device configuration
    audio_codec_config_t *device_config;
    ret = board_manager_get_device_config("audio_dac", &device_config);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to get device config");
        return;
    }

    // Print board information
    board_manager_print_board_info();

    // Print board manager status
    board_manager_print();

    // Use the handles...
}
```

### 4. More Examples

For comprehensive usage examples, refer to the test applications in the `test_apps/main/` directory:

#### Device Examples
- **[`test_dev_audio_codec.c`](test_apps/main/test_dev_audio_codec.c)** - Audio codec with DAC/ADC, SD card playback, recording, and loopback testing
- **[`test_dev_lcd_init.c`](test_apps/main/test_dev_lcd_init.c)** - LCD display initialization and basic control
- **[`test_dev_lcd_lvgl.c`](test_apps/main/test_dev_lcd_lvgl.c)** - LCD display with LVGL, touch screen, and backlight control
- **[`test_dev_pwr_ctrl.c`](test_apps/main/test_dev_pwr_ctrl.c)** - GPIO-based power management for LCD and audio devices
- **[`test_dev_fatfs_sdcard.c`](test_apps/main/test_dev_fatfs_sdcard.c)** - SD card operations and FATFS file system testing
- **[`test_dev_fs_spiffs.c`](test_apps/main/test_dev_fs_spiffs.c)** - SPIFFS file system testing

#### Peripheral Examples
- **[`test_periph_ledc.c`](test_apps/main/test_periph_ledc.c)** - LEDC peripheral for PWM and backlight control
- **[`test_periph_i2c.c`](test_apps/main/test_periph_i2c.c)** - I2C peripheral for device communication
- **[`test_periph_gpio.c`](test_apps/main/test_periph_gpio.c)** - GPIO peripheral for digital I/O operations

#### User Interface

Board Manager's device names are recommended for user projects, while peripheral names are not recommended. This is because device names are functionally named and do not contain additional information, making them easier to adapt to multiple boards. The device names provided by Board Manager are **reserved keywords**, see [board_names.h](./board_names.h). The following device names can be used in user applications:

| Device Name | Description |
|-------------|-------------|
| `audio_dac`, `audio_adc` | Audio codec devices |
| `display_lcd` | LCD display device |
| `fs_sdcard` | SD card device |
| `fs_spiffs` | SPIFFS filesystem device |
| `lcd_touch` | Touch screen device |
| `lcd_power` | LCD power control |
| `lcd_brightness` | LCD brightness control |

## YAML Configuration Rules
For detailed YAML configuration rules and format specifications, please refer to [Device and Peripheral Rules](docs/device_and_peripheral_rules.md).

## Custom Board

### Creating a New Board

#### Create board folder and files

1. **Create Board Directory**
   ```bash
   mkdir boards/<board_name>
   cd boards/<board_name>
   ```

2. **Create Required Files**
   ```bash
   touch board_peripherals.yaml
   touch board_devices.yaml
   touch board_info.yaml
   touch Kconfig
   ```

3. **Configure Kconfig**
   ```kconfig
   config BOARD_<BOARD_NAME>
       bool "<Board Display Name>"
       depends on SOC_<CHIP_TYPE>  # optional
   ```

4. **Add Board Info**
   ```yaml
   # board_info.yaml
   board: <board_name>
   chip: <chip_type>
   version: <version>
   description: "<board description>"
   manufacturer: "<manufacturer_name>"
   ```

5. **Define Peripherals**
   ```yaml
   # board_peripherals.yaml
   board: <board_name>
   chip: <chip_type>
   version: <version>

   peripherals:
     - name: <peripheral_name>
       type: <peripheral_type>
       role: <peripheral_role>
       config:
         # Peripheral-specific configuration
   ```

6. **Define Devices**
   ```yaml
   # board_devices.yaml
   board: <board_name>
   chip: <chip_type>
   version: <version>

   devices:
     - name: <device_name>
       type: <device_type>
       config:
         # Device-specific configuration
       peripherals:
         - name: <peripheral_name>
    ```

### Board Paths

The GMF Board Manager supports board configuration through three different path locations, providing flexibility for different deployment scenarios:

1. **Main Boards Directory**: Built-in boards provided with the package, path like `gmf_board_manager/boards`
2. **User Project Components**: Custom boards defined in project components, path like `{PROJECT_ROOT}/components/{component_name}/boards`
3. **Custom Customer Path**: External board definitions in custom locations. User-specified path via `-c` argument in `gen_config_codes.py`, use the command line like `idf.py -DBOARD_CUSTOMER_PATH=./path/to/boards menuconfig` to set the custom path.

### Verify and Use New Board

1. **Verify Board Configuration**
   ```bash
   # Test if your board configuration is valid
   # For main boards & user project components (default paths)
   idf.py gmf-gen-config -b <board_name>

   # For custom customer path (external locations)
   idf.py gmf-gen-config -b <board_name> -c /path/to/custom/boards

   # Or use the standalone script
   cd  YOUR_GMF_BOARD_MANAGER_PATH
   python gen_config_codes.py -b <board_name>
   python gen_config_codes.py -b <board_name> -c /path/to/custom/boards
   ```

   **Check for Success**: If the board configuration is valid, the following files will be generated on project path:
   - `components/gen_bmgr_codes/gen_board_periph_handles.c` - Peripheral handle definitions
   - `components/gen_bmgr_codes/gen_board_periph_config.c` - Peripheral configuration structures
   - `components/gen_bmgr_codes/gen_board_device_handles.c` - Device handle definitions
   - `components/gen_bmgr_codes/gen_board_device_config.c` - Device configuration structures
   - `components/gen_bmgr_codes/gen_board_info.c` - Board metadata
   - `components/gen_bmgr_codes/CMakeLists.txt` - Build system configuration
   - `components/gen_bmgr_codes/idf_component.yml` - Component dependencies

   **If errors occur**: Check your YAML files for syntax errors, missing fields, or invalid configurations.

   **Note**: The script will automatically generate the Kconfig menu system when you run `idf.py gmf-gen-config` for the first time.

## Supported Components

### Supported Peripheral types

| Peripheral | Type | Role | Status | Description |
|------------|------|------|--------|-------------|
| GPIO | gpio | output/input | ✅ Supported | General purpose I/O |
| I2C | i2c | master/slave | ✅ Supported | I2C communication |
| SPI | spi | master/slave | ✅ Supported | SPI communication |
| I2S | i2s | master/slave | ✅ Supported | Audio interface |
| LEDC | ledc | pwm | ✅ Supported | LED control/PWM |

### Supported Device types

| Device | Type | Chip | Peripheral | Status | Description | Test Functions |
|--------|------|------|------------|--------|-------------|----------------|
| Audio Codec | audio_codec | ES8311 | i2s/i2c | ✅ Supported | Audio codec with DAC/ADC | Audio playback, recording, loopback |
| Audio Codec | audio_codec | ES7210 | i2s/i2c | ✅ Supported | Audio ADC codec | Audio recording, microphone test |
| Audio Codec | audio_codec | ES8388 | i2s/i2c | ✅ Supported | Audio codec with DAC | Audio playback, speaker test |
| LCD Display | display_lcd_spi | ST77916 | spi | ✅ Supported | SPI LCD display | Display test, screen alignment |
| LCD Display | display_lcd_spi | GC9A01 | spi | ✅ Supported | Round LCD display | Dual display test |
| Touch Screen | lcd_touch_i2c | FT5x06 | i2c | ✅ Supported | I2C touch screen | Touch test, button test |
| SD Card | fatfs_sdcard | - | sdmmc | ✅ Supported | SD card storage | SD card test, IMU test |
| SPIFFS Filesystem | fs_spiffs | - | - | ✅ Supported | SPIFFS filesystem | Filesystem test |
| GPIO Control | gpio_ctrl | - | gpio | ✅ Supported | GPIO control device | Power control test |
| LEDC Control | ledc_ctrl | - | ledc | ✅ Supported | LEDC control device | PWM control test |
| IMU | imu | BMI270 | i2c | ❌ | Inertial measurement unit | IMU test, sensor test |

### Supported Boards

| Board Name | Chip | Audio | SDCard | LCD | LCD Touch |
|------------|------|-------|--------|-----|-----------|
| Echoear Core Board V1.0 | ESP32-S3 | ✅ ES8311 + ES7210 | ✅ SDMMC | ✅ ST77916 | ✅ FT5x06 |
| Dual Eyes Board V1.0 | ESP32-S3 | ✅ ES8311 | ❌ | ✅ GC9A01 (Dual) | ❌ |
| ESP-BOX-3 | ESP32-S3 | ✅ ES8311 + ES7210 | ✅ SDMMC | ✅ ST77916 | ✅ FT5x06 |
| ESP32-S3 Korvo2 V3 | ESP32-S3 | ✅ ES8311 + ES7210 | ✅ SDMMC | ❌ | ❌ |
| ESP32-S3 Korvo2L | ESP32-S3 | ✅ ES8311 | ✅ SDMMC | ❌ | ❌ |
| Lyrat Mini V1.1 | ESP32-S3 | ✅ ES8388 | ✅ SDMMC | ❌ | ❌ |
| ESP32-C5 Spot | ESP32-C5 | ✅ ES8311 (Dual) | ❌ | ❌ | ❌ |

## Board Manager Settings

### Automatic SDK Configuration Update

Control whether the board manager automatically updates sdkconfig based on detected device and peripheral types.

**Default**: Enabled (`y`)

**Disable via sdkconfig**:
```bash
# Use menuconfig
idf.py menuconfig
# Navigate to: Component config → GMF Board Manager Configuration → Board Manager Setting

# Set in sdkconfig
CONFIG_GMF_BOARD_MANAGER_AUTO_CONFIG_DEVICE_AND_PERIPHERAL=n
```
If you want to enable devices or peripherals type beyond what's defined in YAML, disable this option.

## Script Execution Process

The GMF Board Manager uses `gen_config_codes.py` for code generation, which handles both Kconfig menu generation and board configuration generation in a unified workflow.

### `gen_config_codes.py` - Configuration Generator

Executes a comprehensive 8-step process to convert YAML configurations into C code and build system files:

1. **Board Directory Scanning**: Discovers boards across default, customer, and component directories
2. **Board Selection**: Reads board selection from sdkconfig or command line arguments
3. **Kconfig Generation**: Creates unified Kconfig menu system for board and component selection
4. **Configuration File Discovery**: Locates `board_peripherals.yaml` and `board_devices.yaml` for selected board
5. **Peripheral Processing**: Parses peripheral configurations and generates C structures
6. **Device Processing**: Processes device configurations, dependencies, and updates build files
7. **Project sdkconfig Configuration**: Updates project sdkconfig based on board device and peripheral types
8. **File Generation**: Creates all necessary C configuration and handle files in project folder `components/gen_bmgr_codes/`

#### Command Line Options

**Board Selection:**
```bash
-b, --board BOARD_NAME           # Specify board name directly (bypasses sdkconfig reading)
-c, --customer-path PATH         # Path to customer boards directory (use "NONE" to skip)
-l, --list-boards               # List all available boards and exit
```

**Generation Control:**
```bash
--kconfig-only                  # Only generate Kconfig menu system (skip board configuration generation)
--peripherals-only              # Only process peripherals (skip devices)
--devices-only                  # Only process devices (skip peripherals)
```

**The SDKconfig Configuration:**
```bash
--sdkconfig-only                # Only check sdkconfig features without enabling them
--disable-sdkconfig-auto-update # Disable automatic sdkconfig feature enabling (default is enabled)
```

**Logging Control:**
```bash
--log-level LEVEL               # Set log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
```

#### Usage Examples


### Setup IDF Action Extension (Recommended)

The GMF Board Manager now supports IDF action extension, providing seamless integration with the ESP-IDF build system:

#### Installation

Set the `IDF_EXTRA_ACTIONS_PATH` environment variable to include the GMF Board Manager directory:

```bash
export IDF_EXTRA_ACTIONS_PATH="/PATH/TO/YOUR_PATH/gmf_board_manager"
```

#### Usage

```bash
# Basic usage
idf.py gmf-gen-config -b echoear_core_board_v1_0

# With custom boards
idf.py gmf-gen-config -b my_board -c /path/to/custom/boards

# Generate Kconfig only
idf.py gmf-gen-config --kconfig-only

# Process peripherals only
idf.py gmf-gen-config -b echoear_core_board_v1_0 --peripherals-only

# List available boards
idf.py gmf-gen-config -l

# Set log level to DEBUG for detailed output
idf.py gmf-gen-config --log-level DEBUG
```

### Method 2: Standalone Script

You can also use the standalone script directly in the gmf_board_manager directory.

**The following describes all parameters supported by `gen_config_codes.py`, which also apply to `idf.py gmf-gen-config`:**

**Basic Usage:**
```bash
# Use sdkconfig and default boards
python gen_config_codes.py

# Specify board directly
python gen_config_codes.py -b echoear_core_board_v1_0

# Add customer boards directory
python gen_config_codes.py -c /path/to/custom/boards

# Both board and custom path
python gen_config_codes.py -b my_board -c /path/to/custom/boards

# List available boards
python gen_config_codes.py -l

# Disable automatic sdkconfig updates
python gen_config_codes.py --disable-sdkconfig-auto-update

# Set log level to DEBUG for detailed output
python gen_config_codes.py --log-level DEBUG
```

**Partial Generation:**
```bash
# Only process peripherals
python gen_config_codes.py --peripherals-only

# Only process devices
python gen_config_codes.py --devices-only

# Check sdkconfig features without enabling
python gen_config_codes.py --sdkconfig-only
```

#### Generated Files

**Configuration Files:**
- `gen_codes/Kconfig.in` - Unified Kconfig menu for board selection
- `components/gen_bmgr_codes/gen_board_periph_config.c` - Peripheral configurations
- `components/gen_bmgr_codes/gen_board_periph_handles.c` - Peripheral handles
- `components/gen_bmgr_codes/gen_board_device_config.c` - Device configurations
- `components/gen_bmgr_codes/gen_board_device_handles.c` - Device handles
- `components/gen_bmgr_codes/gen_board_info.c` - Board metadata
- `components/gen_bmgr_codes/CMakeLists.txt` - Build system configuration
- `components/gen_bmgr_codes/idf_component.yml` - Component dependencies

**Note:** Generated files are organized as follows:
- Kconfig files are placed in the `gen_codes/` directory
- Board configuration files are placed in `components/gen_bmgr_codes/` directory to integrate with the ESP-IDF build system
- These directories are automatically created by the generation scripts if they don't exist and should not be manually modified

## Roadmap

Future development plans for the GMF Board Manager:
- **Build Workflow**: Improve the efficiency and streamline the build workflow
- **Version Management**: Support different version codes and parsers for devices and peripherals
- **Plugin Architecture**: Extensible plugin system for custom device and peripheral support
- **Enhanced Validation**: Comprehensive YAML format checking, schema validation, input validation, and enhanced rule validation with improved error reporting
- **Enhanced Initialization Flow**: Support for skipping specific components or calling initialization on different cores
- **Clear Definition Rules**: Establish clear rules to facilitate customer addition of peripherals and devices
- **Extended Component Support**: Add more peripherals, devices, and boards

## Troubleshooting

### No `gmf_board_manager` path
1. Check the `gmf_board_manager` dependency in your project's main `idf_component.yml`
2. Run `idf.py menuconfig` or `idf.py build` after adding the `gmf_board_manager` dependency. These commands will download the `gmf_board_manager` to `YOUR_PROJECT_ROOT_PATH/managed_components/`

### `idf.py gmf-gen-config` Command Not Found

If `idf.py gmf-gen-config` is not recognized:

1. Check that `IDF_EXTRA_ACTIONS_PATH` is set correctly
2. Restart your terminal session

### `undefined reference for g_board_devices and g_board_peripherals`
1. Make sure there is no `idf_build_set_property(MINIMAL_BUILD ON)` in your project, because MINIMAL_BUILD only performs a minimal build by including only the "common" components required by all other components.
2. Ensure your project has a `components/gen_bmgr_codes` folder with generated files. These files are generated by running `idf.py gmf-gen-config -b YOUR_BOARD`.

### **Switching Boards**
Using `idf.py gmf-gen-config -b` is strongly recommended. Using `idf.py menuconfig` to select boards may result in dependency errors.

## License

This project is licensed under the Modified MIT License - see the [LICENSE](./LICENSE) file for details.