Using ByteKeys

First start

Open ByteKeys from your applications menu, or press your laptop's launch key. It identifies your laptop, picks the right drivers and creates profiles and automations to start from.

Lighting, fans and battery settings need root, so a small service, bytekeysd, does the hardware work while the control center runs as you:

• .deb: the service comes with the package and starts on installation.
• AppImage: it starts in portable mode. Click Install service on the Settings page or the banner; it asks for your password once and installs the service to /opt/bytekeys.
• From source: sudo make install installs to /usr/local and starts the service.

In portable mode, without the service, the control center and the command line run the same engine themselves with whatever your user may access. Brightness still works for the active desktop user; colors, fan control and background automations need the service. Check it with bytekeys service status. When the control center finds an older service than itself, it offers to update it.

The control center

Six pages in the sidebar, in a dark or light look:

• Home: Temperatures, fan speeds and CPU load, the performance mode, quick keyboard controls (power, brightness, mode, color) and the battery with its charge limit.
• Lighting: Live keyboard preview, every hardware and software effect with its settings, brightness, a color wheel for the whole keyboard or selected zones and keys, and device options such as firmware timeouts or boot and sleep lighting.
• Performance: Performance modes, a draggable fan curve per fan and mode with presets, live fan speeds and temperatures, full fan speed and battery care.
• Automation: Automations, applied top to bottom; a manual change wins until the automation stops applying. One-click ideas to start from.
• Profiles: Saved looks for all your keyboards.
• Settings: This laptop, keyboards, the launch key, the background service, preferences and a diagnostic report.

A tray icon gives you quick changes without opening the window.

Performance and fans

Performance modes are the firmware's own: Silent, Balanced and Performance on ASUS, and whatever your laptop offers through its ACPI platform profile elsewhere. ByteKeys switches them through power-profiles-daemon when it runs, so your desktop's power menu stays in sync, and notices changes made with the Fn keys or the desktop.

Fan curves work on ASUS laptops with firmware fan curves, most TUF and ROG since 2021. Drag the eight points of each fan's curve on the Performance page, start from a preset, or go back to the factory curve. Each performance mode keeps its own curves, and ByteKeys switches them with the mode, including from the Fn keys. Every curve is checked before it reaches the firmware: temperatures rise, speeds never drop, at least 50% from 80 °C and at least 70% at the last point.

Full fan speed is a switch on ASUS laptops with SPEC 8.3 fans. Your curves come back when you turn it off.

ByteKeys never drives fan speeds itself: the firmware runs the curves, so a crash or a stopped service can never leave a fan off. The kernel forgets custom curves on every mode change, at boot and after sleep, so the service puts them back and checks every second that they are still active.

$ bytekeys perf                 # current mode and the modes available$ bytekeys perf quiet           # switch mode$ bytekeys fans                 # temperatures, fan speeds and curves$ bytekeys fans boost on        # full fan speed (off to stop)$ bytekeys fans firmware 1      # CPU fan back to the firmware curve

Battery charge limit

A laptop that lives on its charger lasts longer when it stops charging early. Pick 60, 80 or 100% on the Home or Performance page (80 or 100% on LG). It works on laptops with a charge threshold, such as ASUS, ThinkPad, Dell, Huawei, LG, Samsung, MSI, System76, Toshiba and Fujitsu, and on Lenovo IdeaPad and Legion conservation mode. Some laptops reset the limit at boot; the service sets it again at start and after resume.

$ bytekeys charge-limit       # show the limit$ bytekeys charge-limit 80    # stop charging at 80 %

Launch key

The key that opens Armoury Crate, NitroSense, PredatorSense, OMEN Gaming Hub, MSI Center or MyASUS on Windows opens ByteKeys. It knows the keys of the laptops listed on the hardware page; Settings → Launch key → Detect key learns any other special key. With the service running, the key brings ByteKeys to the front from anywhere.

On GNOME-based desktops (Ubuntu, Pop!_OS, Zorin and others) and KDE Plasma, ByteKeys also adds a desktop shortcut, so the key starts ByteKeys when it is closed; on KDE it takes effect at the next login. On other desktops, add a shortcut that runs bytekeys-gui. The hardware page lists the keys ByteKeys knows.

Lighting and effects

One-click modes: Static, Breathing, Color cycle, Wave, Strobe, each with an animated preview. When your keyboard has its own hardware mode for one of them, ByteKeys uses it. Software effects work on every keyboard, even plain white ones: Breathing, Blink, Color cycle, Wave, Gradient, Starlight, Reactive typing, Candle. Pick colors with the color wheel for the whole keyboard, or click and drag over keys in the preview for zones and single keys.

Automation

An automation is when this happens, do that. While its trigger holds, its action is layered on top of your own settings. Automations apply top to bottom, so later ones win. When you change a setting an automation is overriding, it steps aside until it stops applying. Thresholds have some slack, so a value hovering near a limit doesn't flicker.

Ready-made automations

They come with ByteKeys and stay off until you turn them on:

• Turn off when idle: after 2 minutes without input (idle-off)
• Dim on battery: to 40% (battery-dim)
• Night mode: the Night profile from 22:00 to 07:00 (night)
• Low battery warning: a red pulse below 15% (low-battery)
• Caps Lock indicator: RGB keyboards (capslock)
• Overheat warning: an orange pulse above 90 °C, RGB keyboards (hot-cpu)

Triggers and actions

When: Power source is on battery or plugged in; Battery is below a level; Time is between two times; No keyboard or mouse input for a while; Caps Lock is on; CPU is hotter than a temperature; CPU load is above a level; Room is darker than a light level.

Do: Turn the lights off; Set brightness; Set color; Play an effect; Switch to profile; Flash as a warning; Color by CPU temperature; Color by battery level; Color by CPU load.

From the command line they are called rules: bytekeys rules enable battery-dim, bytekeys rules export and bytekeys rules import FILE.

Profiles

A profile is a saved look for all your keyboards. Switch profiles from the control center, the tray, the command line (bytekeys profile apply Night) or an automation, such as Night mode.

Keyboard shortcuts

ByteKeys follows the laptop's own Fn keys. On laptops whose Fn keys don't reach the backlight, bind these commands to shortcuts in your desktop's keyboard settings:

$ bytekeys brightness up$ bytekeys brightness down$ bytekeys toggle

Command line

bytekeys talks to the service, or runs portable when there is none. Add --json for machine-readable output, -d DEVICE to target one keyboard, and --local to skip the service. From the AppImage, run ./ByteKeys-*.AppImage cli COMMAND.

$ bytekeys color "#ff8800"              # whole keyboard orange$ bytekeys color red green blue white   # one color per zone$ bytekeys mode cycle                   # cycle through all colors$ bytekeys flash --color red --count 3  # e.g. from a notification script

Settings

Show them with bytekeys settings and change one with bytekeys settings key=value:

• restore_on_boot (default true): Put your lighting back at boot.
• save_to_firmware (default false): Also save a settled look to keyboard memory, on keyboards that support it.
• fps (default 30): Frame rate for software effects.
• launch_key (default 0): The evdev code of the key that opens ByteKeys; 0 is off. Set it from Settings → Launch key.
• openrgb (default true): Look for an OpenRGB SDK server.
• openrgb_host (default 127.0.0.1): Where the OpenRGB SDK server runs.
• openrgb_port (default 6742): Its port.
• openrgb_all_devices (default false): Use every OpenRGB device, not only keyboards.

OpenRGB

For keyboards ByteKeys has no driver for, such as Razer, Gigabyte and AORUS, MSI per-key or Legion per-key, run OpenRGB with its SDK server enabled. ByteKeys connects to it on 127.0.0.1:6742 and controls whatever OpenRGB supports.

$ openrgb --server

Troubleshooting

My keyboard isn't detected

The Settings page shows what ByteKeys found and hints, such as a kernel module to install. Use Settings → Copy report, or run bytekeys report, and open a Device support issue with it. The hardware page lists what works today.

Colors, fans or automations don't change anything

You are probably in portable mode. Install the service (see First start) and check it with bytekeys service status.

My fan curves keep resetting

Another program is probably rewriting them, for example asusd running alongside ByteKeys. ByteKeys backs off and logs a warning when that happens; use one of the two for fan curves.

ASUS TUF lights stay dark or ignore colors

Kernels 6.1 to 6.4 and 6.10 had bugs in asus-wmi's keyboard lighting. Use kernel 6.5 or later, but not 6.10.0.

My keyboard is marked Experimental

Its driver follows a documented protocol but hasn't been confirmed on that hardware yet. If it works, or doesn't, a report helps everyone with the same laptop.

Security and privacy

• Anyone may read the service's state, but only root, members of the bytekeys group and the user at the active local session may change it. Every request is checked.
• Every value is validated, and device paths come only from the service's own discovery.
• Input devices are read only for activity timestamps and to compare presses with the one configured launch key. Key codes are never stored or logged, and detecting a launch key accepts only special keys, never letters, digits or modifiers.
• Fan curves are validated, and only firmware-run curves are used, so ByteKeys can never leave the fans stopped.
• The systemd unit runs the service sandboxed.
• ByteKeys makes no network connections of its own; the only one is to an OpenRGB SDK server, on your own machine unless you point it elsewhere.

Found a vulnerability? Report it privately, not in a public issue, as the security policy explains.