# Audio



ArchR ships PipeWire + ALSA on top of the RK817 codec. Most things just work; this page documents the corner cases.

***

## Output paths [#output-paths]

Six possible audio sinks, picked automatically:

```
SPK     internal speakers (default if nothing else plugged)
HP      headphone jack (auto-detected via extcon)
HDMI    HDMI audio out (when an HDMI cable is connected)
USB     USB audio device (DAC, headset, gamepad with audio)
BT      Bluetooth audio sink (paired headphones / speaker)
SIMPLE  legacy fallback for clone boards with non-standard amplifier wiring
```

Detection happens in `/etc/profile.d/050-audio` at login + on hotplug via udev.

### Force a path [#force-a-path]

```bash
amixer set 'Playback Path' SPK    # speakers
amixer set 'Playback Path' HP     # headphones
amixer set 'Playback Path' HDMI   # HDMI
```

The setting is reset on next hotplug event, to make it sticky, edit `/storage/.config/system.cfg` → `audio.path=SPK|HP|HDMI`.

***

## Volume [#volume]

Volume buttons (VOL+ / VOL-) drive the **DAC** mixer control directly. Range 0-255, step 2 % per press, persists across reboots.

```bash
amixer get DAC                  # current value, 0..255
amixer cset numid=N <value>     # set explicitly (find numid with `amixer controls`)
```

Max DAC level on RK817 is capped at 98 % to avoid speaker rattle on small clone speakers; this is set by the `050-audio_path` quirk for RK3326 (`Playback Mux` adjustment).

***

## SR variant ("force simple audio") [#sr-variant-force-simple-audio]

Some clone motherboards wire the amplifier to a different GPIO than the standard RK817 codec config expects. The Flasher offers an **SRs** toggle that swaps to a simpler amplifier path.

If your device plays everything through the headphone jack but the speakers are silent regardless of jack state, re-flash with **SRs** ON.

The setting lives in the panel DTBO file, it can't be changed at runtime; you have to re-flash with the right overlay or copy a different `*_SRs.dtbo` to `/flash/overlays/mipi-panel.dtbo` from a PC.

***

## HDMI audio [#hdmi-audio]

Plug an HDMI cable; audio output switches automatically. The HDMI port is HDMI 1.4, supports stereo PCM at 48 kHz. No surround.

If the display works but audio stays on speakers:

```bash
aplay -L | grep -i hdmi
amixer set 'Playback Path' HDMI
```

***

## USB audio [#usb-audio]

Most USB audio class 1.0 devices (the common DACs, headsets, capture devices) work plug-and-play. PipeWire picks them up via `auto-link`. Switch to USB output:

```bash
pactl list sinks short
pactl set-default-sink <name-of-usb-sink>
```

***

## Bluetooth audio [#bluetooth-audio]

Pair from ES → System Settings → Bluetooth → Pair Device. Once paired, audio routes there automatically.

Caveats:

* **Latency**: A2DP is \~150 ms one-way, fine for music, noticeable in games. The RK3326 has no aptX-LL hardware.
* **Re-pairing**: if the speaker doesn't reconnect after sleep, in ES BT menu → Manage Paired Devices → Reconnect.
* **Both speaker + BT simultaneously**: not supported, pulseaudio routing is single-sink at a time.

***

## Per-emulator audio backend [#per-emulator-audio-backend]

```
RetroArch                ALSA via "alsathread" (out of the way of the libretro frame loop)
PPSSPP standalone        SDL2 audio → PipeWire
Flycast standalone       SDL2 audio → PipeWire
Mupen64Plus standalone   SDL2 audio → ALSA
DraStic                  SDL2 audio → ALSA
```

`alsathread` for RetroArch trades a couple ms of latency for predictable scheduling, important on a CPU-bound A35.

***

## Troubleshooting [#troubleshooting]

**Speakers crackle in heavy 3D games.** Pre-v8 builds had a `mali_kbase` PM regulator unbalance that perturbed the audio clock domain. Update to v8+. If still happens: `dmesg | grep -iE 'vdd_logic|clk_gpu|mali'`, empty result is what you want.

**Audio stutters under load.** PipeWire quantum too low. Edit `/storage/.config/pipewire/pipewire.conf.d/99-quantum.conf`:

```ini
default.clock.quantum = 1024
default.clock.min-quantum = 512
default.clock.max-quantum = 2048
```

Restart PipeWire: `systemctl --user restart pipewire`.

**Bluetooth audio choppy / dropouts.** SBC bitpool too high. Force lower-quality: ES → BT → Manage Paired Devices → "Force SBC" toggle.

**HP detected but speakers stay on (or vice versa).** Extcon driver issue. Check `cat /sys/class/extcon/*/state`. Log a bug with this output if it doesn't change when you plug/unplug.


# Bluetooth



ArchR ships BlueZ + PipeWire bluetooth backend. No `bluealsa`, codec routing happens through PipeWire, which gives a cleaner integration but means some quirky devices behave differently than older docs imply.

***

## Pair an audio headset [#pair-an-audio-headset]

<Steps>
  ### Enable Bluetooth [#enable-bluetooth]

  ES → **System Settings** → **Controller & Bluetooth Settings** → **Enable Bluetooth** → ON.

  ### Put your headset in pairing mode [#put-your-headset-in-pairing-mode]

  Refer to your headset's manual, usually holding the power button until the LED blinks rapidly.

  ### Pair from the device [#pair-from-the-device]

  Same menu → **Pair a Bluetooth Device**. Wait for your headset's name to appear, select it.

  ### Route audio [#route-audio]

  Once paired, ES → **System Settings** → **Audio Device** → pick the BT device from the list. ES restarts; output now goes through Bluetooth.
</Steps>

***

## Pair a gamepad [#pair-a-gamepad]

Same menu, **Pair a Bluetooth Device**, put gamepad in pairing mode (varies, most Xbox/8BitDo gamepads have a tiny pairing button under or next to the USB port).

After pairing, ES auto-detects the gamepad and prompts you to map buttons. Mapping is saved per-device in `/storage/.config/SDL2/gamecontrollerdb.txt`.

***

## Caveats on RK3326 [#caveats-on-rk3326]

The RK3326's WiFi/BT chip is on a single shared antenna. Real-world implications:

* **Range is \~3 m**: Bluetooth headphones across the room will stutter.
* **WiFi competes with BT for airtime**: heavy network use during gameplay can crackle the audio. Pause Syncthing/Tailscale/ZeroTier during gameplay (ArchR does this automatically via `pause_background_services` in `runemu.sh`).
* **A2DP latency** is \~150 ms, fine for music, noticeable in fast-paced games. ArchR has no aptX-LL hardware.

***

## Codec selection [#codec-selection]

PipeWire picks the best codec your headset advertises (LDAC > aptX > AAC > SBC). Force a lower codec if you hit dropouts:

```bash
# inspect current codec
pactl list sinks | grep -A 1 "Active Port"

# force SBC (universal, lowest bandwidth)
pactl set-sink-port bluez_sink.<MAC>.a2dp-sink "speaker-output-sbc"
```

For LDAC at higher bitrates the A35 CPU load is non-trivial, `mobile` (330 kbps) and `standard` (660 kbps) profiles work; `high` (990 kbps) on top of an emulator is enough to cause crackle.

***

## Disconnect cleanly [#disconnect-cleanly]

Always toggle BT off in ES (or unpair) before powering off. Cold-disconnect (just turning off your headset) sometimes leaves PipeWire holding a stale sink, which means no audio until reboot.

If it happens, over [SSH](/docs/ssh):

```bash
systemctl --user restart pipewire pipewire-pulse wireplumber
```

***

## Known issues [#known-issues]

* **PCSX-ReARMed core**: silent under Bluetooth audio for unknown reasons (carry-over from upstream). Workaround: use `pcsx_rearmed32` or `swanstation` libretro core, or DuckStation standalone.
* **Reconnect-on-resume**: after a fake-suspend wake-up (when RK3326 supports that some day), BT may not reconnect. Manual reconnect in the Bluetooth menu.


# Build from source



ArchR's build system is fully reproducible, `make docker-RK3326` produces both image variants from a clean checkout, identical to the GitHub release. No hidden steps, no closed-source artifacts.

***

## Requirements [#requirements]

* Docker (recommended) or a native Linux build environment
* \~40 GB free disk space (cached source + build trees)
* \~8 GB RAM recommended (the kernel build is the spike)
* A x86\_64 host (cross-toolchain targets aarch64)

A native build takes \~2 h on a 12-core x86; Docker adds \~5 % overhead.

***

## Quick build [#quick-build]

```bash
git clone https://github.com/archr-linux/Arch-R.git
cd Arch-R

# First time only: build the Docker build environment
make docker-image-build

# Build both image variants for R36S
make docker-RK3326
```

Output in `target/`:

```
ArchR-R36S.aarch64-YYYYMMDD-original.img.gz
ArchR-R36S.aarch64-YYYYMMDD-clone.img.gz
*.sha256                                    # checksums for the flasher
ArchR-R36S.aarch64-YYYYMMDD.tar             # rootfs only (for re-imaging)
```

***

## All commands [#all-commands]

| Command                   | What it does                         |
| ------------------------- | ------------------------------------ |
| `make docker-RK3326`      | Full Docker build, both variants     |
| `make RK3326`             | Native build (toolchain on host)     |
| `make docker-image-build` | (Re)build the Docker build container |
| `make clean`              | `rm -rf build.* target`              |
| `make distclean`          | `clean` + nuke source caches         |

For other devices: `make docker-RK3588`, `make docker-S922X`, etc., see the per-device options under `projects/ArchR/devices/`.

***

## Incremental rebuilds [#incremental-rebuilds]

The build system uses **stamps** in `build.ArchR-RK3326.aarch64/.stamps/<package>` to skip already-built packages. To force a rebuild of a specific package:

```bash
rm -rf build.ArchR-RK3326.aarch64/.stamps/<pkg>
make docker-RK3326
```

Common ones:

```
linux             kernel + DTS + modules
mali-bifrost      libmali kernel module
mesa              Mesa Panfrost
retroarch         RetroArch frontend + libretro frame
ppsspp-sa         PPSSPP standalone
flycast-sa        Flycast standalone
archr             scripts / configs / runemu.sh
emulators         es_systems.cfg generation
```

After a stamp removal, `make docker-RK3326` rebuilds just that package and re-images.

***

## Project layout [#project-layout]

```
Arch-R/
├── packages/                       upstream LibreELEC-style package recipes
│   ├── compress/zlib/              (ArchR uses zlib-ng compat, see PKG_NAME)
│   ├── graphics/mesa/
│   ├── linux/
│   └── ...
├── projects/ArchR/
│   ├── devices/RK3326/             RK3326-specific patches, DTS, kernel config
│   │   ├── linux/                  kernel config + DTS overrides
│   │   ├── patches/linux/          per-version kernel patches
│   │   └── options                 device-level vars (BOOT_SIZE, ROOT_SIZE…)
│   ├── packages/                   ArchR-specific packages on top of upstream
│   │   ├── archr/                  scripts/runemu.sh, profile.d/, autostart/
│   │   ├── linux-drivers/mali-bifrost/   libmali kernel patch
│   │   ├── graphics/gpudriver/     panfrost ↔ libmali switch
│   │   ├── apps/portmaster/        PortMaster + scripts/start_portmaster.sh
│   │   ├── emulators/standalone/   PPSSPP/Flycast/melonDS/DraStic per-device cfg
│   │   └── ui/emulationstation/    ES patches
│   └── options                     project-level vars
├── distributions/ArchR/
│   ├── options                     distro-level vars (BOOT_SIZE=272, ROOT_SIZE=4608…)
│   └── config/
├── config/
│   ├── archr-dts/                  43 motherboard revisions × {original/clone/soysauce}
│   └── mipi-generator/             generator.sh + archr-dtbo.py (DTS → DTBO)
├── scripts/
│   ├── build                       per-package build driver
│   ├── extract                     tarball extract
│   ├── image                       wraps mkimage
│   └── mkimage                     partition layout, FAT32 BOOT, ext4 ROOT, ext4 STORAGE
├── tools/
│   ├── bench.sh                    on-device benchmark (PSI, freq, temp)
│   ├── audit-build.sh              on-device build audit
│   └── ...
└── docs/                           internal design docs / decision logs
```

***

## Common edits [#common-edits]

**Tune a kernel option:**

```
projects/ArchR/devices/RK3326/linux/linux.aarch64.conf
```

Then `rm -rf build.ArchR-RK3326.aarch64/.stamps/linux && make docker-RK3326`.

**Tune CPU OPP / regulator:**

```
projects/ArchR/devices/RK3326/patches/linux/000-rk3326-dts.patch
projects/ArchR/devices/RK3326/linux/dts/rockchip/rk3326-gameconsole-r3xs.dtsi
```

**Add an emulator default:**

```
projects/ArchR/packages/virtual/emulators/package.mk
projects/ArchR/packages/emulators/standalone/<emu-sa>/scripts/start_<emu>.sh
```

**Edit the autostart trace path:**

```
projects/ArchR/packages/sysutils/autostart/sources/autostart
```

***

## Validating a build [#validating-a-build]

`tools/audit-build.sh` runs on the device and verifies:

```bash
bash /flash/audit-build.sh
```

…that no kernel debug flags slipped through, that all libretro cores are stripped, that no sanitizer symbols leaked into binaries. Use it in CI.

`tools/bench.sh` collects PSI / freq / temp / vmstat / dmesg for a 60 s window:

```bash
bash /flash/bench.sh psp 60
# launch a PSP game in a separate terminal / TTY
# results land in /storage/bench-results/<timestamp>-psp/
```


# Cloud sync



Three approaches to keeping your handheld's `/storage` in sync with another machine. Pick whichever fits your setup.

***

## Syncthing (peer-to-peer) [#syncthing-peer-to-peer]

Best when you have a PC or another handheld and want continuous, automatic sync without involving a cloud account.

### Setup on the handheld [#setup-on-the-handheld]

1. ES → **System Settings** → **Network** → **Syncthing** → ON.
2. Note the device IP (visible in **System Information**).
3. Note the `root` password under **Security** (default `archr`, change it).

### Setup on your PC [#setup-on-your-pc]

Install Syncthing from your distro's package manager or [syncthing.net](https://syncthing.net).

### Connect them [#connect-them]

Browse to `http://<handheld-ip>:8384` from your PC. Login: user `root`, password whatever you set.

In the handheld's web UI:

* **Add Remote Device** → paste the PC's Device ID (visible in your PC Syncthing's UI under Actions → Show ID). Same-LAN devices auto-discover, otherwise paste manually.
* **Add Folder** → label it (e.g. `roms`), path `/storage/roms`. In the **Sharing** tab, tick the PC.

On the PC, accept the incoming device + folder. Pick a local folder to mirror to. Done, sync starts.

### What to sync [#what-to-sync]

| Folder                 | Content               | Sync?                |
| ---------------------- | --------------------- | -------------------- |
| `/storage/roms`        | Your games            | sometimes, large     |
| `/storage/saves`       | RetroArch SRAM saves  | yes, small, valuable |
| `/storage/states`      | RetroArch save-states | tricky, see below    |
| `/storage/screenshots` | Screenshots           | yes                  |
| `/storage/.config`     | All app configs       | usually no           |

**RetroArch save-states caveat:** states are tied to the **exact core build**. If your PC RetroArch and the handheld run different libretro core versions, states can corrupt. Saves (SRAM) are core-version-agnostic, states aren't. Sync `saves/` always; sync `states/` only if you keep core versions identical.

ArchR has Syncthing paused during gameplay so it never competes with the emulator for CPU. It resumes on exit.

***

## rclone (cloud storage) [#rclone-cloud-storage]

For Google Drive / OneDrive / Dropbox / S3 / etc. ArchR ships rclone preconfigured with a wrapper at ES → **Tools** → **Cloud Backup** / **Cloud Restore**.

### Setup [#setup]

<Steps>
  ### Enable SSH [#enable-ssh]

  [As in the SSH guide](/docs/ssh).

  ### Configure your cloud provider [#configure-your-cloud-provider]

  ```bash
  ssh root@archr.local
  rclone config
  ```

  Follow the prompts; refer to [rclone provider docs](https://rclone.org/remote_setup/) for OAuth headless setup if needed.

  ### Edit `cloud_sync.conf` [#edit-cloud_syncconf]

  Default at `/storage/.config/cloud_sync.conf`. Most useful keys:

  | Key             | Default                | Meaning                                                               |
  | --------------- | ---------------------- | --------------------------------------------------------------------- |
  | `BACKUPPATH`    | `/storage/roms`        | what to back up                                                       |
  | `RESTOREPATH`   | `/storage/roms`        | where to restore (different from `BACKUPPATH` to test restore safely) |
  | `BACKUPFOLDER`  | `/storage/roms/backup` | local backup files                                                    |
  | `SYNCPATH`      | `/GAMES`               | path on the cloud remote                                              |
  | `BACKUPMETHOD`  | `sync`                 | `sync` mirrors / `copy` adds without deleting                         |
  | `RESTOREMETHOD` | `copy`                 | `copy` preserves existing local / `sync` overwrites                   |
  | `RCLONEOPTS`    | filters & verbosity    | per [rclone flags](https://rclone.org/flags/)                         |

  ### Run a backup [#run-a-backup]

  ES → **Tools** → **Cloud Backup**. Same menu has **Cloud Restore**.
</Steps>

### Logs [#logs]

```bash
tail -f /var/log/cloud_sync.log
```

### Filter rules [#filter-rules]

`/storage/.config/cloud_sync-rules.txt` controls what's included/excluded. The `.defaults` version next to it is the upstream template, copy keys from there if you want to restore defaults.

***

## NFS (LAN file server) [#nfs-lan-file-server]

If you have a NAS or a Linux PC running an NFS server, you can mount the NFS share over the games folder. ROMs live on the server; saves stay on the handheld.

### Drop the mount file [#drop-the-mount-file]

```
/storage/.nfs-mount
```

Single line:

```
NFS_PATH=192.168.1.10:/srv/roms
```

### Mount [#mount]

ES → **Tools** → **Mount NFS**. The remote path is mounted at `/storage/games-external` and an overlay merge is created at `/storage/roms`, saves go to the local upper layer (`/storage/games-internal`), game reads come from the NFS share.

This is nice for big collections, store the 200 GB MAME romset on a NAS, have the handheld just see them on `/storage/roms/arcade`.

### Caveats [#caveats]

* NFS over WiFi is sensitive to packet loss; expect occasional latency spikes when the WiFi signal dips.
* ROMs that need fast random reads (PSP ISO seek-heavy scenes) feel better when the file is local, copy your most-played titles into `/storage/games-internal/roms/` to get the local-disk path of the overlay.
* The mount drops on `power-off` and reconnects on next boot if the file is still present.


# Collections



EmulationStation collections let you create cross-system game lists, every RPG you've ever owned, your "now playing" backlog, "kid-friendly", "speedruns to try". They live alongside the per-system lists in the home view.

All settings live under ES → **Game Collection Settings**.

***

## Three flavours [#three-flavours]

### Automated [#automated]

ES has built-ins for **Favorites**, **Last Played**, and **All Games**. Toggle individually under **Automated Game Collections**.

To add a game to **Favorites**: highlight it → press `Y`. Same `Y` again to remove.

### Editable (curated) [#editable-curated]

Pick a name, then walk your library and tag games one by one.

ES → **Game Collection Settings** → **Create New Custom Collection** → name it. Browse to a game → press `Y` → in the "Add to collection" picker, select the new collection.

Useful for thematic lists: `Final Fantasy series`, `Top 50 of all time`, `Kids`.

### Dynamic (filter-based) [#dynamic-filter-based]

Create a collection driven by metadata filters, every game whose Genre is "RPG", every game from 1992-1995, every game with rating ≥ 4 stars. New games matching the filter automatically appear.

ES → **Game Collection Settings** → **Create New Custom Collection from Theme** → choose **Dynamic** → set filters.

The filters come from the metadata you scraped, see [Scraping](/docs/scraping). Without scraped metadata, dynamic collections have nothing to match.

***

## Now Playing, the backlog tool [#now-playing-the-backlog-tool]

A built-in dynamic collection labelled **Now Playing**. Curates the handful of games you're actively in the middle of, separate from the 800-game library.

Enable it: ES → **Game Collection Settings** → **Create New Custom Collection from Theme** (with Art Book Next active) → tick **Now Playing**.

Add a game: highlight → `Y` → **Add to Collection** → **Now Playing**.

Boot directly into it: ES → **Game Collection Settings** → **Start on System** → `Now Playing`, plus enable **Start on Gamelist**. Now ArchR boots straight into your active backlog instead of the system list.

***

## Hide systems you don't use [#hide-systems-you-dont-use]

Same menu, **Systems Displayed**: untick systems you don't have ROMs for to declutter the home view. The systems still exist (ROMs aren't deleted), they just don't show up.

This is also how to hide the empty systems for stuff you've never bought ROMs for.

***

## Where collections live [#where-collections-live]

`/storage/.config/emulationstation/collections/`

One `.cfg` per collection. The format is plain text, one `<system-tag>:<rom-filename>` per line for editable collections, an XML `<filter>` block for dynamic. You can edit them on a PC if you want, but the in-ES UI is usually friendlier.


# Controls



## Standard hotkeys [#standard-hotkeys]

The R36S has a `MODE` (or `Function`) button. Combined with another button it acts as a hotkey.

```
VOL+ / VOL-               Volume (audio DAC, 2% / step)
MODE + VOL+ / VOL-        Brightness (3% / step, persists across reboots)
MODE + B                  Quit emulator (returns to ES)
MODE + X                  Open RetroArch quick menu (libretro cores only)
MODE + R1                 Save state
MODE + L1                 Load state
MODE + R2                 Next save-state slot
MODE + L2                 Previous save-state slot
MODE + Y                  Take screenshot (saved to /storage/screenshots/)
MODE + START              Reset emulator
MODE + SELECT             Toggle FPS/perf overlay
```

Long-press `POWER` for shutdown menu (suspend / restart / power-off).

***

## Joypad variants [#joypad-variants]

R36S clones use one of two button-mapping conventions. ArchR auto-detects the right one based on the **board profile** you flashed, but you can override it.

### Auto (default) [#auto-default]

The Flasher reads the motherboard revision and picks the right variant:

* **K36 layout**: most R36S clones, including K36, R33S, EE Clone
* **MyMini layout**: soysauce / Y3506 hardware (e.g. mid-2024 batches)

### Manual override [#manual-override]

In the [ArchR Flasher](/docs/installation), the **Joypad variant** dropdown forces a specific layout. Useful if Auto picks wrong (rare). Choices:

| Variant | Effect on physical buttons                            |
| ------- | ----------------------------------------------------- |
| Auto    | Detect from motherboard revision                      |
| K36     | Standard Nintendo / Xbox layout                       |
| MyMini  | Mirrored layout (B↔A and X↔Y swapped relative to K36) |

### Switching after flash [#switching-after-flash]

Edit `/storage/.config/system.cfg` over [SSH](/docs/ssh) and set:

```ini
joypad.variant=K36     # or MyMini
```

Reboot.

***

## JP layout [#jp-layout]

Toggle in the Flasher under **JP layout**: swaps A↔B and X↔Y for Japanese-style button labels (matches Famicom / SFC physical positions).

This is purely a controller remap, ROMs don't need to be Japanese.

***

## RetroArch in-game [#retroarch-in-game]

Press `MODE + X` for the Quick Menu. Common sub-menus:

```
Resume                    Back to game
State Slot                Pick save slot 0-9
Save State / Load State   In-place save (faster than ROM save)
Take Screenshot           PNG to /storage/screenshots/
Options                   Per-core knobs (resolution, frameskip, BIOS)
Controls                  Remap on the fly
Cheats                    Cheat list (if .cht for the ROM)
Disk Control              Multi-disc PSX swap
Information               Core / system / authors
```

`MODE + B` exits without going through the menu.

***

## Standalone emulator hotkeys [#standalone-emulator-hotkeys]

Each standalone has its own internal menu:

| Emulator              | Menu hotkey    |
| --------------------- | -------------- |
| PPSSPP                | `MODE` (alone) |
| Flycast               | `MODE` (alone) |
| Dolphin (not RK3326)  | `MODE + X`     |
| DraStic (NDS)         | `MODE` (alone) |
| Yabasanshiro (Saturn) | `MODE + X`     |
| melonDS               | `MODE` (alone) |

`MODE + B` exits all of them.

***

## Custom remaps [#custom-remaps]

Per-system: ES menu → Game Settings → Default Controllers (per system). Saved to `/storage/.config/retroarch/config/<system>.cfg`.

Per-game (single ROM): launch the game → `MODE + X` → Controls → Save Game Remap File.

Custom hotkey override: edit `/storage/.config/retroarch/retroarch.cfg`, look for `input_hotkey_*` keys.

***

## PortMaster ports [#portmaster-ports]

Ports use a separate input layer (`gptokeyb`) that translates joypad input to keyboard events for the original PC binary. Default mapping is in `/storage/roms/ports/PortMaster/control.txt`, most ports override it with their own config.

In-game hotkey to exit a port: usually `MODE + START + SELECT` or just `MODE + START`. Each port documents its own combo.


# FAQ



<Accordions>
  <Accordion title="What devices are supported?">
    The R36S (genuine + all known clones) and the broader RK3326 family, Odroid Go Advance / Super, Anbernic RG351V/M, GameForce Chi, MagicX XU10/XU-Mini-M, BatLexp G350, Powkiddy RGB10/RGB10X/RGB20S. 43 motherboard revisions, both image variants combined.

    If your device has a Rockchip RK3326 SoC and a supported MIPI panel, it almost certainly works.
  </Accordion>

  <Accordion title="How is this different from ArkOS / ROCKNIX / dArkOS?">
    * **Open-source GPU stack**: Panfrost via Mesa 26.0.5 by default; libmali still available as opt-in.
    * **Built on top of ROCKNIX** with an Arch Linux build environment, same release pipeline, different userspace conventions.
    * **Cleaner runtime**: `runemu.sh` is gated by loglevel (no `set -x` permanente), Saturn/Wii/GC hidden on A35, gptokeyb kill is defensive, etc.
    * **Two-image build with autodetect**: same image works on every motherboard of a variant; SARADC reads the board ID at boot.
    * **CPU turbo is opt-in via UI**: no overclock until you toggle it. Battery-friendly default.
    * **Reproducible**: `make docker-RK3326` matches the GitHub release byte-for-byte.
    * **Pre-installed PortMaster + Python lzma + udev /dev/uinput rule**: ports work without pre-flight.
  </Accordion>

  <Accordion title="Can the same SD card work in different R36S boards?">
    Yes within a *variant*, original-image SDs work in any original-variant board, clone-image SDs in any clone-variant board. The board DTB is selected at boot by SARADC.

    Across variants (original ↔ clone) the U-Boot differs, so an original SD won't boot a clone or vice-versa. Re-flash with the right variant.
  </Accordion>

  <Accordion title="Why doesn't the CPU run at 1.5 GHz by default?">
    Because 1.4 GHz is a better default, it's stable on every chip we've tested at the lower 1.35 V, runs cooler, and gives noticeably longer battery life. Going to 1.5 GHz needs 1.4 V on most chips, raises temperature, and only helps for the really CPU-hungry games (PSP heavy, Dreamcast heavy, box86 ports).

    Toggle "Enable CPU Overclock" in System Settings → Performance when you actually need it. See [Overclock](/docs/overclock).
  </Accordion>

  <Accordion title="What's MESA_GLTHREAD and why is it on for some emulators only?">
    A Mesa option that moves GL command processing to a separate thread. Helps when an app issues lots of small GL calls and has its own render thread, Flycast and PPSSPP standalones tick all those boxes. Hurts when an app uses fences/glReadPixels heavily, most libretro 2D cores.

    ArchR uses a whitelist (default off, opt-in per emulator) to avoid regressing 2D cores. Full matrix in `docs/mesa-glthread-matrix.md` in the source tree.
  </Accordion>

  <Accordion title="What's in /storage and what's in / ?">
    * `/storage` is the writable partition (ROMS in the Flasher, the third partition), your ROMs, save-states, configs, screenshots, BIOS files. ext4. Use the full SD capacity after first-boot resize.
    * `/` is read-only system. ROOT partition, ext4. \~4.6 GB used, the rest is reserved for system updates / snapshots.
    * `/flash` is the BOOT partition, kernel, DTBs, panel overlays, U-Boot, fs-resize log. FAT32, 272 MB. Read-only at runtime; writable for flasher updates.
  </Accordion>

  <Accordion title="How do I update ArchR without losing my saves and configs?">
    Re-flash. The new image's first boot sees that `/storage` already has a `.config` and skips re-creation, preserving your saves and ROMs.

    Even safer: back up `/storage/roms/`, `/storage/.config/`, `/storage/saves/` over [SSH](/docs/ssh) before flashing, then restore after, same effect with no risk.
  </Accordion>

  <Accordion title="Can I run pacman?">
    No. ArchR is built LibreELEC-style, no package manager at runtime, no rolling updates. The "Arch Linux" in the name refers to the build environment, not the runtime. Updates ship as full image releases.
  </Accordion>

  <Accordion title="The first boot is slow / shows a blue screen for a while.">
    Normal, the first boot does a partition resize. About 30 seconds total, then automatic reboot, then ES. Subsequent boots are 19 seconds.
  </Accordion>

  <Accordion title="Why is the boot intermittent / hangs sometimes?">
    If you hit a hang, after the eventual successful boot run:

    ```bash
    cat /storage/.boot_last_hang
    ```

    That file only exists if the previous boot hung, its contents name the script that hung. Open an issue with that name and the dmesg snippet from `/var/log/boot.log`.

    (In v22+ a 60 s timeout on `archr-autostart.service` and a 10 s timeout on `drm_tool list` ensure the UI eventually comes up even if a script hangs.)
  </Accordion>

  <Accordion title="Why is the SSH default password published?">
    Because shipping a unique-per-device password requires either e-fuse provisioning at the factory (we don't have a factory) or a setup wizard on first boot (UX cost). Published default + clear instruction to change it on first login is the pragmatic compromise.

    Change it with `passwd` after first SSH login. Or use key-based auth and disable password login (instructions in [SSH](/docs/ssh)).
  </Accordion>

  <Accordion title="What emulators are included by default?">
    RetroArch + libretro core suite (\~250 cores total) covering NES/SNES/GB family/MD/MS/PSX/N64/Arcade/etc. plus standalones for the heavier systems: PPSSPP, Flycast, Mupen64Plus, DraStic, melonDS, Yabasanshiro, DuckStation. PortMaster is pre-installed for native PC ports.

    GameCube/Wii/Wii U/PS2/Switch/3DS are deliberately not exposed on RK3326, the A35 doesn't run them at playable speeds.
  </Accordion>

  <Accordion title="My panel is wrong / display garbled.">
    You picked the wrong panel overlay. Re-flash with the [ArchR Flasher](/docs/installation) and double-check the motherboard revision printed on the back of your device. The Flasher's panel dropdown matches the silkscreen text exactly.

    If you can't open the device, try flashing with the most generic overlay for your variant first; the colors will be off but the screen should be readable enough to find the right one.
  </Accordion>

  <Accordion title="Black screen / boot loop after switching GPU driver.">
    The `gpudriver` script auto-falls back if the chosen driver doesn't bind, so you should always end up with *some* graphics. If somehow you didn't:

    1. Power off, remove SD card, mount on a PC.
    2. On the STORAGE partition, edit `/storage/.config/system.cfg` → set `gpu.driver=libmali`.
    3. Reinsert and boot.

    (See [GPU driver](/docs/gpu-driver) for the full table.)
  </Accordion>

  <Accordion title="I want to contribute / build from source.">
    See [Build from source](/docs/build). The repo is at [github.com/archr-linux/Arch-R](https://github.com/archr-linux/Arch-R). Issues and PRs welcome.
  </Accordion>
</Accordions>


# Features



## Hardware [#hardware]

```
SoC          Rockchip RK3326 (4× Cortex-A35, in-order dual-issue)
CPU          1416 MHz default · 1512 MHz with "Enable CPU Overclock"
GPU          Mali-G31 MP2 (Bifrost), pinned at 650 MHz during gameplay
DRAM         1 GB DDR3L @ 924 MHz
Display      640×480 MIPI DSI (43 panel revisions covered)
Audio        RK817 codec, speaker, headphone jack, USB audio, HDMI audio
Network      WiFi 802.11n + Bluetooth (RTL/AP6611S/etc.), auto-detect
Battery      3200 mAh (rk817-battery + rk817-charger), LED warning at low
Storage      microSD (hot-swap supported, image works on any size 8 GB+)
```

***

## Software stack [#software-stack]

```
Kernel       6.12 LTS (BSP fork, board auto-detect via SARADC)
GPU driver   Panfrost (default) or libmali (toggle in ES)
              ├─ Mesa 26.0.5 with +speed +lto, NEON-optimised
              └─ zlib-ng for SIMD inflate/deflate (ROM zip 10–30% faster)
Init         systemd 255
Frontend     EmulationStation
Backend      RetroArch + 18 standalone emulators
Shell        bash + GNU coreutils (full PortMaster compatibility)
```

**CMA**: 96 MB (raised from 64 MB after audit found V4L2/Mali allocations
were tight in idle).

**ZRAM**: 512 MB lzo-rle (chosen over zstd because Cortex-A35 in-order
runs lzo-rle 3–4× faster).

***

## Pre-installed emulators [#pre-installed-emulators]

```
SNES, NES, GB/GBC/GBA, NDS, MD, MS, GG, PCE, NeoGeo, Atari (2600/5200/7800/Lynx/Jaguar),
WonderSwan, PC-FX, ColecoVision, Intellivision, Vectrex, ScummVM, DOS

PSX           pcsx_rearmed (default), beetle_psx_hw, swanstation, duckstation (software)
N64           Mupen64Plus standalone (GLideN64 performance / Rice fallback)
PSP           PPSSPP standalone (frameskip 3, FPS cap 30, GLTHREAD on)
Dreamcast     Flycast standalone (240 res, threaded rendering, GLTHREAD on)
Saturn        yabasanshiro standalone (experimental on A35)
Arcade        MAME 2003+, FBNeo, FBA-CPS1/CPS2/Neogeo
NDS           DraStic (default), melonDS as fallback
```

**Not included on RK3326**: GameCube, Wii, Wii U: Cortex-A35 doesn't run them at usable framerates, so they're hidden from the menu.

***

## Display panels [#display-panels]

43 pre-generated MIPI panel overlays:

* **15 original** (R36S V20–V22 board revisions, OGS variants)
* **18 clone** (K36, R33S, RX6S, R36 Max, multiple panel families)
* **10 soysauce** (Y3506-based hardware)

Overlay names mirror the motherboard revision exactly:

```
R36S-V21_2024-12-18_2551.dtbo
G80CA-MB_V1.3-20251212_Panel_8.dtbo
RX6S-2024_05_15-Panel_5.dtbo
```

The panel overlay is selected by the [ArchR Flasher](/docs/installation) at write time. The same image works on every board of a variant; only the overlay differs per panel.

***

## Network features [#network-features]

| Feature                   | Service                          | Default                   |
| ------------------------- | -------------------------------- | ------------------------- |
| WiFi                      | iwd + connman                    | auto-on if config present |
| Bluetooth audio + gamepad | bluez                            | enabled                   |
| Local play                | RetroArch netplay                | UDP discovery             |
| Remote play               | Tailscale / ZeroTier / WireGuard | opt-in via UI             |
| Sync ROMs/saves           | Syncthing                        | opt-in                    |
| Web server                | simple-http-server               | opt-in                    |
| Samba (file share)        | smbd + nmbd + wsdd               | opt-in                    |
| SSH                       | sshd                             | opt-in (ES toggle)        |

All "opt-in" services are paused automatically during gameplay so they don't compete with the emulator for CPU cycles.

***

## Boot timeline [#boot-timeline]

```
0.0 s    U-Boot start
0.7 s    Initramfs splash + DTB selection
~7 s     Kernel hand-off
~9 s     systemd target
~12 s    archr-autostart (quirks + governor + display)
~17 s    EmulationStation
~19 s    Ready to play
```

First boot adds \~10 s for the partition resize and creates ROM directories, only on the very first power-on after flashing.

***

## What's tuned for the RK3326 [#whats-tuned-for-the-rk3326]

Highlights of the RK3326-specific work (full list in [Technical](/docs/technical)):

* GPU OPP 650 MHz turbo at 1.150 V (same voltage as 600 MHz, avoided the original BSP 1.175 V which was unstable on some chips)
* CPU OPP 1512 MHz at 1.400 V with `vdd_arm` regulator-max bumped to 1.45 V (RK817 DCDC\_REG2 spec is 1.5 V max)
* `mali_kbase` PM patch, eliminates the regulator/clock unbalance warnings that were causing audio crackle in Mario 64
* BOOT partition 272 MB FAT32 with 4 KB clusters (above 65525 spec minimum + boot sector & backup auto-synced)
* `rq_affinity=2` on microSD I/O queue (irq landing on the issuing core)
* BFQ scheduler with `low_latency=1` and `read_ahead_kb=2048`


# GPU driver



Two GPU drivers are shipped. ArchR boots &#x2A;*Panfrost (Mesa)** by default, with **libmali** available as opt-in.

***

## Quick reference [#quick-reference]

|                    | Panfrost               | libmali                |
| ------------------ | ---------------------- | ---------------------- |
| Source             | Open-source (Mesa)     | Proprietary (ARM blob) |
| API                | OpenGL 3.1, GLES 3.1   | GLES 3.1 only          |
| Vulkan             | PanVK (experimental)   | Yes (Mali-G31 only)    |
| Default            | ✅                      | ,                      |
| Older RetroArch    | ⚠️ may need newer Mesa | ✅ closer to stock      |
| Active development | ✅ Mesa weekly          | Frozen at vendor BSP   |

***

## Switch driver [#switch-driver]

EmulationStation → **System Settings** → **Graphics** → **GPU driver** → choose `panfrost` or `libmali`. Reboot.

The setting persists in `/storage/.config/system.cfg` (`gpu.driver=panfrost|libmali`). On boot, the `gpudriver --start` script:

1. Loads the chosen kernel module (`panfrost` or `mali_kbase`)
2. Bind-mounts the right user-space libraries over Mesa
3. Masks the wrong Vulkan ICD JSON

If the chosen driver fails to bind to the GPU node (e.g. mali\_kbase reports a regulator error), the script automatically falls back to the other one so you get a graphical system either way.

***

## Why Panfrost is the default [#why-panfrost-is-the-default]

* **Mesa 26.0.5** has solid Mali-G31 (Bifrost v9) support, no missing extensions for any libretro core we ship.
* **MESA\_GLTHREAD** matrix tuned per-emulator (Flycast, PPSSPP) gives extra throughput.
* **Active upstream**: bug fixes land continuously; frozen vendor blob means stuck on whatever 2019 quirk shipped.
* **Same API surface** as libmali for everything except Vulkan.

***

## When to try libmali [#when-to-try-libmali]

Specific edge cases reported in community testing:

* A specific emulator / game shows render glitches under Panfrost
* You want to try Vulkan-via-mali (PanVK at G31 isn't conformant)
* libretro shader pack X works one way but not the other

The runtime fallback means switching is low-risk, if the chosen driver fails to attach to the GPU at boot, the system swaps to the alternate automatically.

***

## Mesa quirks applied (Panfrost path) [#mesa-quirks-applied-panfrost-path]

For RK3326 / Mali-G31, ArchR exports these globally for emulators:

```bash
PAN_MESA_DEBUG=forcepack            # forces format-pack on G31
                                    # (despite the name, NOT a debug flag)
MESA_NO_ERROR=1                     # skip GL error tracking
MESA_SHADER_CACHE_DIR=/storage/.cache/mesa_shader_cache
MESA_SHADER_CACHE_MAX_SIZE=128MB    # shader cache survives reboots
```

Per-emulator (only where benefit was confirmed):

```bash
MESA_GLTHREAD=true   # Flycast, PPSSPP standalone, see /docs/mesa-glthread-matrix
```

***

## Vulkan [#vulkan]

PanVK on Mali-G31 (Bifrost v9) is **not conformant**: the upstream Mesa team only ships PanVK officially for Mali-G610 (Valhall). ArchR disables PanVK at build time on RK3326 so emulators that probe for Vulkan don't try and fail.

If a future emulator update needs Vulkan and we've validated PanVK against it, the toggle would land in the same Graphics menu.

***

## Troubleshooting [#troubleshooting]

**Black screen after switching to Panfrost.** The DTBO overlay for your panel might not have loaded. Check with `cat /sys/class/drm/card0/connector/*/status`. Switch back to libmali via the recovery path:

1. Power off, remove the SD card
2. On a PC, mount the BOOT partition
3. Edit `/storage/.config/system.cfg` (on the storage partition), set `gpu.driver=libmali`
4. Re-insert and boot

**`gpudriver` warns "did not bind to GPU".** The auto-fallback already triggered, your effective driver is the *other* one. Check `journalctl -t gpudriver` (over [SSH](/docs/ssh)) for the exact message.

**Vulkan probe spam in logs.** Some PortMaster ports try Vulkan first. Harmless, they fall back to GLES.


# HDMI output



The R36S ships with a Mini-HDMI port. Plug it into a TV or monitor; ArchR auto-detects and mirrors. The default behaviour is good in 90% of cases, this page covers the 10%.

***

## Plug timing [#plug-timing]

**Connect HDMI before powering on**, when possible. Some R36S clones detect HDMI only at boot, hot-plug works partially (audio routes correctly, video may not).

If hot-plug doesn't pick up:

1. Plug the cable
2. Power off the device fully
3. Power back on with the cable connected

***

## Resolution [#resolution]

Default is to mirror the device panel resolution (640×480 on R36S) and let the TV upscale. If your TV handles non-standard 480p poorly, force a friendlier mode:

<Steps>
  ### Find your TV's preferred mode [#find-your-tvs-preferred-mode]

  Almost all modern TVs natively accept 1280×720\@60 or 1920×1080\@60. Pick one.

  ### Drop an autostart script [#drop-an-autostart-script]

  Over [SSH](/docs/ssh):

  ```bash
  mkdir -p /storage/.config/autostart
  nano /storage/.config/autostart/090-sway-hdmi-resolution
  ```

  Content:

  ```bash
  #!/bin/bash
  echo "output HDMI-A-1 resolution 1280x720" >> /storage/.config/sway/config
  ```

  (Replace `1280x720` with `1920x1080` for full HD.)

  ### Make it executable [#make-it-executable]

  ```bash
  chmod +x /storage/.config/autostart/090-sway-hdmi-resolution
  ```

  ### Reboot [#reboot]

  `sudo reboot`. Sway picks up the new config and the HDMI output runs at the requested resolution.
</Steps>

### Mirroring exactly [#mirroring-exactly]

If the TV is showing the device output offset / cropped, force the position:

```bash
echo "output HDMI-A-1 resolution 1280x720 position 0 0" >> /storage/.config/sway/config
```

***

## Audio [#audio]

ArchR automatically routes audio through HDMI when an HDMI cable is detected. To override (e.g. you want speakers on the device while the TV displays):

```bash
amixer set 'Playback Path' SPK
```

For stickier preference, edit `/storage/.config/system.cfg`:

```ini
audio.path=SPK
```

…and add a quirk in `/storage/.config/profile.d/050-audio_path` if needed.

***

## Why HDMI sometimes shows nothing on a clone [#why-hdmi-sometimes-shows-nothing-on-a-clone]

Clone devices ship with a different SPL/U-Boot than the original R36S. Some clones don't initialize HDMI at U-Boot stage at all, meaning you see no kernel messages or splash on the TV. The kernel still drives HDMI fine after boot, but if your TV insists on a signal during U-Boot to lock on, it may not display anything until ArchR is fully up.

There's no fix at the bootloader level today; the workaround is to power on with the device's internal panel as primary, then once ArchR is loaded, HDMI mirrors.

***

## Disabling the internal panel when on HDMI [#disabling-the-internal-panel-when-on-hdmi]

Some users prefer the device panel off when docked to a TV. Add to the same autostart script:

```bash
#!/bin/bash
echo "output HDMI-A-1 resolution 1280x720"     >> /storage/.config/sway/config
echo "output DSI-1     disable"                >> /storage/.config/sway/config
```

Reboot. Now the device's panel is dark, all output is on HDMI.

To revert: delete the autostart file, reboot.


# Documentation



Custom Linux distribution for the **R36S** and its variants, built on top of [ROCKNIX](https://github.com/ROCKNIX/distribution) with an Arch Linux build environment. Kernel 6.12 LTS, Mesa 26 Panfrost (open-source GPU), 43 pre-generated MIPI panel overlays covering every known motherboard revision.

Two images, both with hardware auto-detection:

* **Original**: for genuine R36S, R33S, Odroid Go family, Anbernic RG351V/M, GameForce Chi, MagicX XU10
* **Clone**: for K36 clones, EE Clone, Powkiddy RGB10/RGB10X/RGB20S, MagicX XU-Mini-M, BatLexp G350

<Cards>
  <Card title="Install in 3 minutes" href="/docs/installation" description="ArchR Flasher GUI or manual dd" />

  <Card title="Add ROMs" href="/docs/roms" description="Where to put games and BIOS files" />

  <Card title="Controls" href="/docs/controls" description="Hotkeys, K36/MyMini variants, JP layout" />

  <Card title="PortMaster" href="/docs/portmaster" description="Run native ports (Half-Life, Quake, Diablo II...)" />

  <Card title="SSH access" href="/docs/ssh" description="Remote shell, file transfer, debug" />

  <Card title="Features" href="/docs/features" description="Hardware specs and software stack" />
</Cards>

***

## What's different [#whats-different]

* **Open-source GPU driver** (Panfrost via Mesa 26.0.5), no proprietary blobs. `libmali` is also available as opt-in.
* **Two-image build with autodetect**: same image boots on every motherboard of a variant. SARADC reads the board ID at boot.
* **CPU overclock toggle**: switch in the ES menu lifts the cap from 1.4 GHz to 1.5 GHz when you need it.
* **Reproducible builds**: Docker-based, no hidden steps. `make docker-RK3326` produces both image variants.
* **Network play out of the box**: Syncthing, Tailscale, ZeroTier, RetroAchievements, scraping.
* **PortMaster pre-installed**: runs PC ports (Half-Life, Diablo II, Doom 3, Quake) on the device.

***

## Quick links [#quick-links]

* **[Releases →](https://github.com/archr-linux/Arch-R/releases)** download the latest image
* **[ArchR Flasher →](https://github.com/archr-linux/archr-flasher/releases)** GUI installer (Linux, macOS, Windows)
* **[Source →](https://github.com/archr-linux/Arch-R)** kernel + rootfs + image build
* **[Issues →](https://github.com/archr-linux/Arch-R/issues)** bug reports


# Installation



You only need a microSD card (8 GB+, 16 GB+ recommended) and 5 minutes. The recommended path is the **ArchR Flasher**: it picks the right image variant for your board, applies the correct panel overlay automatically, and verifies the write.

***

## Option 1, ArchR Flasher (recommended) [#option-1-archr-flasher-recommended]

The Flasher is a small desktop app (Tauri) that downloads the latest release, picks the correct panel overlay for your motherboard, writes the SD card, and verifies the write. Available for Linux, macOS and Windows.

<Steps>
  ### Download the Flasher [#download-the-flasher]

  Get the latest release from [archr-flasher releases](https://github.com/archr-linux/archr-flasher/releases).

  * **Linux**: `.AppImage` (no install) or `.deb` for Debian/Ubuntu/derivatives
  * **macOS**: `.dmg`
  * **Windows**: `.msi` installer

  ### Plug your microSD [#plug-your-microsd]

  8 GB or larger. The Flasher will erase **everything** on the card before writing, back up anything you need first.

  ### Pick the board / panel [#pick-the-board--panel]

  Open the Flasher and:

  1. Choose your **board variant**: Original or Clone. If unsure, check the back of your device or the [boards table](/docs/features#display-panels) on the Features page.
  2. Choose your **motherboard revision** from the dropdown (e.g. `R36S-V21_2024-12-18_2551`, `G80CA-MB_V1.3-20251212_Panel_8`). The Flasher reads the silkscreen text printed on the back of the motherboard.
  3. Optional toggles:
     * **Joypad variant**: Auto · K36 · MyMini (only matters for clones)
     * **JP layout**: Japanese button labels (A↔B, X↔Y swap)
     * **SRs (force simple audio)**: for boards with non-standard amplifier wiring
     * **Dno (skip vendor mode)**: disables the boot-time vendor screen on some boards

  ### Write [#write]

  Click **Flash**. The Flasher downloads the image (or uses the cache), wipes the SD, writes, then reads back to verify the SHA256.

  About 3 minutes total on a class 10 card.

  ### Boot [#boot]

  Insert the SD into the device, power on. First boot does an automatic partition resize and reboots once, total \~30 s. After the second boot you land in EmulationStation.
</Steps>

***

## Option 2, Manual `dd` [#option-2-manual-dd]

If you prefer the command line or are on Windows (use Rufus, Etcher, or the Raspberry Pi Imager equivalent).

<Steps>
  ### Download an image [#download-an-image]

  From [Arch-R releases](https://github.com/archr-linux/Arch-R/releases) grab one of:

  * `ArchR-R36S.aarch64-DATE-original.img.gz`, for genuine R36S
  * `ArchR-R36S.aarch64-DATE-clone.img.gz`, for K36 / clone hardware

  ### Decompress [#decompress]

  ```bash
  gunzip ArchR-R36S.aarch64-*.img.gz
  ```

  ### Identify the SD device [#identify-the-sd-device]

  ```bash
  lsblk
  # look for your card, usually /dev/sdX or /dev/mmcblkX
  ```

  <Callout type="warn">
    Double-check the device path. Writing to the wrong disk will erase it.
  </Callout>

  ### Write [#write-1]

  ```bash
  sudo dd if=ArchR-R36S.aarch64-*.img of=/dev/sdX bs=4M conv=fsync status=progress
  sync
  ```

  ### Apply panel overlay (manual path only) [#apply-panel-overlay-manual-path-only]

  The default image boots a generic panel overlay. If your screen is blank or distorted, mount the BOOT partition and copy the correct overlay:

  ```bash
  sudo mount /dev/sdX1 /mnt
  ls /mnt/overlays/   # see all 43 available overlays
  sudo cp /mnt/overlays/<your-mb-revision>.dtbo /mnt/overlays/mipi-panel.dtbo
  sudo umount /mnt
  ```

  Find your motherboard revision printed on the back of the board.

  ### Boot [#boot-1]

  Insert and power on. First boot resizes and reboots; second boot reaches ES.
</Steps>

***

## First boot [#first-boot]

After flashing, the **first** power-on does the following automatically and then reboots:

```
1. parted resizepart  → /storage uses the full SD
2. e2fsck + resize2fs → ext4 filesystem grows
3. tune2fs -U random  → fresh UUID
4. fsck.fat -a -w     → BOOT FAT primário/backup sincronizados
5. reboot
```

The resize log lives at `/flash/fs-resize.log` if you ever need to inspect it.

The **second** boot creates ROM directories (one per system) and lands in EmulationStation. From there you can [add ROMs](/docs/roms) and [enable SSH](/docs/ssh).

***

## Variants explained [#variants-explained]

| Variant    | U-Boot            | Boot logo | Hardware                                                                    |
| ---------- | ----------------- | --------- | --------------------------------------------------------------------------- |
| `original` | BSP Rockchip      | Yes       | R36S, R33S, Odroid Go family, Anbernic RG351, GameForce Chi, MagicX XU10    |
| `clone`    | Mainline v2025.10 | No        | K36, EE Clone, Powkiddy RGB10/RGB10X/RGB20S, MagicX XU-Mini-M, BatLexp G350 |

The two images differ **only** in U-Boot and panel overlay set. Kernel, rootfs, RetroArch, EmulationStation are identical.

***

## Troubleshooting [#troubleshooting]

**Black screen after the boot logo.** Wrong panel overlay. Re-flash with the correct motherboard revision selected, or copy the right `.dtbo` to `/flash/overlays/mipi-panel.dtbo` from another machine.

**Boot loops or hangs after first reboot.** Capture `cat /storage/.boot_last_hang` after the eventual successful boot, it names the script that hung. See [Troubleshooting](/docs/troubleshooting).

**"BOOT FAILED" on a clone device with the original image.** You picked the wrong variant. Use the clone image.

**Flasher says "image checksum mismatch".** The download was corrupt. Click "Flash" again; the Flasher re-downloads and retries.


# Netplay



RetroArch netplay lets up to 4 players play the same libretro core in real-time. Works over your home WiFi (LAN mode) or directly between two handhelds (device-to-device mode). Both devices must run **the same ArchR version** with **the same core**.

***

## Pre-flight [#pre-flight]

<Steps>
  ### Same version on both sides [#same-version-on-both-sides]

  ES → **System Information**: confirm matching ArchR version on host and clients.

  ### Enable netplay globally [#enable-netplay-globally]

  ES → **Game Settings** → **Netplay Settings** → **NetPlay** → ON. Also tap **Index Games** so RetroArch knows which ROMs you have.

  ### Same core, same ROM [#same-core-same-rom]

  Each player needs the same core (e.g. `snes9x_libretro`) and the same ROM file. RetroArch hashes the ROM, if hashes differ, connection fails.
</Steps>

***

## Option 1, over your home WiFi (LAN) [#option-1-over-your-home-wifi-lan]

### Host [#host]

ES → **Network Settings** → enable WiFi → disable **Local Play Mode** → set role &#x2A;*1 (Host)**.

In ES, highlight the game, press `Y` → **Netplay Options** → **Host a Netplay Session**. RetroArch starts in host mode and waits for clients.

### Clients (up to 3) [#clients-up-to-3]

ES → **Network Settings** → WiFi on → **Local Play Mode** OFF → role &#x2A;*2 / 3 / 4 (Client)**.

In ES, same game, `Y` → **Netplay Options** → **Connect to a Netplay Session**. Pick the host from the discovered list.

***

## Option 2, device-to-device (no router) [#option-2-device-to-device-no-router]

When you're away from your home WiFi (parks, road trips). One device acts as a hotspot, the other connects to it.

### Host [#host-1]

ES → **Network Settings** → **Local Play Mode** → ON → role &#x2A;*1 (Host)**.

ArchR creates a temporary WiFi access point on the host. Note the SSID + password it prints.

### Clients [#clients]

ES → **Network Settings** → connect to the host's SSID → **Local Play Mode** ON → role **2-4**.

Same game-launch flow as LAN play.

<Callout type="warn">
  Device-to-device mode disables internet, you can't scrape, RetroAchievements, or update while it's active.
</Callout>

***

## Game-side setup [#game-side-setup]

Both players launch the **same** ROM. RetroArch's session menu shows handshake status and frame buffer alignment. If you see "checksum mismatch", your ROMs aren't byte-identical (different region / dump).

For cores with rollback netcode (FBNeo, some 16-bit), RetroArch enables it automatically, input lag on a fast LAN feels close to local. For cores without rollback (most), play feels best when the host has the better connection, they run at near-zero lag, the client gets a few frames of buffered delay.

***

## Optimal host pick [#optimal-host-pick]

If you have one wired (eth-via-USB-C) device and one on WiFi, host on the wired one. RetroArch picks the host's frame as canonical, wired hosts mean fewer rollbacks.

If both are on WiFi, pick the device closer to the router as host.

***

## Compatible cores [#compatible-cores]

Any libretro core with `netplay = supported` in its info file. Quick list of known-working on RK3326 ArchR:

* snes9x2010, snes9x
* gambatte (GB/GBC), mgba (GBA)
* fceumm (NES), nestopia
* genesis\_plus\_gx (MD/MS/GG)
* fbneo (Arcade), rollback enabled
* mednafen\_psx\_hw (PSX)

Heavy 3D cores (mupen64plus\_next, ppsspp\_libretro) work technically but the A35 plus rendering load means stutter; not great experience.

***

## Troubleshooting [#troubleshooting]

**"Checksum mismatch"**: different ROM dumps. Use the no-intro / Redump version on both sides.

**"Connection timeout"**: host's IP is wrong (LAN mode) or hotspot isn't visible (device-to-device). In LAN mode, double-check both devices on the same subnet (`ip addr` over [SSH](/docs/ssh)).

**Lag spikes**: WiFi airtime contention. Move closer to the router, or disable Bluetooth on both devices during the session.

**Audio out of sync**: turn off the netplay audio buffer override. Quick Menu → Settings → Netplay → "Allow Asymmetric Frame Rate" → OFF.


# CPU Overclock



The R36S Cortex-A35 has a turbo OPP at 1512 MHz that sits dormant by default. Toggle it on for the games that need every Hz; leave it off for cooler / longer battery life on the rest.

***

## How to enable [#how-to-enable]

EmulationStation → \*\* \*\* (Start) → **System Settings** → **Performance** → **Enable CPU Overclock** → ON.

The toggle persists in `/storage/.config/system.cfg` (`enable.turbo-mode=1`) and is reapplied on every boot by `095-turbo-mode` autostart.

To turn it off, flip the toggle. No reboot required for either direction.

***

## What changes when it's on [#what-changes-when-its-on]

```
                 OFF (default)         ON
─────────────────────────────────────────────────
cpufreq/boost    0                     1
top freq idle    1416 MHz              1416 MHz
top freq game    1416 MHz              1512 MHz
voltage @ top    1.350 V               1.400 V
```

Idle/menu doesn't change, the governor decides on demand. Only when the CPU actually needs the top OPP does the extra \~7 % kick in.

During gameplay, `runemu.sh` switches the governor to `performance` and pins `scaling_max_freq` to the highest value `scaling_available_frequencies` exposes (which depends on whether boost is on).

***

## Why this exists [#why-this-exists]

Stock RK3326 BSP exposes 1512 MHz only as `turbo-mode` in the OPP table, the kernel hides it from `cpuinfo_max_freq` until `cpufreq/boost=1` is set. Plus, the `vdd_arm` regulator default in the upstream PX30 device tree is capped at 1.35 V, which is too low to drive 1.5 GHz reliably on most chips. ArchR raised that cap to 1.45 V (RK817 DCDC\_REG2 spec is 1.5 V), set the OPP to 1.4 V, and exposed the toggle.

Some chips run 1.5 GHz at 1.35 V fine. Some need 1.4 V. None have been reported failing at 1.4 V yet.

***

## When to use it [#when-to-use-it]

* **PSP** (PPSSPP standalone), God of War, Tekken 6, Daxter, small but consistent fps gain
* **Dreamcast** (Flycast), Crazy Taxi, Sonic Adventure 2, frametime smoothing
* **N64** (Mupen64Plus), heavy scenes (SM64 castle, Zelda OoT Hyrule Field)
* **PSX** (Beetle PSX HW), texture-heavy 3D
* **PortMaster**: box86/box64 ports that throttle at 1.4 GHz

For 2D / handheld / 8-16 bit cores, leaving it OFF is the right choice, they don't need it and you save battery + heat.

***

## Verify it's working [#verify-its-working]

Over [SSH](/docs/ssh):

```bash
# OFF expected: 0
# ON expected:  1
cat /sys/devices/system/cpu/cpufreq/boost

# OFF expected: 408000 816000 1008000 1416000
# ON  expected: 408000 816000 1008000 1416000  (turbo OPP shows up separately)
cat /sys/devices/system/cpu/cpufreq/policy0/scaling_available_frequencies

# ON expected: 1512000
cat /sys/devices/system/cpu/cpufreq/policy0/scaling_boost_frequencies

# Live freq during a game (run in a tight loop):
watch -n 0.5 cat /sys/devices/system/cpu/cpufreq/policy0/scaling_cur_freq
```

If you see `1512000` flowing through `scaling_cur_freq` while a heavy game runs, the overclock is active.

***

## Risks [#risks]

* **Thermals**: 1.5 GHz at 1.4 V dissipates more heat than 1.4 GHz at 1.35 V. The R36S is passively cooled; in a hot room, in a sustained heavy load, it will throttle sooner. The kernel handles this, it just means you cap closer to 1.4 GHz once temperature hits the passive trip (\~70 °C).
* **Battery**: \~10–15 % shorter battery life under heavy load with the overclock on. Negligible at idle / menu.
* **Per-chip variation**: a small minority of chips report instability at 1.5 GHz / 1.4 V. If your device reboots while playing PSP/DC, turn the toggle off as a first diagnostic.

***

## Reverting / disabling permanently [#reverting--disabling-permanently]

Toggle in ES → off. To force-off via shell (e.g. if ES is stuck):

```bash
echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost
sudo sed -i 's/^enable.turbo-mode=1/enable.turbo-mode=0/' /storage/.config/system.cfg
```


# PortMaster



[PortMaster](https://portmaster.games/) is a launcher / port repository that runs native PC binaries (Half-Life, Diablo II, Doom 3, Quake, Stardew Valley, Vvvvvv, …) directly on the handheld using `box86` / `box64` translation when needed. ArchR ships PortMaster pre-installed and pre-wired.

***

## What's included by default [#whats-included-by-default]

```
PortMaster GUI            /storage/roms/ports/PortMaster/
gptokeyb                  joypad → keyboard event translator
oga_controls              extra device-specific input glue
control.txt               default key map
SDL2 + lib32 / box86      32-bit x86 binaries via box86
SDL2 + box64              64-bit x86_64 binaries via box64
Python 3 + lzma           used by the GUI and many ports
```

Verified at boot:

```bash
python3 -c 'import lzma'   # works
ls -la /dev/uinput          # crw-rw-rw- (udev rule 91-uinput.rules)
```

***

## Run a port [#run-a-port]

<Steps>
  ### Open PortMaster [#open-portmaster]

  In EmulationStation, scroll to the **Ports** system. The first entry is "PortMaster", open it. The GUI launches.

  ### Browse / install [#browse--install]

  Press `B` on a port to install. Files land in `/storage/roms/ports/<port-name>/`. PortMaster downloads any data files (ROM-style assets aren't included, copy `wad`/`mpq`/etc. to the port folder per its README).

  ### Quit PortMaster GUI [#quit-portmaster-gui]

  `MODE + B` returns to ES. Installed ports appear as launchers (`.sh` files) in the **Ports** system list.

  ### Play a port [#play-a-port]

  Just like a ROM, select the launcher, press A. ArchR pauses background services (Syncthing, Tailscale, ZeroTier) for the duration, switches the CPU governor to `performance`, and pins the GPU at 650 MHz.

  ### Exit [#exit]

  Each port has its own hotkey, usually `MODE + START + SELECT`. Some use `MODE + START` alone. The combo is documented in the port's README inside `/storage/roms/ports/<port>/README.md`.
</Steps>

***

## Bring-your-own-data ports [#bring-your-own-data-ports]

Some ports ship only the engine. They expect you to drop the original game data into the port's folder. Examples:

| Port                       | What to drop                                                        |
| -------------------------- | ------------------------------------------------------------------- |
| **HalfLife**               | `valve/` and `cstrike/` from your Steam install                     |
| **Diablo II**              | `*.mpq` files from a legitimate copy                                |
| **Doom 3**                 | `pak*.pk4` from the retail install                                  |
| **Quake**                  | `id1/pak0.pak` and `pak1.pak`                                       |
| **Stardew Valley**         | `Content/`, `StardewValley.dll`, etc. from your Steam Linux install |
| **TombRaider**             | `data/` from the original CD                                        |
| **DevilutionX (Diablo I)** | `diabdat.mpq`                                                       |

PortMaster shows a per-port checklist of missing files in the GUI before letting you launch.

***

## Network play [#network-play]

PortMaster ports that support multiplayer (Quake, Half-Life DM, etc.) can use:

* **Tailscale** or **ZeroTier** for "internet LAN" play with friends, toggle on in ES → System Settings → Network.
* **Local LAN** broadcast, works out of the box; both devices need to be on the same WiFi.

ArchR keeps all VPN services paused until you launch a game that needs them, then resumes when you exit.

***

## Performance expectations [#performance-expectations]

Cortex-A35 + Mali-G31 is a budget SoC. Realistic baseline:

| Tier                    | Examples                                  | Expectation                                |
| ----------------------- | ----------------------------------------- | ------------------------------------------ |
| Native ARM, lightweight | Vvvvvv, Stardew Valley, Cute Fame, OpenRA | full speed, full battery life              |
| box86 (32-bit x86)      | Diablo II, Half-Life, Quake, Doom 3       | 25-60 fps depending on settings            |
| box64 (64-bit x86\_64)  | Newer indie titles (Hollow Knight class)  | playable but heavy, needs CPU Overclock on |
| Heavy 3D / RT           | DOOM Eternal, modern AAA                  | not viable                                 |

Toggle **Enable CPU Overclock** in ES (lifts cap from 1.4 → 1.5 GHz) for box86/64 ports that struggle.

***

## Troubleshooting [#troubleshooting]

**Port hangs at black screen.** Joypad permissions probably wrong. Check `ls -la /dev/uinput` returns mode `666`. If not, the udev rule didn't apply, `sudo chmod 666 /dev/uinput` for now and report a bug.

**`gptokeyb: Permission denied`.** Same as above.

**Port asks for missing data files.** Drop them in `/storage/roms/ports/<port>/` per the port's README. PortMaster's GUI lists missing files before launch.

**`box86: assertion failure`.** The port was built against a newer libstdc++ than what ArchR ships. Wait for an update or report it on the [PortMaster Discord](https://discord.gg/CMX5sTrgHQ).

**PortMaster GUI itself fails to start.** Run `start_portmaster.sh` over [SSH](/docs/ssh) and read the trace. The script is now idempotent (`rm -rf` + guards) so re-launching is always safe.

***

## Where things live [#where-things-live]

```
/storage/roms/ports/
├── PortMaster/             GUI + scripts (managed)
│   ├── PortMaster.sh
│   ├── control.txt         default joypad → key map
│   ├── gptokeyb            input translator
│   └── ...
├── DiabloII.sh             generated launcher per port
├── DiabloII/               actual port files
├── HalfLife.sh
├── HalfLife/
└── ...
```

Removing a port: delete the `.sh` and the matching folder, then ES → Game Settings → Rescan ROMs.


# RetroAchievements



[RetroAchievements](https://retroachievements.org/) is a community-run service that adds achievements (and leaderboards) to retro games. ArchR's RetroArch is wired up out of the box, sign in once and you start unlocking.

***

## Setup [#setup]

<Steps>
  ### Create an account [#create-an-account]

  Free at [retroachievements.org](https://retroachievements.org/createaccount.php).

  ### Get on the internet [#get-on-the-internet]

  ES → **System Settings** → **Network** → enable WiFi.

  ### Sign in [#sign-in]

  ES → **Game Settings** → **RetroAchievement Settings** → toggle **Enable RetroAchievements** ON, then enter your username and password.

  ### Optional toggles [#optional-toggles]

  In the same menu:

  * **Hardcore Mode**: disables save-states and rewind. Required to earn the *Mastered* badge.
  * **Unlock Sound**: plays the classic chime on every unlock.
  * **Automatic Screenshot**: saves the moment of unlock to `/storage/screenshots/`.
  * **Encore Mode**: re-trigger achievements you already earned.
  * **Verbose Mode**: show progress toward achievements with per-step hints.
</Steps>

***

## Which games / cores are supported [#which-games--cores-are-supported]

RetroAchievements only works with specific libretro cores and only on games that have an achievement set. Quick list of known-working on RK3326 ArchR:

| Console  | Core                             | Notes                   |
| -------- | -------------------------------- | ----------------------- |
| NES      | `fceumm`, `nestopia`             | huge catalog            |
| SNES     | `snes9x2010`, `snes9x`           | most games covered      |
| GB/GBC   | `gambatte`, `sameboy`            | full                    |
| GBA      | `mgba`                           | full                    |
| MD/MS/GG | `genesis_plus_gx`                | full                    |
| N64      | `mupen64plus_next`               | partial, heavy on A35   |
| PSX      | `mednafen_psx_hw`, `swanstation` | full                    |
| PSP      | `ppsspp_libretro`                | partial                 |
| NDS      | `melonds_ds`                     | partial                 |
| Arcade   | `fbneo`, `mame_2003`             | works with mame romsets |

Full list at [docs.retroachievements.org/Emulator-Support-and-Issues/](https://docs.retroachievements.org/Emulator-Support-and-Issues/).

Standalones (PPSSPP, Flycast, Mupen64Plus standalone, DraStic, melonDS standalone) **do not** route through RetroAchievements, only libretro cores do. If you want achievements on PSP/Dreamcast, use the libretro core (`ppsspp_libretro` / `flycast_libretro`) instead of the standalone.

***

## Hardcore vs softcore [#hardcore-vs-softcore]

| Hardcore ON                  | Hardcore OFF                                      |
| ---------------------------- | ------------------------------------------------- |
| No save-states               | Save-states allowed                               |
| No rewind                    | Rewind allowed                                    |
| No cheats                    | Cheats allowed                                    |
| Unlocks count toward Mastery | Unlocks count toward your profile but not Mastery |

Most people leave **Hardcore OFF** for normal play and turn it on for runs they want to officially record.

***

## Where unlocks are tracked [#where-unlocks-are-tracked]

* **In-game**: a notification shows on every unlock (top of the screen).
* **Online profile**: `https://retroachievements.org/user/<your-username>`. Profile, recent unlocks, leaderboards, master sets, everything is on the website.
* **Local screenshots**: if "Automatic Screenshot" is on, every unlock leaves a PNG in `/storage/screenshots/`.

***

## During gameplay performance [#during-gameplay-performance]

The RetroAchievements client polls memory each frame to detect achievement triggers. Net cost on RK3326 ≈ 0.5–1 % CPU per active achievement set, negligible for 8 / 16-bit cores, slightly noticeable on PSX/N64 if you're already CPU-bound.

The game doesn't have to be online during play, unlocks queue locally and sync on next internet contact. Useful for road trips.

***

## Troubleshooting [#troubleshooting]

**No unlocks happening even though I see the achievements list.** Wrong ROM dump. RetroAchievements matches by hash, if your ROM differs, no triggers fire. Use no-intro / Redump-verified dumps.

**"Login failed".** Re-enter username + password in the menu. Confirm `https://retroachievements.org` is reachable: `curl -sI https://retroachievements.org`.

**"Hardcore mode is disabled because save-state was loaded".** Once you load a state in a hardcore session, RA flips to softcore. Restart the core (Quick Menu → Reset) to re-enter hardcore.


# Adding ROMs



ROMs live on the **ROMS** partition (the larger of the two, formatted ext4 on Linux/macOS, accessible as a folder named `roms/` from the device). The folder layout mirrors EmulationStation's system list, one folder per system.

***

## Three ways to copy ROMs [#three-ways-to-copy-roms]

### 1. Plug the SD into a PC [#1-plug-the-sd-into-a-pc]

Mount the larger partition (label `ROMS`) and drop files into the per-system folders. Works from Linux/macOS natively. On Windows, Linux ext4 partitions need a driver like [Linux File Systems for Windows by Paragon](https://www.paragon-software.com/home/linuxfs-windows/) or [WSL with `--mount`](https://learn.microsoft.com/en-us/windows/wsl/wsl2-mount-disk).

### 2. SSH / SCP from your computer [#2-ssh--scp-from-your-computer]

Faster than re-plugging the SD. See [SSH access](/docs/ssh). Once connected:

```bash
scp ~/roms/snes/*.sfc root@<device-ip>:/storage/roms/snes/
```

### 3. Samba (Windows-friendly) [#3-samba-windows-friendly]

Enable Samba in EmulationStation menu → System Settings → Network → Samba. Then on your computer:

* **Windows**: open Explorer, type `\\archr` (or the IP).
* **macOS**: Finder → `Cmd-K` → `smb://archr.local`.
* **Linux**: file manager → "Connect to server" → `smb://archr.local/roms`.

The whole `/storage/roms/` tree is shared. Drop files in.

***

## Supported systems and folders [#supported-systems-and-folders]

```
/storage/roms/
├── nes/             .nes .zip
├── snes/            .sfc .smc .zip
├── n64/             .z64 .v64 .n64 .zip
├── gb/  gbc/  gba/  .gb .gbc .gba .zip
├── nds/             .nds
├── megadrive/       .md .gen .smd .bin .zip
├── mastersystem/    .sms .zip
├── gamegear/        .gg .zip
├── pcengine/        .pce .zip
├── neogeo/          .neo .zip   (BIOS in /storage/roms/bios)
├── psx/             .pbp .chd .iso .bin/.cue .ecm
├── psp/             .iso .cso .pbp
├── dreamcast/       .gdi .cdi .chd
├── saturn/          .chd .cue .iso (experimental on RK3326)
├── arcade/          .zip          (MAME 2003+ romset)
├── fbneo/           .zip
├── atari2600/  atari5200/  atari7800/  .a26 .a52 .a78 .bin
├── lynx/  jaguar/   .lnx .jag
├── ws/  wsc/        .ws .wsc
├── pcfx/  ngp/      
├── ports/           PortMaster .sh launchers, see /docs/portmaster
├── scummvm/         .scummvm short-cuts
├── dos/             .conf or .dosbox launchers
└── bios/            BIOS files for systems that need them
```

EmulationStation rescans on next boot. To trigger a manual rescan: ES menu → Game Settings → Rescan ROMs.

***

## BIOS files [#bios-files]

Some emulators need BIOS dumps you provide yourself (legality is on you, Arch R does not ship BIOS files).

```
/storage/roms/bios/
├── scph5500.bin       PSX (US)
├── scph5501.bin       PSX (Japan)
├── scph5502.bin       PSX (Europe)
├── PSP/               PSP, only if not using PPSSPP HLE
├── neogeo.zip         Neo Geo (MAME romset; often part of arcade/)
├── lynxboot.img       Atari Lynx
├── disksys.rom        Famicom Disk System
├── gba_bios.bin       GBA (mGBA HLE works without)
├── pcengine_cd.pce    PC Engine CD (PCE-CD games)
├── saturn_bios.bin    Saturn (Yabasanshiro)
└── dc/dc_boot.bin     Dreamcast (Flycast)
```

RetroArch tells you which BIOS is missing in the in-game menu (Quick Menu → Show in load core).

***

## Compressed ROMs [#compressed-roms]

Most cores accept `.zip` directly, the [zlib-ng](https://github.com/zlib-ng/zlib-ng) drop-in replacement that ArchR uses gives \~10–30 % faster decompression than plain zlib on the A35.

For PSX and Saturn, prefer `.chd` (Compressed Hunks of Data), it gives smaller files than `.bin/.cue` with zero decode loss. Convert with `chdman createcd -i game.cue -o game.chd`.

For PSP, prefer `.cso` over `.iso` to halve disk usage with negligible CPU cost.

***

## Sync ROMs between devices [#sync-roms-between-devices]

The optional **Syncthing** service keeps a folder identical between your handheld and your PC over LAN/WiFi. Useful if you want save-states and ROMs mirrored automatically without re-mounting the SD.

Enable: ES menu → System Settings → Network → Syncthing. The web UI lives at `http://archr.local:8384`.

The service is paused automatically while you're playing a game so it never competes for CPU.

***

## ROM scraping [#rom-scraping]

EmulationStation includes Skyscraper preconfigured. ES menu → Game Settings → Scraper → Start Scraper. Pulls metadata from ScreenScraper / TheGamesDB / Mobygames.

Pro tip: scrape with the device on AC power and the screen off (you can SSH in, run `pkill emulationstation && skyscraper -p <system>` and let it churn for an hour).

***

## Folder permissions / ownership [#folder-permissions--ownership]

The ROMS partition is mounted with `noatime`. ROM files don't need a specific owner, emulators run with file-mode permissions, and ArchR doesn't enforce ownership on the ROMS partition.

If you ever delete the per-system folders by accident, they're regenerated on next boot from `/storage/.config/system_directories.txt`.


# Samba (network share)



Samba lets your computer browse `/storage/roms/` (and your save-states, screenshots, configs) as a regular network share. Faster than re-mounting the SD; works without an SSH client.

***

## Enable [#enable]

EmulationStation → **System Settings** → **Network** → **Samba** → ON.

ArchR creates the trigger file `/storage/.cache/services/smbd.conf` and starts:

* `smbd`, the actual SMB server
* `nmbd`, NetBIOS name browser
* `wsdd2`, Windows 10/11 discovery (so the device shows up under "Network" in Explorer)

***

## Connect [#connect]

### Windows [#windows]

Open File Explorer and type into the address bar:

```
\\archr
```

If the device doesn't show up under "Network" automatically, force the address:

```
\\archr.local
\\<device-ip>
```

You'll see one share: &#x2A;*`roms`**: that's `/storage/roms/`. No login required by default; the share is open to the LAN.

### macOS [#macos]

Finder → **Go** → **Connect to Server** (`Cmd+K`) → enter:

```
smb://archr.local
```

Or use the IP. macOS will list the available shares; pick **roms**.

### Linux [#linux]

Most file managers (Nautilus, Dolphin, Nemo, Thunar) accept this in the address bar:

```
smb://archr.local/roms
```

Or mount it from CLI:

```bash
sudo mkdir /mnt/archr-roms
sudo mount -t cifs //archr.local/roms /mnt/archr-roms -o guest,uid=$(id -u),gid=$(id -g)
```

***

## What's shared [#whats-shared]

Default share `roms` exposes the entire `/storage/roms/` tree, read-write, no auth. From a security standpoint this is **LAN-only**: fine for home use, do not enable on a hostile network.

To add auth or change the share path, edit `/storage/.config/samba/smb.conf` over [SSH](/docs/ssh):

```ini
[roms]
   path = /storage/roms
   browseable = yes
   read only = no
   guest ok = yes        # change to "no" + set "valid users = archr"
```

Then `sudo systemctl restart smbd`.

***

## During gameplay [#during-gameplay]

Samba is paused automatically when you launch a game (along with Syncthing, Tailscale, ZeroTier, simple-http-server) and resumed when you exit. The pause is per-process, TCP connections keep their state on the client side and reopen when the service comes back.

***

## Troubleshooting [#troubleshooting]

**"Network discovery is turned off" on Windows.** Samba mDNS works but Windows network discovery is off in Settings → Network & Internet → Properties. Either turn it on, or just type `\\archr.local` directly.

**"The specified server cannot perform the requested operation".** Old SMB1 client trying to connect. ArchR ships SMB2/3 only. Update your OS or force the client to SMB2+.

**Permission denied writing to a folder.** The share is wide-open, but the per-folder permissions on the device default to mode `755`. From SSH:

```bash
sudo chmod -R 775 /storage/roms/<system>
```

**Slow transfers (\< 5 MB/s).** WiFi quality. Check `iwconfig wlan0` signal. The R36S has a small antenna, moving 3 m closer to the router typically doubles throughput.


# Scraping



Scraping fills your gamelist with cover art, screenshots, descriptions, release dates, and rating, the difference between a list of filenames and an actual library view. EmulationStation has scraping built in.

| Before                  | After                                          |
| ----------------------- | ---------------------------------------------- |
| `Super Mario World.sfc` | full SNES art + box + screenshot + description |

***

## Setup [#setup]

<Steps>
  ### Get a ScreenScraper account [#get-a-screenscraper-account]

  Free, mandatory: [register at screenscraper.fr](https://screenscraper.fr/membreinscription.php). Anonymous scraping rate-limits you to a trickle; an account is mostly to track requests.

  ### Connect your handheld to the internet [#connect-your-handheld-to-the-internet]

  ES → **System Settings** → **Network** → enable WiFi.

  ### Open the scraper [#open-the-scraper]

  ES → **Scraper** (top-level menu).

  ### Login [#login]

  Enter your ScreenScraper username + password in the Username / Password fields.

  ### Pick what to download [#pick-what-to-download]

  Tick which assets you want, screenshots, box art (2D and/or 3D), wheel logos, marquee, manuals, videos. Each adds bytes per game; for a 200-game library, **screenshots + box 2D + wheel** is a sane default.

  ### Pick which systems [#pick-which-systems]

  The scraper offers per-system selection. Skip systems that won't scrape well (PortMaster ports, custom collections).

  ### Start [#start]

  Press **Start Scraper**. ES walks the system list. Slow part: rate-limited by ScreenScraper.
</Steps>

***

## Recommended for the default Art Book Next theme [#recommended-for-the-default-art-book-next-theme]

Match the theme's expectations to avoid empty thumbnails:

| Setting      | Value                                              |
| ------------ | -------------------------------------------------- |
| Image Source | `Screenshot` (or `Box 2D` for boxart-first themes) |
| Box Source   | `Box 2D`                                           |
| Logo Source  | `Wheel`                                            |

See [themes](/docs/themes#recommended-settings) for the full pairing table.

***

## During gameplay [#during-gameplay]

The scraper takes nontrivial CPU and lots of small file I/O, don't run it while a game is running. If you want it to grind through 1000 games while you're away:

1. SSH in (so ES doesn't have to hold the screen on).
2. Stop ES with `sudo systemctl stop emustation`.
3. Sadly, the in-ES scraper won't run with ES stopped, there's no headless scraper in the ArchR build today.
4. Keep ES running but lock the screen: in ES, **System Settings** → **Screensaver Settings** → set timeout to 1 min, choose the "Black" screensaver. Plug in the charger.

ArchR pauses Syncthing/Tailscale/ZeroTier during emulation but not during scraping, those services keep running, so heavy scraping + active VPN means a bit of WiFi contention.

***

## Manual metadata [#manual-metadata]

Sometimes ScreenScraper gets the wrong region / wrong title (e.g. JP imports). Edit per-game:

ES → highlight game → press `Y` (Edit Metadata) → fix any field. Saved to `/storage/roms/<system>/gamelist.xml`.

If you want to bulk edit on a PC, just edit `gamelist.xml` directly with your favorite XML editor, ES picks up changes on rescan.

***

## Backup before scraping [#backup-before-scraping]

Big scrape sessions hit ScreenScraper rate limits and may leave half-populated metadata if interrupted. Before a long run, copy `/storage/roms/<system>/gamelist.xml` somewhere safe so you can roll back if you don't like the result.

```bash
ssh root@archr.local
cd /storage/roms/snes
cp gamelist.xml gamelist.backup.xml
```


# Shaders



RetroArch ships with hundreds of shaders that recreate CRT scanlines, LCD grids, NTSC artifacts, etc. ArchR enables them but defaults to **off**: A35 + Mali-G31 is tight, and naive multi-pass shaders will halve your framerate.

***

## Try a built-in shader [#try-a-built-in-shader]

<Steps>
  ### Launch a game [#launch-a-game]

  Any libretro core. Standalones (PPSSPP, Flycast, etc.) have their own shader systems; this guide is for libretro/RetroArch.

  ### Open the menu [#open-the-menu]

  `MODE + X` → Quick Menu → **Shaders**.

  ### Set Video Shaders to ON [#set-video-shaders-to-on]

  Then **Load Preset** → browse `shaders_glsl/`.

  ### Pick a preset [#pick-a-preset]

  Recommended starting points for the R36S 480p panel:

  | File path                              | Use case                    |
  | -------------------------------------- | --------------------------- |
  | `shaders_glsl/handheld/lcd1x.glslp`    | LCD grid for GB / GBA / NDS |
  | `shaders_glsl/handheld/lcd3x.glslp`    | Sharper LCD grid            |
  | `shaders_glsl/crt/crt-pi.glslp`        | Light CRT for arcade        |
  | `shaders_glsl/scanline/scanline.glslp` | Just scanlines, ultra-cheap |
</Steps>

The preset applies immediately. Back out of the menu to play.

***

## Save the preset for the system [#save-the-preset-for-the-system]

In the Shaders menu, **Save** → **Save Game Preset** (just this game) or **Save Core Preset** (every game on this core) or **Save Content Directory Preset** (all games in this folder).

Per-game presets land in `/storage/.config/retroarch/config/<core>/<game>.glslp`. Per-core in `/storage/.config/retroarch/config/<core>/<core>.glslp`.

***

## Build a custom multi-pass preset [#build-a-custom-multi-pass-preset]

The example below is the canonical "GBA real hardware" look, color-correct + LCD grid in two passes:

<Steps>
  ### Open Shaders, change passes to 2 [#open-shaders-change-passes-to-2]

  Quick Menu → Shaders → **Shader Passes** → 2.

  ### Pass 1, color correction [#pass-1-color-correction]

  Click pass 1 → browse to `shaders_glsl/handheld/` → choose `vba-color.glslp`.

  ### Pass 2, LCD grid [#pass-2-lcd-grid]

  Click pass 2 → browse to `shaders_glsl/handheld/` → choose `lcd1x.glslp`.

  ### Apply [#apply]

  Hit **Apply Changes**.

  ### Tune parameters [#tune-parameters]

  **Shader Parameters** is where each shader exposes its knobs. For this combo:

  * Darken: `0.25`
  * Brighten Scanlines: `28.0`
  * Brighten LCD: `6.0`

  ### Save [#save]

  Back at the Shaders menu → **Save** → set **Simple Presets** to **off** → **Save Shader Preset As** → name it (e.g. `gba-real-hw`).
</Steps>

The named preset shows up under **Load Preset** the next time, and is also selectable from ES → Game Settings → Per System Advanced Configuration → Shader Set.

***

## Performance budget [#performance-budget]

The R36S has very little overhead for shader passes. As a rule of thumb on RK3326 with overclock OFF (1.4 GHz CPU + 650 MHz GPU):

| Tier               | Ok?       | Examples                        |
| ------------------ | --------- | ------------------------------- |
| 1 cheap pass       | ✅         | scanline, lcd1x, vba-color      |
| 1 expensive pass   | usually ✅ | crt-pi, crt-easymode            |
| 2 cheap passes     | usually ✅ | gba-real-hw (vba-color + lcd1x) |
| 2 expensive passes | ⚠️        | crt-royale, crt-aperture-grille |
| 3+ passes          | ❌         | most CRT-Royale variants        |

Dreamcast / N64 / PSP cores already eat the GPU; even a 1-pass shader on top can drop you below 60 fps. Reserve fancy shaders for 8 / 16-bit cores.

Toggle **Enable CPU Overclock** if you want to try heavier shaders, see [Overclock](/docs/overclock).

***

## ROCKNIX-style shader sets via ES menu [#rocknix-style-shader-sets-via-es-menu]

ES exposes a shader-set picker without going into RetroArch:

ES → **Game Settings** → **Per System Advanced Configuration** → **Shader Set** → pick from the dropdown.

This applies the chosen shader to every game on that system. Useful as a quick toggle. Custom presets you saved earlier appear here too.


# SSH access



SSH is **off by default** for security. Turn it on through the EmulationStation menu, then connect from your computer.

***

## Enable SSH [#enable-ssh]

<Steps>
  ### Toggle in ES [#toggle-in-es]

  EmulationStation → \*\* \*\* (Start) → **System Settings** → **Network** → **Enable SSH** → ON.

  ArchR creates `/storage/.cache/services/sshd.conf` (the trigger file the systemd unit watches), then `systemctl start sshd`.

  ### Optional: enable on every boot [#optional-enable-on-every-boot]

  Same menu, leave the toggle on. The trigger file persists, so `sshd.service` starts at boot via `ConditionPathExists=`.

  ### Find the device's IP [#find-the-devices-ip]

  In ES → System Information shows IP. Or via ssh from any device on the same LAN:

  ```bash
  ping archr.local
  ```

  mDNS publishes `archr.local` automatically (Avahi).
</Steps>

***

## Connect [#connect]

```bash
ssh root@archr.local
# or with the IP:
ssh root@192.168.x.x
```

Default credentials:

```
user        root
password    archr
```

<Callout type="warn">
  Change the password after the first successful login. The default is published, anyone on the LAN can guess it.
</Callout>

```bash
passwd
```

***

## Key-based auth (recommended) [#key-based-auth-recommended]

```bash
# on your computer
ssh-copy-id root@archr.local
```

Then disable password auth on the device (over SSH already logged in):

```bash
sudo sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd
```

***

## File transfer [#file-transfer]

`scp` (one-shot copy) is the simplest way to move files. ROMs, save-states, screenshots:

```bash
# upload a ROM
scp game.sfc root@archr.local:/storage/roms/snes/

# download all screenshots
scp root@archr.local:'/storage/screenshots/*' ~/Pictures/r36s-screenshots/

# upload a directory
scp -r ~/roms/psx root@archr.local:/storage/roms/
```

For continuous sync, use `rsync` instead, it skips files that didn't change:

```bash
rsync -avh --delete ~/roms/snes/ root@archr.local:/storage/roms/snes/
```

For graphical access, your file manager probably supports `sftp://root@archr.local/storage/roms/`.

***

## SSH tips [#ssh-tips]

**EmulationStation in the way.** ES locks the framebuffer; you can't run an X/wayland program over SSH. But you can stop ES and run a one-shot tool:

```bash
sudo systemctl stop emustation
# now you can run things
sudo systemctl start emustation
```

**Long-running tasks (scrape, rsync TBs, etc.).** Use `screen` or `nohup` so they survive SSH disconnects:

```bash
screen -S scrape
skyscraper -p snes
# Ctrl-A D to detach. Reattach later: screen -r scrape
```

**Inspecting boot.** Logs land in `/var/log/boot.log` (not `journalctl`, journald is volatile). The autostart trace is in `/storage/.boot_last_step` only when the previous boot hung.

**Bench scripts.** `/flash/bench.sh <scenario> [duration]` collects PSI / freq / temp / vmstat for the given duration into `/storage/bench-results/`. Useful when reporting a perf regression.

***

## Disable SSH [#disable-ssh]

Same menu, toggle OFF. The trigger file is removed and `sshd.service` stops. The next boot doesn't start it.

***

## Security notes [#security-notes]

* **Public LAN risk**: with default creds and SSH on, anyone on the same WiFi can log in. Change the password.
* **Tailscale/ZeroTier**: if you enable a VPN, your device is reachable from anywhere on that VPN, same advice applies.
* **Port forwarding**: do **not** forward port 22 to your handheld from your home router. The default install isn't hardened for the public internet.
* **Disabling root**: `sudo passwd -l root` if you'd rather no one log in as root over SSH. The `archr` user has `sudo` for whenever you need elevated commands.


# Status



## Validated on hardware (R36S V21) [#validated-on-hardware-r36s-v21]

```
kernel              6.12.79                   ok
display             MIPI DSI                  ok    43 panel DTBOs
gpu / panfrost      Mesa 26.0.5               ok    Mali-G31, GLES 3.1
gpu / libmali       r52p0-00eac0              ok    PM patch eliminates regulator unbalance
gpu turbo 650 MHz   1.150 V (= 600 MHz V)     ok
cpu turbo 1512 MHz  1.4 V (regulator 1.45 V)  ok    toggle via Enable CPU Overclock
audio.spk           RK817                     ok    volume hotkeys, persistence
audio.hp            RK817                     ok    jack detect, auto path switch
audio.hdmi          rk-hdmi                   ok
emustation          ROCKNIX fork              ok    runs at panel refresh
retroarch           libretro                  ok    KMS/DRM + EGL + GLES 2.0
ppsspp-sa           v1.18+                    ok    GLTHREAD on
flycast-sa          recent                    ok    240 res default, GLTHREAD on
mupen64plus-sa      latest                    ok    GLideN64 performance preset
drastic-sa          NDS default               ok
yabasanshiro-sa     Saturn experimental       ok    light scenes only
duckstation-sa      Software renderer         ok
battery             rk817                     ok    3200 mAh, charge support, LED warning
brightness          sysfs + udev              ok    MODE+VOL, persists
usb_otg             u2phy                     ok    keyboard input
shutdown            pmic                      ok    two-stage rail disable
boot                initramfs splash          ok    19 s typical
zlib-ng             2.2.4 --zlib-compat       ok    libz.so.1 ABI preserved
mesa lto+speed                                ok    +5–8 % CPU side
cma 96 MB                                     ok    ~30 MB free at idle (was 8 MB at 64 MB)
boot fat sync                                 ok    primary == backup, 65 525+ clusters
fs-resize                                     ok    fsck.fat -a -w após fatlabel
runemu pause services                         ok    Syncthing/Tailscale/ZeroTier/HTTP suspended
ksm pause-during-game                         ok    save+restore, frametime jitter ↓
```

***

## In progress [#in-progress]

```
panel auto-detect       ⬜    replaces panel selector wizard
preempt voluntary A/B   ⬜    pending bench reproducibility
mesa-glthread per-core  ⬜    standalones done, libretro left as off
```

***

## Untested in 6.12 (carry-over from 6.6) [#untested-in-612-carry-over-from-66]

```
wifi networkmanager    ,    iwd + connman default; NM legacy carry-over
bluetooth controller   ,    a2dp not validated on this kernel
hdmi audio out         ,    on bench, no display tested yet
```

***

## Clone compatibility [#clone-compatibility]

```
                     Original R36S            Clone (K36, G80CA, RX6S, Powkiddy …)
u-boot               BSP (display+logo)       Mainline v2025.10 (no logo)
volume               gpio-keys-vol            adc-keys SARADC ch2
boot config          boot.ini                 boot.scr
display dtb          uboot-display.dtb        not needed
kernel               shared 6.12.79           shared
rootfs               shared                   shared
panel set            15 original DTBOs        18 clone + 10 soysauce DTBOs
```

***

## What's NOT supported on RK3326 [#whats-not-supported-on-rk3326]

These systems are explicitly hidden from the menu on RK3326 because the Cortex-A35 simply can't run them at usable framerates:

```
GameCube, Wii, WiiWare    not viable on A35
Wii U                     not viable
PS2 (AetherSX2)           not viable on A35
Switch (Yuzu/Ryujinx)     not viable
3DS (Citra)               not viable
```

Other RK3326 distros that *do* expose them effectively run them at slideshow-class FPS, ArchR doesn't lure users into trying.


# Technical reference



## Build pipeline [#build-pipeline]

`make docker-RK3326` runs through the full LibreELEC-style stage system inside Docker. Roughly 700 install steps for \~263 packages.

```
toolchain    cross-gcc 14.2 / glibc / binutils, host stage
linux        6.12 LTS kernel + RK3326 DTS + ArchR patches
mali-bifrost out-of-tree mali_kbase + ArchR PM unbalance patch
mesa         26.0.5 Panfrost (GLES 3.1, +speed +lto)
zlib (-ng)   zlib-ng 2.2.4 in --zlib-compat mode (libz.so.1)
retroarch    1.x + libretro core suite
emulators    Flycast, PPSSPP, melonDS, DraStic, Yabasanshiro, Mupen64Plus standalones
es           EmulationStation (ROCKNIX fork)
image        FAT32 BOOT (272 MB, 4 KB clusters) + ext4 ROOT + ext4 STORAGE
```

Output in `target/ArchR-R36S.aarch64-DATE-{original,clone}.img.gz`.

***

## Kernel [#kernel]

```
Source       Linux 6.12 LTS (BSP fork, Rockchip patches + ArchR)
Toolchain    gcc 14.2.0
Config       projects/ArchR/devices/RK3326/linux/linux.aarch64.conf
HZ           300
PREEMPT      CONFIG_PREEMPT=y (PREEMPT_VOLUNTARY A/B pending bench)
DEBUG        all sanitizers / KASAN / KMEMLEAK / FTRACE off in release
DEBUG_FS     y (intentional, needed for CMA debugfs and PSI introspection)
CMA          96 MB (raised from 64 MB after audit; see /docs/features)
ZRAM         lzo-rle by default (zstd opt-in via memory-manager)
ZSWAP        disabled (zswap.enabled=0 cmdline)
```

### DTS [#dts]

Source: `rk3326-gameconsole-r36s.dts` (board) + `rk3326-gameconsole-r3xs.dtsi` (board family) + `px30.dtsi` (SoC) + `000-rk3326-dts.patch` (ArchR overrides).

| Node                | What we changed                                                                    | Why                                                           |
| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `cpu0_opp_table`    | Added 1512 MHz turbo OPP @ 1.4 V; kept full 408–1416 ladder                        | Reachable via "Enable CPU Overclock"                          |
| `vdd_arm` regulator | `regulator-max-microvolt` 1.35 V → 1.45 V                                          | Otherwise kernel rejects 1512 OPP silently                    |
| `gpu_opp_table`     | Restored 200/300/400 MHz lower OPPs; added 600/650 MHz top                         | Lower OPPs needed for boot; 650 MHz is daily turbo at 1.150 V |
| `dmc` / `dfi`       | Defined explicitly so devfreq can be controlled                                    | Upstream px30.dtsi has them disabled                          |
| `gpu`               | Added `clock-names="bus"`, `resets`, `power_policy="coarse_demand"`, power\_models | Required for modern panfrost/mali\_kbase                      |
| `ethernet0` alias   | Added                                                                              | Future USB-Ethernet hot-plug naming                           |
| Power model         | `mali-simple-power-model` + `mali-g31-power-model`                                 | Thermal-aware DVFS                                            |

### Kernel patches [#kernel-patches]

Notable ArchR-specific kernel patches (`projects/ArchR/packages/linux-drivers/mali-bifrost/patches/6.12-LTS/` and `projects/ArchR/packages/linux/patches/6.12-LTS/`):

* **`mali-bifrost/002-fix-unbalanced-regulator-clk-pm.patch`**: eliminates `unbalanced disables for vdd_logic` warnings when `vdd_logic` is shared with rockchip-pm-domain. Adds a `gpu_power_held` flag tracking the driver's own enable state.
* **`linux/0005-drm-panfrost-Add-SYSTEM_TIMESTAMP*.patch`**: required by Mesa 26.0.5 for `GL_TIMESTAMP` queries and `VK_KHR_calibrated_timestamps`.
* **`linux/0006-drm-panfrost-Add-cycle-counter-job-requirement.patch`**: `VK_KHR_shader_clock` plumbing.
* **`linux/0007-0010-drm-panfrost-Add-BO-labelling*.patch`**: debug aid; Mesa calls the new IOCTL even though the labels are debug-only.

***

## Mesa 26.0.5 [#mesa-2605]

Built with `+speed +lto` in `packages/graphics/mesa/package.mk`. Configure flags:

```
-Dgallium-drivers=panfrost   -Dvulkan-drivers=
-Dgles1=disabled             -Dgles2=enabled
-Dglvnd=disabled             -Dplatforms=wl
-Dglx=disabled               -Dshader-cache=enabled
-Dopengl=true                -Dgbm=enabled
-Degl=enabled                -Dlibunwind=disabled
-Dbuild-tests=false          -Ddraw-use-llvm=false
```

`-Dgallium-drivers=panfrost` only, no software fallback shipped (LLVMpipe's overhead would dwarf hardware on G31). `-Dvulkan-drivers=` empty because PanVK isn't conformant on Bifrost v9.

### Runtime env [#runtime-env]

Exported globally in `/etc/profile.d/041-panfrost`:

```bash
PAN_MESA_DEBUG=forcepack             # G31-specific format-pack hint
MESA_NO_ERROR=1
MESA_SHADER_CACHE_DIR=/storage/.cache/mesa_shader_cache
MESA_SHADER_CACHE_MAX_SIZE=128MB
```

Per-emulator `MESA_GLTHREAD=true` whitelist, only Flycast & PPSSPP standalone (see [GPU driver](/docs/gpu-driver) and the in-repo `docs/mesa-glthread-matrix.md`).

***

## libmali (alternative) [#libmali-alternative]

Out-of-tree `mali_kbase` r52p0-00eac0 with the regulator/clk PM patch. Switched at boot via `/usr/bin/gpudriver --start` reading `/storage/.config/system.cfg → gpu.driver`. Auto-fallback if either driver fails to attach to the GPU node.

***

## U-Boot [#u-boot]

|             | Original                                        | Clone                            |
| ----------- | ----------------------------------------------- | -------------------------------- |
| Source      | `bootloader/u-boot-rk3326/` (BSP)               | mainline + ROCKNIX patches       |
| Boot config | `boot.ini`                                      | `boot.scr` (`mkimage -T script`) |
| Display     | hwrev SARADC ch0 → board DTB → DRM → `logo.bmp` | none                             |
| Defconfig   | `odroidgoa`                                     | `rk3326-handheld_defconfig`      |

The two binaries differ enough that you can't boot a clone with the BSP build. ArchR ships both, the build picks based on `--variant` (or `make docker-RK3326` produces both).

***

## Image layout [#image-layout]

```
GPT
├── 1   FAT32  BOOT     272 MB    65525+ clusters of 4 KB (FAT32 spec compliant)
│                       Kernel, DTBs, all 43 panel overlays, U-Boot script
├── 2   ext4   ROOT     ~4.6 GB   read-only system (squashfs in some legacy builds)
└── 3   ext4   STORAGE  rest      writable: configs, ROMs, save-states, screenshots
```

`mkimage` runs `fsck.fat -a -w` on the BOOT FAT before cementing the image, guarantees primary and backup boot sectors are byte-identical. The on-device `fs-resize` script does the same after `fatlabel` regenerates the UUID, so the post-resize boot stays consistent.

***

## Boot flow [#boot-flow]

```
0.0   POR / SPL (ROM-resident)
0.x   U-Boot reads SARADC ch0 → board ID
0.5   loads board DTB + panel overlay from /flash/
0.7   initramfs splash (BMP via xxd, static aarch64 /init)
~7    kernel hand-off
~9    systemd target
~12   archr-autostart (quirks + governor + display + bluetooth + ssh check)
~17   EmulationStation
~19   ready to play
```

Trace is written to `/storage/.boot_last_step` before each autostart script runs and erased on success, if the previous boot hung, the file at `/storage/.boot_last_hang` names the script that hung. Load it for bug reports.

***

## Display panels [#display-panels]

43 panel overlays generated from vendor DTB dumps:

```
config/archr-dts/
├── original/    (15)   R36S V20–V22, OGS variants
├── clone/       (18)   K36, R33S, R36 Max, RX6S, multiple panel families
└── soysauce/    (10)   Y3506-based hardware
```

The generator (`config/mipi-generator/generator.sh` → `archr-dtbo.py`) extracts panel init-sequence + timings from the vendor DTB, applies a base ArchR overlay template, and emits one `.dtbo` per motherboard revision. Six variants per panel are produced:

```
default                    K36 layout, no JP swap, normal audio
_JPk36                     K36 layout, JP A↔B / X↔Y
_JPmm                      MyMini layout, JP swap
_SRs                       force simple audio path
_JPk36_SRs                 K36 + JP + SRs
_JPmm_SRs                  MyMini + JP + SRs
```

258 DTBOs total. The Flasher (or manual copy) drops one of these into `/flash/overlays/mipi-panel.dtbo` at write time.

***

## Pitfalls [#pitfalls]

Edge cases that bit during development. None of them apply to a normal release flash, they only matter if you're hacking on the build.

**Hunk header counts in DTS patches matter.** A wrong `@@ -X,Y +A,B @@` count causes `patch` to silently abort the rest of the hunks, recovered "garbage". Validate with `patch --dry-run --verbose` on a pristine source after every DTS edit.

**`turbo-mode` OPPs hide behind `cpufreq/boost`.** Setting `scaling_max_freq=1512000` directly does nothing if `boost=0`, the freq isn't in `scaling_available_frequencies` until you write `1` to `cpufreq/boost`. ArchR's `set_cpu_max_freq highest` reads both `scaling_available_frequencies` *and* `scaling_boost_frequencies`.

**`vdd_arm` regulator-max gates OPP availability silently.** If an OPP requests a voltage above `regulator-max-microvolt`, kernel drops the OPP with no `dmesg`, and `policy_has_boost_freq()` returns false → `cpufreq/boost` sysfs file is **never created**.

**`fatlabel -i -r` desyncs FAT primary/backup.** It rewrites the UUID/label only on sector 0; backup at sector 6 keeps the old values. Some U-Boot builds occasionally read the backup, causing intermittent boot hangs after resize. Solution: run `fsck.fat -a -w` immediately after.

**`patch.fat` / `cluster < 65525` warnings are mostly harmless** but occasionally bite specific U-Boot ROM versions. ArchR uses `BOOT_SIZE=272 MB` with 4 KB clusters → 69500+ clusters → above spec.

**Mesa shader cache root must exist.** Mesa won't `mkdir` `MESA_SHADER_CACHE_DIR` itself, just falls through to no-cache mode silently. `runemu.sh` creates `/storage/.cache/mesa_shader_cache` if missing.

**`panfrost_devfreq` needs low GPU OPPs to initialize.** Removing 200/300/400 MHz OPPs (to force a higher floor) blocks GPU init at boot, the driver expects the lowest published OPP to be reachable. Keep the ladder; force a high floor at runtime with `set_gpu_min_freq highest` instead.

**`PREEMPT` vs `PREEMPT_VOLUNTARY` is unbenched.** Kernel currently uses `PREEMPT`; ROCKNIX uses `VOLUNTARY`. Pending A/B with the on-device bench.

**Mali\_kbase regulator unbalance is a kernel patch, not a quirk.** Without `002-fix-unbalanced-regulator-clk-pm.patch`, every PM transition emits `unbalanced disables for vdd_logic` and `Enabling unprepared clk_gpu`, audible as crackle in Mario 64.


# Themes



ArchR ships with [**Art Book Next**](https://github.com/anthonycaccese/art-book-next-es) as the default theme. It's the same theme ROCKNIX uses, designed to support every aspect ratio (16:9, 4:3, 16:10, 5:3, 3:2, 1:1). It's installed at `/usr/share/themes/es-theme-art-book-next` and symlinked into the user theme path as `system-theme`.

***

## Configure the default theme [#configure-the-default-theme]

ES → **UI Settings** → **Theme Configuration** has six knobs:

| Option                  | What it does                                                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Distribution**        | Which folder under your ROMs is checked for theme customizations. Leave at `ROCKNIX` (carry-over from upstream), it points at the right path. |
| **Aspect Ratio**        | Auto-detected (640×480 ≈ 4:3 on R36S). Override if the layout looks off.                                                                      |
| **Color Scheme**        | Pick a built-in color scheme or `custom` to use your own (see below).                                                                         |
| **Font Size**           | `default` or `custom`.                                                                                                                        |
| **System View Style**   | Layout for the home screen, Centered Artwork, Multi Artwork, Fullscreen Artwork, Carousel.                                                    |
| **Gamelist View Style** | Layout per game list, Metadata On / Metadata Off / Immersive variants.                                                                        |

***

## Recommended settings [#recommended-settings]

For an R36S (4:3, 640×480) with screenshots:

| Setting               | Value                                                   |
| --------------------- | ------------------------------------------------------- |
| Aspect Ratio          | `4:3` (auto)                                            |
| Scraper: Image Source | `Screenshot`                                            |
| Scraper: Box Source   | `Box 2D`                                                |
| Scraper: Logo Source  | `Wheel`                                                 |
| Gamelist View Style   | `Metadata On (Immersive)` or `Metadata Off (Immersive)` |

For boxart-first:

| Setting               | Value         |
| --------------------- | ------------- |
| Scraper: Image Source | `Box 2D`      |
| Scraper: Box Source   | `None`        |
| Scraper: Logo Source  | `Wheel`       |
| Gamelist View Style   | `Metadata On` |

***

## Customizing Art Book Next [#customizing-art-book-next]

Art Book Next reads customizations from a specific path so your changes survive ArchR updates:

```
/storage/roms/rocknix/theme-customizations/art-book-next/
```

(The folder name is `rocknix` because that's the upstream's distribution key, the theme reuses it across forks. Don't rename.)

### Background art [#background-art]

```
/storage/roms/rocknix/theme-customizations/art-book-next/backgrounds/
   _default.jpg          fallback for systems without a custom image
   snes.jpg              per-system override (filename = es system tag)
   psx.png
   ...
```

In Theme Configuration, set **System View Style** to one of the `(Custom)` variants:

* Centered Artwork (Custom)
* Multi Artwork (Custom)
* Fullscreen Artwork (Custom)

To craft a custom centered artwork that follows the theme's aspect mask, the original author publishes a [resources mask](https://github.com/anthonycaccese/art-book-next-es/tree/main/resources/customizations).

### Custom logos [#custom-logos]

```
/storage/roms/rocknix/theme-customizations/art-book-next/logos/
   snes.svg              SVG preferred (scales clean)
   psx.png
```

**Color Scheme** → `Custom` is what enables the override.

### Color scheme [#color-scheme]

[Download the template](https://github.com/anthonycaccese/art-book-next-es/blob/main/resources/customizations/colors.xml) → save as:

```
/storage/roms/rocknix/theme-customizations/art-book-next/colors.xml
```

Edit the values, set **Color Scheme** to `Custom`.

### Font size [#font-size]

[Download the template](https://github.com/anthonycaccese/art-book-next-es/blob/main/resources/customizations/fonts.xml) → save as:

```
/storage/roms/rocknix/theme-customizations/art-book-next/fonts.xml
```

Set **Font Size** to `Custom`.

***

## Adding additional themes [#adding-additional-themes]

Drop a third-party theme into:

```
/storage/.emulationstation/themes/
```

Each theme is its own folder. ES picks them up on next boot (or **UI Settings** → **Theme Set** → choose).

### Sources of compatible themes [#sources-of-compatible-themes]

ArchR's EmulationStation is forked from the same Batocera/ROCKNIX lineage, so themes designed for either generally work:

* **[Batocera themes](https://batocera.org/themes.php)**: large catalog. Some don't ship every system or fit non-16:9.
* **[es-theme-gbz35-jelos](https://github.com/booYah187/es-theme-gbz35-jelos)**: works well at 4:3.
* **[es-theme-albedo](https://github.com/mluizvitor/es-theme-albedo)**: 3:2, 4:3, 5:3.
* **[es-theme-elementerial](https://github.com/mluizvitor/es-theme-elementerial)**: 3:2, 4:3, 5:3.

<Callout type="info">
  Themes designed for portrait-oriented or 16:9 devices may look cramped on the R36S 4:3 panel. Test before committing, the theme picker is reversible.
</Callout>

***

## Writing your own theme [#writing-your-own-theme]

Out of scope for this page, but the [Batocera theme guide](https://wiki.batocera.org/write_themes_for_emulationstation) is the closest match for the EmulationStation flavour ArchR ships.


# Troubleshooting



## Boot issues [#boot-issues]

### Black screen, just the splash [#black-screen-just-the-splash]

Wrong panel overlay. Most common cause when first flashing a clone device with a recent motherboard revision.

**Fix:** re-flash with the [Flasher](/docs/installation) and pick the exact silkscreen-printed motherboard revision in the panel dropdown.

### Boot loops, never reaches ES [#boot-loops-never-reaches-es]

Three possibilities, in order of likelihood:

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

### Boot reaches ES but freezes there [#boot-reaches-es-but-freezes-there]

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

```bash
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>" [#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 [#display]

### Colors look wrong / inverted [#colors-look-wrong--inverted]

Panel BGR vs RGB swap, happens on a few clone variants where the silkscreen printed the wrong revision label. Re-flash with the next-numerically-similar revision.

### Screen "tearing" in some emulators [#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 [#brightness-has-fewer-steps-than-id-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.

***

## Audio [#audio]

### No sound at all [#no-sound-at-all]

```bash
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 [#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 [#bluetooth-audio-choppy]

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

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

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

***

## Performance [#performance]

### Game runs slower than expected [#game-runs-slower-than-expected]

In order:

1. **CPU governor**: should be `performance` during gameplay. Verify: `cat /sys/devices/system/cpu/cpufreq/policy0/scaling_governor`.
2. **GPU governor**: should be `performance`. `cat /sys/class/devfreq/ff400000.gpu/governor`.
3. **CPU max freq**: `cat /sys/devices/system/cpu/cpufreq/policy0/scaling_max_freq`. Without overclock = 1416000, with overclock = 1512000.
4. **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`).
5. **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 [#run-the-bench]

For repeatable diagnostics:

```bash
bash /flash/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 [#storage--roms]

### Some ROMs don't appear after copying [#some-roms-dont-appear-after-copying]

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

### "Disk full" but my SD is huge [#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:

```bash
sudo touch /storage/.please_resize_me
sudo reboot
```

### Save-states gone after re-flash [#save-states-gone-after-re-flash]

They live in `/storage/saves/`. If you re-flashed and the partition was wiped (Flasher always wipes), they're gone. Back up next time:

```bash
scp -r root@archr.local:/storage/saves ~/r36s-saves-backup/
```

***

## SSH / network [#ssh--network]

### Can't connect: "connection refused" [#cant-connect-connection-refused]

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

### "archr.local" doesn't resolve [#archrlocal-doesnt-resolve]

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

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

### WiFi connects but no internet [#wifi-connects-but-no-internet]

DNS issue. Try:

```bash
sudo systemctl restart connman
sudo connmanctl scan wifi
sudo connmanctl services
```

***

## PortMaster [#portmaster]

### Port hangs at black screen [#port-hangs-at-black-screen]

Most likely `/dev/uinput` permissions wrong. `ls -la /dev/uinput` should be `crw-rw-rw-` (mode 666). If not, the udev rule didn't apply, `sudo chmod 666 /dev/uinput` for now and report a bug.

### "Permission denied" running gptokeyb [#permission-denied-running-gptokeyb]

Same as above, uinput permissions.

### `box86: assertion failure` [#box86-assertion-failure]

The port was built against newer libstdc++ than ArchR ships. Wait for an update (PortMaster usually patches within days) or report at the [PortMaster Discord](https://discord.gg/CMX5sTrgHQ).

### PortMaster GUI itself fails to start [#portmaster-gui-itself-fails-to-start]

```bash
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 [#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 selected     ────  silkscreen-printed motherboard revision
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](https://github.com/archr-linux/Arch-R/issues).

For PortMaster specifically: [github.com/PortsMaster/PortMaster-GUI/issues](https://github.com/PortsMaster/PortMaster-GUI/issues).


# Updating ArchR



ArchR doesn't ship over-the-air updates today, every new version is a full image release. The good news: re-flashing **does not** wipe your `/storage` partition (it has your saves, ROMs, configs). Only the BOOT and ROOT partitions are overwritten.

***

## Update flow [#update-flow]

<Steps>
  ### Back up the things you can't easily re-create [#back-up-the-things-you-cant-easily-re-create]

  Even though `/storage` survives the re-flash, paranoid is good. Over [SSH](/docs/ssh):

  ```bash
  # from your PC
  scp -r root@archr.local:/storage/saves       ~/r36s-backup/saves/
  scp -r root@archr.local:/storage/states      ~/r36s-backup/states/
  scp -r root@archr.local:/storage/.config     ~/r36s-backup/config/
  scp -r root@archr.local:/storage/screenshots ~/r36s-backup/screenshots/
  ```

  ROMs are large; you don't need to back those up unless you've curated metadata in `gamelist.xml` per system.

  ### Power off cleanly [#power-off-cleanly]

  ES → power button (long press) → Power Off. Ensures any pending writes hit the SD.

  ### Flash the new image [#flash-the-new-image]

  Using the [ArchR Flasher](/docs/installation), pick the new image and the same panel/board you used before. The Flasher wipes the partition table and writes from scratch, wiping is what gives you a clean install.

  Alternatively: `dd if=ArchR-R36S.aarch64-DATE-*.img of=/dev/sdX bs=4M conv=fsync status=progress`.

  ### First boot [#first-boot]

  The first boot of the new image **resizes** the storage partition to use the full SD again, then reboots. Boot 2 sees that `/storage/.config` already has your data and skips re-creation. ROMs intact. Saves intact. Custom themes intact.

  ### Verify [#verify]

  ES boots. Your ROM library is there. Your save-states load. Your custom configs are intact.

  If something looks off, restore selectively from the backup you took in step 1.
</Steps>

***

## What gets reset by a re-flash [#what-gets-reset-by-a-re-flash]

| Path                                                    | Survives re-flash?                        |
| ------------------------------------------------------- | ----------------------------------------- |
| `/` (ROOT, ext4)                                        | ❌ Replaced                                |
| `/flash` (BOOT, FAT32)                                  | ❌ Replaced                                |
| `/storage/roms/`                                        | ✅ Survives                                |
| `/storage/saves/`                                       | ✅ Survives                                |
| `/storage/states/`                                      | ✅ Survives                                |
| `/storage/screenshots/`                                 | ✅ Survives                                |
| `/storage/.config/`                                     | ✅ Survives                                |
| `/storage/.cache/services/*.conf`                       | ✅ Survives, your enabled services persist |
| Theme overrides in `/storage/.emulationstation/themes/` | ✅ Survives                                |

Said differently: **everything you put on the SD as a user survives**. Everything that comes from the image gets replaced.

The only edge case: if you customized something in `/etc/` or `/usr/` directly (over SSH, as `root`), that's gone, those live on ROOT. Persistent customizations belong in `/storage/.config/` or `/etc/profile.d/` (which `045-userconfig` regenerates from `/storage/.config/profile.d/` if present).

***

## Going back [#going-back]

Same flow in reverse: re-flash an older image. `/storage` data created on a newer ArchR may have config schema deltas the older one doesn't recognise, usually it falls through to defaults gracefully, but in extreme cases (renamed settings) you may need to re-toggle a few options.

***

## Manual update (without the Flasher) [#manual-update-without-the-flasher]

If you only have an older `.img.gz`:

```bash
# decompress
gunzip ArchR-R36S.aarch64-*.img.gz

# write
sudo dd if=ArchR-R36S.aarch64-*.img of=/dev/sdX bs=4M conv=fsync status=progress

# (optional) verify checksum
sha256sum -c ArchR-R36S.aarch64-*.img.gz.sha256
```

The Flasher additionally wipes the FAT BOOT signatures (1 MB at start + 1 MB at end of the disk) before `dd`, which prevents stale partition tables from confusing U-Boot. Manual `dd` doesn't do this, if you see a black screen after re-flashing manually, run:

```bash
sudo dd if=/dev/zero of=/dev/sdX bs=1M count=1
sudo dd if=/dev/zero of=/dev/sdX bs=1M count=1 \
        seek=$(( $(blockdev --getsize64 /dev/sdX) / 1024 / 1024 - 1 ))
```

Then re-`dd` the image.

***

## When OTA arrives [#when-ota-arrives]

Future releases may ship `.tar` update bundles dropped at `/storage/.update/`, same mechanism ROCKNIX uses. Until then, re-flash is the path.


# VPN



ArchR ships three VPN options. All toggle from EmulationStation → **System Settings** → **Network** and are paused automatically during gameplay so they don't compete with the emulator for CPU.

***

## Tailscale [#tailscale]

Tailscale is a zero-config WireGuard-based VPN that lets your handheld talk to your PC anywhere on the internet, securely.

<Steps>
  ### Sign up [#sign-up]

  [Sign up for Tailscale](https://login.tailscale.com/start). Free for personal use up to 100 devices.

  Tailscale needs an SSO provider, Google, GitHub, Microsoft, or any of the [supported identity providers](https://tailscale.com/kb/1013/sso-providers).

  ### Install on your PC [#install-on-your-pc]

  [Download Tailscale](https://tailscale.com/download/) for your OS and log in.

  ### Enable on the handheld [#enable-on-the-handheld]

  ES → **Network Settings** → **Tailscale VPN** → ON.

  The first time, you'll see an authentication URL. Open it on your PC's browser, click **Connect**, and Tailscale binds the handheld to your tailnet.

  ### Disconnect [#disconnect]

  Same menu, toggle off.
</Steps>

After auth, your handheld appears under your tailnet's machines. SSH, file transfer, RetroArch netplay over the tailnet all work as if the device were on your local LAN.

***

## WireGuard [#wireguard]

For when you have your own VPN server (e.g. via your router or a self-hosted setup).

### Drop the config [#drop-the-config]

Provide a standard `wg0.conf` from your VPN provider or self-hosted server. Place it at:

```
/storage/.config/wireguard/wg0.conf
```

You can copy it via [SSH](/docs/ssh) or [Samba](/docs/samba).

Sample minimal config:

```ini
[Interface]
PrivateKey = <your private key>
Address    = 10.111.10.2/24

[Peer]
PublicKey  = <server public key>
AllowedIPs = 0.0.0.0/0
Endpoint   = <server>:<port>
```

<Callout type="warn">
  The `DNS` directive is **not** supported in this config. Remove any `DNS =` line or the connection won't come up.
</Callout>

### Toggle [#toggle]

ES → **Network Settings** → **WireGuard VPN** is only visible when `wg0.conf` exists. Toggle ON / OFF.

### Diagnose [#diagnose]

```bash
wg show                # active tunnel status
curl -4 ifconfig.co    # current public IP
wg-quick up   /storage/.config/wireguard/wg0.conf
wg-quick down /storage/.config/wireguard/wg0.conf
```

### Generate a keypair [#generate-a-keypair]

For self-hosting (use as the device side):

```bash
wg-genconfig          # writes wg0.conf and wg0.conf.server
```

The `.server` file goes on your Linux PC / Raspberry Pi acting as gateway. Uncomment the `PostUp` lines if you want to access other devices on your home LAN through it (SNAT).

***

## ZeroTier [#zerotier]

ZeroTier is similar to Tailscale but with a different network model, you create networks on your ZeroTier dashboard and join devices to them.

<Steps>
  ### Sign up [#sign-up-1]

  [Sign up at my.zerotier.com](https://my.zerotier.com), create a network, copy its 16-character ID.

  ### Drop the network ID [#drop-the-network-id]

  ```
  /storage/.config/zerotier-networks
  ```

  One network ID per line. Create the file via [SSH](/docs/ssh) or [Samba](/docs/samba).

  ### Enable [#enable]

  ES → **Network Settings** → **ZeroTier VPN** → ON.

  ### Approve in dashboard [#approve-in-dashboard]

  Back at [my.zerotier.com](https://my.zerotier.com) → your network → **Members**: your handheld appears as pending. Tick the **Auth** box.
</Steps>

### Manual join (alternative) [#manual-join-alternative]

Without the `zerotier-networks` file, you can run from [SSH](/docs/ssh):

```bash
zerotier-cli join <network-id>
zerotier-cli listnetworks
```

If you mix this with the file approach, the file wins on next boot, pick one.

***

## Which one to use [#which-one-to-use]

|                         | Tailscale   | WireGuard | ZeroTier   |
| ----------------------- | ----------- | --------- | ---------- |
| Easiest setup           | ✅           | ,         | ,          |
| Self-hostable           | partial     | ✅         | partial    |
| Subnet routing          | yes         | yes       | yes        |
| Persistent peer-to-peer | with NATs   | direct    | with NATs  |
| Free tier               | 100 devices | n/a       | 25 devices |

For most people: **Tailscale** if you want zero-config, **WireGuard** if you already have a VPN server, **ZeroTier** if you prefer their network model.

***

## During gameplay [#during-gameplay]

All three VPN services are paused automatically when a game launches via `runemu.sh` (alongside Syncthing and the simple HTTP server) and resumed when the game exits. The pause is per-process, TCP connections close on the client side and reconnect when the service comes back. For most uses (file sync, remote SSH) this is invisible.

If you specifically want a VPN on during gameplay (e.g. for online netplay over Tailscale), edit `/usr/bin/runemu.sh` and remove the service from the `pause_background_services` list. Heads-up: VPN traffic competes with WiFi airtime which is shared with Bluetooth, expect occasional crackle in BT audio.


# Áudio



O ArchR vem com PipeWire + ALSA sobre o codec RK817. A maioria das coisas funciona automaticamente; esta página documenta os casos de borda.

***

## Caminhos de saída [#caminhos-de-saída]

Seis sinks de áudio possíveis, escolhidos automaticamente:

```
SPK     alto-falantes internos (padrão se nada mais estiver conectado)
HP      saída de fone (auto-detectada via extcon)
HDMI    saída de áudio HDMI (quando um cabo HDMI está conectado)
USB     dispositivo de áudio USB (DAC, headset, gamepad com áudio)
BT      sink de áudio Bluetooth (fones / caixa pareados)
SIMPLE  fallback legado para placas clone com fiação de amplificador não-padrão
```

A detecção acontece em `/etc/profile.d/050-audio` no login e em hotplug via udev.

### Forçar um caminho [#forçar-um-caminho]

```bash
amixer set 'Playback Path' SPK    # alto-falantes
amixer set 'Playback Path' HP     # fones
amixer set 'Playback Path' HDMI   # HDMI
```

A configuração é resetada no próximo evento de hotplug. Para torná-la fixa, edite `/storage/.config/system.cfg` → `audio.path=SPK|HP|HDMI`.

***

## Volume [#volume]

Os botões de volume (VOL+ / VOL-) atuam diretamente no controle de mixer do **DAC**. Faixa 0-255, passo de 2 % por pressão, persiste entre reboots.

```bash
amixer get DAC                  # valor atual, 0..255
amixer cset numid=N <value>     # define explicitamente (descubra o numid com `amixer controls`)
```

O nível máximo do DAC no RK817 está limitado a 98 % para evitar chiados em alto-falantes pequenos de clones; isso é definido pelo quirk `050-audio_path` para RK3326 (ajuste do `Playback Mux`).

***

## Variante SR ("force simple audio") [#variante-sr-force-simple-audio]

Algumas placas-mãe de clones ligam o amplificador a um GPIO diferente do que a configuração padrão do codec RK817 espera. O Flasher oferece um toggle **SRs** que troca para um caminho de amplificador mais simples.

Se o seu dispositivo toca tudo pelo fone mas os alto-falantes ficam silenciosos independentemente do estado do jack, refaça o flash com **SRs** ligado.

A configuração mora no arquivo DTBO do painel. Não pode ser alterada em runtime; você precisa refazer o flash com o overlay correto ou copiar um `*_SRs.dtbo` diferente para `/flash/overlays/mipi-panel.dtbo` a partir de um PC.

***

## Áudio HDMI [#áudio-hdmi]

Conecte um cabo HDMI; a saída de áudio troca automaticamente. A porta HDMI é HDMI 1.4, suporta PCM estéreo a 48 kHz. Sem surround.

Se a tela funciona mas o áudio fica nos alto-falantes:

```bash
aplay -L | grep -i hdmi
amixer set 'Playback Path' HDMI
```

***

## Áudio USB [#áudio-usb]

A maioria dos dispositivos de áudio USB classe 1.0 (os DACs comuns, headsets, dispositivos de captura) funciona plug-and-play. O PipeWire os identifica via `auto-link`. Troque para saída USB:

```bash
pactl list sinks short
pactl set-default-sink <name-of-usb-sink>
```

***

## Áudio Bluetooth [#áudio-bluetooth]

Pareie pelo ES → System Settings → Bluetooth → Pair Device. Uma vez pareado, o áudio é roteado para lá automaticamente.

Ressalvas:

* **Latência**: A2DP é \~150 ms de mão única. Tudo bem para música, perceptível em jogos. O RK3326 não tem hardware aptX-LL.
* **Re-pareamento**: se a caixa não reconectar após o sleep, no menu BT do ES → Manage Paired Devices → Reconnect.
* **Alto-falante + BT simultâneos**: não suportado. O roteamento do PulseAudio é single-sink por vez.

***

## Backend de áudio por emulador [#backend-de-áudio-por-emulador]

```
RetroArch                ALSA via "alsathread" (fora do caminho do frame loop do libretro)
PPSSPP standalone        SDL2 audio → PipeWire
Flycast standalone       SDL2 audio → PipeWire
Mupen64Plus standalone   SDL2 audio → ALSA
DraStic                  SDL2 audio → ALSA
```

O `alsathread` para RetroArch troca alguns ms de latência por escalonamento previsível, importante em um A35 limitado por CPU.

***

## Troubleshooting [#troubleshooting]

**Alto-falantes chiam em jogos 3D pesados.** Builds anteriores ao v8 tinham um desequilíbrio de PM regulator no `mali_kbase` que perturbava o domínio de clock do áudio. Atualize para v8+. Se ainda acontecer: `dmesg | grep -iE 'vdd_logic|clk_gpu|mali'`. Resultado vazio é o que você quer.

**Áudio gagueja sob carga.** Quantum do PipeWire muito baixo. Edite `/storage/.config/pipewire/pipewire.conf.d/99-quantum.conf`:

```ini
default.clock.quantum = 1024
default.clock.min-quantum = 512
default.clock.max-quantum = 2048
```

Reinicie o PipeWire: `systemctl --user restart pipewire`.

**Áudio Bluetooth picotado / com drops.** Bitpool do SBC alto demais. Force qualidade menor: ES → BT → Manage Paired Devices → toggle "Force SBC".

**HP detectado mas alto-falantes continuam ligados (ou vice-versa).** Problema do driver extcon. Verifique `cat /sys/class/extcon/*/state`. Abra um bug com essa saída se ela não muda quando você conecta/desconecta.


# Bluetooth



O ArchR distribui BlueZ + backend bluetooth do PipeWire. Sem `bluealsa`: o roteamento de codec acontece pelo PipeWire, o que dá uma integração mais limpa mas significa que alguns dispositivos peculiares se comportam de forma diferente do que docs mais antigas sugerem.

***

## Parear um headset de áudio [#parear-um-headset-de-áudio]

<Steps>
  ### Habilite o Bluetooth [#habilite-o-bluetooth]

  ES → **System Settings** → **Controller & Bluetooth Settings** → **Enable Bluetooth** → ON.

  ### Coloque o headset em modo de pareamento [#coloque-o-headset-em-modo-de-pareamento]

  Consulte o manual do headset, normalmente é segurar o botão de power até o LED piscar rapidamente.

  ### Pareie pelo dispositivo [#pareie-pelo-dispositivo]

  No mesmo menu → **Pair a Bluetooth Device**. Espere o nome do headset aparecer e selecione-o.

  ### Direcione o áudio [#direcione-o-áudio]

  Uma vez pareado, ES → **System Settings** → **Audio Device** → escolha o dispositivo BT na lista. O ES reinicia; a saída agora vai pelo Bluetooth.
</Steps>

***

## Parear um gamepad [#parear-um-gamepad]

Mesmo menu, **Pair a Bluetooth Device**, coloque o gamepad em modo de pareamento (varia: a maioria dos gamepads Xbox/8BitDo tem um botãozinho de pareamento embaixo ou ao lado da porta USB).

Após o pareamento, o ES detecta o gamepad automaticamente e te pede para mapear os botões. O mapeamento é salvo por dispositivo em `/storage/.config/SDL2/gamecontrollerdb.txt`.

***

## Ressalvas no RK3326 [#ressalvas-no-rk3326]

O chip WiFi/BT do RK3326 está em uma única antena compartilhada. Implicações no mundo real:

* **Alcance é de \~3 m**: fones Bluetooth do outro lado do quarto vão gaguejar.
* **WiFi compete com BT pelo airtime**: uso pesado de rede durante o gameplay pode causar chiado no áudio. Pause Syncthing/Tailscale/ZeroTier durante o jogo (o ArchR faz isso automaticamente via `pause_background_services` no `runemu.sh`).
* **Latência A2DP** é \~150 ms. Tudo bem para música, perceptível em jogos rápidos. O ArchR não tem hardware aptX-LL.

***

## Seleção de codec [#seleção-de-codec]

O PipeWire escolhe o melhor codec que seu headset anuncia (LDAC > aptX > AAC > SBC). Force um codec mais baixo se tiver drops:

```bash
# inspecionar codec atual
pactl list sinks | grep -A 1 "Active Port"

# forçar SBC (universal, banda mais baixa)
pactl set-sink-port bluez_sink.<MAC>.a2dp-sink "speaker-output-sbc"
```

Para LDAC em bitrates mais altos a carga de CPU do A35 não é desprezível. Os perfis `mobile` (330 kbps) e `standard` (660 kbps) funcionam; `high` (990 kbps) em cima de um emulador é o bastante para causar chiado.

***

## Desconecte de forma limpa [#desconecte-de-forma-limpa]

Sempre desligue o BT no ES (ou despareie) antes de desligar. Cold-disconnect (apenas desligar o headset) às vezes deixa o PipeWire segurando um sink velho, o que significa nenhum áudio até reiniciar.

Se acontecer, via [SSH](/docs/ssh):

```bash
systemctl --user restart pipewire pipewire-pulse wireplumber
```

***

## Problemas conhecidos [#problemas-conhecidos]

* **Core PCSX-ReARMed**: silencioso sob áudio Bluetooth por razões desconhecidas (herança do upstream). Contorno: use o core libretro `pcsx_rearmed32` ou `swanstation`, ou o DuckStation standalone.
* **Reconnect-on-resume**: depois de um fake-suspend wake-up (quando o RK3326 suportar isso algum dia), o BT pode não reconectar. Reconexão manual no menu Bluetooth.


# Build a partir do código-fonte



O sistema de build do ArchR é totalmente reproduzível: `make docker-RK3326` gera as duas variantes de imagem a partir de um checkout limpo, idêntico ao release do GitHub. Sem passos escondidos, sem artefatos de código fechado.

***

## Requisitos [#requisitos]

* Docker (recomendado) ou um ambiente de build Linux nativo
* \~40 GB de espaço em disco livre (fonte em cache + árvores de build)
* \~8 GB de RAM recomendado (o build do kernel é o pico)
* Um host x86\_64 (a cross-toolchain tem como alvo aarch64)

Um build nativo leva \~2 h num x86 de 12 núcleos; o Docker adiciona \~5 % de overhead.

***

## Build rápido [#build-rápido]

```bash
git clone https://github.com/archr-linux/Arch-R.git
cd Arch-R

# Apenas na primeira vez: build do ambiente de build Docker
make docker-image-build

# Build das duas variantes de imagem para o R36S
make docker-RK3326
```

Saída em `target/`:

```
ArchR-R36S.aarch64-YYYYMMDD-original.img.gz
ArchR-R36S.aarch64-YYYYMMDD-clone.img.gz
*.sha256                                    # checksums para o flasher
ArchR-R36S.aarch64-YYYYMMDD.tar             # apenas o rootfs (para re-imagem)
```

***

## Todos os comandos [#todos-os-comandos]

| Comando                   | O que faz                                   |
| ------------------------- | ------------------------------------------- |
| `make docker-RK3326`      | Build completo em Docker, as duas variantes |
| `make RK3326`             | Build nativo (toolchain no host)            |
| `make docker-image-build` | (Re)build do container de build Docker      |
| `make clean`              | `rm -rf build.* target`                     |
| `make distclean`          | `clean` + apaga os caches de código-fonte   |

Para outros dispositivos: `make docker-RK3588`, `make docker-S922X`, etc. Veja as opções por dispositivo em `projects/ArchR/devices/`.

***

## Rebuilds incrementais [#rebuilds-incrementais]

O sistema de build usa **stamps** em `build.ArchR-RK3326.aarch64/.stamps/<package>` para pular pacotes já compilados. Para forçar o rebuild de um pacote específico:

```bash
rm -rf build.ArchR-RK3326.aarch64/.stamps/<pkg>
make docker-RK3326
```

Os mais comuns:

```
linux             kernel + DTS + módulos
mali-bifrost      módulo kernel libmali
mesa              Mesa Panfrost
retroarch         frontend RetroArch + frame libretro
ppsspp-sa         PPSSPP standalone
flycast-sa        Flycast standalone
archr             scripts / configs / runemu.sh
emulators         geração do es_systems.cfg
```

Após remover um stamp, `make docker-RK3326` reconstrói apenas aquele pacote e regera a imagem.

***

## Layout do projeto [#layout-do-projeto]

```
Arch-R/
├── packages/                       receitas de pacote estilo LibreELEC upstream
│   ├── compress/zlib/              (ArchR usa zlib-ng compat, veja PKG_NAME)
│   ├── graphics/mesa/
│   ├── linux/
│   └── ...
├── projects/ArchR/
│   ├── devices/RK3326/             patches, DTS, config de kernel específicos do RK3326
│   │   ├── linux/                  config de kernel + overrides de DTS
│   │   ├── patches/linux/          patches de kernel por versão
│   │   └── options                 vars no nível do device (BOOT_SIZE, ROOT_SIZE...)
│   ├── packages/                   pacotes específicos do ArchR sobre o upstream
│   │   ├── archr/                  scripts/runemu.sh, profile.d/, autostart/
│   │   ├── linux-drivers/mali-bifrost/   patch de kernel do libmali
│   │   ├── graphics/gpudriver/     chave panfrost ↔ libmali
│   │   ├── apps/portmaster/        PortMaster + scripts/start_portmaster.sh
│   │   ├── emulators/standalone/   cfg por dispositivo de PPSSPP/Flycast/melonDS/DraStic
│   │   └── ui/emulationstation/    patches do ES
│   └── options                     vars no nível do projeto
├── distributions/ArchR/
│   ├── options                     vars no nível da distro (BOOT_SIZE=272, ROOT_SIZE=4608...)
│   └── config/
├── config/
│   ├── archr-dts/                  43 revisões de placa × {original/clone/soysauce}
│   └── mipi-generator/             generator.sh + archr-dtbo.py (DTS → DTBO)
├── scripts/
│   ├── build                       driver de build por pacote
│   ├── extract                     extração de tarball
│   ├── image                       wrapper do mkimage
│   └── mkimage                     layout de partição, FAT32 BOOT, ext4 ROOT, ext4 STORAGE
├── tools/
│   ├── bench.sh                    benchmark no dispositivo (PSI, freq, temp)
│   ├── audit-build.sh              auditoria de build no dispositivo
│   └── ...
└── docs/                           docs internos de design / decision logs
```

***

## Edições comuns [#edições-comuns]

**Ajustar uma opção do kernel:**

```
projects/ArchR/devices/RK3326/linux/linux.aarch64.conf
```

Depois `rm -rf build.ArchR-RK3326.aarch64/.stamps/linux && make docker-RK3326`.

**Ajustar OPP / regulator da CPU:**

```
projects/ArchR/devices/RK3326/patches/linux/000-rk3326-dts.patch
projects/ArchR/devices/RK3326/linux/dts/rockchip/rk3326-gameconsole-r3xs.dtsi
```

**Adicionar um emulador padrão:**

```
projects/ArchR/packages/virtual/emulators/package.mk
projects/ArchR/packages/emulators/standalone/<emu-sa>/scripts/start_<emu>.sh
```

**Editar o caminho de trace do autostart:**

```
projects/ArchR/packages/sysutils/autostart/sources/autostart
```

***

## Validando um build [#validando-um-build]

`tools/audit-build.sh` roda no dispositivo e verifica:

```bash
bash /flash/audit-build.sh
```

...que nenhuma flag de debug do kernel passou, que todos os cores libretro estão stripados, que nenhum símbolo de sanitizer vazou pros binários. Use no CI.

`tools/bench.sh` coleta PSI / freq / temp / vmstat / dmesg numa janela de 60 s:

```bash
bash /flash/bench.sh psp 60
# inicie um jogo de PSP em um terminal / TTY separado
# os resultados ficam em /storage/bench-results/<timestamp>-psp/
```


# Sincronização na nuvem



Três abordagens para manter o `/storage` do seu handheld sincronizado com outra máquina. Escolha a que melhor se encaixa no seu cenário.

***

## Syncthing (peer-to-peer) [#syncthing-peer-to-peer]

Ideal quando você tem um PC ou outro handheld e quer sincronização contínua e automática sem envolver uma conta na nuvem.

### Configuração no handheld [#configuração-no-handheld]

1. ES, **System Settings**, **Network**, **Syncthing**, ON.
2. Anote o IP do dispositivo (visível em **System Information**).
3. Anote a senha do `root` em **Security** (padrão `archr`, troque ela).

### Configuração no seu PC [#configuração-no-seu-pc]

Instale o Syncthing pelo gerenciador de pacotes da sua distro ou em [syncthing.net](https://syncthing.net).

### Conectando os dois [#conectando-os-dois]

Acesse `http://<handheld-ip>:8384` no navegador do PC. Login: usuário `root`, senha a que você definiu.

Na interface web do handheld:

* **Add Remote Device**, cole o Device ID do PC (visível na interface do Syncthing do PC em Actions, Show ID). Dispositivos na mesma LAN se descobrem automaticamente, caso contrário cole manualmente.
* **Add Folder**, dê um rótulo (ex.: `roms`), caminho `/storage/roms`. Na aba **Sharing**, marque o PC.

No PC, aceite o dispositivo e a pasta recebidos. Escolha uma pasta local para espelhar. Pronto, a sincronização começa.

### O que sincronizar [#o-que-sincronizar]

| Pasta                  | Conteúdo                       | Sincronizar?             |
| ---------------------- | ------------------------------ | ------------------------ |
| `/storage/roms`        | Seus jogos                     | às vezes, são grandes    |
| `/storage/saves`       | Saves SRAM do RetroArch        | sim, pequenos e valiosos |
| `/storage/states`      | Save-states do RetroArch       | complicado, veja abaixo  |
| `/storage/screenshots` | Capturas de tela               | sim                      |
| `/storage/.config`     | Configurações de todos os apps | geralmente não           |

**Cuidado com save-states do RetroArch:** os states estão amarrados à **build exata do core**. Se o RetroArch do PC e o do handheld rodarem versões diferentes dos cores libretro, os states podem corromper. Saves (SRAM) independem da versão do core, states não. Sincronize `saves/` sempre; sincronize `states/` apenas se mantiver as versões dos cores idênticas.

O ArchR mantém o Syncthing pausado durante o jogo para nunca competir com o emulador por CPU. Ele retoma ao sair.

***

## rclone (armazenamento na nuvem) [#rclone-armazenamento-na-nuvem]

Para Google Drive / OneDrive / Dropbox / S3 / etc. O ArchR já vem com o rclone pré-configurado e com um wrapper em ES, **Tools**, **Cloud Backup** / **Cloud Restore**.

### Configuração [#configuração]

<Steps>
  ### Habilite o SSH [#habilite-o-ssh]

  [Como no guia de SSH](/docs/ssh).

  ### Configure seu provedor de nuvem [#configure-seu-provedor-de-nuvem]

  ```bash
  ssh root@archr.local
  rclone config
  ```

  Siga os prompts; consulte a [documentação dos providers do rclone](https://rclone.org/remote_setup/) para configuração OAuth headless, se necessário.

  ### Edite o `cloud_sync.conf` [#edite-o-cloud_syncconf]

  Padrão em `/storage/.config/cloud_sync.conf`. Chaves mais úteis:

  | Chave           | Padrão                 | Significado                                                                    |
  | --------------- | ---------------------- | ------------------------------------------------------------------------------ |
  | `BACKUPPATH`    | `/storage/roms`        | o que será copiado                                                             |
  | `RESTOREPATH`   | `/storage/roms`        | onde restaurar (diferente de `BACKUPPATH` para testar o restore com segurança) |
  | `BACKUPFOLDER`  | `/storage/roms/backup` | arquivos de backup local                                                       |
  | `SYNCPATH`      | `/GAMES`               | caminho no remoto da nuvem                                                     |
  | `BACKUPMETHOD`  | `sync`                 | `sync` espelha / `copy` adiciona sem apagar                                    |
  | `RESTOREMETHOD` | `copy`                 | `copy` preserva o local existente / `sync` sobrescreve                         |
  | `RCLONEOPTS`    | filtros e verbosidade  | conforme as [flags do rclone](https://rclone.org/flags/)                       |

  ### Execute um backup [#execute-um-backup]

  ES, **Tools**, **Cloud Backup**. O mesmo menu tem **Cloud Restore**.
</Steps>

### Logs [#logs]

```bash
tail -f /var/log/cloud_sync.log
```

### Regras de filtro [#regras-de-filtro]

`/storage/.config/cloud_sync-rules.txt` controla o que entra/sai. A versão `.defaults` ao lado é o template upstream, copie chaves de lá se quiser restaurar os padrões.

***

## NFS (servidor de arquivos na LAN) [#nfs-servidor-de-arquivos-na-lan]

Se você tem um NAS ou um PC Linux rodando um servidor NFS, dá para montar o share NFS por cima da pasta de jogos. As ROMs ficam no servidor; os saves ficam no handheld.

### Crie o arquivo de mount [#crie-o-arquivo-de-mount]

```
/storage/.nfs-mount
```

Uma única linha:

```
NFS_PATH=192.168.1.10:/srv/roms
```

### Monte [#monte]

ES, **Tools**, **Mount NFS**. O caminho remoto é montado em `/storage/games-external` e um merge overlay é criado em `/storage/roms`: saves vão para a camada superior local (`/storage/games-internal`), e as leituras dos jogos vêm do share NFS.

Isso é ótimo para coleções grandes. Guarde o romset de 200 GB do MAME num NAS e tenha o handheld vendo tudo em `/storage/roms/arcade`.

### Pegadinhas [#pegadinhas]

* NFS sobre WiFi é sensível à perda de pacotes; espere picos de latência ocasionais quando o sinal do WiFi oscila.
* ROMs que precisam de leituras aleatórias rápidas (cenas pesadas de seek em ISO de PSP) ficam melhores quando o arquivo é local. Copie seus títulos mais jogados para `/storage/games-internal/roms/` para usar o caminho local do overlay.
* O mount cai no `power-off` e reconecta no próximo boot se o arquivo ainda estiver presente.


# Coleções



As coleções do EmulationStation permitem criar listas de jogos que atravessam sistemas: todos os RPGs que você já teve, sua lista de "jogando agora", "amigável para crianças", "speedruns para experimentar". Elas convivem ao lado das listas por sistema na tela inicial.

Todas as configurações ficam em ES → **Game Collection Settings**.

***

## Três variações [#três-variações]

### Automatizadas [#automatizadas]

O ES traz coleções nativas para **Favorites**, **Last Played** e **All Games**. Habilite cada uma individualmente em **Automated Game Collections**.

Para adicionar um jogo aos **Favorites**: destaque-o e pressione `Y`. Pressione `Y` de novo para remover.

### Editáveis (curadas) [#editáveis-curadas]

Escolha um nome e percorra sua biblioteca marcando os jogos um a um.

ES → **Game Collection Settings** → **Create New Custom Collection** → dê um nome. Navegue até um jogo, pressione `Y` e, no seletor "Add to collection", escolha a nova coleção.

Útil para listas temáticas: `Final Fantasy series`, `Top 50 of all time`, `Kids`.

### Dinâmicas (baseadas em filtro) [#dinâmicas-baseadas-em-filtro]

Crie uma coleção orientada por filtros de metadados: todo jogo cujo gênero seja "RPG", todo jogo de 1992 a 1995, todo jogo com avaliação maior ou igual a 4 estrelas. Novos jogos que correspondem ao filtro aparecem automaticamente.

ES → **Game Collection Settings** → **Create New Custom Collection from Theme** → escolha **Dynamic** → defina os filtros.

Os filtros vêm dos metadados que você obteve via scraping. Veja [Scraping](/docs/scraping). Sem metadados raspados, coleções dinâmicas não têm nada para combinar.

***

## Now Playing: a ferramenta de backlog [#now-playing-a-ferramenta-de-backlog]

Uma coleção dinâmica nativa chamada **Now Playing**. Ela cura o punhado de jogos nos quais você está ativamente no meio, separado da biblioteca de 800 jogos.

Para ativá-la: ES → **Game Collection Settings** → **Create New Custom Collection from Theme** (com o tema Art Book Next ativo) → marque **Now Playing**.

Adicione um jogo: destaque-o, pressione `Y`, **Add to Collection**, **Now Playing**.

Inicie direto nela: ES → **Game Collection Settings** → **Start on System** → `Now Playing`, e também ative **Start on Gamelist**. Agora o ArchR inicializa direto no seu backlog ativo em vez da lista de sistemas.

***

## Esconda sistemas que você não usa [#esconda-sistemas-que-você-não-usa]

No mesmo menu, **Systems Displayed**: desmarque sistemas para os quais você não tem ROMs e deixe a tela inicial mais limpa. Os sistemas continuam existindo (as ROMs não são apagadas), eles apenas não aparecem.

Essa também é a forma de esconder sistemas vazios para plataformas das quais você nunca comprou ROMs.

***

## Onde as coleções ficam [#onde-as-coleções-ficam]

`/storage/.config/emulationstation/collections/`

Um arquivo `.cfg` por coleção. O formato é texto puro: um `<system-tag>:<rom-filename>` por linha para coleções editáveis, um bloco XML `<filter>` para as dinâmicas. Você pode editá-los em um PC se quiser, mas a interface do ES costuma ser mais amigável.


# Controles



## Atalhos padrão [#atalhos-padrão]

O R36S tem um botão `MODE` (ou `Function`). Combinado com outro botão, ele funciona como atalho.

```
VOL+ / VOL-               Volume (DAC de áudio, 2% por passo)
MODE + VOL+ / VOL-        Brilho (3% por passo, persiste entre reboots)
MODE + B                  Sai do emulador (volta ao ES)
MODE + X                  Abre o quick menu do RetroArch (só cores libretro)
MODE + R1                 Salva estado
MODE + L1                 Carrega estado
MODE + R2                 Próximo slot de save-state
MODE + L2                 Slot anterior de save-state
MODE + Y                  Tira screenshot (salva em /storage/screenshots/)
MODE + START              Reseta o emulador
MODE + SELECT             Alterna overlay de FPS/perf
```

Segure `POWER` por um tempo para abrir o menu de desligamento (suspender / reiniciar / desligar).

***

## Variantes de joypad [#variantes-de-joypad]

Clones do R36S usam uma de duas convenções de mapeamento de botões. O ArchR detecta a correta automaticamente com base no **perfil de placa** que você gravou, mas você pode forçar manualmente.

### Auto (padrão) [#auto-padrão]

O Flasher lê a revisão da placa-mãe e escolhe a variante certa:

* **Layout K36**: a maioria dos clones do R36S, incluindo K36, R33S, EE Clone
* **Layout MyMini**: hardware soysauce / Y3506 (por exemplo, lotes do meio de 2024)

### Override manual [#override-manual]

No [ArchR Flasher](/docs/installation), o dropdown **Joypad variant** força um layout específico. Útil se o Auto escolher errado (raro). Opções:

| Variante | Efeito nos botões físicos                               |
| -------- | ------------------------------------------------------- |
| Auto     | Detecta pela revisão da placa-mãe                       |
| K36      | Layout padrão Nintendo / Xbox                           |
| MyMini   | Layout espelhado (B↔A e X↔Y trocados em relação ao K36) |

### Trocando depois da gravação [#trocando-depois-da-gravação]

Edite `/storage/.config/system.cfg` via [SSH](/docs/ssh) e defina:

```ini
joypad.variant=K36     # ou MyMini
```

Reinicie.

***

## Layout JP [#layout-jp]

Toggle no Flasher em **JP layout**: troca A↔B e X↔Y para rótulos de botão estilo japonês (compatível com as posições físicas do Famicom / SFC).

Isso é puramente um remap de controle. As ROMs não precisam ser japonesas.

***

## RetroArch em jogo [#retroarch-em-jogo]

Pressione `MODE + X` para o Quick Menu. Sub-menus comuns:

```
Resume                    Volta para o jogo
State Slot                Escolhe o slot de save 0-9
Save State / Load State   Save in-place (mais rápido que save da ROM)
Take Screenshot           PNG em /storage/screenshots/
Options                   Ajustes por core (resolução, frameskip, BIOS)
Controls                  Remap on the fly
Cheats                    Lista de cheats (se houver .cht para a ROM)
Disk Control              Troca de disco em PSX multi-disco
Information               Core / sistema / autores
```

`MODE + B` sai sem passar pelo menu.

***

## Atalhos de emuladores standalone [#atalhos-de-emuladores-standalone]

Cada standalone tem seu próprio menu interno:

| Emulador                           | Hotkey do menu   |
| ---------------------------------- | ---------------- |
| PPSSPP                             | `MODE` (sozinho) |
| Flycast                            | `MODE` (sozinho) |
| Dolphin (não disponível no RK3326) | `MODE + X`       |
| DraStic (NDS)                      | `MODE` (sozinho) |
| Yabasanshiro (Saturn)              | `MODE + X`       |
| melonDS                            | `MODE` (sozinho) |

`MODE + B` sai de todos.

***

## Remaps customizados [#remaps-customizados]

Por sistema: menu do ES → Game Settings → Default Controllers (por sistema). Salvo em `/storage/.config/retroarch/config/<sistema>.cfg`.

Por jogo (ROM única): inicie o jogo → `MODE + X` → Controls → Save Game Remap File.

Override de hotkey customizada: edite `/storage/.config/retroarch/retroarch.cfg`, procure pelas chaves `input_hotkey_*`.

***

## Ports do PortMaster [#ports-do-portmaster]

Ports usam uma camada de input separada (`gptokeyb`) que traduz input de joypad em eventos de teclado para o binário original de PC. O mapeamento padrão fica em `/storage/roms/ports/PortMaster/control.txt`. A maioria dos ports sobrescreve com sua própria configuração.

Hotkey in-game para sair de um port: geralmente `MODE + START + SELECT` ou apenas `MODE + START`. Cada port documenta sua própria combinação.


# FAQ



<Accordions>
  <Accordion title="Quais dispositivos são suportados?">
    O R36S (genuíno e todos os clones conhecidos) e a família RK3326 mais ampla: Odroid Go Advance / Super, Anbernic RG351V/M, GameForce Chi, MagicX XU10/XU-Mini-M, BatLexp G350, Powkiddy RGB10/RGB10X/RGB20S. 43 revisões de placa-mãe, somando as duas variantes da imagem.

    Se o seu dispositivo tem um SoC Rockchip RK3326 e um painel MIPI suportado, é quase certo que funciona.
  </Accordion>

  <Accordion title="Como isto se diferencia do ArkOS / ROCKNIX / dArkOS?">
    * **Stack de GPU open-source**: Panfrost via Mesa 26.0.5 por padrão; libmali ainda disponível como opcional.
    * **Construído sobre o ROCKNIX** com um ambiente de build Arch Linux: mesmo pipeline de release, convenções de userspace diferentes.
    * **Runtime mais limpo**: `runemu.sh` é controlado por loglevel (sem `set -x` permanente), Saturn/Wii/GC ocultos no A35, kill do gptokeyb é defensivo etc.
    * **Build de duas imagens com autodetect**: a mesma imagem funciona em qualquer placa-mãe da variante; o SARADC lê o ID da placa no boot.
    * **Turbo de CPU é opt-in pela UI**: sem overclock até você ligar. Default amigável à bateria.
    * **Reprodutível**: `make docker-RK3326` bate byte a byte com o release no GitHub.
    * **PortMaster pré-instalado + Python lzma + regra udev para /dev/uinput**: os ports funcionam sem nenhum preparativo.
  </Accordion>

  <Accordion title="O mesmo cartão SD funciona em placas R36S diferentes?">
    Sim, dentro de uma mesma *variante*: SDs de imagem original funcionam em qualquer placa de variante original, e SDs de imagem clone em qualquer placa de variante clone. O DTB da placa é selecionado no boot pelo SARADC.

    Entre variantes (original ↔ clone) o U-Boot é diferente, então um SD original não dá boot num clone nem vice-versa. Regrave com a variante correta.
  </Accordion>

  <Accordion title="Por que a CPU não roda a 1.5 GHz por padrão?">
    Porque 1.4 GHz é um default melhor. É estável em todo chip que testamos com os 1.35 V mais baixos, esquenta menos e oferece uma autonomia de bateria perceptivelmente maior. Subir para 1.5 GHz precisa de 1.4 V na maioria dos chips, eleva a temperatura, e só ajuda nos jogos realmente pesados de CPU (PSP pesado, Dreamcast pesado, ports box86).

    Ligue "Enable CPU Overclock" em System Settings → Performance quando você realmente precisar. Veja [Overclock](/docs/overclock).
  </Accordion>

  <Accordion title="O que é MESA_GLTHREAD e por que está ligado só em alguns emuladores?">
    É uma opção do Mesa que move o processamento de comandos GL para uma thread separada. Ajuda quando uma aplicação emite muitas chamadas GL pequenas e tem sua própria thread de render: Flycast e PPSSPP standalone se encaixam nesse perfil. Atrapalha quando uma aplicação usa muito fence/glReadPixels, caso da maioria dos cores libretro 2D.

    O ArchR usa uma whitelist (desligado por padrão, opt-in por emulador) para não regredir cores 2D. Matriz completa em `docs/mesa-glthread-matrix.md` no código-fonte.
  </Accordion>

  <Accordion title="O que vai em /storage e o que vai em / ?">
    * `/storage` é a partição gravável (ROMS no Flasher, a terceira partição): suas ROMs, save-states, configs, screenshots, arquivos de BIOS. ext4. Usa toda a capacidade do SD após o resize do primeiro boot.
    * `/` é o sistema read-only. Partição ROOT, ext4. \~4.6 GB usados, o restante reservado para atualizações de sistema / snapshots.
    * `/flash` é a partição BOOT: kernel, DTBs, panel overlays, U-Boot, log do fs-resize. FAT32, 272 MB. Read-only em runtime; gravável para atualizações via flasher.
  </Accordion>

  <Accordion title="Como atualizo o ArchR sem perder meus saves e configs?">
    Regrave. No primeiro boot da nova imagem ele detecta que `/storage` já tem `.config` e pula a recriação, preservando saves e ROMs.

    Ainda mais seguro: faça backup de `/storage/roms/`, `/storage/.config/`, `/storage/saves/` por [SSH](/docs/ssh) antes de gravar, e restaure depois. Mesmo efeito, sem risco.
  </Accordion>

  <Accordion title="Posso rodar pacman?">
    Não. O ArchR é construído no estilo LibreELEC: sem gerenciador de pacotes em runtime, sem atualização rolling. O "Arch Linux" no nome se refere ao ambiente de build, não ao runtime. Atualizações são distribuídas como releases de imagem completa.
  </Accordion>

  <Accordion title="O primeiro boot é lento / mostra uma tela azul por um tempo.">
    Normal. O primeiro boot faz um resize de partição. Cerca de 30 segundos no total, depois reboot automático, depois ES. Os boots seguintes levam 19 segundos.
  </Accordion>

  <Accordion title="Por que o boot é intermitente / às vezes trava?">
    Se acontecer uma trava, depois do boot bem-sucedido seguinte, rode:

    ```bash
    cat /storage/.boot_last_hang
    ```

    Esse arquivo só existe se o boot anterior travou. O conteúdo dele nomeia o script que travou. Abra uma issue com esse nome e o trecho de dmesg de `/var/log/boot.log`.

    (Na v22+ existe um timeout de 60 s em `archr-autostart.service` e um de 10 s em `drm_tool list` para garantir que a UI eventualmente apareça mesmo que algum script trave.)
  </Accordion>

  <Accordion title="Por que a senha padrão do SSH é pública?">
    Porque entregar uma senha única por dispositivo exige ou provisionamento por e-fuse na fábrica (não temos fábrica) ou um assistente de configuração no primeiro boot (custo de UX). Default publicado + instrução clara para trocar no primeiro login é o compromisso pragmático.

    Troque com `passwd` depois do primeiro login SSH. Ou use autenticação por chave e desabilite o login por senha (instruções em [SSH](/docs/ssh)).
  </Accordion>

  <Accordion title="Quais emuladores vêm por padrão?">
    RetroArch + conjunto de cores libretro (\~250 cores no total) cobrindo NES/SNES/família GB/MD/MS/PSX/N64/Arcade/etc., mais standalones para os sistemas mais pesados: PPSSPP, Flycast, Mupen64Plus, DraStic, melonDS, Yabasanshiro, DuckStation. O PortMaster vem pré-instalado para ports nativos de PC.

    GameCube/Wii/Wii U/PS2/Switch/3DS são deliberadamente ocultos no RK3326. O A35 não os roda em velocidade jogável.
  </Accordion>

  <Accordion title="Meu painel está errado / o display está embaralhado.">
    Você escolheu o panel overlay errado. Regrave com o [ArchR Flasher](/docs/installation) e confirme a revisão da placa-mãe impressa no verso do dispositivo. O dropdown de painel do Flasher corresponde exatamente ao texto da silkscreen.

    Se você não consegue abrir o dispositivo, tente gravar primeiro com o overlay mais genérico para a sua variante; as cores ficarão estranhas, mas a tela deve estar legível o suficiente para você achar a certa.
  </Accordion>

  <Accordion title="Tela preta / boot loop depois de trocar o GPU driver.">
    O script `gpudriver` faz fallback automático se o driver escolhido não conseguir se ligar, então você sempre deve acabar com *algum* gráfico. Se de alguma forma não acabar:

    1. Desligue, remova o SD e monte em um PC.
    2. Na partição STORAGE, edite `/storage/.config/system.cfg` → defina `gpu.driver=libmali`.
    3. Recoloque o SD e dê boot.

    (Veja [GPU driver](/docs/gpu-driver) para a tabela completa.)
  </Accordion>

  <Accordion title="Quero contribuir / compilar a partir do código-fonte.">
    Veja [Build from source](/docs/build). O repositório está em [github.com/archr-linux/Arch-R](https://github.com/archr-linux/Arch-R). Issues e PRs são bem-vindos.
  </Accordion>
</Accordions>


# Funcionalidades



## Hardware [#hardware]

```
SoC          Rockchip RK3326 (4× Cortex-A35, in-order dual-issue)
CPU          1416 MHz padrão · 1512 MHz com "Enable CPU Overclock"
GPU          Mali-G31 MP2 (Bifrost), fixada em 650 MHz durante o jogo
DRAM         1 GB DDR3L @ 924 MHz
Display      640×480 MIPI DSI (43 revisões de painel cobertas)
Audio        Codec RK817: alto-falante, jack de fone, áudio USB, áudio HDMI
Network      WiFi 802.11n + Bluetooth (RTL/AP6611S/etc.), autodetecção
Battery      3200 mAh (rk817-battery + rk817-charger), aviso por LED em bateria baixa
Storage      microSD (hot-swap suportado, imagem funciona em qualquer tamanho 8 GB+)
```

***

## Pilha de software [#pilha-de-software]

```
Kernel       6.12 LTS (fork BSP, autodetecção de placa via SARADC)
GPU driver   Panfrost (padrão) ou libmali (toggle no ES)
              ├─ Mesa 26.0.5 com +speed +lto, otimizado para NEON
              └─ zlib-ng para inflate/deflate via SIMD (zip de ROM 10–30% mais rápido)
Init         systemd 255
Frontend     EmulationStation
Backend      RetroArch + 18 emuladores standalone
Shell        bash + GNU coreutils (compatibilidade total com PortMaster)
```

**CMA**: 96 MB (aumentado de 64 MB depois que um audit identificou que as
alocações de V4L2/Mali estavam apertadas mesmo em idle).

**ZRAM**: 512 MB lzo-rle (escolhido em vez de zstd porque o Cortex-A35 in-order
roda lzo-rle 3–4× mais rápido).

***

## Emuladores pré-instalados [#emuladores-pré-instalados]

```
SNES, NES, GB/GBC/GBA, NDS, MD, MS, GG, PCE, NeoGeo, Atari (2600/5200/7800/Lynx/Jaguar),
WonderSwan, PC-FX, ColecoVision, Intellivision, Vectrex, ScummVM, DOS

PSX           pcsx_rearmed (padrão), beetle_psx_hw, swanstation, duckstation (software)
N64           Mupen64Plus standalone (GLideN64 performance / Rice como fallback)
PSP           PPSSPP standalone (frameskip 3, cap de FPS em 30, GLTHREAD on)
Dreamcast     Flycast standalone (resolução 240, renderização threaded, GLTHREAD on)
Saturn        yabasanshiro standalone (experimental no A35)
Arcade        MAME 2003+, FBNeo, FBA-CPS1/CPS2/Neogeo
NDS           DraStic (padrão), melonDS como fallback
```

**Não incluídos no RK3326**: GameCube, Wii, Wii U. O Cortex-A35 não roda esses jogos em framerates aceitáveis, então eles ficam ocultos do menu.

***

## Painéis de display [#painéis-de-display]

43 overlays MIPI pré-gerados:

* **15 original** (revisões R36S V20–V22, variantes OGS)
* **18 clone** (K36, R33S, RX6S, R36 Max, múltiplas famílias de painel)
* **10 soysauce** (hardware baseado em Y3506)

Os nomes dos overlays espelham exatamente a revisão da placa-mãe:

```
R36S-V21_2024-12-18_2551.dtbo
G80CA-MB_V1.3-20251212_Panel_8.dtbo
RX6S-2024_05_15-Panel_5.dtbo
```

O overlay de painel é selecionado pelo [ArchR Flasher](/docs/installation) no momento da gravação. A mesma imagem funciona em qualquer placa de uma variante; só o overlay muda por painel.

***

## Funcionalidades de rede [#funcionalidades-de-rede]

| Funcionalidade                       | Serviço                          | Padrão                             |
| ------------------------------------ | -------------------------------- | ---------------------------------- |
| WiFi                                 | iwd + connman                    | auto-ligado se houver configuração |
| Áudio Bluetooth + gamepad            | bluez                            | habilitado                         |
| Multiplayer local                    | RetroArch netplay                | descoberta por UDP                 |
| Multiplayer remoto                   | Tailscale / ZeroTier / WireGuard | opt-in pela UI                     |
| Sincronia de ROMs/saves              | Syncthing                        | opt-in                             |
| Servidor web                         | simple-http-server               | opt-in                             |
| Samba (compartilhamento de arquivos) | smbd + nmbd + wsdd               | opt-in                             |
| SSH                                  | sshd                             | opt-in (toggle no ES)              |

Todos os serviços "opt-in" são pausados automaticamente durante o jogo, para que não disputem ciclos de CPU com o emulador.

***

## Linha do tempo do boot [#linha-do-tempo-do-boot]

```
0.0 s    Início do U-Boot
0.7 s    Splash do initramfs + seleção de DTB
~7 s     Hand-off do kernel
~9 s     Target do systemd
~12 s    archr-autostart (quirks + governor + display)
~17 s    EmulationStation
~19 s    Pronto para jogar
```

O primeiro boot adiciona uns 10 s para o resize de partição e cria os diretórios de ROM, somente no primeiríssimo power-on depois da gravação.

***

## O que foi ajustado para o RK3326 [#o-que-foi-ajustado-para-o-rk3326]

Pontos altos do trabalho específico para RK3326 (lista completa em [Técnico](/docs/technical)):

* GPU OPP 650 MHz turbo a 1.150 V (mesma voltagem do 600 MHz, evitando os 1.175 V do BSP original que eram instáveis em alguns chips)
* CPU OPP 1512 MHz a 1.400 V com `vdd_arm` regulator-max elevado para 1.45 V (o spec do RK817 DCDC\_REG2 é 1.5 V máx)
* Patch de PM no `mali_kbase`: elimina os warnings de desbalanceio de regulador/clock que estavam causando estalos de áudio no Mario 64
* Partição BOOT 272 MB FAT32 com clusters de 4 KB (acima do mínimo de 65525 do spec + boot sector e backup auto-sincronizados)
* `rq_affinity=2` na fila de I/O do microSD (a IRQ pousa no core que emitiu a requisição)
* Scheduler BFQ com `low_latency=1` e `read_ahead_kb=2048`


# Driver de GPU



Dois drivers de GPU acompanham o sistema. O ArchR inicializa com &#x2A;*Panfrost (Mesa)** por padrão, com **libmali** disponível como opt-in.

***

## Referência rápida [#referência-rápida]

|                       | Panfrost                           | libmali                        |
| --------------------- | ---------------------------------- | ------------------------------ |
| Origem                | Open-source (Mesa)                 | Proprietário (blob da ARM)     |
| API                   | OpenGL 3.1, GLES 3.1               | Apenas GLES 3.1                |
| Vulkan                | PanVK (experimental)               | Sim (apenas Mali-G31)          |
| Padrão                | ✅                                  | -                              |
| RetroArch mais antigo | ⚠️ pode precisar de Mesa mais novo | ✅ mais próximo do stock        |
| Desenvolvimento ativo | ✅ Mesa semanalmente                | Congelado no BSP do fornecedor |

***

## Trocar de driver [#trocar-de-driver]

EmulationStation → **System Settings** → **Graphics** → **GPU driver** → escolha `panfrost` ou `libmali`. Reinicie.

A configuração é persistida em `/storage/.config/system.cfg` (`gpu.driver=panfrost|libmali`). No boot, o script `gpudriver --start`:

1. Carrega o módulo de kernel escolhido (`panfrost` ou `mali_kbase`)
2. Faz bind-mount das bibliotecas de userspace corretas sobre o Mesa
3. Mascara o JSON de Vulkan ICD errado

Se o driver escolhido falhar ao se vincular ao nó da GPU (por exemplo, mali\_kbase reporta erro de regulador), o script faz fallback automático para o outro, então você tem um sistema gráfico de qualquer maneira.

***

## Por que Panfrost é o padrão [#por-que-panfrost-é-o-padrão]

* **Mesa 26.0.5** tem suporte sólido a Mali-G31 (Bifrost v9). Nenhuma extensão faltando em nenhum core libretro que distribuímos.
* **MESA\_GLTHREAD** ajustado por emulador (Flycast, PPSSPP) entrega throughput extra.
* **Upstream ativo**: correções de bug chegam continuamente. Blob de fornecedor congelado significa preso em qualquer peculiaridade de 2019 que foi distribuída.
* **Mesma superfície de API** que o libmali para tudo exceto Vulkan.

***

## Quando experimentar libmali [#quando-experimentar-libmali]

Casos de borda específicos relatados em testes da comunidade:

* Um emulador / jogo específico mostra glitches de renderização no Panfrost
* Você quer experimentar Vulkan via mali (PanVK no G31 não é conformante)
* Um pacote de shaders libretro X funciona de um jeito mas não do outro

O fallback em runtime significa que trocar é de baixo risco. Se o driver escolhido falhar ao se anexar à GPU no boot, o sistema troca para o alternativo automaticamente.

***

## Quirks do Mesa aplicados (caminho Panfrost) [#quirks-do-mesa-aplicados-caminho-panfrost]

Para RK3326 / Mali-G31, o ArchR exporta isso globalmente para os emuladores:

```bash
PAN_MESA_DEBUG=forcepack            # força format-pack no G31
                                    # (apesar do nome, NÃO é uma flag de debug)
MESA_NO_ERROR=1                     # pula o rastreamento de erros do GL
MESA_SHADER_CACHE_DIR=/storage/.cache/mesa_shader_cache
MESA_SHADER_CACHE_MAX_SIZE=128MB    # cache de shaders sobrevive a reboots
```

Por emulador (apenas onde o benefício foi confirmado):

```bash
MESA_GLTHREAD=true   # Flycast, PPSSPP standalone, veja /docs/mesa-glthread-matrix
```

***

## Vulkan [#vulkan]

PanVK no Mali-G31 (Bifrost v9) **não é conformante**. O time upstream do Mesa só distribui PanVK oficialmente para Mali-G610 (Valhall). O ArchR desabilita o PanVK em tempo de build no RK3326, assim emuladores que sondam por Vulkan não tentam e falham.

Se uma futura atualização de emulador precisar de Vulkan e tivermos validado o PanVK contra ele, o toggle apareceria no mesmo menu Graphics.

***

## Troubleshooting [#troubleshooting]

**Tela preta após trocar para Panfrost.** O overlay DTBO do seu painel pode não ter sido carregado. Verifique com `cat /sys/class/drm/card0/connector/*/status`. Volte para libmali via o caminho de recuperação:

1. Desligue, remova o cartão SD
2. Em um PC, monte a partição BOOT
3. Edite `/storage/.config/system.cfg` (na partição de storage) e defina `gpu.driver=libmali`
4. Reinsira e inicialize

**`gpudriver` alerta "did not bind to GPU".** O auto-fallback já foi disparado. Seu driver efetivo é o *outro*. Verifique `journalctl -t gpudriver` (via [SSH](/docs/ssh)) para a mensagem exata.

**Spam de sonda Vulkan nos logs.** Alguns ports do PortMaster tentam Vulkan primeiro. Inofensivo: eles fazem fallback para GLES.


# Saída HDMI



O R36S vem com uma porta Mini-HDMI. Plugue numa TV ou monitor; o ArchR detecta e espelha automaticamente. O comportamento padrão funciona em 90% dos casos. Esta página cobre os 10% restantes.

***

## Momento de plugar [#momento-de-plugar]

**Conecte o HDMI antes de ligar o dispositivo**, quando possível. Alguns clones do R36S detectam o HDMI apenas no boot, o hot-plug funciona parcialmente (o áudio é roteado certo, o vídeo pode não aparecer).

Se o hot-plug não pegar:

1. Plugue o cabo
2. Desligue o dispositivo completamente
3. Ligue novamente com o cabo conectado

***

## Resolução [#resolução]

O padrão é espelhar a resolução do painel do dispositivo (640×480 no R36S) e deixar a TV fazer o upscale. Se a sua TV não lida bem com 480p não-padrão, force um modo mais amigável:

<Steps>
  ### Descubra o modo preferido da sua TV [#descubra-o-modo-preferido-da-sua-tv]

  Praticamente toda TV moderna aceita nativamente 1280×720\@60 ou 1920×1080\@60. Escolha um.

  ### Crie um script de autostart [#crie-um-script-de-autostart]

  Via [SSH](/docs/ssh):

  ```bash
  mkdir -p /storage/.config/autostart
  nano /storage/.config/autostart/090-sway-hdmi-resolution
  ```

  Conteúdo:

  ```bash
  #!/bin/bash
  echo "output HDMI-A-1 resolution 1280x720" >> /storage/.config/sway/config
  ```

  (Troque `1280x720` por `1920x1080` para Full HD.)

  ### Torne executável [#torne-executável]

  ```bash
  chmod +x /storage/.config/autostart/090-sway-hdmi-resolution
  ```

  ### Reinicie [#reinicie]

  `sudo reboot`. O Sway pega a nova configuração e a saída HDMI roda na resolução pedida.
</Steps>

### Espelhamento exato [#espelhamento-exato]

Se a TV está exibindo a saída do dispositivo deslocada ou cortada, force a posição:

```bash
echo "output HDMI-A-1 resolution 1280x720 position 0 0" >> /storage/.config/sway/config
```

***

## Áudio [#áudio]

O ArchR roteia o áudio automaticamente pelo HDMI quando um cabo HDMI é detectado. Para sobrescrever (ex.: você quer som nas caixas do dispositivo enquanto a TV exibe a imagem):

```bash
amixer set 'Playback Path' SPK
```

Para uma preferência mais persistente, edite `/storage/.config/system.cfg`:

```ini
audio.path=SPK
```

...e adicione um quirk em `/storage/.config/profile.d/050-audio_path` se necessário.

***

## Por que o HDMI às vezes não mostra nada num clone [#por-que-o-hdmi-às-vezes-não-mostra-nada-num-clone]

Dispositivos clone vêm com SPL/U-Boot diferente do R36S original. Alguns clones não inicializam o HDMI na etapa do U-Boot, ou seja, você não vê mensagens do kernel ou splash na TV. O kernel ainda controla o HDMI sem problemas depois do boot, mas se a sua TV exigir um sinal durante o U-Boot para travar, ela pode não exibir nada até o ArchR subir completamente.

Não existe correção no nível do bootloader hoje; o workaround é ligar com o painel interno do dispositivo como primário e, assim que o ArchR carregar, o HDMI passa a espelhar.

***

## Desabilitando o painel interno quando está no HDMI [#desabilitando-o-painel-interno-quando-está-no-hdmi]

Alguns usuários preferem o painel do dispositivo apagado quando acoplado a uma TV. Adicione ao mesmo script de autostart:

```bash
#!/bin/bash
echo "output HDMI-A-1 resolution 1280x720"     >> /storage/.config/sway/config
echo "output DSI-1     disable"                >> /storage/.config/sway/config
```

Reinicie. Agora o painel do dispositivo fica escuro e toda a saída vai pelo HDMI.

Para reverter: apague o arquivo de autostart e reinicie.


# Documentação



Distribuição Linux personalizada para o **R36S** e suas variantes, construída sobre o [ROCKNIX](https://github.com/ROCKNIX/distribution) com ambiente de build baseado em Arch Linux. Kernel 6.12 LTS, Mesa 26 Panfrost (driver de GPU open-source), 43 overlays MIPI pré-gerados cobrindo todas as revisões de placa-mãe conhecidas.

Duas imagens, ambas com detecção automática de hardware:

* **Original**: para R36S genuíno, R33S, família Odroid Go, Anbernic RG351V/M, GameForce Chi, MagicX XU10
* **Clone**: para clones K36, EE Clone, Powkiddy RGB10/RGB10X/RGB20S, MagicX XU-Mini-M, BatLexp G350

<Cards>
  <Card title="Instale em 3 minutos" href="/docs/installation" description="ArchR Flasher (GUI) ou dd manual" />

  <Card title="Adicione ROMs" href="/docs/roms" description="Onde colocar jogos e arquivos de BIOS" />

  <Card title="Controles" href="/docs/controls" description="Atalhos, variantes K36/MyMini, layout JP" />

  <Card title="PortMaster" href="/docs/portmaster" description="Rode ports nativos (Half-Life, Quake, Diablo II...)" />

  <Card title="Acesso SSH" href="/docs/ssh" description="Shell remoto, transferência de arquivos, debug" />

  <Card title="Funcionalidades" href="/docs/features" description="Especificações de hardware e pilha de software" />
</Cards>

***

## O que é diferente [#o-que-é-diferente]

* **Driver de GPU open-source** (Panfrost via Mesa 26.0.5), sem blobs proprietários. `libmali` também está disponível como opt-in.
* **Build de duas imagens com autodetecção**: a mesma imagem dá boot em qualquer placa-mãe de uma variante. O SARADC lê o ID da placa no boot.
* **Toggle de overclock de CPU**: chave no menu do ES eleva o limite de 1.4 GHz para 1.5 GHz quando você precisar.
* **Builds reproduzíveis**: baseados em Docker, sem etapas ocultas. `make docker-RK3326` produz as duas variantes de imagem.
* **Jogo em rede out of the box**: Syncthing, Tailscale, ZeroTier, RetroAchievements, scraping.
* **PortMaster pré-instalado**: roda ports de PC (Half-Life, Diablo II, Doom 3, Quake) no aparelho.

***

## Links rápidos [#links-rápidos]

* **[Releases →](https://github.com/archr-linux/Arch-R/releases)** baixe a imagem mais recente
* **[ArchR Flasher →](https://github.com/archr-linux/archr-flasher/releases)** instalador gráfico (Linux, macOS, Windows)
* **[Código-fonte →](https://github.com/archr-linux/Arch-R)** kernel + rootfs + build da imagem
* **[Issues →](https://github.com/archr-linux/Arch-R/issues)** relatos de bugs


# Instalação



Você só precisa de um cartão microSD (8 GB ou mais, recomendado 16 GB+) e 5 minutos. O caminho recomendado é o **ArchR Flasher**: ele escolhe a variante de imagem correta para sua placa, aplica o overlay de painel certo automaticamente e verifica a gravação.

***

## Opção 1: ArchR Flasher (recomendado) [#opção-1-archr-flasher-recomendado]

O Flasher é um pequeno aplicativo desktop (Tauri) que baixa a release mais recente, escolhe o overlay de painel correto para sua placa-mãe, grava o cartão SD e verifica a gravação. Disponível para Linux, macOS e Windows.

<Steps>
  ### Baixe o Flasher [#baixe-o-flasher]

  Pegue a release mais recente em [archr-flasher releases](https://github.com/archr-linux/archr-flasher/releases).

  * **Linux**: `.AppImage` (sem instalação) ou `.deb` para Debian/Ubuntu/derivados
  * **macOS**: `.dmg`
  * **Windows**: instalador `.msi`

  ### Conecte o microSD [#conecte-o-microsd]

  8 GB ou mais. O Flasher vai apagar **tudo** que estiver no cartão antes de gravar. Faça backup do que precisar antes.

  ### Escolha a placa / painel [#escolha-a-placa--painel]

  Abra o Flasher e:

  1. Escolha a **variante da placa**: Original ou Clone. Se não souber, verifique o verso do seu aparelho ou consulte a [tabela de placas](/docs/features#display-panels) na página Features.
  2. Escolha a **revisão da placa-mãe** no dropdown (por exemplo: `R36S-V21_2024-12-18_2551`, `G80CA-MB_V1.3-20251212_Panel_8`). O Flasher lê o texto serigrafado impresso no verso da placa-mãe.
  3. Toggles opcionais:
     * **Joypad variant**: Auto · K36 · MyMini (só faz diferença em clones)
     * **JP layout**: rótulos de botão japoneses (troca A↔B, X↔Y)
     * **SRs (force simple audio)**: para placas com fiação de amplificador não-padrão
     * **Dno (skip vendor mode)**: desabilita a tela de modo vendor no boot em algumas placas

  ### Grave [#grave]

  Clique em **Flash**. O Flasher baixa a imagem (ou usa o cache), limpa o SD, grava, depois faz leitura de volta para verificar o SHA256.

  Cerca de 3 minutos no total em um cartão classe 10.

  ### Boot [#boot]

  Insira o SD no aparelho e ligue. O primeiro boot faz um redimensionamento automático da partição e reinicia uma vez, totalizando uns 30 s. Após o segundo boot você cai no EmulationStation.
</Steps>

***

## Opção 2: `dd` manual [#opção-2-dd-manual]

Se você prefere a linha de comando ou está no Windows (use Rufus, Etcher ou equivalente ao Raspberry Pi Imager).

<Steps>
  ### Baixe uma imagem [#baixe-uma-imagem]

  Em [Arch-R releases](https://github.com/archr-linux/Arch-R/releases) pegue uma de:

  * `ArchR-R36S.aarch64-DATA-original.img.gz`: para R36S genuíno
  * `ArchR-R36S.aarch64-DATA-clone.img.gz`: para hardware K36 / clones

  ### Descompacte [#descompacte]

  ```bash
  gunzip ArchR-R36S.aarch64-*.img.gz
  ```

  ### Identifique o dispositivo SD [#identifique-o-dispositivo-sd]

  ```bash
  lsblk
  # procure pelo seu cartão, geralmente /dev/sdX ou /dev/mmcblkX
  ```

  <Callout type="warn">
    Confira duas vezes o caminho do dispositivo. Gravar no disco errado vai apagá-lo.
  </Callout>

  ### Grave [#grave-1]

  ```bash
  sudo dd if=ArchR-R36S.aarch64-*.img of=/dev/sdX bs=4M conv=fsync status=progress
  sync
  ```

  ### Aplique o overlay de painel (somente no caminho manual) [#aplique-o-overlay-de-painel-somente-no-caminho-manual]

  A imagem padrão dá boot com um overlay de painel genérico. Se sua tela ficar preta ou distorcida, monte a partição BOOT e copie o overlay correto:

  ```bash
  sudo mount /dev/sdX1 /mnt
  ls /mnt/overlays/   # veja todos os 43 overlays disponíveis
  sudo cp /mnt/overlays/<sua-revisao-de-placa>.dtbo /mnt/overlays/mipi-panel.dtbo
  sudo umount /mnt
  ```

  Encontre a revisão da sua placa-mãe impressa no verso da placa.

  ### Boot [#boot-1]

  Insira e ligue. O primeiro boot redimensiona e reinicia; o segundo boot chega ao ES.
</Steps>

***

## Primeiro boot [#primeiro-boot]

Depois da gravação, o **primeiro** power-on faz o seguinte automaticamente e então reinicia:

```
1. parted resizepart  → /storage usa o SD inteiro
2. e2fsck + resize2fs → filesystem ext4 cresce
3. tune2fs -U random  → UUID novo
4. fsck.fat -a -w     → BOOT FAT primário/backup sincronizados
5. reboot
```

O log do resize fica em `/flash/fs-resize.log` caso você precise inspecionar.

O **segundo** boot cria os diretórios de ROM (um por sistema) e cai no EmulationStation. A partir daí você pode [adicionar ROMs](/docs/roms) e [habilitar SSH](/docs/ssh).

***

## Variantes explicadas [#variantes-explicadas]

| Variante   | U-Boot            | Logo de boot | Hardware                                                                    |
| ---------- | ----------------- | ------------ | --------------------------------------------------------------------------- |
| `original` | BSP Rockchip      | Sim          | R36S, R33S, família Odroid Go, Anbernic RG351, GameForce Chi, MagicX XU10   |
| `clone`    | Mainline v2025.10 | Não          | K36, EE Clone, Powkiddy RGB10/RGB10X/RGB20S, MagicX XU-Mini-M, BatLexp G350 |

As duas imagens diferem **apenas** no U-Boot e no conjunto de overlays de painel. Kernel, rootfs, RetroArch e EmulationStation são idênticos.

***

## Solução de problemas [#solução-de-problemas]

**Tela preta após o logo de boot.** Overlay de painel errado. Regrave selecionando a revisão correta da placa-mãe, ou copie o `.dtbo` certo para `/flash/overlays/mipi-panel.dtbo` a partir de outra máquina.

**Boot em loop ou travado após o primeiro reboot.** Capture `cat /storage/.boot_last_hang` depois de algum boot bem-sucedido: o arquivo nomeia o script que travou. Veja [Solução de problemas](/docs/troubleshooting).

**"BOOT FAILED" em um dispositivo clone com a imagem original.** Você escolheu a variante errada. Use a imagem clone.

**O Flasher diz "image checksum mismatch".** O download veio corrompido. Clique em "Flash" de novo; o Flasher rebaixa e tenta de novo.


# Netplay



O netplay do RetroArch permite que até 4 jogadores joguem o mesmo core libretro em tempo real. Funciona via WiFi doméstico (modo LAN) ou diretamente entre dois handhelds (modo dispositivo-a-dispositivo). Os dois dispositivos precisam rodar **a mesma versão do ArchR** com **o mesmo core**.

***

## Pré-checagem [#pré-checagem]

<Steps>
  ### Mesma versão dos dois lados [#mesma-versão-dos-dois-lados]

  ES → **System Information**: confirme que a versão do ArchR bate entre host e clientes.

  ### Ativar netplay globalmente [#ativar-netplay-globalmente]

  ES → **Game Settings** → **Netplay Settings** → **NetPlay** → ON. Toque também em **Index Games** para que o RetroArch saiba quais ROMs você tem.

  ### Mesmo core, mesma ROM [#mesmo-core-mesma-rom]

  Cada jogador precisa do mesmo core (ex.: `snes9x_libretro`) e do mesmo arquivo de ROM. O RetroArch calcula o hash da ROM, se os hashes diferem, a conexão falha.
</Steps>

***

## Opção 1: pelo WiFi doméstico (LAN) [#opção-1-pelo-wifi-doméstico-lan]

### Host [#host]

ES → **Network Settings** → ative o WiFi → desative **Local Play Mode** → defina o papel &#x2A;*1 (Host)**.

No ES, destaque o jogo, pressione `Y` → **Netplay Options** → **Host a Netplay Session**. O RetroArch inicia em modo host e aguarda os clientes.

### Clientes (até 3) [#clientes-até-3]

ES → **Network Settings** → WiFi ligado → **Local Play Mode** OFF → papel &#x2A;*2 / 3 / 4 (Client)**.

No ES, mesmo jogo, `Y` → **Netplay Options** → **Connect to a Netplay Session**. Escolha o host na lista descoberta.

***

## Opção 2: dispositivo-a-dispositivo (sem roteador) [#opção-2-dispositivo-a-dispositivo-sem-roteador]

Quando você está longe do WiFi de casa (parques, viagens de carro). Um dispositivo atua como hotspot e o outro se conecta a ele.

### Host [#host-1]

ES → **Network Settings** → **Local Play Mode** → ON → papel &#x2A;*1 (Host)**.

O ArchR cria um access point WiFi temporário no host. Anote o SSID e a senha que ele exibe.

### Clientes [#clientes]

ES → **Network Settings** → conecte-se ao SSID do host → **Local Play Mode** ON → papel **2-4**.

Mesmo fluxo de lançamento do jogo do modo LAN.

<Callout type="warn">
  O modo dispositivo-a-dispositivo desativa a internet. Você não consegue fazer scraping, RetroAchievements ou atualizações enquanto ele está ativo.
</Callout>

***

## Setup no lado do jogo [#setup-no-lado-do-jogo]

Os dois jogadores lançam **a mesma** ROM. O menu de sessão do RetroArch mostra o status do handshake e o alinhamento do frame buffer. Se aparecer "checksum mismatch", suas ROMs não são byte-idênticas (região / dump diferentes).

Para cores com rollback netcode (FBNeo, alguns 16 bits), o RetroArch o habilita automaticamente, o input lag em uma LAN rápida fica próximo do local. Para cores sem rollback (a maioria), o jogo flui melhor quando o host tem a conexão melhor: eles rodam com lag quase zero e o cliente recebe alguns frames de buffer.

***

## Escolha ideal de host [#escolha-ideal-de-host]

Se você tem um dispositivo cabeado (eth-via-USB-C) e outro no WiFi, hospede no cabeado. O RetroArch usa o frame do host como canônico, hosts cabeados significam menos rollbacks.

Se os dois estão no WiFi, escolha como host o dispositivo mais próximo do roteador.

***

## Cores compatíveis [#cores-compatíveis]

Qualquer core libretro com `netplay = supported` no arquivo de info. Lista rápida de cores comprovadamente funcionais no ArchR RK3326:

* snes9x2010, snes9x
* gambatte (GB/GBC), mgba (GBA)
* fceumm (NES), nestopia
* genesis\_plus\_gx (MD/MS/GG)
* fbneo (Arcade), rollback habilitado
* mednafen\_psx\_hw (PSX)

Cores 3D pesados (mupen64plus\_next, ppsspp\_libretro) funcionam tecnicamente, mas o A35 mais a carga de renderização resulta em engasgos, experiência ruim.

***

## Solução de problemas [#solução-de-problemas]

**"Checksum mismatch"**: dumps diferentes da mesma ROM. Use a versão no-intro / Redump nos dois lados.

**"Connection timeout"**: o IP do host está errado (modo LAN) ou o hotspot não está visível (dispositivo-a-dispositivo). No modo LAN, confira que os dois dispositivos estão na mesma subnet (`ip addr` via [SSH](/docs/ssh)).

**Picos de lag**: contenção de airtime no WiFi. Aproxime-se do roteador ou desative o Bluetooth nos dois dispositivos durante a sessão.

**Áudio fora de sincronia**: desligue o override do buffer de áudio do netplay. Quick Menu → Settings → Netplay → "Allow Asymmetric Frame Rate" → OFF.


# Overclock de CPU



O Cortex-A35 do R36S tem um OPP turbo em 1512 MHz que fica dormente por padrão. Ative-o nos jogos que precisam de cada Hz disponível; deixe desligado para temperatura mais baixa e mais autonomia de bateria no resto.

***

## Como habilitar [#como-habilitar]

EmulationStation → \*\* \*\* (Start) → **System Settings** → **Performance** → **Enable CPU Overclock** → ON.

O toggle é persistido em `/storage/.config/system.cfg` (`enable.turbo-mode=1`) e reaplicado a cada boot pelo autostart `095-turbo-mode`.

Para desligar, basta inverter o toggle. Nenhuma das direções exige reboot.

***

## O que muda quando está ligado [#o-que-muda-quando-está-ligado]

```
                 OFF (default)         ON
─────────────────────────────────────────────────
cpufreq/boost    0                     1
top freq idle    1416 MHz              1416 MHz
top freq game    1416 MHz              1512 MHz
voltage @ top    1.350 V               1.400 V
```

Idle/menu não muda: o governor decide sob demanda. Só quando a CPU realmente precisa do OPP de topo é que os \~7 % extras entram em ação.

Durante o gameplay, o `runemu.sh` muda o governor para `performance` e fixa `scaling_max_freq` no maior valor que `scaling_available_frequencies` expõe (o que depende de o boost estar ligado ou não).

***

## Por que isso existe [#por-que-isso-existe]

O BSP padrão do RK3326 expõe os 1512 MHz apenas como `turbo-mode` na tabela de OPP. O kernel esconde isso de `cpuinfo_max_freq` até que `cpufreq/boost=1` seja definido. Além disso, o default do regulador `vdd_arm` no device tree upstream do PX30 é limitado a 1.35 V, o que é baixo demais para sustentar 1.5 GHz de forma confiável na maioria dos chips. O ArchR elevou esse teto para 1.45 V (a spec do RK817 DCDC\_REG2 é 1.5 V), definiu o OPP em 1.4 V e expôs o toggle.

Alguns chips rodam 1.5 GHz em 1.35 V sem problema. Alguns precisam de 1.4 V. Nenhum foi reportado falhando em 1.4 V até agora.

***

## Quando usar [#quando-usar]

* **PSP** (PPSSPP standalone): God of War, Tekken 6, Daxter, ganho pequeno mas consistente de fps
* **Dreamcast** (Flycast): Crazy Taxi, Sonic Adventure 2, suavização de frametime
* **N64** (Mupen64Plus): cenas pesadas (castelo do SM64, Hyrule Field em Zelda OoT)
* **PSX** (Beetle PSX HW): 3D com muita textura
* **PortMaster**: ports box86/box64 que sofrem throttle em 1.4 GHz

Para cores 2D / handheld / 8-16 bits, deixar OFF é a escolha certa: eles não precisam disso e você economiza bateria e calor.

***

## Verifique se está funcionando [#verifique-se-está-funcionando]

Via [SSH](/docs/ssh):

```bash
# OFF esperado: 0
# ON  esperado: 1
cat /sys/devices/system/cpu/cpufreq/boost

# OFF esperado: 408000 816000 1008000 1416000
# ON  esperado: 408000 816000 1008000 1416000  (o OPP turbo aparece separado)
cat /sys/devices/system/cpu/cpufreq/policy0/scaling_available_frequencies

# ON esperado: 1512000
cat /sys/devices/system/cpu/cpufreq/policy0/scaling_boost_frequencies

# Frequência ao vivo durante um jogo (rode em loop apertado):
watch -n 0.5 cat /sys/devices/system/cpu/cpufreq/policy0/scaling_cur_freq
```

Se você vir `1512000` aparecendo em `scaling_cur_freq` enquanto um jogo pesado roda, o overclock está ativo.

***

## Riscos [#riscos]

* **Térmica**: 1.5 GHz em 1.4 V dissipa mais calor do que 1.4 GHz em 1.35 V. O R36S é resfriado passivamente; em uma sala quente, sob carga pesada sustentada, ele vai entrar em throttle mais cedo. O kernel cuida disso, significa apenas que você fica mais próximo de 1.4 GHz uma vez que a temperatura atinge o passive trip (\~70 °C).
* **Bateria**: vida útil \~10-15 % menor sob carga pesada com o overclock ligado. Desprezível em idle/menu.
* **Variação por chip**: uma pequena minoria de chips reporta instabilidade em 1.5 GHz / 1.4 V. Se o seu dispositivo reinicia durante PSP/DC, desligue o toggle como primeiro diagnóstico.

***

## Revertendo / desativando de forma permanente [#revertendo--desativando-de-forma-permanente]

Toggle no ES, off. Para forçar via shell (por exemplo se o ES travou):

```bash
echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost
sudo sed -i 's/^enable.turbo-mode=1/enable.turbo-mode=0/' /storage/.config/system.cfg
```


# PortMaster



O [PortMaster](https://portmaster.games/) é um launcher e repositório de ports que executa binários nativos de PC (Half-Life, Diablo II, Doom 3, Quake, Stardew Valley, Vvvvvv...) diretamente no handheld, usando tradução via `box86` / `box64` quando necessário. O ArchR já vem com o PortMaster pré-instalado e configurado.

***

## O que está incluído por padrão [#o-que-está-incluído-por-padrão]

```
PortMaster GUI            /storage/roms/ports/PortMaster/
gptokeyb                  tradutor de eventos joypad → teclado
oga_controls              integração de input específica para o dispositivo
control.txt               mapa de teclas padrão
SDL2 + lib32 / box86      binários x86 de 32 bits via box86
SDL2 + box64              binários x86_64 de 64 bits via box64
Python 3 + lzma           usado pela GUI e por muitos ports
```

Verificação no boot:

```bash
python3 -c 'import lzma'   # funciona
ls -la /dev/uinput          # crw-rw-rw- (regra udev 91-uinput.rules)
```

***

## Executando um port [#executando-um-port]

<Steps>
  ### Abra o PortMaster [#abra-o-portmaster]

  No EmulationStation, navegue até o sistema **Ports**. A primeira entrada é o "PortMaster", abra-a. A GUI será iniciada.

  ### Navegue / instale [#navegue--instale]

  Pressione `B` em um port para instalá-lo. Os arquivos vão para `/storage/roms/ports/<nome-do-port>/`. O PortMaster baixa quaisquer arquivos de dados necessários (assets no estilo ROM não são incluídos, copie `wad`/`mpq`/etc. para a pasta do port conforme o README dele).

  ### Saia da GUI do PortMaster [#saia-da-gui-do-portmaster]

  `MODE + B` retorna ao ES. Os ports instalados aparecem como launchers (arquivos `.sh`) na lista do sistema **Ports**.

  ### Jogue um port [#jogue-um-port]

  Igual a uma ROM. Selecione o launcher e pressione A. O ArchR pausa serviços em segundo plano (Syncthing, Tailscale, ZeroTier) durante a sessão, troca o governor da CPU para `performance` e fixa a GPU em 650 MHz.

  ### Sair [#sair]

  Cada port tem seu próprio hotkey, geralmente `MODE + START + SELECT`. Alguns usam apenas `MODE + START`. A combinação está documentada no README do port em `/storage/roms/ports/<port>/README.md`.
</Steps>

***

## Ports que exigem dados próprios [#ports-que-exigem-dados-próprios]

Alguns ports trazem apenas a engine. Eles esperam que você coloque os dados originais do jogo na pasta do port. Exemplos:

| Port                       | O que colocar                                                       |
| -------------------------- | ------------------------------------------------------------------- |
| **HalfLife**               | `valve/` e `cstrike/` da sua instalação do Steam                    |
| **Diablo II**              | arquivos `*.mpq` de uma cópia legítima                              |
| **Doom 3**                 | `pak*.pk4` da instalação retail                                     |
| **Quake**                  | `id1/pak0.pak` e `pak1.pak`                                         |
| **Stardew Valley**         | `Content/`, `StardewValley.dll`, etc. da sua instalação Steam Linux |
| **TombRaider**             | `data/` do CD original                                              |
| **DevilutionX (Diablo I)** | `diabdat.mpq`                                                       |

O PortMaster mostra um checklist por port com os arquivos faltantes na GUI antes de permitir o lançamento.

***

## Jogo em rede [#jogo-em-rede]

Ports do PortMaster que suportam multiplayer (Quake, Half-Life DM, etc.) podem usar:

* **Tailscale** ou **ZeroTier** para jogar em "LAN pela internet" com amigos. Ative em ES → System Settings → Network.
* Broadcast em **LAN local**, funciona de cara, basta que os dois dispositivos estejam no mesmo WiFi.

O ArchR mantém todos os serviços VPN pausados até você lançar um jogo que precise deles, retomando depois que você sai.

***

## Expectativas de desempenho [#expectativas-de-desempenho]

Cortex-A35 + Mali-G31 é um SoC de baixo custo. Baseline realista:

| Categoria               | Exemplos                                      | Expectativa                                  |
| ----------------------- | --------------------------------------------- | -------------------------------------------- |
| ARM nativo, leve        | Vvvvvv, Stardew Valley, Cute Fame, OpenRA     | velocidade plena, bateria plena              |
| box86 (x86 32 bits)     | Diablo II, Half-Life, Quake, Doom 3           | 25-60 fps dependendo das configurações       |
| box64 (x86\_64 64 bits) | Indies mais recentes (porte de Hollow Knight) | jogável mas pesado, precisa de CPU Overclock |
| 3D pesado / RT          | DOOM Eternal, AAA modernos                    | inviável                                     |

Ative **Enable CPU Overclock** no ES (eleva o limite de 1.4 para 1.5 GHz) para ports box86/64 que estão sofrendo.

***

## Solução de problemas [#solução-de-problemas]

**Port trava em tela preta.** Permissões do joypad provavelmente estão erradas. Verifique se `ls -la /dev/uinput` retorna modo `666`. Se não, a regra udev não foi aplicada, use `sudo chmod 666 /dev/uinput` como paliativo e reporte o bug.

**`gptokeyb: Permission denied`.** Mesma coisa acima.

**O port pede arquivos de dados faltando.** Coloque-os em `/storage/roms/ports/<port>/` conforme o README do port. A GUI do PortMaster lista os arquivos faltando antes do lançamento.

**`box86: assertion failure`.** O port foi compilado contra uma libstdc++ mais nova do que a que o ArchR distribui. Aguarde uma atualização ou reporte no [Discord do PortMaster](https://discord.gg/CMX5sTrgHQ).

**A própria GUI do PortMaster não inicia.** Execute `start_portmaster.sh` via [SSH](/docs/ssh) e leia o trace. O script agora é idempotente (`rm -rf` + guards), então relançar é sempre seguro.

***

## Onde as coisas ficam [#onde-as-coisas-ficam]

```
/storage/roms/ports/
├── PortMaster/             GUI + scripts (gerenciado)
│   ├── PortMaster.sh
│   ├── control.txt         mapa padrão joypad → tecla
│   ├── gptokeyb            tradutor de input
│   └── ...
├── DiabloII.sh             launcher gerado por port
├── DiabloII/               arquivos reais do port
├── HalfLife.sh
├── HalfLife/
└── ...
```

Remover um port: apague o `.sh` e a pasta correspondente, depois ES → Game Settings → Rescan ROMs.


# RetroAchievements



O [RetroAchievements](https://retroachievements.org/) é um serviço mantido pela comunidade que adiciona conquistas (e leaderboards) a jogos retrô. O RetroArch do ArchR já vem configurado, faça login uma vez e comece a desbloquear.

***

## Configuração [#configuração]

<Steps>
  ### Crie uma conta [#crie-uma-conta]

  Gratuita em [retroachievements.org](https://retroachievements.org/createaccount.php).

  ### Conecte-se à internet [#conecte-se-à-internet]

  ES → **System Settings** → **Network** → ative o WiFi.

  ### Faça login [#faça-login]

  ES → **Game Settings** → **RetroAchievement Settings** → ative **Enable RetroAchievements**, depois informe seu usuário e senha.

  ### Opções opcionais [#opções-opcionais]

  No mesmo menu:

  * **Hardcore Mode**: desativa save-states e rewind. Necessário para conseguir o badge *Mastered*.
  * **Unlock Sound**: toca o som clássico em cada desbloqueio.
  * **Automatic Screenshot**: salva o momento do desbloqueio em `/storage/screenshots/`.
  * **Encore Mode**: dispara novamente conquistas que você já ganhou.
  * **Verbose Mode**: mostra o progresso rumo às conquistas com dicas passo a passo.
</Steps>

***

## Quais jogos / cores são suportados [#quais-jogos--cores-são-suportados]

O RetroAchievements só funciona com cores libretro específicos e somente em jogos que tenham um conjunto de conquistas. Lista rápida de cores comprovadamente funcionais no ArchR RK3326:

| Console  | Core                             | Notas                     |
| -------- | -------------------------------- | ------------------------- |
| NES      | `fceumm`, `nestopia`             | catálogo enorme           |
| SNES     | `snes9x2010`, `snes9x`           | maioria dos jogos coberta |
| GB/GBC   | `gambatte`, `sameboy`            | completo                  |
| GBA      | `mgba`                           | completo                  |
| MD/MS/GG | `genesis_plus_gx`                | completo                  |
| N64      | `mupen64plus_next`               | parcial, pesado no A35    |
| PSX      | `mednafen_psx_hw`, `swanstation` | completo                  |
| PSP      | `ppsspp_libretro`                | parcial                   |
| NDS      | `melonds_ds`                     | parcial                   |
| Arcade   | `fbneo`, `mame_2003`             | funciona com romsets mame |

Lista completa em [docs.retroachievements.org/Emulator-Support-and-Issues/](https://docs.retroachievements.org/Emulator-Support-and-Issues/).

Emuladores standalone (PPSSPP, Flycast, Mupen64Plus standalone, DraStic, melonDS standalone) **não** passam pelo RetroAchievements, apenas os cores libretro passam. Se você quer conquistas em PSP/Dreamcast, use o core libretro (`ppsspp_libretro` / `flycast_libretro`) em vez do standalone.

***

## Hardcore vs softcore [#hardcore-vs-softcore]

| Hardcore ON                      | Hardcore OFF                                           |
| -------------------------------- | ------------------------------------------------------ |
| Sem save-states                  | Save-states permitidos                                 |
| Sem rewind                       | Rewind permitido                                       |
| Sem cheats                       | Cheats permitidos                                      |
| Desbloqueios contam para Mastery | Desbloqueios contam para o perfil mas não para Mastery |

A maioria das pessoas deixa **Hardcore OFF** no jogo normal e o ativa para runs que querem registrar oficialmente.

***

## Onde os desbloqueios são acompanhados [#onde-os-desbloqueios-são-acompanhados]

* **No jogo**: aparece uma notificação a cada desbloqueio (no topo da tela).
* **Perfil online**: `https://retroachievements.org/user/<seu-usuário>`. Perfil, desbloqueios recentes, leaderboards, master sets, tudo está no site.
* **Screenshots locais**: se "Automatic Screenshot" estiver ativo, cada desbloqueio deixa um PNG em `/storage/screenshots/`.

***

## Desempenho durante o gameplay [#desempenho-durante-o-gameplay]

O cliente do RetroAchievements faz polling de memória a cada frame para detectar disparos de conquista. Custo no RK3326 ≈ 0,5-1 % de CPU por conjunto de conquistas ativo, desprezível para cores 8 / 16 bits, levemente perceptível em PSX/N64 se você já está limitado pela CPU.

O jogo não precisa estar online durante a partida, os desbloqueios ficam em fila local e sincronizam no próximo contato com a internet. Útil para viagens.

***

## Solução de problemas [#solução-de-problemas]

**Nenhum desbloqueio acontece mesmo eu vendo a lista de conquistas.** Dump de ROM errado. O RetroAchievements casa por hash, se sua ROM difere, nenhum trigger dispara. Use dumps verificados no-intro / Redump.

**"Login failed".** Reinforme usuário e senha no menu. Confirme que `https://retroachievements.org` está acessível com `curl -sI https://retroachievements.org`.

**"Hardcore mode is disabled because save-state was loaded".** Assim que você carrega um state em uma sessão hardcore, o RA cai para softcore. Reinicie o core (Quick Menu → Reset) para voltar ao hardcore.


# Adicionando ROMs



ROMs ficam na partição **ROMS** (a maior das duas, formatada em ext4 no Linux/macOS, acessível como uma pasta chamada `roms/` a partir do dispositivo). O layout de pastas espelha a lista de sistemas do EmulationStation: uma pasta por sistema.

***

## Três formas de copiar ROMs [#três-formas-de-copiar-roms]

### 1. Conecte o SD em um PC [#1-conecte-o-sd-em-um-pc]

Monte a partição maior (label `ROMS`) e arraste arquivos para as pastas de cada sistema. Funciona nativamente no Linux/macOS. No Windows, partições ext4 do Linux precisam de um driver como o [Linux File Systems for Windows da Paragon](https://www.paragon-software.com/home/linuxfs-windows/) ou [WSL com `--mount`](https://learn.microsoft.com/en-us/windows/wsl/wsl2-mount-disk).

### 2. SSH / SCP a partir do seu computador [#2-ssh--scp-a-partir-do-seu-computador]

Mais rápido que reconectar o SD. Veja [acesso SSH](/docs/ssh). Uma vez conectado:

```bash
scp ~/roms/snes/*.sfc root@<ip-do-aparelho>:/storage/roms/snes/
```

### 3. Samba (amigável no Windows) [#3-samba-amigável-no-windows]

Habilite Samba no menu do EmulationStation → System Settings → Network → Samba. Depois, no seu computador:

* **Windows**: abra o Explorer, digite `\\archr` (ou o IP).
* **macOS**: Finder → `Cmd-K` → `smb://archr.local`.
* **Linux**: gerenciador de arquivos → "Conectar ao servidor" → `smb://archr.local/roms`.

Toda a árvore `/storage/roms/` é compartilhada. Solte os arquivos lá dentro.

***

## Sistemas e pastas suportados [#sistemas-e-pastas-suportados]

```
/storage/roms/
├── nes/             .nes .zip
├── snes/            .sfc .smc .zip
├── n64/             .z64 .v64 .n64 .zip
├── gb/  gbc/  gba/  .gb .gbc .gba .zip
├── nds/             .nds
├── megadrive/       .md .gen .smd .bin .zip
├── mastersystem/    .sms .zip
├── gamegear/        .gg .zip
├── pcengine/        .pce .zip
├── neogeo/          .neo .zip   (BIOS em /storage/roms/bios)
├── psx/             .pbp .chd .iso .bin/.cue .ecm
├── psp/             .iso .cso .pbp
├── dreamcast/       .gdi .cdi .chd
├── saturn/          .chd .cue .iso (experimental no RK3326)
├── arcade/          .zip          (romset do MAME 2003+)
├── fbneo/           .zip
├── atari2600/  atari5200/  atari7800/  .a26 .a52 .a78 .bin
├── lynx/  jaguar/   .lnx .jag
├── ws/  wsc/        .ws .wsc
├── pcfx/  ngp/      
├── ports/           launchers .sh do PortMaster, veja /docs/portmaster
├── scummvm/         atalhos .scummvm
├── dos/             launchers .conf ou .dosbox
└── bios/            arquivos de BIOS para os sistemas que precisam
```

O EmulationStation faz novo scan no próximo boot. Para disparar um rescan manual: menu do ES → Game Settings → Rescan ROMs.

***

## Arquivos de BIOS [#arquivos-de-bios]

Alguns emuladores precisam de dumps de BIOS fornecidos por você (a questão legal é com você: o Arch R não distribui arquivos de BIOS).

```
/storage/roms/bios/
├── scph5500.bin       PSX (US)
├── scph5501.bin       PSX (Japão)
├── scph5502.bin       PSX (Europa)
├── PSP/               PSP, só se não estiver usando PPSSPP HLE
├── neogeo.zip         Neo Geo (romset do MAME; frequentemente parte de arcade/)
├── lynxboot.img       Atari Lynx
├── disksys.rom        Famicom Disk System
├── gba_bios.bin       GBA (mGBA HLE funciona sem)
├── pcengine_cd.pce    PC Engine CD (jogos PCE-CD)
├── saturn_bios.bin    Saturn (Yabasanshiro)
└── dc/dc_boot.bin     Dreamcast (Flycast)
```

O RetroArch diz quais BIOS estão faltando no menu in-game (Quick Menu → Show in load core).

***

## ROMs comprimidas [#roms-comprimidas]

A maioria dos cores aceita `.zip` diretamente. O [zlib-ng](https://github.com/zlib-ng/zlib-ng) (drop-in replacement) usado pelo ArchR dá uma descompressão uns 10–30% mais rápida que zlib puro no A35.

Para PSX e Saturn, prefira `.chd` (Compressed Hunks of Data): gera arquivos menores que `.bin/.cue` sem nenhuma perda de decodificação. Converta com `chdman createcd -i game.cue -o game.chd`.

Para PSP, prefira `.cso` em vez de `.iso` para reduzir o uso de disco pela metade com custo de CPU desprezível.

***

## Sincronizar ROMs entre dispositivos [#sincronizar-roms-entre-dispositivos]

O serviço opcional **Syncthing** mantém uma pasta idêntica entre seu handheld e seu PC pela LAN/WiFi. Útil se você quer save-states e ROMs espelhados automaticamente sem remontar o SD.

Habilite: menu do ES → System Settings → Network → Syncthing. A UI web fica em `http://archr.local:8384`.

O serviço é pausado automaticamente enquanto você está jogando, então nunca compete por CPU.

***

## Scraping de ROMs [#scraping-de-roms]

O EmulationStation inclui o Skyscraper pré-configurado. Menu do ES → Game Settings → Scraper → Start Scraper. Puxa metadados de ScreenScraper / TheGamesDB / Mobygames.

Dica de pro: faça o scrape com o aparelho na tomada e a tela apagada (você pode entrar via SSH, rodar `pkill emulationstation && skyscraper -p <sistema>` e deixar processando por uma hora).

***

## Permissões / ownership das pastas [#permissões--ownership-das-pastas]

A partição ROMS é montada com `noatime`. Arquivos de ROM não precisam de um owner específico: emuladores rodam com permissões de file-mode, e o ArchR não impõe ownership na partição ROMS.

Se você apagar as pastas de cada sistema por acidente, elas são regeneradas no próximo boot a partir de `/storage/.config/system_directories.txt`.


# Samba (compartilhamento de rede)



O Samba permite que seu computador navegue por `/storage/roms/` (e seus save-states, screenshots, configs) como um compartilhamento de rede comum. É mais rápido do que remontar o SD e funciona sem precisar de cliente SSH.

***

## Ativar [#ativar]

EmulationStation → **System Settings** → **Network** → **Samba** → ON.

O ArchR cria o arquivo trigger `/storage/.cache/services/smbd.conf` e inicia:

* `smbd`: o servidor SMB propriamente dito
* `nmbd`: navegador de nomes NetBIOS
* `wsdd2`: descoberta para Windows 10/11 (para que o dispositivo apareça em "Rede" no Explorer)

***

## Conectar [#conectar]

### Windows [#windows]

Abra o File Explorer e digite na barra de endereço:

```
\\archr
```

Se o dispositivo não aparecer automaticamente em "Rede", force o endereço:

```
\\archr.local
\\<ip-do-dispositivo>
```

Você verá um compartilhamento: &#x2A;*`roms`**, que é `/storage/roms/`. Não precisa de login por padrão, o compartilhamento é aberto à LAN.

### macOS [#macos]

Finder → **Ir** → **Conectar a Servidor** (`Cmd+K`) → digite:

```
smb://archr.local
```

Ou use o IP. O macOS lista os compartilhamentos disponíveis, escolha **roms**.

### Linux [#linux]

A maioria dos gerenciadores de arquivos (Nautilus, Dolphin, Nemo, Thunar) aceita isso na barra de endereço:

```
smb://archr.local/roms
```

Ou monte via CLI:

```bash
sudo mkdir /mnt/archr-roms
sudo mount -t cifs //archr.local/roms /mnt/archr-roms -o guest,uid=$(id -u),gid=$(id -g)
```

***

## O que é compartilhado [#o-que-é-compartilhado]

O compartilhamento padrão `roms` expõe toda a árvore `/storage/roms/`, com leitura e escrita, sem autenticação. Do ponto de vista de segurança isso é **apenas para LAN**, ok para uso doméstico, não ative em uma rede hostil.

Para adicionar autenticação ou mudar o caminho do compartilhamento, edite `/storage/.config/samba/smb.conf` via [SSH](/docs/ssh):

```ini
[roms]
   path = /storage/roms
   browseable = yes
   read only = no
   guest ok = yes        # mude para "no" + defina "valid users = archr"
```

Depois rode `sudo systemctl restart smbd`.

***

## Durante o gameplay [#durante-o-gameplay]

O Samba é pausado automaticamente quando você lança um jogo (junto com Syncthing, Tailscale, ZeroTier, simple-http-server) e retomado quando você sai. A pausa é por processo, as conexões TCP mantêm o estado no lado do cliente e reabrem quando o serviço volta.

***

## Solução de problemas [#solução-de-problemas]

**"A descoberta de rede está desativada" no Windows.** O mDNS do Samba funciona, mas a descoberta de rede do Windows está desligada em Configurações → Rede e Internet → Propriedades. Ative-a, ou simplesmente digite `\\archr.local` diretamente.

**"O servidor especificado não pode realizar a operação solicitada".** Cliente SMB1 antigo tentando conectar. O ArchR só suporta SMB2/3. Atualize seu SO ou force o cliente para SMB2+.

**Permissão negada ao escrever em uma pasta.** O compartilhamento é aberto, mas as permissões por pasta no dispositivo são modo `755` por padrão. Via SSH:

```bash
sudo chmod -R 775 /storage/roms/<sistema>
```

**Transferências lentas (\< 5 MB/s).** Qualidade do WiFi. Verifique o sinal com `iwconfig wlan0`. O R36S tem uma antena pequena, aproximar-se 3 m do roteador normalmente dobra a vazão.


# Scraping



O scraping preenche a sua gamelist com capas, screenshots, descrições, datas de lançamento e classificação. É a diferença entre uma lista de arquivos e uma visualização de biblioteca de verdade. O EmulationStation já vem com scraping embutido.

| Antes                   | Depois                                               |
| ----------------------- | ---------------------------------------------------- |
| `Super Mario World.sfc` | arte completa de SNES + box + screenshot + descrição |

***

## Configuração [#configuração]

<Steps>
  ### Crie uma conta no ScreenScraper [#crie-uma-conta-no-screenscraper]

  Gratuita, obrigatória: [registre-se em screenscraper.fr](https://screenscraper.fr/membreinscription.php). O scraping anônimo é rate-limited a um filete, ter conta serve principalmente para rastrear as requisições.

  ### Conecte seu handheld à internet [#conecte-seu-handheld-à-internet]

  ES → **System Settings** → **Network** → ative o WiFi.

  ### Abra o scraper [#abra-o-scraper]

  ES → **Scraper** (menu principal).

  ### Login [#login]

  Informe seu usuário e senha do ScreenScraper nos campos Username / Password.

  ### Escolha o que baixar [#escolha-o-que-baixar]

  Marque quais assets você quer: screenshots, capas (2D e/ou 3D), wheel logos, marquees, manuais, vídeos. Cada um adiciona bytes por jogo. Para uma biblioteca de 200 jogos, **screenshots + box 2D + wheel** é um padrão sensato.

  ### Escolha quais sistemas [#escolha-quais-sistemas]

  O scraper oferece seleção por sistema. Pule sistemas que não vão scrappear bem (ports do PortMaster, coleções customizadas).

  ### Inicie [#inicie]

  Pressione **Start Scraper**. O ES percorre a lista de sistemas. A parte lenta é o rate limit do ScreenScraper.
</Steps>

***

## Recomendado para o tema padrão Art Book Next [#recomendado-para-o-tema-padrão-art-book-next]

Combine com as expectativas do tema para evitar thumbnails vazios:

| Configuração | Valor                                                    |
| ------------ | -------------------------------------------------------- |
| Image Source | `Screenshot` (ou `Box 2D` para temas que priorizam capa) |
| Box Source   | `Box 2D`                                                 |
| Logo Source  | `Wheel`                                                  |

Veja [themes](/docs/themes#recommended-settings) para a tabela completa de combinações.

***

## Durante o gameplay [#durante-o-gameplay]

O scraper consome bastante CPU e gera muita I/O de arquivos pequenos, não rode com um jogo aberto. Se você quer deixá-lo moendo 1000 jogos enquanto está ausente:

1. Faça SSH (assim o ES não precisa manter a tela ligada).
2. Pare o ES com `sudo systemctl stop emustation`.
3. Infelizmente, o scraper interno do ES não roda com o ES parado, não existe scraper headless na build atual do ArchR.
4. Mantenha o ES rodando mas trave a tela: no ES, **System Settings** → **Screensaver Settings** → defina timeout para 1 min e escolha o screensaver "Black". Plugue o carregador.

O ArchR pausa Syncthing/Tailscale/ZeroTier durante a emulação, mas não durante o scraping. Esses serviços continuam rodando, então scraping pesado + VPN ativa significa um pouco de contenção no WiFi.

***

## Metadados manuais [#metadados-manuais]

Às vezes o ScreenScraper pega a região errada / título errado (ex.: imports JP). Edite por jogo:

ES → destaque o jogo → pressione `Y` (Edit Metadata) → corrija qualquer campo. Salvo em `/storage/roms/<sistema>/gamelist.xml`.

Se quiser editar em lote no PC, basta editar `gamelist.xml` diretamente com seu editor XML favorito, o ES pega as mudanças no rescan.

***

## Backup antes do scraping [#backup-antes-do-scraping]

Sessões grandes de scraping batem no rate limit do ScreenScraper e podem deixar metadados pela metade se forem interrompidas. Antes de uma rodada longa, copie `/storage/roms/<sistema>/gamelist.xml` para um lugar seguro para poder reverter se não gostar do resultado.

```bash
ssh root@archr.local
cd /storage/roms/snes
cp gamelist.xml gamelist.backup.xml
```


# Shaders



O RetroArch vem com centenas de shaders que recriam scanlines de CRT, grids de LCD, artefatos de NTSC, etc. O ArchR habilita esses shaders mas mantém o padrão **desligado**: o A35 + Mali-G31 é apertado, e shaders ingênuos de múltiplos passes vão cortar seu framerate pela metade.

***

## Teste um shader nativo [#teste-um-shader-nativo]

<Steps>
  ### Inicie um jogo [#inicie-um-jogo]

  Qualquer core libretro. Standalones (PPSSPP, Flycast, etc.) têm seus próprios sistemas de shader; este guia é para libretro/RetroArch.

  ### Abra o menu [#abra-o-menu]

  `MODE + X`, Quick Menu, **Shaders**.

  ### Coloque Video Shaders em ON [#coloque-video-shaders-em-on]

  Em seguida **Load Preset**, navegue até `shaders_glsl/`.

  ### Escolha um preset [#escolha-um-preset]

  Pontos de partida recomendados para o painel 480p do R36S:

  | Caminho do arquivo                     | Caso de uso                     |
  | -------------------------------------- | ------------------------------- |
  | `shaders_glsl/handheld/lcd1x.glslp`    | Grid de LCD para GB / GBA / NDS |
  | `shaders_glsl/handheld/lcd3x.glslp`    | Grid de LCD mais nítido         |
  | `shaders_glsl/crt/crt-pi.glslp`        | CRT leve para arcade            |
  | `shaders_glsl/scanline/scanline.glslp` | Só scanlines, ultra-barato      |
</Steps>

O preset é aplicado imediatamente. Saia do menu para jogar.

***

## Salvar o preset para o sistema [#salvar-o-preset-para-o-sistema]

No menu Shaders, **Save**, **Save Game Preset** (só este jogo) ou **Save Core Preset** (todo jogo neste core) ou **Save Content Directory Preset** (todos os jogos nessa pasta).

Presets por jogo ficam em `/storage/.config/retroarch/config/<core>/<game>.glslp`. Por core em `/storage/.config/retroarch/config/<core>/<core>.glslp`.

***

## Crie um preset customizado de múltiplos passes [#crie-um-preset-customizado-de-múltiplos-passes]

O exemplo abaixo é a aparência canônica de "GBA hardware real": correção de cor + grid de LCD em dois passes:

<Steps>
  ### Abra Shaders, mude passes para 2 [#abra-shaders-mude-passes-para-2]

  Quick Menu, Shaders, **Shader Passes**, 2.

  ### Pass 1, correção de cor [#pass-1-correção-de-cor]

  Clique no pass 1, navegue até `shaders_glsl/handheld/`, escolha `vba-color.glslp`.

  ### Pass 2, grid de LCD [#pass-2-grid-de-lcd]

  Clique no pass 2, navegue até `shaders_glsl/handheld/`, escolha `lcd1x.glslp`.

  ### Aplicar [#aplicar]

  Clique em **Apply Changes**.

  ### Ajuste os parâmetros [#ajuste-os-parâmetros]

  **Shader Parameters** é onde cada shader expõe seus controles. Para esta combinação:

  * Darken: `0.25`
  * Brighten Scanlines: `28.0`
  * Brighten LCD: `6.0`

  ### Salve [#salve]

  De volta ao menu Shaders, **Save**, defina **Simple Presets** para **off**, **Save Shader Preset As**, dê um nome (ex.: `gba-real-hw`).
</Steps>

O preset nomeado aparece em **Load Preset** na próxima vez, e também pode ser selecionado em ES, Game Settings, Per System Advanced Configuration, Shader Set.

***

## Orçamento de performance [#orçamento-de-performance]

O R36S tem pouquíssima folga para passes de shader. Como regra de bolso no RK3326 com overclock DESLIGADO (CPU 1.4 GHz + GPU 650 MHz):

| Categoria        | Ok?          | Exemplos                              |
| ---------------- | ------------ | ------------------------------------- |
| 1 pass barato    | ✅            | scanline, lcd1x, vba-color            |
| 1 pass caro      | geralmente ✅ | crt-pi, crt-easymode                  |
| 2 passes baratos | geralmente ✅ | gba-real-hw (vba-color + lcd1x)       |
| 2 passes caros   | ⚠️           | crt-royale, crt-aperture-grille       |
| 3+ passes        | ❌            | a maioria das variantes do CRT-Royale |

Cores de Dreamcast / N64 / PSP já consomem a GPU; mesmo um shader de 1 pass por cima pode derrubar você abaixo de 60 fps. Reserve os shaders chamativos para cores de 8 / 16 bits.

Habilite **Enable CPU Overclock** se quiser tentar shaders mais pesados, veja [Overclock](/docs/overclock).

***

## Conjuntos de shaders estilo ROCKNIX via menu do ES [#conjuntos-de-shaders-estilo-rocknix-via-menu-do-es]

O ES expõe um seletor de conjunto de shaders sem precisar entrar no RetroArch:

ES, **Game Settings**, **Per System Advanced Configuration**, **Shader Set**, escolha no dropdown.

Isso aplica o shader escolhido a todo jogo daquele sistema. Útil como toggle rápido. Os presets customizados que você salvou antes também aparecem aqui.


# Acesso SSH



O SSH vem **desativado por padrão** por segurança. Ative-o pelo menu do EmulationStation e depois conecte-se a partir do seu computador.

***

## Ativar SSH [#ativar-ssh]

<Steps>
  ### Alternar no ES [#alternar-no-es]

  EmulationStation → \*\* \*\* (Start) → **System Settings** → **Network** → **Enable SSH** → ON.

  O ArchR cria `/storage/.cache/services/sshd.conf` (o arquivo trigger que a unit do systemd observa) e depois executa `systemctl start sshd`.

  ### Opcional: ativar a cada boot [#opcional-ativar-a-cada-boot]

  Mesmo menu, deixe a opção ligada. O arquivo trigger persiste, então `sshd.service` inicia no boot via `ConditionPathExists=`.

  ### Encontre o IP do dispositivo [#encontre-o-ip-do-dispositivo]

  Em ES → System Information o IP é exibido. Ou via ssh a partir de qualquer dispositivo na mesma LAN:

  ```bash
  ping archr.local
  ```

  O mDNS publica `archr.local` automaticamente (Avahi).
</Steps>

***

## Conectar [#conectar]

```bash
ssh root@archr.local
# ou pelo IP:
ssh root@192.168.x.x
```

Credenciais padrão:

```
usuário     root
senha       archr
```

<Callout type="warn">
  Troque a senha após o primeiro login bem-sucedido. A senha padrão é pública, qualquer pessoa na LAN consegue adivinhá-la.
</Callout>

```bash
passwd
```

***

## Autenticação por chave (recomendado) [#autenticação-por-chave-recomendado]

```bash
# no seu computador
ssh-copy-id root@archr.local
```

Depois desative a autenticação por senha no dispositivo (já logado via SSH):

```bash
sudo sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd
```

***

## Transferência de arquivos [#transferência-de-arquivos]

O `scp` (cópia única) é o jeito mais simples de mover arquivos. ROMs, save-states, screenshots:

```bash
# enviar uma ROM
scp game.sfc root@archr.local:/storage/roms/snes/

# baixar todos os screenshots
scp root@archr.local:'/storage/screenshots/*' ~/Pictures/r36s-screenshots/

# enviar um diretório
scp -r ~/roms/psx root@archr.local:/storage/roms/
```

Para sincronização contínua, use `rsync`, ele ignora arquivos que não mudaram:

```bash
rsync -avh --delete ~/roms/snes/ root@archr.local:/storage/roms/snes/
```

Para acesso gráfico, seu gerenciador de arquivos provavelmente suporta `sftp://root@archr.local/storage/roms/`.

***

## Dicas de SSH [#dicas-de-ssh]

**EmulationStation atrapalhando.** O ES bloqueia o framebuffer, você não consegue rodar um programa X/wayland via SSH. Mas dá para parar o ES e rodar uma ferramenta pontual:

```bash
sudo systemctl stop emustation
# agora você pode rodar coisas
sudo systemctl start emustation
```

**Tarefas longas (scrape, rsync de TBs, etc.).** Use `screen` ou `nohup` para que sobrevivam a desconexões de SSH:

```bash
screen -S scrape
skyscraper -p snes
# Ctrl-A D para desconectar. Reconecte depois com: screen -r scrape
```

**Inspecionando o boot.** Os logs ficam em `/var/log/boot.log` (não no `journalctl`, o journald é volátil). O trace do autostart fica em `/storage/.boot_last_step` somente quando o boot anterior travou.

**Scripts de bench.** `/flash/bench.sh <cenário> [duração]` coleta PSI / freq / temp / vmstat pela duração informada em `/storage/bench-results/`. Útil para reportar regressões de performance.

***

## Desativar SSH [#desativar-ssh]

Mesmo menu, alterne para OFF. O arquivo trigger é removido e o `sshd.service` para. O próximo boot não o inicia.

***

## Notas de segurança [#notas-de-segurança]

* **Risco em LAN pública**: com as credenciais padrão e SSH ligado, qualquer um no mesmo WiFi pode logar. Troque a senha.
* **Tailscale/ZeroTier**: se você ativar uma VPN, seu dispositivo fica alcançável por qualquer um na mesma VPN, a mesma orientação vale.
* **Port forwarding**: **não** redirecione a porta 22 para o seu handheld no roteador de casa. A instalação padrão não é endurecida para a internet pública.
* **Desativar root**: `sudo passwd -l root` se você preferir que ninguém logue como root via SSH. O usuário `archr` tem `sudo` para quando precisar de comandos elevados.


# Status



## Validado em hardware (R36S V21) [#validado-em-hardware-r36s-v21]

```
kernel              6.12.79                   ok
display             MIPI DSI                  ok    43 DTBOs de painel
gpu / panfrost      Mesa 26.0.5               ok    Mali-G31, GLES 3.1
gpu / libmali       r52p0-00eac0              ok    patch de PM elimina unbalance do regulador
gpu turbo 650 MHz   1.150 V (= V de 600 MHz)  ok
cpu turbo 1512 MHz  1.4 V (regulador 1.45 V)  ok    alterna via Enable CPU Overclock
audio.spk           RK817                     ok    hotkeys de volume, persistência
audio.hp            RK817                     ok    detecção de jack, troca automática de caminho
audio.hdmi          rk-hdmi                   ok
emustation          fork do ROCKNIX           ok    roda na taxa de atualização do painel
retroarch           libretro                  ok    KMS/DRM + EGL + GLES 2.0
ppsspp-sa           v1.18+                    ok    GLTHREAD ligado
flycast-sa          recente                   ok    resolução 240 por padrão, GLTHREAD ligado
mupen64plus-sa      latest                    ok    preset GLideN64 performance
drastic-sa          NDS default               ok
yabasanshiro-sa     Saturn experimental       ok    apenas cenas leves
duckstation-sa      Software renderer         ok
battery             rk817                     ok    3200 mAh, suporte a carga, aviso por LED
brightness          sysfs + udev              ok    MODE+VOL, persiste
usb_otg             u2phy                     ok    entrada de teclado
shutdown            pmic                      ok    desligamento de trilhos em duas etapas
boot                splash do initramfs       ok    19 s típicos
zlib-ng             2.2.4 --zlib-compat       ok    ABI libz.so.1 preservada
mesa lto+speed                                ok    +5–8 % do lado CPU
cma 96 MB                                     ok    ~30 MB livres em idle (era 8 MB com 64 MB)
boot fat sync                                 ok    primário == backup, 65 525+ clusters
fs-resize                                     ok    fsck.fat -a -w após fatlabel
runemu pause services                         ok    Syncthing/Tailscale/ZeroTier/HTTP suspensos
ksm pause-during-game                         ok    save+restore, jitter de frametime ↓
```

***

## Em andamento [#em-andamento]

```
detecção automática de painel    ⬜    substitui o assistente de seleção de painel
A/B preempt voluntary            ⬜    pendente de reprodutibilidade no bench
mesa-glthread por core           ⬜    standalones prontos, libretro permanece desligado
```

***

## Não testado no 6.12 (carry-over do 6.6) [#não-testado-no-612-carry-over-do-66]

```
wifi networkmanager     :    iwd + connman como padrão; NM mantido como legado
bluetooth controller    :    a2dp não validado neste kernel
hdmi audio out          :    em bancada, ainda sem display testado
```

***

## Compatibilidade com clones [#compatibilidade-com-clones]

```
                     R36S original            Clone (K36, G80CA, RX6S, Powkiddy …)
u-boot               BSP (display+logo)       Mainline v2025.10 (sem logo)
volume               gpio-keys-vol            adc-keys SARADC ch2
config de boot       boot.ini                 boot.scr
display dtb          uboot-display.dtb        não é necessário
kernel               compartilhado 6.12.79    compartilhado
rootfs               compartilhado            compartilhado
conjunto de painéis  15 DTBOs originais       18 DTBOs clone + 10 soysauce
```

***

## O que NÃO é suportado no RK3326 [#o-que-não-é-suportado-no-rk3326]

Estes sistemas são explicitamente ocultados do menu no RK3326 porque o Cortex-A35 simplesmente não consegue rodá-los em framerates usáveis:

```
GameCube, Wii, WiiWare    inviável no A35
Wii U                     inviável
PS2 (AetherSX2)           inviável no A35
Switch (Yuzu/Ryujinx)     inviável
3DS (Citra)               inviável
```

Outras distros para RK3326 que *de fato* expõem esses sistemas acabam rodando-os em FPS de slideshow. O ArchR não atrai usuários para essa frustração.


# Referência técnica



## Pipeline de build [#pipeline-de-build]

`make docker-RK3326` executa todo o sistema de stages no estilo LibreELEC dentro do Docker. Aproximadamente 700 passos de instalação para \~263 pacotes.

```
toolchain    cross-gcc 14.2 / glibc / binutils (stage do host)
linux        kernel 6.12 LTS + DTS do RK3326 + patches do ArchR
mali-bifrost mali_kbase out-of-tree + patch de PM unbalance do ArchR
mesa         26.0.5 Panfrost (GLES 3.1, +speed +lto)
zlib (-ng)   zlib-ng 2.2.4 em modo --zlib-compat (libz.so.1)
retroarch    1.x + conjunto de cores libretro
emulators    Flycast, PPSSPP, melonDS, DraStic, Yabasanshiro, Mupen64Plus standalone
es           EmulationStation (fork do ROCKNIX)
image        FAT32 BOOT (272 MB, clusters de 4 KB) + ext4 ROOT + ext4 STORAGE
```

Saída em `target/ArchR-R36S.aarch64-DATE-{original,clone}.img.gz`.

***

## Kernel [#kernel]

```
Source       Linux 6.12 LTS (fork BSP, patches da Rockchip + ArchR)
Toolchain    gcc 14.2.0
Config       projects/ArchR/devices/RK3326/linux/linux.aarch64.conf
HZ           300
PREEMPT      CONFIG_PREEMPT=y (A/B com PREEMPT_VOLUNTARY pendente de bench)
DEBUG        todos os sanitizers / KASAN / KMEMLEAK / FTRACE desligados no release
DEBUG_FS     y (intencional, necessário para debugfs do CMA e introspecção de PSI)
CMA          96 MB (subiu de 64 MB após auditoria; veja /docs/features)
ZRAM         lzo-rle por padrão (zstd opcional via memory-manager)
ZSWAP        desabilitado (zswap.enabled=0 na cmdline)
```

### DTS [#dts]

Origem: `rk3326-gameconsole-r36s.dts` (placa) + `rk3326-gameconsole-r3xs.dtsi` (família de placas) + `px30.dtsi` (SoC) + `000-rk3326-dts.patch` (overrides do ArchR).

| Nó                  | O que mudamos                                                                               | Por quê                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `cpu0_opp_table`    | Adicionada OPP turbo de 1512 MHz @ 1.4 V; mantida a escada completa 408–1416                | Acessível via "Enable CPU Overclock"                                        |
| Regulador `vdd_arm` | `regulator-max-microvolt` 1.35 V → 1.45 V                                                   | Caso contrário o kernel rejeita a OPP de 1512 silenciosamente               |
| `gpu_opp_table`     | Restauradas as OPPs inferiores de 200/300/400 MHz; adicionadas as superiores de 600/650 MHz | OPPs baixas são necessárias para o boot; 650 MHz é o turbo diário a 1.150 V |
| `dmc` / `dfi`       | Definidos explicitamente para que o devfreq possa ser controlado                            | O px30.dtsi upstream os mantém desabilitados                                |
| `gpu`               | Adicionados `clock-names="bus"`, `resets`, `power_policy="coarse_demand"`, power\_models    | Necessário para panfrost/mali\_kbase modernos                               |
| Alias `ethernet0`   | Adicionado                                                                                  | Nomeação futura para hot-plug de USB-Ethernet                               |
| Power model         | `mali-simple-power-model` + `mali-g31-power-model`                                          | DVFS com consciência térmica                                                |

### Patches de kernel [#patches-de-kernel]

Patches de kernel específicos do ArchR mais relevantes (`projects/ArchR/packages/linux-drivers/mali-bifrost/patches/6.12-LTS/` e `projects/ArchR/packages/linux/patches/6.12-LTS/`):

* **`mali-bifrost/002-fix-unbalanced-regulator-clk-pm.patch`**: elimina os avisos `unbalanced disables for vdd_logic` quando `vdd_logic` é compartilhado com rockchip-pm-domain. Adiciona um flag `gpu_power_held` que acompanha o estado de enable do próprio driver.
* **`linux/0005-drm-panfrost-Add-SYSTEM_TIMESTAMP*.patch`**: requerido pelo Mesa 26.0.5 para queries `GL_TIMESTAMP` e `VK_KHR_calibrated_timestamps`.
* **`linux/0006-drm-panfrost-Add-cycle-counter-job-requirement.patch`**: encanamento para `VK_KHR_shader_clock`.
* **`linux/0007-0010-drm-panfrost-Add-BO-labelling*.patch`**: auxílio de debug; o Mesa chama o novo IOCTL ainda que os labels sejam apenas para debug.

***

## Mesa 26.0.5 [#mesa-2605]

Compilado com `+speed +lto` em `packages/graphics/mesa/package.mk`. Flags do configure:

```
-Dgallium-drivers=panfrost   -Dvulkan-drivers=
-Dgles1=disabled             -Dgles2=enabled
-Dglvnd=disabled             -Dplatforms=wl
-Dglx=disabled               -Dshader-cache=enabled
-Dopengl=true                -Dgbm=enabled
-Degl=enabled                -Dlibunwind=disabled
-Dbuild-tests=false          -Ddraw-use-llvm=false
```

`-Dgallium-drivers=panfrost` apenas, sem fallback de software no release (o overhead do LLVMpipe seria maior que o hardware no G31). `-Dvulkan-drivers=` vazio porque o PanVK não é conformante em Bifrost v9.

### Variáveis de runtime [#variáveis-de-runtime]

Exportadas globalmente em `/etc/profile.d/041-panfrost`:

```bash
PAN_MESA_DEBUG=forcepack             # dica de format-pack específica do G31
MESA_NO_ERROR=1
MESA_SHADER_CACHE_DIR=/storage/.cache/mesa_shader_cache
MESA_SHADER_CACHE_MAX_SIZE=128MB
```

Whitelist `MESA_GLTHREAD=true` por emulador, apenas Flycast e PPSSPP standalone (veja [GPU driver](/docs/gpu-driver) e o `docs/mesa-glthread-matrix.md` no repo).

***

## libmali (alternativo) [#libmali-alternativo]

`mali_kbase` out-of-tree r52p0-00eac0 com o patch de PM do regulador/clk. Trocado no boot via `/usr/bin/gpudriver --start`, que lê `/storage/.config/system.cfg → gpu.driver`. Fallback automático se algum dos drivers falhar em se ligar ao nó da GPU.

***

## U-Boot [#u-boot]

|                | Original                                           | Clone                            |
| -------------- | -------------------------------------------------- | -------------------------------- |
| Origem         | `bootloader/u-boot-rk3326/` (BSP)                  | mainline + patches do ROCKNIX    |
| Config de boot | `boot.ini`                                         | `boot.scr` (`mkimage -T script`) |
| Display        | hwrev SARADC ch0 → DTB da placa → DRM → `logo.bmp` | nenhum                           |
| Defconfig      | `odroidgoa`                                        | `rk3326-handheld_defconfig`      |

Os dois binários diferem o suficiente para que não seja possível dar boot num clone com o build do BSP. O ArchR entrega ambos; o build escolhe com base em `--variant` (ou `make docker-RK3326` produz os dois).

***

## Layout da imagem [#layout-da-imagem]

```
GPT
├── 1   FAT32  BOOT     272 MB    65525+ clusters de 4 KB (conforme spec FAT32)
│                       Kernel, DTBs, todos os 43 panel overlays, script U-Boot
├── 2   ext4   ROOT     ~4.6 GB   sistema read-only (squashfs em alguns builds antigos)
└── 3   ext4   STORAGE  resto     gravável: configs, ROMs, save-states, screenshots
```

O `mkimage` roda `fsck.fat -a -w` no FAT do BOOT antes de cimentar a imagem, o que garante que os setores de boot primário e backup fiquem byte a byte idênticos. O script `fs-resize` no dispositivo faz o mesmo depois que o `fatlabel` regenera o UUID, então o boot pós-resize continua consistente.

***

## Fluxo de boot [#fluxo-de-boot]

```
0.0   POR / SPL (na ROM)
0.x   U-Boot lê SARADC ch0 → ID da placa
0.5   carrega DTB da placa + overlay do painel a partir de /flash/
0.7   splash do initramfs (BMP via xxd, /init estático em aarch64)
~7    entrega ao kernel
~9    target do systemd
~12   archr-autostart (quirks + governor + display + bluetooth + checagem de ssh)
~17   EmulationStation
~19   pronto para jogar
```

O trace é escrito em `/storage/.boot_last_step` antes de cada script de autostart rodar, e apagado em caso de sucesso. Se o boot anterior travou, o arquivo `/storage/.boot_last_hang` nomeia o script que travou. Inclua isso em relatos de bug.

***

## Painéis de display [#painéis-de-display]

43 panel overlays gerados a partir de dumps de DTB dos fabricantes:

```
config/archr-dts/
├── original/    (15)   R36S V20–V22, variantes OGS
├── clone/       (18)   K36, R33S, R36 Max, RX6S, várias famílias de painel
└── soysauce/    (10)   hardware baseado no Y3506
```

O gerador (`config/mipi-generator/generator.sh` → `archr-dtbo.py`) extrai a sequência de init e os timings do painel a partir do DTB do fabricante, aplica um template-base de overlay do ArchR e emite um `.dtbo` por revisão de placa-mãe. São produzidas seis variantes por painel:

```
default                    layout K36, sem swap JP, áudio normal
_JPk36                     layout K36, JP A↔B / X↔Y
_JPmm                      layout MyMini, swap JP
_SRs                       força caminho de áudio simples
_JPk36_SRs                 K36 + JP + SRs
_JPmm_SRs                  MyMini + JP + SRs
```

258 DTBOs no total. O Flasher (ou cópia manual) coloca um destes em `/flash/overlays/mipi-panel.dtbo` no momento da gravação.

***

## Armadilhas [#armadilhas]

Casos extremos que apareceram durante o desenvolvimento. Nenhum se aplica a uma gravação normal de release. Só importam se você está mexendo no build.

**Contagens de cabeçalho de hunk em patches DTS importam.** Uma contagem `@@ -X,Y +A,B @@` errada faz o `patch` abortar silenciosamente o resto dos hunks, deixando "lixo" recuperado. Valide com `patch --dry-run --verbose` sobre uma fonte limpa após cada edição de DTS.

**OPPs de `turbo-mode` se escondem atrás de `cpufreq/boost`.** Setar `scaling_max_freq=1512000` diretamente não faz nada se `boost=0`. A frequência não aparece em `scaling_available_frequencies` até você escrever `1` em `cpufreq/boost`. O `set_cpu_max_freq highest` do ArchR lê tanto `scaling_available_frequencies` *quanto* `scaling_boost_frequencies`.

**O regulator-max do `vdd_arm` controla a disponibilidade de OPPs silenciosamente.** Se uma OPP solicita uma tensão acima de `regulator-max-microvolt`, o kernel descarta a OPP sem nada no `dmesg`, e `policy_has_boost_freq()` retorna false → o sysfs `cpufreq/boost` **nunca é criado**.

**`fatlabel -i -r` dessincroniza primário/backup do FAT.** Reescreve UUID/label apenas no setor 0; o backup no setor 6 mantém os valores antigos. Alguns builds de U-Boot ocasionalmente leem o backup, causando travas intermitentes de boot após o resize. Solução: rodar `fsck.fat -a -w` em seguida.

**Avisos de `patch.fat` / `cluster < 65525` são na maioria inofensivos**, mas ocasionalmente atrapalham versões específicas de ROM do U-Boot. O ArchR usa `BOOT_SIZE=272 MB` com clusters de 4 KB → 69500+ clusters → acima da spec.

**O diretório raiz do shader cache do Mesa precisa existir.** O Mesa não vai fazer `mkdir` em `MESA_SHADER_CACHE_DIR` por conta própria; apenas cai silenciosamente para modo sem cache. O `runemu.sh` cria `/storage/.cache/mesa_shader_cache` se estiver faltando.

**`panfrost_devfreq` precisa de OPPs baixas de GPU para inicializar.** Remover as OPPs de 200/300/400 MHz (para forçar um piso mais alto) bloqueia a inicialização da GPU no boot. O driver espera que a menor OPP publicada seja alcançável. Mantenha a escada; force um piso alto em runtime com `set_gpu_min_freq highest`.

**`PREEMPT` vs `PREEMPT_VOLUNTARY` ainda não foi bencheado.** O kernel atualmente usa `PREEMPT`; o ROCKNIX usa `VOLUNTARY`. A/B pendente com o bench no dispositivo.

**O unbalance do regulador no mali\_kbase é um patch de kernel, não um quirk.** Sem o `002-fix-unbalanced-regulator-clk-pm.patch`, cada transição de PM emite `unbalanced disables for vdd_logic` e `Enabling unprepared clk_gpu`, audível como estalo no Mario 64.


# Temas



O ArchR vem com o [**Art Book Next**](https://github.com/anthonycaccese/art-book-next-es) como tema padrão. É o mesmo tema que o ROCKNIX usa, projetado para suportar todas as proporções (16:9, 4:3, 16:10, 5:3, 3:2, 1:1). Ele fica instalado em `/usr/share/themes/es-theme-art-book-next` e tem um symlink no caminho de temas do usuário como `system-theme`.

***

## Configurar o tema padrão [#configurar-o-tema-padrão]

ES, **UI Settings**, **Theme Configuration** tem seis controles:

| Opção                   | O que faz                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Distribution**        | Qual pasta dentro das suas ROMs é checada por customizações de tema. Deixe em `ROCKNIX` (herdado do upstream), aponta para o caminho certo. |
| **Aspect Ratio**        | Detectado automaticamente (640×480 ≈ 4:3 no R36S). Sobrescreva se o layout parecer estranho.                                                |
| **Color Scheme**        | Escolha um esquema de cores embutido ou `custom` para usar o seu (veja abaixo).                                                             |
| **Font Size**           | `default` ou `custom`.                                                                                                                      |
| **System View Style**   | Layout da tela inicial: Centered Artwork, Multi Artwork, Fullscreen Artwork, Carousel.                                                      |
| **Gamelist View Style** | Layout por lista de jogos: variantes Metadata On / Metadata Off / Immersive.                                                                |

***

## Configurações recomendadas [#configurações-recomendadas]

Para um R36S (4:3, 640×480) com screenshots:

| Configuração          | Valor                                                   |
| --------------------- | ------------------------------------------------------- |
| Aspect Ratio          | `4:3` (auto)                                            |
| Scraper: Image Source | `Screenshot`                                            |
| Scraper: Box Source   | `Box 2D`                                                |
| Scraper: Logo Source  | `Wheel`                                                 |
| Gamelist View Style   | `Metadata On (Immersive)` ou `Metadata Off (Immersive)` |

Para priorizar boxart:

| Configuração          | Valor         |
| --------------------- | ------------- |
| Scraper: Image Source | `Box 2D`      |
| Scraper: Box Source   | `None`        |
| Scraper: Logo Source  | `Wheel`       |
| Gamelist View Style   | `Metadata On` |

***

## Customizando o Art Book Next [#customizando-o-art-book-next]

O Art Book Next lê as customizações de um caminho específico para que suas alterações sobrevivam a updates do ArchR:

```
/storage/roms/rocknix/theme-customizations/art-book-next/
```

(O nome da pasta é `rocknix` porque essa é a chave de distribuição do upstream, o tema reutiliza ela entre os forks. Não renomeie.)

### Arte de fundo [#arte-de-fundo]

```
/storage/roms/rocknix/theme-customizations/art-book-next/backgrounds/
   _default.jpg          fallback para sistemas sem imagem customizada
   snes.jpg              override por sistema (filename = es system tag)
   psx.png
   ...
```

Em Theme Configuration, defina **System View Style** para uma das variantes `(Custom)`:

* Centered Artwork (Custom)
* Multi Artwork (Custom)
* Fullscreen Artwork (Custom)

Para criar uma arte centralizada que siga a máscara de proporção do tema, o autor original publica uma [máscara de recursos](https://github.com/anthonycaccese/art-book-next-es/tree/main/resources/customizations).

### Logos customizados [#logos-customizados]

```
/storage/roms/rocknix/theme-customizations/art-book-next/logos/
   snes.svg              SVG preferido (escala limpa)
   psx.png
```

**Color Scheme** com `Custom` é o que habilita a sobrescrita.

### Esquema de cores [#esquema-de-cores]

[Baixe o template](https://github.com/anthonycaccese/art-book-next-es/blob/main/resources/customizations/colors.xml), salve como:

```
/storage/roms/rocknix/theme-customizations/art-book-next/colors.xml
```

Edite os valores, defina **Color Scheme** como `Custom`.

### Tamanho da fonte [#tamanho-da-fonte]

[Baixe o template](https://github.com/anthonycaccese/art-book-next-es/blob/main/resources/customizations/fonts.xml), salve como:

```
/storage/roms/rocknix/theme-customizations/art-book-next/fonts.xml
```

Defina **Font Size** como `Custom`.

***

## Adicionando temas extras [#adicionando-temas-extras]

Solte um tema de terceiros em:

```
/storage/.emulationstation/themes/
```

Cada tema fica na sua própria pasta. O ES detecta no próximo boot (ou em **UI Settings**, **Theme Set**, escolha).

### Fontes de temas compatíveis [#fontes-de-temas-compatíveis]

O EmulationStation do ArchR é forkado da mesma linhagem Batocera/ROCKNIX, então temas projetados para qualquer um deles geralmente funcionam:

* **[Temas da Batocera](https://batocera.org/themes.php)**, catálogo grande. Alguns não incluem todos os sistemas ou não se encaixam fora de 16:9.
* **[es-theme-gbz35-jelos](https://github.com/booYah187/es-theme-gbz35-jelos)**, funciona bem em 4:3.
* **[es-theme-albedo](https://github.com/mluizvitor/es-theme-albedo)**, 3:2, 4:3, 5:3.
* **[es-theme-elementerial](https://github.com/mluizvitor/es-theme-elementerial)**, 3:2, 4:3, 5:3.

<Callout type="info">
  Temas projetados para dispositivos orientados em retrato ou 16:9 podem ficar apertados no painel 4:3 do R36S. Teste antes de fixar, o seletor de tema é reversível.
</Callout>

***

## Escrevendo seu próprio tema [#escrevendo-seu-próprio-tema]

Fora do escopo desta página, mas o [guia de temas da Batocera](https://wiki.batocera.org/write_themes_for_emulationstation) é a referência mais próxima da variante do EmulationStation que o ArchR usa.


# Solução de problemas



## Problemas de boot [#problemas-de-boot]

### Tela preta, apenas o splash [#tela-preta-apenas-o-splash]

Panel overlay errado. Causa mais comum quando se grava pela primeira vez um clone com uma revisão recente de placa-mãe.

**Solução:** regrave com o [Flasher](/docs/installation) e escolha no dropdown de painel a revisão exata impressa na silkscreen da placa-mãe.

### Boot loops, nunca chega no ES [#boot-loops-nunca-chega-no-es]

Três possibilidades, em ordem de probabilidade:

1. **Instabilidade de CPU em turbo** (somente com Enable CPU Overclock ligado, muito raro). Desligue, remova o SD, edite `/storage/.config/system.cfg` em um PC e defina `enable.turbo-mode=0`.
2. **fs-resize travou** no primeiro boot. Capture `cat /storage/.boot_last_hang` depois do boot bem-sucedido seguinte. Esse arquivo nomeia o script que parou.
3. **Variante de imagem errada** (original em um clone ou vice-versa). Regrave com a variante correta.

### Boot chega no ES mas congela ali [#boot-chega-no-es-mas-congela-ali]

Pare o ES e veja o que está segurando:

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

Ou leia o log de boot (`/var/log/boot.log`, note que o journald é volátil, então os logs do boot anterior são perdidos). Reinicie o ES com `sudo systemctl start emustation` depois de identificar o problema.

### "Boot anterior travou em \<script>" [#boot-anterior-travou-em-script]

O mecanismo de trace pegou uma trava no boot anterior. O script nomeado é o culpado. Abra uma issue com:

* O nome do script em `/storage/.boot_last_hang`
* `dmesg | tail -200` do boot pós-recuperação
* A saída de `cat /flash/fs-resize.log` se aplicável

***

## Display [#display]

### Cores parecem erradas / invertidas [#cores-parecem-erradas--invertidas]

Swap BGR vs RGB no painel. Acontece em algumas variantes clone em que a silkscreen veio com o rótulo de revisão errado. Regrave com a próxima revisão numericamente similar.

### "Tearing" da tela em alguns emuladores [#tearing-da-tela-em-alguns-emuladores]

`video_threaded` vem ligado por padrão. Para jogos sensíveis a tearing, no RetroArch Quick Menu → Settings → Video → Output → Vertical Sync = ON.

### O brilho tem menos passos do que eu gostaria [#o-brilho-tem-menos-passos-do-que-eu-gostaria]

O ArchR usa 3% por passo (33 níveis distintos). Se precisar de controle mais fino, edite `/storage/.config/profile.d/099-freqfunctions` e ajuste o passo de brilho.

***

## Áudio [#áudio]

### Sem som nenhum [#sem-som-nenhum]

```bash
amixer get 'Playback Path'    # deve ser SPK ou HP
amixer get DAC                # deve ser > 0
cat /sys/class/extcon/*/state # detecção de HP (1 = conectado)
```

Se o `Playback Path` estiver errado, force: `amixer set 'Playback Path' SPK`.

### Estalo de áudio no Mario 64 / jogos 3D pesados [#estalo-de-áudio-no-mario-64--jogos-3d-pesados]

Se você está ouvindo estalo junto com `unbalanced disables for vdd_logic` no `dmesg`, está em um build pré-v8. Atualize para o release mais recente. O patch de PM no `mali_kbase` elimina isso.

Se continuar acontecendo no mais recente: abra uma issue com `dmesg | grep -iE 'vdd_logic|clk_gpu|mali'` e o nome do jogo.

### Áudio Bluetooth picotando [#áudio-bluetooth-picotando]

A latência do A2DP é sensível ao codec BT. Force SBC + low-quality se o seu dispositivo suporta apenas perfis básicos:

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

No menu Bluetooth do ES, o toggle "Force SBC" faz o mesmo.

***

## Performance [#performance]

### O jogo roda mais lento do que o esperado [#o-jogo-roda-mais-lento-do-que-o-esperado]

Em ordem:

1. **CPU governor**: deve ser `performance` durante o gameplay. Verifique: `cat /sys/devices/system/cpu/cpufreq/policy0/scaling_governor`.
2. **GPU governor**: deve ser `performance`. `cat /sys/class/devfreq/ff400000.gpu/governor`.
3. **CPU max freq**: `cat /sys/devices/system/cpu/cpufreq/policy0/scaling_max_freq`. Sem overclock = 1416000, com overclock = 1512000.
4. **Serviços em background**: `systemctl is-active syncthing tailscaled zerotier-one simple-http-server`. Todos devem estar `inactive` durante um jogo (são pausados automaticamente pelo `runemu.sh`).
5. **Throttling térmico**: `cat /sys/class/thermal/thermal_zone0/temp` (unidade: m°C). Acima de 70 000 (70 °C) dispara throttle passivo. Dê uma pausa, deixe esfriar.

### Rode o bench [#rode-o-bench]

Para diagnósticos reproduzíveis:

```bash
bash /flash/bench.sh psp 60   # tag do cenário, duração em segundos
```

Resultados em `/storage/bench-results/<timestamp>-psp/`: `summary.json` tem agregados estilo p99, `psi.log` tem stalls de pressão por segundo, `freq-therm.log` tem a trajetória de frequência.

***

## Storage / ROMs [#storage--roms]

### Algumas ROMs não aparecem depois que copiei [#algumas-roms-não-aparecem-depois-que-copiei]

O ES só faz rescan no boot. Menu do ES → Game Settings → Rescan ROMs → aguarde → as ROMs aparecem.

### "Disk full" mas meu SD é enorme [#disk-full-mas-meu-sd-é-enorme]

Verifique se a partição foi redimensionada: `df -h /storage`. Deve mostrar \~95% da capacidade do SD. Se não, o fs-resize não rodou. O arquivo marcador `/storage/.please_resize_me` dispara o resize no próximo boot:

```bash
sudo touch /storage/.please_resize_me
sudo reboot
```

### Save-states sumiram depois de regravar [#save-states-sumiram-depois-de-regravar]

Eles ficam em `/storage/saves/`. Se você regravou e a partição foi apagada (o Flasher sempre apaga), eles se foram. Faça backup na próxima vez:

```bash
scp -r root@archr.local:/storage/saves ~/r36s-saves-backup/
```

***

## SSH / rede [#ssh--rede]

### Não conecta: "connection refused" [#não-conecta-connection-refused]

O SSH vem desligado por padrão. ES → System Settings → Network → Enable SSH → ON.

### "archr.local" não resolve [#archrlocal-não-resolve]

Problema com Avahi/mDNS. Use o IP (visível em ES → System Information). Ou:

```bash
# de um Linux/macOS
avahi-browse -art | grep archr
```

### WiFi conecta mas não tem internet [#wifi-conecta-mas-não-tem-internet]

Problema de DNS. Tente:

```bash
sudo systemctl restart connman
sudo connmanctl scan wifi
sudo connmanctl services
```

***

## PortMaster [#portmaster]

### Port trava em tela preta [#port-trava-em-tela-preta]

Provavelmente as permissões de `/dev/uinput` estão erradas. `ls -la /dev/uinput` deve mostrar `crw-rw-rw-` (modo 666). Se não estiver, a regra udev não aplicou. Por ora, `sudo chmod 666 /dev/uinput` e reporte o bug.

### "Permission denied" rodando gptokeyb [#permission-denied-rodando-gptokeyb]

Mesma coisa: permissões do uinput.

### `box86: assertion failure` [#box86-assertion-failure]

O port foi construído contra um libstdc++ mais novo do que o ArchR entrega. Aguarde uma atualização (o PortMaster costuma corrigir em poucos dias) ou reporte no [Discord do PortMaster](https://discord.gg/CMX5sTrgHQ).

### A GUI do PortMaster em si não inicia [#a-gui-do-portmaster-em-si-não-inicia]

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

Leia o trace. O script é idempotente (rodar de novo é seguro).

***

## Como abrir um bom relato de bug [#como-abrir-um-bom-relato-de-bug]

```
1. Hardware              ────  R36S V21 / K36 / RX6S etc.
2. Versão do ArchR       ────  em ES System Information, ou `cat /etc/os-release`
3. Variante da imagem    ────  original | clone
4. Painel selecionado    ────  revisão de placa-mãe impressa na silkscreen
5. O que você tentou     ────  passos exatos para reproduzir
6. O que aconteceu       ────  observado vs esperado
7. Logs:
   /var/log/boot.log
   dmesg | tail -200
   /storage/.boot_last_hang   (só existe se o boot anterior travou)
   /flash/fs-resize.log       (se relacionado ao primeiro boot)
```

Abra em [github.com/archr-linux/Arch-R/issues](https://github.com/archr-linux/Arch-R/issues).

Para PortMaster especificamente: [github.com/PortsMaster/PortMaster-GUI/issues](https://github.com/PortsMaster/PortMaster-GUI/issues).


# Atualizando o ArchR



O ArchR não faz updates over-the-air no momento: cada versão nova é uma release completa de imagem. A boa notícia: regravar **não** apaga sua partição `/storage` (que tem seus saves, ROMs, configurações). Só as partições BOOT e ROOT são sobrescritas.

***

## Fluxo de atualização [#fluxo-de-atualização]

<Steps>
  ### Faça backup do que não dá para recriar facilmente [#faça-backup-do-que-não-dá-para-recriar-facilmente]

  Mesmo que `/storage` sobreviva à regravação, paranoia é bom. Via [SSH](/docs/ssh):

  ```bash
  # do seu PC
  scp -r root@archr.local:/storage/saves       ~/r36s-backup/saves/
  scp -r root@archr.local:/storage/states      ~/r36s-backup/states/
  scp -r root@archr.local:/storage/.config     ~/r36s-backup/config/
  scp -r root@archr.local:/storage/screenshots ~/r36s-backup/screenshots/
  ```

  ROMs são grandes; você não precisa fazer backup delas, a menos que tenha curado metadados em `gamelist.xml` por sistema.

  ### Desligue de forma limpa [#desligue-de-forma-limpa]

  ES → botão de power (segurar) → Power Off. Garante que qualquer escrita pendente chegue ao SD.

  ### Grave a nova imagem [#grave-a-nova-imagem]

  Usando o [ArchR Flasher](/docs/installation), escolha a nova imagem e a mesma placa/painel que usou antes. O Flasher limpa a tabela de partições e grava do zero, e é justamente essa limpeza que dá a instalação limpa.

  Alternativa: `dd if=ArchR-R36S.aarch64-DATA-*.img of=/dev/sdX bs=4M conv=fsync status=progress`.

  ### Primeiro boot [#primeiro-boot]

  O primeiro boot da nova imagem **redimensiona** a partição de storage para usar o SD inteiro de novo e reinicia. O boot 2 vê que `/storage/.config` já tem seus dados e pula a recriação. ROMs intactas. Saves intactos. Temas customizados intactos.

  ### Verifique [#verifique]

  O ES dá boot. Sua biblioteca de ROMs está lá. Seus save-states carregam. Suas configurações customizadas estão intactas.

  Se algo parecer estranho, restaure seletivamente a partir do backup que você fez no passo 1.
</Steps>

***

## O que é resetado por uma regravação [#o-que-é-resetado-por-uma-regravação]

| Caminho                                                   | Sobrevive à regravação?                              |
| --------------------------------------------------------- | ---------------------------------------------------- |
| `/` (ROOT, ext4)                                          | Não. Substituído                                     |
| `/flash` (BOOT, FAT32)                                    | Não. Substituído                                     |
| `/storage/roms/`                                          | Sim. Sobrevive                                       |
| `/storage/saves/`                                         | Sim. Sobrevive                                       |
| `/storage/states/`                                        | Sim. Sobrevive                                       |
| `/storage/screenshots/`                                   | Sim. Sobrevive                                       |
| `/storage/.config/`                                       | Sim. Sobrevive                                       |
| `/storage/.cache/services/*.conf`                         | Sim. Sobrevive (seus serviços habilitados persistem) |
| Overrides de tema em `/storage/.emulationstation/themes/` | Sim. Sobrevive                                       |

Dito de outra forma: **tudo que você colocou no SD como usuário sobrevive**. Tudo que vem da imagem é substituído.

O único caso de borda: se você customizou algo diretamente em `/etc/` ou `/usr/` (via SSH, como `root`), isso some, porque esses caminhos vivem no ROOT. Customizações persistentes pertencem a `/storage/.config/` ou `/etc/profile.d/` (que o `045-userconfig` regenera a partir de `/storage/.config/profile.d/` se existir).

***

## Voltando para uma versão anterior [#voltando-para-uma-versão-anterior]

Mesmo fluxo na ordem inversa: regrave uma imagem mais antiga. Dados em `/storage` criados em um ArchR mais novo podem ter deltas no schema de configuração que o mais antigo não reconhece. Geralmente caem para os defaults sem problemas, mas em casos extremos (settings renomeadas) você pode precisar re-acionar algumas opções.

***

## Update manual (sem o Flasher) [#update-manual-sem-o-flasher]

Se você só tem um `.img.gz` mais antigo:

```bash
# descompactar
gunzip ArchR-R36S.aarch64-*.img.gz

# gravar
sudo dd if=ArchR-R36S.aarch64-*.img of=/dev/sdX bs=4M conv=fsync status=progress

# (opcional) verificar checksum
sha256sum -c ArchR-R36S.aarch64-*.img.gz.sha256
```

O Flasher adicionalmente apaga as assinaturas FAT do BOOT (1 MB no início + 1 MB no fim do disco) antes do `dd`, o que evita que tabelas de partição antigas confundam o U-Boot. O `dd` manual não faz isso. Se aparecer tela preta após regravar manualmente, rode:

```bash
sudo dd if=/dev/zero of=/dev/sdX bs=1M count=1
sudo dd if=/dev/zero of=/dev/sdX bs=1M count=1 \
        seek=$(( $(blockdev --getsize64 /dev/sdX) / 1024 / 1024 - 1 ))
```

Depois refaça o `dd` da imagem.

***

## Quando o OTA chegar [#quando-o-ota-chegar]

Releases futuras podem trazer bundles `.tar` de update soltos em `/storage/.update/`, mesmo mecanismo que o ROCKNIX usa. Até lá, regravar é o caminho.


# VPN



O ArchR distribui três opções de VPN. Todas se ligam/desligam pelo EmulationStation → **System Settings** → **Network** e são pausadas automaticamente durante o gameplay para não competirem com o emulador por CPU.

***

## Tailscale [#tailscale]

O Tailscale é uma VPN baseada em WireGuard, sem configuração, que permite ao seu handheld conversar com o seu PC em qualquer lugar da internet, de forma segura.

<Steps>
  ### Cadastre-se [#cadastre-se]

  [Cadastre-se no Tailscale](https://login.tailscale.com/start). Gratuito para uso pessoal em até 100 dispositivos.

  O Tailscale precisa de um provedor SSO: Google, GitHub, Microsoft ou qualquer um dos [provedores de identidade suportados](https://tailscale.com/kb/1013/sso-providers).

  ### Instale no seu PC [#instale-no-seu-pc]

  [Baixe o Tailscale](https://tailscale.com/download/) para o seu OS e faça login.

  ### Habilite no handheld [#habilite-no-handheld]

  ES → **Network Settings** → **Tailscale VPN** → ON.

  Na primeira vez, você verá uma URL de autenticação. Abra-a no browser do seu PC, clique em **Connect** e o Tailscale vincula o handheld à sua tailnet.

  ### Desconectar [#desconectar]

  Mesmo menu, desligue o toggle.
</Steps>

Após a autenticação, seu handheld aparece nas máquinas da sua tailnet. SSH, transferência de arquivos, netplay de RetroArch pela tailnet, tudo funciona como se o dispositivo estivesse na sua LAN local.

***

## WireGuard [#wireguard]

Para quando você tem seu próprio servidor VPN (por exemplo via seu roteador ou um setup auto-hospedado).

### Coloque a config [#coloque-a-config]

Forneça um `wg0.conf` padrão do seu provedor de VPN ou servidor self-hosted. Coloque-o em:

```
/storage/.config/wireguard/wg0.conf
```

Você pode copiá-lo via [SSH](/docs/ssh) ou [Samba](/docs/samba).

Config mínima de exemplo:

```ini
[Interface]
PrivateKey = <your private key>
Address    = 10.111.10.2/24

[Peer]
PublicKey  = <server public key>
AllowedIPs = 0.0.0.0/0
Endpoint   = <server>:<port>
```

<Callout type="warn">
  A diretiva `DNS` **não** é suportada nessa config. Remova qualquer linha `DNS =` ou a conexão não vai subir.
</Callout>

### Toggle [#toggle]

ES → **Network Settings** → **WireGuard VPN** só é visível quando o `wg0.conf` existe. Toggle ON / OFF.

### Diagnóstico [#diagnóstico]

```bash
wg show                # estado do túnel ativo
curl -4 ifconfig.co    # IP público atual
wg-quick up   /storage/.config/wireguard/wg0.conf
wg-quick down /storage/.config/wireguard/wg0.conf
```

### Gerar um par de chaves [#gerar-um-par-de-chaves]

Para self-hosting (use como o lado do dispositivo):

```bash
wg-genconfig          # escreve wg0.conf e wg0.conf.server
```

O arquivo `.server` vai no seu Linux PC / Raspberry Pi atuando como gateway. Descomente as linhas `PostUp` se você quiser acessar outros dispositivos na sua LAN doméstica através dele (SNAT).

***

## ZeroTier [#zerotier]

O ZeroTier é parecido com o Tailscale mas com um modelo de rede diferente: você cria redes no dashboard do ZeroTier e junta dispositivos a elas.

<Steps>
  ### Cadastre-se [#cadastre-se-1]

  [Cadastre-se em my.zerotier.com](https://my.zerotier.com), crie uma rede, copie o ID de 16 caracteres dela.

  ### Coloque o ID da rede [#coloque-o-id-da-rede]

  ```
  /storage/.config/zerotier-networks
  ```

  Um ID de rede por linha. Crie o arquivo via [SSH](/docs/ssh) ou [Samba](/docs/samba).

  ### Habilite [#habilite]

  ES → **Network Settings** → **ZeroTier VPN** → ON.

  ### Aprove no dashboard [#aprove-no-dashboard]

  De volta em [my.zerotier.com](https://my.zerotier.com) → sua rede → **Members**. Seu handheld aparece como pendente. Marque a caixa **Auth**.
</Steps>

### Join manual (alternativa) [#join-manual-alternativa]

Sem o arquivo `zerotier-networks`, você pode rodar via [SSH](/docs/ssh):

```bash
zerotier-cli join <network-id>
zerotier-cli listnetworks
```

Se você misturar isso com a abordagem por arquivo, o arquivo ganha no próximo boot. Escolha uma.

***

## Qual usar [#qual-usar]

|                          | Tailscale        | WireGuard | ZeroTier        |
| ------------------------ | ---------------- | --------- | --------------- |
| Setup mais fácil         | ✅                | -         | -               |
| Self-hostable            | parcial          | ✅         | parcial         |
| Roteamento de sub-rede   | sim              | sim       | sim             |
| Peer-to-peer persistente | com NATs         | direto    | com NATs        |
| Tier gratuito            | 100 dispositivos | n/a       | 25 dispositivos |

Para a maioria das pessoas: **Tailscale** se você quer zero config, **WireGuard** se você já tem um servidor VPN, **ZeroTier** se você prefere o modelo de rede dele.

***

## Durante o gameplay [#durante-o-gameplay]

Os três serviços de VPN são pausados automaticamente quando um jogo é lançado via `runemu.sh` (junto com Syncthing e o servidor HTTP simples) e retomados quando o jogo termina. A pausa é por processo: as conexões TCP fecham no lado do cliente e reconectam quando o serviço volta. Para a maioria dos usos (sync de arquivos, SSH remoto) isso é invisível.

Se você especificamente quer uma VPN ligada durante o gameplay (por exemplo para netplay online pela Tailscale), edite `/usr/bin/runemu.sh` e remova o serviço da lista `pause_background_services`. Atenção: o tráfego de VPN compete pelo airtime do WiFi, que é compartilhado com Bluetooth. Espere chiado ocasional no áudio BT.