# 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
```cpp
ESPMegaPRO megapro;
megapro.installCard(slot, &card); // Automatically calls card.begin()
```

### FRAM Usage Pattern
```cpp
card.bindFRAM(&fram, baseAddress);
card.setAutoSaveToFRAM(true);
card.loadFromFRAM(); // Restore state on boot
```

### IoT Component Pattern
```cpp
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.