Rick's b.log - entry 2014/04/26

mailto: blog -at- heyrick -dot- eu

FYI! Last read at 05:12 on 2024/11/24.

Geekfest! An OLED on the Pi! (part 2)

Now that the hardware is in place, it is time to make use of it.

The first step is to download the OLED module. Within the archive, you will find the module, plus various small test programs, and the demo program that you saw the video of in the last b.log entry.

Double-click on the OLED module. Nothing will appear on the display, though it will be configured and made active. If nothing appears to happen, that is good.
This is not good:

If you see the error, verify that your OLED is connected correctly, and is based upon the SSD1306 controller, and - if you have an option - responds as device #60 (or 60<<1 if counting the r/w bit).

Introduction

The OLED module provides you with a simple way to make use of an attached OLED display. How you manage this depends upon your requirements and the level of complexity you wish to attain. SWIs are provided for writing text (which will appear in the RISC OS "system" (VDU) font), basic graphics (line, rectangle, circle, triangle), plus the ability to transfer sprites to the display if you have pre-made images, or if there is something that is more complex than that which can be realistically 'drawn'.

Text plotting

The display module text area is 16×8. This is 16 characters across the display and 8 rows down. This provides a total of 128 characters.
The home position is 1,1, the upper left.

As mentioned above, text is displayed in the RISC OS VDU font, obeying roughly the same rules as the standard VDU text mechanism. Scrolling is automatic, paged mode is not available, and text is plotted in VDU4 mode.
To change how the text appears, simply change the VDU font. The command *FX 25,0 will restore the default font.

When plotting text, most control codes are suppressed. Some have a special purpose:

`0`	Terminator (marks end of line)
`8`	Backspace (moves cursor back a character, does not delete)
`9`	Forwardspace (moves cursor forward a character, does not erase)
`10`	Linefeed (moves cursor down a line)
`11`	Reverse linefeed (moves cursor up a line)
`12`	Clears the display (more simplistic than OLED_CLS)
`13`	Carriage return (moves cursor to leftmost position on line)
`19`	Set inverse text colour
`20`	Restore normal text colour
`30`	Home cursor (to 1,1 upper left)
`31`	Position text cursor (following two bytes give X,Y position)
`127`	Delete (moves cursor back a character, deletes)

Graphics plotting

The display offers 128 pixels horizontally by 64 pixels vertically. The home position is 0,0, the lower left.

Commands are provided to draw lines, (filled) rectangles, (filled) circles, and filled triangles. There is also the possibility to create your own sprites and use these instead of drawing into the display memory.

Display refreshing

Whenever you output something to the display, it will schedule a refresh in 5 centiseconds. This is to permit a number of text/graphics drawing commands to be performed without causing flicker or long delays due to repeated data transfer.
Once the 5cs delay expires, the cached display data will be sent to the OLED's GDRAM. Any subsequent output to the display will cause another refresh to be scheduled, and so on.
If the absolute maximum attainable speed is required (for animation or the like), you can call OLED_ForceRefresh which will remove the scheduled refresh and will instead do it immediately.

Module configuration

In the configuration that I am using, the OLED is actually mounted upside down. As you can see from the photo, this is to permit the connector to pass neatly through the slot in the Pi's casing so that it can lie flush with the casing.

Consequently, the module assumes that the OLED will be upside down. If this is correct, then you need do nothing. If you have a different case and you prefer to mount your OLED the right way up, then you will need to set the OLED$Orientation variable:

*Set OLED$Orientation 1

will force the upside-down (default) orientation.

*Set OLED$Orientation 2

will force the orientation to be the right way up.

I say "force" in italics because the OLED_Initialise SWI has an option to set the orientation, however if an orientation is specified using a system variable, then anything else is ignored.

The default contrast (brightness) of the OLED is nominally 50% (though in actuality there is more difference between dimmest and 50% than 50% and brightest). If you wish to select a different level of contrast, you will need to set the OLED$Contrast variable:

*Set OLED$Contrast 63

will set the contrast level to 25%. The acceptable range is 0 to 255 (&0 to &FF).
Here is a rough demonstration of different contrast levels using a camera with exposure locked:

The configuration is read as the module initialises, and every time OLED_Initialise is called.

Getting going

Step one is to load the module if it is not already present. The usual way would be:

*RMEnsure OLED 0.01 RMLoad <your_path_here>.OLED

In your program, you should call OLED_Initialise once, followed by OLED_CLS.

Here is a simple program to demonstrate:

SYS "OLED_Initialise"
SYS "OLED_CLS"
SYS "OLED_Print", "Hello!"

A simple application

Here is the source code for a simple (single-tasking) clock using the OLED.

SYS "OLED_Initialise"
SYS "OLED_CLS"

invert$ = CHR$(19)
normal$ = CHR$(20)
crlf$   = CHR$(13)+CHR$(10)
curpos$ = CHR$(31)

SYS "OLED_Print", invert$+" RISC OS  clock "+normal$+crlf$+crlf$
SYS "OLED_Print", "The time now is:"+crlf$+crlf$
SYS "OLED_Print", "   "+RIGHT$(TIME$, 8)+crlf$+crlf$
SYS "OLED_Print", LEFT$(TIME$, 4)+" "+MID$(TIME$, 5, 11)

REPEAT
  t% = TIME
  REPEAT : UNTIL ((TIME - t%) > 100) : REM wait a second
  SYS "OLED_Print", curpos$+CHR$(5)+CHR$(5)+RIGHT$(TIME$, 8)
UNTIL FALSE :   REM Cursor to   col 5   row 5

Documentation?

Look at the documentation supplied with the module; also look at the source of the demo program.

Over to you!

Show me what you can do. Place links in the comments below...

Your comments:

Rick, 19th July 2014, 12:21

http://heyrick.co.uk/software/oled/

Chris Hall, 4th January 2017, 08:40

The drivers are excellent. I got a couple of OLED displays and they needed no track cutting and joining. Worked first time. See here: http://www.svrsig.org/images/HZ338s.jpg and here: http://www.svrsig.org/PiGPS.htm.

See the rest of HeyRick :-)

	Rick's b.log - 2014/04/26
It is the 24th of November 2024 You are 3.145.33.230, pleased to meet you!

Rick's b.log - 2014/04/26