From dce11538d1235b3254faa3189a6f438ab8c01941 Mon Sep 17 00:00:00 2001 From: niklascfw Date: Sun, 12 Apr 2026 16:22:45 +0200 Subject: [PATCH] docs: README and install process for debug.ini and backup - Link DEBUG_INI.md; describe clean install backup (dbi.config, prod.keys) - Update INSTALLATION_PROCESS backup/restore steps Made-with: Cursor --- INSTALLATION_PROCESS.md | 49 +++--- README.md | 326 ++++++++++++++++++++-------------------- 2 files changed, 181 insertions(+), 194 deletions(-) diff --git a/INSTALLATION_PROCESS.md b/INSTALLATION_PROCESS.md index f7a5914..b41868a 100644 --- a/INSTALLATION_PROCESS.md +++ b/INSTALLATION_PROCESS.md @@ -2,6 +2,8 @@ This document provides a detailed, step-by-step breakdown of everything that is checked and done during the OmniNX installation/update process. +For **optional debug step skips** (`sd:/config/omninx/debug.ini`), see **[DEBUG_INI.md](DEBUG_INI.md)**. + ## Overview The OmniNX Installer Payload operates in two modes: @@ -305,17 +307,12 @@ channel_pack={variant} # Same as current_pack #### 32. Create Backup Directory - Creates `sd:/temp_backup/` directory -#### 33. Backup DBI -- **Source**: `sd:/switch/DBI/` -- **Destination**: `sd:/temp_backup/DBI/` -- Only if source exists +#### 33. Backup DBI settings +- **Source**: `sd:/switch/DBI/dbi.config` (file only, not the whole `DBI` tree) +- **Destination**: `sd:/temp_backup/dbi.config` +- Only if the source file exists -#### 34. Backup Tinfoil -- **Source**: `sd:/switch/tinfoil/` -- **Destination**: `sd:/temp_backup/tinfoil/` -- Only if source exists - -#### 35. Backup prod.keys +#### 34. Backup prod.keys - **Source**: `sd:/switch/prod.keys` - **Destination**: `sd:/temp_backup/prod.keys` - Only if source exists @@ -325,22 +322,22 @@ channel_pack={variant} # Same as current_pack ### Step 2: Wipe Directories **Location**: `install.c:543-602` -#### 36. Delete Entire Directories +#### 35. Delete Entire Directories Recursively deletes (if they exist): - `sd:/atmosphere/` (entire directory tree) - `sd:/bootloader/` (entire directory tree) - `sd:/config/` (entire directory tree) - `sd:/switch/` (entire directory tree) -#### 37. Delete Root Files +#### 36. Delete Root Files - Uses same deletion list as update mode (Step 19) - Deletes `boot.dat`, `boot.ini`, `exosphere.ini`, etc. -#### 38. Delete Miscellaneous Items +#### 37. Delete Miscellaneous Items - Uses same deletion lists as update mode (Steps 20-21) - Deletes `argon/`, `games/`, `SaltySD/`, etc. -#### 39. Recreate Switch Directory +#### 38. Recreate Switch Directory - Creates empty `sd:/switch/` directory for restoration --- @@ -348,27 +345,17 @@ Recursively deletes (if they exist): ### Step 3: Restore User Data **Location**: `backup.c:55-95` -#### 40. Restore DBI -- **Source**: `sd:/temp_backup/DBI/` -- **Destination**: `sd:/switch/DBI/` -- **Cleanup**: After restoration, deletes old DBI NRO files: - - `sd:/switch/DBI/DBI_810_EN.nro` - - `sd:/switch/DBI/DBI_810_DE.nro` - - `sd:/switch/DBI/DBI_845_EN.nro` - - `sd:/switch/DBI/DBI_845_DE.nro` - - `sd:/switch/DBI/DBI.nro` +#### 39. Restore DBI settings +- **Source**: `sd:/temp_backup/dbi.config` +- **Destination**: `sd:/switch/DBI/dbi.config` (creates `sd:/switch/DBI/` if needed) +- No longer copies the full `DBI` folder; old `.nro` cleanup is unnecessary -#### 41. Restore Tinfoil -- **Source**: `sd:/temp_backup/tinfoil/` -- **Destination**: `sd:/switch/tinfoil/` -- **Cleanup**: After restoration, deletes `sd:/switch/tinfoil/tinfoil.nro` - -#### 42. Restore prod.keys +#### 40. Restore prod.keys - **Source**: `sd:/temp_backup/prod.keys` - **Destination**: `sd:/switch/prod.keys` -#### 43. Cleanup Backup Directory -**Location**: `backup.c:98-103` +#### 41. Cleanup Backup Directory +**Location**: `backup.c` (`cleanup_backup`) - Deletes `sd:/temp_backup/` directory after restoration --- diff --git a/README.md b/README.md index 499c196..453948a 100644 --- a/README.md +++ b/README.md @@ -1,163 +1,163 @@ -# OmniNX Installer Payload - -> **To properly use this payload, download the latest OmniNX Release:** [https://git.niklascfw.de/OmniNX/OmniNX/releases](https://git.niklascfw.de/OmniNX/OmniNX/releases) - -A minimal payload for installing OmniNX CFW Pack files on Nintendo Switch outside of Horizon OS. - -Based on [TegraExplorer](https://github.com/shchmue/TegraExplorer) and [hekate](https://github.com/CTCaer/hekate) by CTCaer, naehrwert, and shchmue. -Based on [HATS-Installer-Payload](https://github.com/sthetix/HATS-Installer-Payload) by sthetix. - -## Features - -- **Automatic Variant Detection**: Detects which OmniNX pack variant is present (Standard/Light/OC) -- **Smart Installation Modes**: - - **Update Mode**: Selective deletion when OmniNX is already installed - - **Clean Install**: Full wipe with backup/restore of user data (DBI, Tinfoil, prod.keys) -- **Version Detection**: Detects installed OmniNX version via marker files (`1.0.0s`, `1.0.0l`, `1.0.0oc`) -- **Progress Display**: Visual status messages during installation -- **Error Handling**: Detailed error reporting on screen -- **Payload Chaining**: Automatically launch hekate after installation - -## Documentation - -For detailed information about the installation process, see: -- **[INSTALLATION_PROCESS.md](INSTALLATION_PROCESS.md)** - Complete step-by-step breakdown of everything checked and done during installation/update - -## Installation Modes - -### Update Mode (OmniNX Detected) -- Detected when version marker files (`1.0.0s`, `1.0.0l`, or `1.0.0oc`) are found -- Performs selective deletion of specific directories/files -- Preserves user data, savegames, and installed games -- Updates only necessary CFW components - -### Clean Install (No OmniNX Detected) -- Detected when no version marker files are found -- Performs full wipe of `/atmosphere`, `/bootloader`, `/config`, and `/switch` -- **Backs up and restores**: - - `sd:/switch/DBI` → preserved - - `sd:/switch/tinfoil` → preserved - - `sd:/switch/prod.keys` → preserved -- Fresh installation of all CFW components - -## Building - -### Prerequisites - -- **devkitARM** - ARM toolchain for Nintendo Switch development -- **BDK** - Blue Development Kit (included in this repo) - -### Build Commands - -```bash -make clean -make -``` - -The built payload will be output to `output/OmniNX-Installer.bin`. - -### CI / GitHub Actions - -Every push triggers a build. The `.bin` file is produced and attached as a workflow artifact (Actions tab → select run → Artifacts). - -## Usage - -### 1. Extract OmniNX Pack to SD Card - -Extract the OmniNX pack zip file directly to your SD card. The pack should contain one of: - -``` -sd:/OmniNX Standard/ -├── atmosphere/ -├── bootloader/ -├── config/ -├── switch/ -├── TegraExplorer/ -├── warmboot_mariko/ -├── boot.dat -├── boot.ini -├── exosphere.ini -├── hbmenu.nro -├── loader.bin -├── payload.bin -└── 1.0.0s -``` - -Or `sd:/OmniNX Light/` or `sd:/OmniNX OC/` for other variants. - -**Important**: Extract both the OmniNX pack zip AND this payload to your SD card. - -### 2. Launch Payload - -Use hekate or another bootloader to launch the payload: - -1. Place `omninx-installer.bin` in `sd:/bootloader/payloads/` -2. Launch the payload from hekate's payload menu -3. The payload will automatically: - - Detect which pack variant is present - - Detect if OmniNX is already installed - - Perform appropriate installation (update or clean) - - Launch hekate after completion - -### 3. What Happens - -1. Payload mounts the SD card -2. Detects current OmniNX installation (if any) -3. Detects which pack variant is on SD card -4. Determines installation mode (update vs clean) -5. Performs cleanup based on mode: - - **Update**: Selective deletion of specific paths - - **Clean**: Full wipe with backup/restore -6. Copies files from pack directory to SD root -7. Creates version marker file -8. Cleans up old version markers -9. Launches hekate (`sd:/bootloader/update.bin`) - -## Variant Support - -The payload supports three OmniNX variants: - -- **Standard** – `sd:/OmniNX Standard/` -- **Light** – `sd:/OmniNX Light/` -- **OC** – `sd:/OmniNX OC/` - -The payload detects the pack variant from the staging directory presence and detects the current installation (variant + version) from `sd:/config/omninx/manifest.ini` (`current_pack` and `version` keys). - -## Project Structure - -``` -OmniNX-Installer-Payload/ -├── source/ # Main source code -│ ├── main.c # Entry point and main flow -│ ├── version.c # Version/variant detection -│ ├── version.h -│ ├── install.c # Installation logic -│ ├── install.h -│ ├── backup.c # Backup/restore operations -│ ├── backup.h -│ ├── deletion_lists.h # Arrays of paths to delete -│ ├── fs.c # File system operations -│ ├── fs.h -│ ├── gfx.c # Graphics utilities -│ ├── gfx.h -│ ├── nx_sd.c # SD card operations -│ ├── nx_sd.h -│ ├── link.ld # Linker script -│ └── start.S # Startup assembly -├── bdk/ # Blue Development Kit -├── Makefile # Build configuration -├── VERSION # Version file -└── README.md # This file -``` - -## License - -This project is based on TegraExplorer and hekate. Please refer to those projects for their respective licenses. - -## Credits - -- **CTCaer** - [hekate](https://github.com/CTCaer/hekate) -- **naehrwert** - Tegra exploration work -- **shchmue** - [TegraExplorer](https://github.com/shchmue/TegraExplorer) -- **sthetix** - [HATS-Installer-Payload](https://github.com/sthetix/HATS-Installer-Payload) (inspiration and base structure) -- **Woody2408** - OmniNX CFW Pack creator +# OmniNX Installer Payload + +> **To properly use this payload, download the latest OmniNX Release:** [https://git.niklascfw.de/OmniNX/OmniNX/releases](https://git.niklascfw.de/OmniNX/OmniNX/releases) + +A minimal payload for installing OmniNX CFW Pack files on Nintendo Switch outside of Horizon OS. + +Based on [TegraExplorer](https://github.com/shchmue/TegraExplorer) and [hekate](https://github.com/CTCaer/hekate) by CTCaer, naehrwert, and shchmue. +Based on [HATS-Installer-Payload](https://github.com/sthetix/HATS-Installer-Payload) by sthetix. + +## Features + +- **Automatic Variant Detection**: Detects which OmniNX pack variant is present (Standard/Light/OC) +- **Smart Installation Modes**: + - **Update Mode**: Selective deletion when OmniNX is already installed + - **Clean Install**: Full wipe with backup/restore of user data (DBI `dbi.config`, prod.keys) +- **Version Detection**: Detects installed OmniNX version via marker files (`1.0.0s`, `1.0.0l`, `1.0.0oc`) +- **Progress Display**: Visual status messages during installation +- **Error Handling**: Detailed error reporting on screen +- **Payload Chaining**: Automatically launch hekate after installation + +## Documentation + +For detailed information about the installation process, see: +- **[INSTALLATION_PROCESS.md](INSTALLATION_PROCESS.md)** - Complete step-by-step breakdown of everything checked and done during installation/update +- **[DEBUG_INI.md](DEBUG_INI.md)** - Optional `sd:/config/omninx/debug.ini` parameters to skip install steps (for testing) + +## Installation Modes + +### Update Mode (OmniNX Detected) +- Detected when version marker files (`1.0.0s`, `1.0.0l`, or `1.0.0oc`) are found +- Performs selective deletion of specific directories/files +- Preserves user data, savegames, and installed games +- Updates only necessary CFW components + +### Clean Install (No OmniNX Detected) +- Detected when no version marker files are found +- Performs full wipe of `/atmosphere`, `/bootloader`, `/config`, and `/switch` +- **Backs up and restores**: + - `sd:/switch/DBI/dbi.config` → preserved (not the whole `DBI` folder) + - `sd:/switch/prod.keys` → preserved +- Fresh installation of all CFW components + +## Building + +### Prerequisites + +- **devkitARM** - ARM toolchain for Nintendo Switch development +- **BDK** - Blue Development Kit (included in this repo) + +### Build Commands + +```bash +make clean +make +``` + +The built payload will be output to `output/OmniNX-Installer.bin`. + +### CI / GitHub Actions + +Every push triggers a build. The `.bin` file is produced and attached as a workflow artifact (Actions tab → select run → Artifacts). + +## Usage + +### 1. Extract OmniNX Pack to SD Card + +Extract the OmniNX pack zip file directly to your SD card. The pack should contain one of: + +``` +sd:/OmniNX Standard/ +├── atmosphere/ +├── bootloader/ +├── config/ +├── switch/ +├── TegraExplorer/ +├── warmboot_mariko/ +├── boot.dat +├── boot.ini +├── exosphere.ini +├── hbmenu.nro +├── loader.bin +├── payload.bin +└── 1.0.0s +``` + +Or `sd:/OmniNX Light/` or `sd:/OmniNX OC/` for other variants. + +**Important**: Extract both the OmniNX pack zip AND this payload to your SD card. + +### 2. Launch Payload + +Use hekate or another bootloader to launch the payload: + +1. Place `omninx-installer.bin` in `sd:/bootloader/payloads/` +2. Launch the payload from hekate's payload menu +3. The payload will automatically: + - Detect which pack variant is present + - Detect if OmniNX is already installed + - Perform appropriate installation (update or clean) + - Launch hekate after completion + +### 3. What Happens + +1. Payload mounts the SD card +2. Detects current OmniNX installation (if any) +3. Detects which pack variant is on SD card +4. Determines installation mode (update vs clean) +5. Performs cleanup based on mode: + - **Update**: Selective deletion of specific paths + - **Clean**: Full wipe with backup/restore +6. Copies files from pack directory to SD root +7. Creates version marker file +8. Cleans up old version markers +9. Launches hekate (`sd:/bootloader/update.bin`) + +## Variant Support + +The payload supports three OmniNX variants: + +- **Standard** – `sd:/OmniNX Standard/` +- **Light** – `sd:/OmniNX Light/` +- **OC** – `sd:/OmniNX OC/` + +The payload detects the pack variant from the staging directory presence and detects the current installation (variant + version) from `sd:/config/omninx/manifest.ini` (`current_pack` and `version` keys). + +## Project Structure + +``` +OmniNX-Installer-Payload/ +├── source/ # Main source code +│ ├── main.c # Entry point and main flow +│ ├── version.c # Version/variant detection +│ ├── version.h +│ ├── install.c # Installation logic +│ ├── install.h +│ ├── backup.c # Backup/restore operations +│ ├── backup.h +│ ├── deletion_lists.h # Arrays of paths to delete +│ ├── fs.c # File system operations +│ ├── fs.h +│ ├── gfx.c # Graphics utilities +│ ├── gfx.h +│ ├── nx_sd.c # SD card operations +│ ├── nx_sd.h +│ ├── link.ld # Linker script +│ └── start.S # Startup assembly +├── bdk/ # Blue Development Kit +├── Makefile # Build configuration +├── VERSION # Version file +└── README.md # This file +``` + +## License + +This project is based on TegraExplorer and hekate. Please refer to those projects for their respective licenses. + +## Credits + +- **CTCaer** - [hekate](https://github.com/CTCaer/hekate) +- **naehrwert** - Tegra exploration work +- **shchmue** - [TegraExplorer](https://github.com/shchmue/TegraExplorer) +- **sthetix** - [HATS-Installer-Payload](https://github.com/sthetix/HATS-Installer-Payload) (inspiration and base structure) +- **Woody2408** - OmniNX CFW Pack creator