Skip to content

development.md

Latest commit

 

History

History
229 lines (155 loc) · 7 KB

development.md

File metadata and controls

229 lines (155 loc) · 7 KB
title Building from Source

Building from Source

Understanding Overlays

The custom firmware uses an overlay system to modify the base Snapmaker firmware. Overlays are modular modifications that:

  • Add patches to modify existing firmware files
  • Copy additional files to the firmware root filesystem
  • Run build-time scripts to install components
  • Enable features without changing the base firmware source

Each overlay is self-contained and numbered to control application order. This modular approach makes it easy to:

  • Enable/disable features by including/excluding overlays
  • Maintain different firmware profiles (basic vs extended)
  • Add custom modifications without conflicts

Prerequisites

  • Docker installed on your system

The ./dev.sh script automatically sets up a Debian Trixie ARM64 environment with all required dependencies.

Quick Start

Build tools and download firmware:

./dev.sh make tools
./dev.sh make firmware

Build basic firmware:

./dev.sh make build PROFILE=basic OUTPUT_FILE=firmware/U1_basic.bin

Build extended firmware:

./dev.sh make build PROFILE=extended OUTPUT_FILE=firmware/U1_extended.bin

Open a shell in the development environment:

./dev.sh bash

Profiles

The build system supports two profiles:

  • basic - simple modifications not changing key components of the firmware
  • extended - extensive modifications changing key components of the firmware

Overlays

Overlays are organized into categories based on their scope and build profile. Each overlay is numbered to indicate its application order within its category.

Overlay Categories

  • common/ - Core modifications applied to all firmware profiles (basic and extended)
  • firmware-basic/ - Modifications specific to the basic firmware profile
  • firmware-extended/ - Modifications specific to the extended firmware profile
  • devel/ - Development tools and utilities (only included with DEVEL=1 flag)
  • staging/ - Disabled overlays kept for potential future use

Build Options

  • basic-devel or extended-devel - Add development overlays from overlays/devel/ to the selected profile
    • e.g. ./dev.sh make build PROFILE=extended DEVEL=1

Devel Profile Features

When running firmware built with the -devel profile, additional development tools are available:

Entware Package Manager

The Entware is considered highly untrusted component, and might be removed at any point in the future without notice.

The devel profile includes Entware support for installing additional packages. After booting the devel firmware, initialize Entware:

entware-ctrl init

This sets up the Entware environment in /userdata/extended/entware and installs the bootstrap packages.

Other entware-ctrl commands:

  • entware-ctrl start - Activate Entware (mount /opt)
  • entware-ctrl stop - Deactivate Entware (unmount /opt)
  • entware-ctrl nuke - Remove Entware installation completely

Once initialized, use opkg to install packages from the Entware repository.

Directory Structure

├── common/                          Core overlays applied to all profiles
├── devel/                           Devel overlays applied to all profiles when `-devel`
└── firmware-${profile}/             Profile-specific firmware overlays

Overlay Structure

Each overlay directory can contain:

  • patches/ - Patch files applied to extracted firmware
  • root/ - Files copied to firmware root filesystem
  • scripts/ - Build-time scripts executed during firmware build
  • pre-scripts/ - Scripts executed before main build process

Application Order

Overlays are applied in the following order:

  1. All overlays from common/ (in numeric order)
  2. Profile-specific overlays from firmware-${profile}/ (in numeric order)

Integrating Upstream Klipper Patches

The 20-klipper-patches overlay in firmware-extended/ backports upstream Klipper commits. To add new patches:

  1. Download the commit as a patch from GitHub:

    wget https://github.com/Klipper3d/klipper/commit/16fc46fe5.patch -O 01_16fc46fe5.patch

    GitHub serves any commit as a patch by appending .patch to the commit URL.

  2. Name with order prefix and commit hash:

    01_16fc46fe5.patch
02_6d1256ddc.patch
03_16b4b6b30.patch

  3. Place in the target path within the overlay:

    overlays/firmware-extended/20-klipper-patches/patches/home/lava/klipper/

    The patches/ directory maps to the firmware root, so patches/home/lava/klipper/ applies patches to /home/lava/klipper/ where Klipper is installed.

  4. Edit the patch to remove irrelevant hunks: Upstream commits often include docs/ and config changes that don't apply. Remove those hunks, keeping only the Python code changes in klippy/.

  5. Document in the overlay README: Update 20-klipper-patches/README.md with links to the upstream commits.

Project Structure

.
├── .github/                     Automated release builds
├── overlays/                    Profile overlay directories
│   ├── common/                  Core overlays for all profiles
│   ├── devel/                   Devel overlays for all profiles
│   └── firmware-${profile}/     Profile-specific firmware overlays
├── firmware/                    Downloaded and generated firmware files
├── scripts/                     Build and modification scripts
├── tmp/                         Temporary build artifacts
├── tools/                       Firmware manipulation tools
│   ├── rk2918_tools/            Rockchip image tools
│   └── upfile/                  Firmware unpacking tool
├── Makefile                     Build configuration
└── vars.mk                      Firmware version and kernel configuration

Configuration

Edit vars.mk to configure base firmware and kernel.

Extract Firmware

To extract and examine the base firmware:

./dev.sh make extract

Output: tmp/extracted/

Upgrade Firmware

To build and deploy firmware directly to a connected printer:

./dev.sh ./scripts/dev/upgrade-firmware.sh root@<printer-ip> <profile>

Example:

./dev.sh ./scripts/dev/upgrade-firmware.sh root@192.168.1.100 extended

By default, the script uses snapmaker as the SSH password. To use a different password:

PASSWORD=mypassword ./dev.sh ./scripts/dev/upgrade-firmware.sh root@192.168.1.100 extended

Release Process

The project uses GitHub Actions for automated releases:

  1. Changes pushed to main trigger a pre-release build
  2. Both basic and extended firmwares are built
  3. Version is auto-incremented using scripts/next_version.sh
  4. Release artifacts are published to GitHub Releases

Tools

rk2918_tools

  • afptool - Android firmware package tool
  • img_maker - Create Rockchip images
  • img_unpack - Unpack Rockchip images
  • mkkrnlimg - Create kernel images

upfile

Firmware unpacking utility for Snapmaker update files.