ALARM H700 ES-DE

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.

What This Is

This is a customized Alpine Linux ARM (ALARM) distribution for the Allwinner H700 SoC, pre-configured with:

• 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...

Tested on Anbernic RG35XX Plus and other H700-based devices.

Prerequisites

The build system requires the following software:

• 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

On Fedora, you can install most dependencies with:

sudo dnf install podman qemu-user-static sgdisk guestfish fakeroot make wget unzip python3 abootimg

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.

Build Instructions

1. Obtain a Factory Image

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.

2. Build the Image

Run the build with:

make FACTORY_IMAGE=/path/to/factory.img

If you named your factory image factory.img in the project root, you can simply run:

make

3. Flash the Image

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):

dd if=artifacts/alarm-h700.img of=/dev/sde bs=1M oflag=dsync status=progress

Default Credentials

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:

ssh emulation@<device-ip>
sudo su -

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:

   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:

   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:

   ssh emulation@<device-ip>
   

2. Use nmtui to connect to WiFi:

   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:

# Create WiFi configuration
sudo nmcli dev wifi connect "YourSSID" password "YourPassword"

Configuration

Customizing WiFi

Place your WiFi configuration in the config directory before building:

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:

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:

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.