Switch Input - Switch¶

Plugin details¶

Type: Switch Input

Name: Switch

Status ESP32: NORMAL CLIMATE

Status ESP8266: NORMAL CLIMATE

GitHub: P001_Switch.ino

Maintainer: TD-er

Supported hardware¶

Switch, Door switch, PIR sensor

MQTT Device class¶

(Only available if both MQTT Auto Discovery and Device Class features are included in the build.)

MQTT Device class: Select the Binary Device class that’s to be used for this task device. Device classes marked with ² are ‘two-way’ devices, meaning that the state will be updated when changed, either on the ESPEasy side, or on the MQTT (Home Assistant) side. For the MQTT Device classes switch and outlet, both also marked with ÷, the discovery is marked as switch instead of light.

The default value used is switch, also when not set (empty), and can be updated in Home Assistant by resending the MQTT Discovery.

The available options are based on the Summer 2025 version of this Home Assistant MQTT Binary sensor documentation page and also related to this Home Assistant MQTT Switch device page (though that doesn’t document any Auto Discovery information)

The switch device class shows an On/Off icon, the default icon shown for other light or binary_sensor devices in Home Assistant (HA) can be changed for an alternative in the HA configuration, if desired, after Auto Discovery has created the device there.

Commands available¶

Internal GPIO handling NORMAL CLIMATE

Supported hardware: Relay, Servo motor

Command (GPIO/Value)	Extra information
`GPIO,<GPIO>,<state>` GPIO: 0 … <max supported GPIO pin> State: 2 (HIGH-Z, input) 1 (HIGH, output) 0 (LOW, output)	Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting GPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).
`GPIOtoggle,<GPIO>` GPIO: 0 … <max supported GPIO pin>	Toggle on/off.. Toggle the current (output) state of the given GPIO pin. When executed, it changes the pin mode to output, for output-capable GPIO pins.
`LongPulse,<GPIO>,<state>,<duration>` `LongPulse,<GPIO>,<state>,<duration high>,<duration low>` `LongPulse,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>` GPIO: All GPIO pins with output capabilities State: 1/0 Duration low/high: 1 … 999 S Nr of Repeats: `-1` = continous repeat, `0` = only single pulse	*To send a long* pulse to a certain pin.**. A long pulse is basically the same as the plain pulse. Duration is defined in seconds, which makes it more suitable for longer duration. This command is not blocking, but will send 2 events to start and stop the pulse. This may have some variation depending on the system load of the module. Variation is typically up-to 10 msec, but may be up-to a second, depending on active plugins and controllers performing blocking operations. Changed: 2022/10/15 Added `<duration low>` and repeat functionality On ESP8266 it now uses the way more accurate `startWaveform` function for high/low durations upto 15 seconds. Example: `longpulse,2,1,1,1,-1` Continuous blinking of the onboard LED at 0.5 Hz. (50% duty cycle)
`LongPulse_mS,<GPIO>,<state>,<duration>` `LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>` `LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>` GPIO: All GPIO pins with output capabilities State: 1/0 Duration low/high: 1 … 15000 msec Nr of Repeats: `-1` = continous repeat, `0` = only single pulse	*To send a (non blocking) long* pulse to a certain pin.** A `LongPulse_mS` is the same as the regular `LongPulse`. The only difference is the time base in milliseconds rather than in seconds. Changed: 2022/10/15 Added `<duration low>` and repeat functionality On ESP8266 it now uses the way more accurate `startWaveform` function for high/low durations upto 15 seconds. Example: `longpulse_ms,2,1,500,500,-1` Continuous blinking of the onboard LED at 1 Hz. (50% duty cycle)
`Pulse,<GPIO>,<state>,<duration>` GPIO: All GPIO pins with output capabilities State: 1/0 Duration: 0 … 1000 msec	*To send a short* pulse to a certain pin.** Example to send an active high (1) pulse on GPIO 14 for 500 mSeconds. Pulse duration is in milliseconds. State is 1 or 0. N.B. this is a blocking call, meaning no other actions will be performed during the pulse.
`PWM,<GPIO>,<duty>` `PWM,<GPIO>,<duty>,<duration>` `PWM,<GPIO>,<duty>,<duration>,<frequency>` ESP8266 GPIO: 0 … 15 ESP32 GPIO: All GPIO pins with output capabilities Duty: 0 … 1023 Duration: 100 … 15000 msec (optional) Frequency: 100 … 40000 Hz (optional)	To set a certain PWM level. If you have set a certain GPIO to a PWM level and want to use it as a regular HIGH/LOW pin you need to reset by setting the PWM level to 0. Duration (in msec) parameter will create a fading. Value of 0 will not set a duration. Frequency (in Hz) will be set to 1000 Hz when not given. Frequencies above 30 kHz are not stable and will likely crash the ESP.
`Servo,<servo ID>,<GPIO>,<position>` ESP8266 GPIO: 0 … 15 ESP32 GPIO: All GPIO pins with output capabilities Servo: 1/2 Position: -180 … 180 (see warning below)	To control a servo motor. Builds before 2020/11/22 only supported a maximum of 2 servos. Later builds allow more and no longer need the `servo ID` as a new ID is generated based on the GPIO pin used. To remain compatible with existing rules, the number of parameters has not changed. Warning Most servos are not able to turn full 360°! Normally the servos are able to go from -90° to 90°, some rare servos do allow for -135° to 135°. A position value of 9000 will stop the PWM signal. This can be useful to save energy on servos which do not need power to remain at the same position.
`Monitor,G,<GPIO>` GPIO: 0 … <max supported GPIO pin>	To monitor a GPIO state. By the use of the command you will receive events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.
`UnMonitor,G,<GPIO>` GPIO: 0 … <max supported GPIO pin>	To cancel the monitor of a GPIO state. By the use of the command you will stop receiving events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.
`Status,G,<GPIO>` GPIO: 0 … <max supported GPIO pin>	Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Command (GPIO/Value)

Extra information

GPIO,<GPIO>,<state>

GPIO: 0 … <max supported GPIO pin>

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting GPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

GPIOtoggle,<GPIO>

GPIO: 0 … <max supported GPIO pin>

Toggle on/off.. Toggle the current (output) state of the given GPIO pin. When executed, it changes the pin mode to output, for output-capable GPIO pins.

LongPulse,<GPIO>,<state>,<duration>

LongPulse,<GPIO>,<state>,<duration high>,<duration low>

LongPulse,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>

GPIO: All GPIO pins with output capabilities

State: 1/0

Duration low/high: 1 … 999 S

Nr of Repeats: -1 = continous repeat, 0 = only single pulse

To send a *long* pulse to a certain pin.. A long pulse is basically the same as the plain pulse. Duration is defined in seconds, which makes it more suitable for longer duration. This command is not blocking, but will send 2 events to start and stop the pulse. This may have some variation depending on the system load of the module. Variation is typically up-to 10 msec, but may be up-to a second, depending on active plugins and controllers performing blocking operations.

Changed: 2022/10/15

Added <duration low> and repeat functionality
On ESP8266 it now uses the way more accurate startWaveform function for high/low durations upto 15 seconds.

Example: longpulse,2,1,1,1,-1 Continuous blinking of the onboard LED at 0.5 Hz. (50% duty cycle)

LongPulse_mS,<GPIO>,<state>,<duration>

LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>

LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>

GPIO: All GPIO pins with output capabilities

State: 1/0

Duration low/high: 1 … 15000 msec

Nr of Repeats: -1 = continous repeat, 0 = only single pulse

To send a (non blocking) *long* pulse to a certain pin.

A LongPulse_mS is the same as the regular LongPulse. The only difference is the time base in milliseconds rather than in seconds.

Changed: 2022/10/15

Added <duration low> and repeat functionality
On ESP8266 it now uses the way more accurate startWaveform function for high/low durations upto 15 seconds.

Example: longpulse_ms,2,1,500,500,-1 Continuous blinking of the onboard LED at 1 Hz. (50% duty cycle)

Pulse,<GPIO>,<state>,<duration>

GPIO: All GPIO pins with output capabilities

State: 1/0

Duration: 0 … 1000 msec

To send a *short* pulse to a certain pin. Example to send an active high (1) pulse on GPIO 14 for 500 mSeconds. Pulse duration is in milliseconds. State is 1 or 0. N.B. this is a blocking call, meaning no other actions will be performed during the pulse.

PWM,<GPIO>,<duty>

PWM,<GPIO>,<duty>,<duration>

PWM,<GPIO>,<duty>,<duration>,<frequency>

ESP8266 GPIO: 0 … 15

ESP32 GPIO: All GPIO pins with output capabilities

Duty: 0 … 1023

Duration: 100 … 15000 msec (optional)

Frequency: 100 … 40000 Hz (optional)

To set a certain PWM level. If you have set a certain GPIO to a PWM level and want to use it as a regular HIGH/LOW pin you need to reset by setting the PWM level to 0.

Duration (in msec) parameter will create a fading. Value of 0 will not set a duration.

Frequency (in Hz) will be set to 1000 Hz when not given. Frequencies above 30 kHz are not stable and will likely crash the ESP.

Servo,<servo ID>,<GPIO>,<position>

ESP8266 GPIO: 0 … 15

ESP32 GPIO: All GPIO pins with output capabilities

Servo: 1/2

Position: -180 … 180 (see warning below)

To control a servo motor. Builds before 2020/11/22 only supported a maximum of 2 servos. Later builds allow more and no longer need the servo ID as a new ID is generated based on the GPIO pin used. To remain compatible with existing rules, the number of parameters has not changed.

Warning

Most servos are not able to turn full 360°! Normally the servos are able to go from -90° to 90°, some rare servos do allow for -135° to 135°.

A position value of 9000 will stop the PWM signal. This can be useful to save energy on servos which do not need power to remain at the same position.

Monitor,G,<GPIO>

GPIO: 0 … <max supported GPIO pin>

To monitor a GPIO state. By the use of the command you will receive events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,G,<GPIO>

GPIO: 0 … <max supported GPIO pin>

To cancel the monitor of a GPIO state. By the use of the command you will stop receiving events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.

Status,G,<GPIO>

GPIO: 0 … <max supported GPIO pin>

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Internal GPIO handling NORMAL CLIMATE

Supported hardware: Buzzer (RTTTL), Piezo element, Speaker (Ringtones etc.)

Command (GPIO/Value)	Extra information
`tone,<gpio>,<tone>,<duration>` ESP8266 GPIO: 0 … 16 ESP32 GPIO: All GPIO pins with output capabilities Tone: 20 … 13000 Hz Duration: 100 … 15000 msec	ESP8266: You should try to use GPIO 12…16 since these generally aren’t used. The recommended tone range is 20 Hz … 13 kHz. Up-to 40 kHz should be possible to generate, but will be inaudible for humans. Frequencies above 30 kHz are not stable and will likely crash the ESP. Duration is set in ms. N.B. tones with a duration less than 50 msec will be blocking. Longer duration will use the scheduler, which may cause some fluctuations in the duration.
`rtttl,<gpio>,<value>` ESP8266 GPIO: 0 … 16 ESP32 GPIO: All GPIO pins with output capabilities Value: d=<duration>,o=<octave>,b=<tempo>,<notes…>	ESP8266: You should try to use GPIO 12…16 since these generally aren’t used by ESP internal functions. Value can be defined like <name_of_melody:duration,octave,beat,notes….> For example: `rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-` More RTTTL Ringtone Downloads Since 2023-09-15: The `rtttl` command, by default, now uses the AnyRtttl library, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously. Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.

Command (GPIO/Value)

Extra information

tone,<gpio>,<tone>,<duration>

ESP8266 GPIO: 0 … 16

ESP32 GPIO: All GPIO pins with output capabilities

Tone: 20 … 13000 Hz

Duration: 100 … 15000 msec

ESP8266: You should try to use GPIO 12…16 since these generally aren’t used.

The recommended tone range is 20 Hz … 13 kHz. Up-to 40 kHz should be possible to generate, but will be inaudible for humans. Frequencies above 30 kHz are not stable and will likely crash the ESP.

Duration is set in ms.

N.B. tones with a duration less than 50 msec will be blocking. Longer duration will use the scheduler, which may cause some fluctuations in the duration.

rtttl,<gpio>,<value>

ESP8266 GPIO: 0 … 16

ESP32 GPIO: All GPIO pins with output capabilities

Value: d=<duration>,o=<octave>,b=<tempo>,<notes…>

ESP8266: You should try to use GPIO 12…16 since these generally aren’t used by ESP internal functions.

Value can be defined like <name_of_melody:duration,octave,beat,notes….>

For example: rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-

More RTTTL Ringtone Downloads

Since 2023-09-15:

The rtttl command, by default, now uses the AnyRtttl library, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously.

Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.

Change log¶

Changed in version 2.0: …

added Major overhaul for 2.0 release.

improved 2019/02/26 Changed default name of value from “Switch” to “State”.

Added in version 1.0: …

added Initial release version.