# bdring/fluidnc architecture

> Architecture diagram of the GitHub repository bdring/fluidnc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bdring/fluidnc
- Repository: https://github.com/bdring/fluidnc

## Overview

FluidNC is configurable CNC-controller firmware, principally aimed at ESP32, with platform variants and a POSIX simulator. A machine configuration describes axes, kinematics, motors, pins, and tool hardware; the firmware parses it, accepts Grbl-compatible commands, plans motion, and drives step outputs and machine peripherals. Users interact through serial or the built-in Web UI, and jobs can also come from files. The README documents flexible machine types, multiple tools, and AI config helpers. The tree supports these major areas; sampled source chiefly confirms configuration parsing and the stepping-engine interface/implementations.

Main entry points: [`FluidNC/include/Driver/step_engine.h`](https://github.com/bdring/fluidnc/blob/main/FluidNC/include/Driver/step_engine.h) (Step engine API), [`FluidNC/src/WebUI/WebUIServer.cpp`](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/WebUI/WebUIServer.cpp) (Web interface), [`FluidNC/src/Protocol.cpp`](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Protocol.cpp) (Command protocol), [`FluidNC/src/Planner.cpp`](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Planner.cpp) (Motion planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Machine configuration"]
  node_parser["Config parser<br/>[Parser.cpp]"]
  node_validator["Config validation<br/>[Validator.cpp]"]
  node_machine_config["Machine setup<br/>[MachineConfig.cpp]"]
  node_config_helpers["Config helpers"]
end

subgraph group_control["CNC control"]
  node_protocol["Command protocol<br/>[Protocol.cpp]"]
  node_gcode["G-code interpreter<br/>[GCode.cpp]"]
  node_job["Job execution<br/>[Job.cpp]"]
  node_planner["Motion planner<br/>[Planner.cpp]"]
  node_motion["Motion control<br/>[MotionControl.cpp]"]
  node_stepping["Step scheduling<br/>[Stepping.cpp]"]
end

subgraph group_machine["Machine hardware"]
  node_kinematics["Kinematics<br/>[Kinematics.cpp]"]
  node_axes["Axes and motors<br/>[Axes.cpp]"]
  node_motor_drivers["Motor drivers<br/>[MotorDriver.cpp]"]
  node_spindles["Spindles and tools<br/>[Spindle.cpp]"]
  node_peripherals["Machine peripherals<br/>[CoolantControl.cpp]"]
end

subgraph group_interfaces["User interfaces"]
  node_webui["Web interface<br/>[WebUIServer.cpp]"]
  node_channels["Command channels<br/>[Channel.cpp]"]
  node_file_jobs["File and SD jobs<br/>[FileCommands.cpp]"]
  node_settings["Settings and reports<br/>[Settings.cpp]"]
end

subgraph group_platform["Platform drivers"]
  node_step_engine["Step engine API<br/>[step_engine.h]"]
  node_esp32_engines["ESP32 engines<br/>[i2s_engine.cpp]"]
  node_rp2040_engine["RP2040 PIO engine<br/>[pio_engine.cpp]"]
  node_posix_engine["Simulator engine"]
end

node_operator(("Operator / sender"))
node_config_file["Machine config"]
node_hardware{{"Controller hardware"}}
node_browser(("Browser / network"))
node_storage[("On-device storage")]

node_operator -->|"writes config"| node_config_file
node_config_file -->|"loads config"| node_parser
node_parser -->|"parses values"| node_validator
node_validator -->|"validates setup"| node_machine_config
node_config_helpers -.->|"checks config"| node_config_file
node_operator -->|"controls machine"| node_webui
node_browser -->|"connects"| node_webui
node_operator -->|"sends commands"| node_channels
node_webui -->|"dispatches commands"| node_channels
node_channels -->|"delivers input"| node_protocol
node_storage -->|"provides job files"| node_file_jobs
node_file_jobs -->|"starts job"| node_job
node_protocol -->|"dispatches G-code"| node_gcode
node_gcode -->|"submits moves"| node_planner
node_planner -->|"transforms motion"| node_kinematics
node_planner -->|"provides planned moves"| node_motion
node_motion -->|"schedules steps"| node_stepping
node_stepping -->|"uses engine API"| node_step_engine
node_step_engine -->|"selects implementation"| node_esp32_engines
node_step_engine -.->|"selects implementation"| node_rp2040_engine
node_step_engine -.->|"selects simulator"| node_posix_engine
node_axes -->|"configures motors"| node_motor_drivers
node_motor_drivers -->|"drives motors"| node_hardware
node_spindles -->|"controls tools"| node_hardware
node_peripherals -->|"controls outputs"| node_hardware
node_esp32_engines -->|"outputs step pulses"| node_hardware
node_rp2040_engine -.->|"outputs step pulses"| node_hardware
node_posix_engine -.->|"queues position updates"| node_webui
node_protocol -->|"handles settings"| node_settings
node_settings -->|"persists settings"| node_storage

click node_parser "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Configuration/Parser.cpp"
click node_validator "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Configuration/Validator.cpp"
click node_machine_config "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Machine/MachineConfig.cpp"
click node_config_helpers "https://github.com/bdring/fluidnc/blob/main/tools/validate_fluidnc_config.py"
click node_protocol "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Protocol.cpp"
click node_gcode "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/GCode.cpp"
click node_job "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Job.cpp"
click node_planner "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Planner.cpp"
click node_motion "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/MotionControl.cpp"
click node_stepping "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Stepping.cpp"
click node_kinematics "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Kinematics/Kinematics.cpp"
click node_axes "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Machine/Axes.cpp"
click node_motor_drivers "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Motors/MotorDriver.cpp"
click node_spindles "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Spindles/Spindle.cpp"
click node_peripherals "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/CoolantControl.cpp"
click node_webui "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/WebUI/WebUIServer.cpp"
click node_channels "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Channel.cpp"
click node_file_jobs "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/FileCommands.cpp"
click node_settings "https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Settings.cpp"
click node_step_engine "https://github.com/bdring/fluidnc/blob/main/FluidNC/include/Driver/step_engine.h"
click node_esp32_engines "https://github.com/bdring/fluidnc/blob/main/FluidNC/esp32/esp32/i2s_engine.cpp"
click node_rp2040_engine "https://github.com/bdring/fluidnc/blob/main/FluidNC/rp2040/pio_engine.cpp"
click node_posix_engine "https://github.com/bdring/fluidnc/blob/main/FluidNC/posix/simulator_engine.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parser,node_validator,node_machine_config,node_config_helpers,node_browser toneBlue
class node_protocol,node_gcode,node_job,node_planner,node_motion,node_stepping,node_storage toneAmber
class node_kinematics,node_axes,node_motor_drivers,node_spindles,node_peripherals toneMint
class node_webui,node_channels,node_file_jobs,node_settings toneRose
class node_step_engine,node_esp32_engines,node_rp2040_engine,node_posix_engine,node_operator,node_config_file,node_hardware toneIndigo
```

## Components

### Machine configuration

- [Config parser](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Configuration/Parser.cpp): `FluidNC/src/Configuration/Parser.cpp`
- [Config validation](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Configuration/Validator.cpp): `FluidNC/src/Configuration/Validator.cpp`
- [Machine setup](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Machine/MachineConfig.cpp): `FluidNC/src/Machine/MachineConfig.cpp`
- [Config helpers](https://github.com/bdring/fluidnc/blob/main/tools/validate_fluidnc_config.py): `tools/validate_fluidnc_config.py`

### CNC control

- [Command protocol](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Protocol.cpp): `FluidNC/src/Protocol.cpp`
- [G-code interpreter](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/GCode.cpp): `FluidNC/src/GCode.cpp`
- [Job execution](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Job.cpp): `FluidNC/src/Job.cpp`
- [Motion planner](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Planner.cpp): `FluidNC/src/Planner.cpp`
- [Motion control](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/MotionControl.cpp): `FluidNC/src/MotionControl.cpp`
- [Step scheduling](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Stepping.cpp): `FluidNC/src/Stepping.cpp`

### Machine hardware

- [Kinematics](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Kinematics/Kinematics.cpp): `FluidNC/src/Kinematics/Kinematics.cpp`
- [Axes and motors](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Machine/Axes.cpp): `FluidNC/src/Machine/Axes.cpp`
- [Motor drivers](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Motors/MotorDriver.cpp): `FluidNC/src/Motors/MotorDriver.cpp`
- [Spindles and tools](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Spindles/Spindle.cpp): `FluidNC/src/Spindles/Spindle.cpp`
- [Machine peripherals](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/CoolantControl.cpp): `FluidNC/src/CoolantControl.cpp`

### User interfaces

- [Web interface](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/WebUI/WebUIServer.cpp): `FluidNC/src/WebUI/WebUIServer.cpp`
- [Command channels](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Channel.cpp): `FluidNC/src/Channel.cpp`
- [File and SD jobs](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/FileCommands.cpp): `FluidNC/src/FileCommands.cpp`
- [Settings and reports](https://github.com/bdring/fluidnc/blob/main/FluidNC/src/Settings.cpp): `FluidNC/src/Settings.cpp`

### Platform drivers

- [Step engine API](https://github.com/bdring/fluidnc/blob/main/FluidNC/include/Driver/step_engine.h): `FluidNC/include/Driver/step_engine.h`
- [ESP32 engines](https://github.com/bdring/fluidnc/blob/main/FluidNC/esp32/esp32/i2s_engine.cpp): `FluidNC/esp32/esp32/i2s_engine.cpp`
- [RP2040 PIO engine](https://github.com/bdring/fluidnc/blob/main/FluidNC/rp2040/pio_engine.cpp): `FluidNC/rp2040/pio_engine.cpp`
- [Simulator engine](https://github.com/bdring/fluidnc/blob/main/FluidNC/posix/simulator_engine.cpp): `FluidNC/posix/simulator_engine.cpp`

### Other components

- **Operator / sender**
- **Machine config**
- **Controller hardware**
- **Browser / network**
- **On-device storage**

## Connections

- Operator / sender → Machine config: writes config
- Machine config → Config parser: loads config
- Config parser → Config validation: parses values
- Config validation → Machine setup: validates setup
- Config helpers → Machine config: checks config
- Operator / sender → Web interface: controls machine
- Browser / network → Web interface: connects
- Operator / sender → Command channels: sends commands
- Web interface → Command channels: dispatches commands
- Command channels → Command protocol: delivers input
- On-device storage → File and SD jobs: provides job files
- File and SD jobs → Job execution: starts job
- Command protocol → G-code interpreter: dispatches G-code
- G-code interpreter → Motion planner: submits moves
- Motion planner → Kinematics: transforms motion
- Motion planner → Motion control: provides planned moves
- Motion control → Step scheduling: schedules steps
- Step scheduling → Step engine API: uses engine API
- Step engine API → ESP32 engines: selects implementation
- Step engine API → RP2040 PIO engine: selects implementation
- Step engine API → Simulator engine: selects simulator
- Axes and motors → Motor drivers: configures motors
- Motor drivers → Controller hardware: drives motors
- Spindles and tools → Controller hardware: controls tools
- Machine peripherals → Controller hardware: controls outputs
- ESP32 engines → Controller hardware: outputs step pulses
- RP2040 PIO engine → Controller hardware: outputs step pulses
- Simulator engine → Web interface: queues position updates
- Command protocol → Settings and reports: handles settings
- Settings and reports → On-device storage: persists settings
