# n0xa/m5stick-nemo architecture

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

- Interactive diagram: https://gitdiagram.com/n0xa/m5stick-nemo
- Repository: https://github.com/n0xa/m5stick-nemo

## Overview

##### Project type and purpose
- Type: Embedded firmware for ESP32-based M5Stack devices (M5Stick-C, ‑C Plus, Cardputer).
- Purpose: Provide a modular “prank toolkit” exposing multiple hardware- and network-driven features (TV-B-Gone, WiFi spam/portal, Bluetooth spam, deauth attacks, IR codes, etc.) via a menu-driven UI.

##### File structure
- Top-level firmware entry: `m5stick-nemo.ino`.
- Feature headers: `NEMOMatrix.h`, `applejuice.h`, `tvbg.h`, `wifispam.h`, `portal.h`, `deauth.h`, etc.
- Hardware abstraction & settings: `sd.h`, `localization.h`, `WORLD_IR_CODES.h`.
- Build/config pipelines:
– `configs/` holds `.env.*` presets per device.
– `scripts/` (compile.sh, docker-build.sh, flash.sh, entrypoint.sh).
– Dockerfile & GitHub Actions workflows (`.github/workflows/`).
- Misc: `.gitignore`, `LICENSE`, `README.md`.

##### README for insights
- Runtime architecture: menu controls → select feature modules → hardware/network interactions → optional SD logging.
- Build options: Arduino IDE, Arduino CLI, Docker, M5Burner, esptool.py, GitHub CI.
- Dependencies: M5Stack boards core, IRRemoteESP8266, ESP-IDF tools.

##### Main components and their interactions
a. Hardware Platform
– ESP32 SoC (WiFi, BT, CPU)
– Display & Buttons (Home/Next/Select)
– RTC & EEPROM
– IR LED (TV-B-Gone)
– SD card interface (optional via `sd.h`)
b. Firmware Modules (each in its own header + code in `.ino`)
– UI/Menu manager → dispatches to feature handlers
– TV-B-Gone IR manager
– AppleJuice Bluetooth spam manager
– WiFi Spam & Scanner manager
– Deauth & Evil-Twin portal manager (DNS, DHCP, Web server)
– Settings manager (brightness, rotation, portal SSID)
– Localization manager (strings in flash)
– Logging (serial, SD card via FAT FS)
– Power & Battery monitor (RTC, AXP192 PMU on some models)
c. External & Build Services
– M5Burner (binary installer)
– Arduino IDE / CLI (compilation)
– Docker container for deterministic build
– GitHub Actions CI for automated compile & release
– esptool.py (flash binaries)

##### Architectural patterns and design principles
- Modular feature isolation via separate headers
- Hardware-agnostic code paths gated by `#define` (STICK_C, STICK_C_PLUS, CARDPUTER)
- Event-driven menu loop → callback pattern
- Build-time configuration via environment files and scripts
- Single monolithic firmware binary for all features, selectable at runtime

##### Essential elements
- Device hardware block with all onboard peripherals
- Firmware modules grouped by function (UI, network, IR, BT, storage, settings)
- Build pipeline flow (source → compile → flash)
- External tools & services (M5Burner, Docker, GitHub Actions, esptool.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Device Runtime
    subgraph "Device Runtime"
        subgraph "Peripherals"
            ESP32["ESP32 SoC"]:::hardware
            Display["Display"]:::hardware
            Buttons["Buttons"]:::hardware
            IR_LED["IR LED"]:::hardware
            Radio["WiFi/BT Radio"]:::hardware
            SD_Card["SD Card"]:::hardware
            RTC["RTC/EEPROM"]:::hardware
        end
        subgraph "Firmware Modules"
            UI["UI/Menu Manager"]:::firmware
            TVBG["TV-B-Gone IR Manager"]:::firmware
            WORLD["IR Code Definitions"]:::firmware
            Songs["Songs/IR Sequences"]:::firmware
            AJ["AppleJuice BT Spam Manager"]:::firmware
            WiFiSpam["WiFi Spam & Scanner Manager"]:::firmware
            Deauth["Deauth Manager"]:::firmware
            PortalMod["Portal Manager"]:::firmware
            Settings["Settings Manager"]:::firmware
            Loc["Localization Manager"]:::firmware
            Logging["Logging Manager"]:::firmware
            Power["Power & Battery Monitor"]:::firmware
            Entry["Firmware Entry Point"]:::firmware
        end
    end

    %% Connections Runtime
    Entry -->|initializes| UI
    UI -->|menu selection| TVBG
    UI -->|menu selection| AJ
    UI -->|menu selection| WiFiSpam
    UI -->|menu selection| Deauth
    UI -->|menu selection| PortalMod
    UI -->|menu selection| Settings
    UI -->|menu selection| Loc
    UI -->|menu selection| Logging
    UI -->|menu selection| Power

    TVBG -->|"uses IR codes"| WORLD
    TVBG -->|"plays sequences"| Songs
    TVBG -->|"drives"| IR_LED

    AJ -->|"spam via"| Radio
    WiFiSpam -->|"scans/spams via"| Radio
    Deauth -->|"sends frames via"| Radio
    PortalMod -->|"runs DNS/DHCP server via"| Radio

    Settings -->|configures| RTC
    Settings -->|configures| Display

    Loc -->|provides strings| Display
    Logging -->|writes to| SD_Card
    Logging -->|logs via UART| ESP32
    Power -->|monitors| RTC
    Power -->|monitors| ESP32

    Display --- ESP32
    Buttons -->|input| UI
    Radio --- ESP32
    SD_Card --- ESP32
    RTC --- ESP32

    %% Build & Deployment Pipeline
    subgraph "Build & Deployment Pipeline"
        subgraph "Source & Configs"
            Entry
            subgraph "Build Configurations"
                envC[".env.M5StickC"]:::config
                envCPlus[".env.M5StickCPlus"]:::config
                envCPlus2[".env.M5StickCPlus2"]:::config
                envCard[".env.M5Cardputer"]:::config
                packageIndex["package_m5stack_index.json"]:::config
            end
        end
        subgraph "Build Tools"
            ArduinoCLI["Arduino CLI"]:::build
            DockerBuild["Docker Build (docker-build.sh)"]:::build
            Scripts["Build Scripts"]:::build
            DockerfileNode["Dockerfile"]:::build
            CI["GitHub Actions CI"]:::build
        end
        subgraph "Artifacts & Flash"
            Binary["Firmware Binary"]:::build
            M5Burner["M5Burner"]:::build
            Esptool["esptool.py"]:::build
        end
        subgraph "CI Workflows"
            compileYml["compile.yml"]:::build
            devCompileYml["dev_compile.yml"]:::build
        end
    end

    %% Connections Build
    envC & envCPlus & envCPlus2 & envCard & packageIndex -->|configured source| Entry
    Entry -->|built by| ArduinoCLI
    Entry -->|built by| DockerBuild
    Scripts -->|invoke| ArduinoCLI
    Scripts -->|invoke| DockerBuild
    DockerfileNode -->|defines image| DockerBuild
    CI -->|triggers| ArduinoCLI
    CI -->|triggers| DockerBuild
    compileYml -->|workflow| CI
    devCompileYml -->|workflow| CI

    ArduinoCLI -->|produces| Binary
    DockerBuild -->|produces| Binary
    Binary -->|flashed by| M5Burner
    Binary -->|flashed by| Esptool

    %% Click Events
    click Entry "https://github.com/n0xa/m5stick-nemo/blob/main/m5stick-nemo.ino"
    click UI "https://github.com/n0xa/m5stick-nemo/blob/main/NEMOMatrix.h"
    click TVBG "https://github.com/n0xa/m5stick-nemo/blob/main/tvbg.h"
    click WORLD "https://github.com/n0xa/m5stick-nemo/blob/main/WORLD_IR_CODES.h"
    click Songs "https://github.com/n0xa/m5stick-nemo/blob/main/songs.h"
    click AJ "https://github.com/n0xa/m5stick-nemo/blob/main/applejuice.h"
    click WiFiSpam "https://github.com/n0xa/m5stick-nemo/blob/main/wifispam.h"
    click Deauth "https://github.com/n0xa/m5stick-nemo/blob/main/deauth.h"
    click PortalMod "https://github.com/n0xa/m5stick-nemo/blob/main/portal.h"
    click Loc "https://github.com/n0xa/m5stick-nemo/blob/main/localization.h"
    click Logging "https://github.com/n0xa/m5stick-nemo/blob/main/sd.h"
    click envC "https://github.com/n0xa/m5stick-nemo/blob/main/configs/.env.M5StickC"
    click envCPlus "https://github.com/n0xa/m5stick-nemo/blob/main/configs/.env.M5StickCPlus"
    click envCPlus2 "https://github.com/n0xa/m5stick-nemo/blob/main/configs/.env.M5StickCPlus2"
    click envCard "https://github.com/n0xa/m5stick-nemo/blob/main/configs/.env.M5Cardputer"
    click packageIndex "https://github.com/n0xa/m5stick-nemo/blob/main/package_m5stack_index.json"
    click Scripts "https://github.com/n0xa/m5stick-nemo/blob/main/scripts/compile.sh"
    click Scripts "https://github.com/n0xa/m5stick-nemo/blob/main/scripts/docker-build.sh"
    click Scripts "https://github.com/n0xa/m5stick-nemo/blob/main/scripts/flash.sh"
    click Scripts "https://github.com/n0xa/m5stick-nemo/blob/main/scripts/entrypoint.sh"
    click DockerfileNode "https://github.com/n0xa/m5stick-nemo/tree/main/Dockerfile"
    click compileYml "https://github.com/n0xa/m5stick-nemo/blob/main/.github/workflows/compile.yml"
    click devCompileYml "https://github.com/n0xa/m5stick-nemo/blob/main/.github/workflows/dev_compile.yml"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef firmware fill:#90EE90,stroke:#333,stroke-width:1px
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
