🔧 HardFOC Internal Interface Layer:

Multi-MCU Peripherals Interface

🎯 Universal Hardware Interface for Multi-MCU Development

A professional hardware abstraction layer enabling seamless MCU portability through unified peripheral APIs - designed for the HardFOC board ecosystem

🎯 Overview

‍📖 📚🌐 Live Complete Documentation - Interactive guides, examples, and step-by-step tutorials

This Internal Interface Wrap (IID) provides a unified interface for common MCU peripherals, enabling seamless portability between different microcontroller platforms. Originally designed for the HardFOC board which needs to support multiple MCU types, this abstraction layer allows developers to write hardware-agnostic code while maintaining optimal performance.

🏆 Core Benefits

• 🔄 MCU Portability - Write once, run on multiple MCU platforms
• 🎯 Unified APIs - Consistent interface across all peripheral types
• ⚡ Performance - Zero-cost abstractions with compile-time optimization
• 🛡️ Type Safety - Strong typing with project-specific type system
• 📈 Extensible - Easy to add new MCUs and peripheral drivers
• 🔌 Complete Coverage - 14+ peripheral interfaces for comprehensive hardware control

🎨 Design Philosophy

// Write hardware-agnostic code
BaseGpio* led = GpioFactory::Create(GPIO_PIN_2, GPIO_OUTPUT);
led->SetHigh();
 
// Same code works on ESP32, STM32, or any supported MCU
// The factory handles MCU-specific implementation selection

🔌 Peripheral Interfaces

‍📖 📚🌐 Live Complete Documentation - Interactive guides, examples, and step-by-step tutorials

Core Peripherals

| Interface | Purpose | Key Features |

|------------—|----------—|---------------—|

| BaseGpio | Digital I/O control | Input/output, interrupts, pull-up/down |

| BaseAdc | Analog measurement | Multi-channel, calibration, DMA support |

| BasePwm | Motor/servo control | Frequency control, duty cycle, phase alignment |

| BaseUart | Serial communication | Async I/O, flow control, custom baud rates |

Communication Buses

| Interface | Purpose | Key Features |

|------------—|----------—|---------------—|

| BaseI2c | Sensor communication | Master/slave, clock stretching, error recovery |

| BaseSpi | High-speed data | Full/half duplex, DMA, chip select management |

| BaseCan | Automotive/industrial | Message filtering, error handling, bus monitoring |

Wireless Connectivity

| Interface | Purpose | Key Features |

|------------—|----------—|---------------—|

| BaseWifi | Network connectivity | STA/AP modes, WPA3 security, power management |

| BaseBluetooth | Short-range wireless | Classic/BLE, pairing, service discovery |

System Services

| Interface | Purpose | Key Features |

|------------—|----------—|---------------—|

| BaseNvs | Configuration storage | Key-value pairs, encryption, wear leveling |

| BaseLogger | Debug/monitoring | Multiple levels, async logging, filtering |

| BaseTemperature | Thermal monitoring | Internal/external sensors, calibration |

| BasePeriodicTimer | Task scheduling | Precise timing, ISR-safe callbacks |

| BasePio | Advanced GPIO | State machines, DMA, complex protocols |

🚀 Quick Start

1. Clone Repository

git clone <repository-url>
cd hf-internal-interface-wrap

2. Setup Development Environment

## For ESP32 development
cd examples/esp32
./scripts/setup_repo.sh

3. Build Example

## Build GPIO test for ESP32
./scripts/build_app.sh gpio_test Release esp32

4. Flash and Monitor

## Flash to connected ESP32
./scripts/flash_app.sh gpio_test Release flash
 
## Monitor serial output
./scripts/flash_app.sh gpio_test Release monitor

5. Basic Usage

#include "base/BaseGpio.h"
#include "mcu/esp32/EspGpio.h"
 
void setup() {
    // Create GPIO instance for built-in LED
    BaseGpio* led = new EspGpio(GPIO_NUM_2, GPIO_MODE_OUTPUT);
    
    // Blink LED
    while(true) {
        led->SetHigh();
        vTaskDelay(pdMS_TO_TICKS(500));
        led->SetLow();
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

🔧 Building

Build System Features

• Multi-MCU Support - Single build system for all platforms
• Automated Testing - Comprehensive test suites
• CI/CD Integration - Automated builds and validation

Build Commands

## Build specific application
./scripts/build_app.sh <app_name> <build_type> <target>
 
## Examples:
./scripts/build_app.sh gpio_test Debug esp32
./scripts/build_app.sh pwm_test Release esp32c6
./scripts/build_app.sh uart_test Debug esp32s3

yaml

Configuration

Applications are configured in examples/esp32/app_config.yml:

applications:
  gpio_test:
    source_file: "GpioComprehensiveTest.cpp"
    description: "GPIO interface testing"
    enabled: true
    
  pwm_test:
    source_file: "PwmComprehensiveTest.cpp" 
    description: "PWM interface testing"
    enabled: true

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create feature branch (feature/new-mcu-support)
3. Implement following coding standards
4. Test with existing applications
5. Document your changes
6. Submit pull request

Adding New Peripherals

1. Create base interface in inc/base/BaseYourPeripheral.h
2. Implement for ESP32 in inc/mcu/esp32/EspYourPeripheral.h
3. Add comprehensive tests in examples/esp32/main/
4. Update documentation

Coding Standards

• Functions: CamelCase (SetDutyCycle, ReadValue)
• Types: snake_case with *t suffix (hf_gpio_state_t)
• Enums: snake_case enum class (hf_adc_err_t)
• Logging: Use Logger::GetInstance() for all output

🔗 Quick Links

Documentation

• 📚 API Reference - Complete interface documentation
• 🔧 ESP32 Implementations - Hardware-specific implementations
• 🛠️ Utility Classes - Advanced utility classes and helpers
  • McuSelect.h - Centralized MCU platform selection and configuration
• 🔧 Build System - Build and deployment guides
• 🛡️ CI/CD Pipeline - Advanced automated workflows and testing

Development

• 🚀 Examples - Test applications and usage examples
• 🧪 Test Documentation - Comprehensive test documentation
• 🔧 Scripts - Build, flash, and development tools
• 📊 Configuration - Application and build settings

Community

• 🤝 Contributing - Please refer to the HardFOC community for contribution guidelines