From a1b8e9f93b06de10a73da6a0bbf3bfa18ec1d2d9 Mon Sep 17 00:00:00 2001 From: blakadder Date: Sat, 23 Feb 2019 20:36:03 +0100 Subject: [PATCH] Reformatted into Displays.md --- Display-Commands.md | 201 -------------------------------------------- Displays.md | 183 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 201 deletions(-) delete mode 100644 Display-Commands.md create mode 100644 Displays.md diff --git a/Display-Commands.md b/Display-Commands.md deleted file mode 100644 index 897e051c..00000000 --- a/Display-Commands.md +++ /dev/null @@ -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 diff --git a/Displays.md b/Displays.md new file mode 100644 index 00000000..afe8b7ce --- /dev/null +++ b/Displays.md @@ -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 +|:--- | :--- + Display | Show current display setting as JSON string + DisplayAddress | `0..255` = set display module address + DisplayDimmer | `0` = switch the display off
`1..100` = switch the display on
`0..100` = set display luminosity *(only on 8x8 Dot-Matrix displays)* + DisplayMode | `0..5` = set to display [predefined content](#displaymode-parameters) according to display type + DisplayModel | Set model of your display:
`1` = I2C LCD Display (default addresses `0x27`, `0x3F`)
`2` = [SSD1306](https://learn.adafruit.com/monochrome-oled-breakouts/arduino-library-and-examples) OLED 128x32/128x64 (default addresses `0x3C`, `0x3D`)
`3` = 8x8 Dot-Matrix
`4` = [ILI9341](https://www.adafruit.com/product/1770) TFT LCD
`5` = E-Paper Display + DisplayRefresh | `1..7` = set time in seconds to update predefined content when using `DisplayMode` ≠ `0` + DisplaySize | `1..4` = set display scale-up size (only for `DisplayModel 2` (SSD1306 OLED) and `DisplayModel 4` (ILI9341 TFT LCD)) + DisplayRotate | Set rotation angle
`0` = 0°
`1` = 90°
`2` = 180°
`3` = 270° + DisplayText | `` = for a full guide see [DisplayText use](displays#displaytext-use) + DisplayCols | `1..44` = set number of display columns + DisplayRows | `1..32` = set number of display rows + 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
+`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 with `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` (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