Skip to content

Expanding Sonoffs

Michael Ingraham edited this page Apr 7, 2019 · 29 revisions

One capability of Tasmota is that you can connect additional things to available pins on the ESP8266 that controls these devices.

If a pin is defined as GPIO_USER in the module template, you can assign it one of the following functions (as of 3/9/17 version 4.0.3):

* GPIO_NONE,           // Not used
* GPIO_DHT11,          // DHT11
* GPIO_DHT21,          // DHT21, AM2301
* GPIO_DHT22,          // DHT22, AM2302, AM2321
* GPIO_DSB,            // Single wire DS18B20 or DS18S20
* GPIO_I2C_SCL,        // I2C SCL
* GPIO_I2C_SDA,        // I2C SDA
* GPIO_WS2812,         // WS2812 Led string
* GPIO_IRSEND,         // IR remote
* GPIO_SWT1,           // User connected external switches
* GPIO_KEY1,           // Button usually connected to GPIO0
* GPIO_REL1,           // Relays (0 = off, 1 = on)
* GPIO_REL1_INV,       // Relays with inverted signal control (0 = on, 1 = off)
* GPIO_LED1,           // Leds (0 = off, 1 = on)
* GPIO_LED1_INV,       // Leds with inverted signal control (0 = on, 1 = off)

To make a link between the different naming schemes of pins, connectors and logical functions, the Pin Definition overview in the esp8266 wiki is quite helpful.


Don't use GPIO: 0, 1, 2, 6-11, 15, 16 if you can avoid it. 3 is RX, so best to avoid also (PWM not working here). That leaves 4, 5, 12, 13, 14 that don't have constraints. The others can be used, but you have to mind the constraints.


Connect switch

If you take a Sonoff Basic and connect a switch between pin4 (ground) and pin5 (GPIO14) of the 5 pin programming header you now have a second switch connected to the device. You can set this through the module config page as option 09 Switch1 or from the command line with gpio14 9.

If you have fewer than two relays on the module, the additional switch(es) will not show up any different than the built-in switch and will control the single relay unless you set switchtopic to something other than 0 (either 1 or a custom topic). Once this is done the built-in switch will produce stat/<topic>/POWER1 while the new switch will produce cmnd/<switchtopic>/POWER1

With more relays on the modules, the additional switch will create additional POWER<n> events without the need to set switchtopic.

You can set the mode of each switch individually with switchmode1 or switchmode2

See Buttons-and-Switches for more information.

Connect jack

Instead of connecting a switch, you could connect a 4-pin 2.5mm jack, with the pins wired:

  • tip pin5 (GPIO14)
  • r1 no connection
  • r2 pin1 (ground)
  • r3 pin4 (3.3V)

You can then plug a sensor into the jack like you would to a Sonoff TH10/TH16 and define what sensor you have connected to GPIO14

On the sonoff TH10/TH16 version 2.1 devices, the r1 is wired to GPIO4. No soldering required.

Electrical considerations

When you switch a GPIO pin to an input and hang a long wire off of it, that wire can pick up stray signals and cause the voltage on the GPIO pin to vary. This can cause the system to think the switch has changed.

To fix this, there are several things you can do.

  1. add a pull-up resistor
  2. add a bypass capacitor
  3. shielding on the wire
  4. use twisted pair wiring

A pull-up resistor is a resistor connected between the GPIO pin and 3.3v. The exact value of this is not critical, 4.7k is a common value to use, as is 10k. This ensures that when the switch it open, the GPIO pin will go high.

A bypass capacitor is a small (pF range) capacitor that is connected between the GPIO and ground. This provides a path for any radio signals that are picked up by the wire to go to ground and not confuse the system.

Shielding or using twisted pair wiring are other ways to reduce the effect of radio signals on the system.

Example for 10K Resistor: Read here: #2708

If the Sensor is connected, go on here: Sensor Configuration

The ESP8266 - Hardware

Digital I/O

Just like a normal Arduino, the ESP8266 has digital input/output pins (I/O or GPIO, General Purpose Input/Output pins). As the name implies, they can be used as digital inputs to read a digital voltage, or as digital outputs to output either 0V (sink current) or 3.3V (source current).

Voltage and current restrictions

The ESP8266 is a 3.3V microcontroller, so its I/O operates at 3.3V as well. The pins are not 5V tolerant, applying more than 3.6V on any pin will kill the chip.

The maximum current that can be drawn from a single GPIO pin is 12mA.

Usable pins

The ESP8266 has 17 GPIO pins (0-16), however, you can only use 11 of them, because 6 pins (GPIO 6 - 11) are used to connect the flash memory chip. This is the small 8-legged chip right next to the ESP8266. If you try to use one of these pins, you might crash your program.

GPIO 1 and 3 are used as TX and RX of the hardware Serial port (UART), so in most cases, you can’t use them as normal I/O while sending/receiving serial data.

Boot modes

Some I/O pins have a special function during boot: They select 1 of 3 boot modes:

0V 0V 3.3V Uart Bootloader
0V 3.3V 3.3V Boot sketch (SPI flash)
3.3V x x SDIO mode (not used for Arduino)

Note: you don’t have to add an external pull-up resistor to GPIO2, the internal one is enabled at boot.

We have to be sure that these conditions are met by adding external resistors, or the board manufacturer of your board has added them for you. This has some implications, however:

GPIO15 is always pulled low, so you can’t use the internal pull-up resistor. You have to keep this in mind when using GPIO15 as an input to read a switch or connect it to a device with an open-collector (or open-drain) output, like I²C. GPIO0 is pulled high during normal operation, so you can’t use it as a Hi-Z input. GPIO2 can’t be low at boot, so you can’t connect a switch to it. Internal pull-up/-down resistors GPIO 0-15 all have a built-in pull-up resistor, just like in an Arduino. GPIO16 has a built-in pull-down resistor.


Unlike most Atmel chips (Arduino), the ESP8266 doesn’t support hardware PWM, however, software PWM is supported on all digital pins. The default PWM range is 10-bits @ 1kHz, but this can be changed (up to >14-bit@1kHz). Check Restrictions.

Analog input

The ESP8266 has a single analog input, with an input range of 0 - 1.0V. If you supply 3.3V, for example, you will damage the chip. Some boards like the NodeMCU have an on-board resistive voltage divider, to get an easier 0 - 3.3V range. You could also just use a trimpot as a voltage divider.

The ADC (analog to digital converter) has a resolution of 10 bits.



The ESP8266 has two hardware UARTS (Serial ports): UART0 on pins 1 and 3 (TX0 and RX0 resp.), and UART1 on pins 2 and 8 (TX1 and RX1 resp.), however, GPIO8 is used to connect the flash chip. This means that UART1 can only transmit data.

UART0 also has hardware flow control on pins 15 and 13 (RTS0 and CTS0 resp.). These two pins can also be used as alternative TX0 and RX0 pins.


The ESP doesn’t have a hardware TWI (Two Wire Interface), but it is implemented in software. This means that you can use pretty much any two digital pins. By default, the I²C library uses pin 4 as SDA and pin 5 as SCL. (The data sheet specifies GPIO2 as SDA and GPIO14 as SCL.) The maximum speed is approximately 450kHz.


The ESP8266 has one SPI connection available to the user, referred to as HSPI. It uses GPIO14 as CLK, 12 as MISO, 13 as MOSI and 15 as Slave Select (SS). It can be used in both Slave and Master mode (in software).

GPIO overview

GPIO Function State Restrictions
0 Boot mode select 3.3V No Hi-Z
1 TX0 - Not usable during Serial transmission
2 Boot mode select TX1 3.3V (boot only) Don’t connect to ground at boot time Sends debug data at boot time
3 RX0 - Not usable during Serial transmission
4 SDA (I²C) - -
5 SCL (I²C) - -
6 - 11 Flash connection x Not usable, and not broken out
12 MISO (SPI) - -
13 MOSI (SPI) - -
14 SCK (SPI) - -
15 SS (SPI) 0V Pull-up resistor not usable
16 Wake up from sleep - No pull-up resistor, but pull-down instead Should be connected to RST to wake up
Clone this wiki locally
You can’t perform that action at this time.