# nanahigh/esp32s3_demo architecture

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

- Interactive diagram: https://gitdiagram.com/nanahigh/esp32s3_demo
- Repository: https://github.com/nanahigh/esp32s3_demo

## Overview

##### Project Type and Purpose
- This is an embedded firmware demo written in Rust for the ESP32-S3 MCU.
- It exercises on-device peripherals: an LCD screen (raw bitmap asset), a sensor, and a PWM-driven output.
- The build system is Cargo (with a `build.rs` helper) and ESP-IDF or HAL configurations (`sdkconfig.defaults`).

##### File Structure
- .cargo/config.toml – custom target or linker overrides for embedded build.
- Cargo.toml + rust-toolchain.toml – Rust package metadata, target toolchain, and dependencies.
- build.rs – build-time steps such as bundling the `ferris.raw` asset or generating bindings.
- src/main.rs – application entry, initialization of peripherals and main loop.
- src/lib.rs – shared utilities or high-level API surface.
- src/lcd.rs, src/sensor.rs, src/pwm.rs – Rust modules encapsulating drivers for each peripheral.
- src/assets/ferris.raw – bitmap data displayed on the LCD.

##### README
- Minimal content (“# esp32s3_demo”), so we infer details from code. No external services or network layers in this demo.

##### Main Components
a. Hardware Layer
– ESP32-S3 MCU core (CPU + on-chip buses)
– External peripherals:
- LCD display (SPI or parallel interface)
- Sensor (I²C, SPI, or ADC input)
- PWM-driven output (motor, LED, buzzer)
b. Software Layer
– Cargo build system
– build.rs (asset embedding / codegen)
– Runtime init (from `main.rs`)
– Driver modules: lcd.rs, sensor.rs, pwm.rs
– Application logic in `main.rs` calling into drivers
c. Relationships & Data Flows
– build.rs → embeds `ferris.raw` → compiled into firmware binary
– MCU Startup → initialize peripherals via driver modules
– sensor.rs reads data → main.rs logic → optionally display or actuate via lcd.rs / pwm.rs

##### Architectural Patterns & Principles
- Layered driver abstraction: each peripheral has its own module exposing a clean API.
- Single‐threaded, bare-metal execution—no OS.
- Build‐time asset bundling (build.rs) for embedding raw resources.
- Use of Cargo.toml features or conditional compilation for different hardware configs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build Pipeline"
        CargoConfig[".cargo/config.toml"]
        Toolchain["rust-toolchain.toml"]
        Package["Cargo.toml"]
        SDKConfig["sdkconfig.defaults"]
        Asset["src/assets/ferris.raw"]
        BuildRS["build.rs"]
        Firmware["Firmware Image"]
    end

    subgraph "Software (Firmware)"
        Main["src/main.rs"]
        Lib["src/lib.rs"]
        LCDMod["src/lcd.rs"]
        SensorMod["src/sensor.rs"]
        PWMMod["src/pwm.rs"]
    end

    subgraph "Hardware Peripherals"
        MCU["ESP32-S3 MCU Core"]
        SensorHW["Sensor"]
        LCDHW["LCD Display"]
        PWMHW["PWM Output"]
    end

    CargoConfig --> BuildRS
    Toolchain --> BuildRS
    Package --> BuildRS
    SDKConfig --> BuildRS
    Asset --> BuildRS
    BuildRS --> Firmware
    Firmware --> MCU
    MCU -->|"executes"| Main
    Main -->|"uses API"| Lib
    Main -->|"calls driver"| SensorMod
    Main -->|"calls driver"| LCDMod
    Main -->|"calls driver"| PWMMod
    Lib --> SensorMod
    Lib --> LCDMod
    Lib --> PWMMod
    SensorMod -->|"read data"| SensorHW
    LCDMod -->|"update display"| LCDHW
    PWMMod -->|"drive output"| PWMHW

    click CargoConfig "https://github.com/nanahigh/esp32s3_demo/blob/main/.cargo/config.toml"
    click Toolchain "https://github.com/nanahigh/esp32s3_demo/blob/main/rust-toolchain.toml"
    click Package "https://github.com/nanahigh/esp32s3_demo/blob/main/Cargo.toml"
    click SDKConfig "https://github.com/nanahigh/esp32s3_demo/blob/main/sdkconfig.defaults"
    click BuildRS "https://github.com/nanahigh/esp32s3_demo/blob/main/build.rs"
    click Main "https://github.com/nanahigh/esp32s3_demo/blob/main/src/main.rs"
    click Lib "https://github.com/nanahigh/esp32s3_demo/blob/main/src/lib.rs"
    click LCDMod "https://github.com/nanahigh/esp32s3_demo/blob/main/src/lcd.rs"
    click SensorMod "https://github.com/nanahigh/esp32s3_demo/blob/main/src/sensor.rs"
    click PWMMod "https://github.com/nanahigh/esp32s3_demo/blob/main/src/pwm.rs"
    click Asset "https://github.com/nanahigh/esp32s3_demo/blob/main/src/assets/ferris.raw"

    classDef build fill:#f96,stroke:#333,color:#000;
    classDef firmware fill:#c9f,stroke:#333,color:#000;
    classDef software fill:#6cf,stroke:#333,color:#000;
    classDef hardware fill:#8f8,stroke:#333,color:#000;

    class CargoConfig,Toolchain,Package,SDKConfig,BuildRS build;
    class Firmware firmware;
    class Main,Lib,LCDMod,SensorMod,PWMMod software;
    class MCU,SensorHW,LCDHW,PWMHW hardware;
```
