zzstoatzz.io
this repo has no description
1# solux
2
3circadian lighting for philips hue.
4
5automatically adjusts lights based on sun position. provides entry points for external systems (geofencing, bedtime routines, etc.) to override behavior.
6
7## deploy
8
9```bash
10# install uv
11curl -LsSf https://astral.sh/uv/install.sh | sh
12
13# clone
14git clone https://tangled.org/zzstoatzz.io/solux
15cd solux
16
17# set your hue bridge credentials
18export HUE_BRIDGE_IP=192.168.0.165
19export HUE_BRIDGE_USERNAME=your-username-here
20
21# test it works
22uv run solux status
23
24# connect to prefect cloud (one-time)
25uv run prefect cloud login
26
27# deploy and start worker
28uv run prefect deploy --all
29uv run prefect worker start --pool default
30```
31
32the worker pulls from git and runs every 15 minutes. to run as a service, use systemd or similar.
33
34## cli
35
36```bash
37solux # run once - apply current circadian state
38solux status # show current mode and light state
39solux schedule # show today's lighting phases
40
41solux set <mode> # set mode: auto, away, bedtime, sleep, wake
42solux set away --by geofence
43solux set auto --by geofence # "coming home"
44solux set wake --expires 60 # auto-expires in 60 minutes
45
46solux override --bri 50 # custom brightness
47solux override --off --expires 30 # lights off for 30 minutes
48```
49
50## python api
51
52```python
53from solux.state import Mode, set_mode, override, load_state
54
55# set mode (primary entry point for external systems)
56set_mode(Mode.AWAY, by="geofence")
57set_mode(Mode.AUTO, by="geofence") # arriving home
58set_mode(Mode.BEDTIME, by="shortcut")
59set_mode(Mode.WAKE, by="alarm", expires_in_minutes=60)
60
61# custom override
62override(brightness=50, by="movie-mode", expires_in_minutes=120)
63override(on=False, groups=["bedroom"], by="goodnight")
64
65# read current state
66state = load_state()
67print(state.mode, state.updated_by)
68```
69
70## state file
71
72external systems can write directly to `~/.solux/state.json`:
73
74```json
75{
76 "mode": "away",
77 "updated_by": "geofence",
78 "updated_at": "2024-01-10T20:00:00-06:00",
79 "expires_at": null
80}
81```
82
83## modes
84
85| mode | behavior |
86|------|----------|
87| `auto` | normal circadian rhythm |
88| `away` | lights off (not home) |
89| `bedtime` | dim nightlight |
90| `sleep` | lights off |
91| `wake` | gentle warm light |
92| `override` | custom brightness/color temp |
93
94## phases
95
96lighting phases are anchored to actual sun position (adapts to seasons):
97
98- **dawn** → **sunrise** → **morning** → **midday** → **afternoon**
99- **golden_hour** → **sunset** → **dusk** → **evening** → **night**
100
101the controller interpolates smoothly between phases.
102
103## configuration
104
105| env var | description |
106|---------|-------------|
107| `HUE_BRIDGE_IP` | ip address of your hue bridge |
108| `HUE_BRIDGE_USERNAME` | hue api username ([how to get one](https://developers.meethue.com/develop/get-started-2/)) |