Adding manual for Sonoff T1 UK 3 Gang V1.1 (#182)

* Adding manual for Sonoff T1 UK 3 Gang V1.1

This manual is based on the existing 4CH version with necessary changes.

I know there's a pending PR for V1 of the same switch but V1.1 is more difficult to get into flashing mode and behaves weirdly after flashing.

* Removing .DS_Store

* Update devices/sonoff_t1_uk_3gang_v1.1.rst

Co-Authored-By: nnmalex <6181345+nnmalex@users.noreply.github.com>

* Update devices/sonoff_t1_uk_3gang_v1.1.rst

Co-Authored-By: nnmalex <6181345+nnmalex@users.noreply.github.com>

* Update devices/sonoff_t1_uk_3gang_v1.1.rst

Co-Authored-By: nnmalex <6181345+nnmalex@users.noreply.github.com>

* Update devices/sonoff_t1_uk_3gang_v1.1.rst

Co-Authored-By: nnmalex <6181345+nnmalex@users.noreply.github.com>

* Update devices/sonoff_t1_uk_3gang_v1.1.rst

Co-Authored-By: nnmalex <6181345+nnmalex@users.noreply.github.com>

* Changing images' extensions

From .jpeg to .jpg

* Fixing image URLs

* Lint

devices/sonoff_t1_uk_3gang_v1.1.rst

@@ -0,0 +1,319 @@
+Using With Sonoff T1 UK 3 Gang
+==============================
+
+.. seo::
+    :description: Instructions for putting Sonoff T1 UK 3 Gang devices into flash mode and installing ESPHome on them.
+    :image: sonoff_t1_uk_3g_v1.1.jpg
+
+ESPHome can also be used with Sonoff T1 UK 3 Gang wireless switches. These devices are
+basically just an ESP8266 chip with 3 relays to control power output ant three backlit capacitive touch buttons to control the relays.
+
+.. note::
+
+    This instruction is made for T1 UK with the touch board v1.1 which is trickier to get into flash mode
+    than v1
+
+.. figure:: images/sonoff_t1_uk_3g_v1.1.jpg
+    :align: center
+    :width: 75.0%
+
+    Sonoff T1 UK 3 Gang WiFi switch.
+
+This guide will step you through setting up your Sonoff T1 UK 3 Gang and flashing the first ESPHome firmware
+with the serial interface. After that, you will be able to upload all future firmwares with the remote
+Over-The-Air update process.
+
+.. note::
+
+    If you've previously installed Sonoff-Tasmota on your Sonoff T1 UK 3 Gang, you're in luck 😀
+    ESPHome can generate a firmware binary which you can then upload via the
+    Tasmota web interface. To see how to create this binary, skip to :ref:`sonoff_t1_uk_3g_v1.1-creating_firmware`.
+
+Since firmware version 1.6.0, iTead (the creator of this device) has removed the ability to upload
+a custom firmware through their own upload process. Unfortunately, that means that the only way to
+flash the initial ESPHome firmware is by physically opening the device up and using the UART
+interface.
+
+.. warning::
+
+    Opening up this device can be very dangerous if not done correctly. While the device is open,
+    you will be a single touch away from being electrocuted if the device is plugged in.
+
+    So, during this *entire* guide **never ever** plug the device in. Also, you should only do this
+    if you know what you're doing. If you, at any step, feel something is wrong or are uncomfortable
+    with continuing, it's best to just stop for your own safety.
+
+    It's your own responsibility to make sure everything you do during this setup process is safe.
+
+For this guide you will need:
+
+- Sonoff T1 UK 3 Gang 😉
+- An USB to UART Bridge for flashing the device. These can be bought on Amazon for less than 5 dollars.
+  Note that the bridge *must* be 3.3V compatible. Otherwise you will destroy your Sonoff.
+- Jumper wires to connect the UART bridge to the header pins and to connect GPIO0 to the Ground.
+- Computer running ESPHome or Hass.io add-on.
+- Screwdriver to open up the Sonoff T1 UK 3 Gang.
+
+Have everything? Great! Then you can start.
+
+
+Step 1: Opening up the Sonoff T1 UK 3 Gang
+------------------------------------------
+
+The first step is to open up the Sonoff T1 UK 3 Gang. Note that you do not have to run the original firmware
+supplied with the Sonoff T1 UK 3 Gang before doing this step.
+
+.. warning::
+
+    Just to repeat this: Make **absolutely sure** the device is not connected to any appliance or
+    plugged in before doing this step.
+
+While the device is not plugged in, turn the device face down and put a narrow flat screwdriver into the slot at the bottom.
+With careful twisting motion detatch the face plate.
+
+.. figure:: images/sonoff_t1_uk_3g_back_v1.1.jpg
+    :align: center
+    :width: 60.0%
+
+    Careful twisting motion.
+
+After that, use the same screwdriver to carefully lift the top PCB off of the switch.
+This PCB contains the ESP chip and what's left inside the switch body are relays.
+
+.. figure:: images/sonoff_t1_uk_3g_plate_off_v1.1.jpg
+    :align: center
+    :width: 75.0%
+
+    "TOUCH BOARD" with touch pads holds the ESP chip.
+
+Step 2: Connecting UART
+-----------------------
+
+Now we need our computer to somehow establish a data connection to the board. For this we will
+have to connect the four wires on the UART to USB bridge to the UART pins of the Sonoff T1 v1.1.
+
+Fortunately for us, these pins on the ESP controller have dedicated solder pads on the PCB. You can identify
+these by the ``VCC33``, ``RX``, ``TX`` and ``GND`` markings on the silk-screen.
+
+Now go ahead and connect these pins to your UART to USB bridge as seen in below image. Make sure
+that you connect these correctly, especially the ``VCC33`` and ``GND`` parts as you can otherwise
+destroy the chip.
+
+``VCC33`` should be connected to the ``3V3`` (**not** 5V) pin of the UART bridge, ``GND`` to ``GND``
+and the same with ``RX``/``TX``.
+
+There's no need for soldering - for quick job like one time firmware flashing you can just hold pins in respective holes by hand
+provided **you are not touching any live contacts**, only the wires.
+
+.. note::
+
+    On some older T1 UK 3 Gangs, the ``RX`` and ``TX`` pins are swapped (sometimes even the written silkscreen is
+    wrong). If your upload fails with a ``error: espcomm_upload_mem failed`` message it's most likely due
+    to the pins being swapped. In that case, just swap ``RX`` and ``TX`` and try again - you won't break
+    anything if they're swapped.
+
+.. _sonoff_t1_uk_3g_v1.1-creating_firmware:
+
+Step 3: Creating Firmware
+-------------------------
+
+The Sonoff T1 UK 3 Gang is based on the ``ESP8266`` platform (technically it's the ``ESP8285``, but for our purposes
+they're the same) and is a subtype of the ``esp01_1m`` board.
+With this information, you can step through the ESPHome wizard (``esphome sonoff_t1_uk_3g.yaml wizard``),
+or alternatively, you can just take the below configuration file and modify it to your needs.
+
+.. code-block:: yaml
+
+    esphome:
+      name: <NAME_OF_NODE>
+      platform: ESP8266
+      board: esp01_1m
+
+    wifi:
+      ssid: <YOUR_SSID>
+      password: <YOUR_PASSWORD>
+
+    api:
+
+    logger:
+
+    ota:
+
+Now run ``esphome sonoff_t1_uk_3g_v1.1.yaml compile`` to validate the configuration and
+pre-compile the firmware.
+
+.. note::
+
+    After this step, you will be able to find the compiled binary under
+    ``<NAME_OF_NODE>/.pioenvs/<NAME_OF_NODE>/firmware.bin``. If you're having trouble with
+    uploading, you can also try uploading this file directly with other tools.
+
+Step 4: Uploading Firmware
+--------------------------
+
+In order to upload the firmware, you're first going to need to get the chip into a flash mode, otherwise
+the device will start up without accepting any firmware flash attempts.
+To put ESP8266 into flash mode you need to connect ``GPIO0`` to ``GND`` when the device is powering up.
+
+This is a tricky process with T1 and the best way to do it is to use a wire with pins on either side.
+To do this, while the device is UART bridge is not connected to your USB port, flip the PCB over,
+take a wire and connect the second Ground hole on the PCB (red) to the third from the right bottom leg on the chip as depicted below (yellow) -
+that leg is connected to the GPIO0 on ESP and plug the UART to your USB port.
+
+Keep holding  GND and GPIO0 connected for 2-4 seconds. The T1 UK 3 Gang should now be in a flash mode and should not blink with any LED.
+The touchpads may light up.
+
+.. figure:: images/sonoff_t1_uk_3g_back_plate_v1.1.jpg
+    :align: center
+
+    Connect red and yellow contacts while powering the board.
+
+Now you can finally run the upload command:
+
+.. code-block:: bash
+
+    esphome sonoff_t1_uk_3g_v1.1.yaml run
+
+If successful, you should see something like this:
+
+.. figure:: images/sonoff_4ch_upload.png
+    :align: center
+
+Hooray 🎉! You've now successfully uploaded the first ESPHome firmware to your Sonoff T1 UK 3 Gang. And in a moment,
+you will be able to use all of ESPHome's great features with your Sonoff T1 UK 3 Gang. Now you can put your T1 back together and fire up.
+
+.. note::
+
+    While now your T1 will start up and connect to your WiFi network if you power it up from UART it will not behave normally,
+    it may flash random LEDs, turn on anf off touchpads' backlight and not react on touching touchpads. This will all be fixed once you re-assemble your T1
+    and power it up from the mains power once safe to do so.
+
+If above step does, however, not work, here are some steps that can help:
+
+-  Sometimes the UART bridge cannot supply enough current to the chip to operate, in this
+   case use a 3.3V supply you have lying around. A nice hack is to use the power supply of
+   NodeMCU boards. Simply connect the NodeMCU's 3.3V to VCC and GND to GND. **Do not attempt
+   to plug the device into a socket to overcome this problem while troubleshooting.**
+-  In other cases the ``TX`` and ``RX`` pin are reversed. Simple disconnect the device, swap
+   the two pins and put it into flash mode again.
+
+Step 5: Adding the Button, Relay and LEDs
+-----------------------------------------
+
+Now we would like the T1 UK 3 Gang to actually do something, not just connect to WiFi and pretty much sit idle.
+
+Below you will find a table of all usable GPIO pins of the Sonoff T1 UK 3 Gang and a configuration file that exposes all
+of the basic functions.
+
+======================================== =========================================
+``GPIO0``                                Touchpad #1 (inverted)
+---------------------------------------- -----------------------------------------
+``GPIO9``                                Touchpad #2 (inverted)
+---------------------------------------- -----------------------------------------
+``GPIO10``                               Touchpad #3 (inverted)
+---------------------------------------- -----------------------------------------
+``GPIO12``                               Relay #1 and Touchpad #1 backlight
+---------------------------------------- -----------------------------------------
+``GPIO5``                                Relay #2 and Touchpad #2 backlight
+---------------------------------------- -----------------------------------------
+``GPIO4``                                Relay #3 and Touchpad #3 backlight
+---------------------------------------- -----------------------------------------
+``GPIO13``                               Blue LED (inverted)
+---------------------------------------- -----------------------------------------
+``GPIO1``                                ``RX`` pin (for external sensors)
+---------------------------------------- -----------------------------------------
+``GPIO3``                                ``TX`` pin (for external sensors)
+======================================== =========================================
+
+.. code-block:: yaml
+
+    esphome:
+      name: <NAME_OF_NODE>
+      platform: ESP8266
+      board: esp01_1m
+
+    wifi:
+      ssid: <YOUR_SSID>
+      password: <YOUR_PASSWORD>
+
+    api:
+
+    logger:
+
+    ota:
+
+    binary_sensor:
+      - platform: gpio
+        pin:
+          number: GPIO0
+          mode: INPUT_PULLUP
+          inverted: True
+        name: "Sonoff T1 UK 3 Gang Touchpad 1"
+      - platform: gpio
+        pin:
+          number: GPIO9
+          mode: INPUT_PULLUP
+          inverted: True
+        name: "Sonoff T1 UK 3 Gang Touchpad 2"
+      - platform: gpio
+        pin:
+          number: GPIO10
+          mode: INPUT_PULLUP
+          inverted: True
+        name: "Sonoff T1 UK 3 Gang Touchpad 3"
+      - platform: status
+        name: "Sonoff T1 UK 3 Gang Status"
+
+    switch:
+      - platform: gpio
+        name: "Sonoff T1 UK 3 Gang Relay 1"
+        pin: GPIO12
+      - platform: gpio
+        name: "Sonoff T1 UK 3 Gang Relay 2"
+        pin: GPIO5
+      - platform: gpio
+        name: "Sonoff T1 UK 3 Gang Relay 3"
+        pin: GPIO4
+
+    output:
+      # Register the blue LED as a dimmable output ....
+      - platform: esp8266_pwm
+        id: blue_led
+        pin: GPIO13
+        inverted: True
+
+    light:
+      # ... and then make a light out of it.
+      - platform: monochromatic
+        name: "Sonoff T1 UK 3 Gang Blue LED"
+        output: blue_led
+
+
+Above example also showcases an important concept of esphome: IDs and linking. In order
+to make all components in esphome as much "plug and play" as possible, you can use IDs to define
+them in one area, and simply pass that ID later on. For example, above you can see an PWM (dimmer)
+output being created with the ID ``blue_led`` for the blue LED. Later on it is then transformed
+into a :doc:`monochromatic light </components/light/monochromatic>`.
+If you additionally want the buttons to control the relays, look at `the complete Sonoff T1 UK 3 Gang
+with automation example <https://github.com/OttoWinter/esphomedocs/blob/current/devices/sonoff_t1_uk_3gang_v1.1.yaml>`__.
+
+Step 6: Finishing Up
+--------------------
+
+If you're sure everything is done with the T1 UK 3 Gang and have double checked there's nothing that could cause a short
+in the case, you can put the T1 back together.
+
+Now triple or even quadruple check the UART bridge is not connected to the T1 UK 3 Gang, then comes the time when you can
+connect it.
+
+Happy hacking!
+
+See Also
+--------
+
+- :doc:`sonoff`
+- :doc:`sonoff_4ch`
+- :doc:`sonoff_s20`
+- :ghedit:`Edit`
+
+.. disqus::

devices/sonoff_t1_uk_3gang_v1.1.yaml

@@ -0,0 +1,78 @@
+esphome:
+  name: <NAME_OF_NODE>
+  platform: ESP8266
+  board: esp01_1m
+  # Automation turning on the blue status LED once T1 is booted up
+  on_boot:
+    priority: -10
+    then:
+      - light.turn_on: blue_led_light
+
+wifi:
+  ssid: <YOUR_SSID>
+  password: <YOUR_PASSWORD>
+
+# Enable logging
+logger:
+
+# Enable Home Assistant API
+api:
+
+ota:
+
+binary_sensor:
+  - platform: gpio
+    pin:
+      number: GPIO0
+      mode: INPUT_PULLUP
+      inverted: True
+    name: "Sonoff T1 UK 3 Gang Touchpad 1"
+    on_press:
+      - switch.toggle: relay_1
+  - platform: gpio
+    pin:
+      number: GPIO9
+      mode: INPUT_PULLUP
+      inverted: True
+    name: "Sonoff T1 UK 3 Gang Touchpad 2"
+    on_press:
+      - switch.toggle: relay_2
+  - platform: gpio
+    pin:
+      number: GPIO10
+      mode: INPUT_PULLUP
+      inverted: True
+    name: "Sonoff T1 UK 3 Gang Touchpad 3"
+    on_press:
+      - switch.toggle: relay_3
+  - platform: status
+    name: "Sonoff T1 UK 3 Gang Status"
+
+switch:
+  - platform: gpio
+    name: "Sonoff T1 UK 3 Gang Relay 1"
+    pin: GPIO12
+    id: relay_1
+  - platform: gpio
+    name: "Sonoff T1 UK 3 Gang Relay 2"
+    pin: GPIO5
+    id: relay_2
+  - platform: gpio
+    name: "Sonoff T1 UK 3 Gang Relay 3"
+    pin: GPIO4
+    id: relay_3
+
+output:
+  # Register the blue LED as a dimmable output ....
+  - platform: esp8266_pwm
+    id: blue_led
+    pin: GPIO13
+    inverted: True
+
+light:
+  # ... and then make a light out of it.
+  - platform: monochromatic
+    name: "Sonoff T1 UK 3 Gang Blue LED"
+    output: blue_led
+    internal: true
+    id: blue_led_light

index.rst

@@ -61,6 +61,7 @@ Technically, all ESP8266/ESP32 devices are supported by ESPHome.
 
     Generic Sonoff, devices/sonoff, sonoff.svg
     Sonoff Basic, devices/sonoff_basic, sonoff_basic.jpg
+    Sonoff T1 UK 3 Gang V1.1, devices/sonoff_t1_uk_3gang_v1.1, sonoff_t1_uk_3g_v1.1.jpg
 
 Core Components
 ---------------