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, and
`first_arrival` with the arriving device ID when an empty house becomes occupied.
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`.