README.md

   1 # elagto-key-light-linux
   2
   3 Small bash script to manage elgato key light and key light air.
   4
   5 The script will let you to manage one, many or all lights depending on what you set as target.
   6
   7 Allows discovery of devices, information collection directly from the lights, changing temperature, changing brightness and turning the lights on and off.
   8
   9 Intended for easy use via CLI, keyboard shortcuts and by StreamDeck, Cinnamon applets etc.
  10
  11 If you are using a StreamDeck you can target this script as a command for the button press.
  12
  13 ## Installation
  14
  15 No installation or configuration required. Download, copy paste or git clone the repo to your local machine and run the script.
  16
  17 ### Dependencies
  18
  19 The script requires avahi-browse, notify-send, jq and curl to be installed.
  20
  21 ```bash
  22 sudo apt-get install avahi-utils curl notify-send jq
  23 ```
  24
  25 ## Usage
  26
  27 Please see the docs sections to get examples and learn more about:
  28
  29 * [output formats - Have it your way](docs/output-formats.md)
  30 * [-t/--target filters - The power of jq filtering](docs/target-filters.md)
  31
  32 ```bash
  33 Usage: keylights.sh [-h] [-f <value>] [-l <value>] [-p] [-s] [-t <value>][-v] [--<option>] [--<option> <value>] <action>
  34
  35 Elgato Lights controller. Works for Key Light and Key Light Air.
  36
  37 Available actions:
  38     list        List available lights
  39     status      Get state of lights
  40     on          Turn all lights on
  41     off         Turn all lights off
  42     temperature Set temperature level (260-470)
  43     brightness  Set brightness level (0-100)
  44     increase    Increases brightness by 10
  45     decrease    Decreases brightness by 10
  46
  47 Available formats:
  48     json        Renders output as JSON (default)
  49     simple      Renders output as JSON array of single level objects with subarrays as .(dot) notation JSON
  50     flat        Renders output as fully flattened single level JSON with .(dot) notation JSON
  51     html        Renders output as basic html table
  52     csv         Renders output as csv
  53     table       Renders output as a printed table
  54     pair        Renders output as flattened key=value pairs
  55
  56
  57 Available options:
  58
  59 -h, --help               Print this help and exit
  60 -f, --format             Set output format
  61 -l, --limit <list>       Limit top level output fields to the specified comma separated list
  62 -p, --pretty             Pretty print console output
  63 -s, --silent             Supress notifications
  64 -t, --target <filter>    Only perform action on devices where value matches filter
  65 -v, --verbose            Print script debug info
  66 ```
  67
  68 ## Example use cases
  69
  70 I have five lights in the room namned: Front Left, Front Right, front center, Rear Right, rear left.
  71
  72 I want to turn all lights on with my StreamDeck by setting a command to:
  73
  74 ```bash
  75 ./keylights.sh on
  76 ```
  77
  78 I want to see the displayName, productName, serialNumber and firmwareVersion of all the lights on the right side of the room in a table:
  79
  80 ```bash
  81 ./keylights.sh --target '.displayName | contains("Right")' --limit "displayName, productName, serialNumber, firmwareVersion"  --format table --pretty list
  82 ```
  83
  84 I want to let my StreamDeck button turn off all lights which contains the name "front" (not case sensitive due to ascii_downcase), i add the following to be a command on button press:
  85
  86 ```bash
  87 ./keylights.sh --target '.displayName | ascii_downcase | contains("front")' off
  88 ```
  89
  90 I want to let my StreamDeck button turn off all lights which contains the name "Left" (case sensitive), I add the following to be a command on button press:
  91
  92 ```bash
  93 ./keylights.sh --target '.displayName | contains("Left")' off
  94 ```