diff --git a/README.md b/README.md index 1708e6e..4dbbc6b 100644 --- a/README.md +++ b/README.md @@ -1 +1,185 @@ -# CoolerMaster-ck550-macos \ No newline at end of file +# ck550-macos + +CoolerMaster has never provided any MacOS SW or SDK for their CK550 keyboards. + +CK550-macos project tries to fix this situation and provides a couple of the MacOS applications for controlling the +majority of available keyboard LED effect. +Applications support only CK550 US-Layout keyboards. + +Both applications differ only in a user interface, one is CLI-based and the latter is GUI-based. Applications do not +overwrite any stored settings in a keyboard. Changes are temporary, so once the keyboard is unplugged, all changes made +by ck550-macos are lost. The same situation happens if you switch a keyboard to a different profile. +The reason for this behavior is to keep the internal keyboard flash write cycles untouched. + + +| Supported LED effects | +|------------------------| +| Static | +| Rainbow Wave | +| Crosshair | +| Reactive Fade | +| Custom | +| Stars | +| Color Cycle | +| Breathing | +| Ripple | +| Snowing | +| Reactive Punch | +| Heartbeat | +| Fireball | +| Circle Spectrum | +| Reactive Tornado | +| Water Ripple | +| Off | + +All effects are previewed on [the official CoolerMaster website][2]. + +---------------------------------------------- + +## Command Line App + +``` +➜ ./ck550-cli +-= CK550 MacOS Utility =- +Available commands: + + about About ck550-cli... + effect-breathing Set a breathing effect + effect-circle-spectrum Set a circle spectrum effect + effect-color-cycle Set a color-cycle effect + effect-crosshair Set a crosshair effect + effect-custom Set a custom color for individual keys + effect-fireball Set a fireball effect + effect-heartbeat Set a heartbeat effect + effect-off Set an off effect + effect-rainbow-wave Set a rainbow-wave effect + effect-reactive-fade Set a reactive-fade effect + effect-reactive-punch Set a reactive-punch effect + effect-reactive-tornado Set a reactive-tornado effect + effect-ripple Set a ripple effect + effect-snowing Set a snowing effect + effect-stars Set a stars effect + effect-static Set a static effect + effect-water-ripple Set a water ripple effect + help Display general or command-specific help + license ck550-cli license + license-components ck550-cli 3rd party components and their licensing + monitor Monitor HID devices continuously to see changes on an USB bus + version Display the current ck550-cli version +``` + +Every available command is heavily documented. + +``` +➜ ./ck550-cli help effect-single-key +-= CK550 MacOS Utility =- +Set a reactive-fade effect + +[--profile (integer)] + keyboard profile to use for a modification + +[--speed (speed)] + effect speed (one of 'highest', 'higher', 'middle', 'lower', or 'lowest'), by default 'middle' + +[--color (integer)] + color (format: --color "255, 255, 255"), by default the color is white + +[--background-color (integer)] + background color (format: --background-color "255, 255, 255"), by default the color is black + + +➜ ./ck550-cli effect-reactive-fade --color "255, 0, 0" +``` + +All effects could be configured from a command line except the *Custom* effect. +This is effect too complicated, which allows to configure any key located on keyboard. +You can use [this configuration file][1] as a template to change any colors for any keys. + +``` +➜ ./ck550-cli help effect-custom +-= CK550 MacOS Utility =- +Set a custom color for individual keys + +[--profile (integer)] + keyboard profile to use for a modification + +(string) + the configuration file describing individual key colors + + +➜ ./ck550-cli effect-custom ~/myFavouriteGameKeys.json +``` + +---------------------------------------------- + +## GUI App + +CK550-MacOS GUI application is a MacOS menu bar (aka status bar) application. + +![CK550 Main Menu](README/images/ck550-macos-main-menu.png?raw=true "") + +The main menu contains two switchable options. + +- *Adjust LEDs on a sleep and wake up* menu item in its *On state* controls if keyboard is instructed to use +a previously selected LED effect on system wake up or to turn off all LEDs when system sleeps. + +- *Set effect on a keyboard detection* menu item in its *On state* instructs a keyboard to use a previously selected +LED effect during a keyboard detection. + +*Effects* menu item displays a submenu containing all available effects for a selection. + +![CK550 Effect Menu](README/images/ck550-macos-effect-menu.png?raw=true "") + +All effects could be configured either by selecting a general *Preferences...* menu item, +or by selecting a configuration icon on the right side of a given effect. + +Changed preferences are saved immediately and are restored during the application startup. + +![CK550 Reactive Punch Preferences](README/images/ck550-macos-reactive-punch-effect-preferences.png?raw=true "") + +The CK550 *Custom effect* could export and import the effect configuration, which is handy to have an ability +to load predefined keys colors for various software or games. The exported configuration files are fully compatible +with the CK550-MacOS CLI application. + +![CK550 Custom Preferences](README/images/ck550-macos-custom-effect-preferences-color-popup.png?raw=true "") + +---------------------------------------------- + +## Installation + +CK550-MacOS Gui & CLI applications are distributed in two fashions, which is either a `Homebrew CASK`, or the self-updatable DMG. + +### Self-updatable DMG + +The self-updatable DMG is available in a [release section.][3]. Be aware that a CLI application is included in the GUI app bundle. You can run the `./ck550.app/Contents/MacOS/ck550-cli.app/Contents/MacOS/ck550-cli` or create a symbolic link to provide an easy access. + +### Homebrew CASK + +If you have't install the Homebrew yet, follow [their instructions.][4] + +Then, applications could be installed by following commands. + +``` +brew tap vookimedlo/homebrew-ck550 +brew cask install ck550-macos +``` + +If everything went well, you see a similar output and both GUI and CLI applications are ready to use. + +``` +➜ brew cask install ck550-macos +==> Satisfying dependencies +==> Downloading https://github.com/vookimedlo/homebrew-ck550/releases/download/v... +==> Verifying SHA-256 checksum for Cask 'ck550-macos'. +==> Installing Cask ck550-macos +==> Moving App 'ck550.app' to '/Applications/ck550.app'. +==> Linking Binary 'ck550-cli' to '/usr/local/bin/ck550-cli'. +🍺 ck550-macos was successfully installed! +``` + +---------------------------------------------- + +[1]: https://github.com/vookimedlo/ck550-macos/blob/master/config/customization.json +[2]: http://www.coolermaster.com/peripheral/keyboards/ck550/ +[3]: https://github.com/vookimedlo/ck550-macos/releases/latest +[4]: https://brew.sh/ diff --git a/README/images/ck550-macos-custom-effect-preferences-color-popup.png b/README/images/ck550-macos-custom-effect-preferences-color-popup.png new file mode 100644 index 0000000..9d6d951 Binary files /dev/null and b/README/images/ck550-macos-custom-effect-preferences-color-popup.png differ diff --git a/README/images/ck550-macos-custom-effect-preferences.png b/README/images/ck550-macos-custom-effect-preferences.png new file mode 100644 index 0000000..9ce1c50 Binary files /dev/null and b/README/images/ck550-macos-custom-effect-preferences.png differ diff --git a/README/images/ck550-macos-effect-menu.png b/README/images/ck550-macos-effect-menu.png new file mode 100644 index 0000000..7f5ca83 Binary files /dev/null and b/README/images/ck550-macos-effect-menu.png differ diff --git a/README/images/ck550-macos-main-menu-with-statusbar.png b/README/images/ck550-macos-main-menu-with-statusbar.png new file mode 100644 index 0000000..5f10300 Binary files /dev/null and b/README/images/ck550-macos-main-menu-with-statusbar.png differ diff --git a/README/images/ck550-macos-main-menu.png b/README/images/ck550-macos-main-menu.png new file mode 100644 index 0000000..7894bfc Binary files /dev/null and b/README/images/ck550-macos-main-menu.png differ diff --git a/README/images/ck550-macos-reactive-punch-effect-preferences.png b/README/images/ck550-macos-reactive-punch-effect-preferences.png new file mode 100644 index 0000000..2be1438 Binary files /dev/null and b/README/images/ck550-macos-reactive-punch-effect-preferences.png differ