From 4a099522195fa9443005e922f3b9891ef7aeb66e Mon Sep 17 00:00:00 2001 From: Michael Ingraham <34340210+meingraham@users.noreply.github.com> Date: Tue, 20 Aug 2019 13:12:56 -0400 Subject: [PATCH] Updated Displays (markdown) --- Displays.md | 229 ++++++++++++++++++++++------------------------------ 1 file changed, 98 insertions(+), 131 deletions(-) diff --git a/Displays.md b/Displays.md index 7c70cf36..66c6a0d8 100644 --- a/Displays.md +++ b/Displays.md @@ -16,8 +16,8 @@ All display commands: DisplayCols | `1..44` = set number of display columns (for display modes>0) DisplayRows | `1..32` = set number of display rows (for display modes>0) DisplayFont | specifies the current font ((1=12, 2=24,(opt 3=8)) if font==0 the classic GFX font is used if font==7 the RA8876 internal font is used - DisplayWidth | specifies the display width in pixles (settable only on ssd1306) - DisplayHeight | specifies the display height in pixles (settable only on ssd1306) + DisplayWidth | specifies the display width in pixels (settable only on ssd1306) + DisplayHeight | specifies the display height in pixels (settable only on ssd1306) ## DisplayMode Parameters @@ -33,7 +33,7 @@ Parameter | LCD Display | OLED Display | TFT Display 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 -## defines used +## Compilation \#define directives used Feature | Description | -- | -- | @@ -65,66 +65,65 @@ In order to use the `DisplayText` command the `DisplayMode` must be set to `0` ( ## DisplayText parameters -In the list below `_p_` stands for parameter and may be a number from 1 to n digits. +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 (on LCD display _p_ = {0…}, on TFT display _p_ = {1…})
-`c _p_` = sets a character column to print at (on LCD display _p_ = {0…}, on TFT display _p_ = {1…})
-`x _p_` = sets the x position for consecutive prints
-`y _p_` = sets the y position for consecutive prints
+`lp` = sets a character line to print at (on LCD display `p` = {0…}, on TFT display `p` = {1…}) +`cp` = sets a character column to print at (on LCD display `p` = {0…}, on TFT display `p` = {1…}) +`xp` = sets the x position for consecutive prints +`yp` = 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
-`u _p_:_p_:_p_` = draws a rounded rectangle with _p_ with, _p_ height and _p_ radius
-`U _p_:_p_:_p_` = draws a filled rounded rectangle with _p_ with, _p_ height and _p_ radius
+`hp` = draws a horizontal line with length `p` (x is advanced) +`vp` = draws a vertical line with length `p` (y is advanced) +`Lp:p` = draws a line top:`p` (x,y are advanced) +`kp` = draws a circle with radius `p` +`Kp` = draws a filled circle with radius `p` +`rp:p` = draws a rectangle with `p` with and `p` height +`Rp:p` = draws a filled rectangle with `p` with and `p` height +`up:p:p` = draws a rounded rectangle with `p` with, `p` height and `p` radius +`Up:p:p` = draws a filled rounded rectangle with `p` with, `p` height and `p` radius ### 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
-`a`_p_ = _p_ (0..3) set rotation angle
-`t` = display Tasmota time in HH:MM
-`tS` = display Tasmota time in HH:MM:SS
-`T` = display Tasmota date in DD.MM.YY
-`p _p_` = pad text with spaces, positiv values align left, negativ values -align right
-`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, if font==7 RA8876 internal font is used
-`C _p_` = set foreground color (0,1) for black or white and RGB decimal code for color
-`B _p_` = set background color (0,1) for black or white and RGB decimal code for color
-`Ci _p_` = set foreground index color (0..18) for color displays (see index color table below)
-`Bi _p_` = set background index color (0..18) for color displays (see index color table below)
-`w _p_` = draws an analog watch with radius p (#define USE_AWATCH)
-`Pfilename:` = display an rgb 16bit color image when sdcard file system is present
+`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 +`Dp` = 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 +`ap` = `p` (0..3) set rotation angle +`t` = display Tasmota time in HH:MM +`tS` = display Tasmota time in HH:MM:SS +`T` = display Tasmota date in DD.MM.YY +`pp` = pad text with spaces, positiv values align left, negativ values +align right +`sp` = set text scaling for classic GFX font (scaling factor 1...N) +`fp` = set font (1=12, 2=24,(opt 3=8)) if font==0 the classic GFX font is used, if font==7 RA8876 internal font is used +`Cp` = set foreground color (0,1) for black or white and RGB decimal code for color +`Bp` = set background color (0,1) for black or white and RGB decimal code for color +`Cip` = set foreground index color (0..18) for color displays (see index color table below) +`Bip` = set background index color (0..18) for color displays (see index color table below) +`wp` = draws an analog watch with radius p (#define USE_AWATCH) +`Pfilename:` = display an rgb 16bit color image when sdcard file system is present -Touch Buttons: +Touch Buttons (`#define USE_TOUCH_BUTTONS`): -Draw GFX Buttons (up to 16) buttons switch real Tasmota devices like relais. When button number + 256 a virtual touch toggle button is created (MQTT => TBT) -when button number + 512 a virtual touch push button is created (MQTT => PBT) -(#define USE\_TOUCH\_BUTTONS) -parameters, separated by colons +Draw up to 16 GFX buttons to switch real Tasmota devices such as relays. +- Button number + 256 - a virtual touch toggle button is created (MQTT => TBT) +- Button number + 512 - a virtual touch push button is created (MQTT => PBT) + +Parameters are separated by colons. For example: `b0:260:260:100:50:2:11:4:2:Rel 1:` -example b0:260:260:100:50:2:11:4:2:Rel 1: - ->b _p_ =button number 0-15 +>bp `p` = button number 0-15 xp = x position yp = y position xa = x size @@ -163,27 +162,19 @@ v = float value to add Gsn:path: = save graph n to path (if optional sdcard present) Grn:path: = restore graph n from path (if optional sdcard present) -### Index colors selected in the color panels ILI9488,SSD1351,RA8876 with Ci and Bi +### Index colors ->0=COLOR\_BLACK -1=COLOR\_WHITE -2=COLOR\_RED -3=COLOR\_GREEN -4=COLOR\_BLUE -5=COLOR\_CYAN -6=COLOR\_MAGENTA -7=COLOR\_YELLOW -8=COLOR\_NAVY -9=COLOR\_DARKGREEN -10=COLOR\_DARKCYAN -11=COLOR\_MAROON -12=COLOR\_PURPLE -13=COLOR\_OLIVE -14=COLOR\_LIGHTGREY -15=COLOR\_DARKGREY -16=COLOR\_ORANGE -17=COLOR\_GREENYELLOW -18=COLOR\_PINK +Selected with `Ci` and `Bi` in the ILI9488, SSD1351, and RA8876 color panels + +| Index | Color | Index | Color | Index | Color | +| -- | -- | -- | -- | -- | -- | +| 0 | BLACK | 1 | WHITE | 2 | RED | +| 3 | GREEN | 4 | BLUE | 5 | CYAN | +| 6 | MAGENTA | 7 | YELLOW | 8 | NAVY | +| 9 | DARKGREEN | 10 | DARKCYAN | 11 | MAROON | +| 12 | PURPLE | 13 | OLIVE | 14 | LIGHTGREY | +| 15 | DARKGREY | 16 | ORANGE | 17 | GREENYELLOW | +| 18 | PINK | ## Notes about e-Paper displays @@ -192,68 +183,49 @@ While full update delivers a clean and sharp picture it has the disadvantage of 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\_SPI, USE\_DISPLAY, USE\_DISPLAY\_EPAPER29 or USE\_DISPLAY\_EPAPER42 +Compilation \#defines => `USE_SPI`, `USE_DISPLAY`, `USE_DISPLAY_EPAPER29`, or `USE_DISPLAY_EPAPER42` -remark: the 4.2 epaper needs about 15k RAM. therefore it only works with Core 2.42 and above +Remark: the 4.2 epaper requires about 15k of RAM. Therefore it only works with Core 2.42 and above -## Notes about OLED lifetime -The lifetime of an OLED when permanetely on ist specified at about 10000 hours (416 days) (dimming to 50% expands the lifetime to about 25000 hours) +## OLED lifetime +The lifetime of an OLED when permanently on ist specified at about 10000 hours (416 days) (dimming to 50% expands the lifetime to about 25000 hours) -## Notes about burnin +## Burn-in The data sheets of the TFT and OLED displays mention burn in effects when a static display is shown for extended periods of time. You may consider switching the display on on demand only. -## Notes about fonts -The EPD fonts contains 95 chars starting from code 32 while the classic -GFX font containts 256 chars ranging from 0 to 255. -To display chars above code 127 you must specify an escape sequence -(standard octal escapes dont work here) the `~`character followed by a -hex byte can define any character code. So custom characters above 127 -can be displayed +## Fonts +The EPD fonts contains 95 characters starting from code 32 while the classic GFX font contains 256 characters ranging from 0 to 255. To display characters above code 127 you must specify an escape sequence (standard octal escapes don't work). The `~`character followed by a hex byte can define any character code. So custom characters above 127 can be displayed -## Hardware connections: +## Hardware Connections +I2C displays are connected in the usual manner and defined via Tasmota pin selection. -I2C displays are connected in the usual manner and defined via Tasmota pin selection. -The I2C Address 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`). +The I2C address must be specified using `DisplayAddress XX`, e.g., `60`. The model must be spedified 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 software 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. +E-Paper displays are connected via software 3-wire SPI `(CS, SCLK, MOSI)` the other three 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. -The ILI9488 and SSD1351 are connected via hardware 3 wire SPI `(MOSI=GPIO13, SCLK=GPIO14,CS=GPIO15)`, the ILI9488 must also be connected to backlight pin -(dimmer supported on SSD1351) - -The RA8876 is connected via standard hardware 4 wire SPI `(MOSI=GPIO13, MISO=GPIO12, SCLK=GPIO14, CS=GPIO15)` no backlight pin needed (dimmer supported) +The ILI9488 and SSD1351 are connected via hardware 3-wire SPI `(MOSI=GPIO13, SCLK=GPIO14,CS=GPIO15)`. The ILI9488 must also be connected to the backlight pin (dimmer supported on SSD1351) +The RA8876 is connected via standard hardware 4-wire SPI `(MOSI=GPIO13, MISO=GPIO12, SCLK=GPIO14, CS=GPIO15)`. No backlight pin is needed (dimmer supported). # Examples -Print Text at size 1 on line 1, column 1: -``` -DisplayText [s1l1c1]Hello how are you? -``` +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 -``` +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] -``` +Clear screen: +`DisplayText [z]` -Draw rectangle from x,y with width and height: -``` -DisplayText [x50y50r200:100] -``` +Draw rectangle from x,y with width and height: +`DisplayText [x50y50r200:100]` -### Display local sensors using rules +### Display local sensors +_(line breaks and indentation added to the rules for readability)_ -Show sensor values, time and a separation line, whiten display every 60 minutes (line breaks and -indentation added for readability): +Use Tasmota rules to display sensor values, time, and a separation line. Clear the display every 60 minutes : ``` rule1 on tele-SHT3X-0x44#Temperature do DisplayText [f1p7x0y5]%value% C endon on tele-SHT3X-0x44#Humidity do DisplayText [f1p10x70y5]%value% %[x0y20h296x250y5t] endon @@ -261,7 +233,7 @@ rule1 on tele-SHT3X-0x44#Temperature do DisplayText [f1p7x0y5]%value% C endon on Time#Minute|60 do DisplayText [Tt] endon ``` -Show 4 analog channels (line breaks and indentation added for readability): +Show 4 analog channels: ``` rule1 on tele-ADS1115#A0 do DisplayText [s1p21c1l01]Analog1: %value% adc endon on tele-ADS1115#A1 do DisplayText [s1p21c1l3]Analog2: %value% adc endon @@ -269,7 +241,7 @@ rule1 on tele-ADS1115#A0 do DisplayText [s1p21c1l01]Analog1: %value% adc endon on tele-ADS1115#A3 do DisplayText [s1p21c1l7]Analog4: %value% adc endon ``` -Show BME280 + SGP30 (line breaks and indentation added for readability): +Show BME280 + SGP30: ``` rule1 on tele-BME280#Temperature do DisplayText [s1p21x0y0]Temp: %value% C endon on tele-BME280#Humidity do DisplayText [s1p21x0y10]Hum : %value% %% endon @@ -278,30 +250,25 @@ rule1 on tele-BME280#Temperature do DisplayText [s1p21x0y0]Temp: %value% C endon on tele-SGP30#eCO2 do DisplayText [s1p21x0y40]eCO2: %value% ppm [s1p0x0y50]Time: [x35y50t] endon ``` -## Notes about display drivers: +## 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. +Waveshare has two kinds of display controllers: with partial update and without partial update. The 2.9 inch driver is for partial update and should also support 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 +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. +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. +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! +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! -The epd fonts use about 9k space, which can be if-def'd. +The epd fonts use about 9k space, which can be selected at compile time using \#ifdef directives. -- SSD1306 = 1,15 k -- EPD42 = 2,57 k -- EPD29 = 2,1 k -- Display and Render class about 12 k \ No newline at end of file +- SSD1306 - 1.15k +- EPD42 - 2.57k +- EPD29 - 2.1k +- Display and Render class - ~12k \ No newline at end of file