OmniNX Installer Payload

To properly use this payload, download the latest OmniNX Release: 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 and hekate by CTCaer, naehrwert, and shchmue.
Based on 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:

• docs/INSTALLATION_PROCESS.md - Complete step-by-step breakdown of everything checked and done during installation/update
• docs/DEBUG_INI.md - Optional sd:/config/omninx/debug.ini parameters to skip install steps (for testing)
• docs/PRESERVE_INI.md - Optional sd:/config/omninx/preserve.ini to skip deleting chosen paths in update mode

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
• Optional sd:/config/omninx/preserve.ini: user-listed sd:/… paths (with =1) are excluded from that cleanup (see PRESERVE_INI.md)
• 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

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 OmniNX-shipped paths (user-installed apps and sysmodules stay)
   • Clean: Selective wipe with backup/restore of user data
6. Moves files from the pack directory to the SD root (same card, so no copying)
7. Applies extras (RAM / Hekate-Pro choice) and removes the pack directory
8. Launches hekate (sd:/bootloader/update.bin)

Details: INSTALLATION_PROCESS.md. Test runs can write a log via debug.ini (log=1).

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/                     # Payload source
│   ├── main.c                  # Entry point, detection, confirmation, launch
│   ├── install.c / install.h   # Install flow, progress lines, menus, extras, preserve/debug ini
│   ├── install_update.c        # Update mode: cleanup + move pack files
│   ├── install_clean.c         # Clean mode: backup, wipe, restore
│   ├── deletion_lists_update.h # Paths removed in update mode
│   ├── deletion_lists_clean.h  # Paths removed in clean mode
│   ├── backup.c / backup.h     # User data + HorizonOC config backup/restore
│   ├── fs.c / fs.h             # Delete/move/copy trees, logging
│   ├── version.c / version.h   # Installation + pack variant detection
│   ├── gfx.c / gfx.h           # Console graphics
│   ├── nx_sd.c / nx_sd.h       # SD card mount
│   ├── screenshot.c            # Capture button screenshots
│   ├── link.ld                 # Linker script
│   └── start.S                 # Startup assembly
├── bdk/                        # Blue Development Kit
├── desktop/                    # Windows desktop installer (C#)
├── tools/                      # Deletion list generator/audit, RAM test payload
├── docs/                       # Installation process, debug.ini, preserve.ini
├── 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
• naehrwert - Tegra exploration work
• shchmue - TegraExplorer
• sthetix - HATS-Installer-Payload (inspiration and base structure)
• Woody2408 - OmniNX CFW Pack creator