# solux

circadian lighting for philips hue.

automatically adjusts lights based on sun position. provides entry points for external systems (geofencing, bedtime routines, etc.) to override behavior.

## deploy

```bash
# install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# clone
git clone https://tangled.org/zzstoatzz.io/solux
cd solux

# set your hue bridge credentials
export HUE_BRIDGE_IP=192.168.0.165
export HUE_BRIDGE_USERNAME=your-username-here

# test it works
uv run solux status

# connect to prefect cloud (one-time)
uv run prefect cloud login

# deploy and start worker
uv run prefect deploy --all
uv run prefect worker start --pool default
```

the worker pulls from git and runs every 15 minutes. to run as a service, use systemd or similar.

## cli

```bash
solux                # run once - apply current circadian state
solux status         # show current mode and light state
solux schedule       # show today's lighting phases

solux set <mode>     # set mode: auto, away, bedtime, sleep, wake
solux set away --by geofence
solux set auto --by geofence      # "coming home"
solux set wake --expires 60       # auto-expires in 60 minutes

solux override --bri 50           # custom brightness
solux override --off --expires 30 # lights off for 30 minutes
```

## python api

```python
from solux.state import Mode, set_mode, override, load_state

# set mode (primary entry point for external systems)
set_mode(Mode.AWAY, by="geofence")
set_mode(Mode.AUTO, by="geofence")  # arriving home
set_mode(Mode.BEDTIME, by="shortcut")
set_mode(Mode.WAKE, by="alarm", expires_in_minutes=60)

# custom override
override(brightness=50, by="movie-mode", expires_in_minutes=120)
override(on=False, groups=["bedroom"], by="goodnight")

# read current state
state = load_state()
print(state.mode, state.updated_by)
```

## state file

external systems can write directly to `~/.solux/state.json`:

```json
{
  "mode": "away",
  "updated_by": "geofence",
  "updated_at": "2024-01-10T20:00:00-06:00",
  "expires_at": null
}
```

## modes

| mode | behavior |
|------|----------|
| `auto` | normal circadian rhythm |
| `away` | lights off (not home) |
| `bedtime` | dim nightlight |
| `sleep` | lights off |
| `wake` | gentle warm light |
| `override` | custom brightness/color temp |

## phases

lighting phases are anchored to actual sun position (adapts to seasons):

- **dawn** → **sunrise** → **morning** → **midday** → **afternoon**
- **golden_hour** → **sunset** → **dusk** → **evening** → **night**

the controller interpolates smoothly between phases.

## configuration

| env var | description |
|---------|-------------|
| `HUE_BRIDGE_IP` | ip address of your hue bridge |
| `HUE_BRIDGE_USERNAME` | hue api username ([how to get one](https://developers.meethue.com/develop/get-started-2/)) |