147 lines
6.8 KiB
Markdown
147 lines
6.8 KiB
Markdown
# OpenKE Stock USB Installer & Firmware Workspace
|
|
|
|
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.
|
|
|
|
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`](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
|
|
./build_openke_image.sh --target ke
|
|
```
|
|
|
|
Build for **Nebula Pad**:
|
|
```bash
|
|
./build_openke_image.sh --target nebula
|
|
```
|
|
|
|
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/
|
|
├── 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
|
|
```
|