{"id":20218372,"url":"https://github.com/dokzlo13/hueplanner","last_synced_at":"2026-02-25T21:05:17.683Z","repository":{"id":214095705,"uuid":"735666923","full_name":"dokzlo13/hueplanner","owner":"dokzlo13","description":"Declarative Philips Hue automation system with extensive automation rules","archived":false,"fork":false,"pushed_at":"2025-02-18T15:02:58.000Z","size":705,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-29T05:34:39.716Z","etag":null,"topics":["hue","hue-api","hue-api-v2","hue-bridge","hue-lights","hue-lights-control","philips-hue"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dokzlo13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-12-25T18:40:53.000Z","updated_at":"2025-03-07T19:09:52.000Z","dependencies_parsed_at":"2024-12-14T22:22:08.455Z","dependency_job_id":"6b1d4a08-82ee-4bfc-80d4-ff49e1f83f08","html_url":"https://github.com/dokzlo13/hueplanner","commit_stats":null,"previous_names":["dokzlo13/hueplanner"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/dokzlo13/hueplanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokzlo13%2Fhueplanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokzlo13%2Fhueplanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokzlo13%2Fhueplanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokzlo13%2Fhueplanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dokzlo13","download_url":"https://codeload.github.com/dokzlo13/hueplanner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokzlo13%2Fhueplanner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29839971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T20:42:33.054Z","status":"ssl_error","status_checked_at":"2026-02-25T20:42:21.322Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["hue","hue-api","hue-api-v2","hue-bridge","hue-lights","hue-lights-control","philips-hue"],"created_at":"2024-11-14T06:38:21.098Z","updated_at":"2026-02-25T21:05:17.667Z","avatar_url":"https://github.com/dokzlo13.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HuePlanner\n\n\u003e The most overengineered way to turn on your lightbulb\n\nhueplanner is a simple, declarative system I built to make automating Philips Hue lights easier. Whether you want to set up schedules, respond to button presses, or trigger actions through HTTP requests, hueplanner helps you control your lights with just a .yaml config file.\n\nYou can use it for everything from syncing your lights with natural daylight cycles to creating custom automations based on events or webhooks. No need for heavy home automation setups—just write your rules and let hueplanner handle the rest. It's flexible, lightweight, and designed to fit around your life.\n\n---\n\n### Why choose hueplanner?\n\n- **Focused Purpose**: When you don’t need a full-fledged home automation system and just want smart, feature-rich control over your lights, hueplanner is a great fit.\n- **Easy Deployment**: Have a place to run a single Docker container? That’s all you need to get hueplanner up and running.\n- **Declarative Configuration**: Enjoy the power and flexibility of config-based automations. Define your lighting plans using simple `.yaml` files.\n- **Extensibility**: Hueplanner is designed to be extendable. Want to trigger your lights based on stock prices or other external data? With a bit of customization, it's possible!\n\n### Why might hueplanner not be for you?\n\n- **No Desktop or Mobile App**: Hueplanner doesn’t have a user-friendly UI. It’s designed to run on a server, preferably within your local network.\n- **Declarative Approach**: If you’re not comfortable learning hueplanner’s domain-specific language (DSL) for configuring automations, this may not be the tool for you.\n- **Not a Hue SDK**: Hueplanner is not a Hue SDK for Python. If you're looking for a dedicated SDK, this isn’t it, but feel free to borrow code from hueplanner’s implementation of Hue API libraries.\n- **Early Development**: Hueplanner is a small hobby project with limited test coverage. It’s still evolving, so you may encounter bugs as it matures.\n- **Limited Action Support**: Currently focused on circadian lighting automation, hueplanner may lack advanced actions for other areas of the Hue ecosystem. Contributions to expand its functionality are welcome!\n\n---\n\n## Dive in\n\nLet's start with simple config file\n\n```yaml\n# hueplanner.yaml\n\nsettings:\n  hue_bridge:\n    addr: \"192.168.0.123\"\n    username: \"\u003cyour HUE bridge access token\u003e\"\n\nplan:\n  - trigger:\n      type: Immediately  # Do something immediately\n    action:\n      type: StoreSceneByName  # We will store some scene in memory, so button press below will have scene to toggle.\n      args:\n          name: \"Energize\"\n          store_as: \"my_scene\"\n\n  - trigger:\n      type: Once  # do something just once\n      args:\n        time: \"12:00\"\n    action:\n      type: StoreSceneByName  # We store another scene at 12:00\n      args:\n          name: \"Concentrate\"\n          store_as: \"my_scene\"\n          activate: True  # also activate this scene (if lights are on)\n\n  - trigger:\n      type: OnHueButtonEvent  # handling button press on the sensor\n      args:\n        action: \"short_release\"\n        resource_id: \"1e53050b-ca07-44f3-977f-ab0477e5e911\"\n    action:\n      type: ToggleStoredScene  # toggle scene lights. Toggles scene, stored by some previous actions\n      args:\n        db_key: \"my_scene\"\n\n  - trigger:\n      type: Minutely  # do something every minute, starting from next one\n    action:\n      type: UpdateLightV2  # V2, because we are using v2 api and v2 identifiers\n      args:\n        id: \"08d6350b-fb3f-4dc1-b6cc-62350d8f4f10\"\n        update: {\"identify\": {\"action\": \"identify\"}}  # let's just blink lightbulb on this trigger\n\n```\n\nInterested in something really functional, not just dummy example? Please check [examples](./examples) folder!\n\nSo, let's start application:\n\n```bash\ndocker run --rm -v $(pwd)/config_ioc.yaml:/hueplanner/hueplanner.yaml:ro -e CONFIG_FILE='./hueplanner.yaml' ghcr.io/dokzlo13/hueplanner:latest\n```\n\nIf you have repository cloned and all dependencies installed, you can simply run\n\n```bash\npython main.py --config ./hueplanner.yaml\n```\n\n---\n\n## Motivation\n\nA while ago, I purchased a Philips HUE hub along with some smart lamps to create ambient lighting for my room. My favorite feature was the \"Natural Light\" mode, which allows for circadian lighting—a great benefit when working long hours at a PC.\n\nHowever, I soon encountered an issue. When using one of the [Philips Hue Dimmer Switches](https://www.philips-hue.com/en-gb/p/hue-dimmer-switch/8719514274617), turning the lights off would not save the current \"Natural Light\" scene. For example, if I turned the lights off while in \"Night Light\" mode before going to bed, the next morning, turning the lights back on would leave them stuck in \"Night Light\" mode instead of switching to the \"Energize\" scene.\n\nI wanted a solution where the lights would automatically revert to the \"Natural Light\" scene based on the time of day whenever they were turned on.\n\nAlthough there are comprehensive home automation solutions available, such as [Home Assistant](https://www.home-assistant.io/), I found them too complex for my specific needs. My goal was simple: improved automation logic for my remote and lamps. Configuring Home Assistant just to set up [flux](https://www.home-assistant.io/integrations/flux/) felt like overkill.\n\nThis led me to spend hundreds of hours designing and developing my own automation system.\n\nI initially created a basic Python script that would adjust the lighting scene based on astronomical events for my location, thanks to the [Astral](https://github.com/sffjunkie/astral) library. It also responded to button presses to toggle the lights. I deployed it as a Docker container on my NAS, and everything worked fine—until winter arrived.\n\nLiving in the far north, our winters are long and dark. I noticed that the lights would dim too early in the day, and I wanted to extend the daylight hours by applying an offset to the dimming schedule. But as summer approached, I realized I'd need to revert all these changes, which felt cumbersome.\n\nThat’s when I decided to go declarative.\n\nI began developing **hueplanner**, a more advanced system that could be easily configured using a declarative approach. This is how **hueplanner** was born.\n\n### Hueplanner declarative approach\n\n**hueplanner** is a declarative automation system designed specifically for Philips Hue. It operates by reading `.yaml` configuration files that define a \"plan\" using a domain-specific language (DSL). The system works based on the following key principles:\n\n- A \"plan\" consists of a list of **PlanEntries**.\n- Each **PlanEntry** defines:\n  - One trigger: an event such as a scheduled time or an event from the Hue hub.\n  - One or more actions: operations like toggling lights, changing scenes, etc.\n- When a trigger is activated, the corresponding action(s) are executed.\n\nIn short, **hueplanner** allows you to automate your Philips Hue lights using a simple, flexible configuration.\n\n---\n\n## Deployment\n\n\n### Settings\n\nHueplanner connects to one HUE bridge, this is required dependency.\n\nHere is minimal required config:\n\n```yaml\nsettings:\n  hue_bridge:\n    addr: \"\u003cHUE bridge IP\u003e\"\n    username: \"\u003cyour HUE bridge access token\u003e\"\n```\n\nHere is list of all available settings:\n\n```yaml\nsettings:\n  tz: Europe/Berlin  # timezone\n  hue_bridge:\n    addr: \"\u003cHUE bridge IP\u003e\"\n    username: \"\u003cyour HUE bridge access token\u003e\"\n  log:\n    level: info  # log level: critical, error, warning, info, debug\n    colors: true # you may disable log coloring for log-collection systems\n  database:\n   # path to sqlite database. If not provided, app will run in memory-only mode.\n    path: ./hueplanner.sqlite\n  # Exposes http://0.0.0.0:9090/health/live and http://0.0.0.0:9090/health/ready for health probes\n  healthcheck:   # If this section not provided, healthcheck will be disabled\n    host: 0.0.0.0\n    port: 9090\n```\n\n### Environment variables substitution\n\nTo prevent storing secrets within config file, hueplanner resolves the environment variables you provide:\n\n```yaml\nsettings:\n  hue_bridge:\n    addr: \"192.168.0.123\"\n    # You can use environment substitution anywhere in the config.\n    username: ${HUE_ACCESS_TOKEN}\n  log:\n    # If no env variable provided, fallback value \"debug\" will be used\n    level: ${LOG_LEVEL:debug}\n  database:\n    path: ${DB_PATH}  # path to sqlite database. If not provided, app will run in memory-only mode.\n\nplan:\n  - trigger:\n      type: OnHueButtonEvent\n      args:\n        action: \"initial_press\"\n        resource_id: ${MY_BUTTON_ID}  # You can substitute values in plan too!\n    action: ...\n```\n\n\n### Docker-compose deployment\n\nHere is example of docker-compose file, used for synology NAS \"Container Manager\":\n\n```yaml\nversion: '3'\n\nservices:\n  hueplanner:\n    image: ghcr.io/dokzlo13/hueplanner\n    container_name: hueplanner\n    restart: unless-stopped\n    user: 1028:65536\n    network_mode: host\n    environment:\n      - TZ=Europe/Berlin\n      - LOG_LEVEL=info\n      - LOG_COLORS=false\n      - HUE_BRIDGE_ADDR=192.168.10.12\n      - HUE_BRIDGE_USERNAME=...\n      - DATABASE_PATH=/app/data/hueplanner.sqlite\n      - CONFIG_FILE=/app/data/hueplanner.yaml\n      - PYTHONUNBUFFERED=1\n    logging:\n      options:\n        max-size: \"100m\"\n        max-file: \"1\"\n    volumes:\n      - /volume0/docker/volumes/hueplanner:/app/data/\n```\n\nAnd here is config file head:\n\n```yaml\nsettings:\n  tz: ${TZ}\n  log:\n    level: ${LOG_LEVEL:info}\n    colors: ${LOG_COLORS:false}\n  database:\n    path: ${DATABASE_PATH}\n  hue_bridge:\n    addr: ${HUE_BRIDGE_ADDR}\n    username: ${HUE_BRIDGE_USERNAME}\nplan: ...\n```\n\n---\n\n\u003e ⚠️**README IS UNDER CONSTRUCTION!** ⚠️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokzlo13%2Fhueplanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdokzlo13%2Fhueplanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokzlo13%2Fhueplanner/lists"}