switch-nix

NixOS configuration for a Nintendo Switch Lite (Mariko / Tegra T214) running alongside Atmosphère CFW as a dual-boot setup via hekate.

Status: Work in progress. All source hashes are pinned. CI builds and publishes releases automatically on every push to main.

---

Prerequisites

Requirement	Notes
Switch Lite with mod chip	HWFLY, SX Core, etc.
Atmosphère + hekate ≥ 6.0.6	Already installed
microSD card ≥ 32 GB	Recommended: 128 GB U3/A2 class

No Ubuntu required. The bootstack (bl31.bin, bl33.bin, boot.scr) is vendored in this repo and included in every release.

---

1. Partition your SD card

You need at minimum:

Partition	Filesystem	Purpose
p1	FAT32	Atmosphère, hekate, bootstack
p2	ext4	NixOS root
p3	linux-swap (optional)	Swap

Create from your PC:

parted /dev/sdX mkpart primary fat32 1MiB 6GiB
parted /dev/sdX mkpart primary ext4 6GiB 54GiB
parted /dev/sdX mkpart primary linux-swap 54GiB 58GiB
mkfs.fat -F32 -n ATMOS /dev/sdXp1
mkfs.ext4 -L nixos /dev/sdXp2
mkswap -L swap /dev/sdXp3

Also run Nyx Options → Dump Joy-Con BT in hekate (required even on Switch Lite — dumps factory touch/IMU calibration).

---

2. Get the build artifacts

Download the latest release from the Releases page.

File	Purpose
uImage	Kernel (U-Boot wrapped)
initramfs	NixOS initrd (U-Boot wrapped)
nx-plat.dtimg	DTB image for all Switch variants
bl31.bin	ARM Trusted Firmware
bl33.bin	U-Boot
boot.scr	U-Boot boot script
nixos-rootfs.tar.zst / .tar.zst.part*	Full NixOS root closure
hekate_ipl.ini.snippet	hekate boot entry

---

3. Deploy to the SD card

Run all commands on your PC:

sudo mount /dev/sdXp1 /mnt/fat32
sudo mount /dev/sdXp2 /mnt/nixos

# Copy bootstack
sudo mkdir -p /mnt/fat32/switchroot/nixos
sudo cp uImage initramfs nx-plat.dtimg bl31.bin bl33.bin boot.scr /mnt/fat32/switchroot/nixos/

# Add hekate boot entry
sudo mkdir -p /mnt/fat32/bootloader/ini
sudo cp hekate_ipl.ini.snippet /mnt/fat32/bootloader/ini/nixos.ini

# Extract NixOS rootfs (reassemble parts if split)
cat nixos-rootfs.tar.zst.part* | sudo tar --zstd -xf - -C /mnt/nixos --numeric-owner
# If single file:
# sudo tar --zstd -xf nixos-rootfs.tar.zst -C /mnt/nixos --numeric-owner

sudo umount /mnt/fat32 /mnt/nixos

---

4. Boot

In hekate → More Configs → NixOS.

---

Building locally

If you want to build from source instead of using CI artifacts:

# Full NixOS system
nix build .#nixosConfigurations.switch-lite.config.system.build.toplevel

# Kernel only (uImage + DTBs)
nix build .#packages.aarch64-linux.kernel

Requires Nix ≥ 2.18 with flakes enabled.

Updating kernel source pins

All 8 kernel source repos are pinned to specific commit SHAs in modules/l4t-kernel.nix. To update a pin:

nix run nixpkgs#nix-prefetch-github -- <owner> <repo> --rev <new-sha>
nix run nixpkgs#nix-prefetch-git -- <url> --rev refs/heads/<branch>

Then replace the rev + hash fields in modules/l4t-kernel.nix.

---

Known limitations (Mariko / T214)

Feature	Status
Display (internal 1280×720)	Works via tegra-fb / modesetting
Touch screen	Works (HID driver)
Joy-Con rails	Works (hid_nintendo)
Wi-Fi (BCM4354)	Works; may need nvs calibration file from HOS
Bluetooth	Partial (BCM4354 BT); pairing works, LE may be flaky
Audio (speakers + headphone)	Partial – ADSP firmware required
USB-C (data/charging)	USB host works; USB-PD negotiation untested
GPU acceleration (GNOME/Wayland)	Partial – Mesa tegra Gallium; no Vulkan
Suspend / resume	Not working in mainline L4T
HDMI dock output	Not applicable (Switch Lite has no dock connector)

---

Directory structure

switch-nix/
├── .github/workflows/build.yml  # GH Actions CI – builds and publishes releases
├── flake.nix                    # Flake entry point, cross-compilation setup
├── flake.lock                   # Pinned nixpkgs (generated by nix flake lock)
├── configuration.nix            # systemd + GNOME + SSH + networking
├── hardware-configuration.nix   # Tegra T214 hardware, SD card layout
├── modules/
│   └── l4t-kernel.nix           # Custom L4T 4.9 kernel derivation
└── README.md                    # This file

---

References

• Switchroot wiki – L4T Ubuntu install guide
• theofficialgman/l4t-kernel-build-scripts
• theofficialgman/switch-l4t-kernel-4.9
• Switchroot GitLab
• hekate releases