jason-mao/gmf_board_manager

readme

# GMF Board Manager

A comprehensive board configuration management system for ESP32-based projects, designed to simplify hardware abstraction and device management across different development boards.

## Overview

GMF Board Manager provides a unified interface for managing board peripherals and devices through YAML configuration files. It automatically generates C code for peripheral and device initialization, making it easy to support multiple boards with minimal code changes.

## Key Features

### 🎯 **Multi-Path Board Scanning**
- **Main boards directory**: Default board configurations
- **Custom customer path**: User-defined board configurations via `BOARD_CUSTOMER_PATH`
- **Component boards**: Automatic scanning of `components/` directories for board configurations

### 🔧 **Automatic Board Selection**
- Reads `sdkconfig` to determine selected board via `CONFIG_BOARD_XX=y` configuration
- Supports menuconfig integration for easy board selection
- Fallback to default board if no selection is found

### 📝 **YAML-Based Configuration**
- **board_peripherals.yaml**: Define I2C, I2S, GPIO, SPI, and other peripherals
- **board_devices.yaml**: Configure audio codecs, SD cards, sensors, and other devices
- **board_info.yaml**: Board metadata and version information

### 🔄 **Automatic Code Generation**
- Generates C configuration structures from YAML files
- Creates peripheral and device handles
- Supports custom parser extensions for new peripheral/device types

## Project Structure

```
gmf_board_manager/
├── board_manager/                 # Core board manager component
│   ├── boards/                   # Board configuration directories
│   │   ├── esp32_s3_korvo2_v3/  # Example board
│   │   │   ├── board_peripherals.yaml
│   │   │   ├── board_devices.yaml
│   │   │   ├── board_info.yaml
│   │   │   └── Kconfig
│   │   └── ...
│   ├── devices/                  # Device parser implementations
│   ├── peripherals/              # Peripheral parser implementations
│   ├── board_manager.c          # Main board manager implementation
│   ├── board_manager.h          # Public API header
│   ├── gen_config_codes.py      # Code generation script
│   └── gen_unified_kconfig.py   # Kconfig generation script
├── main/                        # Example application
├── components/                   # Additional components
└── CMakeLists.txt              # Build configuration
```

## Quick Start

### 1. Basic Usage

```bash
# In your project directory
idf.py menuconfig
# Navigate to: Component config → Board Manager → Select target board
# Choose your board and save

idf.py build
```

### 2. Adding Custom Board Path

In your project's `CMakeLists.txt`:
```cmake
set(BOARD_CUSTOMER_PATH "path/to/your/boards")
```

Or via command line:
```bash
idf.py -DBOARD_CUSTOMER_PATH="path/to/your/boards" build
```

### 3. Using Board Manager API

```c
#include "board_manager.h"

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

    // Get I2C peripheral handle
    void *i2c_handle;
    ret = board_manager_get_periph_handle("i2c-0", &i2c_handle);
    if (ret == ESP_OK) {
        // Use i2c_handle for I2C operations
    }

    // Initialize and get audio codec device
    ret = board_manager_init_device_by_name("es8311");
    if (ret == ESP_OK) {
        void *codec_handle;
        ret = board_manager_get_device_handle("es8311", &codec_handle);
        if (ret == ESP_OK) {
            // Use codec_handle for audio operations
        }
    }

    // Cleanup
    board_manager_deinit();
}
```

## Configuration Files

### Board Peripherals (board_peripherals.yaml)

```yaml
peripherals:
  - name: i2c-0
    type: i2c
    role: master
    config:
      port: 0
      enable_internal_pullup: true
      glitch_count: 7
      pins:
        sda: 17
        scl: 18

  - name: i2s-0-0
    type: i2s
    role: master
    format: std-out
    config:
      sample_rate_hz: 48000
      mclk_multiple: 256
      bclk_div: 8
      data_bit_width: 16
      slot_mode: STEREO
      pins:
        mclk: 16
        bclk: 9
        ws: 45
        dout: 8
        din: 10
```

### Board Devices (board_devices.yaml)

```yaml
devices:
  - name: audio_dac
    chip: es8311
    type: audio_codec
    version: default
    config:
      adc_enabled: false
      dac_enabled: true
      dac_max_channel: 1
      dac_channel_mask: "1"
      dac_init_gain: 0
      mclk_enabled: false
      aec: false
      eq: false
      alc: true

    peripherals:
      - name: gpio-48
        gain: 6
        active_level: 1
      - name: i2s-0-0
      - name: i2c-0
        address: 0x30
        frequency: 400000
```

## Supported Peripherals

| Peripheral | Support Status | Features |
|------------|----------------|----------|
| **I2C** | ✅ Fully Supported | Master/slave mode, configurable pins, pullup, glitch filter |
| **I2S** | ✅ Fully Supported | Standard format, configurable sample rate, bit width, slot mode |
| **GPIO** | ✅ Fully Supported | Input/output modes, pullup/pulldown, interrupt configuration |
| **SPI** | 🔄 In Development | Master/slave mode, configurable pins, frequency, mode |
| **UART** | 🔄 In Development | Configurable baud rate, data bits, stop bits, parity |
| **PWM** | 📋 Planned | Configurable frequency, duty cycle, channels |
| **ADC** | 📋 Planned | Configurable resolution, channels, attenuation |

## Supported Boards

| Board Name | Description | Chip | Audio | SDCard | LCD | Touch | IMU |
|------------|-------------|------|-------|--------|-----|-------|-----|
| **ESP32-S3 Korvo2 V3** | ESP32-S3 Korvo2 V3 Development Board | ESP32-S3 | ✅ ES8311 + ES7210 | ✅ SDMMC | ❌ | ❌ | ❌ |
| **ESP32-S3 Korvo2L** | ESP32-S3 Korvo 2L | ESP32-S3 | ✅ ES8311 | ✅ SDMMC | ❌ | ❌ | ❌ |
| **ESP32 Lyrat Mini V1.1** | ESP32 Lyrat Mini V1.1 Development Board | ESP32 | ✅ ES8388 | ✅ SDMMC | ❌ | ❌ | ❌ |
| **ESP32-C5 Spot** | ESP32-C5 Spot AI Voice Interaction Module | ESP32-C5 | ✅ ES8311 (Dual) | ❌ | ❌ | ❌ | ✅ BMI270 |
| **ESP32-C6 DevKit** | ESP32-C6 Development Kit | ESP32-C6 | ❌ | ❌ | ❌ | ❌ | ❌ |
| **ESP32-S3 Box Lite** | ESP32-S3 Box Lite | ESP32-S3 | ❌ | ❌ | ❌ | ❌ | ❌ |
| **ESP32-P4 Function EV Board** | ESP32-P4 Function Evaluation Board | ESP32-P4 | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Echoear Core Board V1.0** | Echoear Core Board V1.0 | ESP32-S3 | ❌ | ❌ | ❌ | ❌ | ❌ |

**Legend:**
- ✅ **Supported** - Fully implemented and tested
- ❌ **Not Supported** - No implementation available
- 🔄 **In Development** - Implementation in progress

## Supported Devices

| Device Type | Support Status | Supported Models | Features |
|-------------|----------------|------------------|----------|
| **Audio Codecs** | ✅ Fully Supported | ES8311, ES7210, ES7243, ES8388 | DAC/ADC, gain control, ALC, EQ |
| **SD Cards** | ✅ Fully Supported | SD/SDHC/SDXC | SDMMC interface, configurable pins |
| **Sensors** | 🔄 In Development | BMI270 (IMU) | I2C/SPI interface, calibration |
| **Displays** | 📋 Planned | LCD, OLED | Various interfaces (SPI, I2C, Parallel) |
| **Custom Devices** | ✅ Extensible | User-defined | Parser system for custom implementations |

## Extending the System

### Adding New Peripheral Types

1. Create parser in `peripherals/`:
```python
# peripherals/parse_my_periph.py
def parse_my_periph(config):
    # Parse configuration and return C structure
    return {
        'port': config.get('port', 0),
        'frequency': config.get('frequency', 1000000),
        # ... other fields
    }
```

2. Register in `peripheral_parser.py`:
```python
from peripherals.parse_my_periph import parse_my_periph

PERIPHERAL_PARSERS = {
    'my_periph': parse_my_periph,
    # ... existing parsers
}
```

### Adding New Device Types

1. Create parser in `devices/`:
```python
# devices/parse_my_device.py
def parse_my_device(config, peripherals):
    # Parse device configuration
    return {
        'device_type': 'MY_DEVICE',
        'config': config,
        'peripherals': peripherals
    }
```

2. Register in `device_parser.py`:
```python
from devices.parse_my_device import parse_my_device

DEVICE_PARSERS = {
    'my_device': parse_my_device,
    # ... existing parsers
}
```

## Build System Integration

The board manager integrates seamlessly with ESP-IDF build system:

- **Automatic code generation** during build process
- **Menuconfig integration** for board selection
- **Component-based architecture** for easy integration
- **CMake support** for custom board paths

## Error Handling

The system provides comprehensive error handling:

- **Board not found**: Detailed error with available boards list
- **Missing configuration files**: Clear error messages with file paths
- **Invalid configurations**: Validation with helpful error messages
- **Runtime errors**: ESP-IDF error codes with descriptive messages

## Testing

Run the test suite:
```bash
cd board_manager
python test_main.py
```

The test suite covers:
- Board directory scanning
- SDKConfig parsing
- Configuration file validation
- Code generation verification

## Examples

See the `main/` directory for complete example applications demonstrating:
- Basic board manager usage
- Audio codec initialization
- SD card operations
- Custom device integration

## Contributing

1. Follow the existing code structure and naming conventions
2. Add tests for new features
3. Update documentation for new peripherals/devices
4. Ensure backward compatibility

## License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

## Support

For issues and questions:
- Check the existing documentation in `board_manager/README_BOARD_MANAGER.md`
- Review the implementation summary in `board_manager/IMPLEMENTATION_SUMMARY.md`
- Test with the provided example applications