183 lines
No EOL
6.9 KiB
Markdown
183 lines
No EOL
6.9 KiB
Markdown
# 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. |