Buttons and switches are primarily used to toggle (turn ON or OFF) device relays.

A standard device usually has at least one button (exception being bulbs and some lights) to control the relay(s).

Additional buttons and switches can be wired to a free GPIO and configured in Module or Template settings.

Tasmota does not publish the state of the switch in any way. It only sends commands directly to the corresponding relay or to an MQTT topic.

A button (also called a push-button) is a momentary or non-latching switch which causes a temporary change in the state of an electrical circuit only while the switch is pressed. An automatic mechanism (i.e. a spring) returns the switch to its default position immediately afterwards, restoring the initial circuit condition.

A switch (more precisely a latching switch), when activated by the user, remains in that state until activated again.

Both have a similar function but Tasmota distinguishes between a "Button" and a "Switch" in other ways.

By default a button toggles the corresponding relay. Every time the button gets pressed the relay changes Power state (ON or OFF).

Besides toggling the Power state, a button is also used to activate multi press button functions.

See Button-usage on a detailed multi press function list, ButtonTopic options and changing default Button functionality.

• mechanical toggle switch - also called a rocker switch
• capacitive touch switch
• reed switch
• PIR sensor - even though its technically a sensor it is configured as a switch in Tasmota
• mechanical push-button

By default a switch toggles the corresponding relay. Every time the switch gets pressed the relay changes its state (ON or OFF).

Apart from the default toggling of the relay, switches can be configured to do long press (HOLD) actions, send messages to different MQTT topics or commands to other Tasmota devices.

Now to make everything a little confusing:

A built in push-button can be configured as a Switch and a toggle switch can be configured as a Button. We don't recommend to do so, but it is entirely possible!

For visual learners: Tasmota Switchmode Explained - video by Dr Zzs

To change the mode of a switch or button use the SwitchMode command. If there is more than one, use SwitchMode<x> where <x> is the number of your switch or button from GPIO configuration.

SwitchMode 0

Default Tasmota switch mode (toggle)

Sends toggle command on switch press (closing the circuit).

SwitchMode 1

Set switch to follow mode (0 = OFF, 1 = ON)

While pressing the switch (closing the circuit) the button will send ON and when released (open circuit) send OFF .

You want to use SwitchMode 1 when connecting a toggle switch to your device (e.g. a classic light switch). This way the "software switch" will mirror the state of the "hardware switch". If the real switch is in the "ON" position, the state in Tasmota is ON as well.

SwitchMode 2

Set switch to inverted follow mode (0 = ON, 1 = OFF)

While pressing the switch (closing the circuit) the button will send OFF and when released (open circuit) send ON .

SwitchMode 3

Set switch to push-button mode (Default 1 = ON, 0 = toggle)

The switch will send a toggle command when the switch is released (opening the circuit). When pressing the switch (closing the circuit) nothing will happen. Default switch state is ON and when pressed its OFF. (This trigger is known as falling-edge)

SwitchMode 4

Set switch to inverted push-button mode (Default 0 = OFF, 1 = toggle)

The switch will send a toggle command when pressing switch (closing the circuit). When the switch is released (opening the circuit) nothing will happen. Default switch state is OFF and when pressed its ON. (This trigger is known as rising-edge)

When connecting a momentary switch (a push-button) you will want to use SwitchMode 3 or SwitchMode 4.

SwitchMode 5

Set switch to push-button with long press mode (Default 1 = ON, 0 = toggle, long press = HOLD )

The switch will send a toggle command when the switch is released (opening the circuit). When pressing the switch (closing the circuit) nothing will happen. Default switch state is ON and when pressed its OFF.

When held for time set in SetOption32 (default = 4s) sends HOLD message (Use Switch#state=3 in rules).

SwitchMode 6

Set switch to inverted push-button with long press mode (Default 0 = OFF, 1 = toggle, long press = HOLD )

The switch will send a toggle command when pressed (closing the circuit). When the switch is released (opening the circuit) nothing will happen. Default switch state is OFF and when pressed its ON.

When held for time set in SetOption32 (default = 4s) sends HOLD message (Use Switch#state=3 in rules).

Long press or hold can be used in conjunction with rules to create additional features or to control another Tasmota device.

SwitchMode 7

Set switch to toggle PUSHBUTTON (0 = toggle, 1 = toggle)

The switch will send a toggle command when pressed and another toggle command when released.

Not sure why you would use this one, but hey, its here when you need it.

When using SwitchTopic 1 or 2 (or ButtonTopic 1 or 2) and your MQTT broker becomes unavailable, Tasmota falls back to default SwitchTopic 0 (or ButtonTopic 0), which is not optimal.

To avoid this, we recommend using rules. They simply always work!

Example:

Rule1 on switch1#state do publish cmnd/custom-topic/POWER %value% endon
Rule1 1

If you still need to use SwitchTopic or ButtonTopic, read on!

SwitchTopic and ButtonTopic are almost identical in use. You can use this guide interchangeably for both or read ButtonTopic.

SwitchTopic 0

Default option

By default a switch controls the corresponding relay and doesn't send any MQTT messages itself.

No MQTT message will be published on account of the new switch state. The message you see in console is the new state of the relay that is controlled and not the switch state.

SwitchTopic 1

Sets MQTT switch topic to device %topic%

When changing the state of the switch an MQTT message is sent to the device topic with the payload according to SwitchMode set.

Example: Device topic sonoff, SwitchMode 3 yields the following message.

MQT: cmnd/sonoff/POWER = TOGGLE

Notice the cmnd instead of the stat at the beginning.

This is the same as sending an MQTT commands to this device, the device relay will be set to the defined state.

SwitchTopic <value>

Set switch topic to a custom topic (32 characters max)

This will send an MQTT message to a custom defined topic similarly to option 1.

For example, we set the topic to sonoff02 with SwitchTopic sonoff02.

Example: Device topic sonoff, SwitchMode 1, custom topic sonoff02 yields the following message.

MQT: cmnd/sonoff02/POWER = ON

If you have a device with the topic sonoff02 this action will turn on its relay while not affecting anything on the sonoff device.

SwitchTopic 0 controls the relay directly.
SwitchTopic 1 sends an MQTT message to the device topic. This sets the state of the devices relay accordingly.
SwitchTopic <value> sends an MQTT message command to the custom topic. This does not change the state of the devices relay.

For a practical application of everything mentioned in this article read about this excellent LEGO nightstand switch project.