Update README for mainline kernel and overlay architecture

Rewrite to reflect current state: kernel 6.12.61 mainline LTS, board DTB auto-selection via SARADC, panel overlay system (20 panels), two image variants (original + clone), Flasher app for panel selection, updated boot flow, build pipeline, and project structure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add Flasher app specification
2026-07-12 18:19:42 -07:00 · 2026-03-04 17:23:15 -03:00 · 2026-03-04 17:23:03 -03:00 · 2026-03-04 17:22:49 -03:00 · 2026-03-04 17:22:30 -03:00 · 2026-03-04 17:20:09 -03:00
4042 changed files with 33877 additions and 342310 deletions
@@ -1,30 +0,0 @@
---
-name: Bug Report
-about: Describe this issue
-title: "[BUG]"
-labels: ISSUE NEEDS REVIEW
-assignees: ''
-
---
-### Have you first checked existing issues and documentation for a solution?
-[ArchR GitHub Issues](https://github.com/archr-linux/Arch-R/issues)
-<!-- Any issue created without sufficient information may be closed. -->
-
-### Describe the bug
-<!-- A clear description of what the bug is. -->
-
-### How to reproduce
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Play '....'
-3. See error
-
-### Information
- - ArchR Version: [e.g. 20260316]
- - Hardware Platform: [e.g. Powkiddy RGB20SX]
-
-### Log file
-<!-- Add debug log files that we can search for errors. -->
-
-### Context
-<!-- Add any context about the problem here. -->
@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: Help and Support
-    url: https://discord.gg/Q5RY3gEuwv
-    about: Please ask for help and post questions in our Discord
-  - name: Feature Requests
-    url: https://discord.gg/Q5RY3gEuwv
-    about: Please ask for feature requests in our Discord
@@ -1,119 +0,0 @@
-&nbsp;&nbsp;<img src="distributions/ArchR/logos/archr-logo.png" width=192>
-#
-ArchR is a community developed Linux distribution for handheld gaming devices, forked from [ROCKNIX](https://github.com/ROCKNIX/distribution).  Our goal is to produce an operating system that has the features and capabilities that we need, and to have fun as we develop it.
-
-## Licenses
-ArchR is a Linux distribution forked from ROCKNIX, made up of many open-source components.  Components are provided under their respective licenses.  This distribution includes components licensed for non-commercial use only.
-
-### ArchR Branding
-ArchR branding and images are licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-
-#### You are free to
-* Share — copy and redistribute the material in any medium or format
-* Adapt — remix, transform, and build upon the material
-
-#### Under the following terms
-* Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
-* NonCommercial — You may not use the material for commercial purposes.
-* ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
-
-### ArchR Software
-Copyright (C) 2024-2026 ArchR (https://github.com/archr-linux).  Derived from ROCKNIX, Copyright (C) 2024 ROCKNIX (https://github.com/ROCKNIX).
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-## Installation
-* Download the latest version of ArchR.
-* Decompress the image.
-* Write the image to an SDCARD using an imaging tool.  Common imaging tools include [Balena Etcher](https://www.balena.io/etcher/), [Raspberry Pi Imager](https://www.raspberrypi.com/software/), and [Win32 Disk Imager](https://sourceforge.net/projects/win32diskimager/).  If you're skilled with the command line, dd works fine too.
-
-### Installation Package Downloads
-| **Device/Platform**                                                                                                                                              | **Download Package**                                                                                                                                                 | **Documentation**                                                    |
-|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
-| **Anbernic RG351P/M/V, Game Console R33S/R35S/R36S, ODROID Go Advance, ODROID Go Super, Magicx XU10, Powkiddy V10/RGB10**                                        | [ArchR-RK3326.aarch64-$DATE-a.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3326.aarch64-$DATE-a.img.gz)                       | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3326/)     |
-| **Magicx XU Mini M, Powkiddy RGB10X**                                                                                                                            | [ArchR-RK3326.aarch64-$DATE-b.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3326.aarch64-$DATE-b.img.gz)                       | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3326/)     |
-| **Anbernic RG353P/M/V/VS/PS, RG503, RGARC-D/S, Powkiddy RK2023, RGB10 Max 3, RGB30, RGB20SX, RGB20 Pro**                                                         | [ArchR-RK3566.aarch64-$DATE-Generic.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3566.aarch64-$DATE-Generic.img.gz)           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3566/)     |
-| **Anbernic RG552**                                                                                                                                               | [ArchR-RK3399.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3399.aarch64-$DATE.img.gz)                           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3399/)     |
-| **Anbernic RG35XX PLUS/H/SP/2024, RG40XX V/H, RGCUBEXX, RG34XX SP, RG28XX [Must Follow Install Instructions](https://github.com/archr-linux/Arch-R/wiki/h700-installation)** | [ArchR-H700.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-H700.aarch64-$DATE.img.gz)                               | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/H700/)       |
-| **Hardkernel ODROID Go Ultra, Powkiddy RGB10 Max 3 Pro**                                                                                                         | [ArchR-S922X.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-S922X.aarch64-$DATE.img.gz)                             | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/S922X/)      |
-| **Gameforce Ace (default). Orange Pi 5 / 5 Plus, Radxa Rock 5a / 5b / 5b+ / CM5, and Indiedroid Nova**                                                           | [ArchR-RK3588.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3588.aarch64-$DATE.img.gz)                           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3588/)     |
-| **Powkiddy x55**                                                                                                                                                 | [ArchR-RK3566.aarch64-$DATE-Powkiddy_x55.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3566.aarch64-$DATE-Powkiddy_x55.img.gz) | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/RK3566-X55/) |
-| **Retroid Pocket 5, Pocket Mini, Pocket Mini V2, Pocket Flip2**                                                                                                  | [ArchR-SM8250.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8250.aarch64-$DATE.img.gz)                           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/SM8250/)     |
-| **Ayn Odin 2, Odin 2 Mini, Odin 2 Portal, Thor, Ayaneo Pocket ACE/EVO/DMG/DS**                                                                                   | [ArchR-SM8550.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8550.aarch64-$DATE.img.gz)                           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/SM8550/)     |
-| **Ayaneo Pocket S2**                                                                                                                                             | [ArchR-SM8650.aarch64-$DATE.img.gz](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8650.aarch64-$DATE.img.gz)                           | [documentation](/documentation/PER_DEVICE_DOCUMENTATION/SM8650/)     |
-
-## Upgrading
-* Download and install the update online via the System Settings menu.
-* If you are unable to update online
-* Download the latest version of ArchR from Github
-* Copy the update to your device over the network to your device's update share.
-* Reboot the device, and the update will begin automatically.
-
-### Update Package Downloads
-| **Device/Platform**                                                                                                                         | **Download Package**                                                                                                                 |
-|---------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| **Anbernic RG351P/M/V, Game Console R33S/R35S/R36S, ODROID Go Advance, ODROID Go Super, Magicx XU10, XU Mini M, Powkiddy V10/RGB10/RGB10X** | [ArchR-RK3326.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3326.aarch64-$DATE.tar) |
-| **Anbernic RG353P/M/V/VS/PS, RG503, RGARC-D/S, Powkiddy RK2023, RGB10 Max 3, RGB30, RGB20SX, RGB20 Pro, X55**                               | [ArchR-RK3566.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3566.aarch64-$DATE.tar) |
-| **Anbernic RG552**                                                                                                                          | [ArchR-RK3399.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3399.aarch64-$DATE.tar) |
-| **Anbernic RG35XX PLUS/H/SP/2024, RG40XX V/H, RGCUBEXX, RG34XX SP, RG28XX**                                                                 | [ArchR-H700.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-H700.aarch64-$DATE.tar)     |
-| **Hardkernel ODROID Go Ultra, Powkiddy RGB10 Max 3 Pro**                                                                                    | [ArchR-S922X.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-S922X.aarch64-$DATE.tar)   |
-| **Gameforce Ace, Orange Pi 5 / 5 Plus, Radxa Rock 5a / 5b / 5b+ / CM5 and Indiedroid Nova**                                                 | [ArchR-RK3588.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-RK3588.aarch64-$DATE.tar) |
-| **Retroid Pocket 5, Pocket Mini, Pocket Mini V2, Pocket Flip2**                                                                             | [ArchR-SM8250.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8250.aarch64-$DATE.tar) |
-| **Ayn Odin 2, Odin 2 Mini, Odin 2 Portal, Thor, Ayaneo Pocket ACE/EVO/DMG/DS**                                                              | [ArchR-SM8550.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8550.aarch64-$DATE.tar) |
-| **Ayaneo Pocket S2**                                                                                                                        | [ArchR-SM8650.aarch64-$DATE.tar](https://github.com/archr-linux/Arch-R/releases/download/$DATE/ArchR-SM8650.aarch64-$DATE.tar) |
-
-## Documentation
-
-### Contribute
-
-* [Building ArchR](https://github.com/archr-linux/distribution/wiki/contribute/build/)
-* [Code of Conduct](https://github.com/archr-linux/distribution/wiki/contribute/code-of-conduct/)
-* [Contributing to ArchR](https://github.com/archr-linux/distribution/wiki/contribute/)
-* [Modifying ArchR](https://github.com/archr-linux/distribution/wiki/contribute/modify/)
-* [Adding Hardware Quirks](https://github.com/archr-linux/distribution/wiki/contribute/quirks/)
-* [Creating Packages](https://github.com/archr-linux/distribution/wiki/contribute/packages/)
-* [Pull Request Template](/PULL_REQUEST_TEMPLATE.md)
-
-### Play
-
-* [Installing ArchR](https://github.com/archr-linux/distribution/wiki/play/install/)
-* [Updating ArchR](https://github.com/archr-linux/distribution/wiki/play/update/)
-* [Controls](https://github.com/archr-linux/distribution/wiki/play/controls/)
-* [Netplay](https://github.com/archr-linux/distribution/wiki/play/netplay/)
-* [Configuring Moonlight](https://github.com/archr-linux/distribution/wiki/systems/moonlight/)
-* [Device Specific Documentation](/documentation/PER_DEVICE_DOCUMENTATION)
-
-### Configure
-
-* [Optimizations](https://github.com/archr-linux/distribution/wiki/configure/optimizations/)
-* [Shaders](https://github.com/archr-linux/distribution/wiki/configure/shaders/)
-* [Cloud Sync](https://github.com/archr-linux/distribution/wiki/configure/cloud-sync/)
-* [VPN](https://github.com/archr-linux/distribution/wiki/configure/vpn/)
-
-### Other
-
-* [Frequently Asked Questions](https://github.com/archr-linux/distribution/wiki/faqs/)
-* [Donating to ArchR](https://github.com/archr-linux/Arch-R)
-
-## Change Log
-
-### New Features
-* Added...?
-
-### Updates
-* Updated...?
-
-### Bug Fixes
-* Fixed...?
-
-**Full Changelog**: https://github.com/archr-linux/Arch-R/compare/$LAST_TAG...$DATE
@@ -1,170 +1,107 @@
-# build directories
-/build.*/
-/builds
-/.fakeroot.*
-.claude
+# Build output
+output/

-# automatically downloaded source files
-/sources/
+# Kernel and bootloader source (cloned during build)
+kernel/src/

-# prebuild target binarys to provide
-/target/
+# Kernel module build artifacts (compiled .ko/.o are not source)
+kernel/drivers/**/*.o
+kernel/drivers/**/*.ko
+kernel/drivers/**/*.mod
+kernel/drivers/**/*.mod.c
+kernel/drivers/**/*.mod.o
+kernel/drivers/**/*.cmd
+kernel/drivers/**/Module.symvers
+kernel/drivers/**/modules.order
+kernel/drivers/**/.module-common.o

-# mkpkg temp
-mkpkg-temp
+# Compiled DTBs in source tree (use output/boot/dtbs/ instead)
+kernel/dts/*.dtb
+bootloader/src/

-# options
-/.libreelec
+# Build cache
+.cache/
+rootfs/staging/

-# private working directory
-/.work/
-
-# dedicated filesystem
-/lost+found/
-
-# symlinks...
-/sources
-/.work
-
-# ccache
-/.ccache/
-
-# backup files
-*.orig
-
-# crap
-.DS_Store
-.directory
-Thumbs.db
+# Logs
 *.log
+
+# Archives and images (build artifacts)
+*.tar.gz
+*.xz
+*.img
+# Exception: U-Boot prebuilt binaries
+!bootloader/u-boot-r36s-working/*.img
+
+# Datasheets (copyrighted, not distributable)
 *.pdf

-# temp scripts (debug/install helpers)
-fix-debug.sh
-install-debug.sh
+# Backup/stale configs
+*.bak
+*.bak-*
+config/archr-6.6-r36s.config.bak-pre-splash

-# ignore git repos from update scripts
-tools/mkpkg/*.git
+# Cross-compilation (doesn't work on ARM — use native chroot)
+config/toolchain-aarch64.cmake
+cross-build-es.sh

-# ignore old linux configs
-projects/**/*.old
+# One-off deploy/diagnostic scripts (not part of build)
+deploy-*.sh
+diagnose-sd.sh
+cleanup-*.sh
+read-logs.sh

-# Generated MIPI overlay output (regenerated by generator.sh)
-config/mipi-generator/output/
+# Quick rebuild scripts (development iteration, not part of main build)
+quick-*.sh
+quick-rebuild-es.sh.backup-patches1-17

-# Generated DTBO overlays in u-boot config (copied from mipi-generator output)
-projects/ArchR/devices/RK3326/packages/u-boot/config/overlays_original/*.dtbo
-projects/ArchR/devices/RK3326/packages/u-boot/config/overlays_clone/*.dtbo
+# Failed splash approach (retired)
+scripts/archr-splash
+scripts/archr-splash.c
+scripts/splash-diag.sh
+scripts/splash-display.py
+scripts/splash-progress.py
+scripts/splash-show.sh

-# ArchR
-/.archr
-/.cache
-/.doc_cache
-/.env
-/.es_cache
+# Build artifacts from scripts
+scripts/__pycache__/
+scripts/libvlc-stub-aarch64.so
+
+# Build log .txt files
+log-*.txt
+
+# Misc development files
+/lib*.so*
+/es-log*.txt
+/log.txt
 /.config
+/apply-fix-round4.sh
+/fix-sd-issues.sh
+reddit-post.md
+scripts/auto_suspend_update.sh

-# Upstream/legacy distributions (not used by ArchR)
-distributions/ROCKNIX/
-distributions/LibreELEC/
-distributions/LEIoT/
+# Mesa recovery script (utility, not part of build)
+restore-mesa26-gbm.sh

-# Upstream/other platform projects (not used by PROJECT=ArchR)
-projects/ROCKNIX/
-projects/Allwinner/
-projects/Amlogic/
-projects/ARM/
-projects/Generic/
-projects/NXP/
-projects/Qualcomm/
-projects/Rockchip/
-projects/RPi/
-projects/Samsung/
+# Website (separate project)
+website/

-# Non-R36S device directories
-projects/ArchR/devices/H700/
-projects/ArchR/devices/RK3399/
-projects/ArchR/devices/RK3566/
-projects/ArchR/devices/RK3588/
-projects/ArchR/devices/S922X/
-projects/ArchR/devices/SDM845/
-projects/ArchR/devices/SM8250/
-projects/ArchR/devices/SM8550/
-projects/ArchR/devices/SM8650/
+# Environment secrets
+.env

-# Non-R36S device documentation
-documentation/PER_DEVICE_DOCUMENTATION/H700/
-documentation/PER_DEVICE_DOCUMENTATION/RK3399/
-documentation/PER_DEVICE_DOCUMENTATION/RK3566/
-documentation/PER_DEVICE_DOCUMENTATION/RK3588/
-documentation/PER_DEVICE_DOCUMENTATION/S922X/
-documentation/PER_DEVICE_DOCUMENTATION/SDM845/
-documentation/PER_DEVICE_DOCUMENTATION/SM8250/
-documentation/PER_DEVICE_DOCUMENTATION/SM8550/
-documentation/PER_DEVICE_DOCUMENTATION/SM8650/
+# Bootloader source trees (cloned/downloaded during build)
+bootloader/rkbin/
+bootloader/u-boot-mainline/
+bootloader/u-boot-rk3326-clone/

-# Kodi/mediacenter (MEDIACENTER not set in ArchR)
-packages/mediacenter/
+# Pre-built U-Boot backups (working binaries, not part of build pipeline)
+bootloader/u-boot-clone-working/

-# Driver addons (DRIVER_ADDONS_SUPPORT=no in ArchR)
-packages/linux-driver-addons/
+# Extracted DTBs (debugging artifacts)
+bootloader/u-boot-r36s-working/extracted_dtb_*.dtb

-# Kodi addons (no MEDIACENTER in ArchR)
-# Kodi addons (no MEDIACENTER in ArchR) - keep addon-depends for shared libraries
-packages/addons/*
-!packages/addons/addon-depends/
+# Clone U-Boot build output
+bootloader/u-boot-clone-build/

-# Platform-specific bootloaders/tools (not RK3326)
-packages/tools/bcm2835-bootloader/
-packages/tools/bcm2835-utils/
-packages/tools/bcmstat/
-packages/tools/rpi-eeprom/
-packages/tools/amlogic-boot-fip/
-packages/tools/exynos-boot-fip/
-
-# Firmware not used by R36S (FIRMWARE=esp8089-firmware only)
-packages/linux-firmware/brcmfmac_sdio-firmware/
-packages/linux-firmware/brcmfmac_sdio-firmware-imx/
-packages/linux-firmware/brcmfmac_sdio-firmware-rpi/
-packages/linux-firmware/dvb-firmware/
-packages/linux-firmware/firmware-dragonboard/
-packages/linux-firmware/firmware-imx/
-packages/linux-firmware/iwlwifi-firmware/
-
-# Non-R36S CI workflows
-.github/workflows/build-aarch64-emu-libretro.yml
-.github/workflows/build-aarch64-emu-standalone.yml
-.github/workflows/build-aarch64-qt6.yml
-.github/workflows/build-aarch64-mame-lr.yml
-
-# Emulators not used by RK3326 (too heavy or Vulkan-only)
-projects/ArchR/packages/emulators/standalone/aethersx2-sa/
-projects/ArchR/packages/emulators/standalone/azahar-sa/
-projects/ArchR/packages/emulators/standalone/bigpemu-sa/
-projects/ArchR/packages/emulators/standalone/cemu-sa/
-projects/ArchR/packages/emulators/standalone/rpcs3-sa/
-projects/ArchR/packages/emulators/standalone/supermodel-sa/
-projects/ArchR/packages/emulators/standalone/xemu-sa/
-projects/ArchR/packages/emulators/standalone/skyemu-sa/
-projects/ArchR/packages/emulators/libretro/kronos-lr/
-
-# Graphics packages not used by RK3326 (no Vulkan on Mali G31)
-projects/ArchR/packages/graphics/libmali-vulkan/
-projects/ArchR/packages/graphics/vulkan-wsi-layer/
-
-# Qualcomm/non-RK3326 tools
-projects/ArchR/packages/tools/archr-abl/
-projects/ArchR/packages/tools/qcom-abl/
-
-# Platform-specific base packages (not used by RK3326)
-packages/audio/rpi-cirrus-config/
-packages/tools/crust/
-packages/tools/mkbootimg/
-packages/tools/grub/
-packages/linux-firmware/firmware-dragonboard/
-packages/linux-firmware/firmware-imx/
-packages/graphics/nvidia/
-packages/multimedia/intel-vaapi-driver/
-packages/multimedia/media-driver/
-packages/multimedia/gmmlib/
-packages/sysutils/open-vm-tools/
+# Others
+feedback/
@@ -0,0 +1,90 @@
+# Arch R - Project Documentation
+
+## Project Overview
+
+**Arch R** is a custom Arch Linux ARM-based gaming distribution for the R36S handheld console.
+
+## Hardware Support
+
+- **SoC**: Rockchip RK3326
+- **Display**: 640x480 (rotated portrait)
+- **USB OTG**: Host mode with VBUS power control
+- **Wi-Fi**: AIC8800 USB adapter (with modeswitch support from a69c:5721 to a69c:8801)
+- **Multiple R36S hardware revisions**: Multiple DTB support planned
+
+## Build Requirements
+
+- Ubuntu 22.04+ or Arch Linux
+- Cross-compilation toolchain (aarch64-linux-gnu-gcc)
+- Device Tree Compiler (dtc)
+- QEMU for ARM64 userspace emulation
+- ~10GB disk space
+
+## Build Process
+
+1. **Setup toolchain**: `sudo ./setup-toolchain.sh`
+2. **Source environment**: `source env.sh`
+3. **Build kernel**: `./build-kernel.sh`
+4. **Build rootfs**: `sudo ./build-rootfs.sh`
+5. **Build image**: `sudo ./build-image.sh`
+
+## Key Technical Notes
+
+### USB OTG Configuration
+
+The R36S (when using RG351MP-based firmware) had USB OTG issues due to:
+- `otg-port` status set to "disabled" in Device Tree
+- `dr_mode` set to "otg" instead of "host"
+- Missing `vbus-supply` reference to `otg_switch` regulator (phandle 0xec)
+
+**Solution**: Modify Device Tree to:
+```
+usb@ff300000 {
+    dr_mode = "host";  // Force host mode
+};
+
+otg-port {
+    status = "okay";    // Enable OTG port
+    vbus-supply = <&otg_switch>;  // Reference power regulator
+};
+```
+
+### Wi-Fi Modeswitch
+
+The AIC8800 USB adapter appears first as a CD-ROM device (VID:PID a69c:5721).
+A udev rule triggers `/usr/bin/eject` to switch it to Wi-Fi mode (a69c:8801).
+
+See: `config/udev/99-archr-r36s.rules`
+
+### Multiple R36S Revisions
+
+The R36S has multiple hardware revisions requiring different Device Trees.
+The build system should be updated to:
+1. Include all DTB variants in `/kernel/dts/`
+2. Auto-detect hardware revision at boot
+3. Load appropriate DTB
+
+## Directory Structure
+
+```
+arch-r/
+├── bootloader/          # U-Boot configuration
+│   └── configs/
+├── kernel/              # Kernel and Device Trees
+│   ├── configs/         # Kernel defconfig
+│   ├── dts/             # Device Tree sources/binaries
+│   └── patches/         # Kernel patches
+├── rootfs/              # Root filesystem
+│   └── overlay/         # Files to overlay on rootfs
+├── config/              # System configuration
+│   ├── retroarch.cfg    # RetroArch config for R36S
+│   └── udev/            # udev rules
+├── scripts/             # Runtime scripts
+└── output/              # Build artifacts
+```
+
+## References
+
+- Kernel: dArkOS kernel source (4.4.189)
+- Base system: Arch Linux ARM aarch64
+- Frontend: RetroArch + EmulationStation
@@ -1,58 +0,0 @@
-FROM archlinux:latest
-
-SHELL ["/usr/bin/bash", "-c"]
-
-# Update system and install base packages
-# Fix: archlinux:latest has corrupt pacman local db (missing desc files in overlay)
-# Step 1: upgrade base system (creates new layer, fixes stale db entries)
-RUN pacman-db-upgrade 2>/dev/null; \
-    for pkg in /var/lib/pacman/local/*/; do \
-      [ ! -f "${pkg}desc" ] && rm -rf "$pkg" 2>/dev/null; \
-    done; true
-RUN pacman -Syu --noconfirm
-# Step 2: clean stale entries from previous layer, then install build deps
-RUN for pkg in /var/lib/pacman/local/*/; do \
-      [ ! -f "${pkg}desc" ] && rm -rf "$pkg" 2>/dev/null; \
-    done; true
-RUN pacman -S --noconfirm --needed \
-    base-devel bc jdk-openjdk file gawk gettext git go gperf \
-    perl-json perl-xml-parser ncurses lzop make patchutils \
-    python python-setuptools parted unzip wget curl \
-    xorg-mkfontscale libxslt zip vim zstd rdfind automake \
-    xmlstarlet rsync which sudo rpcsvc-proto perl-parse-yapp xorg-bdftopcf \
-    dtc python-pip
-# Python fdt package for MIPI panel overlay generation
-RUN pip3 install --break-system-packages fdt
-
-# Note: GCC downgrade removed - build system compiles its own cross-toolchain (GCC 15.1).
-# Host GCC is only used for host tools. Fixes from projects/ArchR/packages/ handle
-# any GCC 15 incompatibilities in individual packages (spirv-tools, llvm, etc.)
-
-# Create build user
-RUN useradd -m -s /bin/bash docker && \
-    echo 'docker ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
-
-# Set locale
-RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
-    locale-gen
-ENV LANG=en_US.UTF-8 \
-    LANGUAGE=en_US:en \
-    LC_ALL=en_US.UTF-8
-
-# Ensure Perl tools (pod2man, yapp, etc.) are in standard PATH
-RUN for f in /usr/bin/core_perl/*; do [ -f "$f" ] && ln -sf "$f" /usr/bin/ 2>/dev/null; done; \
-    for f in /usr/bin/vendor_perl/*; do [ -f "$f" ] && ln -sf "$f" /usr/bin/ 2>/dev/null; done; \
-    true
-
-### Cross compiling on ARM
-RUN if [ "$(uname -m)" = "aarch64" ]; then pacman -S --noconfirm qemu-user-static; fi
-RUN if [ ! -d /lib64 ]; then ln -sf /usr/x86_64-archr-linux-gnu/lib64 /lib64 2>/dev/null || true; fi
-RUN if [ ! -d /lib/x86_64-archr-linux-gnu ]; then ln -sf /usr/x86_64-archr-linux-gnu/lib /lib/x86_64-archr-linux-gnu 2>/dev/null || true; fi
-
-RUN mkdir -p /work && chown docker /work
-
-# Git safe.directory for any user (env-file may override HOME)
-RUN git config --system --add safe.directory '*'
-
-WORKDIR /work
-USER docker
@@ -1,33 +0,0 @@
-<img src="distributions/ArchR/logos/archr-logo.png" width=192>
-
---
-
-## Licenses
-
-ArchR is a Linux distribution forked from [ROCKNIX](https://github.com/ROCKNIX/distribution), made up of many open-source components.  Components are provided under their respective licenses.  This distribution includes components licensed for non-commercial use only.
-
-### ArchR Branding
-
-ArchR branding and images are licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).  Original ROCKNIX branding remains the property of the ROCKNIX project.
-
-You are free to:
-
- Share: copy and redistribute the material in any medium or format
- Adapt: remix, transform, and build upon the material
-
-Under the following terms:
-
- Attribution: You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- NonCommercial: You may not use the material for commercial purposes.
- ShareAlike: If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
-
-### ArchR Software
-
-Copyright 2024-2026 ArchR (https://github.com/archr-linux)
-
-Original software and scripts developed by the ArchR team are licensed under the terms of the [GNU GPL Version 2](https://choosealicense.com/licenses/gpl-2.0/).  The full license can be found in this project's licenses folder.
-
-Portions of this software are derived from ROCKNIX, Copyright 2024 ROCKNIX (https://github.com/ROCKNIX).
-
-### Bundled Works
-All other software is provided under each component's respective license.  These licenses can be found in the software sources or in this project's licenses folder.  Modifications to bundled software and scripts by the ArchR team are licensed under the terms of the software being modified.
@@ -1,111 +0,0 @@
-include $(HOME)/.archr/options
-
-export OFFICIAL
-
-all: world
-
-system:
-	./scripts/image
-
-release:
-	./scripts/image release
-
-image:
-	./scripts/image mkimage
-
-noobs:
-	./scripts/image noobs
-
-clean:
-	./scripts/makefile_helper --clean
-
-distclean:
-	./scripts/makefile_helper --distclean
-
-src-pkg:
-	tar cvJf sources.tar.xz sources
-
-docs:
-	./tools/foreach './scripts/clean emulators && ./scripts/build emulators'
-
-world: RK3326
-
-kconfig-olddefconfig-%:
-	DEVICE=$* ./tools/adjust_kernel_config olddefconfig
-
-kconfig-menuconfig-%:
-	DEVICE=$* ./tools/adjust_kernel_config menuconfig
-
-RK3326:
-	unset DEVICE_ROOT
-	OFFICIAL=$(if $(filter y yes Y YES 1,$(OFFICIAL)),yes,) PROJECT=ArchR DEVICE=RK3326 ARCH=arm ./scripts/build_distro
-	OFFICIAL=$(if $(filter y yes Y YES 1,$(OFFICIAL)),yes,) PROJECT=ArchR DEVICE=RK3326 ARCH=aarch64 ./scripts/build_distro
-
-update:
-	PROJECT=ArchR DEVICE=RK3326 ARCH=aarch64 ./scripts/update_packages
-
-package:
-	./scripts/build ${PACKAGE}
-
-package-clean:
-	./scripts/clean ${PACKAGE}
-
-## Docker builds - overview
-# docker-* commands just wire up docker to call the normal make command via docker
-# For example: make docker-RK3326 will use docker to call: make RK3326
-# All variables are scoped to docker-* commands to prevent weird collisions/behavior with non-docker commands
-
-docker-%: DOCKER_IMAGE := "archr-build:latest"
-
-# DOCKER_WORK_DIR is the directory in the Docker image - it is set to /work by default
-#   Anytime this directory changes, you must run `make clean` similarly to moving the distribution directory
-docker-%: DOCKER_WORK_DIR := $(shell if [ -n "${DOCKER_WORK_DIR}" ]; then echo ${DOCKER_WORK_DIR}; else echo "$$(pwd)" ; fi)
-
-# ${HOME}/.archr/options is a global options file containing developer and build settings.
-docker-%: GLOBAL_SETTINGS := $(shell if [ -f "${HOME}/.archr/options" ]; then echo "-v \"${HOME}/.archr/options:${HOME}/.archr/options\""; else echo ""; fi)
-
-# LOCAL_SSH_KEYS_FILE is a variable that contains the location of the authorized keys file for development build use.  It will be mounted into the container if it exists.
-docker-%: LOCAL_SSH_KEYS_FILE := $(shell if [ -n "${LOCAL_SSH_KEYS_FILE}" ]; then echo "-v \"${LOCAL_SSH_KEYS_FILE}:${LOCAL_SSH_KEYS_FILE}\""; else echo ""; fi)
-
-# EMULATIONSTATION_SRC is a variable that contains the location of local emulationstation source code. It will be mounted into the container if it exists.
-docker-%: EMULATIONSTATION_SRC := $(shell if [ -n "${EMULATIONSTATION_SRC}" ]; then echo "-v \"${EMULATIONSTATION_SRC}:${EMULATIONSTATION_SRC}\""; else echo ""; fi)
-
-# UID is the user ID of current user - ensures docker sets file permissions properly
-docker-%: UID := $(shell id -u)
-
-# GID is the main user group of current user - ensures docker sets file permissions properly
-docker-%: GID := $(shell id -g)
-
-# PWD is 'present working directory' and passes through the full path to current dir to docker (becomes 'work')
-docker-%: PWD := $(shell pwd)
-
-# Command to use (either `docker` or `podman`)
-docker-%: DOCKER_CMD:= $(shell if which docker 2>/dev/null 1>/dev/null; then echo "docker"; elif which podman 2>/dev/null 1>/dev/null; then echo "podman"; fi)
-
-# Podman requires some extra args (`--userns=keep-id` and `--security-opt=label=disable`).  Set those args if using podman
-#   Make sure that docker isn't just an alias for podman
-docker-%: PODMAN_ARGS:= $(shell if echo "$$(docker --version 2>/dev/null || podman --version 2>/dev/null )" | grep podman 1>/dev/null ; then echo "--userns=keep-id --security-opt=label=disable -v /proc/mounts:/etc/mtab"; fi)
-
-# Launch docker as interactive if this is an interactive shell (allows ctrl-c for manual and running non-interactive - aka: build server)
-docker-%: INTERACTIVE=$(shell [ -t 0 ] && echo "-it")
-
-# By default pass through anything after `docker-` back into `make`
-docker-%: COMMAND=make $*
-
-# If the user issues a `make docker-shell` just start up bash as the shell to run commands
-docker-shell: COMMAND=bash
-
-# Command: builds and saves a docker builder image locally.
-# The build user must also be a member of the "docker" group.
-docker-image-build:
-	$(DOCKER_CMD) buildx create --use
-	$(DOCKER_CMD) buildx build --tag $(DOCKER_IMAGE) --platform $(shell if [ "$$(uname -m)" = "aarch64" ]; then echo "linux/arm64"; else echo "linux/amd64"; fi) --load .
-
-# Command: pulls latest docker image from dockerhub.  This will *replace* locally built version.
-docker-image-pull:
-	$(DOCKER_CMD) pull $(DOCKER_IMAGE)
-
-# Wire up docker to call equivalent make files using % to match and $* to pass the value matched by %
-docker-%:
-	./scripts/get_env > .env
-	BUILD_DIR="$(DOCKER_WORK_DIR)" $(DOCKER_CMD) run $(PODMAN_ARGS) $(INTERACTIVE) --init --env-file .env --rm --user $(UID):$(GID) $(GLOBAL_SETTINGS) $(LOCAL_SSH_KEYS_FILE) $(EMULATIONSTATION_SRC) -v "$(PWD)":"$(DOCKER_WORK_DIR)" -v /tmp:/tmp -w "$(DOCKER_WORK_DIR)" $(DOCKER_EXTRA_OPTS) $(DOCKER_IMAGE) $(COMMAND)
@@ -1,65 +1,39 @@
-<p align="center">
-  <img src="distributions/ArchR/logos/archr-logo.png" width="280" alt="Arch R" style="background:#000">
-</p>
+# Arch R

 <p align="center">
-  <strong>Arch Linux-based gaming distribution for handheld devices.</strong>
+  <img src="ArchR.png" alt="Arch R" width="480">
 </p>

-<p align="center">
-  <a href="https://github.com/archr-linux/Arch-R/releases/latest"><img src="https://img.shields.io/github/release/archr-linux/Arch-R.svg?color=0080FF&label=latest%20version&style=flat-square" alt="Latest Version"></a>
-  <a href="https://github.com/archr-linux/Arch-R/commits"><img src="https://img.shields.io/github/commit-activity/m/archr-linux/Arch-R?color=0080FF&style=flat-square" alt="Activity"></a>
-  <a href="https://github.com/archr-linux/Arch-R/pulls"><img src="https://img.shields.io/github/issues-pr-closed/archr-linux/Arch-R?color=0080FF&style=flat-square" alt="Pull Requests"></a>
-</p>
+> **Arch Linux-based gaming distribution for R36S and all clones.**
+>
+> Leve como uma pluma.

---
-
-Arch R is a custom Linux distribution for the **R36S** handheld gaming console and all its variants, built on top of [ROCKNIX](https://github.com/ROCKNIX/distribution) with an **Arch Linux-based** build environment. It supports **16 board profiles** and **20 display panels** across original and clone hardware.
+Arch R is a custom Linux distribution built from scratch for the R36S handheld gaming console (RK3326 SoC, Mali-G31 GPU, 640x480 MIPI DSI display). It supports all R36S variants and clones — 16 board profiles and 20 display panels.

 ## Features

- Arch Linux-based build system with Docker support.
- Kernel 6.12 LTS with board auto-detection via SARADC.
- Mesa Panfrost open-source GPU driver (GLES 3.1, no proprietary blobs).
- EmulationStation frontend with RetroArch and 18+ cores pre-installed.
- Full audio support with speaker/headphone auto-switch.
- Battery monitoring with capacity reporting and LED warning.
- 20 pre-generated MIPI panel overlays (7 original + 13 clone variants).
- Separate images for original and clone boards, both with hardware auto-detection.
- Integrated cross-device local and remote network play.
- Fine-grained control for battery life and performance.
- Bluetooth audio and controller support.
- HDMI audio/video output, USB audio.
- Device sync with Syncthing and rclone.
- VPN support with WireGuard, Tailscale, and ZeroTier.
- Built-in scraping and RetroAchievements.
-
-## Supported Hardware
-
-### Boards
-
-| Board | Image |
-|-------|-------|
-| R36S (original), R33S | Original |
-| Odroid Go Advance / v1.1 / Super | Original |
-| Anbernic RG351V / RG351M | Original |
-| GameForce Chi, MagicX XU10 | Original |
-| K36 / R36S clones / EE Clone | Clone |
-| Powkiddy RGB10 / RGB10X / RGB20S | Clone |
-| MagicX XU-Mini-M, BatLexp G350 | Clone |
-
-### Display Panels
-
-Arch R ships 20 pre-generated MIPI panel overlays covering all known R36S display variants. Panel selection is done by copying the correct `.dtbo` file to `overlays/mipi-panel.dtbo` on the boot partition.
+- **Kernel 6.12.61** (Mainline LTS) — board auto-detection via SARADC, 16 board DTBs, panel overlays
+- **Mesa 26 Panfrost** — open-source GPU driver, GLES 1.0/2.0/3.1, no proprietary blobs
+- **EmulationStation** (fcamod fork) — 78fps stable, GLES 1.0 native rendering
+- **RetroArch 1.22.2** — KMS/DRM + EGL, 18+ cores pre-installed
+- **19-second boot** — initramfs splash at 0.7s, systemd to EmulationStation
+- **Full audio** — ALSA, speaker + headphone auto-switch, volume/brightness hotkeys
+- **Battery monitoring** — capacity/voltage reporting, LED warning
+- **Multi-panel support** — 20 panel overlays (7 original + 13 clone variants)
+- **Two images** — Original R36S and Clone boards, both auto-detect hardware

 ## Quick Start

-Download the latest images from [Releases](https://github.com/archr-linux/Arch-R/releases):
+Download the latest images from [Releases](../../releases):

- **Original image** -- for genuine R36S and compatible boards.
- **Clone image** -- for K36 clones and compatible boards.
+- **`ArchR-R36S-*.img.xz`** — for genuine R36S, OGA, OGS, RG351V/M, Chi, R33S
+- **`ArchR-R36S-clone-*.img.xz`** — for K36 clones, RGB20S, RGB10X, XU-Mini-M, R36Max

-Flash to a MicroSD card:
+### Using Arch R Flasher (recommended)
+
+Download the [Arch R Flasher](https://github.com/archr-linux/archr-flasher) app, select your console type and display panel, and flash directly. The Flasher handles image download, panel overlay selection, and SD card writing.
+
+### Manual Flash

 ```bash
 xz -d ArchR-R36S-*.img.xz
@@ -67,113 +41,242 @@ sudo dd if=ArchR-R36S-*.img of=/dev/sdX bs=4M status=progress
 sync
 ```

+After flashing, mount the BOOT partition and copy your panel overlay:
+
+```bash
+sudo mount /dev/sdX1 /mnt
+sudo cp /mnt/overlays/panel4-v22.dtbo /mnt/overlays/mipi-panel.dtbo
+sudo umount /mnt
+sync
+```
+
 Insert the SD card and power on. The correct board DTB is selected automatically.

 ## Building from Source

-### Requirements
+### Host Requirements

- Docker (recommended) or native Linux build environment
- ~40 GB free disk space
- ~8 GB RAM recommended
+- **OS:** Ubuntu 22.04+ (or any Linux with QEMU user-static support)
+- **Disk:** 30GB+ free space
+- **RAM:** 4GB+ recommended

-### Build
+### Install Dependencies

 ```bash
-git clone https://github.com/archr-linux/Arch-R.git
-cd Arch-R
-
-# Build Docker image (first time only)
-make docker-image-build
-
-# Build for R36S (all variants)
-make docker-RK3326
+sudo apt install -y \
+    gcc-aarch64-linux-gnu \
+    qemu-user-static \
+    binfmt-support \
+    parted \
+    dosfstools \
+    e2fsprogs \
+    rsync \
+    xz-utils \
+    imagemagick \
+    device-tree-compiler \
+    git \
+    bc \
+    flex \
+    bison \
+    libssl-dev
 ```

-Output images are generated in `target/`.
+### Build Everything

-### Build Commands
+```bash
+git clone --recurse-submodules https://github.com/archr-linux/Arch-R.git
+cd Arch-R

-| Command | Description |
-|---------|-------------|
-| `make docker-RK3326` | Full build inside Docker |
-| `make RK3326` | Native build (requires all dependencies) |
-| `make docker-image-build` | Build the Docker build environment |
-| `make clean` | Remove build artifacts |
+# Full build: kernel + rootfs + mesa + ES + retroarch + panels + both images
+sudo ./build-all.sh
+```
+
+Output: `output/images/ArchR-R36S-YYYYMMDD.img.xz` and `ArchR-R36S-clone-YYYYMMDD.img.xz`
+
+### Build Individual Components
+
+```bash
+sudo ./build-all.sh --kernel     # Kernel + initramfs (~10 min, cross-compile)
+sudo ./build-all.sh --rootfs     # Rootfs + Mesa + ES + RetroArch (~3 hours, QEMU chroot)
+sudo ./build-all.sh --uboot      # U-Boot (~2 min)
+sudo ./build-all.sh --image      # Image assembly only (~2 min per variant)
+sudo ./build-all.sh --clean      # Remove all build artifacts
+```
+
+### Build Pipeline
+
+```
+build-all.sh
+  ├── build-initramfs.sh           # Boot splash (SVG rendering, ~648KB)
+  ├── build-kernel.sh              # Cross-compile kernel 6.12.61 (~10 min)
+  ├── build-rootfs.sh              # Arch Linux ARM in QEMU chroot (~45 min)
+  ├── build-mesa.sh                # Mesa 26 Panfrost + GLES 1.0 (~30 min)
+  ├── build-emulationstation.sh    # ES-fcamod with patches (~20 min)
+  ├── build-retroarch.sh           # RetroArch + cores (~40 min)
+  ├── generate-panel-dtbos.sh      # 20 panel overlays (~10 sec)
+  ├── build-uboot.sh               # BSP U-Boot for original boards
+  ├── build-uboot-clone.sh         # Mainline U-Boot for clone boards
+  └── build-image.sh               # SD card image (×2 variants)
+```
+
+## Project Structure
+
+```
+Arch-R/
+├── build-all.sh                     # Master build orchestrator
+├── build-kernel.sh                  # Kernel 6.12.61 cross-compilation
+├── build-initramfs.sh               # Initramfs with boot splash
+├── build-rootfs.sh                  # Root filesystem (Arch Linux ARM)
+├── build-mesa.sh                    # Mesa 26 GPU driver
+├── build-emulationstation.sh        # EmulationStation frontend
+├── build-retroarch.sh               # RetroArch + cores
+├── build-uboot.sh                   # BSP U-Boot (original boards)
+├── build-uboot-clone.sh             # Mainline U-Boot (clone boards)
+├── build-image.sh                   # SD card image assembly
+├── config/
+│   ├── linux-archr-base.config      # Kernel config (mainline 6.12)
+│   ├── a_boot.ini                   # Boot script — original variant
+│   ├── b_boot.ini                   # Boot script — clone variant
+│   ├── es_systems.cfg               # EmulationStation systems
+│   ├── retroarch.cfg                # RetroArch base config
+│   ├── asound.conf                  # ALSA audio config
+│   ├── gptokeyb/                    # Gamepad-to-keyboard mappings
+│   ├── udev/                        # udev rules (automount, USB gadget)
+│   └── autoconfig/                  # RetroArch controller autoconfig
+├── kernel/
+│   ├── dts/archr/                   # Board device trees (16 boards)
+│   └── drivers/                     # Out-of-tree joypad driver
+├── patches/                         # Kernel patches (mainline + device)
+├── scripts/
+│   ├── emulationstation.sh          # ES launch wrapper
+│   ├── retroarch-launch.sh          # RetroArch launch wrapper
+│   ├── archr-hotkeys.py             # Volume/brightness hotkey daemon
+│   ├── archr-init.c                 # Initramfs splash (static binary)
+│   ├── archr-gptokeyb.c             # Gamepad-to-keyboard mapper
+│   ├── panel-detect.py              # Panel detection
+│   ├── generate-panel-dtbos.sh      # Panel overlay generator
+│   ├── pmic-poweroff                # PMIC shutdown handler
+│   └── opt-system/                  # ES Tools menu scripts
+├── bootloader/
+│   └── u-boot-rk3326/              # U-Boot source (submodule)
+├── prebuilt/
+│   └── cores/                       # Pre-built RetroArch cores
+├── ArchR.png                        # Boot logo
+├── ROADMAP.md                       # Development diary
+└── FLASHER.md                       # Flasher app specification
+```
+
+## Hardware
+
+| Component | Details |
+|-----------|---------|
+| SoC | Rockchip RK3326 (4x Cortex-A35 @ 1.5GHz) |
+| GPU | Mali-G31 Bifrost (Mesa Panfrost, 600MHz) |
+| RAM | 1GB DDR3L (786MHz) |
+| Display | 640x480 MIPI DSI (20 panel variants) |
+| Audio | RK817 codec, speaker + headphone jack |
+| Storage | MicroSD (BOOT + rootfs + ROMS) |
+| Controls | D-pad, ABXY, L1/L2/R1/R2, dual analog sticks |
+| Battery | 3200mAh Li-Po (RK817 charger) |
+| USB | OTG with host/gadget mode switching |

 ## Architecture

 Arch R separates **board configuration** from **panel configuration**:

- **Board DTB** = hardware profile (GPIOs, PMIC, joypad, audio codec). Selected automatically by U-Boot via SARADC.
- **Panel overlay** = display init sequence and timings. Applied on top of the board DTB at boot time.
+- **Board DTB** = hardware profile (GPIOs, PMIC, joypad, audio codec). One per board variant. Selected automatically by U-Boot via SARADC ADC reading.
+- **Panel overlay** = display init sequence and timings. One per panel type. Applied on top of the board DTB at boot time.

-This means the same image works on all boards of a variant. Only the panel overlay needs to match the specific display.
+This means the same image works on all boards of a variant — only the panel overlay needs to match your specific display.

-### Boot Flow
+### Supported Boards
+
+| Board | DTB | Image |
+|-------|-----|-------|
+| R36S (original) | rk3326-gameconsole-r36s | Original |
+| Odroid Go Advance | rk3326-odroid-go2 | Original |
+| Odroid Go Advance v1.1 | rk3326-odroid-go2-v11 | Original |
+| Odroid Go Super | rk3326-odroid-go3 | Original |
+| Anbernic RG351V | rk3326-anbernic-rg351v | Original |
+| Anbernic RG351M | rk3326-anbernic-rg351m | Original |
+| GameForce Chi | rk3326-gameforce-chi | Original |
+| R33S | rk3326-gameconsole-r33s | Original |
+| MagicX XU10 | rk3326-magicx-xu10 | Original |
+| K36 / R36S clone | rk3326-gameconsole-r36max | Clone |
+| EE clone | rk3326-gameconsole-eeclone | Clone |
+| Powkiddy RGB10 | rk3326-powkiddy-rgb10 | Clone |
+| Powkiddy RGB10X | rk3326-powkiddy-rgb10x | Clone |
+| Powkiddy RGB20S | rk3326-powkiddy-rgb20s | Clone |
+| MagicX XU-Mini-M | rk3326-magicx-xu-mini-m | Clone |
+| BatLexp G350 | rk3326-batlexp-g350 | Clone |
+
+### Supported Panels
+
+#### Original R36S (7 panels)
+
+| Panel | Overlay file | Controller | Notes |
+|-------|-------------|------------|-------|
+| Panel 0 | panel0.dtbo | ST7703 | Early R36S units |
+| Panel 1 | panel1.dtbo | ST7703 | V10 board |
+| Panel 2 | panel2.dtbo | ST7703 | V12 board |
+| Panel 3 | panel3.dtbo | ST7703 | V20 board |
+| Panel 4 | panel4.dtbo | ST7703 | V22 board |
+| Panel 4-V22 | panel4-v22.dtbo | ST7703 | Most common (~60%) |
+| Panel 5 | panel5.dtbo | ST7703 | V22 Q8 variant |
+
+R46H (1024x768): `r46h.dtbo`
+
+#### Clone R36S (13 panels)
+
+| Panel | Overlay file | Controller | Notes |
+|-------|-------------|------------|-------|
+| Clone 1 | clone_panel_1.dtbo | ST7703 | |
+| Clone 2 | clone_panel_2.dtbo | ST7703 | |
+| Clone 3 | clone_panel_3.dtbo | NV3051D | |
+| Clone 4 | clone_panel_4.dtbo | NV3051D | |
+| Clone 5 | clone_panel_5.dtbo | ST7703 | |
+| Clone 6 | clone_panel_6.dtbo | NV3051D | |
+| Clone 7 | clone_panel_7.dtbo | JD9365DA | |
+| Clone 8 | clone_panel_8.dtbo | ST7703 | G80CA — most common |
+| Clone 9 | clone_panel_9.dtbo | NV3051D | |
+| Clone 10 | clone_panel_10.dtbo | ST7703 | |
+| R36 Max | r36_max.dtbo | ST7703 | 720x720 |
+| RX6S | rx6s.dtbo | NV3051D | |
+
+### Manual Panel Selection
+
+Mount the BOOT partition and copy the correct overlay as `mipi-panel.dtbo`:
+
+```bash
+sudo mount /dev/sdX1 /mnt
+
+# Example: set Panel 4-V22 (most common original R36S panel)
+sudo cp /mnt/overlays/panel4-v22.dtbo /mnt/overlays/mipi-panel.dtbo
+
+# Example: set Clone 8 (most common clone panel)
+sudo cp /mnt/overlays/clone_panel_8.dtbo /mnt/overlays/mipi-panel.dtbo
+
+sudo umount /mnt
+sync
+```
+
+## Boot Flow

 ```
 Power On
-  U-Boot (BSP or mainline)
-    boot.scr: read SARADC hwrev, select board DTB
-    sysboot: load kernel + DTB + overlay from extlinux.conf
-  Kernel 6.12 + initramfs
-    mount root (ext4) + storage
-    switch_root to systemd
-  systemd
-    archr-autostart (quirks, governors, audio)
-    EmulationStation
+  → U-Boot loads (idbloader → trust → uboot.img)
+  → boot.ini: read SARADC hwrev → select board DTB
+  → boot.ini: apply overlays/mipi-panel.dtbo (panel init sequence)
+  → Kernel 6.12.61 + initramfs splash (0.7s)
+  → systemd → archr-boot-setup (GPU + governors)
+  → emulationstation.service → EmulationStation UI
+  ≈ 19 seconds total
 ```

-### Partition Layout
+## Contributing

-| Partition | Filesystem | Label | Purpose |
-|-----------|-----------|-------|---------|
-| 1 | FAT32 | ARCHR | Boot (kernel, DTBs, overlays, boot.scr) |
-| 2 | ext4 | ARCHR_ROOT | Root filesystem |
-| 3 | ext4 | STORAGE | User data, ROMs, configs |
+See [ROADMAP.md](ROADMAP.md) for current development status and planned features.

-## Community
+## License

-Contributions are welcome. Please open issues or pull requests on [GitHub](https://github.com/archr-linux/Arch-R).
-
-## Licenses
-
-**Arch R** is a fork of [ROCKNIX](https://github.com/ROCKNIX/distribution), which is a fork of [JELOS](https://github.com/JustEnoughLinuxOS/distribution/). All upstream licenses apply.
-
-You are free to:
-
- **Share**: copy and redistribute the material in any medium or format.
- **Adapt**: remix, transform, and build upon the material.
-
-Under the following terms:
-
- **Attribution**: You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- **NonCommercial**: You may not use the material for commercial purposes.
- **ShareAlike**: If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
-
-### Arch R Software
-
-Copyright (C) 2026-present [Arch R](https://github.com/archr-linux/Arch-R)
-
-Original software and scripts developed by Arch R are licensed under the terms of the [GNU GPL Version 2](https://choosealicense.com/licenses/gpl-2.0/). The full license can be found in this project's licenses folder.
-
-### Bundled Works
-
-All other software is provided under each component's respective license. These licenses can be found in the software sources or in this project's licenses folder. Modifications to bundled software and scripts by upstream projects are licensed under the terms of the software being modified.
-
-## Credits
-
-Like any Linux distribution, this project is not the work of one person. It is the work of many people around the world who have developed the open-source components without which this project could not exist.
-
-Special thanks to:
-
- **[ROCKNIX](https://github.com/ROCKNIX/distribution)** -- the upstream distribution that Arch R is forked from. ROCKNIX provided the complete build system, device support, EmulationStation integration, and the foundation for handheld gaming on Linux.
- **[JELOS](https://github.com/JustEnoughLinuxOS/distribution/)** -- the project that ROCKNIX was originally forked from.
- **[CoreELEC](https://coreelec.org/)** and **[LibreELEC](https://libreelec.tv/)** -- the embedded Linux distributions whose build system forms the backbone of this project.
- **[Hardkernel](https://www.hardkernel.com/)** -- for the Odroid Go Advance BSP U-Boot and kernel device trees.
- **[Rockchip](https://www.rock-chips.com/)** -- for the RK3326 SoC and rkbin firmware.
- **[Mesa](https://mesa3d.org/)** -- for the Panfrost open-source GPU driver.
- **[RetroArch](https://www.retroarch.com/)** and **[Libretro](https://www.libretro.com/)** -- for the emulation framework and cores.
- **[EmulationStation](https://emulationstation.org/)** -- for the frontend.
- All developers and contributors across the open-source community who made this possible.
+GPL v3
@@ -0,0 +1,24 @@
+#!/bin/sh
+
+#
+# fusing script for ODROID-GO2 based on Rockchip RK3326
+#
+
+IDBLOADER=idbloader.img
+UBOOT=uboot.img
+TRUST=trust.img
+
+if [ -z $1 ]; then
+        echo "Usage ./sd_fusing.sh <SD card reader's device>"
+        exit 1
+fi
+
+sudo dd if=$IDBLOADER of=$1 conv=fsync bs=512 seek=64
+sudo dd if=$UBOOT of=$1 conv=fsync bs=512 seek=16384
+sudo dd if=$TRUST of=$1 conv=fsync bs=512 seek=24576
+
+sync
+
+sudo eject $1
+
+echo Finished
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Douglas Teles	9b55f926c0	Update README for mainline kernel and overlay architecture Rewrite to reflect current state: kernel 6.12.61 mainline LTS, board DTB auto-selection via SARADC, panel overlay system (20 panels), two image variants (original + clone), Flasher app for panel selection, updated boot flow, build pipeline, and project structure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 17:23:15 -03:00
Douglas Teles	b36a333523	Add Flasher app specification Complete spec for the Arch R Flasher desktop app: console type selection, panel identification wizard, image download from GitHub releases, SD card flashing with panel overlay auto-configuration. Supports Windows/macOS/Linux. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 17:23:03 -03:00
Douglas Teles	c8e7fe99e9	Add ES Tools menu scripts and gptokeyb configs (WIP) Interactive tool scripts for EmulationStation's OPTIONS menu at /opt/system/: system-info, wifi-setup, bluetooth-setup, performance-mode, suspend-mode, usb-mode, factory-reset. Uses shared menu-lib.sh with fbcon rendering. Gamepad configs: default.gptk (RetroArch), tools.gptk (menu navigation with D-pad arrows, A=enter, B=escape). Note: scripts need further testing on hardware — left disabled for now. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 17:22:49 -03:00
Douglas Teles	06dc2d16f3	Add system scripts, services, and boot splash System daemons: hotkeys (volume/brightness), automount, bluetooth agent, memory manager, sleep/suspend, USB gadget mode, save-config persistence. Boot splash: initramfs SVG renderer (fbsplash + svg_parser) for 0.7s splash. Panel tools: generate-panel-dtbos.sh rewrite, convert-panel.py for ROCKNIX panel data extraction, archr-dtbo.py for runtime overlay management. Input: archr-gptokeyb.c gamepad-to-keyboard mapper via uinput. Launch wrappers: emulationstation.sh and retroarch-launch.sh updated for KMS/DRM + Mesa 26 Panfrost environment. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 17:22:30 -03:00
Douglas Teles	8650d940e2	Migrate to mainline kernel 6.12.61 + board/overlay architecture Major architecture change: move from BSP kernel 6.6 with pre-merged panel DTBs to mainline kernel 6.12.61 LTS with separated board DTBs + panel overlays. - Board DTB = hardware profile (GPIOs, PMIC, joypad, audio). 16 boards. Auto-selected by U-Boot via SARADC ADC reading (hwrev). - Panel overlay = display init sequence. 20 panels. Applied at boot time via boot.ini fdt apply. - Two image variants: original (a_boot.ini) and clone (b_boot.ini) - Kernel cross-compiles from x86 host (no ARM chroot needed) - Initramfs boot splash with SVG rendering at 0.7s - Out-of-tree joypad driver (singleadc-joypad) for clone boards - Panel generic-dsi driver with archr,generic-dsi compatible Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 17:20:09 -03:00
Douglas Teles	70342ca457	ROADMAP: detail beta1.2 system changes and update last-updated Input merger, RetroArch tuning, panel ordering, no-panel variant, mirror list, boot.ini autodetect. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-02 02:24:00 -03:00
Douglas Teles	b6eff2e748	ROADMAP: beta1.1 pre-merged DTBs + beta1.2 Flasher diary entries Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-02 02:20:21 -03:00
Douglas Teles	9c30a92cab	Add variant-sync service, update mirrors, native DTB names - build-rootfs.sh: archr-variant-sync.service copies /boot/variant to /etc/archr/variant on first boot (for Flasher no-panel images). Runs once via ConditionPathExists, Before=panel-detect.service - build-rootfs.sh: update ALARM mirror list (remove eu.mirror/403, add de4/gr/tw/tw2/ca.us, reorder Americas first for Brazil) - build-image.sh: no-panel variant uses native DTB names (kernel-panel4.dtb, kernel-clone8.dtb) instead of inherited kernel-original.dtb / kernel-clone.dtb Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-02 00:11:28 -03:00
Douglas Teles	cbc39b8802	Add no-panel universal image variant for Flasher app Third build variant (--variant no-panel) that includes all 18 panel DTBs for both original and clone hardware. Designed for the future Arch R Flasher app to inject the correct kernel.dtb at flash time. - boot.ini: auto-detect root device from mmcdev (no more __ROOTDEV__) - build-image.sh: no-panel uses mainline U-Boot, copies all DTBs - panel-detect.py: wizard disabled for no-panel variant - build-all.sh: generates third image (ArchR-R36S-no-panel)	2026-03-01 22:11:37 -03:00
Douglas Teles	87719600d2	Update README: split panel list by variant, fix panel.txt format Separate panel tables into Original (6 panels) and Clone (12 panels) with numerical ordering and beep counts. Update manual selection to use PanelDTB= format (pre-merged DTBs). Note: ordering available from beta1.2. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-01 21:54:37 -03:00
Douglas Teles	baaeb69a19	Input merger, RetroArch tuning, panel ordering fix - input-merge daemon: combines gpio-keys + adc-joystick into single virtual "Arch R Gamepad" via uinput so RetroArch sees one device (fixes analog sticks ignored due to max_users=1) - retroarch-launch.sh: start/stop input-merge, VT blank on launch - retroarch.cfg: ROCKNIX-based tuning (48kHz audio, triple buffer, late input polling, autosave, core options path) - retroarch-core-options.cfg: per-core tuning from ROCKNIX RK3326 (mupen64plus, pcsx_rearmed, flycast, mame2003-plus, melonds, etc.) - archr-gamepad.cfg: autoconfig for merged virtual device - panel-detect.py: panels in numerical order (beep count = position), default_panel searches by empty dtb_name instead of panels[0] - build-rootfs.sh: compile input-merge, install core options and autoconfig, add input-merge and kill to sudoers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-01 21:48:49 -03:00
Douglas Teles	a1efd4fc01	Pre-merged panel DTBs: eliminate U-Boot fdt apply bugs Users reported that non-default panel overlays caused broken display, audio, and controls. Root cause: BSP U-Boot's fdt apply has bugs with property replacement of different-sized data, corrupting the DTB. Fix: apply overlays at build-time using fdtoverlay (verified working) instead of at boot-time. Each panel now gets a pre-merged kernel-*.dtb. U-Boot simply loads the right DTB by name — no fdt apply needed. - generate-panel-dtbos.sh: add fdtoverlay pre-merge step - build-image.sh: copy pre-merged DTBs instead of ScreenFiles - boot.ini: load PanelDTB by name, remove fdt addr/resize/apply - panel-detect.py: write DTB filename instead of DTBO overlay path	2026-02-28 00:14:54 -03:00
Douglas Teles	e4294ab47b	Two-image build pipeline, clone support, initramfs splash - Clone variant: mainline U-Boot v2025.10, boot.scr, clone DTS (type5) - Initramfs splash: archr-init.c with embedded BMP, sub-second display - Panel wizard: auto-detect with fsync persistence, evdev X-button reset - Hotkeys: adc-keys volume for clone, HP jack detection, brightness persist - Boot.ini: ASCII-only (no Unicode), GPIO check removed - ES wrapper: removed framebuffer blanking (preserves splash) - Build pipeline: both variants, splash generation, panel DTBOs - .gitignore: exclude large bootloader trees and build artifacts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-26 22:38:47 -03:00
Douglas Teles	70765e96bd	update 26.02.25	2026-02-25 17:22:34 -03:00
Douglas Teles	2ccf5383ac	update 26.02.23	2026-02-23 03:03:09 -03:00
Douglas Teles	476b05cd9a	fix roadmap	2026-02-22 14:46:19 -03:00
Douglas Teles	a9029b419f	Fix ROADMAP.md diary timeline ordering Move Day 17-18 entry to correct chronological position (before "What's Left for v1.0 Stable", not after it). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-22 14:43:37 -03:00
Douglas Teles	18c229177a	First successful build — 11 pipeline gaps fixed, repo organized Build pipeline now produces a working bootable image. Found and fixed 11 gaps between the manually-built working SD and build-all.sh output: Boot partition: - extlinux.conf as primary boot method (U-Boot loads first) - PanCho removed from boot.ini and build-image.sh - Stale uInitrd removed (caused wrong boot path) - logo.bmp (U-Boot native BMP) replaces broken splash-1.raw - fstab uses LABEL=ROMS instead of /dev/mmcblk1p3 - Only R36S DTB copied (no extra r35s/rg351mp-linux) Root filesystem: - emulationstation.service created and enabled - getty@tty1 disabled (ES takes over tty1) - archr-boot-setup: Before=emulationstation.service, simplified - All services use After=local-fs.target (not removed getty) - boot-timing captures ES profiling data New files added to repo: - build-mesa.sh, build-retroarch.sh (were untracked) - Custom DTS, ALSA config, controller autoconfig - Runtime scripts (retroarch-launch, pmic-poweroff, hotkeys) - VLC stub source, timezone data Repo cleanup: - README.md rewritten with build instructions + architecture - .gitignore expanded (test scripts, failed approaches, logs) - splash-show.sh removed (failed splash approach) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-22 14:01:13 -03:00
Douglas Teles	351e024374	update 26.02.19	2026-02-20 03:14:24 -03:00
Douglas Teles	4b88153812	update 26.02.18	2026-02-18 23:46:36 -03:00
Douglas Teles	54e8201a6f	update 26.02.17/18	2026-02-18 00:34:51 -03:00
Douglas Teles	9aa062e0fc	update 26.02.15	2026-02-15 23:37:25 -03:00
Douglas Teles	6b1934155a	update 26.02.14/15	2026-02-15 02:27:02 -03:00
Douglas Teles	a580bd3ce0	update 26.02.13/14	2026-02-14 04:14:39 -03:00
Douglas Teles	68b9ff798a	Audio card working, LD_PRELOAD fix, volume/brightness hotkey fixes Audio (3-iteration DTS fix chain): - Removed duplicate pinctrl from codec node (pin conflict) - Fixed sound-dai to reference &rk817_codec (MFD of_node mismatch) - Removed DAPM routing/widgets (BSP codec has no DAPM widgets) - Added 7 missing battery BSP properties Runtime fixes: - unset_preload.so prevents gl4es LD_PRELOAD inheritance to subprocesses - ES Patch 5: getShOutput() null safety for popen() failure - Volume hotkeys: use 'DAC Playback Volume' (not enum 'Playback') - Brightness: 5% minimum clamp, persistence across reboots - current_volume: reads correct ALSA control - perfmax/perfnorm: guard DMC writes with file existence check Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-12 21:07:37 -03:00
Douglas Teles	6e0e085eb8	gl4es GPU pipeline, ES display fixes, runtime hardening GPU rendering: - Panfrost driver working (6 root causes fixed) - gl4es cross-compiled for aarch64 (GOA_CLONE=ON) - ES switched to Desktop GL renderer (-DGL=ON, Renderer_GL21.cpp) - Pipeline: ES (GL 2.1) → gl4es → GLES 2.0 → Panfrost (Mali-G31) ES display (5 root causes fixed): - SDL3 KMSDRM rebuild (ALARM ships without it) - Autologin approach (systemd service can't get DRM master) - MAJOR/MINOR version bug fix - GL context restore after setIcon() - Null safety for glGetString New files: - rebuild-es-sdcard.sh (quick SD card rebuild) - config/PanCho.ini (18-panel selection) - config/es_input.cfg (gpio-keys + adc-joystick) - config/gamecontrollerdb.txt (SDL controller mappings) - scripts/archr-hotkeys.py (volume, brightness, headphone) - scripts/test-kmsdrm.py (KMSDRM diagnostic) - bootloader/u-boot-r36s-working/ (fixed U-Boot) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-11 21:42:50 -03:00
Douglas Teles	bfda02587e	Update ROADMAP.md with detailed development diary Expanded from summary format to day-by-day diary entries with technical details: discoveries, failures, root causes, and fixes. Covers all 16 sessions from Feb 4-11 based on conversation history. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-11 21:40:09 -03:00
Douglas Teles	2082ac4049	Add ROADMAP.md with full project timeline and release tracking Documents all milestones from project inception (2026-02-04) through today's gl4es + Panfrost GPU integration. Tracks what's left for v1.0 stable release. Links from README.md for visibility. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-11 21:31:23 -03:00
Douglas Teles	76d126a80f	Tons of tons	2026-02-10 01:46:47 -03:00
Douglas Teles	84d7d19283	Add development documentation with technical context	2026-02-04 14:12:57 -03:00
Douglas Teles	487c4f2cbd	Initial commit - Arch R project structure	2026-02-04 14:09:18 -03:00