# Home Network Intelligence & Automation Plan

## Context

Probed the `192.168.2.0/24` network from `jamess-mac-mini` (192.168.2.149). Discovered **28 unique devices** across five categories: Ubiquiti network infrastructure, Apple ecosystem, Sonos audio system, Samsung TV, and IoT/unknown devices. The Mac Mini already runs Tailscale (100.109.142.115), making it the ideal always-on hub. Plan: deploy Home Assistant via Docker on the Mac Mini, integrate every identifiable device, and layer in custom tooling for things HA can't do natively.

---

## Device Inventory

### Network Infrastructure
| IP | Device | MAC / Notes |
|----|--------|-------------|
| 192.168.2.1 | TP-Link Router (gateway) | 98:25:4A — `/webpages/login.html` fingerprint |
| 192.168.2.102 | Ubiquiti device (switch?) | 54:EF:44 — UP, no open ports |
| 192.168.2.108 | Ubiquiti UniFi AP | 80:CC:9C — lighttpd/uhttpd, UPnP |
| 192.168.2.113 | Ubiquiti UniFi Camera | 54:EF:44 — RTSP on :8554 |
| 192.168.2.119 | Ubiquiti UniFi AP | 80:CC:9C — lighttpd/uhttpd, UPnP |
| 192.168.2.120 | Ubiquiti UniFi AP | 80:CC:9C — lighttpd/uhttpd, UPnP |

### Apple Ecosystem
| IP | Device | Notes |
|----|--------|-------|
| 192.168.2.101 | Apple TV 4K 1st Gen — "Main Bedroom" | AppleTV11,1 · AirTunes/950.6.1 |
| 192.168.2.111 | Apple TV 4K 3rd Gen — "Living Room" | AppleTV14,1 · AirTunes/950.5.2 |
| 192.168.2.115 | HomePod mini — "Bathroom" | AudioAccessory5,1 · AirTunes/950.6.1 |
| 192.168.2.118 | HomePod (1st gen) — "Office" | AudioAccessory1,1 · AirTunes/940.23.1 |
| 192.168.2.138 | Apple device (iPhone/iPad) | A8:4A:63 OUI — no open ports |
| 192.168.2.149 | Mac Mini — "jamess-mac-mini" | Tailscale 100.109.142.115 · dual NIC |

### Sonos Audio System
| IP | Device | Model |
|----|--------|-------|
| 192.168.2.105 | Sonos Sub 4 — "Sub 4" | S55/ZPS55 |
| 192.168.2.134 | Sonos Arc — "Living Room" | S19/ZPS19 |
| 192.168.2.143 | Sonos One — "Kitchen" | S18/ZPS18 |
| 192.168.2.144 | Sonos One — "Kitchen" (stereo pair) | S18/ZPS18 |

### Entertainment
| IP | Device | Notes |
|----|--------|-------|
| 192.168.2.142 | Samsung QN65S90CDFXZA — 65" OLED TV | Tizen OS · REST API on :8001/:8002 · `name: "65\" OLED"` |

### Peripherals & IoT
| IP | Device | Notes |
|----|--------|-------|
| 192.168.2.122 | Brother HL-L2395DW Laser Printer | `debut/1.30` server · :80/:443/:9100 |
| 192.168.2.109 | ESP32 IoT device | Espressif D4:8C:49 — likely smart plug/sensor |
| 192.168.2.110 | ESP32 IoT device | Espressif E4:FA:C4 |
| 192.168.2.112 | ESP32 IoT device | Espressif E4:FA:C4 |
| 192.168.2.123 | GIGABYTE PC/device | 28:A0:6B — no open ports (firewall?) |
| 192.168.2.125 | Unknown device | 74:84:69 OUI |
| 192.168.2.128 | Realtek device | 00:E0:4C — possibly NAS or Pi |
| 192.168.2.127/130/131/132 | Mobile devices | Random/locally-administered MACs → phones/laptops |

### Remote
| Device | Tailscale IP |
|--------|-------------|
| Mac Mini | 100.109.142.115 |
| iphone171 (James's iPhone) | 100.74.68.20 |

---

## Per-Device Actions & Capabilities

### TP-Link Router (.1)
- Monitor bandwidth usage per client
- Reboot/apply config via `tplink-router` Python lib or TPLINK LAN API
- Device allowlist/blocklist
- Port forwarding management

### Ubiquiti UniFi (3× APs + switch + camera)
- **Requires**: UniFi Network Application (controller) running — can run in Docker on Mac Mini
- Client presence detection → "who's home" (device connected to AP = person home)
- Per-client bandwidth stats
- Guest network toggling
- AP radio health monitoring
- **Camera (.113)**: RTSP stream `rtsp://192.168.2.113:8554/` → record to Mac Mini, motion detection in HA, push notifications, remote viewing via Tailscale

### Apple TV 4K (2×)
- Pair via `pyatv` library → full control: play/pause, volume, app launching, input
- Power on/off
- Display custom dashboard as screensaver
- "Now playing" status in HA
- Push TTS or alerts to the TV display

### HomePod mini + HomePod (2×)
- AirPlay 2 streaming (HA built-in via `pyatv`)
- Multi-room audio synchronized with Sonos
- TTS announcements room-by-room
- Volume control per room
- HomeKit scenes (if HomeKit integration set up)

### Sonos Arc + Sub 4 + 2× One
- Sonos HTTP API (no auth, fully local): `http://192.168.2.134:1400/`
- Room grouping/ungrouping → party mode
- Per-room or whole-home volume
- TTS announcements (HA `tts.speak` service)
- Alarm/wake routines
- Home theater mode: Arc + Sub 4 locked to "Living Room" group
- Now-playing metadata (artist/album/track)

### Samsung 65" OLED TV (.142)
- Local REST API: `http://192.168.2.142:8001/api/v2/`
- Local WebSocket API on :8002 → `samsungtvws` Python lib
- Power on/off, volume, input switching
- Launch apps (Netflix, YouTube, Plex, etc.)
- Display HA dashboard in full screen (browser app)
- Detect if TV is on → trigger automations ("movie mode")
- SmartThings cloud API as fallback

### Brother HL-L2395DW (.122)
- Web interface at `http://192.168.2.122/` (XHTML, no auth)
- SNMP (UDP 161) for toner level, page count, status
- Port 9100 = raw print
- HA sensor: toner remaining %, print job count
- Alert when toner < 10%

### ESP32 Devices (.109, .110, .112)
- Likely: Shelly smart plugs/relays OR ESPHome sensors
- **If Shelly**: local HTTP API `http://<ip>/status` → power monitoring, on/off
- **If ESPHome**: native HA integration, entity auto-discovery
- **If Tasmota**: MQTT control
- Action: identify by flashing LED test or checking Shelly/Tasmota/ESPHome fingerprints after HA integration

### GIGABYTE PC (.123)
- Wake-on-LAN (send magic packet from Mac Mini)
- Remote shutdown via SSH (if SSH enabled)
- File sharing via SMB

### Realtek device (.128)
- Likely NAS or Raspberry Pi — investigate via HA device tracker
- If NAS: mount as media source for HA/Plex
- If Pi: could run additional services

### Mobile devices / iPhones
- HA companion app → precise presence detection
- Location-based automations ("I'm home" → turn on lights/TV/music)
- Push notifications from HA to iPhone via companion app
- Already on Tailscale (iphone171) → can reach HA from anywhere

---

## What We Can Build

### 1. Home Intelligence Hub (Foundation)
Deploy Home Assistant in Docker on Mac Mini. All other systems plug into this.
- **File**: `~/projects/home_network_exploration/docker-compose.yml`
- Accessible at `http://jamess-mac-mini.tailnet-XXXX.ts.net:8123` from anywhere

### 2. Network Presence & Security Monitor
- UniFi integration → live client list, signal strength, AP load
- New-device alert: unknown MAC joins network → push to iPhone
- "Who's home" detection: James's iPhone (Tailscale + HA companion app) + WiFi probe
- Network health dashboard panel in HA
- Camera feed widget (UniFi .113 RTSP → HA camera entity)

### 3. Whole-Home Audio System
- Unified Sonos + AirPlay under one HA media player
- Rooms: Living Room (Arc+Sub4), Kitchen (One×2), Main Bedroom (Apple TV), Bathroom (HomePod mini), Office (HomePod)
- Scenes:
  - **Party Mode**: group all Sonos + AirPlay rooms
  - **Morning Alarm**: fade in music in bedroom + kitchen at set time
  - **Good Night**: fade out all audio rooms
- TTS pipeline: HA → Sonos/HomePod → announcement in chosen room(s)

### 4. Smart TV Automation
- Samsung TV + Apple TV unified under HA
- Scenes:
  - **Movie Night**: TV on → Living Room Sonos muted (Arc takes over) → dim (if lights integrated later) → Apple TV to correct input
  - **Morning News**: TV on at 7am on weekdays → specific app
- "TV is on" sensor → block vacuum/robot (future) → silence HomePod

### 5. Security System
- UniFi camera RTSP → HA camera card + motion binary sensor (via ffmpeg)
- Motion detected → push notification to iPhone with snapshot
- Record clips to `~/projects/home_network_exploration/recordings/`
- View camera remotely via HA + Tailscale

### 6. Custom CLI / Python Layer
- `home.py` CLI: `python home.py sonos living-room play`, `python home.py tv off`, `python home.py camera live`
- Scripts for things HA can't do: UniFi direct API calls, Samsung app launch
- Webhook bridge: expose endpoints for shell triggers

### 7. Full-Screen Dashboard on Samsung TV
- HA Lovelace dashboard → displayed in TV's web browser
- Panels: who's home, now playing (Sonos), camera thumbnail, weather, printer status

---

## Recommended Implementation Order

### Phase 1 — Foundation (Day 1)
1. Install Docker + Docker Compose on Mac Mini
2. Create `~/projects/home_network_exploration/docker-compose.yml` with:
   - Home Assistant (image: `ghcr.io/home-assistant/home-assistant:stable`)
   - Optional: UniFi Network Application container (if no existing controller)
3. First boot HA, create user
4. Assign static DHCP leases for all identified devices (via router)

### Phase 2 — Device Integrations (Days 2–3)
In HA Settings → Integrations, add:
5. **Sonos** — auto-discovers all 4 devices
6. **Apple TV** — pair with each Apple TV (need to enter PIN shown on screen)
7. **Samsung Smart TV** — enter IP, accept TV prompt
8. **UniFi** — enter controller URL + credentials
9. **Brother Printer** — SNMP integration or custom sensor via `requests` to web UI
10. **ESPHome / Shelly** — probe .109/.110/.112 to identify and add

### Phase 3 — Automations (Days 3–4)
11. Presence detection: HA companion app on iPhone → `person.james`
12. Automations:
    - `new_device_on_network` → iPhone notification
    - `morning_alarm` → Sonos fade-in
    - `movie_night` → Samsung TV + Arc scene
    - `away_mode` → Sonos pause all
    - `camera_motion` → iPhone snapshot notification

### Phase 4 — Custom Tooling (Days 4–5)
13. `network_scanner.py` — runs on schedule, compares ARP to known device list, alerts on unknown
14. `home_cli.py` — wrapper CLI for common actions
15. `camera_recorder.py` — RTSP → ffmpeg → save 30s clips on motion

### Phase 5 — Dashboard (Day 5+)
16. Build HA Lovelace dashboard
17. Bookmark as full-screen app on Samsung TV browser
18. Add Tailscale DNS hostname for easy access from anywhere

---

## Critical Files to Create
```
~/projects/home_network_exploration/
├── docker-compose.yml          # HA + optional UniFi controller
├── homeassistant/
│   └── configuration.yaml      # HA config overrides
├── scripts/
│   ├── network_scanner.py      # ARP-based device monitor
│   ├── home_cli.py             # Quick CLI for device control
│   └── camera_recorder.py      # RTSP clip recording
├── recordings/                 # Camera clips
└── DEVICES.md                  # Living device inventory (auto-updated)
```

## Key Libraries / Tools
- `soco` — Sonos Python API (local HTTP, no auth)
- `pyatv` — Apple TV + HomePod control
- `samsungtvws` — Samsung TV WebSocket API
- `unifi` / `pyunifi` — UniFi controller API
- Home Assistant integrations: `sonos`, `apple_tv`, `samsungtv`, `unifi`, `brother`, `esphome`

## Verification
- HA dashboard loads at `http://192.168.2.149:8123`
- All devices show as entities in HA
- `python home_cli.py sonos list` shows all 4 Sonos devices
- `python home_cli.py camera snapshot` saves a frame from UniFi camera
- Tailscale access: `http://100.109.142.115:8123` works from iPhone
- Motion on camera → push notification arrives on iPhone within 30s