ApexCtl

Control SteelSeries Apex keyboards on GNU/Linux!

Rewrite of a utility with the same name, with some influence from Apex-Macros.
Works with the SteelSeries Apex, Apex RAW, 350 and 300, with attempted support of others.
This probably won't work with the newer SteelSeries Apex keyboards. There is no real method of adding support for them at this time. If you know how to figure out USB protocols or somebody who does, help would be GREATLY appreciated.

• Dependencies
• Build
• Installation
• Usage
• Advanced
• Bugs

Dependencies

• udev
• make
• pkgconf
• hidapi

Arch:

pacman -S --needed base-devel hidapi

Fedora (#2):

yum install hidapi-devel pkgconf

TODO: Add more distros
In addition to the distros above, ApexCtl has been reported to work in Ubuntu (#4)

Build

git clone https://github.com/AstroSnail/apexctl
cd apexctl
make

Options can be specified at the end of the make command. For example:

make ENABLE_DATA_PRINT=1 HIDAPI_IMPL=hidapi-hidraw

You can find the options and their defaults at the top of the Makefile.

Nix:

Nix can be used to build and package ApexCtl!

nix build

Note: only the flake is tested. If you're not using flakes and it doesn't work, please open an issue.

Installation

sudo make install

Usage

$ apexctl
Usage: apexctl <command> [arguments...]

Commands:
  probe   Probe for new commands.
  reboot  Reboot the keyboard.
  keys    Enable or disable extra keys.
  poll    Set polling frequency.
  bright  Set backlight brightness.
  save    [NEW&BUGGY] Save state changed since keyboard power-on.
  colors  Set colors and brightnesses per-zone.

Commands usage:
  probe  <numbers>            (up to 32 2-digit hex numbers)
  reboot                      (no arguments)
  keys   <on|off>             
  poll   <frequency>          (125, 250, 500, or 1000)
  bright <zone> <brightness>  (see below)
  save                        (no arguments)
  colors <colors>             (see below)

Brightness specification:
  The meaning of <zone> will depend on which keyboard you're using.
  For the Apex, zones 1 to 5 set south, east, north, west and logo zones.
  For the Apex RAW, zone 1 is the whole keyboard.

  <brightness> is a number from 1 to 8.
  1 will turn off the keyboard backlight for the specified zone.
  2 is minimum brightness, 8 is maximum.

Color specification:
  Up to 5 colors can be specified.
  For the Apex, they set south, east, north, west and logo zones in that order.
  This command is not functional in the Apex RAW.
  The formats are case-insensitive.

  Format   Example  Meaning
  RRGGBBA  ABCDEF4  Sets color to triplet #ABCDEF and brightness to 4
  RRGGBB   ABCDEF   Equivalent to ABCDEF8
  RGBA     ACE4     Equivalent to AACCEE4
  RGB      ACE      Equivalent to AACCEE8
  A        4        Equivalent to FFFFFF4
  0                 SPECIAL: Does not affect the zone

For the Apex, this command may be used to turn off the backlight in all zones:
  # apexctl colors 1 1 1 1 1
For the Apex RAW, you will instead need to use the bright command:
  # apexctl bright 1 1
After running it, you may use the save command immediately to keep it off the
next time the keyboard is powered on.

To help you configure your hotkeys, the default key mappings are as follows:

Key	Symbol
L1	XF86Launch5
L2	XF86Launch6
L3	XF86Launch7
L4	XF86Launch8
↖	XF86ScrollUp
↗	XF86ScrollDown
MX1	XF86AudioMedia
MX2	XF86Display
MX3	XF86KbdLightOnOff
MX4	XF86KbdBrightnessDown
MX5	XF86KbdBrightnessUp
MX6	XF86Reply
MX7	XF86MailForward
MX8	XF86Save
MX9	XF86Documents
MX10	XF86Battery
M1	XF86Launch1
M2	XF86Launch2
M3	XF86WWW
M4	XF86DOS
M5	XF86ScreenSaver
M6	XF86RotateWindows
M7	XF86TaskPane
M8	XF86Mail
M9	XF86Favorites
M10	XF86MyComputer
M11	XF86Back
M12	XF86Forward

If you you use Xorg and you don't like these mappings, you can change them up with the provided misc/Xmodmap file. Copy this file to ~/.Xmodmap (or append its contents if it already exists) and add xmodmap ~/.Xmodmap to your init file. (usually ~/.xinitrc) (TODO: Some display managers automatically load ~/.Xmodmap? Which ones?)

If you do this the key mappings will instead be as follows:

Key	Symbol
L1	XF86Launch1
L2	XF86Launch2
L3	XF86Launch3
L4	XF86Launch4
↖	XF86Back
↗	XF86Forward
MX1	F25
MX2	F26
MX3	F27
MX4	F28
MX5	F29
MX6	F30
MX7	F31
MX8	F32
MX9	F33
MX10	F34
M1	F13
M2	F14
M3	F15
M4	F16
M5	F17
M6	F18
M7	F19
M8	F20
M9	F21
M10	F22
M11	F23
M12	F24

You can modify misc/Xmodmap to your preference before you install it.

If you use Wayland and you don't like the default mappings, you'll have more luck with the Advanced configuration below.

Advanced

If you want more control over the mappings (or plain don't like xmodmap) there is a way using XKB, but it'll take some work, skill, and probably luck.

• sudo make install-advanced

• ln -s /etc/X11/xkb ~/.xkb

• If you use Xorg, add setxkbmap -I "$HOME/.xkb" -print -rules apex | xkbcomp -I"$HOME/.xkb" - "$DISPLAY" to an init file. (usually ~/.xinitrc)

• • You can modify the setxkbmap command to your liking. For example: setxkbmap -I "$HOME/.xkb" -print -rules apex us colemak compose:menu
• • If you want to use different options, you'll need to modify the files in xkb/rules/. They have instructions inside.
• • If you use another keyboard layout manager, it's up to you to figure out how to make it work.

• If you use Wayland, your compositor will need to implement libxkbcommon, and it's up to you to configure it. (TODO: Add examples)

Once you're done, the key mappings will now be like the second table above. If you wish to use different mappings, you can modify xkb/symbols/steelseries before you install it. You're encouraged to play around with XKB to find your preferred setup. How to further enhance XKB configuration and An Unreliable Guide to Xkb Configuration may help you become familiar XKB.

Be aware that Xorg appears to only support F-keys up to F35.

Bugs

#7: Extra keys are disabled after suspending
#11: Apex 3 Keyboard locks up when running apexctl
#12: Udev issues