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 <noreply@anthropic.com>
This commit is contained in:
cloudwithax
parent
67665e597f
commit
cdb260fc58
309
README.md
309
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@<device-ip>
|
||||
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@<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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue