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#

# 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#

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#

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:

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

modes#

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#