displays - seurat-atreides/Sonoff-Tasmota GitHub Wiki

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 according to display type
DisplayModel Set model of your display:
1 = I2C LCD Display (default addresses 0x27, 0x3F)
2 = SSD1306 OLED 128x32/128x64 (default addresses 0x3C, 0x3D)
3 = 8x8 Dot-Matrix
4 = ILI9341 TFT LCD
5 = E-Paper Display
DisplayRefresh 1..7 = set time in seconds to update predefined content when using DisplayMode0
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 <value> = for a full guide see 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

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 (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

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 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).

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
⚠️ **GitHub.com Fallback** ⚠️