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 DISPLAY CLIMATE

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 or frames” of information. The number of pages depends on the number of set lines of text and the font size.

Configuration

../_images/P036_DeviceConfiguration.png
  • Name: A unique name should be entered here.

  • Enabled: The device can be disabled or enabled. When not enabled the device should not use any resources.

I2C Options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the Hardware page

Device Settings

../_images/P036_ControllerOptions.png
  • Controller: Select the controller chip that is used for the display. There are 2 options available, SSD1306 and SH1106.

../_images/P036_DisplaySizeOptions.png
  • Display Size: Select the pixel resolution of the display.

../_images/P036_RotationOptions.png
  • Rotation: Select if the display is mounted normally or upside-down (rotated 180 degrees).

  • Lines per Frame: The maximum number of ‘Lines per frame’ depends on the display size (height). Select from 1..4. This determines the number of frames, so there can be 12 frames of 2 line, 6 frames of 2 lines, 4 frames of 3 lines, or 4 frames of 3 lines.

  • Reduce no. of lines to fit font: (default: off) can be used to reduce the lines per frame to fit the set font for the lines. If not checked the maximum used font size is limited.

../_images/P036_ScrollOptions.png
  • Scroll: Switching between pages can be “instant”, “scrolling” or a “ticker” band. Please note that scrolling will need more resources of the ESP, which can have an effect on other active tasks of the node.

For the Ticker there are some restrictions:

  • Depending on the build used (NORMAL and CUSTOM) this option is available

  • only one line is displaying the ticker string

  • all line contents are parsed and combined to this ticker string, the parsing happens only at each ticker start (using the setting Interval)

  • the optional split token <|> is replaced by three spaces

  • the gaps between the ticker items must be set by the line content (trailing spaces)

  • the starting alignment (left, center, right) depends on the setting Align content (global)

  • the font is taken from the setting Modify font of the first line, the Alignment settings of the lines are ignored (always right aligned)

  • the ticker speed depends on the length of the ticker string and the task Interval setting

  • the footer is automatically hidden

  • GPIO <- Display button: Setting up a Display Button, allows to configure a Display Timeout and wake the display on demand, either by a button, or by using some presence detection.

../_images/P036_PinModeOptions.png
  • Pin mode: Select how the button pin is to be configured, either regular input, using an external pull-up resistor, or using the ESP internal pull-up resistor. When using wiring > 30 cm. an external pull-up resistor of ~10k is advised to be used.

  • Inversed Logic: Should be checked when using a button that connects the input to ground when pressed. Default a high signal is used to wake the display, as that is the standard output for most IR detection sensors.

  • Step through pages with Display button: When enabled the button can also be used to step through the pages (frames), 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.

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

../_images/P036_ContrastOptions.png
  • Contrast: Select the desired contrast. To prolong the working life of the display, it is advised to use a low/medium contrast level, and turn off the display automatically after some time.

  • Disable all scrolling while WiFi is disconnected: When checked switching between the pages is always “instant” and long lines are not scrolling as long as no Wifi connection is established. The Wifi connection attempts use a lot of resources and the scrolling may be disturbed by that.

../_images/P036_GenerateEventsOptions.png
  • Generate Events: Depending on the build used (NORMAL and CUSTOM), an option to generate events can be set, that will generate an event if the display is turned on or off, the contrast setting is changed, a new frame is shown, the number of lines per frame is changed or a line is updated using the oledframedcmd,<line>,<text> command.

Content

  • Hide header: When checked the Header that is normally shown will be suppressed. This will aloow more content on the display, or the content to be displayed in a larger font.

  • Hide indicator: When checked will not show the page indicator at the bottom of the screen, again to fit more content on the screen or use a larger font. On the 128x32 display this option is always enabled, as that display is rather small.

../_images/P036_HeaderOptions.png
  • Header / Header (alternate): The plugin allows for a header line, which may show some user selectable information. When using a different setting for Header (alternate), the header will be updated halfway of the Interval time. The User defined 1/2 options are not available in all builds. If they are available, their content can be set using the oledframedcmd,userDef1,'<user Defined Header1>' and oledframedcmd,userDef2,'<user Defined Header2>' commands (by default they are empty), see the command reference below for details.

  • Scroll long lines: When checked, lines that won’t fit on the display will be scrolled to be completely shown.

  • Wake display on receiving text: (default: on) Allows to not wake up the display when a text is sent from a remote source or rules, when Display Timeout is set, by unchecking this option.

Lines

../_images/P036_AlignContentOptions.png
  • Align content (global): this setting will be used to align all lines that use the Use global setting, but there are also individual align and font settings for each line.

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

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

The user defined texts may also contain a split token <|> to display the line splitted, the left part left-aligned and the other part right-aligned on the display. This will override the Alignment setting.

../_images/P036_ModifyFontOptions.png
  • Modify Font: For each line, the font to be used can be selected, from the options shown here.

../_images/P036_AlignmentOptions.png
  • Alignment: For each line, the alignment to be used can be selected, or the global setting can be used.

  • Interval By default, Interval will be set to 0. It needs to be set to a non-zero value, to switch between the frames using that interval (seconds).

General

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.

  • user will set the contrast, precharge and comdetect to user defined values.

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.

For the parameter of the user setting refer to the data sheet of the display. An example for very low brightness with an user setting is <oledframedcmd,display,user,100,0,64>.

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. A split token <|> can be used to display the line splitted, one part on the left the other one on the right side of the display.

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. The line text can also be restored from the settings by the command restore.

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). If scroll is set to ticker only <framenr> = 1 is supported, it starts the ticker from the beginning.

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.

oledframedcmd,linecount,<1..4>

This command changes the number of lines in each frame. When the next frame is to be displayed, the frames are recalculated and the sequence is restarted at the first frame. If scroll is set to ticker this command is not supported.

If Generate events for ‘Linecount’ is selected, a <taskname#linecount=<lines> event is generated on initialization of the plugin and when changing the setting.

oledframedcmd,leftalign,<0|1>

Set the global Left-align option for content off (0) or on (1).

oledframedcmd,align,<0|1|2>

Set the global align option for content to centre (0), left (1) or right (2).

oledframedcmd,userDef1,'<user Defined Header1>'

Set the user defined header nr. 1 with any desired text value.

Use $<sysvar>$ instead of %<sysvar>% to use system variables.

oledframedcmd,userDef2,'<user Defined Header2>'

Set the user defined header nr. 2 with any desired text value.

Use $<sysvar>$ instead of %<sysvar>% to use system variables.

oledframedcmd,restore,<line>

If the <line> parameter is set to 0 all line contents will be restored from the settings. Otherwise the <line> parameter corresponds with the same lines as the plugin configuration has, and only the content of this line will be restored from the settings.

oledframedcmd,scroll,<speed>

The <speed> parameter corresponds with the line number of the scroll parameter of the settings (1=Very slow … 6=Ticker). After applying the new scroll speed the display restarts with the first page.

Events

Event

Example

OLedFramed#display=<on|off> Will trigger when the display is turned on(1) or off(0).

OLedFramed#frame=<framenr> Will trigger when the displayed frame is changed.

OLedFramed#line=<linenr> Will trigger when a line is updated via the OLedFramedCmd,<linenr>,'<content>' command.

OLedFramed#linecount=<count> Will trigger when the number of lines to display is changed via the OLedFramedCmd,linecount,<count> command, and when the display is initialized.

OLedFramed#contrast=<contrast> Will trigger when the contrast of the display is changed.

Change log

Changed in version 2.0:

added Major overhaul for 2.0 release.

New in version 1.0:

added Initial release version.