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
Tracks 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

Clone this repository
Install required packages:
```
pip install requests urllib3
```
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",
      "rule2": "1"
    }
  }
}

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

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:

Identify devices matching the unknown device patterns
Check if each device has a toggle button (indicating it's a light switch or power plug)
Toggle the button at 1/2Hz (on/off every two seconds) to help identify the physical device
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
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
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

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.

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.

4.7 KiB Raw Blame History