# xblax/flashforge_ad5m_klipper_mod architecture

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

- Interactive diagram: https://gitdiagram.com/xblax/flashforge_ad5m_klipper_mod
- Repository: https://github.com/xblax/flashforge_ad5m_klipper_mod

## Overview

##### Project Type and Purpose
- This is an embedded-Linux build system (using Buildroot) that produces removable “mod” images for the Flashforge Adventurer 5M(Pro).
- At runtime it runs on the printer’s Allwinner T113-S3, hosting Klipper (firmware), Moonraker (API server), web UIs (Mainsail/Fluidd), screen frontends (KlipperScreen/Guppyscreen), camera streaming and hardware utilities (buzzer, backlight, USB automount, Wi-Fi).

##### File Structure Analysis
- Top-level directories:
- build_overlay – rootfs overlays (common + three variants: headless, KlipperScreen, Guppy)
- build_scripts – orchestration scripts, Buildroot configs, toolchain, component patches
- device_files – installer/uninstaller scripts & images for flashing the printer
- device_tools – MCU boot code for the printer controller
- prebuilt – prebuilt Python wheels, plugin bundles, environment tarballs
- printer_configs – sample Klipper/Moonraker printer config files
- submodules – Klipper, Moonraker, KlipperScreen, Buildroot submodule sources
- Patterns:
- Overlay pattern (common + variant) for customizing rootfs
- Build pipeline triggered by build_scripts/build.sh → Buildroot → post_build.sh
- init.d boot scripts in overlays drive service startup on target

##### README Insights
- Clarifies runtime services and their ports: Klipper (firmware), Moonraker (7125), Mainsail (4000), Fluidd (4001), ustreamer (8080).
- Highlights hardware interfaces: Wi-Fi (iwd), camera, buzzer/audio, LCD backlight, USB.
- Describes variants: headless, KlipperScreen UI, lightweight Guppyscreen UI.

a. Main Components
– Developer Workstation (shell environment with toolchain, venv)
– Build System: build_scripts + Buildroot + overlays + submodules + prebuilt wheels
– Build Outputs: flashable rootfs images (common + variant), kernel modules, device_tools MCU binary
– Installer: device_files flash scripts/images
– Target Device: Allwinner T113-S3 SoC running BusyBox/Linux, mounted rootfs
– Runtime Services on Device:
- Kernel + Modules (uinput, cbc, md4, sha512, ustreamer driver)
- init.d scripts (service orchestration)
- Klipper (host ↔ MCU over serial)
- Moonraker API
- Web Frontends: Mainsail, Fluidd (connect to Moonraker)
- Screen Frontends: KlipperScreen or Guppyscreen (framebuffer UI)
- ustreamer (camera → HTTP stream)
- iwd (Wi-Fi), automount, buzzer, backlight controls
b. Relationships & Data Flows
– Build scripts invoke Buildroot with overlays & configs → produces images
– post_build.sh bundles images + device_tools → installer archive
– Installer flash scripts writes rootfs to printer storage
– On boot: init → runs common init.d scripts → mounts data, sets time, loads modules
– init.d starts Moonraker → Klipper → web servers → screen daemon → ustreamer → hardware interfaces
– Moonraker listens on 7125; frontends connect over HTTP; KlipperScreen reads local pipe; Klipper ↔ MCU via serial; ustreamer ↔ camera device
c. Architectural Patterns & Principles
– Layered build pipeline: toolchain → Buildroot → overlays → image generation
– Variant configuration using overlay directories for feature toggles
– Init.d service orchestration for predictable boot ordering
– Separation of concerns: firmware (Klipper), API (Moonraker), UI (web + screen), hardware drivers/utilities
d. Key Technologies & Frameworks
– Buildroot, Makefile, Bash scripts
– Python (Moonraker, Mainsail, Fluidd, plugins, ustreamer)
– C (device_tools MCU code)
– BusyBox init, init.d scripts
– iwd for Wi-Fi, uinput kernel module, Allwinner T113-S3 SoC

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build-time"
        subgraph "Developer Workstation"
            dev1["build_scripts/build.sh"]:::buildtime
            dev2["build_scripts/env.sh"]:::buildtime
            dev3["build_scripts/toolchain.sh"]:::buildtime
            dev4["Makefile"]:::buildtime
        end
        subgraph "Buildroot Build System"
            br1["Config.in"]:::buildtime
            br2["configs/*"]:::buildtime
            br3["external.desc / external.mk"]:::buildtime
            br4["post_build.sh"]:::buildtime
        end
        subgraph "Rootfs Overlays"
            ovc["common"]:::buildtime
            ovg["variant-guppyscreen"]:::buildtime
            ovk["variant-klipperscreen"]:::buildtime
            ovl["variant-lite"]:::buildtime
        end
        dev1 --> br1
        br4 --> ovc
        br4 --> ovg
        br4 --> ovk
        br4 --> ovl
    end

    subgraph "Build Outputs"
        img["Images (rootfs variants)"]:::buildtime
        km["Kernel Modules"]:::buildtime
        dt["Device Tools MCU Bin"]:::buildtime
    end
    ovc --> img
    ovg --> img
    ovk --> img
    ovl --> img
    br4 --> km
    dt --> img

    subgraph "Installer"
        inst1["flashforge_init.sh"]:::buildtime
        inst2["img/*.img.xz"]:::buildtime
    end
    img --> inst1
    img --> inst2

    subgraph "Target Device (Runtime)"
        subgraph "Kernel & Init"
            km2["Kernel + Modules"]:::runtime
            initd["init.d scripts"]:::runtime
        end
        subgraph "Services"
            subgraph "Firmware"
                kl1["Klipper Submodule"]:::runtime
                kl2["klipper_wheels"]:::runtime
                kl3["klipper Makefile"]:::runtime
            end
            moon1["Moonraker Submodule"]:::runtime
            fs1["Mainsail (HTTP:4000)"]:::runtime
            fs2["Fluidd (HTTP:4001)"]:::runtime
            subgraph "Screen UI"
                ks["KlipperScreen"]:::runtime
                gu["Guppyscreen"]:::runtime
            end
            usb["ustreamer (HTTP:8080)"]:::runtime
            subgraph "Hardware Utils"
                wifi["iwd (Wi-Fi)"]:::hardware
                buz["Buzzer & Backlight"]:::hardware
                auto["Automount"]:::hardware
            end
        end
        km2 --> initd
        initd --> kl1
        initd --> moon1
        initd --> fs1
        initd --> fs2
        initd --> ks
        initd --> gu
        initd --> usb
        initd --> wifi
        initd --> buz
        initd --> auto
    end

    click dev1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/build.sh"
    click dev2 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/env.sh"
    click dev3 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/toolchain.sh"
    click dev4 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/Makefile"
    click br1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/buildroot/Config.in"
    click br2 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_scripts/buildroot/configs/"
    click br3 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/buildroot/external.desc"
    click br4 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_scripts/buildroot/post_build.sh"
    click ovc "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/common"
    click ovg "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/variant-guppyscreen"
    click ovk "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/variant-klipperscreen"
    click ovl "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/variant-lite"
    click initd "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_overlay/common/etc/init.d"
    click kl1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/submodules/klipper"
    click kl2 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/prebuilt/wheels/klipper_wheels"
    click kl3 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_scripts/components/klipper/Makefile"
    click moon1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/submodules/moonraker"
    click fs1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/common/etc/init.d/S70mainsail"
    click fs2 "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/common/etc/init.d/S70fluidd"
    click ks "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/submodules/KlipperScreen"
    click gu "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_overlay/variant-guppyscreen/etc/init.d/S80guppyscreen"
    click usb "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_scripts/buildroot/package/ustreamer"
    click auto "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/build_overlay/common/usr/libexec/automount.sh"
    click buz "https://github.com/xblax/flashforge_ad5m_klipper_mod/tree/master/build_scripts/buildroot/package/python-ff-ad5m-backlight"
    click dt "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/device_tools/mcu/boot_eboard_mcu.c"
    click inst1 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/device_files/install/flashforge_init.sh"
    click inst2 "https://github.com/xblax/flashforge_ad5m_klipper_mod/blob/master/device_files/install/img/*.img.xz"

    classDef buildtime fill:#D6EAF8,stroke:#2574A9
    classDef runtime fill:#D5F5E3,stroke:#239B56
    classDef hardware fill:#FCF3CF,stroke:#B7950B
```
