lux

A shell script wrapper around pyluxa4 for controlling the Luxafor USB light.

Manages the pyluxa4 server lifecycle automatically — starts it if not running, then sends your command.

Prerequisites

brew install hidapi bats-core
pip install pyluxa4

AirPlay conflict: pyluxa4 defaults to port 5000, which conflicts with AirPlay Receiver. This script uses port 5001 by default. If you see bind errors, go to System Settings → General → AirPlay & Handoff and disable AirPlay Receiver.

Usage

lux [--verbose] <command> [args]

Commands:
  help            Show help
  color <color>   Set the light color
  strobe <color>  Strobe the light (runs until next command)
  off             Turn off the light
  police          Police light pattern (runs until next command)

Valid colors for 'color':  red blue green cyan magenta yellow white off #RRGGBB
Valid colors for 'strobe': red blue green cyan magenta yellow white #RRGGBB

Options:
  --verbose    Show full server responses and debug info

Examples

lux color red          # solid red
lux color "#FF8000"    # custom orange
lux color off          # turn off via color command
lux off                # turn off via off command
lux strobe blue        # strobe blue
lux police             # police pattern
lux --verbose color green   # show full server response

Exit Codes

Code	Meaning
0	Success
1	Usage error (bad or missing arguments)
2	Server error (failed to start or connect)
3	Command error (pyluxa4 reported failure)

Configuration

All defaults can be overridden with environment variables:

Variable	Default	Description
LUX_PORT	5001	pyluxa4 server port
LUX_TOKEN	batsignal	Auth token
LUX_LOG_DIR	~/.lux	Directory for server logs and PID file
LUX_RETRY_COUNT	3	Number of times to poll after server start
LUX_RETRY_SLEEP	5	Seconds between each poll attempt

Logs

File	Contents
~/.lux/server.log	pyluxa4 server stdout/stderr
~/.lux/server.pid	PID of the running server

Running Tests

bats tests/lux.bats

Tests use a mock pyluxa4 stub — no hardware or running server needed.

Troubleshooting

Server won't start / port already in use

lsof -i :5001          # check what's on the port
python3 -m pyluxa4 kill --token batsignal --port 5001

Device not detected

python3 -m pyluxa4 --version    # verify pyluxa4 is installed

Check server logs

cat ~/.lux/server.log