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:

   pip install requests urllib3
   

3. Create a configuration file (see below)

Configuration

Create a network_configuration.json file with the following structure:

{
  "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:

python TasmotaManager.py

With options:

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
• --Device: Process a single device by hostname or IP address

Single Device Processing

The script can process a single device by hostname or IP address using the --Device parameter. When this parameter is provided, the script will:

1. Connect to the UniFi controller to find the device
2. If a hostname is provided, the script will find the corresponding IP address
3. If an IP address is provided, the script will find the corresponding hostname
4. Verify the device is in the correct network (as defined in network_filter)
5. Check if the device is in the exclude_patterns list (if so, processing will be skipped)
6. Check if the device is in the unknown_device_patterns list:
   • If it is, the script will run the unknown device procedure for just this one device
   • If not, the script will run the normal MQTT configuration procedure for just this one device
7. Save the device details to TasmotaDevices.json

Hostname Matching Features

When using a hostname with the --Device parameter, the script supports:

• Exact matching: The provided hostname matches exactly (case-insensitive)
• Partial matching: The provided hostname is contained within a device's hostname
  • Example: --Device Master will match devices named "MasterLamp-5891" or "MasterBedroom"
• Wildcard matching: The provided hostname contains wildcards (*) that match any characters
  • Example: --Device Master* will match "MasterLamp-5891" but not "BedroomMaster"
  • Example: --Device *Lamp* will match any device with "Lamp" in its name

If multiple devices match the provided hostname pattern, the script will:

1. Log a warning showing all matching devices
2. Automatically use the first match found
3. Continue processing with that device

This feature is useful for:

• Setting up or updating a single new device without processing all devices
• Troubleshooting a specific device
• Quickly checking if a device is properly configured
• Working with devices when you only remember part of the hostname

Example usage:

python TasmotaManager.py --Device mydevice.local
# or
python TasmotaManager.py --Device 192.168.8.123
# Partial match example
python TasmotaManager.py --Device Master
# Wildcard match example
python TasmotaManager.py --Device *Lamp*

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

Command Retry Logic and Error Handling

When setting console commands, the script implements robust error handling with automatic retry logic:

• If a command times out or fails, the script will automatically retry up to 3 times
• Between retry attempts, the script waits for 1 second before trying again
• After 3 failed attempts, the command is marked as failed and the script continues with other commands
• All command failures are tracked and a summary is displayed at the end of execution
• The failure summary is grouped by device and shows which commands failed and the specific errors

This retry mechanism helps handle temporary network issues or device busy states, making the script more reliable in real-world environments with potentially unstable connections.

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:

{
  "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 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.

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.