Troubleshooting, Arch R

Boot Issues

Black screen, just the splash

Check the panel overlay first: a wrong or missing overlay is a common cause. 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 the launcher

Possible causes to investigate:

CPU instability at turbo (only with CPU turbo on). Power off, remove SD, edit /storage/.config/system/configs/system.cfg from a PC, and set enable.turbo-mode=0.
First-boot resizing stalled. Inspect /flash/fs-resize.log. /storage/.boot_last_hang records the last traced step of an interrupted autostart run; it can be stale and does not prove which script caused the failure.
Wrong image variant (original on a clone or vice versa). Reflash with the right variant (this erases the card, so copy your data off first).

Boot reaches the launcher but freezes there

Stop archr-launcher, then check what is holding things up:

sudo systemctl stop archr-launcher-session
sudo journalctl -t archr-autostart -f

Or read the boot log (/var/log/boot.log; journald is volatile, so logs from the previous boot are lost) and the launcher log (/var/log/archr-launcher-session.log). Restart the launcher with sudo systemctl start archr-launcher-session once you have identified the issue.

"Boot anterior travou em <script>"

/storage/.boot_last_hang records the last traced step of an interrupted autostart run. It can be stale and does not prove which script caused the failure. For first-boot resizing, inspect /flash/fs-resize.log. Open an issue with:

The contents of /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. In RetroArch, check Settings → Video → Synchronization → Vertical Sync; ArchR already enables it by default.

Brightness has fewer steps than I'd like

A tap on the brightness shortcut moves 2 points, and holding it goes faster. You can also adjust it in Settings › Sound and display › Brightness. In shell scripts, archr-levels brightness <0-100> sets an exact value and archr-levels brightness +1 steps it by one.

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. It is the same generator, needs a current Python 3 release and nothing else (Python 3.5 is not compatible), and works without a network. 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

Check Settings › Sound and display › Audio output and Volume. Over SSH, set-audio list shows the available outputs; they depend on the detected devices.

Speaker/headphone routing also uses a mixer control that varies by board, so there is no single amixer command for every device. Headphone detection is device-specific too: the helper uses input events with a GPIO fallback, and an extcon path is not universal.

Audio crackle in Mario 64 / 3D-heavy games

Crackle together with unbalanced disables for vdd_logic in dmesg can indicate an older build. Update to the latest release and check again.

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

Bluetooth audio choppy

There is no validated fix documented here yet. Open an issue with the adapter and headset models, the game, and the output of dmesg | tail -200.

Performance

Game runs slower than expected

In order:

CPU governor: game launch applies the effective CPU governor, including supported per-system, per-game or launch overrides, so performance is not unconditional (see Settings › System › CPU governor). 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 turbo = 1416000, with CPU turbo = 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) or check System information › Processor (Y on the Settings home). Thermal trip points differ between board device trees; compare the reading with cat /sys/class/thermal/thermal_zone0/trip_point_*_temp. If it runs hot, take a break and 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 contains maxima, final measurements and sample counts (not latency percentiles), psi.log has per-second pressure stalls, freq-therm.log has the freq trajectory.

Storage / ROMs

Some ROMs don't appear after copying

Verify the file extension matches the supported extensions for that system in /usr/share/archr/systems.cfg (a copy in /storage/.config/archr/systems.cfg takes precedence). The launcher recounts the folders when it starts; to force it, restart the launcher (systemctl restart archr-launcher-session).

"Disk full" but my SD is huge

Check the size in Settings › Storage or with df -h /storage. The STORAGE size depends on the other partitions on the card, such as ARCHR_ROMS (see Adding ROMs).

If it looks wrong, inspect the partition layout (lsblk) and /flash/fs-resize.log. The resize marker is for first-boot initialization and does not resize an already initialized installation. Back up externally before recovery or reflashing.

Save states gone after reflash

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. Reflashing replaces the card's partition layout and filesystems, so both are gone unless you copied them to another device first.

The default backup in Settings › Storage › Back up includes selected settings and themes, emulator saves (including those stored next to the ROMs) and /storage/roms/savestates/. ROMs and gamelists are left out. The ZIP stays on the card in /storage/roms/backup. Before the next reflash, copy the ROM folders, saves, settings and backup archive to another device, for example over SSH:

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

SSH / Network

Can't connect: "connection refused"

SSH is off by default. Turn it on in Settings › Network › Network services › SSH.

"archr.local" doesn't resolve

Avahi/mDNS issue. Use the IP address shown in Settings › Network › Wi-Fi (or in System information › Network, opened with Y on the Settings home). Or:

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

Wi-Fi connects but no internet

This can indicate a DNS or gateway problem. Investigate:

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. Wi-Fi is handled by iwd, through wifictl and iwctl. wifictl accepts enable, disable, connect, disconnect, reconnect, list, scan, and channels.

PortMaster

Port hangs at black screen

One possible cause is wrong /dev/uinput permissions. ls -la /dev/uinput should be crw-rw-rw- (mode 666). If not, the udev rule didn't apply; run sudo chmod 666 /dev/uinput for now and report a bug.

"Permission denied" running gptokeyb

This can also come from /dev/uinput permissions; check them as above.

`box86: assertion failure`

One possible cause is a port built against a newer libstdc++ than ArchR ships. Report it at the PortMaster Discord with the port name and the full error.

PortMaster GUI itself fails to start

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 System information (Y on the Settings home), 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
   /var/log/archr-launcher-session.log
   /var/log/exec.log
   dmesg | tail -200
   /storage/.boot_last_hang   (last traced step of an interrupted autostart run; may be stale)
   /flash/fs-resize.log       (if first-boot related)

Instead of collecting the logs by hand, open Settings › System › Diagnostics and choose Create report now, or hold FN + L1 + R1 for 3 seconds, which works even in a game. Report generation time varies. It writes a .zip to roms/relatorios/ (visible from a PC) with hardware, kernel, services, network, storage, temperatures, emulators and the logs of the boot and of the last game. The tool filters sensitive information; review the archive before sharing. Every report carries this console's ID, a short code taken from the hardware that identifies the console, never you; it stays the same after a reflash and shows in Settings › System › Error reports (mention it when you open an issue). In Diagnostics, Send the last report sends the newest .zip (up to 5 MB) to the Arch R developers; nothing leaves without your confirmation, and it only works with Send error reports turned on. Debug mode on the same page logs in more detail and keeps the logs across restarts.

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

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

Troubleshooting

On this page