Add Home Assistant network control API

README.md

@@ -43,6 +43,12 @@ You can also tune:
 - `MIN_VALUE`
 - `REQUEST_TIMEOUT`
 
+Network control settings:
+
+- `CONTROL_HOST`: bind address for the control API, default `0.0.0.0`
+- `CONTROL_PORT`: bind port for the control API, default `8765`
+- `CONTROL_TOKEN`: optional shared token required for control requests
+
 ## Run
 
 ```bash
@@ -96,9 +102,84 @@ make uninstall-service
 
 This is installed as a user service because `playerctl` needs access to the desktop user's MPRIS session.
 
+## Home Assistant Control
+
+The running script exposes a small HTTP API that Home Assistant can call over the local network:
+
+- `GET /status`
+- `POST /pause`
+- `POST /resume`
+- `POST /toggle`
+
+When paused, the systemd service stays running but the script stops changing the light. When resumed, it forces an update from the current track.
+
+Example requests from another machine on the same network:
+
+```bash
+curl http://ubuntu-host:8765/status
+curl -X POST http://ubuntu-host:8765/pause
+curl -X POST http://ubuntu-host:8765/resume
+curl -X POST http://ubuntu-host:8765/toggle
+```
+
+If you set `CONTROL_TOKEN`, include it as a header:
+
+```bash
+curl -X POST -H "X-Music-Light-Token: your-token" http://ubuntu-host:8765/toggle
+```
+
+Home Assistant `configuration.yaml` example:
+
+```yaml
+rest_command:
+  music_light_pause:
+    url: "http://ubuntu-host:8765/pause"
+    method: post
+  music_light_resume:
+    url: "http://ubuntu-host:8765/resume"
+    method: post
+  music_light_toggle:
+    url: "http://ubuntu-host:8765/toggle"
+    method: post
+```
+
+With `CONTROL_TOKEN`:
+
+```yaml
+rest_command:
+  music_light_toggle:
+    url: "http://ubuntu-host:8765/toggle"
+    method: post
+    headers:
+      X-Music-Light-Token: "your-token"
+```
+
+Create Home Assistant scripts so they can be shown as dashboard buttons:
+
+```yaml
+script:
+  pause_music_light:
+    alias: Pause Music Light
+    sequence:
+      - service: rest_command.music_light_pause
+
+  resume_music_light:
+    alias: Resume Music Light
+    sequence:
+      - service: rest_command.music_light_resume
+
+  toggle_music_light:
+    alias: Toggle Music Light
+    sequence:
+      - service: rest_command.music_light_toggle
+```
+
+Then add `script.pause_music_light`, `script.resume_music_light`, or `script.toggle_music_light` to a Home Assistant dashboard as button cards.
+
 ## Troubleshooting
 
 - If nothing is playing, or `playerctl` cannot read metadata, the loop sleeps and retries.
 - If `mpris:artUrl` is missing, the script logs it and waits for the next track change.
 - If Home Assistant is unreachable or returns an error, the script logs the exception and retries.
 - If the service cannot see the media player, make sure it is running under the same logged-in desktop user.
+- If Home Assistant cannot reach the control API, check the Ubuntu host firewall and confirm `CONTROL_HOST=0.0.0.0`.