# mteinum/erlang_pi_lcd architecture

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

- Interactive diagram: https://gitdiagram.com/mteinum/erlang_pi_lcd
- Repository: https://github.com/mteinum/erlang_pi_lcd

## Overview

##### Project type and purpose
- This is an Erlang/OTP application running on a Raspberry Pi that controls an Adafruit 16×2 LCD via an MCP23017 I²C I/O-expander.
- It bundles a small C-based driver (i2c_drv.so) for accessing the Pi’s I²C bus and an OTP‐style Erlang layer for supervising and exposing LCD functions.

##### File structure
- Top level:
- c_src/ – C driver source (i2c_drv.c) and Makefile
- src/ – Erlang modules: i2c.erl (port interface), mcp.erl (MCP23017 GenServer), lcd.erl (LCD API), lcd_app.app.src, lcd_app.erl (application entry), lcd_sup.erl (supervisor)
- rebar.config – build configuration for rebar3
- Build outputs:
- priv/i2c_drv.so (dynamically built by make via rebar3 hooks)
- compiled BEAM files under _build/

##### README
- Confirms OTP application, no external dependencies beyond standard Erlang runtime and the C driver.
- Describes high-level API (lcd:message/1, lcd:create_char/2, etc.)
- Notes build steps: `rebar3 compile` triggers C compilation into priv/, then Erlang compile.

##### Main components
a. Hardware & OS
- Raspberry Pi hardware
- Linux I²C kernel driver
- Physical devices: MCP23017 I/O expander → LCD module
b. Native driver layer
- c_src → i2c_drv.so (linked‐in driver)
- Exposed as a port or linked NIF to Erlang
c. Erlang/OTP layers
- Erlang VM / BEAM
- lcd_app application
- Supervisor tree:
– lcd_app (Application)
– lcd_sup (root supervisor)
– mcp (GenServer handling MCP23017 commands)
– lcd (GenServer exposing high-level display API)
d. Build & deployment
- rebar3 orchestrates C compilation and Erlang compilation
- Development shell vs. production release

##### Relationships & data flow
- Erlang lcd GenServer → mcp GenServer (JSON/RPC-style calls)
- mcp GenServer → C driver (via port/NIF calls)
- C driver → Linux I²C subsystem → MCP23017 → LCD HW
- Application → Supervisor → Worker processes

##### Architectural patterns & design principles
- OTP application / supervision tree for fault‐tolerance
- GenServer abstraction for both MCP23017 and LCD
- Separation of concerns:
- Hardware access in C → single shared driver
- Business logic & API in Erlang
- Priv directory pattern for native code

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        direction TB
        LCD_GEN["lcd GenServer\n(lcd:message/1, create_char)"]:::blue
    end

    %% OTP Layer
    subgraph "OTP Layer"
        direction TB
        APP_MOD["Application Module\n(lcd_app)"]:::blue
        SUP["Root Supervisor\n(lcd_sup)"]:::blue
        MCP_GEN["mcp GenServer\n(low-level I/O expander)"]:::blue
        I2C_WRAPPER["Port Interface\n(i2c.erl)"]:::blue
    end

    %% Native Driver Layer
    subgraph "Native Driver Layer"
        direction TB
        I2C_DRV_SO["i2c_drv.so\n(C driver)"]:::orange
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        KERNEL["Linux I²C Kernel Driver"]:::green
        I2C_BUS["I²C Bus"]:::green
        MCP_HW["MCP23017 I/O Expander"]:::green
        LCD_HW["LCD Module 16×2"]:::green
        RPI["Raspberry Pi Hardware"]:::green
    end

    %% Build & Docs
    subgraph "Build & Docs"
        direction TB
        REBAR["rebar.config"]:::doc
        MAKE["Makefile"]:::doc
        README["README.md"]:::doc
    end

    %% VM
    VM["Erlang VM (BEAM)"]:::blue

    %% Connections: Data/Control Flow
    LCD_GEN -->|"calls GenServer"| MCP_GEN
    MCP_GEN -->|"calls Port Interface"| I2C_WRAPPER
    I2C_WRAPPER -->|"native call"| I2C_DRV_SO
    I2C_DRV_SO -->|"ioctl calls"| KERNEL
    KERNEL -->|"bus signals"| I2C_BUS
    I2C_BUS --> MCP_HW --> LCD_HW
    RPI --> KERNEL

    %% Supervisor Links (dashed)
    APP_MOD --> SUP
    SUP -.-> LCD_GEN
    SUP -.-> MCP_GEN

    %% VM Hosting
    VM --> APP_MOD
    VM --> SUP
    VM --> LCD_GEN
    VM --> MCP_GEN
    VM --> I2C_WRAPPER

    %% Build & Docs Links
    REBAR --> MAKE
    REBAR --> APP_MOD
    README --- REBAR

    %% Click Events
    click I2C_C_SRC "https://github.com/mteinum/erlang_pi_lcd/blob/master/c_src/i2c_drv.c"
    click MAKE "https://github.com/mteinum/erlang_pi_lcd/tree/master/c_src/makefile"
    click I2C_WRAPPER "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/i2c.erl"
    click MCP_GEN "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/mcp.erl"
    click LCD_GEN "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/lcd.erl"
    click APP_MOD "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/lcd_app.erl"
    click APP_SRC "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/lcd_app.app.src"
    click SUP "https://github.com/mteinum/erlang_pi_lcd/blob/master/src/lcd_sup.erl"
    click REBAR "https://github.com/mteinum/erlang_pi_lcd/blob/master/rebar.config"
    click README "https://github.com/mteinum/erlang_pi_lcd/blob/master/README.md"

    %% Styles
    classDef blue fill:#AED6F1,stroke:#21618C,color:#1B4F72;
    classDef orange fill:#F5B041,stroke:#B9770E,color:#874E0B;
    classDef green fill:#82E0AA,stroke:#1D8348,color:#145A32;
    classDef doc fill:#D7BDE2,stroke:#7D3C98,color:#4A235A;
```
