Technical Architecture

Deep dive into the professional modular firmware design, dual-core FreeRTOS architecture, and advanced system components.

System Architecture Overview

ESP32 GPIO Bridge System Architecture

Python Library

High-level API for GPIO control, PWM, I2C, and more

USB Serial Protocol

115200 baud, text-based commands with response filtering

ESP32 Firmware

Modular dual-core FreeRTOS architecture

Hardware Interface

GPIO pins, PWM, ADC/DAC, I2C, EEPROM

Modular Firmware Architecture (v0.1.6-beta)

Complete transformation from monolithic 961-line file to 8 specialized modules with 54% reduction in main file size.

config.h

Centralized configuration constants and system parameters

  • • Pin definitions
  • • Timing constants
  • • Buffer sizes
  • • System limits

response.h/.cpp

Optimized serial response buffer management

  • • Response buffering
  • • Message filtering
  • • Error handling
  • • Output optimization

gpio.h/.cpp

Digital I/O operations and pin management

  • • Pin mode control
  • • Digital read/write
  • • Pin validation
  • • Batch operations

pwm.h/.cpp

PWM channel allocation and control

  • • Channel management
  • • Frequency control
  • • Duty cycle setting
  • • Resource tracking

analog.h/.cpp

ADC/DAC operations with calibration

  • • ADC reading
  • • DAC output
  • • Calibration support
  • • Voltage conversion

i2c.h/.cpp

I2C communication protocol

  • • Bus initialization
  • • Device scanning
  • • Read/write operations
  • • Error handling

eeprom.h/.cpp

Persistent storage operations

  • • Byte operations
  • • Block operations
  • • String handling
  • • Flash management

i2s.h/.cpp

I2S audio interface

  • • Audio initialization
  • • Data transmission
  • • Sample rate control
  • • Buffer management

Dual-Core FreeRTOS Architecture

Professional dual-core architecture utilizing both ESP32 cores for maximum performance and reliability.

Core 0 - Serial Processing

High-responsiveness command processing

Dedicated Serial Task

  • • Priority 2 (High)
  • • Command parsing and execution
  • • Response generation
  • • Serial communication management

Command Queue Processing

  • • 32-command circular buffer
  • • Batch processing optimization
  • • Priority-based execution
  • • Error handling and recovery

Core 1 - System Monitoring

Independent failsafe and system monitoring

Failsafe Task

  • • Priority 1 (Medium)
  • • Communication monitoring
  • • Safety system management
  • • Pin state protection

System Health Monitoring

  • • Memory usage tracking
  • • Task status monitoring
  • • Performance metrics
  • • Error logging

Communication Protocol

Protocol Specifications

Serial Configuration

  • Baud Rate: 115200
  • Data Bits: 8
  • Stop Bits: 1
  • Parity: None
  • Flow Control: None

Message Format

<COMMAND>          # Command format
<RESPONSE>         # Response format
<ERROR:message>    # Error format

Response Filtering

  • • Filters PONG responses
  • • Removes ESP32 system messages
  • • Handles stale ERROR messages
  • • Optimizes serial throughput

Command Categories

System Commands

  • • IDENTIFY - Device identification
  • • VERSION - Firmware version
  • • PING - Keep-alive
  • • STATUS - System status

GPIO Commands

  • • MODE - Set pin mode
  • • WRITE - Digital write
  • • READ - Digital read
  • • BATCH_WRITE - Multiple pins

Advanced Commands

  • • PWM_INIT/WRITE/STOP
  • • AREAD/AWRITE
  • • I2C_INIT/SCAN/READ/WRITE
  • • EEPROM operations

Memory Management & Optimization

Heap Management

  • • Char buffer parsing (no String allocation)
  • • Fixed-size response buffers
  • • Circular buffer implementation
  • • Memory pool for frequent allocations
  • • Garbage collection optimization

Performance Optimization

  • • O(1) PWM channel lookup
  • • Batch operation support
  • • Single-call response output
  • • Reduced serial overhead
  • • Optimized task scheduling

Safety & Reliability

  • • Mutex-protected shared data
  • • Thread-safe operations
  • • Buffer overflow protection
  • • Error recovery mechanisms
  • • Watchdog integration

Development Workflow & Benefits

Modular Development Benefits

1

Enhanced Maintainability

Bug fixes isolated to specific modules, easier debugging and testing.

2

Parallel Development

Multiple developers can work on different modules simultaneously.

3

Professional Architecture

Industry-standard modular design with clean separation of concerns.

4

Enhanced Testing

Each module can be unit tested independently with better coverage.

Code Organization

Module Structure Example 
firmware/
├── firmware.ino          # Main file (54% smaller)
├── config.h              # Configuration constants
├── response.h/.cpp       # Response management
├── gpio.h/.cpp          # GPIO operations
├── pwm.h/.cpp           # PWM control
├── analog.h/.cpp        # ADC/DAC operations
├── i2c.h/.cpp           # I2C communication
├── eeprom.h/.cpp        # Persistent storage
└── i2s.h/.cpp           # Audio interface

# Each module is self-contained with:
# - Clear interface definitions
# - Independent functionality
# - Minimal dependencies
# - Comprehensive error handling

Future Architecture Enhancements

Network Module

WiFi and Ethernet support for remote GPIO control and monitoring.

Cloud Integration

MQTT and HTTP client support for IoT cloud platforms.

Analytics Module

Built-in data logging and performance analytics capabilities.