{"id":36631012,"url":"https://github.com/stefanvictora/hue-scheduler","last_synced_at":"2026-03-05T22:09:58.431Z","repository":{"id":184655836,"uuid":"354275840","full_name":"stefanvictora/hue-scheduler","owner":"stefanvictora","description":"☀ Sync Philips Hue \u0026 Home Assistant lights to your natural rhythm—with solar-aware schedules and smooth transitions.","archived":false,"fork":false,"pushed_at":"2025-11-16T21:07:01.000Z","size":1570,"stargazers_count":42,"open_issues_count":8,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-11-16T23:12:07.233Z","etag":null,"topics":["circadian","home-automation","homeassistant","hue","hue-lights","philips-hue","raspberry-pi","scheduler","smarthome","sunrise","sunset"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefanvictora.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-04-03T11:36:32.000Z","updated_at":"2025-11-16T09:29:53.000Z","dependencies_parsed_at":"2024-06-28T18:39:21.108Z","dependency_job_id":"57e87ea1-8976-4ac0-8f1c-de7a4b1c1f75","html_url":"https://github.com/stefanvictora/hue-scheduler","commit_stats":null,"previous_names":["stefanvictora/hue-scheduler"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/stefanvictora/hue-scheduler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanvictora%2Fhue-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanvictora%2Fhue-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanvictora%2Fhue-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanvictora%2Fhue-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefanvictora","download_url":"https://codeload.github.com/stefanvictora/hue-scheduler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanvictora%2Fhue-scheduler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circadian","home-automation","homeassistant","hue","hue-lights","philips-hue","raspberry-pi","scheduler","smarthome","sunrise","sunset"],"created_at":"2026-01-12T09:37:08.936Z","updated_at":"2026-03-05T22:09:58.416Z","avatar_url":"https://github.com/stefanvictora.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"right\" width=\"155\" height=\"155\" src=\"https://raw.githubusercontent.com/stefanvictora/hue-scheduler/main/logo.png\"\u003e\n\n# Hue Scheduler\n\n[![build](https://github.com/stefanvictora/hue-scheduler/actions/workflows/maven.yml/badge.svg)](https://github.com/stefanvictora/hue-scheduler)\n[![GitHub Downloads](https://img.shields.io/github/downloads/stefanvictora/hue-scheduler/total?logo=github\u0026color=%235f87c4)](https://github.com/stefanvictora/hue-scheduler/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/stefanvictora/hue-scheduler?logo=docker\u0026color=%235f87c4)](https://hub.docker.com/r/stefanvictora/hue-scheduler)\n\n\u003e Boost your daytime focus and unwind at night. Hue Scheduler fine-tunes your Philips Hue or Home Assistant lights by time, sun position, and weekday.\n\n## Introduction\n\n**New in 0.14.0** — **Update lights even if they are off** (requires Hue Bridge; enabled by default). Lights are now updated in the background, ensuring they turn on directly in the scheduled brightness, color temperature, and color. A lightweight alternative to synced scenes. For complex schedules where lights are intentionally turned off at specific times, **Scene Sync** remains the recommended approach.\n\n**New in 0.12.0** — **Sync schedules to scenes** (opt-in via ``--enable-scene-sync``). Creates synced scenes so lights turn on instantly in the desired state, with full **Home Assistant** support.\n\nHue Scheduler goes beyond tools like Adaptive Lighting by giving you precise control over brightness, color temperature, color, power state, and custom interpolations between solar and absolute times. It's designed to work with dumb wall switches: as soon as lights become available, Hue Scheduler applies the correct settings consistently, even after physical on/off toggles.\n\n## Demo\n\nConfigure your lights with a simple, text-based file (fields separated by a tab or at least two spaces). Below are examples for daily routines, interpolations, power control, and ambiance.\n                     \n```text\n# Living Room\nlight.living_room  sunrise      bri:80%    ct:6000         tr:10s  force:true\nlight.living_room  sunrise+60   bri:100%   ct:5000         interpolate:true\nlight.living_room  sunset       bri:60%    ct:3000         tr-before:golden_hour-20\nlight.living_room  23:00        bri:40%    color:#FE275D   tr-before:1h\n\n# Porch Light: Control power state\nPorch Light  civil_dusk   on:true    bri:100%   tr:1min\nPorch Light  23:00        on:false              tr:5min\n\n# Motion Sensor: Inactive at night on weekdays\nswitch.sensor_hallway_activated   08:00   on:true\nswitch.sensor_hallway_activated   22:00   on:false   days:Mo-Fr\n```\n\n\u003e [!TIP]\n\u003e Hue Scheduler does **not** automatically turn on lights (unless you specify `on:true`). You stay in control; it handles adjustments once lights are on.\n\n\u003e [!NOTE]\n\u003e Manual changes temporarily suspend the schedule until lights are turned off and back on.\n\u003e If lights turn on mid-transition, Hue Scheduler computes the correct mid-transition state and continues seamlessly.\n\n## How It Works\n\nEach line has three parts (separated by a tab or ≥2 spaces):\n\n```yacas\n\u003cLight/Group Name or ID\u003e  \u003cStart Time Expression\u003e  [\u003cProperty\u003e:\u003cValue\u003e]*\n```\n\n**Light/Group Name or ID**\n\nWhich light or group to control. Use names or IDs (e.g., `Couch` or `light.couch`). Combine multiple targets with commas. Supported Home Assistant entities: `light`, `input_boolean`, `switch`, `fan`.\n\n**Start Time Expression**\n\nUse fixed times (24-hour `HH:mm[:ss]`, e.g., `06:00`, `23:30:15`) or solar times (`sunrise`, `sunset`, etc.). You can offset solar times with ± minutes (e.g., `sunset-30`, `sunrise+60`). Available solar constants (chronological): `astronomical_dawn`, `nautical_dawn`, `civil_dawn`, `sunrise`, `noon`, `golden_hour`, `sunset`, `blue_hour`, `civil_dusk`, `night_hour`, `nautical_dusk`, `astronomical_dusk`.\n\n**Properties**\n\n- **Basic**\n    - **`bri`** — brightness `1–254` or `1%–100%`\n    - **`ct`** — color temperature in **Kelvin** `6500–1000` or **Mired** `153–500` (cool → warm)\n    - **`on`** — power state (`true|false`)\n    - **`days`** — active days (e.g., `days:Mo-Fr`, `days:Tu,We`)\n- **Color**\n    - **`color`** (hex or RGB), e.g., `#3CD0E2` or `60,208,226`\n    - **`effect`** (e.g., `prism`, `fire`, `none`)\n- **Advanced**\n    - **`x`** / **`y`** — CIE xy (e.g., `x:0.6024  y:0.3433`)\n    - **`force:true`** — enforce state even after user changes\n- **Transitions**\n    - **`tr`** — transition at start (e.g., `tr:10s`, `tr:1h5min`)\n    - **`tr-before`** — pre-transition starting before the state (relative, absolute, or solar, e.g., `tr-before:30min`, `tr-before:06:00`, `tr-before:civil_dawn+5`)\n    - **`interpolate:true`** — auto-transition from the start of the previous state; also spans across days\n\n\u003e [!TIP]\n\u003e Full syntax and edge cases: see the [full configuration guide](docs/light_configuration.md).\n\n## Quick Start\n\nRun Hue Scheduler via Docker (recommended) or manually with Java. Configuration differs slightly for each method.\n\n### Prerequisites\n\n- A Philips Hue Bridge (up-to-date) or a Home Assistant instance\n- A device that runs continuously on your network (e.g., Raspberry Pi)\n- Docker **or** Java 21\n\n### Docker\n\n1. **Create `docker-compose.yml`:**\n\n   ```yaml\n   services:\n     hue-scheduler:\n       container_name: hue-scheduler\n       image: stefanvictora/hue-scheduler:0.14\n       environment:\n         - API_HOST=\n         - ACCESS_TOKEN=\n         - LAT=\n         - LONG=\n         - ELEVATION=\n         - TZ=\n         - CONFIG_FILE=/config/input.txt # do not edit\n       volumes:\n         - type: bind\n           source: /path/to/your/input.txt  # \u003c- set your file path\n           target: /config/input.txt\n           read_only: true\n       restart: unless-stopped\n   ```\n   A filled-out example is available in [docs/docker_examples.md](docs/docker_examples.md).\n\n2. **Provide parameters:**\n\n   Environment variables:\n    - `API_HOST` — Hue Bridge or Home Assistant origin (e.g., `192.168.0.157`, `http://ha.local:8123`, `https://UNIQUE_ID.ui.nabu.casa`)\n    - `ACCESS_TOKEN` — [Hue bridge username](https://github.com/stefanvictora/hue-scheduler/blob/main/docs/philips_hue_authentication.md) or [Home Assistant long-lived access token](https://www.home-assistant.io/docs/authentication/).\n    - `LAT`, `LONG`, `ELEVATION` — location for solar times\n    - `TZ` — your time zone\n   \n   Volume configuration:\n    - `source` — local path to your [configuration file](docs/light_configuration.md) containing the light schedules.\n    \n    Advanced options: see [Advanced Command-Line Options](docs/advanced_command_line_options.md). From 0.12.0 onward, enable Scene Sync via `ENABLE_SCENE_SYNC=true` (env) or `--enable-scene-sync` (CLI).\n  \n3. **Start/stop with Docker Compose:**\n\n   ```shell\n   # Start:\n   docker compose up -d\n   \n   # Stop \u0026 remove:\n   docker compose down\n   ```\n\nIf your Raspberry Pi doesn't have Docker yet, see [docs/docker_on_raspberrypi.md](docs/docker_on_raspberrypi.md).\n\n### Manual (Java)\n\n1. **Download the latest release**: [releases/latest](https://github.com/stefanvictora/hue-scheduler/releases/latest).\n2. **Run the JAR** (replace placeholders):\n   ```shell\n   java -jar hue-scheduler.jar \u003cAPI_HOST\u003e \u003cACCESS_TOKEN\u003e --lat=\u003cLATITUDE\u003e --long=\u003cLONGITUDE\u003e --elevation=\u003cELEVATION\u003e \u003cCONFIG_FILE_PATH\u003e\n   ```\n\n## FAQ\n\n### Does Hue Scheduler work with motion sensors and smart switches?\n\nYes. Starting with **0.12.0**, when Scene Sync is enabled (``--enable-scene-sync``), Hue Scheduler creates a synced scene (default: `HueScheduler`) that mirrors the current scheduled state of a room or zone. Select this scene in your motion sensor or smart switch so lights turn on in the desired state instantly.\n\nSince **0.14.0**, you can alternatively keep your sensors/switches configured to turn lights on in their **last on state**. Hue Scheduler now updates your lights **even while they’re off**, ensuring they power on directly in the scheduled brightness, color temperature, and color. *(Requires Hue Bridge.)*\n\nFor complex schedules where lights are intentionally turned off at certain times, **Scene Sync** remains the recommended approach. Synced scenes also make it easy to reset manual overrides by simply reapplying the scene.\n\n### Why is there a delay after physically switching lights on?\n\nIt's a Hue Bridge limitation. Physically powered-on lights are typically detected after ~3–4 seconds; app/switch activations are near-instant. Also note: after turning lights **off** via a dumb wall switch, the bridge can take up to ~2 minutes to register the change. Fast off / on cycles may be missed; to clear manual overrides with dumb switches, wait ~2 minutes before turning lights back on.\n\n### My Ikea TRÅDFRI bulbs don’t respect transitions when changing multiple properties\n\nSome TRÅDFRI firmware versions fail when applying **multiple properties with a non-zero transition**. Because the Hue Bridge defaults to 400 ms (`tr:4`) if not specified, set `tr:0` when changing multiple properties on those bulbs—or split changes into separate states. See issue https://github.com/stefanvictora/hue-scheduler/issues/5 for details.\n\n### How does Hue Scheduler compare to Adaptive Lighting?\n\nBoth automate light state across the day. Differences:\n\n- **Control over properties:** Adaptive Lighting mostly adjusts color temperature and brightness. Hue Scheduler also controls color and power.\n- **Flexibility:** Adaptive Lighting continuously adjusts with limited manual scheduling. Hue Scheduler is schedule-driven and highly customizable—define multiple custom interpolations in a single, human-readable file.\n\n### Does Hue Scheduler access the Internet?\n\nNo, unless you explicitly connect to a cloud-hosted Home Assistant instance. You can inspect outbound REST requests by setting `-Dlog.level=TRACE` (JVM) or `log.level=TRACE` (env). See [Advanced Command-Line Options](docs/advanced_command_line_options.md). Solar times are computed locally via [shred/commons-suncalc](https://github.com/shred/commons-suncalc); your location data never leaves the device.\n\n## Roadmap\n\n- [x] **Detect manual overrides** — set state only if not changed by the user since the last scheduled state\n- [x] **Enforce states** — always set state; disallow manual overrides\n- [x] **Interpolate between states** — advanced transitions with `tr-before`\n- [x] **Advanced state interpolations** — all-day interpolations without explicitly using `tr-before`\n- [x] **Docker support** — prebuilt Docker images\n- [x] **Home Assistant API support** — control lights via HA\n- [x] **Hue API v2 effects** — support additional effects\n- [x] **Scene Sync** — scenes that mirror the scheduled state of a room/zone\n- [ ] **Define schedules via scenes** — update schedules without restarting\n- [ ] **Conditional states** — apply only if conditions are met\n- [ ] **Date-based scheduling** — restrict by date ranges\n- [ ] **Gradients** — support gradient-capable lights\n- [ ] **Scene scheduling** — schedule scenes for groups\n- [ ] **Sunrise/sunset min/max** — bound dynamic times to a window\n- [ ] **Web GUI** — configure/update schedules in a browser\n- [ ] **Home Assistant Add-on** — package as an easy install\n\n## Developing\n\n```shell\n# Clone:\ngit clone https://github.com/stefanvictora/hue-scheduler.git\ncd hue-scheduler\n\n# Build with Maven:\nmvnw clean install\n```\n\nThe runnable JAR is created at `target/hue-scheduler.jar` (with all dependencies).\n\n### Docker Image\n\nBuild and run your own image (replace `\u003cVERSION\u003e`):\n\n```shell\ndocker build -t stefanvictora/hue-scheduler:\u003cVERSION\u003e -f Dockerfile .\n```\n\nUsage is shown in **Quick Start → Docker**. Useful commands:\n\n```shell\n# Rebuild and run:\ndocker compose up -d --build\n\n# Remove container on exit:\ndocker run --rm -e \"log.level=TRACE\" --name hue-scheduler ...\n```\n\n## Similar Projects\n\n- [Kelvin — The hue bot](https://github.com/stefanwichmann/kelvin) — automates color temperature and brightness over the day\n- [Adaptive Lighting](https://github.com/basnijholt/adaptive-lighting) — Home Assistant custom component for adaptive CT and brightness\n\n## License\n\n```text\nCopyright 2021-2026 Stefan Victora\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanvictora%2Fhue-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanvictora%2Fhue-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanvictora%2Fhue-scheduler/lists"}