Firmware Architecture

Design Principles

  • Separation of Concerns: Each module focuses on a single responsibility—hardware, protocol, state, business logic, or UI.

  • Explicit APIs: Modules communicate through clear interfaces.

  • Scalability: Structure supports adding new features (web endpoints, hardware interfaces, state transitions) without creating spaghetti code.

  • Testability: Isolated logic is testable without hardware.

Directory Layout

The Ma Bell Gateway firmware is organized into logical modules and directories:

main/
  app/          # Application logic, state machine, and event coordination
  hardware/     # Phone line, GPIO, tones, analog/digital hardware interface
  bluetooth/    # Bluetooth stack, Hands-Free Profile (HFP), and related protocols
  network/      # Wi-Fi management and web interface (REST API, device status)
  storage/      # Persistent storage of configuration and device settings
  platform/     # ESP32/RTOS-specific glue code and project entry point
  include/      # Public headers (optional, if using)
  CMakeLists.txt

Module Responsibilities

app/

  • Contains the application’s core logic, including the state machine, event system, and all “business logic.”

  • Coordinates between hardware, Bluetooth, network, and user interfaces.

hardware/

  • Manages all interaction with the physical hardware: - Pin configuration (GPIO, PCM/I2S) - Analog phone line interfacing (off-hook/ring detect, pulse dial) - Generation of all telephony tones

  • Abstracts hardware details from application logic.

bluetooth/

  • Implements all Bluetooth functionality, including: - Stack integration - Hands-Free Profile (HFP) protocol handling - Audio routing and call event management

  • Provides a clear API for application modules to initiate or respond to Bluetooth events.

network/

  • Responsible for network connectivity and device management: - Wi-Fi provisioning, status, and reconnection - Web server and REST API endpoints for status monitoring, configuration, and control

storage/

  • Provides persistent storage for configuration data (such as paired device info and user settings)

  • Abstracts the ESP32’s NVS (non-volatile storage) details behind a simple interface

platform/

  • Contains project entry points and ESP32/RTOS glue: - Main firmware boot/init - Task registration and synchronization - Component registration (build system integration)

include/

  • Optionally holds public header files for modules that require global access

  • Helps decouple modules and simplify dependency management

Development Guidelines

  • New features should be added in the most appropriate module or directory—never spread logic across unrelated areas.

  • APIs between modules must be explicit and documented in header files.

  • Hardware and protocol details should be abstracted away from core application logic.

  • All project documentation and this architecture page should be updated as you refactor and extend the codebase.

By following this structure, the Ma Bell Gateway firmware will be maintainable, testable, and easy for new contributors to understand.