From 708a467a6212451ad44099c374cc955124009b5c Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 30 Dec 2025 23:21:42 +1100 Subject: [PATCH] Update README with full documentation --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8bb6541..d6bdc48 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,49 @@ -# opnsense-device-control +# OPNsense Device Control for Home Assistant -OPNsense Device Discovery and Internet Access Control for Home Assistant - MAC-based parental controls with tablet-optimized dashboard \ No newline at end of file +A comprehensive system for discovering, managing, and controlling internet access to devices through OPNsense firewall integration with Home Assistant. + +## Repository + +🔗 **https://gitea.hideawaygaming.com.au/jessikitty/opnsense-device-control** + +## Features + +- **Device Discovery**: Automatically discover all devices on your network +- **MAC-Based Blocking**: Block internet access by MAC address (prevents circumvention) +- **Per-Device Control**: Individual blocking for each device +- **User-Wide Control**: Block all devices for a user with one toggle +- **Tablet-Optimized Dashboard**: Clean, intuitive interface for easy management +- **Multiple MAC Support**: Handle devices with both wired and WiFi connections +- **Real-Time Status**: See which devices are blocked at a glance + +## Quick Start + +1. **Generate OPNsense API credentials** (System → Access → Users) +2. **Configure secrets.yaml** with API key/secret +3. **Run device discovery** script to find all devices +4. **Configure MAC addresses** in Home Assistant +5. **Create firewall aliases and rules** in OPNsense +6. **Install dashboard** for control interface + +## Files + +- `opnsense_device_control.yaml` - Home Assistant configuration +- `lovelace_device_control.yaml` - Tablet-optimized dashboard +- `opnsense_device_manager.py` - Device discovery Python script +- `secrets.yaml.example` - API credentials template +- `FULL_DOCUMENTATION.md` - Complete setup and usage guide + +## Family Configuration + +Pre-configured for: +- **Bella** (14) - Phone + Tablet +- **Xander** (15) - Phone + Desktop +- **William** (17) - Phone + Laptop + +Easily customizable! + +## Network + +- **OPNsense**: 10.0.0.254 +- **Home Assistant**: 10.0.0.55 +- **LAN**: 10.0.0.0/24