r36s-darkos-upgrade-macos

name	r36s-darkos-upgrade-macos
description	Install or upgrade dArkOSRE-R36 on an Anbernic R36S handheld from macOS. Use when a user wants to flash dArkOS/dArkOSRE, identify their R36S panel, fix black-screen-on-boot issues, write to ext4 partitions from macOS, or clone/back up their stock SD card before flashing. Covers u-boot bootloader preservation, DTB panel matching, fstab fixes, and ROM migration.
license	MIT
compatibility	claude-code opencode
allowed-tools	["Bash","Read","Write","Edit","AskUserQuestion"]

R36S → dArkOSRE-R36 Upgrade (macOS)

A field-tested guide for flashing dArkOSRE-R36 onto an Anbernic R36S from a Mac. Most community guides assume Windows/Linux — this fills the macOS gap, including the parts that will brick-screen you if you skip them.

When to use this skill

Invoke when the user:

• Just received an R36S and wants to move off stock firmware
• Is trying to install dArkOS / dArkOSRE and getting a black screen with green LED
• Needs to identify which panel their R36S has
• Wants to back up their stock SD card before flashing
• Is on macOS and stuck because guides assume dd on Linux or Rufus on Windows

Prerequisites

brew install e2fsprogs dtc p7zip coreutils

• e2fsprogs → debugfs for writing to ext4 from macOS
• dtc → decompile DTB files to identify your panel
• p7zip → extract .7z dArkOS images
• coreutils → GNU dd with progress

Also: a USB SD card reader, and ~60GB free disk space for backups.

Step 1 — Back up the stock card (non-negotiable)

Insert the stock SD card. Identify it:

diskutil list

Look for the disk showing BOOT + Linux + EASYROMS partitions. Assume it's /dev/disk4 below — verify yours.

Unmount (don't eject):

diskutil unmountDisk /dev/disk4

Back up each partition and the u-boot region. The u-boot part is the one everyone forgets:

# MBR / partition table
sudo dd if=/dev/rdisk4 of=mbr.img bs=512 count=1

# u-boot bootloader (sectors 1-32767, between MBR and first partition)
# THIS IS CRITICAL — without it you get black screen + green LED
sudo dd if=/dev/rdisk4 of=uboot.img bs=512 skip=1 count=32767

# BOOT partition (usually p1)
sudo dd if=/dev/rdisk4s1 bs=4m | gzip > boot_partition.img.gz

# Linux partition (usually p2)
sudo dd if=/dev/rdisk4s2 bs=4m | gzip > linux_partition.img.gz

# ROMs — just copy the files, don't image the partition
mkdir roms_backup
cp -a /Volumes/EASYROMS/roms/* roms_backup/

Keep uboot.img safe. You will need it.

Step 2 — Identify your panel

Mount the BOOT partition and find the active DTB:

ls /Volumes/BOOT/*.dtb

Decompile the one the device is actually using (usually gameconsole-r36s.dtb):

dtc -I dtb -O dts /Volumes/BOOT/gameconsole-r36s.dtb -o panel.dts
grep -A5 "panel-init-sequence\|compatible.*kd35\|compatible.*st7" panel.dts

Match the compatible string and init sequence against the R36S Device Pack (community-maintained, search "R36S Device Pack southoz"). Common panels:

Board rev	Panel	Compatible string
R36S-V12 2023-08-18 Panel 0	various	varies
R36S-V12 2023-08-18 Panel 4	elida,kd35t133	elida,kd35t133

Write down your panel number. You'll need it for DTB selection.

Step 3 — Download dArkOSRE-R36

Grab the latest build from southoz's Mega link (check r/SBCGaming or the dArkOS Discord for the current URL — do not hardcode). Example filename: dArkOSRE_R36_trixie_03082026.7z.

7z x dArkOSRE_R36_trixie_03082026.7z

You'll get a .img file ~4GB.

Step 4 — Flash the image

Unmount the target card:

diskutil unmountDisk /dev/disk4

Flash with progress:

sudo gdd if=dArkOSRE_R36_trixie_03082026.img of=/dev/rdisk4 bs=4M status=progress conv=fsync

Do NOT eject yet.

Step 5 — The four fixes that make it actually boot

After flashing, macOS will mount BOOT. Now apply the fixes that dArkOSRE's default image misses for most R36S units:

Fix 1 — Restore your u-boot

dArkOSRE's bundled u-boot doesn't drive many R36S panels. Overwrite it with the one from your backup:

diskutil unmountDisk /dev/disk4
sudo dd if=uboot.img of=/dev/rdisk4 bs=512 seek=1 count=32767 conv=notrunc

Fix 2 — Install the correct panel DTB

From the R36S Device Pack, copy your panel's DTB to BOOT and rename it so u-boot picks it up:

# Delete ALL existing .dtb files on BOOT first — they will shadow yours
rm /Volumes/BOOT/*.dtb

# Copy your panel's DTB (example: Panel 4)
cp "DevicePack/Panel4/rg351mp-uboot.dtb" /Volumes/BOOT/rg351v-uboot.dtb

The rename from rg351mp-uboot.dtb → rg351v-uboot.dtb is required — u-boot looks for the rg351v name.

Fix 3 — Fix /etc/fstab on the Linux partition

dArkOSRE ships with ntfs-3g for the ROMs partition but the R36S uses exFAT. You must edit ext4 from macOS using debugfs:

diskutil unmountDisk /dev/disk4

# Dump current fstab
sudo debugfs /dev/rdisk4s2 -R "dump /etc/fstab /tmp/fstab.orig"

# Edit
sed 's/ntfs-3g/exfat/g' /tmp/fstab.orig > /tmp/fstab.new

# Write back
sudo debugfs -w /dev/rdisk4s2 -R "rm /etc/fstab"
sudo debugfs -w /dev/rdisk4s2 -R "write /tmp/fstab.new /etc/fstab"

Fix 4 — Skip the panel chooser (optional but recommended)

If the image has a MultiPanel picker that runs on boot, skip it:

touch /Volumes/BOOT/nopanelchooser

Also delete any firstboot scripts that would try to reformat your ROMs partition:

rm -f /Volumes/BOOT/firstboot.sh /Volumes/BOOT/expandtoexfat.sh

Exception: if this is a completely fresh flash and you want the EASYROMS partition auto-expanded to fill the card, LEAVE firstboot.sh in place and let it run once on the device.

Step 6 — Copy your ROMs back

# Prevent macOS from littering the card with ._ metadata files
defaults write com.apple.desktopservices DSDontWriteUSBStores -bool true

cp -a roms_backup/* /Volumes/EASYROMS/roms/

# cp -a still creates ._ files sometimes — clean them
find /Volumes/EASYROMS -name '._*' -delete
find /Volumes/EASYROMS -name '.DS_Store' -delete

Step 7 — Eject and boot

diskutil eject /dev/disk4

Insert into R36S. Expect first boot to take 2-3 minutes. If it boots to EmulationStation, you're done.

Troubleshooting

Black screen, green LED solid → u-boot is missing or wrong. Re-do Fix 1. This is the #1 failure mode.

Black screen, green LED blinking / device boots but display is garbled → Wrong panel DTB. Try a different panel number from the Device Pack. Panel 0 and Panel 4 cover most 2023+ units.

Boots but ROMs partition is empty or read-only → fstab still says ntfs-3g. Re-do Fix 3.

"Operation not permitted" on dd → Grant Terminal Full Disk Access in System Settings → Privacy & Security.

debugfs says "Filesystem has unsupported feature(s)" → You're using the macOS built-in debugfs. Use the Homebrew one: /opt/homebrew/opt/e2fsprogs/sbin/debugfs.

Why this skill exists

The R36S has many silent board revisions and panel variants. Stock dArkOS images target one panel configuration; most users with a different panel hit a black screen and assume the image is broken. It's not — you just need to swap in your own u-boot and the right DTB. This skill encodes the full recovery path so the next person doesn't lose an evening to it.