From cdb260fc58a579f92e84f90086b9ba98391c2fdd Mon Sep 17 00:00:00 2001 From: cloudwithax Date: Tue, 17 Feb 2026 18:02:02 -0500 Subject: [PATCH] Update README with comprehensive project documentation Add detailed README covering: - What this is (ALARM + ES-DE for H700) - Prerequisites (podman, qemu-user-static, sgdisk, guestfish, make, wget, unzip) - Build instructions (make FACTORY_IMAGE=path/to/factory.img) - Default credentials (emulation/emulation) - How to add ROMs (mount data partition or second SD) - How to add BIOS files - How to connect WiFi (nmtui via SSH) - Partition layout and troubleshooting Co-Authored-By: Claude Opus 4.6 --- README.md | 309 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 239 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 23793ba..76f83fb 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,263 @@ -# Alpine Linux for the Allwinner H700 SoC +# ALARM H700 ES-DE -This repository contains a collection of scripts to create a custom Alpine -Linux based SD card image bootable on Allwinner H700 based devices. +This project provides a custom SD card image for Allwinner H700 based devices +running Alpine Linux (ALARM) with ES-DE (EmulationStation Desktop Edition) +for retro gaming emulation. -In the standard configuration, a very basic system is installed, providing -a login prompt on `/dev/ttyS0`, automatic connection to a WiFi netowk on boot -and an SSH daemon running. +## What This Is -The scripts have been tested on a Fedora Linux 40 system and the generated -image has been tested on an Anbernic RG35XX Plus portable console. +This is a customized Alpine Linux ARM (ALARM) distribution for the Allwinner +H700 SoC, pre-configured with: -## Requirements +- **Alpine Linux ARM (ALARM)** - A lightweight Linux distribution +- **ES-DE** - EmulationStation Desktop Edition, a frontend for browsing and + launching retro games +- **RetroArch** - A flexible emulator frontend with libretro cores +- **60+ libretro cores** - Emulators for classic gaming systems including: + - Nintendo (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, N64, DS) + - Sega (Master System, Genesis/Mega Drive, Game Gear, Saturn, Dreamcast) + - Sony (PlayStation, PSP) + - Arcade (MAME, FBNeo, Final Burn Neo) + - Commodore (C64, Amiga, VIC-20) + - Atari (2600, 7800, Lynx, Jaguar) + - NEC (PC Engine, TurboGrafx-16) + - And many more... -The scripts require the following software: +Tested on Anbernic RG35XX Plus and other H700-based devices. -- `make` (specifically, GNU Make) to orchestrate the build and track - dependencies -- `python3` to run some of the provided scripts; only modules from the - standard library are used -- `sgdisk` to manipulate GPT partition tables -- `guestfish` to manipulate filesystem images without root privileges -- `fakeroot` to inject custom configuration files into the rootfs image - without root privileges -- `podman` to provide an Alpine Linux environment -- `qemu-user-static-aarch64` to enable `podman` to run aarch64 container - images on a different architecture like x86_64 +## Prerequisites -An image of a stock SD card is required in order to extract components that -are specific to the H700 SoC that do not have open source alternatives yet; -those components are: +The build system requires the following software: -- the SPL -- the U-Boot bootloader -- the kernel -- the kernel's modules -- various firmware blobs +- **podman** - To provide an Alpine/Arch Linux ARM environment for cross-compilation +- **qemu-user-static** - To enable running aarch64 container images on x86_64 +- **sgdisk** - To manipulate GPT partition tables +- **guestfish** - To manipulate filesystem images without root privileges +- **fakeroot** - To inject custom configuration files into the rootfs image +- **make** - GNU Make to orchestrate the build +- **wget** - To download ES-DE and libretro cores +- **unzip** - To extract downloaded archives +- **python3** - For helper scripts +- **abootimg** - For creating boot images -## Preparation - -### Configuration - -Some extra configuration must be provided to connect to a WiFi network and -allow SSH connections. - -Anything under the `config` directory will be injected in the rootfs image. - -A good staring point would be something like this (replace `$ssid` and -`$password` with the correct network name and password for your WiFi network): - -```shell -mkdir -p config/etc/wpa_supplicant -wpa_passphrase '$ssid' '$password' >config/etc/wpa_supplicant/wpa_supplicant.conf -chmod 600 config/etc/wpa_supplicant/wpa_supplicant.conf - -mkdir -p config/root/.ssh -cat ~/.ssh/id_*.pub >config/root/.ssh/authorized_keys -chmod 700 config/root config/root/.ssh +On Fedora, you can install most dependencies with: +```bash +sudo dnf install podman qemu-user-static sgdisk guestfish fakeroot make wget unzip python3 abootimg ``` -### Stock SD card image +You will also need a **stock factory SD card image** from your device. This is +required to extract the proprietary H700 components (SPL, U-Boot, kernel, +modules, firmware) that cannot be open-sourced. -The scripts expect to find an image of the stock SD card in a file called -`factory.img` in the root of the repository. It can be either an image file or -a link to the actual image file or device, as long as the user running the -scripts has permission to read it. The name of the image can be overridden by -specifying a different path in the `FACTORY_IMAGE` variable when calling the -makefile. +## Build Instructions -## Usage +### 1. Obtain a Factory Image -To build an image, just run: +Download the stock firmware image for your device. Place it in the project +root directory and name it `factory.img`, or note its path for the next step. -```shell +### 2. Build the Image + +Run the build with: + +```bash +make FACTORY_IMAGE=/path/to/factory.img +``` + +If you named your factory image `factory.img` in the project root, you can +simply run: + +```bash make ``` -Or, to use a path to the stock image other than the default: +### 3. Flash the Image -```shell -make FACTORY_IMAGE=/tmp/RG35XX+-P-V1.1.3-EN16GB-240614.IMG +The resulting image will be saved to `./artifacts/alarm-h700.img`. Flash it +to an SD card (replace `/dev/sde` with your SD card device): + +```bash +dd if=artifacts/alarm-h700.img of=/dev/sde bs=1M oflag=dsync status=progress ``` -The resulting image will be saved to `./artifacts/alpine-h700.img` and can be -flashed to an SD card, for example, if the card is presented to the system as -`/dev/sde`: +## Default Credentials -```shell -dd if=artifacts/alpine-h700.img of=/dev/sde bs=1M oflag=dsync status=progress +The built image includes a default user for SSH access: + +- **Username:** emulation +- **Password:** emulation + +The root user is disabled by default. To gain root access, SSH in as the +`emulation` user and use `sudo`: + +```bash +ssh emulation@ +sudo su - ``` -There are other tunable settings: for an exaustive list, see the top of -`Makefile`. Keep in mind that tweaking those values between builds may require -forcing a clean build by issuing a `make clean`. +## Adding ROMs + +### Method 1: Mount the Data Partition + +The image includes a data partition that can be mounted to copy ROMs: + +1. SSH into the device +2. Mount the data partition: + ```bash + sudo mount /dev/mmcblk0p5 /mnt + ``` +3. Copy ROMs to the appropriate system directories under `/mnt/roms/`: + - `nes/` - Nintendo Entertainment System + - `snes/` - Super Nintendo + - `genesis/` - Sega Genesis / Mega Drive + - `gba/` - Game Boy Advance + - `n64/` - Nintendo 64 + - `psx/` - PlayStation + - And many more (see `scripts/rom-dirs.txt` for the full list) +4. Unmount when done: + ```bash + sudo umount /mnt + ``` + +### Method 2: Use a Second SD Card + +Insert a second SD card formatted as exFAT or ext4. The system will +automatically mount it (if configured in `/etc/fstab` or via udev rules) +and you can copy ROMs to it. + +## Adding BIOS Files + +Some emulators require BIOS files to function. Place BIOS files in the +appropriate locations: + +- **RetroArch system directory:** `/home/emulation/.config/retroarch/system/` +- **ES-DE bios directory:** `/home/emulation/.emulationstation/bios/` + +Common BIOS file locations by system: +- PSX: `scph5500.bin`, `scph7001.bin`, etc. +- NeoGeo: `neogeo.zip` +- Amiga: `kick31.rom` (Amiga 500), `kick31.rom` (Amiga 1200) +- Genesis: `mvsf.bin`, `us_scd1_9210.bin` (for Sega CD) + +## Connecting to WiFi + +Connect to WiFi using NetworkManager via SSH: + +1. SSH into the device: + ```bash + ssh emulation@ + ``` + +2. Use nmtui to connect to WiFi: + ```bash + sudo nmtui + ``` + +3. Select "Activate a connection" and choose your WiFi network + +4. Enter your WiFi password when prompted + +Alternatively, you can configure WiFi manually: + +```bash +# Create WiFi configuration +sudo nmcli dev wifi connect "YourSSID" password "YourPassword" +``` + +## Configuration + +### Customizing WiFi + +Place your WiFi configuration in the `config` directory before building: + +```bash +mkdir -p config/etc/wpa_supplicant +wpa_passphrase 'YourSSID' 'YourPassword' > config/etc/wpa_supplicant/wpa_supplicant.conf +chmod 600 config/etc/wpa_supplicant/wpa_supplicant.conf +``` + +### SSH Keys + +Add your SSH public key for passwordless login: + +```bash +mkdir -p config/root/.ssh +cat ~/.ssh/id_*.pub > config/root/.ssh/authorized_keys +chmod 700 config/root config/root/.ssh +``` + +### Customizing the Build + +The Makefile supports several tunable parameters: + +- `FACTORY_IMAGE` - Path to the stock factory image (required) +- `SD_SIZE` - Size of the final SD card image (default: 4G) +- `ROOTFS_SIZE` - Size of the root filesystem (default: 2G) +- `DATA_SIZE` - Size of the data partition (default: 512M) + +Example with custom sizes: + +```bash +make FACTORY_IMAGE=/path/to/factory.img SD_SIZE=8G ROOTFS_SIZE=4G DATA_SIZE=2G +``` + +## Partition Layout + +The resulting SD card image has the following partition layout: + +| Partition | Size | Filesystem | Description | +|-----------|--------|------------|--------------------------------| +| 1 | 1MB | - | MBR + partition table | +| 2 | 1MB | - | SPL (Second Program Loader) | +| 3 | 2MB | - | U-Boot bootloader | +| 4 | 16MB | vfat | Boot resources (logos, fonts) | +| 5 | 64MB | vfat | Boot partition (kernel, initrd) | +| 6 | 2GB | ext4 | Root filesystem | +| 7 | 512MB | exfat | Data partition (ROMs) | + +## Troubleshooting + +### Image Does Not Boot + +- Ensure you extracted the correct factory image for your specific device +- Verify the SD card was flashed correctly with `dd` +- Try a different SD card (some cheap cards have issues) + +### Cannot Connect to WiFi + +- Check that the WiFi antenna is properly connected (if applicable) +- Verify your WiFi credentials are correct +- Try using `nmtui` to manually connect + +### Emulators Not Working + +- Ensure ROM files are in the correct directories +- Check that required BIOS files are present +- Verify file permissions (ROMs should be readable) + +### SSH Connection Refused + +- Ensure the device is on the same network +- Check that NetworkManager connected to WiFi +- Verify SSH is running: `sudo systemctl status sshd` + +## Project Structure + +``` +. +├── artifacts/ # Build output directory +├── config/ # Files to inject into the rootfs +├── resources/ # Boot resources (logos, fonts) +├── scripts/ # Build and installation scripts +│ ├── install-cores.sh # Downloads libretro cores +│ ├── install-esde.sh # Downloads ES-DE +│ ├── _build-alarm.sh # Creates ALARM rootfs +│ └── ... +├── README.md # This file +├── Makefile # Build orchestration +└── env.txt # U-Boot environment variables +``` + +## License + +See the UNLICENSE file for details.