Meet Kelvin

Kelvin is a little helper bot who will automate the lights in your house. Its job is to adjust the color temperature and brightness in your home based on your local sunrise and sunset times and custom intervals defined by you. Think of it as f.lux or Apple's Night Shift for your home.

Imagine your lights shine in an energetic but not too bright blue color to get you started in the early morning. On sunrise your lights will change to a more natural color temperature to reflect the sunlight outside. On sunset they will slowly fade to a warmer and softer color scheme perfectly suited to Netflix and chill. When it's time to go to bed Kelvin will reduce the intensity even more to get you into a sleepy mood. It will keep this reduced setting through the night so you don't get blinded by bright lights if you have to get up at night...

Features

• Adjust the color temperature and brightness of your lights based on the local sunrise and sunset times
• Define fine grained daily schedules to fit your personal needs throughout the day for every single room
• Define a default startup color and brightness for your lights
• Gradual light transitions you won't even notice
• Works with smart switches as well as conventional switches
• Activate via Hue Scene or automatically for every light you turn on
• Respects manual light changes until a light is switched off and on again
• Auto upgrade to seamlessly deliver improvements to you
• Small, self contained binary with sane defaults and no dependencies to get you started right away
• Free and open source

Getting started

If you want to give Kelvin a try, there are some things you will need to benefit from its services:

• [ ] Supported Philips Hue (or compatible) lights
• [ ] A configured Philips Hue bridge
• [ ] A permanently running computer connected to your network (See Raspberry Pi)

Got all these? Great, let's get started!

Installation

1. Download the latest version of Kelvin from the Releases page.
2. Extract the Kelvin archive.
3. Start Kelvin by double-clicking kelvin.exe on Windows or by typing ./kelvin in your terminal on macOS, Linux and other Unix-based systems. You should see an output similar to the following snippet:

   2017/03/22 10:45:41 Kelvin v1.1.0 starting up... 🚀
   2017/03/22 10:45:41 Looking for updates...
   2017/03/22 10:45:41 ⚙ Default configuration generated
   2017/03/22 10:45:41 ⌘ No bridge configuration found. Starting local discovery...
   2017/03/22 10:45:44 ⌘ Found bridge. Starting user registration.
   PLEASE PUSH THE BLUE BUTTON ON YOUR HUE BRIDGE...
   

4. Now you have to allow Kelvin to talk to your bridge by pushing the blue button on top of your physical Hue bridge. Kelvin will wait one minute for you to push the button. If you didn't make it in time just start it again with step 3.
5. Once you pushed the button you should see something like:

   2017/03/22 10:45:41 🤖 Kelvin starting up... 🚀
   2017/03/22 10:45:41 🤖 Looking for updates...
   2017/03/22 10:45:41 ⚙ Default configuration generated
   2017/03/22 10:45:41 ⌘ No bridge configuration found. Starting local discovery...
   2017/03/22 10:45:44 ⌘ Found bridge. Starting user registration.
   PLEASE PUSH THE BLUE BUTTON ON YOUR HUE BRIDGE... Success!
   2017/03/22 10:45:59 🤖 Devices found on current bridge:
   2017/03/22 10:45:59 | Name                 |  ID | On    | Dimmable | Temperature | Color |
   2017/03/22 10:45:59 | Dining table         |   5 | false | true     | true        | true  |
   2017/03/22 10:45:59 | Power outlet         |   6 | false | false    | false       | false |
   2017/03/22 10:45:59 | Window               |   1 | false | true     | true        | true  |
   2017/03/22 10:45:59 | Kitchen              |   2 | false | true     | true        | true  |
   2017/03/22 10:45:59 | Couch                |   3 | false | true     | true        | true  |
   2017/03/22 10:45:59 | Desk                 |   4 | false | true     | false       | true  |
   2017/03/22 10:45:59 Device Power outlet doesn't support any functionality we use. Exclude it from unnecessary polling.
   2017/03/22 10:45:59 🌍 Location not configured. Detecting by IP
   2017/03/22 10:45:59 🌍 Detected location: Hamburg, Germany (53.5553, 9.995).
   2017/03/22 10:45:59 🤖 Starting cyclic update...
   

6. Wohoo! Kelvin is up and running! Well done!
7. Kelvin is now managing your lights and will gradually adjust the color temperature and brightness for you. Give it a try by switching lights on and off to see how Kelvin reacts. If you want to adjust the default schedule to your needs, just read on and edit the configuration.

Docker

As an alternative to manual installation you can also pull the official docker image from docker hub.

• Get the image by running docker pull stefanwichmann/kelvin
• Start a container via docker run -d -e TZ=Europe/Berlin -p 8080:8080 stefanwichmann/kelvin (replace Europe/Berlin with your local timezone)
• docker ps should now report your running container
• Run docker logs {CONTAINER_ID} to see the kelvin output (You can get the valid ID from docker ps)
• To adjust the configuration you should use the web interface running at http://{DOCKER_HOST_IP}:8080/.
• If you want to keep your configuration over the lifetime of your container, you can map the folder /etc/opt/kelvin/ to your host filesystem. If you alter the configuration you have to restart Kelvin through the web interface or by running docker restart {CONTAINER_ID}.

Configuration

Kelvin will create it's configuration file config.json in the current directory and store all necessary information to operate in it. By default it is fully usable and looks like this:

{
  "bridge": {
    "ip": "192.168.10.37",
    "username": "lbCDGagZZ7JEYQX5iGxrjMIx2jIROgpXfsSjHmCv"
  },
  "location": {
    "latitude": 53.5553,
    "longitude": 9.995
  },
  "schedules": [
    {
      "name": "default",
      "associatedDeviceIDs": [1,2,3,4,5,6],
      "enableWhenLightsAppear": true,
      "defaultColorTemperature": 2750,
      "defaultBrightness": 100,
      "beforeSunrise": [
        {
          "time": "4:00",
          "colorTemperature": 2000,
          "brightness": 60
        }
      ],
      "afterSunset": [
        {
          "time": "20:00",
          "colorTemperature": 2300,
          "brightness": 80
        },
        {
          "time": "22:00",
          "colorTemperature": 2000,
          "brightness": 60
        }
      ]
    }
  ]
}

As the configuration file is a simple text file in JSON format you can display and edit it with you favorite text editor. Just make sure you keep the JSON structure valid. If something goes wrong fix it using JSONLint or just delete the config.json and let Kelvin generate a configuration from scratch.

The configuration contains the following fields:

| Name | Description | | ---- | ----------- | | bridge | This element contains the IP and username of your Philips Hue bridge. Both values are usually obtained automatically. If the lookup fails you can fill in this details by hand. Learn more| | location | This element contains the latitude and longitude of your location on earth. Both values are determined by your public IP. If this fails, is inaccurate or you want to change it manually just fill in your own coordinates. | | schedules | This element contains an array of all your configured schedules. See below for a detailed description of a schedule configuration. |

Each schedule must be configured in the following format:

| Name | Description | | ---- | ----------- | | name | The name of this schedule. This is only used for better readability. | | associatedDeviceIDs | A list of all devices/lights that should be managed according to this schedule. Kelvin will print an overview of all your devices on startup. You should use this to associate your lights with the right schedule. ATTENTION: Every light should be associated to only one schedule. If you skip an ID this device will be ignored. | | enableWhenLightsAppear | If this element is set to true Kelvin will be activated automatically whenever you switch an associated light on. If set to false Kelvin won't take over until you enable a Kelvin Scene or activate it via web interface. | | defaultColorTemperature | This default color temperature will be used between sunrise and sunset. Valid values are between 1000K and 6500K. See Wikipedia for reference values. If you set this value to -1 Kelvin will ignore the color temperature and you can change it manually. ATTENTION: The supported color temperature minimum will vary