homebridge-tasmota-commands

Tasmota Commands Homebridge Plugin

• Tasmota Commands Homebridge Plugin
  • Overview
  • Features
  • Install
    • With Config UI X:
    • NPM
  • Configuration
    • Common parameters
    • Protocol parameters (http)
    • Protocol parameters (mqtt, experimental)
    • Preset parameters
  • Roadmap
  • Setup Development Environment
    • Install Development Dependencies
    • Build Plugin
    • Running Homebridge and Watching For Changes
  • Contribution
  • License

Overview

Homebridge plugin for controlling Tasmota devices. Currently in early development.

Features

This plugin currently supports following features:

• [x] Switch
  • [x] On/off
• [x] Lightbulb
  • [x] On/off
  • [x] Brightness
  • [x] Brightness and Color Temperature
• [x] Custom
  • [x] Set device type
  • [x] Set characteristics

For planned features see roadmap.

Install

With Config UI X:

1. Search "homebridge-tasmota-commands" from the Plugins tab
2. Install the plugin and configure accessories using the UI

NPM

1. npm install -g homebridge-tasmota-commands
2. Update your configuration file, see configuration

Configuration

Sample configuration using preset

  "accessories": [
    {
      "name": "Lightbulb (on/off)",
      "protocol": "http",
      "preset": "lightbulb-on-off",
      "address": "127.0.0.1",
      "accessory": "tasmota-commands"
    }
  ]
}

Sample configuration using custom preset

  "accessories": [
    {
      "name": "Custom",
      "protocol": "http",
      "preset": "custom",
      "type": "lightbulb",
      "customPresetCharacteristics": ["On"],
      "address": "127.0.0.1",
      "accessory": "tasmota-commands"
    }
 ]

Common parameters

Parameter	Required	Accepted values	Description
name	yes	Valid Homebridge accessory name
refreshInterval	no	number	Refresh interval in seconds. Set to 0 or undefined to disable. Disabled by default.

Protocol parameters (http)

Parameter	Required	Accepted values	Description
protocol	yes	http
address	if protocol is http	IP Address or address to device without http(s)://, e.x. mydevice.local
username	no	Valid Tasmota username
password	no	Valid Tasmota password

Protocol parameters (mqtt, experimental)

Parameter	Required	Accepted values	Description
protocol	yes	mqtt
host	yes	brokerUrl with protocol	only tcp:// is currently supported, e.g. tcp://127.0.0.1
topic	yes	string	Topic from Tasmota MQTT parameters
topicFormat	yes	topic format string which includes %prefix%, %prefix% and <command>	Full Topic from Tasmota MQTT parameters with added <command>, usually to end of string e.g. %prefix%/%topic%/<command>
port	no	number	Broker port e.g. 1883
username	no	username	Broker username, if any
password	no	password	Broker password, if any
connectOnInit	no	boolean	Defaults to true. Create connection to broker on init.

Preset parameters

Parameter	Required	Accepted values	Description
preset	yes	switch-on-off, lightbulb-on-off, lightbulb-brightness, lightbulb-brightness-ct, lightbulb-rgb, custom	Predefined characteristic sets. Using custom you can manually set what characteristics to use.
type	if preset is custom	lightbulb, switch	Device type
customPresetCharacteristics	if preset is custom	Set/array of On, Brightness, ColorTemperature, Hue, Saturation	Note that not all of characteristics may not work together with each other

Roadmap

Setup Development Environment

You must have Node.js 14 or later installed. This plugin is written with Typescript. This package is part of tasmota-commands monorepo and is using Yarn v2 as package manager with workspaces.

Install Development Dependencies

Navigate to the project folder and install dependencies with yarn

yarn install

Build Plugin

Typescript needs to be compiled into Javascript before it can be used. Following command compiles contents in src into dist. Plugin is depending of two packages in this monorepo, tasmota-commands-core and tasmota-commands-http which should be automatically built during dependency installation.

yarn build

Running Homebridge and Watching For Changes

You can run homebridge in debug mode with Config UI X and watch for changes by running:

yarn dev

Example configuration is here. Homebridge reads configuration from ~/.homebridge/config.json, you may need to setup the Config UI X on first time. There is no need for linking this package to global node_modules, yarn workspaces should link it automatically and it should appear in Plugins tab in the Config UI X.

Contribution

License

MIT