README.md

   1 - [elagto-key-light-linux](#elagto-key-light-linux)
   2   - [JSON filters in -t/--target](#json-filters-in--t--target)
   3     - [Filter basics](#filter-basics)
   4     - [Example target filters](#example-target-filters)
   5
   6 # elagto-key-light-linux
   7
   8 Small bash script to manage elgato key light and key light air.
   9
  10 The script will let you to manage one, many or all lights depending on what you set as target.
  11
  12 Allows discovery of devices, information collection directly from the lights, changing temperature, changing brightness and turning the lights on and off.
  13
  14 Intended for easy use via CLI, keyboard shortcuts and by StreamDeck, Cinnamon applets etc.
  15
  16 If you are using a StreamDeck you can target this script as a command for the button press.
  17
  18 ## JSON filters in -t/--target
  19
  20 The target option is passing along filters to the json parser.
  21 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.
  22
  23 The script transforms the captured base data to JSON, to allow use of jq filtering independently of what output format you want.
  24
  25 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).
  26
  27 ### Filter basics
  28 The parameter data to pass in to the -t or --target option uses.(dot) notation of the JSON data.
  29
  30 **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.**
  31
  32 The dot(.) notation to target a specific host based on its ipv4 address would be:
  33
  34 ```bash
  35     '.ipv4 = "192.168.0.132"'
  36 ```
  37
  38 of for a nested JSON object like the serial number within the info object:
  39 ```bash
  40     '.info.serialNumber = "CW16K1A01748"'
  41 ```
  42
  43 Example of JSON result (see examples directory for more/full output examples):
  44
  45 ```json
  46 [
  47     {
  48         "device": "Elgato Key Light Air 0C2C",
  49         "manufacturer": "Elgato",
  50         "hostname": "elgato-key-light-air-0c2c.local",
  51         "url": "http://192.168.0.132:9123",
  52         "ipv4": "192.168.0.132",
  53         "ipv6": "N/A",
  54         "port": 9123,
  55         ...
  56         <omitted>
  57         ...
  58         "light": {
  59             "numberOfLights": 1,
  60             "lights": [
  61                 {
  62                     "on": 0,
  63                     "brightness": 31,
  64                     "temperature": 179
  65                 }
  66             ]
  67         },
  68         ...
  69         <omitted>
  70         ...
  71         "info": {
  72             "productName": "Elgato Key Light Air",
  73             "hardwareBoardType": 200,
  74             "firmwareBuildNumber": 199,
  75             "firmwareVersion": "1.0.3",
  76             "serialNumber": "CW16K1A01748",
  77             "displayName": "Front  Right",
  78             "features": [
  79                 "lights"
  80             ]
  81         }
  82 ```
  83
  84 ### Example target filters
  85
  86 Here you will find a list of examples for some common use cases that can be adapted to your liking.
  87 [Filter basics](#filter-basics) provides you with the basic information about how filters are constructed.
  88
  89 Note! You can add the other formatting parameters as -p/--pretty -f/--format or specify any of the other action.
  90
  91 Perform action on all ligts that exactly matches "Front Right" (case sensitive) in their names:
  92
  93 ```bash
  94 ./keylights.sh -t '.info.displayName = "Front Right")' <action>
  95 ```
  96
  97 Perform action on all ligts that has "Left" (case sensitive) in their names:
  98
  99 ```bash
 100 ./keylights.sh -t '.info.displayName | contains("Left")' <action>
 101 ```
 102
 103 Perform action on all ligts that has "front" in their names in a case insensitive manner:
 104
 105 ```bash
 106 ./keylights.sh -t '.info.displayName | ascii_downcase | contains("front")' <action>
 107 ```
 108
 109 Perform action on all ligts that are currently turned on (notice the array expansion):
 110
 111 ```bash
 112 ./keylights.sh -t '.light.lights | .[] | .on = 1)' <action>
 113 ```