mirror of https://github.com/arendst/Tasmota.git
Reformatted into Displays.md
blakadder
parent
4f2d326f01
commit
a1b8e9f93b
|
|
@ -1,201 +0,0 @@
|
|||
The display driver supports the following commands:
|
||||
|
||||
Command | Payload | Description
|
||||
-----------------|--------------|---------------------------------------------------------------------------
|
||||
Display | | Show current display setting as JSON string
|
||||
DisplayAddress | 0..255 | Set display module address
|
||||
DisplayDimmer | 0..100 | Set display luminosity (only 8x8 Matrix, for the other display it switch the display on [> 0] or off [=0])
|
||||
DisplayMode | 0..5 | Set display mode, for details see [DisplayMode Command](#displaymode-command) below
|
||||
DisplayModel | 1..5 | Set display model, for details see [DisplayModel Command](#displaymodel-command) below
|
||||
DisplayRefresh | 1..7 | Set time (in seconds) to update predefined content when using `DisplayMode` ≠ `0`
|
||||
DisplayCols | 1..44 | Set number of display columns
|
||||
DisplayRows | 1..32 | Set number of display rows
|
||||
DisplaySize | 1..4 | Set display scale-up size (only OLED SSD 1306 and TFT ILI9341)
|
||||
DisplayFont | 1..4 | (currently unsupported)
|
||||
DisplayRotate | 0..3 | Set display rotation (0=0°, 1=90°, 2=180°, 3=270°)
|
||||
DisplayText | ([])Text | Display Text. [] are an optional prefix and contains display control commands, for details see [DisplayText Command](displaytext-command) below.
|
||||
|
||||
|
||||
## DisplayMode Command
|
||||
|
||||
The display driver is able to display predefined setups of text or user defined text. To display user defined
|
||||
text using `DisplayText` command set `DisplayMode` to `0` (or also `1` for Matrix).
|
||||
|
||||
The modes 1 to 5 are predfined displaying the following content (depends on display type):
|
||||
|
||||
DisplayMode | LCD Display | OLED Display | TFT Display
|
||||
------------|----------------------|-----------------------------------|----------------------------
|
||||
0 | DisplayText | DisplayText | DisplayText
|
||||
1 | Time/Date | Time/Date | Time/Date
|
||||
2 | Local sensors | Local sensors | Local sensors
|
||||
3 | MQTT and Time/Date | Local sensors and Time/Date | Local sensors and Time/Date
|
||||
4 | Local sensors | MQTT and local sensors | MQTT and local sensors
|
||||
5 | MQTT and Time/Date | MQTT, local sensors and Time/Date | MQTT, local sensors and Time/Date
|
||||
|
||||
|
||||
## DisplayModel Command
|
||||
|
||||
Using `DisplayModel` you set the display type you have connected to your Tasmota driven device:
|
||||
|
||||
DisplayModel | Display type
|
||||
-------------|----------------------------------------------
|
||||
1 | I2C LCD Display (default addresses 0x27, 0x3F)
|
||||
2 | OLED 128x32/128x64 with SSD 1306 controller (default addresses 0x3C, 0x3D)
|
||||
3 | 8x8 Dot-Matrix
|
||||
4 | TFT LCD Display ILI9341
|
||||
5 | E-Paper Display
|
||||
|
||||
|
||||
## DisplayText Command
|
||||
|
||||
**The functionality described here is expected to be merged from [PR 3748](https://github.com/arendst/Sonoff-Tasmota/pull/3748)**
|
||||
|
||||
The `DisplayText` command is used to display text as well as graphics and graphs on LCD, OLED and ePaper
|
||||
displays attached to tasmota. The command argument is a string that is printed on the display at the current position.
|
||||
The string can be prefixed by embedded controll commands enclosed in brackets `[]`.
|
||||
|
||||
In order to use the `DisplayText` command the `DisplayMode` must be set to `0` (or optional `1` on LCD displays) or other modes must be disabled
|
||||
before compilation with `#undef USE_DISPLAY_MODES1TO5`.
|
||||
|
||||
### DisplayText Control Commands
|
||||
|
||||
In the list below _p_ stands for parameter and may be a number from 1 to n digits.
|
||||
On monochrome graphics displays things are drawn into a local frame buffer and send to the display either
|
||||
via the `d` command or automatically at the end of the command.
|
||||
|
||||
#### Positioning
|
||||
|
||||
- l _p_ = sets a character line to print at
|
||||
- c _p_ = sets a character column to print at
|
||||
- x _p_ = sets the x position for consecutive prints
|
||||
- y _p_ = sets the y position for consecutive prints
|
||||
|
||||
Text is printed at the last provided position, either l or y for the vertical position,
|
||||
and either x or x for the horizontal position. Neither x nor y are advanced/updated after printing text.
|
||||
|
||||
#### Line primitives
|
||||
|
||||
- h _p_ = draws a horizontal line with length _p_ (x is advanced)
|
||||
- v _p_ = draws a vertical line with length _p_ (y is advanced)
|
||||
- L _p_:_p_ = draws a line to _p_:_p_ (x,y are advanced)
|
||||
- k _p_ = draws a circle with radius _p_
|
||||
- K _p_ = draws a filled circle with radius _p_
|
||||
- r _p_:_p_ = draws a rectangle with _p_ with and _p_ height
|
||||
- R _p_:_p_ = draws a filled rectangle with _p_ with and _p_ height
|
||||
|
||||
#### Miscellaneous
|
||||
|
||||
- z = clear the display
|
||||
- i = (re)init the display (in e-paper mode with partial update)
|
||||
- I = (re)init the display (in e-paper mode with full update)
|
||||
- d = update the display
|
||||
- D _p_ = switch display auto updates on(_p_=1)/off(_p_=0), when off display must be updated via cmd d
|
||||
- o = switch display off
|
||||
- O = switch display on
|
||||
- t = display Tasmota time in HH:MM
|
||||
- T = display Tasmota date in DD.MM.YY
|
||||
- s _p_ = set text scaling for classic GFX font (scaling factor 1...N)
|
||||
- f _p_ = set font (1=12, 2=24,(opt 3=8)) if font==0 the classic GFX font is used
|
||||
- C _p_ = set color (0,1) for black or white (later for color displays index colors)
|
||||
|
||||
### Notes about e-paper displays
|
||||
|
||||
E-paper displays have 2 operating modes: full update and partial update.
|
||||
While full update delivers a clean and sharp picture it has the disadvantage of taking several
|
||||
seconds for the screen update and shows severe flickering during update.
|
||||
Partial update is quite fast (300 ms) with no flickering but there is the possibility that erased
|
||||
content is still slightly visible.
|
||||
To "whiten" the display it is therefore useful to perform a full update in regular intervals (e.g each hour).
|
||||
|
||||
Defines => USE_SOFTSPI, USE_DISPLAY_EPAPER29, USE_DISPLAY_EPAPER42
|
||||
|
||||
## Hardware connections:
|
||||
|
||||
I2C displays are connected in the usual manner and defined via tasmota pin selection.
|
||||
The I2C Adress must be given by `DisplayAddress XX`, e.g. 60, and the model set with `DisplayModel`
|
||||
,e.g. 2 for SSD1306.
|
||||
To permanently turn the display on set `DisplayDimmer 100`.
|
||||
Display rotation can be permanently set using `DisplayRotate X` (0-3).
|
||||
|
||||
E-paper displays are connected via 3 wire SPI (CS, SCLK, MOSI) the other 3 Interface lines of the display
|
||||
(DC, Reset, busy) may be left unconnected.
|
||||
The jumper on the circuit board of the display must be set to 3 wire SPI.
|
||||
|
||||
## Examples
|
||||
|
||||
Print Text at size 1 on line 1, column 1:
|
||||
```
|
||||
DisplayText [s1l1c1]Hello how are you?
|
||||
```
|
||||
|
||||
Draw a rectangle and draw text inside with size 2 and 7 chars padded with spaces:
|
||||
```
|
||||
DisplayText [x85y95h130v30h-130v-30s2p7x90y100]37.25 C
|
||||
```
|
||||
|
||||
Clear screen:
|
||||
```
|
||||
DisplayText [z]
|
||||
```
|
||||
|
||||
Draw rectangle from x,y with width and height:
|
||||
```
|
||||
DisplayText [x50y50r200:100]
|
||||
```
|
||||
|
||||
### Display local sensors using rules
|
||||
|
||||
Show sensor values, time and a separation line, whiten display every 60 minutes (line breaks and
|
||||
indentation added for readability):
|
||||
```
|
||||
rule1 on tele-SHT3X-0x44#Temperature do DisplayText [f1p7x0y5]%value% C endon
|
||||
on tele-SHT3X-0x44#Humidity do DisplayText [f1p10x70y5]%value% %[x0y20h296x250y5t] endon
|
||||
on tele-BMP280#Pressure do DisplayText [f1p10x140y5]%value% hPa endon
|
||||
on Time#Minute|60 do DisplayText [Tt] endon
|
||||
```
|
||||
|
||||
Show 4 analog channels (line breaks and indentation added for readability):
|
||||
```
|
||||
rule1 on tele-ADS1115#A0 do DisplayText [s1p21c1l01]Analog1: %value% adc endon
|
||||
on tele-ADS1115#A1 do DisplayText [s1p21c1l3]Analog2: %value% adc endon
|
||||
on tele-ADS1115#A2 do DisplayText [s1p21c1l5]Analog3: %value% adc endon
|
||||
on tele-ADS1115#A3 do DisplayText [s1p21c1l7]Analog4: %value% adc endon
|
||||
```
|
||||
|
||||
Show BME280 + SGP30 (line breaks and indentation added for readability):
|
||||
```
|
||||
rule1 on tele-BME280#Temperature do DisplayText [s1p21x0y0]Temp: %value% C endon
|
||||
on tele-BME280#Humidity do DisplayText [s1p21x0y10]Hum : %value% %% endon
|
||||
on BME280#Pressure do DisplayText [s1p21x0y20]Prss: %value% hPa endon
|
||||
on tele-SGP30#TVOC do DisplayText [s1p21x0y30]TVOC: %value% ppb endon
|
||||
on tele-SGP30#eCO2 do DisplayText [s1p21x0y40]eCO2: %value% ppm [s1p0x0y50]Time: [x35y50t] endon
|
||||
```
|
||||
|
||||
## Notes about display drivers:
|
||||
|
||||
Waveshare has 2 kinds of display controllers: with partial update and without partial update. The 2.9 inch driver is for partial update and should support also other waveshare partial update models with modified WIDTH and HEIGHT parameters.
|
||||
The 4.2 inch driver is a hack which makes the full update display behave like a partial update and should probably work with other full update displays.
|
||||
|
||||
The drivers are subclasses of the Adafruit GFX library.
|
||||
The class hierarchy is `LOWLEVEL :: Paint :: Renderer :: GFX`, where:
|
||||
- `GFX`: unmodified Adafruit library
|
||||
- `Renderer`: the interface for Tasmota
|
||||
- `Paint`: the modified pixel driver for e-paper
|
||||
- there are several virtual functions that can be subclassed down to `LOWLEVEL`.
|
||||
|
||||
The display dispatcher only does the class init call.
|
||||
All other calls go to the `Renderer` class.
|
||||
|
||||
In black and white displays a local ram buffer must be allocated before calling the driver.
|
||||
This must be set to zero on character or TFT color displays.
|
||||
|
||||
To use the 400x300 e-paper display the Arduino library 2.4 or later must be used because it leaves much
|
||||
more RAM available than prior versions. This display requires 15k of RAM!
|
||||
|
||||
About 28 k flash is used by these 4 drivers, the epd fonts use about 9k space, which can be if-def'd.
|
||||
|
||||
- SSD1306 = 1,15 k
|
||||
- SH1106 = 1,18 k
|
||||
- EPD42 = 2,57 k
|
||||
- EPD29 = 2,1 k
|
||||
- Display and Render class about 12 k
|
||||
|
|
@ -0,0 +1,183 @@
|
|||
Display support is in active development and not all features are implemented in the release version.
|
||||
|
||||
All display commands:
|
||||
|
||||
|Command | Parameters
|
||||
|:--- | :---
|
||||
<a id="Display"> </a> Display | Show current display setting as JSON string
|
||||
<a id="DisplayAddress"> </a> DisplayAddress | `0..255` = set display module address
|
||||
<a id="DisplayDimmer"> </a> DisplayDimmer | `0` = switch the display off<BR> `1..100` = switch the display on<BR>`0..100` = set display luminosity *(only on 8x8 Dot-Matrix displays)*
|
||||
<a id="DisplayMode"> </a> DisplayMode | `0..5` = set to display [predefined content](#displaymode-parameters) according to display type
|
||||
<a id="DisplayModel"> </a> DisplayModel | Set model of your display:<BR>`1` = I2C LCD Display (default addresses `0x27`, `0x3F`)<BR>`2` = [SSD1306](https://learn.adafruit.com/monochrome-oled-breakouts/arduino-library-and-examples) OLED 128x32/128x64 (default addresses `0x3C`, `0x3D`)<BR>`3` = 8x8 Dot-Matrix<BR>`4` = [ILI9341](https://www.adafruit.com/product/1770) TFT LCD<BR>`5` = E-Paper Display
|
||||
<a id="DisplayRefresh"> </a> DisplayRefresh | `1..7` = set time in seconds to update predefined content when using `DisplayMode` ≠ `0`
|
||||
<a id="DisplaySize"> </a> DisplaySize | `1..4` = set display scale-up size (only for `DisplayModel 2` (SSD1306 OLED) and `DisplayModel 4` (ILI9341 TFT LCD))
|
||||
<a id="DisplayRotate"> </a> DisplayRotate | Set rotation angle<BR> `0` = 0°<BR> `1` = 90°<BR> `2` = 180°<BR> `3` = 270°
|
||||
<a id="DisplayText"> </a> DisplayText | `<value>` = for a full guide see [DisplayText use](displays#displaytext-use)
|
||||
<a id="DisplayCols"> </a> DisplayCols | `1..44` = set number of display columns
|
||||
<a id="DisplayRows"> </a> DisplayRows | `1..32` = set number of display rows
|
||||
<a id="DisplayFont"> </a> DisplayFont | (reserved command, currently unsupported)
|
||||
|
||||
## DisplayMode Parameters
|
||||
|
||||
The display driver is able to display predefined setups of text or user defined text. To display user defined
|
||||
text using `DisplayText` command set `DisplayMode` to `0` (or also `1` for Matrix).
|
||||
|
||||
Parameter | LCD Display | OLED Display | TFT Display
|
||||
------------ | ---------------------- | ----------------------------------- | ----------------------------
|
||||
0 | DisplayText | DisplayText | DisplayText
|
||||
1 | Time/Date | Time/Date | Time/Date
|
||||
2 | Local sensors | Local sensors | Local sensors
|
||||
3 | MQTT and Time/Date | Local sensors and Time/Date | Local sensors and Time/Date
|
||||
4 | Local sensors | MQTT and local sensors | MQTT and local sensors
|
||||
5 | MQTT and Time/Date | MQTT, local sensors and Time/Date | MQTT, local sensors and Time/Date
|
||||
|
||||
# DisplayText Use
|
||||
|
||||
**The functionality described here is expected to be merged from [PR 3748](https://github.com/arendst/Sonoff-Tasmota/pull/3748)**
|
||||
|
||||
The `DisplayText` command is used to display text as well as graphics and graphs on LCD, OLED and e-Paper
|
||||
displays. The command argument is a string that is printed on the display at the current position.
|
||||
The string can be prefixed by embedded control commands enclosed in brackets `[]`.
|
||||
|
||||
In order to use the `DisplayText` command the `DisplayMode` must be set to `0` (or optional `1` on LCD displays) or other modes must be disabled before compilation with `#undef USE_DISPLAY_MODES1TO5`.
|
||||
|
||||
## DisplayText parameters
|
||||
|
||||
In the list below `_p_` stands for parameter and may be a number from 1 to n digits.
|
||||
On monochrome graphic displays things are drawn into a local frame buffer and sent to the display either
|
||||
via the `d` command or automatically at the end of the command.
|
||||
|
||||
### Positioning
|
||||
|
||||
`l _p_` = sets a character line to print at<BR>
|
||||
`c _p_` = sets a character column to print at<BR>
|
||||
`x _p_` = sets the x position for consecutive prints<BR>
|
||||
`y _p_` = sets the y position for consecutive prints<BR>
|
||||
|
||||
Text is printed at the last provided position, either l or y for the vertical position,
|
||||
and either x or x for the horizontal position. Neither x nor y are advanced/updated after printing text.
|
||||
|
||||
### Line primitives
|
||||
|
||||
`h _p_` = draws a horizontal line with length _p_ (x is advanced)<BR>
|
||||
`v _p_` = draws a vertical line with length _p_ (y is advanced)<BR>
|
||||
`L _p_:_p_` = draws a line to _p_:_p_ (x,y are advanced)<BR>
|
||||
`k _p_` = draws a circle with radius _p_<BR>
|
||||
`K _p_` = draws a filled circle with radius _p_<BR>
|
||||
`r _p_:_p_` = draws a rectangle with _p_ with and _p_ height<BR>
|
||||
`R _p_:_p_` = draws a filled rectangle with _p_ with and _p_ height<BR>
|
||||
|
||||
### Miscellaneous
|
||||
|
||||
`z` = clear the display<BR>
|
||||
`i` = (re)init the display (in e-Paper mode with partial update)<BR>
|
||||
`I` = (re)init the display (in e-Paper mode with full update)<BR>
|
||||
`d` = update the display<BR>
|
||||
`D _p_` = switch display auto updates on(_p_=1)/off(_p_=0), when off display must be updated with `d`<BR>
|
||||
`o` = switch display off<BR>
|
||||
`O` = switch display on<BR>
|
||||
`t` = display Tasmota time in HH:MM<BR>
|
||||
`T` = display Tasmota date in DD.MM.YY<BR>
|
||||
`s _p_` = set text scaling for classic GFX font (scaling factor 1...N)<BR>
|
||||
`f _p_` = set font (1=12, 2=24,(opt 3=8)) if font==0 the classic GFX font is used<BR>
|
||||
`C _p_` = set color (0,1) for black or white (later for color displays index colors)<BR>
|
||||
|
||||
## Notes about e-Paper displays
|
||||
|
||||
E-Paper displays have 2 operating modes: full update and partial update.
|
||||
While full update delivers a clean and sharp picture it has the disadvantage of taking several seconds for the screen update and shows severe flickering during update.
|
||||
Partial update is quite fast (300 ms) with no flickering but there is the possibility that erased content is still slightly visible.
|
||||
To "whiten" the display it is therefore useful to perform a full update in regular intervals (e.g each hour).
|
||||
|
||||
Defines => USE_SOFTSPI, USE_DISPLAY_EPAPER29, USE_DISPLAY_EPAPER42
|
||||
|
||||
## Hardware connections:
|
||||
|
||||
I2C displays are connected in the usual manner and defined via Tasmota pin selection.
|
||||
The I2C Adress must be given by `DisplayAddress XX`, e.g. 60, and the model set with `DisplayModel`
|
||||
,e.g. 2 for SSD1306.
|
||||
To permanently turn the display on set `DisplayDimmer 100`.
|
||||
Display rotation can be permanently set using `DisplayRotate X` (x = `0..3`).
|
||||
|
||||
E-Paper displays are connected via 3 wire SPI (CS, SCLK, MOSI) the other 3 Interface lines of the display
|
||||
(DC, Reset, busy) may be left unconnected.
|
||||
The jumper on the circuit board of the display must be set to 3 wire SPI.
|
||||
|
||||
# Examples
|
||||
|
||||
Print Text at size 1 on line 1, column 1:
|
||||
```
|
||||
DisplayText [s1l1c1]Hello how are you?
|
||||
```
|
||||
|
||||
Draw a rectangle and draw text inside with size 2 and 7 chars padded with spaces:
|
||||
```
|
||||
DisplayText [x85y95h130v30h-130v-30s2p7x90y100]37.25 C
|
||||
```
|
||||
|
||||
Clear screen:
|
||||
```
|
||||
DisplayText [z]
|
||||
```
|
||||
|
||||
Draw rectangle from x,y with width and height:
|
||||
```
|
||||
DisplayText [x50y50r200:100]
|
||||
```
|
||||
|
||||
### Display local sensors using rules
|
||||
|
||||
Show sensor values, time and a separation line, whiten display every 60 minutes (line breaks and
|
||||
indentation added for readability):
|
||||
```
|
||||
rule1 on tele-SHT3X-0x44#Temperature do DisplayText [f1p7x0y5]%value% C endon
|
||||
on tele-SHT3X-0x44#Humidity do DisplayText [f1p10x70y5]%value% %[x0y20h296x250y5t] endon
|
||||
on tele-BMP280#Pressure do DisplayText [f1p10x140y5]%value% hPa endon
|
||||
on Time#Minute|60 do DisplayText [Tt] endon
|
||||
```
|
||||
|
||||
Show 4 analog channels (line breaks and indentation added for readability):
|
||||
```
|
||||
rule1 on tele-ADS1115#A0 do DisplayText [s1p21c1l01]Analog1: %value% adc endon
|
||||
on tele-ADS1115#A1 do DisplayText [s1p21c1l3]Analog2: %value% adc endon
|
||||
on tele-ADS1115#A2 do DisplayText [s1p21c1l5]Analog3: %value% adc endon
|
||||
on tele-ADS1115#A3 do DisplayText [s1p21c1l7]Analog4: %value% adc endon
|
||||
```
|
||||
|
||||
Show BME280 + SGP30 (line breaks and indentation added for readability):
|
||||
```
|
||||
rule1 on tele-BME280#Temperature do DisplayText [s1p21x0y0]Temp: %value% C endon
|
||||
on tele-BME280#Humidity do DisplayText [s1p21x0y10]Hum : %value% %% endon
|
||||
on BME280#Pressure do DisplayText [s1p21x0y20]Prss: %value% hPa endon
|
||||
on tele-SGP30#TVOC do DisplayText [s1p21x0y30]TVOC: %value% ppb endon
|
||||
on tele-SGP30#eCO2 do DisplayText [s1p21x0y40]eCO2: %value% ppm [s1p0x0y50]Time: [x35y50t] endon
|
||||
```
|
||||
|
||||
## Notes about display drivers:
|
||||
|
||||
Waveshare has 2 kinds of display controllers: with partial update and without partial update. The 2.9 inch driver is for partial update and should support also other Waveshare partial update models with modified WIDTH and HEIGHT parameters.
|
||||
The 4.2 inch driver is a hack which makes the full update display behave like a partial update and should probably work with other full update displays.
|
||||
|
||||
The drivers are sub classes of the Adafruit GFX library.
|
||||
The class hierarchy is `LOWLEVEL :: Paint :: Renderer :: GFX`, where:
|
||||
`GFX`: unmodified Adafruit library
|
||||
`Renderer`: the interface for Tasmota
|
||||
`Paint`: the modified pixel driver for e-paper
|
||||
- there are several virtual functions that can be subclassed down to `LOWLEVEL`.
|
||||
|
||||
The display dispatcher only does the class init call.
|
||||
All other calls go to the `Renderer` class.
|
||||
|
||||
In black and white displays a local ram buffer must be allocated before calling the driver.
|
||||
This must be set to zero on character or TFT color displays.
|
||||
|
||||
To use the 400x300 e-Paper display the Arduino library 2.4 or later must be used because it leaves much
|
||||
more RAM available than prior versions. This display requires 15k of RAM!
|
||||
|
||||
About 28 k flash is used by these 4 drivers, the epd fonts use about 9k space, which can be if-def'd.
|
||||
|
||||
- SSD1306 = 1,15 k
|
||||
- SH1106 = 1,18 k
|
||||
- EPD42 = 2,57 k
|
||||
- EPD29 = 2,1 k
|
||||
- Display and Render class about 12 k
|
||||
Loading…
Reference in New Issue