Dark98/DarKE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Transform workspace into OpenKE Stock USB Installer generator (v1.0.0)

Browse Source
This commit is contained in:
Dark98
2026-09-24 00:16:18 +00:00
parent c0dd058ae7
commit 6a43841867
17 changed files with 1218 additions and 1132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+136 -41
View File
@@ -1,49 +1,144 @@
# Ender-3 V3 KE firmware workspace
This repo contains a stock KE firmware image, a small overlay tree of our changes, and a helper script for rebuilding an `.img` package.
## Files
# OpenKE Stock USB Installer & Firmware Workspace
- `FIRMWARE_NOTES.md`: archive password and firmware layout notes
- `tools/ke_firmware.py`: extract/rebuild helper
- `requirements.txt`: Python dependency list for the helper script
A standalone utility to package **[OpenKE](https://github.com/coreflake1/OpenKE)** (Linux 6.6-rt + Klipper/Moonraker/GuppyScreen) directly into stock CrealityOS-supported OTA update (`.img`) containers.
## Python setup
This enables a **zero-disassembly, single-USB installation of OpenKE straight from an unmodified stock printer or Nebula Pad touchscreen** without requiring Ingenic mask-ROM recovery mode, cloner utilities, or prior root access.
Install the helper dependency with:
---
## Supported Hardware
| Device | Board Identifier | Official Stock Baseline | Generated OTA Installer Package |
| :--- | :--- | :--- | :--- |
| **Creality Ender-3 V3 KE** | `F005` | `Ender-3_V3_KE_F005_ota_img_V1.1.0.17.img` | [`build/Ender-3_V3_KE_F005_ota_img_V1.1.0.34.img`](build/Ender-3_V3_KE_F005_ota_img_V1.1.0.34.img) |
| **Creality Nebula Pad** | `NEBULA` | `NEBULA_ota_img_V1.1.0.30.img` | [`build/NEBULA_ota_img_V1.1.0.34.img`](build/NEBULA_ota_img_V1.1.0.34.img) |
---
## Table of Contents
1. [Quick Start](#1-quick-start)
2. [Flashing Guide](#2-flashing-guide)
3. [Safety & Dual-Slot A/B Architecture](#3-safety--dual-slot-ab-architecture)
4. [Technical Documentation Index](#4-technical-documentation-index)
5. [Repository Structure](#5-repository-structure)
---
## 1. Quick Start
### Prerequisites
* Linux, macOS, or Windows
* Python 3.8+
* `7z` (p7zip) or Python `py7zr` (`pip install -r requirements.txt`)
### Generate Installer Images
Build for **Ender-3 V3 KE** (default):
```bash
pip install -r requirements.txt
./build_openke_image.sh --target ke
```
On Linux, install `squashfs-tools-ng` so `gensquashfs` and `rdsquashfs` are
available on `PATH`. On Windows, the helper uses the bundled `.exe` tools.
Build for **Nebula Pad**:
```bash
./build_openke_image.sh --target nebula
```
## Rebuild flow
```powershell
python .\tools\ke_firmware.py build --stock-archive .\Ender-3_V3_KE_F005_ota_img_V1.1.0.17.img --overlay-dir .\overlay_rootfs --output .\build\DarKE_KE_F005_ota_img_V11034.img
```
If the stock archive is missing, pass `--stock-url` and the helper will download it before extracting.
If your `C:` drive is tight, point `--build-dir` at a larger drive so the stock rootfs can be unpacked there.
The build step downloads or reuses the stock archive, extracts it, overlays `overlay_rootfs/`, rebuilds the root filesystem with the Windows `squashfs-tools-ng` binaries, and repacks the Creality image envelope with `py7zr`.
The rebuild is metadata-preserving, so stock symlinks and executable bits survive the round trip.
## Compare flow
```powershell
python .\tools\ke_firmware.py compare --stock-archive .\Ender-3_V3_KE_F005_ota_img_V1.1.0.17.img --rebuilt-archive .\build\DarKE_KE_F005_ota_img_V11034.img --overlay-dir .\overlay_rootfs
```
Use this after a build to confirm the rebuilt rootfs still matches stock everywhere except the overlayed files.
## Stock flash flow
1. Copy the generated `.img` to a USB drive.
2. Insert the USB drive into the Ender-3 V3 KE.
3. Use the built-in updater to flash the image.
4. After reboot, the firmware reports the UI/display version from the package metadata.
This flow does not require manual edits on the printer itself.
Build for **Both Devices in One Run**:
```bash
./build_openke_image.sh --target all
```
By default, the script automatically:
1. Locates OpenKE build artifacts in `../OpenKE/artifacts/buildroot-halley5-v30-image/`.
2. Validates partition budgets:
- `xImage`: 5.54 MiB / 8 MiB (66.1% capacity, 2.71 MiB free).
- `rootfs.squashfs`: 330.85 MiB / 500 MiB (66.2% capacity, 169.15 MiB free).
3. Verifies SHA256 checksums against `build-manifest.txt` (if present).
4. Slices payloads into 1 MiB chunks with Creality MD5 sidecars.
5. Encrypts the 7z container with the board-derived Creality key (`$1$cxswfile$...`).
6. Verifies archive integrity and outputs the `.img` to `build/`.
### Custom Arguments & CLI Flags
```bash
# Custom artifacts directory and custom version
./build_openke_image.sh --target nebula --artifacts /path/to/artifacts --version 1.1.0.35
# Or invoke the Python packager directly
python3 tools/pack_openke.py --target nebula --artifacts-dir ../OpenKE/artifacts/buildroot-halley5-v30-image
```
---
## 2. Flashing Guide
1. Format a USB flash drive as **FAT32** with an **MBR** (Master Boot Record) partition table.
2. Copy the generated `.img` file to the **root** of the USB drive:
- For Ender-3 V3 KE: `Ender-3_V3_KE_F005_ota_img_V1.1.0.34.img`
- For Nebula Pad: `NEBULA_ota_img_V1.1.0.34.img`
3. Insert the USB drive into the front USB port of the printer / Nebula Pad.
4. On the touchscreen: Navigate to **Settings** $\rightarrow$ **Firmware Update** $\rightarrow$ **Local Update**.
5. Select the firmware image and confirm the update.
6. The stock updater will:
- Flash `xImage` to `kernel2` (`/dev/mmcblk0p6`).
- Flash `rootfs.squashfs` to `rootfs2` (`/dev/mmcblk0p8`).
- Flash `zero.bin` to `rtos2` (`/dev/mmcblk0p4`).
- Set the bootloader marker in `/dev/mmcblk0p1` to `ota:kernel2`.
- Automatically reboot into OpenKE.
7. On first boot, OpenKE seeds `/usr/data/openke/` and starts Klipper, Moonraker, and GuppyScreen.
---
## 3. Safety & Dual-Slot A/B Architecture
* **Non-Destructive Install**: The stock CrealityOS operating system resides permanently in **Slot 1** (`mmcblk0p5`/`p7`) and is **never overwritten**. OpenKE is installed cleanly into **Slot 2** (`mmcblk0p6`/`p8`).
* **Persistent Data Isolation**: Both operating systems share `/usr/data`, but OpenKE isolates its entire runtime in `/usr/data/openke/`. Stock Creality configs (`/usr/data/creality/`), printer calibrations, and WiFi credentials remain completely untouched.
* **Instant Reversion to Stock**: If you ever want to revert to stock CrealityOS, simply toggle the boot marker back to Slot 1:
```bash
# From OpenKE SSH shell:
echo -n "ota:kernel" > /dev/mmcblk0p1 && sync && reboot
```
---
## 4. Technical Documentation Index
For in-depth architectural and developer documentation:
* **[Creality OTA Packaging Specification](docs/CREALITY_OTA_SPECIFICATION.md)**:
Full reverse-engineered specification of Creality's 7z container, MD5-crypt key derivation, 1 MiB payload chunking, manifest formats, and updater execution flow.
* **[Hardware A/B Partition Model](docs/A_B_PARTITION_MODEL.md)**:
Physical partition table, partition capacities, bootloader marker mechanics, and `/usr/data` namespace isolation.
* **[Troubleshooting & Diagnostics](docs/TROUBLESHOOTING.md)**:
Common USB update pitfalls, drive formatting, version string parsing, and how to inspect live updater logs on the device.
* **[Firmware Notes](FIRMWARE_NOTES.md)**:
Official baselines, derived encryption keys, partition budgets, and tool usage notes.
* **[Firmware Changelog](FIRMWARE_CHANGELOG.md)**:
Project history from DarKE v0.0.1 pre-root to OpenKE USB Installer v1.0.0.
---
## 5. Repository Structure
```
DarKE/
├── build_openke_image.sh # Automated build wrapper script
├── README.md # Workspace overview & quickstart
├── FIRMWARE_NOTES.md # Architecture notes & encryption keys
├── FIRMWARE_CHANGELOG.md # Version changelog & release milestones
├── requirements.txt # Python dependencies (`py7zr`)
├── assets/ # Standalone RTOS binaries
│ ├── zero.bin # Stock RTOS for Ender-3 V3 KE (F005)
│ └── zero_nebula.bin # Stock RTOS for Nebula Pad (NEBULA)
├── docs/ # In-depth technical documentation
│ ├── CREALITY_OTA_SPECIFICATION.md # Creality OTA container & updater internals
│ ├── A_B_PARTITION_MODEL.md # GPT partition layout & slot mechanics
│ └── TROUBLESHOOTING.md # USB diagnostics & common issues
├── tools/
│ └── pack_openke.py # OpenKE stock OTA packager
└── build/ # Generated OTA installer images
├── Ender-3_V3_KE_F005_ota_img_V1.1.0.34.img
└── NEBULA_ota_img_V1.1.0.34.img
```