# magruder13/mpcnc architecture

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

- Interactive diagram: https://gitdiagram.com/magruder13/mpcnc
- Repository: https://github.com/magruder13/mpcnc

## Overview

##### Project Type & Purpose
- Marlin is an embedded firmware for 3D printers: a hardware-abstraction-layer (HAL) based, microcontroller-centric application that accepts G-Code commands (over serial, USB, SD card or WebSocket) and controls motion, heaters, sensors, and user interfaces.

##### High-Level File Structure
- Top-Level:
- platformio.ini (build config for PlatformIO)
- Marlin/ (firmware source)
- buildroot/ (PlatformIO toolchain, board definitions, scripts)
- data/www/ (web UI for ESP32 builds)
- docs/, config/, scripts, tests, etc.

- Marlin/src:
- HAL/… per-MCU implementations + shared HAL interfaces
- core (common types, utilities, serial I/O)
- module (planner, motion, temperature, steppers, endstops, etc.)
- feature (optional bundled features: bed leveling, probes, LEDs…)
- gcode (parser + G/M-command handlers)
- lcd + extui (user interfaces: character LCD, DOGM, FTDI-EVE touch)
- libs (third-party libraries: SPI, heatshrink, math utilities)
- pins (board-specific pin mappings)
- sd (SD-card and USB-mass-storage support)

##### Key Components & Their Relationships
- Build System (PlatformIO / Arduino IDE)
→ compiles Configuration.h, MarlinConfigPre.h, Version.h
→ selects target HAL platform (AVR, ARM, ESP32, Linux)
→ integrates platform-specific board files & linker scripts

- Configuration Layer
→ Configuration.h / Configuration_adv.h define hardware & feature options
→ MarlinConfig.h (auto-generated from Configuration*.h)

- Application Layer
- GCode Parser (src/gcode/parser.cpp)
→ feeds commands into
- GCode Queue & Dispatcher (src/gcode/queue.cpp)
→ invokes appropriate G/M handlers (src/gcode/*/*.cpp)
- Feature Modules (src/feature/*.cpp)
→ extend behavior (e.g., bed leveling, probes)
- Core Modules (src/module/*.cpp)
→ coordinate motion planning, endstop logic, temperature control, steppers
- Utilities & libs

- HAL Layer
- Common HAL interfaces (src/HAL/shared)
- MCU-specific HAL implementations (src/HAL/AVR, DUE, ESP32, LPC1768, STM32…)
→ digital I/O, timers, PWM, SPI, serial, watchdog, EEPROM, USB, WebSockets
- Pin mapping (src/pins/…)

- Hardware Peripherals
- MCU (ATmega, Cortex-M, ESP32, Linux)
- Stepper drivers (integrated or external TMCxxxx)
- Temperature sensors (thermistors)
- Endstops, probes
- Heaters (hotend, bed)
- SD-card / USB mass-storage
- LCD / Touch UI
- Communications: Serial, USB-CDC, WebSocket (ESP32), network

- External Host / User
- Slicer / Host-Software sends G-Code via USB or network
- Or user loads G-Code file on SD card or via Web UI

##### Architectural Patterns & Principles
- Layered architecture: Application (GCode → modules) → HAL → Hardware
- Hardware Abstraction: clean C++ interfaces shield core logic from MCU details
- Modular: features can be enabled/disabled at compile time via Configuration.h
- Event/Command dispatch: GCode commands mapped to handlers
- Separation of concerns: parsing, planning, motion control, hardware I/O

- Build System (PlatformIO / Arduino)
- Configuration Module
- GCode Parser & Queue
- Feature Modules
- Core Modules (Planner, Motion, Temperature, Endstops)
- HAL Interfaces (shared)
- HAL Implementations (per-MCU)
- Hardware Peripherals
- External Host / SD / Web UI

- Build System → Configuration + Source Code → Firmware Binary
- External Host → Serial/USB/WebSocket → GCode Parser
- GCode Parser → Queue → Core / Feature Modules
- Core / Feature Modules → HAL Interfaces → HAL Implementations → Hardware
- Hardware → HAL (sensor feedback) → Core Modules (closed-loop)

c. Technologies / Frameworks:
- PlatformIO / Arduino IDE (build)
- C++17, GCC, AVR-GCC, ARM-GCC
- SPI, I2C, PWM, UART, USB-CDC, WebSocket (ESP32)
- u8g / u8glib (LCD graphics)
- heatshrink, backtrace libs, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Host & UI
    ExternalHost["External Host / Slicer"]:::external
    SDCard["SD Card"]:::external
    WebUIClient["Web UI (ESP32)"]:::external

    %% Build & Configuration Layer
    subgraph "Build & Configuration" 
        direction TB
        PlatformIOINI["platformio.ini"]:::build
        Makefile["Marlin/Makefile"]:::build
        MarlinINO["Marlin/Marlin.ino"]:::build
        BuildrootPlatformIO["buildroot/share/PlatformIO"]:::build
        ConfigurationH["Configuration.h"]:::config
        ConfigurationAdv["Configuration_adv.h"]:::config
        MarlinConfigPre["MarlinConfigPre.h"]:::config
        MarlinConfig["MarlinConfig.h"]:::config
        VersionH["Version.h"]:::config
    end

    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        subgraph "G-Code Processing" 
            direction TB
            Parser["GCode Parser"]:::app
            Queue["GCode Queue & Dispatcher"]:::app
            Handlers["G-Code Handlers"]:::app
        end
        subgraph "Modules" 
            direction TB
            FeatureModules["Feature Modules"]:::app
            CoreModules["Core Modules"]:::app
        end
        Utilities["Utilities & Libs"]:::app
        MarlinCore["MarlinCore (Entry Point)"]:::app
    end

    %% HAL Layer
    subgraph "HAL Layer"
        direction TB
        HALInterfaces["HAL Shared Interfaces"]:::hal
        HALImpl["HAL Implementations"]:::hal
        Pins["Pin Mapping"]:::hal
    end

    %% Hardware Peripherals
    subgraph "Hardware Peripherals"
        direction TB
        MCU["MCU"]:::hw
        Steppers["Stepper Drivers"]:::hw
        Sensors["Temp Sensors / Endstops / Probes"]:::hw
        Heaters["Heaters"]:::hw
        Storage["SD / USB Mass-Storage"]:::hw
        Display["LCD / Touch UI"]:::hw
        CommPeriph["Serial / USB-CDC / WebSocket"]:::hw
    end

    %% Test & Board Variants
    subgraph "Tests & Variants"
        direction TB
        Tests["Automated Tests"]:::build
        Variants["Board Variants"]:::build
    end

    %% Flows
    ExternalHost -->|"sends G-Code"| Parser
    SDCard -->|"loads G-Code"| Parser
    WebUIClient -->|"sends G-Code"| Parser

    PlatformIOINI --> Makefile
    Makefile --> MarlinINO
    MarlinINO --> BuildrootPlatformIO
    BuildrootPlatformIO --> ConfigurationH
    ConfigurationH --> MarlinConfigPre
    ConfigurationAdv --> MarlinConfigPre
    MarlinConfigPre --> MarlinConfig
    VersionH --> MarlinCore

    MarlinConfig -->|compile-time options| Parser
    Parser --> Queue
    Queue --> Handlers
    Queue --> FeatureModules
    Queue --> CoreModules
    FeatureModules --> Utilities
    CoreModules --> Utilities
    MarlinCore --> Parser

    CoreModules --> HALInterfaces
    FeatureModules --> HALInterfaces
    Utilities --> HALInterfaces
    HALInterfaces --> HALImpl
    HALInterfaces --> Pins
    HALImpl --> MCU
    HALImpl --> Steppers
    HALImpl --> Sensors
    HALImpl --> Heaters
    HALImpl --> Storage
    HALImpl --> Display
    HALImpl --> CommPeriph

    Sensors -->|feedback| CoreModules
    Sensors -->|feedback| FeatureModules

    BuildrootPlatformIO --> Tests
    BuildrootPlatformIO --> Variants

    %% Click Events
    click PlatformIOINI "https://github.com/magruder13/mpcnc/blob/master/platformio.ini"
    click Makefile "https://github.com/magruder13/mpcnc/tree/master/Marlin/Makefile"
    click MarlinINO "https://github.com/magruder13/mpcnc/blob/master/Marlin/Marlin.ino"
    click BuildrootPlatformIO "https://github.com/magruder13/mpcnc/tree/master/buildroot/share/PlatformIO"
    click ConfigurationH "https://github.com/magruder13/mpcnc/blob/master/Marlin/Configuration.h"
    click ConfigurationAdv "https://github.com/magruder13/mpcnc/blob/master/Marlin/Configuration_adv.h"
    click MarlinConfigPre "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/inc/MarlinConfigPre.h"
    click MarlinConfig "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/inc/MarlinConfig.h"
    click VersionH "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/inc/Version.h"
    click Parser "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/gcode/parser.cpp"
    click Queue "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/gcode/queue.cpp"
    click Handlers "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/gcode/"
    click FeatureModules "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/feature/"
    click CoreModules "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/module/"
    click Utilities "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/libs/"
    click MarlinCore "https://github.com/magruder13/mpcnc/blob/master/Marlin/src/MarlinCore.cpp"
    click HALInterfaces "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/HAL/shared/"
    click HALImpl "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/HAL/"
    click Pins "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/pins/"
    click Storage "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/sd/"
    click Display "https://github.com/magruder13/mpcnc/tree/master/Marlin/src/lcd/"
    click Tests "https://github.com/magruder13/mpcnc/tree/master/buildroot/share/tests/"
    click Variants "https://github.com/magruder13/mpcnc/tree/master/buildroot/share/PlatformIO/variants/"

    %% Styles
    classDef build fill:#dddddd,stroke:#888888,color:#000000
    classDef config fill:#bbbbbb,stroke:#666666,color:#000000
    classDef app fill:#cce5ff,stroke:#3399ff,color:#000000
    classDef hal fill:#d4edda,stroke:#28a745,color:#000000
    classDef hw fill:#ffe5cc,stroke:#ff6600,color:#000000
    classDef external fill:#f0e6f7,stroke:#9370db,color:#000000
```
