4 - select light RGB LED to next program. This is normally done by power the light on (if currently off), then power off the light for a given time (delay) and power on again. The default delay is 15 (=1.5 sec). NPpHMin {<ph>}(only available if pH module is installed)get/set pH lower limit (ph = 0..14)get current limit if is omitted, otherwise set. NPpHMax {<ph>}(only available if pH module is installed)get/set pH upper limit (ph = 0..14)get current limit if is omitted, otherwise set. NPpH {<ph>}(only available if pH module is installed)get/set pH upper limit (ph = 0..14)same as NPpHMax NPRedox {<setpoint>}(only available if redox module is installed)get/set redox set point in mV (setpoint = 0..100, the upper limit of the range may vary depending on the MBF_PAR_HIDRO_NOM register)get current set point if is omitted, otherwise set NPHydrolysis {<level>}(only available if hydrolysis/electrolysis control is present)get/set hydrolysis/electrolysis level in % (level = 0..100)get current level if is omitted, otherwise set NPIonization {<level>}(only available if ionization control is present)get/set ionization target production level (level = 0..x, the upper limit x of the range may vary depending on the MBF_PAR_ION_NOM register)get current level if is omitted, otherwise set NPChlorine {<setpoint>}(only available if free chlorine probe detector is installed)get/set chlorine set point in ppm (setpoint = 0..10)get current set point if is omitted, otherwise set NPControl Show information about system controls NPOnError {<repeat>}get/set auto-repeat Modbus read/write commands on error (repeat = 0..10). Get if repeat is omitted, otherwise set accordingly <repeat>:0 - disable auto-repeat on read/write error1..10 - repeat commands n times until ok
NPResult {<format>}get/set addr/data result format for read/write commands (format = 0|1). Get if format is omitted, otherwise set accordingly <format>:0 - output decimal numbers1 - output hexadecimal strings, this is the default
NPPHRes {<digits>}get/set number of digits in results for PH value (digits = 0..3). NPCLRes {<digits>}get/set number of digits in results for CL value (digits = 0..3). NPIONRes {<digits>}get/set number of digits in results for ION value (digits = 0..3). NPRead <addr> {<cnt>}read 16-bit register (addr = 0..0x060F, cnt = 1..30). cnt = 1 if omitted NPReadL <addr> {<cnt>}read 32-bit register (addr = 0..0x060F, cnt = 1..15). cnt = 1 if omitted NPWrite <addr> <data> {<data>...}write 16-bit register (addr = 0..0x060F, data = 0..0xFFFF). Use of data max 10 times NPWriteL <addr> <data> {<data>...}write 32-bit register (addr = 0..0x060F, data = 0..0xFFFFFFFF). Use of data max 10 times NPBit <addr> <bit> {<data>}read/write a 16-bit register single bit (addr = 0..0x060F, bit = 0..15, data = 0|1). Read if data is omitted, otherwise set single bit NPBitL <addr> <bit> {<data>}read/write a 32-bit register single bit (addr = 0..0x060F, bit = 0..31, data = 0|1). Read if data is omitted, otherwise set single bit NPEscape clears possible errors (like pump exceeded time etc.) NPExec take over changes without writing to EEPROM. This command is necessary e.g. on changes in Installer page (addr 0x0400..0x04EE). NPSave write data permanently into EEPROM.During the EEPROM write procedure the NeoPool device may be unresponsive to MODBUS requests, this process always takes less than 1 second.Since this process is limited by the number of EEPROM write cycles, it is recommend to write all necessary changes to the registers and only then execute EEPROM write process using this command.Note: The number of EEPROM writes for Sugar Valley NeoPool devices is guaranteed 100,000 cycles. As soon as this number is exceeded, further storage of information can no longer be guaranteed."},{"location":"NeoPool/#examples","title":"Examples","text":"Example
Get filtration mode
NPFiltrationmode\nRESULT = {\"NPFiltrationmode\":\"Manual\"}\n
Example
Set filtration mode
NPFiltrationmode 1\n{\"NPFiltrationmode\":\"Auto\"}\n
Example
Enable hydrolysis boost mode without redox control
To do this, write 0x85A0 to register MBF_BOOST_CTRL (0x020C), exec, save it and notify system using register MBF_NOTIFICATION (0x0110) about changes:
Backlog NPWrite 0x020C,0x85A0;NPSave;NPExec;NPWrite 0x0110,0x7F\nRESULT = {\"NPWrite\":{\"Address\":\"0x020C\",\"Data\":\"0x85A0\"}}\nRESULT = {\"NPSave\":\"Done\"}\nRESULT = {\"NPExec\":\"Done\"}\nRESULT = {\"NPWrite\":{\"Address\":\"0x0110\",\"Data\":\"0x0000\"}}\n
Example
Disable hydrolysis boost mode
To do this, write 0 to register MBF_BOOST_CTRL (0x020C), exec, save it and notify system using register MBF_NOTIFICATION (0x0110) about changes:
Backlog NPWrite 0x020C,0;NPSave;NPExec;NPWrite 0x0110,0x7F\nRESULT = {\"NPWrite\":{\"Address\":\"0x020C\",\"Data\":\"0x0000\"}}\nRESULT = {\"NPSave\":\"Done\"}\nRESULT = {\"NPExec\":\"Done\"}\nRESULT = {\"NPWrite\":{\"Address\":\"0x0110\",\"Data\":\"0x0000\"}}\n
Example
Switch light relay on
NPLight 1\nRESULT = {\"NPLight\":\"ON\"}\n
Example
Read Heating setpoint temperature
Here we read register MBF_PAR_HEATING_TEMP (0x0416):
Backlog NPResult 0;NPRead 0x416\nRESULT = {\"NPResult\":0}\nRESULT = {\"NPRead\":{\"Address\":1046,\"Data\":28}}\n
Example
Enable additional factory menu
For that enable bit MBMSK_SHOW_FACTORY_MENU (15) in register MBF_PAR_UICFG_VISUAL_OPTIONS (0x0605)
Backlog NPBit 0x605,15,1;NPSave\nRESULT = {\"NPBit\":{\"Address\":\"0x0605\",\"Data\":\"0xAFC0\",\"Bit15\":1}}\nRESULT = {\"NPSave\":\"Done\"}\n
Example
Read system time
We either use command NPTime or read the 32-bit value starting MBF_PAR_TIME_LOW (0x0408) using decimal output:
Backlog NPResult 0;NPTime;NPReadL 0x408\nRESULT = {\"NPResult\":0}\nRESULT = {\"NPTime\":\"2021-01-31T21:22:20\"}\nRESULT = {\"NPReadL\":{\"Address\":1032,\"Data\":1612124540}}\n
Example
Enable temperature module
Do this by enabling MBF_PAR_TEMPERATURE_ACTIVE (0x04F) and set it permanently in EEPROM::
Backlog NPWrite 0x40F,1;NPSave\nRESULT = {\"NPWrite\":{\"Address\":\"0x040F\",\"Data\":\"0x0001\"}}\nRESULT = {\"NPSave\":\"Done\"}\n
Example
Hide auxiliary relay display from main menu
To do this, set bit MBMSK_HIDE_AUX_RELAYS (3) in register MBF_PAR_UICFG_VISUAL_OPTIONS (0x0605):
NPBit 0x605,3,1\nRESULT = {\"NPBit\":{\"Address\":\"0x0605\",\"Data\":\"0x08C8\"}}\n
Example
Read Filtration interval 1-3 settings
To do this, we read the registers MBF_PAR_TIMER_BLOCK_FILT_INT1 (0x0434), MBF_PAR_TIMER_BLOCK_FILT_INT2 (0x0443) and MBF_PAR_TIMER_BLOCK_FILT_INT3 (0x0452) with offset MBV_TIMER_OFFMB_TIMER_ENABLE (0) as 16-bit values and the remaining timer offset values MBV_TIMER_OFFMB_* as 32-bit values:
Backlog NPResult 0;NPRead 0x434;NPReadL 0x435,7;NPRead 0x443;NPReadL 0x444,7;NPRead 0x452;NPReadL 0x0453,7\nRESULT = {\"NPResult\":0}\nRESULT = {\"NPRead\":{\"Address\":1076,\"Data\":1}}\nRESULT = {\"NPReadL\":{\"Address\":1077,\"Data\":[28800,0,86400,14400,0,1,0]}}\nRESULT = {\"NPRead\":{\"Address\":1091,\"Data\":1}}\nRESULT = {\"NPReadL\":{\"Address\":1092,\"Data\":[43200,0,86400,21600,0,1,0]}}\nRESULT = {\"NPRead\":{\"Address\":1106,\"Data\":1}}\nRESULT = {\"NPReadL\":{\"Address\":1107,\"Data\":[0,0,86400,0,0,1,0]}} *\n
Example
Set filtration interval
Here we set interval 1 to a daily interval between 9:00 - 12:30 (9:00: 3600 * 9 \u2259 32400 / 12:30 \u2259 3,5h = 12600)
For this write register MBF_PAR_TIMER_BLOCK_FILT_INT1 (0x0434) using the offsets MBV_TIMER_OFFMB_. For the sake of simplicity we write 4 consecutive 32-bit registers:
MBV_TIMER_OFFMB_TIMER_ON: Timer start = 93600 + 0060 = 32400MBV_TIMER_OFFMB_TIMER_OFF: Timer stop - not usedMBV_TIMER_OFFMB_TIMER_PERIOD: Time in seconds between starting points = 86400 (means daily interval)MBV_TIMER_OFFMB_TIMER_INTERVAL: Time in seconds that the timer has to run when started. This is the difference between 12:30 (123600 + 3060 = 45000) and 9:30(see Timer start = 32400) = 12600
NPWriteL 0x435,32400 0 86400 12600\nRESULT = {\"NPWriteL\":{\"Address\":1077,\"Data\":[32400,0,86400,12600]}}\n
Example
Manual switch relay 7 (Aux4)
To switch Aux4 ON, we set MBF_PAR_TIMER_BLOCK_AUX4_INT1 (0x04D9) + MBV_TIMER_OFFMB_TIMER_ENABLE (0) to MBV_PAR_CTIMER_ALWAYS_ON (3):.
Backlog NPWrite 0x4D9,3;NPExec\nRESULT = {\"NPWrite\":{\"Address\":\"0x04D9\",\"Data\":\"0x0003\"}}\nRESULT = {\"NPExec\":\"Done\"}\n
To switch Aux4 OFF, we set MBF_PAR_TIMER_BLOCK_AUX4_INT1 (0x04D9) + MBV_TIMER_OFFMB_TIMER_ENABLE (0) to MBV_PAR_CTIMER_ALWAYS_OFF (4):.
Backlog NPWrite 0x4D9,4;NPExec\nRESULT = {\"NPWrite\":{\"Address\":\"0x04D9\",\"Data\":\"0x0004\"}}\nRESULT = {\"NPExec\":\"Done\"}\n
Example
Modbus autorepeat on communication error
Read current autorepeat value:
NPOnError\nRESULT = {\"NPOnError\":2}\n
Set autorepeat value to 3:
NPOnError 3\nRESULT = {\"NPOnError\":3}\n
"},{"location":"NeoPool/#enhancements","title":"Enhancements","text":""},{"location":"NeoPool/#daily-sync-device-to-tasmota-time","title":"Daily sync device to Tasmota time","text":"Since the NeoPool devices, without a WiFi module, have no way of synchronizing their internal clock with an external clock and, in addition, the accuracy of the internal clock leaves something to be desired, it makes sense to synchronize the clock with Tasmota once a day. Advantageously, we do this at night after a possible daylight saving time or normal time change.
We use a rule that synchronizes the time and which is triggered by the Tasmota built-in timer (here we use timer 10):
Rule2\nON Clock#Timer=10 DO NPTime 0 ENDON\n
Activate it:
Backlog Rule2 4;Rule2 1\n
Configure Tasmota \"Timer 10\" for your needs:
"},{"location":"NeoPool/#esp82xx-add-buttons-for-filtration-and-light-control","title":"ESP82xx: Add buttons for filtration and light control","text":"Add two dummy buttons to control the filtration pump and the light.
First we define two dummy relay (which does not have any physical function) on two unused GPIO (here we use GPIO0 and GPIO4 where we define Tasmota Relay 1 and 2):
Backlog GPIO0 224;GPIO4 225\n
Then we rename the buttons for better visibility:
Backlog WebButton1 Filtration;WebButton2 Light\n
Now we have the WebGUI buttons like this:
but missing the functionality behind. For that we use Rules and connect the states for Tasmota Power, Neopool filtration and light:
Rule1\nON Power1#State==0 DO NPFiltration %value% ENDON\nON Power1#State==1 DO NPFiltration %value% ENDON\nON NeoPool#Filtration#State==0 DO Power1 %value% ENDON\nON NeoPool#Filtration#State==1 DO Power1 %value% ENDON\nON Power2#State==0 DO NPLight %value% ENDON\nON Power2#State==1 DO NPLight %value% ENDON\nON NeoPool#Light==0 DO Power2 %value% ENDON\nON NeoPool#Light==1 DO Power2 %value% ENDON\n
Don't wonder about the double trigger definition, which at first glance seem nonsensical - they are necessary so that the rule does not trigger endless.
At least we activate the rule:
Backlog Rule1 5;Rule1 1\n
It is important to enable the Rule ONCE (Rule1 5) function, which prevents the trigger is triggering themself in a loop.
You can now control filtration and light using the WebGUI and get the current status of the device elements when they are switched by auto-mode or manually on the device directly.
Additional advantage is that you can also use Tasmota Timer switching Power1 (=filtration) and Power2 (light) for your needs.
"},{"location":"NeoPool/#esp32-adding-user-defined-neopool-commands-to-tasmota","title":"ESP32: Adding user defined NeoPool commands to Tasmota","text":"The following enhancements are made using the Berry Scripting Language which is available on ESP32 only.
The class NeoPoolCommands below adds two new commands to Tasmota:
Command Parameters NPBoost {<state>}get/set boost mode (state = 0..2). Get if state is omitted, otherwise set accordingly <state>:0 - disable boost mode1 - enable boost mode (without redox control)2 - enable boost mode (with redox control)
NPAux<x> {<state>}get/set auxiliary relay <x> (state = 0..2). Get if state is omitted, otherwise set accordingly <state>:0 - switch off auxiliary relay1 - switch on auxiliary relay
The class members NPBoost and NPAux can also be used as templates for further commands.
Store the following code into a Tasmota file by using the WebGUI \"Console\" / \"Manage File system\".
"},{"location":"NeoPool/#neopoolcmdbe","title":"neopoolcmd.be","text":"# File: neopoolcmd.be\n#\n# Add new commands NPBoost and NPAux\n\n# Neopool definitions\nvar MBF_RELAY_STATE = 0x010E\nvar MBF_NOTIFICATION = 0x0110\nvar MBF_CELL_BOOST = 0x020C\n\nvar MBF_PAR_TIMER_BLOCK_AUX1_INT1 = 0x04AC\nvar MBF_PAR_TIMER_BLOCK_AUX2_INT1 = 0x04BB\nvar MBF_PAR_TIMER_BLOCK_AUX3_INT1 = 0x04CA\nvar MBF_PAR_TIMER_BLOCK_AUX4_INT1 = 0x04D9\nvar PAR_TIMER_BLOCK_AUX = [\n MBF_PAR_TIMER_BLOCK_AUX1_INT1,\n MBF_PAR_TIMER_BLOCK_AUX2_INT1,\n MBF_PAR_TIMER_BLOCK_AUX3_INT1,\n MBF_PAR_TIMER_BLOCK_AUX4_INT1\n]\nvar MBV_PAR_CTIMER_ALWAYS_ON = 3\nvar MBV_PAR_CTIMER_ALWAYS_OFF = 4\n\n# NeoPool command class\nclass NeoPoolCommands\n var TEXT_OFF\n var TEXT_ON\n var TEXT_TOGGLE\n\n # string helper\n def ltrim(s)\n import string\n var i = 0 while(s[i]==' ') i += 1 end\n return string.split(s, i)[1]\n end\n def rtrim(s)\n import string\n return string.split(s, \" \")[0]\n end\n def trim(s)\n return self.rtrim(self.ltrim(s));\n end\n\n # NPBoost OFF|0|ON|1|REDOX|2\n # 0|OFF: Switch boost off\n # 1|ON: Switch boost on without redox control\n # 2|REDOX: Switch boost on with redox control\n def NPBoost(cmd, idx, payload)\n import string\n var ctrl, parm\n\n try\n parm = string.toupper(self.trim(payload))\n except ..\n parm = \"\"\n end\n if parm != \"\"\n if string.find(parm, 'OFF')>=0 || string.find(parm, self.TEXT_OFF)>=0 || string.find(parm, '0')>=0\n ctrl = 0\n elif string.find(parm, 'ON')>=0 || string.find(parm, self.TEXT_ON)>=0 || string.find(parm, '1')>=0\n ctrl = 0x85A0\n elif string.find(parm, 'REDOX')>=0 || string.find(parm, '2')>=0\n ctrl = 0x05A0\n else\n tasmota.resp_cmnd_error()\n return\n end\n tasmota.cmd(string.format(\"NPWrite 0x%04X,0x%04X\", MBF_CELL_BOOST, ctrl))\n tasmota.cmd(\"NPSave\")\n tasmota.cmd(\"NPExec\")\n tasmota.cmd(string.format(\"NPWrite 0x%04X,0x7F\", MBF_NOTIFICATION))\n else\n try\n ctrl = compile(\"return \"..tasmota.cmd(string.format(\"NPRead 0x%04X\", MBF_CELL_BOOST))['NPRead']['Data'])()\n except ..\n tasmota.resp_cmnd_error()\n return\n end\n end\n tasmota.resp_cmnd(string.format('{\"%s\":\"%s\"}', cmd, ctrl == 0 ? self.TEXT_OFF : (ctrl & 0x8500) == 0x8500 ? self.TEXT_ON : \"REDOX\"))\n end\n\n # NPAux<x> OFF|0|ON|1 t (<x> = 1..4)\n # 0|OFF: Switch Aux x to off\n # 1|ON: Switch Aux x to on\n # 2|TOGGLE: Toggle Aux x\n def NPAux(cmd, idx, payload)\n import string\n var ctrl, parm\n\n if idx < 1 || idx > 4\n tasmota.resp_cmnd_error()\n return\n end\n\n try\n parm = string.toupper(self.trim(payload))\n except ..\n parm = \"\"\n end\n if parm != \"\"\n if string.find(parm, 'OFF')>=0 || string.find(parm, self.TEXT_OFF)>=0 || string.find(parm, '0')>=0\n ctrl = MBV_PAR_CTIMER_ALWAYS_OFF\n elif string.find(parm, 'ON')>=0 || string.find(parm, self.TEXT_ON)>=0 || string.find(parm, '1')>=0\n ctrl = MBV_PAR_CTIMER_ALWAYS_ON\n elif string.find(parm, 'TOGGLE')>=0 || string.find(parm, self.TEXT_TOGGLE)>=0 || string.find(parm, '2')>=0\n try\n ctrl = (compile(\"return \"..tasmota.cmd(string.format(\"NPRead 0x%04X\", MBF_RELAY_STATE))['NPRead']['Data'])() >> (idx+2)) & 1 ? MBV_PAR_CTIMER_ALWAYS_OFF : MBV_PAR_CTIMER_ALWAYS_ON\n except ..\n tasmota.resp_cmnd_error()\n return\n end\n else\n tasmota.resp_cmnd_error()\n return\n end\n tasmota.cmd(string.format(\"NPWrite 0x%04X,%d\", PAR_TIMER_BLOCK_AUX[idx-1], ctrl))\n tasmota.cmd(\"NPExec\")\n else\n try\n ctrl = (compile(\"return \"..tasmota.cmd(string.format(\"NPRead 0x%04X\", MBF_RELAY_STATE))['NPRead']['Data'])() >> (idx+2)) & 1\n except ..\n tasmota.resp_cmnd_error()\n return\n end\n end\n end\n\n def init()\n # get tasmota settings\n self.TEXT_OFF = tasmota.cmd(\"StateText1\")['StateText1']\n self.TEXT_ON = tasmota.cmd(\"StateText2\")['StateText2']\n self.TEXT_TOGGLE = tasmota.cmd(\"StateText3\")['StateText3']\n # add commands\n tasmota.add_cmd('NPBoost', / cmd, idx, payload -> self.NPBoost(cmd, idx, payload))\n tasmota.add_cmd('NPAux', / cmd, idx, payload -> self.NPAux(cmd, idx, payload))\n end\n\n def deinit()\n # remove commands\n tasmota.remove_cmd('NPBoost')\n tasmota.remove_cmd('NPAux')\n end\nend\nneopoolcommands = NeoPoolCommands()\n
To activate the new commands, go to WebGUI \"Consoles\" / \"Berry Scripting console\" and execute
load(\"neopoolcmd.be\")\n
"},{"location":"NeoPool/#esp32-add-gui-controls-for-filtration-light-and-aux-relais","title":"ESP32: Add GUI controls for filtration, light and aux relais","text":"The following enhancements are made using the Berry Scripting Language which is available on ESP32 only.
The class NeoPoolButtonMethods below adds new GUI elements to control filtration, light and aux relais:
Store the following code into a Tasmota file by using the WebGUI \"Console\" / \"Manage File system\".
"},{"location":"NeoPool/#neopoolguibe","title":"neopoolgui.be","text":"# File: neopoolgui.be\n#\n# Add GUI elements for filtration control, light and aux relais\n\nimport webserver\nimport string\n\nclass NeoPoolButtonMethods : Driver\n\n #- method for adding elements to the main menu -#\n def web_add_main_button()\n\n def selected(value, comp)\n return comp == value ? 'selected=\"\"' : ''\n end\n\n var speed = tasmota.cmd('NPFiltration')['Speed']\n var mode = tasmota.cmd('NPFiltrationmode')['NPFiltrationmode']\n\n var html = '<p></p>'\n\n # Filtration mode/speed\n html+= '<table style=\"width:100%\"><tbody><tr>'\n html+= ' <td style=\"width:50%;padding: 0 4px 0 4px;\">'\n html+= ' <label for=\"mode\"><small>Mode:</small></label>'\n html+= ' <select id=\"mode\" name=\"mode\">'\n html+= string.format('<option value=\"m_sv_manual\"%s>Manual</option>', selected(mode, 'Manual'))\n html+= string.format('<option value=\"m_sv_auto\"%s>Auto</option>', selected(mode, 'Auto'))\n html+= string.format('<option value=\"m_sv_heating\"%s>Heating</option>', selected(mode, 'Heating'))\n html+= string.format('<option value=\"m_sv_smart\"%s>Smart</option>', selected(mode, 'Smart'))\n html+= string.format('<option value=\"m_sv_intelligent\"%s>Intelligent</option>', selected(mode, 'Intelligent'))\n html+= ' </select>'\n html+= ' </td>'\n html+= ' <td style=\"width:50%;padding: 0 4px 0 4px;\">'\n html+= ' <label for=\"speed\"><small>Speed:</label>'\n html+= ' <select id=\"speed\" name=\"speed\">'\n html+= string.format('<option value=\"m_sv_slow\"%s>Slow</option>', selected(speed, '1'))\n html+= string.format('<option value=\"m_sv_medium\"%s>Medium</option>', selected(speed, '2'))\n html+= string.format('<option value=\"m_sv_fast\"%s>Fast</option>', selected(speed, '3'))\n html+= ' </select>'\n html+= ' </td>'\n html+= '</tr><tr></tr></tbody></table>'\n html+= '<script>'\n html+= 'document.getElementById(\"speed\").addEventListener (\"change\",function(){la(\"&\"+this.value+\"=1\");});'\n html+= 'document.getElementById(\"mode\").addEventListener (\"change\",function(){la(\"&\"+this.value+\"=1\");});'\n html+= '</script>'\n\n # Filtration button\n html+= '<table style=\"width:100%\"><tbody><tr>'\n html+= ' <td style=\"width:100%\">'\n html+= ' <button id=\"bn_filtration\" name=\"bn_filtration\" onclick=\"la(\\'&m_sv_filtration=1\\');\">Filtration</button>'\n html+= ' </td>'\n html+= '</tr><tr></tr></tbody></table>'\n\n # Light button\n html+= '<table style=\"width:100%\"><tbody><tr>'\n html+= ' <td style=\"width:100%\">'\n html+= ' <button onclick=\"la(\\'&m_sv_light=1\\');\">Light</button>'\n html+= ' </td>'\n html+= '</tr><tr></tr></tbody></table>'\n\n # Aux buttons\n html+= '<table style=\"width:100%\"><tbody><tr>'\n html+= ' <td style=\"width:25%\"><button onclick=\"la(\\'&m_sv_aux=1\\');\">Aux1</button></td>'\n html+= ' <td style=\"width:25%\"><button onclick=\"la(\\'&m_sv_aux=2\\');\">Aux2</button></td>'\n html+= ' <td style=\"width:25%\"><button onclick=\"la(\\'&m_sv_aux=3\\');\">Aux3</button></td>'\n html+= ' <td style=\"width:25%\"><button onclick=\"la(\\'&m_sv_aux=4\\');\">Aux4</button></td>'\n html+= '</tr><tr></tr></tbody></table>'\n\n webserver.content_send(html)\n html = nil\n tasmota.gc()\n end\n\n #- As we can add only one sensor method we will have to combine them besides all other sensor readings in one method -#\n def web_sensor()\n if webserver.has_arg(\"m_sv_filtration\")\n tasmota.cmd(\"NPFiltration 2\")\n end\n\n if webserver.has_arg(\"m_sv_slow\")\n tasmota.cmd(\"NPFiltration 1,1\")\n end\n if webserver.has_arg(\"m_sv_medium\")\n tasmota.cmd(\"NPFiltration 1,2\")\n end\n if webserver.has_arg(\"m_sv_fast\")\n tasmota.cmd(\"NPFiltration 1,3\")\n end\n\n if webserver.has_arg(\"m_sv_manual\")\n tasmota.cmd(\"NPFiltrationmode 0\")\n end\n if webserver.has_arg(\"m_sv_auto\")\n tasmota.cmd(\"NPFiltrationmode 1\")\n end\n if webserver.has_arg(\"m_sv_heating\")\n tasmota.cmd(\"NPFiltrationmode 2\")\n end\n if webserver.has_arg(\"m_sv_smart\")\n tasmota.cmd(\"NPFiltrationmode 3\")\n end\n if webserver.has_arg(\"m_sv_intelligent\")\n tasmota.cmd(\"NPFiltrationmode 4\")\n end\n\n if webserver.has_arg(\"m_sv_light\")\n tasmota.cmd(\"NPLight 2\")\n end\n\n if webserver.has_arg(\"m_sv_aux\")\n tasmota.cmd(\"NPAux\"+webserver.arg(\"m_sv_aux\")+\" TOGGLE\")\n end\n end\n\n def init()\n end\n\n def deinit()\n end\nend\n\nneopool_driver = NeoPoolButtonMethods()\ntasmota.add_driver(neopool_driver)\n
To activate the new gui elements, go to WebGUI \"Consoles\" / \"Berry Scripting console\" and execute
load(\"neopoolgui.be\")\n
"},{"location":"NeoPool/#esp32-make-the-scripts-persistent","title":"ESP32: Make the scripts persistent","text":"If you want the extensions to be activated automatically every time you restart your ESP32, save the load() commands into the special file autoexec.be:
"},{"location":"NeoPool/#autoexecbe","title":"autoexec.be","text":"load(\"neopoolcmd.be\")\nload(\"neopoolgui.be\")\n
"},{"location":"NodeRed/","title":"NodeRed","text":""},{"location":"NodeRed/#home-automation-system-examples-with-pi-tasmota-and-node-red","title":"Home automation system examples with Pi, Tasmota and Node-Red","text":" - Detailed setting up Node-Red and mosquitto on a Raspberry PI and initial control of a Sonoff Switch:
https://www.instructables.com/id/Powerful-Standalone-Home-Automation-System-Pi-Sono/
- Detailed setting up of sensors and LEDs using Tasmota:
https://www.instructables.com/id/Home-Automation-Sonoff-Tasmota-Sensors-LEDs-Develo//
Credits: @MikePRoberts
- ESP8266 OTA Firmware Upgrade Manager and Server
https://flows.nodered.org/flow/888b4cd95250197eb429b2f40d188185
- Dynamically Populate Dashboard with Buttons to Tasmota-Sonoff Devices
https://flows.nodered.org/flow/1541bcbba48bb088ec1503dba109f63c
"},{"location":"OTA-over-SCP/","title":"OTA over SCP","text":"How to setup and configure \"OTA over SCP\" upload for PlatformIO. The uploader pushes .bin files to remote OTA server using SCP (SSH connection). Images can be served to Tasmotas from there.
"},{"location":"OTA-over-SCP/#configuration","title":"Configuration","text":"To upload .bin images to OTA server using SCP, edit the following lines under target environment:
; *** Upload file to OTA server using SCP\nupload_port = USER@HOST:/path\nextra_scripts = pio/sftp-uploader.py\n
upload_port should be modified to reflect user, host and path on the host where images should be uploaded."},{"location":"OTA-over-SCP/#requirements","title":"Requirements","text":"SSH communication between the build server and OTA server should be pre-configured so that it doesn't require password (pre-shared keys).
"},{"location":"OTA-over-SCP/#add-the-pre-shared-key","title":"Add the pre-shared key","text":"On a linux client machine type the following to generate the key. Press enter three times (without any input):
ssh-keygen -t rsa -C \"YOUR OWN KEY DESCRIPTION\"\n
Copy the key to your ssh server. You need to confirm this action. Use your server ssh password (one last time): ssh-copy-id -i ~/.ssh/id_rsa.pub USER@HOST\n
Optionally, reload the ssh service: sudo /etc/init.d/ssh restart\n
"},{"location":"OTA-over-SCP/#upload-tasmota","title":"Upload Tasmota","text":"Easy compilation and upload can be performed from the icons at the left side of the PlatformIO screen or use Ctrl + Alt + U to upload (will build if needed).
"},{"location":"Octoprint/","title":"OctoPrint","text":"OctoPrint provides a snappy web interface for controlling consumer 3D printers. It is Free Software and released under the GNU Affero General Public License V3 by Gina H\u00e4u\u00dfge.
Its website can be found at http://www.octoprint.org.
"},{"location":"Octoprint/#octoprint-tasmota","title":"OctoPrint-Tasmota","text":"Jneilliii wrote a plugin to control your Sonoff device with tasmota firmware via OctoPrint, for example shutdown the printer after a print has finished.
Repository: https://github.com/jneilliii/OctoPrint-Tasmota
"},{"location":"OpenHASP/","title":"OpenHASP","text":"This page moved to HASPmota
"},{"location":"OpenTherm/","title":"OpenTherm","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_OPENTHERM\n#define USE_OPENTHERM\n#endif\n
Implementation of OpenTherm protocol
OpenTherm integration is based on OpenTherm protocol specification v2.2 and works with all OpenTherm compatible boilers.
OpenTherm protocol requires a simple low voltage two-wire connection to the boiler, but voltage levels (7..15V) still much higher than ESP8266 levels, which requires OpenTherm Adapter.
"},{"location":"OpenTherm/#compatible-opentherm-adapters","title":"Compatible OpenTherm Adapters","text":" - Ihor Melnyk OpenTherm Adapter
- OpenTherm Gateway Arduino shield
- OpenTherm master shield for Wemos/Lolin
All adapters have a fully isolated circuit from the boiler. However, please be aware that you can damage your boiler. You may also void your boiler warranty by installing this hardware. Please consult with your boiler manufacturer.
Note
For my home automation project, I used OpenTherm Gateway Arduino shield; however, this project uses OpenTherm library from Ihor Melnyk. I assume all adapters will work.
Please note, this integration does not work with the OTGW. You might want to take a look at the HA OpenTherm GW
"},{"location":"OpenTherm/#connecting-to-the-boiler","title":"Connecting to the Boiler","text":"Current integration acts as a master to the boiler.
Note
If OpenTherm master device is present, the boiler may disable its front panel controls. Users may not be able to set a boiler and hot water temperature through the boiler. Now it's the responsibility of the master device. This behavior might vary across different boilers.
You may disable this behavior by removing OpenTherm Slave Status command. However, the integration will not be able to read flame/heating/failure flags.
OpenTherm Gateway Arduino shield support a gateway mode. As of now, this mode is not supported by the integration.
As of now, gateway mode is not supported
"},{"location":"OpenTherm/#setting-up-tasmota","title":"Setting Up Tasmota","text":"Note
You need to define USE_OPENTHERM and rebuild Tasmota to enable OpenTherm integration.
- Log into your Tasmota device
- Go to
Configuration -> Configure Module - Select
Generic module type, save & restart - In the
Module parameters window, assign OpenTherm RX and OpenTherm TX to the corresponding pins - Save settings and restart
Note
The integration attaches ISR to the RX GPIO to avoid pooling. That GPIO should support interrupts. Please consider this while working on the schematics.
"},{"location":"OpenTherm/#troubleshooting","title":"Troubleshooting","text":"In order to troubleshoot you may need to enable Debug or More Debug logging level,
After restart you might see the following in the logs:
00:00:00 CFG: Loaded from flash at 3F7, Count 72\n00:00:00 QPC: Flag 0E\n00:00:00 CFG: CR 338/699\n00:00:00 SRC: Restart\n00:00:00 Project tasmota Tasmota Version 8.2.0(sensors)-STAGE\n00:00:01 [OTH]: perform handshake\n00:00:01 [OTH]: Processing response. Status=SUCCESS, Response=0x4003011B\n00:00:01 [OTH]: getLastResponseStatus SUCCESS. Slave Cfg: 4003011B\n00:00:01 [OTH]: Processing response. Status=SUCCESS, Response=0xC0000000\n00:00:02 [OTH]: Setting Boiler Temp. Old: 0, New: 85\n00:00:02 [OTH]: Processing response. Status=SUCCESS, Response=0xD0015500\n00:00:02 [OTH]: Setting Hot Water Temp. Old: 0, New: 37\n12:34:58 [OTH]: Processing response. Status=INVALID, Response=0x70730000\n12:34:58 [OTH]: command OEMD is not supported by the boiler. Last status: INVALID\n12:35:00 [OTH]: Processing response. Status=INVALID, Response=0xF01B0000\n12:35:00 [OTH]: command TOUT is not supported by the boiler. Last status: INVALID\n12:35:00 [OTH]: Processing response. Status=INVALID, Response=0x701C0000\n12:35:00 [OTH]: command TRET is not supported by the boiler. Last status: INVALID\n12:35:16 MQT: tele/boiler/SENSOR = {\"Time\":\"2020-05-12T12:35:16\",\"ANALOG\":{\"A0\":7},\"OPENTHERM\":{\"conn\":\"BUSY\",\"settings\":3,\"SLAVE\":{\"FAULT\":0,\"CH\":0,\"DHW\":0,\"FL\":0,\"COOL\":0,\"CH2\":0,\"DIAG\":0,\"RAW\":3221225472},\"BTMP\":{\"FAULT\":0,\"REQ\":85.0,\"ACT\": 85.0},\"HWTMP\":{\"REQ\":37.0,\"ACT\": 37.0},\"ASFF\":{\"FC\":0,\"OFC\":0},\"FLM\":0.0,\"TB\":31.0,\"TDHW\":30.0,\"DHWS\":37.0,\"TMAX\":0.0}}\n
In the example, perform handshake was successful, and the OpenTherm integration started to fetch various OpenTherm statuses.
Note
Your boiler may not respond to some of the OpenTherm commands. The integration made 3 attempts to execute the command. If the third attempt failed, the command marked as not supported and excluded from the rotation.
"},{"location":"OpenTherm/#external-thermostat-wiring-and-safety","title":"External Thermostat Wiring and Safety","text":"Central heating is the last thing you want to fail in your home. You might have significant damage to your property in case of the software bug or your custom hardware or wiring failure.
As a last resort measure, you probably want to use some sort of mechanical thermostat, which turns on your boiler if the temperature drops below the safe threshold.
In the worst-case scenario, your OpenTherm hardware stop communicating with the boiler. Proper boiler implementation will flag external panel error and take control back, following the external thermostat circuit state.
The second issue can be with your thermostat logic, especially if your logic is running on some external device. To address this, OpenTherm integration is using Diagnostics Indication to enable central heating. That way, if your external thermostat report freezing condition, OpenTherm integration activates heating. To enable this option, set the CHOD flag.
Note
Another use case for the CHOD flag might be an external hot water tank storage using central heating to heat the hot water in the tank.
"},{"location":"OpenTherm/#configuration","title":"Configuration","text":"OpenTherm integration supports the following commands.
ot_flags Get/Set OpenTherm flagsot_tboiler Get/Set central heating temperatureot_twater Get/Set domestic hot water temperatureot_save_setpoints Save central heating and domestic hot water temperaturesot_ch Activate/Deactivate central heating
"},{"location":"OpenTherm/#ot_flags-command","title":"ot_flags command","text":"OpenTherm integration supports the following flags:
CHOD - Enable CH (central heating) on diagnostics flag. See External Thermostat sectionDHW - Enable Domestic Hot Water. If you have an on-demand gas heater, it won't start heating immediately, but enable heating when water is onCH - If set, activate central heating permanently, following the ot_tboiler setpoint value. If disabled and CHOD is set, it follows the Diagnostics flag. Otherwise, heating is controlled by the ot_ch statusCOOL - Enable cooling, if supported. Refer to your boiler manual.OTC - Enable external temperature compensation thermistor. Refer to your boiler manual.CH2 - Enable auxiliary central heating. Refer to your boiler manual.
Note
During the first run, ot_flags is set to the CHOD,DHW. Hot water setpoint set to 36-degree Celsius and central heating temperature set to 85 degree celsius
To get OpenTherm flags, type ot_flags
13:49:48 CMD: ot_flags\n13:49:48 MQT: stat/boiler/RESULT = CHOD,DHW\n
To set OpenTherm flags, type ot_flags DHW,CH,OTC
13:49:48 CMD: ot_flags DHW,CH,OTC\n13:49:48 MQT: stat/boiler/RESULT = DHW,CH,OTC\n
"},{"location":"OpenTherm/#ot_tboiler-command","title":"ot_tboiler command","text":"ot_tboiler set boiler (CH) desired temperature. The actual command to the boiler will be issued if your new temperature difference bigger than the OPENTHERM_BOILER_SETPOINT_TOLERANCE value which is 1-degree Celsius as of today.
14:12:04 CMD: ot_tboiler\n14:12:04 MQT: stat/boiler/RESULT = {\"ot_tboiler\":60.0}\n
14:12:55 CMD: ot_tboiler 85\n14:12:55 MQT: stat/boiler/RESULT = {\"ot_tboiler\":85.0}\n14:12:57 [OTH]: Setting Boiler Temp. Old: 60, New: 85\n
Note
Some boilers might write setpoint temperature into the Flash memory. Having PID controlled appliance may produce a lot of small fluctuations in the setpoint value, wearing out Boiler flash memory.
Warning
ot_tboiler do not write the value in the Tasmota settings, reducing Flash memory writes. To store it permanently, invoke ot_save_setpoints command after ot_tboiler command
"},{"location":"OpenTherm/#ot_twater-command","title":"ot_twater command","text":"ot_twater set domestic hot water temperature setpoint (DHW).
Warning
ot_twater do not write the value in the Tasmota settings. To store it permanently, invoke ot_save_setpoints command after ot_twater command.
14:13:55 CMD: ot_twater\n14:13:55 MQT: stat/boiler/RESULT = {\"ot_twater\":38.0}\n
14:13:55 CMD: ot_twater 40\n14:13:55 MQT: stat/boiler/RESULT = {\"ot_twater\":40.0}\n
"},{"location":"OpenTherm/#ot_save_setpoints-command","title":"ot_save_setpoints command","text":"ot_save_setpoints store boiler and domestic hot water setpoints into the flash memory of the Tasmota.
"},{"location":"OpenTherm/#ot_ch-command","title":"ot_ch command","text":"ot_ch enable or disable central heating (CH). The Boiler follows the ot_tboiler temperature setpoint.
14:14:57 CMD: ot_ch\n14:14:57 MQT: stat/boiler/RESULT = {\"ot_ch\":0}\n
14:15:57 CMD: ot_ch 1\n14:15:57 MQT: stat/boiler/RESULT = {\"ot_ch\":1}\n
Warning
ot_ch 0 won't turn the boiler off, if CHOD flag is set and external thermostat requires heat
"},{"location":"OpenTherm/#setting-hot-water-temperature","title":"Setting Hot Water temperature","text":"One of the drawbacks, at least with my boiler, is that the boiler disables all the external knobs, so I can not set up the desired hot water temperature from the boiler itself. You might come up with the automation, setting hot water temperature by some schedule.
Another way is to use Home Assistant with the HomeKit integration. I created MQTT Hot Water Heater integration to the Home Assistant, so the Water Heater is exposed to the Home Kit. You should be able to install it through HACS
You can add the following configuration into the configuration.yaml of your Home Assistant set up.
water_heater:\n platform: mqtt_water_heater\n name: \"Water Heater\"\n state_topic: \"tele/boiler/SENSOR\"\n command_topic: \"cmnd/boiler/OT_TWATER\"\n value_template: \"{{ value_json.OPENTHERM.DHWS }}\"\n qos: 0\n availability_topic: \"tele/boiler/LWT\"\n payload_available: \"Online\"\n payload_not_available: \"Offline\"\n target_temperature: 38\n heater_min_temperature: 35\n heater_max_temperature: 50\n
"},{"location":"OpenTherm/#automation-examples","title":"Automation Examples","text":"This automation example turns on then Bathroom towel heater if someone is using hot water more than 5 minutes in the evening or more than 7 minutes in the evening. Bathroom towel heater has a coolant pump relay at 192.168.1.xx Also, it always turns on the heater on Clock#Timer3 event, working according to the schedule
It publishes state to the st/boiler/rr_dry for the Home Assistant bookkeeping. Also, it set boiler temperature to the %var3% value if external heating is required during the bathroom Dry mode.
Also, it syncs up the coolant pump state in case of the pump controller power outage.
# var1 - hot water ON time to enable bathroom Dry mode\n# var2 - Bathroom Dry Mode boiler setpoint\n# var3 - Normal Mode boiler setpoint\n# var15 - a lock of the flame mode to avoid timer restart\n# var16 - sync power4 state\n# use VAR3 to set the actual boiler temperature setpoint\n\n# If heat demand is on during RR Dry Mode, the temperature should be set back to the normal\n\nRule1\non system#boot do backlog TelePeriod 20; var1=540; var2=60; var3=85; var15 0; var16 0 endon\non tele-OPENTHERM#SLAVE#FL do WebSend [192.168.1.xx] POWER4 %var16%; endon\non Clock#Timer=1 do var1=300 endon\non Clock#Timer=2 do var1=420 endon\non Clock#Timer=3 do event dr=1 endon\non var3#state do ot_tboiler %value% endon\n\nRule2\non tele-OPENTHERM#SLAVE#DHW>%var15% do backlog RuleTimer1 %var1%; var15 1 endon\non tele-OPENTHERM#SLAVE#DHW=0 do backlog RuleTimer1 0; var15 0 endon\non Rules#Timer=2 do backlog ot_ch 0; ot_tboiler %var3%; var16 0; WebSend [192.168.1.xx] POWER4 OFF; publish st/boiler/rr_dry 0 endon\non Rules#Timer=1 do event dr=1 endon\non event#dr do backlog RuleTimer2 7200; ot_ch 1; ot_tboiler %var2%; var16 1; WebSend [192.168.1.xx] POWER4 ON; publish st/boiler/rr_dry 1 endon\n\nRule3\non tele-OPENTHERM#SLAVE#DIAG=1 do ot_tboiler %var3%; endon\non tele-OPENTHERM#SLAVE#DIAG=0 do ot_tboiler %var2%; endon\n
"},{"location":"P1-Smart-Meter/","title":"P1 Smart Meter","text":"Reading serial data from a P1 smart meter using a Wemos with Tasmota installed.
Tested on the following smart meters:
- Kaifa MA105C
- De Landis + Gyr, E350 (ZCF110)
- Landis + Gyr, E360
- Sanxing SX631 (S34U18)
"},{"location":"P1-Smart-Meter/#schematics","title":"Schematics","text":"The transistor makes sure that the RxD signal is converted and inverted to 3.3V. According to the DSMR v5.0.2 P1 specification the P1 connector on the meter provides 5V DC output for the OSM (Other Service Module) connected to this port, which is able to continuously supply maximum current of 250mA. A Wemos D1 mini module draws way less than 100mA so it is perfectly safe to use this as a power source. It can be powered through the 5V pin just inserting a protection diode.
"},{"location":"P1-Smart-Meter/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page, select module Generic (18)
From the web console set the serial delimiter to 10 (newline). This makes Tasmota publish each line of the telegram separately to mqtt.
SerialDelimiter 10SerialSend 1
For more details see serial-bridge.
Should you run into problems with serial buffer overflows, then try to increase the serial buffer size using SerialBuffer 520. This will not be automatically persisted, so try the command first and when the device works fine after having increased the serial buffer size, then try to add a rule like:
Rule1 ON Power1#Boot DO SerialBuffer 520 ENDON\n
"},{"location":"P1-Smart-Meter/#example-output","title":"Example output","text":"Below an example of the telegram message published (per line) to mqtt. From here your HA system can process the data required for your needs.
09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"/KFM5KAIFA-METER\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-3:0.2.8(42)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:1.0.0(200913101618S)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.1.1(4530303235303030303639363432393136)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:1.8.1(005779.835*kWh)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:1.8.2(005583.617*kWh)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:2.8.1(000000.000*kWh)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:2.8.2(000000.000*kWh)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.14.0(0001)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:1.7.0(00.498*kW)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:2.7.0(00.000*kW)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.7.21(00000)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.7.9(00000)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:99.97.0(1)(0-0:96.7.19)(000101000001W)(2147483647*s)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:32.32.0(00000)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:32.36.0(00000)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.13.1()\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-0:96.13.0()\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:31.7.0(002*A)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:21.7.0(00.496*kW)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"1-0:22.7.0(00.000*kW)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-1:24.1.0(003)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-1:96.1.0(4730303332353631323736373836373136)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"0-1:24.2.1(200913100000S)(04139.079*m3)\\r\"}\n09:16:17 MQT: tele/wemos-9/RESULT = {\"SerialReceived\":\"!F798\\r\"}\n
"},{"location":"P1-Smart-Meter/#description-of-each-line","title":"Description of each line","text":"see also DSMR 5.0 - P1 Companion Standard
Header information - {\"SerialReceived\":\"/KFM5KAIFA-METER\"}\nEmpty line - {\"SerialReceived\":\"\"}\nVersion information for P1 output - {\"SerialReceived\":\"1-3:0.2.8(42)\"}\nDate-time stamp of the P1 message - {\"SerialReceived\":\"0-0:1.0.0(181227093413W)\"}\nEquipment identifier - {\"SerialReceived\":\"0-0:96.1.1(4530303235303030303639363432393136)\"}\nelectricityUsedTariff1 >> Meter Reading electricity delivered to client (Tariff 1) in 0,001 kWh - {\"SerialReceived\":\"1-0:1.8.1(002293.192*kWh)\"}\nelectricityUsedTariff2 >> Meter Reading electricity delivered to client (Tariff 2) in 0,001 kWh - {\"SerialReceived\":\"1-0:1.8.2(002523.640*kWh)\"}\nMeter Reading electricity delivered by client (Tariff 1) in 0,001 kWh - {\"SerialReceived\":\"1-0:2.8.1(000000.000*kWh)\"}\nMeter Reading electricity delivered by client (Tariff 2) in 0,001 kWh - {\"SerialReceived\":\"1-0:2.8.2(000000.000*kWh)\"}\nelectricityActiveTariff >> Tariff indicator electricity. The tariff indicator can also be used to switch tariff dependent loads e.g boilers. This is the responsibility of the P1 user - {\"SerialReceived\":\"0-0:96.14.0(0002)\"}\nActual electricity power delivered (+P) in 1 Watt resolution - {\"SerialReceived\":\"1-0:1.7.0(00.474*kW)\"}\nActual electricity power received (-P) in 1 Watt resolution - {\"SerialReceived\":\"1-0:2.7.0(00.000*kW)\"}\nNumber of power failures in any phase - {\"SerialReceived\":\"0-0:96.7.21(00000)\"}\nNumber of long power failures in any phase - {\"SerialReceived\":\"0-0:96.7.9(00000)\"}\nPower Failure Event Log (long power failures) - {\"SerialReceived\":\"1-0:99.97.0(1)(0-0:96.7.19)(000101000001W)(2147483647*s)\"}\nNumber of voltage sags in phase L1 - {\"SerialReceived\":\"1-0:32.32.0(00000)\"}\nNumber of voltage swells in phase L1 - {\"SerialReceived\":\"1-0:32.36.0(00000)\"}\nText message max 1024 characters. - {\"SerialReceived\":\"0-0:96.13.1()\"}\nText message max 1024 characters. - {\"SerialReceived\":\"0-0:96.13.0()\"}\nInstantaneous current L1 in A resolution - {\"SerialReceived\":\"1-0:31.7.0(002*A)\"}\nInstantaneous active power L1 (+P) in W resolution - {\"SerialReceived\":\"1-0:21.7.0(00.474*kW)\"}\nInstantaneous active power L1 (-P) in W resolution - {\"SerialReceived\":\"1-0:22.7.0(00.000*kW)\"}\nDevice-Type - {\"SerialReceived\":\"0-1:24.1.0(003)\"}\nEquipment identifier (Gas) - {\"SerialReceived\":\"0-1:96.1.0(4730303332353631323736373836373136)\"}\nGasMeterReadingFiveMinutes >> Last 5-minute value (temperature converted), gas delivered to client in m3, including decimal values and capture time - {\"SerialReceived\":\"0-1:24.2.1(181227090000W)(02910.491*m3)\"}\n{\"SerialReceived\":\"!5E3E\"}\n
Also see Tasmota's Smart Meter Interface if you want to have these OBIS lines translated in selected sensors populatinng MQTT payloads. Additional info * Kaifa Meters (Dutch) * DSMR 5.0 - P1 Companion Standard
"},{"location":"PAJ7620/","title":"PAJ7620U2 gesture sensor","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_PAJ7620\n#define USE_PAJ7620 // [I2cDriver34] Enable PAJ7620 gesture sensor (I2C address 0x73) (+2.5k code)\n#endif\n
PAJ7620U2 is an integrated gesture recognition I2C sensor from PixArt-Imaging Inc. based on infrared. It also has built-in proximity detection and can sense various properties like position (x,y,z) and speed.
Gesture recognition seems to be more stable than with the APDS-9960, which on the other hand is a lot cheaper.
"},{"location":"PAJ7620/#configuration","title":"Configuration","text":""},{"location":"PAJ7620/#wiring","title":"Wiring","text":"Breakout ESP VCC/VIN +3.3VDC GND GND SCL GPIOy SDA GPIOx INT Not used"},{"location":"PAJ7620/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
After a reboot the driver will detect the PAJ7620 automatically.
After restart Tasmota needs some time to completely configure its state. In this time frame it is likely to miss some gestures. This should stabilize after a few moments.
"},{"location":"PAJ7620/#commands","title":"Commands","text":"To use the sensor you need to switch to the desired mode of operation with Sensor50 <x> where <x> = 0\u20265. It will not appear in the webUI but it can be observed via MQTT messages in console.
"},{"location":"PAJ7620/#0-off","title":"0 - Off","text":"Sensor muted, no readings in Tasmota.
"},{"location":"PAJ7620/#1-gesture-mode","title":"1 - Gesture Mode","text":"Reports gesture movement with: Up Down Left Right Near Far CW (clockwise rotation) CCW (counter-clockwise rotation)
As expected, \"Near\" and \"Far\" gestures are tricky and you have to train your movements to catch them. Sometimes the sensor reports \"Near\" and \"Far\" at once (which will be discarded). There is some postprocessing to allow the object (hand or finger) to move into the sensing area and delay the initial direction report (up, down, left, right) to give the chance to trigger (the intended) \"Near\" or \"Far\" movement. Especially \"Far\" is a bit harder to achieve.
example: \u2026{Up:1} = up gesture once \u2026{Left:3} = left gesture 3 times in a row, without any other gesture in between
"},{"location":"PAJ7620/#2-proximity-mode","title":"2 - Proximity Mode","text":"Arbitrary values between 0 (far away) and 255 (very near) are given. Exit from the sensor field will always give at least one \"zero message\". tele is only triggered, when the value has changed.
example: \u2026{Proximity:255} = close proximity, almost touching the sensor \u2026{Proximity:0} = object has left the sensing area
"},{"location":"PAJ7620/#3-corner-mode","title":"3 - Corner Mode","text":"Sensing area is organised in quarters. An object in one of the corners will trigger the corresponding number.
1 2 3 4 example: \u2026{Corner:2} = object in upper right corner
"},{"location":"PAJ7620/#4-pin-mode","title":"4 - PIN Mode:","text":"A fluent movement of an object through a given sequence of corners (similar to unlocking a smartphone) will trigger a valid \"PIN\". The next corner must be reached in about 0.7 seconds.
example: \u2026{PIN:1} = valid PIN
"},{"location":"PAJ7620/#5-cursor-mode","title":"5 - Cursor Mode:","text":"Shows x- and y-coordinates. Mainly intended for debugging and \"seeing\" the sensing area. This reads only the upper 5-bit-values, which automatically removes much of the jitter, giving values between 0 and 15.
example: \u2026{x:1, y:15} = upper left corner
The sensor provides some more goodies, like velocity of an object, so if someone has a fancy use case for this, feel free to open a feature request. Of course it would be possible to mix the modes, but this can produce a lot of MQTT-messages. This could be added later upon user request (based on real world use cases).
"},{"location":"PAJ7620/#breakout-boards","title":"Breakout boards","text":""},{"location":"PCA9557/","title":"PCA9557 GPIO Expander","text":"Technical Data from the manufacturer: * NXP PCA9557
The PCA9557 has 8 IO pins which the PCA9557 driver uses as D0 - D7. This is visualized in the circuit diagram below.
You will need to pick an I2C address using the address mapping according to pin A0, A1, and A2 as from the datasheet as follows:
"},{"location":"PCA9557/#supporting-modes","title":"Supporting modes","text":"Starting with Tasmota v12.5.0.x several and mixed PCA9557 are supported, adding switches, buttons and relays acted on as if they were directly connected to the ESP8266 or ESP32 configured using a JSON file containing a template describing the GPIO's as used on the basic Tasmota device.
To enable it you will only need to add in user_config_override.h
#define USE_PCA9557
This enables the driver which in turn at restart will search for the JSON file in three possible locations:
- if a filesystem is present it looks for file
pca9557.dat - if not found and rules are supported it looks for a specific rule entry like
on file#pca9557.dat do <template> endon - if not found and scripts are supported it looks for a specific script like
-y <template>
If no JSON file is found the driver does not claim any PCA9557 device.
A typical JSON template would look like {\"NAME\":\"PCA9557 expander\",\"BASE\":0,\"GPIO\":[224,225,226,227,32,33,34,35]} which adds four relays and four buttons.
The template consists of a \"NAME\" data pair with any description of the template, an optional \"BASE\" data pair selecting if either relative (0 = default) or absolute (1) button and/or switch numbering is used and a \"GPIO\" data pair with numbers representing the functions of the GPIO's in order from lowest I2C address IO0 to highest I2C address IO7 and are based on the numbers known from the base tasmota template used on the ESP8266 or ESP32.
The following list contains the current supported functions:
Function Code Description None 0 Not used Button_n1..32 Bn 64..95 Button to Gnd (needs external resistor) Button_in1..32 Bin 128..159 Button inverted to Vcc (needs external resistor) Switch_n1..28 Sn 192..219 Switch to Gnd (needs external resistor) Relay1..32 R 224..255 Relay Relay_i1..32 Ri 256..287 Relay inverted Output_Hi Oh 3840 Fixed output high Output_lo Ol 3872 Fixed output low Some example templates
S3 S2 B2 B3 Oh B1 S1 R1 R4 R2 R3 S4\n{\"NAME\":\"PCA9557\",\"GPIO\":[194,193,65,66,3840,64,192,0,224,0,0,0,227,225,226,195]}\n\nInverted relays and buttons Ri1 Ri2 Ri3 Ri4 Ri5 Ri6 Ri7 Ri8 B1 B2 B3 B4 B5 B6 B7 B8\n{\"NAME\":\"PCA9557 A=Ri1-8, B=B1-8\",\"GPIO\":[256,257,258,259,260,261,262,263,32,33,34,35,36,37,38,39]}\n\nUnique inverted relays and buttons with offset 2 Ri3 Ri4 Ri5 Ri6 Ri7 Ri8 Ri9 Ri10B3 B4 B5 B6 B7 B8 B9 B10\n{\"NAME\":\"PCA9557 A=Ri2-10, B=B2-10\",\"BASE\":1,\"GPIO\":[258,259,260,261,262,263,264,265,34,35,36,37,38,39,40,41]}\n\nButtons, relays, buttons and relays B1 B2 B3 B4 B5 B6 B7 B8 R1 R2 R3 R4 R5 R6 R7 R8 B9 B10B11B12B13B14B15B16R9 R10 R11 R12 R13 R14 R15 R16\n{\"NAME\":\"PCA9557 A=B1-8, B=R1-8, C=B9-16, D=R9-16\",\"GPIO\":[32,33,34,35,36,37,38,39,224,225,226,227,228,229,230,231,40,41,42,43,44,45,46,47,232,233,234,235,236,237,238,239]}\n
Since the PCA9557 has no interrupt pin, buttons and switches will be polled every 50ms.
You will need to define the address you are using in user_config_override.h for the driver to know on which address the PCA9557 is expected to be found.
#define USE_PCA9557_ADDR 0x18
The PCA9557 chips allow for both INPUT and OUTPUT.
If OUTPUT is enabled, telemetry data for the current state of OUTPUT pins will also be provided by telemetry.
"},{"location":"PCA9557/#usage-of-the-driver","title":"Usage of the driver","text":"The PCA9557 chip (or breakout board) must be connected to the ESP8266/ESP32 and the I2C pins must be configured for the module similar to the following:
Once that is complete you may want to confirm that the Tasmota firmware is finding your PCA9557 chip by sending the command through serial or MQTT: I2Cscan
You should see a response giving you an address within the range of the PCA9557 chip (0x18 through 0x1F) which may look as follows MQT: stat/tasmota/RESULT = {\"I2CScan\":\"Device(s) found at 0x18\"}
If the extender is not detected, check your wiring and pin configuration.
If sucessful, you should be able to see the changes in Tasmota main web page. Following example has 8 IO lines defined as relays:
"},{"location":"PCA9557/#configuration-example","title":"Configuration example","text":"You can add all necessary settings at once in your user_config_override.h. The following example adds 8 relays (commanded with POWER1 to POWER8), PCA9557 has all address bits tied to GND (0x18) while ESP8266 GPIO 0 and 2 are used for I2C SDA and SCL.
#define USE_PCA9557\n#define USE_PCA9557_ADDR 0x18\n\n#define USER_TEMPLATE \"{\\\"NAME\\\":\\\"Lights\\\",\\\"GPIO\\\":[608,0,640,0,0,0,0,0,0,0,0,0,0,0],\\\"FLAG\\\":0,\\\"BASE\\\":18}\"\n#define USER_RULE1 \"On file#pca9557.dat DO {\\\"NAME\\\":\\\"Lights\\\",\\\"BASE\\\":0,\\\"GPIO\\\":[256,257,258,259,260,261,262,263]} ENDON\"\n
"},{"location":"PCA9685/","title":"PCA9685 12-bit PWM controller","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_PCA9685\n#define USE_PCA9685 // [I2cDriver1] Enable PCA9685 I2C HW PWM Driver - Must define I2C Address in #define USE_PCA9685_ADDR below - range 0x40 - 0x47 (+1k4 code)\n#define USE_PCA9685_ADDR 0x40 // Enable PCA9685 I2C Address to use (Must be within range 0x40 through 0x47 - set according to your wired setup)\n#define USE_PCA9685_FREQ 50 // Define default PWM frequency in Hz to be used (must be within 24 to 1526) - If other value is used, it will revert to 50Hz\n#endif\n
Technical Data: Product Information from NXP
"},{"location":"PCA9685/#implementation-status-in-tasmota","title":"IMPLEMENTATION STATUS IN TASMOTA","text":"The PCA9685 driver is implemented in such a way that it may be used as standard individual OUTPUT pins, or as PWM capable OUTPUT pins - The latter offloads the PWM functionality from the ESP8266 insofar that the PCA9685 will continue to perform its configured output PWM/ON/OFF state without direct control or intervention from the Tasmota firmware.
Support was added in line with the datasheet specification insofar that the PWM frequency can be set from 24hz all the way up to 1526hz.
This driver does not currently have any perpetual settings so will revert to a base frequency of 50hz (usually suitable for most applications) and will be set in an OFF state for all pins during power-up and/or reset.
The latter may change as the driver grows in cases where user requirements and development requirements are met.
"},{"location":"PCA9685/#usage-of-the-pca9685-driver-in-tasmota","title":"USAGE OF THE PCA9685 DRIVER IN TASMOTA","text":"The driver needs to be connected to the I2C bus of your Tasmota powered device (note that most Sonoff devices will not have reachable I2C pins so it's applicable to a limited number, so most likely only applicable to bare ESP8266 or WeMos type users.
If you modify a Sonoff or similar device to gain access to the I2C bus please be aware that other problems may persist and that for such use cases support in Tasmota chat or Issues is not guaranteed in any way whatsoever)
For information on how to set up a development environment please check the wiki on PlatformIO
Note that the I2C selection must correspond with how you have wired the module or chip as incorrect addressing will result in the PCA9685 not being detected. The valid I2C address range is 0x40 through 0x47 for the PCA9685 and most off-the-shelf modules would likely default to 0x40.
If you are unsure please use I2CScan from Tasmota console to scan for devices on the I2C bus and you should find a device within the mentioned range.
You may also get a discovery on 0x70 but please do not use this address as it is a broadcast address and the driver does not currently support its implementation.
Also be aware of other I2C devices you have connected to the same Tasmota driven device in order to avoid I2C address conflicts.
Once connected, correctly flashed, and configured Tasmota will detect the device automatically on startup.
"},{"location":"PCA9685/#driver-usage","title":"DRIVER USAGE","text":"There is no web interface for this driver. The driver is used via MQTT or console command using the following available commands and their respective parameters
driver15 pwmf,frequency // where frequency is the PWM frequency from 24 to 1526 in Hz\ndriver15 pwm,pin,pwmvalue // where pin = LED pin 0 through 15 and pwmvalue is the pulse width between 0 and 4096\ndriver15 pwm,pin,ON // Fully turn a specific pin/LED ON\ndriver15 pwm,pin,OFF // Fully turn a specific pin/LED OFF\ndriver15 reset // Reset to power-up settings - i.e. F=50hz and all pins in OFF state\ndriver15 status // Will return a JSON string containing all the current settings / parameters\n
"},{"location":"PCA9685/#other-important-information","title":"OTHER IMPORTANT INFORMATION","text":" - Please remember to consider the voltage and current limitations of the chip and per pin output current limitations as outlined in the datasheet.
- You may also get a discovery on 0x70 but please do not use this address as it is a broadcast address and the driver does not currently support its implementation.
- Also be aware of other I2C devices you have connected to the same Tasmota driven device in order to avoid I2C address conflicts.
"},{"location":"PCA9685/#outstanding-feature-requests","title":"OUTSTANDING FEATURE REQUESTS","text":" - Dimming ON / OFF a dimming value in a certain time and fade on \"ON / OFF\" (Not yet scheduled for implementation)
- Allow usage of RGBW in pairs of 4 PWM outputs (i.e. drive 4 x 4pin RGBW LED's) (Not yet scheduled for implementation)
"},{"location":"PCF8574/","title":"PCF8574 / PCF8574A GPIO Expander","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_I2C // Add support for I2C\n#define USE_PCF8574 // [I2cDriver2] Enable PCF8574 I/O Expander (I2C addresses 0x20 - 0x26 and 0x39 - 0x3F) (+2k1 code)\n// #define USE_PCF8574_MODE2 // Enable Mode2 virtual relays/buttons/switches (+2k3 code)\n// #define USE_PCF8574_SENSOR // Enable Mode1 inputs and outputs in SENSOR message (+0k2 code)\n// #define USE_PCF8574_DISPLAYINPUT // Enable Mode1 inputs display in Web page (+0k2 code)\n// #define USE_PCF8574_MQTTINPUT // Enable Mode1 MQTT message & rule process on input change detection : stat/%topic%/PCF8574_INP = {\"Time\":\"2021-03-07T16:19:23+01:00\",\"PCF8574-1_INP\":{\"D1\":1}} (+0k5 code)\n
In order to use PCF8574 mode 2, uncomment USE_PCF8574_MODE2. In order to use inputs, uncomment the last three lines."},{"location":"PCF8574/#introduction","title":"Introduction","text":"PCF8574 and PCF8574A are I2C 8-bit IO port extender originally designed by Philips (now NXP) but also now available from various manufacturer.
- PCF8574 and PCF8574A at NXP
- PCF8574 and PCF8574A at Texas Instruments
As usual when using an electronic part, reading the datasheet is highly recommended as the below document only focus on Tasmota integration.
A few different breakout boards are available although some are dedicated to be mounted as a backpack on standard 16x2 or 16x4 LCD displays and are not suitable for general I/Os (but works well with tasmota-display).
- On the left: generic modules suitable for extending IO
- On the right: specific module to control a LCD display (not the purpose of this doc page)
"},{"location":"PCF8574/#supported-i2c-addresses-and-number-of-pcf8574","title":"Supported I2C addresses and number of PCF8574","text":"PCF8574 and PCF8574A are identical functionally and each can be configured to work on 1 of 8 possible I2C address. PCF8574 can use one address of 0x20 to 0x27 and PCF8574A can use one of 0x38 to 0x3F.
As of today, Tasmota driver supports:
- Up to 4 PCF8574 OR PCF8574A is supported by Tasmota allowing up to 32 additional GPIO pins.
- Addresses 0x27 and 0x38 are excluded to avoid conflict with other I2C peripheral which can't be differentiated at run-time.
If USE_MCP230xx_ADDR is defined, this address is reserved for MCP230XX IO expander.
The first 2 lines are mandatory to enable I2C support and including the driver in the build. The 3 other lines allows to add optional features to support inputs. By default only the \"outputs\" feature is enabled.
"},{"location":"PCF8574/#tasmota-configuration","title":"Tasmota Configuration","text":"Note
Once the firmware with the PCF8574 driver has been loaded, make sure to have it enabled with I2Cdriver2 1.
Starting with Tasmota v12.4.0.2 there are two different modes to use PCF8574(A):
- The original approach (now called Mode 1) supports user configurable features using a GUI menu.
- The latest approach called Mode 2, supports adding switches, buttons and relays configured using a JSON file containing a template describing the GPIO's as used on the basic Tasmota device.
"},{"location":"PCF8574/#mode-2","title":"Mode 2","text":"To enable Mode 2 you will need to add in user_config_override.h
#define USE_PCF8574_MODE2
This enables the driver which will at restart search for the JSON file in three possible locations:
- if a filesystem is present it looks for file
pcf8574.dat - if not found and rules are supported it looks for a specific rule entry like
on file#pcf8574.dat do <template> endon - if not found and scripts are supported it looks for a specific script like
-y <template>
Note
If no JSON file is found the driver continues in mode 1.
A typical JSON template would look like {\"NAME\":\"PCF8574 expander\",\"BASE\":0,\"GPIO\":[224,225,226,227,32,33,34,35]} which adds four relays and four buttons.
The template consists of a \"NAME\" data pair with any description of the template, an optional \"BASE\" data pair selecting if either relative (0 = default) or absolute (1) button and/or switch numbering is used and a \"GPIO\" data pair with numbers representing the functions of the GPIO's in order from lowest I2C address D0 to highest I2C address D7 and are based on the numbers known from the base tasmota template used on the ESP8266 or ESP32.
The following list contains the current supported functions:
Function Code Description None 0 Not used Button1..32 B 32..63 Button to Gnd with internal pullup Button_n1..32 Bn 64..95 Button to Gnd without internal pullup Button_i1..32 Bi 96..127 Button inverted to Vcc with internal pullup Button_in1..32 Bin 128..159 Button inverted to Vcc without internal pullup Switch1..28 S 160..187 Switch to Gnd with internal pullup Switch_n1..28 Sn 192..219 Switch to Gnd without internal pullup Relay1..32 R 224..255 Relay Relay_i1..32 Ri 256..287 Relay inverted Output_Hi Oh 3840 Fixed output high Output_lo Ol 3872 Fixed output low Some example templates
Unique inverted relays and buttons with offset 2 B3 B4 B5 B6 Ri3 Ri4 Ri5 Ri6 B7 Ri7 B8 Ri8 B9 Ri9 B10Ri10\n{\"NAME\":\"PCF8574 A=B3456,Ri3456,B=B7Ri7B8Ri8B9Ri9B10Ri10\",\"BASE\":1,\"GPIO\":[34,35,36,37,258,259,260,261,38,262,39,263,40,264,41,265]}\n\nInverted relays and buttons Ri8 Ri7 Ri6 Ri5 Ri4 Ri3 Ri2 Ri1 B1 B2 B3 B4 B5 B6 B7 B8\n{\"NAME\":\"PCF8574 A=Ri8-1, B=B1-8\",\"GPIO\":[263,262,261,260,259,258,257,256,32,33,34,35,36,37,38,39]}\n\n B1 B2 B3 B4 Ri4 Ri3 Ri2 Ri1 B5 B6 B7 B8 Ri8 Ri7 Ri6 Ri5\n{\"NAME\":\"PCF8574 A=B1-4,Ri4-1, B=B5-8,Ri8-5\",\"GPIO\":[32,33,34,35,259,258,257,256,36,37,38,39,263,262,261,260]}\n
"},{"location":"PCF8574/#mode-1","title":"Mode 1","text":"PCF8574 can be configured from Tasmota web GUI in \"Configure\" => \"Configure PCF8574\"
Each IO port can be configured as Input or Output in a similar way as a native GPIO of the ESP.
If you are using outputs to drive relays, it is possible to choose if the relay is activated by a HIGH signal (checkbox \"Invert Ports\" unchecked) or a LOW signal (checkbox checked). The selection applies to all output ports. This checkbox can also be controlled by SetOption81.
Once configuration is complete, it must be saved by clicking on the green \"Save\" button. Like for general ESP GPIO configuration, this will trigger a reboot of the ESP.
It is not possible to change pin definition at run-time.
"},{"location":"PCF8574/#outputs","title":"Outputs","text":"A PCF8574 pin configured as an output support all features of a Tasmota Relay component.
It is assigned a Power index and can be controlled by Power command (on, off, toggle). Power indexes of PCF8574 outputs are assigned after the ESP GPIO configured as Relay. For example, if you have Relay 1 (Power1) to Relay 4 (Power4) configured on the ESP's GPIO, PCF8574 outputs will start at Power5.
A state text and an on/off button are automatically created on the Web GUI and syncs with the pin state.
All Power features are supported including PowerOnState, PulseTime, Blink, SetOption0, ...
"},{"location":"PCF8574/#usage","title":"Usage","text":"Enabling USE_PCF8574_SENSOR adds a PCF8574-xx field into the JSON payload of the tele/topic/SENSOR message. The form of the message is:
{\"Time\":\"2021-03-11T19:50:58+01:00\",\"PCF8574-1\":{\"D0\":1,\"D1\":1,\"D2\":1,\"D3\":1,\"D4\":0,\"D5\":0,\"D6\":0,\"D7\":0}}\n
As you can see, all pins are listed, including both inputs and outputs. The value reported is the digital level of the pin. If \"Invert Ports\" has been enabled, Power ON will be reported as 0 as the pin is at a LOW level.
As for any sensor published in the tele/topic/SENSOR message, it is possible to use Rules triggers such as:
ON tele-PCF8574-1#D0 DO something_with %value% ENDON\n
Numerical operators such as == can be used to compare to 0 or 1. See also change detection."},{"location":"PCF8574/#pcf8574-inputs-pins-in-the-web-gui","title":"PCF8574 inputs pins in the Web GUI","text":"Enabling USE_PCF8574_DISPLAYINPUT will add the state of PCF8574 inputs displayed as sensors in the Web GUI. Outputs are not represented here as they are already shown as Power.
Value of pin is updated in almost \"real-time\".
"},{"location":"PCF8574/#input-change-detection","title":"Input Change Detection","text":"While reporting the pin level in SENSOR or on the GUI is interesting, it is even better to detect pin change. This is enabled by USE_PCF8574_MQTTINPUT. When this feature is enabled at build time, a test will be performed every 50ms to detect if an input pin has changed. In that case, Tasmota will publish on stat/topic/PCF8574_INP a JSON payload with the PCF8574 index and the pin level:
20:19:39.385 MQT: stat/topic/PCF8574_INP = {\"Time\":\"2021-03-11T20:19:39+01:00\",\"PCF8574-1_INP\":{\"D0\":0}}\n20:19:39.584 MQT: stat/topic/PCF8574_INP = {\"Time\":\"2021-03-11T20:19:39+01:00\",\"PCF8574-1_INP\":{\"D0\":1}}\n
This can be caught in rules such as:
Implementing a Power push \"Button\":
ON PCF8574-1_INP#D0=0 DO Power2 toggle ENDON\n
"},{"location":"PID-Control/","title":"PID Control","text":"This extension adds a PID (Proportional Integral Derivative) feature into the Tasmota software.
The PID algorithm is designed to be used to control real-world processes. This includes room heating/cooling, temperature control when brewing, and a multitude of other processes. The PID tuning parameters are designed to be meaningful in the real world (rather than the abstract Ki Kd Kp that are often used which are completely meaningless to most). The algorithm is based on that in the node-red node node-red-contrib-pid which has been well received.
In use it can either regularly be given the current process value via MQTT or if the device has a sensor attached then that sensor can be used to read the process value. So using any Tasmota-capable device with e.g. a temperature sensor (e.g. a TH10 with a DS18B20) the complete PID loop control can be built into the device so that the process will continue to be controlled even if the wifi is down. This is a very cost effective way of achieving PID control.
The algorithm allows the relay to be used in a time proportioned way using the Time Proportioned output extension.
The loop tuning parameters can be set at build time and can be adjusted at run time via MQTT.
The feature is included in Tasmota v9.3.0 onward.
The PID code adds about 11.1k and the Timeprop code another 1k
Detailed instructions for setup are in these two xdrv files: tasmota/xdrv_48_timeprop.ino and tasmota/xdrv_49_pid.ino.
The ESP8266 will run the PID algorithm at 1 cycle per second, which is much faster than is needed for the sort of processes Sonoff devices are usually associated with. It rather clobbers the Tasmota terminal output in the web browser at that rate so it is getting near to the limit. The maximum anyone is likely to need it running at is maybe once every 5 seconds, and the majority of home IoT applications probably nearer once per minute would be sufficient, so the device is well up to the task.
Help with using the PID algorithm and with loop tuning can be found at http://blog.clanlaw.org.uk/pid-loop-tuning.html. This is directed towards using the algorithm in the node-red node node-red-contrib-pid but the algorithm here is based on the same code so the tuning technique described there should work just the same.
Due to limited hardware availability this has so far only been tested in a Sonoff Basic with a TH10, and a Sonoff Mini with a DS18B20 connected. If there are any issues running this on other hardware let us know.
"},{"location":"PIR-Motion-Sensors/","title":"PIR Motion Sensors","text":"PIR motion sensors, albeit called sensors, are configured as switches in Tasmota since they basically report motion (1) or no motion (0) to the device.
Most PIR's are single wire and they require connecting to VCC, GND and one GPIO. In this guide we will use GPIO13 as the pin that the PIR output is connected to. See PIN Restrictions on which pins not to use
"},{"location":"PIR-Motion-Sensors/#tasmota-settings","title":"Tasmota Settings","text":"In Configuration -> Configure Module menu change GPIO13 to Switch1.
If there already is a Switch1 simply choose the next in line. Same applies if you're connecting more than 1 PIR on a single device.
A configured PIR will not appear in the web UI in any form. To make it report like a sensor we need a rule that will send movement triggers to an MQTT topic.
SwitchMode1 1\nSwitchTopic 0\nRule1 on Switch1#state=1 do publish stat/%topic%/PIR1 ON endon on Switch1#state=0 do Publish stat/%topic%/PIR1 OFF endon\nRule1 1\n
You can change (PIR1) and the message (ON/OFF) to whatever suits your needs. %topic% is the configured device topic. Look in console for motion detection messages [20:24:03] stat/%topic%/PIR1 ON to verify everything is working
optional: Before using rules configure any GPIO that doesn't have anything connected to it as Relay1. This creates a dummy relay which is triggered by the PIR so you can see the changes in the web UI. This method is not recommended for daily use and should only be used for testing.
A more advanced example of rules with PIRs.
"},{"location":"PIR-Motion-Sensors/#am312","title":"AM312","text":"AM312 works even on 3.3v instead of 5v (like HC-SR501) which makes it perfect for ESP8266 devices without a 5V line (like Sonoff Basic). It is also less prone to false triggers due to Wi-Fi interference.
"},{"location":"PIR-Motion-Sensors/#pinout","title":"Pinout","text":"Pin marked VOUT is connected to a free GPIO pin on the device.
This PIR goes to off state after a few seconds so we need to use this rule instead of the one in the example.
Rule1 on Switch1#state=1 do Backlog Publish stat/%topic%/PIR1 ON; RuleTimer1 30 endon on Rules#Timer=1 do Publish stat/%topic%/PIR1 OFF endon\n
With this it will stay ON for 30 seconds then send OFF message and the timer restarts every time there's an ON trigger. Another configuration option is to change Switchmode to 14 with Pulsetime of 130 (30 seconds on every time the AM312 is triggered)
Another use case as a hand wave switch.
"},{"location":"PIR-Motion-Sensors/#hc-sr501","title":"HC-SR501","text":""},{"location":"PIR-Motion-Sensors/#pinout_1","title":"Pinout","text":"Configuration with HC-SR501 is easiest with Switchmode 1, since this module has a built-in trigger/delay potentiometers and the state remains ON during the trigger period.
"},{"location":"PIR-Motion-Sensors/#mh-sr602","title":"MH-SR602","text":"This is a very small version of a PIR that is able to modify the sensitivity and delay by soldering resistors.
With factory settings this PIR goes to off state after a few seconds so we need to use this rule instead of the one in the example.
Rule1 on Switch1#state=1 do Backlog Publish stat/%topic%/PIR1 ON; RuleTimer1 30 endon on Rules#Timer=1 do Publish stat/%topic%/PIR1 OFF endon\n
With this it will stay ON for 30 seconds then send OFF message and the timer restarts every time there's an ON trigger. "},{"location":"PIR-Motion-Sensors/#pinout_2","title":"Pinout","text":""},{"location":"PIR-Motion-Sensors/#panasonic-ekmc1603111","title":"Panasonic EKMC1603111","text":"Set the data pin to Switch n for it to work.
Datasheet
"},{"location":"PN532/","title":"PN532 NFC reader","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_PN532_HSU \n#define USE_PN532_HSU // Add support for PN532 using HSU (Serial) interface (+1k8 code, 140 bytes mem)\n// Optional defines, uncomment (remove //) as needed\n// #define USE_PN532_DATA_FUNCTION // Add sensor40 command support for erase, setting data block content (+1k7 code, 388 bytes mem)\n#endif\n
The PN532 is a highly integrated transceiver module for contactless communication at 13.56 MHz based on the 80C51 microcontroller core.
The datasheet for the PN532 chip is available here.
Please note that although the datasheet mentions that the PN532 can be used on SPI, I2C and HSUART that only the HSU interface is implemented in the Tasmota driver.
"},{"location":"PN532/#configuration","title":"Configuration","text":"#define USE_PN532_DATA_FUNCTION This function is experimental. There are limitations because it seems not all cards are supported by this driver and/or the PN532 module. See issue 4941 for more information. We are still researching the
"},{"location":"PN532/#wiring","title":"Wiring","text":"As mentioned earlier the PN532 breakout boards usually have pins broken out for all three protocols supported by the PN532 but we are only interested in the HSU interface as that is all the driver currently supports.
For this reason breakout boards have either micro dip switches as shown in the image below, or they have pads on the PC board which you need to bridge out with solder to select which mode the PN532 will operate in.
After selecting the correct protocol mode and connecting the HSU TX/RX pins of the PN532 to the pins you configured on your ESP8266 board you can power it up and the PN532 should be detected automatically.
PN532 ESP GND GND VCC 3.3V SDA GPIOx SCL GPIOy"},{"location":"PN532/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
PN532 Rx (139) - GPIOy to
PN532 Tx (138)
The module will reboot when you save this configuration. During start-up the following information should be visible in your console output:
00:00:00 NFC: PN532 NFC Reader detected V1.6\n
If the device was not found please check your wiring and configuration and confirm that everything is as it should be. Example
Configured using Wemos D1 mini on pins: D1 (connected to PN532 SCL) and D2 (connected to PN532 SDA)
"},{"location":"PN532/#usage","title":"Usage","text":"Tasmota will scan for a new card detect 4 times per second and if found will report it via immediate telemetry.
The output on the console will look similar to the below when a new card is detected
18:23:24 MQT: tele/tasmota/SENSOR = {\"Time\":\"2019-01-10T18:23:24\",\"PN532\":{\"UID\":\"94D8FC5F\", \"DATA\":\"\"}}\n18:23:24 MQT: stat/tasmota/RESULT = {\"Event\":\"Done\"}\n18:23:25 MQT: stat/tasmota/RESULT = {\"Event\":\"Done\"}\n
The UID of the card/tag is reported and any text stored in BLOCK 1 of a Mifare Classic card or PAGE4-7 of a NTAG card (up to 16 characters in length) is reported in the DATA field of the JSON sent via telemetry. Please note that the DATA field field can contain only printable chars.
The content of the DATA on BLOCK 1 of a Mifare Classic (PAGE4-7 of a NTAG) card can be set as follows
Sensor40 WRITE,I LOVE TASMOTA
Once executed the very next card/tag that is presented to the reader will be programmed accordingly and the data will be retained on the card/tag until either changed or erased.
To erase the content of the DATA field the following command may be used
Sensor40 ERASE
Once executed the very next card/tag that is presented to the reader will have its BLOCK 1 (PAGE4-7 of a NTAG) erased.
For canceling previous command he following command may be used
Sensor40 CANCEL
Once executed will stop waiting next card/tag.
For NTAG213/215/216, NT3H2111/2211 or compatible are additionally available commands: AUTH, SET_PWD, UNSET_PWD for password operations.
Warning. The password is a unsigned 32 bit and acknowledge is a unsigned 16 bit values.
Sensor40 AUTH,password,ack
Set tasmota password phrase and password acknowledge for authentication.
Sensor40 SET_PWD or Sensor40 SET_PWD,new_password or Sensor40 SET_PWD,new_password,new_ack
Write current password and ack / new password and current ack / new password and new acknowledge to a NTAG21x tag.
Sensor40 UNSET_PWD
Clear password and ack in a NTAG21x tag.
Text logging of the above two actions are also presented during the process for information purposes.
"},{"location":"PN532/#using-the-uid-and-data-of-a-presented-card","title":"Using the UID and DATA of a presented card","text":"When a card is presented to the PN532 under normal operating conditions up to 3 ways of using the data is possible.
The first is the immediate telemetry generated which looks as follows. For not NTAG21x:
18:31:39 MQT: tele/tasmota/SENSOR = {\"Time\":\"2019-01-10T18:31:39\",\"PN532\":{\"UID\":\"94D8FC5F\", \"DATA\":\"ILOVETASMOTA\"}}\n
For NTAG21x and correct password and acknowledge:
20:05:48 MQT: tele/tasmota/SENSOR = {\"Time\":\"2023-02-24T20:05:48\",\"PN532\":{\"UID\":\"53BB1F05110001\",\"Data\":\"I love tasmota\",\"Auth\":\"Ok\"}}\n
For NTAG21x and correct password and not correct acknowledge:
20:05:48 MQT: tele/tasmota/SENSOR = {\"Time\":\"2023-02-24T20:05:48\",\"PN532\":{\"UID\":\"53BB1F05110001\",\"Data\":\"I love tasmota\",\"Auth\":\"NOk\"}}\n
For NTAG21x and not password protection in a tag:
20:05:48 MQT: tele/tasmota/SENSOR = {\"Time\":\"2023-02-24T20:05:48\",\"PN532\":{\"UID\":\"53BB1F05110001\",\"Data\":\"I love tasmota\",\"Auth\":\"None\"}}\n
Since this is an immediate telemetry generation as opposed to the sensor data you would normally be expected to be presented when the telemetry period occurs, this telemetry data is not directly usable on the device itself. It is generated and immediately transmitted over MQTT and the purpose of this is so that immediate action may be taken by any home automation software you are using with the data obtained from the card/tag as opposed to waiting for the telemetry period to expire and be sent with normal telemetry data.
For the purpose of using card/tag data on the device itself you will need to use rules along with the events that are caused.
Example
Example rule for responding to a specific UID on the device when a card/tag matching a specific UID is presented
rule1 on PN532#UID=94D8FC5F do power on endon\n
Example
Example rule for responding to a specific DATA content that was previously programmed to one or more cards using the Sensor40 write,xxxx command
Rule 1on EVENT#PN532_DATA=ILOVETASMOTA do power on endon\n
18:41:12 MQT: tele/tasmota/SENSOR = {\"Time\":\"2019-01-10T18:41:12\",\"PN532\":{\"UID\":\"94D8FC5F\", \"DATA\":\"ILOVETASMOTA\"}}\n18:41:13 MQT: stat/tasmota/RESULT = {\"Event\":\"Done\"}\n18:41:13 MQT: stat/tasmota/RESULT = {\"Event\":\"Done\"}\n18:41:13 RUL: EVENT#PN532_DATA=ILOVETASMOTA performs \"power on\"\n18:41:13 MQT: stat/tasmota/RESULT = {\"POWER\":\"ON\"}\n18:41:13 MQT: stat/tasmota/POWER = ON\n
"},{"location":"PN532/#breakout-boards","title":"Breakout Boards","text":"Since the PN532 chip itself is surface mount and requires some external components to operate the best is probably to obtain a breakout board similar to the one below from your favourite online supplier.
Please make sure the breakout board you order has the HSU pins (SCL=TX and SDA=RX) broken out as it will be very difficult to add them manually - Usually they have them but for good measure just make sure.
"},{"location":"PS-16-DZ-Dimmer/","title":"PS-16-DZ Dimmer","text":"The PS-16-DZ dimmer uses eWeLink app same as Sonoff devices. It's available from Amazon and Aliexpress. It may under different name, but the model number is PS-16-DZ.
"},{"location":"PS-16-DZ-Dimmer/#pics","title":"Pics","text":"Opened it up, found an ESP8285 and a Nuvoton N76E003.
"},{"location":"PS-16-DZ-Dimmer/#flash-and-gpio-pins","title":"Flash and GPIO pins","text":"Remove the ESP8285 daughter card DLX-MKCK01 from the main board and flash Tasmota.
pin1 RST -> N76E003 P0.5/PWM2\npin2 TXD -> N76E003 P0.7/RXD\npin3 RXD -> N76E003 P0.6/TXD\npin4 GPIO13/MTCK -> LED\npin5 3.3V\npin6 GND\n
"},{"location":"PS-16-DZ-Dimmer/#communication-between-esp8285-and-n76e003","title":"Communication between ESP8285 and N76E003","text":"It uses AT command to communicate between ESP8285 and N76E003 over UART at 19200 baud.
Turn on the switch from ESP8266:\nSend from ESP8266\nAT+UPDATE=\"sequence\":\"1528335040032\",\"switch\":\"on\"\nReceive from MCU\nAT+RESULT=\"sequence\":1528335040032\"\nSend from ESP8266:\nAT+SEND=ok\nAfter 0.7s\nReceive from MCU\nAT+UPDATE=\"switch\":\"on\",\"bright\":44\nSend from ESP8266:\nAT+SEND=ok\n\nTurn off the switch from ESP8266:\nSend from ESP8266\nAT+UPDATE=\"sequence\":\"1528335118327\",\"switch\":\"off\"\nReceive from MCU\nAT+RESULT=\"sequence\":1528335118327\"\nSend from ESP8266:\nAT+SEND=ok\nAfter 0.7s\nReceive from MCU\nAT+UPDATE=\"switch\":\"on\",\"bright\":44\nSend from ESP8266:\nAT+SEND=ok\n\nChange brightness to 44 from ESP8266:\nSend from ESP8266:\nAT+UPDATE=\"sequence\":\"1528335181502\",\"bright\":44\nReceive from MCU\nAT+RESULT=\"sequence\":1528335181502\"\nSend from ESP8266:\nAT+SEND=ok\nAfter 0.7s\nReceive from MCU\nAT+UPDATE=\"switch\":\"on\",\"bright\":44\nSend from ESP8266:\nAT+SEND=ok\n\nTurn on the switch with faceplate button:\nReceived from MCU\nAT+UPDATE=\"switch\":\"on\",\"bright\":44\nSend from ESP8266:\nAT+SEND=ok\n\nTurn off the switch with faceplate button:\nReceived from MCU\nAT+UPDATE=\"switch\":\"off\",\"bright\":44\nSend from ESP8266:\nAT+SEND=ok\n\nChange the brightness to 52 with faceplate button:\nReceived from MCU\nAT+UPDATE=\"switch\":\"on\",\"bright\":52\nSend from ESP8266:\nAT+SEND=ok\n\nHolding the middle button on faceplate to reset the device:\nReceived from MCU\nAT+SETTING=enterESPTOUCH\nSend from ESP8266:\nAT+SETTING=enterESPTOUCH\n
The sequence number is a 13 digits unix timestamp (in milliseconds). The data after \"bright\" is the brightness. The maximum of the brightness is 100 and the minimum is 10. There is one byte 0x1B at the end of each AT command."},{"location":"PWM-dimmer-switch/","title":"PWM Dimmer","text":"PWM dimmer is supported in standard tasmota.bin
To enable PWM dimmer operation, select the PWM Dimmer module.
PWM Dimmer module adds support for PWM dimmer switches and devices with one or more buttons that control devices in a device group. The brightness of the load for PWM dimmers is controlled by a PWM GPIO pin. They typically have power, up and down buttons, a powered-on LED, five brightness LEDs and another status LED. The SD0x dimmer from Martin Jerry, Acenx, Tessan or NTONPOWER is an example of such a device.
Any other device with one or more buttons, such as any typical Tasmota-capable wall switch, can make use of the PWM Dimmer module to control the power, brightness and light channels of one or more device groups. For single-button devices or multi-button devices with remote device mode enabled, only the operations controlled by the power button in the instructions below apply. Examples include:
"},{"location":"PWM-dimmer-switch/#pwm-dimmer-operation","title":"PWM Dimmer Operation","text":"Pressing and releasing the power button toggles the power on/off. If the toggle turns the power on, the light is returned to the last brightness it was set to. If Fade is enabled, the light is faded on/off at the rate defined by the Speed setting.
When the power is on, holding the down or up button decreases/increases the brightness. The brightness can also be changed using just the power button. When the power is on, holding the power button alternately increases or decreases the brightness. Initially, holding the power button increases the brightness. Releasing and then holding the power button again decreases the brightness.
When the power is off, pressing and releasing the down or up button turns the power on at a temporary brightness of the low/high levels set by the BriPreset command. Turning the power on at the low preset can also be accomplished by holding the power button while the power is off. The brightness presets are intended to enable quickly turning on a light to a dim or bright level without changing the normal desired brightness. Turning the power on to a preset does not change the brightness the light will be set to when the switch is turned on the next time. For example, if the light is on and you adjust the brightness to 80 and then turn the light off, when you turn it back on, the brightness will return to 80. If you turn the power off again and then press the down button, the light will be turned on at the brightness defined by the low preset. If you then turn the light off and on again, the brightness will return to 80.
If there are LEDs defined in the template, they are turned on to indicate the current brightness. More LEDs are turned on at higher brightnesses. SetOption86 enables/disables the LED timeout. If SetOption86 is enabled, the LEDs turn off five seconds after the last change in brightness. Note that the lowest LED and the blue power LED are always on when the power is on. The LED timeout can also be enabled/disabled by holding the power button while tapping (pressing and releasing quickly) the down button.
The LedLink LED can be used as a nightlight/powered-off indicator. SetOption87 enables/disables turning the LedLink LED on when the power is off. The powered-off indicator can also be enabled/disabled by holding the power button and tapping the up button.
Holding the power button and then holding the down or up button publishes an MQTT EVENT command. The topic follows the format of the Full Topic with a subtopic of EVENT (ex. cmnd/LightSwitch1/EVENT). The MQTT payload is Trigger#, where # is 1 if the down button is held or 2 if the up button is held. These triggers can be used in rules on remote devices (ON Event#Trigger1) or by automation software to trigger automations such as scene changes. For example, the Event topic Trigger1 payload could trigger the automation software to turn on the previous scene in a list and the Trigger2 payload could trigger the automation software to turn on the next scene in a list.
Holding the power button, tapping the down button and then tapping or holding the down or up button sends a device group message to set CW/RGB/RGBW/RGBCW lights in the device group to the previous/next fixed color. The command is sent/value is adjusted once every .75 seconds for as long as the button is held. The color sequence is red, green, blue, orange, light green, light blue, amber, cyan, purple, yellow, pink, white using RGB channels; cold white using CT channels; and warm white using CT channels.
Holding the power button, tapping the up button and then tapping or holding the down or up button publishes an MQTT Event command. The command is sent once every .75 seconds for as long as the button is held. The MQTT topic is as described above. The MQTT payload is Trigger#, where # is 3 if the down button is held or 4 if the up button is held.
Pressing and releasing the power button and then holding the power button publishes an MQTT Event command. The command is sent once every .75 seconds for as long as the button is held. The MQTT topic is as described above. The MQTT payload is Trigger#, where # is 5.
Button presses and holds execute the normal ButtonTopic and Rule processing. If ButtonTopic is set and SetOption61 is 0 or a the button press/hold matches a rule, the button press/hold is ignored by PWM Dimmer. Operations invoked by holding the power button in combination with the up/dowm buttons cannot be overridden by rules. Standard Tasmota multi-press button presses operate as normal.
PWM Dimmer uses the Light module to control the PWM. Brightness levels are rescaled to PWM values between the dimmer_min and dimmer_max values specified with DimmerRange. Most LED bulbs do not show a significant difference between PWM value of 1 and PWM value of 100. This results in the lower 10% of the dimmer range having no effect. For best results, DimmerRange <dimmerMin> value should be set to the highest value that results in the lowest bulb brightness (Typically in the range of 8 - 18).
When Device Groups are enabled, the PWM Dimmer brightness presets are kept in sync across all switches in the group. The powered-off LED and LED timeout settings are specific to each switch. Changing them does not replicate the change to the other switches in the group.
When CW/RGB/RGBW/RGBCW lights are in the same device group as the PWM Dimmer device, use the PWMDimmerPWMs command to define the PWM (channel) count of the lights. This allows the PWM Dimmer module to correctly determine the brightness (dimmer) level and allows the color of all the lights in the device group to be controlled from the PWM Dimmer device.
"},{"location":"PWM-dimmer-switch/#commands","title":"Commands","text":"Command Parameters BriPreset <low>,<high> = set brightness low and high presets1..255 = set brightness preset+ = increase brightness preset- = decrease brightness preset LedMask Set a bitmask specifying which LEDs are used to indicate the current brightness. LEDs not included in the bitmask can be controlled with LedPower.<bitmask> = bitwise value representing each LED. Values may be entered as either hexadecimal or decimal values (e.g., 0xFFFF = 65535). Note that LED 0 is tied to the relay and is always used to indicate the first level of brightness. 0xFFFF (= 1111 1111 1111 1111) All LEDs are used to indicate the brightness (default)Ex.: LedMask 3 = Use LEDs 0, 1 and 2 to indicate the brightness. PWMDimmerPWMs Set the PWM (channel) count of lights in the device group controlled by the module (CW=2, RGB=3, RGBW=4, RGBCW=5). SetOption86 Set brightness LED timeout0 = disable timeout (default)1 = enable timeout SetOption87 Set powered-off LED (nightlight)0 = disable powered-off LED (default)1 = enable powered-off LED SetOption88 Set remote device mode0 = disable remote device mode(default)1 = enable remote device mode"},{"location":"PWM-dimmer-switch/#remote-device-mode","title":"Remote Device Mode","text":"Remote device mode allows PWM Dimmer switches to control remote devices. With remote device mode enabled, each button controls a different device.
Remote device mode is included in the default Tasmota binary. To include remote device mode support in other builds, define USE_PWM_DIMMER_REMOTE and USE_DEVICE_GROUPS in your user_config_override. Remote device mode support requires device group support. Remote device mode support adds 1K to the code size in addition to the code size required for device groups support.
To enable remote device mode, execute SetOption88 1 (the device will restart). Each remote device must be running firmware with device group support and have remote device support enabled. Remote devices do not need to be built with PWM Dimmer support nor do they need to be switches.
If a remote device also uses the PWM Dimmer module, the device acts like a 3-way dimmer switch and may or may not have a load connected to it. All PWM Dimmer switches in the device group can control the power, brightness and color of one or more smart lights with Tasmota with device group support loaded on them.
When remote device mode is enabled, button 1 is the power button for the local device while buttons 2 and 3 are the power buttons for remote devices. Group names for buttons 2 and 3 are set by the DevGroupName2 and DevGroupName3 commands respectively. Note that the button numbers are defined by the module template and can be in any physical order on the switch (button 1 can be defined as the top button, the middle button or the bottom button). Button combinations that publish MQTT Event commands use a topic in the format cmnd/%group-topic%/EVENT.
While holding a button, the other two buttons act like the down and up buttons for the remote device associated with the first button pressed. All the functions performed by the down and up buttons in non-remote device mode are available in remote device mode. While holding button 1, button 2 performs the functions of the down button and button 3 performs the functions of the up button. While holding button 2, button 1 performs the functions of the down button and button 3 performs the functions of the up button. While holding button 3, button 1 performs the functions of the down button and button 2 performs the functions of the up button.
"},{"location":"PZEM-0XX/","title":"PZEM-0xx power monitor","text":"PZEM is a dedicated separate energy monitor, device calibration in Tasmota is not supported.
"},{"location":"PZEM-0XX/#pzem-004","title":"PZEM-004","text":" The PZEM-004T together with a Sonoff Basic provide a good clamp on energy monitor.
"},{"location":"PZEM-0XX/#parts-needed","title":"Parts needed","text":" - Sonoff Basic
- PZEM-004T
- Resistor 1k
- Enclosure
- Power cable
"},{"location":"PZEM-0XX/#preparation","title":"Preparation","text":"Install Tasmota on the Sonoff Basic and confirm it is functional before connecting the PZEM-004T to its serial interface.
"},{"location":"PZEM-0XX/#hardware-connections","title":"Hardware connections","text":"As the PZEM-004T RX optocoupler series resistor (1K ohm, R15 for v.1 .0 and R8 for v.3.0 ) is designed for 5V, that resistor value had to be reduced in order to achieve the current for driving the RX optocoupler diode. This can be accomplished by soldering a 1k resistor between the joints shown below (modification works for version v.1.0 and v.3.0). The resistor has to be connected between VDD (5V/3.3V) terminal and the RX opto terminal 1.
PZEM-004T v.1.0
PZEM-004T v.3.0 It can be used a SMD resistor 102 or 1001 (1K) soldered near/parallel with R8 or a normal resistor (THT) similar to that used on the image of v.1.0 The resistor is placed in different place on v.3.0 because the optocouplers RX and TX are reversed compared to v.1.0
Connect the serial interface of the Sonoff Basic with the serial interface of the PZEM-004T. See pictures regarding used colors and connections.
- 3V3/5V Red
- Rx Yellow
- Tx Green
- Gnd Grey
(Image re-used from https://www.instructables.com/id/Use-Homie-Firmware-to-Drive-Sonoff-Switch-Module-E/ Thanks @amayii0)
If you need 5V you can use directly from Sonoff (for something else) but do not connect to PZEM logic because this will result in a big flash (kaboom!, the sonoff LIVE line may reach the PZEM NEUTRAL or viceversa). Using 5V from Sonoff for PZEM TTL port is safe but the resistor mod explained above must be undone and another mod is needed for dropping the PZEM TX line from 5V to 3.3V. So, the simplest way is to use 3.3V from Sonoff to 5V TTL terminal of the PZEM and the resistor mod explained in the above images.
Cut the power cable in two and connect the input wires to both Sonoff Basic and PZEM-004T. Route one of the power output wires through the PZEM-004T core and connect the output wires to the Sonoff Basic output.
As most parts are connected to high voltage AC it is recommended to fit the hardware in a solid enclosure.
"},{"location":"PZEM-0XX/#software-configuration","title":"Software configuration","text":"Configure the GPIO's for hardware serial connection as shown below.
IMPORTANT: If using the connections as following, the communication works in all cores due to TASMOTA using hardware serial. If the user wants to use other GPIOs for communication, TASMOTA will emulate a serial interface using software serial. This feature does not work using core 2.3.0 due to insufficient RAM. To use the software serial feature, you must use a core version of 2.4.2 or greater.
Device Template PZEM-004T version prior to V3:
{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,63,0,0,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":1}
"},{"location":"PZEM-0XX/#pzem-004t-version-v3","title":"PZEM-004T version V3","text":"{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,98,0,0,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":1}
The PZEM-004T together with a HW-655 Relay provide a good clamp-on energy monitor for a 240V clothes dryer.
"},{"location":"PZEM-0XX/#parts-needed_1","title":"Parts needed","text":" - Circuit Box
- 3-prong Dryer Electrical Cord (Note - some households use a 4-prong plug)
- 3-prong Dryer Receptacle (Note - some households use a 4-prong plug)
- PZEM-004T
- HW-655 w/ ESP-01
- ESHION SPSD-5S AC-DC 5V Buck Converter
- 4-pin Serial Connector
- DuPont Connectors & 22 AWG wire
"},{"location":"PZEM-0XX/#preparation_1","title":"Preparation","text":"Install Tasmota on the ESP-01 and confirm it is functional before connecting the PZEM-004T to its serial interface. Use of pins other that the default hardware serial GPIO (01 & 03) in order for TASMOTA to emulate a serial interface using software serial.
"},{"location":"PZEM-0XX/#hardware-connections_1","title":"Hardware connections","text":"Connect the serial interface of the HW-655 with the serial interface of the PZEM-004T.
As most parts are connected to high voltage AC it is recommended to fit the hardware in a solid enclosure.
"},{"location":"PZEM-0XX/#software-configuration_1","title":"Software configuration","text":"Device Template PZEM-004T version prior to V3:
{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,63,0,0,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":18}
"},{"location":"PZEM-0XX/#pzem-004t-version-v3_1","title":"PZEM-004T version V3","text":"{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,98,0,0,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":18}
Use the module template to configure the GPIO's for hardware serial connection.
IMPORTANT: If using the connections as following, the communication works in all cores due to TASMOTA using hardware serial. If the user wants to use other GPIOs for communication, TASMOTA will emulate a serial interface using software serial. This feature does not work using core 2.3.0 due to insufficient RAM. To use the software serial feature, you must use a core version of 2.4.2 or greater.
"},{"location":"PZEM-0XX/#connected-power-meter-using-pzem-004t-wemos-d1-mini-and-a-1602-i2c-display","title":"Connected Power Meter using PZEM-004T, Wemos D1 Mini and a 1602 I2C display","text":""},{"location":"PZEM-0XX/#parts-needed_2","title":"Parts needed","text":" - Wemos D1 Mini
- PZEM-004T
- 1kOhm Resistor (optional - see alternate wiring)
- Enclosure
- 5V buck converter power supply (search for \"700ma 3.5w 5v\" on usual stores...)
- I2C 1602 LCD Display (I had issues with green one, I2C address 0x3F, while no problems with blue ones, address 0x27)
- Mains Power cable
- Mammuth Clamps
"},{"location":"PZEM-0XX/#preparation_2","title":"Preparation","text":"You need to compile your own Tasmota firmware as none of the pre-compiled binaries have support for display and PZEM module.
Set up your preferred IDE as described in wiki
"},{"location":"PZEM-0XX/#enable-ide-to-use-custom-settings","title":"Enable IDE to Use Custom Settings","text":"Create user_config_override.h in the tasmota folder and paste the contents of this sample configuration file.
"},{"location":"PZEM-0XX/#platformio","title":"PlatformIO","text":" - Rename platformio_override_sample.ini. to platformio_override.ini
- Enter
platformio run -e <variant-name> Examples: platformio run -e tasmota-sensors platformio run -e tasmota-DE
"},{"location":"PZEM-0XX/#arduino-ide","title":"Arduino IDE","text":" - Edit my_user_config.h. Uncomment the statement by removing the \"//\" in front of the line:
#define USE_CONFIG_OVERRIDE - Click compile
Flash the binary on the Wemos D1 Mini and confirm it is functional before connecting the PZEM-004T to its serial interface.
"},{"location":"PZEM-0XX/#tasmota-parameter-configuration","title":"Tasmota Parameter Configuration","text":"Device Template PZEM-004T version prior to V3:
{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,63,6,5,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":18}
"},{"location":"PZEM-0XX/#pzem-004t-version-v3_2","title":"PZEM-004T version V3","text":"{\"NAME\":\"HW-655 PZEM\",\"GPIO\":[0,62,0,98,6,5,0,0,0,0,0,0,0],\"FLAG\":0,\"BASE\":18}
"},{"location":"PZEM-0XX/#images-and-wiring-diagram","title":"Images and Wiring diagram","text":"DANGER - MAINS VOLTAGE. Be sure to crimp connectors and use heat-shrinking tube wherever possible/needed, and tightly secure any screw.
How it looks, from web GUI:
How it looks, from enclosure:
You can set the contrast using the little trimmer/pot on back of the display. I cut a bit of the corners from the display to have it flush with border, and used two hexagonal plastic standoffs with nuts and bolts to secure it to transparent top.
Mains IN, mains OUT, all sealed:
Wiring Diagram: * Check images below for more information about the 1kOhm resistor needed to use 3.3V instead of 5V for the PZEM-004T serial connection.
PZEM-004T v.1.0
PZEM-004T v.3.0
"},{"location":"PZEM-0XX/#calibration","title":"Calibration","text":"Per Theo - As the PZEM is a dedicated energy monitor, device calibration in TASMOTA is currently not supported.
"},{"location":"PZEM-0XX/#pzem-016","title":"PZEM-016","text":" DO NOT PERFORM THIS MODIFICATION WITHOUT REMOVING POWER FROM THE PZEM FIRST!
Note: the PZEM-016 TTL output is at 5V signal levels. There are varying schools of thought on whether the ESP82xx has 5V tolerant GPIO. You may want to use a level shifter for the serial communications signals to bring them to the recommended 3.3V.
PZEM-016 modules can be converted from RS485 to TTL serial level devices by simply removing the internal MAX485 chip and adding two internal jumper wires. This will bring the serial port connections out via the four-pin terminal block. Pin A is now TTL serial out (Tx) and pin B TTL serial in (Rx). The modification retains the optical isolation used by the PZEM for safety to ensure no high voltages on the outputs.
You can use a voltage level shifter to power the ESP82xx from the PZEM-016 module's 5V power. This may also require a 470uf 35V capacitor across the 5V line to work reliably.
"},{"location":"PZEM-0XX/#tasmota-configuration","title":"Tasmota Configuration","text":"It is recommended to use GPIO1/GPIO3 or GPIO13/GPIO15 for the most reliable serial communications. When using other GPIOs software serial will be activated and used.
GPIO Component PZEM 1 PZEM0XX Tx (62) Pin B 3 PZEM016 Rx (98) Pin A"},{"location":"Peripherals/","title":"Peripherals","text":"Peripherals are sensors, displays, controllers, LEDs and other devices wired to available GPIO pins of your device
Tip
A peripheral must have correctly wired power, GND and data pins to the device prior to booting in order for Tasmota to detect it and initialize it properly.
"},{"location":"Peripherals/#supported-peripherals","title":"Supported peripherals","text":""},{"location":"Peripherals/#tasmota-settings","title":"Tasmota Settings","text":" Tasmota allows for easy selection of peripherals and assignment to GPIO pins.
Configuration is possible in the webUI Configuration - Configure Module page
or by using commands: Module and GPIO, or Template.
"},{"location":"Peripherals/#module","title":"Module","text":"First select desired module for the device (Wait for the restart). Depending on the type of Module, only certain GPIO pins are user configurable. Module Generic (18) has all the GPIOs configurable.
Modules shows supported modules
"},{"location":"Peripherals/#gpio","title":"GPIO","text":"Assign a component to a GPIO.
GPIO14 2 configures sensor AM2301 to GPIO14_ Backlog GPIO14 5; GPIO4 6 sets I2C SCL to GPIO14 and I2C SDA to GPIO4 Tasmota will auto-detect all connected and supported I2C devices. If you have conflicting I2C addresses see I2CDEVICES
GPIOs All shows list of all available components by name and index
For a peripheral to show up you may need to power cycle your device instead of a soft restart.
"},{"location":"Peripherals/#template","title":"Template","text":"Instead of using Module and GPIO you can define everything using Template. Read more...
"},{"location":"Peripherals/#additional-options","title":"Additional Options","text":""},{"location":"Peripherals/#measurement-units","title":"Measurement Units","text":"Temperature units can be set to Celsius or Fahrenheit with SetOption8 command.
Pressure units can be set to hPa or mmHg with SetOption24 command.
"},{"location":"Peripherals/#update-interval","title":"Update Interval","text":"To change the update interval (TelePeriod) of MQTT messages change the TelePeriod. Default interval is 300 seconds but can be set between 10 and 3600 seconds. TelePeriod 10 will set the update interval to 10 seconds, so the sensor will update 6 times a minute.
"},{"location":"Peripherals/#peripheral-specific","title":"Peripheral Specific","text":"Some peripherals offer, or even require, additional commands. See Sensor commands page for peripheral specific commands.
Tip
To make a link between the different naming schemes the Pin Definition overview in the ESP8266 wiki is quite helpful.
"},{"location":"Peripherals/#examples","title":"Examples","text":""},{"location":"Peripherals/#connect-switch","title":"Connect switch","text":"If you take a Sonoff Basic and connect a switch between pin4 (GND) 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 Switch1 (9) or from the command line with gpio14 9.
See Buttons and Switches for more information.
"},{"location":"Peripherals/#connect-jack","title":"Connect jack","text":"Instead of connecting a switch, you could connect a 4-pin 2.5mm jack, with the pins wired:
Jack Pin ESP8266 tip 5 GPIO14 R1 no connection R2 1 GND R3 4 3.3V You can then plug a sensor into the jack like you would to a Sonoff TH and define what sensor you have connected to GPIO14.
"},{"location":"Peripherals/#restrictions","title":"Restrictions","text":"Danger
If you can avoid it, don't use GPIOs: 0, 1, 2, 6-11, 15 and 16. That leaves 4, 5, 12, 13, 14 as GPIOs without any constraints. 3 being RX is also good to avoid (PWM is not working on this GPIO).
Others can be used but you have to mind the constraints outlined in this document.
"},{"location":"Peripherals/#voltage-and-current","title":"Voltage and Current","text":"Danger
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 release the magic smoke (fry the chip). The maximum current that can be drawn from a single GPIO pin is 12mA.
"},{"location":"Peripherals/#power-supply","title":"Power Supply","text":"It is important to have a reliable power supply
The power supplied to the device is one of the most important elements for stable device operation. Many devices on the market have barely adequate power supplies for normal operation. Connected peripherals may strain the ability of the power supply on the device to deliver appropriate power to all the components, both on-board as well as externally connected.
Voltage regulation issues typically result in fatal exception fault code 1. You must ensure that the device receives sufficient power (current and appropriate voltage level). Take into account the current that each wired component (f.e. sensor) will draw from the device itself.
"},{"location":"Peripherals/#electrical-considerations","title":"Electrical Considerations","text":"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.
- add a pull-up resistor
- add a bypass capacitor
- shielding on the wire
- 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 (issue#2708)
"},{"location":"Peripherals/#esp8266-in-depth","title":"ESP8266 In Depth","text":"Complete document available from https://tttapa.github.io/ESP8266/Chap04%20-%20Microcontroller.html
"},{"location":"Peripherals/#digital-io","title":"Digital I/O","text":"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).
"},{"location":"Peripherals/#usable-pins","title":"Usable Pins","text":"The ESP8266 and ESP8285 have 17 GPIO pins (0-16) but several are reserved or have constraints. Do not use any of the reserved pins. If you do, you might crash your program. On the ESP8266, six pins (GPIO 6 - 11) are used to interface the flash memory (the small 8-legged chip usually right next to the ESP8266). The ESP8285 has its flash memory integrated into the chip which frees up GPIO 9 and 10.
GPIO 1 and 3 are used as TX and RX of the hardware Serial port (UART), so in most cases, you can\u2019t use them as normal I/O while sending/receiving serial data. GPIO 1, 2 and 3 will cause boot failure if LOW on boot - use with care.
"},{"location":"Peripherals/#boot-mode-pins","title":"Boot Mode Pins","text":"Some I/O pins have a special function during boot: They select 1 of 3 boot modes:
GPIO15 GPIO0 GPIO2 Mode 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\u2019t 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\u2019t 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\u00b2C. GPIO0 is pulled high during normal operation, so you can\u2019t use it as a Hi-Z input. GPIO2 can\u2019t be low at boot, so you can\u2019t 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.
"},{"location":"Peripherals/#pwm","title":"PWM","text":"ESP8266 Unlike most Atmel chips (Arduino), the ESP8266 doesn\u2019t 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.
ESP8266 has only software and supports 5 PWM channels. PWM and PWMi GPIOs are used in two modes depending on SetOption15: either as lights or as pure PWM.
ESP32 has hardware PWM support, named ledc, up to 16 channels depending on CPU type. You can mix lights and pure PWM channels. The first 5 PWM are reserved for lights, unless SetOption15 0. For pure PWM GPIOs, you can assign any PWM number, they don't need to be continuous. For example you can use PWM 1/2/3 for a 3-channel RGB light, and PWM 6 & PWM 10 for pure PWM at the same time.
CPU type PWM channels ESP32 16 channels ESP32S2 8 channels ESP32C3 6 channels Channels are assigned to GPIOs in a first-in-first-serve way, and PWM GPIOs are assigned first. If ledc channel are exhausted, an error will appear in logs.
The following GPIOs use ledc PWM channels:
GPIO type Description PWM or PWMi PWM 1..5 are used for lights, PWM O6..11 are general purpose PWM. LedPwmMode Assigns a Led GPIO to a PWM channel Buzzer If BuzzerPwm is used Backlight PWM backlighting for displays XCLK Used as a clock generator for webcam Example of PWM console output with 16 PWM assigned. By default PWM range is 0..1023.
RSL: RESULT = {\"PWM\":{\"PWM1\":410,\"PWM2\":286,\"PWM3\":286,\"PWM4\":0,\"PWM5\":0,\"PWM6\":0,\"PWM7\":0,\"PWM8\":0,\"PWM9\":0,\"PWM10\":0,\"PWM11\":0,\"PWM12\":0,\"PWM13\":0,\"PWM14\":0,\"PWM15\":0,\"PWM16\":0}}\n
"},{"location":"Peripherals/#auto-phasing-of-pwm","title":"Auto-phasing of PWM","text":"(ESP32 only) By default, phases of consecutive PWM are disaligned so that a PWM pulses starts when the pulse of the previous PWM channels ends. This helps in distributing over time all pulses and have a smoother effect on power supply.
With auto-phasing:
You can revert this with SetOption134 1; all phases are synces and all pulses start at the same moment.
"},{"location":"Peripherals/#h-bridge","title":"H-bridge","text":"H-bridge is an electronic circuit that switches the polarity of a voltage applied to a load. It uses 2 PWM outputs to control the current sent to each polarity.
When auto-phasing is enabled, you can use 2 consecutive PWM to drive a H-bridge siunce PWM phases don't overlap - under the condition that the sum of both PWM don't exceed 1023.
Important: you must always ensure that the sum of both PWM channels is less or equal than 1023. Values over this threshold can damage the circuit.
"},{"location":"Peripherals/#analog-input","title":"Analog Input","text":"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.
"},{"location":"Peripherals/#communication","title":"Communication","text":""},{"location":"Peripherals/#serial","title":"Serial","text":"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.
"},{"location":"Peripherals/#i2c","title":"I\u00b2C","text":"ESP8266 doesn\u2019t 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\u00b2C 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.
"},{"location":"Peripherals/#spi","title":"SPI","text":"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).
"},{"location":"Peripherals/#gpio-overview","title":"GPIO Overview","text":"NodeMCU Labelled Pin GPIO# Function State Restrictions D3 0 Boot mode select 3.3V No Hi-Z D10 1 TX0 - Not usable during Serial transmission - Boot will fail if LOW at boot D4 2 Boot mode select TX1 3.3V (boot only) Don\u2019t connect to ground at boot time - boot will fail. Sends debug data at boot time D9 3 RX0 - Not usable during Serial transmission D2 4 SDA (I\u00b2C) - - D1 5 SCL (I\u00b2C) - - x 6 - 8 Flash connection x Not usable, and not broken out x 9, 10 Flash connection * Only available on the ESP8285 x 11 Flash connection x Not usable, and not broken out D6 12 MISO (SPI) - - D7 13 MOSI (SPI) - - D5 14 SCK (SPI) - - D8 15 SS (SPI) 0V Pull-up resistor not usable (extern pull down resistor) D0 16 Wake up from sleep - No pull-up resistor, but pull-down instead Should be connected to RST to wake up"},{"location":"Pinouts/","title":"Wi-Fi Module Pinouts","text":""},{"location":"Pinouts/#esp82xx-based","title":"ESP82xx Based","text":""},{"location":"Pinouts/#esp8266-and-esp8285","title":"ESP8266 and ESP8285","text":""},{"location":"Pinouts/#esp-12eesp-12f","title":"ESP-12E/ESP-12F","text":""},{"location":"Pinouts/#esp-12s","title":"ESP-12S","text":""},{"location":"Pinouts/#esp-wroom-02","title":"ESP-WROOM-02","text":""},{"location":"Pinouts/#lm1","title":"LM1","text":""},{"location":"Pinouts/#lm2","title":"LM2","text":""},{"location":"Pinouts/#tywe1s","title":"TYWE1S","text":""},{"location":"Pinouts/#tywe2s","title":"TYWE2S","text":""},{"location":"Pinouts/#tywe2l","title":"TYWE2L","text":""},{"location":"Pinouts/#tywe3s","title":"TYWE3S","text":""},{"location":"Pinouts/#tywe3l","title":"TYWE3L","text":""},{"location":"Pinouts/#tylc4","title":"TYLC4","text":""},{"location":"Pinouts/#tylc5","title":"TYLC5","text":""},{"location":"Pinouts/#tywe5p","title":"TYWE5P","text":""},{"location":"Pinouts/#psf-b85psf-b01psf-b04","title":"PSF-B85/PSF-B01/PSF-B04","text":""},{"location":"Pinouts/#esp8266-s3","title":"ESP8266-S3","text":""},{"location":"Pinouts/#wt8266-s1","title":"WT8266-S1","text":""},{"location":"Pinouts/#449a-ecoplugs","title":"449A-ECOPLUGS","text":" Datasheet
"},{"location":"Pinouts/#cuco-z0-v11-used-by-gosund","title":"CUCO-Z0-V1.1 (Used by Gosund)","text":"Overview Front Back"},{"location":"Pinouts/#esp32-based","title":"ESP32 Based","text":""},{"location":"Pinouts/#esp32-cam","title":"ESP32-CAM","text":""},{"location":"Pinouts/#esp32-s","title":"ESP32-S","text":""},{"location":"Pinouts/#esp32-solo-1","title":"ESP32-SOLO-1","text":""},{"location":"Pinouts/#esp32-wrover","title":"ESP32-WROVER","text":"Includes ESP32-WROVER-B and ESP32-WROVER-BI
"},{"location":"Pinouts/#esp32-wroom-32x","title":"ESP32-WROOM-32x","text":""},{"location":"Pinouts/#esp32-s_1","title":"ESP32-S","text":""},{"location":"Pinouts/#esp-12k","title":"ESP-12K","text":""},{"location":"Pinouts/#esp32-c3","title":"ESP32-C3","text":""},{"location":"Pinouts/#esp-c3-12f","title":"ESP-C3-12F","text":""},{"location":"Pinouts/#esp-c3-32s","title":"ESP-C3-32S","text":""},{"location":"Pinouts/#esp-c3-13","title":"ESP-C3-13","text":""},{"location":"Pinouts/#esp-c3-01m","title":"ESP-C3-01M","text":""},{"location":"Pinouts/#devices","title":"Devices","text":""},{"location":"Pinouts/#sonoff-mini","title":"Sonoff Mini","text":""},{"location":"Pinouts/#sonoff-th","title":"Sonoff TH","text":""},{"location":"Pinouts/#sonoff-basic","title":"Sonoff Basic","text":""},{"location":"Pinouts/#digoo-dg-sp202-oxaoxe-nx-sp202","title":"Digoo DG-SP202 / OxaOxe NX-SP202","text":" (Found out by tracing the PCB copper tracks of the unknown ESP module. Not verified, except GPIO0, RX, TX, Vcc and GND which have successfully been used for flashing.)
"},{"location":"PlatformIO-CLI/","title":"PlatformIO CLI","text":"How to flash the Tasmota firmware onto a device using the platformio command line interface. This manual was tested on Ubuntu 17.10.
"},{"location":"PlatformIO-CLI/#prerequisites","title":"Prerequisites","text":""},{"location":"PlatformIO-CLI/#install-python-and-pip","title":"Install Python and PIP","text":"sudo apt-get install python-pip
"},{"location":"PlatformIO-CLI/#install-platformio-cli","title":"Install PlatformIO CLI","text":"sudo pip install -U platformio
"},{"location":"PlatformIO-CLI/#download-the-tasmota-source-code","title":"Download the Tasmota source code","text":"Either download the latest Tasmota Source code from https://github.com/arendst/Tasmota/ and extract it or clone the Git repository:
git clone https://github.com/arendst/Tasmota.git
"},{"location":"PlatformIO-CLI/#select-the-environment","title":"Select the environment","text":"The default environment configuration can be used to easily generate Tasmota firmware variants (tasmota, sensors, display, etc.). If you're not sure which binary is the right one for you, consult the builds table or just start with tasmota.bin. To build and/or flash exactly one of these, use the -e command line argument (e.g., -e tasmota-sensors).
"},{"location":"PlatformIO-CLI/#compile-and-upload","title":"Compile and upload","text":"Once all the prerequisites are in place, compiling and uploading is one simple command. Execute this from within the Tasmota source code directory:
platformio run -e <variant> --target upload --upload-port <port>
Just make sure to replace <port> with the actual serial port your device is connected to. On Windows these interfaces are named COM ports (COM1, COM2, etc.). On Linux these interfaces are named TTY ports (e.g., /dev/ttyUSB0, /dev/ttyUSB1, etc.)].
Depending on your configuration your user account may need to be in the dialout group.
"},{"location":"PlatformIO/","title":"PlatformIO","text":"How to setup and configure PlatformIO for Tasmota compilation and upload.
"},{"location":"PlatformIO/#download-platformio","title":"Download PlatformIO","text":"Download PlatformIO from https://platformio.org/
"},{"location":"PlatformIO/#install-platformio","title":"Install PlatformIO","text":"Install PlatformIO to a known folder.
"},{"location":"PlatformIO/#download-tasmota","title":"Download Tasmota","text":"Download the latest Tasmota Source code from https://github.com/arendst/Tasmota and unzip to another known folder.
"},{"location":"PlatformIO/#compile-tasmota","title":"Compile Tasmota","text":"Choose the Tasmota variant from the Platformio menu.
"},{"location":"PlatformIO/#upload-tasmota","title":"Upload Tasmota","text":"PlatformIO uses the serial interface to upload the firmware to your device. On Windows these interfaces are named COM ports (COM1, COM2, etc.). On Linux these interfaces are named TTY ports (e.g., /dev/ttyUSB0, /dev/ttyUSB1, etc.).
"},{"location":"PlatformIO/#put-device-into-programming-mode","title":"Put device into programming mode","text":"When performing a firmware upload do not connect the device to AC. Use a 3.3v DC power supply such as that provided by your serial programming adapter.
Put the device in programming mode by grounding pin GPIO0 and then applying power (e.g., connecting your computer to the serial adapter). Grounding pin GPIO0 can often be achieved by pressing the button on the device or using a wire between GPIO0 and GND if the button is not available. Deviations may apply.
"},{"location":"PlatformIO/#perform-serial-upload","title":"Perform serial upload","text":"Select Upload from the menu.
NOTE: For a proper device initialization after first firmware upload power down and power up the device.
"},{"location":"Power-Monitoring-Calibration/","title":"Power Monitoring Calibration","text":"You need to calibrate your power monitoring device as correct measurements are influenced by hardware and timing differences.
- Your power monitoring capable device flashed with Tasmota and configured with the correct module/template that supports power monitoring
- An AC capable calibrated multi-meter
- A known wattage load with a power factor as close to 1 as possible (e.g., a resistive load) for best results
Note
A resistive load device is any device which draws a constant amount of power. For example, an incandescent or halogen light bulb (best choice since their power draw is declared on them). An electric kettle, heater, or blow dryer are also options but you will also need a power meter since the power draw could vary.
Danger
Do not use switch mode driven devices such as LED lamps, computer equipment, or inductive/capacitive devices such as motors!
- (optional) A calibrated power meter (a.k.a Kill-a-Watt) or AC multi-meter
"},{"location":"Power-Monitoring-Calibration/#setup","title":"Setup","text":" - Connect the load (e.g., a 60W incandescent light bulb) to your device
- (optional) Plug your load into the Kill-a-Watt
- Open two Tasmota web UI browser windows for your power monitoring device:
- Click on Console in one browser window
- Keep the other on the main page to view the Power telemetry data
- Turn the power on to your device. Be sure to turn the output on so the load is powered on as well
- Wait a few seconds for the readings to stabilize
"},{"location":"Power-Monitoring-Calibration/#calibration-procedure","title":"Calibration Procedure","text":" -
Verify the Power reading in the web UI (optionally with the power meter as well) for the expected wattage. Adjust the power offset if needed (in Watts): PowerSet 60.0 If you're using something other than a 60W bulb, enter your load's power rating
-
Verify the Voltage reading. Adjust the voltage offset if needed (in Volts): VoltageSet <voltage> Replace <voltage> with your standard voltage or with reading on your multi-meter if you have one. Your voltage will vary depending on the electrical standards and your electrical grid
-
Verify the Current reading by calculating current value (amperage) using this formula: P(W)/V(V)=I(A). Adjust the current offset if needed (in milliAmps (mA=A*1000)): CurrentSet <current> Replace <current> with your calculated value (in milliAmps)
CurrentSet calculation: P/V=I 1000 * Watts/Volts = milliAmperes
Example
1000*(60.0/235.5) = 254.777
- Confirm the validity of your calibration process checking
Power Factor from the web UI which should be as close as possible to 1.00. In theory resistive loads will always provide a power factor of 1.00. If that is not the case, we recommend you repeat the calibration process and make sure everything was done correctly.
"},{"location":"Power-Monitoring-Calibration/#fine-tuning","title":"Fine Tuning","text":"This procedure requires the use of a calibrated power meter or AC multi-meter.
Commands CurrentCal, PowerCal and VoltageCal allow fine tuning of the power calibration.
Repeat the procedure below for each of the readings: Current, Power, and Voltage using the corresponding calibration command (CurrentCal, PowerCal, and VoltageCal respectively). Take note that the offset ranges vary for each command.
- Check the reading using a multi-meter
- Compare it with the reading on the Tasmota web UI
- If there is an observed difference, change the offset value by issuing the calibration command in the Console (e.g.,
PowerCal 10000) - Adjust the offset value up or down until the readings on the multi-meter and the web page are as close as possible
The CurrentCal, PowerCal, VoltageCal commands accept values up to 32000. If the offset values you would like to specify are larger, you may have configured an incorrect power monitoring chip in the template. For example: if you specify the BL0937 (134) while you actually have an HLW8012 (133). Change the template to proper power monitoring chip to fix.
"},{"location":"Power-Monitoring-Calibration/#known-issues","title":"Known Issues","text":"Power monitoring chips such as HLW8032 (Blitzwolf SHP5) and CSE7766 (Sonoff S31, Sonoff POW R2) occasionally report invalid power measurements for load values below 5W. During this situation it sometimes reports a valid load. By setting SetOption39 to 128 (default) it must read at least 128 invalid power readings before reporting there is no load.
To discard all loads below 6W simply set SetOption39 1 (0 will reset to default on next restart) so it will report no load below 6W.
"},{"location":"PowerOnState/","title":"PowerOnState","text":""},{"location":"PowerOnState/#poweronstate-functionality","title":"PowerOnState Functionality","text":"Command Description PowerOnState Control relay state after powering up the device. 0 / OFF = keep relay(s) OFF after power up 1 / ON = turn relay(s) ON after power up 2 / TOGGLE = toggle relay(s) from last saved state 3 = switch relay(s) to their last saved state (default) 4 = turn relay(s) ON and disable further relay control 5 = after a PulseTime period turn relay(s) ON (acts as inverted PulseTime mode) The PowerOnState device configuration parameter is applied when the device is initially powered up. It does not apply to device warm restarts.
Tasmota tracks the relays' state in a masked variable. A set bit (1) means the corresponding relay is turned ON. The associated GPIO state will be high or low according to whether the relay is configured as Relay<x> or Relay<x>i. Every command for setting the relay state is \"recorded\" in the variable and saved to flash (depending on SetOption0). The setting of the relay GPIO is then executed.
After a warm restart, the mask variable is re-initialised with the saved state from flash and the relay(s) set to that state. PowerOnState is not executed. During any a device restart, the relay power feedback state is scanned according to the setting of SetOption63. Scanning the relay state attempts to READ from GPIOs that are configured as relays, i.e., OUTPUTS! The result will not always be what is expected as it depends on how the device relays are wired to the GPIO. SetOption63 was introduced to make this scan optional. With SetOption63 set to 0 (the default), each GPIO assigned as a Relay<x> or Relay<x>i is scanned using 'digitalRead'. The mask variable will be updated with the detected values. The state of the relay(s) will not be changed. READING from an OUTPUT GPIO may result in the mask value being different from the state the relays are in. Thus, SetOption63 was introduced to disable the startup scan for devices where the scan leads to undefined results.
SetOption63 is executed after PowerOnState or restart initialization.
"},{"location":"Project-AM312-and-Sonoff-R2/","title":"Project AM312 and Sonoff R2","text":"This use case represents a method to use AM312 as a \"wave hand toggle\" (for under-cabinet kitchen LED). Please note that this solution isn't working in 100% (this sensor has a detection range of a few meters, to decrease the range you can remove the lens from the sensor but still it will pick up movement from 50 cm. You can create the Tasmota rule that will disable AM312 toggle action when the light is on and turn off the power after a few minutes. The gesture sensor APDS-9960 should work better for \"hand-wave\" toggle.
"},{"location":"Project-AM312-and-Sonoff-R2/#wiring-for-sonoff-basic-r2","title":"Wiring for Sonoff Basic R2","text":"As the R2 version doesn't have GPIO14 exposed you can use GPIO3 (RX) as the AM312 data pin. GPIO2 goes high during the boot (it would toggle the switch then).
AM312 ESP8255 device VCC 3V3 or VCC VOUT GPIO3 (RX) GND GND Remember to remove the lens to lower the sensitivity of the sensor.
"},{"location":"Project-AM312-and-Sonoff-R2/#configuration","title":"Configuration","text":" - Go to IP of the device, next Configuration --> Configure Module --> set \"GPIO3 Serial In\" to \"Switch1 (9)\"
- Go to Console and type \"SwitchMode 4\" (detailed description of SwitchModes) to enable toggle switch type.
- Set rule to turn off light after X amount of seconds (mentioned workaround):
rule1 on Switch1#State=2 do backlog Power1 1; RuleTimer1 180 endon on Rules#Timer=1 do backlog Power1 0 endon\nrule1 1\n
Rule explanation: Switch1#State=2 - fire the event when switch1 is toggled, Power1 1 - turn on power, RuleTimer1 180 - set Timer1 to 180 seconds and start counting, Rules#Timer=1 - fire the event when Timer1 has stopped, Power1 0 - turn off power.
This rule will turn off the light after 3 minutes, if the movement will be detected prior, the timer will be restarted and will count the time from the beginning.
- Instead of point 3, you can set below rules in order to ignore the second and next movements. It will just turn off the power after 3 minutes.
rule1 on Switch1#State=2 do backlog Power1 1; RuleTimer1 180; Rule1 0; Rule2 1 endon\nrule2 on Rules#Timer=1 do backlog Power1 0; Rule1 1; Rule2 0 endon on Switch1#State=2 do break\nbacklog rule1 1; rule2 0\n
Rules explanation: rule1 on Switch1#State=2 do backlog Power1 1; RuleTimer1 180; Rule1 0; Rule2 1 endon: Switch1#State=2 - fire the event when switch1 is toggled, Power1 1 - turn on power, RuleTimer1 180 - set Timer1 to 180 seconds and start counting, Rule1 0 - disable Rule1, Rule2 1 - enable Rule2.
rule2 on Rules#Timer=1 do backlog Power1 0; Rule1 1; Rule2 0 endon on Switch1#State=2 do break: Rules#Timer=1 - fire the event when Timer1 has stopped Power1 0 - turn off power Rule1 1 - enable Rule1 Rule2 0 - disable Rule2 Switch1#State=2 do break - ignore toggling
"},{"location":"Projector/","title":"LCD/DLP projector Serial Control","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_PROJECTOR_CTRL\n// _Mandatory:_ choose the communication protocol for your projector. define only one of them:\n#define USE_PROJECTOR_CTRL_NEC\n#define USE_PROJECTOR_CTRL_OPTOMA\n#define USE_PROJECTOR_CTRL_ACER\n// _Optional:_ set the Relay that powers your device (default is 1)\n#define PROJECTOR_CTRL_PWR_BY_RELAY 1 //the relay that powers the projector\n// _Optional:_ set the baudrate to communicate to your device (default is 9600):\n#define PROJECTOR_CTRL_SERIAL_BAUDRATE 9600\n// _Optional:_ enable debugging messages:\n#define DEBUG_PROJECTOR_CTRL\n// _Optional:_ Add Serial to TCP Bridge to your build if you want to play with your projector's communication protocol over network connection. Useful for ASCII protocol testing. Needs a different GPIO configuration and is completely independent to this module:\n#define USE_TCP_BRIDGE\n
"},{"location":"Projector/#description","title":"Description","text":"This driver simulates an additional relay in your Tasmota device. If you have N physical relays and you configure GPIO pin functions DLP Tx and DLP Rx you'll see relay (N+1) after reboot. The two GPIO pins will be used for serial communication with your LCD or DLP projector. The communication protocol is unique for each manufacturer (compile-time option). The driver polls the projector's state periodically and updates the fake relay state. When you toggle the fake relay, serial commands are sent to the projector to power it up or down. While the projector is running, the driver prevents to switch off the real relay that feeds the projector. This protects the lamp of the projector (needs to be cooled down before power is cut from the device).
"},{"location":"Projector/#supported-projectors","title":"Supported Projectors","text":" - NEC projectors - tested with NEC V300W
- OPTOMA projectors - not tested yet / report your results!
- Acer projectors - tested with Acer P1500 & H5360BD
Fixes and definitions for further manufacturers should go to tasmota\\xdrv_53_projector_ctrl.h
"},{"location":"Projector/#physical-connection","title":"Physical Connection","text":"Connect your Tasmota GPIO pins (3.3V TTL level) to a MAX3232 interface (cheap items on internet sales). Such interface changes TTL signals to proper RS232 levels. There are 4 wires on TTL side (Vcc, GND, Rx and Tx) and 3 wires on RS232 side (GND, Tx and Rx). A wire jumper between pins 7(RTS) and 8(CTS) may be needed in DSUB9 connector going to projector.
"},{"location":"Projector/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIO1 to
DLP Tx - GPIO3 to
DLP Rx
Replace GPIO1/GPIO3 with your scenario. Use command Weblog 3 to see extended logging of serial communication in Console.
"},{"location":"Projector/#projector-configuration","title":"Projector Configuration","text":"Check your projector settings concerning Serial port. It must match Tasmota settings eg. 9600 8N1. Some models have \"ID number\" feature to allow several projectors in one room. The control commands in Tasmota contain ID 0. Please switch off the \"ID\" control completely or set the ID to 0.
Since Acer H5360BD does not offer a simple RS2332 port setup is as follows:
"},{"location":"Python-HTTP-OTA-Server/","title":"Python HTTP OTA Server","text":""},{"location":"Python-HTTP-OTA-Server/#introduction","title":"Introduction","text":"Tasmota firmware can be upgraded using 'Firmware Upgrade' option on the main menu and selecting an OTA URL to fetch (and flash) a new firmware on the device.
To use this feature, firmware files need to be hosted on an HTTP web server (e.g., http://ota.tasmota.com/tasmota). Alternatively, users can to deploy a local HTTP server with Apache, Nginx, or other software solutions.
Python makes available the Flask (micro)framework that can be used at different levels of complexity due to its modular architecture. A simple HTTP server (hello-world) can be deployed with only six lines of Python code.
A Flask application to offer Tasmota firmware images for OTA upgrades is available as part of the available tools.
"},{"location":"Python-HTTP-OTA-Server/#requirements","title":"Requirements","text":""},{"location":"Python-HTTP-OTA-Server/#instructions","title":"Instructions","text":"Copy Tasmota firmware binary files in 'tools/fw' directory. A set of pre-built firmware binary files can be downloaded from the Tasmota repository.
Configure your Tasmota device with your firmware server URL:
Firmware Upgrade -> Upgrade by web server:\n http://<ip_address>:5000/tasmota.bin\n
or use the following command:
Backlog OTAURL http://<ip_address>:5000/tasmota.bin; Upgrade 1\n
"},{"location":"Python-HTTP-OTA-Server/#usage","title":"Usage","text":"To start Python HTTP server: python fw-server.py -d <net_iface> (default: eth0) or python fw-server.py -i <ip_address>
Example: python fw-server.py -d wlan0 or python fw-server.py -i 192.168.1.1
Note: On Windows it is advisable to use '-i' option because Windows uses UUID naming for network interfaces that are difficult to enter.
"},{"location":"Python-HTTP-OTA-Server/#linux-server","title":"Linux server:","text":"If your MQTT broker is hosted on a local server, you may want your firmware web server used for Tasmota OTA updates to reside on the same server. Follow these steps to create it as a service: - Copy the python script on the Linux server:
$ sudo su\n# mkdir /srv/tasmota/fw_server/fw\n# cd /srv/tasmota/fw_server\n# wget https://github.com/arendst/Tasmota/tree/development/tools/fw_server/fw-server.py\n
- Create a new file named tasmota.service in /etc/systemd/system/ and paste these lines (replace XYZ by your username): [Unit]\nDescription=Local OTA server for Tasmota\nRequires=network.target\nAfter=network.target multi-user.target\n\n[Service]\nUser=XYZ\nType=idle\nExecStart=/usr/bin/python /srv/tasmota/fw_server/fw-server.py -d wlan0\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n
- User rights: The files and directories have been created as root but this is not desirable. Invoke the following commands (replace the four instances of XYZ by your username): # chown -hR XYZ:XYZ /srv/tasmota\n# chown XYZ:XYZ /etc/systemd/system/tasmota.service\n
- Run the service: # systemctl daemon-reload\n# systemctl enable tasmota.service\n# systemctl start tasmota.service\n
If the server is rebooted, the service will automatically restart. - Check that the service is active and running:
# systemctl status tasmota.service\n
- Test the server: Copy new firmware files to the /srv/tasmota/fw_server/fw folder. Ensure that they have XYZ user rights in a similar fashion as shown above. You can use scp or a samba share. Copy the firmware files into the folder (firmware.bin in the example below). The service can be tested from any browser by issuing the address http://<ip_address>:5000/firmware.bin were <ip_address> is the address of the Linux server.
-
If the web server becomes unresponsive: After a power failure, your wlan0 IP may resolve to an invalid value like 169.254.5.153 because your LAN gateway was not ready when the web server restarted. If you notice that the OTA mechanism is broken, try to download the file from a browser. If you can't, then restart the service and check the status. Log in using a terminal session and enter:
$ sudo su\n# systemctl restart tasmota.service\n# systemctl status tasmota.service\n
If you recognize the IP address of your server on the last line of the status output, the web server should be OK. You can confirm that your OTA web server is restored by trying to download a file using your web browser. -
PlatformIO: If you want PlatformIO to be able to upload your compiled binaries to the local server, you'll still have to setup ssh with ssh-keygen in order to use the Tasmota script pio/sftp-uploader.py without a password.
"},{"location":"RCWL-0516/","title":"RCWL-0516 microwave radar motion sensor","text":"module uses a \u201cmicrowave Doppler radar\u201d technique to detect moving objects. Its advantage over traditional PIRs is that it can detect presence through obstacles with a sensing distance of 3m average in real life conditions.
"},{"location":"RCWL-0516/#configuration","title":"Configuration","text":""},{"location":"RCWL-0516/#wiring","title":"Wiring","text":"RCWL-0516 ESP GND GND VIN 5V OUT GPIOx"},{"location":"RCWL-0516/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
A configured RCWL-0516 will not appear in the web UI, only the console displays the status of Switch1 as POWER.
Continue to use RCWL-0516 just as any other PIR in Tasmota.
Buy from AliExpress Features of RCWL-0516 RCWL-0516 Datasheet RCWL-0516 GitHub
"},{"location":"RDM6300/","title":"RDM6300 RFID reader","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_RDM6300 \n#define USE_RDM6300 // Add support for RDM6300 125kHz RFID Reader (+0k8)\n#endif\n
RDM6300 125KHz cardreader mini-module is designed for reading code from 125KHz card compatible read-only tags and read/write card.
"},{"location":"RDM6300/#warning","title":"Warning","text":"There seems to be an issue with some card readers!(the cheap ones?) These output some fake/ghost readings that look like valid card numbers and validate thru the XOR method but are not real. This is confirmed by multiple users. Please see details in issue #9952. There seem to not be issues yet with SeeedStudio Grove 125Khz Reader or RDM630
"},{"location":"RDM6300/#configuration","title":"Configuration","text":"Sensor uses serial interface for communication.
"},{"location":"RDM6300/#wiring","title":"Wiring","text":"RDM6300 ESP TX GPIOx RX GPIOy Pin3 unused GND GND VCC 5V"},{"location":"RDM6300/#tasmota-settings","title":"Tasmota Settings","text":"Update 12.10.2020: Seems there is a new driver and you can use RDM6300 RX instead of the SerBr Tx and SerBr Rx. This also seems to show the last card read in the management interface. As a note, the card number that comes from the SerBr was 12 chars and the RDM6300 one has only 8, being stripped by the first 2 and last 2 chars.
In the Configuration -> Configure Module page assign:
- GPIOx to
SerBr Tx (71) - GPIOy to
SerBr Rx (72)
If the RFID Tag is held in front of the Antenna the reader starts sending the Tag ID. The Tag Id is prefaced with a 0x02 and the end is delimited with a 0x03. If the reader reads the tag multiple times you would get one line with multiple times the Tag ID. For this to separate you can add a SerialDelimiter of 0x03. This will split the result from the serial into several single mqtt messages. But (probably) all the messages wil be prepended with a binary 0x02.
Set SerialDelimiter to 3
SerialDelimiter 3\n
"},{"location":"RDM6300/#openhab","title":"OpenHab","text":"sonoff-rfid.items:
// tele/sonoff-rfid-1/RESULT {\"SSerialReceived\":\"01020304FAFA\"}\nString RFID_1 \"RFID [%s]\"\n {mqtt=\"<[broker:tele/sonoff-rfid-1/RESULT:state:JSONPATH($.SSerialReceived)]\"}\n
"},{"location":"RDM6300/#breakout-boards","title":"Breakout Boards","text":""},{"location":"RF-Protocol/","title":"RF Communication","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_RC_SWITCH\n#define USE_RC_SWITCH // Add support for RF transceiver using library RcSwitch (+2k7 code, 460 iram)\n#endif\n
This guide does not apply to Sonoff RF Bridge specific commands
Tasmota uses the rc-switch library to decode RF codes. Supported hardware depends on rc-switch library support only.
"},{"location":"RF-Protocol/#sending-rf-codes","title":"Sending RF Codes","text":"Send an RF control code as a decimal or hexadecimal string in a JSON payload. An inexpensive RF receiver such as a STX882 can be connected to a device running Tasmota. In order to send RF data you need to configure the connected GPIO as RFSend (105)
Command Parameters RfSend <value> = code decimal or JSON. Data value is required and can be decimal or hexadecimal (using the 0x prefix), other values are optional.JSON{\"Data\":\"<value>\",\"Bits\":<value>,\"Protocol\":<value>,\"Pulse\":<value>}\"Data\":\"<value>\" = hexadecimal code\"Bits\":<value> = required number of data bits (default = 24)\"Protocol\":<value> = protocol number (default = 1)\"Repeat\":<value> = repeat value (default = 10)\"Pulse\":<value> = pulse value (350 = default for protocol 1)\u2003e.g., RfSend {\"Data\":\"0x7028DC\",\"Bits\":24,\"Protocol\":1,\"Pulse\":238}Decimaldata, bits, protocol, repeat, pulse \u2003e.g., RfSend 7350492, 24, 1, 10, 238 or RfSend 0x7028DC, 24, 1, 10, 238 If you send only the \"Data\" value in decimal or hexadecimal other values will be sent as default.
Example
RfSend 123456
will be sent as {\"Data\":\"0x1E240\",\"Bits\":24,\"Protocol\":1,\"Pulse\":351}
When sending decimal formatted command you need to follow the pattern otherwise a part of the command will be ignored.
Example
RfSend 123456, 24, 1, 238 is missing the repeat value so the last number intended as pulse value won't be sent
"},{"location":"RF-Protocol/#receiving-rf-codes","title":"Receiving RF Codes","text":"An inexpensive RF receiver such as a SRX882 can be connected to a device running Tasmota. Configure the GPIO connected to Data pin on the RF receiver as 'RFrecv (106)'. Once you have identified the protocols that you want to receive data on , you can enable only those protocols . The RfProtocol command will only work if you have set a pin function to rfrecv
Command Parameters RfProtocol <value> <value> 0 .. 0x7FFFFFFFF or 'A' for All :: This Sets the Enabled Protocol Mask Value RfProtocol<idx> <value> <idx> 1 .. 35 <value> 0 or 1 :: This Disables or Enables a Specific Protocol Example
RfProtocol 5 \u00a0 \u00a0 \u00a0 will enable only protocols 1 & 3 \u00a0 \u00a0 \u00a0 stat/tasmota_D728A8/RESULT {\"RfProtocol\":\"1,3\"} RfProtocol27 1 \u00a0 \u00a0 \u00a0 will enable protocol 27 \u00a0 \u00a0 \u00a0 stat/tasmota_D728A8/RESULT {\"RfProtocol\":\"1,3,27\"} RfProtocol 0 stat/tasmota_D728A8/RESULT {\"RfProtocol\":\"None Enabled\"} RfProtocol a stat/tasmota_D728A8/RESULT {\"RfProtocol\":\"1,2,3,4,5,6,7,8,9,10,11,12, 13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35\"}
If you have an RF receiver configured, a message will be logged each time an RF code is seen. RF driver will try to decode it against all protocols supported by rc-switch library.
When Tasmota receives an RF message, the data portion of the payload has the same format as the RfSend JSON parameters.
\"RfReceived\":{\"Data\":\"<hex-value>\",\"Bits\":<value>,\"Protocol\":<value>,\"Pulse\":<value>}\n
This JSON payload data can be used in a rule such as:
ON RfReceived#Data=<hex-value> DO <command> ENDON\n
Examples: Sonoff RM433 Remote MQT: tele/tasmota/RESULT = {\"Time\":\"2020-05-27T18:59:06\",\"RfReceived\":{\"Data\":\"0x7028D2\",\"Bits\":24,\"Protocol\":1,\"Pulse\":238}}
"},{"location":"RF-Transceiver/","title":"RF Transceiver","text":"RC Switch driver enables sending RF codes through an RF transmitter and receiving them through an RF receiver via rc-switch library.
"},{"location":"RF-Transceiver/#rf-transmitter","title":"RF Transmitter","text":"Not all transmitter modules will work with the rc-switch library. Some of officially supported modules by rc-switch are:
- SC5262 / SC5272
- HX2262 / HX2272
- PT2262 / PT2272
- EV1527 / RT1527 / FP1527 / HS1527
- Intertechno outlets
- HT6P20X
This guide was created using STX882 RF transmitter which also works without issues.
"},{"location":"RF-Transceiver/#wiring","title":"Wiring","text":"RF ESP data GPIOx + 3.3v/5v - GND"},{"location":"RF-Transceiver/#tasmota","title":"Tasmota","text":"In the Configuration -> Configure Module page assign:
See RF commands for use.
"},{"location":"RF-Transceiver/#rf-receiver","title":"RF Receiver","text":"RF receiver is used to capture RF codes. Those codes can be sent using RFSend or used as a rule trigger.
Not all transmitter modules will have sufficient power or range for normal use
This guide is using SRX882 RF receiver module with a helical antenna.
"},{"location":"RF-Transceiver/#wiring_1","title":"Wiring","text":"SRX882 ESP Data GPIOx VCC 5v GND GND CS 3v3 or 5v CS pin needs to be pulled high to put the module in active mode
"},{"location":"RF-Transceiver/#tasmota_1","title":"Tasmota","text":"In the Configuration -> Configure Module page assign:
On a captured code RF receiver sends a tele/%topic%/RESULT JSON response visible in console:
{\n\"Time\": \"2019-01-01T00:00:00\",\n\"RfReceived\": {\n\"Data\": \"0x7028D5\",\n\"Bits\": 24,\n\"Protocol\": 1,\n\"Pulse\": 238\n}\n}\n
"},{"location":"Range-Extender/","title":"Range Extender","text":"This feature allows Tasmota to publish an AP with a dedicated SSID that is then routed to the core WiFi network.
This feature is not included in precompiled binaries To use it you must compile your build
Copy platformio_tasmota_cenv_sample.ini to platformio_tasmota_cenv.ini which already contains the following sections for ESP8266 and ESP32. Or create a section in your platformio_tasmota_cenv.ini such as the following for an ESP8266:
[env:tasmota-rangeextender]\nmonitor_port = /dev/cu.SLAB*\nupload_port = /dev/cu.SLAB*\nupload_speed = 921600\nbuild_unflags = ${esp_defaults.build_unflags}\nbuild_flags = ${esp82xx_defaults.build_flags}\n-D FIRMWARE_RANGE_EXTENDER\n-D USE_WIFI_RANGE_EXTENDER ; adds about 11k to flash size\n-D USE_WIFI_RANGE_EXTENDER_NAPT ; Optional, adds about 1k to flash size\n-D PIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH ; required option to use this feature\n
For ESP32 (note this extends the tasmota32idf4 section included in the platformio_tasmota_cenv_sample.ini):
[env:tasmota32-rangeextender]\nextends = env:tasmota32idf4\nbuild_flags = ${env:tasmota32idf4.build_flags}\n-D FIRMWARE_TASMOTA32\n-D USE_WIFI_RANGE_EXTENDER\n-D USE_WIFI_RANGE_EXTENDER_NAPT\n
Alternatively, add the following to user_config_override.h (however the PIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH or tasmota32idf4 must still be set as per above):
#ifndef USE_WIFI_RANGE_EXTENDER\n#define USE_WIFI_RANGE_EXTENDER\n#endif\n// Optionally, to enable NAT/NAPT\n#ifndef USE_WIFI_RANGE_EXTENDER_NAPT\n#undef USE_WIFI_RANGE_EXTENDER_NAPT\n#endif\n
"},{"location":"Range-Extender/#overview","title":"Overview","text":"If you have a Tasmota device at the edge of your WiFi coverage and require a bit more distance, this feature allows you to turn it into a routing WiFi node.
Note that this should be considered low bandwidth as the ESP has to process every packet.
Additionally, if desired, it can also NAT/NAPT traffic, removing the need for a route on your core router. See below for the pros and cons of each option.
"},{"location":"Range-Extender/#routing-not-napt","title":"Routing (not NAPT)","text":"If using routing, you must setup a return route on your \"core\" router for each extender node. Each extender must also have a unique client side IP address range, and a static core side IP address so the core router knows where to send routes.
Pros
- Can access web interface remote devices
- Lower overhead on the extender device
- Slightly smaller flash foot print if you choose to disable NAPT
Cons
- More complex to setup, requiring return routes and static IP addressing
An example setup using commands to match the above image to route traffic, with an AP name rangeextender and password securepassword would be:
RgxSSId rangeextender\nRgxPassword securepassword\nRgxAddress 10.99.1.1\nRgxSubnet 255.255.255.0\nRgxState ON\n
Alternatively, it could also be set in your user_config_override.h with:
#define WIFI_RGX_SSID \"rangeextender\"\n#define WIFI_RGX_PASSWORD \"securepassword\"\n#define WIFI_RGX_IP_ADDRESS \"10.99.1.1\"\n#define WIFI_RGX_SUBNETMASK \"255.255.255.0\"\n#define WIFI_RGX_STATE 1\n
NAPT defaults to off - however if you needed to disable it, run RgxNAPT OFF.
"},{"location":"Range-Extender/#with-napt","title":"With NAPT","text":"If using NAPT, deployment is a lot easier as there is no need for a static IP address, or adding routes to your core router. Also, all extender nodes could have the same \"remote\" IP address range as these addresses never enter into the \"core\" network.
Pros
Cons
- More overhead on the extender device
- Access to the web interface of the remote devices needs port forwarding -> see RgxPort command
An example setup using commands to match the above image with NAPT, with an AP name rangeextender and password securepassword would be:
RgxSSId rangeextender\nRgxPassword securepassword\nRgxAddress 10.99.1.1\nRgxSubnet 255.255.255.0\nRgxState ON\nRgxNAPT ON\n
Alternatively, it could also be set in your user_config_override.h with:
#define WIFI_RGX_SSID \"rangeextender\"\n#define WIFI_RGX_PASSWORD \"securepassword\"\n#define WIFI_RGX_IP_ADDRESS \"10.99.1.1\"\n#define WIFI_RGX_SUBNETMASK \"255.255.255.0\"\n#define WIFI_RGX_STATE 1\n#define WIFI_RGX_NAPT 1\n
To access the web page (which uses tcp port 80) of a client with mac 11:22:33:44:55:66 you execute the following command after the client is connected:
RgxPort tcp,8080,112233445566,80\n
If the result is OK the range extender port 8080 is forwarded to port 80 of the client and the web page can be accessed with URL http://range-extender-name:8080 The setting is not permanent and needs to be repeated each time the client (re)connects since its IP could have changed.
So, if access to a device behind the NAT is required it is easiest to configure this device with a static IP in the range extender subnet. Then the RgxPort command can be used with that IP instead of the MAC. Since the IP is known, it is not required that the IP is already active at the time of the port forward. That way the RgxPort command could be used in a simple startup rule. Given the range extender subnet is the default 192.168.4.0/24, and the device has a static IP of 192.168.4.44 then this command would work:
RgxPort tcp,8084,192.168.4.44,80\n
If the result is OK the range extender port 8084 is forwarded to port 80 of the client and the web page can be accessed with URL http://range-extender-name:8084 while the client is active."},{"location":"Range-Extender/#commands","title":"Commands","text":"Command Parameters RgxSSId The SSID of the AP that Tasmota will present for devices to connect to RgxPassword The password for the above SSID RgxAddress The IP address on the AP side, the connection to the \"core\" network IP addressing remains the same (eg: DHCP) RgxSubnet The subnet mask for the AP side, it's recommended to use 255.255.255.0. The AP will automatically use addresses from this subnet to serve via DHCP to connecting devices RgxState Enable or disable the AP. Note that turning the AP off will cause a reboot RgxNAPT Only available if USE_WIFI_RANGE_EXTENDER_NAPT is enabled. Enable or disable NAPT. Note that turning off NAPT will cause the device to reboot RgxClients Show JSON list of currently connected clients with their MAC and IP. On ESP32 last RSSI is also shown RgxPort protocol,range_extender_port,[client_mac|client_ip],client_port: Forward a tcp or udp STA port to a port of an AP client"},{"location":"Rules/","title":"Rules","text":"Rules expand the functionality of Tasmota with user configurable flexible logic
Tasmota provides a Rule feature heavily inspired by the ESPEasy implementation while maintaining a small memory footprint. Automation solutions can be implemented without having to add dedicated code or use external solutions.
Rules perform actions based on triggers (e.g., switch state change, temperature threshold, events like system boot, a defined timer elapsing, custom defined events, etc.) They are stored in flash and therefore will survive a reboot.
Note
Most pre-compiled builds have the Rules feature enabled. If you are >compiling your own firmware, in order to use rules, include #define USE_RULES in user_config_override.h.
List of Rules Commands
"},{"location":"Rules/#rule-syntax","title":"Rule Syntax","text":"Rule definition syntax
ON <trigger> DO <command> [ENDON | BREAK]\n
ON - marks the beginning of a rule <trigger> - what condition needs to occur for the rule to trigger DO - statement marking end of trigger and beginning of command part<command> - command that is executed if the <trigger> condition is met ENDON - marks the end of a rule. It can be followed by another rule.BREAK - marks the end of a rule. BREAK will stop the execution of the remaining rules that follow this rule within the rule set. If a rule that ends with BREAK is triggered, the following rules in that rule set will not be executed. This allows the rules to somewhat simulate an \"IF/ELSE\" statement.
Rule sets are defined by using the Rule<x> command. After defining a rule set, you have to enable it (turn it on) using Rule<x> 1. Similarly you can disable the rule set using Rule<x> 0.
Note
If bootloops are detected all rules will be disabled as a precaution. See SetOption36.
There are three separate rule sets called Rule1, Rule2 and Rule3. Each rule set can contain many rules. The number of rules that can fit in a rule set varies, but expect at least 1000 characters available per set. Additionally, rules are dynamically compressed, meaning they will be compressed automatically when doing so is required, but left uncompressed until that point.
Whenever a rule set is enabled all the rules in it will be active. If the character count of the rules in one set actually exceeds the limit, start using the next rule set. If you have a long list of rules, verify the rules have all fit by inspecting the resulting log.
Rules inside a rule set Rule<x> are concatenated and entered as a single statement.
Rule<x> ON <trigger1> DO <command> ENDON ON <trigger2> DO <command> ENDON ...\n
Spaces after ON, around DO, and before ENDON or BREAK are mandatory. A rule is not case sensitive.
"},{"location":"Rules/#rule-trigger","title":"Rule Trigger","text":"Rule trigger names are derived from the JSON message displayed in the console. Each JSON level (all values enclosed in {...}) is separated in the trigger with a #. Top level JSON fields are referenced without any #, except when the JSON has only one field, where you need #Data.
A rule trigger can consist of:
[TriggerName]#[ValueName][TriggerName]#[ValueName][comparison][value][SensorName]#[ValueName][SensorName]#[ValueName][comparison][value]Tele-[SensorName]#[ValueName][TriggerName1]#[TriggerName2]#[ValueName][TriggerName1]#?#[ValueName][ValueName][ValueName#Data]
Use ? as a wildcard for a single trigger level. Rule will trigger on [TriggerName]#?#[Value] where ? is any value.
Example
Rule with a trigger of ZBReceived#?#Power=0 will trigger on {\"ZBReceived\":{\"0x4773\":{\"Power\":0}}} and on {\"ZBReceived\":{\"aqara_switch\":{\"Power\":0}}} both.
Note
Same trigger may be used in more than one rule. This may be required for some cases of using IF/ELSE since an IF statement cannot be used within a Backlog.
"},{"location":"Rules/#rule-trigger-comparison-operators","title":"Rule Trigger Comparison Operators","text":"Operator Function = equal to (used for string comparison) == equal to (used for numerical comparison) > greater than < lesser than != number not equal to (for string see below) >= greater than or equal to <= lesser than or equal to $< string starts with $> string ends with $| string contains $! string is not equal to $^ string do not contains | used for modulo operation with remainder = 0 (exact division)"},{"location":"Rules/#examples-of-available-triggers","title":"Examples of Available Triggers","text":"This is just a sampling of available triggers to showcase what is possible and not a definitive list
Trigger When it occurs Analog#A0div10 when the A0 input changes by more than 1% it provides a value between 0 and 100 Button2#State when a button changes state:0 = OFF1 = ON2 = TOGGLE3 = HOLD Clock#Timer=3 when global Timer3 is activated Dimmer#Boot occurs after Tasmota starts Dimmer#State when the value for Dimmer is changed Eth#Connected when Ethernet is connected (ESP32 only) Eth#Disconnected when Ethernet is disconnected (ESP32 only) Event#eventName when command Event eventName is executed. You can define your own event values and trigger them with the Event command. An event with a = will provide a %value% to use in the execution part of the rule. Example: Command Event speed=2 in rule trigger on event#speed will have the %value% of 2. FanSpeed#Data=3 when the fan speed is set to 3 Mem<x>#State when the value for Mem<x> is changed Http#Initialized Mqtt#Connected when MQTT is connected Mqtt#Disconnected when MQTT is disconnected Power1#Boot Relay1 state before Wi-Fi and MQTT are connected and before Time sync but after PowerOnState is executed. Power#Boot triggers before System#Boot.This trigger's value will be the last state of Relay1 if PowerOnState is set to its default value (3). Power1#State when a power output is changeduse Power1#state=0 and Power1#state=1 for comparison, not =off or =onPower2 for Relay2, etc. Rotary1#Pos1 when rotary encoder change. See Use a rotary encoder. Rules#Timer=<x> when countdown RuleTimer<x> expires (x = 1..8). Switch1#Boot occurs after Tasmota starts before it is initializated. Switch1#State when a switch changes to state. Will not trigger if SwitchTopic is set.use Switch1#state=0 and Switch1#state=1 for comparison, not =off or =on0 = OFF1 = ON2 = TOGGLE3 = HOLD (SwitchTopic 0 must be set for this to trigger)4 = INC_DEC (increment or decrement dimmer)5 = INV (change from increment to decrement dimmer and vice versa)6 = CLEAR (button released for the time set with SetOption32) System#Boot occurs once after Tasmota is fully initialized (after the INFO1, INFO2 and INFO3 console messages). System#Boot triggers after Wi-Fi and MQTT (if enabled) are connected. If you need a trigger prior to every service being initialized, use Power1#Boot System#Init occurs once after restart before Wi-Fi and MQTT are initialized System#Save executed just before a planned restart Time#Initialized once when NTP is initialized and time is in sync Time#Minute every minute Time#Minute|5 every five minutes Time#Minute=241 every day once at 04:01 (241 minutes after midnight) Time#Set every hour when NTP makes time in sync Var<x>#State when the value for Var<x> is changed (triggers whenever a value is written to Var<x> even if it's the same value) Wifi#Connected when Wi-Fi is connected Wifi#Disconnected when Wi-Fi is disconnected Tele-Heap when a teleperiod message is sent with available heap memory (example of top-level JSON) Tele-Wifi#AP when a teleperiod message is sent with the number of the used AP Tele-Wifi#Ssid when a teleperiod message is sent with the name of the used AP Tele-Wifi#Bssid when a teleperiod message is sent with the name of the bSSID Tele-Wifi#Channel when a teleperiod message is sent with the number of the wifi channel used Tele-Wifi#RSSI when a teleperiod message is sent with the RSSI LEVEL Tele-Wifi#LinkCount when a teleperiod message is sent with the number of wifi disconnections Tele-Wifi#Downtime when a teleperiod message is sent with the total seconds of wifi disconnections Every command with a JSON payload response has an associated rule trigger.
Trigger When it occurs <command>#Data A one level JSON payload such as {\"Command\":\"value\"}. For example, for {\"Fanspeed\":3}, the trigger isFanspeed#Data. <command>#level1#level2#levelN A multi-level JSON payload such as {\"TriggerLevel1\":{\"TriggerLevel2\":{\"ValueName\":\"value\"}}} does NOT have the #Data trigger. Instead, the trigger for these responses is TriggerLevel1#TriggerLevel2#ValueName. When the JSON payload response is produced by a command executed by a rule i.e. on time=120 do status 8 endon, the StatusSNS#Data trigger will not fire unless the command is wrapped in backlog i.e. on time=120 do backlog status 8 endon
Example
For {\"PulseTime2\":{\"Set\":0,\"Remaining\":0}}, the triggers are PulseTime2#Set and PulseTime2#Remaining.|
For a 3 level JSON message such as {\"ZbReceived\":{\"test_switch\":{\"Device\":\"0x0C94\",\"Power\":1,\"Endpoint\":8,\"LinkQuality\":70}}} one possible trigger is ZbReceived#test_switch#Power or another ZbReceived#test_switch#LinkQuality
Connected sensors can be a trigger in the form as they are represented in the TelePeriod and Status 8 JSON payloads.
Trigger When it occurs DS18B20#Temperature whenever the temperature of sensor DS18B20 updates (also unchanged) DS18B20#Temperature<20 whenever the temperature of sensor DS18B20 is below 20 degrees BME280#Humidity==55.5 whenever the humidity of sensor BEM280 equals 55.5% INA219#Current>0.100 whenever the current drawn is more than 0.1A Energy#Power>100 whenever the power used is more than 100W When the payload consists of an array of data eg: ENERGY\":{Current\":[1.320,2.100]}
Trigger When it occurs Energy#Current[N] N = Number of the field. 1 for the first 1.320, 2 for the second 2.100 etc. Energy#Current[1]>1.000 whenever the first value of Energy#Current is higher than 1.000. To trigger only at TelePeriod time, prefix the sensor with the word Tele-.
Trigger When it occurs Tele-AM2301#Temperature sensor AM2301 Temperature value when the TelePeriod JSON payload is output Hardware and software serial interface, RF, IR and TuyaMCU are also supported based on their JSON status message:
Trigger When it occurs TuyaReceived#Data=<hex_string> whenever <hex_string> is received with TuyaMCU component SerialReceived#Data=<string> whenever <string> is received via hardware serial SSerialReceived#Data=<string> whenever <string> is received via software serial IrReceived#Data=801 whenever an IR signal for a RC5 remote control button 1 is received IrReceived#Data=0x00FF9867 whenever an IR signal with hex code 0x00FF9867 is received RfReceived#RfKey=4 whenever the RF Bridge receives a recognized RfKey 4 signal RfReceived#Data=0xE8329E whenever an RF signal with hex code 0xE8329E is received"},{"location":"Rules/#rule-command","title":"Rule Command","text":"A rule command can be any command listed in the Commands list. The command's <parameter> can be replaced with %value% which will use the value of the trigger.
ON Switch1#State DO Power %value% ENDON
To accomplish a rule with one trigger but several commands, you need to use Backlog:
ON <trigger> DO Backlog <command1>; <command2>; <command3> ENDON
Appending new rule onto an existing rule set Use the + character to append a new rule to the rule set. For example:
\u00a0\u00a0\u00a0\u00a0Existing Rule1: ON Rules#Timer=1 DO Mem2 %time% ENDON
\u00a0\u00a0\u00a0\u00a0Rule to append: ON Button1#state DO POWER TOGGLE ENDON
\u00a0\u00a0\u00a0\u00a0Command: Rule1 + ON button1#state DO POWER TOGGLE ENDON
\u00a0\u00a0\u00a0\u00a0Resulting in
Rule1 ON Rules#Timer=1 DO Mem2 %time% ENDON ON Button1#state DO POWER TOGGLE ENDON\n
You can repeate the same trigger in rules.
Rule\nON Power2#state=1 DO Power1 1 ENDON\nON Power2#state=1 DO RuleTimer1 100 ENDON\n
"},{"location":"Rules/#rule-variables","title":"Rule Variables","text":"There are thirty-two (32) available variables (single precision reals) in Tasmota: Var1..Var16 and Mem1..Mem16. They provide a means to store the trigger %value% to be used in any rule. All Var will be empty strings when the program starts. The value of all Mem persists after a reboot.
The value of a Var<x> and Mem<x> can be:
- any number
- any text
- %var1% to %var16%
- %mem1% to %mem16%
- %color%
- %deviceid%
- %macaddr%
- %sunrise%
- %sunset%
- %time%
- %timer1% to %timer16%
- %timestamp%
- %topic%
- %uptime%
- %utctime%
- %zbdevice%
- %zbgroup%
- %zbcluster%
- %zbendpoint%
To set the value for Var<x> and Mem<x> use the command
Var<x> <value>Mem<x> <value>
The <value> can also be the value of the trigger of the rule.
- Set Var2 to the temperature of the AM2301 sensor -
ON AM2301#Temperature DO Var2 %value% ENDON - Set Var4 to Var2's value -
ON Event#temp DO Var4 %Var2% ENDON - Set Mem2 to the current time (minutes elapsed since midnight) -
ON Rules#Timer=1 DO Mem2 %time% ENDON - After a Wi-Fi reconnect event, publish a payload containing timestamps of when Wi-Fi was disconnected in From: and when Wi-Fi re-connected in To: to
stat/topic/BLACKOUT.
Rule1\nON wifi#disconnected DO Var1 %timestamp% ENDON\nON wifi#connected DO Var2 %timestamp% ENDON\nON mqtt#connected DO Publish stat/topic/BLACKOUT {\"From\":\"%Var1%\",\"To\":\"%Var2%\"} ENDON\n
"},{"location":"Rules/#delete-rule","title":"Delete rule","text":"To clear / delete use double quote(s):
Rule1 \"\n
"},{"location":"Rules/#conditional-rules","title":"Conditional Rules","text":"This feature is not included in precompiled binaries.
To use it you must compile your build. Add the following to user_config_override.h:
#define USE_EXPRESSION // Add support for expression evaluation in rules (+3k2 code, +64 bytes mem) \n#define SUPPORT_IF_STATEMENT // Add support for IF statement in rules (+4k2 code, -332 bytes mem) \n
"},{"location":"Rules/#major-features","title":"Major features","text":" - Support IF, ELSEIF, ELSE
- Support for
<comparison> and <logical expression> as condition - Support for executing multiple commands
- Available free RAM is the only limit for logical operators and parenthesis.
"},{"location":"Rules/#grammar","title":"Grammar","text":"<if-statement>
IF (<logical-expression>) <statement-list> {ELSEIF (<logical-expression>) <statement-list>} [ELSE <statement-list>] ENDIF
(<logical-expression>) Parentheses must enclose the expression. They can also be used to explicitly control the order of evaluation.
<comparison-expression> ( <comparison-expression> | <logical-expression> ) {{AND | OR} <logical-expression>} ( <logical-expression> ) {AND | OR} <logical expression>}
<comparison-expression>
<expression> {= | < | > | | | == | <= | >= | !=} <expression>
<statement-list>
<statement> {; <statement>}
<statement>
- {
<Tasmota-command> | <if-statement>}
"},{"location":"Rules/#syntax","title":"Syntax","text":"IF statement supports 3 formats:
IF (<logical-expression>) <statement-list> ENDIF IF (<logical-expression>) <statement-list> ELSE <statement-list> ENDIF IF (<logical-expression>) <statement-list> [ELSEIF (<logical-expression>) <statement-list> ] ELSE <statement-list> ENDIF
When the <if-statement> directly follows the trigger the standard 'Do' syntax applies, however, it is not necessary to use 'Backlog' within the chain Rule1 ON Power1#State DO IF (%value%==1) Backlog Power2 1;Power3 1 ENDIF ENDON is permitted Rule1 ON Power1#State DO IF (%value%==1) Power2 1;Power3 1 ENDIF ENDON is also permitted
When the <if-statement> is preceded by other Tasmota commands you should use Backlog along with Do , e.g. Rule1 ON ENERGY#Current>10 DO Backlog Power1 0; IF (%var1%==1) Power1 1 ENDIF;Power 2 0;Power3 1 ENDON and not Rule1 ON ENERGY#Current>10 DO Power1 0; IF (%var1%==1) Power1 1 ENDIF ENDON or Rule1 ON ENERGY#Current>10 Backlog Power1 0; IF (%var1%==1) Power1 1 ENDIF ENDON
(<logical-expression>) example: (VAR1>=10) - Multiple comparison expressions with logical operator AND or OR between them. AND has higher priority than OR. For example: ((UPTIME>100) AND (MEM1==1) OR (MEM2==1)) - Parenthesis can be used to change the priority of the logical expression evaluation. For example: ((UPTIME>100) AND ((MEM1==1) OR (MEM2==1)))
- Following variables can be used in
<condition>:
Symbol Description VAR<x> variable (<x> = 1..MAX_RULE_VARS, e.g., VAR2) MEM<x> persistent variable (<x> = 1..MAX_RULE_MEMS, e.g., MEM3) TIME minutes past midnight UPTIME uptime minutes UTCTIME UTC time, UNIX timestamp, seconds since 01/01/1970 LOCALTIME local time, UNIX timestamp SUNRISE current sunrise time (minutes past midnight) SUNSET current sunset time (minutes past midnight) COLOR current color <statement-list> - A Tasmota command (e.g.,LedPower on) - Another IF statement (IF ... ENDIF) - Multiple Tasmota commands or IF statements separated by ;. For example: Power1 off; LedPower on; IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on Backlog is implied and is not required (saves rule set buffer space).
But not like this: Power1 off; LedPower on; IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on
You should split it in two lines like: ON Power2#state=1 DO Power1 off; LedPower on; ENDON ON Power2#state=1 DO IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on ENDON
Example
Rule used to control pressure cooker with a Sonoff S31. Once it is finished cooking, shut off the power immediately.
Rule1\nON system#boot DO var1 0 ENDON\nON energy#power>100 DO if (var1!=1) ruletimer1 0;var1 1 endif ENDON\nON tele-energy#power<50 DO if (var1==1) var1 2;ruletimer1 600 endif ENDON\nON rules#timer=1 DO Backlog var1 0;power off ENDON
"},{"location":"Rules/#expressions-in-rules","title":"Expressions in Rules","text":"This feature is not included in precompiled binaries.
To use it you must compile your build. Add the following to user_config_override.h:
#define USE_EXPRESSION // Add support for expression evaluation in rules (+3k2 code, +64 bytes mem) \n#define SUPPORT_IF_STATEMENT // Add support for IF statement in rules (+4k2 code, -332 bytes mem) \n
Beginning with Tasmota version 6.4.1.14, an optional feature for using mathematical expressions in rules was introduced.
"},{"location":"Rules/#supported-commands","title":"Supported Commands","text":"Once the feature is enabled, the use of expressions is supported in the following commands:
- Var
- Mem
- RuleTimer
- If conditional statement (requires
#define SUPPORT_IF_STATEMENT)
"},{"location":"Rules/#syntax_1","title":"Syntax","text":"Expressions can use of the following operators. They are listed by the order of operations priority, from higher to lower.
( ) (parentheses can be used to explicitly control the order of operations)^ (power)% (modulo, division by zero returns modulo \"0\")* and / (multiplication and division; division by zero returns \"0\")+ and - (addition and subtraction)
Example
1+2*2 results in 5.0 as the multiplication is done first due to its higher priority
In addition to numeric constants, the following symbolic values can be used:
Symbol Description VAR<x> variable (<x> = 1..MAX_RULE_VARS, e.g., VAR2) MEM<x> persistent variable (<x> = 1..MAX_RULE_MEMS, e.g., MEM3) TIME minutes past midnight UPTIME uptime minutes UTCTIME UTC time, UNIX timestamp, seconds since 01/01/1970 LOCALTIME local time, UNIX timestamp SUNRISE current sunrise time (minutes past midnight) SUNSET current sunset time (minutes past midnight) COLOR current color Example
Mem1=((0.5*Var1)+10)*0.7
To use expressions in the Var, Mem and RuleTimer commands, an equal sign (=) character has to be used after the command. If not, the traditional syntax interpretation is used.
Statement Var1 Result Var1=42 42 Var1 1+1 \"1+1\" (the literal string) Var1=1+1 2 Var1=sunset-sunrise duration of daylight in minutes"},{"location":"Rules/#rule-cookbook","title":"Rule Cookbook","text":""},{"location":"Rules/#long-press-on-a-switch","title":"Long press on a switch","text":"This example is for GPIOs defined as switches not buttons
Activate long press action with Switchmode 5 and shorten long press time to 2 seconds (Setoption32 20).
Backlog SwitchMode 5; SetOption32 20\nRule ON switch1#state=3 DO publish cmnd/tasmota02/POWER 2 ENDON\n
Long pressing on switch1 sends POWER 2 (toggle action) command to the tasmota02 device
Notice we use Rule which edits Rule1 rule set. They can be used interchangeably. If your rule does not trigger there could some constraints, in this case if SwitchTopic has a value it will override rules for switches and will need to be disabled: SwitchTopic 0.
"},{"location":"Rules/#send-mqtt-message-on-button-press","title":"Send MQTT message on button press","text":"When a button is pressed the user has the possibility to send a MQTT message based on FullTopic and ButtonTopic. This MQTT message is going to be received by the MQTT broker and if there is any other device(s) subscribed to that Topic, it will receive also that message. So this approach can be used for sending messages/commands to MQTT Broker to Home Automation System, and/or sending messages/commands to MQTT Broker to other device(s).
A problem with this solution is that on a Sonoff 4CH all four buttons will be sending the same MQTT topic using only a different Power index number like cmnd/ButtonTopic/Power3 toggle.
By using a rule a single button can send any MQTT message allowing for more flexibility.
Disable ButtonTopic as it overrides rules for buttons: ButtonTopic 0
"},{"location":"Rules/#rule","title":"Rule","text":"Rule1\nON button1#state DO publish cmnd/ring2/power %value% ENDON\nON button2#state DO publish cmnd/strip1/power %value% ENDON\n
You will need to enable this rule if it's the first time you've used rule with Rule1 1
"},{"location":"Rules/#result","title":"Result","text":"When Button1 is pressed the rule kicks in and sends a MQTT message substituting variable %value% with the button state, f.e cmnd/ring2/Power 2. When Button2 is pressed an MQTT message cmnd/strip1/Power 2 will be sent.
"},{"location":"Rules/#usage-of-one-shot-once","title":"Usage of one-shot (once)","text":"The rule command once option provides the possibility to trigger only once ON a slow change while the change is still within the bounds of the test.
Rule\nON ENERGY#Current>0.100 DO publish tool/tablesaw/power 1 ENDON\nON ENERGY#Current<0.100 DO publish tool/tablesaw/power 0 ENDON\n
This creates a rule to publish MQTT commands whenever a Sonoff POW has current passing through it. Used as is, it will publish MQTT commands repeatedly, over and over, while current is >0.100 ... but, executing another command:
Rule 5
Now the MQTT message will be sent once, and only once, while the condition is met. This is perfect for thermostat on/off depending on temperature, bathroom extractor fan on/off depending on humidity, workshop dust collector on/off depending on whether some dust-producing machine is running.
It meets the 'hard thermostat' requests that have been common.
"},{"location":"Rules/#use-a-potentiometer","title":"Use a potentiometer","text":"Connecting a potentiometer to the Analog A0 input and a rule can be used to control the dimmer state of any device.
Hardware - Wemos D1 mini - Potentiometer of 2k2 connected to Gnd, A0 and 3V3 - WS2812 LED
Rule ON analog#a0div10 DO dimmer %value% ENDON\n
"},{"location":"Rules/#result_1","title":"Result","text":"Turning the potentiometer the voltage on the analog input will change resulting in a value change of 0 (Off) to 100 for the trigger. Using this value to control the dimmer of the WS2812 will control the brightness of the led(s)
Rule ON analog#a0div10 DO publish cmnd/grouplight/dimmer %value% ENDON\n
Result This time all lights configured with GroupTopic grouplight will change their brightness according to the potentiometer position.
NOTE: You might want to execute command SaveData 2 to reduce flash writes ;-)
"},{"location":"Rules/#use-a-rotary-encoder","title":"Use a rotary encoder","text":"You can capture in rules the value of a rotary encoder connected to 2 GPIOs configured as Rotary_a|<n> and Rotary_b|<n>. Optionally the button of the rotary encoder can be connected to another GPIO configured as Button|<n>. <n> must be the same to allow the encoder to manage 2 absolute counters from the same rotary encoder.
To get triggers from the rotary encoder into rules, you must enable SetOption98 1. The rotary encoder <n> provides a JSON in the form of {'Rotary<n>': {'Pos1': value, 'Pos2': value}}. You can use the following rules triggers:
SetOption98 1\nRule1\nON Rotary1#Pos1 DO something_with %value% ENDON\nON Rotary1#Pos2 DO something_with %value% ENDON\n
"},{"location":"Rules/#result_2","title":"Result","text":"Pos1 is changed when the rotary encoder is turned while button is not pressed. Pos2 is changed while button is pressed. Both Pos1 and Pos2 are published whatever is the button position, so both trig at the same time.
The button will still have its default action (such as toggling power). If you want to avoid that, you need to capture the button into a dummy rule such as ON Button1#state DO Delay 0 ENDON.
The step range of the rotary encoder can be selected using SetOption43, and the default is hardcoded in #define ROTARY_MAX_STEPS 10. To change the default range, set it in your user_config_override.h and recompile.
"},{"location":"Rules/#use-zigbee-to-control-tasmota-devices","title":"Use Zigbee to control Tasmota devices","text":"This setup uses a Zigbee gateway with an Ikea remote switch paired.
Ikea switch's name was set with ZbName to make it more user friendly.
"},{"location":"Rules/#rule_1","title":"Rule","text":"Rule1 on zbreceived#ikea_switch#power=1 do publish cmnd/backyard/POWER TOGGLE endon on zbreceived#ikea_switch#power=0 do publish cmnd/hall_light/POWER TOGGLE endon\n
"},{"location":"Rules/#result_3","title":"Result","text":"Pressing I on the Ikea switch will toggle backyard device and pressing O toggles hall_light device.
"},{"location":"Rules/#button-single-press-double-press-and-hold","title":"Button single press, double press and hold","text":"This example show how to assign different behavior to a button other than Button1. Button1 has special multi-press behaviors associated with it (see Note in Multi-Press Functions), examples 1 and 2 cannot be applied to Button1.
"},{"location":"Rules/#1st-example","title":"1st example:","text":"[assuming Button2 (or >2) and Setoption73 0]
- single press: Toggle Power2 (or >2)
- double press: send a mqtt message
- hold 2 secs: send a different mqtt message
Backlog ButtonTopic 0; SetOption1 1; SetOption11 0; SetOption32 20\nRule1\nON button2#state=3 DO publish cmnd/topicHOLD/power2 2 ENDON\nON button2#state=2 DO publish cmnd/topicDOUBLEPRESS/power2 2 ENDON Rule1 1\n
"},{"location":"Rules/#2nd-example-with-setoption11-1","title":"2nd example with Setoption11 1:","text":"[assuming Button2 (or >2) and Setoption73 0]
- single press: send MQTT message
- double press: Toggle Power2 (or >2) (SetOption11 swaps single and double press)
- hold 2 secs: send another mqtt message
Backlog ButtonTopic 0; SetOption1 1; SetOption11 1; SetOption32 20 Rule1\nON button2#state=3 DO publish cmnd/topicHOLD/power2 2 ENDON\nON button2#state=2 DO publish cmnd/topicSINGLEPRESS/power2 2 ENDON Rule1 1\n
"},{"location":"Rules/#3rd-example-for-button1","title":"3rd example for Button1:","text":"For assigning different actions to multi-press on Button1, it is mandatory to detach buttons from their default function using SetOption73 1. With SetOption73 1 buttons only publish a MQTT message (stat/tasmota/BUTTON<x> = {\"ACTION\":\"xxxx\"}). To re-assign a specific action, rules must be used like below:
- single press: Toggle Power1
- double press: send a mqtt message
- hold 2 secs: send a different mqtt message
Backlog ButtonTopic 0; SetOption73 1; SetOption32 20\nRule1\nON button1#state=10 DO power1 2 ENDON\nON button1#state=3 DO publish cmnd/topicHOLD/power 2 ENDON\nON button1#state=11 DO publish cmnd/topicDOUBLEPRESS/power 2 ENDON\nRule1 1\n
Note
SetOption73 1 detaches ALL buttons. If you have more than 1 button, you must create rules for each buttons where you want an action (other than publishing stat/tasmota/BUTTON<x> = {\"ACTION\":\"xxxx\"})
"},{"location":"Rules/#disable-switch-single-press-and-use-long-press","title":"Disable switch single press and use long press","text":"SetOption11 0
Switches do not have double press feature
[assuming a connected pushbutton configured as Switch1]
- single press: Does nothing (empty
Delay commands) - hold 2 secs: Toggle Power1
Backlog SwitchTopic1 0; SwitchMode1 5; SetOption32 20
Rule1\nON Switch1#State=3 DO Power1 2 ENDON\nON Switch1#State=2 DO Delay ENDON
Rule1 1
"},{"location":"Rules/#execute-several-commands-when-a-timer-expires","title":"Execute several commands when a Timer expires","text":"The default Timer1..16 functionality allows for controlling one output to either off, on, toggle or blink. When rules are enabled the blink option will be replaced by rule functionality allowing much more flexibility.
Configure timer5 for rule execution when activated:
Timer5 {\"Enable\":1,\"Mode\":0,\"Time\":\"16:00\",\"Days\":\"1111111\",\"Repeat\":1,\"Action\":3}\n
"},{"location":"Rules/#rule_2","title":"Rule","text":"Rule1 ON clock#Timer=5 DO Backlog Power2 on; Power1 off; Power3 2 ENDON\n
"},{"location":"Rules/#result_4","title":"Result","text":"When the timer expires the rule kicks in and set Power1 to OFF, Power2 to ON and Power3 TOGGLE.
If you want to have blink functionality define a rule like ON clock#Timer=5 DO power 3 ENDON
"},{"location":"Rules/#setting-variables","title":"Setting variables","text":"Demonstrate the use of variables. Make sure to execute commands Rule 4(Disable one-shot detection) first when trying the following example.
Set a variable
Rule ON event#setvar1 DO var1 %value% ENDON\n
Command: event setvar1=1
View a variable
rule ON event#getvar1 DO var1 ENDON\n
Command: event getvar1
Rule\nON event#togglevar1 DO event toggling1=%var1% ENDON\nON event#toggling1<1 DO event setvar1=1 ENDON\nON event#toggling1>0 DO event setvar1=0 ENDON\nON event#setvar1 DO var1 %value% ENDON\n
Command: event togglevar1
Show Messages:
Rule ON event#message DO publish stat/[topic]/log %value% ENDON\n
Command: event message=INIT
All event commands can be executed from:
- console:
event anyname=number - mqtt:
cmnd/[topic]/event anyname=number
Everything together:
Rule1 ON event#togglevar1 DO event toggling1=%var1% ENDON ON event#toggling1<1 DO event setvar1=1 ENDON ON event#toggling1>0 DO event setvar1=0 ENDON ON event#setvar1 DO var1 %value% ENDON ON event#getvar1 DO var1 ENDON ON event#message DO publish stat/mqttTopic/log %value% ENDON\n
The following won't work:
Rule1 ON event#setvar1 DO Backlog var1 %value%; Power1 %var1% ENDON
At least not as you probably would expect. The var1 value used by the Power1 command will be the value present before the Backlog command is executed. This is so, because the rule will replace %var1% BEFORE the Backlog commands are put in the Backlog command stream.
"},{"location":"Rules/#time-delayed-auto-off-switch","title":"Time-delayed Auto-off Switch","text":""},{"location":"Rules/#rule_3","title":"Rule","text":"Rule1\nON button1#state DO Backlog Power1 %value%; RuleTimer1 600 ENDON\nON Rules#Timer=1 DO Power1 off ENDON\n
"},{"location":"Rules/#result_5","title":"Result","text":"on button1#state do Backlog Power1 %value%; On Button press the Light will toggle on/off
RuleTimer1 600 ENDON Additionally RuleTimer1 will begin to countdown 10 minutes
ON Rules#Timer=1 DO Power1 off ENDON After the RuleTimer1 expires the light will be turned off (if you forgot to turn it off)
"},{"location":"Rules/#time-delay-after-switch-off","title":"Time-delay After Switch Off","text":""},{"location":"Rules/#rule_4","title":"Rule","text":"Backlog switchmode1 1; rule1 1\n
Rule1 ON switch1#state=1 DO Backlog Power1 on; ruletimer1 0 ENDON\nON switch1#state=0 DO ruletimer1 300 ENDON\nON rules#timer=1 DO Power1 0 ENDON\n
"},{"location":"Rules/#result_6","title":"Result","text":"ruletimer1 300 sets a 5 minute timer. After that time, fan will be switched off. If during the defined 5 minutes (or in general - when timer is counting) you the switch on, the timer will be canceled.
switchmode1 1 sets the switch in follow mode (LOW=off, HIGH=on) If you have inverted switch (LOW=on, HIGH=off) then use switchmode1 2
"},{"location":"Rules/#auto-off-motion-sense-switch","title":"Auto-off Motion Sense Switch","text":"Example works fine on a Wemos D1 Mini. Used as night light with motion sensor or as ambient light on floor or kitchen.
Connect an LED Strip WS2812 on D1 and the PIR on D2 and a LDR on A0 (voltage divider with 10k ohm resistor)
SwitchMode1 1
"},{"location":"Rules/#rule_5","title":"Rule","text":"Rule1\nON analog#a0<400 DO Backlog Rule3 0; Rule2 1 ENDON\nON analog#a0>500 DO Backlog Rule2 0; Rule3 1 ENDON\n
Rule2\nON switch1#state DO Backlog Power1 1; RuleTimer1 30 ENDON\nON Rules#Timer=1 DO Power1 off ENDON\n
Rule3\nON switch1#state DO Power1 off ENDON\n
Activate Rule1 with one shot detection Backlog Rule1 1; Rule1 6
Optional Backlog Rule2 4; Rule3 4
"},{"location":"Rules/#result_7","title":"Result","text":"on analog#a0>400 disable Rule3 and activate Rule2
on analog#a0>500 disable Rule2 and activate Rule3
Rule2 activates the LEDs for RuleTimer1 30 seconds on each trigger from PIR the RuleTimer start again.
on Rules#Timer=1 do Power1 off The LEDs turn off after the RuleTimer expires
Rule3 is active on daylight and pipe the PIR signal in a Power1 off signal. The LEDs stay off.
"},{"location":"Rules/#auto-off-if-or-when-current-is-idle","title":"Auto-off if or when current is idle","text":"The example is used on a Sonoff POWR316D.
It assumes an idle current of less than 0.1 amps and a grace period of 10 minutes to get consumption above the idle level.
If the consumer uses less than 0.1 amps for more than 10 minutes, then it will be turned off.
This works with either manually turning on power, using a timer or whatever.
"},{"location":"Rules/#rule_6","title":"Rule","text":"Rule1\nON system#boot DO var1 0 ENDON\nON ENERGY#Current==0.0 DO if (var1!=0) RuleTimer1 0; var1 0 endif BREAK\nON ENERGY#Current>=0.1 DO if (var1!=0) RuleTimer1 0; var1 0 endif BREAK\nON ENERGY#Current<0.1 DO if (var1!=1) RuleTimer1 600; var1 1 endif ENDON\nON Rules#Timer=1 DO Power1 off ENDON\n
"},{"location":"Rules/#control-timers-from-a-switch","title":"Control Timers from a Switch","text":"Assuming that your switch is on GPIO00 and configured as Switch1:
Switchmode1 1 will make Switch1#state be 1 when ON and 0 when OFF
If you don't set Switchmode1 or it is equal 0, it will only have Switch1#state=2 (toggle) and the rule will not work.
"},{"location":"Rules/#rule_7","title":"Rule","text":"Rule1\nON Switch1#state=1 DO Timers 0 ENDON\nON Switch1#state=0 DO Timers 1 ENDON\n
"},{"location":"Rules/#toggle-relay-when-holding-button-for-2-seconds","title":"Toggle Relay when holding button for 2 seconds","text":"The following example is to explain how to catch and use the HOLD feature for buttons.
Behavior: Disable Button1 Short Press and Toggle Relay1 only when holding button1 for 2 Seconds.
Backlog ButtonTopic 0; SetOption1 1; SetOption32 20\n
Rule1\nON button1#state=3 DO Power1 2 ENDON\nON button1#state=2 DO delay ENDON\n
Rule1 1\n
Commands Explanation
ButtonTopic 0 : (default) To not use topics for buttons SetOption1 1 : Allow only single, double and hold press button actions SetOption32 20 : Set key hold time from 0.1 to 10 seconds (20 = 2 seconds) Rule ON button1#state=3 DO Power1 2 ENDON : When holding the button1 for 2 seconds it will toggle relay 1 (state = 3 means HOLD) ON button1#state=2 DO delay ENDON : Do nothing when short pressing the button1 (state = 2 means TOGGLE) Rule1 1 : To enable rules
NOTE: There is no state value for \"double press\" for Buttons. It is designed that double press will toggle the relay. See Multi-Press Functions for more information.
In the case you do not want the double press feature you can configure your button as switch and also set SwitchMode that fits your use case (such as SwitchMode 5 to make the switch behave like a pushbutton) [SWITCH does not support double press]
Another example but using switch instead of button:
Backlog SwitchTopic1 0; SwitchMode1 5; SetOption32 20\n\nRule1\nON switch1#state=3 DO Power1 2 ENDON\nON switch1#state=2 DO delay ENDON\n\nRule1 1\n
"},{"location":"Rules/#make-sure-light-is-on-at-night","title":"Make sure Light is on at night","text":"Using Timers, you can set a light to turn on and off to illuminate a street/patio by night. But if the device has no power at the trigger time, then, when it powers up, the light will be off all night. So, as a fail-safe, implement a conditional control to be checked at Tasmota Startup.
Set Timers to turn on your light at Sunset and Turn off at sunrise. Use poweronstate 0 in order to start with lights off when powering up your device. Set the following rules:
Rule1\nON Time#Initialized DO Backlog event checksunrise=%time%; event checksunset=%time% ENDON\nON event#checksunset>%sunset% DO Power1 1 ENDON\nON event#checksunrise<%sunrise% DO Power1 1 ENDON\n
The previous rules are conditionals that represent the following logic:
IF %time%>%sunset DO Power1 1 / IF %time%<%sunrise DO Power1 1
"},{"location":"Rules/#turn-on-light-before-dawn-and-at-dusk","title":"Turn On Light Before Dawn and At Dusk","text":"Turn on light at dusk until your nighttime and again in the morning before dawn. (memory variable method)
What if the sun sets after your nighttime, as in during the summer? Then the timer will turn off the light at \"night\", but then the Sunset timer will turn it on again, so it stays on all night.
"},{"location":"Rules/#rule_8","title":"Rule","text":"Rule1\nON Time#Initialized DO event chkSun ENDON\nON Time#Minute=%sunset% DO event chkSun ENDON\nON Time#Minute=%mem2% DO event chkSun ENDON\nON Time#Minute=%sunrise% DO event chkSun ENDON\nON Time#Minute=%mem1% DO event chkSun ENDON\n
Rule2\nON event#chkSun DO Backlog var1 0; event chkSunrise=%time%; event chkSunset=%time%; event chkmorn=%time%; event chknight=%time%; event setPower ENDON\nON event#chkSunrise<%sunrise% DO var1 1 ENDON\nON event#chkSunset>=%sunset% DO var1 1 ENDON\nON event#chkmorn<%mem1% DO var1 0 ENDON\nON event#chknight>=%mem2% DO var1 0 ENDON\nON event#setPower DO Power1 %var1% ENDON\n
Backlog mem1 360; mem2 1350; Rule1 1; Rule2 1\n
"},{"location":"Rules/#result_8","title":"Result","text":" -
When device restarts, calculate if the light should be on or off ON Time#Initialized DO event chkSun ENDON
-
Calculate if the light should be on or off ON Time#Minute=%sunset% DO event chkSun ENDON ON Time#Minute=%mem2% DO event chkSun ENDON ON Time#Minute=%sunrise% DO event chkSun ENDON ON Time#Minute=%mem1% DO event chkSun ENDON
-
Calculate if the light should be on or off on event#chkSun do Backlog
-
Assume off var1 0;
-
Trigger each event with the current time event chkSunrise=%time%; event chkSunset=%time%; event chkmorn=%time%; event chknight=%time%; event setPower
-
End rule ENDON
-
If before sunrise, turn on ON event#chkSunrise<%sunrise% DO var1 1 ENDON
-
If past sunset, turn on ON event#chkSunset>=%sunset% DO var1 1 ENDON
-
But if before Morning time (mem1), do not turn on ON event#chkmorn<%mem1% DO var1 0 ENDON
-
Or if after Night time (mem2), do not turn on ON event#chknight>=%mem2% DO var1 0 ENDON
-
Perform on/off state ON event#setPower DO Power1 %var1% ENDON
-
Set variables for Morning (06h00) and Night (22h30) times Backlog mem1 360; mem2 1350
-
Turn on the rule sets Backlog Rule1 1; Rule2 1
"},{"location":"Rules/#turn-on-light-before-dawn-and-at-dusk_1","title":"Turn On Light Before Dawn and At Dusk","text":"Turn on light at dusk until your nighttime and again in the morning before dawn. (Web UI timer method)
What if the sun sets after your nighttime, as in during the summer? Then the timer will turn off the light at \"night\", but then the Sunset timer will turn it on again, so it stays on all night. This version uses the timers to set the actual time, using the %timerN% variables made availible in Tasmota V11. As a result, while the rule still needs to be applied by a skilled user, a less savvy family member can next choose or modify the desired times.
"},{"location":"Rules/#rule_9","title":"Rule","text":"Rule1\nON Time#Initialized DO event checktime=%time% ENDON\nON Clock#Timer DO event checktime=%time% ENDON\nON event#checktime DO %var10% 0 ENDON\nON event#checktime>=%timer1% DO var10 1 ENDON\nON event#checktime>=%timer2% DO var10 0 ENDON\nON event#checktime>=%timer3% DO var10 1 ENDON\nON event#checktime>=%timer4% DO var10 0 ENDON\nON event#checktime DO Power1 %var10% ENDON\n
You do need to make sure the timers are set to run rules instead of hard ON-OFF. Timer 1,3 are interpreted as ON, Timer 2,4 as OFF. Here are some example timers, on at 06h00, off at 23h00, but you can also set these in the Web UI
Timer1 {\"Enable\":1,\"Mode\":0,\"Time\":\"06:00\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":2,\"Action\":3}\nTimer2 {\"Enable\":1,\"Mode\":1,\"Time\":\"00:00\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":2,\"Action\":3}\nTimer3 {\"Enable\":1,\"Mode\":2,\"Time\":\"00:00\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":2,\"Action\":3}\nTimer4 {\"Enable\":1,\"Mode\":0,\"Time\":\"23:00\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":2,\"Action\":3}\n
The basic rule above works for all situations where the sun (with or without offset) or scheduled time does not pass midnight. The more advanced version below works (from #16914 onward) also if the sunset or scheduled time is after midnight, or even if there is no sunset at all (permanent daylight or night in north scandinavia)
Rule1\nON Time#Initialized DO event checktime=%time% ENDON\nON Clock#Timer DO event checktime=%time% ENDON\nON event#checktime DO Backlog var1 %timer1%; var2 %timer2%; var3 %timer3%; var4 %timer4%; var5 %value%; var6 %value%; var10 0; event checknoon=%value%; ENDON\nON var1#state>1140 DO sub1 1440 ENDON\nON var2#state>1140 DO sub2 1440 ENDON\nON var5#state>1140 DO sub5 1440 ENDON\nON var3#state<=420 DO add3 1440 ENDON\nON var4#state<=420 DO add4 1440 ENDON\nON var6#state<=420 DO add6 1440 ENDON\nON event#checknoon DO Backlog event checkafternoon=%var6% ENDON\nON event#checknoon<=780 DO Backlog event checkmorning=%var5%; event settime ENDON\nON event#checknoon>780 DO Backlog event checkafternoon=%var6%; event settime ENDON\nON event#checkmorning>=%var1% DO var10 1 ENDON\nON event#checkmorning>=%var2% DO var10 0 ENDON\nON event#checkafternoon>=%var3% DO var10 1 ENDON\nON event#checkafternoon>=%var4% DO var10 0 ENDON\nON event#settime DO Power1 %var10% ENDON\n
For an attempted explanation of above advanced rule, please refer to the design and test XLS in #16914"},{"location":"Rules/#enable-a-pir-switch-only-at-night","title":"Enable a PIR Switch only at night","text":"Latitude and Longitude need to be set in config. Use PulseTime to specify the duration the light should remains on. Every PIR trigger will restart for that amount of time.
SwitchMode1 14\nPulseTime 60\n
Rule1\nON Switch1#state=1 DO Backlog event checksunrise=%time%; event checksunset=%time% ENDON\nON event#checksunrise<%sunrise% DO Power1 1 ENDON\nON event#checksunset>%sunset% DO Power1 1 ENDON\n
"},{"location":"Rules/#control-luminance-switch-with-timer","title":"Control luminance switch with Timer","text":"Background: Tasmota powers a Sonoff Basic attached to a TS-2561 Luminance Sensor. This switch toggles a lamp ON or OFF. The switch should work as below: i) during daytime (sunrise-sunset): ON when it is too dark (<150 lx) and OFF when it gets brighter (>175 lx). ii) during evenings it ignores the sensor and turns on at sunset and turns off after about 5 hours
Approach: Used a combination of Clock Timers and Rule to do this.
Timer 1: Power ON switch at Sunset Powers on the switch at sunset with an offset of 20 minutes. Repeats every day.
Timer1 {\"Enable\":1,\"Mode\":2,\"Time\":\"-00:20\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":1,\"Action\":1}\n
Timer 2: Power OFF switch at Night. Turns power OFF at 23.00hrs. Repeats every day.
Timer2 {\"Enable\":1,\"Mode\":0,\"Time\":\"23:00\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":1,\"Action\":0}\n
Timer 3: Trigger Luminance Rule at Sunrise Start watching the Lux sensor 15 minutes after sunrise.
Timer3 {\"Enable\":1,\"Mode\":1,\"Time\":\"00:15\",\"Window\":0,\"Days\":\"1111111\",\"Repeat\":1,\"Output\":1,\"Action\":3}\n
Rule 1: Main Rule to check Luminance If Luminance is less than 150lx, power ON. If it goes beyond 175lx, power OFF.
Rule1\nON tele-TSL2561#Illuminance<150 DO Power1 1 ENDON\nON tele-TSL2561#Illuminance>175 DO Power1 0 ENDON Rule1 1\n```haskell\n\n**Rule 2:** Trigger Rule1 only in the Mornings This ensures that Rule1 is triggered when Timer3 starts (in the morning) and stops when Timer1 starts (in the evenings). ```haskell\nRule2\nON Clock#Timer=3 DO Rule1 1 ENDON\nON Clock#Timer=1 DO Rule1 0 ENDON\n\nRule2 1\n
"},{"location":"Rules/#automatically-vary-the-color-temperature-of-a-cct-light","title":"Automatically vary the color temperature of a CCT light","text":"Background: Tasmota powers a CCT light which is adjustable from cool white to warm white. You want the color temperature to automatically vary between cool (CT=153) at midday to warm (CT=500) at midnight.
Approach: Check that your timezone and DST (if applicable) are set correctly and the time is correctly set on your light using NTP. Create the two rules to scale the CT based on the time of day. If Wifi is unavailable or NTP can't determine the time of day then the light will default to the mid point for neutral white (CT=326). Adjusting the CT will switch the light on so Rule 2 disables and enables Rule 1 according to the state of the light.
Rule 1: Set the CT according to the time of day.
rule1 on Power1#Boot do CT 326 endon\non Time#Initialized do backlog event myCT=%time% endon\non Time#Minute do backlog event myCT=%time% endon\non event#myCT<=720 do backlog scale1 %time%,0,720,500,153; event updateCT endon\non event#myCT>720 do backlog scale1 %time%,720,1440,153,500; event updateCT endon\non event#updateCT do CT %var1% endon\nrule1 1\n
Rule 2: Toggle rule 1 on and off with the light and also update the CT for the current time when the light is switched on. Rule2 on Power1#State do backlog Rule1 %value%; event myCT=%time% endon\nRule2 1\n
Notes: When the light is powered up on it should change to neutral white for a few seconds while Wifi, MQTT and NTP are initialised then switch to the correct color temperature for the time of day. If the light is switched off in software then it will come back on with the previous CT then update to the current CT after a few seconds.
If you have a RGBCCT light then the CT light may be Power2 rather than Power1.
It is possible to use %sunrise% and %sunset% to adjust the CT if you set your latitude, longitude and elevation but it's much more complex especially at extreme Northern and Southern latitudes.
"},{"location":"Rules/#perform-any-action-on-singledouble-press-for-switches-and-buttons","title":"Perform any action on single/double press (for switches AND buttons)","text":""},{"location":"Rules/#rule_10","title":"Rule","text":"SwitchMode 5
Rule1\nON switch1#state==2 DO add1 1 ENDON\nON switch1#state==2 DO Power1 2 ENDON\nON var1#state!=0 DO Backlog delay 6;var1 0 ENDON\nON var1#state==2 DO publish cmnd/othertasmota/POWER toggle ENDON\n
Rule1 on
"},{"location":"Rules/#result_9","title":"Result","text":" - each toggle of the switch triggers first condition and adds 1 to our variable (var1 in the example),
- each toggle of the switch toggles the associated relay (
Power1 2 - but can do anything else instead, Publish for example) - when var1 changes to non zero, we set it back to 0 but after a
Delay (arbitrarily chosen 6 here - 0.6 seconds) - when var1 reaches 2 (i.e. the switch has been toggled twice within the last 0.6 seconds), desired action is triggered (here:
Publish to othertasmota)
Every time you press the switch, your light toggles state (as it should). If you do press the switch twice in a rapid succession (i.e., double-click), you can trigger a different action (e.g., on a remote device).
"},{"location":"Rules/#enable-or-disable-relay-with-a-switch-in-domoticz","title":"Enable or disable relay with a switch in Domoticz","text":"When you want to send MQTT messages ( we use domoticz in this example ) and choose when you want the relay on or off, by simply sending HTTP commands to trigger an event.
Initial Config:
- PushButton Doorbell
- (Sonoff Basic R1) GPIO14 - Switch4 (12)
Connect the Switch to GND and the GPIO on your device. Be sure put a 4.7k resistor between VCC(3.3v) and the GPIO. This prevents ghost switching (capacitor is optional) See: YouTube
Dont forget to change the IDX value
Commands:
Backlog SwitchTopic 0; SwitchMode4 2; SetOption0 0; PowerOnState 0\n\nvar1 1\n\nRule1\nON event#doorbell DO var1 %value% ENDON\nON switch4#state=1 DO publish domoticz/in {\"idx\":11,\"nvalue\":1} ENDON\nON switch4#state=1 DO Power1 %var1% ENDON\nON switch4#state=0 DO publish domoticz/in {\"idx\":11,\"nvalue\":0} ENDON\nON switch4#state=0 DO Power1 0 ENDON\n\nRule1 1\n
Usage:
Turn off the relay by calling the event using HTTP: http://<tasmotaIP>/cm?cmnd=event%20doorbell=0
Turn on the relay by calling the event using HTTP: http://<tasmotaIP>/cm?cmnd=event%20doorbell=1
If your Tasmota device is password protected, which is most common, then use the following HTTP commands instead. Make sure you change <tasmotaUsername> and <tasmotaPassword>
Off: http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=0 On: http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=1
"},{"location":"Rules/#force-automatic-re-connection-to-mqtt-server-via-sd-dns","title":"Force automatic re-connection to MQTT server via SD DNS","text":"In order to search for the MQTT server using SD-DNS service (a.k.a. Bonjour or Zero Network Configuration) the suggested configuration is to leave the MQTT Host field blank.
The standard behavior of Tasmota is
- searches for _mqtt._tcp service
- resolve that to the proper IP address
- connect to it
- in case the connection is successful, retain the IP address and use that in the subsequent connections
The above is not proper, though, in case you have a redundant MQTT (e.g., two MQTT server synchronized). In such case, when the active MQTT fails for any reason, the expected behavior is to achieve automatic re-connection to the other MQTT server.
That can be easily configured defining the following rule on the device console:
Rule1 ON Mqtt#Disconnected DO MqttHost 0 ENDON\nRule1 1\n
If the MqttHost field already contains an IP, you have to delete it using the web interface or the following MQTT command:
mosquitto_pub -h mqtt_server.local -t \"cmnd/mqttTopic/MqttHost\" -m ''\n
"},{"location":"Rules/#change-distance-to-percentage","title":"Change distance to percentage","text":"When measuring distance and you have the need to see it in percentage of distance. In the example 100% is everything below 69cm and 0% is everything above 128cm. This is used for showing fill percentage of a wood pellets storage.
Rule1\nON tele-SR04#distance DO Backlog var1 %value%; event checklimit=%value%; event senddistance ENDON\nON event#checklimit>128 DO var1 128 ENDON\nON event#checklimit<69 DO var1 68 ENDON\nON event#senddistance DO Backlog SCALE1 %var1%, 128, 69, 0, 100; event pubdata ENDON\nON event#pubdata DO publish tele/pannrum-temp/SENSOR %var1% ENDON\n\nRule1 1\n
"},{"location":"Rules/#distinguish-switch1-and-switch2-without-the-use-of-relay1-and-relay2","title":"Distinguish Switch1 and Switch2 (without the use of Relay1 and Relay2)","text":"When two (or more) switches are defined as input and you want to distinguish these in the RESULT topic without the use of Relays, then consider the following rules.
-
SwitchMode1 1 will make Switch1#state to be 1 when ON and 0 when OFF SwitchMode1 1
-
SwitchMode2 1 will make Switch2#state to be 1 when ON and 0 when OFF SwitchMode2 1
-
Publish json with key POWER1 and value %value%
Rule1 ON switch1#state DO publish stat/wemos-4/RESULT {\"POWER1\":\"%value%\"} ENDON\n
-
Publish json with key POWER2 and value %value%
Rule2 ON switch2#state DO publish stat/wemos-4/RESULT {\"POWER2\":\"%value%\"} ENDON\n
-
Enable Rules Backlog Rule1 1; Rule2 1
Output:
RUL: SWITCH1#STATE performs \"publish stat/wemos-4/RESULT {\"POWER1\":\"1\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER1\":\"1\"}\nRUL: SWITCH2#STATE performs \"publish stat/wemos-4/RESULT {\"POWER2\":\"1\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER2\":\"1\"}\nRUL: SWITCH1#STATE performs \"publish stat/wemos-4/RESULT {\"POWER1\":\"0\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER1\":\"0\"}\nRUL: SWITCH2#STATE performs \"publish stat/wemos-4/RESULT {\"POWER2\":\"0\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER2\":\"0\"}\nRUL: SWITCH1#STATE performs \"publish stat/wemos-4/RESULT {\"POWER1\":\"1\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER1\":\"1\"}\nRUL: SWITCH1#STATE performs \"publish stat/wemos-4/RESULT {\"POWER1\":\"0\"}\"\nMQT: stat/wemos-4/RESULT = {\"POWER1\":\"0\"}\n
"},{"location":"Rules/#receiving-state-of-anything-that-triggers-switch-more-than-one-time","title":"Receiving state of anything that triggers SWITCH more than one time","text":"With analog intercom doorbells you can take out info about ringing from speaker voltage. You can connect GPIO to it via opto-isolator and resistor to take out state. But even with those speaker voltage is dropping so it switches the device multiple times.
MQT: cmnd/doorbell/POWER2 = OFF (retained)\nMQT: cmnd/doorbell/POWER2 = ON (retained)\nMQT: cmnd/doorbell/POWER2 = OFF (retained)\nMQT: cmnd/doorbell/POWER2 = ON (retained)\nMQT: cmnd/doorbell/POWER2 = OFF (retained)\n
To solve it we can use rules.
SwitchTopic 0\n\nRule1\non System#Boot DO var1 0 ENDON\nON Switch2#State DO Backlog add1 1; event START ENDON\nON event#START DO event BELL=%var1% ENDON\nON event#BELL=1.000 DO Backlog publish cmnd/bell/power on; RuleTimer1 60 ENDON\nON event#BELL=0 DO publish cmnd/bell/power off ENDON\nON Rules#Timer=1 DO Backlog var1 0; event BELL=0 ENDON\n\nRule1 1\n
description:
- Disable SwitchTopic as it overrides rules for switches:
SwitchTopic 0 - on system boot set var1 to 0
- on switch2 click (person pushing doorbell) - var1 += 1; trigger event START
- on START - set event BELL equal to var1
- if event#BELL=1 (triggered first time) publish mqtt message ON and trigger RulesTimer1 for 60 seconds
- if event#BELL=0 publish mqtt message OFF
- on RulesTimer1 - reset var1 to 0, and call event#BELL.
- enable rule 1
In this case we have lock for 60 seconds for multiple people calls or to be resistant for speaker voltage drops.
"},{"location":"Rules/#prevent-wemos-d1-mini-load-overcurrent","title":"Prevent Wemos D1 mini load overcurrent","text":"As a WS2812 24 led ring draws approximately 24x3x20 mA = 1.44A and the Wemos D1 mini powered from a PC's USB port can only provide up to 0.5A it would be nice to have some kind of mechanism in place to limit the amount of current to the WS2812 LEDring to 0.1A. This is still enough to light all 24 leds up to color 202020.
Hardware
- Wemos D1 mini
- INA219 I2C sensor
- WS2812 LEDring with 24 LEDs powered by the Wemos D1 mini 5V thru the INA219 sensor
Rule1 ON INA219#Current>0.100 DO Backlog Dimmer 10;Color 10,0,0 ENDON\nRule1 on\n
Result - When a user raises brightness to a level using more than 0.1A the rule kicks in and lowers the current by executing command Dimmer 10 and changes the color to Red with command Color 10,0,0.
"},{"location":"Rules/#using-dummy-gpio-to-send-serial-codes-to-an-mcu","title":"Using dummy GPIO to send Serial codes to an MCU","text":"By having a device that controls all its features through an MCU and reports the states in serial codes to the ESP8266 we have to create some rules to control it using the Web UI or standard Power commands.
Rule1\nON Power1#state=1 DO serialsend5 55AA00060005020400010213 ENDON ON Power1#state=0 DO serialsend5 55AA00060005020400010011 ENDON ON Power2#state=1 DO serialsend5 55AA00060005060400010217 ENDON ON Power2#state=0 DO serialsend5 55AA00060005060400010015 ENDON\n
Power1 controls the device, Power2 turn on and off the light on the device. Another rule was created to issue commands on boot so the serial interface works every time and to control the built in fan using Event triggers and have its state retained in an MQTT message for Home Assistant.
Rule2 ON system#boot DO Backlog baudrate 9600; seriallog 2; serialsend5 55aa000300010306 ENDON ON event#high DO Backlog serialsend5 55AA00060005650400010175; publish2 stat/diffuser/FAN high ENDON ON event#low DO Backlog serialsend5 55AA00060005650400010074; publish2 stat/diffuser/FAN low ENDON\n
"},{"location":"Rules/#arithmetic-commands-used-with-var","title":"Arithmetic commands used with VAR","text":"Note
The arithmetic is done using single point precision floating point. This means calculations involving values larger than approximately 16 million (ex: %utctime%) will not be precise.
"},{"location":"Rules/#add","title":"ADD","text":"ADD1 to ADD5: Add a value to VARx Syntax: ADDx value Usage: ADD1 15 Result: VAR1 = VAR1 + 15
"},{"location":"Rules/#subtract","title":"SUBTRACT","text":"SUB1to SUB5: Subtract a value from VARx Syntax: SUBx value Usage: SUB1 15 Result: VAR1 = VAR1 - 15
"},{"location":"Rules/#multiply","title":"MULTIPLY","text":"MULT1to MULT5: Multiply a value to VARx Syntax: MULTx value Usage: MULT1 15 Result: VAR1 = VAR1 * 15
"},{"location":"Rules/#scale-a-value","title":"SCALE A VALUE","text":"SCALE1to SCALE5: Scale a value from a low and high limit to another low and high limit and store it in VARx (directly equivalent to MAP arduino command)
Syntax: SCALEx value, fromLow, fromHigh, toLow, toHigh
where,
value: the number to scale fromLow: the lower bound of the value\u2019s current range fromHigh: the upper bound of the value\u2019s current range toLow: the lower bound of the value\u2019s target range toHigh: the upper bound of the value\u2019s target range
(omitted values are taken as zero)
Usage: SCALE1 15, 0, 100, 0, 1000 Result: VAR1 = 150
"},{"location":"Rules/#transmit-sensor-value-only-when-a-delta-is-reached","title":"Transmit sensor value only when a delta is reached","text":"Send only when the sensor value changes by a certain amount.
Rule1\nON SI7021#temperature>%var1% DO Backlog var1 %value%; publish stat/mqttTopic/temp %value%; var2 %value%; add1 2; sub2 2 ENDON\nON SI7021#temperature<%var2% DO Backlog var2 %value%; publish stat/mqttTopic/temp %value%; var1 %value%; add1 2; sub2 2 ENDON\n
This example explains expands on the above example while matching typical sensor data. Helpful for HA tasmota integration sensors when polling and adding in delta value changes.
Normal polling data below
23:58:41 MQT: tele/ds1820/SENSOR = {\"Time\":\"2021-01-13T23:58:41\",\"DS18B20\":{\"Id\":\"030597946B04\",\"Temperature\":20.9},\"TempUnit\":\"C\"}\n
The matching rule. Rule1 ON DS18B20#temperature>%var1% DO Backlog var1 %value%; publish tele/ds1820/SENSOR {\"Time\":\"%timestamp%\",\"DS18B20\":{\"Id\":\"030597946B04\",\"Temperature\":%value%},\"TempUnit\":\"C\"}; var2 %value%; add1 0.5; sub2 0.5 ENDON ON DS18B20#temperature<%var2% DO Backlog var2 %value%; publish tele/ds1820/SENSOR {\"Time\":\"%TIMESTAMP%\",\"DS18B20\":{\"Id\":\"030597946B04\",\"Temperature\":%value%},\"TempUnit\":\"C\"}; var1 %value%; add1 0.5; sub2 0.5 ENDON\n
"},{"location":"Rules/#adjust-a-value-and-send-it-over-mqtt","title":"Adjust a value and send it over MQTT","text":"This example adds 2 degrees to the measured temperature and then sends that value to an MQTT topic.
Rule1\nON tele-SI7021#temperature DO Backlog var1 %value%; add1 2; event sendtemp ENDON\nON event#sendtemp DO publish stat/mqttTopic/temp %var1% ENDON\n
"},{"location":"Rules/#control-relays-via-serial","title":"Control relays via serial","text":"This example switches connected relays over the software serial on and off.
Write the following rules:
rule1\nON SSerialReceived#Data=on DO Power1 1 ENDON\nON SSerialReceived#Data=off DO Power1 0 ENDON\n
receiving on and off results in
MQT: tele/mqttTopic/RESULT = {\"SSerialReceived\":\"on\"}\nRUL: SSERIALRECEIVED#DATA=ON performs \"Power1 1\"\nMQT: stat/mqttTopic/RESULT = {\"POWER\":\"ON\"}\nMQT: stat/mqttTopic/POWER = ON\nMQT: tele/mqttTopic/RESULT = {\"SSerialReceived\":\"off\"}\nRUL: SSERIALRECEIVED#DATA=OFF performs \"Power1 0\"\nMQT: stat/mqttTopic/RESULT = {\"POWER\":\"OFF\"}\nMQT: stat/mqttTopic/POWER = OFF\n
"},{"location":"Rules/#processing-json-received-from-softwareserialbridge","title":"Processing JSON received from (Software)SerialBridge","text":"When using SerialBridge (or SoftwareSerialBridge), the received string will be published to Rules as SerialReceived (or SSerialReceived). If the string starts with a { then Tasmota will parse the string as a JSON and make the different keys available for Rules. For example with the following string {\"DeviceID\":\"TM182\",\"Temp\":25.3,\"Hum\":50}, it is possible to use any of the keys in the trigger.
rule1\n ON SSerialReceived#DeviceID DO var1 %value% ENDON\n ON SSerialReceived#Temp DO var2 %value% ENDON\n ON SSerialReceived#Hum DO publish /some/topic/%var1% {\"Temperature\":%var2%,\"Humidity\":%value%} ENDON\n
The 1st and 2nd rules store the values for Device and Temp into variables. The last key triggers the 3rd rule, here re-publication on a different topic.
Execution:
12:51:48.050 MQT: tele/nodemcu/SSERIALRECEIVED = {\"SSerialReceived\":{\"DeviceID\":\"TM182\",\"Temp\":25.3,\"Hum\":50}}\n12:51:48.064 RUL: SSERIALRECEIVED#DEVICEID performs \"var1 TM182\"\n12:51:48.071 MQT: stat/nodemcu/VAR = {\"Var1\":\"TM182\"}\n12:51:48.083 RUL: SSERIALRECEIVED#TEMP performs \"var2 25.3\"\n12:51:48.091 MQT: stat/nodemcu/VAR = {\"Var2\":\"25.3\"}\n12:51:48.104 RUL: SSERIALRECEIVED#HUM performs \"publish /some/topic/TM182 {\"Temperature\":25.3,\"Humidity\":50}\"\n12:51:48.110 MQT: /some/topic/TM182 = {\"Temperature\":25.3,\"Humidity\":50}\n
Note
It is important that the receive string strictly starts with the opening {. If other characters, such as spaces or new line are inserted before, Tasmota will not par as a JSON. Characters after the closing } are not a problem.
"},{"location":"Rules/#using-break-to-simulate-ifelseifelseendif","title":"Using BREAK to simulate IF..ELSEIF..ELSE..ENDIF","text":"BREAK is an alternative to ENDON. BREAK will stop the execution for the triggers that follow. If a trigger that ends with BREAK fires, then the following triggers of that rule will not be executed. This allows to simulate IF..ELSEIF..ELSE..ENDIF
Example:
IF temp > 85 then\n VAR1 more85\nELSEIF temp > 83 then\n VAR1 more83\nELSEIF temp > 81 then\n VAR1 more81\nELSEIF temp = 81 then\n VAR1 equal81\nELSE\n VAR1 less81\nENDIF\n
With the actual rules, if we use a set like the following:
Rule1\nON event#temp>85 DO VAR1 more85 ENDON\nON event#temp>83 DO VAR1 more83 ENDON\nON event#temp>81 DO VAR1 more81 ENDON\nON event#temp=81 DO VAR1 equal81 ENDON\nON event#temp<81 DO VAR1 less81 ENDON\n
This is the output in the console:
CMD: rule\nMQT: stat/living/RESULT = {\"Rule1\":\"ON\",\"Once\":\"ON\",\"StopOnError\":\"OFF\",\"Free\":322,\"Rules\":\"ON event#temp>85 do VAR1 more85 ENDON ON event#temp>83 do VAR1 more83 ENDON on event#temp>81 do VAR1 more81 ENDON on event#temp=81 do VAR1 equal81 ENDON on event#temp<81 DO VAR1 less81 ENDON\"}\nCMD: event temp=10\nMQT: stat/living/RESULT = {\"Event\":\"Done\"}\nRUL: EVENT#TEMP<81 performs \"VAR1 less81\"\nMQT: stat/living/RESULT = {\"Var1\":\"less81\"}\nCMD: event temp=100\nMQT: stat/living/RESULT = {\"Event\":\"Done\"}\nRUL: EVENT#TEMP>85 performs \"VAR1 more85\"\nMQT: stat/living/RESULT = {\"Var1\":\"more85\"}\nRUL: EVENT#TEMP>83 performs \"VAR1 more83\"\nMQT: stat/living/RESULT = {\"Var1\":\"more83\"}\nRUL: EVENT#TEMP>81 performs \"VAR1 more81\"\nMQT: stat/living/RESULT = {\"Var1\":\"more81\"}\n
So, all the triggers where TEMP>100, are firing. With the BREAK statement the rule set can be changed to: Rule\non event#temp>85 do VAR1 more85 break\non event#temp>83 do VAR1 more83 break\nON event#temp>81 DO VAR1 more81 ENDON\nON event#temp=81 DO VAR1 equal81 ENDON\nON event#temp<81 DO VAR1 less81 ENDON\n
Which will result in the following output:
CMD: rule\nRSL: RESULT = {\"Rule1\":\"ON\",\"Once\":\"OFF\",\"StopOnError\":\"OFF\",\"Free\":321,\"Rules\":\"ON event#temp>85 do VAR1 more85 break ON event#temp>83 do VAR1 more83 break on event#temp>81 do VAR1 more81 ENDON on event#temp=81 do VAR1 equal81 ENDON on event#temp<81 DO VAR1 less81 ENDON\"}\nCMD: event temp=10\nRSL: RESULT = {\"Event\":\"Done\"}\nRUL: EVENT#TEMP<81 performs \"VAR1 less81\"\nRSL: RESULT = {\"Var1\":\"less81\"}\nCMD: event temp=100\nRSL: RESULT = {\"Event\":\"Done\"}\nRUL: EVENT#TEMP>85 performs \"VAR1 more85\"\nRSL: RESULT = {\"Var1\":\"more85\"}\nCMD: event temp=83\nRSL: RESULT = {\"Event\":\"Done\"}\nRUL: EVENT#TEMP>81 performs \"VAR1 more81\"\nRSL: RESULT = {\"Var1\":\"more81\"}\n
"},{"location":"Rules/#adjust-powerdelta-according-to-current-power-values","title":"Adjust PowerDelta according to current Power values","text":"Power sensor reporting thresholds are set by a percentage change in the Power value by setting PowerDelta. Power changes from 10W to 11W (10%) may not be very interesting. But power changes from 1000W to 1100W (also 10%) could be very important. To avoid getting reports for small changes but ensuring that larger power swings are reported, a rule set can be used to create a gradient threshold based on the absolute power values.
This rule also uses the one-shot feature of rules to avoid reporting of every small change within a threshold window. The rule (a ON/DO/ENDON rule in this the set) will trigger only once when a threshold is crossed.
Backlog PowerDelta 0; Rule1 0; Rule1 5\n\nRule1\nON ENERGY#Power>=35 DO Backlog PowerDelta 10; Status 8 BREAK ON ENERGY#Power>=15 DO Backlog PowerDelta 25; Status 8 BREAK ON ENERGY#Power>5 DO Backlog PowerDelta 35; Status 8 BREAK ON ENERGY#Power<=5 DO PowerDelta 100 ENDON\n\nRule1 1\n
Which translates (pseudo code):
IF ENERGY#Power>=35 // ENERGY#Power GE 35\nDO Backlog PowerDelta 10; Status 8\nELSE IF ENERGY#Power>=15 // ENERGY#Power GE 15 and LT 35\nDO Backlog PowerDelta 25; Status 8\nELSE IF ENERGY#Power>5 // ENERGY#Power GT 5 and LT 15\nDO Backlog PowerDelta 35; Status 8\nELSE // ENERGY#Power changed (i.e. LE 5)\nDO PowerDelta 100\n
"},{"location":"Rules/#forward-ir-signals","title":"Forward IR signals","text":"Using one IR receiver and one sender (or both extender) you can simply forward signals from one to another using the following rule
rule1 ON IRreceived#Data DO publish cmnd/irsideboard/irsend {Protocol:NEC,Bits:32,Data:%value%} ENDON\n
"},{"location":"Rules/#garage-door-opener","title":"Garage Door Opener","text":"(#3942)
// Set the relay on time to signal the opener PulseTime 7
// Send ON and OFF as the switch is ON or OFF
Backlog SwitchMode1 1; SwitchMode2 1; SwitchMode3 1\n
//No need to save changes on power cycle SetOption0 0
//Don\u2019t blindly run the door on power up PowerOnState 0
//One shot Detection off
Backlog Rule1 0; Rule1 4; Rule2 0; Rule2 4; Rule2 0; Rule2 4\n
//Set Counter to measure the period between on and off, check if it's blinking because of an obstruction
Backlog CounterType 1; CounterDebounce 100\n
//So the door doesn't close if you send it an Open when it's already Opened, etc.
// var1=1 Only When OPEN \n// var2=1 Only When CLOSED \n// var3=1 Only When OPENING \n// var4=1 Only When CLOSING \n
Rule1\nON Switch1#Boot=1 DO Backlog delay 99; event Opened ENDON\nON Switch2#Boot=1 DO Backlog delay 99; event Closed ENDON\nON EVENT#OPEN DO Power1 %var2% ENDON\nON EVENT#CLOSE DO Power1 %var1% ENDON\nON EVENT#STOP DO Backlog Power1 %var3%; Power1 %var4%; event PState=STOP ENDON\nON Switch1#State=1 DO event Opened ENDON\nON Switch2#State=1 DO event Closed ENDON\nON Switch1#State=0 DO event Closing ENDON\nON Switch2#State=0 DO event Opening ENDON\n\nRule2\nON event#Opened DO Backlog var 1; var2 0; var3 0; var4 0; ruletimer1 0; event PState=OPEN ENDON\nON event#Closed DO Backlog var1 0; var2 1; var3 0; var4 0; ruletimer1 0; event PState=CLOSE ENDON\nON event#Opening DO Backlog var1 0; var2 0; var3 1; var4 0; ruletimer1 15; event PState=OPENING ENDON\nON event#Closing DO Backlog var1 0; var2 0; var3 0; var4 1; ruletimer1 15; event PState=CLOSING ENDON\n\nRule3\nON counter#c1>1000 DO event PObstr=0 ENDON\nON counter#c1<1000 DO event PObstr=1 ENDON\nON event#PObstr DO publish stat/GarageDoor/OBSTR %value% ENDON\nON event#PState DO publish stat/GarageDoor/STATE %value% ENDON\nON rules#timer=1 DO event PState=STOP ENDON\n
//Turn on Rules
Backlog Rule1 1; Rule2 1; Rule3 1\n
"},{"location":"Rules/#ir-remote-button-multi-press","title":"IR Remote Button Multi-press","text":"For example, a remote control with one button to change speed. This rules simulates pressing the button three times to set the receiving device to the third speed setting.
Specify the rule set
- The
<trigger> can be a condition or an event sent from another device or home automation hub. <topic> corresponds to the device transmitting the code (e.g., YTF IR Bridge). This could also be modified to send an RF code from a Sonoff RF Bridge. - The
Delay may not be necessary in your environment or may need to be adjusted according to your device characteristics.
Rule 1\nON Event#tora DO Backlog Publish cmnd/<topic>/IRSend {\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":\"0x00FF30CF\"}; Delay 10 ENDON\nON <trigger> DO Backlog Event tora; Event tora; Event tora ENDON\n
- Enable the Rule set
Rule1 1
"},{"location":"Rules/#two-way-light-switches-without-mqtt","title":"Two-way light switches without MQTT","text":"Two Sonoff T1 3-gang light switches can be used at either end of a room by setting up one the master and the other as the slave. The master performs the switching of the power to the lights, while the slave just asks the master to toggle the power state. The master also turns the slave's relays on and off so that the LED indicators follow the master's state.
Using the WebSend command, the two switches can talk to each other without an MQTT broker. It remains to be seen how reliable this is.
Starting with the slave, the rule to toggle the master is pretty simple:
Rule1\nON Event#sendPower DO WebSend [192.168.0.74] POWER%value% TOGGLE ENDON\nON Button1#State DO Event sendPower=1 ENDON\nON Button2#State DO Event sendPower=2 ENDON\nON Button3#State DO Event sendPower=3 ENDON\n
Rule1 1 Note that having a rule for the Button#State disables the power toggling of the slave's relay(s). This is desirable because we want the master to control the slave's relay state(s) according to its own as follows:
Rule1\nON Event#sendPower DO WebSend [192.168.0.144] POWER%Var1% %value% ENDON\nON Power1#state DO Backlog Var1 1;Event sendPower=%value% ENDON\nON Power2#state DO Backlog Var1 2;Event sendPower=%value% ENDON\nON Power3#state DO Backlog Var1 3;Event sendPower=%value% ENDON\n
Rule1 1"},{"location":"Rules/#control-remote-light-on-switch-double-press","title":"Control remote light on switch double press","text":"Toggling the switch controls local POWER state while toggling twice fast controls another device.
Great with two SONOFF MINI in adjacent rooms, to control both rooms with either switch.
SwitchMode 8\nRule1 ON switch1#state=3 DO websend [ip/hostname of remote] power1 toggle ENDON\nRule1 1\n
"},{"location":"Rules/#roller-shutter-push-button-toggle","title":"Roller shutter push-button toggle","text":"With a two relay device (e.g., Shelly 2.5) configured for a roller shutter, you can also connect push-buttons (configured as switch components in this example) and set them for inverted toggle behavior. Pressing a push-button once makes the roller shutter move in one direction. Pressing it again stops it. These rules each use a variable to remember the shutter state where 0 == Stopped and 1 == Moving.
Backlog SwitchTopic 0; SwitchMode1 4; SwitchMode2 4\n\nRule1\nON Switch1#State==1 DO Add1 1 ENDON\nON Var1#State==0 DO ShutterStop1 ENDON\nON Var1#State==1 DO ShutterClose1 ENDON\nON Var1#State>=2 DO Var1 0 ENDON\nON Shutter1#Close DO Var1 0 ENDON\nON Switch2#State==1 DO Add2 1 ENDON\nON Var2#State==0 DO ShutterStop1 ENDON\nON Var2#State==1 DO ShutterOpen1 ENDON\nON Var2#State>=2 DO Var2 0 ENDON\nON Shutter1#Open DO Var2 0 ENDON\n\nRule1 1\n
"},{"location":"Rules/#control-a-dimmer-with-one-switch","title":"Control a dimmer with one switch","text":"This example is for GPIOs defined as switches not buttons
Activate dimmer mode with Switchmode 11 and shorten long press time to 1 second (Setoption32 10).
A short press of the switch sends a TOGGLE message to toggle the dimmer. A long press sends repeated INC_DEC messages to increment the dimmer. If a second press of the switch follows the first press an INV message is sent to invert the function from increment to decrement and repeated INC_DEC messages are sent to decrement the dimmer. After releasing the switch a timeout message CLEAR resets the automation
Backlog SwitchMode 11; SetOption32 10; Rule1 1;\n\nRule1 on system#boot do var1 + ENDON\non switch1#state=2 do POWER TOGGLE ENDON\non switch1#state=4 do DIMMER %var1% ENDON\non switch1#state=7 do event upordown=%var1% ENDON\non event#upordown=+ do var1 - ENDON\non event#upordown=- do var1 + ENDON\n
Restart Tasmota after creating the rule set. Notice we use Rule which edits Rule1 rule set. They can be used interchangeably."},{"location":"Rules/#watchdog-for-wi-fi-router-or-modem","title":"Watchdog for Wi-Fi router or modem","text":"The ping method requires #define USE_PING and Tasmota version 8.2.0.3 or newer
The WebQuery method requires Tasmota version 10.0.0 or newer
A Tasmota plug can check a remote host (router itself, something else connected to the router, or a site on the Internet) via an ICMP Ping or loading a URL and can power cycle the router or modem if the remote host isn't responding. In this example, an interval of 3 minutes is used. The simplest watchdog rule does not use variables:
Rule1\nON Time#Minute|3 DO backlog Ping4 192.168.1.10 ENDON\nON Ping#192.168.1.10#Success==0 DO Backlog Power1 0; Delay 10; Power1 1; ENDON\nRule1 1\n
However, if the endpoint becomes unreachable for a long time, the watchdog will keep cycling it every three minutes. This could reduce the watchdog's relay lifetime to months, at most years. A safer option would be to use an exponential backoff algorithm. Var1 contains the current interval in minutes, which is tripled after each failed query, but limited to 1439 minutes (1 day).
Rule1\nON system#boot do Var1 3 ENDON\nON Var1#State>1439 DO Var1 1439 ENDON\n\nON Time#Minute|%var1% DO backlog Ping4 192.168.1.10 ENDON\nON Ping#192.168.1.10#Success==0 DO backlog Mult1 3; Power1 0; Delay 10; Power1 1 ENDON\nON Ping#192.168.1.10#Success>0 DO Var1 3 ENDON\n
If your Tasmota doesn't have ping compiled in and your remote host has an HTTP server you can access, you can use WebQuery as below:
Rule1\nON system#boot do Var1 3 ENDON\nON Var1#State>1439 DO Var1 1439 ENDON\n\nON Time#Minute|%var1% DO backlog WebQuery http://192.168.1.10/ GET ENDON\nON WebQuery#Data$!Done DO backlog Mult1 3; Power1 0; Delay 10; Power1 1 ENDON\nON WebQuery#Data=Done DO Var1 3 ENDON\n
Triggering off the JSON response to webquery (and other commands) may require wrapping the command in backlog, as per example above
"},{"location":"Rules/#simple-thermostat-example","title":"Simple Thermostat Example","text":"As example, to be used on a Sonoff TH10 with Sensor Si7021
This example turn on and off an output based on the temperature value and the upper set point and the lower set point. It waits until is enabled by pressing the button or by mqtt message 1 to mem1. This value is remembered. So if power cycle occurs, will resume operation. The set point values can be changed on the fly by mqtt or console commands If the Temperature sensor disconnects, the outputs will shutdown until the sensor is back again and will resume operation. When the device is power up, the thermostat also waits until the sensor value to resume operation.
Initial Config:
- Available physical button as Switch1
- Relay1 will be used the controller
- Rules must be used to control Relay so the pushbutton must only control Switch1 and not directly control the relay - For this we use SwitchMode1 3 as described below and create the necessary rules because the pushbutton control of the relay is only disabled when the rules are in place.
Initial config on console:
SwitchMode1 3 <- Use the switch1 as pushbutton (It will allow us to disable the link between the button and the relay by inserting a rule to dictate what the pushbutton will do - NOTE: Until rules are created the pushbutton will still control the relay!)Rule1 1 <- turn on rulesRule1 4 <- turn off one-shot ruleTelePeriod 60 <- check temp every minuteSetOption26 1 <- use Power1 on mqtt messagesSetOption0 0 <- dont save relay status on eepromPowerOnState 0 <- start all relays offMem1 0 <- thermostat status: 0-off 1-enabled - View or set by MQTT cmnd/mqttTopic/mem1Mem2 25 <- setpoint Temp upper limit - View or set by MQTT cmnd/mqttTopic/mem2Mem3 23 <- setpoint Temp lower limit - View or set by MQTT cmnd/mqttTopic/mem3Var1 0 <- thermostat actual status: 1-OK 0-NOT READY - View by MQTT cmnd/mqttTopic/var1
"},{"location":"Rules/#rules","title":"Rules","text":"On boot start a watchdog timer to check temp sensor connection.
Rule ON system#boot DO RuleTimer1 70 ENDON\n
An available button is configured as switch to set thermostat ON or OFF
Rule1\nON switch1#state DO Backlog event toggling1=%mem1% ENDON\nON event#toggling1=0 DO mem1 1 ENDON\nON event#toggling1=1 DO mem1 0 ENDON\n
Check temp sensor connection. If fails, set to off and turn off thermostat. Also continue checking
Rule ON Rules#Timer=1 DO Backlog var1 0; RuleTimer1 70; Power1 0 ENDON\n
Resets checking timer if temperature is connected
Rule ON tele-SI7021#temperature DO Backlog var1 1; RuleTimer1 30; event ctrl_ready=1; event temp_demand=%value% ENDON\n
Thermostat control - upper limit and lower limit and enabled
Rule1\nON event#ctrl_ready>%mem1% DO var1 0 ENDON\nON event#temp_demand>%mem2% DO Power1 0 ENDON\nON event#temp_demand<%mem3% DO Power1 %var1% ENDON\n
Thermostat can be turned On by:
- pushing button
- by command on local console: mem1 1
- by command on any other console: publish cmnd/mqttTopic/mem1 1
- or MQTT at: cmnd/mqttTopic/mem1 1
Thermostat can be turned Off by:
- pushing button
- by command on local console: mem1 0
- by command on any other console: publish cmnd/mqttTopic/mem1 0
- or MQTT at: cmnd/mqttTopic/mem1 0
To get the status:
mem1 <- thermostat status: 0-off 1-enabled - View or set by MQTT cmnd/mqttTopic/mem1mem2 <- setpoint Temp upper limit - View or set by MQTT cmnd/mqttTopic/mem2mem3 <- setpoint Temp lower limit - View or set by MQTT cmnd/mqttTopic/mem3var1 <- thermostat actual status: 1-OK 0-NOT READY - View by MQTT cmnd/mqttTopic/var1
Everything together:
Initial config:
RuleTimer1 must be greater that TelePeriod for expected results
Backlog SwitchMode1 3; Rule 1; Rule 4; TelePeriod 60; SetOption26 1; SetOption0 0; poweronstate 0; mem1 0; mem2 25; mem3 23; var1 0\n
Rules
Rule1 ON system#boot DO RuleTimer1 70 ENDON ON Switch1#State DO event toggling1=%mem1% ENDON ON event#toggling1=0 DO mem1 1 ENDON ON event#toggling1=1 DO mem1 0 ENDON ON Rules#Timer=1 DO Backlog var1 0; RuleTimer1 70; Power1 0 ENDON ON tele-SI7021#temperature DO Backlog var1 1; RuleTimer1 70; event ctrl_ready=1; event temp_demand=%value% ENDON ON event#ctrl_ready>%mem1% DO var1 0 ENDON ON event#temp_demand>%mem2% DO Power1 0 ENDON ON event#temp_demand<%mem3% DO Power1 %var1% ENDON\n
Example rules without temp sensor to test the thermostat rules
Rule1 ON system#boot DO RuleTimer1 70 ENDON ON Switch1#State DO event toggling1=%mem1% ENDON ON event#toggling1=0 DO mem1 1 ENDON ON event#toggling1=1 DO mem1 0 ENDON ON Rules#Timer=1 DO Backlog var1 0; RuleTimer1 70; Power1 0 ENDON ON event#temp DO Backlog var1 1; RuleTimer1 70; event ctrl_ready=1; event temp_demand=%value% ENDON ON event#ctrl_ready>%mem1% DO var1 0 ENDON ON event#temp_demand>%mem2% DO Power1 0 ENDON ON event#temp_demand<%mem3% DO Power1 %var1% ENDON\n
Tests:
- Push the button1. The thermostat changes to ENABLED (mem1=1)
- on console: event temp=20 (now the system receives like a tele message from temperature sensor) and will turn on the relay1 (to heat)
- on console: event temp=26 (the thermostat turn off the heater)
- on console: event temp=22 (the thermostat turn on the heater)
- wait more than a minute without using the event temp and the thermostat will turn off as there is no temperature value (like a sensor error or disconnection)
- will resume when using again the event temp
- console mem1 0, DISABLED, console mem1 1, ENABLED
Timers:
- With the above the timers can be used to control mem1 and add a schedule to when the thermostat will be enabled
Rule2 ON Clock#Timer=1 DO mem1 1 ENDON ON Clock#Timer=2 DO mem1 0 ENDON
"},{"location":"Rules/#solar-heater-control","title":"Solar heater control","text":"In a swimming pool, a filter pump and a solar panel is installed. When the sun is shining, the pump should push water through the solar panel, to heat the pool. When it's night or cloudy, the pump should be off, to avoid cooling the pool water through the solar panel. The pump is controlled by a Sonoff TH10 with 2x DS18B20 sensors connected.
3 rules:
- Pump should start when solar panel is more than 2 deg warmer than the pool water
- Pump should stop when solar panel is less than 1 deg warmer than the pool water
- Pump should not start if the solar panel is below 25 deg Celsius.
t1: pool temp t2: panel temp var1: in valid panel temp range? var2: off threshold temp for panel var3: on threshold temp for panel mem3: lowest valid panel temp
mem3 25\n
rule1\nON DS18B20-1#temperature DO event t1=%value% ENDON\nON DS18B20-2#temperature DO event t2=%value% ENDON\nON event#t2>%mem3% DO var1 1 ENDON\nON event#t2<=%mem3% DO var1 0 ENDON\nON event#t1 DO Backlog var2 %value%; add2 1 ENDON\nON event#t1 DO Backlog var3 %value%; add3 2 ENDON\nON event#t2>%var3% DO Power1 %var1% ENDON\nON event#t2<%var2% DO Power1 0 ENDON\n
To test the rule without having the sensors in place, simply enter the events for t1 and t2 in the console: Backlog event t1=21;event t2=30
And watch the relay turn on and off based on the values.
Please note that this example does not support manual override or handles missing sensor data.
"},{"location":"Rules/#energy-saving-switch","title":"Energy Saving Switch","text":"Example of a switch controlling a light with a condition of a required amount of lux.
When the switch is on, the light will turn on but only when you have less than 100 lux in that room. While if the switch is off the light will be off.
Rule1\nON switch1#state=1 DO var1 100 ENDON\nON switch1#state=0 DO Backlog var1 0; Power1 off ENDON\nON APDS9960#Ambient<%var1% DO Power1 on ENDON\n
"},{"location":"Rules/#use-of-variables-and-tele-in-domoticz","title":"Use of variables and tele- in Domoticz","text":"Using variables allows for storing sensor results to be used in composing a single HA message like used with Domoticz. To prevent flooding Domoticz with messages we only want to send a message at TelePeriod time. This is achieved by prefixing the <SensorName> with the label tele-. This example will use a variable storing the temperature to be used together with humidity in one Domoticz MQTT message.
- Domoticz configured with a virtual sensor Temp+Hum using Idx 134
Rule
Rule\nON tele-am2301-12#temperature DO var1 %value% ENDON\nON tele-am2301-12#humidity DO publish domoticz/in {\"idx\":134,\"svalue\":\"%var1%;%value%;1\"} ENDON\n
Result - As a result of the tele- prefix the rules will be checked at TelePeriod time for sensor AM2301-12 Temperature and Humidity. The first rule will use the Temperature stored in %value% and save it in %var1% for future use. The second rule will use the Humidity stored in %value% and the Temperature stored in %var1% to compose a single MQTT message suitable for Domoticz.
"},{"location":"Rules/#publish-maximum-value-from-sensor-in-a-time-period","title":"Publish Maximum Value from sensor in a time period","text":"This rule stores the sensor value in var1. When the current value is greater than the previous, var1 is updated. If the current value is smaller, var1 remains unchanged. Then every minute, var1 is published and reset. This results in publication of the maximum/peak value for the last minute. Useful, for example in a decibel meter, when the peak value is important, rather than the value that is occurring by chance at normal telemetry time.
This example uses Analog Range mode (trigger analog#range) which is a scaled output value (the raw analog value would be analog#a0). On ESP32 which supports multiple ADC inputs, the ADC index must be appended such as analog#range1 for ADC#1.
Rule\n ON analog#range>%var1% DO VAR1 %value% ENDON\n ON Time#Minute DO Backlog publish shed/tele/maxdb %var1%; var1 0 ENDON\n\nRule 1 1\n
"},{"location":"Rules/#rf-repeater-ir-repeater","title":"RF Repeater / IR Repeater","text":"In some applications, an RF-Repeater may come in handy to increase the range of RF based devices. We need to use RF receiver and RF transmitter modules with tasmota powered controllers. The following rule looks for data received by the RF receiver and re transmits the same over the transmitter.
Rule1\non RfReceived#data do RfSend {\"Data\":%value%,\"Bits\":24,\"Protocol\":1,\"Pulse\":454} endon\n
Enable it with Rule1 1 A similar concept can also work for IR- Repeater. Connect IR receiver module and IR trnasmitter to Tasmotized device and the following rule retransmits any data over IR
Rule1\non IrReceived#Data do IRsend {\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":%value%} endon\n
Enable it with Rule1 1 The only catch is that the protocol needs to be setup in the rule. Most likely this can be taken care of by using a more complex rule maybe using variables. Would update in future
"},{"location":"SDS011/","title":"SDS011 air quality sensor","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_NOVA_SDS \n#define USE_NOVA_SDS // Add support for SDS011 and SDS021 particle concentration sensor (+1k5 code)\n#define STARTING_OFFSET 30 // Turn on NovaSDS XX-seconds before tele_period is reached \n#endif\n
Nova PM Sensor SDS011 can measure the air quality very accurately by measuring air particles or dust based on laser detection.
Specifications:
- Voltage: 4.7 - 5.3V DC (5V DC with <20mV ripple advised)
- Power consumption: 70mA \u00b110mA (in operation), <4mA (laser and fan sleep mode)
- Measuring range: 0.0-999.9 \u03bcg/m3
- PM2.5 and PM10 output
See manufacturer site for more information.
"},{"location":"SDS011/#configuration","title":"Configuration","text":""},{"location":"SDS011/#wiring","title":"Wiring","text":"SDS011 ESP GND GND 5V 5V TX GPIO RX RX GPIO TX"},{"location":"SDS011/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign: 1. GPIO RX to SDS0X1 Tx (101) 2. GPIO TX to SDS0X1 Rx (70)
To extend the lifetime of the sensor, you can use the command Sensor20 in association with setting TelePeriod for how often you want the fan to run and the sensor to be polled.
"},{"location":"SDS011/#tasmota-main","title":"Tasmota Main","text":"After reboot of the device the displays the SDS011 measurements.
"},{"location":"SDS011/#openhab","title":"OpenHab","text":"Number Dust_Sensor_2_5 \"PM 2.5 [%.2f \u00b5g/m\u00b3]\" <door> (Dust) {mqtt=\"<[mosquitto:tele/dust/SENSOR:state:JSONPATH($.SDS0X1['PM2.5'])]\"}\nNumber Dust_Sensor_10 \"PM 10 [%.2f \u00b5g/m\u00b3]\" <door> (Dust) {mqtt=\"<[mosquitto:tele/dust/SENSOR:state:JSONPATH($.SDS0X1['PM10'])]\"}\n
"},{"location":"SHT30/","title":"SHT30 temperature sensor","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_SHT3X \n#define USE_SHT3X // [I2cDriver15] Enable SHT3x (I2C address 0x44 or 0x45) or SHTC3 (I2C address 0x70) sensor (+0k7 code)\n#endif\n
Wemos SHT30 Shield High Precision Humidity & Temperature (I2C) sensor
From the Wemos SHT30 shield specs the SDA pin on the SHT30 shield is connected to D2 and the SCL pin to D1.
"},{"location":"SHT30/#configuration","title":"Configuration","text":"As a default the SHT30 uses I2C address 0x45 and is user changeable by short-circuiting the two soldering pads at the lower left-side of the sensor (see image below marked green).
Also if no other I2C devices are connected to the Wemos it might be wise to short-circuit the three soldering pads at the upper left-side of the sensor (see image below marked red). This connects the pull-up resistors for I2C and biases the SCL and SDA pins to VCC. This is to avoid possible false detections of other sensors like VEML6070.
Note: On the v2.1.0 board these pads are on the rear.
"},{"location":"SHT30/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- D2 GPIO4 to
I2C SDA - D1 GPIO5 to
I2C SCL
After reboot of the device the temperature, humidity and dew point are displayed.
"},{"location":"SHT30/#breakout-boards","title":"Breakout Boards","text":"Three versions are known to exist, they all share the same pinout. Lolin is the new name for Wemos going forward.
- v.1.0.0 - original design (retired)
- v.2.0.0 - detachable design
- v.2.1.0 - detachable design with TFT I2C connector
"},{"location":"SK6812/","title":"SK6812 RGBW Addressable LEDs","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_WS2812_HARDWARE NEO_HW_SK6812 \n#define USE_WS2812_CTYPE NEO_GRBW // Color type (NEO_RGB, NEO_GRB, NEO_BRG, NEO_RBG, NEO_RGBW, NEO_GRBW)\n
Wiring with a level shifter is required. Look at WS2812B LEDs article for instructions.
"},{"location":"SK6812/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page, select the following:
- GPIOx to
WS2812
"},{"location":"SK6812/#tasmota-main","title":"Tasmota Main","text":"After reboot of the device the color sliders and toggle button are displayed to control the LED.
Set number of pixels used on your strip with Pixels x command
Select whether use white in separate channel or blended with RGB colors.
Configuration was done on a round 7 LED board and an ESP-01S Addressable LED adapter
"},{"location":"SPS30/","title":"SPS30 Particulate sensor","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_SPS30 // [I2cDriver30] Enable Sensiron SPS30 particle sensor (I2C address 0x69) (+1.7 code)\n
"},{"location":"SPS30/#device-information","title":"Device information","text":"The Sensirion SPS30 is a laser based, fan driven, MCERTS-certified particulate matter (PM) sensor with a I\u00b2C and UART interface (datasheet). The Tasmota driver implements the I\u00b2C interface.
"},{"location":"SPS30/#mass-concentration-measurements","title":"Mass Concentration Measurements","text":"The device exposes the following data:
- Volumetric concentration (\u03bcg/m\u00b3):
- PM1.0, PM2.5, PM4 and PM10
- Number concentration (binning, #/cm\u00b3):
- PM0.5, PM1.0, PM2.5, PM4 and PM10
- Typical particle size (\u03bcm)
"},{"location":"SPS30/#sampling","title":"Sampling","text":"The module has a minimum sampling interval of 1 second in continuous mode (default).
"},{"location":"SPS30/#automatic-cleaning","title":"Automatic Cleaning","text":"It implements an automatic fan cleaning routine, which sets the built-in fan speed to maximum for 10 seconds to clear out the detector chamber and accumulated dust on the fan blades. The default cleaning interval is 1 week of interrupted use, and resetting the sensor power also resets the built-in time counter for this. The current implementation does not support disabling this or setting a custom interval.
"},{"location":"SPS30/#configuration","title":"Configuration","text":"The sensor has a 5 pin JST ZHR type connector, with a 1.5mm pitch (connector, datasheet). Pin5 (SEL/Interface Select) must be shorted to Pin4/Ground to enable the I\u00b2C interface.
The sensor and fan components require 5V VDD, so a 5V capable board (e.g. Wemos D1) or external power must be supplied.
Finding appropriate connectors/cables for this module are somewhat cumbersome, SparkFun sells them with handy breadboard friendly breakout cables.
Pin SPS30 ESP Comment 1 VDD + 5V \u00b1 10% 2 SDA GPIOx 5V and 3.3V compatible 3 SCL GPIOy 5V and 3.3V compatible 4 SEL - Pull to GRD to enable I\u00b2C 5 GND -"},{"location":"SPS30/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
After saving the board will reboot and the particulate measurements will be displayed on the main page.
"},{"location":"Safeboot/","title":"Safeboot Partition Layout","text":"This page is specific to ESP32 and variants (not applicable to ESP8266)
This feature was introduced in Tasmota v12
Safeboot partition layout is a new feature in Tasmota v12 that optimizes the use of Flash memory and allows for bigger filesystems and bigger firmware sizes.
"},{"location":"Safeboot/#before-v12","title":"Before v12","text":"Tasmota used a standard partition layout consisting of 2 firmware partitions of equal sizes. One partition is active and is booted from, while the other partition receives the new code when an OTA (Over The Air) update occurs.
This scheme is standard in ESP32 Arduino. Its main advantage is that it is very safe. If a power failure occurs during the OTA update, the device is not bricked and reboots on the untouched version. The main drawback is that it consumes a lot of flash space, enough to contains twice the firmware size.
Example, standard Tasmota layout for 4MB flash:
- a fixed size 64KB system area
- 2x partitions of 1856KB each to receive Tasmota code
- a filesystem of 320KB
"},{"location":"Safeboot/#introducing-safeboot","title":"Introducing Safeboot","text":"We introduced a new variant of Tasmota called \"Safeboot\". It contains a minimal version of Tasmota used only for OTA, and a normal firmware. The main advantage is that it provides 1024KB of additional storage for firmware and/or filesystem.
Example of new partition layout since v12:
- a fixed size 64KB system area
- a Safeboot partition of 832KB
- 1x partition of 2880KB to receive Tasmota code
- a filesystem of 320KB
An alternate partition scheme is used in Sonoff Zigbee Bridge Pro:
- a fixed size 64KB system area
- a Safeboot partition of 832KB
- 1x partition of 1856KB to receive Tasmota code
- a filesystem of 1344KB
Note: the Safeboot firmware is a reduced version of Tasmota containing only what's required for OTA updates (Web UI, MQTT, TLS...). However it does not save settings nor support initial Wi-Fi configuration.
"},{"location":"Scripting-Language/","title":"Scripting","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_SCRIPT\n#define USE_SCRIPT // adds about 17k flash size, variable ram size\n#endif\n#ifdef USE_RULES\n#undef USE_RULES\n#endif \n
Additional features are enabled by adding the following #define compiler directive parameters and then compiling the firmware. These parameters are explained further below in the article.
Feature Description USE_BUTTON_EVENT enable >b section (detect button state changes) USE_SCRIPT_JSON_EXPORT enable >J section (publish JSON payload on TelePeriod) USE_SCRIPT_SUB_COMMAND enables invoking named script subroutines via the Console or MQTT USE_SCRIPT_HUE enable >H section (Alexa Hue emulation) USE_HOMEKIT enable >h section (Siri Homekit support (ESP32 only),define must be given in platform_override see below) USE_SCRIPT_STATUS enable >U section (receive JSON payloads from cmd status) SCRIPT_POWER_SECTION enable >P section (execute on power changes) SUPPORT_MQTT_EVENT enables support for subscribe unsubscribe USE_SENDMAIL enable >m section and support for sending e-mail(on ESP32 you must add USE_ESP32MAIL) USE_SCRIPT_WEB_DISPLAY enable >W section (modify web UI) SCRIPT_FULL_WEBPAGE enable >w section (separate full web page and webserver) USE_TOUCH_BUTTONS enable virtual touch button support with touch displays USE_WEBSEND_RESPONSE enable receiving the response of WebSend and WebQuery commands (received in section >E) SCRIPT_STRIP_COMMENTS enables stripping comments when attempting to paste a script that is too large to fit USE_ANGLE_FUNC add sin(x),acos(x) and sqrt(x) e.g. to allow calculation of horizontal cylinder volume USE_SCRIPT_FATFS_EXT enables additional FS commands USE_WEBCAM enables support ESP32 Webcam which is controlled by scripter cmds USE_FACE_DETECT enables face detecting in ESP32 Webcam USE_SCRIPT_TASK enables multitasking Task in ESP32 USE_LVGL enables support for LVGL USE_SCRIPT_GLOBVARS enables global variables and >G section USE_SML_M enables Smart Meter Interface SML_REPLACE_VARS enables possibility to replace the lines from the (SML) descriptor with Vars NO_USE_SML_SCRIPT_CMD disables SML script cmds USE_SCRIPT_I2C enables I2C support USE_SCRIPT_SERIAL enables support for serial io cmds USE_LVGL enables support for LVGL USE_SCRIPT_TIMER enables up to 4 Arduino timers (so called tickers) SCRIPT_GET_HTTPS_JP enables reading HTTPS JSON WEB Pages (e.g. Tesla Powerwall) LARGE_ARRAYS enables arrays of up to 1000 entries instead of max 127 SCRIPT_LARGE_VNBUFF enables to use 4096 in stead of 256 bytes buffer for variable names USE_GOOGLE_CHARTS enables definition of google charts within web section USE_FEXTRACT enables array extraction from database fxt(...), fxto() and tso(), tsn(), cts(), s2t() functions USE_SCRIPT_SPI enables support for SPI interface USE_DSIPLAY_DUMP enables to show epaper screen as BMP image in >w section TS_FLOAT may be define as double to use double precision numbers (uses double RAM memory and is slower) Scripting Language for Tasmota is an alternative to Tasmota Rules. For ESP32 builds it is recommended to use Berry
To enter a script, go to Consoles -> Edit Script in the Tasmota web UI menu (for version before 9.4, go to Configuration -> Edit script)
To save code space almost no error messages are provided. However it is taken care of that at least it should not crash on syntax errors.
"},{"location":"Scripting-Language/#features","title":"Features","text":" - Up to 50 variables (45 numeric and 5 strings - this may be changed by setting a compilation
#define directive) - Freely definable variable names (all variable names are intentionally case sensitive)
- Nested if,then,else up to a level of 8
- Math operators
+,-,*,/,%,&,|,^,<<,>> - All operators may be used in the
op= form, e.g., += - Comparison operators
==,!=,>,>=,<,<= and , or support - Hexadecimal numbers with prefix
0x are supported - Strings support
+ and += operators - Support for \\n \\r regular expressions on strings
- String comparison
==, != - String size is 19 characters (default). This can be increased or decreased by the optional parameter on the
D section definition
"},{"location":"Scripting-Language/#script-interpreter","title":"Script Interpreter","text":" - Execution is strictly sequential, line by line
- Evaluation is left to right with optional brackets
- All numbers are float, e.g., temp=hum*(100/37.5)+temp-(timer*hum%10)
- No spaces are allowed between math operators
- Comments start with
;
"},{"location":"Scripting-Language/#script-buffer-size","title":"Script buffer size","text":"the script language normally shares script buffer with rules buffer which is 1536 chars. with below options script buffer size may be expanded. PVARS is size for permanent vars.
Feature ESP ESP32 PVARS remarks fallback 1536 1536 50 no longer supported compression (default) 2560 2560 50 actual compression rate may vary #define USE_UFILESYS#define UFSYS_SIZE S S<=8192 S<=16384 1536 ESP must use 4M Flash use linker option -Wl,-Teagle.flash.4m2m.ld or SDCARD ESP32 can use any linker file, size of Filesystem depends on linker file #define EEP_SCRIPT_SIZE S#define USE_EEPROM#define USE_24C256 S<=8192 S<=16384 1536 for hardware eeprom only #define EEP_SCRIPT_SIZE 8192#define USE_EEPROM S=8192 not supported 1536 script may be lost on OTA and serial flash, not on restart most useful definition for larger scripts would be
"},{"location":"Scripting-Language/#esp8266","title":"ESP8266","text":"with 1M flash only default compressed mode should be used (or an SDCARD) a special mode can be enabled for 8192 chars by defining #define USE_EEPROM, #define EEP_SCRIPT_SIZE 8192 however this has some side effects. the script may be deleted on firware OTA or serial update and may have to be reinstalled after update.
with 4M Flash best mode would be #define USE_UFILESYS with linker file \"eagle.flash.4m2m.ld\"
"},{"location":"Scripting-Language/#esp32","title":"ESP32","text":"with all linker files #define USE_UFILESYS
"},{"location":"Scripting-Language/#script-init-error-codes","title":"script init error codes","text":"after initialization the script reports some info in the console e.g: 20:21:28.259 Script: nv=51, tv=13, vns=279, vmem=3305, smem=4096 nv = number of used variables in total (numeric and strings) tv = number of used string variables vns = total size of name strings in bytes (may not exceed 255) or #define SCRIPT_LARGE_VNBUFF extents the size to 4095 vmem = used heap ram by the script (psram if available) smem = used script (text) memory (psram if available)
if the script init fails an error code is reported: -4 = not enough memory -5 = variable name length too long in total -6 = too many arrays defined -7 = not enough memory
number of variables is only limited by RAM. you will probably get a memory error when you define to many variables. you may increase the number of allowed array and the maximum string size defines in user_config_override defaults and override defines: Number of filters (arrays) = 5 (override #define MAXFILT) Max string size = 20 (increase with >D size up to default default 48) (override #define SCRIPT_MAXSSIZE)
"},{"location":"Scripting-Language/#optional-external-editor","title":"Optional external editor","text":"you may use a special external editor with syntax highlighting to edit the scripts. (mac and pc) you may use any number of comments and indents to make it better readable. then with cmd r the script is transferred to the ESP and immediately started. (all comments and indents are removed before transferring) see further info and download here
"},{"location":"Scripting-Language/#console-commands","title":"Console Commands","text":"script <n> : 0 = switch script off; 1 = switch script on script ><cmdline> execute - Can be used to set variables, e.g., script >mintmp=15 - Multiple statements can be specified by separating each with a semicolon, e.g. script >mintmp=15;maxtemp=40
script?<var> queries a script variable var
- The script itself can't be specified because the size would not fit the MQTT buffers
"},{"location":"Scripting-Language/#script-sections","title":"Script Sections","text":"Section descriptors (e.g., >E) are case sensitive a valid script must start with >D in the first line >D ssize ssize = optional max string size (default=19, max=48 unless increased with #define SCRIPT_MAXSSIZE) define and init variables here, must be the first section, no other code allowed p:vname specifies permanent variables. The number of permanent variables is limited by Tasmota rules space (50 bytes) - numeric variables are 4 bytes; string variables are one byte longer than the length of string t:vname specifies countdown timers, if >0 they are decremented in seconds until zero is reached. see example below i:vname specifies auto increment counters if =0 (in seconds) g:vname specifies global variable which is linked to all global variables with the same definition on all devices in the homenet. when a variable is updated in one device it is instantly updated in all other devices. if a section >G exists it is executed when a variable is updated from another device (this is done via UDP-multicast, so not always reliable) I:vname specifies an integer 32 bit variable instead of float. (limited support) integer constants must be preceeded by '#' m:vname specifies a median filter variable with 5 entries (for elimination of outliers) M:vname specifies a moving average filter variable with 8 entries (for smoothing data, should be also used to define arrays) (max 5 filters in total m+M) optional another filter length (1..127) can be given after the definition. Filter vars can be accessed also in indexed mode vname[x] (x = 1..N, x = 0 returns current array index pointer (may be set also), x = -1 returns array length, x = -2 returns array average) Using this filter, vars can be used as arrays, #define LARGE_ARRAYS allows for arrays up to 1000 entries array may also be permanent by specifying an extra :p m:p:vname defines a permanent array. Keep in mind however that in 1M Flash standard configurations you only have 50 bytes permanent storage which stands for a maximum of 12 numbers. (see list above for permanent storage in other configurations) arrays may also be preset in auto increment mode array=X sets the value at index array[0] and increments the index by 1. array = {x y z} sets 3 values in an array from index array[0]
Tip
Keep variable names as short as possible. The length of all variable names taken together may not exceed 256 characters. Memory is dynamically allocated as a result of the D section. Copying a string to a number or reverse is supported
>B executed on BOOT time before sensors are initialized and on save script
>BS executed on BOOT time after sensors are initialized
>E Executed when a Tasmota MQTT RESULT message is received, e.g., on POWER change. Also Zigbee reports to this section.
>F Executed every 100 ms
>S Executed every second
>R Executed on restart. p vars are saved automatically after this call
>T Executed at least at TelePeriod time (SENSOR and STATE) but mostly faster up to every 100 ms, only put tele- vars in this section Remark: JSON variable names (like all others) may not contain math operators like - , you should set SetOption64 1 to replace - (dash) with _ (underscore). Zigbee sensors will not report to this section, use E instead.
>H Alexa Hue interface (up to 32 virtual hue devices) (example) device,type,onVars Remark: hue values have a range from 0-65535. Divide by 182 to assign HSBcolors hue values.
device device name type device type - E = extended color; S = switch onVars assign Hue \"on\" extended color parameters for hue, saturation, brightness, and color temperature (hue,sat,bri,ct) to scripter variables
Example
lamp1,E,on=pwr1,hue=hue1,sat=sat1,bri=bri1,ct=ct1
>h passcode Siri Homekit interface (up to 16 virtual Homekit devices) passcode = 111-11-111 keep this format, numbers 0-9 name,type,opt,var1,var2...
name device name (max 23 characters) type device type (HAP_CID) - 7 = outlet, on/off - 5 = light, on/off,hue,sat,bri - 10 = sensor
opt sensor type - 0 = Temperature,val - 1 = Humidity,val - 2 = Light level,val - 3 = Battery status,level,low battery,charging - 4 = Ambient light level with extended range -10000,+10000 - 5 = Contact Sensor (switch)
var1 ... variable name (max 11 characters) the variables denote scripting variables that need to be set by script the special variables @px x (1..9) directly set, read power states e.g. relays @sx x (1..9) directly read switch state @bx x (1..9) directly read button state
Example
>h 111-11-111 outlet,7,0,@p1 lamp1,5,0,pwr,hue,sat,bri temperature,10,0,tval
a restart is required after modification of descriptor! by faulty parameters the homekit dataset may get corrupted to reset the homekit dataset completely type in console script>hki(89)
compilation:
needs to add in linker to
build_flags -DUSE_HOMEKIT
lib_extra_dirs lib/libesp32_div
>U JSON messages from cmd status arrive here
>C HTML messages arrive here (on web user io event, (if defined USE_HTML_CALLBACK))
>G global variable updated section
>P any power change triggers here (if defined SCRIPT_POWER_SECTION)
>jp https webpage json parse arrives here
>ti1 >ti2 >ti3 >ti4 ticker callback after timer expiration
>b (note lower case) executed on button state change
bt[x] read button state (x = 1.. MAX_KEYS)
Example
>D\ntmp=0\n>b\ntmp=bt[1]\nif tmp==0 \nthen \nprint falling edge of button1 \nendif \nif tmp==1 \nthen \nprint rising edge of button1 \nendif\n
>J The lines in this section are published via MQTT in a JSON payload on TelePeriod. Requires compiling with #define USE_SCRIPT_JSON_EXPORT.
>W The lines in this section are displayed in the web UI main page. Requires compiling with #define USE_SCRIPT_WEB_DISPLAY.
You may put any html code here.
- Variables may be substituted using %var%
- HTML statements are displayed in the sensor section of the main page
- HTML statements preceded with a
@ are displayed at the top of the page - HTML statements preceded with a
$ are displayed in the main section - USER IO elements are displayed at the top of the page
optionally these sections may be used >WS - HTML statements are displayed in the sensor section of the main page
>WM - HTML statements are displayed in the main section of the main page
for next loops are supported to repeat HTML code (precede with % char) %for var from to inc %next
but this method is preferred: script subroutines may be called sub=name of subroutine, like normal subroutines %=#sub in this subroutine a web line may be sent by wcs (see below) thus allowing dynamic HTML pages
=#sub(x) in any position of webline calls subroutine. this allows inserting content
insa(array) in any position insert all elements from an array comma separated
%/file calls a file from the file system and send its content to browser. in this file any cmds may apply.
A web user interface may be generated containing any of the following elements:
remark: state variable names used for IO in the web interface may not contain an underscore. Button: bu(vn txt1 txt2) (up to 4 buttons may be defined in one row) vn = name of variable to hold button state txt1 = text of ON state of button txt2 = text of OFF state of button
Pulldown: pd(vn label (xs) txt1 txt2 ... txtn) vn = name of variable to hold selected state label = label text xs = optional xs (default 200) txt1 = text of 1. entry txt2 = text of 2. entry and so on
Radio button: rb(vn label (xs) txt1 txt2 ... txtn) vn = name of variable to hold selected state label = label text xs = optional xs (default 200) txt1 = text of 1. entry txt2 = text of 2. entry and so on
Checkbox: ck(vn txt (xs)) vn = name of variable to hold checkbox state txt = label text xs = optional xs (default 200)
Slider: sl(min max vn ltxt mtxt rtxt) min = slider minimum value max = slider maximum value vn = name of variable to hold slider value ltxt = label left of slider mtxt = label middle of slider rtxt = label right of slider
Text Input: tx(vn lbl (xs) (type min max)) vn = name of string variable to hold text state lbl = label text xs = optional xs (default 200) type min max = optional strings type = e.g \"datetime-local\" for date+time selector, min, max = date-time min max range
Time Input: tm(vn lbl (xs)) vn = name of number variable to hold time HHMM as number e.g. 1900 means 19:00 lbl = label text xs = optional xs (default 70)
Number Input: nm(min max step vn txt (xs) (prec)) min = number minimum value max = number maximum value step = number step value for up/down arrows vn = name of number variable to hold number txt = label text xs = optional xs (default 200) prec = optional number precision (default 1)
special html options: so(flags) WSO_NOCENTER = 1 force elements not centered WSO_NODIV = 2 force elements not in extra \\<div> WSO_FORCEPLAIN = 4 send line in plain (no table elements) WSO_FORCEMAIN = 8 send lines in main mode ($ mode)
Google Charts: google chart support requires arrays and to make sense also permanent arrays. Therefore on 4M Flash Systems the use of USE_UFILESYS is recommended while on 1 M Flash Systems the special EEPROM mode should be used (see above). other options may also be needed like LARGE_ARRAYS
draws a google chart with up to 4 data sets per chart gc(T (size) array1 ... array4 \"name\" \"label1\" ... \"label4\" \"entrylabels\" \"header\" {\"maxy1\"} {\"maxy2\"}) T = type - b=barchart - c=columnchart - cs=columnchart stacked - C=combochart - p=piechart - l=linechart up to 4 lines with same scaling - l2=linechart with exactly 2 lines and 2 y scales (must be given at end) - lf2 like above but with splined lines - h=histogram - t=data table - g=simple gauges (must give extra 3 vars after header, yellow start, red start, maxval) - T=Timeline (special type arrays contains start,stop pairs in minutes timeofday)
b,l,h type may have the '2' option to specify exactly 2 arrays with 2 y scales given at the end of parameter list.
a very individual chart may be specified by splitting the chart definition and inserting the chart options directly see example below
size = optional size, allows to use only part of an array, must be lower then array size
array = up to 4 arrays of data name = name of chart label = label for up to the 4 datasets in chart entrylabel = labels of each x axis entry separated by '|' char (\"cntN\" starts numbering entries with the number N an optional /X generates numbers divided by X. Produce labels that cycle through the array indexes, starting with the number N. For instance, \"cnt6\" with an array of length 8 will produce the labels 6|7|0|1|2|3|4|5| Using \"cntN/X\" will then divide the numeric value of the label, so \"cnt6/2\" with an array of length 8 will produce the labels 3|3|0|0|1|1|2|2|) (\"wdh: before a week definition generates a week with full hours) header = visible header name of chart the curve displayed in google chart starts at array index (array[0]) so array index must be set also. thus the displayed curve may be shifted to the desired position by adjusting the array index.
additionally you have to define the html frame to put the chart in (both lines must be preceded by a $ char) e.g.
$<div id=\"chart1\"style=\"width:640px;height:480px;margin:0 auto\"></div>\n $gc(c array1 array2 \"wr\" \"pwr1\" \"pwr2\" \"mo|di|mi|do|fr|sa|so\" \"Solar feed\")\n\nyou may define more then one chart. The charts id is chart1 ... chartN
\nvery customized chart definition:\n define a chart like above, but add a t to the definition\n this generates a google table from the arrays e.g.:\n &gc(lt array1 array2 \"wr\" \"pwr1\" \"pwr2\" \"mo|di|mi|do|fr|sa|so\")
\nthen define the options for the graph as from the doku of google e.g.:\n $var options = {\n $vAxes:{0:{maxValue:40,title:'Au\u00dfentemperatur'},1:{maxValue:60,title:'Solarspeicher'}},\n $series:{0:{targetAxisIndex:0},1:{targetAxisIndex:1}},\n $hAxis: {title: 'Wochenverlauf'},\n $};\n then gc(e) closes the definition \n $gc(e)
\n>w ButtonLabel\ngenerates a button with the name \"ButtonLabel\" in Tasmota main menu.\nClicking this button displays a web page with the HTML data of this section.\nall cmds like in >W apply here. these lines are refreshed frequently to show e.g. sensor values.\nlines preceded by $ are static and not refreshed and displayed below lines without $.\nthis option also enables a full webserver interface when USE_UFILESYS is active.\nyou may display files from the flash or SD filesystem by specifying the url: IP/ufs/path .\n(supported files: *.jpg, *.html, *.txt)\n>w1 >w2 >w3 >w4 >w5 >w6 some as above >w\nRequires compiling with #define SCRIPT_FULL_WEBPAGE.
\n>M\nSmart Meter Interface
\nIf a variable does not exist, ??? is displayed for commands
\nIf a Tasmota SENSOR or STATUS or RESULT message is not generated or a Var does not exist the destination variable is NOT updated.
"},{"location":"Scripting-Language/#special-variables","title":"Special Variables","text":"(read only)\nupsecs = seconds since start\nuptime = minutes since start\ntime = minutes since midnight\nsunrise = sunrise minutes since midnight\nsunset = sunset minutes since midnight\ntper = TelePeriod (may be set also)\ncbs = command text buffer size for tasmota cmds (default 256) (may be set also)\ntstamp = timestamp (local date and time)\ntopic = mqtt topic\ngtopic = mqtt group topic\nlip = local ip as string\nluip = udp ip as string (from updating device when USE_SCRIPT_GLOBVARS defined)\nprefixn = prefix n = 1-3\nfrnm = friendly name\ndvnm = device name\npwr[x] = power state (x = 1..N)\nnpwr = number of tasmota power devices \npc[x] = pulse counter value (x = 1..4)\ntbut[x] = touch screen button state (x = 1..N)\nsw[x] = switch state (x = 0..N) (Switch1 = sw[0])\nbt[x] = button state (x = 1..N) only valid in section b (if defined USE_BUTTON_EVENT)\npin[x] = GPIO pin level (x = 0..16)\npn[x] = GPIO for sensor code x. 99 if none\npd[x] = defined sensor for GPIO x. 999 if none\nadc(fac (pin)) = get adc value (on ESP32 can select pin) fac is number of averaged samples (power of 2: 0..7)\nsht[x] = shutter position (x = 1..N) (if defined USE_SHUTTER)\ngtmp = global temperature\nghum = global humidity\ngprs = global pressure\npow(x y) = calculates exponential powers x^y (imprecise version only)\nmed(n x) = calculates a 5 value median filter of x (2 filters possible n=0,1)\nint(x) = gets the integer part of x (like floor)\nfloor(x) = gets the integer part of x\nceil(x) = gets the integer + 1 part of x\nround(x) = round to nearest integer x\ni(x) = convert float x to integer\nf(x) = convert integer x to float\nhn(x) = converts x (0..255) to a hex nibble string\nhni(x) = converts integer x (0..255) to a hex nibble string\nhx(x) = converts x (0..4294967295, 32-bit) to a hex string\nhxi(x) = converts integer x (0..4294967295, 32-bit) to a hex string\nhd(\"hstr\") = converts hex number string to a decimal number\naf(array index) = converts 4 bytes of an array at index index to float number \nas(array) = sort array\nsas(index) = sort string array (is, is1, is2, index = 1,2,3)\nhf(\"hstr\") = converts hex float number string to a decimal number\nhf(\"hstr\" r) = converts hex float number string (reverse byte order) to a decimal number\nst(svar c n) or = st(svar 'c' n)string token - retrieve the nth element of svar delimited by c,\nins(s1 s2) = check if string s2 is contained in string s1, return -1 if not contained or position of contained string\nsl(svar) = gets the length of a string\nasc(svar) = gets the binary value of 1. char of a string\nsb(svar p n) = gets a substring from svar at position p (if p<0 counts from end) and length n\nis(num \"string1|string2|....|stringn|\") = defines a string array optionally preset with immediate strings separated by '|' (this immediate string may be up to 255 chars long) num = 0 read only string array, num > 0 number of elements in read write string array\nis[index] = gets string index from string array, if read-write also write string of index\nis1(..), is2(...) string array see above\nis1[x], is2[x] string array see above\nrr() = returns the reset reason of last restart (as string)\ns2hms(S), converts seconds to HH:MM:SS string\nsin(x) = calculates the sinus(x) (if defined USE_ANGLE_FUNC) \ncos(x) = calculates the cosinus(x) (if defined USE_ANGLE_FUNC)\nacos(x) = calculates the acos(x) (if defined USE_ANGLE_FUNC)\nsqrt(x) = calculates the sqrt(x) (if defined USE_ANGLE_FUNC)\nabs(x) = calculates the absolute value of x\nmpt(x) = measure pulse time, x>=0 defines pin to use, -1 returns low pulse time,-2 return high pulse time (if defined USE_ANGLE_FUNC)\nrnd(x) = return a random number between 0 and x, (seed may be set by rnd(-x))\nsf(F) = sets the CPU Frequency (ESP32) to 80,160,240 Mhz, returns current Freq.\ns(x) = explicit conversion from number x to string may be preceded by precision digits e.g. s(2.2x) = use 2 digits before and after decimal point
\nI2C support #define USE_SCRIPT_I2C\nia(AA), ia2(AA) test and set I2C device with address AA (on BUS 1 or 2), returns 1 if device is present\niw(aa val) , iw1(aa val), iw2(aa val), iw3(aa val)write val to register aa (1..3 bytes), if in aa bit 15 is set no destination register is transfered (needed for some devices), if bit 14 is set byte order is reversed\nir(aa), ir1(aa), ir2(aa), ir3(aa) read 1..3 bytes from register aa
\nOnewire support #define USE_SCRIPT_ONEWIRE\nsupport for onewire either directly or via serial port with onewire bus driver DS2480B\now(SEL <opt PAR>)\n SEL 0 = init bus with pin number N (if bit 15 ist set, select serial DS2480B, lsb = rec pin, msb = trx pin)\n SEL 1 = reset cmd\n SEL 2 = skip cmd\n SEL 3 = write PAR\n SEL 4 = read\n SEL 5 = reset search cmd\n SEL 6 = search cmd addr index PAR\n SEL 7 = select cmd addr index PAR \n SEL 8 = select and set bits index PAR\n SEL 9 = select and read word index PAR bit 7 = 0 start, bit 7 = 1 read result\n SEL 10-18 = get byte (1-8) of adress from index PAR\n SEL 99 = delete bus driver
\nSerial IO support #define USE_SCRIPT_SERIAL\nso(RXPIN TXPIN BR) open serial port with RXPIN, TXPIN and baud rate BR with 8N1 serial mode (-1 for pin means don't use)\nso(RXPIN TXPIN BR MMM) open serial port with RXPIN, TXPIN and baud rate BR and serial mode e.g 7E2 (all 3 modechars must be specified)\nso(RXPIN TXPIN BR MMM BSIZ) open serial port with RXPIN, TXPIN and baud rate BR and serial mode e.g 7E2 (all 3 modechars must be specified) and serial IRW buffer size\nsc() close serial port\nsw(STR) write the string STR to serial port\nswb(NUM) write the number char code NUM to serial port\nsa() returns number of bytes available on port\nsr() read a string from serial port, all available chars up to string size\nsr(X) read a string from serial port until charcode X, all available chars up to string size or until charcode X\nsrb() read a number char code from serial port\nsp() read a number char code from serial port, don't remove it from serial input (peek)\nsra(ARRAY (flags)) fill an array from serial port, if USE_SML_M is enabled and Array size is 8 it is assumed to be a MODBUS request and the checksum is evaluated, if OK 8 is returned, else -2, or if flags is set Modbus response is assumed and checksum is calculated, 0 = standard Modbus, 1 = Rec BMA mode, return -2 on checksum error a
\nsra(ARRAY (flags)) fill an array from serial port, if USE_SML_M is enabled and Array size is 8 it is assumed to be a MODBUS request and the checksum is evaluated, if OK 8 is returned, else -2, or if flags is set Modbus response is assumed and ckum is calculated, 0 = standard Modbus, 1 = Rec BMA mode \nswa(ARRAY len (flags)) send len bytes of an array to serial port, if flags is set Modbus cmd is assumed and cksum is calculated, 0 = standard Modbus, 1 = Rec BMA mode\nsmw(ADDR MODE NUMBER) send a value with checksum to MODBUS Address, MODE 0 = uint16, 1 = uint32, 3 = float
\nSPI IO support #define USE_SCRIPT_SPI\nspi(0 SCLK MOSI MISO) defines a software SPI port with pin numbers used for SCLK, MOSI, MISO.\nspi(0 -1 freq) defines a hardware SPI port with pin numbers defined by Tasmota GPIO definition with bus frequency in Mhz.\nspi(0 -2 freq) defines a hardware SPI port 2 on ESP32 with pin numbers defined by Tasmota GPIO definition.\nspi(1 N GPIO) sets the CS pin with index N (1..4) to pin Nr GPIO.\nspi(2 N ARRAY LEN S) sends and receives an ARRAY with LEN values with S (1..3) (8,16,24 bits) if N==-1 CS is ignored. If S=4, CS is raised after each byte.
\nttget(TNUM SEL) get tasmota timer setting from timer TNUM (1 .. 16)\nSEL:\n 0 = time\n 1 = time window\n 2 = repeat\n 3 = days\n 4 = device\n 5 = power\n 6 = mode\n 7 = arm\nmqtts = MQTT connection status: 0 = disconnected, >0 = connected\nwbut = button status of watch side button (if defined USE_TTGO_WATCH)\nwdclk = double tapped on display (if defined USE_TTGO_WATCH)\nwtch(sel) = gets state from touch panel sel=0 => touched, sel=1 => x position, sel=2 => y position (if defined USE_TTGO_WATCH)\nslp(time) = sleep time in seconds, pos values => light sleep, neg values => deep sleep (if defined USE_TTGO_WATCH)\npl(\"path\") = play mp3 audio from filesystem (if defined USE_I2S_AUDIO or USE_TTGO_WATCH or USE_M5STACK_CORE2)\nsay(\"text\") = plays specified text to speech (if defined USE_I2S_AUDIO or USE_TTGO_WATCH or USE_M5STACK_CORE2) \nc2ps(sel val) = gets, sets values on ESP32 CORE2 sel=0 green led, sel=1 vibration motor, sel=2,3,4 get touch button state 1,2,3 (if defined USE_M5STACK_CORE2)\nrec(path seconds) = rec n seconds wav audio file from i2s microphone to filesystem path (if defined USE_I2S_AUDIO or USE_M5STACK_CORE2)\npwmN(-pin freq) = defines a pwm channel N (1..N) with pin Nr and frequency (pin 0 being -64, N=5 with esp8266 and N=8 with esp32)\npwmN(val) = outputs a pwm signal on channel N (1..N) with val (0-1023)\nwifis = Wi-Fi connection status: 0 = disconnected, >0 = connected
\nwcs = send this line to webpage (WebContentSend)\nwcf = flushes the web buffer (WSContentFlush)\nwfs = send this file to webpage\nrapp = append this line to MQTT (ResponseAppend)\nwm = contains source of web request code e.g. 0 = Sensor display (FUNC_WEB_SENSOR)
\nacp(dst src) = copy array
\nknx(code value) = sends a number value to KNX
\nsml(m 0 bd) = set SML baud rate of Meter m to bd (baud)\nsml(m 1 htxt) = send SML Hex string htxt as binary to Meter m\nsml(-m 1 initstr) = reinits serial port of Meter m, initstr: \"baud:mode\" e.g. \"9600:8E1\", currently only baud and N,E,O are evaluated. \nsml(m 2) = reads serial data received by Meter m into string (if m<0 reads hex values, else asci values)\nsml(m 3 hstr) = inserts SML Hexstring variable hstr as binary to Meter m in Output stream e.g. for special MODBUS cmds, hstr must be a string variable NO string constant \nsml[n] = get value of SML energy register n \nsmls[m] = get value of SML meter string info of meter m, if m < 0 gets string representation of numeric value of decode line m, this enables double number resolution.\nsmlv[n] = get SML decode valid status of line n (1..N), returns 1 if line decoded. n=0 resets all status codes to zero \nsmld(m) = call decoder of meter m\nsmlj = read or write variable, when 0 disables MQTT output of SML.\nenrg[n] = get value of energy register n 0=total, 1..3 voltage of phase 1..3, 4..6 current of phase 1..3, 7..9 power of phase 1..3, 10=start energy, 11=daily energy, 12=energy yesterday (if defined USE_ENERGY_SENSOR)\ngjp(\"host\" \"path\") = trigger HTTPS JSON page read as used by Tesla Powerwall (if defined SCRIPT_GET_HTTPS_JP)\ngwr(\"del\" index) = gets non JSON element from webresponse del = delimiter char or string, index = n\u00b4th element (if defined USE_WEBSEND_RESPONSE)\nhttp(\"url\" \"payload\") = does a GET or POST request on a URL (http:// is internally added)\ntsN(ms) = set up to 4 timers (N=1..4) to millisecond time on expiration triggers section >tiN (if defined USE_SCRIPT_TIMER)\nhours = hours\nmins = mins\nsecs = seconds\nday = day of month\nwday = day of week (Sunday=1,Monday=2;Tuesday=3;Wednesday=4,Thursday=5,Friday=6,Saturday=7)\nmonth = month \nyear = year\nepoch = epoch time (from 2019-1-1 00:00:00)\nepoffs = set epoch offset, (must be no longer then 2 years to fit into single float with second precision)\neres = result of >E section set this var to 1 in section >E to tell Tasmota event is handled (prevents MQTT)
\nThe following variables are cleared after reading true:\nchg[var] = true if a variables value was changed (numeric vars only)\ndiff[var] = difference since last variable update\nupd[var] = true if a variable was updated\nboot = true on BOOT\ntinit = true on time init\ntset = true on time set\nmqttc = true on mqtt connect\nmqttd = true on mqtt disconnect\nwific = true on Wi-Fi connect\nwifid = true on Wi-Fi disconnect
\nSystem variables (for debugging)\nstack = stack size\nheap = free heap size\npheap = PSRAM free heap size (ESP32)\ncore = current core (0 or 1) (ESP32)\nram = used ram size\nslen = script length\nfreq = cpu frequency\nmicros = running microseconds\nmillis = running milliseconds\nloglvl = loglevel of script cmds (may be set also)
\nRemarks:\nIf you define a variable with the same name as a special variable that special variable is discarded
"},{"location":"Scripting-Language/#commands","title":"Commands","text":"=> <command> Execute cmd with MQTT output enabled\n-> <command> Execute cmd with MQTT output disabled, recursion disabled. Do not send MQTT or log messages (i.e., silent execute - useful to reduce traffic)\n+> <command> Execute cmd with MQTT output enabled, recursion enabled. \n
Warning
\nRecursion: If you execute a tasmota cmd in an >E section and this cmd itself executes >E you will get an infinite loop.\nthis is disabled normally and enabled by the +> in case you know what you are doing
\nVariable Substitution\n- A single percent sign must be given as %%\n- Variable replacement within commands is allowed using %varname%. Optionally, the decimal places precision for numeric values may be specified by placing a digit (%Nvarname%, N = 0..9) in front of the substitution variable (e.g., Humidity: %3hum%%% will output Humidity: 43.271%)\n- instead of variables arbitrary calculations my be inserted by bracketing %N(formula)%\n- Linefeed, tab and carriage return may be defined by \\n, \\t and \\r
\nSpecial commands:\nprint or =>print prints to the log for debugging\nA Tasmota MQTT RESULT message invokes the script's E section. Add print statements to debug a script.
\nExample
\n>E\nslider=Dimmer\npower=POWER\n\nif upd[slider]>0\nthen\nprint slider updated %slider%\nendif\n\nif upd[power]>0\nthen\nprint power updated %power%\nendif\n
\nbreak exits a section or terminates a for next loop\ndpx sets decimal precision to x (0-9)\ndpx.y sets preceding digits to x and decimal precision to y (0-9)\ndp(x y) sets preceding digits to x and decimal precision to y\nsvars save permanent vars\ndelay(x) pauses x milliseconds (should be as short as possible)\nbeep(f l) (ESP32) beeps with a passive piezo beeper. beep(-f 0) attaches PIN f to the beeper, beep(f l) starts a sound with frequency f (Hz) and len l (ms). f=0 stops the sound.\nspin(x b) set GPIO x (0..16) to value b (0,1). Only bit 0 of b is used - even values set the GPIO to 0 and uneven values set the GPIO to 1\nspinm(x m) set GPIO x (0..16) to mode m (input=0, output=1, input with pullup=2,alternatively b may be: O=out, I=in, P=in with pullup)\nws2812(array dstoffset) copies an array (defined with m:vname) to the WS2812 LED chain. The array length should be defined as long as the number of pixels. Color is coded as 24 bit RGB. optionally the destination offset in the LED chain may be given\n if dstoffset is flagged by 0x1000, 2 values 16 bits each in an array are used for 32 bit RGBW pixels\nhsvrgb(h s v) converts hue (0..360), saturation (0..100) and value (0..100) to RGB color\ndt display text command (if #define USE_DISPLAY)
\nSubroutines and Parameters\n#name names a subroutine. Subroutine is called with =#name\n#name(param) names a subroutine with a parameter.\nEach parameter variable must be declared in the '>D' section.\nA subroutine with multiple parameters is declared as '#name(p1 p2 p3)', i.e. spaces between parameters.\nA subroutine is invoked with =#name(param) or '=#name(p1 p2)\nInvoking a subroutine sets the parameter variable to the corresponding expression of the invocation. This means that parameter variables have script wide scope, i.e. they are not local variables to the subroutine.\nSubroutines end with the next # or > line or break. Subroutine invocations may be nested (each level uses about 600 bytes stack space, so nesting level should not exceed 4).\nParameters can be numbers or strings and on type mismatch are converted.
\nIf #define USE_SCRIPT_SUB_COMMAND is included in your user_config_override.h, a subroutine may be invoked via the Console or MQTT using the subroutine's name. For example, a declared subroutine #SETLED(num) may be invoked by typing SETLED 1 in the Console. The parameter 1 is passed into the num argument. This also works with string parameters. since Tasmota capitalizes all commands you must use upper case labels.
\nIt is possible to \"replace\" internal Tasmota commands. For example, if a #POWER1(num) subroutine is declared, the command POWER1 is processed in the scripter instead of in the main Tasmota code.
\nString parameter should be passed within double quotas: CUSTOMCMD \"Some string here\"
\n=(svar) executes a routine whose name is passed as a string in a variable (dynamic or self modifying code). The string has to start with > or =# for the routine to be executed.
\na subroutine may return a value (number or string):\nreturn var
\na subroutine is called with:\nvar=#sub(x) when returning a value\nor\n=#sub(x) when not returning a value
\nD\nsvar=\"=#subroutine\"\n\nS\n=(svar)\n\n#subroutine\nprint subroutine was executed\n
\nFor loop (loop count must not be less than 1, no direct nesting supported)
\nfor var <from> <to> <inc> \nnext \n
\nSwitch selector (numeric or string)
\nswitch x \ncase a \ncase b \nends \n
\nConditional Statements\nThere are two syntax alternatives. You may NOT mix both formats.
\nif a==b \nand x==y \nor k==i \nthen = do this \nelse = do that \nendif \n
\nor
\nif a==b \nand x==y \nor k==i { \n = do this \n} else { \n = do that \n} \n
\nRemarks:\nThe last closing bracket must be on a separate line\nCalculations are permitted in conditional expressions, e.g.,
\nif var1-var2==var3*var4\n
\nConditional expressions may be enclosed in parentheses. The statement must be on a single line. e.g.,
\nif ((a==b) and ((c==d) or (c==e)) and (s!=\"x\"))\n
\nMapping Function\n
mp(x cond1 result1 cond2 result2 ... cond<n> result<n>) \n
\nIt addresses a standard task with less code and much flexibility: mapping an arbitrary incoming numeric value into the allowed range. The numeric value x (float only - no integer I:) passed as the first parameter is followed by parameter pairs which can be repeated. A parameter pair consists of condition and result. So input value x is compared to the conditions in the order they are provided as subsequent parameters. If the value matches the condition, the associated result is returned as function. Subsequent rules are skipped. If x matches none of the conditions, x is returned unchanged as result.\nConditions consist of one of the comparison operators \"<\", \">\", \"=\" followed by a numeric value/variable. Be noted that 2-char-operators like \">=\" are not allowed.\nResults consist of a numeric value/variable.\nExample 1: y=mp(x <8 0)\n This mapping reads: If x is less than 8 return 0, otherwise return x\n .\nExample 2: y=mp(x >100 100)\n This mapping reads: If x is greater than 100 return 100, otherwise x.\n\nExample 3: y=mp(x <8 0 >100 100)\n This mapping reads: Assigns 0 to y if x is less than 8. Assigns 100 to y if x is greater than 100. \n Assigns x to y for all values of x that do not meet the above criteria (8 to 100).\nThe above code of example 3 does the same as the following code - with just one line of code and 16 characters less:\ny=x\nif x<8 {\ny=0\n}\nif x>100 {\ny=100\n}\n
\nE-mail\n#define USE_SENDMAIL\nEnabling this feature also enables Tasmota TLS as sendmail uses SSL.
\nsendmail [server:port:user:passwd:from:to:subject] msg
\nExample
\nsendmail [smtp.gmail.com:465:user:passwd:<sender@gmail.com>:<rec@gmail.com>:alarm] %string%\n
\nRemark:\nA number of e-mail servers (such as Gmail) require the receiver's e-mail address to be enclosed by angle brackets < ... > as in example above. Most other e-mail servers also accept this format. While ESP8266 sendmail needs brackets, ESP32 sendmail inserts brackets itself so you should not specify brackets here.
\nWarning
\nDon't use your Google account password with GMAIL SMTP server.\nYou must create an Application specific password
\nThe following parameters can be specified during compilation via #define directives in user_config_override.h:\n* EMAIL_SERVER\n* EMAIL_PORT\n* EMAIL_USER\n* EMAIL_PASSWORD\n* EMAIL_FROM
\nTo use any of these values, pass an * as its corresponding argument placeholder.
\nExample
\nsendmail [*:*:*:*:*:<rec@gmail.com>:theSubject] theMessage
\nInstead of passing the msg as a string constant, the body of the e-mail message may also be composed using the script m (note lower case) section. The specified text in this script section must end with a # character. sendmail will use the m section if * is passed as the msg parameter. in this >m section you may also specify email attachments.\n@/filename specifies a file to be attached (if file system is present)\n&arrayname specifies an array attachment (as tab delimited text, no file system needed)\n$N attach a webcam picture from rambuffer number N (usually 1)
\nSee [Scripting Cookbook Example].(#send-e-mail)
\nSubscribe, Unsubscribe\n#define SUPPORT_MQTT_EVENT\nsubscribe and unsubscribe commands are supported. In contrast to rules, no event is generated but the event name specifies a variable defined in D section and this variable is automatically set on transmission of the subscribed item\nwithin a script the subscribe cmd must be send with +> instead of =>\nthe MQTT decoder may be configured for more space in user config overwrite by\n#define MQTT_EVENT_MSIZE xxx (default is 256)\n#define MQTT_EVENT_JSIZE xxx (default is 400)
\nFile System Support #define USE_UFILESYS\noptional for SD_CARD:\n#define USE_SDCARD\n#define SDCARD_CS_PIN X X = GPIO of card chip select \nSD card uses standard hardware SPI GPIO: mosi,miso,sclk\ndepending on used linker file you get a flash file system with the same functionality but very low capacity (e.g. 2 MB)\nA maximum of four files may be open at a time\ne.g., allows for logging sensors to a tab delimited file and then downloading the file (see Sensor Logging example) \nThe script itself is also stored on the file system with a default size of 8192 characters
\nfr=fo(\"fname\" m) open file fname, mode 0=read, 1=write, 2=append (returns file reference (0-3) or -1 for error (alternatively m may be: r=read, w=write, a=append). For files on SD card, filename must be preceded with / e.g. fr=fo(\"/fname.txt\" 0)\nres=fw(\"text\" fr) writes text to (the end of) file fr, returns number of bytes written\nres=fr(svar fr) reads a string into svar, returns bytes read. String is read until delimiter (\\t \\n \\r) or eof\nfc(fr) close file\nff(fr) flush file, writes cached data and updates directory\nfd(\"fname\") delete file fname\nfrn(\"spath\" \"dpath\") rename a file\nflx(fname) create download link for file (x=1 or 2) fname = file name of file to download\nfsm return 1 if filesystem is mounted, (valid SD card found)\nres=fsi(sel) gets file system information, sel=0 returns total media size, sel=1 returns free space both in kB \nfra(array fr) reads array from open file with fr (assumes tab delimited entries)\nfwa(array fr) writes array to open file with fr (writes tab delimited entries)\nfz(fr) returns file size\nfa(fr) returns number of available bytes in open file stream\nfs(fr pos) seek to file position pos\nfwb(byte fr) write byte to file\nfrb(fr) read byte from file\nfrw(fr url) read file from web url
\nOther commands (+?? flash)\n#define USE_FEXTRACT\nfxt(fr ts_from ts_to col_offs accum array1 array2 ... arrayn) read arrays from csv file from timestamp to timestamp with column offset and accumulate values into arrays1 .. N, assumes csv file with timestamp in 1. column and data values in columns 2 to n.\nfxto(... same as above with time optimized access\ncts(tstamp flg) convert timestamp to German locale format back and forth flg=0 to webformat, 1 to German format\ntso(tstamp day flag) add time offset in days to timestamp optional flg = char 0 zo zero time HH:MM:SS\ntsn(tstamp) convert timestamp to seconds\ns2t(seconds) convert seconds to Tasmota timestamp
\nExtended commands (+0,9k flash)\n#define USE_SCRIPT_FATFS_EXT\nfmd(\"fname\") make directory fname\nfrd(\"fname\") remove directory fname\nfx(\"fname\") check if file fname exists\nfe(\"fname\") execute script fname (max 2048 bytes, script must start with the '>' character on the first line)\nlfw(\"fname\" payload limit) logs a string (payload) to a file (fname) with size limit (limit) paylyoad is added to end of file together with a LF character. if file size is exceeded first line of file is removed.
\nESP32 real Multitasking support\n#define USE_SCRIPT_TASK \nenables support for multitasking scripts\nres=ct(num timer core (prio) (stack))\ncreates a task num (1 or 2) with optional priority and stack size\nwhich is executed every timer (ms) time\non core 0 or 1
\nthe sections are named\n>t1 for task 1\n>t2 for task 2
\nExample
\n>D\n>B\n; create task 1 every 1000 ms on core 0\nct(1 1000 0)\n; create task 2 every 3000 ms on core 1\nct(2 3000 1)\n\n>t1\nprint task1 on core %core%\n\n>t2\nprint task2 on core %core%\n
\nminimal LVGL support\n#define USE_LVGL\nto test LVGL a few functions are implemented:\nlvgl(sel ...) general lvgl call\neach object gets a concurrent number 1 ... N with which you can reference the object\nsel = 0 => initialize LVGL with current display\nsel = 1 => clear screen\nsel = 2 xp yp xs ys text => create a button. the button press is reported in section >lvb\nsel = 3 xp yp xs ys => create a slider. the slider move is reported in section >lvs\nsel = 4 xp yp xs ys min max => create a gauge. \nset = 5 objnr value => set gauge value.\nsel = 6 xp yp xs ys text => create a label.\nsel = 7 objnr text => set label text\nsel = 8 create a keyboard, just get a look and feel \nsel = 50 => get obj nr from caller in callback >lvb or >lvs\nsel = 51 => get event nr from caller in callback >lvb or >lvs\nsel = 52 => get slider value from caller in callback >lvs
\nminimal LVGL support\n#define USE_LVGL\nto test LVGL a few functions are implemented:\nlvgl(sel ...) general lvgl call\neach object gets a concurrent number 1 ... N with which you can reference the object\nsel = 0 => initialize LVGL with current display\nsel = 1 => clear screen\nsel = 2 xp yp xs ys text => create a button. the button press is reported in section >lvb\nsel = 3 xp yp xs ys => create a slider. the slider move is reported in section >lvs\nsel = 4 xp yp xs ys min max => create a gauge. \nset = 5 objnr value => set gauge value.\nsel = 6 xp yp xs ys text => create a label.\nsel = 7 objnr text => set label text\nsel = 8 create a keyboard, just get a look and feel
\nsel = 50 => get obj nr from caller in callback >lvb or >lvs\nsel = 51 => get event nr from caller in callback >lvb or >lvs\nsel = 52 => get slider value from caller in callback >lvs
\nESP32 Webcam support #define USE_WEBCAM\nTemplate for AI THINKER CAM :
\nremarks:\n- GPIO0 zero must be disconnected from any wire after programming because this pin drives the cam clock and does not tolerate any capacitive load\n- Only boards with PSRAM should be used. To enable PSRAM board should be se set to esp32cam in common32 of platform_override.ini\nboard = esp32cam\n- To speed up cam processing CPU frequency should be better set to 240Mhz in common32 of platform_override.ini\nboard_build.f_cpu = 240000000L
\nfile system extension:\nfwp(pnum fr) write picture from RAM buffer number pnum to SD card file with file reference fr\nspecific webcam commands:\nres=wc(sel p1 p2) control webcam, sel = function selector p1 ... optional parameters\nres=wc(0 pres) init webcam with picture resolution pres, returns 0 when error, 2 when PSRAM found, else 1\n pres\n* 0 = FRAMESIZE_QQVGA, // 160x120\n* 1 = FRAMESIZE_QQVGA2, // 128x160\n* 2 = FRAMESIZE_QCIF, // 176x144\n* 3 = FRAMESIZE_HQVGA, // 240x176\n* 4 = FRAMESIZE_QVGA, // 320x240\n* 5 = FRAMESIZE_CIF, // 400x296\n* 6 = FRAMESIZE_VGA, // 640x480\n* 7 = FRAMESIZE_SVGA, // 800x600\n* 8 = FRAMESIZE_XGA, // 1024x768\n* 9 = FRAMESIZE_SXGA, // 1280x1024\n* 10 = FRAMESIZE_UXGA, // 1600x1200
\nres=wc(1 bnum) capture picture to rambuffer bnum (1..4), returns framesize of picture or 0 when error\nres=wc(2 sel p1) execute various controls, details below.\nres=wc(3) gets picture width\nres=wc(4) gets picture height\nres=wc(5 p) start stop streaming 0=stop, 1=start\nres=wc(6 p) start stop motion detector, p=0 => stop detector, p=T start detector with picture every T ms, -1 get picture difference, -2 get picture brightness\nres=wc(7 p) start stop face detector, p=0 => stop detector, p=T start detector with picture every T ms, -1 get number of faces found in picture (USE_FACE_DETECT must be defined)
\ncontrol cmds sel =\n* 0 fs = set frame size (see above for constants) \n* 1 se = set special effect
\n\nto read a value without setting pass -1
\n\n- \n
extensions to the email system on ESP32\n#define SEND_EMAIL and #define USE_ESP32MAIL\nenables specific ESP32 mail server\nthis server can handle more mail servers by supporting START_TLS\nremark: mail addresses must not be enclosed with <> because the server inserts them automatically\nthis server also supports email attachments\nin the >m section you may write\n&/file.txt to attach a file from SD card\n$N N=1..4 to attach a picture from picture RAM buffer number N
\n \n- \n
displaying webcam pictures in WEBUI\nyou may display a webcam picture by giving the name /wc.jpg?p=N (1..4) for RAM picturebuffer N\n\"<img src=\"/wc.jpg?p=1\" alt=\"webcam image\" >\"\nyou may also provide the picture size (h and v have to be preset before)\n\"<img src=\"/wc.jpg?p=1\" alt=\"webcam image\" style=\"width:%w%px;height:%h%px;\">\"\nif you precede the line by & char the image is displayed in the main section, else in the sensor tab section
\n \n
\nthe webcam stream can be specified by the following line\nlip is a system variable containing the local device ip \n\"&<br>\"\n\"&<img src=\"http://%lip%:81/stream\" style=\"width:%w%px;height:%h%px\">\"\n\"&<br><center>webcam stream\"
\nremark: the Flash illumination LED is connected to GPIO4
\nExample
\n >D\n res=0\n w=0\n h=0\n mot=0\n bri=0\n\n >B\n ; init cam with QVGA\n res=wc(0 4)\n ; get pixel size\n w=wc(3)\n h=wc(4)\n ; start motion detector, picture every 1000 ms\n mot=wc(6 1000)\n\n >S\n if wific>0\n then\n ; when wifi up, start stream\n res=wc(5 1)\n endif\n\n ; get motion detect diff value\n mot=wc(6 -1)\n ; get picture brightnes\n bri=wc(6 -2)\n\n >W\n <center>motion diff = %mot%<br>\n <center>brightness = %bri%<br>\n ; show stream on WEBUI\n &<br>\n &<img src=\"http://%lip%:81/stream\" style=\"width:%w%px;height:%h%px\">\n &<br><center>webcam stream\n
"},{"location":"Scripting-Language/#scripting-cookbook","title":"Scripting Cookbook","text":"a valid script must start with >D in the first line! \nsome samples still contain comment lines before >D. This is no longer valid!\n
"},{"location":"Scripting-Language/#simple-example-to-start-with","title":"simple example to start with","text":">D\n; in this section you may define and or preset variables, there are numbers or strings.\n; in contrast to rules you may choose any variable name\n; numeric variable\nval1=1.234\n; numeric variable that is preserved after reboot or power down\np:val2=0\n; text variable\ntxt=\"hello world\"\n\n>B\n; this section is executed durig boot or on script restart\nprint we are booting\n\n>S\n; this section is executed every second\nprint one second tick\n; variables may be printed enclosed with % char, thus showing \"hello world 1.234\"\n; very handy for debugging\nprint %txt% %val1%\n\n; check if upcounting seconds give zero result when dividing by 10\n; upsecs is a system defined variable that counts seconds from start\n\n; you may use if then, else, endif\nif upsecs%10==0\nthen\n print every 10 seconds\nendif\n\n; or if {} else {}\nif upsecs%10==0 {\n print every 10 seconds\n}\n\n>R\n; this section is executed on restart\nprint we are restarting\n
"},{"location":"Scripting-Language/#scripting-language-example","title":"Scripting Language Example","text":"**Actually this code is too large**. This is only meant to show some of the possibilities\n\n>D\n; define all vars here\np:mintmp=10 (p:means permanent)\np:maxtmp=30\nt:timer1=30 (t:means countdown timer)\nt:mt=0\ni:count=0 (i:means auto counter)\nhello=\"hello world\"\nstring=\"xxx\"\nurl=\"[_IP_]\";\nhum=0\ntemp=0\nzigbeetemp=0\ntimer=0\ndimmer=0\nsw=0\nrssi=0\nparam=0\n\ncol=\"\"\nocol=\"\"\nchan1=0\nchan2=0\nchan3=0\n\nahum=0\natemp=0\ntcnt=0\nhour=0\nstate=1\nm:med5=0\nM:movav=0\n; define array with 10 entries\nm:array=0 10\n\n>B\nstring=hello+\"how are you?\"\nprint BOOT executed\nprint %hello%\n=>mp3track 1\n\n; list gpio pin definitions\nfor cnt 0 16 1\ntmp=pd[cnt]\nprint %cnt% = %tmp%\nnext\n\n; get gpio pin for relais 1\ntmp=pn[21]\nprint relais 1 is on pin %tmp%\n\n; pulse relais over raw gpio\nspin(tmp 1)\ndelay(100)\nspin(tmp 0)\n\n; raw pin level\nprint level of gpio1 %pin[1]%\n\n; pulse over tasmota cmd\n=>power 1\ndelay(100)\n=power 0\n\n>T\nhum=BME280#Humidity\ntemp=BME280#Temperature\nrssi=Wifi#RSSI\nstring=SleepMode\n\n; add to median filter\nmedian=temp\n; add to moving average filter\nmovav=hum\n\n; show filtered results\nprint %median% %movav%\n\nif chg[rssi]>0\nthen print rssi changed to %rssi%\nendif\n\nif temp>30\nand hum>70\nthen print damn hot!\nendif\n\n=#siren(5)\n\n; loop nesting workaround\n; by using subroutine\n#siren(num)\nfor cnt 1 num 1\n=#stone\nnext\n\n#stone\nfor tone 2000 1000 -20\nbeep(tone 10);\ndelay(12)\nnext\n\n>S\n; every second but not completely reliable time here\n; use upsecs and uptime or best t: for reliable timers\n\n; arrays\narray[1]=4\narray[2]=5\ntmp=array[1]+array[2]\n\n; call subrountines with parameters\n=#sub1(\"hallo\")\n=#sub2(999)\n\n; stop timer after expired\nif timer1==0\nthen timer1=-1\nprint timer1 expired\nendif\n\n; auto counter with restart\nif count=10\nthen print 10 seconds over\ncount=0\nendif\n\nif upsecs%5==0\nthen print %upsecs% (every 5 seconds)\nendif\n\n; not recommended for reliable timers\ntimer+=1\nif timer>=5\nthen print 5 seconds over (may be)\ntimer=0\nendif\n\ndimmer+=1\nif dimmer>100\nthen dimmer=0\nendif\n\n=>dimmer %dimmer%\n=>WebSend %url% dimmer %dimmer%\n\n; show on display\ndp0\ndt [c1l1f1s2p20] dimmer=%dimmer%\n\nprint %upsecs% %uptime% %time% %sunrise% %sunset% %tstamp%\n\nif time>sunset\nor time<sunrise\nthen\n; night time\nif pwr[1]==0\nthen =>power1 1\nendif\nelse\n; day time\nif pwr[1]>0\nthen =>power1 0\nendif\nendif\n\n; clr display on boot\nif boot>0\nthen dt [z]\nendif\n\n; frost warning\nif ((temp<0 or zigbeetemp<0) and mt<=0)\nthen =#sendmail(\"frost alert\")\n; alarm only every 5 minutes\nmt=300\n=mp3track 2\nendif\n\n; var has been updated\nif upd[hello]>0\nthen print %hello%\nendif\n\n; send to Thingspeak every 60 seconds\n; average data in between\nif upsecs%60==0\nthen\nahum>=tcnt\natemp>=tcnt\n=WebSend [_IP_]/update?key=_token_&field1=%atemp%&field2=%ahum%\ntcnt=0\natemp=0\nahum=0\nelse\nahum+=hum\natemp+=temp\ntcnt+=1\nendif\n\nhour=int(time/60)\nif chg[hour]>0\nthen\n; exactly every hour\nprint full hour reached\nendif\n\nif time5 {\nprint more then 5 minutes after midnight\n} else {\nprint less then 5 minutes after midnight\n}\n\n; publish abs hum every teleperiod time\nif mqtts>0\nand upsecs%tper==0\nthen\n; calc abs humidity\ntmp=pow(2.718281828 (17.67*temp)/(temp+243.5))\ntmp=(6.112*tmp*hum*18.01534)/((273.15+temp)*8.31447215)\n; publish median filtered value\n=>Publish tele/%topic%/SENSOR {\"Script\":{\"abshum\":%med(0 tmp)%}}\nendif\n\n;switch case state machine\nswitch state\ncase 1\nprint state=%state% , start\nstate+=1\ncase 2\nprint state=%state%\nstate+=1\ncase 3\nprint state=%state% , reset\nstate=1\nends\n\n; subroutines\n#sub1(string)\nprint sub1: %string%\n#sub2(param)\nprint sub2: %param%\n\n#sendmail(string)\n=>sendmail [smtp.gmail.com:465:user:passwd:<sender@gmail.de:<rec@gmail.de:alarm] %string%\n\n>E\nprint event executed!\n\n; Assign temperature from a Zigbee sensor\nzigbeetemp=ZbReceived#0x2342#Temperature\n; get HSBColor 1. component\ntmp=st(HSBColor , 1)\n\n; check if switch changed state\nsw=sw[1]\nif chg[sw]>0\nthen =>power1 %sw%\nendif\n\nhello=\"event occurred\"\n\n; check for Color change (Color is a string)\ncol=Color\n; color change needs 2 string vars\nif col!=ocol\nthen ocol=col\nprint color changed %col%\nendif\n\n; or check change of color channels\nchan1=Channel[1]\nchan2=Channel[2]\nchan3=Channel[3]\n\nif chg[chan1]>0\nor chg[chan2]>0\nor chg[chan3]>0\nthen = color has changed\nendif\n\n; compose color string for red\ncol=hn(255)+hn(0)+hn(0)\n=color %col%\n\n>R\nprint restarting now\n
"},{"location":"Scripting-Language/#sensor-logging","title":"Sensor Logging","text":"; define all vars here\n; reserve large strings\n>D 48\nhum=0\ntemp=0\nfr=0\nres=0\ncnt=0\n; moving average for 60 seconds\nM:mhum=0 60\nM:mtemp=0 60\nstr=\"\"\n\n>B\n; set sensor file download link\n;fl1(\"slog.txt\")\n; delete file in case we want to start fresh\n;fd(\"slog.txt\")\n\n; list all files in root directory\nfr=fo(\"/\" 0)\nfor cnt 1 20 1\nres=fr(str fr)\nif res>0\nthen\nprint %cnt% : %str%\nelse\nbreak\nendif\nnext\nfc(fr)\n\n>T\n; get sensor values\ntemp=BME280#Temperature\nhum=BME280#Humidity\n\n>S\n; average sensor values every second\nmhum=hum\nmtemp=temp\n\n; write average to sensor log every minute\nif upsecs%60==0\nthen\n; open file for write\nfr=fo(\"slog.txt\" 1)\n; compose string for tab delimited file entry\nstr=s(upsecs)+\"\\t\"+s(mhum)+\"\\t\"+s(mtemp)+\"\\n\"\n; write string to log file\nres=fw(str fr)\n; close file\nfc(fr)\nendif\n\n>R\n
"},{"location":"Scripting-Language/#global-variables-example","title":"global variables example","text":"make temperature and humidity of an SHT sensor public\nall devices in the local network may use the global variables\nneeds #define USE_SCRIPT_GLOBVARS
\nSender:
\n>D\ng:temp=0\ng:hum=0\n\n>T\ntemp=SHT3X_0x44#Temperature\nhum=SHT3X_0x44#Humidity\n
\nReceiver(s) displays the value on a display
\n>D\ng:temp=0\ng:hum=0\n\n>S\ndt [l1c1p10]temp=%temp% C\ndt [l2c1p10]hum=%hum% %%\n
"},{"location":"Scripting-Language/#e-paper-29-display-with-sgp30-and-bme280","title":"e-Paper 29 Display with SGP30 and BME280","text":"Some variables are set from ioBroker
\n>D\nhum=0\ntemp=0\npress=0\nahum=0\ntvoc=0\neco2=0\nzwz=0\nwr1=0\nwr2=0\nwr3=0\notmp=0\npwl=0\ntmp=0\n; preset units in case they are not available\npunit=\"hPa\"\ntunit=\"C\"\n\n>B\n;reset auto draw\ndt [zD0]\n;clr display and draw a frame\ndt [x0y20h296x0y40h296]\n\n>T\n; get telemetry sensor values\ntemp=BME280#Temperature\nhum=BME280#Humidity\npress=BME280#Pressure\ntvoc=SGP30#TVOC\neco2=SGP30#eCO2\nahum=SGP30#aHumidity\ntunit=TempUnit\npunit=PressureUnit\n\n>S\n; update display every [`TelePeriod`](Commands.md#teleperiod)\nif upsecs%tper==0\nthen\ndp2\ndt [f1p7x0y5]%temp% %tunit%\ndt [p5x70y5]%hum% %%[x250y5t]\ndt [p11x140y5]%press% %punit%\ndt [p10x30y25]TVOC: %tvoc% ppb\ndt [p10x160y25]eCO2: %eco2% ppm\ndt [p10c26l5]ahum: %ahum% g^m3\n\ndp0\ndt [p25c1l5]WR 1 (Dach) : %wr1% W\ndt [p25c1l6]WR 2 (Garage): %-wr3% W\ndt [p25c1l7]WR 3 (Garten): %-wr2% W\ndt [p25c1l8]Aussentemperatur: %otmp% C\ndt [x170y95r120:30f2p6x185y100] %pwl% %%\n; now update screen\ndt [d]\nendif\n\n>E\n\n>R\n
"},{"location":"Scripting-Language/#e-paper-42-display-with-sht31-and-bme280","title":"e-Paper 42 Display with SHT31 and BME280","text":"This script shows 2 graphs on a 4.2 inch e-Paper display: 1. some local sensors, and 2. power statistics
\n\n- The first graph is the battery level of a solar battery (Tesla PowerWall 2)
\n- The second graph shows the solar yield of the roof panels in Watts
\n- Another special feature is that this script displays daily and weekly averages (via moving average) of all power IO of the house.
\n- it sends an email every Sunday night with the weekly data
\n- it displays a google bar chart on the webui with values for each weekday of the last week
\n- ESP32 CPU with SD card
\n- Since the display is a full update panel it is updated only once a minute
\n- Some values (like power meters) are set remotely from ioBroker
\n
\n>D\nhum=0\ntemp=0\npress=0\nzwz=0\nwr1=0\nwr2=0\nwr3=0\notmp=0\npwl=0\nez1=0\nsez1=0\nM:mez1=0 7\nezh=0\nsezh=0\nM:mezh=0 7\nvzh=0\nsvzh=0\nM:mvzh=0 7\nwd=0\nres=0 \nhr=0\nt1=0\nres=0\n\n>B\n->setoption64 1\ntper=30\n\ndt [IzD0]\ndt [zG10352:5:40:-350:80:10080:0:100f3x360y40]100 %%[x360y115]0 %%\ndt [f1x100y25]Powerwall - 7 Tage[f1x360y75] 0 %%\ndt [G10353:5:140:-350:80:10080:0:5000f3x360y140]+5000 W[x360y215]0 W\ndt [f1x70y125]Volleinspeisung - 7 Tage[f1x360y180] 0 W\ndt [p13x10y230]WR 1,2,3:\ndt [p13x10y245]H-Einsp.:\ndt [p13x10y260]H-Verbr.:\ndt [p13x10y275]D-Einsp.:\ndt [d]\n\ndt [Gr0:/g0_sav.txt:]\ndt [Gr1:/g1_sav.txt:]\n\nbeep(-25 0)\nbeep(1000 100)\n\n>T\npress=BMP280#Pressure\ntemp=SHT3X_0x44#Temperature\nhum=SHT3X_0x44#Humidity\n\n>S\n\nif upsecs%60==0\nthen\ndp2\ndt [f1p7x0y5]%temp% C\ndt [x0y20h400x250y5T][x350t][f1p10x70y5]%hum% %%\ndt [p10x140y5]%press% hPa\ndp0\ndt [p5x360y75]%pwl% %%\ndt [p6x360y180]%wr1%W\ndt [g0:%pwl%g1:%wr1%]\n\ndt [p24x75y230] %wr1% W : %-wr2% W : %-wr3% W\ndt [p-10x75y245]%ezh% kWh\ndt [p-10x75y260]%vzh% kWh\ndt [p-10x75y275]%ez1% kWh\n\nt1=mezh*7\ndt [p-10x150y245]: %t1% kWh\nt1=mvzh*7\ndt [p-10x150y260]: %t1% kWh\nt1=mez1*7\ndt [p-10x150y275]: %t1% kWh\n\ndp1\nt1=ezh-sezh\ndt [p12x250y245]: %t1% kWh\nt1=vzh-svzh\ndt [p12x250y260]: %t1% kWh\nt1=ez1-sez1\ndt [p12x250y275]: %t1% kWh\n\ndp0\ndt [f2p5x320y250] %otmp%C\n\ndt [d]\nprint updating display\nendif\n\nhr=hours\nif chg[hr]>0\nand hr==0\nthen\nmez1=ez1-sez1\nsez1=ez1\nmezh=ezh-sezh\nsezh=ezh\nmvzh=vzh-svzh\nsvzh=vzh\nendif\n\nif sezh==0\nthen\nsez1=ez1\nsezh=ezh\nsvzh=vzh\nendif\n\nwd=wday\nif chg[wd]>0\nand wd==1\nthen\n=>sendmail [*:*:*:*:*:user.tasmota@gmail.com: Wochenbericht]*\nprint sending email\nendif\n\n\nif upsecs%300==0\nthen\n=#savgraf\nprint saving graph\nendif\n\n#savgraf\ndt [Gs0:/g0_sav.txt:]\ndt [Gs1:/g1_sav.txt:]\n\n>m\nWochenbericht Einspeisung und Verbrauch<br><br>\nw1=%mez1[1]%,%mez1[2]%,%mez1[3]%,%mez1[4]%,%mez1[5]%,%mez1[6]%,%mez1[7]%,%mez1[8]%<br>\nw2=%mezh[1]%,%mezh[2]%,%mezh[3]%,%mezh[4]%,%mezh[5]%,%mezh[6]%,%mezh[7]%,%mezh[8]%<br>\nw3=%mvzh[1]%,%mvzh[2]%,%mvzh[3]%,%mvzh[4]%,%mvzh[5]%,%mvzh[6]%,%mvzh[7]%,%mvzh[8]%<br>\n#\n>W\n&<br><div id=\"container\"style=\"width:640px;height:480px;margin:0 auto\"></div><br>\n&<script type=\"text/javascript\" src=\"https://www.gstatic.com/charts/loader.js\"></script>\n&<script type=\"text/javascript\">google.charts.load('current',{packages:['corechart']});</script>\n&<script language=\"JavaScript\">function drawChart(){var data=\n&google.visualization.arrayToDataTable([\n&['weekday','Power'],['Mo',%mvzh[1]%],['Di',%mvzh[2]%],['Mi',%mvzh[3]%],['Do',%mvzh[4]%],\n&['Fr',%mvzh[5]%],['Sa',%mvzh[6]%],['So',%mvzh[7]%]]);\n&var options={title:'daily solar feed',isStacked:true};\n&var chart=new \n&google.visualization.ColumnChart(document.getElementById('container'));chart.draw(data,options);}\n&google.charts.setOnLoadCallback(drawChart);</script>\n#\n
"},{"location":"Scripting-Language/#ili-9488-color-lcd-display-with-bmp280-and-vl5310x","title":"ILI 9488 Color LCD Display with BMP280 and VL5310X","text":"Shows various BMP280 energy graphs\nTurn display on and off using VL5310X proximity sensor to prevent burn-in
\nSome variables are set from ioBroker
\n>D\ntemp=0\npress=0\nzwz=0\nwr1=0\nwr2=0\nwr3=0\notmp=0\npwl=0\ntmp=0\ndist=0\npunit=\"hPa\"\ntunit=\"C\"\nhour=0\n\n>B\ndt [z]\n\n// define 2 graphs, 2. has 3 tracks\ndt [zCi1G2656:5:20:400:80:1440:-5000:5000:3Ci7f3x410y20]+5000 W[x410y95]-5000 W [Ci7f1x70y3] Zweirichtungsz~80hler - 24 Stunden\ndt [Ci1G2657:5:120:400:80:1440:0:5000:3Ci7f3x410y120]+5000 W[x410y195]0 W [Ci7f1x70y103] Wechselrichter 1-3 - 24 Stunden\ndt [Ci1G2658:5:120:400:80:1440:0:5000:16][Ci1G2659:5:120:400:80:1440:0:5000:5]\ndt [f1s1b0:260:260:100​:50:2:11:4:2:Rel 1:b1:370:260:100​:50:2:11:4:2:Dsp off:]\n=>mp3volume 100\n=>mp3track 4\n\n>T\n; get some telemetry values\ntemp=BMP280#Temperature\npress=BMP280#Pressure\ntunit=TempUnit\npunit=PressureUnit\ndist=VL53L0X#Distance\n\n; check proximity sensor to turn display on and off to prevent burn-in\nif dist>300\nthen\nif pwr[2]>0\nthen\n=>power2 0\nendif\nelse\nif pwr[2]==0\nthen\n=>power2 1\nendif\nendif\n\n>S\n; update graph every teleperiod\nif upsecs%tper==0\nthen\ndp2\ndt [f1Ci3x40y260w30Ci1]\ndt [Ci7x120y220t]\ndt [Ci7x180y220T]\ndt [Ci7p8x120y240]%temp% %tunit%\ndt [Ci7x120y260]%press% %punit%\ndt [Ci7x120y280]%dist% mm\ndp0\ndt [g0:%zwz%g1:%wr1%g2:%-wr2%g3:%-wr3%]\nif zwz0\nthen\ndt [p-8x410y55Ci2Bi0]%zwz% W\nelse\ndt [p-8x410y55Ci3Bi0]%zwz% W\nendif\ndt [p-8x410y140Ci3Bi0]%wr1% W\ndt [p-8x410y155Ci16Bi0]%-wr2% W\ndt [p-8x410y170Ci5Bi0]%-wr3% W\nendif\n\n; chime every full hour\nhour=int(time/60)\nif chg[hour]>0\nthen ->mp3track 4\nendif\n\n>E\n\n>R\n
"},{"location":"Scripting-Language/#led-bar-display-with-ws2812-led-chain","title":"LED Bar Display with WS2812 LED Chain","text":"Used to display home's solar power input/output (+-5000 Watts)
\n>D\nm:array=0 60 ;defines array for 60 led pixels\ncnt=0\nval=0\nind=0\n; rgb values for grid\ncolr1=0x050000\ncolr2=0x050100\ncolg1=0x000300\ncolg2=0x020300\nledbar=0\nblue=64\npixels=60\nsteps=10\ndiv=0\ntog=0\nmax=5000\nmin=-5000\npos=0\n\n>B\ndiv=pixels/steps\n=#prep\nws2812(array)\n\n; ledbar is set from broker\n\n>S\nif ledbar<min\nthen ledbar=min\nendif\n\nif ledbar>max\nthen ledbar=max\nendif\n\npos=(ledbar/max)*(pixels/2)\nif ledbar>0\nthen\npos+=(pixels/2)\nif pospixels-1\nthen pos=pixels\nendif\nelse\npos+=(pixels/2)+1\nif pospixels-1\nthen pos=1\nendif\nendif\n\nif pos<1\nor pos>pixels\nthen pos=1\nendif\n\n=#prep\nif ledbar==0\nthen\narray[pos]=blue\narray[pos-1]=blue\nelse\narray[pos]=blue\nendif\n\n; only used if power is off\n; so lets may be used normally if on\nif pwr[1]==0\nthen\nws2812(array)\nendif\n\n; subroutine for grid\n#prep\nfor cnt 1 pixels 1\nind+=1\nif ind>div\nthen ind=1\ntog^=1\nendif\n\nif cnt<=pixels/2\nthen\nif tog>0\nthen val=colr1\nelse val=colr2\nendif\nelse\nif tog>0\nthen val=colg1\nelse val=colg2\nendif\nendif\narray[cnt]=val\nnext\n\n>R\n
"},{"location":"Scripting-Language/#multiple-ir-receiver-synchronization","title":"Multiple IR Receiver Synchronization","text":"Shows how a Magic Home with IR receiver works\nSynchronizes 2 Magic Home devices by also sending the commands to a second Magic Home via WebSend
\nScript example using if then else\n ; expand default string length to be able to hold WebSend [xxx.xxx.xxx.xxx]
\n>D 25\nistr=\"\"\nws=\"WebSend [_IP_]\"\n\n; event section\n>E\n; get ir data\nistr=IrReceived#Data\n\n; on\nif istr==\"0x00F7C03F\"\nthen\n->wakeup\n->%ws% wakeup\nendif\n\n; off\nif istr==\"0x00F740BF\"\nthen\n->power1 0\n->%ws% power1 0\nendif\n\n;white\nif istr==\"0x00F7E01F\"\nthen\n->color 000000ff\n->%ws% color 000000ff\nendif\n\n;red\nif istr==\"0x00F720DF\"\nthen\n->color ff000000\n->%ws% color ff000000\nendif\n\n;green\nif istr==\"0x00F7A05F\"\nthen\n->color 00ff0000\n->%ws% color 00ff0000\nendif\n\n;blue\nif istr==\"0x00F7609F\"\nthen\n->color 0000ff00\n->%ws% color 0000ff00\nendif\n\n; dimmer up\nif istr==\"0x00F700FF\"\nthen\n->dimmer +\n->%ws% dimmer +\nendif\n\n;dimmer down \nif istr==\"0x00F7807F\" \nthen \n->dimmer - \n->%ws% dimmer - \nendif\n\nistr=\"\"\n
\nScript example using switch case ends\n ; expand default string length to be able to hold WebSend [xxx.xxx.xxx.xxx]
\n>D 25\nistr=\"\"\nws=\"WebSend [_IP_]\"\n\n; event section\n>E\n; get ir data\nistr=IrReceived#Data\n\nswitch istr\n; on\ncase \"0x00F7C03F\"\n->wakeup\n->%ws% wakeup\n\n;off\ncase \"0x00F740BF\"\n->power1 0\n->%ws% power1 0\n\n;white\ncase \"0x00F7E01F\"\n->color 000000ff\n->%ws% color 000000ff\n\n;red\ncase \"0x00F720DF\"\n->color ff000000\n->%ws% color ff000000\n\n;green\ncase \"0x00F7A05F\"\n->color 00ff0000\n->%ws% color 00ff0000\n\n;blue\ncase \"0x00F7609F\"\n->color 0000ff00\n->%ws% color 0000ff00\n\n; dimmer up\ncase \"0x00F700FF\"\n->dimmer +\n->%ws% dimmer +\n\n; dimmer down\ncase \"0x00F7807F\"\n->dimmer -\n->%ws% dimmer -\nends\n\nistr=\"\"\n
"},{"location":"Scripting-Language/#fast-polling","title":"Fast Polling","text":"; expand default string length to be able to hold `WebSend [xxx.xxx.xxx.xxx]` \n>D 25\nsw=0\nws=\"WebSend [_IP_]\"\ntimer=0\nhold=0\ntoggle=0\n\n>B\n; gpio 5 button input\nspinm(5,0)\n\n; fast section 100ms\n>F\nsw=pin[5]\n; 100 ms timer\ntimer+=1\n\n; 3 seconds long press\n; below 0,5 short press\nif sw==0\nand timer5\nand timer<30\nthen\n; short press\n;print short press\ntoggle^=1\n=>%ws% power1 %toggle%\nendif\n\nif sw>0\nthen\n;pressed\nif timer>30\nthen\n; hold\nhold=1\n;print hold=%timer%\nif toggle>0\nthen\n=>%ws% dimmer +\nelse\n=>%ws% dimmer -\nendif\nendif\nelse\ntimer=0\nhold=0\nendif\n
"},{"location":"Scripting-Language/#web-ui","title":"Web UI","text":"An example to show how to implement a web UI. This example controls a light via WebSend
\n>D\ndimmer=0\nsw=0\ncolor=\"\"\ncol1=\"\"\nred=0\ngreen=0\nblue=0\nww=0\n\n>F\ncolor=hn(red)+hn(green)+hn(blue)+hn(ww)\nif color!=col1\nthen\ncol1=color\n=>websend [192.168.178.75] color %color%\nendif\n\nif chg[dimmer]>0\nthen \n=>websend [192.168.178.75] dimmer %dimmer%\nendif\n\nif chg[sw]>0\nthen\n=>websend [192.168.178.75] power1 %sw%\nendif\n\n>W\nbu(sw \"Light on\" \"Light off\")\nck(sw \"Light on/off \u00a0\u00a0\")\nsl(0 100 dimmer \"0\" \"Dimmer\" \"100\")\nsl(0 255 red \"0\" \"red\" \"255\")\nsl(0 255 green \"0\" \"green\" \"255\")\nsl(0 255 blue \"0\" \"blue\" \"255\")\nsl(0 255 ww \"0\" \"warm white\" \"255\")\ntx(color \"color: \u00a0\u00a0\")\n
"},{"location":"Scripting-Language/#hue-emulation","title":"Hue Emulation","text":"An example to show how to respond to Alexa requests via Hue Emulation
\nWhen Alexa sends on/off, dimmer, and color (via hsb), send commands to a MagicHome device
\n>D\npwr1=0\nhue1=0\nsat1=0\nbri1=0\ntmp=0\n\n>E\nif upd[hue1]>0\nor upd[sat1]>0\nor upd[bri1]>0\nthen\ntmp=hue1/182\n->websend [192.168.178.84] hsbcolor %tmp%,%sat1%,%bri1%\nendif\n\nif upd[pwr1]>0\nthen\n->websend [192.168.178.84] power1 %pwr1%\nendif\n\n>H\n; on,hue,sat,bri,ct\nlivingroom,E,on=pwr1,hue=hue1,sat=sat1,bri=bri1\n
"},{"location":"Scripting-Language/#alexa-controlled-mcp230xx-i2c-gpio-expander","title":"Alexa Controlled MCP230xx I2C GPIO Expander","text":"Uses Tasmota's Hue Emulation capabilities for Alexa interface
\n; define vars\n>D\np:p1=0\np:p2=0\np:p3=0\np:p4=0\n\n; init ports\n>B\n->sensor29 0,5,0\n->sensor29 1,5,0\n->sensor29 2,5,0\n->sensor29 3,5,0\n->sensor29 0,%0p1%\n->sensor29 1,%0p2%\n->sensor29 2,%0p3%\n->sensor29 3,%0p4%\n\n; define Alexa virtual devices\n>H\nport1,S,on=p1\nport2,S,on=p2\nport3,S,on=p3\nport4,S,on=p4\n\n; handle events\n>E\nprint EVENT\n\nif upd[p1]>0\nthen\n->sensor29 0,%0p1%\nendif\nif upd[p2]>0\nthen\n->sensor29 1,%0p2%\nendif\nif upd[p3]>0\nthen\n->sensor29 2,%0p3%\nendif\nif upd[p4]>0\nthen\n->sensor29 3,%0p4%\nendif\n\n=#pub\n\n; publish routine\n#pub\n=>publish stat/%topic%/RESULT {\"MCP23XX\":{\"p1\":%0p1%,\"p2\":%0p2%,\"p3\":%0p3%,\"p4\":%0p4%}}\nsvars\n\n; web interface\n>W\nbu(p1 \"p1 on\" \"p1 off\")bu(p2 \"p2 on\" \"p2 off\")bu(p3 \"p3 on\" \"p3 off\")bu(p4 \"p4 on\" \"p4 off\")\n
"},{"location":"Scripting-Language/#retrieve-network-gateway-ip-address","title":"Retrieve network gateway IP Address","text":">D\ngw=\"\"\n\n; Request Status information. The response will trigger the `U` section\n>B\n+>status 5\n\n; Read the status JSON payload\n>U\ngw=StatusNET#Gateway\nprint %gw%\n
"},{"location":"Scripting-Language/#send-e-mail","title":"Send e-mail","text":">D 25\nday1=0\net=0\nto=\"<mrx@gmail.com>\"\n\n>T\net=ENERGY#Total\n\n>S\n; send at midnight\nday1=day\nif chg[day1]>0\nthen\n=>sendmail [*:*:*:*:*:%to%:energy report]*\nendif\n\n>m\nemail report at %tstamp%\nyour power consumption today was %et% KWh\n#\n
"},{"location":"Scripting-Language/#send-power-reading-with-formatted-time-stamp-via-websend","title":"Send power reading with formatted time stamp via websend","text":"Some web APIs require certain formats (e.g. date & time) to be provided. This example illustrates how to reformat the timestamp and embed it in the get payload.\nOn ESP8266 based devices this is limited to unsecured http (no \"s\") connections! Don't use this for sensitive data!
\n>D 42\n;long string required for key\ny=0\nm=0\nd=0\nkey=\"yourkey\"\nid=\"yourSystemID\"\nws=\"WebSend [pvoutput.org]\"\net=0\np=0\n\n>T\net=ENERGY#Total\np=ENERGY#Power\n; every 5 minutes\nif upsecs%300==0\nthen\ny=sb(tstamp 0 4)\nm=sb(tstamp 5 2)\nd=sb(tstamp 8 2)\n=>%ws%/service/r2/addstatus.jsp?key=%key%&sid=%id%&d=%1.0(y)%%2.0(m)%%2.0(d)%&t=%1(sb(tstamp 11 5))%&v2=%s(2.0p)%\nendif\n
"},{"location":"Scripting-Language/#switching-and-dimming-by-recognizing-mains-power-frequency","title":"Switching and Dimming By Recognizing Mains Power Frequency","text":"Switching in Tasmota is usually done by High/Low (+3.3V/GND) changes on a GPIO. However, for devices like the Moes QS-WiFi-D01 Dimmer, this is achieved by a pulse frequency when connected to the GPIO, and these pulses are captured by Counter1 in Tasmota.
\n\n\n- When the light is OFF and there is a short period of pulses - then turn the light ON at the previous dimmer level.
\n- When the light is ON and there is a short period of pulses - then turn the light OFF.
\n- When there is a longer period of pulses (i.e., HOLD) - toggle dimming direction and then adjust the brightness level as long as the button is pressed or until the limits are reached.
\n
\nIssue 6085
\nIn the Data Section D at the beginning of the Script the following initialization variables may be changed:
\ndim multiplier = 0..2.55 set the dimming increment value\ndim lower limit = range for the dimmer value for push-button operation (set according to your bulb); min 0\ndim upper limit = range for the dimmer value for push-button operation (set according to your bulb); max 100\nstart dim level = initial dimmer level after power-up or restart; max 100
\n>D\nsw=0\ntmp=0\ncnt=0\ntmr=0\nhold=0\npowert=0\nslider=0\ndim=\"\"\nshortprl=2 ;short press lo limit\nshortpru=10;short press up limit\ndimdir=0 ;dim direction 0/1\ndimstp=2 ;dim step/speed 1 to 5\ndimmlp=2.2 ;dim multiplier\ndimll=15 ;dim lower limit\ndimul=95 ;dim upper limit\ndimval=70 ;start dim level\n\n>B\nprint \"WiFi-Dimmer-Script-v0.2\"\n=>Counter1 0\n=>Baudrate 9600\n; boot sequence\n=#senddim(dimval)\ndelay(1000)\n=#senddim(0)\n\n>F\ncnt=pc[1]\nif chg[cnt]>0\n; sw pressed\nthen sw=1\nelse sw=0\n; sw not pressed\nendif\n\n; 100ms timer\ntmr+=1\n\n; short press\nif sw==0\nand tmr>shortprl\nand tmr<shortpru\nthen\npowert^=1\n\n; change light on/off\nif powert==1\nthen\n=#senddim(dimval)\nelse\n=#senddim(0)\nendif\nendif\n\n\n; long press\nif sw>0\nthen\nif hold==0\nthen\n\n; change dim direction\ndimdir^=1\nendif\nif tmr>shortpru\nthen\nhold=1\nif powert>0\n; dim when on & hold\nthen\nif dimdir>0\nthen\n\n; increase dim level\ndimval+=dimstp\nif dimval>dimul \nthen\n\n; upper limit\ndimval=dimul\nendif\n=#senddim(dimval)\nelse\n\n; decrease dim level\ndimval-=dimstp\nif dimval<dimll\nthen\n\n; lower limit\ndimval=dimll\nendif\n=#senddim(dimval)\nendif\nendif\nendif\nelse\ntmr=0\nhold=0\nendif\n\n>E\nslider=Dimmer\n\n; slider change\nif chg[slider]>0\nthen\n\n; dim according slider\nif slider>0\nthen\ndimval=slider\n=#senddim(dimval)\nelse\npowert=0\n=#senddim(0)\nendif\nendif\n\nif pwr[1]==1\n; on/off webui\nthen\npowert=1\n=#senddim(dimval)\nelse\npowert=0\n=#senddim(0)\nendif\n\n; subroutine dim\n#senddim(tmp)\ndim=\"FF55\"+hn(tmp*dimmlp)+\"05DC0A\"\n=>SerialSend5 %dim%\n=>Dimmer %tmp%\n#\n
"},{"location":"Scripting-Language/#dual-display-example","title":"Dual display example","text":">D\n>B\n; load sh1106 driver\ndt [S2/SH1106_desc.txt:]\n; clear screen, switch to LCD font; set auto draw\ndt [zf4s1D1]\ndt [S1:]\n>S\n; switch to display 2\ndt [S2:]\n; show time\ndt [x20y20t]\n; switch back to display 1\ndt [S1:]\n
"},{"location":"Scripting-Language/#read-i2c-example-axp192","title":"read I2C example (AXP192)","text":">D\nvolt=0\ncurr=0\nfound=0\n>B\n; check device on I2C bus Nr.2\nfound=ia2(0x34)\n\n>S\n; if found read registers, (this example takes 2ms to read both values)\nif found>0 {\nvolt=ir(0x5a)<<4|ir(0x5b)*1.7/1000\ncurr=ir(0x58)<<4|ir(0x59)*0.625\n}\n\n>W\n; show on webui\nBus Voltage{m}%volt% V\nBus Current{m}%curr% mA\n
"},{"location":"Scripting-Language/#multiplexing-a-single-adc-with-cd4067-breakout","title":"Multiplexing a single adc with CD4067 breakout","text":">D\n; this script works with a CD4067 breakout to multiplex a single ADC channel\n; of an ESP\nIP=192.168.178.177\nSB=8192\nres=0\ncnt=0\nmcnt=0\nm:mux=0 16\n\n>B\n; define output pins for multiplexer\nspinm(12 O)\nspinm(13 O)\nspinm(14 O)\nspinm(15 O)\n; define string array with 16 entries\nres=is1(16 \"\")\nis1[1]=\"Azalea\"\nis1[2]=\"Aster\"\nis1[3]=\"Bougainvillea\"\nis1[4]=\"Camellia\"\nis1[5]=\"Carnation\"\nis1[6]=\"Chrysanthemum\"\nis1[7]=\"Clematis\"\nis1[8]=\"Daffodil\"\nis1[9]=\"Dahlia\"\nis1[10]=\"Daisy\"\nis1[11]=\"Edelweiss\"\nis1[12]=\"Fuchsia\"\nis1[13]=\"Gladiolus\"\nis1[14]=\"Iris\"\nis1[15]=\"Lily\"\nis1[16]=\"Periwinkle\"\n\n>F\n; get adc value into array, average 4 values\n; this is for ESP32 here on pin 32\nmux[mcnt+1]=adc(2 32)\n; this is for ESP8266 it has only 1 ADC input\n; mux[mcnt+1]=adc(2)\nmcnt+=1\nif mcnt>=16\nthen\nmcnt=0\nendif\n; set multiplexer\nspin(12 mcnt)\nspin(13 mcnt/2)\nspin(14 mcnt/4)\nspin(15 mcnt/8)\n\n; display web UI\n#wsub\nif wm==0\nthen\nfor cnt 1 16 1\nwcs {s}Ch %0cnt%: %is1[cnt]%{m}%mux[cnt]% %%{e}\nnext\nendif\n\n#rsub\nrap ,\"CD4067\":{\nfor cnt 1 16 1\nrap \"%is1[cnt]%\":%mux[cnt]%\nif cnt<16\nthen\nrap ,\nendif\nnext\nrap }\n\n>J\n; send to mqtt\n; call json subroutine\n%=#rsub\n\n>W\n; call web subroutine\n%=#wsub\n
"},{"location":"Scripting-Language/#image-gallery-of-various-tasmota-scripts","title":"Image gallery of various Tasmota scripts","text":"these are some examples of more complex scripts to show what is possible.\ncomplex scripts should be edited with the external source editor as they contain lots of comments and indents.\ni will provide the sources later.\n
"},{"location":"Scripting-Language/#internet-radio","title":"Internet radio","text":""},{"location":"Scripting-Language/#webcam-with-multiple-options","title":"Webcam with multiple options","text":""},{"location":"Scripting-Language/#energy-collector","title":"Energy collector","text":""},{"location":"Scripting-Language/#energy-display-main-menu","title":"Energy display main menu","text":""},{"location":"Scripting-Language/#energy-display-one-day-of-database","title":"Energy display one day of database","text":""},{"location":"Scripting-Language/#energy-display-last-week-of-database","title":"Energy display last week of database","text":""},{"location":"Scripting-Language/#energy-display-last-weeks-of-database","title":"Energy display last weeks of database","text":""},{"location":"Scripting-Language/#environment-sensor","title":"environment sensor","text":""},{"location":"Scripting-Language/#timer-main-menu","title":"timer main menu","text":""},{"location":"Scripting-Language/#timer-setup","title":"timer setup","text":""},{"location":"Securing-your-IoT-from-hacking/","title":"Securing your IoT from hacking","text":""},{"location":"Securing-your-IoT-from-hacking/#general-weaknesses","title":"General Weaknesses","text":"Whenever you add devices to your network you generate additional points of potential intrusion. This is not only valid for your mobile phones and computers, but also for you Smart TV, you Alexa, or all of your SONOFF devices (ESP8266).
There are following potential risks you have to mitigate:
- Someone is able to communicate with your device (Scenario 1)
- Someone hacks your device and is able to log in into your WLAN. (why is this a problem? Scenario 2)
- Someone hacks your device and is able to read and change any value on your MQTT server (why is this a problem? Scenario 3)
- Someone hacks your network and can interact with your devices (why is this a problem? Scenario 4)
- Someone hacks your device and use it for different things like mail bot or DOS (Denial of Service) device or WLAN jammer (why is this a problem? Scenario 5)
"},{"location":"Securing-your-IoT-from-hacking/#scenario-1","title":"Scenario 1","text":"It is possible to set a password to the webadmin interface, however ESP8266 devices SHALL not be exposed to internet or accessible to other network clients. (e.g. users in the same network) [1] [2].
"},{"location":"Securing-your-IoT-from-hacking/#scenario-2","title":"Scenario 2","text":"If someone is able to get your WLAN key, he can login into your network, if he is nearby and scan for any traffic and for any devices. Many communication is not encrypted in your WLAN by default. Therefore be part of your WLAN gives the attacker a great opportunity to screw-up the rest of your infrastructure. Also be part of your WLAN does mean, that the attacker can use your IP-Address and your traffic to do nasty things.
"},{"location":"Securing-your-IoT-from-hacking/#scenario-3","title":"Scenario 3","text":"If you can hack an ESP82xx device, you might get access to the keys stored in the device. For example, the MQTT password allows you to read ALL of your devices and change any device at any time. With the information of the MQTT-Server user/password, it might be not required anymore to physically be in your WLAN. Maybe your MQTT Server is publicly accessible. Then the attacker can control your home from any place.
Update: Beginning with version 6.0.0, passwords are not directly exposed through the serial connection or web interface in configuration mode. Therefore it is now less simple, however still possible to obtain the MQTT or WLAN password from a device. Such can be accomplished by downloading a configuration backup via the web UI of the device and decoding it using the decode-config.py script found in the Tasmota tools folder.
"},{"location":"Securing-your-IoT-from-hacking/#scenario-4","title":"Scenario 4","text":"It might happen, that e.g. your Samsung SmartTV is not as secure as it should be and an attacker gets access to your network. Now he can listen to any traffic and maybe can make changes on all of your IoT devices.
"},{"location":"Securing-your-IoT-from-hacking/#scenario-5","title":"Scenario 5","text":"If someone uses your device to spam mail or do a DOS attack the impact at your home is minimal. You might have more outbound traffic, but maybe you don't recognize this either. But thousands of hacked IoT devices can generate tremendous trouble even at the largest internet providers.
I hope these five typical scenarios ( the list is not complete) give you some idea, why you should take care, even if you're not a terrorist and normally nobody is interested into hacking you personally.
"},{"location":"Securing-your-IoT-from-hacking/#securing-your-wlan","title":"Securing your WLAN","text":"That you should have a WLAN key and use WPA2 for encryption is a \"no brainer\". This is a minimum requirement. Now think about someone can extract the password from the device. E.g. because the device is in the garden and someone with a Laptop and some USB stuff can connect and extract information.
The hacker will get the key. The ONLY possible preventive action to mitigate worst case scenario is to have a second WLAN, like the \"FritzBox Guest WLAN\". Many other routers offer similar things. This guest WLAN has no access to your private WLAN. Additionally, there are some interesting switched you can configure for the WLAN.
At the FritzRouter you can configure \"network separation\". At Fritz this is done by DISABLE \"The wireless devices connected with the guest access can communicate with each other\". This does mean, that a device in the network can not interact with any other device in the WLAN. It can only communicate with the Internet. This simple configuration prevents any attacker to do nasty stuff on YOUR network. Now we have to take care, that the attacker is not creating a Bot-Net and sending e.g., Spam-Mails.
Normally a device in the \"guest WLAN\" can use any internet service. For our IoT devices and for any new device we can create a Router rule, that ONLY MQTT is allowed to our server and any other traffic is blocked. This is a great configuration because it limits the options what a hacker can do. If you have a FritzBox following configuration has to be created to get this working:
-
Create Profile to block all communication except MQTT and NTP Time services. Internet -> Filters -> List -> \"Add Network Application\" \"New Protocol\" (Add four rules, This will block all but UDP123 for Timeserver and 8883 for MQTT Server)
-
TCP from any to Port 1 to 8882
- TCP from any to Port 8884 to 65636
- UDP from any to Port 1 to 122
-
UDP from any to Port 124 to 65636
-
Create a list of \"websites\" your IoT devices are allowed to access. Internet -> Filters -> List -> \"Permitted web sites\" -> EDIT
yourserver\n01.de.pool.ntp.org\n
Replace with the full qualified name of your router in the Internet. NTP server - Use the one you have defined in Tasmota to be the timeserver. -
Create a profile you can attach to your IoT devices. Internet -> Filters -> Access profiles -> \"new Access profile\" \"Filter Web sites\" DISABLE \"Allow HTTPS queries\" SELECT \"Permit web sites (whitelist)
Now you will probably ask two questions:
- How can I communicate with my MQTT Server in my personal WLAN if only traffic into the internet is allowed?
- How can I access the WebConsole of my devices to upload new Firmware and/or make investigations?
The first topic will be solved by exposing your MQTT server to the Internet (no worries, can be done securely).
The second topic has only a workaround. If you want access to your devices you need to change the configuration temporary on your router and ENABLE \"The wireless devices connected with the guest access can communicate with each other\". Secondly, you must login with your Laptop into the GuestWLAN to be able to communicate. If the Webserver is running you should be able to connect and upload e.g. a new firmware.
"},{"location":"Securing-your-IoT-from-hacking/#securing-your-communication","title":"Securing your Communication","text":"In the world of IoT devices and more and more devices in a network, it is essential to use encryption ALL the time. The Tasmota project is able to enable encryption for MQTT. This is great. But it cannot enable encryption on the WebServer. This is bad. As a conclusion, the Webserver must be switched OFF all the time and only be switched ON for administrative purpose. This also disables the feature to change the Relay Status with an HTTP REST call. But this option is insecure anyway and should be avoided.
Now let's work on the MQTT configuration. Also here an attacker can get access to user and password. To minimize the impact EVERY and really EVERY device must have a unique USER and a unique password. If you don't follow this rule the attacker get one device he can control ALL devices. With the USER/PASSWORD he now can control the one device he already holds in his hands. ok, no big deal. How to configure Mosquitto?
In general, Tasmota stores data in stat//+ and tele//+. or cmnd//+ to control something. If we use the as username we can make some quite nice and straight forward configuration.
Example: Topic: ESP_123456 User: ESP_123456 (must be the same to Topic) password: 987654321
Configuration file: /etc/mosquitte/conf.d/jp.acl
user root\ntopic read #\ntopic write #\n\npattern read cmnd/%u/#\npattern write stat/%u/#\npattern write tele/%u/#\n
My user root is allowed to do everything. This is used in my home-automation to control all devices and listen to all devices. The \"pattern\" is used for ALL other users and the %u is a substitute. The great thing is that the device can read its configuration but cannot write to it. And the status information it posts to the /status/ but is not able to read it afterward. With this minimal configuration, Tasmota devices are running.
To add the different user to Mosquitto the following two commands work fine. There is also a re-read available, but a restart works better for me.
sudo mosquitto_passwd -b /etc/mosquitto/conf.d/jp.pw ESP_123456 987654321\nsudo /etc/init.d/mosquitto restart\n
If this is running, we switch the Mosquitto to secure communication on Port 8883 and disable all insecure options.
/etc/mosquitto/conf.d/user.conf
#User Config\npassword_file /etc/mosquitto/conf.d/jp.pw\nacl_file /etc/mosquitto/conf.d/jp.acl\n\nallow_anonymous false\n\nlistener 8883\n\ncafile /etc/mosquitto/certs/ca.crt\ncertfile /etc/mosquitto/certs/server.crt\nkeyfile /etc/mosquitto/certs/server.key\nrequire_certificate false\n
How to generate the certificates in mosquitto please look at:
- Mosquitto SSL Configuration - MQTT TLS Security
- Adding TLS to connect to Mosquitto
- Internet of Things messaging MQTT with TLS
- Enable Secure Communication with TLS and the Mosquitto Broker
"},{"location":"Securing-your-IoT-from-hacking/#ssltls-on-tasmota","title":"SSL/TLS on Tasmota","text":"TLS article explains how to set it up in Tasmota
Self-signed-Mosquitto article explain how to set up Tasmota with certificate-based TLS authentication on a local installation of Mosquitto.
"},{"location":"Securing-your-IoT-from-hacking/#disable-unsecured-fallback-wifi-wifimanager","title":"Disable unsecured fallback WiFi (WifiManager)","text":"Type WifiConfig into the tasmota console. If this parameter is set to 2, you might want to change it after completing the setup of your device since in case your Wifi SSID is not available (i.e. access point dies or WLAN jammer is used as in Scanario 5), the WiFiManager will jump into action and make your tasmota devices available using an unsecured access point.
Some less risky options would be: 0/4/5. Currently the default WiFiConfig value is (WIFI_RETRY) which means that device retries other AP without rebooting. (For details, see Wi-Fi commands).
"},{"location":"Securing-your-IoT-from-hacking/#home-assistant-os-mqtt-add-on","title":"Home Assistant OS MQTT Add-On","text":"If you are using Home Assistant OS MQTT add-on with Tasmota integration the devices will need write access to the tasmota/discovery/# topic.
Add the following to the ACL file (user section or general section): topic write tasmota/discovery/#.
For completeness' sake, below is a snippet of the ACL file with the full recommended structure.
########\n######## General section\n# Commented out all general rules.\n# topic readwrite homeassistant/#\n# topic write tasmota/discovery/#\n########\n\n########\n######## User section\n\nuser sonoff-living-fan-2\n# This is used when SetOption19 1 is used.\ntopic readwrite homeassistant/#\n# This is used when SetOption19 0 is used.\ntopic write tasmota/discovery/#\n\n########\n\n########\n######## Pattern Section\n# https://tasmota.github.io/docs/Securing-your-IoT-from-hacking/\npattern read cmnd/%u/#\npattern write stat/%u/#\npattern write tele/%u/#\n########\n
"},{"location":"Self-signed-Mosquitto/","title":"Self signed Mosquitto","text":"This feature is not included in precompiled binaries
To use it you must compile your build.
The following guide will walk you through the setup of Tasmota with your own instance of Mosquitto Server with Certificate-based TLS encryption and a Self-signed CA (Certificate Authority).
"},{"location":"Self-signed-Mosquitto/#benefits","title":"Benefits","text":"The following setup provides stronger security in communication between your devices and your MQTT server.
"},{"location":"Self-signed-Mosquitto/#-no-cloud-usage","title":"- No cloud usage","text":"Many people might prefer cloud-based solutions, such as AWS IOT. Nonetheless, running local MQTT provides various benefits like no internet requirements, no data sharing with third parties and lower latencies.
"},{"location":"Self-signed-Mosquitto/#-maximum-security","title":"- Maximum security","text":"This setup is designed with 'security first' in mind.
Communication is done over TLS 1.2 tunnels, using client certificates to authenticate each device.
Strong encryption is particularly valuable considering that ESP8266-based Tasmota devices can only connect using WPA2 with preshared keys. Because WPA2 Personal has known security weaknesses, the MQTT strong TLS configuration is encouraged in this scenario.
"},{"location":"Self-signed-Mosquitto/#caveats","title":"Caveats","text":"Certificate-based MQTT-TLS requires each Tasmota device to have its own distinct Private Key and Certificate (~800 bytes). Although you could imagine to use the same Private Key in all your devices, this is considered as a very bad practice. You are warned!
During TLS handshake, a secondary stack of 5.3k is allocated on the heap to allow BearSSL to have enough stack room. Memory is freed at the end of the handshake. Allocating such big chunks of memory can cause issues when heap fragmentation gets too high. If you see memory going below 15KB, you may experience crashes.
"},{"location":"Self-signed-Mosquitto/#how-to-configure","title":"How to configure?","text":"Ideally we will work on three systems: 1. CA machine: a secure, possibly air-gap system, where you generate your certificates; 2. Server Machine: the machine running your MQTT server. We will assume it is running some Debian-based distribution (i.e. Ubuntu Server), though the steps could be adapted to different OSes; 3. Compiling Machine: the machine used to compile your customized Tasmota firmware. This machine might be the same Server Machine, though I would not recommend it.
!!! failure \"Security notice\" Private keys, and in particular the CA private key should reside on a secure, possibly air-gapped system. Securing your CA and procedures for managing private keys exceeds the scope of this guide, but we assume you follow best security practices.
There are several figures below containing command sequences that need to be executed in a POSIX shell. The intention is that text in the figure windows will be selected and copied, then pasted into a terminal window. These commands will not work if pasted into a Windows command prompt.
"},{"location":"Self-signed-Mosquitto/#linux-and-windows","title":"Linux and Windows","text":"The description below is written mainly from the perspective of someone using a Linux OS. Information is also provided for those working on a Windows OS, but a Linux command shell (e.g. sh or bash) is assumed for much of the work. Cygwin is a good choice for this purpose. It's not impossible to do perform these tasks in native Windows without a POSIX shell, although that is beyond the scope of this document.
A Cygwin installation should include the git package (Devel category) and openssl package (Net category). Additional packages will be required as discussed later if BearSSL is to be installed.
"},{"location":"Self-signed-Mosquitto/#1-prepare-your-ca-on-server-machine","title":"1. Prepare your CA (on Server Machine)","text":"We will use Easy-RSA for easy management of the CA and certificates. Some modification are required to match our configuration.
"},{"location":"Self-signed-Mosquitto/#11-prepare-easy-rsa","title":"1.1. Prepare Easy-RSA :","text":"Get a copy of Easy-RSA and add a reduced x509 extension definition for Tasmota. Certificates obtained using standard client definitions are too big and results in failure when storing them on Tasmota devices.
git clone https://github.com/OpenVPN/easy-rsa.git\ncd easy-rsa/easyrsa3\n\n# Define reduced x509 extension for Tasmota\ncat <<EOF > x509-types/tasmota\n# X509 extensions for a Tasmota client\nbasicConstraints = critical,CA:FALSE\nsubjectKeyIdentifier = hash\nauthorityKeyIdentifier = keyid:always\nkeyUsage = critical,digitalSignature\nEOF\n
Windows users may have trouble running EasyRSA natively. If that happens, it's also possible to install Cygwin, and work from a Cygwin terminal window. One note of caution: The easyrsa shell script may wind up with the wrong line endings if git is not configured to checkout line endings \"as is\". When this happens, the shell script will not run in Cygwin, and this problem may be fixed by using the tr program to delete carriage returns in the script file: mv easyrsa tmprsa\ntr -d '\\r' <tmprsa >easyrsa\n
"},{"location":"Self-signed-Mosquitto/#12-define-your-certificate-information","title":"1.2. Define your certificate information","text":"The commands below may be copied and pasted into a terminal window, then the resulting file, vars edited as appropriate.
# Define your info\ncat <<EOF > vars\n# Define X509 DN mode.\n# This is used to adjust what elements are included in the Subject field as the DN\n# (this is the \"Distinguished Name.\")\n# Note that in cn_only mode the Organizational fields further below aren't used.\n#\n# Choices are:\n# cn_only - use just a CN value\n# org - use the \"traditional\" Country/Province/City/Org/OU/email/CN format\n\nset_var EASYRSA_DN \"org\"\n\n# Organizational fields (used with 'org' mode and ignored in 'cn_only' mode.)\n# These are the default values for fields which will be placed in the\n# certificate. Don't leave any of these fields blank, although interactively\n# you may omit any specific field by typing the \".\" symbol (not valid for\n# email.)\n\nset_var EASYRSA_REQ_COUNTRY \"UK\"\nset_var EASYRSA_REQ_PROVINCE \"London\"\nset_var EASYRSA_REQ_CITY \"London\"\nset_var EASYRSA_REQ_ORG \"myorg\"\nset_var EASYRSA_REQ_EMAIL \"info@myorg.com\"\nset_var EASYRSA_REQ_OU \"MQTT\"\n\n# Choose a size in bits for your keypairs. The recommended value is 2048. Using\n# 2048-bit keys is considered more than sufficient for many years into the\n# future. Larger keysizes will slow down TLS negotiation and make key/DH param\n# generation take much longer. Values up to 4096 should be accepted by most\n# software. Only used when the crypto alg is rsa (see below.)\n\nset_var EASYRSA_KEY_SIZE 2048\n\n# The default crypto mode is rsa; ec can enable elliptic curve support.\n# Note that not all software supports ECC, so use care when enabling it.\n# Choices for crypto alg are: (each in lower-case)\n# * rsa\n# * ec\n# * ed\n\nset_var EASYRSA_ALGO rsa\n\n# Define the named curve, used in ec & ed modes:\n\nset_var EASYRSA_CURVE prime256v1\n# In how many days should the root CA key expire?\n\nset_var EASYRSA_CA_EXPIRE 3650\n\n# In how many days should certificates expire?\n\nset_var EASYRSA_CERT_EXPIRE 1800\n# Cryptographic digest to use.\n# Do not change this default unless you understand the security implications.\n# Valid choices include: md5, sha1, sha256, sha224, sha384, sha512\n\n#set_var EASYRSA_DIGEST \"sha256\"\nEOF\n
This creates a configuration file named vars -- the default file which the easyrsa shell script looks for.
If the configuration is to be changed there are two options. First, vars can simply be edited to reflect the new configuration. However, if multiple configurations are often used, it may be easier to use a different file for each configuration, and the configuration specified on the command line. For example, to use a configuration file named vars3, the command would look like this (the config file spec must come before other arguments):
./easyrsa --vars=./vars3 <remaining arguments>\n
Note that the file is specified as ./<filename>, not <filename>. This required because the specified file will be sourced in the EasyRSA shell script, and it's assumed that the current directory is not part of the search path (that would be a security concern).
"},{"location":"Self-signed-Mosquitto/#13-initialize-and-generate-the-ca-and-the-server-certificates","title":"1.3. Initialize and generate the CA and the server certificates:","text":"When generating the server (aka broker) certificate, it is crucial that the Common Name (CN) be set correctly. Failing to do this will result in Tasmota devices refusing to make TLS connections to the server.
Each Tasmota device needs to be configured with the host name of the server. This is done via the MQTT_HOST macro in user_config_override.h, and/or in the device's MQTT Configuration web page. The host name string must meet two requirements: - The Tasmota device must be able to resolve the name, which might require access to a DNS server. - This string must match the Common Name (CN) in the broker's certificate -- exactly.
Consider a situation where the device is running on an isolated WiFi network with no access to a DNS server. In this case, it may be necessary to specify the MQTT Host as a numeric IP address (e.g. 192.168.2.3). For this example, the CN in the host's certificate must be the string 192.168.2.3.
To generate the root CA and server certificates, issue these commands. This example assumes the server's hostname and server certificate CN is mqtt.myorg.com.
# Reset PKI\n./easyrsa init-pki\n# Build CA following instructions\n./easyrsa build-ca\n# Request server certificate following instructions\n./easyrsa gen-req mqtt.myorg.com\n# Sign certificate for server\n./easyrsa sign-req server mqtt.myorg.com\n
"},{"location":"Self-signed-Mosquitto/#14-change-key-types-ec-is-required-for-tasmota-devices","title":"1.4. Change key types (EC is required for tasmota devices)","text":"This example shows editing of the vars file, although a second configuration file could be created for EC keys as explained previously.
sed -i '/^set_var\\ EASYRSA_ALGO/ s/rsa/ec/' vars\n
"},{"location":"Self-signed-Mosquitto/#15-copy-the-following-files-to-the-server-machine","title":"1.5. Copy the following files to the Server Machine","text":"./pki/ca.crt --> CA certificate file\n./pki/issued/mqtt.myorg.com.crt --> Server certificate file\n./pki/private/mqtt.myorg.com.key --> Server private Key file\n
"},{"location":"Self-signed-Mosquitto/#16-optional-step-for-full-certificate-validation","title":"1.6. (Optional step for full certificate validation)","text":" ./brssl ta pki/ca.crt | sed -e 's/TA0/PROGMEM TA0/' -e '/br_x509/,+999 d' > local_ca_data.h\n./brssl ta pki/ca.crt | sed -e '1,/br_x509/ d' -e '/};/,+999 d' >local_ca_descriptor.h\n
"},{"location":"Self-signed-Mosquitto/#2-configure-your-tasmotabuild-on-compiling-machine","title":"2. Configure your Tasmotabuild (on Compiling Machine)","text":"Refer to your preferred way to custom compile Tasmota. Modify the default configuration following one of 2.1 or 2.2 solutions (Easier or Advanced):
"},{"location":"Self-signed-Mosquitto/#21-easier-using-fingerprint-validation","title":"2.1. Easier: Using fingerprint validation","text":"Add the following to user_config_override.h:
#ifndef USE_MQTT_TLS\n#define USE_MQTT_TLS\n// #define USE_MQTT_TLS_CA_CERT // Force full CA validation instead of fingerprints, slower, but simpler to use. (+2.2k code, +1.9k mem during connection handshake)\n#define USE_MQTT_AWS_IOT // This includes the LetsEncrypt CA in tasmota_ca.ino for verifying server certificates\n#define USE_MQTT_TLS_FORCE_EC_CIPHER // Force Elliptic Curve cipher (higher security) required by some servers (automatically enabled with USE_MQTT_AWS_IOT) (+11.4k code, +0.4k mem)\n#define MQTT_FINGERPRINT1 \"00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00\" // [MqttFingerprint1] (auto-learn)\n#define MQTT_FINGERPRINT2 \"DA 39 A3 EE 5E 6B 4B 0D 32 55 BF EF 95 60 18 90 AF D8 07 09\" // [MqttFingerprint2] (invalid)\n#endif\n
"},{"location":"Self-signed-Mosquitto/#22-advanced-using-full-certificate-validation","title":"2.2. Advanced: Using Full certificate validation","text":"Add the following to user_config_override.h:
#ifndef USE_MQTT_TLS\n#define USE_MQTT_TLS\n#define USE_MQTT_TLS_CA_CERT // Force full CA validation instead of fingerprints, slower, but simpler to use. (+2.2k code, +1.9k mem during connection handshake)\n#define USE_MQTT_AWS_IOT // This will include LetsEncrypt CA, as well as our CA, in tasmota_ca.ino for verifying server certificates\n#define USE_MQTT_TLS_FORCE_EC_CIPHER // Force Elliptic Curve cipher (higher security) required by some servers (automatically enabled with USE_MQTT_AWS_IOT) (+11.4k code, +0.4k mem)\n#define INCLUDE_LOCAL_CERT\n#endif\n
Copy or move the files created in step 1.6 above (local_ca_data.h and local_ca_descriptor.h) to the $TASMOTAROOT/tasmota/include directory. If desired, the two built-in certificates for Let's Encrypt and Amazon AWS may be omitted from the build by defining these macros in user_config_override.h: #define OMIT_LETS_ENCRYPT_CERT\n#define OMIT_AWS_CERT\n
"},{"location":"Self-signed-Mosquitto/#3-build-your-tasmota-binaries-flash-and-configure-your-devices","title":"3. Build your Tasmota Binaries, flash and configure your devices","text":"Initially at least, build the binaries with the web server enabled. Pull up the web page on each device and check the configuration. In particular check the following settings.
- WiFi Host Name
- MQTT Host -- must be resolvable, and match the Common Name on the server's certificate
- MQTT Port -- this often does not come up as defined in the configuration file, and must be changed to 8883
- MQTT Topic
"},{"location":"Self-signed-Mosquitto/#4-configure-your-network","title":"4. Configure your network","text":"The Common Name (CN) in the server's certificate will either be a resolvable name (like mqtt.myorg.com), or the IP address string for the server (e.g. 192.168.2.3). The host name assigned to the server must match this CN, unless an IP address string is used in the server certificate CN, in which case the host name can be anything. These next two items are only necessary where the CN is not an IP address string.
- Configure your router to resolve the Tasmota device's MQTT Host Name (e.g.
mqtt.myorg.com) to your Server Machine. - Configure your Server Machine hostname to the same name (e.g.
mqtt.myorg.com).
In all cases, check these Tasmota guidelines about Securing your IoT.
"},{"location":"Self-signed-Mosquitto/#5-install-and-configure-mosquitto-on-your-server","title":"5. Install and configure Mosquitto on your server","text":"Install Mosquitto
"},{"location":"Self-signed-Mosquitto/#linux","title":"Linux","text":"sudo apt-get install Mosquitto\n
"},{"location":"Self-signed-Mosquitto/#windows","title":"Windows","text":"Download and run the Windows installer from https://www.mosquitto.org/. Mosquitto may be installed either as a program or service. The main difference is in how mosquitto is started. As a program, it must be started by a user every time, but as a service it can be automatically started by the OS during boot.
"},{"location":"Self-signed-Mosquitto/#51-configuration","title":"5.1 Configuration","text":"Copy the files from CA Machine to the following locations on a Linux server machine:
/etc/mosquitto/ca_certificates/ca.crt\n/etc/mosquitto/certs/mqtt.myorg.com.crt\n/etc/mosquitto/certs/mqtt.myorg.com.key\n
and to here on a Windows server machine (requires Administrative privileges):
C:\\Program Files\\mosquitto\\ca.crt\nC:\\Program Files\\mosquitto\\mqtt.myorg.com.crt\nC:\\Program Files\\mosquitto\\mqtt.myorg.com.key\n
On Windows, if preferred, one or two subdirectories within the mosquitto installation directory can be created to hold the certificates. That might make it easier to restrict access to a private key in plain text form. There are two options for configuring the server's private key. It can be converted to plain text form (.pem) as shown below, or left encrypted (.key). If left encrypted, the password will need to be entered by hand every time the server is started. This will not be feasible if mosquitto is to be run as a service. Security risks can be minimzed by setting tight permissions on the files, as shown below.
Convert the private key to plain text format like this:
openssl rsa -in mqtt.myorg.com.key -out mqtt.myorg.com.pem
"},{"location":"Self-signed-Mosquitto/#file-permissions-linux","title":"File Permissions: Linux","text":"Ensure the files have owner mosquitto:mosquitto and permissions -r--------. Also ensure ca_certificates and certs directories have owner mosquitto:mosquitto and permissions dr-x------.
"},{"location":"Self-signed-Mosquitto/#file-permissions-windows","title":"File Permissions: Windows","text":"It should be possible to configure permissions so that only the SYSTEM user can read the private key file, and when mosquitto is run as a service, it runs under the SYSTEM account. How to do this is currently beyond the scope of this guide.
"},{"location":"Self-signed-Mosquitto/#53-configure-and-start-the-server","title":"5.3 Configure and start the server","text":"Edit /etc/mosquitto/conf.d/default.conf as following:
protocol mqtt\nallow_anonymous false\nlistener 8884\nsocket_domain ipv4\n# Certs and Keys\ncafile /etc/mosquitto/ca_certificates/ca.crt\ncertfile /etc/mosquitto/certs/mqtt.myorg.com.crt\nkeyfile /etc/mosquitto/certs/mqtt.myorg.com.pem\nrequire_certificate true\nuse_identity_as_username true\n
On a Windows machine, the configuration file is C:\\Program Files\\mosquitto\\mosquitto.conf, and the paths to the certificate and key files should be set accordingly using standard Windows path syntax.
To start Mosquitto on Linux:
sudo service mosquitto Start\n
To start Mosquitto on Windows, either use the services snap-in (services.msc), or from an Administrator command prompt:
net start mosquitto\n
"},{"location":"Self-signed-Mosquitto/#6-generate-and-configure-certificates-for-your-devices","title":"6. - Generate and configure certificates for your devices","text":"!!! failure \"Repeated step\" Repeat the following 6.x steps once for every device, changing tasmota_name for each device. You will be prompted for a private key password for each device. After entering the new password (twice for verification), you will also be prompted for the private key password of the root CA certificate.
"},{"location":"Self-signed-Mosquitto/#61-generate-the-client-certificates","title":"6.1 Generate the client certificates","text":"export TAS=tasmota_name\n# Request tasmota certs (will ask for password)\n./easyrsa gen-req $TAS\n# Sign certificate for Tasmota\n./easyrsa sign-req tasmota $TAS\n
"},{"location":"Self-signed-Mosquitto/#62-convert-certificate-keys-to-tasmota-compatible-format","title":"6.2 Convert certificate keys to Tasmota compatible format","text":"The new certificate must be converted to Tasmota commands which can be entered into the device's web console. Credentials are composed of two distinct parts:
- Private Key - this is the secret that will allow your device to prove its identity, and consists of 32 bytes (256 bits). Consider this as sensitive as a password.
- Public Key - this allows others to encrypt messages which can only be decrypted with the Private Key, and contains 256 bytes (2048 bits).
Both of these must be loaded into flash in the Tasmota device. This is done by entering TLSKey commands in the device's web console.
This step must be performed on the machine where the device certificates were created, from within the easyrsa3 directory. The following commands will generate a shell script, gen-tlskeys, which will perform the necessary work.
cat >gen-tlskeys <<'EOF'\n# Decrypt private key (will ask for a password), then extract TLSKey1 (private) and TLSKey2 (public) values\nif [ \"$#\" -ne 1 ] ; then\n echo \"Usage: gen-tasmota-cert <device-certificate-name>\"\n exit 1\nfi\nif [ ! -f pki/private/$1.key ] ; then\n echo \"Could not find private key file pki/private/$1.key\"\n exit 1\nfi\nif [ ! -f pki/issued/$1.crt ] ; then\n echo \"Could not find public key file pki/issued/$1.crt\"\n exit 1\nfi\nopenssl ec -in ./pki/private/$1.key -outform PEM | \\\nopenssl ec -inform PEM -outform DER | openssl asn1parse -inform DER | \\\nhead -3 | tail -1 | awk -F':' '{ print $4 }' | xxd -r -p | base64 | \\\necho -e \"----\\n\\nCopy the following commands and paste them into the device's web console\\n\\n---\\n\\nTLSKey1 $(</dev/stdin)\" && \\\nopenssl x509 -in ./pki/issued/$1.crt -inform PEM -outform DER | \\\nopenssl base64 -e -in - -A|echo -e \"\\n\\nTlskey2 $(</dev/stdin)\"\nEOF\nchmod 755 gen-tlskeys\n
Now, for each device, simply enter this command. As above, the variable ($TAS) is set to the name of the device's certificate. Output will consist of two Tasmota device commands printed to the terminal window; these must be copied and pasted into the device's web console.
./gen-tlskeys $TAS\n
The TLSKey1 command contains the device's private key in plain text (unencrypted) format, so don't keep it around any longer than necessary.
"},{"location":"Self-signed-Mosquitto/#63-access-your-devices-web-console-and-configure-the-keys","title":"6.3 Access your device's web console and configure the keys.","text":"Run the TLSKey1 and TLSKey2 commands as obtained in the previous output. Open each of the files, copy the text and paste it into the web console.
"},{"location":"Self-signed-Mosquitto/#64-verify-the-device-is-connecting-as-expected","title":"6.4 Verify the device is connecting as expected.","text":""},{"location":"Self-signed-Mosquitto/#building-bearssl-on-windows-machines","title":"Building BearSSL on Windows machines","text":"This can be a challenging task, and a method to accomplish this through Cygwin is described here.
Here are the issues that need to be fixed before BearSSL will build under Cygwin. Many of them are related to the differences between Windows and Linux when it comes to programming socket I/O. - Commands for compiling and linking are gcc, not cc - Additional compiler flags are required to compile and link socket I/O code - A Windows socket library (libws2_32) must be included in the link edit step when building the brssl executable - A local implementation of a missing function (inet_ntop) must be added to the build
The current git master branch of BearSSL is required -- the 0.6 version available as a gzipped tar archive will not work. An up-to-date version of gcc in Cygwin is also required -- old versions may experience an internal compiler error when building BearSSL.
Start by installing Cygwin, selecting the gcc and make packages in the Devel category, and the openssl package in the Net category.
Open a Cygwin terminal window and change to the directory where BearSSL source was cloned. To access a Windows letter drive such as F:\\somepath in Cygwin, use the path /cygdrive/f/somepath.
All of the necessary patches are easily made by copying and pasting this set of commands into the Cygwin terminal window. This will create files needed to patch the BearSSL build. First, change to the top level BearSSL directory in the Cytwin window. After selecting the text in the window below, click in the Cygwin window and hit Control-Insert to paste, or right-click in the window and select Paste from the drop-down menu. You may need to hit Enter after doing this.
cat >edit-Unix-mk.sed <<'EOF'\n1 a \\# Modified for building on Cygwin systems\n/^CC.*=.*cc/ c \\CC = gcc\n/^LDDLL.*=.*cc/ c \\LDDLL = gcc\n/^LD.*=.*cc/ c \\LD = gcc\n/^CFLAGS.*=/ s/-fPIC/-DWINVER=0x0501 -DEWOULDBLOCK=EAGAIN/\n/^LDOUT.*=/ a \\BRSSL_EXT_LIBS = -lws2_32\nEOF\n\ncat >extraTargets <<'EOF'\n\n$(OBJDIR)$Pinet_ntop$O: tools$Pinet_ntop.c $(HEADERSTOOLS)\n $(CC) $(CFLAGS) $(INCFLAGS) $(CCOUT)$(OBJDIR)$Pinet_ntop$O tools$Pinet_ntop.c\n\n$(BRSSL): $(BEARSSLLIB) $(OBJBRSSL)\n $(LD) $(LDFLAGS) $(LDOUT)$(BRSSL) $(OBJBRSSL) $(BEARSSLLIB) $(BRSSL_EXT_LIBS)\nEOF\n\ncat >tools/inet_ntop.c <<'EOF'\n#ifdef _WIN32\n#include <stdio.h>\n#include <stdlib.h>\n#include <string.h>\n#include <stdint.h>\n#include <errno.h>\n#include <signal.h>\n#include <winsock2.h>\n#include <ws2tcpip.h>\nconst char *inet_ntop(int af, const void *src, char *dst, int cnt)\n{\n if (af == AF_INET)\n {\n struct sockaddr_in in;\n memset(&in, 0, sizeof(in));\n in.sin_family = AF_INET;\n memcpy(&in.sin_addr, src, sizeof(struct in_addr));\n getnameinfo((struct sockaddr *)&in, sizeof(struct\nsockaddr_in), dst, cnt, NULL, 0, NI_NUMERICHOST);\n return dst;\n }\n else if (af == AF_INET6)\n {\n struct sockaddr_in6 in;\n memset(&in, 0, sizeof(in));\n in.sin6_family = AF_INET6;\n memcpy(&in.sin6_addr, src, sizeof(struct in_addr6));\n getnameinfo((struct sockaddr *)&in, sizeof(struct\nsockaddr_in6), dst, cnt, NULL, 0, NI_NUMERICHOST);\n return dst;\n }\n return NULL;\n}\n#endif\nEOF\n\ncat >patch-bearssl <<'EOF'\nsed -f edit-Unix-mk.sed conf/Unix.mk >conf/Cygwin.mk\nsed -e '/^OBJBRSSL = / a \\ $(OBJDIR)$Pinet_ntop$O \\\\' mk/Rules.mk >Rules.tmp\ncat Rules.tmp extraTargets >mk/Rules.mk\nrm -f Rules.tmp\ncp -f tools/brssl.h brssl.tmp\nsed -e '/^#include.*bearssl\\.h/ a \\const char *inet_ntop(int,const void*,char*,int);' brssl.tmp >tools/brssl.h\nrm -f brssl.tmp\nEOF\nchmod 755 patch-bearssl\n
Check to make sure that the file extraTargets contains a leading tab character, not spaces on the $(CC) and $(LD) lines. Executing the following commands should get the job done:
./patch-bearssl\nmake tools CONF=Cygwin\n
The resulting brssl.exe file will be found in the build directory, and should be copied to the top level EasyRSA directory.
"},{"location":"Sensor-API/","title":"Sensor API","text":"Tasmota sensor API documentation for sensor driver development.
"},{"location":"Sensor-API/#important-things-to-consider","title":"Important things to consider","text":" - There are several I2C sensor examples you can take from the development codebase when writing your own and you are encouraged to do this as it is a quick and easy way to see how things fit together.
- The Tasmota firmware is essentially intended for ESP8266/ESP8285 Wi-Fi SoC based devices and commits to the main development branch will be subject to review based on whether or not what you intend to develop or add to the existing code is relevant to the general ESP device users.
- That being said, there is a lot of development going into the firmware which extends the functionality of standard off the shelf Sonoff devices. The firmware in itself is also useful for boards such as the WeMos ESP82xx boards. More technically inclined individuals who use generic ESP82xx modules in their own circuits to provide more access to pins and the ability to add more sensors and hardware external to the device or the generic ESP82xx module circuits can also take advantage of Tasmota.
- The resources on the ESP82xx are finite. Most devices ship with 1MByte SPI flash which means for the generic device users, the code generally needs to be less than 502KBytes to ensure that OTA (Over The Air) flash functionality (which is the main reason why people use this firmware) remains available. RAM is also limited to an absolute maximum of 80KBytes. This memory is divided into heap (used by global variables and Strings) and stack (used by local variables) where stack space is just 4KBytes.
- Given the above resource constraints it's important to keep your code as small as possible, as fast running as possible, and use as little RAM as possible.
- You need to think about these resource constraints all the time whilst doing any development you wish to add to the firmware functionality - Face the fact that microcontroller development isn't as close a relative to standard computer programming as you'd expect.
- You will be adding code to an existing framework which requires you to adhere to some simple but strict rules such as not having any infinite loops like you would have in your generic Arduino code and try to avoid using the delay() functions when writing your code as this will cause the entire firmware to be subjected to the delays you have added - Infinite loops will cause the firmware to lock up completely!
- If your sensor has configuration options please make these available by using the
SensorXX framework which is already incorporated in the base code - This may not stop you from using a web-based configuration interface but since web-based configuration takes up a lot of code space in flash it is very important to make this optional by means of a compiler directive or a #define in the configuration file and as such something you need to keep in mind during your development and debugging - The more progressively optional additional features are in your driver the smaller the basic codebase can be for minimalist implementations. - Whilst developing drivers for devices that use the I2C bus always consider other devices already supported in the codebase which may use the same address range. This could mean you need to find a unique way of differentiating your device detection from other devices on the same address range (e.g. querying a model-specific register) and/or disabling by #undef existing devices if yours is selected with a #define statement and in such cases always provide a warning to the user during compile time using the #warning pragma such as including
#warning **** Turned off conflicting drivers SHT and VEML6070 **** in your code. - DO NOT ADD WEB INTERFACE FOR SENSOR CONFIGURATION if your sensor requires additional user configuration. The reason for this is the additional program memory required but most importantly the amount of RAM required to even create minimal user interfaces. Running out of RAM during runtime will lead to abnormal behaviour of your driver and/or other drivers or the entire firmware! See sensors such as the MCP23008/MCP23017 driver on more information on how to implement
SensorXX commands instead! - While developing you might want to enable additional debugging provided by file
xdrv_99_debug.ino using #define USE_DEBUG_DRIVER which provides some commands for managing configuration settings and CPU timing. In addition you can enable define PROFILE_XSNS_SENSOR_EVERY_SECOND to profile your drivers duration. - Do not assume others will know immediately how to use your addition and know that you will need to write a Wiki for it in the end.
"},{"location":"Sensor-API/#managing-a-forked-branch","title":"Managing a Forked Branch","text":"If you plan to submit a PR bigger than a simple change in one file, here is a short intro about how to do a clean PR.
- fork the Tasmota repository in Github
git clone https://github.com/<github_user>/Tasmota.git and work on your local copygit remote add upstream https://github.com/arendst/Tasmota.gitgit checkout developmentgit checkout -b <temp_branch> to create a working branch where you can push commitsgit push --set-upstream origin <temp_branch>- work on your local version and push as many commits as you want
When you think it is ready to merge and submit a PR:
git checkout development to go back to the main branchgit pull upstream development to update all the latest changesgit push to update your forkgit checkout -b <pr_branch> to create a new branch for the final PRgit push --set-upstream origin <pr_branch>- Merge the edits but be sure to remove the history of your local commits
git merge --squash <temp_branch>git commit -m \"Message\"
Now you have a clean single commit from which you can create the PR on the Tasmota Github.
"},{"location":"Sensor-API/#directoryfile-structure","title":"Directory/file structure","text":"Sensor libraries are located in the lib/ directory. Sensor drivers are located in the tasmota/ directory. The filename of the sensor driver is xsns_<driver_ID>_<driver_name>.ino, e.g. xsns_05_ds18b20.ino where <driver_ID> is a unique number between 01 and 90 and <driver_name> is a human-readable name of the driver.
Using generic libraries from external sources for sensors should be avoided as far as possible as they usually include code for other platforms and are not always written in an optimized way.
"},{"location":"Sensor-API/#api-structure","title":"API structure","text":""},{"location":"Sensor-API/#pre-processor-directives","title":"Pre-processor directives","text":"Conditional compiling of a sensor driver is achieved by adding a pre-processor directive of the scheme USE_<driver_name> in my_user_config.h. Accordingly the driver code has to be wrapped in #ifdef USE_<driver_name> ... #endif // USE_<driver_name>. Any Sensor driver must contain a pre-processor directive defining the driver ID by the scheme #define XSNS_<driver_ID>.
"},{"location":"Sensor-API/#callback-function","title":"Callback function","text":"Any sensor driver needs a callback function following the scheme
// Conditional compilation of driver\n#ifdef USE_<driver_name>\n\n// Define driver ID\n#define XSNS_<driver_ID> <driver_ID>\n\n/**\n * The callback function Xsns<driver_ID>() interfaces Tasmota with the sensor driver.\n *\n * It provides the Tasmota callback IDs.\n *\n * @param byte callback_id Tasmota function ID.\n * @return boolean Return value.\n * @pre None.\n * @post None.\n *\n */\nboolean Xsns<driverID>(byte callback_id) {\n\n// Set return value to `false`\nboolean result = false;\n\n// Check if I2C interface mode\n// if(i2c_flg) {\n\n// Check which callback ID is called by Tasmota\nswitch (callback_id) {\ncase FUNC_INIT:\nbreak;\ncase FUNC_EVERY_50_MSECOND:\nbreak;\ncase FUNC_EVERY_SECOND:\nbreak;\ncase FUNC_JSON_APPEND:\nbreak;\n#ifdef USE_WEBSERVER\ncase FUNC_WEB_APPEND:\nbreak;\n#endif // USE_WEBSERVER\ncase FUNC_SAVE_BEFORE_RESTART:\nbreak;\ncase FUNC_COMMAND:\nbreak;\n}\n// } // if(i2c_flg)\n\n// Return boolean result\nreturn result;\n}\n#endif // USE_<driver_name>\n
"},{"location":"Sensor-API/#callback-ids","title":"Callback IDs","text":"FUNC_INIT
This callback ID is called when sensor drivers should be initialized.
FUNC_EVERY_50_MSECOND
This callback ID is called every 50 milliseconds, e.g. for near real-time operation
FUNC_EVERY_SECOND
This callback ID is called every second.
It can be useful for anything that you need to do on a per second basis and is commonly used as an entry point to detect a driver or initialize an externally driven device such as a sensor, relay board or other forms of input/output required by your driver.
You would normally want to make sure you've detected and initialised before it is used by JSON_APPEND, etc. so that it's ready to serve data.
The generally accepted way to use this would be to detect your sensor and once this is done set a sensor value accordingly so that the function does not use unnecessary resources during future calls, for example:
void MySensorDetect()\n{\nif (MySensorDetected) { return; }\n/*\n * Perform the code which needs to be completed to\n * detect your sensor and then set MySensorDetected to\n * a non-zero value which will prevent this section\n * of your code to re-run every time the function is\n * called.\n * \n * Under normal circumstances you'd not need to do\n * re-detect or initialise your sensor once it has been\n * done\n */\n}\n
Setting a flag that the driver was successful in detecting the attached chip/board via I2C or SPI will prevent it from continuously trying to initialize an already initialized device.
When writing your function responsible for detecting an externally connected I2C device try to create a method by which you read or write to specific registers that would be applicable to that specific I2C device only as to confirm a positive detect for the device. If this is not done extensively it will lead to some drivers getting false detects for a different device type simply because it shares the same I2C address.
Unless your driver is specifically going to use the entire array of addresses provisioned by the manufacturer please consider using a #define USE_MYCHIPNAME_ADDR in the my_user_config.h so that the user may specify the address on which to expect the device. This is of course only applicable to drivers that are not enabled by default in any of the pre-built binaries.
I2C address auto-detection example
#define MPR121_I2C_ADDR_1ST 0x5A /** 1st I2C address of sensor model **/\n#define MPR121_I2C_ADDR_NUM 4 /** Number of sensors/I2C addresses **/\n#define MPR121_I2C_ID_REG 0x5D /** Sensor model specific ID register **/\n#define MPR121_I2C_ID_VAL 0x24 /** Sensor model specific ID register value **/\n\n/* Sensor data struct type declaration/default definition */\ntypedef struct {\nbool connected = false; /** Status if sensor is connected at I2C address */\nbool running = false; /** Running state of sensor */\n.\n.\n.\n} mpr121;\n\n// Declare array of sensor data structs\nmpr121 mpr121[MPR121_I2C_ADDR_NUM];\n\n// Sensor specific init function\nvoid mpr121_init() {\nbool anyConnected = false;\n// Loop through I2C addresses\nfor (uint8_t i = 0; i < MPR121_I2C_ADDR_NUM); i++) {\n\n// Check if sensor is connected on I2C address\nmpr121[i].connected = (MPR121_I2C_ID_VAL == I2cRead8(MPR121_I2C_ADDR_1ST + i, MPR121_I2C_ID_REG);\nif(mpr121[i].connected) {\nanyConnected = true;\n\n// Log sensor found\nsnprintf_P(log_data, sizeof(log_data), PSTR(D_LOG_I2C \"MPR121-%d \" D_FOUND_AT \" 0x%X\"), i, MPR121_I2C_ADDR_1ST + i);\nAddLog(LOG_LEVEL_INFO);\n\n// Initialize sensor\n.\n.\n.\n\n// Set running to true\nmpr121[i].running = true;\n}\n}\nif(!anyConnected){\nsnprintf_P(log_data, sizeof(log_data), PSTR(D_LOG_I2C \"MPR121: No sensors found\"));\nAddLog(LOG_LEVEL_INFO);\n}\n}\n
Four advanced methods to use FUNC_EVERY_SECOND (Food for thought) :
- If a sensor needs an action which takes a long time, like more than 100mS, the action will be started here for a future follow-up. Using the uptime variable for testing like (uptime &1) will happen every 2 seconds. An example is the DS18B20 driver where readings (conversions they call it) can take up to 800mS from the initial request.
- If a sensor needed the previous action it is now time to gather the information and store it in a safe place to be used by
FUNC_JSON_APPEND and/or FUNC_WEB_APPEND. Using the else function of the previous test (uptime &1) will happen every 2 seconds too but just 1 second later than the previous action. - If a sensor does not respond for 10 times the sensor detection flag could be reset which will stop further processing until the sensor is re-detected. This is currently not being used actively as some users complain about disappearing sensors for whatever reason - Could be hardware related but easier to make Tasmota a little more flexible.
- Making re-detection of a sensor possible by executing this once every 100 seconds (94 == (uptime %100)) a re-attached sensor can be detected without a restart of Tasmota. The 94 given in this example should be different for every sensor driver to make sure not all sensors start detection at the same time. Using the drivers index number should be a good starting point.
FUNC_PREP_BEFORE_TELEPERIOD
NOTE: This callback ID is deprecated as sensors should prepare for more regular updates due to \"realtime\" rule execution. Use FUNC_EVERY_SECOND instead. See examples used in xsns_05_ds18x20.ino and xsns_09_bmp.ino where updated sensor data is stored in preparation to calls to FUNC_JSON_APPEND and FUNC_WEB_APPEND.
FUNC_JSON_APPEND
This callback ID is called when TelePeriod is due to append telemetry data to the MQTT JSON string or at approximately every 2 seconds when a rule is checked, e.g.
snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR(\"{\\\"MPR121%c\\\":{\\\"Button%i\\\":%i}}\"), pS->id[i], j, BITC(i,j));\n
FUNC_WEB_APPEND
This callback ID is called every millisecond when HTML code should be added to the Tasmota web-interface main page, e.g.,
snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR(\"%s{s}MPR121%c Button%d{m}%d{e}\"), mqtt_data, pS->id[i], j, BITC(i,j));\n
It should be wrapped in #ifdef USE_WEBSERVER ... #endif // USE_WEBSERVER FUNC_SAVE_BEFORE_RESTART
This callback ID is called to allow a sensor to prepare for saving configuration changes. To be used to save volatile data just before a restart. Variables can be appended to struct SYSCFG {} Settings in file tasmota/settings.h.
FUNC_COMMAND
This callback ID is called when a sensor specific command Sensor<xx> or Driver<xx> is executed where xx is the sensor index.
case FUNC_COMMAND:\nif (XSNS_<driver_ID> == XdrvMailbox.index) {\nresult = <driver_name>Command() { ... }; // Return true on success\n}\nbreak;\n
// Data struct of FUNC_COMMAND ID\nstruct XDRVMAILBOX {\nuint16_t valid; // ???\nuint16_t index; // Sensor index\nuint16_t data_len; // Length of command string\nuint16_t payload16; // 16 bit unsigned int of payload if it could be converted, otherwise 0\nint16_t payload; // 16 bit signed int of payload if it could be converted, otherwise 0\nuint8_t grpflg; // ???\nuint8_t notused; // ???\nchar *topic; // Command topic\nchar *data; // Command string/value - length of which is defined by data_len\n} XdrvMailbox;\n
If your driver needs to accept multiple parameters for SensorXX and/or DriverXX please consider using comma delimited formatting and use the already written subStr() function declared in support.ino to parse through the parameters you need.
An example of those could be
SensorXX reset // The reset parameter may be intercepted using:\nif (!strcmp(subStr(sub_string, XdrvMailbox.data, \",\", 1),\"RESET\")) { // Note 1 used for param number\nMyDriverName_Reset(); return serviced;\n}\n
Or in the case of multiple parameters SensorXX mode,1\nif (!strcmp(subStr(sub_string, XdrvMailbox.data, \",\", 1),\"MODE\")) { // Note 1 used for param number\nuint8_t mode = atoi(subStr(sub_string, XdrvMailbox.data, \",\", 2); // Note 2 used for param number\n}\n
"},{"location":"Sensor-API/#useful-functions","title":"Useful functions","text":""},{"location":"Sensor-API/#mqtt","title":"MQTT","text":"void MqttPublishPrefixTopic_P(uint8_t prefix, const char* subtopic, boolean retained)\n
This function publishes MQTT messages immediately, e.g., snprintf_P(mqtt_data, sizeof(mqtt_data), PSTR(\"{\\\"MPR121%c\\\":{\\\"Button%i\\\":%i}}\"), pS->id[i], j, BITC(i,j));\nMqttPublishPrefixTopic_P(RESULT_OR_STAT, mqtt_data);\n
"},{"location":"Sensor-API/#logging","title":"Logging","text":"void AddLog(byte loglevel)\n
This function adds log messages stored in log_data to the local logging system, e.g. snprintf_P(log_data, sizeof(log_data), PSTR(D_LOG_I2C \"MPR121(%c) \" D_FOUND_AT \" 0x%X\"), pS->id[i], pS->i2c_addr[i]);\nAddLog(LOG_LEVEL_INFO);\n
void AddLogSerial(byte loglevel)\n
This function adds a log message to the local logging system dumping the serial buffer as hex information, e.g. AddLogSerial(LOG_LEVEL_INFO);\n
void AddLogMissed(char *sensor, uint8_t misses)\n
This function adds a log message to the local logging system about missed sensor reads."},{"location":"Sensor-API/#i2c-interface","title":"I2C Interface","text":"bool I2cValidRead8(uint8_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidRead16(uint16_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidReadS16(int16_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidRead16LE(uint16_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidReadS16_LE(int16_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidRead24(int32_t *data, uint8_t addr, uint8_t reg)\n
bool I2cValidRead(uint8_t addr, uint8_t reg, uint8_t size)\n
These functions return true if 1, 2, 3 or size bytes can be read from the I2C address addr and register reg into *data. Functions with a S read signed data types while functions without a S read unsigned data types. Functions with LE read little-endian byte order while functions without LE read machine byte order. uint8_t I2cRead8(uint8_t addr, uint8_t reg)\n
uint16_t I2cRead16(uint8_t addr, uint8_t reg)\n
int16_t I2cReadS16(uint8_t addr, uint8_t reg)\n
uint16_t I2cRead16LE(uint8_t addr, uint8_t reg)\n
int16_t I2cReadS16_LE(uint8_t addr, uint8_t reg)\n
int32_t I2cRead24(uint8_t addr, uint8_t reg)\n
These functions return 1, 2 or 3 bytes from the I2C address addr and register reg. Functions with a S read signed data types while functions without a S read unsigned data types. Functions with LE read little endian byte order while functions without LE read machine byte order. bool I2cWrite8(uint8_t addr, uint8_t reg, uint8_t val)\n
bool I2cWrite16(uint8_t addr, uint8_t reg, uint16_t val)\n
bool I2cWrite(uint8_t addr, uint8_t reg, uint32_t val, uint8_t size)\n
These functions return true after successfully writing 1, 2 or size bytes to the I2C address addr and register reg. int8_t I2cReadBuffer(uint8_t addr, uint8_t reg, uint8_t *reg_data, uint16_t len)\n
int8_t I2cWriteBuffer(uint8_t addr, uint8_t reg, uint8_t *reg_data, uint16_t len)\n
These functions copy len bytes from/to *reg_data starting at I2C address addr and register reg. void I2cScan(char *devs, unsigned int devs_len)\n
This functions writes a list of I2C addresses in use into the string *dev with maximum length devs_len. bool I2cDevice(byte addr)\n
This functions checks if the I2C address addr is in use."},{"location":"Sensor-API/#useful-pre-processor-directives","title":"Useful pre-processor directives","text":"PSTR(\"string\")
This pre-processor directive saves RAM by storing strings in flash instead of RAM.
const char MyTextStaticVariable[] PROGMEM = \"string\";\n
This pre-processor directive saves RAM by storing strings in flash instead of RAM. You may then reference them directly (if the type matches the parameter required) or force it to 4 byte alignment by using the variable as FPSTR(MyTextStaticVariable)
"},{"location":"Sensor-API/#keeping-esp8266-code-compact","title":"Keeping ESP8266 code compact","text":"Below are various tips and tricks to keep ESP8266 code compact and save both Flash and Memory. Flash code is limited to 1024k but keep in mind that to allow OTA upgrade, you need Flash memory to contain two firmwares at the same time. To go beyond 512k, you typically use tasmota-minimal as an intermediate firmware. tasmota-minimal takes roughly 360k, so it's safe not to go uint32_t beyond 620k of Flash. Memory is even more limited: 80k. With Arduino Core and basic Tasmota, there are 25k-30k left of heap space. Heap memory is very precious, running out of memory will generally cause a crash.
"},{"location":"Sensor-API/#about-esp8266","title":"About ESP8266","text":"ESP8266 is based on Xtensa instruction set. Xtensa is a 32 bits RISC processor core, containing 16 x 32 bits registers. ESP8266 supports integer operations, including 32x32 multiplication. It does not contain an FPU for floating point operations, nor integer divisions.
Contrary to classical RISC processors, all instructions are 24 bits wide instead of 32 bits. To increase code compactness, some instructions have a 16 bits version used whenever possible by gcc.
If you want to see what assembly is generated by gcc, in file platform.ini, at the section used to compile (ex: [core_2_6_1]) in section build_flags add:
-save-temps=obj -fverbose-asm
Gcc will store <file>.s in the same folder as the .o file, typically in .pioenvs/.
"},{"location":"Sensor-API/#first-example","title":"First example","text":"Let's take a basic function:
uint32_t Example(uint32_t a, uint32_t b) {\nreturn a + b;\n}\n
Below is the generated assembly. Function names are mangled using standard C++, i.e. their name derive from their arguments and return types:
_Z7Examplejj:\nadd.n a2, a2, a3 #, a, b\nret.n\n
As you can see, this is the simplest function we can think of. Register A2 holds the first argument and is used for return value. A3 holds the second argument.
"},{"location":"Sensor-API/#uint8_t-or-uint32_t","title":"uint8_t or uint32_t ?","text":"uint32_t Example(uint32_t a, uint32_t b) {\nuint8_t c = a + b;\nreturn c;\n}\n
Assembly:
_Z7Examplejj:\nadd.n a2, a2, a3 # tmp52, a, b\nextui a2, a2, 0, 8 #, tmp52\nret.n\n
Whenever gcc needs to convert from uin32_t to uint8_t, it uses an extra instruction extui <reg>, <reg>, 0, 8.
Whenever you allocate uint8_t as a local variable, it will anyways allocate 32 bits on the stack.
In conclusion you can easily use uint32_t in many places in the code. The main reason to force uint8_t are:
- in structures, to save memory. This is the only place where
uint8_t will take 1 byte and the compiler will try to pack as much as 4 uint8_t in 32 bits - when you want to ensure that the value can never exceed 255. Beware though that the compiler will just chunk the last 8 bits of a 32 bits value and will not report any overflow.
"},{"location":"Sensor-API/#loops","title":"Loops","text":"Should you use uint8_t or uint32_t for loops?
Let's try:
uint32_t Example(uint32_t a, uint32_t b) {\nfor (uint8_t i = 0; i < 10; i++) {\na += b;\n}\nfor (uint32_t j = 0; j < 10; j++) {\na += b;\n}\nreturn a;\n}\n
Assembly:
_Z7Examplejj:\nmovi.n a3, 0 # ivtmp$7334, <- loop 1\n.L2031:\nadd.n a2, a2, a3 # a, a, ivtmp$7334\naddi.n a3, a3, 1 # ivtmp$7334, ivtmp$7334,\nbnei a3, 10, .L2031 # ivtmp$7334,,\nmovi.n a3, 0 # j, <- loop 2\n.L2033:\nadd.n a2, a2, a3 # a, a, j\naddi.n a3, a3, 1 # j, j,\nbnei a3, 10, .L2033 # j,,\nret.n\n
As you can see here, both loops generate the same assembly for fixed size loops.
Let's now see for variable size loops.
uint32_t Example(uint32_t a, uint32_t b) {\nfor (uint8_t i = 0; i < b; i++) {\na += i;\n}\nfor (uint32_t j = 0; j < b; j++) {\na += j;\n}\nreturn a;\n}\n
Assembly:
_Z7Examplejj:\nmovi.n a4, 0 # i, <- loop 1\nj .L2030 #\n.L2031:\nadd.n a2, a2, a4 # a, a, i\naddi.n a4, a4, 1 # tmp48, i,\nextui a4, a4, 0, 8 # i, tmp48 <- extra 32 to 8 bits conversion\n.L2030:\nbltu a4, a3, .L2031 # i, b,\nmovi.n a4, 0 # j, <- loop 2\nj .L2032 #\n.L2033:\nadd.n a2, a2, a4 # a, a, j\naddi.n a4, a4, 1 # j, j,\n.L2032:\nbne a4, a3, .L2033 # j, b,\nret.n\n
In the first loop, the register a4 needs to be converted from 32 bits to 8 bits in each iteration.
Again, there is no definitive rule, but keep in mind that using uint8_t can sometimes increase code size compared to uint32_t.
"},{"location":"Sensor-API/#floats-not-doubles","title":"Floats, not doubles!","text":"ESP8266 does not have a FPU (Floating Point Unit), all floating point operations are emulated in software and provided in libm.a. The linker removes any unused functions, so we need to limit the number of floating point function calls.
Rule 1: use ints where you can, avoid floating point operations.
Rule 2: if you really need floating point, always use float, never ever use double.
Let's now see why.
floatfits in 32 bits, with a mantissa of 20 bits, exponent of TODO. The mantissa is 20 bits wide, which provides enough precision for most of our needs.
float is 32 bits wide and fits in a single register, whereas double is 64 bits and requires 2 registers.
float Examplef(float a, float b) {\nreturn sinf(a) * (b + 0.4f) - 3.5f;\n}\n
Assembly:
.literal .LC1012, 0x3ecccccd <- 0.4f\n.literal .LC1013, 0x40600000 <- 3.5f\n_Z8Examplefff:\naddi sp, sp, -16 #,, <- reserve 16 bytes on stack\ns32i.n a0, sp, 12 #, <- save a0 (return address) on stack\ns32i.n a12, sp, 8 #, <- save a12 on stack, to free for local var\ns32i.n a13, sp, 4 #, <- save a13 on stack, to free for local var\nmov.n a13, a3 # b, b <- a3 holds 'b', save to a13\ncall0 sinf # <- calc sin of a2 (a)\nl32r a3, .LC1012 #, <- load 0.4f in a3\nmov.n a12, a2 # D.171139, <- save result 'sin(a)' to a12\nmov.n a2, a13 #, b <- move a13 (second arg: b) to a2\ncall0 __addsf3 # <- add floats a2 and a3, result to a2\nmov.n a3, a2 # D.171139, <- copy result to a3\nmov.n a2, a12 #, D.171139 <- load a2 with a12: sin(a)\ncall0 __mulsf3 # <- multiply 'sin(a)*(b+0.4f)'\nl32r a3, .LC1013 #, <- load a3 with 3.5f\ncall0 __subsf3 # <- subtract\nl32i.n a0, sp, 12 #, <- restore a0 (return address)\nl32i.n a12, sp, 8 #, <- restore a12\nl32i.n a13, sp, 4 #, <- restore a13\naddi sp, sp, 16 #,, <- free stack\nret.n <- return\n
Now with double:
double Exampled(double a, double b) {\nreturn sin(a) * (b + 0.4) - 3.5;\n}\n
Assembly:
.literal .LC1014, 0x9999999a, 0x3fd99999 <- 0.4\n.literal .LC1015, 0x00000000, 0x400c0000 <- 3.5\n_Z8Exampleddd:\naddi sp, sp, -32 #,,\ns32i.n a0, sp, 28 #,\ns32i.n a12, sp, 24 #,\ns32i.n a13, sp, 20 #,\ns32i.n a14, sp, 16 #,\ns32i.n a15, sp, 12 #,\nmov.n a14, a4 #,\nmov.n a15, a5 #,\ncall0 sin #\nl32r a4, .LC1014 #,\nl32r a5, .LC1014+4 #,\nmov.n a12, a2 #,\nmov.n a13, a3 #,\nmov.n a2, a14 #,\nmov.n a3, a15 #,\ncall0 __adddf3 #\nmov.n a4, a2 #,\nmov.n a5, a3 #,\nmov.n a2, a12 #,\nmov.n a3, a13 #,\ncall0 __muldf3 #\nl32r a4, .LC1015 #,\nl32r a5, .LC1015+4 #,\ncall0 __subdf3 #\nl32i.n a0, sp, 28 #,\nl32i.n a12, sp, 24 #,\nl32i.n a13, sp, 20 #,\nl32i.n a14, sp, 16 #,\nl32i.n a15, sp, 12 #,\naddi sp, sp, 32 #,,\nret.n\n
As you can see the double needs to move many more registers around. Examplef (float) is 84 bytes, Exampled (double) is 119 bytes (+42% code size). Actually it's even worse, sin is larger than float version sinf.
Also, never forget to explicitly tag literals as float: always put 1.5f and not 1.5. Let's see the impact:
float Examplef2(float a, float b) {\nreturn sinf(a) * (b + 0.4) - 3.5; // same as above with double literals\n}\n
Assembly:
.literal .LC1014, 0x9999999a, 0x3fd99999\n.literal .LC1015, 0x00000000, 0x400c0000\n.align 4\n.global _Z9Examplef2ff\n.type _Z9Examplef2ff, @function\n_Z9Examplef2ff:\naddi sp, sp, -16 #,,\ns32i.n a0, sp, 12 #,\ns32i.n a12, sp, 8 #,\ns32i.n a13, sp, 4 #,\ns32i.n a14, sp, 0 #,\nmov.n a14, a3 # b, b\ncall0 sinf #\ncall0 __extendsfdf2 # <- extend float to double\nmov.n a12, a2 #,\nmov.n a2, a14 #, b\nmov.n a13, a3 #,\ncall0 __extendsfdf2 # <- extend float to double\nl32r a4, .LC1014 #,\nl32r a5, .LC1014+4 #,\ncall0 __adddf3 # <- add double\nmov.n a4, a2 #,\nmov.n a5, a3 #,\nmov.n a2, a12 #,\nmov.n a3, a13 #,\ncall0 __muldf3 # <- multiply double\nl32r a4, .LC1015 #,\nl32r a5, .LC1015+4 #,\ncall0 __subdf3 # <- subtract double\ncall0 __truncdfsf2 # <- truncate double to float\nl32i.n a0, sp, 12 #,\nl32i.n a12, sp, 8 #,\nl32i.n a13, sp, 4 #,\nl32i.n a14, sp, 0 #,\naddi sp, sp, 16 #,,\nret.n\n
The last example takes 143 bytes, which is even worse than the double version, because of conversions from float to double and back. Internally, if you don't force float literals, gcc will make all intermediate compute in double and convert to float in the end. This is usually what is wanted: compute with maximum precision and truncate at the last moment. But for ESP8266 we want the opposite: most compact code.
"},{"location":"Sensor-API/#string-concatenation","title":"String concatenation","text":"Let's start with an easy example:
void ExampleStringConcat(String &s) {\ns += \"suffix\";\n}\n
Assembly (25 bytes):
.LC1024:\n.string \"suffix\"\n.literal .LC1025, .LC1024\n_Z19ExampleStringConcatR6String:\nl32r a3, .LC1025 #,\naddi sp, sp, -16 #,,\ns32i.n a0, sp, 12 #,\ncall0 _ZN6String6concatEPKc #\nl32i.n a0, sp, 12 #,\naddi sp, sp, 16 #,,\nret.n\n
If you need to add more complex strings, do not concatenate using native c++ concat:
void ExampleStringConcat2(String &s, uint8_t a, uint8_t b) {\ns += \"[\" + String(a) + \",\" + String(b) + \"]\";\n}\n
Assembly (122 bytes!):
.LC231:\n.string \",\"\n.LC1026:\n.string \"[\"\n.LC1029:\n.string \"]\"\n.literal .LC1027, .LC1026\n.literal .LC1028, .LC231\n.literal .LC1030, .LC1029\n_Z20ExampleStringConcat2R6Stringhh:\naddi sp, sp, -64 #,,\ns32i.n a13, sp, 52 #,\nextui a13, a3, 0, 8 # a, a\nl32r a3, .LC1027 #,\ns32i.n a12, sp, 56 #,\nmov.n a12, a2 # s, s\naddi.n a2, sp, 12 #,,\ns32i.n a0, sp, 60 #,\ns32i.n a14, sp, 48 #,\nextui a14, a4, 0, 8 # b, b\ncall0 _ZN6StringC2EPKc # . <- allocate String\nmovi.n a4, 0xa #,\naddi a2, sp, 24 #,,\nmov.n a3, a13 #, a\ncall0 _ZN6StringC1Ehh # <- allocate String\naddi a3, sp, 24 #,,\naddi.n a2, sp, 12 #,,\ncall0 _ZplRK15StringSumHelperRK6String #\nl32r a3, .LC1028 #,\ncall0 _ZplRK15StringSumHelperPKc #\nmovi.n a4, 0xa #,\nmov.n a13, a2 # D.171315,\nmov.n a3, a14 #, b\nmov.n a2, sp #,\ncall0 _ZN6StringC1Ehh # <- allocate String\nmov.n a3, sp #,\nmov.n a2, a13 #, D.171315\ncall0 _ZplRK15StringSumHelperRK6String #\nl32r a3, .LC1030 #,\ncall0 _ZplRK15StringSumHelperPKc #\nmov.n a3, a2 # D.171315,\nmov.n a2, a12 #, s\ncall0 _ZN6String6concatERKS_ #\nmov.n a2, sp #,\ncall0 _ZN6StringD1Ev # <- destructor\naddi a2, sp, 24 #,,\ncall0 _ZN6StringD1Ev # <- destructor\naddi.n a2, sp, 12 #,,\ncall0 _ZN6StringD2Ev # <- destructor\nl32i.n a0, sp, 60 #,\nl32i.n a12, sp, 56 #,\nl32i.n a13, sp, 52 #,\nl32i.n a14, sp, 48 #,\naddi sp, sp, 64 #,,\nret.n\n
Instead use native String concat:
void ExampleStringConcat3(String &s, uint8_t a, uint8_t b) {\ns += \"[\";\ns += a;\ns += \",\";\ns += b;\ns += \"]\";\n}\n
Assembly (69 bytes, -43%):
.LC231:\n.string \",\"\n.LC1026:\n.string \"[\"\n.LC1029:\n.string \"]\"\n.literal .LC1031, .LC1026\n.literal .LC1032, .LC231\n.literal .LC1033, .LC1029\n_Z20ExampleStringConcat3R6Stringhh:\naddi sp, sp, -16 #,,\ns32i.n a13, sp, 4 #,\nextui a13, a3, 0, 8 # a, a\nl32r a3, .LC1031 #,\ns32i.n a0, sp, 12 #,\ns32i.n a12, sp, 8 #,\ns32i.n a14, sp, 0 #,\nmov.n a12, a2 # s, s\nextui a14, a4, 0, 8 # b, b\ncall0 _ZN6String6concatEPKc # <- native char* add\nmov.n a3, a13 #, a\nmov.n a2, a12 #, s\ncall0 _ZN6String6concatEh # <- native int add\nl32r a3, .LC1032 #,\nmov.n a2, a12 #, s\ncall0 _ZN6String6concatEPKc # <- native char* add\nmov.n a3, a14 #, b\nmov.n a2, a12 #, s\ncall0 _ZN6String6concatEh # <- native int add\nl32r a3, .LC1033 #,\nmov.n a2, a12 #, s\ncall0 _ZN6String6concatEPKc # <- native char* add\nl32i.n a0, sp, 12 #,\nl32i.n a12, sp, 8 #,\nl32i.n a13, sp, 4 #,\nl32i.n a14, sp, 0 #,\naddi sp, sp, 16 #,,\nret.n\n
"},{"location":"Sensor-API/#extension-to-vsnprintf","title":"Extension to (v)snprintf()","text":"Tasmota code uses extensively snprintf() to build Web UI, MQTT messages and logs.
However there are some limitations. First we use a stripped down version of (v)snprintf() to save a big amount of code size; and types like float or uint64 or not supported. Second Arduino core often uses high level objects like IPAddress that are not natively supported by snprintf().
GCC libc normally includes a way to extend printf to new data types, but again the reduced lib in Arduino does not provide such a standard extension mechanism.
We have now build an extension mechanism to snprintf() to allow for simpler code and less flash space.
"},{"location":"Sensor-API/#how-to-use","title":"How to use","text":"All extensions are using %_<x> where <x> is one of the following:
Warning: most high-level values must be passed by address
%_X: support for uint64_t.
Example:
uint64_t u64 = 0x1122334455667788LL;\next_snprintf(PSTR(\"Int64 = 0x%_X\"), &u64);\n
%_I: support for IPv4 ip address in the form of uint32_t. Note: it is passed by value, not by address.
Example:
uint32_t ip = 0x10203040;\next_snprintf(PSTR(\"IP = 0x%_I\"), ip);\n
%_f or %*_f or %<number>_f: support for float. Note: float must be passed by address (otherwise it is silently converted to double and creates alignment issues on the stack).
When using %*_f, the first argument specifies the number d of decimal for the float, as a signed int. d can also be directly coded in the format ex: %2_f of %-2_f.
If d > 0 we output exactly d decimals (even zeros), if d < 0 we output d decimals but remove any trailing zeros. Default value is -2 (2 decimals).
Example:
char s[128];\nfloat fl = 3.14;\next_snprintf(s, sizeof(s), PSTR(\"f1=%*_f f2=%*_f f3=%4_f f4=%-4_f\"), 4, &fl, -4, &fl, &fl, &fl);\n// outputs:\n// \"f1=3.1400 f2=3.14 f3=3.1400 f4=3.14\"\n
%*_H: prints an array of bytes as Hex (uppercase). The first argument is the length in bytes of the array (if zero or negative, it outputs an empty string). The second argument is the pointer to the array of bytes. The pointer can be null if the length is zero or negative. The pointer can be in PROGMEM. Note: %_H will output an empty string because it is missing the length.
Example:
char s[16];\nconst uint8_t b[] PROGMEM = { 0x00, 0x01, 0x80, 0xFF };\next_snprintf(s, sizeof(s), PSTR(\"Hex=%*_H\"), sizeof(b), b);\n// outputs:\n// \"Hex=000180FF\"\n
%_B: this is equivalent to %*_H but directly takes an SBuffer() object.
Example:
char s[16];\nSBuffer b(8); // statically allocate 8 bytes\nb.add8(0x5A);\nb.add8(0xA5);\n\next_snprintf(s, sizeof(s), PSTR(\"Hex=%_B\"), &b);\n// outputs:\n// \"Hex=5AA5\"\n
"},{"location":"Sensor-API/#code-size-reduction","title":"Code size reduction","text":""},{"location":"Sensor-API/#floats","title":"Floats","text":"It is not needed to call explicitly dtostrfd() anymore:
Before:
int ResponseAppendTHD(float f_temperature, float f_humidity)\n{\n char temperature[FLOATSZ];\n dtostrfd(f_temperature, Settings.flag2.temperature_resolution, temperature);\n char humidity[FLOATSZ];\n dtostrfd(f_humidity, Settings.flag2.humidity_resolution, humidity);\n char dewpoint[FLOATSZ];\n dtostrfd(CalcTempHumToDew(f_temperature, f_humidity), Settings.flag2.temperature_resolution, dewpoint);\n\n return ResponseAppend_P(PSTR(\"\\\"\" D_JSON_TEMPERATURE \"\\\":%s,\\\"\" D_JSON_HUMIDITY \"\\\":%s,\\\"\" D_JSON_DEWPOINT \"\\\":%s\"), temperature, humidity, dewpoint);\n}\n
Assembly (117 bytes):
_Z17ResponseAppendTHDff:\naddi sp, sp, -64 #,,\ns32i.n a0, sp, 60 #,\ns32i.n a12, sp, 56 #,\ns32i.n a13, sp, 52 #,\ns32i.n a14, sp, 48 #,\nmov.n a13, a3 # f_humidity, f_humidity\nmov.n a14, a2 # f_temperature, f_temperature\ncall0 __extendsfdf2 #\nl32r a12, .LC658 #, tmp57\naddi a5, sp, 32 #,,\naddmi a12, a12, 0x500 # tmp60, tmp57,\nl32i a4, a12, 188 # Settings, Settings\nextui a4, a4, 30, 2 #, Settings,\ncall0 _Z8dtostrfddhPc #\nmov.n a2, a13 #, f_humidity\ncall0 __extendsfdf2 #\nl32i a4, a12, 188 # Settings, Settings\naddi a5, sp, 16 #,,\nextui a4, a4, 28, 2 #, Settings,,\ncall0 _Z8dtostrfddhPc #\nmov.n a3, a13 #, f_humidity\nmov.n a2, a14 #, f_temperature\ncall0 _Z16CalcTempHumToDewff #\ncall0 __extendsfdf2 #\nl32i a4, a12, 188 # Settings, Settings\nmov.n a5, sp #,\nextui a4, a4, 30, 2 #, Settings,\ncall0 _Z8dtostrfddhPc #\nl32r a2, .LC659 #,\naddi a3, sp, 32 #,,\naddi a4, sp, 16 #,,\nmov.n a5, sp #,\ncall0 _Z16ResponseAppend_PPKcz #\nl32i.n a0, sp, 60 #,\nl32i.n a12, sp, 56 #,\nl32i.n a13, sp, 52 #,\nl32i.n a14, sp, 48 #,\naddi sp, sp, 64 #,,\nret.n\n
After:
int ResponseAppendTHD(float f_temperature, float f_humidity)\n{\nfloat dewpoint = CalcTempHumToDew(f_temperature, f_humidity);\n\nreturn ResponseAppend_P(PSTR(\"\\\"\" D_JSON_TEMPERATURE \"\\\":%*_f,\\\"\" D_JSON_HUMIDITY \"\\\":%*_f,\\\"\" D_JSON_DEWPOINT \"\\\":%*_f\"),\nSettings.flag2.temperature_resolution, &f_temperature,\nSettings.flag2.humidity_resolution, &f_humidity,\nSettings.flag2.temperature_resolution, &dewpoint);\n}\n
Assembly (61 bytes):
_Z17ResponseAppendTHDff:\naddi sp, sp, -64 #,,\ns32i.n a0, sp, 60 #,\ns32i.n a3, sp, 36 # f_humidity, f_humidity\ns32i.n a2, sp, 32 # f_temperature, f_temperature\ncall0 _Z16CalcTempHumToDewff #\ns32i.n a2, sp, 16 # dewpoint,\nl32r a2, .LC658 #, tmp51\naddi a4, sp, 32 #,,\naddmi a2, a2, 0x500 # tmp54, tmp51,\nl32i a5, a2, 188 # Settings, Settings\naddi a2, sp, 16 # tmp68,,\nextui a7, a5, 30, 2 # D.156427, Settings,\ns32i.n a2, sp, 0 #, tmp68\nl32r a2, .LC659 #,\naddi a6, sp, 36 #,,\nmov.n a3, a7 #, D.156427\nextui a5, a5, 28, 2 #, Settings,,\ncall0 _Z16ResponseAppend_PPKcz #\nl32i.n a0, sp, 60 #,\naddi sp, sp, 64 #,,\nret.n\n
"},{"location":"Serial-to-TCP-Bridge/","title":"Serial to TCP Bridge","text":"This feature is included only in tasmota-zbbridge and tasmota-zbbrdgpro binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_TCP_BRIDGE \n#define USE_TCP_BRIDGE // Add support for Serial to TCP bridge (+1.3k code)\n#endif\n
Connect to a serial device over the network, also known as ser2net
This feature can be used to add a \"serial to network\" functionality to a device that is otherwise serial only. You connect the device to a ESP8266/ESP32 and Tasmota will bridge between serial and network.
This is commonly used with a CCxxxx Zigbee based module to connect it to a remote ZHA or zigbee2mqtt instance.
"},{"location":"Serial-to-TCP-Bridge/#commands","title":"Commands","text":" TCPBaudRate <x>: sets the baud rate for serial (only 8N1 mode), min 1200, max 115200 by 1200 increments.TCPStart <port>: listens to port <port>. This features supports 2 parallel TCP connections, which can be useful if you need a terminal + a specific protocol (like XMODEM). The 3rd connection will disconnect a previous connection. The number of parallel connections is a compile-time option. Note that this can be accessed by any host on the network and may have security implications.TCPStart <port>,<ip address>: listens to port <port>, but only allows connections from the provided IPv4 address. Any connections from a different host will be immediately closed.TCPStart 0 or TCPStart: shuts down the TCP server and disconnects any existing connection(s).
For security reasons, the TCP bridge is not started at boot, and requires an explicit TCPStart command (this can be automated with Rules).
"},{"location":"Serial-to-TCP-Bridge/#configuration","title":"Configuration","text":"First assign two GPIOs to TCP Tx (208) and TCP Rx (209) types in the \"Configure Module\" page. The Rx/Tx are relative to the ESP device. For example with ESP01's hardware serial, set GPIO1 as TCP Tx and GPIO3 as TCP Rx.
Then set baud rate with TCPBaudRate and port with TCPStart.
You can add a rule to start the TCP server at boot. To do this for port 8888 and allow connections only from host 192.168.0.10, run Rule1 ON System#Boot do TCPStart 8888,192.168.0.10 endon then enable with Rule1 1 and restart the device.
"},{"location":"Serial-to-TCP-Bridge/#additional-resources","title":"Additional resources","text":"PR Sonoff ZBBridge reference
"},{"location":"SetOption36/","title":"SetOption36","text":"SetOption36 is deprecated in favour of using the sleep command to use either Dynamic or Normal sleep as from Tasmota version 6.3.0.15.
Click here for Dynamic Sleep
"},{"location":"SetOption37/","title":"SetOption37","text":"SetOption37 is used for re-mapping the RGBWcWw channels. This transformation happens right before the hardware-specific output, so all the advanced features (schemes, hsb setting, etc.) works with the original, un-mapped values.
The main reason for this option is to provide support for bulbs whose physical wiring is almost the usual/standard one, but the channels are arranged in a different way.
For technical reasons this transformation isn't a full N-to-N mapping, it can only the re-arrange the channels, which is equivalent to map the (R,G,B,Wc,Ww) channels to one of their permutations.
The required permutation can be configured via SetOption37 n, where n is the systematic index of the permutation, a number from the [0 .. 119] interval, from 0=(R,G,B,Wc,Ww) to 119=(Ww,Wc,B,G,R):
Idx Perm. Idx Perm. Idx Perm. Idx Perm. 0 R,G,B,Wc,Ww 1 R,G,B,Ww,Wc 2 R,G,Wc,B,Ww 3 R,G,Wc,Ww,B 4 R,G,Ww,B,Wc 5 R,G,Ww,Wc,B 6 R,B,G,Wc,Ww 7 R,B,G,Ww,Wc 8 R,B,Wc,G,Ww 9 R,B,Wc,Ww,G 10 R,B,Ww,G,Wc 11 R,B,Ww,Wc,G 12 R,Wc,G,B,Ww 13 R,Wc,G,Ww,B 14 R,Wc,B,G,Ww 15 R,Wc,B,Ww,G 16 R,Wc,Ww,G,B 17 R,Wc,Ww,B,G 18 R,Ww,G,B,Wc 19 R,Ww,G,Wc,B 20 R,Ww,B,G,Wc 21 R,Ww,B,Wc,G 22 R,Ww,Wc,G,B 23 R,Ww,Wc,B,G 24 G,R,B,Wc,Ww 25 G,R,B,Ww,Wc 26 G,R,Wc,B,Ww 27 G,R,Wc,Ww,B 28 G,R,Ww,B,Wc 29 G,R,Ww,Wc,B 30 G,B,R,Wc,Ww 31 G,B,R,Ww,Wc 32 G,B,Wc,R,Ww 33 G,B,Wc,Ww,R 34 G,B,Ww,R,Wc 35 G,B,Ww,Wc,R 36 G,Wc,R,B,Ww 37 G,Wc,R,Ww,B 38 G,Wc,B,R,Ww 39 G,Wc,B,Ww,R 40 G,Wc,Ww,R,B 41 G,Wc,Ww,B,R 42 G,Ww,R,B,Wc 43 G,Ww,R,Wc,B 44 G,Ww,B,R,Wc 45 G,Ww,B,Wc,R 46 G,Ww,Wc,R,B 47 G,Ww,Wc,B,R 48 B,R,G,Wc,Ww 49 B,R,G,Ww,Wc 50 B,R,Wc,G,Ww 51 B,R,Wc,Ww,G 52 B,R,Ww,G,Wc 53 B,R,Ww,Wc,G 54 B,G,R,Wc,Ww 55 B,G,R,Ww,Wc 56 B,G,Wc,R,Ww 57 B,G,Wc,Ww,R 58 B,G,Ww,R,Wc 59 B,G,Ww,Wc,R 60 B,Wc,R,G,Ww 61 B,Wc,R,Ww,G 62 B,Wc,G,R,Ww 63 B,Wc,G,Ww,R 64 B,Wc,Ww,R,G 65 B,Wc,Ww,G,R 66 B,Ww,R,G,Wc 67 B,Ww,R,Wc,G 68 B,Ww,G,R,Wc 69 B,Ww,G,Wc,R 70 B,Ww,Wc,R,G 71 B,Ww,Wc,G,R 72 Wc,R,G,B,Ww 73 Wc,R,G,Ww,B 74 Wc,R,B,G,Ww 75 Wc,R,B,Ww,G 76 Wc,R,Ww,G,B 77 Wc,R,Ww,B,G 78 Wc,G,R,B,Ww 79 Wc,G,R,Ww,B 80 Wc,G,B,R,Ww 81 Wc,G,B,Ww,R 82 Wc,G,Ww,R,B 83 Wc,G,Ww,B,R 84 Wc,B,R,G,Ww 85 Wc,B,R,Ww,G 86 Wc,B,G,R,Ww 87 Wc,B,G,Ww,R 88 Wc,B,Ww,R,G 89 Wc,B,Ww,G,R 90 Wc,Ww,R,G,B 91 Wc,Ww,R,B,G 92 Wc,Ww,G,R,B 93 Wc,Ww,G,B,R 94 Wc,Ww,B,R,G 95 Wc,Ww,B,G,R 96 Ww,R,G,B,Wc 97 Ww,R,G,Wc,B 98 Ww,R,B,G,Wc 99 Ww,R,B,Wc,G 100 Ww,R,Wc,G,B 101 Ww,R,Wc,B,G 102 Ww,G,R,B,Wc 103 Ww,G,R,Wc,B 104 Ww,G,B,R,Wc 105 Ww,G,B,Wc,R 106 Ww,G,Wc,R,B 107 Ww,G,Wc,B,R 108 Ww,B,R,G,Wc 109 Ww,B,R,Wc,G 110 Ww,B,G,R,Wc 111 Ww,B,G,Wc,R 112 Ww,B,Wc,R,G 113 Ww,B,Wc,G,R 114 Ww,Wc,R,G,B 115 Ww,Wc,R,B,G 116 Ww,Wc,G,R,B 117 Ww,Wc,G,B,R 118 Ww,Wc,B,R,G 119 Ww,Wc,B,G,R Source: this spreadsheet
"},{"location":"Smart-Meter-Interface/","title":"Smart Meter Interface","text":""},{"location":"Smart-Meter-Interface/#smart-meter-interface","title":"Smart Meter Interface","text":"
This driver extracts selected values from Smart Meters over various protocols, filters and publishes them to MQTT as regular sensors.
This feature is not included in precompiled binaries
Based on Tasmota's scripting language. To use it you must compile your build. Add the following to user_config_override.h:
#ifndef USE_SCRIPT\n#define USE_SCRIPT\n#endif\n#ifndef USE_SML_M\n#define USE_SML_M\n#endif\n#ifdef USE_RULES\n#undef USE_RULES\n#endif\n
Additional features can be enabled by adding the following #define compiler directive parameters and then compiling the firmware. These parameters are explained further below in the article. Most features are now enabled by default, others may be set in the descriptor per meter.
Feature Description SML_BSIZ n (default 48) Maximum number of characters per line in serial input buffer. Complete chunk of serial data must fit into this size, so include any CR/LF if that applies. can now be defined per meter in descriptor, see special options MAX_METERS n (default 5) Maximum number of meters. Decrease this to 1 for example if you have a meter with many lines and lots of characters per descriptor line. TMSBSIZ n (default 256) Maximum number of characters in serial IRQ buffer (should always be larger than SML_BSIZ and even larger on high baud rates).can now be defined per meter in descriptor, see special options SML_DUMP_SIZE n (default 128) Maximum number of characters per line in dump mode. Only use if you have long strings comin in and they truncate. SML_PREFIX_SIZE n (default 8) Maximum number of characters + 1 for SML jsonPrefix. USE_ESP32_SW_SERIAL enables additional software serial channels for ESP32, (receive only), define pin with '-' sign to assign to software serial NO_USE_SML_SPECOPT disables special decoder entry to specify direction bit for some SML meters NO_USE_SML_SCRIPT_CMD disables some special SML script cmds and allows access to sml vars in other parts of the script. Is needed by some of the examples below. NO_SML_REPLACE_VARS disables replacement of any text in descriptor by script text variables. Useful if several occurrences of a text occupies a lot of space and you get short of script buffer. Readability may get worse so only makes sense on large descriptors. Note: to use % symbol un measurement units, you need to escape it like %%. NO_USE_SML_DECRYPT disables decoding of encrypted ams meters. decrypting needs TLS, so must define USE_TLS also. USE_SML_AUTHKEY enables authentication, this is not needed by most energy meters."},{"location":"Smart-Meter-Interface/#general-description","title":"General description","text":"To use this interface, connect the meter to available GPIO pins. These GPIOs must be set as None in Tasmota. If the interface detects that a script driven meter descriptor GPIO conflicts with a Tasmota GPIO setting, the interface will generate a duplicate GPIO defined error in the log and the meter descriptor will be ignored.
Note
When changing GPIO configurations, especially in conjunction with other Tasmota drivers, a restart may be required.
Note
On an ESP32, due to a different implementation, serial ports may not be used in conjunction with other Tasmota serial devices.
Note
when using bidirectional serial IO (receive and transmit), hardware serial is recommended.
The Smart Meter Interface provides a means to connect many kinds of meters to Tasmota. The following types of meter protocols are supported:
Protocol Description OBIS ASCII telegrams emitted from many smart meters, including P1 Smart Meters OBIS Binary SML telegrams emitted from many smart meters MODBus Binary telegrams used by many power meters and industrial devices Kamstrup Binary telegrams used by many power meters from Kamstrup EBus Binary telegrams emitted by many heaters and heat pumps (e.g. Vaillant, Wolf) VBus Binary telegrams emitted by many solar thermal systems boilers (e.g. Resol, Viessmann) RAW Binary decodes all kinds of binary data eg EMS heater bus Counter interface uses Tasmota counter storage (for e.g. REED contacts either in polling or IRQ mode) There are many different meters that use the same protocol. There are multitudes of variants and use cases. This interface provides a means of specifying these definitions through meter descriptors. This method uses the scripting language editor to define the descriptors. In this way, only one firmware binary version is required and a modification can be made easily on the fly.
Note
Additional hardware may be required to read certain measuring devices. For example: RS485toTTL adapter for Modbus, IR transistor for electricity meters. Sometimes an additional IR diode and resistors.
By default, a SENSOR telegram is sent to MQTT every 300 seconds. This can be adjusted by changing the TelePeriod.
"},{"location":"Smart-Meter-Interface/#descriptor-syntax","title":"Descriptor Syntax","text":"This section must be present, even if it's empty. If compiled with SML_REPLACE_VARS, here is the place where text variables can be defined for the script:
>D
Declare >B (boot) section to inform the interface to read the meter descriptor(s):
>B =>sensor53 r
(Optional) declare >S section with additional scripting commands:
>S <n>
Declare >M section with the number of connected meters (n = 1..5):
>M <n>
Note
If no >M section is found in the script or if the scripting language is not compiled, the driver reverts to the default hardcoded #define definitions. If no meter script is defined, the default hardcoded descriptor interface (deprecated) uses RX GPIO3 for receiving data and thus may interfere with other Tasmota Definitions without warning.
Note
Software serial only supports 8N1 serial format. Must use hardware serial for e.g. 8E1!
"},{"location":"Smart-Meter-Interface/#meter-definition","title":"Meter Definition","text":"+<M>,<rxGPIO>,<type>,<flag>,<parameter>,<jsonPrefix>{,<txGPIO>,<txPeriod>,<cmdTelegram>}
Parameter Description +<M> Meter number. The number must be increased with each additional Meter (default 1 to 5). <rxGPIO> The GPIO pin number where meter data is received. [xxx.xxx.xxx.xxx] IP number instead of pin number enables MODBUS TCP mode (tx pin can be any number and is ignored) <type> The type of meter: - o - OBIS ASCII type of coding- s - SML binary smart message coding- e - EBus binary coding- v - VBus binary coding- m - MODBus binary coding with serial mode 8N1- M - MODBus binary coding with serial mode 8E1- k - Kamstrup binary coding with serial mode 8N1- c - Counter type- r - Raw binary coding (any binary telegram) <flag> Options flag:- 0 - counter without pullup- 1 - counter with pullup- 16 - enable median filter for that meter. Can help with sporadic dropouts, reading errors (not available for counters). this option is enabled by default #define USE_SML_MEDIAN_FILTER, if you are low on memory and dont use this feature you may outcomment this define in the driver <parameter> Parameters according to meter type:- for o,s,e,v,m,M,k,r types: serial baud rate e.g. 9600.- for c type: a positive value = counter poll interval (not really recommended) or a negative value = debounce time (milliseconds) for irq driven counters. <jsonPrefix> Prefix for Web UI and MQTT JSON payload. Up to 7 characters. <txGPIO> The GPIO pin number where meter command is transmitted (optional). <tx enable> The GPIO pin number to enable transmitter (RS485) may follow the TX pin in bracket (pin) without a colon an 'i' in front of the pin number means 'inverted' (optional). <txPeriod> Period to repeat the transmission of commands to the meter (optional). Number of 100ms increments (n * 100ms). <cmdTelegram> Comma separated hex coded byte blocks to send to meter device. For MODBus each comma separated block is a command to retrieve a certain register from the meter (optional: only required for measuring devices that have to be triggered with a certain character string). Note
for other serial protocols you may specify the exact mode (only for hardware serial) by the following code after the type specifier:
N =no parity E =even parity O =odd parity and number of stop-bits
e.g for Modbus: mN1,mN2,mE1,mE2,mO1,mO2
Example
+1,3,o,0,9600,OBIS1,1,2,2F3F210D0A\n+1,3,o,0,9600,OBIS1,1(i4),2,2F3F210D0A with pin 4 as inverted TX enable\n+1,3,o,16,115200,NormalTariff,1\n+1,3,s,16,9600,SML1\n+1,12,c,1,-10,H20_Cnt\n+1,3,v,0,9600,Solar\n
Example
For MODBus: +1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010 Components of the character string: ...01040000,01040002,... 01 = Modbus slave device ID 04 = Instruction to read an Input Register (alternatively, 03 = Instruction to read a Holding Register) 0000/0002 = Register # (as Hexadecimal codification, without the prefix 0x. Example: 0x0079 -> 0079) the number of requested registers is fixed to 2, however with the char 'r' before the hex string the complete request string may be specified ...r010400000001,r010400020003,... Note: ID, Instruction to read the register value (Input vs Holding) and Register# may differ depending on the measuring device.
"},{"location":"Smart-Meter-Interface/#meter-metrics","title":"Meter Metrics","text":"Each meter typically provides multiple metrics (energy, voltage, power, current etc.) which it measures. An entry for each metric to be collected must be specified. An entry defines how to decode the data and put it into variables.
<M>,<decoder>@<scale><offs>,<label>,<UoM>,<var>,<precision>
Parameter Description <M> The meter number to which this decoder belongs <decoder> Decoding specification: OBIS as ASCII; SML, EBus, VBus, MODBus, RAW as HEX ASCII etc. No space characters allowed in this section! OBIS: ASCII OBIS code terminated with ( character which indicates the start of the meter valueCounter: ASCII code 1-0:1.8.0*255 for counter value, code 1-0:1.7.0*255 for pulse rate (e.g. for actual power value) SML: SML binary OBIS as hex terminated with 0xFF indicating start of SML encoded valueEBus, MODBus, RAW - hex values of data blocks to compare: - xx = ignore value (1 byte) or xN = ignore N bytes - ss = extract a signed byte - uu = extract an unsigned byte - UUuu = extract an unsigned word (high order byte first) - uuUU = extract an unsigned word (low order byte first) - UUuuUUuu = extract an unsigned long word (high order byte first) - uuUUuuUU = extract an unsigned long word (low order byte first) - SSss = extract a signed word (high order byte first) - ssSS = extract a signed word (low order byte first) - SSssSSss = extract a signed long word (high order byte first) - ssSSssSS = extract a signed long word (low order byte first) - on long word values, if a trailing s is added at the end of the mask, word order is reversed - bcdN = extract a binary coded decimal N=2..12 - ffffffff = extract a float value - IEEE754 decode - FFffFFff = extract a reverse float value - IEEE754 decode- kstr = decode KAMSTRUP data- pm(x.y.z) = pattern match(asci obis code)- pm(hHHHHHH) = pattern match(hex obis code)- pm(rHHHHHH) = pattern match(any hex pattern)if using VBus - hex values of data blocks to compare: - AAffffaddrff0001ffff = VBus-specific hex header: AA-sync byte, addr-the reversed address of the device. To find his out first look up the known hex address of the device. E.g. Resol DeltaSol BS Plus is 0x4221. Reverse it (without 0x) and you will get 21 42 hex characters. Now turn on raw dump mode using command sensor53 d1 and look for rows starting with aa, containing your reversed address at position 4 and 5 and 00 01 hex characters at position 7 and 8. If found, the entire header will be 10 hex characters long including aa (20 ascii chars without space, e.g. for Resol DeltaSol BS Plus this will be AA100021421000010774). At position 9 you see the number of frames containing readable data. To turn off raw dump use sensor53 d0. - v = VBus protocol indicator - oN = extract data from offset N (see offsets of your device in VBus protocol documentation) - u or s = extract unsigned or signed data - w or b = extract word or byteEnd of decoding: @ indicates termination of the decoding procedure.- ( following the @ character in case of obis decoder indicates to fetch the 2. value in brackets, not the 1. value. (e.g. to get the second value from an obis like 0-1:24.2.3(210117125004W)(01524.450*m3))- decoding multiple values coming in brackets after each other is possible with (@(0:1, (@(1:1, (@(2:1 and so on (e.g. to get values from an obis like 0-0:98.1.0(210201000000W)(000000.000*kWh)(000000.000*kWh))- decoding a 0/1 bit is indicated by a @ character followed by bx: (x = 0..7) extracting the corresponding bit from a byte. (e.g.: 1,xxxx5017xxuu@b0:1,Solarpump,,Solarpump,0)- in case of MODBus/Kamstrup, ix: designates the index (x = 0..n) referring to the requested block in the transmit section of the meter definition <scale> scaling factor (divisor) or string definitionThis can be a fraction (e.g., 0.1 = result * 10), or a negative value. When decoding a string result (e.g. meter serial number), use # character for this parameter (Note: only one string can be decoded per meter!). For OBIS, you need a ) termination character after the # character. <offs> optional offset must precede with + or - sign, note: offset is applied before scale! <label> web UI label (max. 23 characters) <UoM> unit of measurement (max. 7 characters) <var> MQTT label (max. 23 characters) <precision> number of decimal places. Add 16 to transmit the data immediately. Otherwise it is transmitted on TelePeriod only. Use ; character to comment lines in the script.
Put # character at the end to terminate M section of the script.
Example
(OBIS/SML/MODBus):
1,1-0:1.8.1*255(@1,Total consumption,KWh,Total_in,4` \n1,77070100010801ff@1000,W1,kWh,w1,4` \n1,010304UUuuxxxxxxxx@i0:1,Spannung L1,V,Voltage_L1,0` \n1,0:98.1.0(@(0:1,Havi adat, KWh,havi1,3`\n1,0:98.1.0(@(1:1,Havi adat, KWh,havi2,3`\n1,0:98.1.0(@(2:1,Havi adat, KWh,havi3,3`\n
OBIS: 1,1-0:0.0.0*255(@#),Meter Nr,, Meter_number,0
Counter: 1,1-0:1.8.0*255(@1000,consumption,KWh,Total_in,3) precision of 3, scale for 1000 pulses/kWh 1,1-0:1.7.0*255(@0.01667, power,W,Power_actual,0) actual power from pulse rate (in pulses/min) of counter meter, scale for 1 pulse/Wh (1 pulse/min => 60W; 1/60(=0.01667) (pulses/min)/W)
SML: 1,77078181c78203ff@#,Service ID,,Meter_id,0 1,1-0:1.8.0*255(@1,consumption,KWh,Total_in,4 precision of 4, transmitted only on TelePeriod 1,1-0:1.8.0*255(@1,consumption,KWh,Total_in,20 precision of 4, transmitted immediately (4 + 16 = 20)
MODBus: +1,3,M,1,9600,SBC,1,2,01030023,01030028... 1,010304UUuuxxxxxxxx@i0:1,Voltage L1,V,Voltage_L1,0 the i0:1 refers to: 01030023 with a scaling factor (:1) for 1 1,010304UUuuxxxxxxxx@i1:10,Current L1,V,Current_L1,2 the i1:10 refers to: 01030028 with a scaling factor (:10) for 10
Tip
Use: sensor53 dM to output the received data in the console. M = the number of the meter in the definition line. During the output of the data in the console, the data in the WEB UI are not updated. To return write: sensor53 d0
Tip
You can monitor the serial activity at a GPIO with a connected LED. This function is useful for debugging purposes and also to see data is coming in during normal operation. Usage: Enter the command sensor53 lx to activate this function (Lowercase L for LED). x is the number of the GPIO where the LED is connected. For example you can use sensor53 l2 for the onboard LED on a Wemos D1-mini or sensor53 l13 on a Sonoff Basic. sensor53 l255 turns the function off. This is the default value. With sensor53 mx you can choose which serial meter (x) will be monitored. Set sensor53 m0 will monitor all serial meters. This is the default value. To start the monitoring at boot-time, simply add the necessary entries in the boot-section (>B) of the script:
Example
>B\n=>sensor53 r\n=>sensor53 l13\n
"},{"location":"Smart-Meter-Interface/#special-commands","title":"Special Commands","text":"With = character at the beginning of a line you can do some special decoding. With * character fields can be hidden or skipped.
Command Description M,=m Perform arithmetic (+,-,*,/) on the measured data. Use # before a number to designate a constant value e.g. 1,=m 3+4+5/#3 @100,Voltage L1+L2+L3/3,V,Volt_avg,2 to sum results of decoder entries 3,4,5 and divide by 3 (average) M,=d Calculate difference between metric values decoded at time intervals (up to 10 =d lines possible) e.g. 1,=d 3 10 calculate 10 second interval difference of decoder entry 3 M,=h Insert text on the web interface (html text up to 30 chars). These lines do not count as decoder entry. e.g. 1,=h<hr/> to insert a separator line on the web UI * character To hide fields from result output or disable output completely. Compiling with USE_SML_SCRIPT_CMD required. - as single character in <label> of the metrics line will hide that value from the web UI - as single character in <label> of the meter definition line will suppress the entire JSON output on MQTT M,=so1 special SML option for meters that use a bit in the status register to sign import or export like ED300L, AS2020 or DTZ541 e.g. 1,=so1,00010800,65,11,65,11,00100700 for DTZ541 1. obis code that holds the direction bit, 2. Flag identifier, 3. direction bit, 4. second Flag identifier (some meters use 2 different flags), 5. second bit, 6 obis code of value to be inverted on direction bit. M,=so2 if 1 fixes the bug introduced by meter DWS74, if 2 enabled OBIS line compare mode instead of shift compare mode, if 4 invert hardware serial line.e.g. 1,=so2,2 enable obis line compare. M,=so3 sets serial buffer size, serial IRQ buffer size and serial dump buffer size.e.g. 1,=so3,512 set serial buffer size to 512. M,=so4 sets AES decrytion key for encrypted meters.must define exactly 16 hexadecimal charse.g. 1,=so4,deabcd0020a0cfdedeabcd0020a0cfde sets decryption key and enables decrypt mode for that meter. M,=so5 sets AES authentication key for encrypted meters.must define exactly 16 hexadecimal charse.g. not needed by most energy meters (needs USE_SML_AUTHKEY). M,=so6 sync time in milliseconds for serial block detection with AMS meters (defaults to 1000). M,=so7 on ESP32 force selection of UART Nr. X (0,1,2) allows coexistence with other serial drivers Example
To get the value of one of the descriptor lines, use sml[X]. X = Line number. Starts with 1. (compiling with USE_SML_SCRIPT_CMD required)
>D\nv1=0\nv2=0\n>S\n;Writes the value of Descriptorline 1 to v1\nv1=sml[1] \n;Writes the value of Descriptorline 2 to v2\nv2=sml[2]\n
Example
To disable and enable publishing of MQTT data on TelePeriod, use smlj=0 and smlj|=1, respectively. For example to skip first MQTT publishing after boot (may contain erroneous data at after restart if meter is slow, see Sanxing SX6x1):
>B\n;disable publishing at MQTT teleperiod, on boot\nsmlj=0\n>S\n;re-enable publishing at MQTT teleperiod, after 10 seconds of uptime\nif upsecs>10\nthen\nsmlj|=1\nendif\n
the variable smlj also switches to obis_line_mode if bit 1 = 1, default is 0 Example
If you have large meter descriptors and want to extract multiple values from the same descriptor, you can save flash space using SML_REPLACE_VARS at compile time (see Resol Deltasol BS Plus):
>D\n;define a text variable\nr=\"1,AA100021421000010774\"\n>M 1\n;in your meter definitions you can use your variable for the same descriptor\n+1,3,v,0,9600,Solar\n%r%vo12ut@#,time,,zeit,1\n%r%vo0uw@10,S1 COL,\u00b0C,sens1,1\n%r%vo2uw@10,S2 TST1,\u00b0C,sens2,1\n%r%vo4uw@10,S3 TST2,\u00b0C,sens3,1\n%r%vo6uw@10,S4 TR,\u00b0C,sens4,1\n;%r% inserts the text variable and saves script storage space (3 instead of 22 chars for each line)\n
Attention
With a few meters, it is necessary to request the meter to send data using a specific character string. This string has to be sent at a very low baud rate (300Baud). If you reply the meter with an acknowledge and ask the it for a new baud rate of 9600 baud, the baud rate of the SML driver has to be changed, too (see Landis + Gyr ZMR120AR).
To change the baud rate:
sml(METERNUMBER 0 BAUDRATE)
For sending a specific character string:
sml(METERNUMBER 1 STRING)
And it works like this:
>D\nres=0 \nscnt=0 \n;For this Example in the >F section \n>F\n;count 100ms \nscnt+=1 \nswitch scnt \ncase 6 \n;set sml driver to 300 baud and send /?! as HEX to trigger the Meter \nres=sml(1 0 300) \nres=sml(1 1 \"2F3F210D0A\") \n;1800ms later \\> Send ACK and ask for switching to 9600 baud \ncase 18 \nres=sml(1 1 \"063035300D0A\") \n;2000ms later \\> Switching sml driver to 9600 baud \ncase 20 \nres=sml(1 0 9600) \n;Restart sequence after 50x100ms \ncase 50 \n; 5000ms later \\> restart sequence \nscnt=0 \nends \n>M 1\n+1,3,o,0,9600, ,1 \n;...etc. \n
Note: This procedure is only necessary, if the meter explicitly asks for 300 baud. The most meters work directly with 9600 baud. Therefore it is easier to give this method a try (see Iskra MT 174):
Meter#,GPIO# Input,TYPE,FLAG,Baudrate,JSONNAME,GPIO# Output,TX Period,Character string +1,3,o,0,9600,energy,1,4,2F3F210D0A
Tip
If you use a Wemos D1 Mini you could compile a 4M flash image with filesystem support so your script will survive upgrades and factory resets. To do this, create a new entry in platformio_tasmota_env.ini:
[env:tasmota-4mb]\nboard_build.ldscript = eagle.flash.4m2m.ld\n
Add tasmota-4mb to platformio.ini's build variants. Add the following to user_config_override.h:
#undef MODULE\n#define MODULE WEMOS\n#define USE_UFILESYS\n#define GUI_TRASH_FILE\n
Also recommended, if you use lots of vars and increased buffer sizes to free up the image from unused drivers. You should get some inspiration from the tasmota-lite image definition in tasmota_configurations.h. Tip
You can dump to your PC the raw data coming in if you use the module's hardware serial ports (1 and 3) as GPIOs of the script, using Serial to TCP Bridge. Compile your firmware with USE_TCP_BRIDGE, disable the script and configure in module parameters TCP Tx and TCP Rx. After module reboot, start the server with command TCPStart 8888. Connect to this port from your PC to see or dump the data, in Linux it's as easy as cat < /dev/tcp/IP.OF.YOUR.TASMOTA/8888 > rawdump.txt. To revert to SML you need to set back both GPIO ports to None, enable the script and restart.
"},{"location":"Smart-Meter-Interface/#commands","title":"Commands","text":" - sensor53 r = resets the sml driver, must be applied in script >B section
- sensor53 cx num = sets counter x (1 or 2) to number (persistent change)
- sensor53 dm = sets dump mode for meter m (1...N), must be set to 0 for normal operation
- sensor53 l x = set an optional LED GPIO pin to indicate serial activity of a meter, set to 255 for disable
- sensor53 m x = sets the meter from which to show activity via the l cmd
"},{"location":"Smart-Meter-Interface/#smart-meter-descriptors","title":"Smart Meter Descriptors","text":""},{"location":"Smart-Meter-Interface/#abb-b23-modbus","title":"ABB B23 (MODBus)","text":"Meter is basically the same as Janitza B23 with the same interface. It's just missing whole section of registers which are used in Janitza B23 example.
Beware that A and B MODBus connectors are switched!
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,m,0,9600,ABB,1,10,01035B00,01035B02,01035B04,01035B14,01035B16,01035B18,01035B1A,r010350080004,r010350000004,r010350040004\n1,010304UUuuUUuu@i0:10,Voltage L1-N,V,Voltage_L1,1\n1,010304UUuuUUuu@i1:10,Voltage L2-N,V,Voltage_L2,1\n1,010304UUuuUUuu@i2:10,Voltage L3-N,V,Voltage_L3,1\n1,010304SSssSSss@i3:100,Active power Total,W,Active_power_Total,2\n1,010304SSssSSss@i4:100,Active power L1-N,W,Active_power_L1,2\n1,010304SSssSSss@i5:100,Active power L2-N,W,Active_power_L2,2\n1,010304SSssSSss@i6:100,Active power L3-N,W,Active_power_L3,2\n1,010308xxxxxxxxSSssSSss@i7:100,Real energy,kWh,Real_energy,2\n1,010308xxxxxxxxUUuuUUuu@i8:100,Real energy consumed,kWh,Real_energy_consumed,2\n1,010308xxxxxxxxUUuuUUuu@i9:100,Real energy delivered,kWh,Real_energy_delivered,2\n#\n
"},{"location":"Smart-Meter-Interface/#abb-b-series-like-b21-b23-m-bus-over-infrared-port","title":"ABB B-Series (like B21, B23) (M-Bus over Infrared port)","text":"Using the IR Port on left side of the device. The IR interface does NOT support MODBUS, only M-Bus (Meter Bus) and EQ-Bus protocol. Configure the IR output at the device menu. This example is using 9600 baud and address 10h (16 decimal) for the meter. The meter is using equal parity 1 stop bit 9600E1 The upper diode is TX the lower RX. My device is sending always 2 telegrams. I tried to add additional values by sending SND_UD telegram. I only receive the e5 response showing that the request was accepted. No change in response. The last telegram will end on a \"0F xx 16\" instead of a \"1F xx 16\", which will show that additional telegrams are available. If you can receive more telegrams, add alternating 107b108b16 - 105b106b16. One for each telegram. This example will only work with address 10! the second last byte is a check sum. For this REQ_UD2 it is the sum of the 2 bytes before (Address and VIF).
View script >M 1\n+1,3,rE1,0,9600,ABB,1,10,1040105016,107b108b16,105b106b16[,107b108b16[,105b106b16]] \n1,081072bcd8@1,Meter ID,,ID,0 ; meter ID (BCD-8)\n1,0E8400bcd8@100,E Imp total,kWh,Imp,2 ; Total imported energy 0.01 kWh\n1,04A900ssSSssSSs@100,P total,W,P_tot,2 ; Total Power 0.01 W\n1,04A9FF8100ssSSssSSs@100,P L1,W,P_L1,2 ; L1 Power 0.01 W\n1,04A9FF8200ssSSssSSs@100,P L2,W,P_L2,2 ; L2 Power 0.01 W\n1,04A9FF8300ssSSssSSs@100,P L3,W,P_L3,2 ; L3 Power 0.01 W\n1,04FDC8FF8100uuUUuuUUs@10,U L1,V,U_L1,1 ; Voltage L1 0.1 V\n1,04FDC8FF8200uuUUuuUUs@10,U L2,V,U_L2,1 ; Voltage L2 0.1 V\n1,04FDC8FF8300uuUUuuUUs@10,U L3,V,U_L3,1 ; Voltage L3 0.1 V\n1,0AFFD900bcd4@100,*,Hz,F,2 ; Frequency\n1,0E84FF8100bcd8@100,E Imp L1,kWh,Imp-L1,2 ; L1 imported energy 0.01 kWh\n1,0E84FF8200bcd8@100,E Imp L2,kWh,Imp-L2,2 ; L2 imported energy 0.01 kWh \n1,0E84FF8300bcd8@100,E Imp L3,kWh,Imp-L3,2 ; L3 imported energy 0.01 kWh\n#\n
"},{"location":"Smart-Meter-Interface/#apator-apox-sml","title":"Apator APOX+ (SML)","text":"Energy provider supplied a PIN code to enable output of additional data.
View script >D \n>B \n->sensor53 r\n>M 1 \n+1,3,s,0,9600,SML\n1,77070100010801ff@1000,Verbrauch_Tarif_1,kWh,Total_Tarif1,3\n1,77070100010802ff@1000,Verbrauch_Tarif_2,kWh,Total_Tarif2,3\n1,77070100010800ff@1000,Verbrauch_Summe,kWh,Total_Summe,3\n1,77070100100700ff@1,Current consumption,W,Power_curr,3\n1,=h ---- \n1,770701001f0700ff@1,Current L1,A,Curr_p1,3 \n1,77070100330700ff@1,Current L2,A,Curr_p2,3 \n1,77070100470700ff@1,Current L3,A,Curr_p3,3 \n1,=h ---- \n1,77070100200700ff@1,Voltage L1,V,Volt_p1,3 \n1,77070100340700ff@1,Voltage L2,V,Volt_p2,3 \n1,77070100480700ff@1,Voltage L3,V,Volt_p3,3\n#\n
"},{"location":"Smart-Meter-Interface/#carlo-gavazzi-em340-modbus-rtu","title":"Carlo Gavazzi EM340 (MODBUS RTU)","text":"View script >D\n>B\n->sensor53 r\n;->sensor53 d1\n>M 1\n+1,13,m,0,115200,MODBUS,12,2,01030000,01030002,01030004,0103000C,0103000E,01030010,01030012,01030014,01030016,01030018,0103001A,0103001C,0103001E,01030020,01030022,01030034,01030038,0103002e,0103002f,01030030,0103004e\n1,010304SSssSSsss@i0:10,Voltage L1,V,Voltage_L1,1\n1,010304SSssSSsss@i1:10,Voltage L2,V,Voltage_L2,1\n1,010304SSssSSsss@i2:10,Voltage L3,V,Voltage_L3,1\n1,010304SSssSSsss@i3:1000,Current L1,A,Current_L1,3\n1,010304SSssSSsss@i4:1000,Current L2,A,Current_L2,3\n1,010304SSssSSsss@i5:1000,Current L3,A,Current_L3,3\n1,010304SSssSSsss@i6:10,Power L1,W,Power_L1,1\n1,010304SSssSSsss@i7:10,Power L2,W,Power_L2,1\n1,010304SSssSSsss@i8:10,Power L3,W,Power_L3,1\n1,010304SSssSSsss@i9:10,Power VA L1,VA,Power_va_L1,1\n1,010304SSssSSsss@i10:10,Power VA L2,VA,Power_va_L2,1\n1,010304SSssSSsss@i11:10,Power VA L3,VA,Power_va_L3,1\n1,010304SSssSSsss@i12:10,Power var L1,var,Power_var_L1,1\n1,010304SSssSSsss@i13:10,Power var L2,var,Power_var_L2,1\n1,010304SSssSSsss@i14:10,Power var L3,var,Power_var_L3,1\n1,010304SSssSSsss@i15:10,Energy Tot,kWh,Energy_Tot,1\n1,010304SSssSSsss@i16:10,Energy Demand,W,Energy_Demand,1\n1,010304SSss@i17:1000,PF L1,PF,PF_L1,1\n1,010304SSss@i18:1000,PF L2,PF,PF_L2,1\n1,010304SSss@i19:1000,PF L3,PF,PF_L3,1\n1,010304SSssSSsss@i20:10,Energy Tot Export,kWh,Energy_Tot_Export,1\n#\n
"},{"location":"Smart-Meter-Interface/#combo-meter-water-gas-sml","title":"COMBO Meter (Water, Gas, SML)","text":"View script >D \n>B \n->sensor53 r\n>M 3 \n+1,1,c,0,10,H20 \n+2,4,c,0,50,GAS \n+3,3,s,0,9600,SML \n1,1-0:1.8.0*255(@10000,Water reading,cbm,Count,4 \n2,=h================== \n2,1-0:1.8.0*255(@100,Gas reading,cbm,Count,3 \n3,77070100010800ff@1000,Total consumption,KWh,Total_in,3 \n3,=h================== \n3,77070100100700ff@1,Current consumption,W,Power_curr,2 \n3,=h ---- \n3,=m 10+11+12 @100,Currents L1+L2+L3,A,Curr_summ,2 \n3,=m 13+14+15/#3 @100,Voltage L1+L2+L3/3,V,Volt_avg,2 \n3,=h================== \n3,77070100240700ff@1,Consumption P1,W,Power_p1,2 \n3,77070100380700ff@1,Consumption P2,W,Power_p2,2 \n3,770701004c0700ff@1,Consumption P3,W,Power_p3,2 \n3,=h ---- \n3,770701001f0700ff@100,Current L1,A,Curr_p1,2 \n3,77070100330700ff@100,Current L2,A,Curr_p2,2 \n3,77070100470700ff@100,Current L3,A,Curr_p3,2 \n3,=h ---- \n3,77070100200700ff@100,Voltage L1,V,Volt_p1,2 \n3,77070100340700ff@100,Voltage L2,V,Volt_p2,2 \n3,77070100480700ff@100,Voltage L3,V,Volt_p3,2 \n3,=h================== \n3,77070100000009ff@#,Service ID,,Meter_id,0 \n3,=h \n# \n
"},{"location":"Smart-Meter-Interface/#ddm18sd-modbus","title":"DDM18SD (MODBus)","text":"This script, based on tasmota scripting language, is to read data on a unsupported DDM18SD power meter. It has 8E1 parity and the slave ID address is n 5. On a Nodemcu or Wemos D1 board, put wires between GPIO3 and GPIO1 to the RX and TX pinout of a RS485 to TTL board, but leave empty (none) the GPIO Tasmota software settings. A & B connected to the meter pinout.
View script >B \n->sensor53 r\n>M 1 \n+1,3,M,0,9600,DDM,1,2,05040000,05040008,05040012,0504001A,05040036,0504002A,05040100,05040400\n1,050404ffffffff@i0:1,Tensione,V,DDM_Voltage,2 \n1,050404ffffffff@i1:1,Corrente,A,DDM_Current,2 \n1,050404ffffffff@i2:1,Consumo Ist.,W,DDM_Power,2\n1,050404ffffffff@i3:1,Reactive power,Var,DDM_React_Power,2\n1,050404ffffffff@i4:1,Frequenza,Hz,DDM_Frequency,2 \n1,050404ffffffff@i5:1,Power factor,,DDM_PF,2\n1,050404ffffffff@i6:1,Consumi tot.,Kwh,DDM_Tot_Power,2\n1,050404ffffffff@i7:1,Tot. react. power,Kvarh,DDM_Reac_Power,2\n#\n
"},{"location":"Smart-Meter-Interface/#digimeto-gs303-sml","title":"Digimeto GS303 (SML)","text":"View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,GS303\n1,77070100010800ff@1000,Total Consumed,KWh,Total_in,3\n1,77070100100700ff@1,Current Consumption,W,Power_cur,0\n1,77070100020800ff@1000,Total Delivered,KWh,Total_out,3\n1,7707010060320101@#,Service ID,,Meter_id,0\n# \n
"},{"location":"Smart-Meter-Interface/#dzg-dws74102vg2-sml-and-dzg-dvs74202-sml","title":"DZG DWS7410.2V.G2 (SML) and DZG DVS7420.2 (SML)","text":"A bidirectional metering device from DZG Metering GmbH.
Once unlocked with a PIN and set to Inf on, the meter returns not only an integer of the total consumption, but an extended dataset which also includes decimals as well as the current power.
View script for the extended dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7410\n1,77070100010800ff@1000,Energie,kWh,energy,4\n1,77070100020800ff@1000,Lieferung,kWh,en_out,4\n1,77070100100700ff@1,Leistung,W,power,2\n1,7707010060320101@#,SID,,meter_id,0\n#\n
The script was derived from the DZG DWS76 (SML) device below and extended by the delivered energy. The lines for meter_id, unknown and meter_number were reduced to one line for meter_id because all values were identical.
For Inf off, a simplified dataset is returned only.
Alternative script for the simplified dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7410\n1,77070100010800ff@1000,Energie,kWh,energy,0\n1,7707010060320101@#,Service ID,,meter_id,0\n1,77010b0a01445a47@#,Unbekannt,,unknown,0\n1,77070100600100ff@#,Z\u00e4hlernummer,,meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#dzg-dws74121g2-sml","title":"DZG DWS7412.1.G2 (SML)","text":"A uni-directional metering device from DZG Metering GmbH.
Once unlocked with a PIN and set to Inf on, the meter returns not only an integer of the total consumption, but an extended dataset which also includes decimals as well as the current power.
View script for the extended dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7412\n1,77070100010800ff@1000,Energy,kWh,energy,4\n1,77070100240700ff@1,Power,W,power,2\n1,7707010060320101@#,Service ID,,meter_id,0\n#\n
For Inf off, a simplified dataset is returned only.
Alternative script for the simplified dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7412\n1,77070100010800ff@1000,Energy,kWh,energy,4\n1,7707010060320101@#,Service ID,,meter_id,0\n#\n
"},{"location":"Smart-Meter-Interface/#dzg-dws76-sml","title":"DZG DWS76 (SML)","text":"Should also be applicable to many other DZG Metering GmbH meters, like DVS76, DVS74, DWS74 or in general DxS7x - not tested though.
Once unlocked with a PIN and set to Inf on, the meter returns not only an integer of the total consumption, but an extended dataset which also includes decimals as well as the current power. Further values unknown yet.
View script for the extended dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7612\n1,77070100010800ff@1000,Energie,kWh,energy,4\n1,77070100100700ff@1,Leistung,W,power,2\n1,7707010060320101@#,Service ID,,meter_id,0\n1,77010b0a01445a47@#,Unbekannt,,unknown,0\n1,77070100600100ff@#,Z\u00e4hlernummer,,meter_number,0\n# \n
For Inf off, a simplified dataset is returned only.
Alternative script for the simplified dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWS7612\n1,77070100010800ff@1000,Energie,kWh,energy,0\n1,7707010060320101@#,Service ID,,meter_id,0\n1,77010b0a01445a47@#,Unbekannt,,unknown,0\n1,77070100600100ff@#,Z\u00e4hlernummer,,meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#dzg-dwsb122-sml","title":"DZG DWSB12.2 (SML)","text":"For Inf off, a simplified dataset is returned. The energy meter does have 2 meters, one for incoming and outgoing power. If you have a solar panel installed and you are delivering power to the network the second value will increase appropriately.
Alternative script for the simplified dataset >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,DWSB122\n1,77070100010800ff@1000,Energie bezogen,kWh,energy,0\n1,77070100020800ff@1000,Energie geliefert,kWh,energy,0\n1,7707010060320101@#,Service ID,,meter_id,0\n1,77010b0a01445a47@#,Unbekannt,,unknown,0\n1,77070100600100ff@#,Z\u00e4hlernummer,,meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#easymeter-q3a-apator-apox-sml","title":"EasyMeter Q3A / Apator APOX+ (SML)","text":"A 2-Tariff Meter which for Example SWM (Stadtwerke M\u00fcnchen) oder DGY (Discovergy) uses. Unfortunately this Version sends only whole kWh (precision 0) without PIN. With PIN behaviour changes and high resolution is available as seen below (e.g. precision 7 for consumption/kWh, precision 2 for power/W, precision 1 for voltage/V).
Apator APOX+ behaves same as the EasyMeter while pin locked, just precision 0 without additional data. After calling the energy provider they send a letter with the unlock pin.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,SML\n1,77070100010801ff@1000,Verbrauch_Tarif_1,kWh,Verbrauch_T1,7\n1,77070100010802ff@1000,Verbrauch_Tarif_2,kWh,Verbrauch_T2,7\n1,77070100010800ff@1000,Verbrauch_Summe,kWh,Verbrauch_Summe,7\n1,77070100020800ff@1000,Einspeisung_Summe,kWh,Einspeisung_Summe,7\n1,=h-- \n1,77070100240700ff@1,Leistung_L1,W,Watt_L1,2\n1,77070100380700ff@1,Leistung_L2,W,Watt_L2,2\n1,770701004c0700ff@1,Leistung_L3,W,Watt_L3,2\n1,77070100100700ff@1,Leistung_Summe,W,Watt_Summe,2\n1,=h-- \n1,77070100200700ff@1,Spannung_L1,V,Volt_L1,1\n1,77070100340700ff@1,Spannung_L2,V,Volt_L2,1\n1,77070100480700ff@1,Spannung_L3,V,Volt_L3,1\n#\n
"},{"location":"Smart-Meter-Interface/#easymeter-q3b-sml","title":"EasyMeter Q3B (SML)","text":"Two separate 2-Tariff meters (e.g. from Fairenergie Reutlingen) are readout by the same Tasmota device. The first one is for general purpose and is connected to GPIO14. The JSON prefix is set to Power. The second one is for the heat pump and connected to GPIO13. The JSON prefix is set to Pump. For both meters, tariff 1 & 2 are rounded kWh (precision 0), actual consumption in W has a higher precision (1).
View script >D\n>B\n=>sensor53 r\n>M 2\n+1,14,s,0,9600,Power\n1,77070100010801ff@1000,Tarif 1,kWh,Power_T1,0\n1,77070100010802ff@1000,Tarif 2,kWh,Power_T2,0\n1,77070100010800ff@1000,Summe,kWh,Power_Sum,0\n1,77070100010700ff@1000,Verbrauch,W,Power_Use_Sum,1\n+2,13,s,0,9600,Pump\n2,77070100010801ff@1000,Tarif 1,kWh,HP_T1,0\n2,77070100010802ff@1000,Tarif 2,kWh,HP_T2,0\n2,77070100010800ff@1000,Summe,kWh,HP_Sum,0\n2,77070100010700ff@1000,Verbrauch,W,HP_Use_Sum,1 \n#\n
"},{"location":"Smart-Meter-Interface/#easymeter-q3d-q3da1024-obis","title":"EasyMeter Q3D, Q3DA1024 (OBIS)","text":"The Q3D is a three-phase model energy meter, which was sold in a number of different configurations. This is a legacy device, however still available new in some shops. The most popular model seems to be the two-direction model for solar power metering. The D0 port is read-only with a fixed time interval of two seconds. The communication settings are unusual: 7 data bits, even parity, one stop bit, 9600 baud (9600 7E1).
Because the 7E1 serial mode is not supported by Tasmota software serial, the hardware serial port must be used, i.e. GPIO 3. This will /not/ work using GPIO 0 or 2.
Also, the source code has to be patched from 8N1 to 7E1 mode for the hardware serial in file src/TasmotaSerial.cpp, please see the patch further down below. Since Tasmota 9.5.0 the serial mode can be changed in the console by typing SerialConfig 7E1 without having to patch TasmotaSerial.
Example reading of the two-direction model using GPIO 3 - P_in power reading will be negative in case of inverse power flow: >D\n>B\n=>sensor53 r\n>M 1\n+1,12,o,0,9600,SML,1\n1,1-0:1.7.255*255(@1,P_in,W,P_in,18\n1,1-0:21.7.255*255(@1,L1,W,L1,18\n1,1-0:41.7.255*255(@1,L2,W,L2,18\n1,1-0:61.7.255*255(@1,L3,W,L3,18\n1,1-0:1.8.0*255(@1,E_in,kWh,E_in,19\n1,1-0:2.8.0*255(@1,E_out,kWh,E_out,19\n1,1-0:0.0.0*255(@1,Netzbetreiber-ID,,NetID,0\n1,0-0:96.1.255*255(@#),Seriennummer,,serial,0\n#\n
Alternative script running on a Wemos D1 mini on hardware serial pin 3 for the Q3DB1024 two direction >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,9600,Haupt,1\n1,1-0:1.7.0*255(@1,P_in,W,P_in,18\n1,1-0:1.8.0*255(@1,E_in,kWh,E_in,19\n1,1-0:2.8.0*255(@1,E_out,kWh,E_out,19\n1,1-0:21.7.0*255(@1,L1,W,L1,18\n1,1-0:41.7.0*255(@1,L2,W,L2,18\n1,1-0:61.7.0*255(@1,L3,W,L3,18\n1,1-0:0.0.0*255(@1,Netzbetreiber-ID,,NetID,0\n1,0-0:96.1.255*255(@#),Seriennummer,,serial,0\n# \n
Apply following patch to src/TasmotaSerial.cpp --- a/lib/default/TasmotaSerial-3.2.0/src/TasmotaSerial.cpp\n+++ b/lib/default/TasmotaSerial-3.2.0/src/TasmotaSerial.cpp\n@@ -117,7 +117,7 @@ bool TasmotaSerial::begin(long speed, int stop_bits) {\nif (2 == m_stop_bits) {\nSerial.begin(speed, SERIAL_8N2);\n} else {\n- Serial.begin(speed, SERIAL_8N1);\n+ Serial.begin(speed, SERIAL_7E1);\n}\nif (m_hardswap) {\nSerial.swap();\n
"},{"location":"Smart-Meter-Interface/#ebz-dd3-obis","title":"eBZ DD3 (OBIS)","text":"The eBZ DD3 by eBZ GmbH is a three-phase model energy meter, which is sold in a number of different configurations. The D0 port is read-only with a fixed time interval of one second.
There are two communication interfaces: * The INFO interface on the front, with a metal backplate. Pushes a reduces OBIS ASCI datagram every second. * The MSB interface on the top, no metal backplate. Pushes a full OBIS ASCI datagram every second.
There are two types available using different communication settings: * OD-type: 7 data bits, even parity, one stop bit, 9600 baud (9600 7E1) * SM-type: 8 data bits, no parity, one stop bit, 9600 baud (9600 8N1)
Tested with an eBZ DD3 2R06 ODZ1 (two-direction model for e. g. solar power metering).
Because the 7E1 serial mode is not supported by Tasmota software serial, the hardware serial port must be used, i.e. GPIO 3. This will /not/ work using GPIO 0 or 2.
Change the serial mode in the console by typing SerialConfig 7E1.
Example reading of the two-direction model using GPIO 3:
- \"TelePeriod 30\" sets telemetry period to 30 seconds (remove if not needed/wanted)
- Values for ?6.7.0 (power) are transmit immediately (precision + 16)
- power readings will be negative in case of inverse power flow
View script >D\n>B\nTelePeriod 30\n=>sensor53 r\n>M 1\n; Device: eBZ DD3 2R06 ODZ1\n; protocol is D0 OBIS ASCII\n; 9600@7E1 for OP-type devices, 9600@8N1 for SM-type devices\n+1,3,o,0,9600,SM,1\n; Z\u00e4hlerstand zu +A, tariflos, \n; Z\u00e4hlerst\u00e4nde Aufl\u00f6sung 10 \u00b5W*h (6 Vorkomma- und 8 Nachkommastellen)\n1,1-0:1.8.0*255(@0.001,Energie Bezung,Wh,1_8_0,8\n; Z\u00e4hlerstand zu +A, Tarif 1\n1,1-0:1.8.1*255(@0.001,Energie Bezung T1,Wh,1_8_1,8\n; Z\u00e4hlerstand zu +A, Tarif 2\n1,1-0:1.8.2*255(@0.001,Energie Bezung T2,Wh,1_8_2,8\n; Z\u00e4hlerstand zu -A, tariflos\n1,1-0:2.8.0*255(@0.001,Energie Export,Wh,2_8_0,8\n; Summe der Momentan-Leistungen in allen Phasen, Aufl\u00f6sung 0,01W (5 Vorkomma- und 2 Nachkommastellen)\n1,1-0:16.7.0*255(@1,Leistung,W,16_7_0,18\n; Momentane Leistung in Phase Lx, Aufl\u00f6sung 0,01W (5 Vorkomma- und 2 Nachkommastellen)\n1,1-0:36.7.0*255(@1,Leistung L1,W,36_7_0,18\n1,1-0:56.7.0*255(@1,Leistung L2,W,56_7_0,18\n1,1-0:76.7.0*255(@1,Leistung L3,W,76_7_0,18\n; Spannung in Phase Lx, Aufl\u00f6sung 0,1V (nur \u00fcber MSB)\n1,1-0:32.7.0*255(@1,Spannung L1,V,32_7_0,1\n1,1-0:52.7.0*255(@1,Spannung L2,V,52_7_0,1\n1,1-0:72.7.0*255(@1,Spannung L3,V,72_7_0,1\n; Statuswort, 4 Byte Information \u00fcber den Betriebszustand, HEX string\n; tasmota can decode one string per device only!\n;1,1-0:96.5.0*255(@#),Status1,,96_5_0,0\n;1,1-0:96.8.0*255(@#),Status2,,96_8_0,0\n; Ger\u00e4te-Identifikation, Nach DIN 43863-5 \n1,1-0:96.1.0*255(@#),Identifikation,,96_1_0,0\n;1,1-0:0.0.0*255(@#),Identifikation,,0_0_0,0\n#\n
For the SM-type meter DD3 2R06 DTA SMZ1 the following script worked without having to apply the above patch, because it uses 8N1 for communication >D\n>B\n;TelePeriod 30\n=>sensor53 r\n>M 1\n; Device: eBZ DD3 2R06 DTA SMZ1\n; protocol is D0 SML HEX\n; 9600@7E1 for OP-type devices, 9600@8N1 for SM-type devices\n+1,3,s,0,9600,SML,1\n; Z\u00e4hlerstand zu +A, tariflos, \n; Z\u00e4hlerst\u00e4nde Aufl\u00f6sung 10 \u00b5W*h (6 Vorkomma- und 8 Nachkommastellen)\n1,77070100010800FF@100000000,Energie Bezug,kWh,1_8_0,8\n; Z\u00e4hlerstand zu +A, Tarif 1\n1,77070100010801FF@100000000,Energie Bezug T1,kWh,1_8_1,8\n; Z\u00e4hlerstand zu +A, Tarif 2\n1,77070100010802FF@100000000,Energie Bezug T2,kWh,1_8_2,8\n; Z\u00e4hlerstand zu -A, tariflos\n1,77070100020800FF@100000000,Energie Export,kWh,2_8_0,8\n; Summe der Momentan-Leistungen in allen Phasen, Aufl\u00f6sung 0,01W (5 Vorkomma- und 2 Nachkommastellen)\n1,77070100100700FF@1,Leistung,W,16_7_0,16\n; Momentane Leistung in Phase Lx, Aufl\u00f6sung 0,01W (5 Vorkomma- und 2 Nachkommastellen)\n1,77070100240700FF@1,Leistung L1,W,36_7_0,16\n1,77070100380700FF@1,Leistung L2,W,56_7_0,16\n1,770701004C0700FF@1,Leistung L3,W,76_7_0,16\n; Spannung in Phase Lx, Aufl\u00f6sung 0,1V (nur \u00fcber MSB)\n;1,77070100200700FF@1,Spannung L1,V,32_70,1\n;1,77070100340700FF@1,Spannung L2,V,52_7_0,1\n;1,77070100480700FF@1,Spannung L3,V,72_7_0,1\n; Statuswort, 4 Byte Information \u00fcber den Betriebszustand, HEX string\n; tasmota can decode one string per device only!\n;1,1-0:96.5.0*255@#),Status1,,96_5_0,0\n;1,1-0:96.8.0*255@#),Status2,,96_8_0,0\n; Ger\u00e4te-Identifikation, Nach DIN 43863-5 \n1,77070100000009FF@#),Identifikation,,96_1_0,0\n;1,77070100000000FF@#),Identifikation,,0_0_0,0\n#\n
"},{"location":"Smart-Meter-Interface/#easymeter-q1a-sml","title":"EasyMeter Q1A (SML)","text":"The Q1A series of EasyMeter is available as one- or two-way meter, with and without backstop respectively. It is also available as single or dual tariff meter. The script below works for the Q1Ax1054 variant. This variant is a single-tariff one-way meter with a backstop mechanism. The script only reads two values: the energy counter value and the current power value.
The meter has no bidirectional IR-communication port, only an \"INFO-DSS\" send-only IR-LED. It also has no metal plate to attach a magnet so the IR reader has to be attached in another way.
The current power and counter in high resolution are available after PIN entry with a flashlight, see manual.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,16,9600,SML\n1,77070100010800ff@1000,Zaehlerstand,kWh,Counter,6\n1,77070100100700ff@1,Verbrauch,W,Power,1\n#\n
"},{"location":"Smart-Meter-Interface/#easymeter-q1d-ascii-obis","title":"EasyMeter Q1D (ASCII OBIS)","text":"This script is for the EasyMeter Q1DB1004 variant of the Q1D series. This variant is a one-phase one-way electricity counter with a backstop mechanism.
Therefore the script reads only two values: the energy counter value and the power value. The power value is positive when you are drawing power from the public grid, and negative when you are feeding power to the public grid. Due to the backstop mechanism, the energy counter value will not decrease when you feed power to the public grid.
The meter's manufacturer's datasheet neatly explains the serial message format used, so you can easily adapt the code below to your EasyMeter Q1D, e.g. if you have a two-way counter variant like the EasyMeter Q1DA1026.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,9600,SML\n1,1-0:1.8.0*255(@1,EC_CounterVal,kWh,EC_CounterVal,4\n1,1-0:61.7.255*255(@1,EC_PowerVal,W,EC_PowerVal,0\n#\n
According to the manufacturer's datasheet, the serial parameters are 9600 baud and 7E1.
For Tasmota versions that are built with a TasmotaSerial.cpp of version 3.5.0 (and probably all higher versions, too), no modification of the TasmotaSerial.cpp source code (as suggested in other entries of this documentation) is necessary to set the serial parameters to 7E1: By configuring the meter type as OBIS (\"o\") in line 5 of the above code, you implicitly tell Tasmota to set the serial parameters to 7E1 (probably the same applies to all other meters in this documentation where a modification of TasmotaSerial.cpp has previously been recommended).
"},{"location":"Smart-Meter-Interface/#efr-sgm-c2c4-sml","title":"EFR SGM-C2/C4 (SML)","text":"By default, the energy meter only sends the total energy values. To be able to read all the other values, you need to enter the PIN and set InF on. The PIN must be requested from the metering provider, which is usually your local grid provider and not your energy provider (but they know whom to ask). After entering the PIN and setting InF on, all the values will be available. The jsonPrefix ENERGY and variable names (between second to last and last ,) Total, Power, Voltage and Current are chosen to match the regular MQTT message format, used by tasmota powerplugs. For SGM-C4, double-tariff variants or meters measuring supply remove the appropriate leading ; to uncomment and enable the values you are interested in.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,16,9600,ENERGY\n1,77070100010800ff@1000,Comsumption,kWh,Total,4\n;for meters measuring feed-in SGM-Cx-xxx2xx\n;1,77070100020800ff@1000,Supply,kWh,Supply,4\n;next 4 lines for double-tariff meters SGM-Cx-xxxxTx\n;1,77070100010801ff@1000,Comsumption_t1,kWh,Total_t1,4\n;1,77070100010802ff@1000,Comsumption_t2,kWh,Total_t2,4\n;1,77070100020801ff@1000,Supply_t1,kWh,Supply_t1,4\n;1,77070100020802ff@1000,Supply_t2,kWh,Supply_t2,4\n;all commented lines from here on for 3-phase meter SGM-C4\n1,77070100100700ff@1,Actual Power,W,Power,0\n1,77070100200700ff@1,Voltage L1,V,Voltage,1\n;1,77070100340700ff@1,Voltage L2,V,Voltage_L2,1\n;1,77070100480700ff@1,Voltage L3,V,Voltage_L3,1\n1,770701001f0700ff@1,Current L1,A,Current,2\n;1,77070100330700ff@1,Current L2,A,Current_L2,2\n;1,77070100470700ff@1,Current L3,A,Current_L3,2\n;1,77070100510701ff@1,Phaseangle L2-L1,deg,phase_angle_L2_L1,0\n;1,77070100510702ff@1,Phaseangle L3-L1,deg,phase_angle_L3_L1,0\n1,77070100510704ff@1,Phaseangle I/U L1,deg,phase_angle_L1,1 \n;1,7707010051070fff@1,Phaseangle I/U L2,deg,phase_angle_L2,1 \n;1,7707010051071aff@1,Phaseangle I/U L3,deg,phase_angle_L3,1 \n1,770701000e0700ff@1,Frequency,Hz,Freq,1\n;all commented lines from here on just for completeness\n;1,7707010000020000@1,Firmware Version,,FwVer,0\n;1,77070100605a0201@1,Firmware Checksum,,FwCheck,0\n;1,7707010061610000@1,Error Register,,ErrorReg,0\n;1,7707010060320101@1,Hardware Version,,HwVer,0\n;1,7707010060320104@1,Parameter Version,,ParamVer,0\n1,77070100600100ff@#,Server-ID,,ID,0\n;You can find your server-id printed on your meter. If you want you can also convert it to your Identifikationsnummer with some ASCII, DEC and HEX encoding. 0A-01-45-46-52-ST-UV-WX-YZ = 1EFR + string(S) + string(T) + hexToDec(UVWXYZ)\n#\n
Overview of the codes
"},{"location":"Smart-Meter-Interface/#elster-honeywell-as1440-obis","title":"Elster / Honeywell AS1440 (OBIS)","text":"Based on Landis script with changed timings in the >F section, as AS1440 seems to be slower in responding.
This defines metrics for totals and current power usage for both incoming and outgoing power. Just delete the lines you don't need from the last sections. Current power values get published to mqtt immediately when received from the meter.
View script >D\nscnt=0\nres=0\n\n>B\n=>sensor53 r\n\n>F\n; count 100ms\nscnt+=1\nswitch scnt\n\n;300ms after start: set sml driver to 300 baud and send /?! as HEX to trigger the Meter\ncase 3\nres=sml(1 0 300)\nres=sml(1 1 \"2F3F210D0A\")\n\n;1700ms later: Ack and ask for switching to 9600 baud\ncase 20\nres=sml(1 1 \"063035300D0A\")\n\n;300ms later: switch sml driver to 9600 baud\ncase 23\nres=sml(1 0 9600)\n\n;6000ms after start: Restart sequence\ncase 60\nscnt=0\n\nends\n\n>M 1\n+1,3,o,0,9600,AS1440,1\n1,1.7.0(@0.001,Power In,W,power_in,16\n1,1.8.1(@1,Total In,KWh,Total_in,1\n1,2.7.0(@0.001,Power Out,W,power_out,16\n1,2.8.1(@1,Total Out,KWh,Total_out,1\n#\n
"},{"location":"Smart-Meter-Interface/#elster-f96-plus-sharky-775-ditech-integral-v-ultralite-pro-m-bus","title":"Elster F96 Plus (Sharky 775) (Ditech Integral-V UltraLite PRO) M-Bus","text":"This heat meter needs a wakeup sequence with 2400 Baud 8N1, wheras communication is done by 2400 Baud 8E1. The script will therefore only rund starting with Tasmota 12.2 where switching parity is implemented. For compiling, add the following to your user_config_override.h to increase serial communication buffer size and enable MQTT and Web publishing:
View user_config_override.h #ifndef USE_SCRIPT\n#define USE_SCRIPT\n#endif\n#ifndef USE_SML_M\n#define USE_SML_M\n#endif\n#ifdef USE_RULES\n#undef USE_RULES\n#endif\n#ifndef SML_BSIZ\n#define SML_BSIZ 200\n#endif\n#ifndef USE_SML_SCRIPT_CMD\n#define USE_SML_SCRIPT_CMD\n#endif\n#ifndef USE_SCRIPT_JSON_EXPORT\n#define USE_SCRIPT_JSON_EXPORT\n#endif\n#ifndef USE_SCRIPT_WEB_DISPLAY\n#define USE_SCRIPT_WEB_DISPLAY\n#endif\n
Delta calculation for previous day is included as the meter shall not be read often when operated with a battery.
View script >D\n;start, define variables\ncnt=1\ntimer=1\nw_new=0\nw_delta=0\np:w_last=0\n\n>B\n;setup sensor\n->sensor53 r\n\n>T\nw_new=WAERME#w_total\n\n>S\ntimer=int(time)\nif chg[timer]>0 \nthen\nswitch timer\ncase 0\nprint It is midnight\nprint wakeup start\nsml(-1 1 \"2400:8N1\")\nfor cnt 1 72 1\nsml(1 1 \"55555555555555555555\")\nnext\nprint wakeup end\nprint wait for the meter\ndelay(350)\nsml(-1 1 \"2400:8E1\")\nprint request data\nsml(1 1 \"105BFE5916\")\ncase 1\nprint It is a minute after midnight\nprint calculating daily value\nprint w_last %0w_last%\nw_delta=w_new-w_last\nw_last=w_new\nsvars\nprint w_new %0w_new%\nprint w_delta %0w_delta%\nends\nendif\n\n>J \n,\"w_delta\":%w_delta% \n\n>W\n===============\nVortagsverbrauch: {m} %3w_delta% KWh \n\n>M 1\n+1,3,rE1,0,2400,WAERME,1\n1,0C06bcd8@1,Total Energy,kWh,w_total,0\n1,0C13bcd8@1000,Total volume,m\u00b3,v_total,2\n1,0C2Bbcd8@1,Current power,W,p_act,0\n1,0B3Bbcd6@1000,Current flow,m\u00b3/h,F_akt,3\n1,0A5Abcd4@10,Flow temp,\u00b0C,t_flow,1\n1,0A5Ebcd4@10,Return temp,\u00b0C,t_return,1\n1,0A62bcd4@10,Temp diff,\u00b0C,t_diff,2\n#\n
"},{"location":"Smart-Meter-Interface/#elster-honeywell-as2020-sml","title":"Elster / Honeywell AS2020 (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,,1\n1,77070100600100ff@#,Server-ID,,Wert,0\n1,77070100010800ff@1000,Total Consumed,kWh,total_consumed_kwh,1\n1,77070100020800ff@1000,Total Delivered,kWh,total_delivered_kwh,1\n1,77070100100700ff@0.1,Current Consumption,W,current_consumption,0\n#\n
"},{"location":"Smart-Meter-Interface/#elster-t510-obis","title":"Elster T510 (OBIS)","text":"It seems you can not read the total power like 1,1.7.0(@0.001,Leistung,W,Power_curr,0, as the value just alternates between the values of the three phases. So in this script the three phases get added and published as Power_total.
View script >D\n;Var for baudrate changing\nres=0\n;Var for counter see >F=ms \nscnt=0 \n\n>B\n->sensor53 r\n;Set teleperiod to 20sec \n;tper=10\n\n>F\n; count 100ms \nscnt+=1 \nswitch scnt \ncase 6 \n;set sml driver to 300 baud and send /?! as HEX to trigger the Meter \nres=sml(1 0 300) \nres=sml(1 1 \"2F3F210D0A\") \n\n;1800ms later \\> Ack and ask for switching to 9600 baud \ncase 18 \nres=sml(1 1 \"063035300D0A\") \n\n;2000ms later \\> Switching sml driver to 9600 baud \ncase 20 \nres=sml(1 0 9600) \n\n;Restart sequence after 50x100ms \ncase 50 \n; 5000ms later \\> restart sequence \nscnt=0 \nends \n\n>M 1\n\n+1,3,o,0,9600,,1\n1,0.0.0(@1,Z\u00e4hlernummer,,Meter_number,0\n1,0.9.1(@#),Zeitstempel,Uhr,timestamp,0\n1,1.8.0(@1,Z\u00e4hlerstand,kWh,Total_in,3\n1,21.7.0(@0.001,Leistung Phase 1,W,Power_L1,0\n1,41.7.0(@0.001,Leistung Phase 2,W,Power_L2,0\n1,61.7.0(@0.001,Leistung Phase 3,W,Power_L3,0\n1,=m 4+5+6 @1,Leistung,W,Power_total,0\n1,31.7.0(@1,Strom Phase 1,A,Current_L1,2\n1,51.7.0(@1,Strom Phase 2,A,Current_L2,2\n1,71.7.0(@1,Strom Phase 3,A,Current_L3,2\n#\n
"},{"location":"Smart-Meter-Interface/#emh-ebzd-sml","title":"EMH eBZD (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,Main\n1,77070100100700ff@1,Power,W,power,0\n1,77070100010800ff@1000,Total Consumed,kWh,counter_pos,3\n1,77070100020800ff@1000,Total Feed,kWh,counter_neg,3\n#\n
"},{"location":"Smart-Meter-Interface/#emh-ed300l-sml","title":"EMH ED300L (SML)","text":"View script >D \n>B \n->sensor53 r \n>M 2 \n+1,13,s,0,9600,Haus \n+2,12,s,0,9600,Heizung \n1,770701000F0700FF@1,Aktuell,W,Power_curr,0 \n1,77070100010800FF@1000,Z\u00e4hlerstand Verb.,kWh,Tariflos,2 \n1,77070100020800FF@1000,Z\u00e4hlerstand Einsp.,kWh,Tariflos,2 \n2,=h================== \n2,770701000F0700FF@1,Aktuell,W,Power_curr,0 \n2,77070100010800FF@1000,Z\u00e4hlerstand Verb.,kWh,Tariflos,2 \n2,77070100020800FF@1000,Z\u00e4hlerstand Einsp.,kWh,Tariflos,2 \n# \n
"},{"location":"Smart-Meter-Interface/#emh-ed300s-sml","title":"EMH ED300S (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,Main\n1,77070100100700ff@1,Power,W,power,0\n1,77070100010800FF@1000,Counter,kWh,counter,3\n#\n
"},{"location":"Smart-Meter-Interface/#emh-ehz-generation-k-sml","title":"EMH eHZ Generation K (SML)","text":"View script >D\n>B\n\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,\n1,77070100010800ff@1000,Gesamtverbrauch,KWh,Total_in,2\n1,77070100020800ff@1000,Gesamteinspeisung,KWh,Total_out,2\n1,77070100100700ff@1,Verbrauch,W,Power_curr,0\n#\n
"},{"location":"Smart-Meter-Interface/#emh-mme40-sml","title":"EMH mMe4.0 (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,Main,1,10\n1,77070100010800FF@1000,Total Consumed,kWh,counter_pos,3\n1,77070100020800FF@1000,Total Feed,kWh,counter_neg,3\n1,77070100100700FF@1,Power,W,power,0\n#\n
"},{"location":"Smart-Meter-Interface/#ezb-md3-sml","title":"eZB MD3 (SML)","text":"View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,Smartmeter\n1,77070100010800ff@100000000,Total consumption,KWh,Total_in,3\n1,77070100020800ff@100000000,Total generation,KWh,Total_out,3\n1,77070100100700ff@1,Power L1+L2+L3,W,P_L1_L2_L3,18\n1,77070100240700ff@1,Power L1,W,P_L1,18\n1,77070100380700ff@1,Power L2,W,P_L2,18\n1,770701004C0700ff@1,Power L3,W,P_L3,18\n#\n
"},{"location":"Smart-Meter-Interface/#growatt-max4200-modbus","title":"Growatt MAX4200 (MODBus)","text":"Growatt solar inverter. this example also shows how to send cmds to modbus
View script >D 22\n\ncstr=\"\"\ngl=0\ntmp=0\n\n>B\n=>sensor53 r\n\n\n>S\nif chg[gl]>0 {\n ; change limit\n tmp=int(gl/42)\n cstr=\"r0106000300\"+hn(tmp)\n sml(1 3 cstr)\n}\n\n>M 1\n+1,18,m,0,9600,GRW,19,5,01040026,01040028,01040005,01040009,01030003\n1,010404UUuu@i0:10,Netzspannung,V,mainsv,1\n1,010404xxxxUUuu@i0:10,Einspeisestrom,A,mainsc,1\n1,010404UUuuUUuu@i1:10,Einspeiseleistung,W,mainsw,1\n1,010404UUuuUUuu@i2:10,string 1 unten,W,s1w,1\n1,010404UUuuUUuu@i3:10,string 2 oben,W,s2w,1\n1,010304UUuu@i4:1,limit,%,limit,0\n#\n\n>W\n<hr>\nnm(1000 3600 10 gl \"Growatt limit (W) \" 80 0) \n
"},{"location":"Smart-Meter-Interface/#hager-ehz161-ehz361-obis","title":"Hager EHZ161 / EHZ361 (OBIS)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,o,0,9600,OBIS\n1,1-0:0.0.0*255(@#),Meter Number,,meter_number,0\n1,1-0:1.8.0*255(@1,Power Consumption A+,kWh,zaehler_a+,4\n1,1-0:2.8.0*255(@1,Power Feed A-,kWh,zaehler_a-,4\n1,1-0:32.7.0*255(@1,Volt_L1,V,volt_l1,2\n1,1-0:52.7.0*255(@1,Volt_L2,V,volt_l2,2\n1,1-0:72.7.0*255(@1,Volt_L3,V,volt_l3,2\n1,1-0:31.7.0*255(@1,Ampere_L1,A,volt_l1,2\n1,1-0:51.7.0*255(@1,Ampere_L2,A,volt_l2,2\n1,1-0:71.7.0*255(@1,Ampere_L3,A,volt_l3,2\n1,1-0:21.7.0*255(@1,Watt_L1,W,watt_l1,0\n1,1-0:41.7.0*255(@1,Watt_L2,W,watt_l2,0\n1,1-0:61.7.0*255(@1,Watt_L3,W,watt_l3,0\n#\n
"},{"location":"Smart-Meter-Interface/#hager-ehz363-apator-norax-3d-sml","title":"Hager EHZ363, Apator Norax 3D (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,SML\n1,77070100010800ff@1000,Total consumption,KWh,Total_in,4\n1,77070100020800ff@1000,Total Feed,KWh,Total_out,4\n1,77070100100700ff@1,Current consumption,W,Power_curr,0\n1,77070100200700ff@1,Voltage L1,V,Volt_p1,1\n1,77070100340700ff@1,Voltage L2,V,Volt_p2,1\n1,77070100480700ff@1,Voltage L3,V,Volt_p3,1\n1,770701001f0700ff@1,Amperage L1,A,Amperage_p1,1\n1,77070100330700ff@1,Amperage L2,A,Amperage_p2,1\n1,77070100470700ff@1,Amperage L3,A,Amperage_p3,1\n1,77070100510704ff@1,Phaseangle I-L1/U-L1,deg,phase_angle_p1,1 \n1,7707010051070fff@1,Phaseangle I-L27I-L2,deg,phase_angle_p2,1 \n1,7707010051071aff@1,Phaseangle I-L3/I-L3,deg,phase_angle_p3,1 \n1,770701000e0700ff@1,Frequency,Hz,frequency,0\n#\n
SML with daily values >D \npin=0 \npout=0 \npi_d=0 \npo_d=0 \nhr=0 \n; permanent midnight values \np:pi_m=0 \np:po_m=0 \n>B \n->sensor53 r \n>T \n; get total consumption and total feed \npin=SML#Total_in \npout=SML#Total_out \n>S \n; at midnight, save meter total values \nhr=hours \nif chg[hr]>0 \nand hr==0 \nthen \npi_m=pin \npo_m=pout \nsvars \nendif \n; on teleperiod calculate current daily values from midnight \nif upsecs%tper==0 \nthen \npi_d=pin-pi_m \npo_d=pout-po_m \nendif \n; show these values on WEB UI \n>W \nTagesverbrauch: {m} %pi_d% kWh \nTageseinspeisung: {m} %po_d% kWh \n; transmit these values with MQTT \n>J \n,\"daily_consumption\":%pi_d%,\"daily_feed\":%po_d% \n; meter definition \n>M 1 \n+1,3,s,0,9600,SML \n1,77070100010800ff@1000,Total Consumed,KWh,Total_in,4 \n1,77070100020800ff@1000,Total Delivered,KWh,Total_out,4 \n1,77070100100700ff@1,Current Consumption,W,Power_curr,0 \n1,77070100000009ff@#,Meter Number,,Meter_number,0 \n#\n
"},{"location":"Smart-Meter-Interface/#hiking-dds238-2-zns3-4x-modbus","title":"Hiking DDS238-2 ZN/S3 4x (MODBus)","text":"This is an example for 4 MODBus devices on the same bus (at different addresses).
Wiring diagram View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,m,1,9600,Hiking,1,10,0103000c,0103000e,0303000c,0303000e,0403000c,0403000e,0503000c,0503000e\n;---> two groups of registers for each device --> default 2 registers returned ---> 4 values per device\n1,=h Contatore 1\n1,010304UUuu@i0:10,C1_Voltage,V,C1Voltage,1\n;---> decoder for the first registry returned for the first group\n1,010304xxxxUUuu@i0:1000,C1_Current,A,C1Current,3\n;---> decoder for the second registry returned for the first group\n1,010304SSss@i1:1,C1_ActivePower,W,C1ActivePower,0\n1,010304xxxxUUuu@i1:1,C1_ReactivePower,Var,C1ReactivePower,0\n1,=h Contatore 3\n1,030304UUuu@i2:10,C3_Voltage,V,C3Voltage,1\n1,030304xxxxUUuu@i2:1000,C3_Current,A,C3Current,3\n1,030304SSss@i3:1,C3_ActivePower,W,C3ActivePower,0\n1,030304xxxxUUuu@i3:1,C3_ReactivePower,Var,C3ReactivePower,0\n1,=h Contatore 4\n1,040304UUuu@i4:10,C4_Voltage,V,C4Voltage,1\n1,040304xxxxUUuu@i4:1000,C4_Current,A,C4Current,3\n1,040304SSss@i5:1,C4_ActivePower,W,C4ActivePower,0\n1,040304xxxxUUuu@i5:1,C4_ReactivePower,Var,C4ReactivePower,0\n1,=h Contatore 5\n1,050304UUuu@i6:10,C5_Voltage,V,C5Voltage,1\n1,050304xxxxUUuu@i6:1000,C5_Current,A,C5Current,3\n1,050304SSss@i7:1,C5_ActivePower,W,C5ActivePower,0\n1,050304xxxxUUuu@i7:1,C5_ReactivePower,Var,C5ReactivePower,0\n#\n
"},{"location":"Smart-Meter-Interface/#holley-dtz541-sml","title":"Holley DTZ541 (SML)","text":"This script reads pretty much all given information. Make sure to enable info in the settings, otherwise you only get total / current consuption and total export.
This script was used and tested on a WeMos D1 mini with an IR Head connected to the RX pin (3).
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,16,9600,SML\n1,77070100600100ff@#,Server ID,,server_id,0\n1,77070100020800ff@1000,Export (Total),kWh,export_total_kwh,4\n1,77070100010800ff@1000,Consumption (Total),kWh,total_kwh,4\n1,77070100100700ff@1,Consumption (Current),W,curr_w,0\n1,77070100200700ff@1,Voltage L1,V,volt_p1,1\n1,77070100340700ff@1,Voltage L2,V,volt_p2,1\n1,77070100480700ff@1,Voltage L3,V,volt_p3,1\n1,770701001f0700ff@1,Amperage L1,A,amp_p1,1\n1,77070100330700ff@1,Amperage L2,A,amp_p2,1\n1,77070100470700ff@1,Amperage L3,A,amp_p3,1\n1,77070100510701ff@1,Phase angle U-L2/U-L1,deg,phase_angle_l2_l1,1\n1,77070100510702ff@1,Phase angle U-L3/U-L1,deg,phase_angle_l3_l1,1\n1,77070100510704ff@1,Phase angle I-L1/U-L1,deg,phase_angle_p1,1\n1,7707010051070fff@1,Phase angle I-L2/U-L2,deg,phase_angle_p2,1\n1,7707010051071aff@1,Phase angle I-L3/U-L3,deg,phase_angle_p3,1\n1,770701000e0700ff@1,Frequency,Hz,freq,0\n#\n
"},{"location":"Smart-Meter-Interface/#holley-dtz541-zdba-sml","title":"Holley DTZ541-ZDBA (SML)","text":"This meter differatiates between day and night time consumption. The script is based on the DTZ541. Look above for more information.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,16,9600,SML\n1,77070100600100ff@#,Server ID,,server_id,0\n1,77070100020800ff@1000,Export (Total),kWh,export_total_kwh,4\n1,77070100010802ff@1000,Night (Total),kWh,total_night_kwh,4\n1,77070100010801ff@1000,Day (Total),kwH,total_day_kwh,4\n1,77070100100700ff@1,Consumption (Current),W,curr_w,0\n1,77070100200700ff@1,Voltage L1,V,volt_p1,1\n1,77070100340700ff@1,Voltage L2,V,volt_p2,1\n1,77070100480700ff@1,Voltage L3,V,volt_p3,1\n1,770701001f0700ff@1,Amperage L1,A,amp_p1,1\n1,77070100330700ff@1,Amperage L2,A,amp_p2,1\n1,77070100470700ff@1,Amperage L3,A,amp_p3,1\n1,77070100510701ff@1,Phase angle U-L2/U-L1,deg,phase_angle_l2_l1,1\n1,77070100510702ff@1,Phase angle U-L3/U-L1,deg,phase_angle_l3_l1,1\n1,77070100510704ff@1,Phase angle I-L1/U-L1,deg,phase_angle_p1,1\n1,7707010051070fff@1,Phase angle I-L2/U-L2,deg,phase_angle_p2,1\n1,7707010051071aff@1,Phase angle I-L3/U-L3,deg,phase_angle_p3,1\n1,770701000e0700ff@1,Frequency,Hz,freq,0\n#\n
"},{"location":"Smart-Meter-Interface/#iskra-mt-174-obis","title":"Iskra MT 174 (OBIS)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,o,0,300,STROM,1,100,2F3F210D0A\n1,1-0:1.8.1*255(@1,Total Consumed,KWh,Total_in,3\n1,1-0:2.8.1*255(@1,Total Delivered,KWh,Total_out,3\n1,1-0:0.0.0*255(@#),Meter Number,,Meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#iskra-mt-175-sml","title":"Iskra MT 175 (SML)","text":"This meter needs a PIN to unlock the current power usage. You need to ask your provider.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,16,9600,MT175\n1,77070100010800ff@1000,E_in,kWh,E_in,1\n1,77070100020800ff@1000,E_out,kWh,E_out,1\n1,77070100100700ff@1,P,W,P,18\n1,77070100240700ff@1,L1,W,L1,18\n1,77070100380700ff@1,L2,W,L2,18\n1,770701004C0700ff@1,L3,W,L3,18\n1,77070100000009ff@#,Server_ID,,Server_ID,0\n#\n
"},{"location":"Smart-Meter-Interface/#iskra-mt-681-sml","title":"Iskra MT 681 (SML)","text":"This is script for a two-direction meter (consumption and delivery) for the Isra MT 681, that is widely used in Germany. If you don't deliver energy, just delete the \"Total Delivered\" line. If the meter provides the consumption values for the 3 phases depends also on the configuration by your local energy provider.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,MT681\n1,77070100010800ff@1000,Total Consumed,KWh,Total_in,3\n1,77070100100700ff@1,Current Consumption,W,Power_cur,0\n1,77070100240700ff@1,Current Consumption P1,W,Power_p1,0\n1,77070100380700ff@1,Current Consumption P2,W,Power_p2,0\n1,770701004c0700ff@1,Current Consumption P3,W,Power_p3,0\n1,77070100020800ff@1000,Total Delivered,KWh,Total_out,3\n1,77070100000009ff@#,Service ID,,Meter_id,0|\n#\n
"},{"location":"Smart-Meter-Interface/#iskra-ehz-mt681-d4a51-k0p","title":"Iskra eHZ-MT681-D4A51-K0p","text":"2012 version of the Iskra MT 681 with slightly other OBIS codes for the power values.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,MT681\n1,77070100010800ff@1000,Gesamtverbrauch,KWh,Total_in,3\n1,770701000f0700ff@1,Leistung,W,Power_cur,0\n1,77070100150700ff@1,Leistung P1,W,Power_p1,0\n1,77070100290700ff@1,Leistung P2,W,Power_p2,0\n1,770701003d0700ff@1,Leistung P3,W,Power_p3,0\n1,77070100020800ff@1000,Gesamteinspeisung,KWh,Total_out,3\n1,77070100000009ff@#,Service ID,,Meter_id,0|\n#\n
"},{"location":"Smart-Meter-Interface/#itron-sml-v104","title":"Itron (SML V1.04)","text":"The Itron electrical meter is a German end-user meter installed by EnBW. You can read values using an IR Sensor. The following script shows the meter number and the consuption and the generation of a Photovoltaik generator.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,12,s,0,9600,ELZ\n1,77070100600100ff@#,Z\u00e4hlernummer,,Wert,0\n1,77070100010800ff@1000,Verbrauch,kWh,ELZ_PV_1.8.0,1\n1,77070100020800ff@1000,Erzeugung,kWh,ELZ_PV_2.8.0,1\n#\n
This script additionally reads the power in watts It has enhanced precision of 4 decimal places for the total consumption. Be sure to turn on the full precision at the meter using a flashlight (if you see inF=Off, hold for 5 seconds until you see inF=On)
>D\n>B\n=>sensor53 r\n;Set teleperiod to 20sec \ntper=10 \n>M 1\n+1,3,s,0,9600,Power\n1,77070100600100ff@#,Z\u00e4hlernummer,,Meter_Number,0\n1,77070100010800ff@1000,Verbrauch,kWh,Total_in,4\n1,77070100100700ff@1,Leistung,W,Power_curr,0\n1,77070100020800ff@1000,Erzeugung,kWh,Total_out,4\n#\n
"},{"location":"Smart-Meter-Interface/#janitza-b23-modbus","title":"Janitza B23 (MODBus)","text":"View script >D\n>B \n->sensor53 r\n>M 1 \n+1,3,m,0,9600,Janitza,1,1,01034A38,01034A3A,01034A3C,01034A4C,01034A4E,01034A50,01034A72,01034A7A,01034A82 \n1,010304ffffffff@i0:1,Voltage L1-N,V,Voltage_L1-N,2 \n1,010304ffffffff@i1:1,Voltage L2-N,V,Voltage_L2-N,2 \n1,010304ffffffff@i2:1,Voltage L3-N,V,Voltage_L3-N,2 \n1,010304ffffffff@i3:1,Real power L1-N,W,Real_power_L1-N,2 \n1,010304ffffffff@i4:1,Real power L2-N,W,Real_power_L2-N,2 \n1,010304ffffffff@i5:1,Real power L3-N,W,Real_power_L3-N,2 \n1,010304ffffffff@i6:1,Real energy L3,Wh,Real_energy_L3,2 \n1,010304ffffffff@i7:1,Real energy L3-consumed,Wh,Real_energy_L3_consumed,2 \n1,010304ffffffff@i8:1,Real energy L3-delivered,Wh,Real_energy_L3_delivered,2 \n#\n
"},{"location":"Smart-Meter-Interface/#janz-c3801-modbus","title":"JANZ C3801 (MODBus)","text":"This is an example for one of the many quite similar smart meters implemented in Portugal, by EDP Distribui\u00e7\u00e3o S.A. May be valid for many more models, as stated.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,14,m,1,9600,EB,5,50,0104006C,01040079,0104007A,0104007F,01040026,01040027,01040028,0104000B,01040084\n1,=hVALORES T\u00c9CNICOS\n1,010404UUuuxxxx@i0:10,Tens\u00e3o,V,Voltage_P1,17\n1,010404xxxxUUuu@i0:10,Corrente,A,Current_P1,17\n1,010408UUuuUUuuxxxxxxxxxxxx@i1:1,Pot\u00eancia ativa,W,Power_P1,16\n1,010406xxxxxxxxUUuu@i2:1000,Fator de pot\u00eancia,pu,PFactor_P1,19\n1,01040aUUuuxxxx@i3:10,Frequ\u00eancia,Hz,Frequency_P1,17\n1,=h‍\n1,=hTOTALIZADORES DE ENERGIA\n1,010408UUuuUUuuxxxxxxxxxxxx@i4:1000,Vazio (1),kWh,Energy_P1_R1,17\n1,010408UUuuUUuuxxxxxxxxxxxx@i5:1000,Ponta (2),kWh,Energy_P1_R2,17\n1,010408UUuuUUuuxxxxxxxxxxxx@i6:1000,Cheia (3),kWh,Energy_P1_R3,17\n1,=h‍\n1,=hESTADOS\n1,010406uuxxxxxxxx@i7:1,Tarifa,,Tariff_P1,16\n1,010406uuxxxxxxxx@i8:1,DCP,,DCP_P1,16\n#\n
"},{"location":"Smart-Meter-Interface/#kaifa-mb310h4bde","title":"KAIFA MB310H4BDE","text":"By default, the KAIFA MB310H4BDE will only deliver the Total_in and Total_out values (without decimals). In order to get precise values, and especially in order to receive Power_curr, you have to login to configure it: Press the button besides the display. When asked for pin, enter it with a flashlight or by pressing the same button repeatedly. (If you don't have a PIN, get it from your grid operator.) If that was successful, you will see accurate values in the meters display already. To activate them on the SML interface, press the button repeatedly for 13 times, until \"INF OFF\" is displayed. Now press and hold the button, until it switches to INF ON. After that, you should receive all values.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,Haus\n1,77070100010800ff@1000,Zaehlerstand In,KWh,Total_in,2\n1,77070100020800ff@1000,Zaehlerstand Out,KWh,Total_out,2\n1,77070100100700ff@1,Leistung-akt.,W,Power_curr,0\n1,77070100600100ff@#,Server-ID,,Meter_Number,0\n
"},{"location":"Smart-Meter-Interface/#kamstrup-multical-4xx-6xx-8xx","title":"Kamstrup Multical 4xx / 6xx / 8xx","text":"Those meters provide several registers via optical interface called D0 interface. Baudrate is only 1200 thus reading multiple registers simultaneously takes some time (e.g. one: ~300ms, six ~750ms). Size of response varies depending on register type and needs to be considered when reading more than one with a single telegram. Analyze length with sensor53 d1. Responses have format of 3F10<rg><response><rg><response>. So asking for 0x003C and 0x0056 with telegram 3F10 02 003C 0056 could be responded with 3F10 003C xxXXxxXXxxXXxx 0056 xxXXxxXXxx.
Default buffer size suffices for four values at once. The following example reads seven values at once so please #define SML_BSIZ 90. SML allows only one date value per meter at the moment.
View script (seven at once, needs #define SML_BSIZ 90) >D\n>B\n=>sensor53 r\n>M 1\n+1,3,kN2,0,1200,KSMC403,1,10,3F1007003C005600570059004A0044007B\n1,3F10003Ckstr@i0:1000,W\u00e4rmemenge,MWh,HeatEnergyE1,3\n1,3F10x08xx0056kstr@i0:100,Vorlauftemp.,\u00b0C,PreTemp,2\n1,3F10x15xx0057kstr@i0:100,R\u00fccklauftemp.,\u00b0C,AftTemp,2\n1,3F10x22xx0059kstr@i0:100,Temp.diff.,\u00b0C,DifTemp,2\n1,3F10x29xx004Akstr@i0:1,Flie\u00dfgeschw.,l/h,Flow,0\n1,3F10x36xx0044kstr@i0:100,Volumenstrom,m\u00b3,Volume,2\n1,3F10x45xx007Bkstr@#,max. Fluss am,,MaxFlowDate,0\n#\n
View script (same as above with two telegrams and default SML_BSIZ) >D\n>B\n=>sensor53 r\n>M 1\n+1,3,kN2,0,1200,KSMC403,1,5,3F1004003C005600570059,3F1003004A0044007B\n1,3F10003Ckstr@i0:1000,W\u00e4rmemenge,MWh,HeatEnergyE1,3\n1,3F10x08xx0056kstr@i0:100,Vorlauftemp.,\u00b0C,PreTemp,2\n1,3F10x15xx0057kstr@i0:100,R\u00fccklauftemp.,\u00b0C,AftTemp,2\n1,3F10x22xx0059kstr@i0:100,Temp.diff.,\u00b0C,DifTemp,2\n1,3F10004Akstr@i1:1,Flie\u00dfgeschw.,l/h,Flow,0\n1,3F10x06xx0044kstr@i1:100,Volumenstrom,m\u00b3,Volume,2\n1,3F10x15xx007Bkstr@#,max. Fluss am,,MaxFlowDate,0\n#\n
"},{"location":"Smart-Meter-Interface/#landis-gyr-e220-sml","title":"Landis + Gyr E220 (SML)","text":"For read-out of \"current power\" the advanced data set has to be enabled in user menu
View script >D\n>B\n=>sensor53 r\n;Set teleperiod to 20sec \ntper=10 \n>M 1\n+1,3,s,0,9600,Power\n1,77070100600100ff@#,Server-ID,,Meter_Number,0\n1,77070100010800ff@1000,Verbrauch,kWh,Total_in,4\n1,77070100100700ff@1,Leistung-akt.,W,Power_curr,0\n#\n
"},{"location":"Smart-Meter-Interface/#landis-gyr-e320-sml","title":"Landis + Gyr E320 (SML)","text":"For read-out of \"Current power\" the advanced data set has to be enabled in user menu
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,20,9600,E320\n1,77070100020800ff@1000,Total Delivered,KWh,Total_out,3\n1,77070100010800ff@1000,Total Consumed,KWh,Total_in,3\n1,77070100100700ff@1,Current power,W,Power_in,3\n1,77070100600100ff@#,Server-ID,,Meter_Number,0 \n#\n
"},{"location":"Smart-Meter-Interface/#landis-gyr-zmb120-t213cs-obis","title":"Landis + Gyr ZMB120 T213CS (OBIS)","text":"This meter may need a PIN to unlock the current power usage - ask your provider.
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,300,STROM,1,10,2F3F210D0A,063030300D0A\n1,0(@1,Z\u00e4hlernummer,,Meter_number,0 \n1,=h=================== \n1,8.0(@1,Total T1 & T2,KWh,Total,2 \n1,8.1(@1,T1 aktuell,KWh,Total_T1,2 \n1,8.2(@1,T2 aktuell,KWh,Total_T2,2 \n1,=h=================== \n1,8.1.1(@1,T1 letzte Saison,KWh,Total_T1-1,2 \n1,8.2.1(@1,T2 letzte Saison,KWh,Total_T2-1,2 \n1,8.1.2(@1,T1 vorletzte Saison,KWh,Total_T1-2,2\n1,8.2.2(@1,T2 vorletzte Saison,KWh,Total_T2-2,2 \n#\n
"},{"location":"Smart-Meter-Interface/#landis-gyr-zmr120ares2r2sfcs-obis","title":"Landis + Gyr ZMR120AReS2R2sfCS (OBIS)","text":"Example: Changing the baud rate during operation.
View script >D \n;Var Power consumption total HT+NT \nv1=0 \n;HT Main electricity tariff consumption total \nv2=0 \n;NT Night electricity tariff consumption total \nv3=0 \n; Energie L1+L2+L3 \nv4=0 \n;recent Energie L1 \nv5=0 \n;recent Energie L2 \nv6=0 \n;recent Energie L3 \nv7=0 \n\n;Var minute \nmin=0 \n;Var hour \nhr=0 \n;Var begin of the month 01.xx.20xx 0:00 Uhr \nmd=0 \n;Var begin of the year 01.01. 0:00 Uhr \nyr=0 \n;Var for counter see >F=ms \nscnt=0 \n;Var for baudrate changing\nres=0 \n\n;Permanent Var Meter1 0:00 \np:sm=0 \np:HT_sm=0 \np:NT_sm=0 \n;Var for daily =0 \nsd=0 \nHT_sd=0 \nNT_sd=0 \n;Permanent Var for month begin \np:sma=0 \np:HT_sma=0 \np:NT_sma=0 \n;Var for monthly =0 \nsmn=0 \nHT_smn=0 \nNT_smn=0 \n;Permanent Var for year begin \np:sya=0 \np:HT_sya=0 \np:NT_sya=0 \n;Var for yearly =0 \nsyn=0 \nHT_syn=0 \nNT_syn=0 \n\n;Fill vars with content on teleperiod \n>T \nv1=#Total_in \nv2=#HT_Total_in \nv3=#NT_Total_in \nv4=#kW_L1+L2+L3 \nv5=#kw_L1 \nv6=#kw_L2 \nv7=#kw_L3 \n\n>B \n;Restart driver \n->sensor53 r \n;Set teleperiod to 20sec \ntper=20 \n\n>F \n; count 100ms \nscnt+=1 \nswitch scnt \ncase 6 \n;set sml driver to 300 baud and send /?! as HEX to trigger the Meter \nres=sml(1 0 300) \nres=sml(1 1 \"2F3F210D0A\") \n\n;1800ms later \\> Ack and ask for switching to 9600 baud \ncase 18 \nres=sml(1 1 \"063035300D0A\") \n\n;2000ms later \\> Switching sml driver to 9600 baud \ncase 20 \nres=sml(1 0 9600) \n\n;Restart sequence after 50x100ms \ncase 50 \n; 5000ms later \\> restart sequence \nscnt=0 \nends \n\n>S \n;daily usage \nhr=hours \nif chg[hr]>0 \nand hr==0 \nand v1>0 \nthen \nsm=v1 \nHT_sm=v2 \nNT_sm=v3 \nsvars \nendif \n\nif upsecs%tper==0{ \nsd=v1-sm \nHT_sd=v2-HT_sm \nNT_sd=v3-NT_sm \n} \n\n;Monthly usage \nmd=day \nif chg[md]>0 \nand md==1 \nand v1>0 \nthen \nsma=v1 \nHT_sma=v2 \nNT_sma=v3 \nsvars \nendif \n\nif upsecs%tper==0{ \nsmn=v1-sma \nHT_smn=v2-HT_sma \nNT_smn=v3-NT_sma \n} \n\n;Yearly usage \nyr=year \nif chg[yr]>0 \nand v1>0 \nthen \nsya=v1 \nHT_sya=v2 \nNT_sya=v3 \nsvars \nendif \n\nif upsecs%tper==0{ \nsyn=v1-sya \nHT_syn=v2-HT_sya \nNT_syn=v3-NT_sya \n\n; Json payload \\> send on teleperiod \n>J \n,\"Strom_Vb_Tag\":%3sd% \n,\"HT_Strom_Vb_Tag\":%3HT_sd% \n,\"NT_Strom_Vb_Tag\":%3NT_sd% \n,\"Strom_Vb_M\":%1smn% \n,\"HT_Strom_Vb_M\":%1HT_smn% \n,\"NT_Strom_Vb_M\":%1NT_smn% \n,\"Strom_Vb_Jahr\":%0syn% \n,\"HT_Strom_Vb_Jahr\":%0HT_syn% \n,\"NT_Strom_Vb_Jahr\":%0NT_syn% \n,\"Strom_0:00 _Uhr\":%1sm% \n,\"HT_Strom_0:00 _Uhr\":%1HT_sm% \n,\"NT_Strom_0:00 _Uhr\":%1NT_sm% \n,\"Strom_Ma\":%3sma% \n,\"HT_Strom_Ma\":%3HT_sma% \n,\"NT_Strom_Ma\":%3NT_sma% \n,\"Strom_Ja\":%3sya% \n,\"HT_Strom_Ja\":%3HT_sya% \n,\"NT_Strom_Ja\":%3NT_sya% \n\n;Webdisplay stuff \n>W \n\n0:00 Uhr \u03a3 HT+NT: {m} %0sm% KWh \nHT: {m} %0HT_sm% KWh \nNT: {m} %0NT_sm% KWh \n\nMonatsanfang: {m} %1sma% KWh \nHT: {m} %1HT_sma% KWh \nNT: {m} %1NT_sma% KWh \n\nJahresanfang: {m} %0sya% KWh \nHT: {m} %0HT_sya% KWh \nNT: {m} %0NT_sya% KWh \n............................. \nTagesverbrauch: {m} %1sd% KWh \nHT: {m} %1HT_sd% KWh \nNT: {m} %1NT_sd% KWh \n\nMonatsverbrauch: {m} %0smn% KWh \nHT: {m} %0HT_smn% KWh \nNT: {m} %0NT_smn% KWh \n - \nJahresverbrauch: {m} %0syn% KWh \nHT: {m} %0HT_syn% KWh \n0:00 Uhr \u03a3 HT+NT: {m} %0sm% KWh \nHT: {m} %0HT_sm% KWh \nNT: {m} %0NT_sm% KWh \n\nMonatsanfang: {m} %1sma% KWh \nHT: {m} %1HT_sma% KWh \nNT: {m} %1NT_sma% KWh \n\nJahresanfang: {m} %0sya% KWh \nHT: {m} %0HT_sya% KWh \nNT: {m} %0NT_sya% KWh \n............................. \nTagesverbrauch: {m} %1sd% KWh \nHT: {m} %1HT_sd% KWh \nNT: {m} %1NT_sd% KWh \n\nMonatsverbrauch: {m} %0smn% KWh \nHT: {m} %0HT_smn% KWh \nNT: {m} %0NT_smn% KWh \n - \nJahresverbrauch: {m} %0syn% KWh \nHT: {m} %0HT_syn% KWh \nNT: {m} %0NT_syn% KWhNT: {m} %0NT_syn% KWh \n\n>M 1 \n+1,3,o,0,9600,,1 \n1,0.0.1(@1,Z\u00e4hlernummer,,Meter_number,0 \n1,0.9.1(@#),Zeitstempel,Uhr,time-stamp,0 \n1,=h=================== \n1,1.8.0(@1,HT+NT Z\u00e4hlerstand,KWh,Total_in,3 \n1,1.8.1(@1,HT,KWh,HT_Total_in,3 \n1,1.8.2(@1,NT,KWh,NT_Total_in,3 \n1,=h=================== \n1,36.7.0(@1,Power_L1,kW,kW_L1,2 \n1,56.7.0(@1,Power_L2,kW,kW_L2,2 \n1,76.7.0(@1,Power_L3,kW,kW_L3,2 \n1,16.7.0(@1,\u03a3_L1+L2+L3,kW,kW_L1+L2+L3,2 \n1,=h=================== \n1,31.7.0(@1,Strom_L1,A,I_L1,2 \n1,51.7.0(@1,Strom_L2,A,I_L2,2 \n1,71.7.0(@1,Strom_L3,A,I_L3,2 \n#\n
"},{"location":"Smart-Meter-Interface/#2-landisgyr-e450-encrypted","title":"2 * Landis+Gyr E450 (encrypted)","text":"View script >D\n>B\nsmlj=0\n=>sensor53 r\n>R\nsmlj=0\n>S\nif upsecs>22\nthen\nsmlj|=1\nendif\n>M 2\n+1,17,r,0,2400,Heizung\n1,=so3,512\n1,=so4,GUEK\n1,pm(1.8.0)@1000,kWh_IN,kWh,kWh_IN,3;Wirkenergie Lieferung (+A)\n1,pm(1.8.1)@1000,kWh_IN_T1,kWh,kWh_IN_T1,3;Wirkenergie Lieferung (+A) Tarif 1\n1,pm(1.8.2)@1000,kWh_IN_T2,kWh,kWh_IN_T2,3;Wirkenergie Lieferung (+A) Tarif 2\n1,pm(1.7.0)@1000,kW_IN,kW,kW_IN,3;Momentane Wirkleistung Lieferung (+A)\n;1,pm(2.8.0)@1000,kWh_OUT,kWh,kWh_OUT,3;Wirkenergie Bezug (-A)\n;1,pm(2.8.1)@1000,kWh_OUT_T1,kWh,kWh_OUT_T1,3;Wirkenergie Bezug (-A) Tarif 1\n;1,pm(2.8.2)@1000,kWh_OUT_T2,kWh,kWh_OUT_T2,3;Wirkenergie Bezug (-A) Tarif 2\n;1,pm(.2.7.0)@1000,kW_OUT,kW,kW_OUT,3;Momentane Wirkleistung Bezug (-A)\n1,pm(3.8.0)@1000,kvarh_IN,kvarh,kvarh_IN,3;Blindenergie Lieferung (+R)\n1,pm(.3.8.1)@1000,kvarh_IN_T1,kvarh,kvarh_IN_T1,3;Blindenergie Lieferung (+R) Tarif 1\n1,pm(.3.8.2)@1000,kvarh_IN_T2,kvarh,kvarh_IN_T2,3;Blindenergie Lieferung (+R) Tarif 2\n1,pm(.3.7.0)@1000,kvar_IN,kvar,kvar_IN,3;Momentane Blindleistung Lieferung (+R)\n1,pm(4.8.0)@1000,kvarh_OUT,kvarh,kvarh_OUT,3;Blindenergie Bezug (-R)\n1,pm(.4.8.1)@1000,kvarh_OUT_T1,kvarh,kvarh_OUT_T1,3;Blindenergie Bezug (-R) Tarif 1\n1,pm(.4.8.2)@1000,kvarh_OUT_T2,kvarh,kvarh_OUT_T2,3;Blindenergie Bezug (-R) Tarif 2\n1,pm(.4.7.0)@1000,kvar_OUT,kvar,kvar_OUT,3;Momentane Blindleistung Bezug (-R)\n\n+2,16,r,0,2400,Haus\n2,=so3,512\n2,=so4,GUEK\n2,pm(1.8.0)@1000,kWh_IN,kWh,kWh_IN,3;Wirkenergie Lieferung (+A)\n2,pm(1.8.1)@1000,kWh_IN_T1,kWh,kWh_IN_T1,3;Wirkenergie Lieferung (+A) Tarif 1\n2,pm(1.8.2)@1000,kWh_IN_T2,kWh,kWh_IN_T2,3;Wirkenergie Lieferung (+A) Tarif 2\n2,pm(1.7.0)@1000,kW_IN,kW,kW_IN,3;Momentane Wirkleistung Lieferung (+A)\n;2,pm(2.8.0)@1000,kWh_OUT,kWh,kWh_OUT,3;Wirkenergie Bezug (-A)\n;2,pm(2.8.1)@1000,kWh_OUT_T1,kWh,kWh_OUT_T1,3;Wirkenergie Bezug (-A) Tarif 1\n;2,pm(2.8.2)@1000,kWh_OUT_T2,kWh,kWh_OUT_T2,3;Wirkenergie Bezug (-A) Tarif 2\n;2,pm(2.7.0)@1000,kW_OUT,kW,kW_OUT,3;Momentane Wirkleistung Bezug (-A)\n2,pm(.3.8.0)@1000,kvarh_IN,kvarh,kvarh_IN,3;Blindenergie Lieferung (+R)\n2,pm(3.8.1)@1000,kvarh_IN_T1,kvarh,kvarh_IN_T1,3;Blindenergie Lieferung (+R) Tarif 1\n2,pm(3.8.2)@1000,kvarh_IN_T2,kvarh,kvarh_IN_T2,3;Blindenergie Lieferung (+R) Tarif 2\n2,pm(3.7.0)@1000,kvar_IN,kvar,kvar_IN,3;Momentane Blindleistung Lieferung (+R)\n2,pm(4.8.0)@1000,kvarh_OUT,kvarh,kvarh_OUT,3;Blindenergie Bezug (-R)\n2,pm(4.8.1)@1000,kvarh_OUT_T1,kvarh,kvarh_OUT_T1,3;Blindenergie Bezug (-R) Tarif 1\n2,pm(4.8.2)@1000,kvarh_OUT_T2,kvarh,kvarh_OUT_T2,3;Blindenergie Bezug (-R) Tarif 2\n2,pm(4.7.0)@1000,kvar_OUT,kvar,kvar_OUT,3;Momentane Blindleistung Bezug (-R)\n#\n
"},{"location":"Smart-Meter-Interface/#landisgyr-e650-obis","title":"Landis+Gyr E650 (OBIS)","text":"The script switches to a higher baud rate as the data set is pretty big and takes minutes to complete at 300 baud. The usable speed for my setup/hardware was 4800 baud.
The script requires tasmota version 12+ so it supports variables.
Switching to different baud rates requires changing the ack sequence 06303x300D0A, the baud rate in 2 places 4800->x and the case 200 (20x100ms) so the cycle can complete before restarting.
View script >D\n; Script needs v12+\nres=0\nscnt=0\n>F\n;F section is executed every 100ms\nscnt+=1\nswitch scnt\ncase 6\n;set sml driver to 300 baud and send /?! as HEX to trigger the Meter\nres=sml(1 0 300)\nres=sml(1 1 \"2F3F210D0A\")\n;1800ms later \\> Send ACK and ask for switching to 4800 baud\ncase 18\nres=sml(1 1 \"063034300D0A\")\nres=sml(1 0 4800)\ncase 200\n; 20s later \\> restart sequence\nscnt=0\nends \n>M 1\n+1,3,o,0,4800,data,1\n\n1,1-1:1.8.0(@1,energy_import,KWh,1-8-0,1\n1,1-1:2.8.0(@1,energy_export,KWh,2-8-0,1\n1,1-1:36.7.0(@1,power_L1,KWh,36-7-0,2\n1,1-1:56.7.0(@1,power_L2,KWh,56-7-0,2\n1,1-1:76.7.0(@1,power_L3,KWh,76-7-0,2\n1,1-1:31.7.0(@1,current_L1,A,31-7-0,2\n1,1-1:51.7.0(@1,current_L2,A,51-7-0,2\n1,1-1:71.7.0(@1,current_L3,A,71-7-0,2\n1,1-1:16.7.0(@1,power_total,W,16-7-0,2\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk11bl-obis","title":"Logarex LK11BL (OBIS)","text":"This script keeps optical communication on the initial 300 baud speed and reject to switch any other speed smart meter requests.\n\nIn my case, smart meter wanted to switch to 9600 baud but I felt it is better to follow the 'keep it simple' principle at the script's level and use 300 baud through the whole communication.\n\nIf you know the meaning of the below unnamed OBIS codes please update the script.\n
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,300,zm,1,100,2F3F210D0A,060000D0A\n\n1,15.8.0(@1,total,kWh,total,3\n1,0.0.0(@1,serial,,serial,0\n1,F.F(@1,F.F,,F.F,0\n1,C.8.0(@1,C.8.0,,C.8.0,0\n1,0.2.0(@#),ver,,ver,3\n1,0.3.0(@1,0.3.0,imp/kWh,0.3.0,0\n1,.8.1(@1,.8.1,,.8.1,0\n1,C.7.1(@1,C.7.1,,C.7.1,0\n1,C.2.1(@1,C.2.1,,C.2.1,0\n1,C.2.9(@1,C.2.9,,C.2.9,0\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk13be-obis","title":"Logarex LK13BE (OBIS)","text":"View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,9600,LK13BE,13,30,2F3F210D0A,063035310D0A\n\n1,1-0:1.8.0*255(@1,Gesamtverbrauch,KWh,total,4\n1,1-0:1.8.0*96(@1,Verbrauch 1 Tag,KWh,total_1d,4\n1,1-0:1.8.0*97(@1,Verbrauch 7 Tage,KWh,total_7d,4\n1,1-0:1.8.0*98(@1,Verbrauch 30 Tage,KWh,total_30d,4\n1,1-0:1.8.0*99(@1,Verbrauch 365 Tage,KWh,total_365d,4\n1,1-0:16.7.0*255(@1,Verbrauch aktuell,W,power,20\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk13be803039","title":"Logarex LK13BE803039","text":"The Logarex LK13BE803039 does publish the data automatically. Do not poll this can lead to missreadings
View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,o,0,9600,LK13BE\n\n1,1-0:1.8.0*255(@1,Gesamtverbrauch,KWh,total,4\n1,1-0:1.8.0*96(@1,Verbrauch 1 Tag,KWh,total_1d,4\n1,1-0:1.8.0*97(@1,Verbrauch 7 Tage,KWh,total_7d,4\n1,1-0:1.8.0*98(@1,Verbrauch 30 Tage,KWh,total_30d,4\n1,1-0:1.8.0*99(@1,Verbrauch 365 Tage,KWh,total_365d,4\n1,1-0:16.7.0*255(@1,Verbrauch aktuell,W,current,20\n1,1-0:2.8.0*255(@1,Gesamteinspeisung,KWh,total_out,4\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk13be803319-obis","title":"Logarex LK13BE803319 (OBIS)","text":"setupline for the HichiIR WiFi module (GPIO1: send, GPIO3: receive)
View script >D\n>B\n=>sensor53 r\n>M 1\n; setupline\n+1,3,o,0,9600,LK13BE,1,30,2F3F210D0A,063035310D0A\n; available without PIN, remove the semicolon the enable some optional values\n; only one string (@#) can be decoded per meter\n1,1-0:96.1.0*255(@#),Z\u00e4hlernummer,,id,0\n;1,1-0:0.2.0*255(@#),Firmware,,fw,0\n1,1-0:1.8.0*255(@1,Gesamtverbrauch,KWh,total,4\n; available with PIN\n1,1-0:1.8.0*96(@1,Verbrauch 1 Tag,KWh,total_1d,4\n1,1-0:1.8.0*97(@1,Verbrauch 7 Tage,KWh,total_7d,4\n1,1-0:1.8.0*98(@1,Verbrauch 30 Tage,KWh,total_30d,4\n1,1-0:1.8.0*99(@1,Verbrauch 365 Tage,KWh,total_365d,4\n1,1-0:1.8.0*100(@1,Verbrauch ab reset,KWh,total_reset,4\n1,1-0:16.7.0*255(@1,Verbrauch aktuell,W,power,20\n; available with PIN and full dataset enabled\n1,1-0:32.7.0*255(@1,Spannung L1,V,voltage_l1,1\n1,1-0:52.7.0*255(@1,Spannung L2,V,voltage_l2,1\n1,1-0:72.7.0*255(@1,Spannung L3,V,voltage_l3,1\n1,1-0:31.7.0*255(@1,Strom L1,A, amperage_l1,1\n1,1-0:51.7.0*255(@1,Strom L2,A, amperage_l2,1\n1,1-0:71.7.0*255(@1,Strom L3,A, amperage_l3,1\n1,1-0:81.7.1*255(@1,UL2 zu UL1,deg,angle_ul2_ul1,0\n1,1-0:81.7.2*255(@1,UL3 zu UL1,deg,angle_ul3_ul1,0\n1,1-0:81.7.4*255(@1,IL1 zu UL1,deg,angle_il1_ul1,0\n1,1-0:81.7.15*255(@1,IL2 zu UL2,deg,angle_il2_ul2,0\n1,1-0:81.7.26*255(@1,IL3 zu UL3,deg,angle_il2_ul3,0\n1,1-0:14.7.0*255(@1,Frequenz,Hz,frequency,1\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk13be-sml-lk13be904639","title":"Logarex LK13BE (SML) (LK13BE904639)","text":"This meter does not provide detailed information regarding phase etc.
View script >D\n>B\n=>sensor53 r\n; Monitor Sensor at GPIO25\n=>sensor53 l25\n>M 1\n+1,3,s,0,9600,LK13BE,1,10,2F3F210D0A,063035310D0A\n\n1,77070100010800ff@1000,Energie gesamt,kWh,energy_sum,3 \n1,77070100010801ff@1000,Energie Tarif 1,kWh,energy_tarif1,3 \n1,77070100010802ff@1000,Energie Tarif 2,kWh,energy_tarif2,3\n1,77070100020800ff@1000,Einspeisung,kWh,energy_supply,3\n1,=h --------------\n1,77070100100700ff@1,Leistung,W,power,16\n1,=h --------------\n1,77070100600100ff@#,Server ID,,meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#logarex-lk13be-sml-eg-lk13be6067x9","title":"Logarex LK13BE (SML) (e.g. LK13BE6067x9)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,LK13BE,1,10,2F3F210D0A,063035310D0A\n\n1,77070100010800ff@1000,Gesamt kWh bezogen,kWh,Power_total_in,1\n1,77070100020800ff@1000,Gesamt kWh geliefert,kWh,Power_total_out,1\n1,77070100100700ff@1,Verbrauch aktuell,W,Power_curr,0\n1,77070100240700ff@1,Power L1,W,Power_L1_curr,0\n1,77070100380700ff@1,Power L2,W,Power_L2_curr,0\n1,770701004C0700ff@1,Power L3,W,Power_L3_curr,0\n1,77070100200700ff@1,Voltage L1,V,Volt_L1_curr,1\n1,77070100340700ff@1,Voltage L2,V,Volt_L2_curr,1\n1,77070100480700ff@1,Voltage L3,V,Volt_L3_curr,1\n1,770701001f0700ff@1,Amperage L1,A,Amperage_L1_curr,2\n1,77070100330700ff@1,Amperage L2,A,Amperage_L2_curr,2\n1,77070100470700ff@1,Amperage L3,A,Amperage_L3_curr,2\n1,770701000e0700ff@1,Frequency,Hz,HZ,2\n1,77070100510704ff@1,Phaseangle I-L1/U-L1,deg,phase_angle_p1,1 \n1,7707010051070fff@1,Phaseangle I-L2/I-L2,deg,phase_angle_p2,1 \n1,7707010051071aff@1,Phaseangle I-L3/I-L3,deg,phase_angle_p3,1 \n1,77070100510701ff@1,Phase angle U-L2/U-L1,deg,phase_angle_l2_l1,1\n1,77070100510702ff@1,Phase angle U-L3/U-L1,deg,phase_angle_l3_l1,1\n#\n
"},{"location":"Smart-Meter-Interface/#norax-3d-sml","title":"Norax 3D+ (SML)","text":"This script gives also the wattage per phase. Make sure to get the PIN from your grid operator! Tested on a WeMos D1 mini with an IR Head from https://agalakhov.github.io/ir-interface connected to the RX pin (3). The meter also outputs the phase angles, but i left them out since i do not need them. You can easily find additional values by activating the debug mode (\"sensor53 d1\" for the first meter, switch off after a few seconds with \"sensor53 d0\").
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,1,9600,SML\n1,77070100010800ff@1000,Total consumption,KWh,Total_in,4\n1,77070100020800ff@1000,Total Feed,KWh,Total_out,4\n1,77070100100700ff@1,Current consumption,W,Power_curr,0\n1,77070100200700ff@1,Voltage L1,V,Volt_p1,1\n1,77070100340700ff@1,Voltage L2,V,Volt_p2,1\n1,77070100480700ff@1,Voltage L3,V,Volt_p3,1\n1,770701001f0700ff@1,Amperage L1,A,Amperage_p1,1\n1,77070100330700ff@1,Amperage L2,A,Amperage_p2,1\n1,77070100470700ff@1,Amperage L3,A,Amperage_p3,1\n1,77070100240700ff@1,Current consumption L1,W,Power_curr_p1,0\n1,77070100380700ff@1,Current consumption L2,W,Power_curr_p2,0\n1,770701004c0700ff@1,Current consumption L3,W,Power_curr_p3,0\n1,770701000e0700ff@1,Frequency,Hz,frequency,0\n#\n
"},{"location":"Smart-Meter-Interface/#pafal-20ec3gr","title":"PAFAL 20EC3gr","text":"Documentation for this Counter is very small. This informations were collected across the internet.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,o,0,300,PAFAL,1,30,2F3F210D0A,063030300D0A\n1,1.8.1*00(@1),Gesamtverbrauch_HT,kWh,Total_IN,2\n1,1.8.2*00(@1),Gesamtverbrauch_NT,kWh,Total_IN,2\n1,2.8.0*00(@1),Einspeisung,kWh,Total_OUT,2\n#\n
Dump of the script 15:48:40.855 : \ufffdH/PAF5EC3gr00006\n15:48:45.643 : \ufffd0.0.0(serialnumber)\n15:48:46.260 : 0.0.1(PAF)\n15:48:46.768 : F.F(00)\n15:48:47.405 : 0.2.0(1.27)\n15:48:48.314 : 1.8.1*00(071354.27)\n15:48:49.228 : 1.8.2*00(070726.91)\n15:48:50.149 : 2.8.0*00(013640.33)\n15:48:52.730 : C.2.1(000000000000)( )\n15:48:53.542 : 0.2.2(:::::G11)!\n
"},{"location":"Smart-Meter-Interface/#peacefair-pzem004tv30-modbus","title":"Peacefair PZEM004TV30 (MODBUS)","text":"PZEM004T V30 multiple meters on Modbus
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,m,0,9600,ENERGY,1,1,02040000,02040001,02040003,02040005,02040007,02040008,03040000,03040001,03040003,03040005,03040007,03040008,05040000,05040001,05040003,05040005,05040007,05040008\n1,=h<hr/>Sensor-1\n1,020404UUuuxxxxxxxx@i0:10,Voltage,V,Sensor-1-V,2\n1,020404UUuuUUuusxxxx@i1:1000,Current,A,Sensor-1-A,2\n1,020404UUuuUUuusxxxx@i2:10,Power,W,Sensor-1-W,2\n1,020404UUuuUUuusxxxx@i3:1000,Energy,kWh,Sensor-1-kWh,4\n1,020404UUuuxxxxxxxx@i4:10,Frequency,Hz,Sensor-1-hz,2\n1,020404UUuuxxxxxxxx@i5:100,Power Factor,PF,Sensor-1-PF,2\n1,=h<hr/>Sensor-2\n1,030404UUuuxxxxxxxx@i6:10,Voltage,V,Sensor-2-V,2\n1,030404UUuuUUuusxxxx@i7:1000,Current,A,Sensor-2-A,2\n1,030404UUuuUUuusxxxx@i8:10,Power,W,Sensor-2-W,2\n1,030404UUuuUUuusxxxx@i9:1000,Energy,kWh,Sensor-2-kWh,4\n1,030404UUuuxxxxxxxx@i10:10,Frequency,Hz,Sensor-2-hz,2\n1,030404UUuuxxxxxxxx@i11:100,Power Factor,PF,Sensor-2-PF,2\n1,=h<hr/>Sensor-5\n1,050404UUuuxxxxxxxx@i12:10,Voltage,V,Sensor-05-V,2\n1,050404UUuuUUuusxxxx@i13:1000,Current,A,Sensor-05-A,2\n1,050404UUuuUUuusxxxx@i14:10,Power,W,Sensor-05-W,2\n1,050404UUuuUUuusxxxx@i15:1000,Energy,kWh,Sensor-05-kWh,4\n1,050404UUuuxxxxxxxx@i16:10,Frequency,Hz,Sensor-05-hz,2\n1,050404UUuuxxxxxxxx@i17:100,Power Factor,PF,Sensor-05-PF,2\n\n#\n
"},{"location":"Smart-Meter-Interface/#resol-deltasol-bs-plus-vbus","title":"Resol Deltasol BS Plus (VBus)","text":"This is a controller for standard solar thermal systems equipped with VBus data interface. Outputs data every second at 9600 baud 8N1. To connect to this and read data from the bus a level shifting is needed as the voltage is around 8V. Although this is a symmetric connection supporting long wires for our purposes it's enough to measure its polarity with a voltmeter and adapt the level appropriately to 3.3V using the below circuit (many others exist but this is simple and works). Do not connect the GND pin of Wemos with the ground of Resol unit as that may damage the output port of it. The Wemos module needs its own power supply (double insulated recommended).
The script (compile firmware with SML_REPLACE_VARS) >D\nr=\"1,AA100021421000010774\"\n>B\n=>sensor53 r\n>M 1\n+1,3,v,0,9600,Solar\n%r%vo12ut@#,time,,zeit,1\n%r%vo0sw@10,S1 COL,\u00b0C,sens1,1\n%r%vo2sw@10,S2 TST1,\u00b0C,sens2,1\n%r%vo4sw@10,S3 TST2,\u00b0C,sens3,1\n%r%vo6sw@10,S4 TR,\u00b0C,sens4,1\n%r%vo10ub@b0:1,R1 PUMP,,relay1,0\n%r%vo10ub@b1:1,R2 VALVE,,relay2,0\n%r%vo8ub@1,Pump1 speed,%%,pump1,0\n%r%vo9ub@1,Pump2 speed,%%,pump2,0\n%r%vo20uw@1,p1,Wh,p1,0\n%r%vo22uw@1,p1000,Wh,p2,0\n%r%vo24uw@1,p1000000,Wh,p3,0\n%r%vo15ub@b0:1,Col Max,,col1,0\n%r%vo15ub@b1:1,Col Min,,col2,0\n%r%vo15ub@b2:1,Col Frost,,col3,0\n%r%vo15ub@b3:1,Col Opt,,col4,0\n%r%vo15ub@b4:1,Col Rueck,,col5,0\n%r%vo15ub@b5:1,Col WMZ,,col6,0\n#\n
"},{"location":"Smart-Meter-Interface/#sanxing-sx6x1-sxxu1x-ascii-obis","title":"Sanxing SX6x1 (SxxU1x) (Ascii OBIS)","text":"Tested on SX631 (S34U18). Needs an RJ12 cable and a small adaptor circuit: (Note how power for the Wemos module is drawn directly from the meter. No external power supply needed)
This meter sends bursts of data at 115200 baud every 10 seconds. Some data lines exceed 1038 characters. To adapt to these conditions, compile firmware with:
#define SML_BSIZ 1060\n#define MAX_METERS 1\n#define TMSBSIZ 2048\n#define USE_SML_SCRIPT_CMD\n#define SML_REPLACE_VARS\n
View script >D\nr=\"1,0-0:98.1.0(@(\"\n;use a variable to store the decode string\n>B\nsmlj=0\n;don't send teleperiod MQTT at boot, because we can have 0 values (meter didn't send data yet)\n->sensor53 r\n>R\nsmlj=0\n;don't send teleperiod MQTT at script restart, because we can have 0 values (meter didn't send data yet)\n>S\nif upsecs>22\nthen\nsmlj|=1\nendif\n;only send teleperiod MQTT if 22 seconds passed since boot (during this time meter most probably sent data)\n>M 1\n+1,3,o,16,115200,Name,1\n1,1-0:32.7.0(@1,L1 Voltage,V,volts_l1,1\n1,1-0:52.7.0(@1,L2 Voltage,V,volts_l2,1\n1,1-0:72.7.0(@1,L3 Voltage,V,volts_l3,1\n1,1-0:14.7.0(@1,Frequency,Hz,freq,2\n1,0-0:96.14.0(@1,Current tariff,,tariff,0\n1,=h<hr/>\n1,1-0:1.8.0(@1,Energy import,kWh,enrg_imp,3\n1,1-0:2.8.0(@1,Energy export,kWh,enrg_exp,3\n1,1-0:1.8.1(@1,Energy import T1,kWh,enrg_imp_t1,3\n1,1-0:1.8.2(@1,Energy import T2,kWh,enrg_imp_t2,3\n1,1-0:2.8.1(@1,Energy export T1,kWh,enrg_exp_t1,3\n1,1-0:2.8.2(@1,Energy export T2,kWh,enrg_exp_t2,3\n1,1-0:1.7.0(@1,Power import,kW,pwr_imp,3\n1,1-0:2.7.0(@1,Power export,kW,pwr_exp,3\n1,1-0:13.7.0(@1,Power factor,,factor,3\n1,=h<hr/>\n1,1-0:3.8.0(@1,Reactive nrg import,kvarh,nrg_reac_imp,3\n1,1-0:4.8.0(@1,Reactive nrg export,kvarh,nrg_reac_exp,3\n1,1-0:5.8.0(@1,Reactive energy QI,kvarh,nrg_reac_q1,3\n1,1-0:6.8.0(@1,Reactive energy QII,kvarh,nrg_reac_q2,3\n1,1-0:7.8.0(@1,Reactive energy QIII,kvarh,nrg_reac_q3,3\n1,1-0:8.8.0(@1,Reactive energy QIV,kvarh,nrg_reac_q4,3\n1,1-0:5.7.0(@1,Reactive power QI,kvar,pwr_reac_q1,3\n1,1-0:6.7.0(@1,Reactive power QII,kvar,pwr_reac_q2,3\n1,1-0:7.7.0(@1,Reactive power QIII,kvar,pwr_reac_q3,3\n1,1-0:8.7.0(@1,Reactive power QIV,kvar,pwr_reac_q4,3\n1,=h<hr/>\n1,=hPrevious month stats:\n%r%1:1,Energy import,kWh,mo_enrg_imp,3\n%r%2:1,Energy import T1,kWh,mo_enrg_impt1,3\n%r%3:1,Energy import T2,kWh,mo_enrg_impt2,3\n%r%4:1,Energy export,kWh,mo_enrg_exp,3\n%r%5:1,Energy export T1,kWh,mo_enrg_expt1,3\n%r%6:1,Energy export T2,kWh,mo_enrg_expt2,3\n%r%7:1,Reactive nrg import,kvarh,mo_nrg_reac_imp,3\n%r%8:1,Reactive nrg export,kvarh,mo_nrg_reac_exp,3\n%r%9:1,Reactive energy QI,kvarh,mo_nrg_reac_q1,3\n%r%10:1,Reactive energy QII,kvarh,mo_nrg_reac_q2,3\n%r%11:1,Reactive energy QIII,kvarh,mo_nrg_reac_q3,3\n%r%12:1,Reactive energy QIV,kvarh,mo_nrg_reac_q4,3\n%r%13:1,Reactive energy SUM?,kvarh,mo_nrg_reac_sum,3\n%r%14:1,Peak power import L1,kW,mo_pw_pk_in_l1,3\n%r%15:1,Peak power import L2,kW,mo_pw_pk_in_l2,3\n%r%16:1,Peak power import L3,kW,mo_pw_pk_in_l3,3\n%r%17:1,Peak power export L1,kW,mo_pw_pk_ex_l1,3\n%r%18:1,Peak power export L2,kW,mo_pw_pk_ex_l2,3\n%r%19:1,Peak power export L3,kW,mo_pw_pk_ex_l3,3\n#\n
Sample data /1234567890123\n\n0-0:1.0.0(202056789012W)\n0-0:42.0.0(AUX1234567890123)\n0-0:96.1.0(1234567890)\n0-0:96.14.0(0001)\n0-0:96.50.68(ON)\n0-0:17.0.0(90.000*kW)\n1-0:1.8.0(000258.072*kWh)\n1-0:1.8.1(000103.782*kWh)\n1-0:1.8.2(000154.290*kWh)\n1-0:1.8.3(000000.000*kWh)\n1-0:1.8.4(000000.000*kWh)\n1-0:2.8.0(000048.367*kWh)\n1-0:2.8.1(000032.813*kWh)\n1-0:2.8.2(000015.554*kWh)\n1-0:2.8.3(000000.000*kWh)\n1-0:2.8.4(000000.000*kWh)\n1-0:3.8.0(000003.513*kvarh)\n1-0:4.8.0(000156.910*kvarh)\n1-0:5.8.0(000003.498*kvarh)\n1-0:6.8.0(000000.015*kvarh)\n1-0:7.8.0(000027.718*kvarh)\n1-0:8.8.0(000129.192*kvarh)\n1-0:15.8.0(000306.440*kWh)\n1-0:32.7.0(233.0*V)\n1-0:52.7.0(230.6*V)\n1-0:72.7.0(228.7*V)\n1-0:31.7.0(002*A)\n1-0:51.7.0(002*A)\n1-0:71.7.0(001*A)\n1-0:13.7.0(0.758)\n1-0:33.7.0(0.615)\n1-0:53.7.0(0.746)\n1-0:73.7.0(0.937)\n1-0:14.7.0(49.98*Hz)\n1-0:1.7.0(00.000*kW)\n1-0:2.7.0(00.854*kW)\n1-0:5.7.0(00.000*kvar)\n1-0:6.7.0(00.000*kvar)\n1-0:7.7.0(00.735*kvar)\n1-0:8.7.0(00.000*kvar)\n0-0:98.1.0(210301000000W)(000249.070*kWh)(000100.816*kWh)(000148.254*kWh)(000047.903*kWh)(000032.349*kWh)(000015.554*kWh)(000003.513*kvarh)(000150.665*kvarh)(000003.498*kvarh)(000000.015*kvarh)(000027.119*kvarh)(000123.546*kvarh)(000296.974*kWh)(04.872*kW)(04.872*kW)(04.072*kW)(01.844*kW)(01.672*kW)(01.844*kW)\n0-0:96.13.0(\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd)\n!DA6A\n
"},{"location":"Smart-Meter-Interface/#sbc-ale3-modbus","title":"SBC ALE3 (MODBus)","text":"View script >DH\n>B\n->sensor53 r\n>M 1\n+1,3,M,1,9600,SBC,1,1,02030023,02030028,0203002d,02030025,0203002a,0203002f,02030032,02030027,0203002c,02030031,02030021,02030015,02030018\n1,020304UUuu@i0:1,Spannung L1,V,Voltage_L1,0\n1,020304UUuu@i1:1,Spannung L2,V,Voltage_L2,0\n1,020304UUuu@i2:1,Spannung L3,V,Voltage_L3,0\n1,020304xxxxUUuu@i0:10,Strom L1,A,Current_L1,2\n1,020304xxxxUUuu@i1:10,Strom L2,A,Current_L2,2\n1,020304xxxxUUuu@i2:10,Strom L3,A,Current_L3,2\n1,=h=\n1,020304UUuu@i3:100,Leistung L1,kW,Power_L1,3\n1,020304UUuu@i4:100,Leistung L2,kW,Power_L2,3\n1,020304UUuu@i5:100,Leistung L3,kW,Power_L3,3\n1,020304UUuu@i6:100,Leistung Total,kW,Power_Total,3\n1,020304xxxxSSss@i3:100,BlindLeistung L1,kVAr,ReaktivePower_L1,3\n1,020304xxxxSSss@i4:100,BlindLeistung L2,kVAr,ReaktivePower_L2,3\n1,020304xxxxSSss@i5:100,BlindLeistung L3,kVAr,ReaktivePower_L3,3\n1,020304xxxxSSss@i6:100,BLeistung Total,kVAr,ReaktivePower_Total,3\n1,=h=\n1,020304UUuu@i7:100,CosPhi L1,,CosPhi_L1,2\n1,020304UUuu@i8:100,CosPhi L2,,CosPhi_L2,2\n1,020304UUuu@i9:100,CosPhi L3,,CosPhi_L3,2\n1,=h=\n1,020304UUuuUUuu@i10:100,T2 Wert,kWh,T2_Value,2\n#\n
"},{"location":"Smart-Meter-Interface/#sbc-ale3-2x-modbus","title":"SBC ALE3 2x (MODBus)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,M,1,9600,Meter,1,1,01030023,01030028,0103002d,01030025,0103002a,0103002f,01030032,01030027,0103002c,01030031,0103001B,0103001d,03030023,03030028,0303002d,03030025,0303002a,0303002f,03030032,03030027,0303002c,03030031,0303001B,0303001d\n1,=h Domestic Electricity:\n1,010304UUuuUUuu@i10:100,1 Tariff 1 total,kWh,M1_T1_total,2\n1,010304UUuuUUuu@i11:100,1 Tariff 1 partial,kWh,M1_T1_par,2\n1,=h Readings:\n1,010304UUuu@i0:1,1 Voltage L1,V,M1_Voltage_L1,0\n1,010304UUuu@i1:1,1 Voltage L2,V,M1_Voltage_L2,0\n1,010304UUuu@i2:1,1 Voltage L3,V,M1_Voltage_L3,0\n1,010304xxxxUUuu@i0:10,1 Current L1,A,M1_Current_L1,2\n1,010304xxxxUUuu@i1:10,1 Current L2,A,M1_Current_L2,2\n1,010304xxxxUUuu@i2:10,1 Current L3,A,M1_Current_L3,2\n1,010304UUuu@i3:100,1 Active Power L1,kW,M1_PRMS_L1,3\n1,010304UUuu@i4:100,1 Active Power L2,kW,M1_PRMS_L2,3\n1,010304UUuu@i5:100,1 Active Power L3,kW,M1_PRMS_L3,3\n1,010304UUuu@i6:100,1 Active Power total,kW,M1_PRMS_total,3\n1,010304xxxxSSss@i3:100,1 Reactive Power L1,kVAr,M1_QRMS_L1,3\n1,010304xxxxSSss@i4:100,1 Reactive Power L2,kVAr,M1_QRMS_L2,3\n1,010304xxxxSSss@i5:100,1 Reactive Power L3,kVAr,M1_QRMS_L3,3\n1,010304xxxxSSss@i6:100,1 Reactive Power total,kVAr,M1_QRMS_total,3\n1,010304UUuu@i7:100,1 CosPhi L1,,M1_CosPhi_L1,2\n1,010304UUuu@i8:100,1 CosPhi L2,,M1_CosPhi_L2,2\n1,010304UUuu@i9:100,1 CosPhi L3,,M1_CosPhi_L3,2\n1,=h________________________________________________\n; meter 2 +12 offset\n1,=h Heat Pump\n1,030304UUuuUUuu@i22:100,2 Tariff 1 total,kWh,M2_T1_total,2\n1,030304UUuuUUuu@i23:100,2 Tariff 1 partial,kWh,M2_T1_par,2\n1,=h Readings:\n1,030304UUuu@i12:1,2 Voltage L1,V,M2_Voltage_L1,0\n1,030304UUuu@i13:1,2 Voltage L2,V,M2_Voltage_L2,0\n1,030304UUuu@i14:1,2 Voltage L3,V,M2_Voltage_L3,0\n1,030304xxxxUUuu@i12:10,2 Current L1,A,M2_Current_L1,2\n1,030304xxxxUUuu@i13:10,2 Current L2,A,M2_Current_L2,2\n1,030304xxxxUUuu@i14:10,2 Current L3,A,M2_Current_L3,2\n1,030304UUuu@i15:100,2 Active Power L1,kW,M2_PRMS_L1,3\n1,030304UUuu@i16:100,2 Active Power L2,kW,M2_PRMS_L2,3\n1,030304UUuu@i17:100,2 Active Power L3,kW,M2_PRMS_L3,3\n1,030304UUuu@i18:100,2 Active Power total,kW,M2_PRMS_total,3\n1,030304xxxxSSss@i15:100,2 Reactive Power L1,kVAr,M2_QRMS_L1,3\n1,030304xxxxSSss@i16:100,2 Reactive Power L2,kVAr,M2_QRMS_L2,3\n1,030304xxxxSSss@i16:100,2 Reactive Power L3,kVAr,M2_QRMS_L3,3\n1,030304xxxxSSss@i18:100,2 Reactive Power total,kVAr,M2_QRMS_total,3\n1,030304UUuu@i19:100,2 CosPhi L1,,M2_CosPhi_L1,2\n1,030304UUuu@i20:100,2 CosPhi L2,,M2_CosPhi_L2,2\n1,030304UUuu@i21:100,2 CosPhi L3,,M2_CosPhi_L3,2\n#\n
"},{"location":"Smart-Meter-Interface/#schneider-iem3155-modbus","title":"Schneider iEM3155 (MODBus)","text":"Set device parity to NONE
View script >D \n>B \n->sensor53 r\n>M 1 \n+1,3,m,0,19200,iEM3155,1,1,0103B02D,0103B02B,01030BF3,01030BED,01030BEF,01030BF1,01030BD3,01030BD5,01030BD7,01030BB7,01030BB9,01030BBB,01030C0B,01030C25\n; ***************************************\n; * Schneider iEM3155 Energy Meter *\n; ***************************************\n; Serial: 19200\n; Set device parity to NONE\n; Slave address: 0x01\n; https://download.schneider-electric.com/files?p_Doc_Ref=DOCA0005EN&p_enDocType=User+guide&p_File_Name=DOCA0005EN-13.pdf\n1,010304ffffffff@i0:1,Gesamteinspeisung,kWh,Gesamteinspeisung,0\n1,010304ffffffff@i1:1,Gesamtverbrauch,kWh,Gesamtverbrauch,0\n1,010304ffffffff@i2:0.001,Momentanverbrauch,W,Momentanverbrauch,0\n1,010304ffffffff@i3:1,L1 Wirkenergie,kW,L1Wirkenergie,3\n1,010304ffffffff@i4:1,L2 Wirkenergie,kW,L2Wirkenergie,3\n1,010304ffffffff@i5:1,L3 Wirkenergie,kW,L3Wirkenergie,3\n1,010304ffffffff@i6:1,L1 Spannung,V,L1Spannung,0\n1,010304ffffffff@i7:1,L2 Spannung,V,L2Spannung,0\n1,010304ffffffff@i8:1,L3 Spannung,V,L3Spannung,0\n1,010304ffffffff@i9:1,L1 Strom,A,L1Strom,2\n1,010304ffffffff@i10:1,L2 Strom,A,L2Strom,2\n1,010304ffffffff@i11:1,L3 Strom,A,L3Strom,2\n1,010304ffffffff@i12:1,Leistungsfaktor,,Leistungsfaktor,2\n1,010304ffffffff@i13:1,Frequenz,Hz,Frequenz,0\n#\n
"},{"location":"Smart-Meter-Interface/#sdm230-modbus","title":"SDM230 (MODBus)","text":"View script >D \nms=\"1,010404ffffffff@\" \n>B \n->sensor53 r \n>M 1 \n+1,3,m,0,9600,PV,1,2,01040000,01040006,0104000C,01040012,01040018,0104001E,01040024,01040046,01040048,0104004A,0104004C,0104004E,01040054,01040056,01040058,0104005A,0104005C,0104005E,01040102,01040108,01040152,01040158,01040180,01040182 \n%ms%i0:1,Volt,V,Volt,2 \n%ms%i1:1,Strom P1,A,Strom,3 \n%ms%i2:1,*,W,Leistung,2 \n%ms%i3:1,Scheinleistung,VA,ScheinLeistung,2 \n%ms%i4:1,Blindleistung,VAr,Blindleistung,2 \n%ms%i5:1,P-Faktor,,P_Faktor,1 \n%ms%i6:1,cosPhi,\u00b0,cosPhi,2 \n%ms%i7:1,Frequenz,Hz, Frequenz,1 \n%ms%i8:1,Wirkleistung Import,kWh,Wirkleistung_Im1,3 \n%ms%i9:1,Wirkleistung Export,kWh,Wirkleistung_Ex,3 \n%ms%i10:1,Blindleistung Import,VkkVARh,Blindleistung_Im,3 \n%ms%i11:1,Blindleistung Export,VkkVARh,Blindleistung_Ex,3 \n%ms%i12:1,Gesamtleistungsbedarf,W,GesLeistBed,2 \n%ms%i13:1,GesamtLeistung Max,W,GesLeistMax,2 \n%ms%i14:1,Akt.Nachfrage,W,AktNachfrage,2 \n%ms%i15:1,R\u00fcckleistungs Bed,W,RueckLeistBed,2 \n%ms%i16:1,R\u00fcckleistungs Bed Max,W,RueckLeistBedMax,2 \n%ms%i17:1,Strom Nachfrage,A,StromNachfrage2,2 \n%ms%i19:1,Max Strombedarf,A,StromBedMax,2 \n%ms%i20:1,Wirkleistung Gesamt,kWh,Wirkleistung_total,2 \n%ms%i21:1,Blindleistung Gesamt,kVARh,Blindleistung_total,2 \n%ms%i22:1,Temp Gesamtleistung,kWh,TempGesamtLeist,2 \n# \n
"},{"location":"Smart-Meter-Interface/#sdm530-modbus","title":"SDM530 (MODBus)","text":"View script >D \n>B \n->sensor53 r\n>M 1 \n+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010 \n1,010404ffffffff@i0:1,Voltage P1,V,Voltage_P1,2 \n1,010404ffffffff@i1:1,Voltage P2,V,Voltage_P2,2 \n1,010404ffffffff@i2:1,Voltage P3,V,Voltage_P3,2 \n1,010404ffffffff@i3:1,Current P1,A,Current_P1,2 \n1,010404ffffffff@i4:1,Current P2,A,Current_P2,2 \n1,010404ffffffff@i5:1,Current P3,A,Current_P3,2 \n1,010404ffffffff@i6:1,Active Power P1,W,Power_P1,2 \n1,010404ffffffff@i7:1,Active Power P2,W,Power_P2,2 \n1,010404ffffffff@i8:1,Active Power P3,W,Power_P3,2 \n# \n
"},{"location":"Smart-Meter-Interface/#sdm72d-modbus","title":"SDM72D (MODBus)","text":"Script to extract readings from Eastron SDM72D Series devices (tested on SDM72D-M). Manual with comprehensive documentation about all Modbus registers available here.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,25,mN1,0,9600,SDM72D,26,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010,01040012,01040014,01040016,01040018,0104001a,0104001c,0104001e,01040020,01040022,0104002a,0104002e,01040030,01040034,01040038,0104003c,0104003e,01040046,01040048,0104004A,01040156,01040158,0104018c,01040500,01040502\n1,010404ffffffff@i0:1,Voltage P1,V,voltage_phase1,2\n1,010404ffffffff@i1:1,Voltage P2,V,voltage_phase2,2\n1,010404ffffffff@i2:1,Voltage P3,V,voltage_phase3,2\n1,010404ffffffff@i3:1,Current P1,A,current_phase1,2\n1,010404ffffffff@i4:1,Current P2,A,current_phase2,2\n1,010404ffffffff@i5:1,Current P3,A,current_phase3,2\n1,010404ffffffff@i6:1,Power P1,W,power_phase1,2\n1,010404ffffffff@i7:1,Power P2,W,power_phase2,2\n1,010404ffffffff@i8:1,Power P3,W,power_phase3,2\n1,010404ffffffff@i9:1,Power Apparent P1,VA,power_apparent_phase1,2\n1,010404ffffffff@i10:1,Power Apparent P2,VA,power_apparent_phase2,2\n1,010404ffffffff@i11:1,Power Apparent P3,VA,power_apparent_phase3,2\n1,010404ffffffff@i12:1,Power Reactive P1,VAr,power_reactive_phase1,2\n1,010404ffffffff@i13:1,Power Reactive P2,VAr,power_reactive_phase2,2\n1,010404ffffffff@i14:1,Power Reactive P3,VAr,power_reactive_phase3,2\n1,010404ffffffff@i15:1,Power Factor P1,,power_factor_phase1,2\n1,010404ffffffff@i16:1,Power Factor P2,,power_factor_phase2,2\n1,010404ffffffff@i17:1,Power Factor P3,,power_factor_phase3,2\n1,010404ffffffff@i18:1,Average Voltage,V,voltage_avg,2\n1,010404ffffffff@i19:1,Average Current,A,current_avg,2\n1,010404ffffffff@i20:1,Current Total,A,current_total,2\n1,010404ffffffff@i21:1,Power Total,W,power_total,2\n1,010404ffffffff@i22:1,Power Apparent Total,VA,power_apparent_total,2\n1,010404ffffffff@i23:1,Power Reactive Total,VAr,power_reactive_total,2\n1,010404ffffffff@i24:1,Power Factor Total,,power_factor_total,2\n1,010404ffffffff@i25:1,Frequency,Hz,frequency,2\n1,010404ffffffff@i26:1,Energy Imported,kWh,energy_imported,3\n1,010404ffffffff@i27:1,Energy Exported,kWh,energy_exported,3\n1,010404ffffffff@i28:1,Energy Total,kWh,energy_total,3\n1,010404ffffffff@i29:1,Energy Reactive Total,kVArh,energy_reactive_total,3\n1,010404ffffffff@i30:1,Net Energy,kWh,energy_net,3\n1,010404ffffffff@i31:1,Import Power,W,power_import,2\n1,010404ffffffff@i32:1,Export Power,W,power_export,2\n#\n
"},{"location":"Smart-Meter-Interface/#siemens-td-3511","title":"Siemens TD-3511","text":"This device is used in the grid of EGTF - Elektrizit\u00e4ts-Genossenschaft Tacherting-Feichten eG. Read uses IEC 62056-21 data mode \"C\" without acknowledgement by the reading device.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,o,0,300,STROM,1,600,2F3F210D0A\n1,1.8.1(@1,Total Consumed,KWh,Total_in,3\n1,2.8.1(@1,Total Delivered,KWh,Total_out,3\n1,0.0.0(@#),Meter Number,,Meter_number,0\n#\n
"},{"location":"Smart-Meter-Interface/#trovis-557x-modbus","title":"Trovis 557x (MODBus)","text":"These heating regulators have a lot of registers. If your station number is different from standard (247 ==> 0xF7) you have got to change every first byte accordingly.
View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,m,0,19200,Trovis,1,2,rF7030009000E,rF703001C0004,F703006A\n1,F7031CSSss@i0:10,Au\u00dfentemp.,\u00b0C,Temp_Outside,1\n1,F7031CxxxxxxxxxxxxSSss@i0:10,Vorlauftemp.,\u00b0C,Temp_Flow,1\n1,F7031CxxxxxxxxxxxxxxxxxxxxxxxxxxxxSSss@i0:10,R\u00fccklauftemp.,\u00b0C,Temp_Return,1\n1,F7031CxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSSss@i0:10,Speichertemp.,\u00b0C,Temp_Vessel,1\n1,F70308UUuu@i1:1,MesswertImp-h,imp/h,Metric_ImpH,0\n1,F70308xxxxUUuu@i1:100,Messwertm3-h,m\u00b3/h,Metric_M3H,2\n1,F70308xxxxxxxxUUuu@i1:10,AA10-10V,V,Metric_AA10,1\n1,F70308xxxxxxxxxxxxUUuu@i1:10,AA20-10V,V,Metric_AA20,1\n1,F70304UUuu@i2:1,StellsignalRk1,%,CtrlSig_RK1,0\n#\n
"},{"location":"Smart-Meter-Interface/#wolf-csz-11300-heater-ebus","title":"WOLF CSZ 11/300 Heater (EBus)","text":"View script >D \n>B \n->sensor53 r\n>M 1 \n+1,3,e,0,2400,EBUS \n1,xxxx0503xxxxxxxxxxxxxxxxss@1,Outside temperature,C,Outsidetemp,0 \n1,xxxx5014xxxxxxxxxxuu@1,Romm temperature,C,Roomtemp,0 \n1,xxxx0503xxxxxxxxxxxxxxuu@1,Warmwater,C,Warmwater,0 \n1,xxxx0503xxxxxxxxxxuu@1,Boiler,C,Boiler,0 \n1,03fe0503xxxxxxxxxxxxuu@1,Returns,C,Returns,0 \n1,03fe0503xxxxuu@1,Status,,Status,0 \n1,03fe0503xxxxxxuu@b3:1,Burner on,,Burner,0 \n1,xxxx5017xxxxxxuuuu@16,Solar collektor,C,Collector,1 \n1,xxxx5017xxxxxxxxxxuuuu@16,Solar storage,C,Solarstorage,1 \n1,xxxx5017xxuu@b0:1,Solar pump on,,Solarpump,0 \n# \n
"},{"location":"Smart-Meter-Interface/#zpa-gh302-sml","title":"ZPA GH302 (SML)","text":"View script >D\n>B\n=>sensor53 r\n>M 1\n+1,3,s,0,9600,Strom\n1,77070100010800ff@1000,Bezug,kWh,Total_in,0\n1,77070100020800ff@1000,Einspeisung,kWh,Total_out,0\n#\n
"},{"location":"Smart-Meter-Interface/#zpa-gh305-sml","title":"ZPA GH305 (SML)","text":"View script >D\n>B\n->sensor53 r\n>M 1\n+1,3,s,0,9600,SML\n1,77070100010800ff@1000,Total Verbrauch,KWh,Total_in,3\n1,77070100020800ff@1000,Total Einspeisung,kWh,Total_in,3\n1,=h==================\n1,77070100100700ff@1,Actual load,W,Power_curr,0\n1,=h==================\n1,=m 9+10+11 @1,Currents L1+L2+L3,A,Curr_summ,3\n;1,=m 12+13+14/#3 @1,Voltage L1+L2+L3/3,V,Volt_avg,3\n1,=h==================\n1,77070100240700ff@1,Consumption P1,W,Power_p1,2\n1,77070100380700ff@1,Consumption P2,W,Power_p2,2\n1,770701004c0700ff@1,Consumption P3,W,Power_p3,2\n1,=h ----\n1,770701001f0700ff@1,Current L1,A,Curr_p1,3\n1,77070100330700ff@1,Current L2,A,Curr_p2,3\n1,77070100470700ff@1,Current L3,A,Curr_p3,3\n1,=h ----\n1,77070100200700ff@1,Voltage L1,V,Volt_p1,3\n1,77070100340700ff@1,Voltage L2,V,Volt_p2,3\n1,77070100480700ff@1,Voltage L3,V,Volt_p3,3\n1,=h==================\n1,77070100510701ff@1,Phaseangle L2-L1,deg,phase_angle_L2_L1,0\n1,77070100510702ff@1,Phaseangle L3-L1,deg,phase_angle_L3_L1,0\n1,77070100510704ff@1,Phaseangle I/U L1,deg,phase_angle_L1,1 \n1,7707010051070fff@1,Phaseangle I/U L2,deg,phase_angle_L2,1 \n1,7707010051071aff@1,Phaseangle I/U L3,deg,phase_angle_L3,1 \n1,770701000e0700ff@1,Frequency,Hz,Freq,1\n;1,=h=======UNBEKANNT===========\n;1,77070100000009FF@#,unbekannt1,,Power_Use_Sum,3\n;1,77070100000000FF@#,unbekannt2,,Power_Use_Sum,3\n;1,7707010060320101@#,unbekannt3,,Meter_id,0\n;1,77010b0a01445a47@#,unbekannt4,,Meter_id,0\n;1,77070100600100ff@#,unbekannt5,,Meter_id,0\n1,=h\n#\n
"},{"location":"Smart-Meter-Interface/#inepro-metering-pro380-mb-m-bus","title":"inepro Metering PRO380-MB (M-Bus)","text":"This is a controller for standard solar thermal systems equipped with VBus data interface. Outputs data every second at 9600 baud 8N1. To connect to this and read data from the bus a level shifting is needed as the voltage is around 8V. Although this is a symmetric connection supporting long wires for our purposes it's enough to measure its polarity with a voltmeter and adapt the level appropriately to 3.3V using the below circuit (many others exist but this is simple and works). Do not connect the GND pin of Wemos with the ground of Resol unit as that may damage the output port of it. The Wemos module needs its own power supply (double insulated recommended).
The script (compile firmware with USE_SML_M)
>D\n>B\n->sensor53 r \n; ->sensor53 d1 ; Dump mode for console debug\n>M 1\n+1,16,rE1,0,2400,,17,100,680303685300b40716,105b005b16,680303685300B10416\n1,4BFD47bcd6@100,L1 voltage,V,L1_V,2\n1,8B01FD47bcd6@100,L2 voltage,V,L2_V,2\n1,CB01FD47bcd6@100,L3 voltage,V,L3_V,2\n1,4BFD59bcd6@100,L1 current,A,L1_I,2\n1,8B01FD59bcd6@100,L2 current,A,L2_I,2\n1,CB01FD59bcd6@100,L3 current,A,L3_I,2\n1,4C2Abcd5@1000,L1 active power,kW,L1_P,3\n1,8C012Abcd5@1000,L2 active power,kW,L2_P,3\n1,CC012Abcd5@1000,L3 active power,kW,L3_P,3\n1,0C2Abcd6@1000,Total active power,kW,T_P,3\n1,4C04bcd8@100,L1 total energy,kWh,L1_TE,2\n1,8C0104bcd8@100,L2 total energy,kWh,L2_TE,2\n1,CC0104bcd8@100,L3 total energy,kWh,L3_TE,2\n1,000C04bcd8@100,Total active energy,kWh,TE,2\n1,6C04bcd8@100,L1 reverse energy,kWh,L1_TRE,2\n1,AC0104bcd8@100,L2 reverse energy,kWh,L2_TRE,2\n1,EC0104bcd8@100,L3 reverse energy,kWh,L3_TRE,2\n1,2C04bcd8@100,Total reverse energy,kWh,TRE,2\n#\n
"},{"location":"Smart-Meter-Interface/#aeconversion-solar-inverter-invxxx-raw","title":"AEConversion solar inverter INVXXX (RAW)","text":"Tested on an AEConversion INV500-90 with RS485 interface.
View script >D\n>B\n=>sensor53 r\n; Monitor Sensor at GPIO25\n=>sensor53 l255\n>M 1\n+1,13,r,0,9600,aec,15,50,2101B203FD4D0D\n\n1,212717UUuux7@1,Leistung,W,power,0\n1,212717x4UUuux4@1000,Energie,kWh,energy_sun,3\n#\n
"},{"location":"SolaX-X1/","title":"SolaX X1","text":""},{"location":"SolaX-X1/#solax-power-single-phase-string-inverter-x1","title":"SolaX Power - Single phase string inverter X1","text":"This feature is not included in precompiled binaries
When compiling your build add the following to user_config_override.h:
#ifndef USE_SOLAX_X1\n#define USE_SOLAX_X1\n#endif\n
There are additional #define compiler directive parameters which can be used, if they are necessary for your setup. Set an other serial speed than the default value of 9600:
#undef SOLAXX1_SPEED\n#define SOLAXX1_SPEED 9600\n
If your inverter has two PV-inputs, you can activate the 2nd one: #ifndef SOLAXX1_PV2\n#define SOLAXX1_PV2\n#endif\n
By using the standard firmware variant with Solax-X1 on top, the resulting binary fits into a normal 1M chip. If you need more space, e.g for other modules, you can disable the ReadConfig command to save about 3k1 bytes of code. To do this, simply remove the compiler directive: #define SOLAXX1_READCONFIG\n
This module works as energy sensor. So be sure to define this, if not already done: #ifndef USE_ENERGY_SENSOR\n#define USE_ENERGY_SENSOR\n#endif\n
"},{"location":"SolaX-X1/#general","title":"General","text":"This module reads runtime values from a Solax X1 device via RS485 Modbus interface and publishes them to MQTT. The communication of this module is based on the description of the communication protocol version 1.8.
"},{"location":"SolaX-X1/#wiring","title":"Wiring","text":"To connect the inverter to the Tasmota-device, you have to use a breakout board to adapt the RS485 interface of the inverter to serial interface of the ESP.
"},{"location":"SolaX-X1/#breakout-boards","title":"Breakout boards","text":"There are many RS485-to-TTL modules, aka breakout boards, available. They may work or not. You should have attention on the operation voltage. The ESP-devices work with 3 volts. Because of that be careful experimenting with 5 volts. In the best case nothing works. In the worst case it will destroy your ESP or breakout board. Here are two examples of tested breakout boards. Recommended is a board with a SP3485 chip, because it is designed for operating at 3 volts.
"},{"location":"SolaX-X1/#sp3485","title":"SP3485","text":"The SP3485 breakout board is specially made to work with only 3 volts. It has a separate RTS-pin and works with a voltage from 3 to 5 volts.
"},{"location":"SolaX-X1/#hw-0519","title":"HW-0519","text":"The HW-0519 breakout board does not need a separate RTS-pin, because it automatically switches between sending and receiving. The recommended voltage is 5 volts, but it should also work with 3 volts.
"},{"location":"SolaX-X1/#esp-breakout-board","title":"ESP \u2b0c breakout board","text":"The RX-, TX- and RTS- (if needed) lines have to be connected to the ESP matching the module configuration.
ESP SP3485 HW-0519 3.3V 3-5V VCC GND GND GND RX TX-O RXD TX RX-I TXD RTS RTS -"},{"location":"SolaX-X1/#breakout-board-inverter","title":"Breakout board \u2b0c inverter","text":"The RS485 interface is a 2-wire-connection. The wires are called A+ and B-. The big advantage of the interface is, beside of needing only two wires, that it can reach a length up to 1200 meters. The inverter has a RJ45-jack, where the interface is accessible. Please consult the manual of your inverter where it is located.
Tip: You can use an ethernet cable and cut off one connector. The RS485 interface uses the blue wire pair.
Breakout board RJ45 inverter Wire color (T568B) A (+) Pin 4 blue B (-) Pin 5 blue-white G / Ground Pin 7 brown-white Info
In many cases two wires are enough to keep it working without errors. When your environment has electrical interferences or your cable is quiet long, you should use a third wire to establish a common signal reference. This wire has to be connected to the Ground pins.
"},{"location":"SolaX-X1/#configuration","title":"Configuration","text":"You have to configure the module or the template. Select SolaxX1 Tx and SolaxX1 Rx for the RS485 communication. If you have a breakout board which needs the RTS line, you must also select SolaxX1 RTS.
"},{"location":"SolaX-X1/#operation","title":"Operation","text":""},{"location":"SolaX-X1/#result","title":"Result","text":"When every thing works you will see the current data on the main page. They are also provided via MQTT.
Tips
- To send a MQTT telemetry message immediately on every change of power, you can set a
PowerDelta value. E.g. PowerDelta 101 for every change of at least 1 W. - Set
SetOption72 to 1 for displaying the value of total energy reported from the inverter.
"},{"location":"SolaX-X1/#console-commands","title":"Console commands","text":"There are two special console commands for the X1 converter: EnergyConfig ReadIDinfo reads and displays ID-data from the inverter EnergyConfig ReadConfig reads and displays the configuration from the inverter
"},{"location":"SolaX-X1/#inverter-status","title":"Inverter status","text":"The inverter status field represents the value reported by the inverter, when the inverter is sending data. In the case when no data is received, it will be display off. As the converter is only working, when the sun is shining, you will see off normally at night or too low light.
Tip
When the inverter is working and off is displayed, so you have to check your hard- and software setup.
"},{"location":"Sonoff-DIY/","title":"Sonoff DIY","text":"Some new Sonoff devices support the new Itead DIY architecture which allows OTA firmware upload. With Sonoff DIY, a user has more control over the hardware features of the device and also allows for upgrading the firmware without additional hardware. The following procedure upgrades Sonoff eWelink firmware to Tasmota.
There are many reports this procedure has changed with newer versions of Sonoff DIY
Tasmota does not provide any kind of support for flashing using this method. Please contact Sonoff Support for help.
IMPORTANT: There are some reports suggesting that the Windows version of Sonoff DIY Tool contains a trojan. It is not clear if it actually contains the malicious code or these are just false positives due to the way Python code was converted to native executables. Nevertheless, proceed with care.
"},{"location":"Sonoff-DIY/#compatible-devices","title":"Compatible devices","text":"Currently the following devices officially support Sonoff DIY: - Sonoff Basic R3 - Sonoff RF R3 - Sonoff Mini
As Sonoff DIY is enabled by connecting GPIO16 to GND it may well be possible that other Sonoff devices running eWelink will support it.
Note
The OTA process Sonoff provides through the Sonoff DIY procedure does not create a backup of the Itead firmware on the device. If you use this OTA method to flash Tasmota on the Sonoff device, you will not be able to revert to the original factory firmware.
"},{"location":"Sonoff-DIY/#flash-procedure","title":"Flash procedure","text":"Guide originally from @Brunas
- Pair the device with the eWeLink app and update firmware. The wifi network you connect to during this step will need to be reachable in order to enter DIY mode.
-
Follow instructions how to enter DIY mode from Sonoff. This is the excerpt from it:
- Long press the button for 5 seconds to enter pairing mode, then press another 5 seconds to ender Compatible Pairing Mode (AP). The LED indicator should blink continuously.
- From mobile phone or PC WiFi setting, an Access Point of the device named ITEAD-XXXXXXXX will be found, connect it with default password 12345678
- Open the browser and access http://10.10.7.1/
- Next, Fill in WiFi SSID and password. Once successfully connected, the device is in DIY mode.
Note: I needed to manually change IP address to 10.10.7.2, 255.0.0.0 with gateway 10.10.7.1 in adapter TCP/IPv4 settings to access that IP address.
- Use Fing or any similar local network scanning app on your smartphone or PC to find IP address of your Sonoff Mini device. MAC Vendor most likely is Espressif and the device has 8081 port open.
- Check that diy mode is working properly.
$SONOFF_IP must be defined with the IP or FQDN of the intended Sonoff device before running the curl command. With curl:
SONOFF_IP=\"10.0.0.2\"\ncurl -XPOST --header \"Content-Type: application/json\" --data-raw '{\"deviceid\": \"\", \"data\": {}}' http://$SONOFF_IP:8081/zeroconf/info\n
Or with the Rester browser extension: Install **Rester** extension in Chrome or Firefox or any other preferred tool to perform REST API operations. To test your device DIY mode create new request in **Rester**: 1. Method: **POST** 2. URL: http://<*IP of your device*>:8081/zeroconf/info 3. Body: `{\"data\": {}}` 4. You might need to add Header **Content-Type** with value **application/json** 5. Press **SEND** If all is OK, status code 200 should be returned with bunch of data:
{\n\"seq\": 1,\n\"error\": 0,\n\"data\": {\n\"switch\": \"off\",\n\"startup\": \"off\",\n\"pulse\": \"off\",\n\"pulseWidth\": 2000,\n\"ssid\": \"YourWiFi\",\n\"otaUnlock\": false,\n\"fwVersion\": \"3.6.0\",\n\"deviceid\": \"YourDeviceId\",\n\"bssid\": \"YourBSSId\",\n\"signalStrength\": -52\n}\n}\n
If that doesn't return 200, try going back to 5s+5s reset above. 4. If all above works, let's unlock OTA: With curl:
curl -XPOST --header \"Content-Type: application/json\" --data-raw '{\"deviceid\": \"\", \"data\": {}}' http://$SONOFF_IP:8081/zeroconf/ota_unlock\n
Or with the Rester browser extension: 1. Method: **POST** 2. URL: http://<*IP of your device*>:8081/zeroconf/ota_unlock 3. Body: `{\"data\": {}}` 4. You might need to add Header **Content-Type** with value **application/json** 5. Press **SEND** 6. You should get status code *200* Optionally for curiosity you could retry info query to check if otaUnlock value now is true 5. Download the appropriate binary from http://ota.tasmota.com/tasmota/release and flash it. NOTE: The maximum firmware size is 508kb, which precludes the standard release binary. Absolutely do not use tasmota-minimal at this stage, this would brick your device.
There are a number of reported issues with the stock firmware's OTA behavior, so it may be easier to use an existing server that works around these issues. $HASH must be defined with the sha256sum of the intended firmware file (the .bin file) before running the curl command. For example:
HASH=\"f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2\"\ncurl -XPOST --data \"{\\\"deviceid\\\":\\\"\\\",\\\"data\\\":{\\\"downloadUrl\\\": \\\"http://sonoff-ota.aelius.com/tasmota-latest-lite.bin\\\", \\\"sha256sum\\\": \\\"$HASH\\\"} }\" http://$SONOFF_IP:8081/zeroconf/ota_flash\n
You're now ready to configure tasmota.
"},{"location":"Sonoff-DIY/#video-tutorials","title":"Video tutorials","text":" - Andreas Spiess
- DrZzs
- Paul Hibbert
"},{"location":"Sonoff-DIY/#more-info","title":"More info:","text":""},{"location":"Sonoff-SPM/","title":"Sonoff SPM","text":"This feature is included only in tasmota32 binaries Do not use this device as safety fuse!
Info
For ARM firmware upgrades it's advised to make a full backup of the SPM-Main ESP 4M flash firmware before flashing Tasmota.
The Sonoff Smart Stackable Power Meter uses a SPM-Main unit with ESP32 providing Wi-Fi and ethernet connections. A serial interface and a SPI interface connects to an ARM MCU which in turn provides a RS-485 bus to up to 32 SPM-4Relay modules. The SPM-4Relay module contains an ARM MCU too providing independent power management for four bi-stable relays rated for 20A at 240V for a total of 4400W.
Note
As of this writing Tasmota v11.1.0.3 supports ARM firmware versions 1.0.0 and 1.2.0.
The firmware monitors the attached SPM-4Relay modules and stores energy usage history for up to 180 days on an optional SD-Card accessible by the ARM MCU only. The ARM firmware provides numerous un-documented functions allowing the ESP32 to send and receive information.
"},{"location":"Sonoff-SPM/#background-information","title":"Background information","text":"More information about the SPM can be obtained here:
- Sonoff tech product documentation
- SPM HTTP API
- Sonoff DIY mode API
"},{"location":"Sonoff-SPM/#tasmota","title":"Tasmota","text":"Tasmota, installed on the ESP32, can connect to the SPM-Main ARM MCU using the serial interface and provides the following functionality:
- Support for up to 8 SPM-4Relays limited by current register usage
- Power control of all 32 relays using standard features
- Energy usage using standard features
- Overload detection using ARM firmware
- GUI display of rotating relays or a user selected 4Relay module
- Fix firmware max 180 days energy usage by storing daily Energy Total in Tasmota's filesystem
- Mapping physical relays to scanned relays
"},{"location":"Sonoff-SPM/#limitations","title":"Limitations","text":"The following notes currently apply:
- Tasmota is unable to upgrade the ARM firmware. In case an upgrade is wanted install the backed-up sonoff firmware and perform the upgrade using the eWeLink app. Once upgraded make another backup before restoring Tasmota for future ARM firmware upgrades.
"},{"location":"Sonoff-SPM/#configuration","title":"Configuration","text":"In addition to installing the tasmota32.bin image some configuration might be needed.
"},{"location":"Sonoff-SPM/#relay-mapping","title":"Relay mapping","text":"After a restart the ARM firmware starts to scan for available 4Relay modules. Every module has a unique id which is send to Tasmota in random order. For a user to pinpoint a physical set of four relays it is therefor needed to \"map\" the scanned modules once. Tasmota stores the id's in a mapping table build using the command SSPMMap <scanned module number>,<scanned module number>,.. where the first entry will map to physical relays 1 to 4, the second entry will map to physical relays 5 to 8 etc. The scanned module information needed is displayed on the console during restart or on request by executing command SSPMScan with a weblog 2 setting.
Note
Scanning takes over 20 seconds so be patient
Look for the below information during a restart for a two 4Relay module system:
00:00:00.123 Project tasmota - Sspm2 Version 11.0.0.1(tasmota)-2_0_2_2(2022-02-18T12:09:05)\n00:00:05.191 CFG: SPM loaded from file\n00:00:08.305 SPM: Main version 1.0.0 found\n13:54:05.392 SPM: 4Relay 1 (mapped to 2) type 130 version 1.0.0 found with id 8B343237393734134B353637\n13:54:05.401 SPM: 4Relay 2 (mapped to 1) type 130 version 1.0.0 found with id 6B7E3237393734134B353637\n
In this case the two modules are mapped using command SSPMMap 2,1. As Tasmota does store the ids of the 4Relay modules a future hussle of the received modules will keep the physical mapping correct.
"},{"location":"Sonoff-SPM/#commands-list","title":"Commands List","text":"The following SPM specific commands are supported.
Command Parameters SspmDisplay Change GUI display between rotating display of all scanned relays, of all scanned relays that are powered on or select a group of four relays using a tab0 = Display all relays1 = Display powered on relays2 = Provide user selectable tabs to display four relays within a 4Relay module SspmEnergyTotal<x> (P)reset total energy in kWh without today's energy for relay <x>0 = preset with total of history0.01..262143.99 = set value in kWh SspmEnergyYesterday<x> (P)reset energy yesterday in kWh for relay <x>0.01..262143.99 = set value in kWh SspmHistory<x> Show daily energy for relay <x> of up to 180 days SspmIAmHere<x> Blink SPM-4Relay module error light containing relay <x> SspmLog<x> Show relay <x> power state change and cause SspmMap Map scanned SPM-4Relay modules to physical location. Use unique numbers for all fields0 = rescan modbus for SPM-4Relay modules and reset mapping to default. This takes at least 20 seconds3,4,1,2 = map scanned module 1 to physical module 3 containing relays 9 to 12, module 2 to 4 with relays 13 to 16, module 3 to 1 with relays 1 to 4 and module 4 to 2 with relays 5 to 8 SspmOverload<x> Set overload detection criteria for relay <x> 0 = reset and disable overload detection to scanned module criteria<delay>,<min_power>,<max_power>,<min_voltage>,<max_voltage>,<max_current> = set any or all overload detection criteria0,0.10,4400.00,0.10,240.00,20.00 = enable overload detection with default values9,0,22.1 = enable max_power over 22.1W detection after 9 seconds0,0,0,0,235.2 = enable immediate max_voltage over 235.2V detection SspmPowerOnState<x> Set v1.2.0 relay <x> power on state overruling Tasmota global power on state0 = off, 1 = on, 2 = saved state SspmScan Rescan modbus for SPM-4Relay modules. This takes at least 20 seconds"},{"location":"Supported-Modules/","title":"Supported Modules","text":" - Sonoff 4CH
- Sonoff 4CH Pro
- Sonoff 4CH DIY
- Sonoff B1 / B1 R2
- Sonoff Basic R1/R2/R3
- Sonoff Dual
- Sonoff Dual R2
- Sonoff iFan02
- Sonoff iFan03
- Sonoff Mini
- Sonoff Pow
- Sonoff Pow R2
- Sonoff PSA
- Sonoff RF
- Sonoff RF R3
- Sonoff RF Bridge 433
- Sonoff S20 Smart Socket
- Sonoff S26 Smart Socket
- Sonoff S31
- Sonoff SC
- Sonoff Slampher
- Sonoff SV
- Sonoff T1
- Sonoff Touch
- Sonoff TH
- Arilux LC02
- Armtronix Dimmers
- Blitzwolf BW-SHP2
- Blitzwolf BW-SHP4
- Blitzwolf BW-SHP6
- Digoo DG-SP202
- Geekcreit 2CH
- Gosund SP1
- H801 LED Controller
- HuaFan Smart Socket
- Luminea LED Controller
- MagicHome LED Controller (ESP-12S/ESP-2M.md)
- MagicHome LED Controller (ESP8285.md)
- Mi Desk Lamp
- PS-16-DZ Dimmer
- OBI Socket
- OBI Socket 2
- OBI Socket IP44 (Black.md)
- Shelly 1
- Shelly 1PM
- Shelly 2
- Shelly 2.5
- SK03 Outdoor Smart Plug
- Teckin SP10 Smart Socket
- Teckin SP22
- YTF IR Bridge
- WT003-EU 4 AC + 4 USB Outlet Tuya Power Strip EU
- Wemos D1 R1 & R2
- Wemos D1 Mini
- Other Devices
"},{"location":"Supported-Peripherals/","title":"Supported Peripherals","text":"Name Description Connection 74x595 74x595 Shift Registers gpio A4988 Stepper Motor Controller ADC Analog input over A0 pin analog ADS111x A/D Converter I2C AHT1x Asair AHT10/AHT15 Temperature and Humidity Sensor I2C AHT2x Asair AHT20/AHT21/AHT25/AM2301B Temperature and Humidity Sensor I2C AM2301 / DHT21 AM2302 / DHT22AM2321 Temperature and Humidity Sensor gpio AM2301B Temperature and Humidity SensorUse same driver as AHT2X I2C AM2320 Temperature and Humidity Sensor gpio AS608 AS608 Optical and R503 Capacitive Fingerprint Sensor serial AS3935 Franklin Lightning Sensor serial APDS-9960 Ambient Light, RGB Color and Proximity Sensor with Gesture Detection I2C AZ 7798 CO2 Meter Datalogger BH1750 Luminosity Sensor BMP280BMP085BMP180) Pressure Sensor BME280 Temperature, Humidity and Pressure Sensor I2C BME680BME688 Temperature, Humidity, Pressure and Gas Sensor I2C Buzzer Audio Signalling Device gpio CC2530 TI CC2530 Zigbee Adapter serial CCS811 Gas and Air Quality Sensor I2C Chirp! Soil Moisture Sensor Moisture Sensor I2C DFR0299 DFRobot DFPlayer Mini MP3 Player serial DHT11 Temperature and Humidity Sensor gpio DHT12 Temperature and Humidity Sensor gpio DY-SV17F DY-SV17F MP3 Player serial DYP-ME007 Ultrasonic distance Sensor serial DS18x20 Temperature Sensor 1-Wire DS1624DS1621 Temperature Sensor 1-Wire DS3231 Real-Time-Clock I2C DS3502 Digital potentiometer I2C EZO EZO series of chemical Sensors I2C F&F LE-01MR F&F LE-01MR Single Phase Modbus Energy meter GPS-NTP-server GPS-NTP-server serial GGreg20_V3 Ionizing Radiation Detector gpio (ESP32 only) HDC1080 Texas Instruments HDC1080 Humidity and Temperature Sensor I2C HDC2010 Texas Instruments HDC2010 Humidity and Temperature Sensor I2C HM-10 BLE Bluetooth gateway serial HM-17HM-16 Bluetooth iBeacon reader serial HMC5883L 3-channels Magnetic Field Sensor I2C HP303B Barometric Pressure Shield I2C HYTxx Temperature and Humidity Sensor I2C HR-E Water Meter Encoder interface serial HRG-15 Hydreon RG-15 Rain Gauge Sensor serial HRXL MaxBotix HRXL line of Sonar Ranging Sensors gpio HC-SR04HC-SR04PJSN-SR04T) Ultrasonic Sensor gpio HM330x SeedStudio Grove HM3301 Particulate Matter Sensor I2C HLK-LD2410 24GHz mmWave Presence Sensor serial Honeywell HIH Temperature and Humidity Sensor I2C Honeywell HPMA115xx Particulate Matter Sensor serial HTU21 Temperature and Humidity Sensor I2C HX711 Load Cell Sensor gpio HRG15 Solid State Rain Sensor serial I2S Audio I2S Audio DAC and microphone I2s iAQ-Core Indoor Air Quality Sensor I2C iEM3000 Schenider Electric modbus energy meter serial INA219ISL28022 High-Side DC Current and Voltage Sensor I2C INA226 High-Side or Low-side DC Current and Voltage Sensor I2C IR Remote IR transmitter and receiver K30, K70, S8 SenseAir CO2 Sensors serial LM75AD Temperature Sensor I2C LMT01 Temperature Sensor gpio MAX31855MAX6675 Thermocouple Sensor SPI MAX31865 RTD Temperature Sensor Amplifier SPI MAX44009 Ambient Light Sensor I2C MCP23008MCP23017 I/O Expander I2C MCP2515 CAN bus controller SPI MCP9808 Temperature Sensor I2C ME007 Ultrasonic Distance Sensor gpio MFRC522 NFC Tag Reader SPI MGC3130 3D Tracking and Gesture Controller MH-Z19B CO2 Sensor MLX90614 MLX9061X Infrared Thermometer I2C MLX90640 MLX90640 Far Infrared Thermal Sensor Array I2C MPR121 Proximity Capacitive Touch Sensor Controller (I2C) MPU6050 3-Axis Gyroscope and 3-Axis Accelerometer Sensor (I2C) MQ MQ Sensors (MQ-02, MQ-03, MQ-04, MQ-05, MQ-06, MQ-07, MQ-08, MQ-09, MQ-131, MQ-135) analog MS01 Moisture sensor from Sonoff 1wire NeoPool Sugar Valley NeoPool Controller serial NRF24L01 NRF24L01 as BLE-bridge for Mijia BT Sensors SPI OpenTherm OpenTherm adapter serial P1 Smart Meter Energy Meter serial PAJ7620 Gesture & Proximity Detection Sensor PIR Passive Infrared Sensor gpio PCA9557 I/O Expander I2C PCA9685 16-channel, 12-bit PWM LED controller I2C PCF8574(A) 8-port I/O Expander I2C PMS3003PMS5003PMS7003 Particle Concentration Sensor serial PMSx003T Particle Concentration, Temperature and Humidity Sensor serial PN532 NFC/RFID controller PZEM-004PZEM-016 Energy Monitor serial QMC5883L Magnetic Field sensor I2C RCWL-0516 Microwave Radar Presence detection RDM6300 125Khz RFID Module RF Transceiver IR receiver and/or transmitter RX-4M50RR30SFRX-AM8SF RF Sensor receiver gpio SCD30 CO2 Sensor I2C SCD40SCD41 CO2 Sensor I2C Eastron SDM72 Modbus Energy Meter serial Eastron SDM120 Modbus Energy Meter serial Eastron SDM220 Modbus Energy Meter serial Eastron SDM230 Modbus Energy Meter serial Eastron SDM630 Modbus Energy Meter serial YF-DN50 Flow rate meter gpio SDS011SDS021 Laser Dust Sensor SEN0390 Ambient Light Sensor I2C SGP30 Gas and Air Quality Sensor I2C SGP40 Gas and Air Quality Sensor I2C SHT1x Temperature and Humidity Sensor I2C SHT30 Humidity & Temperature Sensor I2C SHT4x Temperature and Humidity Sensor I2C SI114x UV Index, IR and Visible Light Sensor I2C Si7021 Humidity and Temperature Sensor I2C SK6812 Addressable LEDs Smart Meter Interface Smart Meter Interface serial, gpio SolaX X1 SolaX Power X1 inverter serial SPS30 Particulate Matter PM) T6703T6713 Telaire T6700 Series CO2 sensor I2C T\u00e9l\u00e9info French energy measuring system serial TFMini TFmini, TFmini Plus, TFmini Plus (Indoor Version), TFmini-S LiDAR module serial TM1638 8 Switch, LED and 7 Segment Unit Sensor gpio TSL2561 Luminosity Sensor I2C TSL2591 Luminosity Sensor I2C TX20TX23WS2300 La Crosse TX2x / Technoline WS2300-15 Anemometer gpio VEML6070 UV Sensor I2C VEML6075 UVA/UVB/UVINDEX Sensor I2C VEML7700 Ambient light intensity Sensor I2C VL53L0x Time of flight Sensor I2C VL53L1x Time of flight Sensor I2C **VINDRIKTNING IKEA VINDRIKTNING Particle Concentration Sensor serial WindMeter Analog cup anemometer WS2812B Wemos Shield with Addressable LED WS2812BWS2813B Addressable LEDs **Xadow Grove) Mutichannel Gas Sensor** gas Sensor (I2C Google Sheet list of supported peripherals
Sensor API Documentation
"},{"location":"Supported-Peripherals/#expanding-specific-devices","title":"Expanding Specific Devices","text":" - LEGO nightstand switch using Sonoff SV
- Add a physical button to Sonoff Basic
- Remote button for Sonoff
- Expand Sonoff S20 with a jack plug
- Expand Sonoff 4CH with a jack plug
- Modify KaKu to WKaKu Power Socket
- GPIO Locations for some devices
"},{"location":"TFL/","title":"TensorFlow Lite","text":"This feature is not included in precompiled binaries add as a build flag to your build environment in platformio_tasmota_cenv.ini:
build_flags = ${env:tasmota32_base.build_flags}\n -DUSE_BERRY_TF_LITE\n -DESP_NN ; use optimized kernels for ESP32\n -DUSE_I2S ; add only for speech/microphone use\nlib_extra_dirs = lib/libesp32, lib/libesp32_div, lib/lib_basic, lib/lib_i2c, lib/lib_div, lib/lib_ssl, lib/libesp32_ml\n; lib/libesp32_ml is important to include \n
"},{"location":"TFL/#different-levels-of-tensorflow","title":"Different Levels of TensorFlow","text":"TensorFlow is an open-source machine-learning platform that is widely adopted and thus is a whole ecosystem with tools, libraries and a huge community. It is not application specific and can be used for all kind of tasks. Initially it was only usable on fully fledged computers but over time technical advances in software and hardware made it possible to step down the stairs and make it usable on weaker devices. So the next smaller thing is called TensorFlow Lite that was targeted for smaller devices like the famous ARM-based 'RaspberryPi'.
But - you guessed it - this was not the end of the line and the whole armada of microcontrollers reached out to be part of the machine learning world. The name of this stripped down platform is TensorFlow Lite for Microcontrollers. Tasmota uses a fork from Espressif with optimized functions for maximal performance.
"},{"location":"TFL/#machine-learning-is-what-exactly-again","title":"Machine Learning ... is what exactly again?","text":"Machine learning, deep learning, KI, AI, ... - these are very blurry defined words, that mean more or less the same and scale from pretty complex up to extremely complex software constructs. Let's try to have a very simplified look at it.
In ancient times (like 20 years ago) problems where solved on computers by finding an algorithm to compute input data and thus getting output data. With machine learning the process is still to have input data, but to use known good output data to let a piece of software find the algorithm to get from the known input data to the known output data - and hope that this still works with unknown input data. The mixture of algorithms and found parameters will be put into a structure which is called a model and the process of building it is usually named training. The model is created programmatically, although this process can be hidden behind a GUI and at this stage the number of inputs and outputs will be defined. Although it would be technically possible to feed raw sensor data into the model, this is not how it is done in most cases. The very common step in between is called feature extraction, which reduces the amount of data and often the dimensionality to make the whole process more efficient and thus even possible for some applications. A good feature extraction will help to later run a successful inference and there are tools to show, how different input entities form clusters of feature data. After feeding the model with sensible data it is time to press a virtual \"go button\" and invoke an inference, that does the magic computations inside the model. After that the outputs will get populated with some values, that have to be interpreted as probabilities. It can be required to add some complex logic in order interpret this data or do some averaging of real-time data.
The processed data is historically typically in the floating point format, but for weak devices like MCU's it is a very common thing to shrink the 4 bytes of a float32 to 1 byte of an int8 by quantization. This happens on various places and will lead to a loss of precision, but is very often nearly on par in the final result.
"},{"location":"TFL/#design-considerations-for-tasmota","title":"Design Considerations for Tasmota","text":"The understandable way to optimize machine learning applications for MCU's is to build and later flash one monolithic firmware, where everything has to be done at/before compile time. This makes sense and is fundamentally the only way to quench out every little bit of performance and memory optimization.
Nonetheless for Tasmota we do not really want to build one-trick-pony firmwares and the idea is to be able to run all kinds of TensorFlow applications with one firmware, that has enough generic capabilities to dynamically load models and extra code at runtime. On the other hand we can optimize the program flow for the ESP chips and Free-RTOS. The API shall be quite slim with as few boilerplate code as possible, but can be extended as needed and use Berry to add additional logic in the first place.
Accelerate your development workflow for machine learning
Usually developing machine learning applications on MCU's means that every small change to the model and/or application code will need a firmware compilation and flashing. With Tasmota this is now independent to each other. You can retrain and reupload the model to the file system as often as needed at runtime. The same is valid for refining the Berry code.
In order to get things done like speech recognition, where especially realtime feature extraction is not possible to achieve with Berry (with the knowledge of today), additional specialized functionality is included. Where it makes sense helper functions for capturing data are added too.
Before you proceed, check you expectations!!
The most important prerequisite for speech recognition on MCU's is to have the right mindset. It is totally impossible to reach the level of recognition of a commercial product (Alexa, Siri, Cortana, ... you name it) on much stronger hardware. The usual cheap I2S MEMS microphone alone is a severe problem and the tuning of the various variables of the model is trial and error in many cases. It will make the final application fail with wrong but similar sounding words or mumbling. Be happy if it works and just don't do it, if you can not handle frustration! You will have to invest some time to fine tune every specific application!
This sums up to these steps:
-
Create a TensorFlow lite model (including collecting data, finding good parameters, final training). Use Edgeimpulse to make this easy or create your own training pipeline.
-
Create a Berry application (loading the model, running inference, interpret the result, acting on the result). Use building blocks from this page to get started.
"},{"location":"TFL/#speech-recognition","title":"Speech Recognition","text":"For the specific task of speech recognition a big hurdle lies in the way in the form of \"How to create a model\"?. Although there are numerous ways published on various places, that sound quite similar to each other, this is a very non-trivial task. While the same principles apply to all examples that you may find, the implementation differences under the hood are quite substantial. The hardest part here is to do the feature extraction of the audio data in a compatible(!!!) way for training and inference on the device. Usually the raw audio data is processed using mel frequency conversion, FFT and some kind of logarithm. You may find words like power spectrum, mel frequency energies and mel frequency cepstral coefficients, which sadly are very implementation specific and not interchangeable. So it is utterly important to use the same (= compatible) implementations for the whole pipeline of Training->Deployment->Usage.
For convenience reasons and after extended testing it was decided to be compatible with Speechpy (with small differences). Thus it is possible to use Edge Impulse as the training platform for model creation, which uses Speechpy too and is a development platform for machine learning on small devices, that shares some similarities to GitHub with regards to costs. Everything that we need for Tasmota is free, the enterprise solution they offer for money is not needed. Technically it is definitely possible to build a complete offline training pipeline as basically everything on Edgeimpulse is open source and can be recreated by a motivated user for local usage.
If you use Edge Impulse for online training, you do not have to create a new firmware image for your Tasmota device. Instead of choosing one of the deployment options from Edge Impulse, you only have to download the binary TensorFlow Lite model (usually the int8 quantized version) from the Dashboard, give it a suitable name and upload it to Tasmotas filesystem in order to use it with Berry afterwards.
Example - speech recognition using MFCC: "},{"location":"TFL/#usage","title":"Usage","text":"Functionality is provided by the module TFL, so always start with import TFL.
TFL Function Parameters and details begin (type:string, descriptor:bytes)First step creates an internal context of type\"BUF\" - generic session with arbitrary byte buffers for input and output\"MIC\" - for voice recognition and capturing training data\"CAM\" - not implemented yet\"\" - stops a running session, can be used to init the internal log buffer`descriptora byte array with specific meaning for every type load (model:bytes, output:bytes, memory:int)Will load and run the modelmodel a bytes buffer that holds the model data for the entire lifecycleoutput a byte buffer that matches the output size of the modelmemory optional (default: 2000), a model specific memory size in bytes that will be allocated, find by trial-end-error input (input:bytes)Feed the input of the model with values, must match the size of the model input. Will invoke an inference. output (output:bytes) -> boolReturns true if function was not called yet on actual output data. rec (filename:string, seconds:int)Records audio to a WAV file (Mono, 16 kHz, 16 Bit). stats () -> stringReturns a JSON string with some metrics of the current session. log () -> stringReturns a log message, typically for debugging. Use Netron to check your model
https://netron.app shows the inner structure of a tensorflow model including format and size of the inputs and outputs. Online and offline versions of the application available for every major platform.
"},{"location":"TFL/#hello-world-sort-of","title":"\"Hello World\" Sort Of...","text":"Perhaps THE starter project is the in itself pretty useless \"sinewave example\", which is nicely explained in these videos.
Of course we can run this model perfectly fine inside Tasmota, with a Berry code snippet:
import TFL\nTFL.begin(\"BUF\") # generic TFL session \nvar i = bytes(-4) # holds one float, size must match the model\nvar o = bytes(-4) # dito\n\nvar model = open(\"sine_model.tflite\").readbytes() # this binary file must have been saved in the FS before\nTFL.load(model,o,3000) # load and run\n\nvar count = 0.0\ndef cb() if TFL.output(o)\n# \"draw\" a bar\nvar v = int((o.getfloat(0) + 1) * 15)\nvar bar_el = \"=\"\nvar bar = \"\"\nfor i:0..v bar+=bar_el end\nprint(bar)\n\n# or print the value\n# print(o.getfloat(0))\n\n# prepare new input in the range of 0..6\ncount+= 0.1 if count>6 count=0 end\ni.setfloat(0,count) TFL.input(i) # and feed it into the model\nend\nvar s = TFL.log() # receive log messages from the TF lite tasks\nif s print(s) end tasmota.set_timer(50, cb) end\ncb()\n\n# initiate loop \nTFL.input(i)\n
This will pollute your Tasmota console with a moving bar resembling a sine wave.
In fact this shows a very generic application, where the format and size as well as the meaning of the in- and outputs must be known, but the model itself can remain a \"black box\". We do not need to know, which kernels or parameters are used.
Use 'TFL.stats()' to find memory size
The metrics will show the used bytes of the model. So start with a large value and tune down, but leave a margin above the number in the output of the command.
"},{"location":"TFL/#speech-recognition-keyword-spotting","title":"Speech Recognition / Keyword Spotting","text":"Training can be done entirely with Edgeimpulse. See their documentation for Responding to your voice.
It is important to have a basic understanding of the process of speech recognition in order to set and tune the configuration: An audio stream is processed in small slices, which have a duration and a stride. They can overlap or run one after the other.
Tasmota will process every audio slice and immediately extract the features with support for the modes: MFE and MFCC. For performance reasons, we do not support every setting Edgeimpulse provides. Do not use Window size for MFCC mode by setting it to 0. More on this later.
We use the following fixed audio settings:
Setting Value Sample length 1 second - means the word to train should be shorter (you might get away with training a shorter part of a longer word) Sample frequency 16kHz - a proven compromise of sound quality, that is just enough for voice recognition, but can be handled by the ESP32 Sample format 16 bit, mono Low frequency 300 Hz - default in Edgeimpulse High frequency 8000 Hz - Sample frequency/2 and default too. Higher values would not make sense because of the NYQUIST theorem."},{"location":"TFL/#create-training-data","title":"Create Training Data","text":"A working microphone setup for recording training data and later audio recognition is needed.
Therefor the -DUSE_I2S must be defined in the build_flags: section of the environment in platformio_tasmota_cenv.ini. This allows to set the GPIO pins for the I2S microphone according to I2S-Audio.
Although you can use the microphone of your computer or smartphone, it is highly recommended to use your ESP32 microphone at least for a large amount of samples in order to train the model with the same pure sound quality, that it later has to run inference on. A working SD card config is the best way to capture training data.
You can use a simple Berry driver to get this done:
# record to 16-bit WAV file at 16 kHz, SD card highly recommended\n# repeat the intended keyword roughly every second in the same technical setup, that will later be used for keyword spotting\n# usage 'rec<seconds> filename', example: rec30 left -> record 30 seconds from I2S microphone to '/left.wav'\nclass WAV_REC : Driver\nvar secs\n\ndef init()\nimport TFL\nTFL.begin(\"\") # init empty for log buffer\nprint(\"TFL: command 'rec' added\")\nself.secs = 0\nend\n\ndef begin()\nimport TFL\nvar descriptor = bytes(-10) # mic descriptor\ndescriptor[0] = 4 # i2s_channel_fmt, 4=left\ndescriptor[1] = 16 # amplification factor\ndescriptor[2] = 32 # slice_dur\ndescriptor[3] = 32 # slice_stride\ndescriptor[4] = 40 # mfe filter (= features if MFE mode)\ndescriptor[5] = 0 # mfcc coefficients, if 0 -> compute MFE only\ndescriptor[6] = 9 # 2^9 = 512 fft_bins\ndescriptor[7] = 10 # max. invocations per second\ndescriptor[8] = 52 # db noisefloor -> negative value\ndescriptor[9] = 0 # preemphasis\nTFL.begin(\"MIC\",descriptor)\nend\n\ndef every_second()\nif self.secs > 0\nprint(self.secs)\nif self.secs == 1 print(\"... done!\") end\nself.secs -= 1\nend\nend\n\ndef every_100ms()\nimport TFL\nvar s = TFL.log()\nif s print(s) end\nend\n\ndef rec(name,secs)\nimport TFL\nself.begin()\nTFL.rec(name,secs) # Edgeimpulse can infer the label from the name, so name it accordingly\nself.secs = secs + 1 # add startup latency\nprint(\"TFL: record\",secs,\"seconds to\",name)\nend\nend\n\nvar wav_rec = WAV_REC()\ntasmota.add_driver(wav_rec)\n\ndef rec(cmd, idx, payload, payload_json)\nvar file = \"/\" + payload + \".wav\"\nwav_rec.rec(file,idx)\ntasmota.resp_cmnd_str(file)\nend\n\ntasmota.add_cmd('rec', rec) # rec30 left -> record 30 seconds from I2S microphone to \"/left.wav\"\n
Most of the descriptor values do not really matter here, but the whole descriptor must have valid values, meaning some values MUST not be 0!
Then you can talk into the microphone with around 1 word per second and later upload this file to your Edge Impulse project via your computer.
"},{"location":"TFL/#general-strategies","title":"General strategies","text":" - Mix input samples from different microphones. Using the computer or phone for audio recording is way more user friendly, so add some samples the easy way. But without enough samples from your ESP32 microphone the final performance will be mediocre at best.
- Input samples from different speakers will very likely lead to a more robust model. So ask family and friends for help.
- More is more. Almost always adding more samples will result in a better performing model. Don't give up, if testing performance degrades in the early stages of audio harvesting. Just make sure to only add valid audio data with correct labels and the final result will improve with more audio data.
"},{"location":"TFL/#edge-impulse","title":"Edge Impulse","text":"For training on Edge Impulse some post processing is usually necessary.
If you have uploaded a sample containing many repetitions of one word, there is a convenient split function, that slices the long mega-sample into one-second samples. For very short words this works automatically pretty well, for longer words close to one second it is recommended to check and fix possible errors immediately. You can check the resulting simple sample including the correct label:
16-bit-sample with label \"computer\": The feature extraction step needs some parameters and will happen in the same way before training and later on-device.
MFCC parameters: This will create a feature array, which will stack the features of every slice on each other. This will be visualized as a heat map, where a slice is a column (oldest left) and the lines represent the frequency banks. Thus this \"picture\" holds the data of one second of audio, that the ML model will later \"see\" to do inference.
MFCC features for 1 second of audio: Configuring the neural network architecture can be done in a GUI. Following the rule to go deep (more layers) and not too wide (less neurons) results in smaller models.
\"Deep\" model for 7 keywords (plus unknown and noise) with size of only 14 kB: After training and configuring the model on Edgeimpulse we can simply download the TensorFlow Lite model from the dashboard (the int8 version) and upload it to the ESP32 filesystem.
"},{"location":"TFL/#tasmota-side","title":"Tasmota Side","text":"On the Tasmota side the feature settings have to be translated in Berry with a descriptor. The descriptor settings may change in the future!
number property value 0 i2s_channel_fmt_t i2s_channel_fmt_t from i2s_types.h, we need mono, so 3 for right or 4 for left 1 amplification factor typical values are 8 - 32, must be >0, too high values will lead to clippingThe audio output of most I2S microphone is very low. Check your setup by recording a WAV file and analyze in Edgeimpulse or use an audio tool like Audacity. 2 slice durationor Frame length A slice of audio data in milliseconds. With the fixed audio settings 32 milliseconds translate to 512 samples, which as a power of 2 is a good fit for FFT. 3 slice strideor Frame stride Time in milliseconds between the starts of 2 adjacent slices. No overlap happens if duration and stride are equal. Lower values create more stress for the system. Values around and below 20 milliseconds may leads to problems. Bad Wifi will worsen things earlier!! 4 Filter number Number of captured mel energies. For MFE mode these are the feature values for one slice. 5 MFCC coefficientsor Number of coefficients If not 0, this means we use MFCC mode and these are the feature values for one slice. 6 FFT sizeor FFT length In powers of 2. For now must be equal or greater than sample size, means slice duration of 32 ms -> sample size 512 -> 2^9 -> 9 7 Inferences per second Typical values 4-10. More values need more averaging in post-processing, but will likely show less missed words. 8 Noisefloor In dB for MFE mode. Sound data with level below that threshold will be discarded. 9 preemphassis Factor will be divided by 100, so 98 -> 0.98. It is recommended to not use this, as Edgeimpulse and Speechpy compute this over the whole sample, while Tasmota does this per slice, which is way more efficient but creates a difference. There is a way to overcome this. More later ... The Berry driver for the speech recognition must be adapted for every model and use case. A plain old ESP32 without extra PS-RAM is enough to \"hear\" with about 10 inferences per per second.
Demo example:
# globals\nvar key_words = [\"down\", \"left\", \"noise\", \"right\", \"up\"] # must match your trained model!! Edgeimpulse sorts them alphabetically\nvar thresholds = [700,710,680,680,720] # same indices as key_words, increase against false positives, decrease against misses, \n# max. theoretical value = 256 * number of averages for int8_t output tensor\n\nclass PREDICTOR\nvar avgs, sz, time_out\nvar out_buf, out_buf_idx\n\ndef init(sz, averages)\nself.out_buf = bytes(-(averages * sz)) # creates circular buffer for averaging\nself.out_buf_idx = 0 self.time_out = 0 # after successful word finding, make a break to avoid \"noise findings\"\nself.sz = sz # size of word list/output tensor\nself.avgs = averages # number of averaging/oversampling steps\nend\n\ndef clear() # clear oversampling buffer after word was found\nfor i:0..size(self.out_buf)-1\nself.out_buf[i] = 0\nend\nend\n\ndef run(data)\nif self.time_out > 0\nself.time_out -= 1\nreturn 255 # return some error code = no result\nend\n\nfor i:0..(self.sz-1)\nself.out_buf[self.out_buf_idx+i] = data[i]\nend\nself.out_buf_idx += self.sz\nif self.out_buf_idx>(self.avgs-1) * self.sz\nself.out_buf_idx = 0 end\n\nvar average\nfor i:0..(self.sz-1)\naverage = 0\nfor j:0..self.avgs-1\naverage += self.out_buf[i+(j*self.sz)]\nend\n# if i == 4\n# print(average) # test the threshold for single words while developing, needed in the next step\n# end\nif average > thresholds[i] # find the threshold stored in the global list by trial and error\nif i != 2 # this is the non-noise/unknown output - you must infer this from your model\nself.clear() # only clear the buffer after finding a keyword, not for noise/unknown\nself.time_out = 10 # find the value by trial and error - good starting point is one second\n# lower number allows faster speech, but might increase false positives\nprint(average)\nend\nreturn i\nend\nend\nreturn 255 # return some error code = no result\nend\nend\n\nclass MICROSPEECH : Driver\nvar o, o_sz # output tensor, size of output tensor\nvar p # predictor instance\nvar model # this var really holds the model data for the entire session\nvar new_out # current output sensor converted to uint8_t\n\ndef init()\nimport TFL\nself.o_sz = size(key_words) # this value must be correctly taken from the model/training pipeline\nself.new_out = []\nself.new_out.resize(self.o_sz)\nself.o = bytes(-self.o_sz) # size must match the model\nself.p = PREDICTOR(self.o_sz,4) # second arg is number of averages for prediction\n\nvar descriptor = bytes(-10)\ndescriptor[0] = 4 # i2s_channel_fmt, 4=left\ndescriptor[1] = 16 # amplification factor\ndescriptor[2] = 32 # slice_dur in ms \ndescriptor[3] = 32 # slice_stride in ms\ndescriptor[4] = 26 # mfe filter (= features if MFE mode)\ndescriptor[5] = 13 # mfcc coefficients, if 0 -> compute MFE only\ndescriptor[6] = 9 # 2^9 = 512 fft_bins\ndescriptor[7] = 10 # max. invocations per second - find best value by testing on device\ndescriptor[8] = 52 # db noisefloor -> negative value\ndescriptor[9] = 0 # preemphasis\nTFL.begin(\"MIC\",descriptor)\nself.model = open(\"mfcc.lite\").readbytes() # file must be present on the ESP\nif self.model\nTFL.load(self.model,self.o,28000)\nend\nend\n\ndef every_50ms()\nimport TFL\nif TFL.output(self.o)\nfor i:0..(self.o_sz-1)\nself.new_out[i] = self.o.geti(i,1) + 128\nend\n#print(self.new_out)\nvar r = self.p.run(self.new_out)\nif r != 2 && r != 255 # in this example not noise/unknown/error code - can be more complex\nprint(key_words[r])\n# do something useful\nend\nend\nvar s = TFL.log()\nif s print(s) end\nend\nend\n\nvar mic = MICROSPEECH()\n\ntasmota.add_driver(mic)\n
"},{"location":"TLS/","title":"TLS Secured MQTT","text":"This feature is included only in tasmota32 and tasmota-zbbridge binaries Starting with version 10.0.0.4, TLS now support dual mode, depending of the value of SetOption132:
SetOption132 0 (default): the server's identity is checked against pre-defined Certificate Authorities. There is no further configuration needed. Tasmota includes the following CAs:- LetsEncrypt R3 certificate, RSA 2048 bits SHA 256, valid until 20250915
- Amazon Root CA, RSA 2048 bits SHA 256, valid until 20380117, used by AWS IoT
SetOption132 1: Fingerprint validation. This method works for any server certificate, including self-signed certificates. The server's public key is hashed into a fingerprint and compared to a pre-recorded value. This method is more universal but requires an additional configuration (see below)
There is no performance difference between both modes.
"},{"location":"TLS/#fingerprint-validation","title":"Fingerprint Validation","text":"The fingerprint is now calculated on the server's Public Key and no longer on its Certificate. The good news is that Public Keys tend to change far less often than certificates, i.e. LetsEncrypt triggers a certificate renewal every 3 months, the Public Key fingerprint will not change after a certificate renewal. The bad news is that there is no openssl command to retrieve the server's Public Key fingerprint.
The original Fingerprint V1 algorithm had a security potential vulnerability, it has been replaced by a new more robust method v2. To avoid breaking compatibility, Tasmota will automatically detect when a fingerprint v1 is present and will convert it automatically to V2.
Important: the following tool to calculate it from your certificate is now deprecated. The fingerprint will work once and will be replaced with the new fingerprint.
So to simplify your task, we have added two more options: 1/ auto-learning of the fingerprint, 2/ disabling of the fingerprint validation altogether.
"},{"location":"TLS/#option-1-fingerprint-auto-learn","title":"Option 1: Fingerprint auto-learn","text":"If set, Tasmota will automatically learn the fingerprint during the first connection and will set the Fingerprint settings to the target fingerprint. To do so, use one of the following commands:
#define MQTT_FINGERPRINT1 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00\n
or #define MQTT_FINGERPRINT2 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00\n
"},{"location":"TLS/#option-2-disable-fingerprint","title":"Option 2: Disable Fingerprint","text":"You can completely disable server fingerprint validation, which means that Tasmota will not check the server's identity. This also means that your traffic can possibly be intercepted and read/changed, so this option should only be used on trusted networks, i.e. with an MQTT on your local network. YOU HAVE BEEN WARNED!
To do so, set one of the Fingerprints to all 0xFF:
#define MQTT_FINGERPRINT1 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF\n
Tasmota also provide an option to authenticate clients using an x509 certificate and a public key for authentication, instead of username/password. For details on how to set up your local instance of Mosquitto, check the article Self-signed-Mosquitto.
"},{"location":"TLS/#compiling-tls-for-esp8266","title":"Compiling TLS for ESP8266","text":"To use it you must compile your build. Add the following to user_config_override.h:
#ifndef USE_MQTT_TLS \n#define USE_MQTT_TLS // Use TLS for MQTT connection (+34.5k code, +7.0k mem and +4.8k additional during connection handshake)\n#define MQTT_TLS_ENABLED true // [SetOption103] Enable TLS mode (requires TLS version)\n// #define USE_MQTT_TLS_CA_CERT // Force full CA validation instead of fingerprints, slower, but simpler to use. (+2.2k code, +1.9k mem during connection handshake)\n// This includes the LetsEncrypt CA in tasmota_ca.ino for verifying server certificates\n// #define USE_MQTT_TLS_FORCE_EC_CIPHER // Force Elliptic Curve cipher (higher security) required by some servers (automatically enabled with USE_MQTT_AWS_IOT) (+11.4k code, +0.4k mem)\n#endif\n
"},{"location":"TLS/#change-port-to-8883","title":"Change port to 8883","text":"#define MQTT_PORT 8883 // [MqttPort] MQTT port (10123 on CloudMQTT)\n
"},{"location":"TLS/#ensure-that-for-the-environment-you-have-selected-liblib_ssl-is-included-on-platformio_tasmota_envini","title":"Ensure that for the environment you have selected, lib/lib_ssl is included on platformio_tasmota_env.ini :","text":"lib_extra_dirs = lib/lib_ssl\n
TLS offers increased security between your connected devices and your MQTT server, providing server authentication and encryption. Please refer to the general discussion in Securing-your-IoT-from-hacking
Starting version 6.5.0.15, there are major changes to TLS to make it lighter in memory and easier to use. It has now reduced flash and memory requirements that makes it compatible with Web and Hue Emulation.
If you are upgrading from a previous TLS activated version, there are breaking changes in the way Fingerprints are calculated
At the Tasmota configuration, you need to enable to use the TLS Version. This is done by enable #define USE_MQTT_TLS in user_config_override.h and
If you are using LetsEncrypt to generate your server certificates, you should activate #define USE_MQTT_TLS_CA_CERT. Tasmota will transparently check the server's certificate with LetsEncrypt CA. If you are generating self-signed certificates or prefer fingerprints, read below.
"},{"location":"TLS/#limitations","title":"Limitations","text":"On ESP8266, starting with 6.5.0.15, AxTLS has been replaced with BearSSL. This uses less memory, typically 6.0k constantly, and an additional 6.8k during TLS connection.
On ESP32, BearSSL provides a much lighter footprint than MbedTLS (~45kB instead of ~150kB) and continues to be used by Tasmota.
Main limitations are:
- Your SSL/TLS server must support TLS 1.2 and the
ECDHE_ cipher - which is the case with the default Mosquitto configuration - The server certificate must have an RSA private key (max 2048 bits) and the certificate must be signed with RSA and SHA256 hash. This is the case with default LetsEncrypt certificates. ESP32 supports by default RSA private keys up to 4096 bits, ESP8266 must be compiled with option
-DUSE_4K_RSA to support 4096 private keys. - Your SSL/TLS should support TLS 1.2 MFLN to limit buffer to 1024 bytes. If MFLN is not supported, it will still work well, as long as the server does not send any message above 1024 bytes. On ESP32 buffers are raised to 2048 bytes.
- If you are using certbot with Letsencrypt: starting with v2.0.0 certbot requests ECDSA certificates by default. Make sure you explicitly add
--key-type rsa and --rsa-key-size 2048 (or --rsa-key-size 4096).
"},{"location":"TLS/#implementation-notes","title":"Implementation Notes","text":"Arduino Core switched from AxTLS to BearSSL in 2.4.2, allowing further optimization of the TLS library footprint. BearSSL is designed for compactness, both in code size and memory requirements. Furthermore it is modular and allows for inclusion of only the code necessary for the subset of crypto-algorithms you want to support.
All numbers below are for ESP8266
Thanks to BearSSL's compactness and aggressive optimization, the minimal TLS configuration requires just 34.5k of Flash and 6.7k of Memory. The full-blown AWS IoT version with full certificate validation requires 48.3k of Flash and 9.4k of Memory.
Here are the tips and tricks used to reduce Flash and Memory:
- MFLN (Maximum Fragment Length Negotiation): TLS normally uses 16k buffers for send and receive. 32k looks very small on a server, but immensely huge for ESP8266. TLS 1.2 introduced MFLN, which allows the TLS Client to reduce both buffers down to 512 bytes. MFLN is not widely supported yet, but it is by recent OpenSSL versions and by AWS IoT. This is a huge improvement in memory footprint. If your server does not support MFLN, it will still work as long as the messages sent by the server do not exceed the buffer length. In Tasmota the buffer length is 1024 bytes for send buffer and 1024 bytes for receive buffer. Going below creates message fragmentation and much longer TLS connection times (above 3s). If your server does not support MFLN, you'll see a message to that effect in the logs.
- Max Certificate size: BearSSL normally supports server certificates of up to RSA 4096 bits and EC 521 bits. These certificates are very uncommon currently. To save extra memory, the included BearSSL library is trimmed down to maximum RSA 2048 bit certificate and EC 256 bit certificate. This should not have any impact for you.
Tasmota will crash if the server serves a 4096 bit RSA certificate. The crash will likely be in br_rsa_i15_pkcs1_vrfy. Enable USE_4K_RSA to avoid this behaviour.
- EC private key: AWS IoT requires the client to authenticate with its own Private Key and Certificate. By default AWS IoT will generate an RSA 2048 bit private key. In Tasmota, we moved to an EC (Elliptic Curve) Private Key of 256 bits. EC keys are much smaller, and handshake is significantly faster. Note: the key being 256 bits does not mean it's less secure than RSA 2048, it's actually the opposite.
- Single Cipher: to reduce code size, we only support a single TLS cipher and embed only the code strictly necessary. When using TLS (e.g. LetsEncrypt on Mosquitto) the supported cipher is
ECDHE_RSA_WITH_AES_128_GCM_SHA256. Additionally, ECDHE offers Perfect Forward Secrecy which means extra security. - Adaptive Thunk Stack: BearSSL does not allocate memory on its own. It's either the caller's responsibility or memory is taken on the Stack. Stack usage can go above 5k, more than the ESP8266 stack. Arduino created a Thunk Stack, a secondary stack of 5.6k, allocated on Heap, and activated when a TLS connection is active. Actually the stack is mostly used during TLS handshake, and much less memory is required during TLS message processing. Tasmota only allocates the Thunk Stack during TLS handshake and switches back to the normal Stack afterwards. See below for details of actual memory usage.
- Keys and CA in PROGMEM: BearSSL was adapted from original source code to push most on the tables and static data into PROGMEM: https://github.com/earlephilhower/bearssl-esp8266. Additional work now allows us to put the Client Private Key, Certificate and CA in PROGMEM too, saving at least 3k of Memory.
"},{"location":"TLS/#memory-usage","title":"Memory Usage","text":"TLS on Tasmota has been aggressively optimized to use as little memory (heap) as possible. It was also optimized to limit code size.
Memory consumption (nominal):
- BearSSL lib: 1424 bytes (or 1024 bytes with LetsEncrypt or regular TLS)
- BearSSL ClientContext: 3440 bytes
- Buffers (1024 bytes in + 1024 bytes out + overhead): 2528 bytes
- Total = 7.4k (or 7.0k with LetsEncrypt or regular TLS)
Note: if you use USE_WEBSERVER, your impact is lowered by 2k since the Web log buffer is reduced from 4k to 2k. Overall, when activating USE_WEBSERVER, you just see a memory impact of 5.4k.
Memory needed during connection (TLS handshake - fingerprint validation):
- ThunkStack = 5308 bytes (or 3608 bytes with LetsEncrypt or regular TLS)
- DecoderContext = 1152 bytes
- Total for connection = 6.5k (or 4.8k with LetsEncrypt or regular TLS)
Memory needed during connection (TLS handshake - full CA validation):
- ThunkStack = 5308 bytes (or 3608 bytes with LetsEncrypt or regular TLS)
- DecoderContext = 3072 bytes
- Total for connection = 8.4k (or 6.7k with LetsEncrypt or regular TLS)
"},{"location":"TLS/#connection-time","title":"Connection Time","text":"ESP8266 is quite slow compared to modern processors when it comes to SSL handshakes. Here are observed performance times when connecting to an SSL/TLS server, depending on CPU frequency (80MHz or 160MHz):
AWS IoT Connection, with EC Private Key, simple fingerprint validation:
- 0.7s at 160MHz
- 1.3s at 80 MHz
AWS IoT Connection, with EC Private Key, full CA validation (easier to configure than fingerprints):
- 1.0s at 160MHz
- 1.8s at 80 MHz
LetsEncrypt based server (Mosquitto for ex), simple fingerprint validation:
- 0.3s at 160MHz
- 0.4s at 80MHz
LetsEncrypt based server (Mosquitto for ex), with full CA validation (easier to configure than fingerprint):
- 0.4s at 160MHz
- 0.7s at 80MHz
"},{"location":"TLS/#tls-troubleshooting","title":"TLS Troubleshooting","text":"Here are most common TLS errors:
Error code Description -1004 Missing CA -1003 Missing EC private key -1002 Cannot connect to TCP port -1001 Cannot resolve IP address -1000 Out of memory error 1 Bad fingerprint 2 \u00a0BR_ERR_BAD_STATE 3 BR_ERR_UNSUPPORTED_VERSION 4 \u00a0BR_ERR_BAD_VERSION 5 \u00a0BR_ERR_BAD_LENGTH 6 \u00a0BR_ERR_TOO_LARGE 7 \u00a0BR_ERR_BAD_MAC 8 BR_ERR_NO_RANDOM 9 BR_ERR_UNKNOWN_TYPE\u00a0 10 BR_ERR_UNEXPECTED 12 BR_ERR_BAD_CCS 13 \u00a0BR_ERR_BAD_ALERT 14 BR_ERR_BAD_HANDSHAKE 15 \u00a0BR_ERR_OVERSIZED_ID 16 \u00a0BR_ERR_BAD_CIPHER_SUITE 17 BR_ERR_BAD_COMPRESSION 18 \u00a0BR_ERR_BAD_FRAGLEN 19 BR_ERR_BAD_SECRENEG 20 \u00a0BR_ERR_EXTRA_EXTENSION 21 BR_ERR_BAD_SNI 22 BR_ERR_BAD_HELLO_DONE\u00a0 23 BR_ERR_LIMIT_EXCEEDED: the server's public key is too large. Tasmota TLS is limited to 2048 RSA keys 24 \u00a0BR_ERR_BAD_FINISHED\u00a0 25 \u00a0BR_ERR_RESUME_MISMATCH 26 \u00a0BR_ERR_INVALID_ALGORITHM 27 \u00a0BR_ERR_BAD_SIGNATURE 28 BR_ERR_WRONG_KEY_USAGE 29 BR_ERR_NO_CLIENT_AUTH 31 BR_ERR_IO 54 BR_ERR_X509_EXPIRED X.509 status: certificate is expired or not yet valid. 56 BR_ERR_X509_BAD_SERVER_NAME X.509 status: expected server name was not found in the chain. 62 X509 not trusted, the server certificate is not signed by the CA (AWS IoT or LetsEncrypt) 266 SSL3_ALERT_UNEXPECTED_MESSAGE 276 TLS1_ALERT_BAD_RECORD_MAC 277 \u00a0TLS1_ALERT_DECRYPTION_FAILED 278 TLS1_ALERT_RECORD_OVERFLOW 286 SSL3_ALERT_DECOMPRESSION_FAIL 296 SSL3_ALERT_HANDSHAKE_FAILURE 298 TLS1_ALERT_BAD_CERTIFICATE: Missing or bad client private key 299 TLS1_ALERT_UNSUPPORTED_CERT 300 \u00a0TLS1_ALERT_CERTIFICATE_REVOKED 301 \u00a0TLS1_ALERT_CERTIFICATE_EXPIRED 302 \u00a0TLS1_ALERT_CERTIFICATE_UNKNOWN 303 \u00a0SSL3_ALERT_ILLEGAL_PARAMETER 304 \u00a0TLS1_ALERT_UNKNOWN_CA\u00a0 305 TLS1_ALERT_ACCESS_DENIED 306 \u00a0TLS1_ALERT_DECODE_ERROR 307 TLS1_ALERT_DECRYPT_ERROR 316 \u00a0TLS1_ALERT_EXPORT_RESTRICTION 326 \u00a0TLS1_ALERT_PROTOCOL_VERSION 327 \u00a0TLS1_ALERT_INSUFFIENT_SECURITY 336 \u00a0TLS1_ALERT_INTERNAL_ERROR 346 \u00a0TLS1_ALERT_USER_CANCELED 356 TLS1_ALERT_NO_RENEGOTIATION 366 TLS1_ALERT_UNSUPPORTED_EXT Additional BR_ERR* error codes
"},{"location":"TM163x/","title":"TM1637, TM1638 and MAX7219 Seven-Segment Display","text":"This feature is included only in tasmota*-display.bin precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_DISPLAY\n#define USE_DISPLAY\n#endif\n\n#ifndef USE_DISPLAY_TM1637\n#define USE_DISPLAY_TM1637\n#endif\n
In case you want MAX7219 also add: #ifndef USE_DISPLAY_MAX7219\n#define USE_DISPLAY_MAX7219\n#endif\n
In order to use TM1368 leds and buttons, see instructions in TM1638 leds and buttons TM1637 TM1638 MAX7219 The TM1637, TM1638 and MAX7219 display modules are small (~ 10mm high digits) 7-segment, LED-based display units with 4/6 digits (TM1637), 8 digits and 8 digits (TM1638 and MAX7219) respectively. They use a two-wire (TM1637) or three-wire (TM1638 and MAX7219) I2C-like (but not exactly) protocol for communication with MCUs like the ESP8266 / ESP32 / Arduino etc.,
These modules are a great way to add a simple numeric display to any MCU project.
"},{"location":"TM163x/#features","title":"Features","text":"The Tasmota support for these modules can --
- display Numbers and Floats with control over position and leading zeros.
- display basic Text, for example, sending the text
22.5^ will display: - display Raw segments.
- display Level, like a bar graph
- display Scrolling text
- display a Clock in 12 hr and 24 hr format
- set Brightness (8 levels) and Clear the display.
"},{"location":"TM163x/#configuration","title":"Configuration","text":""},{"location":"TM163x/#wiring","title":"Wiring","text":"The TM1637 module needs to be connected to two GPIO pins and a 3.3V-5V power supply.
TM1637 ESP based module CLK GPIOx DIO GPIOy VCC 3.3V (e.g., ESP-01) or 5V (e.g., Wemos D1 Mini) GND GND The TM1638 module needs to be connected to three GPIO pins and a 5V power supply.
TM1638 ESP based module CLK GPIOx DIO GPIOy STB GPIOz VCC 5V GND GND The MAX7219 module needs to be connected to three GPIO pins and a 5V power supply.
MAX7219 ESP based module CLK GPIOx DIN GPIOy CS GPIOz VCC 5V GND GND"},{"location":"TM163x/#tasmota-settings","title":"Tasmota Settings","text":"In Tasmota's Configuration -> Configure Module page, assign:
For TM1637
GPIOx to TM1637 CLKGPIOy to TM1637 DIO
For TM1638
GPIOx to TM1638 CLKGPIOy to TM1638 DIOGPIOz to TM1638 STB
For MAX7219
GPIOx to MAX7219 CLKGPIOy to MAX7219 DINGPIOz to MAX7219 CS
For example, if x=0 and y=2, z=4 then the module configuration would look like the following: TM1637 TM1638 MAX7219
"},{"location":"TM163x/#initial-setup","title":"Initial Setup","text":"The power toggle button in webUI turns the display on or off. However, if there are additional relays defined, resulting in multiple power toggle buttons in WebUI, display power will create and map to the last button. Thus, it is necessary to ensure that relays are numbered from 1, otherwise a conflict will occur with the display power.
In the console, turn ON the display with the command Power 1.
"},{"location":"TM163x/#displaymodel","title":"DisplayModel","text":"Once the GPIO configuration is saved and the ESP8266 / ESP32 module restarts, set the Display Model to 15 using the command:
DisplayModel 15
"},{"location":"TM163x/#displaywidth","title":"DisplayWidth","text":"If you have a TM1637 with 6 digits, set the number of digits using the command:
DisplayWidth 6
"},{"location":"TM163x/#displaytype","title":"DisplayType","text":"The 6-digit TM1637 has 2 known variants with different hardware wiring for the digit ordering. You can switch between these two variants with the following commands:
DisplayType 0 - Use this for the Type 0 variant, with wiring similar to the TM1637 4-digit modules DisplayType 1 - Use this for the Type 1 variant, with a different wiring that causes the text 123456 to appear as 321654
After the ESP8266/ESP32 module restarts again, the display module is ready to accept commands.
"},{"location":"TM163x/#displaymodes","title":"DisplayModes","text":"DisplayModes 0..3 are supported. The firmware default is DisplayMode 1.
To use the Seven-Segment specific Display- commands described below, set the DisplayMode to 0 with:
DisplayMode 0
"},{"location":"TM163x/#displaydimmer","title":"DisplayDimmer","text":"The brightness of the display can be set using the DisplayDimmer command.
DisplayDimmer 0..100 maps the brightness value to 8 steps from 0..7
For a minimum brightness, make sure this value is at least about 13
"},{"location":"TM163x/#7-segment-specific-commands","title":"7-Segment specific Commands","text":"The Display- commands listed below can be used from the Tasmota web-console, MQTT, and from Tasmota Rules
"},{"location":"TM163x/#tm1638-leds-and-buttons","title":"TM1638 leds and buttons","text":"In order to use the TM1638 leds and buttons, you must self-compile tasmota with the following in your user_config_override.h:
#define USE_DISPLAY\n#define USE_DISPLAY_TM1637\n\n#define USE_TM1638 // Add support for TM1638 switches copying Switch1 .. Switch8 (+1k code)\n// #define TM1638_USE_AS_BUTTON // Add support for buttons\n#define TM1638_USE_AS_SWITCH // Add support for switches (default)\n#define TM1638_MAX_DISPLAYS 8 // Add support for power control 8 displays\n#define TM1638_MAX_KEYS 8 // Add support for 8 keys\n#define TM1638_MAX_LEDS 8 // Add support for 8 leds \n
This will define the buttons as Switches. If you want to use them as Buttons, invert the comments on the lines:
#define TM1638_USE_AS_BUTTON // Add support for buttons\n//#define TM1638_USE_AS_SWITCH // Add support for switches (default)\n
The 8 leds will be created as Relays. If no other relays are defined, they will start as Relay1 up to Relay8. A 9th relay is assigned to the 7-segment display.
The 8 buttons will be created by default as Switches with all the features of switches including debouncing and all Switchmodes.
Alternatively, using #define TM1638_USE_AS_BUTTON they would be created as Buttons fully equivalent to a native Tasmota Button on a GPIO.
In all cases, leds, switches or buttons index will be assigned after native relays, switches or buttons get assigned. Other drivers providing relays, buttons or switchs initialized before TM1368 will be also get index assigned before TM1638. So actual indexes may depends on what other GPIO/drivers are configured on your system.
See rule sample below.
"},{"location":"TM163x/#commands-and-usage","title":"Commands and Usage","text":"Console/MQTT Commands Description values DisplayClear Clears the display DisplayNumber Clears and then displays number without decimal. command e.g., \"DisplayNumber 1234\". Control position, leading zeros, and length. position can be 0 (left-most) to NUM_DIGITS-1 (right-most), leading zeros can be 1 or 0 (default), length can be 1 to NUM_DIGITS (4 or 6). Command example: DisplayNumber 12, 1, 1, 3 This will display: num [, position[, leading_zeros[, length]]] DisplayNumberNC Display integer number as above, but without clearing first. e.g., \"DisplayNumberNC 1234\". Usage is same as above. same as above DisplayFloat Clears and then displays float (with decimal point) command e.g., \"DisplayFloat 12.34\". Control position, precision, length and alignment. position can be 0 (left-most) to NUM_DIGITS-1 (right-most), precision can be 0 to NUM_DIGITS (default), length can be 1 to NUM_DIGITS (4 or 6). alignment can be 0 for left and 1 for right. Command example: DisplayFloat 2.48, 1, 1, 2 This will display: num[, position[, precision[, length [, alignment]]]] DisplayFloatNC Displays float (with decimal point) as above, but without clearing first. command e.g., \"DisplayFloatNC 12.34\" same as above DisplayRaw Takes up to NUM_DIGITS comma-separated integers (0-255) and displays raw segments. Each number represents a 7-segment digit. Each 8-bit number represents individual segments of a digit. Segment a=1, b=2, c=4, d=8, e=16, f=32, g=64 and h (decimal point)=128. To turn on all segments, the number would be 1+2+4+8+16+32+64+128 = 255 For example, the command DisplayRaw 0, 2, 255, 255 would display: position, length, num1 [, num2[, num3[, num4[, ...up to NUM_DIGITS numbers]]...] DisplayText Clears and then displays basic text. Command e.g., DisplayText a.b12 Control length and position of the displayed text. length can be 1 to NUM_DIGITS , position can be 0 (left-most) to NUM_DIGITS-1 (right-most) A caret(^) symbol in the text input is displayed as the degrees(\u00b0) symbol. This is useful for displaying Temperature (or angle)! For example, the command DisplayText 22.5^ will display: text[, position[, length]] DisplayTextNC Displays text without first clearing the display. Usage is same as above. same as above DisplayScrollText Displays scrolling text, up to 50 characters. If num_iterations is not specified, it scrolls indefinitely, until another Display- command is issued. Optionally, specifying num_iterations causes the scrolling to stop after the specified number of iterations.Command examples: DisplayScrollText tasmota is awesome -- causes indefinite scrollingDisplayScrollText tasmota is awesome, 5 -- causes scrolling to stop after 5 iterations text [, num_iterations] DisplayScrollDelay Sets the speed of text scroll. Smaller delay = faster scrolling. 0 to 15 DisplayLevel Display a horizontal bar graph. Command e.g., DisplayLevel 50 will display: 0 to 100 DisplayClock Displays a clock. DisplayClock 1 displays a clock in 12-hour format. DisplayClock 2 displays a clock in 24-hour format. DisplayClock 0 turns off the clock and clears the display 1 or 2 or 0"},{"location":"TM163x/#usage-in-rules","title":"Usage in Rules","text":"All the above commands can be used in Tasmota Rules, as usual.
For example, a simple digital thermometer can be implemented by connecting a DHT22 Temperature-Humidity Sensor and a TM1637 to a Wemos D1 Mini, and writing a Rule like the following:
Rule1\nON Tele-AM2301#Temperature DO DisplayText %value%^ ENDON\n
Another example, using a MAX7219 and a SHT3X temp/humidity sensor, with value comparison so displaytext only fires when the value changes. The first four digits display the temperature and the second four digits display the humidity. The DisplayTextNC command is used to leave unused digits illuminated, so both numbers can be independently updated. Rule1\non sht3x#Temperature!=%var1% do backlog displaytextnc %value%^;var1 %value% endon on sht3x#Humidity!=%var2% do backlog displaytextnc %value%h,4;var2 %value% endon on system#init do power 1 endon\n
"},{"location":"TM163x/#tm1638-in-rules","title":"TM1638 in rules","text":"As the leds and buttons are fully equivalent to Relays and Buttons/Switches, they can be used in rules in exactly the same way as native Relay/Power, Buttons/Switches.
Here is a little ruleset which implement a 8-digit code entry (using only digit 1 to 8).
At start Time is displayed (DisplayMode 1) but as soon as you type in the 1st key, it starts the entry mode. After each digit entry the user has up to 5 seconds to enter the next digit. It (s)he fails, the state machine is reset and the display reverts showing Time.
Once all 8 digits are entered, the resulting string is stored in var3 as a text message.
This is only a sample which can be adapted for example to send the code through MQTT.
DisplayModel 15\nDisplayWidth 8\n\nrule1 \n on system#init do event reset endon \n on event#reset do backlog ruletimer1 0; displaymode 1; var1 1; var2 \" endon\n on button1#state do event key=1 endon\n on button2#state do event key=2 endon \n on button3#state do event key=3 endon \n on button4#state do event key=4 endon \n on button5#state do event key=5 endon \n on button6#state do event key=6 endon \n on button7#state do event key=7 endon \n on button8#state do event key=8 endon \n on event#key do backlog var2 %var2%%value%; displaymode 0; displaytext %var2%%value%; ruletimer1 5; add1 1 endon \n on rules#timer=1 do event reset endon \n on var1#state==9 do backlog ruletimer1 5; var3 The Code is %var2% endon\n\nrule1 1\n
"},{"location":"TM163x/#tm1637-images","title":"TM1637 Images","text":" The TM1637 4-digit module (front and back) TM1637 4-digit module with Wemos D1 Mini
"},{"location":"TM1650/","title":"TM1650 Seven-Segment Display","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_I2C\n#define USE_I2C\n#endif\n\n#ifndef USE_DISPLAY\n#define USE_DISPLAY\n#endif\n#ifndef USE_DISPLAY_MODES1TO5\n#define USE_DISPLAY_MODES1TO5\n#endif\n#ifndef USE_DISPLAY_TM1650\n#define USE_DISPLAY_TM1650\n#endif\n\n// ONLY XY-Clock\n#ifndef USE_RTC_CHIPS \n#define USE_RTC_CHIPS\n#endif\n#ifndef USE_DS3231\n#define USE_DS3231\n#endif\n
TM1650 - XY-Clock TM1650 - 303WiFiLC01 The TM1650 display modules are usually found in \"cheap\" Wifi LED clock. They manage 7-segment LED displays (~ 27 mm high) with 4 digits. They use two wire I2C protocol to communicate with MCU such as ESP8266/ESP32/Arduino etc.,
"},{"location":"TM1650/#features","title":"Features","text":"The Tasmota support for these modules can --
- display Numbers and Floats with control over position and leading zeros.
- display basic Text, for example, sending the text
22.5^ will display: - display Raw segments.
- display Level, like a bar graph
- display Scrolling text
- display a Clock in 12 hr and 24 hr format
- set Brightness (8 levels) and Clear the display.
"},{"location":"TM1650/#configuration","title":"Configuration","text":""},{"location":"TM1650/#wiring","title":"Wiring","text":"The TM1650 module needs to be connected to I2C GPIO pins and a 3.3V-5V power supply.
TM1650 ESP based module SCL GPIOx SDA GPIOy VCC 3.3V (e.g., ESP-01) or 5V (e.g., Wemos D1 Mini) GND GND"},{"location":"TM1650/#tasmota-settings","title":"Tasmota Settings","text":"In Tasmota's Configuration -> Configure Module page, assign:
For TM1650
GPIOx to I2C SCLGPIOy to I2C SDA
For example, with XY-Clock hardware, the module configuration would look like the following: TM1650 - XY-Clock
"},{"location":"TM1650/#initial-setup","title":"Initial Setup","text":"The power toggle button in webUI turns the display on or off. However, if there are additional relays defined, resulting in multiple power toggle buttons in WebUI, display power will create and map to the last button. Thus, it is necessary to ensure that relays are numbered from 1, otherwise a conflict will occur with the display power.
In the console, turn ON the display with the command Power 1.
"},{"location":"TM1650/#displaymodel","title":"DisplayModel","text":"Once the GPIO configuration is saved and the ESP8266 / ESP32 module restarts, set the Display Model to 20 using the command:
DisplayModel 20
"},{"location":"TM1650/#displaytype","title":"DisplayType","text":"The 6-digit TM1637 has 2 known variants with different hardware wiring for the digit ordering. You can switch between these two variants with the following commands:
DisplayType 0 - Use this for the Type 0 variant XY-Clock, with wiring is equal to datasheet DisplayType 2 - Use this for the Type 2 variant 303WifiLC01, with a different wiring
After the ESP8266/ESP32 module restarts again, the display module is ready to accept commands.
"},{"location":"TM1650/#displaymodes","title":"DisplayModes","text":"DisplayModes 0..3 are supported. The firmware default is DisplayMode 1.
To use the Seven-Segment specific Display- commands described below, set the DisplayMode to 0 with:
DisplayMode 0
"},{"location":"TM1650/#displaydimmer","title":"DisplayDimmer","text":"The brightness of the display can be set using the DisplayDimmer command.
DisplayDimmer 0..100 maps the brightness value to 8 steps from 0..7
For a minimum brightness, make sure this value is at least about 13
"},{"location":"TM1650/#7-segment-specific-commands","title":"7-Segment specific Commands","text":"The Display- commands listed below can be used from the Tasmota web-console, MQTT, and from Tasmota Rules
"},{"location":"TM1650/#commands-and-usage","title":"Commands and Usage","text":"Console/MQTT Commands Description values DisplayClear Clears the display DisplayNumber Clears and then displays number without decimal. command e.g., \"DisplayNumber 1234\". Control position, leading zeros, and length. position can be 0 (left-most) to NUM_DIGITS-1 (right-most), leading zeros can be 1 or 0 (default), length can be 1 to NUM_DIGITS (4 or 6). Command example: DisplayNumber 12, 1, 1, 3 This will display: num [, position[, leading_zeros[, length]]] DisplayNumberNC Display integer number as above, but without clearing first. e.g., \"DisplayNumberNC 1234\". Usage is same as above. same as above DisplayFloat Clears and then displays float (with decimal point) command e.g., \"DisplayFloat 12.34\". Control position, precision, and length. position can be 0 (left-most) to NUM_DIGITS-1 (right-most), precision can be 0 to NUM_DIGITS (default), length can be 1 to NUM_DIGITS (4 or 6). Command example: DisplayFloat 2.48, 1, 1, 2 This will display: num[, position[, precision[, length]]] DisplayFloatNC Displays float (with decimal point) as above, but without clearing first. command e.g., \"DisplayFloatNC 12.34\" same as above DisplayRaw Takes up to NUM_DIGITS comma-separated integers (0-255) and displays raw segments. Each number represents a 7-segment digit. Each 8-bit number represents individual segments of a digit. Segment a=1, b=2, c=4, d=8, e=16, f=32, g=64 and h (decimal point)=128. To turn on all segments, the number would be 1+2+4+8+16+32+64+128 = 255 For example, the command DisplayRaw 0, 2, 255, 255 would display: position, length, num1 [, num2[, num3[, num4[, ...up to NUM_DIGITS numbers]]...] DisplayText Clears and then displays basic text. Command e.g., DisplayText a.b12 Control length and position of the displayed text. length can be 1 to NUM_DIGITS , position can be 0 (left-most) to NUM_DIGITS-1 (right-most) A caret(^) symbol in the text input is displayed as the degrees(\u00b0) symbol. This is useful for displaying Temperature (or angle)! For example, the command DisplayText 22.5^ will display: text[, position[, length]] DisplayTextNC Displays text without first clearing the display. Usage is same as above. same as above DisplayScrollText Displays scrolling text, up to 50 characters. If num_iterations is not specified, it scrolls indefinitely, until another Display- command is issued. Optionally, specifying num_iterations causes the scrolling to stop after the specified number of iterations.Command examples: DisplayScrollText tasmota is awesome -- causes indefinite scrollingDisplayScrollText tasmota is awesome, 5 -- causes scrolling to stop after 5 iterations text [, num_iterations] DisplayScrollDelay Sets the speed of text scroll. Smaller delay = faster scrolling. 0 to 15 DisplayLevel Display a horizontal bar graph. Command e.g., DisplayLevel 50 will display: 0 to 100 DisplayClock Displays a clock. DisplayClock 1 displays a clock in 12-hour format. DisplayClock 2 displays a clock in 24-hour format. DisplayClock 0 turns off the clock and clears the display 1 or 2 or 0"},{"location":"TM1650/#usage-in-rules","title":"Usage in Rules","text":"All the above commands can be used in Tasmota Rules, as usual.
For example, a simple digital thermometer can be implemented by connecting a DHT22 Temperature-Humidity Sensor and a TM1650 to a Wemos D1 Mini, and writing a Rule like the following:
Rule1\nON Tele-AM2301#Temperature DO DisplayText %value%^ ENDON\n
"},{"location":"TSL2561/","title":"TSL2561 light sensor","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_TSL2561\n#define USE_TSL2561 // [I2cDriver16] Enable TSL2561 sensor (I2C address 0x29, 0x39 or 0x49) using library Joba_Tsl2561 (+2k3 code)\n#endif\n
The TSL2561 luminosity sensor is an advanced digital light I2C sensor, ideal for use in a wide range of light situations.
"},{"location":"TSL2561/#configuration","title":"Configuration","text":""},{"location":"TSL2561/#wiring","title":"Wiring","text":"TSL2561 ESP GND GND VCC 3.3V SCL GPIOy SDA GPIOx INT not used"},{"location":"TSL2561/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
After a reboot the driver will detect TSL2561 automatically and display Illuminance.
Sensor sends a tele/%topic%/SENSOR JSON response:
{\"Time\":\"2019-11-03T21:04:05\",\"TSL2561\":{\"Illuminance\":21.180}}\n
"},{"location":"TSL2561/#breakout-boards","title":"Breakout Boards","text":""},{"location":"TX2x/","title":"TX20/TX23/WS2300-15 anemometer","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h: For TX20 sensor
#ifndef USE_TX20_WIND_SENSOR\n#define USE_TX20_WIND_SENSOR // Add support for La Crosse TX20 anemometer (+2k6/0k8 code)\n#endif\n
For TX23 sensor #ifndef USE_TX23_WIND_SENSOR\n#define USE_TX23_WIND_SENSOR // Add support for La Crosse TX20 anemometer (+2k6/0k8 code)\n#endif\n
For WS2300-15 sensor #ifndef USE_WS2300_WIND_SENSOR\n#define USE_WS2300_WIND_SENSOR // Add support for Technoline WS2300-15 anemometer\n#endif\n
This setting compiles Tasmota with sensor statistical values (needs the higher value size of code), which are useful for the wind sensor, since the measured values naturally change very quickly. The values generated in addition to the wind speed and wind direction are:
- Wind speed min/max
- Wind speed average (\u2205)
- Wind direction average (\u2205)
- Wind direction range (\u2220) and min/max
The average (\u2205) values are continuously calculated values. The range (\u2220) and min/max values are held for the time TelePeriod and reset after MQTT SENSOR message has been output.
If you do not want the statistical calculation having speed and direction value only, use
#ifndef USE_TX2X_WIND_SENSOR_NOSTATISTICS\n#define USE_TX2X_WIND_SENSOR_NOSTATISTICS\n#endif\n
in your user_config_override.h. This will save approx. 1k8 bytes of code.
The TX20 (retired) and TX23 sensor supplies the two measured values wind speed and wind direction.
The TX23 sensor is still available under various brand names such as \"La Crosse\", \"Technoline\". Unfortunately, the TX20 (at least in Europe) is almost impossible to get. However, the two sensors differ only in the protocol used, but deliver the same measured values.
"},{"location":"TX2x/#configuration","title":"Configuration","text":""},{"location":"TX2x/#wiring","title":"Wiring","text":""},{"location":"TX2x/#tx20-ws2300-15","title":"TX20 / WS2300-15","text":"Pin Color Description ESP 1 Brown/Black TxD GPIOx 2 Red 3.3V 3.3V 3 Green DTR GND 4 Yellow GND GND"},{"location":"TX2x/#tx23","title":"TX23","text":"Pin Color Description ESP 1 Brown/Black TxD GPIOx 2 Red 3.3V 3.3V 3 Green - - 4 Yellow GND GND"},{"location":"TX2x/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign: GPIOx to TX2x (104)
The TX2 pin needs a pull-up resistor. The internal pull-up is activated for this so you can use any useful GPIO except GPIO15 and GPIO16 (GPIO15 is always pulled low, GPIO16 has a built-in pull-down resistor).
To be on the save side you can add an additional external 10k pull-up to TX2x GPIOx.
After a reboot the driver will detect TX20/TX23/WS2300 automatically and display the wind data:
Sensor sends a tele/%topic%/SENSOR JSON response:
{\n\"Time\": \"2020-03-03T00:00:00+00:00\",\n\"TX23\": {\n\"Speed\": {\n\"Act\": 14.8,\n\"Avg\": 8.5,\n\"Min\": 12.2,\n\"Max\": 14.8\n},\n\"Dir\": {\n\"Card\": \"WSW\",\n\"Deg\": 247.5,\n\"Avg\": 266.1,\n\"AvgCard\": \"W\",\n\"Min\": 247.5,\n\"Max\": 247.5,\n\"Range\": 0\n}\n},\n\"SpeedUnit\": \"km/h\"\n}\n
"},{"location":"TX2x/#commands","title":"Commands","text":"The wind speed unit is set to km/h as default. You can change the unit using the command SpeedUnit <x> where <x> = 1\u20266: - 1 = m/s (meter per second) - 2 = km/h (kilometer per hour) - 3 = kn (knots) - 4 = mph (miles per hour) - 5 = ft/s (foot per second) - 6 = yd/s (yard per second)
The changed unit will appear in the webUI and via MQTT SENSOR messages.
"},{"location":"TasUI/","title":"TasUI","text":"Warning
Development of TasUI has stopped!!!
TasUI is a zero-install device management interface web application for all your Tasmota devices. It will discover your deployed devices and allow you to set up and configure every device from a single dashboard. This initial version includes multiple views (Control, Health, Firmware, Wi-Fi, & MQTT) to allow you to quickly assess the state of your devices. There is also a detailed view (e.g., SetOptions, Status, etc.) available.
TasUI provides a syntax-aware command interface for every Tasmota command by category (e.g., Configuration, Timers, Sensors, Lights, etc.) as well as the \"familiar\" Console interface to enter commands directly. This is a beta version (i.e., we expect you to find some unexpected features). As these issues are fixed, it will not require you to reinstall any software to get these fixes. This also applies to new features as they are added to the app.
Join us on Discord!
"},{"location":"TasUI/#docker","title":"Docker","text":"For those who prefer to have everything installed locally, a Docker image for linux amd64, arm32v7, arm64v8 and i386 is available for download.
docker pull iotreboot/tasui:latest\ndocker run -p [PORT]:80 iotreboot/tasui:latest\n
"},{"location":"TasUI/#home-assistant","title":"Home Assistant","text":"The add-on can be installed on amd64, arm32v7, arm64v8 and i386 builds. Simply add the TasUI repository on your addons list: https://github.com/iotreboot/TasUI
No configuration is required.
"},{"location":"TasmoAdmin/","title":"TasmoAdmin","text":"TasmoAdmin is an administrative Website for Devices flashed with Tasmota. You can find it here: TasmoAdmin GitHub. It supports running on Windows, Linux and as Docker container.
"},{"location":"TasmoAdmin/#features","title":"Features","text":" - Login protected
- Multi Update Process
- Select devices to update
- Automatic Modus downloads latest firmware bin from Tasmota GitHub
- Show device information
- Mobile Responsive (Bootstrap4)
- Config devices
- SelfUpdate function for TasmoAdmin (disabled for Docker)
- NightMode (Enable/Disable/Auto) in settings
- AutoScan to find Tasmota Devices
- Support for multiple sensors
- chat (beta)
"},{"location":"TasmoAdmin/#installation","title":"Installation","text":""},{"location":"TasmoAdmin/#docker","title":"Docker","text":"TasmoAdmin is available as a Docker image on GitHub packages.
This is a Linux Alpine based image with Nginx and PHP7 installed. It supports multiple architectures, amd64 (i.e. Synology DSM), arm (i.e. Raspberry PI3) and arm64 (i.e. Pine64). Check out the Guide for TasmoAdmin on Docker for setup instructions.
This is the recommended way to get up and running.
"},{"location":"TasmoAdmin/#linux","title":"Linux","text":"Running TasmoAdmin on a Linux/Unix hosts requires the following:
- A Webserver
- apache2 recommended
- php7 recommended (works with php5 too)
- php-curl php-zip Modules installed
You need to install a web server with php-zip and php-curl modules installed. Also mod_rewrite must be enabled. I suggest to look in the Guide for Ubuntu Server 16.04 and try to adjust it to your server OS.
"},{"location":"TasmoAdmin/#example-images","title":"Example Images","text":""},{"location":"TasmoAdmin/#login-page","title":"Login Page","text":""},{"location":"TasmoAdmin/#start-page","title":"Start Page","text":""},{"location":"TasmoAdmin/#devices-page","title":"Devices Page","text":""},{"location":"TasmoAdmin/#devices-addedit-page","title":"Devices Add/Edit Page","text":""},{"location":"TasmoAdmin/#config-general-page","title":"Config General Page","text":""},{"location":"TasmoAdmin/#config-network-page","title":"Config Network Page","text":""},{"location":"TasmoAdmin/#update-devices-page","title":"Update Devices Page","text":""},{"location":"TasmoAdmin/#settings-page","title":"Settings Page","text":""},{"location":"TasmoAdmin/#mobile","title":"Mobile","text":""},{"location":"Tasmota-Application/","title":"Tasmota Application Files","text":"Easily import any configuration or script using the .tapp file extension
Any file with .tapp (Tasmota Application) extension will be considered as an uncompressed ZIP, and if it contains a sub-file autoexec.be it will be executed. In parallel tasmota.wd (working dir) contains the archive tapp prefix to easily load other assets from the same archive.
Example
heating.tapp contains: autoexec.be and html.json. The sub-file html.json can be opened with f = open(tasmota.wd + \"html.json\", \"r\")
Berry allow imports from files inside a Tasmota App (.tapp file). Also enabled sys module.
Here is the code you should add in your autoexec.be inside tapp file:
import sys\nvar wd = tasmota.wd\nif size(wd) sys.path().push(wd) end\n\n# [...] you can import files from within the archive\n\nif size(wd) sys.path().pop() end\n
"},{"location":"Tasmota-Application/#tapps","title":"TAPP's","text":""},{"location":"Tasmota-Application/#lcdoled-anti-screen-burn","title":"LCD/OLED Anti Screen Burn","text":" - copy Antiburn.tapp to file system
- Either issue Tasmota command
Antiburn or programmatically using lv.antiburn() in Berry
The LVGL screen will change from black to red to green to blue to white each second for 30 seconds. The anti-burn cleaning can be cancelled by touching the screen or it will complete after 30 seconds. Once complete the previous screen will be reloaded.
"},{"location":"Tasmota-Application/#partition-management","title":"Partition Management","text":"Partition Wizard
Partition Manager
To run either of these apps, simply upload the .tapp file to the filesystem and reboot the board. After doing so, the app will appear on the consoles page in the GUI.
"},{"location":"Tasmota-Application/#display-calibration","title":"Display Calibration","text":"Tasmota Application useful for Touch Screen calibration (resistive touchscreens only). This application guides you through simple steps and generates automatically the required settings in display.ini (the ':M' line).
-
First download DisplayCalibrate.tapp application and upload it in the file system, and restart.
-
Make sure you are in orientation DisplayRotate 0
-
In the console, type the command DisplayCalibrate
You will see the following screens. Click on all 4 crosses near corners.
Note: measures are taken every 50 ms and are averaged, and requires at least 3 measures (150ms).
If everything went well, you will see the following screen. After reboot, your touchscreen is ready and calibrate.
If the geometry is wrong, you will see the following screen and no change is done to display.ini
"},{"location":"Tasmota-Device-Locator/","title":"Tasmota Device Locator","text":"Locate Tasmota Devices on your network when you only know the subnet of the device. The search is done with JavaScript in a browser and no software installation is required. Only newer devices with HTTP Cross-Origin Resource Sharing (CORS) support will be found. CORS is disabled in Tasmota by default. Use the CORS command to change this setting.
"},{"location":"Tasmota-Device-Locator/#usage","title":"Usage","text":"Enter any IP address in the subnet and it will search for devices on the entire subnet. For example, specify 192.168.0.0 to locate all devices in the range 192.168.0.0 to 192.168.0.255.
If the devices are password protected also enter the password. The password will be tried on all devices. If they have different passwords, multiple searches must be performed.
"},{"location":"Tasmota-Device-Locator/#run-the-live-version","title":"Run the live version","text":"The live version can be found here
"},{"location":"Tasmota-Device-Locator/#local-deployment","title":"Local Deployment","text":"If you want to run your own server, the Tasmota Device Locator can be served by any static http server (not https). - Checkout the branch gh-pages. - Copy the files to the root of the web server
"},{"location":"Tasmota-Device-Locator/#development","title":"Development","text":"Sources can be found on github, Tasmota Device Locator.
"},{"location":"Tasmota-Device-Manager/","title":"Tasmota Device Manager","text":"Tasmota Device Manager or TDM is a GUI application written in Python for discovery and monitoring of Tasmota flashed devices.
"},{"location":"Tasmota-Device-Manager/#features","title":"Features","text":" - clean, readable interface
- autodetection of devices following the default topic template for Tasmota (%prefix%/%topic%/) and for HomeAssistant Auto Discovery protocol (%topic%/%prefix%/)
- module and GPIO configuration
- rules editor
- devices with different syntax can be added manually
- clean retained MQTT topic messages
- toggleable active querying of telemetry
- passive monitoring of state and telemetry (currently supported sensors are listed in \"status8.json\")
- relay control via context menu on device list (all ON/OFF, or individual)
- MQTT console with payload preview (dbl-click an entry to display), sorting and filtering
- selectable detail columns in device list
- BSSID aliasing for larger deployments
"},{"location":"Tasmota-Device-Manager/#installation","title":"Installation","text":"Python 3.6+ is required. Clone the repo or download zip and extract, install prerequisites and run tdm.py using Python binary.
"},{"location":"Tasmota-Device-Manager/#prerequisites","title":"Prerequisites","text":"PyQt5:
pip install PyQt5
paho-mqtt:
pip install paho-mqtt
"},{"location":"Tasmota-IR/","title":"IR Communication","text":"The default Tasmota firmware variants include support for IR send/receive for a limited set of protocols (see IR Remote commands).
Tasmota uses the IRremoteESP8266 library that supports numerous protocols. Each protocol consumes some memory, especially air conditioner protocols (up to 81k of flash size). Also, every protocol included increases the time to decode the IR signal.
There are two additional Tasmota firmware variants that provide almost all IRremoteESP8266 protocols. This requires disabling some other features to keep code size manageable.
tasmota-ir is pre-packaged for IR bridge devices such as Automate Things IRBR, Eachen or YTF. Choose tasmota-ir if you are using an IR blaster. tasmota-ircustom is used if you want to customize your features (additional sensors, language, etc.). See compile your own firmware.
You can flash the binary or upgrade your existing one.
To test that you have the correct firmware on your device issue the following command in the web UI Console:
IRHVAC {\"Vendor\":\"xx\"}
The output should be a list of the supported protocols/vendors. For example:
RESULT = {\"IRHVAC\":\"Wrong Vendor (COOLIX|DAIKIN|KELVINATOR|MITSUBISHI_AC|GREE|ARGO|TROTEC|TOSHIBA_AC|FUJITSU_AC|MIDEA|HAIER_AC|HITACHI_AC|HAIER_AC_YRW02|WHIRLPOOL_AC|SAMSUNG_AC|ELECTRA_AC|PANASONIC_AC|DAIKIN2|VESTEL_AC|TECO|TCL112AC|MITSUBISHI_HEAVY_88|MITSUBISHI_HEAVY_152|DAIKIN216|SHARP_AC|GOODWEATHER|DAIKIN160|NEOCLIMA|DAIKIN176|DAIKIN128|AMCOR)\"}\n
See Codes for IR Remotes.
"},{"location":"Tasmota-IR/#sending-ir-commands","title":"Sending IR Commands","text":"Send an IR remote control code as a decimal or hexadecimal string in a JSON payload. In order to send IR data, you must configure one of the free device GPIO as IRSend (8). Neither GPIO01 nor GPIO03 can be used.
Command Parameters IRSend<x> <x> [optional] = number of times the IR message is sent. If not specified or 0..1, the message is sent only once (i.e., not repeated) (default)>1 = emulate a long-press on the remote control, sending the message <x> times, or sending a repeat message for specific protocols (like NEC){\"Protocol\":\"<value>\",\"Bits\":<value>,\"Data\":<value>,\"DataLSB\":<value>,\"Repeat\":<value>}\"Protocol\" or \"Vendor\" (select one of the following): RC5, RC6, NEC, SONY, PANASONIC, JVC, SAMSUNG, WHYNTER, AIWA_RC_T501, LG, MITSUBISHI, DISH, SHARP, DENON, SHERWOOD, RCMM, SANYO_LC7461, RC5X, NEC (non-strict), NIKAI, MAGIQUEST, LASERTAG, CARRIER_AC, MITSUBISHI2, HITACHI_AC1, HITACHI_AC2, GICABLE, LUTRON, PIONEER, LG2, SAMSUNG36, LEGOPF, INAX, DAIKIN152\"Bits\":1..64 = required number of data bits\u00a0\u00a0\u00a0\u00a0for PANASONIC protocol this parameter is the the address, not the number of bits\"Data\":0x1..0xFFFFFFFFFFFFFFFF = data frame as 64 bit hexadecimal.\u00a0\u00a0\u00a0\u00a0e.g., IRSend {\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":0x8166817E}Or\"DataLSB\":0x1..0xFFFFFFFFFFFFFFFF = data frame as 64 bit hexadecimal with LSB (each byte with bits reversed).\u00a0\u00a0\u00a0\u00a0e.g., IRSend {\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":0x8166817E}DataLSB comes handy with LSB-first (Least Significant Bit First) protocols like NEC, and makes decoding/encoding easier.\"Repeat\":0..<x> if 0 send the frame once, if >0 simulates a long press; Note: \"Repeat\":1 sends the message twice.Alternatively, you can send IR remote control codes using RAW command encoding. See also SetOption29 - Set IR received data formatSetOption38 - Set IR received protocol sensitivitySetOption58 - IR Raw data in JSON payload"},{"location":"Tasmota-IR/#sending-irhvac-commands","title":"Sending IRHVAC Commands","text":"Command Parameters IRHVAC Send HVAC IR remote control code as JSON payloadIRHVAC {\"Vendor\":\"Mitsubishi_Heavy_152\", \"Power\":\"On\",\"Mode\":\"Hot\",\"FanSpeed\":3,\"Temp\":22.5}\"Protocol\" or \"Vendor\" (select one of the following): COOLIX, DAIKIN, KELVINATOR, MITSUBISHI_AC, GREE, ARGO, TROTEC, TOSHIBA_AC, FUJITSU_AC, MIDEA, HAIER_AC, HITACHI_AC, HAIER_AC_YRW02, WHIRLPOOL_AC, SAMSUNG_AC, ELECTRA_AC, PANASONIC_AC, DAIKIN2, VESTEL_AC, TECO, TCL112AC, MITSUBISHI_HEAVY_88, MITSUBISHI_HEAVY_152, DAIKIN216, SHARP_AC, GOODWEATHER, DAIKIN160, NEOCLIMA, DAIKIN176, DAIKIN128\"Model\": Some HVAC have variants in protocols, this field allows to specify the variant, see detailed list.Fujitsu_AC: ARRAH2E|ARDB1Panasonic_AC: LKE|NKE|DKE|JKE|CKP|RKRWhirlpool_AC: DG11J13A|DG11J104|DG11J1-04|DG11J191
\"Power\":On, Yes, True, 1Off, No, False, 0
\"Mode\":Off, StopAuto, AutomaticCool, CoolingHeat, HeatingDry, Drying, DehumidifyFan, Fanonly, Fan_Only
\"FanSpeed\":Auto, AutomaticMin, Minimum, Lowest, 1Low, 2Med, Medium, Mid, 3High, Hi, 4Max, Maximum, Highest, 5
\"SwingV\": vertical swing of FanAuto, Automatic, On, SwingOff, StopMin, Minimum, Lowest, Bottom, DownLowMid, Middle, Med, Medium, Centre, CenterHigh, HiHighest, Max, Maximum, Top, Up
\"SwingH\": horizontal swing of FanAuto, Automatic, On, SwingOff, StopLeftMax, Left Max, MaxLeft, Max Left, FarLeft, Far LeftLeftMid, Middle, Med, Medium, Centre, CenterRightRightMax, Right Max, MaxRight, Max Right, FarRight, Far RightWide
\"Celsius\": temperature is in Celsius (\"On\") or Fahrenheit (\"Off\")\"Temp\": Temperature, can be float if supported by protocol\"Quiet\": Quiet mode (\"On\" / \"Off\")\"Turbo\": Turbo mode (\"On\" / \"Off\")\"Econo\": Econo mode (\"On\" / \"Off\")\"Light\": Light (\"On\" / \"Off\")\"Filter\": Filter active (\"On\" / \"Off\")\"Clean\": Clean mode (\"On\" / \"Off\")\"Beep\": Beep active (\"On\" / \"Off\")\"Sleep\": Timer in seconds\"StateMode\":SendOnly (default)StoreOnlySendStore
"},{"location":"Tasmota-IR/#controlling-acs-with-toggle-fields","title":"Controlling ACs with toggle fields","text":"Some ACs such as Airwell, Whirlpool and others use a differential IR protocol for some properties. If \"power\" is a toggle property, then value of '1' in the protocol will mean \"turn off\" if the AC is currently \"on\" and it will mean \"turn on\" if the AC is currently \"off\". This could also be the case for other properties such as \"light\", \"swing\", etc. Since Tasmota and IRRemote8266 send and receive absolute states (i.e. the HVAC JSON object has a field called 'Power' not 'PowerToggle'), some functionality was added to keep track of the predicted state of the AC. This way, if the predicted state is in-sync with the actual state, the device can transmit a correct IR packet to transition the AC from the previous state to the desired state. This logic is controlled by the StateMode HVAC property. If your AC IR protocol sends absolute values you can ignore this property. If your AC has a differential protocol Tasmota will be able to control the AC assuming the Tasmota IR device has at most one differential AC in IR range. If you would like to also control your AC with the physical remote your Tamsota IR device will need to have an IR receiver so that it can sync with the actual state.
If at some point the state in Tasmota and the actual state get out of sync, you can specify StateMode=StoreOnly to update Tasmota with the actual state. This will update state but not send an IR command.
Normally when receiving an IR command via the IR receiver the command will be processed and the state will be updated. As a result it is not needed to store state when sending as it will cause duplication and the toggle will happen twice. The most common operation mode, and default, therefore is StateMode=SendOnly.
If your Tasmota device does not have an IR receiver you can still control a differential AC with it by specifying StateMode=SendStore but you will not be able to use a physical remote without loosing sync between the actual and predicted states.
"},{"location":"Tasmota-IR/#receiving-ir-commands","title":"Receiving IR Commands","text":"If you have an IR receiver, a message will be logged each time an IR message is seen. IR driver will try to decode the message against all supported protocols. If unrecognized, the \"Protocol\":\"UNKNOWN\" will be shown. In this case, the \"Data\" field contains a hash of the received message. The hash can't be used to send the a message, but the same hash will be produced by the same message.
An inexpensive IR sensor such as a TSOP1838 can be connected to a device running Tasmota. Configure a free device GPIO as 'IRrecv (51)'. When Tasmota receives an IR message, the data portion of the payload has the same format as the IRsend parameter.
{\"IrReceived\":{\"Protocol\":\"<value>\",\"Bits\":<value>,\"Data\":<value>}}\n
This JSON payload data can be used in a rule such as:
ON IrReceived#Data=<value> DO <command> ENDON\n
If the data is received on an unknown protocol use SetOption58 1. See here.
Examples: Pioneer Vol+ MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"PIONEER\",\"Bits\":64,\"Data\":\"0xA55A50AFA55A50AF\",\"DataLSB\":\"0xA55A0AF5A55A0AF5\",\"Repeat\":0}}
Pioneer Vol- tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"PIONEER\",\"Bits\":64,\"Data\":\"0xA55AD02FA55AD02F\",\"DataLSB\":\"0xA55A0BF4A55A0BF4\",\"Repeat\":0}}
Toshiba (NEC): Channel 1 MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":\"0x02FD807F\",\"DataLSB\":\"0x40BF01FE\",\"Repeat\":0}}
Toshiba (NEC): Channel 2 MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":\"0x02FD40BF\",\"DataLSB\":\"0x40BF02FD\",\"Repeat\":0}}
Toshiba (NEC): Channel 3 MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"NEC\",\"Bits\":32,\"Data\":\"0x02FDC03F\",\"DataLSB\":\"0x40BF03FC\",\"Repeat\":0}}
As you can see above, \"DataLSB\" are easier to decode than \"Data\". The third byte contains the command, and the fourth byte is the third with all bits reversed.
Example of HVAC message: MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"MITSUBISHI_HEAVY_152\",\"Bits\":152,\"Data\":\"0xAD513CE51A08F705FA02FDC03F08F700FF807F\",\"Repeat\":0,\"IRHVAC\":{\"Vendor\":\"MITSUBISHI_HEAVY_152\",\"Model\":-1,\"Power\":\"on\",\"Mode\":\"auto\",\"Celsius\":\"on\",\"Temp\":22,\"FanSpeed\":\"medium\",\"SwingV\":\"off\",\"SwingH\":\"off\",\"Quiet\":\"off\",\"Turbo\":\"off\",\"Econo\":\"off\",\"Light\":\"off\",\"Filter\":\"off\",\"Clean\":\"off\",\"Beep\":\"off\",\"Sleep\":-1}}}
MQT: tele/tasmota/IR1/RESULT = {\"IrReceived\":{\"Protocol\":\"COOLIX\",\"Bits\":24,\"Data\":\"0xB25F78\",\"DataLSB\":\"0x4DFA1E\",\"Repeat\":0,\"IRHVAC\":{\"Vendor\":\"COOLIX\",\"Model\":-1,\"Power\":\"on\",\"Mode\":\"auto\",\"Celsius\":\"on\",\"Temp\":22,\"FanSpeed\":\"medium\",\"SwingV\":\"off\",\"SwingH\":\"off\",\"Quiet\":\"off\",\"Turbo\":\"off\",\"Econo\":\"off\",\"Light\":\"on\",\"Filter\":\"off\",\"Clean\":\"on\",\"Beep\":\"off\",\"Sleep\":-1}}}
RSL: RESULT = {\"Time\":\"2019-09-09T21:52:35\",\"IrReceived\":{\"Protocol\":\"PANASONIC_AC\",\"Bits\":216,\"Data\":\"0x0220E004000000060220E00400032C805F06000EE0000081000089\",\"Repeat\":0,\"IRHVAC\":{\"Vendor\":\"PANASONIC_AC\",\"Model\":2,\"Power\":\"on\",\"Mode\":\"auto\",\"Celsius\":\"on\",\"Temp\":22,\"FanSpeed\":\"medium\",\"SwingV\":\"auto\",\"SwingH\":\"middle\",\"Quiet\":\"off\",\"Turbo\":\"off\",\"Econo\":\"off\",\"Light\":\"off\",\"Filter\":\"off\",\"Clean\":\"off\",\"Beep\":\"off\",\"Sleep\":-1}}}
"},{"location":"TasmotaClient/","title":"Arduino MCU","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_TASMOTA_CLIENT\n#define USE_TASMOTA_CLIENT // Enable the driver\n#endif\n\n#ifndef USE_TASMOTA_CLIENT_FLASH_SPEED\n#define USE_TASMOTA_CLIENT_FLASH_SPEED 57600 // Configure the baud rate of the bootloader\n#endif\n\n#ifndef USE_TASMOTA_CLIENT_SERIAL_SPEED 57600 \n#define USE_TASMOTA_CLIENT_SERIAL_SPEED 57600 // Configure the baud rate at which the client microcontroller will be interfacing to Tasmota\n#endif\n
It is possible to amend your existing Arduino Uno/Mini/Nano project to interface with a Tasmota powered ESP8266/ESP8285 generic development boards such as the Wemos D1 or NodeMCU branded hardware boards.
The creation of a client driver interface implemented since Tasmota 7.0.0.2 enables this possibility.
Please note that the USE_TASMOTA_CLIENT_FLASH_SPEED will depend on the variant of Arduino Uno/Mini/Nano board you are using - The general observation is that the 3.3V devices usually run at 57600 whereas the 5V devices usually run on 115200 but this is provided for guidance only as it has been found that some boards will not necessarily adhere to this. The main driving factor behind the baud rate is the crystal oscillator on the board which is usually 8Mhz for 3.3V variants and 16Mhz for 5V variants - hence 57600 being 1/2 of 115200.
It should also be noted that this option is only really applicable if you're actually using an Arduino UNO/Mini/Nano as a client device and you want to be able to update the firmware on the Arduino OTA via the Tasmota Web UI.
If you are using another type of microcontroller, obviously the OTA update functionality will not work (for now, until support is added for other microcontrollers). But if you are able to program the device manually there is no reason why you cannot use any microcontroller or development board as a client to your Tasmota powered ESP8266/8285 hardware.
Once you have compiled your own variant with the correct settings and flashed the self-compiled binary to your Tasmota device it is time to make the necessary configuration within Tasmota.
"},{"location":"TasmotaClient/#configuring-tasmota-to-use-the-tasmotaclient-functionality","title":"Configuring Tasmota to use the TasmotaClient functionality","text":"The communication interface between Tasmota and your client micro-controller will be over serial communication. To make this possible you will need to configure two of the GPIO pins to Client TX and Client RX respectively. In addition to this you also need to define the GPIO which will be used to pull the reset pin of your client microcontroller down to GND or up to 3.3V, so either Client RST for normal reset behaviour (active low) or Client RSTi for inverted reset behaviour (active high)
As mentioned above it is possible to connect any microcontroller of your choice but for the purpose of this article, only the implementation of an Arduino Pro Mini (3.3V) will be covered.
"},{"location":"TasmotaClient/#getting-things-wired-up","title":"Getting things wired up","text":"With Tasmota GPIO configuration provided above you may now proceed to make the necessary electrical connections between the ESP8266/ESP8285 and your client device, for example:
ESP Arduino Pro Mini (3.3V) VCC VCC GND GND D2 (GPIO4) RX (0) D1 (GPIO5) TX (1) D4 (GPIO2) Reset (RST) So to visualize the above:
Please verify your specific board's pin naming as they are not always exactly the same depending on where they came from!
"},{"location":"TasmotaClient/#compiling-a-test-sketch-for-the-client","title":"Compiling a test sketch for the client","text":"The TasmotaClient driver requires your client to operate within specific parameters allowed by the driver itself so head over to the TasmotaClient Library and install the library in your local Arduino development environment.
Once installed you should be able to access the examples from the menu system:
Make sure you have the correct board and speed selected:
Now that everything is set, it's time to export the compiled binary by selecting it from the Arduino menu:
Once completed head over to the known folder you chose in previous steps and locate the .hex file which should be in the same folder as where your sketch was originally saved to.
You will most likely see a file listing like this:
You are interested in Blink.ino.eightanaloginputs.hex and can ignore the one which has bootloader as part of the file name since the Arduino Pro Mini already has the bootloader flashed. Take note of the location and name of this file as you will need it in the next step to upload the compiled file to your client device.
"},{"location":"TasmotaClient/#uploading-a-new-hex-file-to-your-client-device","title":"Uploading a new hex file to your client device","text":"If you are using an Arduino Pro Mini as is the case in this example you would have created a .hex file in the previous step. This file can be flashed directly to the Arduino Pro Mini via the Tasmota Web UI.
Navigate to the Firmware Upgrade page where you would normally upload a new binary file to upgrade Tasmota. The same method is used to upload a HEX file to the client device. Tasmota will automatically decide where it will flash the upload based on whether you're uploading a .bin file or a .hex file.
Tasmota will prompt you for the firmware file you wish to upload - You need to navigate to the previously known location folder you chose in earlier steps and select the .hex file previously identified:
After selecting the hex file you may proceed to click the Start Upgrade button:
The hex file will upload to Tasmota and Tasmota will flash the new client firmware onto the Arduino Pro Mini and present you with the following web page:
After the device completes a restart you should now have an Arduino Pro Mini running as a client where the blink is controlled from Tasmota's internal one-second callback.
"},{"location":"Teleinfo/","title":"Teleinfo","text":"This feature is not included in precompiled binaries.
See below how to build you own Tasmota with Teleinfo enabled.
"},{"location":"Teleinfo/#overview","title":"Overview","text":"Teleinfo is a Tasmota ENERGY driver for energy meters installed by French national electricity grid manager Enedis in all households. Teleinfo driver works with either legacy meters or the new Linky meters. It is based on Charles Hallard's LibTeleinfo.
Teleinfo driver features:
- Support for Legacy mode (mode Historique at 1200 baud) or Standard mode (9600 baud)
- Extract fields to feed Tasmota standard ENERGY module allowing Tasmota to report standard SENSOR.ENERGY messages and all related features (PowerDelta, margins, ...)
- Publish raw Teleinfo frame to MQTT for processing by the backend
Support in french is available on Charles Hallard forums.
"},{"location":"Teleinfo/#compiling-with-support-for-teleinfo","title":"Compiling with support for Teleinfo","text":"As the feature is not included by default, you must compile your build.
To enable Teleinfo, add the following line in your user_config_override.h and compile tasmota or tasmota32.
#define USE_TELEINFO\n
But as I'm testing lot of boards, my preference goes to add my custom boards section into the file platformio_tasmota_cenv.ini
For example on ESP8266 board with teleinfo and I2C display to display Energy data
[env:tasmota-tic-display]\nextends = env:tasmota\nplatform_packages = ${common.platform_packages}\nbuild_unflags = ${common.build_unflags}\nbuild_flags = ${common.build_flags}\n-DUSE_TELEINFO\n-DUSE_DISPLAY\n
"},{"location":"Teleinfo/#configure-gpios-for-teleinfo","title":"Configure GPIOs for Teleinfo","text":""},{"location":"Teleinfo/#serial-reception","title":"Serial reception","text":"Once you have flashed Tasmota with the support for Teleinfo, you need to configure the proper GPIO to receive the Teleinfo serial data with \"TInfo RX\"
On ESP8266, suitable pins are
- Standard UART0 RX pin on GPIO3
- Alternate UART0 RX pin on GPIO13 (D7)
On ESP32, most of the pins can be used since uart can be mapped on almost all pins.
On Denky boards it's connected to GPIO33 and on new DenkyD4 it's on GPIO8.
"},{"location":"Teleinfo/#optional-enable-pin","title":"Optional enable pin","text":"An optional Enable GPIO can be configured as \"TInfo EN\". Any GPIO output can be used for that purpose. Enable pin is for low power future use and avoid to have any consumption when there is nothing to do.
For example schematic on custom Denky board (ESP32) is as follow
Resistors values R3 and R4 need to be changed to work with standard and historique. New official values for R3 is 220ohm and R4 is 3.3Kohm. If you still have issues in Standard mode try to increase R3 up to 1Kohm
As you can see GPIO33 is used for RX and GPIO4 for Enable (need set to 1 to be able to receive data)
Setup in this case is
- Enable pin on GPIO4
- RX pin on GPIO33
Another example on ESP8266 could be D5/GPIO14:
After selecting the GPIOs, click on \"SAVE\" and Tasmota will reboot.
"},{"location":"Teleinfo/#configuring-teleinfo","title":"Configuring Teleinfo","text":"You can customize Teleinfo with the command EnergyConfig <command> <parameter>. The list of supported commands and parameters are:
Subcommand Parameters Without any command and parameter, displays the current active configuration. Historique Set Teleinfo in legacy (historique) mode at 1200 baud. Standard Set Teleinfo in standard mode at 9600 baud. NoRaw Disable sending of raw frame (see below). Full Enable sending of all frames in raw mode. Changed Enable sending raw frames only when data has changed. Skip n Skips n frames before sending raw frame. Limit Limit raw frames to values subject to fast change (Power, Current, ...) Stats Show Teleinfo frames errors statistics Changing mode from historique to standard and vice-versa will restart tamota.
"},{"location":"Teleinfo/#check-current-configuration","title":"Check current configuration","text":"First thing is to see how teleinfo is configured, for this you need to use EnergyConfig command from console
17:24:56.758 CMD: EnergyConfig\n17:24:56.766 TIC: Settings Mode:historique, RX:GPIO23, EN:None, Raw:noraw, Skip:0, Limit:0, Stats:0\n17:24:56.783 MQT: emoncms/ch2i/factory/denky_D6C0C0/stat/RESULT = {\"EnergyConfig\":\"Done\"}\n
In this case we can see we are in historique mode, RX data is coming on GPIO32 (it's an ESP32) and Enable Pin is not used. No MQTT raw frame will be sent (noraw) on teleinfo frame reception, so keeping default config of telemetry. Statistics are disabled, so won't be displayed on WEB UI but still available on console.
"},{"location":"Teleinfo/#energy-from-teleinfo","title":"Energy from Teleinfo","text":"If correct mode and GPIO configuration are set, you'll be able to see on main tasmota screen something like that
It's happening only as soon as tasmota was able to read one valid frame from Teleinfo.
Data received from teleinfo is used by tasmota in real time to display information but also to calculate daily energy consumption. Of course as Teleinfo is returning lot of data (such as kWh indexes) all interesting information is displayed on the Web interface. Since we know (because it's on teleinfo frame) the current contract we can display bargraph of charge (in %). This can help to see when main house smartmeter will shut down due to over consumption (for example)
"},{"location":"Teleinfo/#default-data","title":"Default data","text":"If configuration is left by default (and if you have configured MQTT of course) you will receive a frame each time telemtry happens (menu configuration -> configure logging -> telemetry period) which is by default every 5 minutes.
You can check on console, the frame received is sent every 5 minutes under SENSOR topic as a JSON string. This frame as all default tasmota fields and also a object ENERGY related to tasmota Energy module.
17:28:45.907 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"Time\":\"2021-10-26T17:28:45\",\"ENERGY\":{\"TotalStartTime\":\"2021-10-25T15:22:04\",\"Total\":9098.245,\"Yesterday\":6822.685,\"Today\":2275.560,\"Period\": 9,\"Power\":170,\"Current\":1.000,\"Load\":6},\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275560,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":170,\"HHPHC\":\"A\",\"MOTDETAT\":0},\"ESP32\":{\"Temperature\":36.1},\"TempUnit\":\"C\"}\n17:33:45.906 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"Time\":\"2021-10-26T17:33:45\",\"ENERGY\":{\"TotalStartTime\":\"2021-10-25T15:22:04\",\"Total\":9098.255,\"Yesterday\":6822.685,\"Today\":2275.570,\"Period\":10,\"Power\":190,\"Current\":1.000,\"Load\":6},\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275570,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":190,\"HHPHC\":\"A\",\"MOTDETAT\":0},\"ESP32\":{\"Temperature\":36.1},\"TempUnit\":\"C\"}\n17:38:45.905 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"Time\":\"2021-10-26T17:38:45\",\"ENERGY\":{\"TotalStartTime\":\"2021-10-25T15:22:04\",\"Total\":9098.265,\"Yesterday\":6822.685,\"Today\":2275.579,\"Period\": 9,\"Power\":170,\"Current\":1.000,\"Load\":6},\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275579,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":170,\"HHPHC\":\"A\",\"MOTDETAT\":0},\"ESP32\":{\"Temperature\":36.7},\"TempUnit\":\"C\"}\n
But in our case we have also a TIC object which contains all the frame received on teleinfo frame (last reveived value), for example in the frame above the TIC object is the following.
{\n\"TIC\":{\n\"ADCO\":\"021528603314\",\n\"OPTARIF\":\"HC..\",\n\"ISOUSC\":15,\n\"HCHC\":920750,\n\"HCHP\":2275579,\n\"PTEC\":\"HP..\",\n\"IINST\":1,\n\"IMAX\":2,\n\"PAPP\":170,\n\"HHPHC\":\"A\",\n\"MOTDETAT\":0\n}\n}\n
"},{"location":"Teleinfo/#sending-data-to-other","title":"Sending data to other","text":"Teleinfo is a very powerful tool to monitor house energy consumption that many of you may need to send these date to backend for other treatment. For example receiving power value every 5 minutes may be an issue to real time monitoring house consuption, this is why we introduced option to send data in real time.
Best would be sending full received frame to MQTT for example, let's do that.
"},{"location":"Teleinfo/#raw-frame-going-outside-mqtt","title":"Raw Frame going outside (MQTT)","text":"To enable real time raw teleinfo frame to be sent to MQTT you need to use EnergyConfig Full command from console
17:57:04.579 TIC: Raw to 'full'\n17:57:04.594 MQT: emoncms/ch2i/factory/denky_D6C0C0/stat/RESULT = {\"EnergyConfig\":\"Done\"}\n17:57:05.038 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275613,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":180,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n17:57:06.693 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275613,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":180,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n17:57:08.183 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275614,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":170,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n17:57:09.684 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275614,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":200,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n
Then each frame received is sent immediately thru MQTT
"},{"location":"Teleinfo/#skip-frames","title":"Skip frames","text":"Depending on what you want to do on backend side it may be too much data and flood your database so we introduced Skip flag. For example we may need only one frame up to 10 to be send on backend (so free up some network traffic). To limit teleinfo frame to one each 10 frames, you need to use EnergyConfig Skip 10 command from console
18:04:43.210 CMD: EnergyConfig Skip 10\n18:04:43.214 TIC: Raw each 11 frame(s)\n18:04:43.226 MQT: emoncms/ch2i/factory/denky_D6C0C0/stat/RESULT = {\"EnergyConfig\":\"Done\"}\n18:05:00.438 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275628,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":170,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n18:05:17.438 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"ADCO\":\"021528603314\",\"OPTARIF\":\"HC..\",\"ISOUSC\":15,\"HCHC\":920750,\"HCHP\":2275629,\"PTEC\":\"HP..\",\"IINST\":1,\"IMAX\":2,\"PAPP\":170,\"HHPHC\":\"A\",\"MOTDETAT\":0}}\n
As you can see we now send one full frame every approx 17s, choose your limit depending on frame length (of course) and serial speed. In historique mode a frame takes about 1.2s to be received.
This works only if Raw mode has been selected with EnergyConfig Full.
"},{"location":"Teleinfo/#relevant-data","title":"Relevant data","text":"We can also going further, in previous mode, even if we limited the number of frames sent, a complete frame with all data was send. And this is not optimized because some fields in the frame may vary only once or twice a day PTEC or even never ADCO, ISOUSC, ... So we indroduced the Changed mode where only data changed from one frame to another is sent. To enable this mode, you need to use EnergyConfig Changed command from console
18:28:57.610 CMD: EnergyConfig Changed\n18:28:57.615 TIC: Raw to 'changed'\n18:28:57.627 MQT: emoncms/ch2i/factory/denky_D6C0C0/stat/RESULT = {\"EnergyConfig\":\"Done\"}\n18:29:00.425 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"PAPP\":160}}\n18:29:17.745 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"PAPP\":190}}\n18:29:34.689 MQT: emoncms/ch2i/factory/denky_D6C0C0/tele/SENSOR = {\"TIC\":{\"PAPP\":170}}\n
As you can see we now only data changed is sent.
This works only if Raw mode has been selected with EnergyConfig Full and Skip mode should be disabled EnergyConfig Skip 0 for this to works properly.
Don't worry about other fields, they will be send on each telemetry data as usual.
"},{"location":"Teleinfo/#errors-statistics","title":"Errors Statistics","text":"You can check classic frame reception errors (checksum, size, format, ...), with EnergyConfig Stats x command. Setting to 1 allow to display statistics on WEB UI while setting to 0 disable this option, but you will be able to always see stats on console with command EnergyConfig Stats.
You can clear Stats counters with EnergyConfig Stats 2
"},{"location":"Teleinfo/#tasmota-rules-examples","title":"Tasmota Rules examples","text":""},{"location":"Teleinfo/#raw-frame-going-outside-http","title":"Raw Frame going outside (HTTP)","text":"TBD, example to post HTTP data every 5 minutes
"},{"location":"Teleinfo/#driving-rgb-led-depending-on-power","title":"Driving RGB Led depending on power","text":"TBD, example to manage Led from Green (no charge) to Red (full charge)
"},{"location":"Teleinfo/#tasmota-berry-script-examples","title":"Tasmota Berry script examples","text":"TBD, any idea is welcome
"},{"location":"Teleinfo/#display-info-on-display","title":"Display info on display","text":"TBD, any idea is welcome
"},{"location":"Teleinfo/#raw-frames-examples","title":"Raw frames examples","text":"You can find various raw frames for standard and historique mode and different contracts on Teleinfo replay tool here
"},{"location":"Teleinfo/#hardware-information","title":"Hardware information","text":""},{"location":"Teleinfo/#basic-schematics","title":"Basic Schematics","text":"Classic connectivity of teleinfo can be done with following schematic, works with historique and standard mode.
"},{"location":"Teleinfo/#diy-or-ready-made-shields","title":"DIY or ready made Shields","text":""},{"location":"Teleinfo/#wemos","title":"WeMos","text":"Wemos Mini D1 (ESP8266) and MH-ET Live ESP32 Mini Kit
You can get more information about this shield on github repository
"},{"location":"Teleinfo/#raspberry-pi-bare-pcb","title":"Raspberry Pi (Bare PCB)","text":"You can also use or buy tiny Raspberry Pi shield to connect Teleinfo output signal to Tasmota device RX Pin
Documentation and reference of this shield are available on tindie
"},{"location":"Teleinfo/#references","title":"References","text":"You can find a lot of information, such as schematics and wiring diagrams, on Charles' blog
"},{"location":"Templates/","title":"Templates","text":"Template is a definition of a device and how its GPIOs are assigned.
Templates provide an easy way for you to create, modify and share configurations for various devices that have features supported in Tasmota.
Bug
Tasmota 9.1 completely redesigned template layout to allow for future expansion. Read more about the GPIO Conversion.
To provide easy processing by Tasmota a template is written as a JSON string and looks like this:
{\"NAME\":\"Example Template\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45}\n
Tip
Tasmota Supported Devices Repository has a complete list of supported devices. We encourage everyone who creates a template for a new unknown device to submit it using Add New Template form.
"},{"location":"Templates/#how-to-use","title":"How to Use","text":"Go to Configuration - Configure Template ...
... and you'll end up looking at this screen.
Time to create your template.
"},{"location":"Templates/#creating-your-template","title":"Creating Your Template","text":" - Change the template name (also defines the name for the module).
- Select a module to BASE your template on. If you're not sure,
Module 18 is the best choice. In this example the device is based on Blitzwolf SHP (45) module. -
Configure the components assigned to the GPIOs to match your device. If you do not know what pins your device uses, read about the new device configuration procedure to determine the correct pin assignments.
- Any unused GPIO that has cannot have a peripheral connected should be set to
None (0). In our example the device has no exposed GPIO's so the unused ones are set to 0 compared to the original BlitzWolf module. - GPIOs that can have peripherals connected to (exposed GPIOs) should be set to
User (1). This allows future configuration through the Configure Module dialog without the need to create a new template.
Example
Sonoff TH has a jack connected to GPIO4 that allows a user to plug in a sensor. Assigning GPIO4 as User allows a Template to have correct GPIOs for this device even if nothing is plugged in. But, when a user decides to connect a sensor using the jack, GPIO4 can be set to the type of sensor through the Configure Module page.
-
Click on Save and you'll see this message
-
Finally, the device will reboot with the new template name
"},{"location":"Templates/#exporting-your-template","title":"Exporting Your Template","text":"Now that you've set up your previously unsupported device in Tasmota it is time to share the knowledge:
- Check that
Module 0 is selected in the Configuration - Configure Module menu. - Open up Console and issue command
Template which will output a string with the configuration of your currently active template. Our example gives the following:
MQT: stat/tasmota/RESULT = {\"NAME\":\"Merged\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45}\n
Copy the string {\"NAME\":\"Merged\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45} and share it on the Tasmota Supported Devices Repository.
"},{"location":"Templates/#importing-templates","title":"Importing Templates","text":"Go to Configuration - Configure Other
When there:
- Paste the template string into the Template field
- Make sure you check Activate
- Click on Save.
The device will reboot with a name reflecting your template name and Module 0 selected which has your new template stored.
If your device was previously configured you will have to manually change to Module 0 in *Configuration -> Configure Module*.
"},{"location":"Templates/#commands","title":"Commands","text":"A user provided template can be stored in Tasmota using the Template command. It has the following parameters.
Parameter Description 0 Create template from active module 1..71 Create template from a supported module { ... } Store template written in a JSON string 255 Merge configured template and current module Template {\"NAME\":\"Example Template\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45} stores a complete template based on the Generic module
Template {\"NAME\":\"AnotherModuleName\"} updates the name of a stored template
Template {\"FLAG\":0} changes FLAG value
Template {\"BASE\":18} updates the base of a stored template to Generic
Template {\"CMND\":\"LedTable 1\"} adds LedTable 1 command to the stored template
After setting a template in command line it is necessary to issue Module 0 command if the device doesn't reboot on its own.
"},{"location":"Templates/#merge-template-with-module","title":"Merge Template with Module","text":"You can set up your device in module *Configuration -> Configure Module* and use command Template 255 to merge the settings of the Module with current template into a new Template named \"Merged\".
"},{"location":"Templates/#anatomy-of-a-template","title":"Anatomy of a Template","text":"Let's look again at our example template:
{\"NAME\":\"Example Template\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45}\n
The four properties with UPPERCASE property names have the following functionality:
Property name Property value description NAME Up to 60 characters for the Module name GPIO Numbers from 0 to 65535 representing GPIO0 to GPIO5, GPIO09, GPIO10 and GPIO12 to GPIO16 and GPIO17 for A0 pin for ESP8266. ESP32 has more configurable GPIO's FLAG *Deprecated Replaced with GPIO17. 8 bit mask flag register. BASE Module number of a hard-coded device to be used when device specific functionality is needed CMND (Optional) Commands executed after activating the template"},{"location":"Templates/#gpio","title":"GPIO","text":""},{"location":"Templates/#gpio-order","title":"GPIO order","text":"GPIO# |00| 01|02| 03|04| 05| 09| 10| 12| 13| 14| 15| 16| 17 \nCODE [416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0] \n
"},{"location":"Templates/#gpio-functionality","title":"GPIO functionality","text":"The GPIO functionality numbers are the same as shown by command GPIOs. In addition code 1 is added to select a GPIO as user configurable via the GUI Configure Module menu.
Example
In our example the GPIO 12 data element is 32 which corresponds to the Button1 component, according to the components table. If you change that template element to 160 it would then be assigned as a Switch1 component instead.
"},{"location":"Templates/#components","title":"Components","text":"See Components for a complete list or use command Gpios 255 in console.
"},{"location":"Templates/#flag","title":"FLAG","text":"Before Tasmota 9.1 used to configure the ADC type. In new templates this should be set to 0 and the analog pin should be configured on GPIO17
FLAG Feature description 0 No features 1 Analog value 2 Temperature 3 Light 4 Button 5 Buttoni 15 User configured (same as User)"},{"location":"Templates/#base","title":"BASE","text":"BASE is the starting module setup for the custom template. Some modules include special programming. If your device is similar to an existing built-in module it is best to use that as a starting point. When you're not sure which BASE module is suitable for your device use the Generic (18) module. A list of hard-coded devices can be found in Modules.
Example
In the RGB Smart Plug template we used the BlitzWolf SHP (45) module as BASE since the power monitoring circuitry is identical but GPIO00 and GPIO02 were changed and an unused GPIO04 was added to enable the RGB LED function. Using that specific module we took advantage of that module's calibrated power monitoring special programming which the Generic (18) module does not use.
"},{"location":"Templates/#cmnd","title":"CMND","text":"CMND is an optional field in the template JSON string. It is used to embed commands for configuring the device instead of needing to type them in console. Multiple commands are separated with |.
\"CMND\":\"<any template related command>|<any template related command>|...\"
Commands will only be executed if the template is enabled (device module is set to 0), either before the template is loaded, when the activate box in the UI is selected or if the module 0 command is included in the CMND string itself.
Disable LED gamma correction and remap RGB channels
{\"NAME\":\"Example\",\"GPIO\":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],\"FLAG\":0,\"BASE\":45,\"CMND\":\"LedTable 1|ChannelRemap 36\"}\n
Total size of the template string should not exceed 500 chars.
"},{"location":"Thermal-considerations/","title":"Thermal considerations","text":"Even though LEDs consume far less energy than incandescent bulbs, these devices contain more complex circuitries and sometimes they still produce more heat than they can handle. The produced heat is proportional to the LED intensities, and if it builds up faster than how it dissipates from the chassis, then the temperature will rise.
The circuitries usually (but not necessarily) contain some last-resort countermeasure that shuts down the device when it is critically overheated, but it shouldn't be relied upon.
When testing the device for the first time, especially at higher light intensities, monitor its temperature for some time, like for at least half an hour, and if it rises rapidly, then please consider:
- Reducing the overall brightness
- Using only one of the light sources (i.e. either the color LEDs, or the high-power white ones)
For such a test use an electrically safe lamp in which you can access the bulb, and which you can easily disconnect from the mains anytime. For measuring the temperature the best tool is an IR thermometer: aim it at the heatsink part of the chassis from a direction perpendicular to it, from such a distance that its cone of sensitivity is fully on the chassis. If you choose to test the temperature by hand, then be prepared that it may be hot, so approach it slowly, and if you already feel its heat, then don't touch it.
During this check please also consider that a bulb standing on your desk in a test socket has considerably better cooling than one in a closed armature right below your ceiling, so try to 'model' the operating conditions in which you plan to use the device.
If you have found a solution that keeps the temperature stable, don't forget to configure a limit in your home automation system so you (or anyone else) won't accidentally set the device to overheating when it'll be already installed.
Some of the devices' original firmwares do contain such software throttling, but as the thermal behaviour differs from one model to another, there is no generic way to apply the right amount of throttling that would be both required and enough for everyone, so \"your mileage may vary\".
"},{"location":"Thermal-considerations/#technical-background","title":"Technical background","text":"Light bulb circuitries consist of 3 main stages:
- A small power supply unit that converts the 230V or 110V mains to approx. 20V for the LEDs and 3.3V for the controller. This is a small switching-mode power supply, but usually of a parsimonius design, so it's usually barely adequate for the average power requirement, and sometimes not enough for the maximum.
The main problem is not the transformer, but the voltage regulators: they produce heat proportionally to the current that's drawn through them, and they aren't connected to the heatsink, so all their heat goes just into the air within the bulb.
-
The controller module, usually a SoC that contains the CPU, memory, flash and wifi. It is a logic circuit, its heat production is negligible compared to the other stages.
-
The LED circuitry, meaning the LEDs themselves and their driver chips, usually on a separate board. They produce a lot of heat, but they are always connected to the chassis via either thermal grease or thermally conductive glue.
So the problems are: - Voltage regulators produce heat proportional to light intensity - Their thermal coupling to the chassis is terrible: via a huge air gap - The chassis is not an effective heatsink (for aesthetic reasons it can't be) - The overall system is designed for the average conditions and not for the maximum.
Thus our goal is to limit the power consumption to such a level that the heat produced can be dissipated by the chassis heatsink, and the way to achieve this is throttling down the light intensity and/or limiting the switched-on time.
"},{"location":"Thermal-considerations/#measured-values","title":"Measured values","text":""},{"location":"Thermal-considerations/#syf05-fcmilasunyesmart","title":"SYF05 (Fcmila/Sunyesmart)","text":" - At start: 23\u00b0C
- After 10 minutes: 40\u00b0C (warm)
- After 20 minutes: 48\u00b0C (hot)
- After 30 minutes: 53\u00b0C (barely touchable)
- After 40 minutes: 55\u00b0C
At this point the thermal protection has shut the device down, and the local temperatures were: - Chassis: 55\u00b0C - RGB LED driver chip: 73\u00b0C - White LED driver chip: 76\u00b0C - Controller module: 76\u00b0C - Transformer: 85\u00b0C - Area around the voltage regulator: 91\u00b0C
"},{"location":"Thermal-considerations/#sonoff-b1","title":"Sonoff B1","text":" - At start: 26\u00b0C
- After 10 minutes: 33\u00b0C
- After 20 minutes: 40\u00b0C
- After 30 minutes: 44\u00b0C
- After 40 minutes: 47\u00b0C
- After 50 minutes: 48\u00b0C
- After 1 hour: 50\u00b0C
The bulb was operational at this point, but I considered this temperature too high for sustained use.
"},{"location":"Thermostat/","title":"Thermostat","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_THERMOSTAT // Add support for Thermostat\n#define THERMOSTAT_CONTROLLER_OUTPUTS 1 // Number of outputs to be controlled independently\n#define THERMOSTAT_SENSOR_NAME \"DS18B20\" // Name of the local sensor to be used\n#define THERMOSTAT_SENSOR_NUMBER 1 // Number of local sensors to be used\n#define THERMOSTAT_RELAY_NUMBER 1 // Default output relay number for the first controller (+i for following ones)\n#define THERMOSTAT_SWITCH_NUMBER 1 // Default input switch number for the first controller (+i for following ones)\n#define THERMOSTAT_TIME_ALLOW_RAMPUP 300 // Default time after last target update to allow ramp-up controller phase in minutes\n#define THERMOSTAT_TIME_RAMPUP_MAX 960 // Default time maximum ramp-up controller duration in minutes\n#define THERMOSTAT_TIME_RAMPUP_CYCLE 30 // Default time ramp-up cycle in minutes\n#define THERMOSTAT_TIME_SENS_LOST 30 // Maximum time w/o sensor update to set it as lost in minutes\n#define THERMOSTAT_TEMP_SENS_NUMBER 1 // Default temperature sensor number\n#define THERMOSTAT_TIME_MANUAL_TO_AUTO 60 // Default time without input switch active to change from manual to automatic in minutes\n#define THERMOSTAT_TIME_RESET 12000 // Default reset time of the PI controller in seconds\n#define THERMOSTAT_TIME_PI_CYCLE 30 // Default cycle time for the thermostat controller in minutes\n#define THERMOSTAT_TIME_MAX_ACTION 20 // Default maximum thermostat time per cycle in minutes\n#define THERMOSTAT_TIME_MIN_ACTION 4 // Default minimum thermostat time per cycle in minutes\n#define THERMOSTAT_TIME_MIN_TURNOFF_ACTION 3 // Default minimum turnoff time in minutes, below it the thermostat will be held on\n#define THERMOSTAT_PROP_BAND 4 // Default proportional band of the PI controller in degrees celsius\n#define THERMOSTAT_TEMP_RESET_ANTI_WINDUP 8 // Default range where reset antiwindup is disabled, in tenths of degrees celsius\n#define THERMOSTAT_TEMP_HYSTERESIS 1 // Default range hysteresis for temperature PI controller, in tenths of degrees celsius\n#define THERMOSTAT_TEMP_FROST_PROTECT 40 // Default minimum temperature for frost protection, in tenths of degrees celsius\n#define THERMOSTAT_TEMP_RAMPUP_DELTA_IN 4 // Default minimum delta temperature to target to get into rampup mode, in tenths of degrees celsius\n#define THERMOSTAT_TEMP_RAMPUP_DELTA_OUT 2 // Default minimum delta temperature to target to get out of the rampup mode, in tenths of degrees celsius\n#define THERMOSTAT_TEMP_PI_RAMPUP_ACC_E 200 // Default accumulated error when switching from ramp-up controller to PI in hundredths of degrees celsius\n#define THERMOSTAT_TIME_OUTPUT_DELAY 180 // Default output delay between state change and real actuation event (f.i. valve open/closed)\n#define THERMOSTAT_TEMP_INIT 180 // Default init target temperature for the thermostat controller\n#define THERMOSTAT_TIME_MAX_OUTPUT_INCONSIST 3 // Default maximum time where the input and the output shall differ (for diagnostic) in minutes\n#define THERMOSTAT_TIME_MAX_AUTOTUNE 21600 // Maximum time for the PI autotune function to complete in seconds\n#define THERMOSTAT_DUTYCYCLE_AUTOTUNE 35 // Default duty cycle (in % over PI cycle time) for the step response of the autotune PI function\n#define THERMOSTAT_PEAKNUMBER_AUTOTUNE 8 // Default number of peak temperatures (max or min) to be used for the autotune PI function\n#define THERMOSTAT_TEMP_BAND_NO_PEAK_DET 1 // Default temperature band in thenths of degrees celsius within no peak will be detected\n#define THERMOSTAT_TIME_STD_DEV_PEAK_DET_OK 10 // Default standard deviation in minutes of the oscillation periods within the peak detection is successful \n
Control over heating and cooling as a true HVAC unit
Thermostat driver allows a Tasmota device, provided it receives the temperature input via MQTT or a locally connected sensor, to follow control heating/cooling strategies to reach the desired setpoint. The thermostat offers similar functions as feature rich commercial ones as the models found below:
"},{"location":"Thermostat/#typical-setup-heating-floor-system","title":"Typical setup: Heating floor system","text":"A typical setup for heating room systems can be found in the picture below. A conventional room thermostat is connected to a heating floor valve actuator, both running at AC voltage (f.e. 220V). The thermostat is connected to neutral as well as to the phase, the actuator to the same neutral connection of the thermostat and to its actuation signal. The actuation signal will switch between the neutral voltage (actuation Off) and the phase voltage (actuation On).
The conventional room thermostats offer nowadays either 2 point control with hysteresis or a more advanced PI (Proportional-Integral) control. The result of the PI control is typically transformed into a PWM signal with a pre-defined period and a variable duty cycle.
"},{"location":"Thermostat/#use-of-tasmota-switch-to-bypass-an-existing-wall-thermostat","title":"Use of tasmota switch to bypass an existing wall thermostat","text":"A tasmota switch can be installed in a way that it bypasses the existing wall thermostat. The advantage of this setup is that the thermostat driver offers the possibility to follow the output of the existing wall thermostat or acting autonomously. This setup allows a seamless integration with existing wall thermostats and gives the user the freedom to still use them.
Below you can find an example of a Shelly switch bypassing a wall thermostat:
"},{"location":"Thermostat/#configuration-for-standalone-application-or-bypass-of-existing-wall-thermostat","title":"Configuration for standalone application or bypass of existing wall thermostat","text":"The driver by default does not consider the input switch states even if available and it's therefore suitable for standalone use. If the application requires to follow the command of the input once active (see bypass setup explained in previous section). This bypass function is specially useful to allow the user to use the device bypassed, in case of a wall thermostat, to allow this thermostat to be used if desired. To enable this bypass function, the following command is to be sent to the tasmota device:
cmnd/Tasmota_Name/INPUTSWITCHUSE 1\n
Note
Some devices (such as the Sonoff 4CH Pro R2) even if having input buttons to manually switch the state of the output, report always its inputs in active state no matter if the button is pressed or not. For these devices the parameter above needs to be set to 0, otherwise the thermostat driver will activate the output continuously and stay permanently in manual mode.
Once active, the thermostat, in case of its input being active, will switch to manual mode and set as output the same state of its input. The thermostat will switch back from manual to automatic mode after a defined time where the input is inactive. The following parameter can be set to modify the time window in minutes to switch back to automatic in case the input is inactive:
cmnd/Tasmota_Name/TIMEMANUALTOAUTOSET 60\n
The default value for the time window to switch from manual to automatic is 60 minutes.
"},{"location":"Thermostat/#temperature-input-setpoint","title":"Temperature input / setpoint","text":""},{"location":"Thermostat/#local-temperature-sensor","title":"Local temperature sensor","text":"The tasmota driver can receive the temperature either via the related MQTT command or via a local temperature sensor (see example of a DS18B20 temperature sensor and a shelly temperature sensor addon below).
The default temperature input is MQTT. The following command can be used to select the local sensor as default input:
cmnd/Tasmota_Name/SENSORINPUTSET 1\n
Note
The default local temperature sensor is a DS18B20. In case a different Tasmota supported sensor is used, the following define in my_user_config.h is to be changed (or redefined in user_config_override.h) and a user specific tasmota software needs to be compiled:
#define THERMOSTAT_SENSOR_NAME \"DS18B20\" // Name of the local sensor to be used\n
"},{"location":"Thermostat/#mqtt-temperature-value-and-setpoint","title":"MQTT temperature value and setpoint","text":"The following commands can be used to provide the driver with the temperature value of the room and the desired setpoint:
cmnd/Tasmota_Name/TEMPTARGETSET 22.5\n
cmnd/Tasmota_Name/TEMPMEASUREDSET 21.8\n
Examples for room temperature of 21.8\u00b0C and temperature setpoint of 22.5\u00b0C
There are several ways to send the MQTT room temperature. For the development and testing of this driver, a Raspberry Pi with Domoticz and a Z-Wave stick has been used to gather all room temperatures from Z-Wave sensors and send them to the respective Tasmota room thermostats.
"},{"location":"Thermostat/#customization-of-the-controller-for-best-results","title":"Customization of the controller for best results","text":"The thermostat controller includes a default parameter set that targets a typical floor heating application for mid-sized rooms (< 20m2) with one heating circuit. The controller is however highly configurable via MQTT. The following sections will guide the user to adapt the main parameters to improve the performance of the thermostat controller via customization.
"},{"location":"Thermostat/#enable-the-thermostat-driver","title":"Enable the thermostat driver","text":"The thermostat driver is by default disabled. To enable it the following command can be used:
cmnd/Tasmota_Name/THERMOSTATMODESET 1\n
"},{"location":"Thermostat/#set-the-controller-in-degrees-celsius-or-fahrenheit","title":"Set the controller in degrees Celsius or Fahrenheit","text":"The default temperature format is degrees Celsius. The format can be easily switched to degrees Fahrenheit via MQTT command, see below:
cmnd/Tasmota_Name/TEMPFORMATSET 1\n
"},{"location":"Thermostat/#set-the-control-strategy","title":"Set the control strategy","text":"The control strategy by default is a Hybrid one. The hybrid control strategy mixes a so called \"Ramp-Up\" strategy (invention during the development of this driver, initially as a LUA script and ported to Tasmota later) and a PI one. The \"Ramp-Up\" strategy is typically used to reach as fast as possible the setpoint for big deltas between desired temperature and setpoint, the PI on the other hand for most part of the normal thermostat operation.
The control strategy can be however modified, if the Hybrid one is not desired, the PI or \"Ramp-Up\" mode, can be forced. For that purpose the following command can be used:
cmnd/Tasmota_Name/CONTROLLERMODESET 1\n
The value 1 forces the PI operation and the value 2 the \"Ramp-Up\" one.
"},{"location":"Thermostat/#pi-controller-main-parameters","title":"PI controller main parameters","text":""},{"location":"Thermostat/#cycle-time","title":"Cycle time","text":"Depending on the heating system, the cycle time (PMW period) can be adapted. Very slow systems (high time constants) such as heating floor systems might need higher values (default value is 30 minutes), faster systems might need smaller cycle times. Below the command to adapt the cycle time can be found:
cmnd/Tasmota_Name/TIMEPICYCLESET 30\n
"},{"location":"Thermostat/#proportional-band","title":"Proportional Band","text":"Depending on the dimensioning of your heating system, the proportional band of the controller might be increased (if it takes too long to reach setpoint) or reduced (very high overshoot). The default proportional gain is 4, which means that the duty cycle due to the proportional part of the PI controller will be 100% for temperature deltas between setpoint and room temperature equal or bigger than 4\u00b0C. Below the command to adapt the proportional band can be found:
cmnd/Tasmota_Name/PROPBANDSET 1\n
Note
With the command above, the PI controller will output a proportional time equivalent to 100% of the duty cycle for delta temperatures between setpoint and room temp. above 1\u00b0C (f.e. for big rooms with weak dimensioned heating circuit).
"},{"location":"Thermostat/#reset-time","title":"Reset Time","text":"The reset time is the time the PI controller takes to overcome steady-state errors. The default value for the reset time is 1800 seconds. This value can be for instance increased in case a stronger integral reaction of the controller is desired. Below the command to adapt the proportional band can be found:
cmnd/Tasmota_Name/TIMERESETSET 1800\n
"},{"location":"Thermostat/#temperature-for-the-anti-windup-reset","title":"Temperature for the anti-windup reset","text":"To avoid the accumulated error and therefore integral component of the PI controller to grow too much and produce a high overshoot, a temperature delta can be defined within the integrator will work. Outside this range the accumulated error and integral part will be set to 0. The default value for the integrator to work is 0.8\u00b0C. Below the command to adapt the anti-windup temperature can be found:
cmnd/Tasmota_Name/TEMPANTIWINDUPRESETSET 0.8\n
"},{"location":"Thermostat/#temperature-hysteresis","title":"Temperature hysteresis","text":"A temperature hysteresis can be set to avoid any PI controller actions within a certain value around the setpoint. The default value for the hysteresis is 0.1\u00b0C. In well configured controller this value should be as low as possible to avoid unwanted temperature oscillations which reduce efficiency and therefore increase costs. Below the command to adapt the anti-windup temperature can be found:
cmnd/Tasmota_Name/TEMPHYSTSET 0.1\n
"},{"location":"Thermostat/#maximum-action-of-the-controller","title":"Maximum action of the controller","text":"The maximum On time (Duty Cycle) in minutes within a cycle can be set by this parameter. The default value is 20 minutes. This represents for the default cycle time of 30 minutes 2 thirds of the complete cycle. In case the controller takes too long to reach the setpoint, this value can be increased to values closer to the cycle time. Below the command to adapt the maximum action time can be found:
cmnd/Tasmota_Name/TIMEMAXACTIONSET 20\n
"},{"location":"Thermostat/#minimum-action-of-the-controller","title":"Minimum action of the controller","text":"The minimum On time (Duty Cycle) in minutes within a cycle can be set by this parameter. The default value is 4 minutes. Below the command to adapt the minimum action time can be found:
cmnd/Tasmota_Name/TIMEMINACTIONSET 4\n
It is very important to adapt this value to your heating system to obtain accurate temperature control
If the value is very low, in case of floor heating systems for instance, the heating actuators might not have enough time to open the valves and the temperature will drop (depending on the actuator open/close time could take from 1 to 3 minutes) if it is too high, there will be unwanted oscillations around the setpoint. One way to configure this value in heating mode is to manually tune it in worst case conditions (highest typically desired room temperature and lower winter temperature outside) checking that the proportional action generated by the controller is sufficient to raise slightly the temperature. If the temperature still goes down after the pulse plus delay time of the system and rises just once the accumulated error triggers integral actions then the value set is too low.
"},{"location":"Thermostat/#ramp-up-controller-main-parameters","title":"Ramp-Up controller main parameters","text":""},{"location":"Thermostat/#temperature-delta-to-get-into-ramp-up-mode","title":"Temperature delta to get into \"Ramp-Up\" mode","text":"When the controller is configured in Hybrid mode (default), the control strategy will be a mix between \"Ramp-Up\" (for big deltas between room temperature and setpoint) and PI (around the setpoint). The following parameter can be set to define the delta temperature (between measured and setpoint) above which the \"Ramp-Up\" controller will be active:
cmnd/Tasmota_Name/TEMPRUPDELTINSET 0.3\n
The default value is 0.4\u00b0C.
"},{"location":"Thermostat/#time-passed-after-latest-setpoint-change-to-get-into-ramp-up-mode","title":"Time passed after latest setpoint change to get into \"Ramp-Up\" mode","text":"When the controller is configured in Hybrid mode (default), the activation of the \"Ramp-Up\" mode will not just depend on the defined temperature delta between measured and setpoint, but as well on the time in minutes passed since the last setpoint change occurred. This strategy matches the purpose of the \"Ramp-Up\" controller, which was developed to reach the desired temperature as fast as possible in very specific scenarios, f.e. after a night keeping the room temperature low. In hybrid mode, the controller active most part of the time should be the PI one. The following parameter can be used to define the time to allow switching to \"Ramp-Up\" in minutes.
cmnd/Tasmota_Name/TIMEALLOWRAMPUPSET 300\n
The default value is 300 minutes.
"},{"location":"Thermostat/#cycle-time_1","title":"Cycle time","text":"Depending on the heating system, the cycle time (PMW period) can be adapted. Very slow systems (high time constants) such as heating floor systems might need higher values (default value is 30 minutes), faster systems might need smaller cycle times. The following parameter can be used to define the cycle time in minutes:
cmnd/Tasmota_Name/TIMERAMPUPCYCLESET 45\n
"},{"location":"Thermostat/#maximum-ramp-up-time","title":"Maximum Ramp-Up time","text":"The maximum time the ramp-up phase of the controller shall be active can be configured (default value is 960 minutes). The following parameter can be used to define the ramp-up time in minutes:
cmnd/Tasmota_Name/TIMERAMPUPMAXSET 180\n
"},{"location":"Thermostat/#thermostat-persistent-storage-for-configuration","title":"Thermostat persistent storage for configuration","text":"The thermostat driver stores all configured parameters over MQTT exclusively in RAM, it does not use flash due to the amount of the parameters. This means that at every restart the default parameters will be set again. To avoid this behavior rules can be set-up to reconfigure desired parameters at every restart. See below an example:
ON Power1#boot DO Backlog sensorinputset 1;controllermodeset 2;thermostatmodeset 1;temptargetset %mem1% ENDON\nON mqtt#connected DO Publish2 stat/TestTopic/targetTempValue {\"Temp\":%mem1%} ENDON\nON mem1#state DO Backlog temptargetset %value%;Publish2 stat/TestTopic/targetTempValue {\"Temp\":%mem1%} ENDON\n
"},{"location":"Thermostat/#detecting-an-opened-window-by-temperature-drop","title":"Detecting an opened window by temperature drop","text":"When opening windows, temperature will drop significantly faster than is normal. During that period, heating is usually not desired. Following rules will detect a .3C drop in 1min and send the thermostat into a 15min timeout. Replace HTU21 with your sensor's name, if your Teleperiod is < 1min, consider using Tele-HTU21#Temperature.
ON Event#windowstop DO Backlog EnableOutputSet 0; Power 0; RuleTimer1 900 ENDON\nON Rules#Timer=1 DO EnableOutputSet 1 ENDON\nON HTU21#Temperature DO Var1 %value% ENDON\nON Time#Minute DO Backlog Var3 %Var2%; Sub3 .3; Var2 %Var1% ENDON\nON Var2#State<=%Var3% DO Event windowstop ENDON\n
"},{"location":"Thermostat/#advanced-features","title":"Advanced features","text":""},{"location":"Thermostat/#multi-controller","title":"Multi-controller","text":"The tasmota driver can be compiled to be used in devices with more than one output, allowing independent controllers for each one of the outputs. This feature has been successfully tested with a Sonoff 4CH PRO R2.
To increase the number of controller outputs, modify the value of the thermostat controller outputs in my_user_config.h or redefine it in user_config_override.h and compile a customized tasmota software.
#define THERMOSTAT_CONTROLLER_OUTPUTS 1 // Number of outputs to be controlled independently\n
"},{"location":"Thermostat/#alternative-outputs-pwm-duty-cycle","title":"Alternative outputs: PWM duty cycle","text":"The driver provides the possibility to read the duty cycle in % (0-100) of the actuated relay. Below the command to read the duty cycle can be found:
cmnd/Tasmota_Name/CTRDUTYCYCLEREAD\n
The physical switch of the output can as well be disabled via command. Below the command to disable it can be found:
cmnd/Tasmota_Name/ENABLEOUTPUTSET 0\n
"},{"location":"Thermostat/#future-improvements","title":"Future improvements","text":""},{"location":"Thermostat/#cooling","title":"Cooling","text":"The controller offers the possibility to switch from heating to cooling. Due to lack of cooling setup at the time of the development of the driver, this feature has however not been properly tested. Testers for cooling are therefore welcomed.
The following MQTT command can be used to switch from heating (default) to cooling:
cmnd/Tasmota_Name/CLIMATEMODESET 1\n
"},{"location":"Thermostat/#self-learning-process-of-the-ramp-up-controller-to-reduce-overshoot","title":"Self learning process of the \"Ramp-Up\" controller to reduce overshoot","text":"The \"Ramp-Up\" controller evaluates the time constant of the system and predicts when to switch off the actuator to reach the desired temperature as fast as possible. This controller offers the best speed to reach the Setpoint. This controller will be improved by a learning process to evaluate how accurate the target value has been reached and therefore minimize gradually the overshoot. This feature will improve the behavior of the current controller which depending on the application and thermal capacity of the system might produce some overshoot. By default the controller set is the Hybrid one, enabling \"Ramp-Up\" for big temperature deltas between Setpoint and measured temperature and PI for smaller ones. If you are not satisfied with the performance of this controller in your system, you can disable it by MQTT and force the use of the PI controller exclusively (see Controller configuration section above).
"},{"location":"Thermostat/#pi-autotune","title":"PI Autotune","text":"A PI autotune feature following the Zigler-Nichols closed loop algorithm has been implemented. This feature is untested and will be further developed soon. To enable it for testing purposes add the following define in user_config_override.h and compile a customized tasmota software.
#define USE_PI_AUTOTUNING // (Ziegler-Nichols closed loop method)\n
"},{"location":"Thermostat/#example","title":"Example","text":"The following chart shows the thermostat behavior in a forced air heated house:
The red shaded areas are where the thermostat commanded heat and the green line is the temperature. The temperature setpoint is 18 C at night and is then increased to 22.5 in the morning. This step demonstrates the ramp part of the hybrid control algorithm of the thermostat. Once the temperature is near the set point the thermostat switches to he PI algorithm. In the evenings the temperature is increased to 23.5 C.
"},{"location":"Time-Proportioned-Output-support/","title":"Time Proportioned Output support","text":"This extension adds a Time Proportioned Digital Output feature into the Tasmota software.
The relay output on a Sonoff device provides (obviously) just on/off control. Often it is desirable to be able to get a value between off and on, for example 25% power. The conventional way to achieve this with devices such as electrical heaters or hot water radiators is to switch the device on for a period and then off for a period. This extension allows a required power value between 0 and 1 to be specified via MQTT and the code will automatically cycle the relay on/off to achieve this power. The s/w is configured with a Cycle Time that specifies the period. So for example if a power value of 0.25 is specified with a cycle time of 12 minutes then the relay will be on for 3 minutes and off for 9 minutes every 12 minute period.
The s/w includes a safety mechanism where the maximum time expected between MQTT power updates is specified. If this time is exceeded with no value being received then the power will revert to a specified fallback value.
Instructions for setting it up and using it are in xdrv_48_timeprop.ino. The feature adds about 1.2k to the compiled code.
Currently all configuration parameters must be setup at build time. If anyone wanted to add these to the MQTT and/or web interfaces a PR would be gratefully received.
"},{"location":"Timers/","title":"Timers","text":"Timers allow you to automate your device based on time triggers
To control a device locally 16 timers are programmable. They can be configured with the Timer<x> command followed by a JSON payload with optional parameters. For example:
Timer 1 will ENABLE output of POWER1 at exactly 2:23 every Tue/Wed and Sat
Timer1 {\"Enable\":1,\"Time\":\"02:23\",\"Window\":0,\"Days\":\"--TW--S\",\"Repeat\":1,\"Output\":1,\"Action\":1}\n
Timer 4 will TOGGLE output of POWER2 within a 30 minute window centered around 16:23 each Sunday, Monday, Thursday and Friday and will disable (disarm) after executing.
Timer4 {\"Enable\":1,\"Time\":\"16:23\",\"Window\":15,\"Days\":\"SM00TF0\",\"Repeat\":0,\"Output\":2,\"Action\":2}\n
When Mode 1 or Mode 2 is used, Latitude and Longitude are required. In that case the Time value is always used as an offset from sunrise or sunset, so make sure to set it to 00:00 if no offset is wanted. Timer 1 will ENABLE output of POWER1 2 hours and 23 minutes before sunset every day of the week.
Timer1 {\"Enable\":1,\"Mode\":2,\"Time\":\"-2:23\",\"Window\":0,\"Days\":\"11TW11S\",\"Repeat\":1,\"Output\":1,\"Action\":1}\n
"},{"location":"Timers/#commands","title":"Commands","text":"Command Parameters Latitude <value> = set latitude Longitude <value> = set longitude Sunrise Sunrise/Sunset type0 = Normal (default)1 = Civil2 = Nautical3 = Astronomicalintroduced in version 12.1.1.5 Timers Timers control0 = disable all timers\u2003 \u00bb v6.2.01 = enable all timers2 = toggle all timers Timer<x> Parameters for Timer<x> where x = 1..160 = clear parameters for Timer<x>\u2003 \u00bb v6.2.01..16 = copy Timer<y> parameters to Timer<x>{ \"name\":value ; .. } = set all or individual parameters using JSON payload with names and values of data pairs from the table below"},{"location":"Timers/#json-payload-anatomy","title":"JSON Payload Anatomy","text":"JSON Name JSON Value Enable 0 = disarm or disable timer1 = arm or enable timer Mode 0 = use clock time1 = Use local sunrise time using Longitude, Latitude and Time offset2 = use local sunset time using Longitude, Latitude and Time offset Time hh:mm = set time in hours 0 .. 23 and minutes 0 .. 59-hh:mm = set time in offset hours -11 .. 12 and minutes 0 .. 59 (used with Mode 1 and Mode 2) Window 0..15 = add or subtract a random number of minutes to Time Days SMTWTFS = set day of weeks mask where 0 or - = OFF and any different character = ON Repeat 0 = allow timer only once1 = repeat timer execution Output 1..16 = select an output to be used if no rule is enabled Action 0 = turn output OFF 1 = turn output ON2 = TOGGLE output3 = RULE/BLINKIf the Tasmota Rules feature has been activated by compiling the code (activated by default in all pre-compiled Tasmota binaries), a rule with Clock#Timer=<timer> will be triggered if written and turned on by the user.If Rules are not compiled, BLINK output using BlinkCount parameters."},{"location":"Timers/#sunrise","title":"Sunrise","text":"In order to set a timer to use the automatically calculated sunrise or sunset time, the latitude and longitude of the location as decimal degrees needs to be entered using the respective commands.
By default, Tasmota calculates the times of the actual sunrise and sunset. Starting with version 12.1.1.5, it is possible instead to use the beginning and ending times of civil, nautical or astronomical twilight. In particular, civil twilight is the period of time when the sun is below the horizon, but artificial lighting is not yet needed.
"},{"location":"Timezone-Table/","title":"Timezone Table","text":""},{"location":"Timezone-Table/#tasmota-timezone-table","title":"Tasmota Timezone Table","text":"Use this table to look up the correct Timezone, TimeStd, and TimeDst commands to configure a Tasmota device for your local timezone.
Timezone Commands Africa/Abidjan Timezone +0:00 Africa/Accra Timezone +0:00 Africa/Addis_Ababa Timezone +3:00 Africa/Algiers Timezone +1:00 Africa/Asmara Timezone +3:00 Africa/Asmera Timezone +3:00 Africa/Bamako Timezone +0:00 Africa/Bangui Timezone +1:00 Africa/Banjul Timezone +0:00 Africa/Bissau Timezone +0:00 Africa/Blantyre Timezone +2:00 Africa/Brazzaville Timezone +1:00 Africa/Bujumbura Timezone +2:00 Africa/Cairo Timezone +2:00 Africa/Casablanca Timezone +1:00 Africa/Ceuta Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Africa/Conakry Timezone +0:00 Africa/Dakar Timezone +0:00 Africa/Dar_es_Salaam Timezone +3:00 Africa/Djibouti Timezone +3:00 Africa/Douala Timezone +1:00 Africa/El_Aaiun Timezone +1:00 Africa/Freetown Timezone +0:00 Africa/Gaborone Timezone +2:00 Africa/Harare Timezone +2:00 Africa/Johannesburg Timezone +2:00 Africa/Juba Timezone +2:00 Africa/Kampala Timezone +3:00 Africa/Khartoum Timezone +2:00 Africa/Kigali Timezone +2:00 Africa/Kinshasa Timezone +1:00 Africa/Lagos Timezone +1:00 Africa/Libreville Timezone +1:00 Africa/Lome Timezone +0:00 Africa/Luanda Timezone +1:00 Africa/Lubumbashi Timezone +2:00 Africa/Lusaka Timezone +2:00 Africa/Malabo Timezone +1:00 Africa/Maputo Timezone +2:00 Africa/Maseru Timezone +2:00 Africa/Mbabane Timezone +2:00 Africa/Mogadishu Timezone +3:00 Africa/Monrovia Timezone +0:00 Africa/Nairobi Timezone +3:00 Africa/Ndjamena Timezone +1:00 Africa/Niamey Timezone +1:00 Africa/Nouakchott Timezone +0:00 Africa/Ouagadougou Timezone +0:00 Africa/Porto-Novo Timezone +1:00 Africa/Sao_Tome Timezone +0:00 Africa/Timbuktu Timezone +0:00 Africa/Tripoli Timezone +2:00 Africa/Tunis Timezone +1:00 Africa/Windhoek Timezone +2:00 America/Adak Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-600; TimeDst 0,2,3,1,2,-540 America/Anchorage Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/Anguilla Timezone -4:00 America/Antigua Timezone -4:00 America/Araguaina Timezone -3:00 America/Argentina/Buenos_Aires Timezone -3:00 America/Argentina/Catamarca Timezone -3:00 America/Argentina/ComodRivadavia Timezone -3:00 America/Argentina/Cordoba Timezone -3:00 America/Argentina/Jujuy Timezone -3:00 America/Argentina/La_Rioja Timezone -3:00 America/Argentina/Mendoza Timezone -3:00 America/Argentina/Rio_Gallegos Timezone -3:00 America/Argentina/Salta Timezone -3:00 America/Argentina/San_Juan Timezone -3:00 America/Argentina/San_Luis Timezone -3:00 America/Argentina/Tucuman Timezone -3:00 America/Argentina/Ushuaia Timezone -3:00 America/Aruba Timezone -4:00 America/Asuncion Backlog0 Timezone 99; TimeStd 1,4,3,1,0,-240; TimeDst 1,1,10,1,0,-180 America/Atikokan Timezone -5:00 America/Atka Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-600; TimeDst 0,2,3,1,2,-540 America/Bahia Timezone -3:00 America/Bahia_Banderas Timezone -6:00 America/Barbados Timezone -4:00 America/Belem Timezone -3:00 America/Belize Timezone -6:00 America/Blanc-Sablon Timezone -4:00 America/Boa_Vista Timezone -4:00 America/Bogota Timezone -5:00 America/Boise Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Buenos_Aires Timezone -3:00 America/Cambridge_Bay Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Campo_Grande Timezone -4:00 America/Cancun Timezone -5:00 America/Caracas Timezone -4:00 America/Catamarca Timezone -3:00 America/Cayenne Timezone -3:00 America/Cayman Timezone -5:00 America/Chicago Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Chihuahua Timezone -6:00 America/Ciudad_Juarez Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Coral_Harbour Timezone -5:00 America/Cordoba Timezone -3:00 America/Costa_Rica Timezone -6:00 America/Creston Timezone -7:00 America/Cuiaba Timezone -4:00 America/Curacao Timezone -4:00 America/Danmarkshavn Timezone +0:00 America/Dawson Timezone -7:00 America/Dawson_Creek Timezone -7:00 America/Denver Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Detroit Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Dominica Timezone -4:00 America/Edmonton Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Eirunepe Timezone -5:00 America/El_Salvador Timezone -6:00 America/Ensenada Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 America/Fort_Nelson Timezone -7:00 America/Fort_Wayne Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Fortaleza Timezone -3:00 America/Glace_Bay Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 America/Godthab Timezone -2:00 America/Goose_Bay Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 America/Grand_Turk Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Grenada Timezone -4:00 America/Guadeloupe Timezone -4:00 America/Guatemala Timezone -6:00 America/Guayaquil Timezone -5:00 America/Guyana Timezone -4:00 America/Halifax Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 America/Havana Backlog0 Timezone 99; TimeStd 0,1,11,1,1,-300; TimeDst 0,2,3,1,0,-240 America/Hermosillo Timezone -7:00 America/Indiana/Indianapolis Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indiana/Knox Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Indiana/Marengo Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indiana/Petersburg Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indiana/Tell_City Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Indiana/Vevay Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indiana/Vincennes Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indiana/Winamac Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Indianapolis Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Inuvik Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Iqaluit Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Jamaica Timezone -5:00 America/Jujuy Timezone -3:00 America/Juneau Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/Kentucky/Louisville Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Kentucky/Monticello Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Knox_IN Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Kralendijk Timezone -4:00 America/La_Paz Timezone -4:00 America/Lima Timezone -5:00 America/Los_Angeles Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 America/Louisville Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Lower_Princes Timezone -4:00 America/Maceio Timezone -3:00 America/Managua Timezone -6:00 America/Manaus Timezone -4:00 America/Marigot Timezone -4:00 America/Martinique Timezone -4:00 America/Matamoros Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Mazatlan Timezone -7:00 America/Mendoza Timezone -3:00 America/Menominee Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Merida Timezone -6:00 America/Metlakatla Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/Mexico_City Timezone -6:00 America/Miquelon Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-180; TimeDst 0,2,3,1,2,-120 America/Moncton Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 America/Monterrey Timezone -6:00 America/Montevideo Timezone -3:00 America/Montreal Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Montserrat Timezone -4:00 America/Nassau Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/New_York Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Nipigon Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Nome Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/Noronha Timezone -2:00 America/North_Dakota/Beulah Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/North_Dakota/Center Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/North_Dakota/New_Salem Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Nuuk Timezone -2:00 America/Ojinaga Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Panama Timezone -5:00 America/Pangnirtung Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Paramaribo Timezone -3:00 America/Phoenix Timezone -7:00 America/Port-au-Prince Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Port_of_Spain Timezone -4:00 America/Porto_Acre Timezone -5:00 America/Porto_Velho Timezone -4:00 America/Puerto_Rico Timezone -4:00 America/Punta_Arenas Timezone -3:00 America/Rainy_River Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Rankin_Inlet Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Recife Timezone -3:00 America/Regina Timezone -6:00 America/Resolute Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Rio_Branco Timezone -5:00 America/Rosario Timezone -3:00 America/Santa_Isabel Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 America/Santarem Timezone -3:00 America/Santiago This timezone uses a DST start/end rule that Tasmota does not support. America/Santo_Domingo Timezone -4:00 America/Sao_Paulo Timezone -3:00 America/Scoresbysund Backlog0 Timezone 99; TimeStd 0,0,10,1,1,-60; TimeDst 0,0,3,1,0,0 America/Shiprock Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 America/Sitka Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/St_Barthelemy Timezone -4:00 America/St_Johns Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-210.0; TimeDst 0,2,3,1,2,-150.0 America/St_Kitts Timezone -4:00 America/St_Lucia Timezone -4:00 America/St_Thomas Timezone -4:00 America/St_Vincent Timezone -4:00 America/Swift_Current Timezone -6:00 America/Tegucigalpa Timezone -6:00 America/Thule Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 America/Thunder_Bay Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Tijuana Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 America/Toronto Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 America/Tortola Timezone -4:00 America/Vancouver Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 America/Virgin Timezone -4:00 America/Whitehorse Timezone -7:00 America/Winnipeg Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 America/Yakutat Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 America/Yellowknife Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 Antarctica/Casey Timezone +11:00 Antarctica/Davis Timezone +7:00 Antarctica/DumontDUrville Timezone +10:00 Antarctica/Macquarie Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Antarctica/Mawson Timezone +5:00 Antarctica/McMurdo Backlog0 Timezone 99; TimeStd 1,1,4,1,3,720; TimeDst 1,0,9,1,2,780 Antarctica/Palmer Timezone -3:00 Antarctica/Rothera Timezone -3:00 Antarctica/South_Pole Backlog0 Timezone 99; TimeStd 1,1,4,1,3,720; TimeDst 1,0,9,1,2,780 Antarctica/Syowa Timezone +3:00 Antarctica/Troll Backlog0 Timezone 99; TimeStd 0,0,10,1,3,0; TimeDst 0,0,3,1,1,120 Antarctica/Vostok Timezone +6:00 Arctic/Longyearbyen Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Asia/Aden Timezone +3:00 Asia/Almaty Timezone +6:00 Asia/Amman Timezone +3:00 Asia/Anadyr Timezone +12:00 Asia/Aqtau Timezone +5:00 Asia/Aqtobe Timezone +5:00 Asia/Ashgabat Timezone +5:00 Asia/Ashkhabad Timezone +5:00 Asia/Atyrau Timezone +5:00 Asia/Baghdad Timezone +3:00 Asia/Bahrain Timezone +3:00 Asia/Baku Timezone +4:00 Asia/Bangkok Timezone +7:00 Asia/Barnaul Timezone +7:00 Asia/Beirut Backlog0 Timezone 99; TimeStd 0,0,10,1,0,120; TimeDst 0,0,3,1,0,180 Asia/Bishkek Timezone +6:00 Asia/Brunei Timezone +8:00 Asia/Calcutta Timezone +5:30 Asia/Chita Timezone +9:00 Asia/Choibalsan Timezone +8:00 Asia/Chongqing Timezone +8:00 Asia/Chungking Timezone +8:00 Asia/Colombo Timezone +5:30 Asia/Dacca Timezone +6:00 Asia/Damascus Timezone +3:00 Asia/Dhaka Timezone +6:00 Asia/Dili Timezone +9:00 Asia/Dubai Timezone +4:00 Asia/Dushanbe Timezone +5:00 Asia/Famagusta Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Asia/Gaza This timezone uses a DST start/end rule that Tasmota does not support. Asia/Harbin Timezone +8:00 Asia/Hebron This timezone uses a DST start/end rule that Tasmota does not support. Asia/Ho_Chi_Minh Timezone +7:00 Asia/Hong_Kong Timezone +8:00 Asia/Hovd Timezone +7:00 Asia/Irkutsk Timezone +8:00 Asia/Istanbul Timezone +3:00 Asia/Jakarta Timezone +7:00 Asia/Jayapura Timezone +9:00 Asia/Jerusalem This timezone uses a DST start/end rule that Tasmota does not support. Asia/Kabul Timezone +4:30 Asia/Kamchatka Timezone +12:00 Asia/Karachi Timezone +5:00 Asia/Kashgar Timezone +6:00 Asia/Kathmandu Timezone +5:45 Asia/Katmandu Timezone +5:45 Asia/Khandyga Timezone +9:00 Asia/Kolkata Timezone +5:30 Asia/Krasnoyarsk Timezone +7:00 Asia/Kuala_Lumpur Timezone +8:00 Asia/Kuching Timezone +8:00 Asia/Kuwait Timezone +3:00 Asia/Macao Timezone +8:00 Asia/Macau Timezone +8:00 Asia/Magadan Timezone +11:00 Asia/Makassar Timezone +8:00 Asia/Manila Timezone +8:00 Asia/Muscat Timezone +4:00 Asia/Nicosia Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Asia/Novokuznetsk Timezone +7:00 Asia/Novosibirsk Timezone +7:00 Asia/Omsk Timezone +6:00 Asia/Oral Timezone +5:00 Asia/Phnom_Penh Timezone +7:00 Asia/Pontianak Timezone +7:00 Asia/Pyongyang Timezone +9:00 Asia/Qatar Timezone +3:00 Asia/Qostanay Timezone +6:00 Asia/Qyzylorda Timezone +5:00 Asia/Rangoon Timezone +6:30 Asia/Riyadh Timezone +3:00 Asia/Saigon Timezone +7:00 Asia/Sakhalin Timezone +11:00 Asia/Samarkand Timezone +5:00 Asia/Seoul Timezone +9:00 Asia/Shanghai Timezone +8:00 Asia/Singapore Timezone +8:00 Asia/Srednekolymsk Timezone +11:00 Asia/Taipei Timezone +8:00 Asia/Tashkent Timezone +5:00 Asia/Tbilisi Timezone +4:00 Asia/Tehran Timezone +3:30 Asia/Tel_Aviv This timezone uses a DST start/end rule that Tasmota does not support. Asia/Thimbu Timezone +6:00 Asia/Thimphu Timezone +6:00 Asia/Tokyo Timezone +9:00 Asia/Tomsk Timezone +7:00 Asia/Ujung_Pandang Timezone +8:00 Asia/Ulaanbaatar Timezone +8:00 Asia/Ulan_Bator Timezone +8:00 Asia/Urumqi Timezone +6:00 Asia/Ust-Nera Timezone +10:00 Asia/Vientiane Timezone +7:00 Asia/Vladivostok Timezone +10:00 Asia/Yakutsk Timezone +9:00 Asia/Yangon Timezone +6:30 Asia/Yekaterinburg Timezone +5:00 Asia/Yerevan Timezone +4:00 Atlantic/Azores Backlog0 Timezone 99; TimeStd 0,0,10,1,1,-60; TimeDst 0,0,3,1,0,0 Atlantic/Bermuda Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 Atlantic/Canary Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Atlantic/Cape_Verde Timezone -1:00 Atlantic/Faeroe Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Atlantic/Faroe Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Atlantic/Jan_Mayen Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Atlantic/Madeira Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Atlantic/Reykjavik Timezone +0:00 Atlantic/South_Georgia Timezone -2:00 Atlantic/St_Helena Timezone +0:00 Atlantic/Stanley Timezone -3:00 Australia/ACT Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/Adelaide Backlog0 Timezone 99; TimeStd 1,1,4,1,3,570.0; TimeDst 1,1,10,1,2,630.0 Australia/Brisbane Timezone +10:00 Australia/Broken_Hill Backlog0 Timezone 99; TimeStd 1,1,4,1,3,570.0; TimeDst 1,1,10,1,2,630.0 Australia/Canberra Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/Currie Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/Darwin Timezone +9:30 Australia/Eucla Timezone +8:45 Australia/Hobart Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/LHI Backlog0 Timezone 99; TimeStd 1,1,4,1,2,630.0; TimeDst 1,1,10,1,2,660 Australia/Lindeman Timezone +10:00 Australia/Lord_Howe Backlog0 Timezone 99; TimeStd 1,1,4,1,2,630.0; TimeDst 1,1,10,1,2,660 Australia/Melbourne Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/NSW Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/North Timezone +9:30 Australia/Perth Timezone +8:00 Australia/Queensland Timezone +10:00 Australia/South Backlog0 Timezone 99; TimeStd 1,1,4,1,3,570.0; TimeDst 1,1,10,1,2,630.0 Australia/Sydney Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/Tasmania Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/Victoria Backlog0 Timezone 99; TimeStd 1,1,4,1,3,600; TimeDst 1,1,10,1,2,660 Australia/West Timezone +8:00 Australia/Yancowinna Backlog0 Timezone 99; TimeStd 1,1,4,1,3,570.0; TimeDst 1,1,10,1,2,630.0 Brazil/Acre Timezone -5:00 Brazil/DeNoronha Timezone -2:00 Brazil/East Timezone -3:00 Brazil/West Timezone -4:00 CET Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 CST6CDT Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 Canada/Atlantic Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-240; TimeDst 0,2,3,1,2,-180 Canada/Central Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 Canada/Eastern Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 Canada/Mountain Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 Canada/Newfoundland Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-210.0; TimeDst 0,2,3,1,2,-150.0 Canada/Pacific Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 Canada/Saskatchewan Timezone -6:00 Canada/Yukon Timezone -7:00 Chile/Continental This timezone uses a DST start/end rule that Tasmota does not support. Chile/EasterIsland Backlog0 Timezone 99; TimeStd 1,1,4,7,22,-360; TimeDst 1,1,9,7,22,-300 Cuba Backlog0 Timezone 99; TimeStd 0,1,11,1,1,-300; TimeDst 0,2,3,1,0,-240 EET Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 EST Timezone -5:00 EST5EDT Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 Egypt Timezone +2:00 Eire Backlog0 Timezone 99; TimeStd 1,0,3,1,1,60; TimeDst 1,0,10,1,2,0 Etc/GMT Timezone +0:00 Etc/GMT+0 Timezone +0:00 Etc/GMT+1 Timezone -1:00 Etc/GMT+10 Timezone -10:00 Etc/GMT+11 Timezone -11:00 Etc/GMT+12 Timezone -12:00 Etc/GMT+2 Timezone -2:00 Etc/GMT+3 Timezone -3:00 Etc/GMT+4 Timezone -4:00 Etc/GMT+5 Timezone -5:00 Etc/GMT+6 Timezone -6:00 Etc/GMT+7 Timezone -7:00 Etc/GMT+8 Timezone -8:00 Etc/GMT+9 Timezone -9:00 Etc/GMT-0 Timezone +0:00 Etc/GMT-1 Timezone +1:00 Etc/GMT-10 Timezone +10:00 Etc/GMT-11 Timezone +11:00 Etc/GMT-12 Timezone +12:00 Etc/GMT-13 Timezone +13:00 Etc/GMT-14 This timezone has a UTC offset outside the range Tasmota supports. Etc/GMT-2 Timezone +2:00 Etc/GMT-3 Timezone +3:00 Etc/GMT-4 Timezone +4:00 Etc/GMT-5 Timezone +5:00 Etc/GMT-6 Timezone +6:00 Etc/GMT-7 Timezone +7:00 Etc/GMT-8 Timezone +8:00 Etc/GMT-9 Timezone +9:00 Etc/GMT0 Timezone +0:00 Etc/Greenwich Timezone +0:00 Etc/UCT Timezone +0:00 Etc/UTC Timezone +0:00 Etc/Universal Timezone +0:00 Etc/Zulu Timezone +0:00 Europe/Amsterdam Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Andorra Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Astrakhan Timezone +4:00 Europe/Athens Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Belfast Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Belgrade Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Berlin Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Bratislava Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Brussels Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Bucharest Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Budapest Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Busingen Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Chisinau Backlog0 Timezone 99; TimeStd 0,0,10,1,3,120; TimeDst 0,0,3,1,2,180 Europe/Copenhagen Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Dublin Backlog0 Timezone 99; TimeStd 1,0,3,1,1,60; TimeDst 1,0,10,1,2,0 Europe/Gibraltar Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Guernsey Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Helsinki Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Isle_of_Man Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Istanbul Timezone +3:00 Europe/Jersey Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Kaliningrad Timezone +2:00 Europe/Kiev Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Kirov Timezone +3:00 Europe/Kyiv Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Lisbon Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Ljubljana Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/London Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Europe/Luxembourg Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Madrid Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Malta Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Mariehamn Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Minsk Timezone +3:00 Europe/Monaco Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Moscow Timezone +3:00 Europe/Nicosia Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Oslo Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Paris Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Podgorica Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Prague Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Riga Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Rome Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Samara Timezone +4:00 Europe/San_Marino Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Sarajevo Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Saratov Timezone +4:00 Europe/Simferopol Timezone +3:00 Europe/Skopje Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Sofia Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Stockholm Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Tallinn Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Tirane Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Tiraspol Backlog0 Timezone 99; TimeStd 0,0,10,1,3,120; TimeDst 0,0,3,1,2,180 Europe/Ulyanovsk Timezone +4:00 Europe/Uzhgorod Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Vaduz Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Vatican Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Vienna Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Vilnius Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Volgograd Timezone +3:00 Europe/Warsaw Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Zagreb Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Europe/Zaporozhye Backlog0 Timezone 99; TimeStd 0,0,10,1,4,120; TimeDst 0,0,3,1,3,180 Europe/Zurich Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Factory Timezone +0:00 GB Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 GB-Eire Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 GMT Timezone +0:00 GMT+0 Timezone +0:00 GMT-0 Timezone +0:00 GMT0 Timezone +0:00 Greenwich Timezone +0:00 HST Timezone -10:00 Hongkong Timezone +8:00 Iceland Timezone +0:00 Indian/Antananarivo Timezone +3:00 Indian/Chagos Timezone +6:00 Indian/Christmas Timezone +7:00 Indian/Cocos Timezone +6:30 Indian/Comoro Timezone +3:00 Indian/Kerguelen Timezone +5:00 Indian/Mahe Timezone +4:00 Indian/Maldives Timezone +5:00 Indian/Mauritius Timezone +4:00 Indian/Mayotte Timezone +3:00 Indian/Reunion Timezone +4:00 Iran Timezone +3:30 Israel This timezone uses a DST start/end rule that Tasmota does not support. Jamaica Timezone -5:00 Japan Timezone +9:00 Kwajalein Timezone +12:00 Libya Timezone +2:00 MET Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 MST Timezone -7:00 MST7MDT Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 Mexico/BajaNorte Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 Mexico/BajaSur Timezone -7:00 Mexico/General Timezone -6:00 NZ Backlog0 Timezone 99; TimeStd 1,1,4,1,3,720; TimeDst 1,0,9,1,2,780 NZ-CHAT This timezone has a UTC offset outside the range Tasmota supports. Navajo Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 PRC Timezone +8:00 PST8PDT Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 Pacific/Apia Timezone +13:00 Pacific/Auckland Backlog0 Timezone 99; TimeStd 1,1,4,1,3,720; TimeDst 1,0,9,1,2,780 Pacific/Bougainville Timezone +11:00 Pacific/Chatham This timezone has a UTC offset outside the range Tasmota supports. Pacific/Chuuk Timezone +10:00 Pacific/Easter Backlog0 Timezone 99; TimeStd 1,1,4,7,22,-360; TimeDst 1,1,9,7,22,-300 Pacific/Efate Timezone +11:00 Pacific/Enderbury Timezone +13:00 Pacific/Fakaofo Timezone +13:00 Pacific/Fiji Timezone +12:00 Pacific/Funafuti Timezone +12:00 Pacific/Galapagos Timezone -6:00 Pacific/Gambier Timezone -9:00 Pacific/Guadalcanal Timezone +11:00 Pacific/Guam Timezone +10:00 Pacific/Honolulu Timezone -10:00 Pacific/Johnston Timezone -10:00 Pacific/Kanton Timezone +13:00 Pacific/Kiritimati This timezone has a UTC offset outside the range Tasmota supports. Pacific/Kosrae Timezone +11:00 Pacific/Kwajalein Timezone +12:00 Pacific/Majuro Timezone +12:00 Pacific/Marquesas Timezone -9:30 Pacific/Midway Timezone -11:00 Pacific/Nauru Timezone +12:00 Pacific/Niue Timezone -11:00 Pacific/Norfolk Backlog0 Timezone 99; TimeStd 1,1,4,1,3,660; TimeDst 1,1,10,1,2,720 Pacific/Noumea Timezone +11:00 Pacific/Pago_Pago Timezone -11:00 Pacific/Palau Timezone +9:00 Pacific/Pitcairn Timezone -8:00 Pacific/Pohnpei Timezone +11:00 Pacific/Ponape Timezone +11:00 Pacific/Port_Moresby Timezone +10:00 Pacific/Rarotonga Timezone -10:00 Pacific/Saipan Timezone +10:00 Pacific/Samoa Timezone -11:00 Pacific/Tahiti Timezone -10:00 Pacific/Tarawa Timezone +12:00 Pacific/Tongatapu Timezone +13:00 Pacific/Truk Timezone +10:00 Pacific/Wake Timezone +12:00 Pacific/Wallis Timezone +12:00 Pacific/Yap Timezone +10:00 Poland Backlog0 Timezone 99; TimeStd 0,0,10,1,3,60; TimeDst 0,0,3,1,2,120 Portugal Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 ROC Timezone +8:00 ROK Timezone +9:00 Singapore Timezone +8:00 Turkey Timezone +3:00 UCT Timezone +0:00 US/Alaska Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-540; TimeDst 0,2,3,1,2,-480 US/Aleutian Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-600; TimeDst 0,2,3,1,2,-540 US/Arizona Timezone -7:00 US/Central Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 US/East-Indiana Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 US/Eastern Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 US/Hawaii Timezone -10:00 US/Indiana-Starke Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-360; TimeDst 0,2,3,1,2,-300 US/Michigan Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-300; TimeDst 0,2,3,1,2,-240 US/Mountain Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-420; TimeDst 0,2,3,1,2,-360 US/Pacific Backlog0 Timezone 99; TimeStd 0,1,11,1,2,-480; TimeDst 0,2,3,1,2,-420 US/Samoa Timezone -11:00 UTC Timezone +0:00 Universal Timezone +0:00 W-SU Timezone +3:00 WET Backlog0 Timezone 99; TimeStd 0,0,10,1,2,0; TimeDst 0,0,3,1,1,60 Zulu Timezone +0:00 This table was generated from the IANA Time Zone Database, version 2022g.
"},{"location":"TouchPin/","title":"Capacitive Touch GPIO","text":"The ESP32 has 10 capacitive touch GPIOs. It is possible to use a maximum number of 4 as a touch button.
Note
Only special pins are usable and not all of these 10 pins are exposed on every dev-board. More info in this article
After wiring a cable or electrode to a supported pin you have to configure it in Configure Module as \"button_tc\".
It is helpful to understand, what is going on under the hood: The continuous pin reading gives a unitless value, that will decrease when the pin (or connected cable) is touched. The touch pin driver will report a button touch when the pin reading falls below a threshold value for a certain amount of read cycles. The latter is important to filter out spikes.
The default values are very conservative in order to rule out unwanted actions. In most cases it will be desirable to do a calibration.
"},{"location":"TouchPin/#commands","title":"Commands:","text":"Command Description TouchCal x x=button 1 .. 4. This plots the sensor values to the console, to get information regarding the setting of the 2 following commands 0 will turn off calibration 255 will turn on calibration for all buttons TouchThres x x=button 1 .. 4. This plots the sensor values to the console, to get information regarding the setting of the 2 following commands TouchNum x sets number of ignored measurements below the threshold, because there will likely be spikes. The default value of 3 is very conservative and 1 should be fine most of the time. A higher value is safer in a noisy environment, but for obvious reasons you will have to touch the pin (or cable ...) longer to trigger the button press. While the calibration process is running, the raw data values will be printed in the console in the format: PLOT: g, v, h,
g - number of the graph (= number of the button) v - raw value of the corresponding touch pin h - number of continuous hits below current threshold, useful to see the number and length of \"spikes\", should be 0 without touching
The new values for a personal configuration can be stored in RULE:
Example
rule1 on System#Init do TouchNum 1 endon
"},{"location":"TouchPin/#tasmota-serial-plotter","title":"Tasmota Serial Plotter","text":"This little tool should be helpful to get a feel for the touch values. It is located in the /tools folder of the Tasmota repository and needs the installation of \"mathplotlib\" and \"pyserial\" in the active python environment. It is confirmed to work under Windows 10 and macOS Catalina.
Example: ./serial-plotter.py --port /dev/XXX --baud 115200
You can send commands to Tasmota via SEND-box.
For the touch button driver:
TouchCal 255 - turns on calibration mode for all buttons
(Note the short spikes, which in this config only would need TouchNum 1 to get filtered out)
"},{"location":"Troubleshooting/","title":"Troubleshooting","text":""},{"location":"Troubleshooting/#debugging","title":"Debugging","text":""},{"location":"Troubleshooting/#logs","title":"Logs","text":"For debugging purposes you can use Level 4 or Level 5 logging to the MqttLog, WebLog, SerialLog, or remote SysLog.
The logging level is set separately for each log destination. Log levels range from 0 to 5. The higher the log level, the more information is logged. When troubleshooting your device it's recommended to set the logging level to 4.
"},{"location":"Troubleshooting/#web-logging","title":"Web Logging","text":"These show up in the Web UI Console (http://deviceip/cs). The default logging level for WebLog logging is 2.
"},{"location":"Troubleshooting/#serial-logging","title":"Serial Logging","text":"Warning
Never connect to serial while the device is connected to mains power. You can still collect the logs, but only when powering it via your serial connection.
Some devices use the serial port to control the relays or an MCU, so serial logging might interfere with control and even switch relays or lights.
The default logging level for SerialLog logging is 2. Unless explicitly set by a command (e.g., user input in the Console, a System#Boot triggered rule), SerialLog will be disabled automatically 10 minutes after the device reboots.
Through a terminal program set the baud rate to 115200 (19200 for Sonoff Dual), both NL & CR, and disable hardware flow control.
- Debugging the Sonoff Pow is a bit tricky as the serial interface has a direct connection to one of the AC power lines. The schematic below uses two optocouplers separating the AC connection on the left from the low voltage connection on the right allowing for serial control at 115200 baud and uploading of firmware up to 57600 baud while AC is connected.
"},{"location":"Troubleshooting/#crashdumps","title":"Crashdumps","text":"If the ESP8266 crashes, it frequently dumps information about the crash out the serial port, so the process listed above to see serial logs can provide extremely useful information
"},{"location":"Troubleshooting/#syslog-logging","title":"Syslog Logging","text":"If you have a Linux system, it is probably already running syslog. You just need to configure it to listen on the network. SysLog logging is disabled in Tasmota by default.
On systems running rsyslog (most linux distros), edit the /etc/rsyslog.conf file. Adding (or uncommenting) the following lines will probably start making the logs show up in some file under /var/log
$ModLoad imudp \n$UDPServerRun 514 \n
If you do not have access to a Linux system, there are Microsoft Windows Syslog server options.
"},{"location":"Troubleshooting/#mqtt-logging","title":"MQTT Logging","text":"These log messages show up as MQTT messages. MqttLog logging is disabled by default.
"},{"location":"Troubleshooting/#mqtt-traffic","title":"MQTT traffic","text":"To check the flow of MQTT traffic you can use MQTT Explorer which shows your entire MQTT traffic in an organised and structured way.
Tasmota Device Manager offers an overview of all your Tasmota devices using MQTT protocol. You can manage them, use device features and do basic troubleshooting with ease. It also cleanly displays if your device is dropping from the network often or reboots unexpectedly.
"},{"location":"Troubleshooting/#running-out-of-ram","title":"Running out of RAM","text":"This typically shows up in the device working when it first starts up (hitting the button toggles the relay), but some time later it either reboots or some function won't work.
For example, you can't load the module configuration page.
The only fix for this is to recompile the firmware and disable features you don't need. Known large features are web server and TLS, but other things to consider disabling if you don't need them are emulation support, Domoticz support and WS8212 support.
"},{"location":"Troubleshooting/#program-memory","title":"Program Memory","text":"A 512K firmware binary size is a good \"target\" and rule of thumb for allowing future OTA firmware updates. Flashing over the air (OTA) requires that there is enough free program memory available to upload the new firmware along with the existing copy before the old copy is deleted. If your firmware binary is larger than the available free program memory, you can replace the existing firmware with a minimal functionality version of Tasmota (roughly 375K). This leaves enough free in the 1024K program memory for the final copy of the firmware (i.e., larger than 512K).
Flashing Tasmota makes it simpler to update to newer versions because it is built for OTA upgrades. In fact, if the new firmware is larger than the available free memory, Tasmota's OTA process will, automatically, first replace the existing firmware with \"minimal\" to then have enough space to put the new firmware in.
If one is loading firmware only via the serial interface (i.e., wired), then theoretically you could load firmware as large at the program memory size. since you can erase the flash and then fill it to the rim with the new firmware. But then you'd be left with performing upgrades by having to have physical access to the device each time.
"},{"location":"Tutorials/","title":"Projects and Tutorials","text":"Find more projects and share them in Show and Tell!
"},{"location":"Tutorials/#gallery-of-projects-running-tasmota","title":"Gallery of projects running Tasmota","text":"Click on name for larger image TrDA's 3xINA219 (Solar+Sensor+Display) TrDA's Motorised Roller Blinds Solar and battery power monitoring stationSchematic Water tank monitor Multisensor Aquarium controller"},{"location":"Tutorials/#external-links-to-coolamazing-projects-made-with-tasmota","title":"External Links to cool/amazing projects made with Tasmota","text":" - LEGO Nightstand Switch
- Tasmota based drop pin door lock
"},{"location":"Tutorials/#installation-tutorials","title":"Installation Tutorials","text":" - Installing Tasmota using Tasmotizer
"},{"location":"Tutorials/#video-tutorials","title":"Video tutorials","text":" - Tasmota and Tasmotizer Easy Flashing Guide for ESP8266 devices
- Installation tutorial of Tasmota using PlatformIO made by QuickPi.
- True 3-Way Smart Switch
- Make a motion activated switch with temperature and humidity sensor
- Sonoff Basic as UK Light Switch
"},{"location":"Tutorials/#3d-printed-cases","title":"3D Printed Cases","text":"Don't have 3D printer? Depending on where you live, you may be able to find a third party to print the model for you. Some schools and public libraries provide printing services. Search for a printing service using 3D Hubs or send your design to a service like Shapeways. - Thingiverse - Yeggi
"},{"location":"Tutorials/#related-youtube-channels","title":"Related YouTube Channels","text":" - DigiblurDIY - Great and Easy Tasmota related Videos
- DrZzs - Great and Easy Tasmota related Videos
- Super House - Home Automation Tutorials
- The Hook Up - Home Automation Tutorials
- BRUH Automation - Home Automation Tutorials
- Burns Home Automation - Home Automation Tutorials
- Step to Step Tutorials - Hobbytronics Tutorials
- Kiril Peyanski - Tasmota Tutorials
"},{"location":"Tutorials/#non-english-tutorials","title":"Non-English Tutorials","text":" - ES - Cayetano YouTube Channel
- DE - Tuya Ger\u00e4te Flashen
- DE - ESP8266 flashen von A - Z
- FR - Ajouter un bouton physique au Sonoff basic
- IT - Installazione firmware Tasmota su Sonoff Basic
- IL - Hebrew - Install Tasmota firmware on all Sonoff devices
- ?? - Yuval Mejahez - Tasmota Flash tutorials Channel
"},{"location":"Tuya-Convert/","title":"Tuya Convert","text":"Tuya devices are sold under numerous brand names but they're all identifiable by the fact that they connect with these phone apps: \"Smart Life\" or \"Tuya Smart\". They incorporate different types of Tuya Wi-Fi modules internally.
Tuya has begun manufacturing some Wi-Fi modules using a Realtek RTL8710BN Wi-Fi SOC instead of an ESP82xx chip. Tasmota cannot run on Realtek devices and there are no plans on supporting them.
Tuya-Convert is the most successful method of flashing Tuya modules without opening the device and soldering.
Tuya-Convert comes with tasmota-lite.bin build which includes basic Tasmota features required for normal operation with Tuya devices, while removing sensors, IR, RF and home automation integration support for reduced filesize. It is recommended to upgrade to a full build of the firmware (tasmota.bin) if needed.
To ensure Tasmota runs reliably execute the command reset 5 after Tuya-Convert is finished and Tasmota is up and running. Doing this removes fragments of the original firmware left in flash which can create issues in the future. After all that is done you can proceed with the needed configuration of your device.
Help and troubleshooting for Tuya-Convert is done on Tuya-Convert's Github.
Danger
The fact that you can flash Tasmota on your device does not mean all of its features are currently supported. Please research before purchasing to see if other users have successfully flashed the device and are able to use it fully
- Tuya-Convert video walkthrough
- TuyOTA walkthrough
- Mock Tuya Cloud - A general purpose framework for interacting with Tuya devices without the Tuya operated cloud.
- Tuya API - A library for communicating with devices that use the Tuya cloud network.
"},{"location":"TuyaMCU-Devices/","title":"TuyaMCU Devices","text":"There are several Tuya dimmer and switch variants made by various manufacturers. The switches range from 1 to 8 gangs. The dimmers are usually 1 gang. They dim mains voltage for various lighting types: incandescent, CFL, and LED. Consult the specific device for the type of bulbs and capacity it supports as well as the bulbs themselves to verify they support dimming.
"},{"location":"TuyaMCU-Devices/#identification-and-technical-details","title":"Identification and Technical details","text":"The basic identification of a Tuya device is when the device information references the \"Tuya Smart\", \"SmartLife\", or \"Smart Living\" app. These switches and dimmers are based on a Tuya TYWE3S Wi-Fi PCB module along with an MCU. TYWE3S is based on the ESP8266 which is supported by Tasmota.
Wiki page for TYWE3S
The TYWE3S module mostly takes care of Wi-Fi and software features while the MCU controls the actual hardware (buttons, relays, dimmer, power measurement, etc). The MCU is interfaced to TYWE3S using the serial interface which connects to the Rx and Tx pins.
The easiest way to identify if your switch or dimmer uses MCU is by using a continuity tester (multimeter, ohmmeter) and checking continuity from the Rx and Tx pins on TYWE3S to any other chip. Then check the datasheet of that chip to see if it is an MCU.
"},{"location":"TuyaMCU-Devices/#flashing-preparation","title":"Flashing - Preparation","text":"To boot the TYWE3S in flashing mode, GPIO0 needs to be connected to GND while powering up. It can be left grounded for the entire process. Flashing a TYWE3S connected to a MCU is a bit trickier than one without MCU. This is due the same Rx Tx pins used by MCU and serial programmer for flashing. The TYWE3S cannot be booted to flash mode with MCU sending data over the same pins. To be able to do that, we need to disable MCU from sending data over Rx and Tx pins. There are few ways to do it: 1. Disconnect TYWE3S module from the rest of board. (Naah, too much work) 2. Just break the Rx track from MCU to TYWE3S, flash and then reconnect. (Messy work, we want cleaner approach) 3. Just keep MCU disabled while flashing TYWE3S without any soldering / cutting. (We like that)
The easiest is to keep MCU disabled is by identifying the NRST/RST (Reset) pin of the MCU from its datasheet and connect it to GND for the entire flashing process. This will keep MCU disabled while you flash TYWE3S. If there are some contacts or test points in switches that connect to the MCU, you might be lucky to find contacts for RST that you can easily solder onto.
"},{"location":"TuyaMCU-Devices/#tywe3s-connection-options","title":"TYWE3S Connection Options","text":" - 3D print a flashing Jig and use pogo pins to make nice and easy to use flashing jig
- Solder wires directly onto TYWE3S
- Use a jumper header like the one below and bend the pins to match VCC, Rx Tx GPIO0 and GND. You can just press the jumper header to the contacts during the flashing process
"},{"location":"TuyaMCU-Devices/#flashing-process","title":"Flashing - Process","text":"Once you are done identifying the pins and ready to connect, BEFORE connecting USB to PC you need to connect them as follows: NOTE : Use 3.3V NOT 5V
TYWE3S SerialProgrammer RX TX TX RX GPIO0 GND GND GND VCC 3.3V If an MCU is present, bridge RST to GND on the MCU
Use a 6.6.0.10 Tasmota version or higher. There are lots of Tuya Serial fixes / features added in there and the tutorial below expects them.
Now you need to follow the commands explained in the flashing tutorial.
TIP: If you are using jumper headers use sleep 15 && before your commands, this would free your hand and give you some time to set the jumper pins and connect the USB to PC.
"},{"location":"TuyaMCU-Devices/#configuration","title":"Configuration","text":" - Once Tasmota is flashed on the TYWE3S, just disconnect GND -> GPIO0 (and RST if there is an MCU), and power your device again from USB.
- On your PC, you should see a Wi-Fi network named
sonoff-xxxx where xxxx is a number from the ESP's MAC address. - Connect to it and go to 192.168.4.1 in your browser. Enter the Wi-Fi credentials for your network and click save.
- Connect your PC back to your network. Now you need to find the IP of newly connected Tasmota device. Refer to this very good video from SuperHouseTV (ignore flashing information) about configuring Tasmota.
- Once you get to the Tasmota configuration you need to select
TuyaMCU module assign GPIO components as indicated below depending on your hardware. You already know the pin connections to the MCU.
GPIO Component 01 Tuya Rx (108) 03 Tuya Tx (107) 13 Tuya Rx (108) 15 Tuya Tx (107) - If the device is connecting fine to your network, now is the time to power it down and re-assemble it. Connect a test bulb (or to the final place if you don't mind testing there)
- Once this is saved and device is rebooted. Open the Tasmota configuration page and you should be able to use the Toggle button to toggle the dimmer or at least one of the gangs in a multi gang switch.
- Follow the process here depending on switch or dimmer.
"},{"location":"TuyaMCU-Devices/#product-specific-guides","title":"Product Specific guides","text":""},{"location":"TuyaMCU-Devices/#otim-dimmer","title":"Otim Dimmer","text":"This Device is based on a Tuya Wi-Fi Module. Refer to \"MCU Based Tuya Dimmers and Switches\" for details.
Flashing and Setup Video Guide
These devices use a Tuya TYWE3S Wi-Fi PCB module. Once the switch is carefully popped open you will need to remove the ribbon cables for flashing and ease of soldering. An easy soldering method is to take several Dupont style jumper wires, cut one end off, and apply a bit of solder to each stripped end. This will keep the wire flexible and prevent any circuit board pads from ripping off. Apply a bit of solder to each pad necessary to flash (double check your pin-outs). Once the wire and pad have solder simply put the two together and apply a bit of heat and they will join together.
Attach the GPIO0 wire to ground during initial boot to flash. You may need to also connect MCU RST to GND during initial boot to get it into programming mode as described here. A 3-pin header bridged together works great with GPIO0, GND and the GND from the USB flasher attached. (TX pin to RX pin and RX pin to TX pin on USB flash adapter). Verify that you are using 3.3volts to flash, NOT 5V!
Product Links:
- Oittm
- Moes DS01 (Template)
- Konesky
- Heygo
"},{"location":"TuyaMCU-Devices/#costco-charging-essentials","title":"Costco Charging Essentials","text":"This devices use a Tuya TYWE1S Wi-Fi PCB module. And it uses U1TX (GPIO15) and U1RX (GPIO13) to communicate between ESP8266 and MCU, no other GPIO is used in this device.
"},{"location":"TuyaMCU-Devices/#flashing","title":"Flashing","text":"The CE dimmer uses standard Tuya GPIO
"},{"location":"TuyaMCU-Devices/#touch-eu-and-us-multiple-manufacturers","title":"Touch (EU and US) - Multiple manufacturers","text":""},{"location":"TuyaMCU-Devices/#flashing_1","title":"Flashing","text":"The procedure is similar to above, additionally NRST must be connected to GND during flashing.
"},{"location":"TuyaMCU-Devices/#optional-configuration-recommended","title":"Optional configuration (recommended)","text":"LedState 0 Only use the green LED for Wi-Fi/MQTT connectivity status.
"},{"location":"TuyaMCU-Devices/#product-links","title":"Product Links:","text":""},{"location":"TuyaMCU-Devices/#zemismart-curtain-motor","title":"Zemismart Curtain Motor","text":"Curtain motors come in a confusing array. This one has a little Wi-Fi dongle, that looks like a USB stick. But it talks using 9600 8N1, not USB. This means we can unplug the Tuya Dongle and flash it without worrying about the PCI micro. Excellent.
U1RX and U1TX, top right of the module are connected to the USB plug on D- and D+ respectively. This dongle uses a Tuya TYWE1S, which is an ESP8266 with 2MB flash. USB3 pin R- connects the onboard LED to the MCU via a 4k7 resistor. R+, T+, and T- are all unused and unconnected on the motor PCB, so I liberated them for soldering to GPIO0, U0RX and U0TX, to flash the chip.
- short GPIO0 and flash Tasmota
- Connect to your Wi-Fi and get MQTT and SSL working
- change to TuyaMCU with
module 54 (will reboot) - Switch from U0RX/TX to U1RX/TX with
backlog gpio1 0; gpio3 0; gpio15 107; gpio13 108 (will reboot) - Treat DpId 0x65 as a Dimmer with
tuyamcu 21,101 - Allow the dimmer to get down to 1% with
setoption69 0
And done. The curtain motor now presents as a Dimmer, with 100% full brightness = fully closed, and 0% full darkness = fully open.
The curtain motor also presents DpId 0x66 as a single event \"Full Open\" 00, \"Full Close\" 01, and \"Stop\" 02 command; but as of September 2019, I can't see how to get that working.
The curtain motor also presents DpId 0x67 as a Boolean. I have only seen value 0x01 in all my prodding. 55 aa 00 07 00 05 67 01 00 01 01 75 = 07 Status, 0005 length, 67 DpId, 01 type, 0001 length, 01 value, 75 checksum
"},{"location":"TuyaMCU-Devices/#product-links_1","title":"Product Links:","text":""},{"location":"TuyaMCU-Devices/#dm_wf_mdv4-leading-edge-dimmer","title":"DM_WF_MDV4 Leading edge dimmer","text":"This is a 240V Leading Edge Dimmer with a TYWE3S controller and an STM8 MCU
"},{"location":"TuyaMCU-Devices/#flashing_2","title":"Flashing:","text":"The simplest approach is to use Tuya-Convert to flash the device
In order to flash via serial, the NRST pin of the STM8 needs to be grounded upon boot to disable it, this is brought out to a header pin, along with ground and VCC from the TYWE3S. Confirm by checking continuity with a multimeter
IO0 from the TYWE3s also needs to be grounded upon boot, otherwise it's normal tasmota flashing procedure.
Header J3 (STM8 debug interface) pins from left to right (Pin 1 is the square shaped) *VCC *STM8 SWIM (Pin 18) *Ground *STM8 NRST (Pin 4)
"},{"location":"TuyaMCU-Devices/#config","title":"Config:","text":"As per main TuyaMCU page using
GPIO Component 01 Tuya Rx (108) 03 Tuya Tx (107) Note that the push button is wired to the MCU (PA3 Pin 10) so it cannot be used by Tasmota. Similarly the devices has a bi-color LED where one color (green) is wired to the TYWE3S (GPIO14) and the other one (red) to the MCU (PC5 Pin15).
"},{"location":"TuyaMCU-Devices/#more-information","title":"More information:","text":"Bought from ebay
More information on TYWE3S]
"},{"location":"TuyaMCU-Devices/#product-links_2","title":"Product Links:","text":" - AIGLEN
- ALLOMN
- MakeGood
- ZemiSmart
"},{"location":"TuyaMCU/","title":"TuyaMCU","text":"TuyaMCU - Module (54) is configured for devices with a Tuya Wi-Fi module and a secondary MCU.
Originally, in those devices, the Wi-Fi module takes care of network and software features. Meanwhile, the MCU controls the hardware based on commands received from the Wi-Fi module or built-in controls (buttons, switches, remotes and similar) and reports the status back to the Wi-Fi module.
TuyaMCU module facilitates communication between Tasmota and the MCU using Tuya Serial Port Communication Protocol:
TuyaMCU command maps device functions to Tasmota components TuyaSend<x> command calculates and sends complex serial commands using only two parametersTuyaReceived MCU response interpreted and publishes as status message and a JSON payload to an MQTT topic
"},{"location":"TuyaMCU/#tuyamcu-command","title":"TuyaMCU Command","text":"Command TuyaMCU is used to map Tasmota components to Tuya device dpId's.
Warning
Used only if your device is defined as module TuyaMCU (54).
Command value consists of two comma separated parameters: fnId and dpId.
TuyaMCU <fnId>,<dpId>\n
where <fnId> is a Tasmota component and <dpId> is the dpId to map the function to. Example
TuyaMCU 11,1 maps Relay1 (fnId 11) to dpId 1.
If any existing entry with same fnId or dpId is already present, it will be updated to the new value.
Entry is removed when fnId or dpId is 0.
When no parameters are provided TuyaMCU prints the current mapped values.
"},{"location":"TuyaMCU/#dpid","title":"dpId","text":"All the device functions controlled by the MCU are identified by a dpId. Whenever a command is sent to the MCU, this dpId determines which component needs to be controlled and the applies when the status is received from MCU.
There is no way to autodetect dpId's and their functions.
To assist in the process of determining what dpId does what, there is a bookmarklet available that can be used on the console screen. This will send the weblog and other required commands automatically, and present the TuyaMCU information in a single table allowing for easier testing.
Use this procedure to determine which dpId's are available:
- Go to
Configure -> Console option in Tasmota web interface. - Use command
weblog 4 to enable verbose logging in web interface. - Observe the log. After every 9-10 seconds you should see Tuya specific messages labelled as
TYA:.
{\"TuyaReceived\":{\"Data\":\"55AA0107000501010001000F\",\"Cmnd\":7,\"CmndData\":\"0101000100\",\"DpType1Id1\":0,\"1\":{\"DpId\":1,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=11 is set for dpId=1\nTYA: RX Relay-1 --> MCU State: Off Current State:Off\n{\"TuyaReceived\":{\"Data\":\"55AA01070005020100010010\",\"Cmnd\":7,\"CmndData\":\"0201000100\",\"DpType1Id2\":0,\"2\":{\"DpId\":2,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=2\n{\"TuyaReceived\":{\"Data\":\"55AA01070005030100010011\",\"Cmnd\":7,\"CmndData\":\"0301000100\",\"DpType1Id3\":0,\"3\":{\"DpId\":3,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=3\n{\"TuyaReceived\":{\"Data\":\"55AA01070005040100010012\",\"Cmnd\":7,\"CmndData\":\"0401000100\",\"DpType1Id4\":0,\"4\":{\"DpId\":4,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=4\n
- Observe all lines printed as
TYA: FnId=0 is set for dpId=XXX and note all dpId values.
Now that you have a list of usable dpId's you need to determine what their functions are:
- Consulting our list of commonly used dpId's and existing device configurations
- Observing Tasmota logs while activating features of the device (with a remote or on device controls) and correlating log messages and looking at the DpIdType and DpIdData values (eg: boolean vs value)
- Extrapolating possible function of the dpId based on Data Type and Function Command, then testing using
TuyaSend<x>
"},{"location":"TuyaMCU/#fnid","title":"fnId","text":"Identifier used in TuyaMCU command to map a dpId to a Tasmota component.
Component FnId Note Switch1 to Switch4 1 to 4 Map only to dpId with on / off function Relay1 to Relay8 11 to 18 Map only to dpId with on / off function Lights 21 to 28 21 for Dimmer22 for Dimmer223 for CCT Light24 for RGB light25 for white light26 for light mode set (0 = white and 1 = color)27 to report the state of Dimmer128 to report the state of Dimmer2 Power Monitoring 31 to 33 31 for Power (in deci Watt)32 for Current (in milli Amps)33 for Voltage (in deci Volt) Relay1i to Relay8i 41 to 48 Map only to dpId with on / off function Battery powered sensor mode 51 Battery powered devices use a slightly different protocol Enum dpId 61 to 64 Range for each enum is 0 to 31 Sensors 71 to 79 Range of sensors (temperature, humidity, co2, gas, etc) Timers 81 to 84 Manage integer based timers Extra functions 97 to 99 97 for motor direction98 for error logging (report only)99 as a dummy function Note
This component is under active development which means the function list may expand in the future.
Since the majority of devices have a power on/off functions on dpId 1 it's mapped to fnId 11 (Relay1) by default. If you don't need it, map it to fnId 99 with TuyaMcu 99,1
Danger
Mapping a relay or switch to a dpId that is not a simple on/off function (data Type 1) might result in unwanted power toggling (i.e. dpId sends value of 4 which toggles the relay to Power 4 aka blink mode)
"},{"location":"TuyaMCU/#tuyasend-command","title":"TuyaSend Command","text":"Command TuyaSend is used to send commands to dpId's. It is required for dpId's that shouldn't be mapped to a fnId.
With this command it is possible to control every function of the dpId that is controllable, providing you know its data type and data length. With them provided, the rest of the protocol command is calculated.
Command's value consists of two comma separated parameters: dpId and data.
TuyaSend<x> dpId,data
"},{"location":"TuyaMCU/#tuyasend0","title":"TuyaSend0","text":"Used without payload to query states of dpID's.
"},{"location":"TuyaMCU/#tuyasend1","title":"TuyaSend1","text":"Sends boolean (Type 1) data (0/1) to dpId (Max data length 1 byte)
Example
TuyaSend1 1,0 sends value 0 to dpId=1 switching the device off
"},{"location":"TuyaMCU/#tuyasend2","title":"TuyaSend2","text":"Sends integer or 4 byte (Type 2) data to dpId (Max data length 4 bytes)
Example
TuyaSend2 14,100 sends value 100 to dpId=14 setting timer to 100 minutes
"},{"location":"TuyaMCU/#tuyasend3","title":"TuyaSend3","text":"Sends an ASCII string (Type 3) data to dpId (Max data length? Not known at this time).
Warning
Note that when sending color values, the MCU may interpret lower case and upper case hex codes differently. You may need to test with your specific MCU to ensure that the values sent properly render the color you desire.
Example
TuyaSend3 108,ff0000646464ff sends a 14 char hex string to dpId=108 (Type 3) containing RGBHSV values to control a light
"},{"location":"TuyaMCU/#tuyasend4","title":"TuyaSend4","text":"Sends enum (Type 4) data (0/1/2/3/4/5) to dpId (Max data length 1 bytes)
Example
TuyaSend4 103,2 sends value 2 to dpId=103 to set fan speed to high
"},{"location":"TuyaMCU/#tuyasend5","title":"TuyaSend5","text":"Sends an HEX string (Type 3) data to dpId (Max data length? Not known at this time). Does NOT require 0x prefix.
Example
TuyaSend5 108, ABCD sends a string of 2 bytes defined by hex codes to dpId=108
Differences between TuyaSend3 and TuyaSend5:
TuyaSend3 108, ABCD sends 55aa000600086c030004414243448a where the payload is 41424344 which is the ASCII bytes representing the string ABCDTuyaSend5 108, ABCD sends 55aa000600066c030002abcdf4 where the payload is a abcd which is a string of 2 bytes 0xAB and 0xCD
"},{"location":"TuyaMCU/#tuyasend6","title":"TuyaSend6","text":"Sends payload with raw data (type 0) to dpId (Max data length? Not known at this time). Does NOT require 0x prefix.
Example
TuyaSend6 37, 060000DC08000096 sends raw data defined by hex codes to dpId=37
Differences between TuyaSend3, TuyaSend5 and TuyaSend6: * TuyaSend3 and TuyaSend5 sends payload with the data type 0x03 = string * TuyaSend6 sends payload with the data type 0x00 = raw
"},{"location":"TuyaMCU/#tuyasend8","title":"TuyaSend8","text":"Used without payload to get device information and dpId states. Replaces SerialSend5 55aa000100000
"},{"location":"TuyaMCU/#tuyasend9","title":"TuyaSend9","text":"Use without any payload to toggle a new STAT topic reporting changes to a dpId, for example:
17:45:38 MQT: stat/TuyaMCU/DPTYPE1ID1 = 1\n
"},{"location":"TuyaMCU/#tuyareceived","title":"TuyaReceived","text":"Every status message from the MCU gets a JSON response named TuyaReceived which contains the MCU protocol status message inside key/value pairs which are hidden from the user by default.
To publish them to a MQTT Topic of tele/%topic%/RESULT you need to enable SetOption66 1.
To avoid some cyclic MCU <-> ESP messages published via MQTT to the topic tele/%topic%/RESULT you need to enable SetOption137 1.
If SetOption137 set to 1 the following cmds will not forwarded: - the heartbeat between the MCU <-> ESP (every 10 seconds, TUYA_CMD_HEARTBEAT) - the Wifi-State between the MCU <-> ESP (during start-up and wifi events, TUYA_CMD_WIFI_STATE) - the local time info query of the MCU (every minute, TUYA_CMD_SET_TIME) - the received update package info from MCU (during firmware update of Tuya MCU, TUYA_CMD_UPGRADE_PACKAGE)
If SetOption137 set to 0 all received Tuya MCU messages will be published. SetOption137 is very useful to reduce the MQTT-traffic.
"},{"location":"TuyaMCU/#example","title":"Example","text":"After issuing serial command 55aa0006000501010001010e (Device power (dpId=1) is mapped to Relay1 (fnId=11)) we get the following console output (with weblog 4):
19:54:18 TYA: Send \"55aa0006000501010001010e\"\n19:54:18 MQT: stat/GD-30W/STATE = {\"Time\":\"2019-10-25T19:54:18\",\"Uptime\":\"0T01:45:51\",\"UptimeSec\":6351,\"Heap\":27,\"SleepMode\":\"Dynamic\",\"Sleep\":0,\"LoadAvg\":999,\"MqttCount\":1,\"POWER1\":\"ON\",\"POWER2\":\"OFF\",\"POWER3\":\"ON\",\"POWER4\":\"OFF\",\"POWER5\":\"ON\",\"Dimmer\":100,\"Fade\":\"OFF\",\"Speed\":1,\"LedTable\":\"OFF\",\"Wifi\":{\"AP\":1,\"SSId\":\"HTPC\",\"BSSId\":\"50:64:2B:5B:41:59\",\"Channel\":10,\"RSSI\":24,\"LinkCount\":1,\"Downtime\":\"0T00:00:08\"}}\n19:54:18 MQT: stat/GD-30W/RESULT = {\"POWER1\":\"ON\"}\n19:54:18 MQT: stat/GD-30W/POWER1 = ON\n19:54:18 MQT: stat/GD-30W/RESULT = {\"TuyaReceived\":{\"Data\":\"55AA0007000501010001010F\",\"ChkSum\":\"0x0F\",\"Cmnd\":7,\"CmndDataLen\":5,\"CmndData\":\"0101000101\",\"DpId\":1,\"DpIdType\":1,\"DpIdLen\":1,\"DpIdData\":\"01\"}}\n19:54:18 TYA: fnId=11 is set for dpId=1\n19:54:18 TYA: RX Relay-1 --> MCU State: On Current State:On\n
Above TYA: fnId=11 is set for dpId=1 you can see the JSON response for that dpId. This JSON string displays the response MCU gave to our command. \"Data\" field contains the complete response and the rest of the key/value pairs show the protocol broken into parts. \"DpId\", \"DpIdData\" and \"DpIdType\" are the ones we're most interested in since we can use them for TuyaSend.
Tip
Use command TuyaSend8 and/or TuyaSend0 at any time to request statuses of all dpId's from the MCU.
"},{"location":"TuyaMCU/#use-in-rules","title":"Use in Rules","text":"This data can also be used as a trigger for rules using TuyaReceivedData#Data=hex_string
Rule1 on TuyaReceived#Data=55AA000700056E040001007E do publish2 stat/tuya_light/effect rgb_cycle endon\n
will publish a status message to a custom topic when 55AA000700056E040001007E appears in \"Data\" field of the response."},{"location":"TuyaMCU/#device-configurations","title":"Device Configurations","text":"Before proceeding identify dpId's and their function.
"},{"location":"TuyaMCU/#dimmer","title":"Dimmer","text":"We need to configure four functions of a dimmer:
- Dimming dpId
- Dimming Range
- Dimming less than 10%
"},{"location":"TuyaMCU/#dimming-dpid","title":"Dimming dpId","text":"The dimmer FunctionId is 21. On a dimmer dpId generally is 2 or 3. Try both.
- Go to the Tasmota Console and type
TuyaMCU 21,2 and wait for it to reboot. - Enter
Backlog Dimmer 10; Dimmer 100 in the Console. - If your bulb responds to
Dimmer commands, you have successfully configured the dimmer FunctionId. Make note of it. - If not try id
3 and if even 3 doesn't work keep trying Ids from all unknown Ids from the log until one works.
"},{"location":"TuyaMCU/#dimming-range","title":"Dimming Range","text":"Once you have figured out the dimming functionId, we need to find the maximum dimming range. Once the dimming Id is set, the logs will continue
TYA: Heartbeat \nTYA: RX Packet: \"55aa03070005010100010011\" \nTYA: RX Relay-1 --> MCU State: Off Current State:Off \nTYA: RX Packet: \"55aa03070008020200040000000720\" \nTYA: FnId=21 is set for dpId=2 \nTYA: RX Dim State=7 \n
Now using the hardware buttons increase the dimmer to its maximum and observe the log. The Dim State=XXX shows the current dimmer level reported by MCU. Once the dimmer is at max, note this number. Again using hardware buttons decrease dimmer to minimum and note the number for minimum. Now we need to tell Tasmota to use maximum and minimum values. This controlled by DimmerRange command. We can set it using DimmerRange <Min>,<Max> where <Min> is the minimum dimmer state and <Max> maximum dimmer state reported in logs.
Once set, try dimmer 100 in the Console and check if the brightness of bulb is same is the same as when the maximum was set using hardware buttons.
Warning
Some Tuya devices automatically send the state of a dimmer after a power off. Tasmota could misunderstand the command and try to turn on the light even with SetOption20 and SetOption54 enabled.
"},{"location":"TuyaMCU/#dual-dimmer","title":"Dual Dimmer","text":"To enable a dual dimmer setup assign fnId's:
21 as Dimmer122 as Dimmer211 as Relay112 as Relay2
Tasmota will automatically enable SetOption68 and the dimmers will respond to Channel1 and Channel2 commands.
Warning
The use of SetOption68 is limited to two channels and will be automatically disabled if any other combination of lights is used.
"},{"location":"TuyaMCU/#lights","title":"Lights","text":""},{"location":"TuyaMCU/#cct-light","title":"CCT Light","text":"To enable a CCT light assign fnId's:
21 as Dimmer111 as Relay123 as CT channel
"},{"location":"TuyaMCU/#rgb-light","title":"RGB Light","text":"To enable an RGB light assign fnId's:
21 as Dimmer111 as Relay124 as RGB controller
TuyaMCU uses different types of RGB Hex format where the most recent is 0HUE0SAT0BRI0 (type 1) and the older being RRGGBBFFFF6464 (type 2). Depending on the MCU, code can be case sensitive.
After enabling the RGB function check the TuyaReceived information and use TuyaRGB to configure and store the correct (or the closest) format:
TuyaRGB 0 - Type 1, 12 characters uppercase. Example: 00DF00DC0244 (default)TuyaRGB 1 - Type 1, 12 characters lowercase. Example: 008003e8037aTuyaRGB 2 - Type 2, 14 characters uppercase. Example: 00FF00FFFF6464TuyaRGB 3 - Type 2, 14 characters lowercase. Example: 00e420ffff6464
TuyaRGB without payload will return the actual configured format.
"},{"location":"TuyaMCU/#rgbx-light","title":"RGB+X Light","text":"To enable an RGB+W light use RGB Light configuration and assign fnId 25 as white color.
To enable an RGB+CCT light use RGB Light configuration and assign fnId 23 as CT channel.
"},{"location":"TuyaMCU/#light-mode-selector","title":"Light mode selector","text":"The majority of \u00a0TuyaMCU devices with an RGB+W or an RGB+CCT light have a button or app function to switch between White and Colored light.
To do the same in Tasmota, assign function (fnId) 26 to the mode select dpId. The possible values are 0 (white) and 1 (colorful). A button on the WebUI will be available once configured.
When the ModeSet function is enabled it is not possible to update both lights at the same time. Only the currently selected light mode will be updated.
Warning
Use of SetOption68 for more than two channels and the light split option (SetOption37 >= 128) are not supported in TuyaMCU mode.
"},{"location":"TuyaMCU/#enums","title":"Enums","text":"Better control over Type4 or enum dpId's. Up to four can be added, with a range from 0 to 31.
61 as Enum162 as Enum263 as Enum364 as Enum4
After an enum is configured, use TuyaEnumList to declare the range it must respect (note 0 is always the first item in range).
TuyaEnumlist <enum>,<range> where <enum> is declared using TuyaMCU and <range> is 0..31.
Example: configure Enum 1 with a range from 0 to 8.
21:14:52 CMD: tuyaenumlist 1,8\n21:14:52 MQT: stat/TuyaMCU/RESULT = {\"TuyaEnumList\":{\"Enum1\":8,\"Enum2\":9,\"Enum4\":1}}\n
Entering a value greater than 31 will return an error
TuyaEnumList without payload will return the configuration of all the enums enabled in the list.
To update an enum use the command TuyaEnum:
Usage TuyaEnum [1|2|3|4],[TuyaEnumList range]
Example: update Enum 2 to 4.
21:14:12 CMD: tuyaenum2 4\n21:14:12 MQT: stat/TuyaMCU/RESULT = {\"TuyaEnum2\":4}\n
Entering a value not in range will return an error
TuyaEnum without payload will return the state of all the enums configured.
"},{"location":"TuyaMCU/#sensors","title":"Sensors","text":"These are the currently available sensors:
71 as Temperature Sensor73 as Humidity Sensor75 as Illuminance Sensor76 as TVOC Sensor77 as CO2 Sensor78 as ECO2 Sensor79 as %LEL gas Sensor
If your device has a dpId for setting a specific Temperature and/or Humidity:
72 for Temperature Set74 for Humidity Set
Use TuyaSend2 to manage them.
Temperature and Temperature Set default to \u00b0C. If you need \u00b0F change SetOption8 to 1.
The TuyaMCU driver sends the temperature as a byte integer. As of 9.3.x, the integer is converted by Tasmota to a float based on the \"TempRes\" setting which indicates the number of places after the decimal. The TempRes setting is by default \"1\" which means a device which sends 101 will be interpreted as 10.1. If your device normally returns an integer temperature, you may need to set TempRes to \"0\".
If your device requires the temperature to be divided (eg. increases in .5\u00b0 increments), you may need to use the rules functionality to convert the temperature value.
Please note this will not update the value sent by the MCU but will just change the unit of measure reported on /SENSOR topic. You have to find a dpid to set the correct unit and change reported values (if it exists) or perhaps use the rules functionality to do the conversion.
"},{"location":"TuyaMCU/#timers","title":"Timers","text":"4 Type2 (integer) timers can be managed directly from Tasmota
81 as Timer182 as Timer283 as Timer384 as Timer4
Timers can be managed with TuyaSend2 and are visible in the WebUI.
"},{"location":"TuyaMCU/#covers","title":"Covers","text":"Single shutter or double shutters devices can be managed with a dimmer setup For devices that are reporting position to another dpId assign fnId's:
27 to report the state of Dimmer128 to report the state of Dimmer2
If your cover device has a motor direction change option assign fnId 97 for motor direction.
"},{"location":"TuyaMCU/#switches","title":"Switches","text":"There is currently no way to detect the number of relays present in an MCU based switch. We need to tell the number of relays to Tasmota using FunctionIDs 12 to 18 for Relay2 to Relay4.
Example
For a 4 gang switch set TuyaMCU 12,2, TuyaMCU 13,3 and TuyaMCU 14,4 if the dpIds for Relays 2-4 are 2,3,4.
Tip
You can configure all at once by using Backlog TuyaMCU 12,2; TuyaMCU 13,3; TuyaMCU 14,4
"},{"location":"TuyaMCU/#power-metering","title":"Power Metering","text":"Some Tuya MCU devices support Power measurement support over serial. For this it is better to use a bulb with known wattage rating.
Observe the logs in the Console
TYA: Heartbeat\n{\"TuyaReceived\":{\"Data\":\"55AA0107000501010001000F\",\"Cmnd\":7,\"CmndData\":\"0101000100\",\"DpType1Id1\":0,\"1\":{\"DpId\":1,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=11 is set for dpId=1\nTYA: RX Relay-1 --> MCU State: Off Current State:Off\n{\"TuyaReceived\":{\"Data\":\"55AA01070005020100010111\",\"Cmnd\":7,\"CmndData\":\"0201000101\",\"DpType1Id2\":1,\"2\":{\"DpId\":2,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=2\n{\"TuyaReceived\":{\"Data\":\"55AA01070005030100010011\",\"Cmnd\":7,\"CmndData\":\"0301000100\",\"DpType1Id3\":0,\"3\":{\"DpId\":3,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=3\n{\"TuyaReceived\":{\"Data\":\"55AA01070005040100010113\",\"Cmnd\":7,\"CmndData\":\"0401000101\",\"DpType1Id4\":1,\"4\":{\"DpId\":4,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=4\n{\"TuyaReceived\":{\"Data\":\"55AA0107000807020004000000001C\",\"Cmnd\":7,\"CmndData\":\"0702000400000000\",\"DpType2Id7\":0,\"7\":{\"DpId\":7,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=7\n{\"TuyaReceived\":{\"Data\":\"55AA0107000808020004000000001D\",\"Cmnd\":7,\"CmndData\":\"0802000400000000\",\"DpType2Id8\":0,\"8\":{\"DpId\":8,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=8\n{\"TuyaReceived\":{\"Data\":\"55AA0107000809020004000000001E\",\"Cmnd\":7,\"CmndData\":\"0902000400000000\",\"DpType2Id9\":0,\"9\":{\"DpId\":9,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=9\n{\"TuyaReceived\":{\"Data\":\"55AA010700080A020004000000001F\",\"Cmnd\":7,\"CmndData\":\"0A02000400000000\",\"DpType2Id10\":0,\"10\":{\"DpId\":10,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=10\n{\"TuyaReceived\":{\"Data\":\"55AA0107000865020004000000007A\",\"Cmnd\":7,\"CmndData\":\"6502000400000000\",\"DpType2Id101\":0,\"101\":{\"DpId\":101,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=101\n{\"TuyaReceived\":{\"Data\":\"55AA01070008660200040000009813\",\"Cmnd\":7,\"CmndData\":\"6602000400000098\",\"DpType2Id102\":152,\"102\":{\"DpId\":102,\"DpIdType\":2,\"DpIdData\":\"00000098\"}}}\nTYA: fnId=0 is set for dpId=102\n{\"TuyaReceived\":{\"Data\":\"55AA01070008670200040000017EFB\",\"Cmnd\":7,\"CmndData\":\"670200040000017E\",\"DpType2Id103\":382,\"103\":{\"DpId\":103,\"DpIdType\":2,\"DpIdData\":\"0000017E\"}}}\nTYA: fnId=0 is set for dpId=103\n{\"TuyaReceived\":{\"Data\":\"55AA0107000868020004000009951B\",\"Cmnd\":7,\"CmndData\":\"6802000400000995\",\"DpType2Id104\":2453,\"104\":{\"DpId\":104,\"DpIdType\":2,\"DpIdData\":\"00000995\"}}}\nTYA: fnId=0 is set for dpId=104\n
In the TuyaReceived we are interested in DpIdData. For example: 00000995 is the second last entry.
- Make sure the bulb if off.
- Find out the voltage standard of your country (generally 220, 240, 120v) from this table.
- Multiply that number by 10 (2400) and Convert that number (2400) to Hex using any hex converter (2400 = 0x960)
- Now look for the number nearest to
960 in the logs. In our case it is 00000995. So we expect that's the voltage which is \"DpId\":104 in our example. - Set voltage functionId
33 by entering TuyaMCU 33,104. - Now set dimmer to 100% using the
dimmer 100 command, or power on using power1 on (depending on the device) and observe the logs. - Now we need the power rating of your bulb, for example
40W. Multiply by 10 (400) and convert to hex which gives us 0x190. Check which unknown ID is close to 190. I this example it is 17E for \"DpId\":103. This is the Id of Active Power function. - Set the active power functionId
31 by entering TuyaMCU 31,103. - Once Power and Voltage are set you should see something such as this in the logs:
TYA: Heartbeat\n{\"TuyaReceived\":{\"Data\":\"55AA0107000501010001000F\",\"Cmnd\":7,\"CmndData\":\"0101000100\",\"DpType1Id1\":0,\"1\":{\"DpId\":1,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=11 is set for dpId=1\nTYA: RX Relay-1 --> MCU State: Off Current State:Off\n{\"TuyaReceived\":{\"Data\":\"55AA01070005020100010111\",\"Cmnd\":7,\"CmndData\":\"0201000101\",\"DpType1Id2\":1,\"2\":{\"DpId\":2,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=2\n{\"TuyaReceived\":{\"Data\":\"55AA01070005030100010011\",\"Cmnd\":7,\"CmndData\":\"0301000100\",\"DpType1Id3\":0,\"3\":{\"DpId\":3,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=3\n{\"TuyaReceived\":{\"Data\":\"55AA01070005040100010113\",\"Cmnd\":7,\"CmndData\":\"0401000101\",\"DpType1Id4\":1,\"4\":{\"DpId\":4,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=4\n{\"TuyaReceived\":{\"Data\":\"55AA0107000807020004000000001C\",\"Cmnd\":7,\"CmndData\":\"0702000400000000\",\"DpType2Id7\":0,\"7\":{\"DpId\":7,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=7\n{\"TuyaReceived\":{\"Data\":\"55AA0107000808020004000000001D\",\"Cmnd\":7,\"CmndData\":\"0802000400000000\",\"DpType2Id8\":0,\"8\":{\"DpId\":8,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=8\n{\"TuyaReceived\":{\"Data\":\"55AA0107000809020004000000001E\",\"Cmnd\":7,\"CmndData\":\"0902000400000000\",\"DpType2Id9\":0,\"9\":{\"DpId\":9,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=9\n{\"TuyaReceived\":{\"Data\":\"55AA010700080A020004000000001F\",\"Cmnd\":7,\"CmndData\":\"0A02000400000000\",\"DpType2Id10\":0,\"10\":{\"DpId\":10,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=10\n{\"TuyaReceived\":{\"Data\":\"55AA0107000865020004000000007A\",\"Cmnd\":7,\"CmndData\":\"6502000400000000\",\"DpType2Id101\":0,\"101\":{\"DpId\":101,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=101\n{\"TuyaReceived\":{\"Data\":\"55AA01070008660200040000009712\",\"Cmnd\":7,\"CmndData\":\"6602000400000097\",\"DpType2Id102\":151,\"102\":{\"DpId\":102,\"DpIdType\":2,\"DpIdData\":\"00000097\"}}}\nTYA: fnId=0 is set for dpId=102\n{\"TuyaReceived\":{\"Data\":\"55AA01070008670200040000017BF8\",\"Cmnd\":7,\"CmndData\":\"670200040000017B\",\"DpType2Id103\":379,\"103\":{\"DpId\":103,\"DpIdType\":2,\"DpIdData\":\"0000017B\"}}}\nTYA: fnId=31 is set for dpId=103\nTYA: Rx ID=103 Active_Power=379\n{\"TuyaReceived\":{\"Data\":\"55AA0107000868020004000009961C\",\"Cmnd\":7,\"CmndData\":\"6802000400000996\",\"DpType2Id104\":2454,\"104\":{\"DpId\":104,\"DpIdType\":2,\"DpIdData\":\"00000996\"}}}\nTYA: fnId=33 is set for dpId=104\nTYA: Rx ID=104 Voltage=2454\n
- To get the Id for the current, calculate Current = Power / Voltage ( 37.9 / 245.4 ) = ~0.1544 (Remember to divide each value by 10). Multiply this by 1000 = 154. Now convert 154 to hex which is 0x9A. This is closest to
97 which is Id \"DpId\":102. - Set the current FunctionId
32 using command TuyaMCU 32,102. - Observe the logs should start showing Current in addition to Active_Power and Voltage
TYA: Heartbeat\n{\"TuyaReceived\":{\"Data\":\"55AA0107000501010001000F\",\"Cmnd\":7,\"CmndData\":\"0101000100\",\"DpType1Id1\":0,\"1\":{\"DpId\":1,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=11 is set for dpId=1\nTYA: RX Relay-1 --> MCU State: Off Current State:Off\n{\"TuyaReceived\":{\"Data\":\"55AA01070005020100010111\",\"Cmnd\":7,\"CmndData\":\"0201000101\",\"DpType1Id2\":1,\"2\":{\"DpId\":2,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=2\n{\"TuyaReceived\":{\"Data\":\"55AA01070005030100010011\",\"Cmnd\":7,\"CmndData\":\"0301000100\",\"DpType1Id3\":0,\"3\":{\"DpId\":3,\"DpIdType\":1,\"DpIdData\":\"00\"}}}\nTYA: fnId=0 is set for dpId=3\n{\"TuyaReceived\":{\"Data\":\"55AA01070005040100010113\",\"Cmnd\":7,\"CmndData\":\"0401000101\",\"DpType1Id4\":1,\"4\":{\"DpId\":4,\"DpIdType\":1,\"DpIdData\":\"01\"}}}\nTYA: fnId=0 is set for dpId=4\n{\"TuyaReceived\":{\"Data\":\"55AA0107000807020004000000001C\",\"Cmnd\":7,\"CmndData\":\"0702000400000000\",\"DpType2Id7\":0,\"7\":{\"DpId\":7,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=7\n{\"TuyaReceived\":{\"Data\":\"55AA0107000808020004000000001D\",\"Cmnd\":7,\"CmndData\":\"0802000400000000\",\"DpType2Id8\":0,\"8\":{\"DpId\":8,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=8\n{\"TuyaReceived\":{\"Data\":\"55AA0107000809020004000000001E\",\"Cmnd\":7,\"CmndData\":\"0902000400000000\",\"DpType2Id9\":0,\"9\":{\"DpId\":9,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=9\n{\"TuyaReceived\":{\"Data\":\"55AA010700080A020004000000001F\",\"Cmnd\":7,\"CmndData\":\"0A02000400000000\",\"DpType2Id10\":0,\"10\":{\"DpId\":10,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=10\n{\"TuyaReceived\":{\"Data\":\"55AA0107000865020004000000007A\",\"Cmnd\":7,\"CmndData\":\"6502000400000000\",\"DpType2Id101\":0,\"101\":{\"DpId\":101,\"DpIdType\":2,\"DpIdData\":\"00000000\"}}}\nTYA: fnId=0 is set for dpId=101\n{\"TuyaReceived\":{\"Data\":\"55AA01070008660200040000009712\",\"Cmnd\":7,\"CmndData\":\"6602000400000097\",\"DpType2Id102\":151,\"102\":{\"DpId\":102,\"DpIdType\":2,\"DpIdData\":\"00000097\"}}}\nTYA: fnId=32 is set for dpId=102\nTYA: Rx ID=102 Current=151\n{\"TuyaReceived\":{\"Data\":\"55AA01070008670200040000017BF8\",\"Cmnd\":7,\"CmndData\":\"670200040000017B\",\"DpType2Id103\":379,\"103\":{\"DpId\":103,\"DpIdType\":2,\"DpIdData\":\"0000017B\"}}}\nTYA: fnId=31 is set for dpId=103\nTYA: Rx ID=103 Active_Power=379\n{\"TuyaReceived\":{\"Data\":\"55AA0107000868020004000009961C\",\"Cmnd\":7,\"CmndData\":\"6802000400000996\",\"DpType2Id104\":2454,\"104\":{\"DpId\":104,\"DpIdType\":2,\"DpIdData\":\"00000996\"}}}\nTYA: fnId=33 is set for dpId=104\nTYA: Rx ID=104 Voltage=2454\n
- Power and current should change on dimming high / low or turning the device on and off. The Tasmota web UI should show power values now on the home page.
"},{"location":"TuyaMCU/#battery-powered-sensors","title":"Battery Powered Sensors","text":" - TYMC-1 Door/Window Sensor
- TY-01 Door/Window Sensor
- Gas Sensor
- Smoke Sensor
- PIR Sensor
"},{"location":"TuyaMCU/#specific-devices","title":"Specific Devices","text":" - Aromatherapy Diffuser
- Water Kettle
- Air Purifier
- Mouse Trap
- Humidifer
"},{"location":"TuyaMCU/#tuya-protocols","title":"Tuya Protocols","text":"The MCU communicates with the Wi-Fi module through the serial port with a Tuya specified protocol. Those are classified into basic and functional protocols.
"},{"location":"TuyaMCU/#basic-protocols","title":"Basic protocols","text":"They are common protocols integrated in Tasmota's TuyaMCU module. They stay the same for each product and are mandatory for Tuya module to work correctly.
"},{"location":"TuyaMCU/#functional-protocols","title":"Functional protocols","text":"Functional protocols are used for delivering and reporting data of functions. These protocols differ between devices and manufacturers and might require configuration in Tasmota using TuyaMCU command or with TuyaSend<x> command.
"},{"location":"TuyaMCU/#anatomy-of-tuya-protocol","title":"Anatomy of Tuya Protocol","text":"Name Description Frame Header Version Fixed value of 0x55aa Command Word 0x06 - send commands0x07 - report status Data Length defines expected length of data dpID numbered ID of a function (DP = Data Point or Define Product) Data Type see Data Type table below Function Length length of command Function Command formatted according to Data Type Verification Method checksum = remainder of the byte sum starting from Frame Header to 256"},{"location":"TuyaMCU/#data-type","title":"Data Type","text":"Hex Tasmota Command Description Max length 0x00 TuyaSend6 raw data unknown 0x01 TuyaSend1 boolean data 0/1 1 byte 0x02 TuyaSend2 value data. If a value contains less than 4 bytes, 0 is supplemented before 4 bytes 0x00 TuyaSend3 string data unknown 0x04 TuyaSend4 enum data 0/1/2/3/4/5 1 byte 0x05 ### fault data, report only 8 bytes Let's dissect and explain the MCU protocol using serial command 55aa0006000501010001010e:
Frame Header Version Command Word Data Length dpID Data Type Function Length Function Command Verification Method 55aa00 06 0005 01 01 0001 01 0e This is the command which powers on the device sending Function Command = 1 to dpID 1 (Switch):
- Frame Header Version =
0x55aa00 which is a fixed value and always the same - Command Word =
0x06 because we're sending a command - Data Type =
0x01 since the command sent is a 1 byte boolean - Function Length =
0x001 instruct 1 character only for function command length - Function Command =
0x01 in hex which equals 1 in int - Verification Method =
0e is calculated
"},{"location":"TuyaMCU/#protocol-flow","title":"Protocol flow","text":"On device boot, TuyaMCU executes the required basic protocols and reads the functional protocol data received, which are used to update status of components mapped in TuyaMCU (Relays, dimmer, power monitoring data).
After receiving a command from Tasmota (Command Word 0x06), the MCU performs corresponding logical control. When the dpID status is changed, the MCU reports the data (Command Word 0x07) to TuyaMCU component.
"},{"location":"TuyaMCU/#dpid-function-tables","title":"dpId Function Tables","text":"This information is just for orientation. Functions are assigned by the manufacturer and can be on different dpId's
- DP ID: dpId.
- Function Point\uff1aUsed to describe the product function.
- Identifier: Function codename. Can only be letters, numbers and underscores
- Data type\uff1a
- Issue and report: command data can be sent and status data can be reported back to the Wi-Fi module
-
Report only: supports only status reporting, no control options
-
Function Type (Referred as Data Type):
- Boolean (bool): non-true or false binary variable, such as: switch function, on / off
- Value (value): suitable for linear adjustment of the type of data, such as: temperature regulation, temperature range 20-40 \u2103
- Enum (enum): custom finite set value, such as: working levels, low / mid / high
- Fault (fault): dedicated to reporting and statistical failure of the function points. Support multi-fault, the data is reported only
- Integer\uff08integer\uff09: transmitted as integer
- Transparent (raw): data in binary
"},{"location":"TuyaMCU/#switches-or-plugspower-strips","title":"Switches or Plugs/Power Strips","text":"DP ID Identifier Data type Function type Properties 1 switch_1 Control and report Boolean 2 switch_2 Control and report Boolean 3 switch_3 Control and report Boolean 4 switch_4 Control and report Boolean 5 switch_5 Control and report Boolean 9 countdown_1 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s 10 countdown_2 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s 11 countdown_3 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s 12 countdown_4 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s 13 countdown_5 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s"},{"location":"TuyaMCU/#aromatherapy-machine-oil-diffuser","title":"Aromatherapy Machine (Oil Diffuser)","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch Power Issue and report Boolean 6 Amount of fog fog Issue and report Enum Enumerated values:small, large 11 Light Light Issue and report Boolean 12 Fault alarm fault Only report Fault Barrier values:1 13 Countdown countdown Issue and report Enum Enumerated values: 0, 1, 2, 3 14 Countdown remaining time countdown_left Only report Integer Values range: 0-360, Pitch1, Scale0, Unit:min 101 Light mode work_mode Issue and report Enum Enumerated values: white, colour, scene, scene1, scene2, scene3, scene4 102 Color value colour_data Issue and report Char type *see below 103 Light mode lightmode Issue and report Enum Enumerated values: 1, 2, 3 104 Brightness setting setlight Issue and report Integer Values range: 0-255, Pitch1, Scale0, Unit:\\% colour_data format of the lights is a string of 14 characters, for example, 00112233334455, where 00 indicates R, 11 indicates G, 22 indicates B, 3333 indicates the hue, 44 indicates the saturation, and 55 indicates the value. The initial value is saved by default. If you do not want to adjust the light, set the data to the maximum value 100% (0x64). The last four characters have fixed values.
"},{"location":"TuyaMCU/#curtain-motor","title":"Curtain Motor","text":"DP ID Function points Identifier Data type Function type Properties 1 Percentage percent_state Only report Integer Values range:0-100, Pitch1, Scale0, Unit:% 2 Motor Direction control_back Issue and report Boolean 3 Auto Power auto_power Issue and report Boolean 4 Left time countdown Issue and report Enum Enumerated values:cancel, 1, 2, 3, 4 5 Total Time time_total Only report Integer Values range:0-120000, Pitch1, Scale0, Unit:m Complete document on protocols
DP ID Function points Identifier Data type Function type Properties 1 Control (required) control Issue and report Enum Enumerated values:open, stop, close, continue 2 Curtain position setting percent_control Issue and report Integer Values range:0-100, Pitch1, Scale0, Unit:% 3 Current curtain position percent_state Only report Integer Values range:0-100, Pitch1, Scale0, Unit:% 4 Mode mode Issue and report Enum Enumerated values:morning, night 5 Motor Direction control_back Issue and report Enum Enumerated values:forward, back 6 Auto Power auto_power Issue and report Boolean 7 Work State (required) work_state Only report Enum Enumerated values:opening, closing 11 Situation_set situation_set Only report Enum Enumerated values:fully_open, fully_close 12 Fault (required) fault Only report Fault Barrier values:motor_fault"},{"location":"TuyaMCU/#power-monitoring-plug","title":"Power Monitoring Plug","text":"DP ID Function points Identifier Data type Function type Properties 1 switch_1 switch_1 Control and report Boolean 9 countdown_1 countdown_1 Control and report Integer undefined0-86400, undefined1, Scale0, Unit:s 17 statistics Function add_ele Control and report Integer undefined0-50000, undefined100, Scale3, Unit: 18 current cur_current Data report Integer undefined0-30000, undefined1, Scale0, Unit:mA 19 power cur_power Data report Integer undefined0-50000, undefined1, Scale1, Unit:W 20 voltage cur_voltage Data report Integer undefined0-5000, undefined1, Scale1, Unit:V 21 test flag test_bit Data report Integer undefined0-5, undefined1, Scale0, Unit: 22 voltage coefficient voltage_coe Data report Integer undefined0-1000000, undefined1, Scale0, Unit: 23 current coefficient electric_coe Data report Integer undefined0-1000000, undefined1, Scale0, Unit: 24 power coefficient power_coe Data report Integer undefined0-1000000, undefined1, Scale0, Unit: 25 statistics coefficient electricity_coe Data report Integer undefined0-1000000, undefined1, Scale0, Unit: 26 warning fault Data report Fault Barrier values:ov_cr"},{"location":"TuyaMCU/#dehumidifier","title":"Dehumidifier","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch Switch Issue and report Boolean 2 PM2.5 PM25 Only report Integer Values range:0-999, Pitch1, Scale0, Unit: 3 Work mode Mode Issue and report Enum Enumerated values:Manual, Auto, Sleep 4 Wind speed Speed Issue and report Enum Enumerated values:speed1, speed2, speed3, speed4, speed5 5 Filter usage Filter Only report Integer Values range:0-100, Pitch1, Scale0, Unit:% 6 Fresh Anion Issue and report Boolean 7 Child lock Lock Issue and report Boolean 9 UV light UV Issue and report Boolean 11 Filter reset FilterReset Issue and report Boolean 12 indoor temp Temp Only report Integer Values range:-20-50, Pitch1, Scale0, Unit:\u2103 13 Indoor humidity Humidity Only report Integer Values range:0-100, Pitch1, Scale0, Unit:%"},{"location":"TuyaMCU/#lighting","title":"Lighting","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch led_switch Control and report Boolean 2 Mode work_mode Control and report Enum Enumerated values:white, colour, scene, scene_1, scene_2, scene_3, scene_4 3 Bright bright_value Control and report Integer undefined25-255, undefined1, Scale0, Unit: 5 Colour mode colour_data Control and report Char type 6 Scene scene_data Control and report Char type 7 Scene1 flash_scene_1 Control and report Char type 8 Scene2 flash_scene_2 Control and report Char type 9 Scene3 flash_scene_3 Control and report Char type 10 Scene4 flash_scene_4 Control and report Char type"},{"location":"TuyaMCU/#contact-sensor","title":"Contact Sensor","text":"DP ID Function points Identifier Data type Function type Properties 1 Door Sensor doorcontact_state Only report Boolean 2 Battery Level battery_percentage Only report Integer Values range:0-100, Pitch1, Scale0, Unit:% 3 Battery Level battery_state Only report Enum Enumerated values:low, middle, high 4 Anti-remove Alarm temper_alarm Only report Boolean"},{"location":"TuyaMCU/#air-purifier","title":"Air purifier","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch Switch Issue and report Boolean 2 PM2.5 PM25 Only report Integer Values range:0-999, Pitch1, Scale0, Unit: 3 Work mode Mode Issue and report Enum Enumerated values:Manual, Auto, Sleep 4 Wind speed Speed Issue and report Enum Enumerated values:speed1, speed2, speed3, speed4, speed5 5 Filter usage Filter Only report Integer Values range:0-100, Pitch1, Scale0, Unit:% 6 Fresh Anion Issue and report Boolean 7 Child lock Lock Issue and report Boolean 9 UV light UV Issue and report Boolean 11 Filter reset FilterReset Issue and report Boolean 12 indoor temp Temp Only report Integer Values range:-20-50, Pitch1, Scale0, Unit:\u2103 13 Indoor humidity Humidity Only report Integer Values range:0-100, Pitch1, Scale0, Unit:%"},{"location":"TuyaMCU/#heater","title":"Heater","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch Power Issue and report Boolean 2 Target temperature TempSet Issue and report Integer Values range:0-37, Pitch1, Scale0, Unit:\u2103 3 Current Temperature TempCurrent Only report Integer Values range:-9-99, Pitch1, Scale0, Unit:\u2103 4 Mode Mode Issue and report Enum Enumerated values:m, p 5 Fault alarm Fault Only report Fault Barrier values:1, 2, 3 6 Gear position gear Issue and report Enum Enumerated values:low, mid, high, off 7 Conservation eco_mode Issue and report Boolean"},{"location":"TuyaMCU/#smart-fan","title":"Smart fan","text":"DP ID Function points Identifier Data type Function type Properties 1 Switch switch Issue and report Boolean 2 Wind Speed Level fan_speed Issue and report Enum Enumerated values:1, 2, 3, 4 3 Left-and-Right Swing fan_horizontal Issue and report Enum Enumerated values:on, off 4 Up-and-Down Swing fan_vertical Issue and report Enum Enumerated values:on, off 5 Fault Alarm fault Only report Fault Barrier values:1, 2 6 Anion anion Issue and report Boolean 7 Humidify humidifier Issue and report Boolean 8 Oxygen oxygan Issue and report Boolean 9 Child Lock lock Issue and report Boolean 10 Cool fan_cool Issue and report Boolean 11 Set Temperate temp Issue and report Integer Values range:0-50, Pitch1, Scale0, Unit:\u2103 12 Current Temperature temp_current Only report Integer Values range:0-50, Pitch1, Scale0, Unit:\u2103"},{"location":"TuyaMCU/#kettle","title":"Kettle","text":"DP ID Function points Identifier Data type Function type Properties 1 Working switch start Issue and report Boolean 2 Heat to target temperature shortcut (\u00b0C) temp_setting_quick_c Issue and report Enum Enumerated values:50, 65, 85, 90, 100 3 Heat to target temperature shortcut (\u00b0F) temp_setting_quick_f Issue and report Enum Enumerated values:122, 149, 185, 194, 212 4 Cool to the target temperature shortcut after boiling (\u00b0C) temp_boiling_quick_c Issue and report Enum Enumerated values:50, 65, 85, 90, 100 5 Cool to the target temperature shortcut after boiling (\u00b0F) temp_boiling_quick_f Issue and report Enum Enumerated values:122, 149, 185, 194, 212 6 Temperature scale switching temp_unit_convert Issue and report Enum Enumerated values:c, f 7 Insulation switch switch_keep_warm Issue and report Boolean 8 Holding time setting keep_warm_setting Issue and report Integer Values range:0-360, Pitch1, Scale0, Unit:min 9 Mode work_type Issue and report Enum Enumerated values: setting_quick, boiling_quick, temp_setting, temp_"},{"location":"TuyaMCU/#becathermostat","title":"BecaThermostat","text":"Work in progress
DP ID Function points Identifier Data type Function type Properties 1 Switch Power Issue and report Boolean 2 Target temperature TempSet Issue and report Integer Values range:0-37, Pitch1, Scale0, Unit:\u2103 3 Current Temperature TempCurrent Only report Integer Values range:-9-99, Pitch1, Scale0, Unit:\u2103 4 Mode Mode Issue and report Enum Enumerated values:m, p (wip) 102 Floor Temperature FloorCurrent Issue and report Integer Values range:0-37, Pitch1, Scale0, Unit:\u2103"},{"location":"TuyaMCU/#inkbird-itc-308-wifi","title":"Inkbird ITC-308-Wifi","text":"Temperature controller with individual plug in sockets for heating/cooling
DP ID Function points Identifier Data type Function type Properties 101 Temperature unit Cf Issue and report Integer 0=C, 1=F 102 Calibration Ca Issue and report Integer Unit is 0.1C 104 Temperature sensor Issue and report Integer Unit is 0.1C 106 Temperature set point Ts Issue and report Integer Unit is 0.1C 108 Compressor delay time Pt Issue and report Integer Unit is minutes 109 Alarm high temperature Ah Issue and report Integer Unit is 0.1C 110 Alarm low temperature Al Issue and report Integer Unit is 0.1C, For negative values use -(0xFFFFFFFF - value) 115 Relay status Only report Integer 01=cool, 02=off, 03=heating 116 Temperature sensor Issue and report Integer Unit is 0.1F 117 Heating differential value Hd Issue and report Integer Unit is 0.1C 118 Cooling differential value Cd Issue and report Integer Unit is 0.1C The unit will constantly be sending the temperature sensor value in celsius and fahrenheit: 104 and 116. To trigger the unit to send all settings, send any value to a non-used register, e.g. TuyaSend1 2,1
Example:
Tasmota command Result TuyaSend1 2,1 Trigger the unit to reveal all settings TuyaSend2 106,250 Change set-point to 25.0C TuyaSend2 101,1 Change units to Fahrenheit"},{"location":"TuyaMCU/#inkbird-ihc-200-wifi","title":"Inkbird IHC-200-Wifi","text":"Humidity controller with two relay sockets very similar to the ITC-308-WIFI This unit ships with a RTL based WR3 module which cannot be flashed with Tasmota, however the WR3 module is pin compatible with an ESP12-F module and is on a daughter board similar to the one in the ITC-308-WIFI
DP ID Function points Identifier Data type Function type Properties 104 Humidity sensor Only report Integer Unit is 0.1C 106 Humidity set point HS Issue and report Integer Unit is 0.1C Dpid 102,108,109,110,106,117,118 return data and are not yet reverse engineered but are likely similar to ITC-308 but related to humidity.
"},{"location":"TuyaMCU/#further-reading","title":"Further Reading","text":" - TuyaMCU Flashing and Device Configuration
"},{"location":"UFS/","title":"Universal File System","text":"This feature is included in every precompiled binary with flash size >1M
For ESP8266 modules that have more than 1MB of flash memory (NodeMCU, Wemos-D1) you can build a variant with a universal file system or UFS and store your files there (data, images, commands, etc). There are some special files that you can upload and use to execute actions.
Warning
The file partition DOES NOT get erased by reset commands. Only a complete flash erase will remove it.
"},{"location":"UFS/#ufs-in-the-web-gui","title":"UFS in the Web GUI","text":"After compiling and flashing you will find a new entry in Tasmota webUI: Consoles - Manage File system
The \"Manage File System\" page provides:
- On top, the total size of the file system and the free size
- A button to upload a file from the host (1st select the file with the
Choose File button, then Start Upload) - A list of available files with timestamp of upload and size in bytes
- The 'fire' icon allows to delete the file without any confirmation
- The 'memo' icon allows to edit the file and the \"Create and edit new file\" button launches the editor with a new file.
The file editor allows to edit the content of a text file online, save it back to the UFS. By changing the name at the top, it will be saved-as the new name (original file remains unchanged). Changes can be discarded by clicking on the button \"Manage File System\" to returns to the manager.
"},{"location":"UFS/#commands","title":"Commands","text":"Complete list of UFS commands
Also look into Berry scripting language for ESP32 which works with UFS.
"},{"location":"UFS/#special-files","title":"Special files","text":""},{"location":"UFS/#autoexecbat","title":"autoexec.bat","text":"Stores commands that will be executed at every boot, similar to the backlog commands in rules trigger at System#Boot.
Almost any command can be used in the file. However, avoid commands that will make the device reboot, such as: changing Wifi setting, MQTT settings, Templates & GPIO, etc. Commands that triggers reboot will create a boot loop which will force Tasmota to automatically disable autoexec.bat and other settings. See SetOption36 for more details.
Commands must be kept one command per line and they will be executed sequentially. Lines starting with semicolon are ignored as comments.
"},{"location":"UFS/#displaybat","title":"display.bat","text":"Stores data that will be displayed at every boot, similar to the DisplayText commands in rules trigger at System#Init (as long as you have a display driver initializated).
Example
; clr screen\n[z]\n; draw full screen picture - corona.rgb file must exist in UFS storage\n[x0y0P/corona.rgb]\n; define index color\n[dc19:31000]\n; draw transparent text with new index color\n[x60y30f2Ci19D2]Tasmota\n
"},{"location":"UFS/#autoexecbe","title":"autoexec.be","text":"For ESP32 with Berry scripting language, autoexec.be file will be automatically loaded and executed at boot.
"},{"location":"UFS/#compiling-for-universal-file-system","title":"Compiling for Universal File System","text":"Copy platformio_override_sample.ini as platformio_override.ini
For ESP8266 boards, activate by removing the ; in front of one of the below lines:
board = esp8266_4M3M for 3Mb universal file systemboard = esp8266_4M2M for 2Mb universal file systemboard = esp8266_2M1M for 1Mb universal file system
About ESP32
ESP32 boards with default 4MB flash only support a file system limited to 320KB. You need a board with more than 4MB to enable a larger file system.
Extending file system size on ESP32 is performed through the board_build.partitions setting. There are preconfigured settings for 4M, 8M and 16MB ESP32 devices. The are enabled in platformio_override.ini like for the ESP8266. Comment the standard setting and uncomment the variant you want.
; Build variant ESP32 4M Flash, Tasmota 1856k Code/OTA, 320k LITTLEFS (UFS) (default)\nboard = esp32_4M\n; Build variant ESP32 8M Flash, Tasmota 2944k Code/OTA, 2112k LITTLEFS (UFS)\n;board = esp32_8M\n; Build variant ESP32 16M Flash, Tasmota 2944k Code/OTA, 10M LITTLEFS (UFS)\n;board = esp32_16M\n
"},{"location":"ULP/","title":"ULP for ESP32","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#define USE_BERRY_ULP // (ESP32, ESP32S2 and ESP32S3 only) Add support for the ULP via Berry (+5k flash)\n
or add as a build flag to any build environment, i.e. in platformio_tasmota_cenv.ini: build_flags = ${env:tasmota32_base.build_flags}\n -DUSE_BERRY_ULP\n
"},{"location":"ULP/#ultra-low-power-coprocessor","title":"Ultra Low Power coprocessor","text":"The purpose of this document is not to repeat every information of these documents: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ulp.html https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ulp_instruction_set.html
It will also not make it easy to write assembler code for the ULP and embed it in Berry projects. But it shall guide you through the process of adapting one of many open source examples, do some little changes and setting up a toolchain for personal use cases.
Tip
It can even make it easier and substantially faster to rapidly develop assembler projects, because there is no flashing involved in the code deployment, which happens in Berry at runtime.
"},{"location":"ULP/#fsm-and-riscv-what","title":"FSM and RISCV ... what?","text":"Currently there are 3 SOC's of the ESP32-family with an included ULP, which are the ESP32, the ESP32S2 and the ESP32S3. The oldest one - the ESP32 - features the simplest type, which Espressif names Finite State Machine or in short FSM. This ULP can only be programmed in assembly. The newer ESP32S2/S3 allow to run the ULP in FSM mode too with some minor additions in the instruction set. They are able ( = should be able in most cases) to use the same assembly source code, but the resulting binaries are not compatible. But additionally both of the new models (ESPS2/S3) are able to run the ULP in RISCV mode, which has a different toolchain and allows to use C as programming language. This makes it a lot easier to work with it. Only one ULP mode possible at a time, so you can run only in FSM or RISCV mode. For Tasmota it was decided to keep things as simple and modern as possible, thus for ESP32S2 and ESP32S3 the old FSM mode is not supported and we enjoy the simplicity of the high level language C.
Bottom line for Tasmota: ESP32 - uses ULP in FSM mode ESP32S2 and ESP32S3 - use ULP in RISCV mode
Tip
Although the main core of the ESP32C3 uses the RISCV architecure, there is no built in ULP at all. For the upcoming ESP32C6 an integrated ULP was anounced, but no further info is available at the moment.
"},{"location":"ULP/#limits-of-the-ulp","title":"Limits of the ULP","text":"To simplify some things: Everything in the ULP is limited. On the old FSM type ULP there are only 4 registers, very few operations and limited memory access. For some operations it is not possible to use mutable values, but the code must be fixed (for pin/register access) at compile time. That's why you will see lots of defines and constants in basically every example project. This was the reason, why for projects like Tasmota it never made sense to include ULP code.
"},{"location":"ULP/#advantages-of-the-ulp","title":"Advantages of the ULP","text":"Besides the possibility to run code in deep sleep and wake up the system, it can also make sense to run the ULP in parallel to the main system. To simplify again: Everything that is critical to precise timing and is somehow portable to ULP, should run better than on the main cores! This includes the internal temperature sensor and the hall sensor. Additionally it can free the main cores of some tasks.
"},{"location":"ULP/#data-exchange-between-main-system-and-ulp","title":"Data exchange between main system and ULP","text":"There is a memory region which is located at fixed address 0x5000000, which is called RTC_SLOW_MEM. This is the only region that is accessible from main cores and the ULP. It is the coders job to find a way to control the data flow, by reading and writing from and to certain addresses. The toolchains down below will print out data, that will show, where accessible variable can be found to access from Berry with ULP.get_mem() and ULP.set_mem().
"},{"location":"ULP/#general-program-flow","title":"General program flow","text":"A typical ULP program is started from the main core at the position of the so called global entry point. Then it executes its chain of commands and ends with a halt command. It is technically possible to create a run loop inside the code and to not end with halt. But typically such a loop is realized with a wakeup timer, that restarts the with a certain interval, which can be set with ULP.wake_period(register,time in microseconds). The register is numbered from 0 to 4 and can be changed in the assembly code with sleep register.
"},{"location":"ULP/#tasmota-conventions","title":"Tasmota conventions","text":"The assembly code can be divided in different sections of which the so called .textsections contains the program, but can hold variables or arbitrary data too. In general for the assembler it is not so important, where the functions or the global entry point is located. But for the FSM in Tasmota the rule is, that the global entry point or a jump to it is located at position 0 in RTC_SLOW_MEM. That way ULP.run() can always point to this address 0. On RISCV ULP's the entry point is always 0. It is a design decision to keep the ULP module as small as possible and the addition of more internal functions shall be avoided, i.e. for doing setup of GPIO/RTC pins. If possible, this should be done in assembly code.
Example
// rtc_gpio_isolate(12) translates to:\nWRITE_RTC_REG(RTC_IO_TOUCH_PAD5_REG, 27, 1, 0) //disable pullup\nWRITE_RTC_REG(RTC_IO_TOUCH_PAD5_REG, 28, 1, 0) //disable pulldown\nWRITE_RTC_REG(RTC_IO_TOUCH_PAD5_REG, 13, 1, 0) //disable input\nWRITE_RTC_REG(RTC_GPIO_ENABLE_W1TS_REG, 29, 1, 0) //disable output\nWRITE_RTC_REG(RTC_IO_TOUCH_PAD5_REG, 31, 1, 1) //hold\n
"},{"location":"ULP/#using-external-toolchains-for-this-driver","title":"Using external toolchains for this driver","text":"There are 2 ways to assemble code for later use in Tasmota. In theory every external ULP project, which fits in the reserved memory space that is defined in the framework package used to compile the Tasmota firmware, should be convertible. This limit is subject to change.
"},{"location":"ULP/#micropython-and-micropython-esp32-ulp-fsm-only","title":"Micropython and micropython-esp32-ulp (FSM only)","text":"Only available for the ESP32 using the FSM type ULP.
A great project to run ULP code in Micropython on the ESP32 can be used to assemble and export the same projects to Tasmota. There are ports of Micropython for Linux, Windows and Mac, which must be installed to the system of your choice. Run it and in the Micropython console install like that:
# MacOS\nimport upip\n# Linux\nimport mip\nupip.install('micropython-esp32-ulp')\n
After that your are ready to assemble. The ULP code is embedded as a multiline string in Micropython scripts. For use in Tasmota it makes sense to make some changes, that are described in an ulp_template.py and to use this template by replacing the source code string with the new code.
Tip
The Micropython module can not really include external headers, but it offers a very convenient database function as described here: link:preprocess Otherwise the missing defines must be added annually.
After you created or did download your ulp_app.py you can export the data with 'micropython ulp_app.py' to the console, from where it can be copy pasted to the Berry console or to your Berry project.
Tip
It is recommended to embed the setup steps for GPIO pins or ADC to the bottom part of this ulp_app.py by printing Berry commands for easier testing in the Berry console.
"},{"location":"ULP/#export-from-esp-idf-project","title":"Export from ESP-IDF project","text":"This is the only way, that works for every ULP version in Tasmota.
Many projects are using the ESP-IDF with CMAKE and will be compiled with idf.py build. We can extract the ULP code without flashing this project, with two simple methods:
"},{"location":"ULP/#python-script-bins2berrypy","title":"Python script 'binS2Berry.py'","text":"Start a helper Python binS2Berry.py script in the root level of the project, which prints the same information to console as the Micropython way.
"},{"location":"ULP/#web-app","title":"Web-App:","text":"Use the embedded JS application right here.
ESP-IDF build folder:
(You can drag and drop the folder on the button too.)
# Generate ULP code in your browser !! Parsing completely in JS, no file upload to a server.\n
Thus the ULP projects that may fail to assemble in Micropython can be used too. Additionally it can be helpful, to test the ULP code in a minimal working example outside of Tasmota.
"},{"location":"ULP/#examples","title":"Examples","text":"This is all about porting and adapting existing code. Thank you to everyone who is sharing their ULP code!!
"},{"location":"ULP/#blink-an-led-fsm","title":"Blink an LED - FSM","text":"Let's take a look at https://github.com/micropython/micropython-esp32-ulp/blob/master/examples/blink.py.
- Use a copy of ulp_template.py and name it to your liking.
- Replace the
source string of the template with the version of the example. The .textsection starts with: .text\nmagic: .long 0\nstate: .long 0\n
this must become: .text\njump entry\nmagic: .long 0\nstate: .long 0\n
- This is already enough to assemble. For convenience it is recommended to add a line to the last section (with multiple \"prints\") with content:
print(\"ULP.wake_period(0, 500000)\").
Done!
Now let's modify the code slightly for different intervals for \"on\" and \"off\".
- Add a second wake period with
print(\"ULP.wake_period(1, 200000)\"). - Add
sleep commands to the source code like so: on:\n# turn on led (set GPIO)\nWRITE_RTC_REG(RTC_GPIO_ENABLE_W1TS_REG, RTC_GPIO_ENABLE_W1TS_S + gpio, 1, 1)\nsleep 0\njump exit\n\noff:\n# turn off led (clear GPIO)\nWRITE_RTC_REG(RTC_GPIO_ENABLE_W1TC_REG, RTC_GPIO_ENABLE_W1TC_S + gpio, 1, 1)\nsleep 1\njump exit\n
The console output should look something like that:
#You can paste the following snippet into Tasmotas Berry console:\nimport ULP\nULP.wake_period(0,500000) # on time\nULP.wake_period(1,200000) # off time \nvar c = bytes().fromb64(\"dWxwAAwAaAAAAAAADAAAgAAAAAAAAAAAEACAcgEAANDlryxyMABAgCcFzBkABWgdEACAcuGvjHIBAABoIQCAcgQAANASAIByCAAgcAQAAGgBAAWCWAAAgAQFaB0AAACSZAAAgAUFaB0BAACSZAAAgAAAALA=\")\nULP.load(c)\nULP.run()\n
After executing it the built in LED should blink (if wired to the usual GPIO 2). You can change the wake intervals on-the-fly with i.e. ULP.wake_period(1, 800000) in the Berry console.
Now on to something more complex with wake from deep sleep.
"},{"location":"ULP/#hall-sensor-fsm","title":"Hall sensor - FSM","text":"We have a working example here: https://github.com/duff2013/ulptool/blob/master/src/ulp_examples/ulp_hall_sensor/hall_sensor.s
Converting is possible in the same manner as before. Start with ulp_template.py, replace the string with the content of the .s file and make sure you have the include database properly populated or you add the missing defines from the header files manually. Additionally we need to setup the ADC pins with the help of ULP.adc_config(). In this particular example the resulting code is (in the form of print outputs placed in the .py file):
print(\"ULP.adc_config(0,2,3)\") # adc1_config_channel_atten(ADC1_CHANNEL_0, ADC_ATTEN_DB_6);\nprint(\"ULP.adc_config(3,2,3)\") # adc1_config_channel_atten(ADC1_CHANNEL_3, ADC_ATTEN_DB_6); + adc1_config_width(ADC_WIDTH_BIT_12);\n
The entry point is already at address zero, so there are no changes needed to assemble, load and start he ULP program in Tasmota. In the console output we can find the positions of the variables which hold the voltage measurements and can read out it values:
0000 entry\n0051 jmp_threshold\n0052 exit\n0053 wake_up\n0059 Sens_Vp0\n0060 Sens_Vn0\n0061 Sens_Vp1\n0062 Sens_Vn1\n0063 Sens_Diff_p1\n0064 Sens_Diff_n1\n
In order to use this whole construction to wake the ESP32 with the help of a magnet, we now have to do some measurements to find feasible threshold values. This can be done by calculating the difference between Sens_Vpx and Sens_Vnx in Berry. Then place the magnet of your choice near the ESP32 and note how these values change. If the magnet is strong enough, chances are great, that you find a stable threshold. Now let's add some assembly code!
We can add some constants in the header part of the code (that worked with a tested weak magnet):
.set threshold_pos , 7\n.set threshold_neg , 2\n
Now append some variables to the end of the .bss section:
.global Sens_Diff_p1\nSens_Diff_p1:\n.long 0\n\n.global Sens_Diff_n1\nSens_Diff_n1:\n.long 0\n
The we need some code, which replaces line 135 and 136 of the original example:
/* calculate differences */\nmove r3, Sens_Vn1\nld r3, r3, 0\nmove r2, Sens_Vn0\nld r2, r2, 0\nsub r3, r2, r3 # eventually change to sub r3, r3, r2 for your setup\nmove r2, Sens_Diff_n1\nst r3,r2,0\nmove r3, Sens_Vp1\nld r3, r3, 0\nmove r2, Sens_Vp0\nld r2, r2, 0\nsub r3, r3, r2 # eventually change to sub r3, r2, r3 for your setup\nmove r2, Sens_Diff_p1\nst r3,r2,0\n\n/* wake up */\nld r0,r2,0 # Sens_Diff_p1\nJUMPR wake_up, threshold_pos, GE\n
After loading and starting you can send the ESP to deep sleep. For testing it is recommended to add the optional wake timer as a fallback: ULP.sleep(30)
Try to wake up the system with the magnet.
But is there a way to circumvent the limitation of this example, that forces us to set the threshold value as a constant? Well ... yes, we can do some hacky stuff.
We must dig a little deeper, to understand how the 32-bit instructions are constructed. Let's look at the jumpr command, which is defined in ulp.h like that:
struct {\nuint32_t imm : 16; /*!< Immediate value to compare against */\nuint32_t cmp : 1; /*!< Comparison to perform: B_CMP_L or B_CMP_GE */\nuint32_t offset : 7; /*!< Absolute value of target PC offset w.r.t. current PC, expressed in words */\nuint32_t sign : 1; /*!< Sign of target PC offset: 0: positive, 1: negative */\nuint32_t sub_opcode : 3; /*!< Sub opcode (SUB_OPCODE_B) */\nuint32_t opcode : 4; /*!< Opcode (OPCODE_BRANCH) */\n} b; /*!< Format of BRANCH instruction (relative address, conditional on R0) */\n
The constant (= immediate) value is stored in the upper 16 bits and we can access in the byte buffer. To find the address of the command we can simply add a label in the code:
.global jmp_threshold\njmp_threshold:\nJUMPR wake_up, threshold_pos, GE\n
This will get printed to the console while assembling. Then in Berry we can do a:
var c = bytes(\"...\")\n# jmp_threshold is the 32-bit-address in RTC_SLOW_MEM\nvar jmp_threshold = 51\nvar pos = (3+jmp_threshold)*4\nvar cmd = c[pos..pos+4] # we do not have uint32 in Berry\ncmd.set(0,threshold,2) # upper 16 bit\nULP.set_mem(51,cmd.get(0, 4)) # modify running ULP program\n
Now we can change these constant values on the fly.
"},{"location":"ULP/#example-driver-in-berry-allowing-deep-sleep-with-wake-up-via-magnet","title":"Example driver in Berry allowing deep sleep with wake up via magnet:","text":"Add commands: hall_thres x - shows current threshold for the p difference value or sets it to x. usleep x - start deep sleep for x seconds or infinitely
ulp_hall.be
"},{"location":"ULP/#i2c-access-fsm","title":"I2C access - FSM","text":"Although there are special assembler commands to access I2C devices the most common method in the examples on GitHub is bit banging. This is reported to be more reliable and circumvents some limitations (only 2 pin combinations and bytewise access with special I2C commands). Nearly every example is based on some very clever macros and control flow tricks, that replicate a simple stack and subroutines (similar to a library), which is a good example for the \"Art of coding\". To make it assemble in Micropython we need some functions in the Micropython-script, that can expand the macros. These functions are in a very early stage of development and might eventually later find their way into the micropython-esp32-ulp project after more refinement.
Tip
If your examples do not assemble in Micropython, please try out the ESP-IDF variant.
An example for the BH-1750 light sensor can be found here: https://github.com/duff2013/ulptool/tree/master/src/ulp_examples/ulp_i2c_bitbang
With our techniques from above the concatenation of the .s files results in: BH-1750
"},{"location":"ULP/#example-berry-driver","title":"Example Berry driver:","text":"ulp_bh1750.be
"},{"location":"Upgrading/","title":"Upgrading","text":"Easily upgrade Tasmota to a newer version or different build while keeping all your settings
The first rule of upgrading: If it ain't broke, don't fix it!
In other words, ensure that there is a good reason to mess with a working installation (e.g., a need to use a new feature or address a found problem fixed in the current version).
Backup before upgrading
Any time you upgrade it is highly recommended to back up your device settings. That is easily done from the webUI using Configuration - Backup Config.
If you wish to switch to a different build or use development branch you need to download a binary file (gzipped or regular) or change the OTA Url link.
Download binaries from:
- Official firmware server:
- Current release
- Development branch
- Older release binaries: 9.1.0, 8.5.1, 7.2.0, 6.7.1. You can build a similar URL for another release.
- Your personal OTA server
"},{"location":"Upgrading/#gz-binaries","title":".gz binaries","text":"Gzipped binaries can be used only once you've upgraded to atleast Tasmota 8.2
Trying to upgrade with a gzipped binary using versions older than 8.2 will fail.
Tasmota 8.2 introduced upgrading using gzipped binaries which are smaller in size and will likely skip the intermediary minimal build installation. This makes the upgrade process faster and straightforward.
To use simply add .gz to the existing OTA Url or download the .bin.gz binary from the official OTA Server and the next upgrade will use the compressed file.
"},{"location":"Upgrading/#upgrade-flow","title":"Upgrade Flow","text":"v1.0.11 v3.9.22 v4.2.0 v5.14.0 v6.7.1 v7.2.0 v8.5.1 v9.1 Current release
Follow the path strictly to ensure success. Do not install only tasmota-minimal.bin but upgrade to full, working firmware. Linked -lite.bin binaries will do the job. If you want to download binaries from the upgrade flow links, you may need to do a right-click and save the file, depending on your browser security rules.
Tasmota v9.1 introduced a major change in GPIO mapping
Downgrading is not recommended and will probably not work correctly.
Tasmota v8.1 introduced a major change in parameter storage.
Downgrading is not recommended and upgrading to 8.1 has to follow the recommended path and can still fail in some cases. Don't forget to backup!
"},{"location":"Upgrading/#upgrade-using-webui","title":"Upgrade using webUI","text":"Upgrading the device firmware over-the-air, aka OTA, is the most convenient way to upgrade.
To start the upgrade, open a web browser to your device's web UI and select Firmware Upgrade.
You are presented with two choices:
- Upgrade by webserver - use an OTA server
- Upgrade by file upload - uploading a downloaded or self-compiled binary file from your computer
"},{"location":"Upgrading/#upgrade-by-web-server","title":"Upgrade by web server","text":"If you want to upgrade to the latest release version click the first Start Upgrade button. This screen should appear
During this process Tasmota will download the new firmware from the url and install it. If you're not using a gzipped binary it might need to download tasmota-minimal.bin first, but all that happens automatically. All you have to do is wait 2 to 5 minutes.
After the upgrade is completed you can reconnect back to the web UI and check the firmware version on the bottom of the page or in the Information tab of the webUI.
"},{"location":"Upgrading/#upgrade-by-file-upload","title":"Upgrade by file upload","text":"Go to Firmware Upgrade. This time browse to the binary you want to upgrade to with Choose File and click Start upgrade. In our example it's tasmota-sensors.bin.
You will see an Upload starting... and then Upload successful message. Wait until the device restarts, reconnect back to the web UI and check the firmware version on the bottom of the page or in the Information tab of the webUI.
Minimal build upgrade step
If the binary you're upgrading with is larger than 500kb you also need to download the minimal build (tasmota-minimal.bin(.gz)) since the upload process needs the space in flash memory to upload the new binary.
When you try to immediately upgrade with the new binary without using smaller minimal firmware you will be greeted with this error.
"},{"location":"Upgrading/#upload-buffer-miscompare-error","title":"Upload Buffer Miscompare Error","text":"This step is necessary only if you get the \"Upload buffer miscompare\" error
This means your flash doesn't have enough free space to install the binary you're trying to upload. Use a .gz binary instead of the .bin one. If you still receive the same error download tasmota-minimal.bin(.gz) and follow instructions:
Browse to the minimal binary with Choose File. The chosen filename should be visible. In our example it's tasmota-minimal.bin.
Wait until the device restarts. In the Main Menu web UI will display this warning message on top.
Proceed to upgrade
"},{"location":"Upgrading/#using-commands","title":"Using Commands","text":"Your device can be upgraded using commands via MQTT, web requests or Console in the web UI.
OtaUrl is used to set your OTA address.
OtaUrl http://ota.tasmota.com/tasmota/tasmota-sensors.bin\n
In this example we chose a development branch version with additional sensors support Initiate upgrade from OTA server
Upgrade 1\n
Wait for the upgrade process to complete and check the Tasmota version. In console you can use Status 2."},{"location":"Upgrading/#serial-upgrade","title":"Serial Upgrade","text":"Upgrade over the serial connection using serial-to-USB adapter.
Upload the new version over serial using the same process as in Flashing but DO NOT erase flash. The new binary will overwrite the old one and keep your settings.
"},{"location":"Upgrading/#external-programs","title":"External Programs","text":"Tasmota Device Manager or TDM is a multiplatform GUI application written in Python for discovery and management of Tasmota devices. You can set up OTA url and initiate OTA upgrade from TDM using GUI.
openHAB - implement an automation rule to upgrade devices from openHAB
Node-RED OTA server and firmware manager - Node-RED flow for managing OTA updates
OTA over SCP - setup and configure \"OTA over SCP\" upload for PlatformIO
Deploy via HTTP - deploy .bin and .bin.gz files to your own web server via PlatformIO upload
"},{"location":"Upgrading/#private-ota-server","title":"Private OTA Server","text":"It is possible to create your own simple http OTA server (https is not supported) using Python and perform upgrades from there. Install Python3 and from the folder where the binary resides (make sure tasmota-minimal.bin is located there too) run:
python -m http.server 8000\n
(If the response is \"No module named http\" then try again with python3 instead of python.) Change your OtaUrl to http://ipoftheserver:8000/yourbinary.bin(.gz) and start the upgrade process. Note: do not use /, -, or . characters in the name of yourbinary.
If your binary build (yourbinary.bin) is larger than the available free flash program space, Tasmota will need to first install the minimal version of Tasmota to make more space. To have this work via the web server OTA process, you have to copy the file tasmota-minimal.bin in the same folder where OTAURL for yourbinary.bin is placed, and rename tasmota-minimal.bin to yourbinary-minimal.bin.
"},{"location":"Upgrading/#migration-path","title":"Migration Path","text":"Until now several versions of Tasmota have been released starting with the C version Sonoff-MQTT-OTA followed by Sonoff-MQTT-OTA-Arduino, Sonoff-Tasmota and ultimately Tasmota.
Intermediate upgrade steps are needed to migrate from older firmware to the current version. No migration is possible from original Sonoff-MQTT-OTA to Sonoff-MQTT-OTA-Arduino v1.0.11.
DO NOT ATTEMPT TO UPGRADE VERSIONS PRIOR TO v7.x STRAIGHT TO THE CURRENT VERSION
Remember that you must take each individual step between the device firmware version and the latest available.You can find all the required binaries in Tasmota Releases listed by version number.
Tip
As a safeguard perform \"Backup Configuration\" before upgrading. If settings are lost \"Restore Configuration\" should bring them back.
Upgrading from one minor version to the next is mostly painless as the settings are saved in the same location in flash and newer settings are appended.
As said, mostly painless! There are some deviations to this rule as the flash settings changed.
Notice for versions between 6.6.0.7 and 6.6.0.11
If you've used development versions between 6.6.0.7 and 6.6.0.11 back up your device settings. Convert the backup to human readable form as you MUST restore these settings manually. Perform a Reset 6 before upgrading the firmware and, for safe measure, after the upgrade completes.
"},{"location":"Upgrading/#downgrading","title":"Downgrading","text":"While fallback or downgrading is common practice it was never supported due to Settings additions or changes in newer releases.
Starting with release v8.1.0 Doris settings in flash are re-allocated in such a way that fallback is only allowed and possible to v7.2.0. Once at v7.2.0 you're on your own when downgrading even further.
"},{"location":"Upgrading/#backing-up-settings","title":"Backing Up Settings","text":"Tasmota uses flash memory to store options and settings. New versions add (or remove) features that use various regions of that memory. If you did not erase flash when you flashed your device, an updated version of Tasmota may be accessing areas with values left over from the old Tasmota or even the original factory firmware. This might cause unexpected and unwanted behavior or even major problems (constant reboots or reconnects).
To avoid this use our decode-config tool to easily create and restore backups in Tasmota:
"},{"location":"Upgrading/#decode-config-tool","title":"decode-config tool","text":" - decode-config - OS independent Python program to backup and restore Tasmota configuration data, also available as precompiled executables for Windows, MacOS and Linux. See Using instructions for details. If using one of the precompiled binary for your OS replace
decode-config.py with decode-config_win32.exe, decode-config_win64.exe, decode-config_mac or decode-config_linux from the instruction examples.
"},{"location":"Upgrading/#1-make-a-configuration-backup","title":"1. make a configuration backup:","text":" -
Create a new backup straight from your device
decode-config.py --source <deviceIP> --backup-file Config-@f
@f will be replaced by decode-config to device's FriendlyName
or
- Create a backup from previously made
.dmp file
decode-config.py --source <dmp_filename> --backup-file Config-@f
"},{"location":"Upgrading/#2-perform-a-device-reset","title":"2. perform a device reset","text":"Erase flash settings area but keep Wi-Fi and MQTT settings
Reset 6
"},{"location":"Upgrading/#3-upgrade-the-firmware-via-ota-or-file-upload","title":"3. upgrade the firmware via OTA or file upload","text":""},{"location":"Upgrading/#4-restore-configuration","title":"4. restore configuration","text":"decode-config.py --source <deviceIP> --restore-file <backupfile>
...and you're done!
If you can't restore configuration directly you can configure the device manually referring to the Commands article and the settings (e.g., SetOptions, Rules, etc.) in the JSON file you created in step #1. You can paste the JSON into a JSON parser to make it easily readable.
Tip
If Backup Configuration -> Restore Configuration fails, reset to firmware defaults and use decode-config tool to restore your backed up configuration.
"},{"location":"User-created-templates/","title":"User created templates","text":"Follow this link to new templates repository.
"},{"location":"VEML6070/","title":"VEML6070 UV light sensor","text":"This feature is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_VEML6070\n#define USE_VEML6070 // [I2cDriver12] Enable VEML6070 sensor (I2C addresses 0x38 and 0x39) (+1k5 code)\n#define USE_VEML6070_RSET 270000 // VEML6070, Rset in Ohm used on PCB board, default 270K = 270000ohm, range for this sensor: 220K ... 1Meg\n#define USE_VEML6070_SHOW_RAW // VEML6070, shows the raw value of UV-A\n#endif\n
This little sensor is a great way to add UV light sensing to any microcontroller project. The VEML6070 from Vishay has a true UV A light sensor and an I2C-controlled ADC that will take readings and integrate them for you over ~60ms to 500ms.\" See VEML6070 UV Sensor for more information.
"},{"location":"VEML6070/#configuration","title":"Configuration","text":""},{"location":"VEML6070/#wiring","title":"Wiring","text":"VEML6070 ESP GND GND VCC 3.3V SDA GPIOx SCL GPIOy"},{"location":"VEML6070/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
"},{"location":"VEML6070/#tasmota-main","title":"Tasmota Main","text":"After a reboot the driver will detect VEML6070 automatically and display UV light intensity.
"},{"location":"VEML6070/#breakout-boards","title":"Breakout Boards","text":""},{"location":"VEML6075/","title":"VEML6075 UVA/UVB/UVINDEX Sensor","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_VEML6075\n#define USE_VEML6075 // [I2cDriver49] Enable VEML6075 UVA/UVB/UVINDEX Sensor (I2C address 0x10) (+2k1 code)\n#endif\n
This little sensor is a great way to add UVA and UVB light sensing to any microcontroller project. The VEML6075 from Vishay has both true UVA and UVB band light sensors and an I2C-controlled ADC that will take readings and integrate them. The sensor also comes with calibration registers so you can easily convert the UVA/UVB readings into the UV Index.
"},{"location":"VEML6075/#configuration","title":"Configuration","text":""},{"location":"VEML6075/#wiring","title":"Wiring","text":"VEML6075 ESP GND GND VCC 3.3V SDA GPIOx SCL GPIOy"},{"location":"VEML6075/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
"},{"location":"VEML6075/#commands-and-use","title":"Commands and Use","text":"Console Commands Description values VEML6075power Power on/off the module 0/1 VEML6075inttime UV integration time (50ms, 100ms, 200ms, 400ms, 800ms) 0/1/2/3/4 VEML6075dynamic dynamic setting (low, high) 0/1"},{"location":"VEML6075/#tasmota-main","title":"Tasmota Main","text":"After a reboot the driver will detect VEML6075 automatically and display UVA/UVB/UVindex intensity.
"},{"location":"VEML6075/#breakout-boards","title":"Breakout Boards","text":""},{"location":"VEML7700/","title":"VEML7700 Ambient light sensor","text":"This feature is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_VEML7700\n#define USE_VEML7700 // [I2cDriver50] Enable VEML7700 Ambient Light sensor (I2C addresses 0x10) (+4k5 code)\n#endif\n
VEML7700 is a high accuracy ambient light digital 16-bit resolution sensor in a miniature transparent 6.8 mm x 2.35 mm x 3.0 mm package. It includes a high sensitive photo diode, a low noise amplifier, a 16-bit A/D converter and supports an easy to use I2C bus communication interface. The ambient light result is available as digital value.
"},{"location":"VEML7700/#configuration","title":"Configuration","text":""},{"location":"VEML7700/#wiring","title":"Wiring","text":"VEML7700 ESP GND GND VCC 3.3V SDA GPIOx SCL GPIOy"},{"location":"VEML7700/#tasmota-settings","title":"Tasmota Settings","text":"In the Configuration -> Configure Module page assign:
- GPIOx to
I2C SDA - GPIOy to
I2C SCL
"},{"location":"VEML7700/#commands-and-use","title":"Commands and Use","text":"Console Commands Description values VEML7700power Power on/off the module 0/1 VEML7700inttime Integration time in ms 25, 50, 100, 200, 400, 800 VEML7700gain Gain setting (x1, x2, x1/8, x1/4) 0 = x11 = x2 2 = x1/8 3 = x1/4 VEML7700persist ALS persistence protect number setting 0 = 1 1 = 2 2 = 43 = 8 With gain 1/8 and inttime 25 the sensor goes up to 120.000 Lux if someone needs it.
"},{"location":"VEML7700/#tasmota-main","title":"Tasmota Main","text":"After a reboot the driver will detect VEML7700 automatically and display light intensity.
"},{"location":"VEML7700/#breakout-boards","title":"Breakout Boards","text":""},{"location":"VL53Lxx/","title":"VL53L0X and VL53L1X laser ranging modules","text":"Support for VL53L0X is included only in tasmota-sensors and tasmota32 binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_VL53L0X \n#define USE_VL53L0X // [I2cDriver31] Enable VL53L0x time of flight sensor (I2C address 0x29) (+4k code)\n#define VL53L0X_XSHUT_ADDRESS 0x78 // VL53L0X base address when used with XSHUT control\n#endif\n
Support for VL53L1X is not included in precompiled binaries When compiling your build add the following to user_config_override.h:
#ifndef USE_VL53L1X \n#define USE_VL53L1X // [I2cDriver54] Enable VL53L1X time of flight sensor (I2C address 0x29) using Pololu VL53L1X library (+2k9 code)\n#define VL53L1X_XSHUT_ADDRESS 0x78 // VL53L1X base address when used with XSHUT control\n#define VL53L1X_DISTANCE_MODE Long // VL53L1X distance mode : Long | Medium | Short\n#endif\n
The VL53L0X and VL53L1X are Time-of-Flight (ToF) laser-ranging devices from ST MicroElectronics commonly available on small modules.
In the documentation below, VL53LXX is used whenever the information applies to either VL53L0X or VL53L1X. The exact name is used for any information that is specific to the specific model.
"},{"location":"VL53Lxx/#the-devices","title":"The devices","text":"About how to install those sensor and how to adapt the laser operation for several use-cases, please check:
- Datasheet VL53L0X
- Datasheet VL53L1X
Characteristic VL53L0X VL53L1X Unit Max distance 2000 4000 mm Field of vision 25 27 \u00b0 For more details on the supported distance range depending on the mode, the reflectance of the object and the ambient light regarding the different modes, please refer to the datasheets.
If you are going to use long I2C wires read this article
"},{"location":"VL53Lxx/#breakout-boards","title":"Breakout Boards","text":"Sample boards for VL53L0X. Similar boards exist for VL53L1X.
"},{"location":"VL53Lxx/#configuration-for-single-sensor","title":"Configuration for single sensor","text":""},{"location":"VL53Lxx/#wiring-for-single-sensor","title":"Wiring for single sensor","text":"VL53LXX ESP GND GND VCC 3.3V SDA GPIOa SCL GPIOb"},{"location":"VL53Lxx/#tasmota-settings-for-single-sensor","title":"Tasmota Settings for single sensor","text":"In order to use a VL53LXX sensor you need to: - configure ESP GPIOs for I2C bus - enable the right driver
"},{"location":"VL53Lxx/#step-1-configure-i2c","title":"Step 1 - Configure I2C","text":"In the Configuration -> Configure Module page assign:
- GPIOa to
I2C SDA - GPIOb to
I2C SCL
On ESP8266 almost any GPIO can be used for I2C except for GPIO15. However the standard is to use GPIO4 (D1) for I2C SCL and GPIO5 (D2) for I2C SDA.
On ESP32 any pin can be assigned to I2C.
"},{"location":"VL53Lxx/#step-2-enable-the-proper-driver","title":"Step 2 - Enable the proper driver","text":"I2C devices are identified on the I2C bus by their address. Because the number of possible addresses are limited (127) a lot of devices are sharing the same address. This as means that it is not possible to use simultaneously on the same I2C bus 2 devices that are using the same address. Beside, in most cases, a driver cannot correctly identify the chip it is talking to. This is why in most of the case it is important to disable Tasmota drivers for devices that you are not using and leave enabled only driver for a device you are going to use.
In the list of I2CDEVICES supported by Tasmota it is listed that the address 0x29 can be used by either TSL2561 (driver 16), VL53L0X (driver 31), TSL2591 (driver 40) and VL53L1X (driver VL53L1X). It means that you can't use a TSL2561 or a TSL2591 at the same time as a VL53L0X/VL53L1X. And you can't use a VL53L0X at the same time as a VL53L1X.
If you have build a tasmota binary that include the driver for TSL2561 and/or TSL2591 you must disable those drivers. You must also disable the driver for the other VL53LXX device. As a summary, here are the command to type in the console:
- To use a VL53L0X :
backlog i2cdriver16 0;i2cdriver40 0;i2cdriver31 1;i2cdriver54 0 - To use a VL53L1X :
backlog i2cdriver16 0;i2cdriver40 0;i2cdriver31 0;i2cdriver54 1
After a reboot Tasmota will detect the VL53LXX automatically is the proper driver has been enabled.
Sensor sends a tele/%topic%/SENSOR JSON response:
For VL53L0X:
{\"Time\":\"2019-12-20T11:29:22\",\"VL53L0X\":{\"Distance\":263}}\n
Or for VL53L1X {\"Time\":\"2019-12-20T11:29:22\",\"VL53L1X\":{\"Distance\":263}}\n
"},{"location":"VL53Lxx/#configuration-for-multiple-vl53lxx-sensors-in-parallel","title":"Configuration for Multiple VL53LXX sensors in parallel","text":"Tasmota supports by default up to 8 of these sensors in parallel. Note that they all must be of the same model (either all VL53L0X or all VL53L1X). In any case, the above I2C GPIO and I2C driver configuration remain valid.
When using multiple VL53LXX, it is required to wire the XSHUT pin of each sensors to a dedicated free GPIO and assign as VL53LXX XSHUT 1 to 8. This is to let Tasmota change by software the I2C address of those and give them an unique address for operation. The sensor don't save its address and this procedure is performed automatically at every restart. The Addresses used for this are by default 0x78 (120) to 0x7F (127). As for a single sensor, you must not use any other I2C device on those addresses. As the date of writing, there is currently no I2C device supported by Tasmota with those addresses. However such devices exists and may be supported by later versions of Tasmota. You can change the relocation address by a compile option, see the compile options section.
"},{"location":"VL53Lxx/#wiring-for-multiple-sensors","title":"Wiring for Multiple Sensors","text":"VL53LXX-1 VL53LXX-2 VL53LXX-3 ... ESP GND GND GND GND GND VCC VCC VCC VCC 3.3V SDA SDA SDA SDA GPIOa SCL SCL SCL SCL GPIOb XSHUT - - - GPIOc - XSHUT - - GPIOd - - XSHUT - GPIOe - - - XSHUT GPIOz On ESP8266, please refer to the guide Expending Tasmota for suitable GPIOs. GPIO 1 and 3 being used by serial console are generally unadvised. GPIO15 has a pull-down on every ESP board to allow proper boot. If you want to use this GPIO for a XSHUT, you must remove the pull-up resistor that is on the VL53LXX module otherwise your ESP will not boot.
On ESP32 any GPIO that can be an output can be used.
"},{"location":"VL53Lxx/#tasmota-settings-for-multiple-sensors","title":"Tasmota Settings for multiple sensors","text":"In the Configuration -> Configure Module page assign:
- GPIOa to
I2C SDA - GPIOb to
I2C SCL - GPIOc to
XSHUT 1 - GPIOd to
XSHUT 2 - GPIOe to
XSHUT 3 - ...
After a reboot Tasmota will detect each VL53LXX in sequence and after auto-configuring them, it will display distance in mm.
Example: for VL53L0X it sends tele/%topic%/SENSOR JSON such as:
{\"Time\":\"2019-12-20T11:29:22\",\"VL53L0X_1\":{\"Distance\":263},\"VL53L0X_2\":{\"Distance\":344},\"VL53L0X_3\":{\"Distance\":729}}\n
With VL053L1X, the name of the sensor is adapted.
The index separator is either a - if SetOption4 is 0 or a _ if it is 1. See SetOption4.
"},{"location":"VL53Lxx/#compile-options","title":"Compile options","text":""},{"location":"VL53Lxx/#general","title":"General","text":" -
MAXIMUM AMOUNT OF SENSORS: Tasmota supports by default up to 8 of these sensors in parallel. Expanding this limit is possible but backwards incompatible. The default value of VL53LXX_MAX_SENSORS is set in the file tasmota.h
-
XHUT Relocation address The addresses at which the VL53LXX are relocated when using XSHUT can be changed by a define in user_config_override.h file. Replace the 0x78 for the 1st address. You need that as many consecutives address are free for the number of devices you are using. For VL53L0X use:
#define VL53L0X_XSHUT_ADDRESS 0x78\n
For VL53L1X use: #define VL53L1X_XSHUT_ADDRESS 0x78\n
"},{"location":"VL53Lxx/#vl53l0x-options","title":"VL53L0X options","text":" -
VL53L0X LONG RANGE: By default VL53L0X reads up to 1.2 meters. If you want to use the long range mode (up to 2.2 meters), you need to add a define in user_config_override.h file:
#define VL53L0X_LONG_RANGE\n
This increases the sensitivity of the sensor and extends its potential range, but increases the likelihood of getting an inaccurate reading because of reflections from objects other than the intended target. It works best in dark conditions. -
VL53L0X_HIGH_SPEED vs VL53L0X_HIGH_ACCURACY Either or the other can be added in user_config_override.h file to change the default compromise to either proceed at higher speed (but at the cost of accuracy) or at higher accuracy.
#define VL53L0X_HIGH_SPEED\n
or #define VL53L0X_HIGH_ACCURACY\n
"},{"location":"VL53Lxx/#vl53l1x-options","title":"VL53L1X options","text":""},{"location":"Visual-Studio-Code/","title":"Visual Studio Code","text":"How to setup and configure Visual Studio Code with PlatformIO for Tasmota compilation and upload.
"},{"location":"Visual-Studio-Code/#easy-way-only-windows-portable-install-of-visual-studio-code-for-tasmota","title":"Easy way (only Windows): Portable install of Visual Studio Code for Tasmota","text":"Download the ready made Portable Installation of VSC/PlatformIO and extract the ZIP to a folder or a fast extern drive. Grab Tasmota unpack and Start VS Code.exe (in folder VSC)
"},{"location":"Visual-Studio-Code/#full-install-windows-linux-and-mac","title":"Full Install (Windows, Linux and Mac)","text":""},{"location":"Visual-Studio-Code/#download-and-install-visual-studio-code","title":"Download and Install Visual Studio Code","text":"Download Visual Studio Code (VSC) from https://code.visualstudio.com/
"},{"location":"Visual-Studio-Code/#install-platformio-extension","title":"Install PlatformIO Extension","text":"Install the PlatformIO IDE extension in VSC.
Select View - Extensions and type PlatformIO in the search box.
Make sure to select the official PlatformIO.org PlatformIO IDE extension and select Install. Accept to install dependencies.
"},{"location":"Visual-Studio-Code/#download-tasmota","title":"Download Tasmota","text":"Download the latest Tasmota version from https://github.com/arendst/Tasmota and unzip to a known folder.
"},{"location":"Visual-Studio-Code/#copy-files","title":"Copy files","text":"Copy all files from the Tasmota Source code into your VSC working folder.
"},{"location":"Visual-Studio-Code/#compile-tasmota","title":"Compile Tasmota","text":"Start VSC and select File - Open Folder... to point to the working folder.
Note: Press Ctrl + Shift + P and type PlatformIO to see all options.
Select the desired firmware via VSC menu.
Easy compilation can be performed from the icons at the bottom of the VSC screen.
"},{"location":"Visual-Studio-Code/#upload-tasmota","title":"Upload Tasmota","text":"Enable desired options in platformio.ini for serial upload like:
; *** Upload Serial reset method for Wemos and NodeMCU\nupload_port = COM5\n;upload_speed = 512000\nupload_speed = 115200\n;upload_resetmethod = nodemcu\n
"},{"location":"Visual-Studio-Code/#deploy-via-http-upload","title":"deploy via HTTP upload","text":"Special options (not needed for compiling Tasmota!) are enabled in platformio_override.ini :
; *** Upload file to OTA server using HTTP\nupload_port = -i domus1 -p 80 -u /api/upload-arduino.php\nextra_scripts = ${esp_defaults.extra_scripts} pio/http-uploader.py\n
For ESP32 replace esp_defaults with esp32_defaults. Or if you wish to upload the gzip files (not for ESP32 only for ESP8266):
upload_port = -i domus1 -p 80 -u /api/upload-arduino.php\nextra_scripts = ${esp_defaults.extra_scripts} pio/http-gz-uploader.py\n
Easy compilation and upload can be performed from the icons at the bottom of the VSC screen or use Ctrl + Alt + U to upload (will build if needed). The upload.php file at your webserver could look like this:
<?php\n$image = basename($_FILES[\"file\"][\"name\"]);\n$target_file = \"./\".$image;\n$hostname = $_SERVER['SERVER_NAME'];\n\nif (move_uploaded_file($_FILES[\"file\"][\"tmp_name\"], $target_file)) {\n echo \"The file $image has been uploaded to OTA server $hostname. \\n\";\n} else {\n echo \"Sorry, there was an error uploading your file $image to OTA server $hostname. \\n\";\n}\n?>\n
"},{"location":"Visual-Studio-Code/#hint","title":"Hint:","text":"In case vscode shows a huge amount of errors using PlatformIO - Intellisense a possible \"solution\" is to change the cpp-Intelli Sense Engine type to \"TAG PARSER\"
This setting can be changed in workspace settings by: Use Ctrl + Shift + P and type Preferences: Open Workspace Settings and type intelli Sense in the search box. Now change the value for Intelli Sense Engine to Tag Parser.
"},{"location":"WS2812B-RGB-Shield/","title":"WS2812B RGB Shield","text":""},{"location":"WS2812B-RGB-Shield/#ws2812b-rgb-shield-single-pin","title":"WS2812B RGB Shield (single pin)","text":"From the Wemos WS2812b shield specs the DATA pin is connected to D2 of the Wemos.
"},{"location":"WS2812B-RGB-Shield/#tasmota-settings","title":"Tasmota Settings","text":"In Configuration -> Configure Module page assign:
After a reboot of the device the toggle button and light controls are displayed in the webUI.
"},{"location":"WS2812B-and-WS2813/","title":"WS2812B and WS2813","text":""},{"location":"WS2812B-and-WS2813/#ws2813b-versus-ws2812b","title":"WS2813B versus WS2812B","text":"The newer version of ws2812b is the ws2813b, which has dual signal lines to prevent a led failure also consecutive leds fail.
"},{"location":"WS2812B-and-WS2813/#esp8266-needs-level-shifting-ws281x-schematic","title":"ESP8266 needs Level shifting - WS281x schematic","text":"Below the schematics to connect an ESP82xx to a WS281x.
"},{"location":"WS2812B-and-WS2813/#about-this-circuit-diagram-and-the-oscilloscope-traces","title":"About this circuit diagram and the oscilloscope traces","text":"Channel 1 (yellow) is connected to an output of the ESP8266 Chip, and therefore shows the input voltage of the level shifting circuit.
Channel 2 (green) is connected to the output of the level shifting circuit, and therefore shows the input voltage to the first WS281X pixel.
How does the MOSFET circuit work and what are the challenges?
When the GPIO is HIGH (3.3V), the voltage between Gate and Source of the FET is zero since the Gate is tied to +3.3V through R4 and the Source follows the GPIO. The FET is not conducting between its Source and Drain connections. In this state the Output is pulled to +5V by R5.
(BTW: R4 is only there to charge/discharge the parasitic input capacitance of the FET and could be omitted entirely for an ideal FET.)
When the GPIO goes low, it pulls the Source of the FET to GND (0V). That increases the voltage across Gate and Source of the FET (VGS) to 3.3V, causing the FET to become conductive between Source and Drain, and consequently pull the output to GND.
The major flaw of this circuit is that its usefulness degrades towards higher frequencies (shorter pulses) and capacitive loads because the only force pulling the output to HIGH is the pull-up resistor R5. So the load capacitance gets charged through R5 only. You can mitigate the effect partially by selecting a smaller R5 but the tradeoff will be increased power consumption of the circuit.
A WS2813 signal input imposes a capacitive load of 15 pF onto the level shifter\u2019s output according to its datasheet. That doesn\u2019t sound like a lot, but you can see from the plots that we have only few nanoseconds time to charge the parasitic capacitor. It also partially adds up with the reverse transfer capacitance of the BSS138 FET (Crss=6pF according to the datasheet).
The result is clearly visible in the oscilloscope plot: the leading edges are not sharp and therefore reducing the pulse duration acquired by the pixel\u2019s input, depending on the input voltage threshold of the pixel (0.7 x VDD = 3.5V @ 5V according to the datasheet). The effect of sampled pulse shortening gets worse with rising input HIGH threshold of the pixel.
NB: The design frequency of this circuit would be 1 / (433 ns x 2) = 1.155 MHz
So what would be a better solution?
Better Circuit: TTL logic gates
We need a circuit with well-defined and matching input voltage thresholds. TTL gates represent such circuits. For a power supply of 5V, a TTL input is guaranteed logic LOW when the input voltage is below 0.8V. That same input is guaranteed logic HIGH when the input voltage is above 2.0V.
That perfectly matches our 3.3V GPIO output voltage!
The output weakness of the MOSFET circuit does not apply to a TTL gate\u2019s output since it can drive to HIGH as well as to LOW by means of a circuit known as \u201cTotem Pole\u201d push-pull transistor output stage. 74HCT and 74AHCT chips will drive the output to a voltage close to VCC.
This output stage gives much sharper leading edges as can be seen on the lower right oscilloscope picture.
So this is actually the circuit I would suggest for the application. A large variety of TTL chips can be used: 74HCTXX series, 74AHCTXX series, but not 74HC or 74AHC!
Which logic function you choose is up to your liking and availability in your parts bin. The input characteristics are the same for all of them (with a slight deviation for those with Schmitt trigger inputs like the 74XX14).
- 5V power supply: the power of the power supply depends on the number of leds. A pixel has 3 leds (RGB), each led drains a max of 20mA, so a pixel drains a max of 60mA (3 * 20mA). So the total current that the power supply must deliver is 60mA times the number of pixels. For example 80 pixels: 60mA * 80 = 4800mA = 4.8A. Also the ESP8266 is powered by the power supply so in this example a power supply of 6A (30W) will do.
note: connect the ledstrip from both sides to the power supply
"},{"location":"WS2812B-and-WS2813/#tasmota-configuration","title":"Tasmota Configuration","text":"In the Configuration -> Configure Module page, select the following:
"},{"location":"WS2812B-and-WS2813/#tasmota-main","title":"Tasmota Main","text":""},{"location":"WebUI/","title":"WebUI","text":"Tasmota's web user interface is a practical way to control and manage your tasmotized device.
Warning
WebUI does not and can not have all the features and commands implemented. For precise and complete control use Console or MQTT commands!
To access the WebUI use your device's IP address in your favorite web browser.
By default, WebUI starts in unprotected admin mode which allows complete access to your device to anyone with access to that IP.
If you want to restrict other users to only control through the WebUI, use WebServer 1.
Command WebPassword will set up a password that needs to be entered when trying to access WebUI. This is a very thin layer of protection since everything is transmitted over unencrypted HTTP protocol.
"},{"location":"WebUI/#menus","title":"Menus","text":""},{"location":"WebUI/#configuration","title":"Configuration","text":"Configuration menu allows you to configure everything from components to Wi-Fi and gives you the option to backup and restore the configuration in a secure location.
"},{"location":"WebUI/#information","title":"Information","text":"Displays a single page loaded with information about the device including: current Tasmota version, Wi-Fi AP data, MQTT host data, and more
"},{"location":"WebUI/#firmware-upgrade","title":"Firmware Upgrade","text":"An easy to use menu to initiate a firmware upgrade from an uploaded .bin file or an OTA server.
"},{"location":"WebUI/#console","title":"Console","text":"Terminal access to Tasmota. Issue commands here or follow the information stream. Useful for debugging when using \u02d9Weblog 4`.
"},{"location":"WebUI/#customizing","title":"Customizing","text":""},{"location":"WebUI/#webbutton","title":"WebButton","text":"Change names of the toggle buttons using WebButton.
"},{"location":"WebUI/#themes","title":"Themes","text":"WebUI is themable using WebColor commands.
To apply a theme from below copy the entire code block and send it using the console or via MQTT.
"},{"location":"WebUI/#dark-default-theme","title":"Dark (default theme)","text":"WebColor {\"WebColor\":[\"#eaeaea\",\"#252525\",\"#4f4f4f\",\"#000000\",\"#dddddd\",\"#65c115\",\"#1f1f1f\",\"#ff5661\",\"#008000\",\"#faffff\",\"#1fa3ec\",\"#0e70a4\",\"#d43535\",\"#931f1f\",\"#47c266\",\"#5aaf6f\",\"#faffff\",\"#999999\",\"#eaeaea\"]}\n
"},{"location":"WebUI/#light-default-until-671","title":"Light (default until 6.7.1.)","text":"WebColor {\"WebColor\":[\"#000000\",\"#ffffff\",\"#f2f2f2\",\"#000000\",\"#ffffff\",\"#000000\",\"#ffffff\",\"#ff0000\",\"#008000\",\"#ffffff\",\"#1fa3ec\",\"#0e70a4\",\"#d43535\",\"#931f1f\",\"#47c266\",\"#5aaf6f\",\"#ffffff\",\"#999999\",\"#000000\"]}\n
"},{"location":"WebUI/#halloween","title":"Halloween","text":"WebColor {\"WebColor\":[\"#cccccc\",\"#2f3133\",\"#3d3f41\",\"#dddddd\",\"#293134\",\"#ffb000\",\"#293134\",\"#ff5661\",\"#008000\",\"#ffffff\",\"#ec7600\",\"#bf5f00\",\"#d43535\",\"#931f1f\",\"#47c266\",\"#5aaf6f\",\"#ffffff\",\"#999999\",\"#bc4d90\"]}\n
"},{"location":"WebUI/#navy","title":"Navy","text":"WebColor {\"WebColor\":[\"#e0e0c0\",\"#000033\",\"#4f4f4f\",\"#000000\",\"#dddddd\",\"#a7f432\",\"#1e1e1e\",\"#ff0000\",\"#008000\",\"#ffffff\",\"#1fa3ec\",\"#0e70a4\",\"#d43535\",\"#931f1f\",\"#47c266\",\"#5aaf6f\",\"#ffffff\",\"#999999\",\"#eedd77\"]}\n
"},{"location":"WebUI/#purple-rain","title":"Purple Rain","text":"WebColor {\"WebColor\":[\"#eaeaea\",\"#252525\",\"#282531\",\"#eaeaea\",\"#282531\",\"#d7ccff\",\"#1d1b26\",\"#ff5661\",\"#008000\",\"#faffff\",\"#694fa8\",\"#4d3e7f\",\"#b73d5d\",\"#822c43\",\"#1f917c\",\"#156353\",\"#faffff\",\"#716b7f\",\"#eaeaea\"]}\n
"},{"location":"WebUI/#solarized-dark","title":"Solarized Dark","text":"WebColor {\"WebColor\":[\"#839496\",\"#002b36\",\"#073642\",\"#839496\",\"#002b36\",\"#839496\",\"#073642\",\"#b58900\",\"#859900\",\"#eee8d5\",\"#268bd2\",\"#185886\",\"#dc322f\",\"#90211f\",\"#859900\",\"#647300\",\"#839496\",\"#073642\",\"#839496\"]}\n
Tip
When using an MQTT client such as mosquitto_pub, enclose the message payload in single quotes (')
mosquitto_pub -h 192.168.1.20 -t \"cmnd/myTopic/WebColor\" -m '{\"WebColor\":[\"#eaeaea\",\"#252525\",\"#4f4f4f\",\"#000000\",\"#dddddd\",\"#65c115\",\"#1f1f1f\",\"#ff5661\",\"#008000\",\"#faffff\",\"#1fa3ec\",\"#0e70a4\",\"#d43535\",\"#931f1f\",\"#47c266\",\"#5aaf6f\",\"#faffff\",\"#999999\",\"#eaeaea\"]}'\n
"},{"location":"White-Blend-Mode/","title":"White Blend Mode for lights","text":"White Blend Mode is used for 4 channel (RGBW) and 5 channel (RGBWC) devices. It is enabled by setting the last PWM channel to zero (e.g., RGBWWTable 255,255,255,<n>,0) to lower the white channel intensity.
Generally, white LEDs are brighter than RGB LEDs. If you want to keep the same brightness, you need to calibrate the white level. In this mode, any white component will be removed from RGB LEDs and sent to the white LEDs. This makes whites look much better.
Example: Color 30508000 will be converted to Color 0020503000 (0x30 is subtracted from R,G,B channels and added to the White channel)
To calibrate:
Color FFFFFF00RGBWWTable 255,255,255,255,255 - reset to RGB modeRGBWWTable 255,255,255,<n>,0 (begin the calibration process with <n> == 150)- If too bright, decrease
<n>. If too dim, increase <n> - Go back to step 2 and iterate until satisfied with the color intensities.
Examples: * Sonoff B1: RGBWWTable 255,255,255,35,0 * Teckin SB50: RGBWWTable 255,255,255,80,0
"},{"location":"WifiPower/","title":"WifiPower Command","text":"WifiPower allows you to fine tune the Wi-Fi transmission power level. The default is 17dBm which should be enough power for the device to transmit to the Wi-Fi access point (AP) in a normal network environment use case. Changing this setting will impact the Wi-Fi range of the device. The general rule of thumb is for every 3dBm change up or down will double or halve the range, respectively. However, this is largely dependent on the Wi-Fi router's capabilities.
Use the RSSI signal level reported by the router for a particular Tasmota device to adjust the power level of a device. Lower the value incrementally until you achieve a balance between connection stability and energy saving. In some cases a device may require slightly more power to maintain a stable connection to the Wi-Fi network. In this case, increment the value in 1 dBm increments until stable connectivity is observed. Do not exceed 17dBm! Exceeding the default 17dBm transmit power setting may cause unreliable device operation. Most devices have been designed with the 17dBm theoretical power setting and may not have the ability to dissipate the additional heat generated. Setting the transmit power too high may cause interference in the device antenna causing Wi-Fi reception problems.
This setting will not affect the signal level received from the AP (i.e., the RSSI reading that Tasmota reports).
Improper setting of this parameter may cause operational instability and can generate exceptions. Increasing WifiPower puts additional demand on the device electrical power supply. Exceeding the capabilities of the power supply can cause other erratic device behaviors. Of course, the opposite may be the case when reducing transmit power levels allowing a device with a borderline power regulator to operate reliably.
You should perform substantial testing and monitoring to find the sweet spot for WifiPower.
"},{"location":"Zigbee-CCLib-Flashing/","title":"Zigbee CCLib Flashing","text":""},{"location":"Zigbee-CCLib-Flashing/#flash-using-cclib","title":"Flash using CClib","text":"To simplify this procedure, a ready to use fork of the needed firmware files is available.
"},{"location":"Zigbee-CCLib-Flashing/#flash-cclib-on-an-esp82xx-device","title":"Flash CCLib on an ESP82xx Device","text":"Flashing the CC2530 normally requires a CC_DEBUGGER. Using an ESP82xx device like a Wemos D1 Mini is a lower cost alternative.
If you are using a Wemos D1 Mini or NodeMCU, just plug the microUSB port. Vcc (3.3V), GND, Tx (GPIO1), and Rx (GPIO3) are connected via the microUSB port. Be sure that you are using a USB data cable.
For ESP devices that do not have a microUSB connector, make the following connections:
ESPDevice SerialProgrammingAdapter Vcc Vcc GND GND GPIO0 GND GPIO1 Rx GPIO3 Tx Follow the usual ESP82xx flashing process - you are just using CCLib_proxy.ino.bin instead of Tasmota.
Once the firmware upload completes, retain the serial interface connections (3.3V, GND, Tx, Rx). These will be used later for flashing the CC2530.
C. Flash a DL-20 Zigbee module The DL-20 Zigbee module has a 5-pin 1.27mm pitch unpopulated header with 0.6mm througholes. For flashing any of the Zigbee modules, you need the following connections:
ESPPin D1 MiniNodeMCU CC2530Pin DL-20 J2Pin Location GPIO12 D6 CC_DD(A.K.A. P2_1 ('P21') or Debug Data) 5 GPIO4 D2 CC_DC(A.K.A. P2_2 ('P22') or Debug Clock) 4 Vcc 3.3v Vcc 3 GPIO5 D1 CC_RST 2 GND GND GND 1 DL-20 Flashing Jumpers Insert alternating male Dupont jumpers; one jumper on one side, the next one on other side. This allows the pins to provide the friction themselves to maintain contact and remain firmly in place. You only need DD, DC, and RST (a fourth jumper is shown which is used to keep the RST jumper in place). Vcc and GND are available on the main serial interface pins.
D. Upload the firmware to the CC2530 The CC2530 requires Z-Stack_Home_1.2, of type Default (not Source Routing). For convenience, ready to use firmware files are provided. Select the right one for your hardware: CC2530, CC2530 + CC2591 or CC2530 + CC2592.
These Python scripts require Python 2.7. 1) Ensure that you have Python 2.7 installed
2) Install pyserial 3.0.1:
pip install pyserial==3.0.1\n
3) Check for connectivity before flashing:
python Python/cc_info.py -p <serial_port>\n
where <serial_port> is the serial port for the ESP82xx device. e.g. /dev/cu.usbserial-xxxx or COM7
Example of result:
INFO: Found a CC2530 chip on /dev/cu.usbserial-xxxx\n\nChip information:\n Chip ID : 0xa524\n Flash size : 16 Kb\n Page size : 2 Kb\n SRAM size : 1 Kb\n USB : No\n\nDevice information:\n IEEE Address : 000000000000\n PC : 0000\n\nDebug status:\n [ ] CHIP_ERASE_BUSY\n [ ] PCON_IDLE\n [X] CPU_HALTED\n [ ] PM_ACTIVE\n [ ] HALT_STATUS\n [X] DEBUG_LOCKED\n [X] OSCILLATOR_STABLE\n [ ] STACK_OVERFLOW\n\nDebug config:\n [ ] SOFT_POWER_MODE\n [ ] TIMERS_OFF\n [ ] DMA_PAUSE\n [ ] TIMER_SUSPEND\n
If your CC2530 is DEBUG_LOCKED, then the flash size will be incorrectly reported as 16kB. Dont worry flashing the Z-Stack firmware will work and reset the DEBUG_LOCKED bit.
In some situation flashing fails with the error message flash have not enough space. If this happens do the following:
python Python/cc_read_flash.py -p <serial_port> -o x.hex\npython Python/cc_write_flash.py --erase -p <serial_port> -i x.hex\n
Recheck for connectivity and the correct flash size by repeating step #3. 4) Flash the Z-Stack firmware using the following command:
Flashing the CC2530 takes about 20 minutes
python Python/cc_write_flash.py -e -p <serial_port> -i Bin/CC2530_DEFAULT_20190608_CC2530ZNP-Prod.hex\n
INFO: Found a CC2530 chip on /dev/cu.usbserial-xxxx\n\nChip information:\n Chip ID : 0xa524\nFlash size : 256 Kb\nPage size : 2 Kb\nSRAM size : 8 Kb\n USB : No\nSections in Bin/CC2530_DEFAULT_20190608_CC2530ZNP-Prod.hex:\n\nAddr. Size\n-------- -------------\n0x0000 8176 B \n0x1ff6 10 B \n0x3fff0 1 B \n0x2000 239616 B \n\nThis is going to ERASE and REPROGRAM the chip. Are you sure? <y/N>: y\n\nFlashing:\n- Chip erase...\n- Flashing 4 memory blocks...\n-> 0x0000 : 8176 bytes \nProgress 100%... OK\n-> 0x1ff6 : 10 bytes \nProgress 100%... OK\n-> 0x3fff0 : 1 bytes \nProgress 100%... OK\n-> 0x2000 : 239616 bytes \nProgress 100%... OK\n\nCompleted\n
If you don't see any on screen activity that flashing has begun (i.e., progress percentages increasing) within a couple minutes, then abort the command, cycle power on the ESP82xx, and start this step over.
Described in greater detail in this blog post.
"},{"location":"Zigbee-Internals/","title":"Zigbee internals","text":"Back to Zigbee
This page is for developers who want to understand how Zigbee2Tasmota (Z2T) works and its implementation details.
"},{"location":"Zigbee-Internals/#cc2530-serial-protocol","title":"CC2530 Serial protocol","text":"The CC2530 is flashed with Texas Instrument ZNP Software version 1.2. The protocol is build on a serial communication between the main cpu and the CC2530.
Z-Stack 1.2 Monitor and Test API
Serial communication is configured as 8N1, 115200 bauds. We suggest to use GPIO13/15 because they have hardware serial support. Please note that there is only one usable hardware serial, either on GPIO1/3 or GPIO13/15.
To enable hardware serial on GPIO13/15 for Tasmota, set Serial 0 and restart. Otherwise Z2T will use Software serial provided by TasmotaSerial.
Receiving 115200 bauds in software is a timing challenge. Here is the anatomy of a byte transmitted in serial mode. Each bit is 8.7\u00b5s, or ~700 CPU cycles at 80MHz (1400 cycles at 160MHz).
It all starts with a LOW \"start bit\" that generates an interrupt transferred to TasmotaSerial. Then TasmotaSerial enters a tightly controlled loop to read each bit (least sifnificant first). The frame stops with a HIGH stop bit.
What can go wrong? Tasmota may be already handling an interrupt when the start bit arrives, potentially causing a shift by 1 bit and a wrong message.
Here is a 0xFE byte correctly received:
Same frame with a delay in the interrupt handler, and mistakenly read 0xFF:
TasmotaSerial has been improved to allow receiving a train of bytes withtout any disruption.
CC2530 generally sends all the bytes one after the other for a single ZNP message (up to 250 bytes). Instead of giving back control after the first byte, the TasmotaSerial interrupt handler continues to monitor the serial RX line for the next 4 bits and checks whether a new start bit arrived. It avoids any error after the first byte was received.
Still the first byte in the message could have been wrong. Fortunately, the first byte sent by ZNP is always 0xFE (see below). This means that if the interrupt arrives too late, Tasmota will read 0xFF instead of 0xFE. Z2T software does automatic error correction in this case, i.e. if the first byte received is 0xFF, it is automatically assumed to be 0xFE and the rest of the message is read normally.
With these two schemes, software serial for Zigbee proved to be extremely reliable, even at 80MHz. It is highly recommended though to run at 160MHz.
"},{"location":"Zigbee-Internals/#state-machine-cc2530-initialization-and-configuration","title":"State machine - CC2530 initialization and configuration","text":"After Tasmota boots, it sends the sequence 410001 to force a CC2530 hardware reset. Z2T implements an asynchronous state machine to handle the initialization and configuration of the CC2530. The state machine sends commands and waits for responses (with time-outs) and takes different branches depending on the responses.
"},{"location":"Zigbee-Internals/#instruction-set","title":"Instruction set","text":"The program is encoded as a list of 32 bits instructions, stored in Flash in the zb_prog array of type Zigbee_Instruction[]. There is a PC (program counter) that is increased at each tick (i.e. every 50ms).
The state machine has very simple instructions.
Instructions encoded with 4 bytes:
Keep a copy of those parameters in a file, you might need them again.
- Diagram v412: simple universal setup. For example, the control of horizontal curtain or vertical shutters, blinds adjuster or window opener, pet feeders, opening of a water tap for watering the lawn, rotating table for subject photography, opening the ventilation flap, PTZ camera, 3D Scanner Table, linear Actuator.
- Diagram v414: parallel setup is to run two parallel steppers motors from the same controller. For example, to control a large and heavy hanging screen for an LCD projector, or two curtains at once on one large window.
- Diagram v416: minimum setup size. For example, for small curtains located in a limited space.
- Diagram v422: parallel setup is to run two shutters and independent control of two stepper motors from one controller. For example, to control two independent curtains.
- Diagram v424: big parallel setup is to run two shutters and independent control of two pairs of stepper motors from one controller. For example, to control four curtains on one very large window.
For 
WARNING Do not use on ESP8266 devices! 
You must specify either 
If you wish to expand a device with a peripheral component, after properly wiring everything, you need to assign it to a free GPIO in Configure Module page or use command 
, no guarantees!) 
NOTE: with this schematic, the DHT sensor is on GPIO2. You'll have to change the
Tasmota supports 
Tasmota provides different ways to configure Domoticz parameters. Choose the method you prefer:
Many serial programmers do not have a voltage regulator on board like the pictured ones. The ESP requires at least 150mA, many 3.3V serial programmers cannot supply this much current as many serial programming tasks do not require a large amount of power.
Once the installation is successful, click on NEXT. The installer will scan for Wi-Fi networks and select the strongest one. Use the dropdown to select between networks.
Enter the Wi-Fi password.
Wait until configuration completes and click CONTINUE 
From here click on VISIT DEVICE to enter the 
Connect your device to a power source and grab your smartphone (or tablet or laptop or any other web and Wi-Fi capable device). Search for a Wi-Fi AP named tasmota_XXXXXX-#### (where XXXXXX is a string derived from the device's MAC address and #### is a number) and connect to it. In this example the Wi-Fi AP is named tasmota_3D5E26-7718. 
After you have connected to the Tasmota Wi-Fi AP, open 
At the top of the page you can select one of the discovered Wi-Fi networks or have Tasmota scan again. Enter your WiFi credentials:
In case the network name or password were entered incorrectly, or it didn't manage to connect for some other reason, Tasmota will return to the "Wi-Fi parameters" screen with an error message.
Tasmota supports 
Common transmitter modules in the market have a weak IR LED, thus effective transmit distance is really short. If you need range it is best to 
The PZEM-004T together with a Sonoff Basic provide a good clamp on energy monitor.
It can be used a SMD resistor 102 or 1001 (1K) soldered near/parallel with R8 or a normal resistor (THT) similar to that used on the image of v.1.0 The resistor is placed in different place on v.3.0 because the optocouplers RX and TX are reversed compared to v.1.0
Tasmota allows for easy selection of peripherals and assignment to GPIO pins. 
(Found out by tracing the PCB copper tracks of the unknown ESP module. Not verified, except GPIO0, RX, TX, Vcc and GND which have successfully been used for flashing.)
the template name (also defines the name for the module).
+
+
+ 
+ 
+
+
+
+
+
+
.
You can now toggle the light and use the slider to dim the lights from the tasmota webpage. Or better, use your favorite domotica software to control it via MQTT.
Rx and Tx are inverted on this picture! 
3.3V, GND and GPI00 are accessible on the main board. The used TYWE3S board unfortunately does not have easily reachable solderpads for TX/RX, but I managed to solder with a normal 60W iron between main board and TYWE3S board: 
The HuaFan Wireless Wifi Smart Plug/Socket is a useful bit of kit that allows you to introduce home automation without getting into any mains re-wiring. As an added bonus, the device also provides energy monitoring functions (voltage, current, power) in much the same way as the 
This smart socket comes with its own iPhone/Android App and is controllable from the HF Smart cloud service. As well as allowing on/off control, the plug/socket also measures current, voltage and power. It’s pretty well made but almost certainly doesn’t meet the full British electrical standards, as it doesn’t have a shutter to close off the live socket holes when a plug is removed. This a rather a shame and would not be too tricky to implement and would only marginally increase the cost of these pretty cheap (~£UK 10) units. The provided software/service all seemed rather closed and proprietary and not able to talk to other stuff. So something had to change!
There are no screws; to disassemble you need to prise it open on each side. 
There’s not a lot to see on the top apart from the mains relay, the button and the red/blue LEDs that illuminate it.
The main item of interest on the top is the daughter board. This has our trusty ESP8266EX and an 8Mbit SPI flash memory. You can also see the 40MHz crystal - more on this later…  
You need a hefty soldering iron to unsolder the board from the plug pins and on the reverse you see the main circuitry. Next door to the AMS1117 3.3V regulator for the ESP is a HLW8012 chip that does the current/voltage/power measurement. Conveniently, this is the same chip that's used in the Sonoff Pow module, so all the code to drive it is already in place. Below the two ICs is R12 it's R002 i.e. a 2mOhm resistor. This may be different to the one in the Sonoff, so expect to use different calibration settings. 
For programming you need to unplug the unit for any mains and make connections to GND, Vcc and Rx. That’s 1, 2 and 4 on the back of the daughter board, counting from the right.
Instead you have two options, either re-instate R5 with a very small piece of wire (or a teeny resistor if you have one) or solder a wire directly to the resistor pad/chip pin. As the connection should be temporary (subsequent flashes will be Over the Air) I initially went for the simpler but more fragile direct connection, mechanically secured with some insulating tape.
-- Image: The 1 Gang Touch Panel, featuring the glass front (protective plastic film still on)
Sorry for the horrible pics.. will replace
* Some leads * A soldering iron (solder, bits.. etc) - I'm going to assume you know how/what to do with this.
* NOW: Apply power. You can remove the short to ground after a second or two.
The Dutch Klik Aan Klik Uit PAR-1000 434MHz Power socket might suffer from Capacitor degeneration. In effect the power needed to engage the relay is too low. Replacing the Yellow Capacitor often solves the problem. 
During Proof of Concept I used 5V power supplies from itead. After three units were built one crashed caused by debris on the PS PCA resulting in an AC short which in turn blew the large resistor. As the selected Songle relay has the control leads close to the AC leads I also changed the relay. 
The parts used are:
( Note: Same PCB as OBI Socket IP44 (Black) ) 
* Aliexpress: 
Inside PCB
The chip used WT8266-S1. The specs can be found on 
Pins used. You can choose one of 3 GND to your liking. the RESET(RST) pin is also marked for those that use that pin to reset the chip while flashing
The Sonoff 4CH features four hardware buttons. Button marked FW/IO0 is connected to GPIO0 and can be used to bring the module into flash mode. 
The button labelled IO0 is connected to GPIO0 and can be used to bring the module into flash mode. 
- GPIO13 - You must remove the bi-colour LED - GPIO04 - You must solder wire to pin on ESP chip 
The picture shows how to program the S20 Smart Socket powered by the serial-to-USB converter. With newer US sockets, either use a right-angle header, or remove the header after flashing. Otherwise,the pushbutton may rub against a pin and get stuck.
Notes: 1. There is not enough room with this version to solder header pins to the programming port and still close the case. One possibility is to slightly bend the pins of a 4-way header and push it into the holes, removing it after programming. 2. GPIO0 is connected to the helper chip on this version, so the only way to get Ver1.1 of the board into flash mode is to solder a lead onto the resistor R19 from pin 15 on the ESP chip (GPIO0) and connect this lead to GND on power up; the device will set all the touch pads to dim and the WiFi LED D3 will NOT be on at all. 3. The connection marked 'LOG' on the J3 header is GPIO2.
All the flashing pins are in the front top right corner (sorry about covering them with the wires). From top to bottom: - LOG (GPIO2 not used) - GND - TXD - RXD - VCC
This USB powered or external powered board provides one GPIO controlling two alternating relays with Normally Open (NO) and Normally Closed (NC) contacts. It can be used for changing directions of a connected motor.
Total local control with quick setup and updates. Control using MQTT, Web UI, HTTP or serial. Automate using timers, rules or scripts. Integration with home automation solutions. Incredibly expandable and flexible.
