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     flat        Renders output as flattened JSON with .(dot) notation JSON (default)
  41     html        Renders output as basic html table
  42     csv         Renders output as csv
  43     table       Renders output as a printed table
  44     pair        Renders output as flattened key=value pairs
  45
  46
  47 Available options:
  48
  49 -h, --help      Print this help and exit
  50 -f  --format    Set output format
  51 -p, --pretty    Pretty print console output
  52 -s, --silent    Supress notifications
  53 -t, --target    Only perform action on devices where value matches filter
  54 -v, --verbose   Print script debug info
  55 ```
  56
  57 ## Installation
  58
  59 No installation or configuration required. Download, copy paste or git clone the repo to your local machine and run the script.
  60
  61 ### Dependencies
  62
  63 The script requires avahi-browse, notify-send and curl to be installed.
  64
  65 ```bash
  66 sudo apt-get install avahi-utils curl notify-send
  67 ```
  68
  69 ## JSON filters in -t/--target
  70
  71 The target option is passing along filters to the json parser.
  72 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.
  73
  74 The script transforms the captured base data to JSON, to allow use of jq filtering independently of what output format you want.
  75
  76 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).
  77
  78 ### Filter basics
  79
  80 The parameter data to pass in to the -t or --target option uses.(dot) notation of the JSON data.
  81
  82 **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.**
  83
  84 The dot(.) notation to target a specific host based on its ipv4 address would be:
  85
  86 ```bash
  87     '.ipv4 == "192.168.0.132"'
  88 ```
  89
  90 of for a nested JSON object like the serial number within the info object:
  91
  92 ```bash
  93     '.serialNumber == "CW16K1A01748"'
  94 ```
  95
  96 Example of JSON result (see examples directory for more/full output examples):
  97
  98 ```json
  99 [
 100     {
 101         "productName": "Elgato Key Light Air",
 102         "firmwareVersion": "1.0.3",
 103         "displayName": "Front  Right",
 104         "device": "Elgato Key Light Air 0C2C",
 105         "url": "http://192.168.0.132:9123",
 106         "ipv4": "192.168.0.132",
 107         ...
 108         <omitted>
 109         ...
 110         "numberOfLights": 1,
 111         "lights": [
 112             {
 113                 "on": 0,
 114                 "brightness": 31,
 115                 "temperature": 179
 116             }
 117         ]
 118         "settings": {
 119             "powerOnBehavior": 1,
 120             "powerOnBrightness": 20,
 121             "powerOnTemperature": 213,
 122             "switchOnDurationMs": 100,
 123             "switchOffDurationMs": 300,
 124             "colorChangeDurationMs": 100
 125         }
 126 ```
 127
 128 ### Example target filters
 129
 130 Here you will find a list of examples for some common use cases that can be adapted to your liking.
 131 [Filter basics](#filter-basics) provides you with the basic information about how filters are constructed.
 132
 133 Note! You can add the other formatting parameters as -p/--pretty -f/--format or specify any of the other action.
 134
 135 Perform action on all lights that exactly matches "Front Right" (case sensitive) in their names:
 136
 137 ```bash
 138 ./keylights.sh -t '.displayName == "Front Right")' <action>
 139 ```
 140
 141 Perform action on all lights that has "Left" (case sensitive) in their names:
 142
 143 ```bash
 144 ./keylights.sh -t '.displayName | contains("Left")' <action>
 145 ```
 146
 147 Perform action on all lights that has "front" in their names in a case insensitive manner:
 148
 149 ```bash
 150 ./keylights.sh -t '.displayName | ascii_downcase | contains("front")' <action>
 151 ```
 152
 153 Perform action on all lights that have a duration of 100 ms when switched on (notice the object expansion with .(dot)):
 154
 155 ```bash
 156 ./keylights.sh -t '.settings.switchOnDurationMs == 100)' <action>
 157 ```