ArchySP/README.md

# 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:
```bash
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:

```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
```

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

```bash
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`:

```bash
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:
   ```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@<device-ip>
   ```

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.