Skip to content

Community Guides

Jump to bottom Edit New page
Aarron Lee edited this page Aug 30, 2024 · 18 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.

Firmware Update

Lenovo Legion Go

The Lenovo Legion Go is compatible with the fwupd tool. To use it follow the following steps:

Note: Ensure your device is plugged into AC power before beginning.

1.) Download the latest BIOS exe from https://pcsupport.lenovo.com/us/en/products/laptops-and-netbooks/legion-series/legion-go-8apu1/downloads/driver-list

2.) Extract the isflash.bin from the exe archive using file roller or some other archive tool.

3.) Run sudo fwupdtool install-blob isflash.bin

4.) Select System Firmware from the options menu.

5.) It will ask you to reboot, Select y. The system will reboot multiple times. Leave the AC plugged in and wait for it to return to the OS.

InputPlumber controller management via Decky

You can enable per-game controller modes with InputPlumber via the DeckyPlumber plugin: https://github.com/aarron-lee/DeckyPlumber

NOTE: This required DeckyLoader to have already been installed. Please follow the guide above to install it.

You can install it via the following:

curl -L https://github.com/aarron-lee/DeckyPlumber/raw/main/install.sh | sh

LED RGB Controls

You can customize the RGB of SOME of your handheld devices with HueSync.

NOTE: This required DeckyLoader to have already been installed. Please follow the guide above to install it.

To install HueSync, use the fast install by running the following command in console:

curl -L https://raw.githubusercontent.com/honjow/huesync/main/install.sh | sh

Reboot. You should see HueSync in your Steam QAM under the new tab for Decky plugins.

For more information, see here.

Fan Controls

SimpleDeckyTDP + PowerControl (fan controls only)

If you want to use SimpleDeckyTDP while still being able to keep the fan control of PowerControl, install the following PowerControl fork here.

Use the fast install by running the following command in console after you have already installed SimpleDeckyTDP:

curl -L https://github.com/aarron-lee/PowerControl/raw/main/install.sh | sh

Reboot. You should see both SimpleDeckyTDP and PowerControl in your Steam QAM under the new tab for Decky plugins.

They should be able to both run without conflict.

Setting Battery Charge Thresholds Using Command Lines

NOTE: This can be applied for both KDE and GNOME desktop, but I wrote this guide specifically because GNOME has no built-in battery control.

If you want to stop charging the battery at a certain level, or start charging the battery after it has decreased to a certain level, follow the below instruction:

In desktop mode, navigate to /sys/class directory.

There should be one or multiple folders in format of BAT# (where # is the battery number, starting with 0)

Supposing our battery to be named BAT0, the files we should write charge thresholds values would be:

/sys/class/power_supply/BAT0/charge_start_threshold and /sys/class/power_supply/BAT0/charge_stop_threshold

Confirm that both of those files existed inside the battery BAT0 directory.

Suppose we want the battery to start charging when the charge level drops under 80%, and stop when it reaches 90%. We would run the following commands

echo 80 | sudo tee /sys/class/power_supply/BAT0/charge_start_threshold

echo 90 | sudo tee /sys/class/power_supply/BAT0/charge_stop_threshold

Some notebooks come with more than one battery. Since the batteries are named progressively, a second one would be named “BAT1”. To set the same thresholds on all available batteries at once, we would shell filename expansion (“globbing”), and run:

echo 80 | sudo tee /sys/class/power_supply/BAT*/charge_start_threshold

echo 90 | sudo tee /sys/class/power_supply/BAT*/charge_stop_threshold
Add a custom footer
Add a custom sidebar
Clone this wiki locally