TasmotaManager/README.md

# TasmotaManager

A Python utility for discovering, monitoring, and managing Tasmota devices on a network using UniFi Controller.

## Features

- Discovers Tasmota devices on the network via UniFi Controller API
- Track device changes over time (new, moved, deprecated devices)
- Checks and updates MQTT settings on Tasmota devices
- Generates detailed device information including firmware versions
- Processes unknown devices (matching unknown_device_patterns) to set up names and MQTT

## Requirements

- Python 3.6+
- UniFi Controller with API access
- Network with Tasmota devices

## Dependencies

- requests
- urllib3
- Standard library modules (json, logging, os, sys, datetime, re, time, argparse)

## Installation

1. Clone this repository
2. Install required packages:
   ```bash
   pip install requests urllib3
   ```
3. Create a configuration file (see below)

## Configuration

Create a `network_configuration.json` file with the following structure:

```json
{
  "unifi": {
    "host": "https://your-unifi-controller.local",
    "username": "your-username",
    "password": "your-password",
    "site": "default",
    "network_filter": {
      "network_name": {
        "name": "Human-readable name",
        "subnet": "192.168.1",
        "exclude_patterns": [
          "device-to-exclude*"
        ],
        "unknown_device_patterns": [
          "tasmota*",
          "ESP-*"
        ]
      }
    }
  },
  "mqtt": {
    "Host": "mqtt-broker.local",
    "Port": 1883,
    "User": "mqtt-user",
    "Password": "mqtt-password",
    "Topic": "%hostname_base%",
    "FullTopic": "%prefix%/%topic%/",
    "NoRetain": false,
    "console": {
      "SwitchRetain": "Off",
      "ButtonRetain": "Off",
      "PowerOnState": "3",
      "PowerRetain": "On",
      "SetOption1": "0",
      "SetOption3": "1",
      "SetOption13": "0",
      "SetOption19": "0",
      "SetOption32": "8",
      "SetOption53": "1",
      "SetOption73": "1",
      "rule1": "on button1#state=10 do power0 toggle endon"
    }
  }
}
```

## Usage

Basic usage:
```bash
python TasmotaManager.py
```

With options:
```bash
python TasmotaManager.py --config custom_config.json --debug --skip-unifi
```

Command-line options:
- `--config`: Path to configuration file (default: network_configuration.json)
- `--debug`: Enable debug logging
- `--skip-unifi`: Skip UniFi discovery and use existing current.json
- `--process-unknown`: Process unknown devices (matching unknown_device_patterns) to set up names and MQTT

## Unknown Device Processing

The script can process devices that match patterns in the `unknown_device_patterns` list (like "tasmota_" or "ESP-" prefixed devices). When using the `--process-unknown` flag, the script will:

1. Identify devices matching the unknown device patterns
2. Check if each device has a toggle button (indicating it's a light switch or power plug)
3. Toggle the button at 1/2 Hz (on/off every two seconds) to help identify the physical device
4. **How to enter the hostname:**
   - The script will display a clear prompt in the console showing the current device name and IP address
   - While the device is toggling, you'll see a prompt asking for a new name for the device
   - Type the new hostname directly in the console and press Enter
   - All debug messages are completely suppressed during this process to keep the console clear
5. Once a hostname is entered, the script will:
   - Configure the "Friendly Name 1" field with the new hostname
   - Enable MQTT if not already enabled
   - Configure MQTT settings from the configuration file
   - Save the configuration and reboot the device
6. Move on to the next unknown device

This feature helps automate the setup of new Tasmota devices that haven't been properly named yet.

## Console Parameters

The script supports setting Tasmota console parameters via the `console` section in the MQTT configuration. After verifying and updating MQTT settings, the script will apply all console parameters to each device. This allows you to:

- Configure device behavior (PowerOnState, SetOptions, etc.)
- Set up rules for button actions
- Configure retain flags for various message types
- Apply any other Tasmota console commands

### Retain Parameters Behavior

For all Retain parameters (`ButtonRetain`, `SwitchRetain`, `PowerRetain`), the script automatically sets the opposite state first before applying the final state specified in the configuration. This is necessary because the changes (not the final state) are what create the update of the Retain state at the MQTT server. 

For example, if you specify `"PowerRetain": "On"` in your configuration:
1. The script will first set `PowerRetain Off`
2. Then set `PowerRetain On`

This ensures that the MQTT broker's retain settings are properly updated. The values in the configuration represent the final desired state of each Retain parameter.

### Automatic Rule Enabling

The script automatically enables rules when they are defined. If you include a rule definition (e.g., `rule1`, `rule2`, `rule3`) in the console section, the script will automatically send the corresponding enable command (`Rule1 1`, `Rule2 1`, `Rule3 1`) to the device. This means you no longer need to include both the rule definition and the enable command in your configuration.

For example, this configuration:
```json
{
  "console": {
    "rule1": "on button1#state=10 do power0 toggle endon"
  }
}
```

Will automatically enable rule1 on the device, equivalent to manually sending both:
```
rule1 on button1#state=10 do power0 toggle endon
Rule1 1
```

Each parameter is sent as a command to the device using the Tasmota HTTP API. The device details in `TasmotaDevices.json` will include a `console_status` field indicating whether console parameters were updated.

For detailed documentation of all available SetOptions and other console commands, please refer to the [CONSOLE_COMMANDS.md](CONSOLE_COMMANDS.md) file. This documentation includes:

- Explanations of all SetOptions currently used in the configuration
- Additional useful SetOptions that can be added
- MQTT retain settings
- Power settings
- Rules configuration

The documentation is based on the official [Tasmota Commands Reference](https://tasmota.github.io/docs/Commands/#setoptions).

## Output Files

The script generates several output files:
- `current.json`: List of currently active Tasmota devices
- `deprecated.json`: Devices that were previously active but are no longer present
- `TasmotaDevices.json`: Detailed information about each device, including MQTT and console parameter status

## License

This project is licensed under the MIT License - see the LICENSE file for details.