search

stefanvictora / hue-scheduler

☀ Adjust your Philips Hue and Home Assistant lights to your natural rhythm. With advanced schedules and transitions based on solar times.
Apache License 2.0
16 stars 0 forks source link
circadian home-automation homeassistant hue hue-lights philips-hue raspberry-pi scheduler smarthome sunrise sunset

readme

Hue Scheduler

build GitHub Downloads Docker Pulls

Boost your daytime focus and unwind at night with Hue Scheduler. Easily fine-tune your Philips Hue or Home Assistant lights based on the time, sun's position, and the day of the week.

Introduction

New in Version 0.10.0: Full support for the Home Assistant REST API :partying_face: Control even more devices in your home with Hue Scheduler.

Hue Scheduler goes beyond tools like Adaptive Lighting by providing extended control over brightness, color temperature, color, power state, and custom interpolations between solar and absolute times. Specifically designed to work with dumb wall switches, it adjusts light states as soon as they're reachable, ensuring consistent results even when lights have been physically turned off.

Demo

Hue Scheduler allows you to configure your smart lights with a simple, text-based configuration file. Below, you can see various examples demonstrating how to create daily routines, dynamic interpolations, power management schedules, and ambiance settings.

# Living Room
light.living_room  sunrise      bri:80%    ct:6000         tr:10s
light.living_room  sunrise+60   bri:100%   ct:5000         interpolate:true
light.living_room  sunset       bri:60%    ct:3000         tr-before:golden_hour-20
light.living_room  23:00        bri:40%    color:#FE275D   tr-before:1h

# Porch Light: Control power state
Porch Light  civil_dusk   on:true    bri:100%   tr:1min
Porch Light  23:00        on:false              tr:5min

# Motion Sensor: Inactive at night on weekdays
switch.sensor_hallway_activated   08:00   on:true
switch.sensor_hallway_activated   22:00   on:false   days:Mo-Fr

[!TIP] Hue Scheduler does not automatically turn on your lights (unless explicitly specified with on:true), allowing you to maintain control while it handles all the adjustments once they are turned on.

[!NOTE] Any manual changes to your lights will temporarily suspend the schedule until they are turned off and on again. If lights are turned on midway through a transition, Hue Scheduler calculates the appropriate mid-transition state to continue the transition seamlessly.

How It Works

Each configuration line has three parts:

<Light/Group Name or ID>  <Start Time Expression>  [<Property>:<Value>]*

Light/Group Name or ID:

Start Time Expression:

Properties:

[!TIP] Visit the full documentation for more detailed information on how to configure your light schedules.

Quick Start Guide

You can run Hue Scheduler in two ways: using the official Docker image or by manually downloading and running the Java application. The configuration differs slightly for each method, as detailed below.

Prerequisites

To run Hue Scheduler, you will need the following:

Via Docker

To get started with Docker, follow these steps:

  1. Create a docker-compose.yml template:

    services:
 hue-scheduler:
   container_name: hue-scheduler
   image: stefanvictora/hue-scheduler:0.11
   environment:
     - API_HOST=
     - ACCESS_TOKEN=
     - LAT=
     - LONG=
     - ELEVATION=
     - TZ=
     - CONFIG_FILE=/config/input.txt # do not edit
   volumes:
     - type: bind
       source: # <- Insert your config file path
       target: /config/input.txt
       read_only: true
   restart: unless-stopped

    You can find a filled-out docker-compose example here.

  2. Provide the required parameters:

    • API_HOST: IP address or host of your Philips Hue bridge or Home Assistant instance, e.g., 192.168.0.157, http://ha.local:8123, or https://UNIQUE_ID.ui.nabu.casa (untested)
    • ACCESS_TOKEN: A Philips Hue bridge username or Home Assistant access token.
    • LAT, LONG & ELEVATION: Location details to calculate local solar times.
    • TZ: Your time zone.
    • SOURCE: Path to the configuration file containing the light schedules.

    For additional configuration options, see the list of advanced command line options.

  3. Run Docker Compose commands:

    # Create and run container:
docker compose up -d

# Stop and remove container:
docker compose down

If your Raspberry Pi does not yet have Docker installed, check out this short guide.

Manually

To run Hue Scheduler manually, follow these steps:

  1. Download the latest release from GitHub here.
  2. Run the application using the following command. Replace the placeholders enclosed in <> with your actual values: 
    java -jar hue-scheduler.jar <API_HOST> <ACCESS_TOKEN> --lat=<LATITUDE> --long=<LONGITUDE> --elevation=<ELEVATION> <CONFIG_FILE_PATH>

FAQ

Why is there a short delay when physically turning lights on and the scheduler taking over?

This is a known limitation of the Hue Bridge. There is typically a delay of around 3–4 seconds until physically turned on lights are detected as available again. In contrast, lights turned on via smart switches or an app are detected almost instantly.

Another limitation with dumb wall switches is that the Hue Bridge can take up to ~2 minutes to detect lights being physically turned off, and therefore won't detect fast off and on switches. This means if you want to reset manual overrides with dumb wall switches, you have to wait at least 2 minutes before turning the lights back on.

How does Hue Scheduler compare to Adaptive Lighting?

Both Adaptive Lighting and Hue Scheduler aim to automate the state of your lights based on the time of day. However, there are key differences:

Does Hue Scheduler access the Internet?

Hue Scheduler does not access the Internet unless you explicitly connect to a cloud-hosted Home Assistant instance. You can see exactly which REST requests Hue Scheduler sends to your devices by setting the -Dlog.level=TRACE JVM parameter or log.level=TRACE environment variable. See Advanced Command Line Options. The dynamic solar times are calculated locally using the shred/commons-suncalc library, with no location data ever leaving your device.

Does Hue Scheduler work with motion sensors?

Yes, but you should probably use a third-party app like iConnectHue to configure your motion sensor to only adjust the brightness of your lights, not the color or color temperature. Otherwise, the color or color temperature of your lights would switch between the sensor set values and the ones scheduled by Hue Scheduler, causing some flicker every time the sensor is activated.

Roadmap

Developing

To build Hue Scheduler from source, run:

# Clone the repository:
git clone https://github.com/stefanvictora/hue-scheduler.git
# Navigate to project root:
cd hue-scheduler
# Build using maven
mvnw clean install

This process creates the runnable JAR file target/hue-scheduler.jar containing all dependencies.

Docker Image

Alternatively, you can use the provided Dockerfile to build and run a new Docker image of Hue Scheduler. Replace <VERSION> with the desired version number:

docker build -t stefanvictora/hue-scheduler:<VERSION> -f Dockerfile .

The usage of the image is shown above in the Getting Started section. Other useful Docker commands for development include:

# Rebuild and Run:
docker-compose up -d --build

# Remove container on exit:
docker run --rm -e "log.level=TRACE" --name hue-scheduler ...

Similar Projects

License

Copyright 2021-2024 Stefan Victora

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.