# kurokesu/sce2-grbl architecture

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

- Interactive diagram: https://gitdiagram.com/kurokesu/sce2-grbl
- Repository: https://github.com/kurokesu/sce2-grbl

## Overview

##### Main Components
- MCU / Hardware Platform: At the center, show the STM32F10x microcontroller, since all firmware components run on this hardware.
- Core Firmware / GRBL Engine: Illustrate this as a central block that encompasses:
- G-code parsing and protocol handling (files such as src/gcode.c, src/protocol.c, inc/gcode.h, inc/protocol.h)
- Motion planning and control (src/motion_control.c, src/planner.c, inc/motion_control.h, inc/planner.h)
- Stepper motor control (src/stepper.c, inc/stepper.h)
- Auxiliary functionalities like coolant control, limits, probe, jog (the corresponding modules in inc and src)
- USB Communication Stack:
- USB interface unit by showing two layers:
▪ The USB FS Library module (from stm_usb_fs_lib and usb directories), including configurations and ISR handling.
▪ The mapping between the physical USB hardware and the firmware’s serial/USB routines.
- Hardware Abstraction / Middleware:
- CMSIS Libraries and STM32F10x Standard Peripheral Driver: Group these libraries (found under Libraries/CMSIS and Libraries/STM32F10x_StdPeriph_Driver) as the peripheral abstraction layer that bridges the raw hardware with the firmware.
- Configuration & Build Infrastructure:
- Configuration files (inc/config.h, other header files, and linker scripts like stm32_flash.ld) and startup routines (e.g., src/startup_stm32f10x_md.s).
- Debug/Build Artifacts:
- That there is a Debug folder containing the compiled binaries and associated build files. (This is less critical for data flow but might be useful in a complete architecture document.)

##### Relationships and Interactions
- Data Flow from USB to Controller:
- Internal Processing:
- From the GRBL Engine, include flows to lower-level drivers (e.g., motion control and stepper motor control) to represent the sequencing of commands and pulse generation.
- Hardware Abstraction:
- Dependencies flowing from the GRBL Engine to the peripheral libraries (CMSIS, StdPeriph_Driver) which handle the actual hardware control such as GPIO, timers, and interrupts.
- Configuration & System Initialization:
- A separate block should illustrate the role of initialization/startup routines and configuration settings that prepare the MCU and the firmware.

##### Architectural Patterns and Design Principles
- Embedded Application Pattern:
- That the entire design is tightly coupled with the microcontroller’s hardware and the firmware is designed for real-time control.
- Layered Architecture:
- Distinct layers where the top represents application-specific logic (g-code, motion, stepper control) and the bottom layer represents hardware abstraction (CMSIS, peripheral drivers).
- Modular Design:
- Each major functionality (e.g., coolant control, spindle control, USB communication) is implemented in its own source and header files – indicate these as separate modules within the GRBL engine block.

##### Relevant Technologies & Libraries
- Microcontroller: STM32F10x
- USB Stack: Custom USB library from stm_usb_fs_lib and various USB modules in the usb directory
- Peripheral Libraries: CMSIS and STM32F10x Standard Peripheral Driver Libraries
- Build System: Managed via makefiles (as seen in the Debug folder) and project files (.cproject, .project)

## Diagram (Mermaid)

```mermaid
graph TD
    %% USB Communication Stack
    subgraph "USB Communication Stack"
        USB_FS["USB FS Library"]:::usb
        USB_PI["USB Physical Interface"]:::usb
    end

    %% Core Firmware / GRBL Engine
    subgraph "Core Firmware / GRBL Engine"
        Gcode["G-code Parser & Protocol"]:::grbl
        Motion["Motion Planner & Control"]:::grbl
        Stepper["Stepper Motor Control"]:::grbl
        subgraph "Auxiliary Functions"
            Coolant["Coolant Control"]:::grbl
            Jog["Jog Control"]:::grbl
            Limits["Limits"]:::grbl
            Probe["Probe"]:::grbl
            Spindle["Spindle Control"]:::grbl
            Settings["Settings & Reports"]:::grbl
            Nuts["Nuts & Bolts"]:::grbl
            EEPROM["EEPROM"]:::grbl
        end
    end

    %% Hardware Abstraction / Middleware
    subgraph "Hardware Abstraction / Middleware"
        CMSIS["CMSIS Libraries"]:::hal
        StdPeriph["STM32F10x StdPeriph Driver"]:::hal
    end

    %% Configuration & Build Infrastructure
    subgraph "Configuration & Build Infrastructure"
        Config["Configuration Files"]:::config
        Build["Build Artifacts & Makefiles"]:::config
    end

    %% MCU Hardware Platform
    MCU["STM32F10x MCU Hardware"]:::mcu

    %% Connections from USB to GRBL Engine
    USB_FS -->|"g-code_cmd"| Gcode
    USB_PI -->|"hw_mapping"| Gcode

    %% Internal GRBL Engine Processing
    Gcode -->|"control"| Motion
    Gcode -->|"control"| Stepper
    Gcode -->|"control"| Coolant
    Gcode -->|"control"| Jog
    Gcode -->|"control"| Limits
    Gcode -->|"control"| Probe
    Gcode -->|"control"| Spindle
    Gcode -->|"control"| Settings
    Gcode -->|"control"| Nuts
    Gcode -->|"control"| EEPROM
    Motion -->|"drives"| Stepper

    %% GRBL Engine dependency on Hardware Abstraction
    Gcode -->|"dep"| CMSIS
    Motion -->|"dep"| CMSIS
    Stepper -->|"dep"| StdPeriph

    %% Hardware Abstraction drives the MCU Hardware
    CMSIS --> MCU
    StdPeriph --> MCU

    %% Configuration & Build Initialization into MCU
    Config --> MCU
    Build --> MCU

    %% GRBL Engine runs on MCU
    Gcode -->|"runs_on"| MCU

    %% Click Events for MCU / Hardware Platform
    click MCU "https://github.com/kurokesu/sce2-grbl/blob/master/src/main.c"
    click MCU "https://github.com/kurokesu/sce2-grbl/blob/master/src/system.c"
    click MCU "https://github.com/kurokesu/sce2-grbl/blob/master/src/system_stm32f10x.c"
    click MCU "https://github.com/kurokesu/sce2-grbl/blob/master/src/startup_stm32f10x_md.s"
    click MCU "https://github.com/kurokesu/sce2-grbl/blob/master/stm32_flash.ld"

    %% Click Events for Core Firmware / GRBL Engine - G-code Parsing and Protocol Handling
    click Gcode "https://github.com/kurokesu/sce2-grbl/blob/master/src/gcode.c"
    click Gcode "https://github.com/kurokesu/sce2-grbl/blob/master/inc/gcode.h"
    click Gcode "https://github.com/kurokesu/sce2-grbl/blob/master/src/protocol.c"
    click Gcode "https://github.com/kurokesu/sce2-grbl/blob/master/inc/protocol.h"

    %% Click Events for Motion Planning and Control
    click Motion "https://github.com/kurokesu/sce2-grbl/blob/master/src/motion_control.c"
    click Motion "https://github.com/kurokesu/sce2-grbl/blob/master/inc/motion_control.h"
    click Motion "https://github.com/kurokesu/sce2-grbl/blob/master/src/planner.c"
    click Motion "https://github.com/kurokesu/sce2-grbl/blob/master/inc/planner.h"

    %% Click Events for Stepper Motor Control
    click Stepper "https://github.com/kurokesu/sce2-grbl/blob/master/src/stepper.c"
    click Stepper "https://github.com/kurokesu/sce2-grbl/blob/master/inc/stepper.h"

    %% Click Events for Auxiliary Functionalities
    click Coolant "https://github.com/kurokesu/sce2-grbl/blob/master/src/coolant_control.c"
    click Coolant "https://github.com/kurokesu/sce2-grbl/blob/master/inc/coolant_control.h"
    click Jog "https://github.com/kurokesu/sce2-grbl/blob/master/src/jog.c"
    click Jog "https://github.com/kurokesu/sce2-grbl/blob/master/inc/jog.h"
    click Limits "https://github.com/kurokesu/sce2-grbl/blob/master/src/limits.c"
    click Limits "https://github.com/kurokesu/sce2-grbl/blob/master/inc/limits.h"
    click Probe "https://github.com/kurokesu/sce2-grbl/blob/master/src/probe.c"
    click Probe "https://github.com/kurokesu/sce2-grbl/blob/master/inc/probe.h"
    click Spindle "https://github.com/kurokesu/sce2-grbl/blob/master/src/spindle_control.c"
    click Spindle "https://github.com/kurokesu/sce2-grbl/blob/master/inc/spindle_control.h"
    click Settings "https://github.com/kurokesu/sce2-grbl/blob/master/src/settings.c"
    click Settings "https://github.com/kurokesu/sce2-grbl/blob/master/inc/settings.h"
    click Settings "https://github.com/kurokesu/sce2-grbl/blob/master/src/report.c"
    click Settings "https://github.com/kurokesu/sce2-grbl/blob/master/inc/report.h"
    click Nuts "https://github.com/kurokesu/sce2-grbl/blob/master/src/nuts_bolts.c"
    click Nuts "https://github.com/kurokesu/sce2-grbl/blob/master/inc/nuts_bolts.h"
    click EEPROM "https://github.com/kurokesu/sce2-grbl/blob/master/src/eeprom.c"
    click EEPROM "https://github.com/kurokesu/sce2-grbl/blob/master/inc/eeprom.h"

    %% Click Events for USB Communication Stack
    click USB_FS "https://github.com/kurokesu/sce2-grbl/tree/master/stm_usb_fs_lib/"
    click USB_PI "https://github.com/kurokesu/sce2-grbl/tree/master/usb/"

    %% Click Events for Hardware Abstraction / Middleware
    click CMSIS "https://github.com/kurokesu/sce2-grbl/tree/master/Libraries/CMSIS/"
    click StdPeriph "https://github.com/kurokesu/sce2-grbl/tree/master/Libraries/STM32F10x_StdPeriph_Driver/"

    %% Click Events for Configuration & Build Infrastructure
    click Config "https://github.com/kurokesu/sce2-grbl/blob/master/inc/config.h"
    click Config "https://github.com/kurokesu/sce2-grbl/blob/master/.cproject"
    click Config "https://github.com/kurokesu/sce2-grbl/blob/master/.project"
    click Build "https://github.com/kurokesu/sce2-grbl/tree/master/Debug/"

classDef mcu fill:#ADD8E6,stroke:#000,stroke-width:2px;
classDef grbl fill:#90EE90,stroke:#000,stroke-width:2px;
classDef usb fill:#FFFF99,stroke:#000,stroke-width:2px;
classDef hal fill:#D3D3D3,stroke:#000,stroke-width:2px;
classDef config fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
