Pushing saves

README.md

@@ -1,8 +1,159 @@
-# Sample GitLab Project
+# Tasmota Device Manager
 
-This sample project shows how a project in GitLab looks for demonstration purposes. It contains issues, merge requests and Markdown files in many branches,
+A tool for discovering, configuring, and managing Tasmota devices on a network.
-named and filled with lorem ipsum.
 
-You can look around to get an idea how to structure your project and, when done, you can safely delete this project.
+## Device Discovery Script
 
-[Learn more about creating GitLab projects.](https://docs.gitlab.com/ee/gitlab-basics/create-project.html)
+The `discover_devices.py` script implements the Device Discovery process for Tasmota devices on a network. It connects to a Unifi Switch, retrieves a list of connected devices, and filters for potential Tasmota devices based on network_filter information in the config file.
+
+### Features
+
+- Connects to Unifi Switch using configured credentials
+- Retrieves list of all connected devices
+- Filters devices based on network and subnet configuration
+- Classifies devices into three categories:
+  - Valid hostname devices (ready for configuration)
+  - Default hostname devices (need proper naming)
+  - Deprecated devices (no longer available)
+- Generates JSON files for each device category
+- Provides detailed logging
+- Supports debug mode for troubleshooting
+
+### Prerequisites
+
+- Python 3.8+
+- Network access to Unifi Switch
+- API Key for the Unifi Switch
+- Network access to all potential Tasmota devices
+
+### Installation
+
+1. Clone this repository
+2. Create and activate a virtual environment:
+   ```
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+3. Install dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+4. Configure access credentials in `config.yaml` (see Configuration section)
+
+### Configuration
+
+Create a `config.yaml` file with the following structure:
+
+```yaml
+unifi:
+  type: UDMSE     # Unifi Dream Machine SE
+  host: https://192.168.6.1
+  port: 8443  # Default Unifi Controller port
+  API_Key: "nIfTdZAXVUGQgyNqsATluTja-noaNLAk"  # API Key for Unifi Controller
+  
+  network_filter: 
+    NoT_network:
+      name: "NoT"
+      subnet: "192.168.8"
+      exclude_patterns:
+        - "homeassistant*"
+        - "*sonos*"
+      default_name_patterns:
+        - "tasmota*"
+        - "ESP-*"
+
+tasmota:
+  mqtt_settings: 
+    host: "homeassistant.NoT.mgeppert.com"
+    port: 1883
+    user: "mgeppert"
+    password: "mgeppert"
+    topic: "%hostname_base%"
+    full_topic: "%prefix%/%topic%/"
+    no_retain: false  
+
+other_settings:  # Yet to be defined
+```
+
+### Usage
+
+Run the device discovery script:
+
+```
+python discover_devices.py
+```
+
+#### Command-line Options
+
+- `-h, --help`: Show help message and exit
+- `-d, --debug`: Enable debug mode with verbose logging
+- `-c, --config`: Specify a custom config file path (default: config.yaml)
+
+### Output Files
+
+The script generates the following JSON files:
+
+- `valid_hostnames.json`: Devices with valid hostnames that can be configured
+- `default_hostnames.json`: Devices with default hostnames that need proper naming
+- `deprecated_hostnames.json`: Devices that were previously valid but are no longer available
+
+### Logging
+
+Logs are stored in the `logs/` directory:
+
+- `discovery.log`: Device discovery process logs
+
+Log level is set to INFO by default, or DEBUG when using the `-d` flag.
+
+## Next Steps
+
+After running the device discovery script:
+
+1. For devices with default hostnames, assign proper hostnames based on location and function
+2. For devices with valid hostnames, proceed with configuration auditing and standardization
+
+## Testing
+
+The project includes scripts to verify and test the device discovery functionality without requiring the actual dependencies to be installed.
+
+### Syntax Verification
+
+To verify the syntax of the device discovery script without running it:
+
+```
+python verify_syntax.py
+```
+
+This will check that the script has valid Python syntax without executing it or requiring any dependencies.
+
+### Functional Testing
+
+To test the core functionality of the device discovery script with mocked dependencies:
+
+```
+python test_discovery.py
+```
+
+This script mocks the external dependencies (yaml, requests, urllib3) and tests:
+- Pattern matching functionality
+- Device filtering based on network and subnet
+- Device classification into valid and default hostname groups
+
+The test script uses sample device data to simulate the discovery process and verify that the filtering and classification logic works correctly.
+
+## Troubleshooting
+
+### Common Issues
+
+- **No devices retrieved from Unifi Controller**: Check Unifi credentials and network connectivity
+- **No devices match the filter criteria**: Check network_filter configuration in config.yaml
+- **Error loading configuration**: Verify config.yaml syntax and structure
+- **Missing dependencies**: Make sure to install all required packages from requirements.txt
+
+### Debug Mode
+
+Run the script with the `-d` flag to enable debug mode with verbose logging:
+
+```
+python discover_devices.py -d
+```