Display - OLED SSD1306/SH1106 Framed¶

Plugin for displaying information on several pages on SSD1306/SH1106 OLED

Plugin details¶

Type: Display

Name: OLED SSD1306/SH1106 Framed

Status: NORMAL

GitHub: P036_FrameOLED.ino

Maintainer: TD-er

Used libraries: https://github.com/squix78/esp8266-oled-ssd1306 version 3.2.7

Description¶

The Framed OLED plugin does allow a bit more fancy look and feel compared to P023 OLED.

The plugin allows to show several “pages” of information. The number of pages depends on the number of set lines of text and the font size.

Switching between pages can be “instant” or “scrolling”. Please note that scrolling may need more resources of the ESP, which can have an effect on other active tasks of the node.

Setting up a Display Button, allows to configure a Display Timeout and wake the display on demand. Inversed Logic should be checked when using a button that connects the input to ground when pressed.

When enabling “Step through pages with Display button”, the button can also be used to step through the pages, when having multiple pages, to display the content on demand. If this option is unchecked, then, when available, the next page will be displayed after Interval seconds have passed. Pressing the button restarts the Display Timeout timer. When holding the button pressed, the next page will be shown after a 1 second delay.

The Display Timeout setting sets the numbers of seconds after which the display is turned off. When set to 0 no timeout is active.

The plugin allows for a header and footer line, which may show some user selectable information.

Checkbox ‘Wake display on receiving text’ (default: on) allows to not wake up the display when a text is sent from a remote source, and Display Timeout is set.

All user defined texts may contain references to system variables or task values which will be interpreted when displayed on screen.

For example: [bme#T#D2.1] {D}C [bme#H]%

Supported hardware¶

Commands available¶

Command	Extra information
`oledframedcmd,display,<value>` Value: `on` will turn the display ON. `off` will turn the display OFF. `low` will dim the display to low. `med` will dim the display to medium. `high` will set the brightness to maximum.	OLED displays will age quite fast, so it is not adviced to run them continously at max brightness. Some displays do not accept all brightness levels and some also make a quite high pitch coil whine noise when running on some brightness levels. So different levels of brightness can also be of help on those displays. The display controller itself does support more brightness levels, but these are chosen to give noticable change in brightness levels and also to help in choosing the best values for the 2 brightness control registers. As there are 2 brightness control registers, there is some overlap in their range, but some combinations may lead to issues like coil whining noise or sometimes not even working displays as not all of these displays are wired to support both controls to be used.
`oledframedcmd,<line>,<text>`	The <line> parameter corresponds with the same lines as the plugin configuration has. The <text> parameter must be a single command parameter. Meaning, it must be wrapped in quotes when using a space or comma as text. If double quote characters are needed, wrap the parameter in single quotes or back quotes. The updated line text is not stored in the settings itself, but kept in memory. After a reboot the stored plugin settings will be used. All template notations can be used, like system variables, or reference to a task value. After receiving text this way, the frame where the text is placed is shown, if the setting for ‘Wake display on receiving text’ is checked.
`oledframedcmd,frame[,<framenr>]`	This command is to display a specific frame (aka page), or the next frame. When reaching the last frame, a ‘next’ (0) will display the first frame. The <framenr> parameter corresponds to the desired frame (1..<number of frames>) to display. The number of frames is determined by dividing the lines in use (at least one line in that frame with some data), by the number of Lines per Frame. So practically, the range is 1..3 when all lines are used and 4 Lines per Frame is set, or 1..12 if Line per frames is set to 1. The number of frames is updated if a frame would initially be empty, and an external source places text on a line of that frame (see above). When omitting <framenr>, or providing 0, the next frame is displayed. When the display is off, because a ‘Display Timeout’ is set and the timer has expired or it is turned off by the off command (see above), then it is turned on, and, when set, the timer is started again.

Command

Extra information

oledframedcmd,display,<value>

Value:

on will turn the display ON.
off will turn the display OFF.
low will dim the display to low.
med will dim the display to medium.
high will set the brightness to maximum.

OLED displays will age quite fast, so it is not adviced to run them continously at max brightness.

Some displays do not accept all brightness levels and some also make a quite high pitch coil whine noise when running on some brightness levels. So different levels of brightness can also be of help on those displays.

The display controller itself does support more brightness levels, but these are chosen to give noticable change in brightness levels and also to help in choosing the best values for the 2 brightness control registers. As there are 2 brightness control registers, there is some overlap in their range, but some combinations may lead to issues like coil whining noise or sometimes not even working displays as not all of these displays are wired to support both controls to be used.

oledframedcmd,<line>,<text>

The <line> parameter corresponds with the same lines as the plugin configuration has.

The <text> parameter must be a single command parameter. Meaning, it must be wrapped in quotes when using a space or comma as text.

If double quote characters are needed, wrap the parameter in single quotes or back quotes.

The updated line text is not stored in the settings itself, but kept in memory. After a reboot the stored plugin settings will be used.

All template notations can be used, like system variables, or reference to a task value.

After receiving text this way, the frame where the text is placed is shown, if the setting for ‘Wake display on receiving text’ is checked.

oledframedcmd,frame[,<framenr>]

This command is to display a specific frame (aka page), or the next frame. When reaching the last frame, a ‘next’ (0) will display the first frame.

The <framenr> parameter corresponds to the desired frame (1..<number of frames>) to display. The number of frames is determined by dividing the lines in use (at least one line in that frame with some data), by the number of Lines per Frame. So practically, the range is 1..3 when all lines are used and 4 Lines per Frame is set, or 1..12 if Line per frames is set to 1. The number of frames is updated if a frame would initially be empty, and an external source places text on a line of that frame (see above).

When omitting <framenr>, or providing 0, the next frame is displayed.

When the display is off, because a ‘Display Timeout’ is set and the timer has expired or it is turned off by the off command (see above), then it is turned on, and, when set, the timer is started again.

Change log¶

Changed in version 2.0: …

added Major overhaul for 2.0 release.

New in version 1.0: …

added Initial release version.