ESPMegaPRO-v3-SDK/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the ESPMegaPRO library - a comprehensive Arduino/PlatformIO library for the ESPMegaPRO industrial automation board. The library provides both procedural (legacy) and object-oriented interfaces for interfacing with the ESP32-based ESPMegaPRO hardware platform.

Architecture

Core Components

ESPMegaPRO.h: Legacy procedural interface for basic board functions (digital I/O, analog I/O, RTC, PWM)

ESPMegaProOS.hpp: Modern OOP interface - main class that manages the entire system including:

• Built-in Digital Input Card (slot 0)
• Built-in Digital Output Card (slot 1)
• Expansion card management (255 slots)
• IoT module integration
• Internal display management
• Web server functionality
• Recovery mode

Expansion Card System

The library uses a modular expansion card architecture:

ExpansionCard.hpp: Base abstract class for all expansion cards

• All cards inherit from this class
• Defines standard interface: begin(), loop(), getType()

Available Card Types:

• DigitalInputCard: 16-channel digital input with debouncing and callbacks
• DigitalOutputCard: 16-channel PWM/digital output with FRAM persistence
• AnalogCard: 8-channel ADC input + 4-channel DAC output (MCP4725)
• ClimateCard: IR-controlled AC + DHT/DS18B20 sensors
• CurrentTransformerCard: AC current monitoring

Protocol Support

• RTU Classes: ModbusTCP/RTU support for industrial protocols
• IR Communication: Climate card supports IR AC control
• Web Interface: AsyncWebServer for configuration
• OTA Updates: Built-in firmware update capability

IoT Integration

IoTComponent.hpp: Base class for MQTT-enabled card interfaces

• Provides MQTT publish/subscribe helpers
• Each expansion card can have a corresponding IoT component
• Pattern: {CardName}IoT classes (e.g., DigitalInputIoT, AnalogIoT)

ESPMegaIoT: Main IoT management class handling WiFi and MQTT connectivity

Display & Interface

InternalDisplay: Nextion display interface for boards with built-in displays ESPMegaWebServer: HTTP server for web-based configuration ESPMegaRecovery: Bootloop recovery system SmartVariable/RemoteVariable: MQTT-enabled configuration variables

File Naming Conventions

• Card classes: {Name}Card.hpp/.cpp
• IoT components: {Name}IoT.hpp/.cpp
• RTU components: {Name}RTU.hpp/.cpp
• Display classes: ESPMegaDisplay, InternalDisplay
• Utility classes: SmartVariable, RemoteVariable

Development Workflow

File Structure

• *.hpp: Header files with class definitions
• *.cpp: Implementation files
• html/: Web interface templates
• *_html.h: Compiled HTML resources

Key Constants

• I2C addresses defined in headers (0x21, 0x22, 0x5F, etc.)
• Card type constants (CARD_TYPE_DIGITAL_INPUT = 0x01, etc.)
• Hardware pin mappings and interrupt pins
• Default debounce time: 50ms for digital inputs
• PWM range: 0-4095 (12-bit)
• FRAM addresses: 0-1000 reserved for internal use

Special Files

• ESPMegaCommon.hpp: Shared constants and typedefs
• TimeStructure.hpp: Time-related structures
• html/*.html: Web interface templates
• *_html.h: Compiled HTML as C arrays
• all_html.h: Combined HTML resources

Memory Management

• Uses FRAM (0x56) for persistent storage
• Built-in RTC (0x68) for timekeeping
• NTP synchronization support

Development Guidelines

Adding New Cards

1. Inherit from ExpansionCard
2. Implement required virtual methods
3. Define unique card type constant
4. Create corresponding IoTComponent if MQTT support needed

Working with I2C

• Multiple I2C devices with fixed addresses
• Cards typically use PCF8574 GPIO expanders
• Analog cards use ADS1X15 ADCs and MCP4725 DACs
• Wire.begin(14, 33) - specific SDA/SCL pins for ESPMegaPRO

Callback System

• Digital inputs support callback registration with debouncing
• Use std::function<void(uint8_t, bool)> for pin change callbacks
• Output cards use std::function<void(uint8_t, bool, uint16_t)> for state/value changes
• Analog cards use std::function<void(uint8_t, bool, uint16_t)> for DAC changes

Card Installation Pattern

ESPMegaPRO megapro;
megapro.installCard(slot, &card); // Automatically calls card.begin()

FRAM Usage Pattern

card.bindFRAM(&fram, baseAddress);
card.setAutoSaveToFRAM(true);
card.loadFromFRAM(); // Restore state on boot

IoT Component Pattern

DigitalInputCard card;
DigitalInputIoT cardIoT;
cardIoT.begin(cardId, &card, &mqtt, baseTopic);

Key Implementation Patterns

Memory Management

• FRAM Integration: Persistent storage using I2C FRAM (address 0x56)
  • Cards can bind to FRAM with bindFRAM(fram, address)
  • Auto-save functionality for state persistence
  • Memory layout reservations (0-1000 for ESPMegaPRO internal use)

Callback Architecture

• std::function: Extensive use of C++ std::function for callbacks
• std::map: Callback storage using maps with handler IDs
• Pin Change Detection: Debounced input handling with configurable timing
• Change Notifications: State change callbacks for outputs/DACs

Pin Mapping System

• Virtual Pin Maps: Configurable pin mapping between logical and physical pins
• Dual Arrays: pinMap[16] (virtual→physical) and virtualPinMap[16] (physical→virtual)
• Flexible Addressing: Support both I2C addresses and DIP switch configurations

Error Handling & Logging

• ESP_LOG: Consistent ESP-IDF logging throughout (LOGD, LOGE, LOGV, LOGI)
• Initialization Checking: Cards track initOk status and validate before operations
• Graceful Degradation: Failed card initialization doesn't crash the system

MQTT/IoT Integration

• Topic Structure: {base_topic}/{card_id}/{subtopic} hierarchy
• Relative Publishing: Helper functions for topic construction
• State Requests: Global /requeststate and /requestinfo endpoints
• Component Registration: Cards register IoT components for MQTT handling

Thread Safety

• Mutex Protection: Serial communication protected with mutexes
• IRAM Functions: Interrupt handlers marked with IRAM_ATTR
• Buffer Management: Circular buffers for serial communication

Hardware Abstraction

• I2C Multiplexing: Multiple devices on shared I2C bus
• PWM Management: Adafruit PWM driver for outputs with push-pull configuration
• ADC/DAC: Multi-channel analog I/O via dedicated ICs
• RTC Integration: DS1307 RTC with NTP synchronization

Development Conventions

• Doxygen Documentation: Comprehensive function documentation
• Namespace Prefixes: ESPMega_ for procedural, class names for OOP
• Header Guards: #pragma once used consistently
• File Organization: Separate .hpp/.cpp pairs for each major component

This is a pure library with no build system - it's designed to be included in Arduino/PlatformIO projects as a dependency.