1_Installation

TOISWITCH installation and first-time-wizard

If you'd like to install toiswitch on a device, please make sure the device is controlled by ESP8266 chip with at least 2 MB of RAM
(1 MB is also possible without OTA).
A short list of supported devices:

-MANY RGB/RGBWW lights (you may you need to exchange the controller module)
-MOTION DETECTORS
-MOTOR CONTROLS
-PWM-based DIMMERS
-SENSOR and CLASSIC WALL-SWITCHES
-WIFI SINGLE PLUG WITH/WITHOUT POWER MEASUREMENT
-WIFI MULTI PLUG WITH/WITHOUT POWER MEASUREMENT and WITH/WITHOUT USB CHARGER
-ROTO WINDOWS with wireless control (you need to modify the transmitter)
-MANY MORE

TOISWITCH can also be used with other devices, but in this case you need to create your own device in init.c
It supports currently the following types of inputs and outputs:

-Outputs: Digital output pin, PWM, digital button emulation, digital changeover switch emulation, digital toggle switch emulation, all inverted or non-inverted
-Inputs: Digital button, digital switch, power meter, infrared- and radar-based motion detectors

This article can give only a general overview because there are many different devices, programmers and tools outside.

I prefer to use the build-in make scripts from the ESP8266 IDF under linux using make.

There are 3 versions out:

1MB-Version for all devices controlled by ESP8266 Boards with 1MB flash or ESP8285, like TYWE2S/TYWE2L
2MB-Version for all devices controlled by ESP8266 Boards with 2MB flash, like TYWE3S/TYWE3L
4MB-Version for all devices controlled by ESP8266 Boards with 4MB flash, eg. ESP12-F

Steps to install:

-Find out the correct version for your board, depending on flash size (1M, 2M, 4M).
-Download the toiswitch.zip from here, it contains the install binaries for all versions.
-Wire the controller appropriate with your programmer (RX, TX, GND, VCC, IO0, RST).
-Connect IO15 via 2k2 resistor to GND on ESP12-S / TYWE3S / TYWE3L.
-Connect EN with VCC.
-Extract the correct version (1M,2M,4M) from the zip into a directory of choice.
(This includes only the binaries, the sourcecode can be found in the git-repo in here)
-Connect programmer to PC.

IF YOU USE ESP IDF:

-erase flash: esptool.py --port /dev/ttyUSB0 erase_flash (the port needs to be adjusted to the port your programmer is connected to).
-use esptool commands below to flash.

OR:

-Use any programmer of choice. Be sure to erase the flash and program the .bin file to the correct address (0x0).

1M version:
0x0 toiswitch_install_1M.bin

esptool command:
esptool.py --chip esp8266 --port /dev/ttyUSB0 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dout --flash_freq 40m --flash_size 1MB 0x0 toiswitch_install_1M.bin
The port needs to be adjusted to the port your programmer is connected to.

2M version:
0x0 toiswitch_install_2M.bin

esptool.py --chip esp8266 --port /dev/ttyUSB0 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dout --flash_freq 40m --flash_size 2MB 0x0 toiswitch_install_2M.bin
The port needs to be adjusted to the port your programmer is connected to.

4M version:
0x0 toiswitch_install_4M.bin

esptool.py --chip esp8266 --port /dev/ttyUSB0 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dout --flash_freq 40m --flash_size 4MB 0x0 toiswitch_install_4M.bin
The port needs to be adjusted to the port your programmer is connected to.

After flashing connect the ESP8266 device connect the controller to VCC (3V3) and GND.
Connect EN-PIN to VCC. For some boards its also neccessary to connect RST to VCC.

You should be able to find a access point "toiswitch" when you search for wifi networks.
Connect to this AP with password "toiswitch123".
After connecting open website "http://192.168.4.1" in your browser.
Enter "admin /test_123" as credentials if you'll be prompted for.
Under "Wlan data" enter your Wlan SSID and password.
Here you'll find also the MAC address of your device, in case you'll need it (eg. if you have a MAC filter installed for your WLAN).
Under "Network data" enter IP/GW/Subnet mask / DNS if you are not using DHCP. Mostly DHCP is used then you can leave it as is.
Change "Station Name" and "Station password" under "Station data" if you like to (its not neccessary in here).
Under "Firmware settings" choose appropriate type of device, eg "HAMA_WIFI_STRIP". Be sure to use the correct device here, a wrong device setting can damage the device or controller!
Click "SAVE" Button.

The device will restart and you'll find the device connected in your network.

After the installation you can remove all downloaded and extracted files from your pc.

Firmware update (OTA)

Currently OTA is only available for the 2MB and 4MB versions.

Once the device is installed and the first-time-wizard is done, you can easily update the firmware via OTA:
To do so, click "configure me" within the main page to enter the configuration menu.
Within the configuration menu, scroll down to "Firmware settings", and set "Do firmware update" to YES.
After that click "SAVE" button.
The device will restart and fetch the update from https://toiswitch.de/
Usually the update will take apx. 90 seconds. Sometimes it may take longer. In these cases you need to refresh the page manually.
After the update is completed you should see an entry "update (success) in the bottom line of the page.
If you see "update (failed)" entry, you should check your network connection and if the firmware file is reachable, i.e. with a browser.

Soft reset

A soft reset can always be done by unplug the power from the device for 5 seconds.
If the software hangs it will also do an auto-reset in most cases.
You can also switch the power off, when you don't need the device.
The configuration will be restored after power is back.

Factory reset

In case something goes wrong and the device is not responding any more, you can reset the device with the following actions:

-Devices that has a button:
Unplug power from device.
Press and hold the reset button (usually the first button) and plug power.
Wait 10 secs before releasing the button.

-Devices with no button, eg Lamps:
Unplug power from device.
Wait 5 seconds.
Plug power again.
Wait 5 seconds.
Repeat this procedure 10 times in a row.

The device will reset and will re-open the default access point "toiswitch" again.
All config on the device will be erased, so you need to complete the first-time-wizard again before using the device.

Support

You can raise a support question under https://sourceforge.net/p/toiswitch/discussion/support/ or within the thread of the mikrocontroller.net forum https://www.mikrocontroller.net/topic/524051#new
I will try to answer questions as fast as i can, but be aware i am doing this project as a hobbyist.
I am not willed to guarantee any kind of response times or SLAs.

Serial monitor

The device will log some serial monitor messages. They can be helpful when encountering some trouble and can be read with a serial-to-usb converter
connected to the device and a serial monitor on the pc, e.g, a "make monitor" command with ESP IDF.

Security hint

You are responsible for installing this firmware on a device.
Be aware that installing a custom firmware can may break guarantee or damage the device.
When working with high voltages be always aware of the risk for your life!

Experimental path

There's also an experimental path available within the repo. Binaries can be found under

https://toiswitch.de/experimental/toiswitch_exp_1m.bin
https://toiswitch.de/experimental/toiswitch_exp_2m.bin
https://toiswitch.de/experimental/toiswitch_exp_4m.bin

These versions contain may new features, but these features are under test and not stable.
Do not use them for productive use cases.