Porting NextUI Paks to H700

Porting a NextUI Pak to H700

H700 is the NextUI platform for the Anbernic RG XX family. This playbook covers the changes commonly needed when porting an existing tg5040 Pak.

1. Add the H700 package

Place the H700 version under the appropriate platform folder:

Emus/h700/<NAME>.pak/
Tools/h700/<NAME>.pak/

Do not install community Paks under .system; NextUI replaces that directory during updates.

2. Check or rebuild bundled binaries

TG5040 and H700 are both 64-bit AArch64/Cortex-A53 targets, so a simple binary may already run. Do not assume it will: graphics, audio, input, device paths and the host userland differ.

Use the NextUI H700 toolchain for bundled executables and libretro cores. Check the result before release:

file your_binary
ldd your_binary

It must be AArch64 and every dynamic dependency must resolve on a clean H700 installation. For a bundled libretro core, also verify that LTO has not stripped its frontend symbols:

nm -D core_libretro.so | grep retro_api_version

3. Use a POSIX launch.sh

H700's /bin/sh may be dash. A common TrimUI launcher bug is using the Bash-only &> redirect. Under dash this can background the emulator and immediately return to NextUI.

Use:

command > "$LOGS_PATH/MyPak.txt" 2>&1

Avoid &>, [[ ... ]], arrays, source, brace expansion and other Bash-only syntax. Use Unix line endings, quote paths and preserve executable permissions.

A safe tool launcher is:

#!/bin/sh

PAK_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cd "$PAK_DIR" || exit 1

./mytool > "$LOGS_PATH/MyTool.txt" 2>&1

4. Use NextUI paths, not OS paths

NextUI exports a normalized environment including:

$PLATFORM             h700
$DEVICE               device family
$SDCARD_PATH          NextUI SD card
$SYSTEM_PATH          .system/h700
$USERDATA_PATH        platform-specific writable data
$SHARED_USERDATA_PATH cross-platform writable data
$BIOS_PATH            $ROMS_PATH
$SAVES_PATH           $CHEATS_PATH
$CORES_PATH           $LOGS_PATH
$HOME

Use these variables instead of /mnt/sdcard, /mnt/mmc, /mnt/vendor, /usr/trimui, raw mmcblk devices or .userdata/tg5040.

The real H700 TF2 mount is normally /mnt/sdcard, while NextUI exposes /mnt/SDCARD through $SDCARD_PATH. It can be a symlink or bind mount depending on the base OS. Treat $SDCARD_PATH as authoritative and do not compare resolved mount paths as strings.

Store persistent configuration in $USERDATA_PATH or $SHARED_USERDATA_PATH, and logs in $LOGS_PATH.

5. Do not depend on the host OS

NextUI supports Anbernic stock OS, StockMod and BaseOS. Stock and StockMod use an Ubuntu/systemd environment; BaseOS has a smaller BusyBox-style init environment. Installed commands and service behavior are not identical.

• Do not call systemctl, loginctl, /etc/init.d/*, apt or vendor scripts.
• Do not manage NetworkManager, wpa_supplicant, BlueZ or audio services.
• Do not assume bash, timeout, realpath, readlink -f, udhcpc or dhclient exists.
• Invoke tools by name through PATH, not through hardcoded /usr/bin/... paths.
• Feature-test optional commands with command -v.

Stock OS does not ship curl, but NextUI bundles a static build, places it first on PATH and exports its CA bundle. This is portable across all three OSes:

curl -fL "$URL"

This is not:

/usr/bin/curl -fL "$URL"

A Pak should not normally need to detect the underlying OS. The Stock/StockMod "MU style" setting only affects whether NextUI boots; it needs no handling after a Pak has launched.

6. Reuse NextUI's graphics and audio runtime

Unlike TG5040, H700 uses a custom NextUI SDL2 build for its Mali-G31 framebuffer stack. The launcher already exports the required SDL, EGL, GLES, audio, input and rotation environment.

• Dynamically link SDL2 and let NextUI's LD_LIBRARY_PATH select the runtime.
• Do not bundle a generic desktop, X11, Wayland or KMS/DRM SDL build.
• Do not clear or replace LD_LIBRARY_PATH, SDL_VIDEODRIVER, SDL_AUDIODRIVER, SDL_ROTATION or the EGL/GLES driver variables.
• Link GLES directly with -lGLESv2 -lEGL; TrimUI's glesv2.pc may incorrectly add the unavailable libUMP.
• Do not bundle TrimUI's libUMP or libasound.

If the Pak needs private libraries, prepend only its own directory:

LD_LIBRARY_PATH="$PAK_DIR/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
export LD_LIBRARY_PATH

Audit libraries loaded with dlopen as well as those reported by ldd; missing runtime-loaded dependencies can fail silently.

7. Handle the H700 device family

One h700 platform covers several layouts:

$DEVICE	Relevant difference
rg28xx	Rotated 480x640 panel
rg34xx	720x480 family
rgsp	720x480, no analog sticks
rg35xx	RG35XX family
rg40xx	RG40XX family
cube	720x720 square panel

Use $DEVICE for layout families. $RGXX_MODEL contains the more specific model string when an exact model distinction is genuinely required.

SDL applications should inherit NextUI's environment, including SDL_ROTATION on RG28XX. Software that directly opens /dev/fb0, /dev/input/event*, LEDs, mixer controls or PMIC devices needs a real H700 port; TrimUI paths and mappings will not carry over. Do not assume every model has analog sticks, RGB LEDs, a lid sensor or HDMI.

8. Standalone emulator notes

A standalone emulator does not automatically receive MinArch quicksave, auto-resume, menu or input integration.

If it resets brightness or volume during startup, run this before it:

syncsettings.elf &

Do not invoke poweroff or reboot directly. Ask the NextUI launcher to perform the platform-appropriate operation, then exit:

touch /tmp/poweroff    # or /tmp/reboot
exit 0

9. Minimum test pass

Before advertising H700 support, test:

• launch and clean exit, including paths containing spaces;
• save and configuration persistence;
• sleep/resume and brightness/volume after exit;
• network use through curl, if applicable;
• stock OS, StockMod and BaseOS;
• a 640x480 device and a non-640x480 device;
• RG28XX rotation or CubeXX layout if the Pak draws its own UI;
• HDMI if the application owns display setup.

For the general Pak format and MinArch launcher boilerplate, see PAKS.md.