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

2026-09-24 00:16:18 +00:00
parent c0dd058ae7
commit 6a43841867
17 changed files with 1218 additions and 1132 deletions
@@ -0,0 +1,86 @@
+# Hardware Partition Layout & Dual-Slot A/B Boot Model
+
+This document details the eMMC physical partition layout, the hardware A/B slot mechanics, and the persistent storage architecture used by Creality X2000 devices (Ender-3 V3 KE and Nebula Pad).
+
+---
+
+## 1. Physical Partition Table
+
+The onboard eMMC is partitioned with a standard GPT partition table:
+
+| Partition | Label | Fixed Capacity | Mount / Role | Active Slot 1 (Stock) | Active Slot 2 (OpenKE) |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `/dev/mmcblk0p1` | `ota` | **1 MiB** | Boot marker storage | Stores `ota:kernel` or `ota:kernel2` | Shared |
+| `/dev/mmcblk0p2` | `sn_mac` | **1 MiB** | Factory serial & MAC addresses | Read-only identity | Shared |
+| `/dev/mmcblk0p3` | `rtos` | **4 MiB** | Aux RTOS firmware (Slot 1) | Active | Inactive |
+| `/dev/mmcblk0p4` | `rtos2` | **4 MiB** | Aux RTOS firmware (Slot 2) | Inactive | Active |
+| `/dev/mmcblk0p5` | `kernel` | **8 MiB** | Linux uImage (Slot 1) | Active | Inactive |
+| `/dev/mmcblk0p6` | `kernel2` | **8 MiB** | Linux uImage (Slot 2) | Inactive | Active |
+| `/dev/mmcblk0p7` | `rootfs` | **500 MiB** | SquashFS rootfs (Slot 1) | Active | Inactive |
+| `/dev/mmcblk0p8` | `rootfs2` | **500 MiB** | SquashFS rootfs (Slot 2) | Inactive | Active |
+| `/dev/mmcblk0p9` | `rootfs_data` | **300 MiB** | Ext4 writable overlay | `/overlay` | `/overlay` |
+| `/dev/mmcblk0p10` | `userdata` | **~6.1 GiB** | Ext4 persistent storage | Mounted at `/usr/data` | Mounted at `/usr/data` |
+
+---
+
+## 2. Boot Selection via the OTA Marker
+
+The bootloader (U-Boot) reads the 1 MiB `ota` partition (`/dev/mmcblk0p1`) on power-up to decide which kernel and rootfs to mount. The partition contains a simple ASCII string:
+
+* `ota:kernel` $\rightarrow$ Boots **Slot 1** (Stock CrealityOS: kernel `p5`, rootfs `p7`).
+* `ota:kernel2` $\rightarrow$ Boots **Slot 2** (Custom / OpenKE: kernel `p6`, rootfs `p8`).
+
+### How Stock OTA Updater Flashes to Slot 2
+
+When you run a USB update from the stock Creality touchscreen:
+1. Stock firmware queries which slot is currently running (`local_get_kernel_dev_path`).
+2. Since the printer is running on Slot 1 (`ota:kernel`), the updater targets the **inactive** slot:
+   - Flashes `xImage` to `kernel2` (`mmcblk0p6`).
+   - Flashes `rootfs.squashfs` to `rootfs2` (`mmcblk0p8`).
+   - Flashes `zero.bin` to `rtos2` (`mmcblk0p4`).
+3. Calls `local_set_next_boot_device`, which writes `ota:kernel2` into `mmcblk0p1`.
+4. Reboots into OpenKE.
+
+> [!NOTE]
+> Stock firmware in Slot 1 (`mmcblk0p5` and `mmcblk0p7`) is **never overwritten** by this process.
+
+---
+
+## 3. Persistent Data Isolation (`/usr/data`)
+
+`/dev/mmcblk0p10` is the single shared ~6.1 GiB persistent partition mounted at `/usr/data`. Both Slot 1 and Slot 2 share this partition, but they use strict directory separation:
+
+```
+/usr/data/
+├── creality/            # Stock CrealityOS files (gcode, logs, userdata, factory data)
+│   ├── userdata/
+│   └── printer_data/
+└── openke/              # OpenKE isolated runtime
+    ├── apps/            # Mutable checkouts (klipper, moonraker, mainsail)
+    ├── envs/            # Python virtual environments
+    ├── system/          # Boot logs, activation state, machine configs
+    └── printer_data/    # Klipper config (printer.cfg), macros, Moonraker DB
+```
+
+Because OpenKE namespaces all its data under `/usr/data/openke/`, flashing OpenKE does not erase or corrupt stock print history, WiFi credentials, or factory calibration files.
+
+---
+
+## 4. Reverting to Stock Firmware
+
+If you ever wish to return to stock CrealityOS, you do not need to reflash. You simply toggle the boot marker back to Slot 1:
+
+### From OpenKE Shell (SSH)
+```bash
+echo -n "ota:kernel" > /dev/mmcblk0p1
+sync
+reboot
+```
+
+### From Stock CrealityOS (if toggling forward again)
+```bash
+. /etc/ota_bin/ota_utils.sh
+. /etc/ota_bin/ota_local_method.sh
+local_set_next_boot_device
+reboot
+```