# robtillaart/i2c_24lc1025 architecture

> Architecture diagram of the GitHub repository robtillaart/i2c_24lc1025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robtillaart/i2c_24lc1025
- Repository: https://github.com/robtillaart/i2c_24lc1025

## Overview

##### Project type and purpose
- This is an **Arduino library** (“I2C_24LC1025”) that provides a clean C++ API to read/write a 1 Mbit I2C EEPROM (24LC1025 and equivalents).
- It is an **open-source tool** for embedded developers—no front-end or server back-end, but a hardware abstraction layer plus examples, tests, and CI.

##### File structure
- Top-level source:
- I2C_24LC1025.h / I2C_24LC1025.cpp – the core API implementation.
- keywords.txt, library.json, library.properties – Arduino/PlatformIO packaging metadata.
- Examples: eight separate Arduino sketches under `examples/…` showing various use cases on AVR, ESP32, RP2040, etc.
- Tests: `test/unit_test_001.cpp` – a host-based unit test.
- CI configs: `.github/workflows/*.yml`, `.arduino-ci.yml` – automated builds, linting, JSON checks.

##### Extract extra insights from the README
- Confirms API matches a predecessor (I2C_EEPROM) with 32-bit addressing.
- Describes hardware wiring (SDA, SCL, WP, A0–A2, GND, VCC) and critical constraints (A2 tied to VCC, optional WP control).
- Demonstrates extension points: injecting custom TwoWire instance, enabling/disabling write-protect, adjusting write cycle delays.

##### Main components
a. **Software components**
1. Arduino Sketch (example application)
2. I2C_24LC1025 Library (public API, internal logic)
3. TwoWire / Wire (Arduino core I2C driver)
4. Unit‐test harness (host-side test runner)
5. CI/CD pipelines (GitHub Actions workflows)
b. **Hardware components**
6. I2C Bus (SDA, SCL lines)
7. 24LC1025 EEPROM chip (pins: A0, A1, A2, WP, SDA, SCL)
8. MCU GPIO for WP (optional)
c. **Relationships / Interactions**
- Sketch calls library API → library invokes TwoWire methods → I2C frames on SDA/SCL → EEPROM chip responds.
- Library toggles WP GPIO to enter/exit write mode.
- Unit tests instantiate library in host simulation → verify logic without real hardware.
- CI workflows run examples compilation, lint, JSON validation, and unit tests on every push/PR.

##### Architectural patterns & principles
- **Hardware abstraction**: the library wraps TwoWire; supports dependency injection of the Wire object.
- **Separation of concerns**:
- API layer (I2C_24LC1025.h)
- Implementation layer (I2C_24LC1025.cpp)
- Packaging layer (library.json/properties, keywords.txt)
- Build/test layer (examples, unit tests, CI config)
- **Extensibility**:
- Example sketches demonstrate portability to multiple MCUs (AVR, ESP32, RP2040).

##### Final checklist to capture all essential elements
- Clearly labeled components in distinct lanes.
- Notes on configuration points (device address, WP pin, delays).
- CI pipelines as side processes.
- Technology callouts: C++, Arduino SDK, TwoWire, GoogleTest (if used), PlatformIO metadata.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        SketchFormat["24LC1025_format.ino"]:::app
        SketchTest["24LC1025_test.ino"]:::app
        SketchESP32["24LC1025_test_ESP32.ino"]:::app
        SketchRP2040["24LC1025_test_RP2040.ino"]:::app
        SketchWire1["24LC1025_test_Wire1.ino"]:::app
        SketchRead["24LC1025_test_read.ino"]:::app
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        API["I2C_24LC1025.h"]:::lib
        Impl["I2C_24LC1025.cpp"]:::lib
        Metadata["Packaging Metadata\n(library.json, library.properties, keywords.txt)"]:::lib
    end

    %% Platform Layer
    subgraph "Platform Layer"
        direction TB
        Wire["TwoWire / Wire"]:::platform
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        I2CBus["I2C Bus\n(SDA, SCL)"]:::hardware
        WPGPIO["MCU GPIO (WP)"]:::hardware
        EEPROM["24LC1025 EEPROM Chip"]:::hardware
    end

    %% CI/Test Layer
    subgraph "CI/Test Layer"
        direction TB
        UnitTest["unit_test_001.cpp"]:::ci
        CIWorkflows["CI/CD Workflows\n(.github/workflows/*.yml, .arduino-ci.yml)"]:::ci
    end

    %% Connections
    SketchFormat -->|"uses API"| API
    SketchTest -->|"uses API"| API
    SketchESP32 -->|"uses API"| API
    SketchRP2040 -->|"uses API"| API
    SketchWire1 -->|"uses API"| API
    SketchRead -->|"uses API"| API

    API -->|"declares functions"| Impl
    Impl -->|"calls Wire.begin(), read/write"| Wire
    Wire -->|"drives signals"| I2CBus
    I2CBus -->|"SDA/SCL signals"| EEPROM
    Impl -->|"toggles WP GPIO"| WPGPIO
    WPGPIO -->|"control write-protect"| EEPROM

    UnitTest -->|"calls API"| API
    CIWorkflows -->|"runs examples build"| SketchFormat
    CIWorkflows -->|"runs examples build"| SketchTest
    CIWorkflows -->|"runs unit tests"| UnitTest

    %% Click Events
    click SketchFormat "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_format/24LC1025_format.ino"
    click SketchTest "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_test/24LC1025_test.ino"
    click SketchESP32 "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_test_ESP32/24LC1025_test_ESP32.ino"
    click SketchRP2040 "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_test_RP2040/24LC1025_test_RP2040.ino"
    click SketchWire1 "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_test_Wire1/24LC1025_test_Wire1.ino"
    click SketchRead "https://github.com/robtillaart/i2c_24lc1025/blob/master/examples/24LC1025_test_read/24LC1025_test_read.ino"
    click API "https://github.com/robtillaart/i2c_24lc1025/blob/master/I2C_24LC1025.h"
    click Impl "https://github.com/robtillaart/i2c_24lc1025/blob/master/I2C_24LC1025.cpp"
    click Metadata "https://github.com/robtillaart/i2c_24lc1025/blob/master/library.json"
    click Metadata "https://github.com/robtillaart/i2c_24lc1025/blob/master/library.properties"
    click Metadata "https://github.com/robtillaart/i2c_24lc1025/blob/master/keywords.txt"
    click UnitTest "https://github.com/robtillaart/i2c_24lc1025/blob/master/test/unit_test_001.cpp"
    click CIWorkflows "https://github.com/robtillaart/i2c_24lc1025/blob/master/.github/workflows/arduino-lint.yml"
    click CIWorkflows "https://github.com/robtillaart/i2c_24lc1025/blob/master/.github/workflows/arduino_test_runner.yml"
    click CIWorkflows "https://github.com/robtillaart/i2c_24lc1025/blob/master/.github/workflows/jsoncheck.yml"
    click CIWorkflows "https://github.com/robtillaart/i2c_24lc1025/blob/master/.arduino-ci.yml"

    %% Styles
    classDef app fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef platform fill:#FFA500,stroke:#000,stroke-width:1px
    classDef hardware fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ci fill:#D8BFD8,stroke:#000,stroke-width:1px
```
