Troubleshooting, Arch R

Boot issues

Black screen, just the splash

Wrong or missing panel overlay. The image does not ship one, so a card written without an overlay boots with whatever panel description the base device tree carries, which only matches some boards.

Fix: generate mipi-panel.dtbo on the Overlay Generator from the .dtb of your console's own original card, then copy it to overlays/mipi-panel.dtbo on the ARCHR partition. The Flasher can do the copy for you, either while it writes the card or afterwards from its Overlay tab.

Boot loops, never reaches ES

Three possibilities, in order of likelihood:

CPU instability at turbo (only with Enable CPU Overclock on, very rare). Power off, remove SD, edit /storage/.config/system/configs/system.cfg from a PC and set enable.turbo-mode=0.
fs-resize hung on first boot. Capture cat /storage/.boot_last_hang after the eventual successful boot, that file names the script that stalled.
Wrong image variant (original on a clone or vice versa). Re-flash with the right variant.

Boot reaches ES but freezes there

Stop ES, then check what's holding things up:

sudo systemctl stop emustation
sudo journalctl -t archr-autostart -f

Or read the boot log (/var/log/boot.log, note that journald is volatile so logs from the previous boot are lost). Restart ES with sudo systemctl start emustation once you've identified the issue.

"Boot anterior travou em <script>"

The trace mechanism caught a hang on the previous boot. The named script is the culprit. Open an issue with:

The script name from /storage/.boot_last_hang
dmesg | tail -200 from the post-recovery boot
The output of cat /flash/fs-resize.log if applicable

Display

Colors look wrong / inverted

The panel is wired BGR where the overlay describes RGB, or the other way round. Generate the overlay again from your console's own original .dtb, since that file carries the real colour order for the board in front of you. A .dtb borrowed from another device is the usual cause.

Screen "tearing" in some emulators

video_threaded is on by default. For tearing-sensitive games, in RetroArch Quick Menu → Settings → Video → Output → Vertical Sync = ON.

Brightness has fewer steps than I'd like

ArchR uses 3% / step (33 distinct levels). If you need finer control, edit /storage/.config/profile.d/099-freqfunctions and adjust the brightness step.

The overlay generator page never finishes loading

The web Overlay Generator downloads a WebAssembly Python runtime of about 8.6 MB before it can run. On a slow or filtered connection that download may never complete, and the page keeps asking you to reload.

Use the offline edition instead: archr-dtbo-offline.zip, about 100 KB, same generator, Python 3.5+ and nothing else, no network needed. Extract it, open a terminal in the folder and run:

python3 archr_dtbo.py rk3326-r36s-linux.dtb SDORIG -o mipi-panel.dtbo

On Windows the command is python instead of python3. The option strings are SDORIG (R36S Original), SDCLONE (R36S Clone) and SDORIG-NAm (R36S Soysauce), with extra flags appended by a dash, for example SDCLONE-LSi. Copy the resulting file to the ARCHR partition as overlays/mipi-panel.dtbo, which is the exact folder and filename extlinux.conf already points at.

Full instructions, including the fix for No module named 'fdt' and anti-gap: base not available, are in Installation.

Audio

No sound at all

amixer get 'Playback Path'    # should be SPK or HP
amixer get DAC                # should be > 0
cat /sys/class/extcon/*/state # HP detect (1 = plugged)

If Playback Path is wrong, force it: amixer set 'Playback Path' SPK.

Audio crackle in Mario 64 / 3D-heavy games

If you're seeing crackle plus unbalanced disables for vdd_logic in dmesg, you're on a pre-v8 build. Update to the latest release, the mali_kbase PM patch eliminates this.

If still happens on latest: open an issue with dmesg | grep -iE 'vdd_logic|clk_gpu|mali' and the game name.

Bluetooth audio choppy

A2DP latency is sensitive to the BT codec. Force SBC + low-quality if your device only supports basic profiles:

pactl set-sink-port bluez_sink.<MAC>.a2dp-sink "speaker-output"

In ES Bluetooth menu, the toggle "Force SBC" does the same.

Performance

Game runs slower than expected

In order:

CPU governor: should be performance during gameplay. Verify: cat /sys/devices/system/cpu/cpufreq/policy0/scaling_governor.
GPU governor: should be performance. cat /sys/class/devfreq/ff400000.gpu/governor.
CPU max freq: cat /sys/devices/system/cpu/cpufreq/policy0/scaling_max_freq. Without overclock = 1416000, with overclock = 1512000.
Background services: systemctl is-active syncthing tailscaled zerotier-one simple-http-server. Should all be inactive during a game (they're paused automatically by runemu.sh).
Thermal throttling: cat /sys/class/thermal/thermal_zone0/temp (units: m°C). Above 70 000 (70 °C) triggers passive throttle. Take a break, let it cool.

Run the bench

The bench script is not installed in the image. Copy tools/bench.sh from the Arch-R source tree to the console first, then run it from wherever you put it:

bash bench.sh psp 60   # tag the scenario, duration in seconds

Results in /storage/bench-results/<timestamp>-psp/, summary.json has p99-style aggregates, psi.log has per-second pressure stalls, freq-therm.log has the freq trajectory.

Storage / ROMs

Some ROMs don't appear after copying

ES rescans only at boot. ES menu → Game Settings → Rescan ROMs → wait → ROMs appear.

"Disk full" but my SD is huge

Check that the partition was resized: df -h /storage. Should show ~95% of the SD capacity. If not, fs-resize didn't run; the marker file /storage/.please_resize_me triggers it on next boot:

sudo touch /storage/.please_resize_me
sudo reboot

Save-states gone after re-flash

Save-states live in /storage/roms/savestates/<system>/ and battery saves (.srm, .sav) sit next to the ROM itself, because RetroArch runs with savefiles_in_content_dir on. Both are inside /storage/roms, which survives a re-flash. If the whole card was rewritten, they are gone. Back up next time:

scp -r root@archr.local:/storage/roms/savestates ~/r36s-saves-backup/

SSH / network

Can't connect: "connection refused"

SSH is off by default. ES → System Settings → Network → Enable SSH → ON.

"archr.local" doesn't resolve

Avahi/mDNS issue. Use the IP (visible in ES → System Information). Or:

# from a Linux/macOS box
avahi-browse -art | grep archr

WiFi connects but no internet

DNS issue. Try:

cat /etc/resolv.conf                  # is there a nameserver at all
iwctl station wlan0 show              # link state, IP, gateway
wifictl reconnect                     # drop and redial the saved network

connman is compiled with --disable-wifi, so connmanctl cannot see or manage wireless at all on ArchR. WiFi is handled by iwd, through wifictl and iwctl. wifictl accepts enable, disable, connect, disconnect, reconnect, list, scan and channels.

ssh root@archr.local
bash /usr/bin/start_portmaster.sh

Read the trace. The script is idempotent (re-running is safe).

How to file a useful bug report

1. Hardware           ────  R36S V21 / K36 / RX6S etc.
2. ArchR version      ────  in ES System Information, or `cat /etc/os-release`
3. Image variant      ────  original | clone
4. Panel overlay      ────  where the .dtb you generated it from came from
5. What you tried     ────  exact steps to reproduce
6. What happened      ────  observed vs expected
7. Logs:
   /var/log/boot.log
   dmesg | tail -200
   /storage/.boot_last_hang   (only exists if the previous boot hung)
   /flash/fs-resize.log       (if first-boot related)

Open at github.com/archr-linux/Arch-R/issues.

For PortMaster specifically: github.com/PortsMaster/PortMaster-GUI/issues.

Troubleshooting