How magruder13/mpcnc works
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.