A standalone utility to package OpenKE (Linux 6.6-rt + Klipper/Moonraker/GuppyScreen) directly into stock CrealityOS-supported OTA update (.img) containers.

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.

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`
Creality Nebula Pad	`NEBULA`	`NEBULA_ota_img_V1.1.0.30.img`	`build/NEBULA_ota_img_V1.1.0.34.img`

Quick Start
Flashing Guide
Safety & Dual-Slot A/B Architecture
Technical Documentation Index
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):

./build_openke_image.sh --target ke

Build for Nebula Pad:

./build_openke_image.sh --target nebula

Build for Both Devices in One Run:

./build_openke_image.sh --target all

By default, the script automatically:

Locates OpenKE build artifacts in ../OpenKE/artifacts/buildroot-halley5-v30-image/.
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).
Verifies SHA256 checksums against build-manifest.txt (if present).
Slices payloads into 1 MiB chunks with Creality MD5 sidecars.
Encrypts the 7z container with the board-derived Creality key ($1$cxswfile$...).
Verifies archive integrity and outputs the .img to build/.

Custom Arguments & CLI Flags

# 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

Format a USB flash drive as FAT32 with an MBR (Master Boot Record) partition table.
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
Insert the USB drive into the front USB port of the printer / Nebula Pad.
On the touchscreen: Navigate to Settings \rightarrow Firmware Update \rightarrow Local Update.
Select the firmware image and confirm the update.
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.
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:
```
# 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: 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: Physical partition table, partition capacities, bootloader marker mechanics, and /usr/data namespace isolation.
Troubleshooting & Diagnostics: Common USB update pitfalls, drive formatting, version string parsing, and how to inspect live updater logs on the device.
Firmware Notes: Official baselines, derived encryption keys, partition budgets, and tool usage notes.
Firmware Changelog: Project history from DarKE v0.0.1 pre-root to OpenKE USB Installer v1.0.0.

5. Repository Structure

DarKE/
├── Ender-3_V3_KE_F005_ota_img_V1.1.0.17.img  # Stock CrealityOS baseline for Ender-3 V3 KE (F005)
├── NEBULA_ota_img_V1.1.0.30.img              # Stock CrealityOS baseline for Nebula Pad (NEBULA)
├── 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

README.md

OpenKE Stock USB Installer & Firmware Workspace