Skip to content

About

A NetherSX2 Loader for Linux ARM RK3588

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NetherSX2 Linux ARM (RK3588)

License Platform Device Release Stars

Run the NetherSX2 PlayStation 2 emulator (based on AetherSX2 v1.5-4248) natively on ARM Linux, without Android. Currently supported: ROCKNIX on the Orange Pi 5.

This project is a loader: a small Linux program that loads the emulator core (libemucore.so) from the NetherSX2 Android APK and runs it on Linux. It translates the Android C library calls to Linux, replaces the Java parts of the Android app (settings, files, network, controllers, video and audio), and adds its own in-game menu.

No emulator files are included in this repository. You provide your own NetherSX2 APK and the installer extracts what it needs from it on your device.


Contents


What works

Tested on an Orange Pi 5 with ROCKNIX 20261001, with both GPU drivers (Panfrost and libmali):

  • Games running at full speed (for example Burnout Revenge and Crash Nitro Kart).
  • Very fast startup: a game opens almost immediately after you select it in EmulationStation, much faster than the other PS2 emulators we tried on ROCKNIX.
  • Vulkan renderer (the default), with the same image as on Android.
  • Internal resolution from 1x to 6x (in 0.25x steps up to 3x), anisotropic filtering, FXAA, widescreen patches.
  • Fast forward (hold L2 + R2 by default), also during loading screens.
  • Full in-game menu in the style of the ARMSX2 / AetherSX2 Big Picture interface: pause screen, every setting the emulator supports in 13 tabs, per-game settings, controller and hotkey remapping, input profiles, macros, and an English / Portuguese language option.
  • Integration with EmulationStation: NetherSX2 appears as an emulator choice for the PlayStation 2 system, and ROCKNIX's CPU/GPU performance settings are still applied.
  • RetroAchievements login taken from EmulationStation, with the emulator's own notifications (game summary and unlocks, with icons and badges) (see the limitation below).
  • Memory card as a folder (one folder per game, the default) or as a classic 8 MB .ps2 file.

Known limitations

  • RetroAchievements: the RetroAchievements server only accepts NetherSX2/AetherSX2 4248 in casual (softcore) mode. Every time a game starts you will see a "Warning: Casual Only" message: casual unlocks count, hardcore unlocks do not. This project will not try to hide or fake the emulator identity.
  • OpenGL renderer: it starts, but the game image is black. Use Vulkan (the default).
  • Only the APK version listed in What you need has been tested. Other NetherSX2/AetherSX2 builds may not work.

Supported devices

Only the Orange Pi 5 (Rockchip RK3588, Mali-G610 GPU) running ROCKNIX. It is the only device the author owns and can test on.

Other RK3588 devices may work, but they are not tested. Reports and pull requests are welcome, and working devices will be listed here with credit to whoever tested them.


What you need

  1. An Orange Pi 5 with ROCKNIX installed and working (EmulationStation boots, controller works).

  2. A computer on the same network (Windows, Linux or macOS) to copy files to the Orange Pi.

  3. The NetherSX2 APK (Android app file), which you download yourself. Tested version:

    • NetherSX2 v2.2n: NetherSX2-v2.2n-4248.apk, 21 621 788 bytes, SHA-256 2029e30dcc1ba1ecb8d73313f18b429b40e6044c7785c52af08b948ef94b3ddf

    The online multiplayer added in v2.2n is not supported by this loader yet.

  4. A PlayStation 2 BIOS dumped from your own console (a 4 MB file, for example SCPH-70012.bin or scph39001.bin).

  5. Your PS2 games dumped from your own discs (.iso, .chd, .cso, …).

The APK, the BIOS and the games are not provided by this project. Do not ask for them in the issues.


Installation, step by step

Step 1: Download this project

  1. Open the Releases page of this repository.
  2. Download the latest nethersx2-rocknix.tar.gz.

The package contains only the loader (nethersx2), the scripts and this README. It does not contain any file from the APK.

Step 2: Get the NetherSX2 APK

  1. Open the official NetherSX2 releases page: https://github.com/Trixarian/NetherSX2-patch/releases
  2. Find the NetherSX2 v2.2n release and download NetherSX2-v2.2n-4248.apk (under Assets). Download it only from there: copies from other sites may be modified.
  3. (Optional) Check that it is the tested file. Its SHA-256 should be the one listed in What you need:
    • Linux: sha256sum NetherSX2-v2.2n-4248.apk
    • macOS: shasum -a 256 NetherSX2-v2.2n-4248.apk
    • Windows (PowerShell): Get-FileHash NetherSX2-v2.2n-4248.apk

You do not need to unzip the APK yourself. The installer does that on the Orange Pi.

Step 3: Prepare the network on the Orange Pi

The files are copied over your local network (SFTP), and the installer is run from a terminal (SSH).

  1. On the Orange Pi, open the EmulationStation main menu (Start).
  2. Go to Network Settings and check:
    • IP Address: write it down (for example 192.168.1.50); you only need it if the network name below does not work.
    • Hostname: the network name of the Orange Pi (RK3588 by default).
    • Enable SSH: must be on.
  3. Go back to the main menu and open System Settings → Security → Root Password. Write down the password shown there.

In the steps below the Orange Pi is reached by its hostname followed by .local, for example rk3588.local. If you changed the hostname, use yours (for example mypi.local). If your computer cannot find it, use the IP address instead (for example sftp://192.168.1.50 and ssh root@192.168.1.50).

Step 4: Copy the files to the Orange Pi with FileZilla

FileZilla is free and works on Windows, macOS and Linux.

  1. Install and open FileZilla (the FileZilla Client).
  2. In the Quickconnect bar at the top, fill in:
    • Host: sftp://rk3588.local
    • Username: root
    • Password: the root password from Step 3
    • Port: 22
  3. Click Quickconnect. Accept the server key if FileZilla asks (only the first time).
  4. In the Remote site box on the right, type /storage and press Enter.
  5. Drag these two files from the left side (your computer) to the right side (/storage):
    • nethersx2-rocknix.tar.gz (from Step 1)
    • your NetherSX2 APK, for example NetherSX2-v2.2n-4248.apk (from Step 2)

Keep FileZilla open: you will use it again for the BIOS and the games.

Step 5: Run the installer

The installer runs on the Orange Pi, through a terminal connection (SSH).

  1. Open a terminal on your computer:

    • Windows: open PowerShell (Start menu → type PowerShell).
    • macOS: open Terminal (Applications → Utilities).
    • Linux: open your terminal app.
  2. Connect to the Orange Pi:

    ssh root@rk3588.local

    The first time, type yes to accept the key. Then type the root password from Step 3 (nothing appears while you type it; this is normal) and press Enter.

  3. Run these commands, one at a time (use your APK's real file name in the third one):

cd /storage
tar xzf nethersx2-rocknix.tar.gz
mv NetherSX2-v2.2n-4248.apk nethersx2/
sh nethersx2/install.sh --default

What each command does:

Command What it does
cd /storage Goes to the folder where you copied the files.
tar xzf nethersx2-rocknix.tar.gz Unpacks the release into the new folder /storage/nethersx2.
mv NetherSX2-v2.2n-4248.apk nethersx2/ Moves your APK into that folder.
sh nethersx2/install.sh --default Extracts the emulator files from the APK and adds NetherSX2 to EmulationStation as the default PS2 emulator.

If everything went well, you will see:

Extracting emulator files from NetherSX2-v2.2n-4248.apk...
Emulator files extracted. The APK is no longer needed and can be deleted.
NetherSX2 added to the PS2 system (backup: /storage/.config/emulationstation/es_systems.cfg.bak-nethersx2).
Restart EmulationStation to apply (or reboot).

Prefer to keep another PS2 emulator as the default? Run sh nethersx2/install.sh without --default. NetherSX2 will still be available as an option in EmulationStation (see Step 9).

After this step you can delete the APK and the .tar.gz file:

rm /storage/nethersx2/*.apk /storage/nethersx2-rocknix.tar.gz

Type exit to close the connection.

Step 6: Copy the PS2 BIOS

In FileZilla, go to /storage/roms/bios on the right side and drag your BIOS file into it. This is the normal ROCKNIX BIOS folder.

NetherSX2 finds any 4 MB BIOS file in that folder (and in its subfolders) automatically every time a game starts.

Step 7: Copy your games

In FileZilla, go to /storage/roms/ps2 and drag your PS2 games into it. This is the same folder used by the other PS2 emulators of ROCKNIX.

Then, on the Orange Pi, open Start → Game Settings → Update Gamelists and choose Yes, so the new games appear in the list.

Step 8: Restart EmulationStation

Restart the Orange Pi, or restart only EmulationStation from its menu (Start → Quit → Restart EmulationStation).

Step 9: Play

  1. In EmulationStation, open PlayStation 2 and start a game.
  2. If you installed without --default, choose NetherSX2 as the PS2 emulator first, in either of these ways:
    • Start → Game Settings → Per System Advanced Configuration → PlayStation 2 → Emulator → NetherSX2: nethersx2-sa
    • or, in the PlayStation 2 game list, press Select (Options) → Advanced System Options → Emulator → NetherSX2: nethersx2-sa
  3. The first start writes the default settings (Vulkan renderer, fast forward on L2 + R2, etc.). Press the menu hotkey (L3 + R3 by default) at any time to open the in-game menu; the same hotkey closes it again.

After a ROCKNIX update, the PS2 entry in EmulationStation may be reset. Just run sh /storage/nethersx2/install.sh --default again (no APK needed this time) and restart EmulationStation (Step 8).


Controls and in-game menu

Hotkeys during the game

Buttons (default) Action
L3 + R3 (press both sticks) Menu hotkey: opens the in-game menu. While the menu is open, the same hotkey closes it, and the next time the menu reopens exactly where you left it, which makes quick tweaks easy. This works with whatever combination you assign to Open Pause Menu.
L2 + R2 (hold) Fast forward

Both are only defaults: every hotkey can be changed in Settings → Hotkeys (see Remapping). If the menu hotkey is ever left unbound, L3 + R3 is restored at the next start, so you can never lock yourself out of the menu.

Button names use the PlayStation layout. On an Xbox-style controller, Cross is A, Circle is B, Square is X and Triangle is Y.

In-game menu

The game pauses while the menu is open. The look follows ARMSX2 / AetherSX2's Big Picture interface. The icons and controller glyphs come from the ARMSX2 package that ROCKNIX already includes (nothing extra to install).

Pause screen: Resume Game, Toggle Frame Limit, Load State, Save State, Save Slot (1 to 10), Game Properties (per-game settings), Achievements, Switch To Software Renderer, Settings, Reset and Close Game. The header shows the game, its serial / CRC, the clock (12 or 24 hours, as set in EmulationStation) and the play time.

Settings are split in tabs: Interface, BIOS, Emulation, Graphics, On-Screen Display, Audio, Memory Cards, Network & HDD, Folders, Achievements, Controllers, Hotkeys and Advanced. Each row has a short description; options that depend on another one are dimmed while it is off.

Buttons Action
D-pad up / down (or left stick) Move between options. Up from the first row selects the tab bar.
D-pad left / right Change the value (on the tab bar: change tab)
L1 / R1 Change tab
Cross (A) Select: opens the list of values, toggles a switch, runs an action
Square (X) Clear a binding / go back to the global setting (per-game)
Circle (B) Back (from Settings to the pause screen; from the pause screen to the game)
Start Close the menu

Changed settings are saved and applied when the menu closes.

Some highlights:

  • Internal Resolution sits at the top of Graphics → Display, for quick changes.
  • Performance Preset (On-Screen Display): Off, FPS, Detailed or Full information in the top-right corner.
  • Hardcore mode (Achievements): can be turned off for the rest of the session (loading states is allowed again). As required by RetroAchievements, it only comes back on by restarting the game.
  • Language (Interface): English (default) or Português.

Per-game settings

Pause screen → Game Properties edits the settings of the running game only (tabs Summary, Emulation, Patches, Cheats, Graphics, On-Screen Display, Audio, Memory Cards and Advanced).

  • Every option starts as Use Global Setting; switches have a third, grey "global" position. Change a value to override it for this game; Square (or Use Global Setting in the list) goes back to the global value.
  • Summary shows the title, serial, CRC, region and path, lets you pick an input profile for the game, and has Copy Settings (copy the current global settings) and Clear Settings.
  • Settings are stored in /storage/.config/nethersx2/gamesettings/<SERIAL>_<CRC>.ini, the emulator's own per-game file.

Remapping buttons and hotkeys

In Settings → Controllers (buttons) and Settings → Hotkeys, select a row with Cross: a window counts down 5 seconds. Press the new button (or move a stick / trigger). To bind a combination, hold the buttons together; it is saved when you release them all. Pressing nothing leaves the binding unchanged; Square clears it.

Also in Controllers: controller type, Automatic Mapping (maps a port to a connected controller), multitap, stick inversion, deadzones, sensitivity, vibration, 16 macro buttons per port (trigger, buttons, frequency, pressure), and Load / Save Profile (input profiles, named with an on-screen keyboard). A profile can then be used by a single game from its Game Properties.

Where your files are

Memory cards and save states

You choose where they are kept in the in-game menu (Save Folder in the Interface, Memory Cards and Folders tabs):

Save folder Memory cards Save states
roms/ps2 (default) /storage/roms/ps2 /storage/roms/savestates/ps2/nethersx2
roms/saves/ps2 /storage/roms/saves/ps2 /storage/roms/saves/ps2/sstates
.config/nethersx2 /storage/.config/nethersx2/memcards /storage/.config/nethersx2/sstates
  • By default the memory cards are in the same folder as the AetherSX2 and ARMSX2 emulators included in ROCKNIX, so your game saves are shared with them. Save states are kept in their own nethersx2 subfolder: they only work with the emulator that created them, and ARMSX2 uses the same file names.
  • A memory card folder holds the folder card saves.ps2 (one folder per game save) and any classic card file (Mcd001.ps2, …). Your games in roms/ps2 are never moved or changed.
  • A new choice takes effect the next time a game starts. Your existing memory cards and save states are then moved automatically to the new folder.
  • If the same save exists in both folders, the identical copy is removed, the newest one is kept and the older one is moved to /storage/.config/nethersx2/save-backups/<date>/. Nothing is deleted. A message on screen tells you what was moved.
  • Choose Folder... lets you pick (or create) any other folder with the controller: memory cards go in that folder, save states in its sstates subfolder.
  • The other data folders (BIOS, snapshots, cheats, texture replacements, covers, logs) can be changed in Settings → Folders, also with the folder browser. They take effect the next time a game starts.

Other files

What Where on the Orange Pi
Loader, scripts and files extracted from the APK /storage/nethersx2
Settings (nethersx2.ini) and other emulator data /storage/.config/nethersx2
BIOS (links to your BIOS files) /storage/.config/nethersx2/bios
Log of the last run /var/log/nethersx2.log (deleted when the device restarts)

To sync your saves between devices (for example with Syncthing), sync the memory card and save state folders above. Back up /storage/.config/nethersx2 to keep your settings.


RetroAchievements

NetherSX2 uses the RetroAchievements account you set up in EmulationStation (Start → Game Settings → RetroAchievements Settings): the username, the on/off switch and Hardcore Mode are read every time a game starts.

  • When a game starts, a message shows the game title and your progress (achievements and points).
  • New unlocks are shown on screen.
  • In Hardcore mode, loading states is blocked (this is a RetroAchievements rule). The menu shows the option as locked.

Remember the limitation: the RetroAchievements server marks this emulator as unsupported, so achievements may not count.


Updating

  1. Download the new nethersx2-rocknix.tar.gz and copy it to /storage with FileZilla (Step 4).
  2. Connect with ssh root@rk3588.local (Step 5) and unpack it over the old install. Your extracted APK files, settings and saves are kept:
cd /storage
tar xzf nethersx2-rocknix.tar.gz
sh nethersx2/install.sh --default
rm nethersx2-rocknix.tar.gz
  1. Restart EmulationStation (Step 8).

Uninstalling

# put back the EmulationStation config saved by the last install.sh run
cp /storage/.config/emulationstation/es_systems.cfg.bak-nethersx2 /storage/.config/emulationstation/es_systems.cfg
# remove the loader
rm -rf /storage/nethersx2

Then restart EmulationStation (Step 8).

Your settings and saves in /storage/.config/nethersx2 are not removed. Delete that folder too only if you do not need them anymore.


Troubleshooting

The first thing to check is always the log of the last run:

cat /var/log/nethersx2.log
Problem What to do
The game closes right away and the log says no PS2 BIOS found Copy a 4 MB PS2 BIOS file into /storage/roms/bios (Step 6).
install.sh says No APK found Copy your NetherSX2 .apk into /storage/nethersx2 and run it again.
install.sh says the APK has no libemucore.so The file is not the NetherSX2 APK, or it is a version for another CPU. Download it again (Step 2).
The log says NativeLibrary.initialize failed The APK files are missing or from an unsupported version. Run install.sh again with the tested APK.
NetherSX2 does not appear in EmulationStation Run sh /storage/nethersx2/install.sh --default, then restart EmulationStation (Step 8).
Black game image You are using the OpenGL renderer. Switch back to Vulkan (renderer 14 under [EmuCore/GS] in nethersx2.ini).
A game is slow Lower the internal resolution in the menu, then try EE Cycle Rate / EE Cycle Skip.

When reporting a problem, open an issue and include: the game, your settings (nethersx2.ini), the log (/var/log/nethersx2.log), your ROCKNIX version, the GPU driver (Panfrost or libmali) and your APK's SHA-256.


Building from source

You only need this if you want to change the loader. Releases already contain the compiled program.

The loader is cross-compiled on a Linux PC (x86-64) for aarch64 with clang and lld, using a Debian bookworm arm64 sysroot (glibc 2.36).

# once: download the Debian arm64 sysroot (needs python3)
make sysroot

# build the loader -> build/nethersx2
make

# build the release package -> dist/nethersx2-rocknix.tar.gz (no APK files inside)
make dist

Source layout:

File Purpose
src/elf_loader.c Loads the Android libemucore.so into memory
src/bionic.c, src/bionic_setjmp.S Android C library (bionic) → Linux (glibc) translation
src/jni.c, src/java.c Replacement for the Java side of the app (settings, files, network…)
src/platform.c SDL2, Wayland, EGL, Vulkan, audio and controllers
src/vkproxy.c Vulkan swapchain proxy (lets fast forward go past the display refresh rate)
src/overlay.c Full-screen menu canvas (Wayland subsurface, SDL_ttf)
src/menu.c, src/menu_pages.c In-game menu: engine (screens, popups, remapping) and page contents
src/i18n.c Menu and on-screen message languages (English, Portuguese)
src/saves.c Memory card / save state folders and moving saves between them
src/affinity.c Places the emulator threads on the right CPU cores
src/settings.c nethersx2.ini
src/main.c Main flow, menu hotkey, RetroAchievements, memory cards
tools/menu_preview.c make preview: renders the menu to images on the PC, for development
scripts/ Installer, launcher and EmulationStation integration

Planned updates

  • Online multiplayer (the network adapter support added in NetherSX2 v2.2n).
  • Batocera version of the loader.

Credits and legal

  • AetherSX2 by Tahlreth, and NetherSX2 by Trixarian and contributors: the emulator core this loader runs. This project is not affiliated with or endorsed by them.
  • PCSX2, which AetherSX2 is based on.
  • ROCKNIX team, for the distribution this runs on.

This repository contains only the loader's own code and scripts. It does not include and will never distribute the NetherSX2/AetherSX2 APK or any file taken from it (libemucore.so, assets, certificates), nor any PS2 BIOS or game. Use your own legally obtained copies.

License

The loader's code and scripts are free software, released under the GNU General Public License v3.0 or later (see LICENSE). You can use, study, change and share them; if you distribute a modified version, its source code must be available under the same license.

Exception: src/include/jni.h is the standard JNI header from the Android Open Source Project and keeps its original Apache License 2.0 (see LICENSES/Apache-2.0.txt).

This license covers only this project's files. NetherSX2/AetherSX2, its APK and everything extracted from it are not part of this project and are not covered by it.

About

A NetherSX2 Loader for Linux ARM RK3588

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages