HueUpdater

Controls Hue API compatible lights based on the status of projects in CI systems monitored by CIStatusAggregator.

Stable | Stable & Building | Broken | Broken & Building

Build status

AppVeyor status:

Sonarcloud status:

Motivation

I use lamps at work to give my teams instant feedback about the status of multiple projects tracked by our CI systems.

Multiple copies of this application manage lamps with lights that are connected to a Hue bridge. The information required to determine the color of each light is obtained from CIStatusAggregator.

Based on a defined schedule and a calendar, the program turns the lamps on/off and sets the light colors accordingly.

Usage prerequisites

• An operational instance of CIStatusAggregator and access to the files it generates via a web server.

• Operational Hue lights, and related networking equipment.

• An API key to control the Hue lights.

• Basic JSON knowledge to edit the settings file.

• Write permission on a local folder to save the file that keeps track of the lamps' last status.

Deployment

Unpack the release file wherever you want on the target system. I suggest C:\HueUpdater on Windows or /opt/HueUpdater on Linux.

Open the appsettings.json file with a plain text editor and carefully tweak the sample values in the HueUpdater section to match your needs.

💥 NOTE
Be careful to follow JSON formatting rules, or the program will not work correctly

Here's an attempt to explain each value:

• AppearancePresets

  Every element in this section defines a named preset that controls the look of one or more lights. Bulbs from different manufacturers usually look different, so this allows the configuration of each light type individually to achieve the desired look.

  
  

  "HueUpdater": {
    "AppearancePresets": {
      // appearance preset definitions go in here
    }
  }

  
  

• AppearancePresets -> ArbitraryName:

  Set this to any value you want, but don't repeat names within this section. Using the name of the light manufacturer is recommended. In the example below, the chosen name was Philips.

• AppearancePresets -> ArbitraryName -> Sat:

  Value that defines the color saturation. Must be between 0 and 254.

• AppearancePresets -> ArbitraryName -> Bri:

  Value that defines the brightness of the light. Must be between 0 and 254.

• AppearancePresets -> ArbitraryName -> BlueHue:

  Value that defines the color blue for this preset. Must be between 0 and 65535.

• AppearancePresets -> ArbitraryName -> GreenHue:

  Value that defines the color green for this preset. Must be between 0 and 65535.

• AppearancePresets -> ArbitraryName -> RedHue:

  Value that defines the color red for this preset. Must be between 0 and 65535.

• AppearancePresets -> ArbitraryName -> YellowHue:

  Value that defines the color yellow for this preset. Must be between 0 and 65535.

  The values for colors in the Hue API are not straight forward. For more information, refer to the official docs at https://developers.meethue.com/develop/get-started-2/core-concepts/

  
  

  "AppearancePresets": {
    "Philips": {
      "Sat": 254,
      "Bri": 50,
      "BlueHue": 44000,
      "GreenHue": 26000,
      "RedHue": 65000,
      "YellowHue": 10000
    }
  }

  
  

• StatusUrls

  This is a list of one or more URLs that point to files generated by CIStatusAggregator

  
  

  "HueUpdater": {
    "StatusUrls": [
      "https://cistatusaggregator.example/global.json",
      "https://cistatusaggregator.example/aux.json"
    ]
  }

  
  

• HueLights

  This is a list of nameless Hue endpoint definitions. Each entry defines a light to be updated and its properties. It is assumed all the lights defined in this section represent the status of the same system.

  NOTE: You can run multiple copies of this application in different locations with varying configuration files if you need to monitor separate systems.

  
  

  "HueUpdater": {
    "HueLights": {
      // endpoint definitions go in here
    }
  }

  
  

• HueLights -> AppearancePreset

  The appearance preset must be defined in the AppearancePresets section, or it will default to the first preset.

• HueLights -> Endpoint

  Fully valid Hue API URL to the light to be updated. You will know the IP/hostname and API key once you've completed your Hue API setup.

  
  

  "HueLights": {
    {
      "AppearancePreset": "Philips",
      "Endpoint": "http://huebridge.example/api/0123456789012345678901234567890123456789/lights/1/state"
    }
  }

  
  

• Persistence -> LightStatusFilePath

  Full or relative path to a file used to persist the collective status of the lights.

  
  

  "HueUpdater": {
    "Persistence": {
      "LightStatusFilePath": "light-status.json"
    }
  }

  
  

• Workplan

  Defines when the lamp turns on and off. It contains multiple sections to do so, explained below.

  
  

  "HueUpdater": {
    "Workplan": {
      "Schedule": { /* The definition of the schedule goes here. */ }
      "Calendar": { /* The definition of the calendar goes here. */ }
      "Overrides": { /* The definition of the schedule overrides by day of the week goes here. */ }
    }
  }

  
  

• Workplan -> Schedule

  Contains named entries that define the working hours for the lamps. Each entry has a priority that is used to solve ambiguities between the Calendar and the Overrides sections. The schedule with the lowest number will be given the highest priority. For example, a schedule with priority 1 is always chosen over a schedule with priority 4.

  The following example defines two schedules. The Off schedule starts and finishes at 00:00, so the lamp never turns on. The Regular schedule stipulates the lights should turn on at 08:15 in the morning and off at 19:15 in the evening. The priority of the Off schedule ensures it is always chosen over the Regular schedule.

  
  

  "Workplan": {
    "Schedule": {
      "Off":     { "Priority": 1, "Hours": { "Start": "00:00", "Finish": "00:00" } }
      "Regular": { "Priority": 4, "Hours": { "Start": "08:15", "Finish": "19:15" } }
    }
  }

  
  

• Workplan -> Calendar

  Contains named entries that themselves contain a list of date ranges. The name must coincide with one of the schedules defined in the Schedules section. This is the way that schedules are mapped to days of the year.

  The following example shows how to map three days to the Off schedule, and the whole month of May to the Regular schedule.

  
  

  "Workplan": {
    "Calendar": {
      "Off": [
        { "Start": "2023/01/06", "Finish": "2023/01/06" },
        { "Start": "2023/04/06", "Finish": "2023/04/07" }
      ],
      "Regular": [
        { "Start": "2023/05/01", "Finish": "2023/05/31" }
      ]
    }
  }

  
  

• Workplan -> Overrides

  Allows mapping day names to schedules. This section is meant to force a schedule with higher priority on certain days, like weekends.

  The following example sets the schedule Off for Saturdays and Sundays. If you combine all the examples in the file so far, May will have all its days assigned to the Regular schedule, except for Saturday and Sunday which will resolve to Off

  
  

  "Workplan": {
    "Overrides": {
      "Saturday": "Off",
      "Sunday":   "Off"
    }
  }

  
  

Finally, use your preferred scheduling method to run this application frequently. I usually run it every minute with the Windows Task Scheduler or with a systemd timer.

License

This project is licensed under the MIT License - see the LICENSE.md file for details