🚀 HardFOC Interface Wrapper API Reference

HardFOC Interface

🎯 Hardware Abstraction Layer for Embedded Systems

A platform-agnostic interface wrapper for hardware peripherals

📚 Table of Contents

🎯 Overview

The HardFOC Interface Wrapper provides a unified, platform-agnostic abstraction layer for embedded hardware peripherals. It enables developers to write portable, maintainable code that works across different microcontrollers and hardware platforms without modification.

✨ Key Benefits

  • 🔄 Platform Portability - Write once, run anywhere
  • 🛡️ Type Safety - Strongly typed interfaces with error handling
  • ⚡ Performance Optimized - Minimal overhead with direct hardware access
  • 🔧 Extensible - Easy to add new hardware platforms and peripherals
  • 📊 Observable - Built-in statistics, diagnostics, and monitoring
  • 🧵 Thread Safe - Designed for multi-threaded applications

🎯 Target Applications

  • Motor Control Systems - FOC, BLDC, stepper motor control
  • Sensor Networks - Multi-sensor data acquisition and processing
  • Communication Systems - CAN, UART, I2C, SPI protocols
  • Industrial Automation - PLC-like control systems
  • IoT Devices - Connected embedded systems
  • Robotics - Real-time control and sensing

🏗️ Architecture

Design Philosophy

The HardFOC Interface follows a layered abstraction pattern:

1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────┐
│           Application Layer         │
├─────────────────────────────────────┤
│         Interface Wrapper           │
├─────────────────────────────────────┤
│        Platform Implementation      │
├─────────────────────────────────────┤
│           Hardware Layer            │
└─────────────────────────────────────┘

Core Components

  1. Base Classes - Abstract interfaces defining the API contract
  2. Platform Implementations - Concrete implementations for specific hardware
  3. Utility Classes - Helper classes for common patterns
  4. Type System - Platform-agnostic type definitions

Error Handling Strategy

  • Comprehensive Error Codes - Detailed error enumeration for each peripheral
  • String Conversion - Human-readable error messages
  • Error Recovery - Recovery mechanisms where possible
  • Diagnostics - Runtime error tracking and statistics

📋 Base Classes

The HardFOC Interface provides abstract base classes for all major hardware peripherals:

Class Purpose Key Features Typical Use Cases

|——-|———|————–|——————-|

| BaseAdc | Analog-to-Digital Conversion | Multi-channel, calibration | Sensor reading |

| BaseGpio | Digital I/O Control | Dynamic direction, interrupts | Status LEDs, switches |

BaseI2c I2C Bus Communication Device scanning, register access EEPROM, sensors
BaseNvs Non-Volatile Storage Key-value storage, namespaces Configuration storage

| BasePeriodicTimer | High-Precision Timing | Microsecond resolution, callbacks | Control loops, sampling |

BasePio Programmable I/O Precise timing, symbol transmission WS2812 LEDs, IR
BasePwm Pulse Width Modulation Multi-channel, frequency control Motor control, LED
BaseSpi SPI Bus Communication Full-duplex transfers, chip select Flash memory, ADCs
BaseUart Serial Communication Flow control, buffering, printf support Debug output, GPS
BaseCan CAN Bus Communication Message filtering, error handling Motor control, vehicle
BaseWifi WiFi Communication Station/AP modes, security IoT connectivity
BaseBluetooth Bluetooth Communication Classic & BLE, pairing Mobile apps, wireless
BaseTemperature Temperature Sensing Multi-sensor support, calibration System monitoring
BaseLogger System Logging Multi-level logging, multiple outputs Debugging, diagnostics

🔧 ESP32 Implementations

ESP32-C6 specific implementations with optimized features:

Implementation Base Class ESP32-C6 Features Documentation

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

| EspGpio | BaseGpio | Drive strength, slew rate, interrupts | ✅ Complete |

EspAdc BaseAdc 12-bit resolution, multiple units ✅ Available
EspPwm BasePwm LEDC controller, fade effects 📝 In Progress
EspI2c BaseI2c Clock stretching, multi-master 📝 In Progress
EspSpi BaseSpi Full-duplex, DMA support ✅ Complete
EspUart BaseUart Hardware flow control 📝 In Progress
EspCan BaseCan TWAI controller 📝 In Progress
EspWifi BaseWifi 802.11n, WPA3, mesh 📝 In Progress
EspBluetooth BaseBluetooth Classic & BLE support 📝 In Progress
EspTemperature BaseTemperature Internal sensor, calibration 📝 In Progress
EspLogger BaseLogger UART, network, file output 📝 In Progress

🎯 Type System

Platform-agnostic type definitions for consistent APIs:

Documentation Description Status

|—————|————-|——–|

HardwareTypes Core type definitions, validation functions ✅ Complete

Core Types 

1
2
3
4
5
6
7
8
9
10
11

// Integer types
using hf_u8_t = uint8_t;
using hf_u16_t = uint16_t;
using hf_u32_t = uint32_t;
using hf_u64_t = uint64_t;

// Hardware types
using hf_pin_num_t = hf_i32_t;
using hf_channel_id_t = hf_u32_t;
using hf_frequency_hz_t = hf_u32_t;
using hf_time_t = hf_u32_t;

📊 Getting Started

1. Include the Headers 

1
2
3
4
5
6
7

// Base classes (abstract interfaces)
#include "inc/base/BaseAdc.h"
#include "inc/base/BaseGpio.h"

// Platform implementations
#include "inc/mcu/esp32/EspAdc.h"
#include "inc/mcu/esp32/EspGpio.h"

2. Create Hardware Instances 

1
2
3

// Use platform-specific implementations
EspAdc adc(ADC_UNIT_1, ADC_ATTEN_DB_11);
EspGpio led_pin(2, hf_gpio_direction_t::HF_GPIO_DIRECTION_OUTPUT);

3. Initialize and Use 

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

// Lazy initialization (automatic on first use)
adc.EnsureInitialized();
led_pin.EnsureInitialized();

// Use the hardware
float voltage;
if (adc.ReadChannelV(0, voltage) == hf_adc_err_t::ADC_SUCCESS) {
    printf("Voltage: %.3f V\n", voltage);
}

if (voltage > 3.0f) {
    led_pin.SetActive();
}

4. Error Handling 

1
2
3
4
5

hf_adc_err_t result = adc.ReadChannelV(0, voltage);
if (result != hf_adc_err_t::ADC_SUCCESS) {
    printf("ADC Error: %s\n", HfAdcErrToString(result));
    // Handle error appropriately
}

🧪 Examples

Motor Control System 

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
27
28
29
30
31
32
33
34
35
36
37

#include "inc/mcu/esp32/EspAdc.h"
#include "inc/mcu/esp32/EspPwm.h"
#include "inc/mcu/esp32/EspGpio.h"

class MotorController {
private:
    EspAdc current_sensor*;
    EspPwm motor_driver*;
    EspGpio enable_pin*;
    
public:
    MotorController() 
        : current_sensor*(ADC_UNIT_1, ADC_ATTEN_DB_11)
        , motor_driver*()
        , enable_pin*(5, hf_gpio_direction_t::HF_GPIO_DIRECTION_OUTPUT) {}
    
    bool Initialize() {
        current_sensor*.EnsureInitialized();
        motor_driver*.EnsureInitialized();
        enable_pin*.EnsureInitialized();
        
        // Configure motor driver
        motor_driver*.EnableChannel(0);
        motor_driver*.SetFrequency(0, 20000);  // 20kHz PWM
        return true;
    }
    
    void SetSpeed(float speed_percent) {
        motor_driver*.SetDutyCycle(0, speed_percent);
    }
    
    float GetCurrent() {
        float voltage;
        current_sensor*.ReadChannelV(0, voltage);
        return (voltage - 2.5f) / 0.1f;  // Convert to current (A)
    }
};

Sensor Network 

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
27
28
29
30
31
32
33
34
35
36

#include "inc/mcu/esp32/EspI2c.h"
#include "inc/mcu/esp32/EspAdc.h"

class SensorNetwork {
private:
    EspI2c i2c_bus*;
    EspAdc analog_sensors*;
    
public:
    bool ScanSensors() {
        hf_u8_t addresses[16];
        hf_u8_t count = i2c_bus*.ScanBus(addresses, 16);
        
        printf("Found %u I2C devices:\n", count);
        for (hf_u8_t i = 0; i < count; i++) {
            printf("  Address: 0x%02X\n", addresses[i]);
        }
        return count > 0;
    }
    
    float ReadTemperature() {
        // Read from I2C temperature sensor
        hf_u8_t data[2];
        if (i2c_bus*.ReadRegisters(0x48, 0x00, data, 2)) {
            hf_u16_t raw = (data[0] << 8) | data[1];
            return (raw >> 4) * 0.0625f;  // Convert to Celsius
        }
        return -999.0f;  // Error value
    }
    
    float ReadPressure() {
        float voltage;
        analog_sensors*.ReadChannelV(1, voltage);
        return voltage * 100.0f;  // Convert to PSI
    }
};

🧪 Testing

Comprehensive test suites for validating hardware interface implementations:

Test Features

  • Automated Testing - Comprehensive validation of all functionality
  • Performance Testing - Speed, DMA, and optimization validation
  • Error Handling - Edge case and failure mode testing
  • Hardware Validation - Real hardware signal verification
  • Pattern Testing - Data integrity and timing validation

🔗 Navigation

Documentation Structure

Base Class Documentation

Interface Documentation Status

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

BaseAdc Analog-to-Digital Conversion ✅ Complete
BaseGpio Digital I/O Control ✅ Complete
BaseI2c I2C Bus Communication ✅ Complete
BaseNvs Non-Volatile Storage ✅ Complete
BasePeriodicTimer High-Precision Timing ✅ Complete
BasePio Programmable I/O ✅ Complete
BasePwm Pulse Width Modulation ✅ Complete
BaseSpi SPI Bus Communication ✅ Complete
BaseUart Serial Communication ✅ Complete
BaseCan CAN Bus Communication ✅ Complete
BaseWifi WiFi Communication ✅ Complete
BaseBluetooth Bluetooth Communication ✅ Complete
BaseTemperature Temperature Sensing ✅ Complete
BaseLogger Logging System ✅ Complete

🚀 HardFOC Interface Wrapper

Part of the HardFOC Ecosystem

📋 Table of Contents