Huemility: Hue Schedules for Dumb Homes

This is a service you can run on your home server, which allows you to run light schedules for Phillips Hue that behave correctly when used with dumb switches. It includes the following features:

• You can schedule changes in light intensity and temperature per-light as you please.
• Scheduling is done with keyframes, where the light settings are interpolated between keyframes, allowing smooth transitions over the course of hours.
• The service detects when a light comes back online after being turned off by a dumb switch, and automatically adjusts its intensity and temperature.
• Manually changing the settings of a light will override it in huemility for a set duration, meaning it won't be updated by the service for that time.

Requirements

Only Linux (x86_64 and ARM) is supported.

For this service to work, you'll need to have a Hue Bridge managing your lights.

You'll also need an app key generated from your Hue Bridge. To get one, follow these steps. Your app key is the "authorized user" you generated. It should look similar to kW6GOfd077oXpqYexE6Ms5YzRs0riGVlRQTkUlsQ.

Finally, you'll need to know which lights you want to configure. Each light has a unique ID that we can use to address it. The following command will produce a list of available lights, with their respective ID under the field "id":

curl --insecure -N -H "hue-application-key: [HUE APP KEY]" https://[HUE BRIDGE ADDRESS]/clip/v2/resource/light

Make a note of the ones you care about, you'll need them later when configuring huemility.

Installation and Usage (NixOS)

Installation With Flakes

The easiest way to use huemility is as a NixOS service. If you're using flakes, add this repo to your inputs:

{
  inputs = {
    huemility.url = "git+https://codeberg.org/xlambein/huemility";
  }
}

and import the NixOS module in your configuration:

{
  outputs = {
    nixpkgs,
    huemility,
    ...
  }: {
    nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        huemility.nixosModules.default  # <--- here

        # ... your other modules
      ];
    };
  }
}

This should be enough to enable and configure the service, see below.

Note that I'm also publishing binaries for x86_64-linux and aarch64-linux to cachix. It's particularly helpful if like me you're deploying to a Raspberry Pi and don't want to wait half an hour to build with qemu. You may add the binary cache to your NixOS config, but I'd recommend against it. Instead, you should manually build the package with the following:

# Targetting x86_64-linux
nix build git+https://codeberg.org/xlambein/huemility#packages.x86_64-linux.default
# Targetting aarch64-linux
nix build git+https://codeberg.org/xlambein/huemility#packages.aarch64-linux.default

which will prompt you about using the huemility binary cache (you should answer y n y n), and then proceed to download the binaries and put them in the Nix store. Once this is done, you can do the usual nixos-rebuild switch, which will use those binaries you just downloaded.

Installation Without Flakes

TODO (contributions welcome!)

Usage

The easiest way to understand the module is probably to check out the example in this repo. It contains a description of some common options, as well as a good starting point for configuring a circadian lighting schedule. For a detailed list of options, see Options below.

If you clone this repository, you should be able to run the example locally in a NixOS container in order to test things out without rebuilding your computer or server's NixOS configuration. First you'll want to change the bridgeAddress, appKey, and targets in example.nix to match your own bridge's and lights' (see Requirements above). Then, you can start the container with:

sudo nixos-container create huemility --flake .example
sudo nixos-container start huemility

Make sure the huemility service is running properly with:

sudo nixos-container run huemility -- journalctl -fu huemility.service

And destroy the container when you're done with:

sudo nixos-container destroy huemility

If the example runs properly, it should set the lights in your home to a bright white during the day, a dark orange during the night, and some gradient of these in the mornings and evenings. To test whether things are working properly, you could set the lights manually, then restart huemility and verify that the lights change shade or intensity.

Installation (non-NixOS)

Download the latest release for your platform of choice and store the huemility binary in a location of your liking.

Next, you'll want to write a JSON configuration file for huemility. A good starting point is the example.json file in this repo, which sets up an example circadian lighting. For a detailed list of options, see Options below.

Before anything, you'll want to change bridgeAddress, appKey, and each instance oftargets, to match that of your bridge and lights IDs (see Requirements above). Once this is done, you can test huemility:

huemility -c /path/to/your/config/file.json

If this runs properly, it should set the lights you selected to their current settings in the schedule.

You can automate the running of huemility any way you want, but I'd recommend using a systemd service. There's an example file in example/huemility.service, which you should adapt slightly to your own config. Write your service file to /etc/systemd/system/huemility.service, then enable it with:

systemctl enable huemility

Options

huemility is configured with a JSON file (in the NixOS module, under services.huemility.settings) that accepts the following fields:

• bridgeAddress (string) the address of the Hue Bridge in the local network, e.g. 192.168.1.123.
• appKey (string) the app key used to authenticate requests to the Hue Bridge, e.g. kW6GOfd077oXpqYexE6Ms5YzRs0riGVlRQTkUlsQ.
• updateInterval (string, optional) the interval between two updates of the lights, defaults to 5min.
• overrideDuration (string, optional) the length of time for which a light is overridden when set manually, defaults to 30min.
• onlineDelay (string, optional) the delay before which a light is updated after it was turned on, defaults to 1sec.
• keyframes (list of objects) the list of keyframes that are used for scheduling.

Keyframes are how the scheduler is programmed to control the lights. They represent values of brightness and temperature that we want to achieve at specific points in time. When we fall between these moments, the values will be interpolated. For example, if we have a keyframe at 8:00 that sets brightness to 50.0, and another one at 10:00 that sets brightness to 100.0, at 9:00 huemility will update lights to a brightness of 75.0.

Each keyframe has the following fields:

• targets (list of strings) the list of light IDs that are affected by this keyframe, e.g. ["88582ef4-237b-4895-ac29-9ada4b363bce"].
• time (string) the HH:MM time of this keyframe, e.g. 08:00.
• brightness (number, optional) the brightness that targets achieve at the time of the keyframe, must be between 0.0 (darkest) and 100.0 (brightest).
• temperature (number, optional) the temperature that targets achieve at the time of the keyframe, must be between 153 (coldest) and 500 (warmest).

Brightness and temperature are controlled independently: you can have keyframes that set both, as well as keyframes that only set one of the two.

Note that huemility also accepts command-line arguments and environment variables for some of its settings. For more details, run huemility --help. On NixOS, this is helpful to avoid storing the app key in the Nix store. More details can be found in the example.

Possible Planned Features

I might do these things someday:

• Add support for colors. I can't currently do this because I do not have color bulbs. If you mail me some I'll implement it.

Known Bugs

I think I've ironed out most of the bugs, but there are still a few remaining. Mainly, I've observed some situations where lights don't update after being turned off. This is due to the override mechanism, which still needs a bit of fine-tuning.

Contributing

Contributions are welcome, as long as they fit the scope of the project. Don't hesitate to open an issue or e-mail me about it. Any help improving documentation and ease of use are also extremely welcome!