-
Notifications
You must be signed in to change notification settings - Fork 116
General Configuration
ChimeraOS's design philosophy is to cast a wide net when it comes to compatibility of hardware. The ability to install on as many configurations as possible sometimes presents the opportunity for conflicts with necessary quirks or workarounds for some devices. As such, these are not normally enabled by default but if well understood they can be included in the image in a disabled state or documented with steps to reproduce. This page attempts to document general quirks and how to enable them.
Multiple sessions come pre-installed in ChimeraOS. A session is the selected user interface that you want to enable at boot time.
Provides the Steam Big Picture UI with an additional OpenGamepadUI overlay. Primarily for TDP control, this is a transitional mode while we work on getting OpenGamepadUI feature complete. For many handhelds a button has been mapped on the built in controller to open the overlay. If using a controller the button combination guide + b will open the overlay.
Provides a full replacement UI. It is intended as a multi-library launcher ecosystem with built in plugin support. Currently only the Steam plugin is available, but GOG and EGS are in development with plans for emulator support as well. This session also allows for updates to the client without the need for full OS releases.
The default vanilla Steam user session.
Switch to desktop mode if for some reason "switch to desktop mode" is not working, or you always want to boot directly to the desktop
Running the chimera-session command with no arguments will display the full list of sessions. The session with a * preceding it is the currently selected one
[gamer@lego ~]$ chimera-session
desktop
desktop-xorg
* steam
steam-plus
opengamepadui
Note: If no * is indicated, no session override has been done and you are using the default
steamsession
To select a session, run chimera-session <session-name> and the session will be loaded, e.g. chimera-session steam-plus
You may want to change which channel you are using for updates if you want to test new features or revert to an older version.
There are three main update channels available:
- stable | Current stable release, fully tested and bugfixed for stability and regressions
- testing | Release candidate builds undergoing thorough testing and bug fixing. Recommended for users who wish to contribute to the continued development of ChimeraOS.
- unstable | Untested builds that have not been vetted for regressions or stability. This channel is only recommended for advanced users and developers. Do not submit help requests on our Discord if using this channel
Additionally, if a stable release misses a major regression of a feature you need, each tagged release is available. These can only be applied using the CLI method specified below
- Go to Settings-> System and turn on "Enable Developer Mode"
- Go to Settings-> Developer and turn on "Show Advanced Update Channels"
- Go to Settings-> System and set "System Update Channel" to the desired channel
- Apply the update and then restart
From a terminal, run sudo frzr-deploy chimeraos/chimeraos:<channel> where channel is one of the above options, or a tagged version. E.g. sudo frzr-deploy chimera-session chimeraos/chimeraos:44-1
If forking your own build of ChimeraOS, you can switch to your own update channel by substituting the first two entries of the command with your github name and project name, e.g. sudo frzr-deploy imadev/myfork:testing
Adding additional steam libraries can be done through the Chimera Web UI, through the Steam UI, or via the CLI.
Only SD cards can be added as additional libraries using the Steam UI.
- Press
Guideon your controller to bring up the left menu. - Select
Settings - Select
System - Scroll to
Format SD Cardand selectFormat
- Select the hamburger menu in the top left
- Select
System - Select
Configure Storage Devices - Locate the drive and select
Format
- This will take a few minutes to complete, be patient until the page refreshes automatically.
- System volumes and devices configured in /etc/fstab are not available to the configuration utility.
See the steam-removable-media wiki for instructions on using the CLI.
Some devices have bugs in their ACPI tables or display firmware that can cause issues with various devices. The device-quirks scripts are able to install overrides that resolve these issues. The ChimeraOS team intentionally disables DSDT and EDID overrides by default. This decision is made to ensure that users have full control over their firmware settings and can make an informed decision about enabling overrides. Despite the community's extensive testing and belief in the safety of the override process, it is important to note that the ChimeraOS team intentionally leaves it up to the user to decide whether to take the "risk" of enabling DSDT overrides.
There are two ways to enable firmware overrides:
- Select the "Advanced Install" option when doing a fresh install or repair install. This will enable firmware overrides until disabled manually
- Edit
/etc/device-quirks/device-quirks.confand changeexport USE_FIRMWARE_OVERRIDES=0toexport USE_FIRMWARE_OVERRIDES=1
To apply firmware overrides, as well as other configuration tweaks for your device, simply run frzr-tweaks with sudo to run the script to identify your device and apply changes.
For DSDT overrides, your system's checksum will be compared against the database of "fixed" DSDT's. If your checksum matches, the DSDT override will be installed and metadata from your BIOS is recorded. During upgrades, if the metadata information matches your current BIOS, the previously used DSDT can be loaded. Upgrading your BIOS will cause this check to fail and after the next boot your system will load without an override. If your new BIOS is supported by a quirk it will be applied by running frzr-tweaks again manually. If it is not supported but still requires an override, please open an issue on the device quirks GitHub page.
You can set environment variables by creating any file with a .conf extension in the directory ~/.config/environment.d/.
Create this folder if it does not already exist.
You can customize the ChimeraOS splash screen logo by placing a PNG file at this location:
~/.config/chimera/splash.png
For best results, the image dimensions should be roughly 800 x 900.
You can also hide the splash screen by setting the environment variable HIDE_CHIMERA_SPLASH to any value.
Note that this does not disable the operations that are performed at startup, it simply hides the logo and information display.
⚠️ WarningTDP control adjustment can have negative affects if set to levels that exceed the power or thermal capacity of your device. Not all device manufacturers have fully functional or entirely reliable thermal cutouts. Excessive settings or faulty manufacturing can have adverse affects on the longevity of your hardware and are used at you own risk
For handheld devices, it can be useful to adjust the amount of power used by the system to help preserve the battery or improve performance over initial settings. The TDP controls built into the Steam client UI are hard coded by Valve to a limit of 15W. It uses the same power limit path as dedicated AMD GPU's and thus cannot be enabled in ChimeraOS as it would limit the power of all AMD dedicated GPU's to 15w as well.
There are currently five methods of TDP Control in ChimeraOS:
- The Chimera App in v42+ has support for controlling the TDP of the AYANEO 2. This is an operational test to see if this way of control is a good path forward.
- The OpenGamepadUI Sessions can be used with AMD APU's and some Intel iGPU's.
- The Decky-loader plugin PowerControl can be installed. There are some issues with decky-loader and its plugins breaking due to updates to the UI from Valve.
- The Decky-loader plugin SimpleDeckyTDP can be installed.
- Simple Ryzen TDP can be installed and added as a steam library item.
- Instructions to come
OpengamepadUI supports most AMD APU's and some Intel iGPU's. It is available in v42+ of ChimeraOS. If available for your hardware it can control the following settings:
- Toggle CPU Boosting
- Toggle SMT
- Set max number of usable cores
- Adjust Average TDP
- Adjust peak TDP
- Adjust Tjunction temperature limit
- Adjust GPU Min/Max Clock
- Adjust power profiles
The software will automatically detect and enable any detected capabilities. See session switching above to use one of the two methods OpenGamepadUI provides
⚠️ Warning PowerControl only works on AMD APU's. It will not detect the limits of your hardware so use caution as unsafe TDP levels can be set. Due to DeckyLoaders method of patching the SteamDeck UI it can break frequently and require the loader and the plugins to require updates. As a result, ChimeraOS does not recommend using these tools.
The following options are available for adjustment in PowerControl:
- Toggle CPU boost
- Toggle SMT
- Adjust Core Count
- Adjsut TDP
- Adjust GPU frequency
Use the fast install by running the following command in console:
curl -L https://github.com/SteamDeckHomebrew/decky-installer/releases/latest/download/install_release.sh | sh
type your password when prompted, default password is gamer.
Full instructions at the Decky-Loader installation guide on their Github.
Navigate to https://github.com/mengmeet/PowerControl/releases and identify the latest release.
Download the latest release, then extract the file.
Then move the entire PowerControl folder to /home/gamer/homebrew/plugins/. Note that you might need to move it with sudo.
After adding it to the correct folder, reboot your device.
- Once back in the Steam Deck UI open the Quick Access Menu, either by pressing
guide + Aor if it is a device managed by HandyGCCS there is likely a dedicated QAM button. - An ElectricPlug Icon will be present at the bottom for DeckyLoader, highlight it and press
A - PowerControl will now be present in the DeckyLoader list.
Note that ChimeraOS should already ship with ryzenadj pre-installed, which is one of the requirements for SimpleDeckyTDP.
- If not already installed, install decky loader:
curl -L https://github.com/SteamDeckHomebrew/decky-installer/releases/latest/download/install_release.sh | sh - Install Simple Decky TDP:
curl -L https://github.com/aarron-lee/SimpleDeckyTDP/raw/main/install.sh | sh - Reboot, you should see SimpleDeckyTDP in your Steam QAM under the new tab for Decky plugins
For full install instructions, see here
Follow the Installation Guide on the Simple Ryzen TDP Github.
Given the verity of mobile devices they can all handle gamescope differently. While we make every effort to ensure compatibility across as many devices as possible some devices may require some additional tweaks. A common tweak that is required is rotating the screen either left or right when loading into gamescope.
Gamescope is initiated when the OS loads, and when you click "Game Mode" from the desktop environment. It is a highly flexible system but can work differently on mobile devices. After preforming these steps, you will have a custom Gamescope launch command that should address screen rotation. In these steps you will be asked to create a custom XX-my.conf file where the XX denotes order it should be run. We will use 01 as the numeral in the fix below.
Note: The variable that handles rotation is --force-orientation right, your device may require this to be right, or left. The GPD Win 2 requires the value "right" for the Gamescope rotation to be correct.
- Boot the system normally
- In GamepadUI press the “menu” button in the bottom left of the screen
- In the menu click “Shutdown” >> “Switch to Desktop”
- At the Desktop click the icon with 9 squares >> Applications
- Open Console
- Use the following command:
echo “export GAMESCOPECMD="/usr/bin/gamescope -e --generate-drm-mode-fixed --xwayland-count 2 -O *,DSI-1, --default-touch-mode --hide-cursor-delay 3000 --fade-out-duration 200 --force-orientation right” > ~/.config/environment.d/01-my.conf”
- Verify the file was created, you can do so by running this command:
“cat ~/.config/environment.d/01-my.conf”
- Reboot your system.
Depending on the system you may need to modify the above command, we'll update the wiki with Gamescope variables.
Starting with chimeraOS v42 it is now possible to configure what GPU you want to be used for the gamescope-session making it really easy to to specify what GPU you want to be used for gamescope. This helps us do the following:
- Use an iGPU of any compatible CPU to do the compositing and use a dedicated GPU to run the games. (Extremely useful for Nvidia)
- Configure gamescope to prefer an eGPU whenever it's available at boot instead of the integrated graphics
When using this utility to use an iGPU you will need to plug into your motherboard and not the GPU itself or else you won't get an image on the screen.
To do this you will need the following:
- Have a motherboard that allows you to enable both the iGPU and dedicated GPU at the same time (usually called iGPU multi-montior support or something similar). In same cases using
autowill work just fine if the setting is available. - A keyboard to enter the TTY or type into a console in the desktop to use the
export-gpuutility.
To run the utility all you need to do is either open console from the activities menu on the desktop or use the TTY, see here for instructions on how to do that.
Type export-gpu and follow the simple instructions to create the configuration needed for gamescope-session and reboot the system.
Sometimes plugging into the motherboard is all you need to do to get things working, but you may find that session-switching does not work. This is the time where you need to use the export-gpu utility to make sure gamescope always uses the iGPU and not use the dedicated GPU by mistake.
This is useful for desktops AND laptops alike. If you have a Ryzen CPU with an iGPU and a RTX 4090 this is your way of using Nvidia with ChimeraOS with excellent performance and as trouble free as it can be! You can use an Intel CPU as well, and it will be fine, but AMD is the preferred option.