Custom Snapmaker U1 Firmware

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:

All overlays from common/ (in numeric order)
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:

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.

Name with order prefix and commit hash:

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

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.
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/.
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/

Release Process

The project uses GitHub Actions for automated releases:

Changes pushed to main trigger a pre-release build
Both basic and extended firmwares are built
Version is auto-incremented using scripts/next_version.sh
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.