mailto: blog -at- heyrick -dot- eu
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.
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).
This is not good:
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'.
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:
|Terminator (marks end of line)|
|Backspace (moves cursor back a character, does not delete)|
|Forwardspace (moves cursor forward a character, does not erase)|
|Linefeed (moves cursor down a line)|
|Reverse linefeed (moves cursor up a line)|
|Clears the display (more simplistic than OLED_CLS)|
|Carriage return (moves cursor to leftmost position on line)|
|Set inverse text colour|
|Restore normal text colour|
|Home cursor (to 1,1 upper left)|
|Position text cursor (following two bytes give X,Y position)|
|Delete (moves cursor back a character, deletes)|
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.
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.
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
will force the upside-down (default) orientation.
*Set OLED$Orientation 1
will force the orientation to be the right way up.
*Set OLED$Orientation 2
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
will set the contrast level to 25%. The acceptable range is 0 to 255 (&0 to &FF).
*Set OLED$Contrast 63
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.
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
Here is a simple program to demonstrate:
SYS "OLED_Print", "Hello!"
A simple application
Here is the source code for a simple (single-tasking) clock using the OLED.
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)
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
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...
Please note that while I check this page every so often, I am not able to control what users write; therefore I disclaim all liability for unpleasant and/or infringing and/or defamatory material. Undesired content will be removed as soon as it is noticed. By leaving a comment, you agree not to post material that is illegal or in bad taste, and you should be aware that the time and your IP address are both recorded, should it be necessary to find out who you are. Oh, and don't bother trying to inline HTML. I'm not that stupid! ☺
You can now follow comment additions with the comment RSS feed. This is distinct from the b.log RSS feed, so you can subscribe to one or both as you wish.
|Rick, 19th July 2014, 12:21|
|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.
List all b.log entries
Return to the site index
PS: Don't try to be clever.
It's a simple substring match.
Last read at 03:04 on 2020/07/13.
© 2014 Rick Murray
This web page is licenced for your personal, private, non-commercial use only. No automated processing by advertising systems is permitted.
RIPA notice: No consent is given for interception of page transmission.