Skip to content

Community Guides

Jump to bottom Edit New page
Zetarancio edited this page May 2, 2024 · 11 revisions

EmuDeck

⚠️ Warning

EmuDeck is not officially supported on ChimeraOS. EmuDeck may have assumptions about running on the Steam Deck. ChimeraOS highly recommends using our built-in emulation solution. It is much easier to use and setup, especially since there is no need to use Desktop mode. See the Getting Started guide for more details.

Installation

The installation instructions on the EmuDeck website do not work on ChimeraOS.

To install EmuDeck on ChimeraOS:

  1. Switch to Desktop Mode.
  2. Open a terminal window using the Console application.
  3. Paste the following into the Console (this must be done locally, not over SSH) window and hit enter: curl -L https://raw.githubusercontent.com/dragoonDorise/EmuDeck/main/install.sh | bash
  4. Follow the instructions in the EmuDeck application/installer

NOTE: Launching Steam ROM Manager from the Desktop menu does not work, launch Steam ROM Manager from the EmuDeck application as a workaround.

EmulationStation-DE and RetroArch

EmuDeck downloads EmulationStation-DE (AppImage) and RetroArch (Flatpak). In order to use EmuDeck's pre-configured RetroArch with its bundled EmulationStation-DE, you will need to create a custom es_find_rules.xml and place it in /home/gamer/.emulationstation/custom_systems.

To create a custom es_find_rules.xml:

  1. Create a es_find_rules.xml file
  2. Open it in a text editor of your choice
  3. Paste the below contents into the file
<ruleList>
    <emulator name="RETROARCH">
        <rule type="systempath">
            <entry>org.libretro.RetroArch</entry>
            <entry>retroarch</entry>
        </rule>
    </emulator>
</ruleList>
  1. Save and exit out of the file
  2. Place the es_find_rules.xml file in the /home/gamer/.emulationstation/custom_systems folder

RetroArch Controls

Note: This section is specifically referring to the RetroArch Flatpak installed by EmuDeck.

If input is not working in RetroArch, you will need to change the Input driver to SDL.

To change the driver:

  1. Open RetroArch (the Flatpak installed by EmuDeck)
    • To open RetroArch: Add RetroArch to Steam through the Emulators parser in Steam ROM Manager. Afterwards, you can open RetroArch directly in Game Mode
  2. Click the Settings menu
  3. Click Drivers
  4. Select Input
  5. Select sdl2
  6. Back out of the Drivers menu and select the Main Menu
  7. Click Configuration File
  8. Click Save Current Configuration and exit out of RetroArch
  9. Your RetroArch controls will now work in Game Mode

RClone

Saves can easily be backed up or synced using rclone, a multi-protocol sync tool that can be extracted to /home/gamer so it persists between upgrades.

Installation and Configuration

After downloading from https://rclone.org/downloads/ you'll want to extract to your home directory (suggested to use /home/gamer/rclone). After downloading and unzipping, your first step will be to configure a sync target by using the following command:

/home/gamer/rclone config

Rclone supports many different targets, including Gdrive, OneDrive, S3, FTP, WebDAV (including Nexcloud and Owncloud) and many others, so it's up to you what target you sync with. It's recommended to do this from a desktop session, since some choices require the use of a browser to fully authorize rclone. Even though it's text based, it takes you through each question and offers a logical default.

Saving and Syncing Saves

Saves are located in /home/gamer/.local/chimera/content/saves. Once a target is configured it's time to test and do an initial sync. Rclone has full documentation but for this task we only need a few basic commands:

/home/gamer/rclone/rclone copy /home/gamer/.local/chimera/content/saves mytarget:/saves

  • This will copy everything from the source to the target.
  • Good for an initial setup or a periodic backup.
  • Swap the source and destination to do a restore from the target.

/home/gamer/rclone/rclone sync /home/gamer/.local/chimera/content/saves mytarget:/saves

  • This will make the target look like the source, copying missing files to the target as well as deleting files from the target that aren't on the source.
  • Also good for a periodic backup provided you're OK with things that are removed from the source to be automatically removed from the target.
  • This ONLY changes the target.

/home/gamer/rclone/rclone bisync /home/gamer/.local/chimera/content/saves mytarget:/saves

  • This will do a bidirectional sync based on file checksum, date, and size (depending on which is available on the target), keeping the most recently changed copy.
  • A first run needs to be done manually with the --resync option
  • Good for keeping multiple devices in sync with each other. Conflits will be saved with a .conflict extension and will need to be resolved manually.
  • Because FTP is supported on ChimeraOS, and rclone supports custom FTP ports, a second ChimeraOS device can be the target and a direct sync between two ChimeraOS devices can be done.

It's helpful to set up a periodic schedule for these tasks rather than running them manually. Since cron is not part of the default ChimeraOS setup, that means using systemd timers, which are a little more complex and require two files, a service, and a timer. Both would be located in /home/gamer/.config/systemd/user/ and can be named whatever you want as long as they match (rclone-sync is used as an example below). You can use either a direct rclone command line or create a script with your rclone command(s) or in it. If you're doing multiple sync commands with multiple directories it's strongly recommended to use the script option, so you only have to work on your commands in one place.

rclone-sync.service:

[Unit]
Description=RClone Sync

[Service]
Type=simple
ExecStart=<your rclone commandline>

rclone-sync.timer:

[Unit]
Description=RClone Sync Timer

[Timer]
Unit=rclone-sync.service
OnBootSec=15m
OnUnitInactiveSec=15m
OnActiveSec=1s

[Install]
WantedBy=timers.target

The scheduling is completely flexible, and can be done based on calendar times (hourly/daily/weekly/etc) or activity times. The example shown above will run the timer on boot, 15 minutes after boot, and then every 15 minutes after it completes each time.

After creating these files, run this command to read in your new service/timer definitions:

systemctl daemon-reload

Then, to enable the timer on boot:

systemctl enable rclone.timer

Add --now to also start it immediately. You can check status and manually start/stop it just like any other systemd service. Likewise, if you want to run the task manually you can just start the service unit.

If performing an automatic periodic sync it is advisable to create a second task to do a sync as part of a shutdown (this is also good for setting up a backup-on-shutdown task), in order to catch and upload any changes that might have been missed in any interval you set.This is seperate from the timer above, and runs independently, only at shutdown, before the network shuts down.

rclone-shutdown.service

[Unit]
Description=RClone sync on shutdown
Before: shutdown.target network.target

[Service]
Type=oneshot
ExecStart=<your rclone commandline>

[Install]
WantedBy=shutdown.target

As before, run systemctl daemon-reload to read in the new unit file, and then systemctl enable rclone.shutdown-service to enable. While this may not be necessary if your system is on all the time, it's especially useful if you shut down when done playing, to make sure you get a backup or a sync in before that shutdown.

Security and support notes

It is strongly recommended to not sync ROM collections with the cloud or any other public facing server. Even though your ROM collection might be 100% legally dumped by you, anything seen as offering it to others might be seen as piracy and piracy is not encouraged or endorsed by this project. Syncing any other data, including Epic and GOG saves, Flatpak saves, configs, data, etc, while it is entirely possible to do, is beyond the scope of this document and is up to you to try on your own.

Dual booting Windows and ChimeraOS on the same Disk

Warning: Dual booting is not officially supported by ChimeraOS, however it is possible. This is a general outline of how to complete this. The stability of this method has not been evaluated by ChimeraOS developers.

Some considerations first:

1. This guide assumes you already have a fully functional installation of Windows 10 or later on the target disk, complete with a properly configured EFI partition.

2. This guide was made with the ROG Ally as a target device. For others you may be able to simplify the process.

  1. Enter the BIOS and disable Secure Boot

Some users have encountered issues with this step. For example, on the ROG Ally, ASUS sometimes resets the value. To successfully disable it, I disabled Secure Boot, booted into Windows, unlocked the HD with a Bitlocker key obtained from the Microsoft website, and on the next boot, Secure Boot was successfully disabled.

  1. Disable Bitlocker (if you have it disabled, skip this step)

In Windows settings, search for 'Bitlocker' or 'Encryption' and disable disk encryption. This process can take approximately one hour as it decrypts each file on the disk.

  1. Prepare to Install ChimeraOS from a USB Stick

You can use Balena Etcher for this step.

  1. Boot from the ChimeraOS USB Stick via BIOS

You should have another disk connected to the hub, either another USB drive or a micro SD card. This is because the system will not allow you to install ChimeraOS on the same disk as Windows without completely erasing it. Hence, we first install it onto an intermediate disk.

  1. Shrink the Data Partition in Windows

There are multiple ways to do this; choose the method that works best for you. I used the Device Manager that comes bundled with Windows.

  1. Migrate frzr_root partition to the internal drive

After installing ChimeraOS, migrate the big partition (frzr_root) to the internal NVMe drive using the space you freed in step 5. The duration of this process will be proportional to the size of the partition being migrated. For that step you can use a tool called "Macrium Reflect" that has a free trial.

  1. Patch the EFI Folder

Manually merge the EFI partition created by the ChimeraOS installer with the one on the internal NVMe. If you installed rEFInd previously, there's no need to replace '/EFI/BOOT/BOOTX64.efi', as we will use the Systemd one to boot ChimeraOS.

  1. Create a Boot Option in BIOS for ChimeraOS

In BIOS, go to advanced mode and to Bios tab, create a manual boot entry pointing to '/EFI/systemd/systemd-bootx64.efi' and name it 'ChimeraOS'. You can use this to boot directly.

  1. Partition Labels Required by ChimeraOS

ChimeraOS expects to find two partitions by label:

  • frzr_root: This is where your system and home directories are located. If you cloned using the software mentioned above, the label will be automatically applied. If not apply it using e2label /dev/nvme0n1pX frzr_root (replace X with the right partition)
  • frzr_efi: This is the boot partition. You should rename it using fatlabel /dev/nvme0n1p1 frzr_efi.
  1. Dual Boot Windows and ChimeraOS

At this point, you should be able to dual boot Windows and ChimeraOS and also apply OTA updates from ChimeraOS without affecting Windows. You can change the boot order in BIOS to choose the default system.

  1. Bonus Step: Install rEFInd to Manage Dual Boot

Although it might seem redundant now (on the Ally, more information bellow), installing rEFInd could be very useful in the near future. Here are the steps:

  • Install rEFInd on the internal NVMe drive by following the instructions on the rEFInd page.

  • Configure rEFInd. There are many documents available to guide you, and the sample configuration file provided is comprehensive. Perhaps someone can provide examples at a later stage.

  • IMPORTANT: On the Ally, currently, the D-pad and touchscreen will only work in rEFInd if you boot manually from BIOS. We are hoping for a solution from ASUS to address this issue.

Enabling Modern Sleep on 7000 Series AMD Hardware.

The 7000 series AMD APU's removed S3 sleep. Unfortunately, many handheld manufacturers don't properly set up the PBS firmware to take advantage of S0i2/S0i3 Modern sleep properly. However, this can be manually enabled.

⚠️ Warning

The following tool has been known to brick devices even by reading values in the BIOS. There is a good chance that setting something incorrectly in the BIOS with this tool will brick your device and void your warranty. This article is posted for informational purposes only and ChimeraOS makes no recommendation to utilize this information and takes no responsibility for any harm caused by following these steps. By following this guide you acknowledge that you are solely responsible for the outcome.

Tested devices

This technique has successfully enabled modern sleep on the following devices:

  • AYANEO GEEK 1S
  • AYANEO 2S
  • AYANEO AIR 1S
  • AYANEO KUN
  • AYANEO FLIP KB

Enable Modern Sleep

The first step is to create a UEFI compatible EFI bootloader on a USB drive.

  1. If you're on Arch you can get an EFI shell by installing edk2-shell which will install to /usr/share/edk2-shell/x64/Shell_Full.bin. This can be sourced other places as well if you don't have arch using a simple google search. Place the EFI shell bin file in a blank FAT32 formatted USB at /EFI/BOOT/BOOTx64.EFI
  2. Download Smokeless UMAF at this link, Then extract UMAF_Beta.zip in the same USB into a folder called UMAF.
  3. reboot into the BIOS and select to boot from the USB which will give you a DOS-like shell, enter fs1: to change to the USB drive directory.
  4. type UMAF\UiApp.efi and press enter to open the UMAF EFI BIOS. This will look similarly to your default BIOS.
  5. Navigate to the Front Page tab and select Device Manager then AMD PBS then Power Saving Configurations
  6. Under S3/Modern Standby Support change the entry to Modern Standby (or Modern Standby Enable on some devices)
  7. Under Modern Standby Type select Modern Standby + S0i2 + S0i3
  8. Save changes and exit. This will drop you back to the EFI shell. Type exit and you will drop to your default bios. Save changes and exit again to restart.

note: The first restart after this change may take longer than usual.

Add a custom footer
Add a custom sidebar
Clone this wiki locally