# 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/
├── 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
```