add claude.md

2025-07-20 22:14:12 +07:00 · 2025-07-20 22:14:12 +07:00 · 0d83df11a2
commit 0d83df11a2
parent fb61fa85f3
2 changed files with 184 additions and 2 deletions
--- a/.gitignore
+++ b/.gitignore
@ -1,3 +1,2 @@

-.DS_Store
-/ESPMegaPRO-OS-SDK
+.DS_Store
--- a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md
+++ b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md
@ -0,0 +1,183 @@
+# 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.