README.md

   1 - [elagto-key-light-linux](#elagto-key-light-linux)
   2   - [USAGE](#usage)
   3   - [Installation](#installation)
   4     - [Dependencies](#dependencies)
   5   - [JSON filters in -t/--target](#json-filters-in--t--target)
   6     - [Filter basics](#filter-basics)
   7     - [Example target filters](#example-target-filters)
   8
   9 # elagto-key-light-linux
  10
  11 Small bash script to manage elgato key light and key light air.
  12
  13 The script will let you to manage one, many or all lights depending on what you set as target.
  14
  15 Allows discovery of devices, information collection directly from the lights, changing temperature, changing brightness and turning the lights on and off.
  16
  17 Intended for easy use via CLI, keyboard shortcuts and by StreamDeck, Cinnamon applets etc.
  18
  19 If you are using a StreamDeck you can target this script as a command for the button press.
  20
  21 ## USAGE
  22
  23 ```bash
  24 Usage: keylights.sh [-h] [-f <value>] [-l] [-p] [-s] [-t <value>][-v] [--<option>] [--<option> <value>] <action>
  25
  26 Elgato Lights controller. Works for Key Light and Key Light Air.
  27
  28 Available actions:
  29     list        List available lights
  30     status      Get state of lights
  31     on          Turn all lights on
  32     off         Turn all lights off
  33     temperature Set temperature level (260-470)
  34     brightness  Set brightness level (0-100)
  35     increase    Increases brightness by 10
  36     decrease    Decreases brightness by 10
  37
  38 Available formats:
  39     json        Renders output as JSON (default)
  40     simple      Renders output as JSON array of single level objects with subarrays as .(dot) notation JSON
  41     flat        Renders output as fully flattened single level JSON with .(dot) notation JSON
  42     html        Renders output as basic html table
  43     csv         Renders output as csv
  44     table       Renders output as a printed table
  45     pair        Renders output as flattened key=value pairs
  46
  47
  48 Available options:
  49
  50 -h, --help      Print this help and exit
  51 -f  --format    Set output format
  52 -p, --pretty    Pretty print console output
  53 -s, --silent    Supress notifications
  54 -t, --target    Only perform action on devices where value matches filter
  55 -v, --verbose   Print script debug info
  56 ```
  57
  58 ## Installation
  59
  60 No installation or configuration required. Download, copy paste or git clone the repo to your local machine and run the script.
  61
  62 ### Dependencies
  63
  64 The script requires avahi-browse, notify-send, jq and curl to be installed.
  65
  66 ```bash
  67 sudo apt-get install avahi-utils curl notify-send jq
  68 ```
  69
  70 ## JSON filters in -t/--target
  71
  72 The target option is passing along filters to the json parser.
  73 Specified filters will be inserted into the jq select and therefore allows you to utilize the full feature set and power of jq on the json result.
  74
  75 The script transforms the captured base data to JSON, to allow use of jq filtering independently of what output format you want.
  76
  77 jq allows you to pipe results to further transform, compare and parse in many ways. The threshold of starting to use JQ can feel a bit high for novice shell users and we therefore give you some [basic information on jq filters](#filter-basics) and [examples](#example-target-filters).
  78
  79 ### Filter basics
  80
  81 The parameter data to pass in to the -t or --target option uses.(dot) notation of the JSON data.
  82
  83 **IMPORTANT! When specifying a filter you MUST do so within single quotes (') and use double quote (") around data values, as per jq standard. Not doing this will throw a jq parse error.**
  84
  85 The dot(.) notation to target a specific host based on its ipv4 address would be:
  86
  87 ```bash
  88     '.ipv4 == "192.168.0.132"'
  89 ```
  90
  91 or for a nested JSON object like the power on behaviour within the settings object:
  92
  93 ```bash
  94     '.settings.powerOnBehavior" == 1'
  95 ```
  96
  97 while .(dot) notation is used to target underlying objects, you can also search in nested arrays by piping them '|' and catching/expanding them with '[]' like this:
  98
  99 ```bash
 100 '.lights | .[].on == 0'
 101 ```
 102
 103 Example of JSON result (see examples directory for more/full output examples):
 104
 105 ```json
 106 [
 107     {
 108         "productName": "Elgato Key Light Air",
 109         "firmwareVersion": "1.0.3",
 110         "displayName": "Front  Right",
 111         "device": "Elgato Key Light Air 0C2C",
 112         "url": "http://192.168.0.132:9123",
 113         "ipv4": "192.168.0.132",
 114         ...
 115         <omitted>
 116         ...
 117         "numberOfLights": 1,
 118         "lights": [
 119             {
 120                 "on": 0,
 121                 "brightness": 31,
 122                 "temperature": 179
 123             }
 124         ]
 125         "settings": {
 126             "powerOnBehavior": 1,
 127             "powerOnBrightness": 20,
 128             "powerOnTemperature": 213,
 129             "switchOnDurationMs": 100,
 130             "switchOffDurationMs": 300,
 131             "colorChangeDurationMs": 100
 132         }
 133 ```
 134
 135 ### Example target filters
 136
 137 Here you will find a list of examples for some common use cases that can be adapted to your liking.
 138 [Filter basics](#filter-basics) provides you with the basic information about how filters are constructed.
 139
 140 Note! You can add the other formatting parameters as -p/--pretty -f/--format or specify any of the other action.
 141
 142 Perform action on all lights that exactly matches "Front Right" (case sensitive) in their names:
 143
 144 ```bash
 145 ./keylights.sh -t '.displayName == "Front Right")' <action>
 146 ```
 147
 148 Perform action on all lights that has "Left" (case sensitive) in their names:
 149
 150 ```bash
 151 ./keylights.sh -t '.displayName | contains("Left")' <action>
 152 ```
 153
 154 Perform action on all lights that has "front" in their names in a case insensitive manner:
 155
 156 ```bash
 157 ./keylights.sh -t '.displayName | ascii_downcase | contains("front")' <action>
 158 ```
 159
 160 Perform action on all lights that have a duration of 100 ms when switched on (notice the object expansion with .(dot)):
 161
 162 ```bash
 163 ./keylights.sh -t '.settings.switchOnDurationMs == 100)' <action>
 164 ```
 165
 166 Perform action on all lights that are currently switched on (notice the array expansion with | .[])):
 167
 168 ```bash
 169 ./keylights.sh -t '.lights | .[].on == 1' <action>
 170 ```