From 0d83df11a22d930bc3ee16b8437c3ad1162286e9 Mon Sep 17 00:00:00 2001 From: Siwat Sirichai Date: Sun, 20 Jul 2025 22:14:12 +0700 Subject: [PATCH] add claude.md --- .gitignore | 3 +- ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md | 183 +++++++++++++++++++++ 2 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md diff --git a/.gitignore b/.gitignore index a965236..4538236 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,2 @@ -.DS_Store -/ESPMegaPRO-OS-SDK +.DS_Store \ No newline at end of file diff --git a/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md b/ESPMegaPRO-OS-SDK/lib/ESPMegaPRO/CLAUDE.md new file mode 100644 index 0000000..83bcc8c --- /dev/null +++ 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` for pin change callbacks +- Output cards use `std::function` for state/value changes +- Analog cards use `std::function` 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. \ No newline at end of file