Tasmota: Difference between revisions

From Leo's Notes
This page was last edited on 13 June 2021, at 05:42.
← Older editNewer edit →
VisualWikitext
reorganized content
mNo edit summary
Line 81: Line 81:
|}
|}


=== Rules ===
===Rules===
Rules are sets of commands that should run when a specific condition is met. They are a way to program user defined behaviors to Tasmota without requiring a recompile. The ability to write rules allow for interesting behaviors between sensors and peripherals, such as updating an attached display when sensor values change.
Rules are sets of commands that should run when a specific condition is met. They are a way to program user defined behaviors to Tasmota without requiring a recompile. The ability to write rules allow for interesting behaviors between sensors and peripherals, such as updating an attached display when sensor values change.


==== Quick start ====
Rules are defined within a rule set. Tasmota out of the box has 3 rule sets called rule1, rule2, and rule3. Any number of rules can be placed in each set (though, limited by the device's memory, but the documentation says at least 1000 bytes). Rule sets can be enabled or disabled, which also enables or disables any rules within.  This allows for entire behaviors to be enabled or disabled simply by enabling or disabling a rule set.
With the power of Tasmota rules, we can trigger text to be written when a state changes. In the case of a CO2 monitor, we can create the following rule which clears and prints the PPM value on the first line of the display whenever the value changes.{{Highlight
 
| code = Rule1 on MHZ19B#CarbonDioxide do DisplayText [zc1l1]%value%ppm endon
<br />
Rule1 1
 
| lang = terminal
====Quick start with rules====
Frequently, we want to do something with a sensor reading. In the case of a CO2 monitor, we could possibly want to update a display when the PPM value changes. {{Highlight
| code = Rule1
  on MHZ19B#CarbonDioxide do DisplayText [zc1l1]%value%ppm endon
| lang = text
}}
Rules are always defined within a rule set and always begin with '<code>on</code>' and end with '<code>endon</code>'. In this example, the rule is defined within <code>rule1</code> and would run <code>DisplayText</code> whenever the sensor's <code>CarbonDioxide</code> metric changes. We can add additional rules within rule1 by appending additional rules as a list. In another example with the INA219, we could write the following rules which will write the voltage, current, and wattage value to a display:
 
{{Highlight
| code = Rule1
  on INA219#Voltage do DisplayText [c1l1]V %value% V endon
  on INA219#Current do DisplayText [c1l2]I %value% A endon
  on INA219#Power do DisplayText [c1l3]P %value% W endon
| lang = text
}}
 
For the rules to take effect, enable the rule set:
 
{{Highlight
| code = rule1 1
| lang = text
}}
}}
This rule would print "400ppm" if the CO2 reading was at 400, for example.


Alternatively, we can also trigger rules on every TelePeriod time (the telemetry period) by prefixing the trigger with <code>Tele-</code>. This might be desirable for values that requires constant polling.
For more complex rules that need to run multiple commands, chain them together with the <code>backlog</code> command. Rules can also enable or disable entire rule sets to enable or disable some behavior. Case in point, from one of my other projects, we could enable and later disable the screen from updating when a button is pressed:
 
{{Highlight
{{Highlight
| code = Rule1 on Tele-MHZ19B#CarbonDioxide do DisplayText [zc1l1]%value%ppm endon
| code = Rule2
Rule1 1
  ON button1#state=3 do backlog power1 1; rule1 1 endon
| lang = terminal
  ON button1#state=10 do backlog rule1 1; power1 1; delay 500; power1 0; rule1 0 endon
| lang = text
}}
}}


Line 103: Line 124:
There are a different set of supported peripherals out of the box depending on which Tasmota build you used. Refer to the BUILDS page at https://github.com/arendst/Tasmota/blob/development/BUILDS.md to determine if a particular feature is enabled. If it isn't, you will need to compile Tasmota with the desired feature enabled using the <code>users_config_override.h</code> file placed in the Tasmota source directory.
There are a different set of supported peripherals out of the box depending on which Tasmota build you used. Refer to the BUILDS page at https://github.com/arendst/Tasmota/blob/development/BUILDS.md to determine if a particular feature is enabled. If it isn't, you will need to compile Tasmota with the desired feature enabled using the <code>users_config_override.h</code> file placed in the Tasmota source directory.


==== Setting up I2C ====
====Setting up I2C====
[[File:Tasmota I2C GPIO Configuration.jpg|alt=Tasmota I2C GPIO Configuration|thumb|Tasmota I2C GPIO Configuration]]Some sensors and displays use the I2C protocol. The ESP8266 uses GPIO4 and GPIO5 as the I2C data and clock, respectively. When using I2C devices with Tasmota, configure the template as shown on the right. Save and activate the template. If configured properly, the <code>i2cscan</code> command should return a list of addresses that was found on the I2C bus.
[[File:Tasmota I2C GPIO Configuration.jpg|alt=Tasmota I2C GPIO Configuration|thumb|Tasmota I2C GPIO Configuration]]Some sensors and displays use the I2C protocol. The ESP8266 uses GPIO4 and GPIO5 as the I2C data and clock, respectively. When using I2C devices with Tasmota, configure the template as shown on the right. Save and activate the template. If configured properly, the <code>i2cscan</code> command should return a list of addresses that was found on the I2C bus.
{{Highlight
{{Highlight
Line 179: Line 200:
For more information, see the rules section.
For more information, see the rules section.


== Compiling ==
==Compiling==
Compile instructions are available at https://tasmota.github.io/docs/Compile-your-build/. The most simple way I've used is to use their docker image with the following commands:
Compile instructions are available at https://tasmota.github.io/docs/Compile-your-build/. The most simple way I've used is to use their docker image with the following commands:
{{Highlight
{{Highlight

Revision as of 05:42, 13 June 2021

Tasmota is an open source firmware for the ESP8266 and ESP32. It is mostly used for home automation devices, but can also be loaded on any other ESP device. It comes with support for a wide range of peripherals 'out of the box' and makes interacting with sensors via WiFi extremely easy as a result.

Flashing Tasmota

Obtain ESPTool and the latest Tasmota binary. Use ESPTool.py to erase and load Tasmota via serial.

Here is what I did to flash a Wemos D1, for example. 

$ python -m esptool --port /dev/ttyUSB0  erase_flash                                                                                                                                                                                                                          
esptool.py v3.0                                                                                                                                                                                                                                                                 
Serial port /dev/ttyUSB0                                                                                                                                                                                                                                                        
Connecting....                                                                                                                                                                                                                                                                  
Detecting chip type... ESP8266                                                                                                                                                                                                                                                  
Chip is ESP8266EX                                                                                                                                                                                                                                                               
Features: WiFi                                                                                                                                                                                                                                                                  
Crystal is 26MHz                                                                                                                                                                                                                                                                
MAC: 50:02:91:fe:9d:a4                                                                                                                                                                                                                                                          
Uploading stub...                                                                                                                                                                                                                                                               
Running stub...                                                                                                                                                                                                                                                                 
Stub running...                                                                                                                                                                                                                                                                 
Erasing flash (this may take a while)...                                                                                                                                                                                                                                        
Chip erase completed successfully in 8.6s                                                                                                                                                                                                                                       
Hard resetting via RTS pin...                                                                                                                                                                                                                                                   


$ python -m esptool --port /dev/ttyUSB0 write_flash -fs 1MB -fm dout 0x0 tasmota.bin            
esptool.py v3.0 
Serial port /dev/ttyUSB0  
Connecting....  
Detecting chip type... ESP8266          
Chip is ESP8266EX         
Features: WiFi  
Crystal is 26MHz
MAC: 50:02:91:fe:9d:a4    
Uploading stub...         
Running stub... 
Stub running... 
Configuring flash size... 
Compressed 613568 bytes to 438208...      
Wrote 613568 bytes (438208 compressed) at 0x00000000 in 38.7 seconds (effective 126.8 kbit/s)...      
Hash of data verified.    

Leaving...      
Hard resetting via RTS pin...

Configuration

After a factory reset, you will need to configure its WiFi settings manually by connecting to the WifiManager created access point. After it connects to the proper network, connect to it again through a web browser.

The following section applies to my own network and setup. For my own network, because the IoT devices are all in its own isolated network, I need to do a SSH tunnel in order to access the web interface. This is done by running: ssh -L 8080:192.168.1.x:80 root@iot-router and then connecting to localhost:8080 in a web browser. In the web interface, there are a few things that needs to be configured in order for it to work properly with the NodeRED/MQTT service outside of the IoT network.

  1. Setup the device template. Remember to check off 'activate' or else the template won't get applied.
  2. Configure MQTT. Set the host as mqtt, port as 1883, topic as the device name, and the prefix as tasmota/%topic%/. The mqtt hostname resolves to the MQTT server and the IoT router allows MQTT traffic on port 1883 to leave the network to this server.

MQTT and hostname

When configuring the Tasmota hostname and MQTT strings, you may substitute variable names. This table outlines what you can use.

Description What you type What you get
%06X 0353C0
last 4 digits of mac %04d
hostname %s
MQTT prefix %prefix% One of: cmnd, stat, tele
MQTT topic %topic% User defined. Eg: WP5-1

Rules

Rules are sets of commands that should run when a specific condition is met. They are a way to program user defined behaviors to Tasmota without requiring a recompile. The ability to write rules allow for interesting behaviors between sensors and peripherals, such as updating an attached display when sensor values change.

Rules are defined within a rule set. Tasmota out of the box has 3 rule sets called rule1, rule2, and rule3. Any number of rules can be placed in each set (though, limited by the device's memory, but the documentation says at least 1000 bytes). Rule sets can be enabled or disabled, which also enables or disables any rules within. This allows for entire behaviors to be enabled or disabled simply by enabling or disabling a rule set.


Quick start with rules

Frequently, we want to do something with a sensor reading. In the case of a CO2 monitor, we could possibly want to update a display when the PPM value changes. 

Rule1
  on MHZ19B#CarbonDioxide do DisplayText [zc1l1]%value%ppm endon

Rules are always defined within a rule set and always begin with 'on' and end with 'endon'. In this example, the rule is defined within rule1 and would run DisplayText whenever the sensor's CarbonDioxide metric changes. We can add additional rules within rule1 by appending additional rules as a list. In another example with the INA219, we could write the following rules which will write the voltage, current, and wattage value to a display: 

Rule1
  on INA219#Voltage do DisplayText [c1l1]V %value% V endon
  on INA219#Current do DisplayText [c1l2]I %value% A endon
  on INA219#Power do DisplayText [c1l3]P %value% W endon

For the rules to take effect, enable the rule set: 

rule1 1

For more complex rules that need to run multiple commands, chain them together with the backlog command. Rules can also enable or disable entire rule sets to enable or disable some behavior. Case in point, from one of my other projects, we could enable and later disable the screen from updating when a button is pressed: 

Rule2
  ON button1#state=3 do backlog power1 1; rule1 1 endon
  ON button1#state=10 do backlog rule1 1; power1 1; delay 500; power1 0; rule1 0 endon


Configuring peripherals

There are a different set of supported peripherals out of the box depending on which Tasmota build you used. Refer to the BUILDS page at https://github.com/arendst/Tasmota/blob/development/BUILDS.md to determine if a particular feature is enabled. If it isn't, you will need to compile Tasmota with the desired feature enabled using the users_config_override.h file placed in the Tasmota source directory.

Setting up I2C

Tasmota I2C GPIO Configuration
Tasmota I2C GPIO Configuration

Some sensors and displays use the I2C protocol. The ESP8266 uses GPIO4 and GPIO5 as the I2C data and clock, respectively. When using I2C devices with Tasmota, configure the template as shown on the right. Save and activate the template. If configured properly, the i2cscan command should return a list of addresses that was found on the I2C bus. 

CMD: i2cscan
MQT: tasmota/device/RESULT = {"I2CScan":"Device(s) found at 0x3c 0x40"}

SSD1306 display

The SSD1306 is an OLED display that comes in various sizes. These displays use I2C. The Wemos D1 OLED module is one such device with a screen size of 64x48. Tasmota supports this display through the tasmota-displays.bin image.

To get the display working:

  1. Attach the display to the Wemos D1 stack.
  2. Configure I2C for Tasmota (see section above)
  3. Run i2cscan via MQTT or the console. You should see the display at address 0x3c.
05:26:20.151 CMD: i2cscan
05:26:20.173 MQT: tasmota/D1-2/RESULT = {"I2CScan":"Device(s) found at 0x3c"}
  1. Configure the display in Tasmota by setting:
    • DisplayAddress 0x3c, the address discovered by i2cscan
    • DisplayModel 2, for SSD1306
    • DisplayWidth 64, DisplayHeight 48, for the display resolution
    • DisplayDimmer 100, to turn the display on
    • DisplayMode 0, for text mode
  2. Save and restart (Restart 1)
  3. Confirm that text can be written by running: Displaytext Hello.

To control the text location, specify any arguments within square brackets before the text when calling the DisplayText command. For example, to print "Hello World" across two lines, we write hello on line 1 column 1 (l1c1) and world on line 2 column 1 (l2c1): 

Displaytext [l1c1]hello
Displaytext [l2c1]world!

There are many other parameters which can be found at: https://tasmota.github.io/docs/Displays/#displaytext-use. The most important ones you should know are listed below. You may chain any number of these together and they will run in the order they appear. Eg. [zl1c1f0s1]Hello would clear, then write the world Hello in the smallest font on line 1 column 1 after clearing the screen.

Command/parameter Result Example
l# line (1..) l1
c# column (1..) c1
f# font size (0..) f0
s# font scaling (1..) s1
z clears screen
o / O turns off / on the display

With the power of Tasmota rules, we can trigger text to be written when a state changes. In the case of a CO2 monitor, we can create the following rule which clears and prints the PPM value on the first line of the display whenever the value changes. 

Rule1 on MHZ19B#CarbonDioxide do DisplayText [zc1l1]%value%ppm endon
Rule1 1

This rule would print "400ppm" if the CO2 reading was at 400, for example.

For more information, see the rules section.

Compiling

Compile instructions are available at https://tasmota.github.io/docs/Compile-your-build/. The most simple way I've used is to use their docker image with the following commands: 

$ git clone https://github.com/tasmota/docker-tasmota
$ cd docker-tasmota
$ docker build -t docker-tasmota .

$ git clone https://github.com/arendst/Tasmota.git
$ docker run -ti --rm -v $(pwd)/Tasmota:/tasmota -u $UID:$GID docker-tasmota -e tasmota

The different builds are available at https://github.com/arendst/Tasmota/blob/063611314777d4dd9dc8c25905f19f8b25f510aa/platformio.ini#L18

Project structure

Peripherals are prefixed in the source tree with xdrv (driver), xdsp (display), xlgt (lights), xnrg (energy), xsns (sensors).

Creating a new sensor driver

See: https://tasmota.github.io/docs/Sensor-API/

After creating the sensor driver file, edit the configurations header file and recompile: