home_control/README.md

# home_control

Detects an arrival when an iPhone reconnects to a Zyxel EX5601-T1. The service
logs into the router's encrypted web API and polls its active LAN clients.

1. Install dependencies: `python -m pip install -r requirements.txt`
2. Fill in the router login and the iPhone Wi-Fi MAC address under
   `arrival_detection` in `service.yaml`.
3. Test connectivity: `python service.py --once`
4. Run continuously: `python service.py`

Check any MAC address directly through the Zyxel client with:

```bash
python lib/_zyxel.py --mac AA:BB:CC:DD:EE:FF
```

Omit `--mac` to check the first entry in `arrival_detection.devices` from
`service.yaml`. Arrival detection supports one to three devices and tracks each
device independently.

Set `arrival_detection.zyxel.debug` to `true` to log every Zyxel HTTP/DAL call
and MAC presence result. Under systemd, view these messages with
`journalctl -u home-control.service -f`.

An arrival is logged after the phone was confirmed absent and then present. It
also calls `send_notification()` from `lib/_notify.py`; its message, ntfy topic,
and timeout are configured under the top-level `notify` section. Set
`arrival_detection.enabled` to `false` to disable this function.

Plugins emit dictionaries containing `sender`, `event`, `id`, and `text`. The
controller routes each sender to one or more actions through `controller.plugins`.
For example, `_arrival_detection` emits an `arrived` event and can be routed to
both actions through `on_event: [_notify, _cloud_logger]`. A single action name
such as `on_event: _notify` remains supported.

Arrival detection emits `arrived` and `departed` for individual device IDs. It
also emits `empty` with ID `house` after the last present device departs. Initial
startup state never generates these transition events.

Plugin modules, factories, configuration sections, and event actions are all
declared under `controller`. The controller contains no plugin-specific imports
or startup logic. A plugin module exposes a configured factory (normally
`create`), and an action module exposes a configured handler (normally
`on_event`).

The `_notify` action can filter by event or ID under `notify.filter`. Empty
`accept` lists allow all values; populated lists act as allow-lists. Values in
`ignore` are always rejected, even when also accepted.

On the iPhone, open **Settings > Wi-Fi**, tap the info button beside the home
network, and copy **Wi-Fi Address**. If Private Wi-Fi Address is enabled, that
per-network address is the correct one to configure.

## Install as a systemd service

The included unit expects the project and its virtual environment at
`/opt/home_control`, owned by a dedicated `home-control` system user:

```bash
sudo useradd --system --home-dir /opt/home_control --shell /usr/sbin/nologin home-control
sudo chown -R home-control:home-control /opt/home_control
sudo chmod 600 /opt/home_control/service.yaml
sudo install -d -o home-control -g home-control -m 750 /log
sudo cp /opt/home_control/home-control.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now home-control.service
```

Check its state and follow its logs with:

```bash
sudo systemctl status home-control.service
sudo journalctl -u home-control.service -f
```

Confirmed arrival notifications are also appended to
`/log/detect-arrivals.txt`. The path is configurable as
`arrival_detection.event_log`.