- Name : SSD1306_OLED_RPI
- Description :
- Library to support the I2C 128X64 OLED Display Module driven by the SSD1306 controller for the Raspberry PI.
- Dynamic install-able system level Raspberry Pi C library.
- Inverse color, rotate, sleep, scroll and contrast control.
- Default font is Extended ASCII, scalable font.
- 12 fonts included.
- Graphics class included.
- Bitmaps supported.
- Hardware I2C
- Also tested on 128X32 display size. Should work for 96X16 display size.
- Dependency: bcm2835 Library
-
Author: Gavin Lyons
-
Development Tool chain.
- Raspberry PI 3 model b
- C , g (Debian 12.2.0)
- Raspbian , Debian 12 bookworm OS, , 64 bit.
- kernel : aarch64 Linux 6.1.0-rpi7-rpi-v8
- bcm2835 Library 1.74 dependency. Provides low level I2C bus, delays and GPIO control.
-
Install the dependency bcm2835 Library if not installed (See Notes and issues)
- The bcm2835 library is a dependency and provides I2C bus, delays and GPIO control.
- Install the C libraries of bcm2835, Installation instructions here
-
Download the SSD1306_OLED_RPI library
- Open a Terminal in a folder where you want to download,build & test library
- Run following command to download from github.
curl -sL https://github.com/gavinlyonsrepo/SSD1306_OLED_RPI/archive/1.6.1.tar.gz | tar xz- Run "make" to run the makefile in repo base folder to install library, it will be installed to usr/lib and usr/include
cd SSD1306_OLED_RPI-1.6.1
make
sudo make install- Next step is to test OLED and installed library with an example. Wire up your OLED. Next enter the examples folder and run the makefile in THAT folder, This makefile builds the examples file using the just installed library. and creates a test exe file in "bin". The default example file is "hello world", user should see hello world on the OLED by end of these steps.
cd examples/
make
make run- There are multiple examples files to try out. To decide which one the makefile builds simply edit "SRC" variable at top of the makefile in examples folder. in the "User SRC directory Option Section". Pick an example "SRC" directory path and ONE ONLY. Comment out the rest and repeat: make and make run.
| Filepath | File Function | Screen Size |
|---|---|---|
| src/HELLO_WORLD | Basic use case | 128x64 |
| src/BITMAP | Shows use of bitmaps | 128x64 |
| src/CLOCK_DEMO | A basic clock Demo | 128x64 |
| src/OLED_FUNCTIONS | Test functions like scroll, rotate etc | 128x64 |
| src/SPEED_TEST | Frame rate per second test | 128x64 |
| src/TEXT_GRAPHICS | Tests Text , fonts and graphics | 128x64 |
Manufacturers diagram showing connections.
The Software is commented for "doxygen". If users uses "doxygen" software an application programming interface document can be generated.
Hardware I2C.
-
I2C Address is set by default to 0x3C(your module could be different, user can change argument passed into "OLEDbegin" method).
-
I2C Clock rate can be a passed into in the LCD class constructor method as a argument, User can pass 1 of 4 BCM2835_I2C_CLOCK_DIVIDER values 2500, 626 150 or 148. See image below.
-
In the event of an error writing a byte, debug info with error code will be written to console. This error code is the bcm2835I2CReasonCodes enum. Debug flag must be set to true to see this output. See image below for bcm2835I2CReasonCodes.
For more info on bcm2835I2CClockDivider & bcm2835I2CReasonCodes see bcm2835 doc's for details
Font data table:
| num | enum name | Char size XbyY | ASCII range | Size bytes | Scale-able |
|---|---|---|---|---|---|
| 1 | $_Default | 5x8 | 0-0xFF, Full Extended | 1275 | Y |
| 2 | $_Thick | 7x8 | 0x20-0x5A, no lowercase letters | 406 | Y |
| 3 | $_SevenSeg | 4x8 | 0x20-0x7A | 360 | Y |
| 4 | $_Wide | 8x8 | 0x20-0x5A, no lowercase letters | 464 | Y |
| 5 | $_Tiny | 3x8 | 0x20-0x7E | 285 | Y |
| 6 | $_Homespun | 7x8 | 0x20-0x7E | 658 | Y |
| 7 | $_Bignum | 16x32 | 0x2D-0x3A ,0-10 - . / : | 896 | N |
| 8 | $_Mednum | 16x16 | 0x2D-0x3A ,0-10 - . / : | 448 | N |
| 9 | $_ArialRound | 16x24 | 0x20-0x7E | 4608 | N |
| 10 | $_ArialBold | 16x16 | 0x20-0x7E | 3072 | N |
| 11 | $_Mia | 8x16 | 0x20-0x7E | 1520 | N |
| 12 | $_Dedica | 6x12 | 0x20-0x7E | 1152 | N |
- $ = OLEDFontType
- A print class is available to print out many data types.
- Fonts 1-6 are byte high(at text size 1) scale-able fonts, columns of padding added by SW.
- Font 7-8 are large numerical fonts and cannot be scaled(just one size).
- Fonts 9-12 large Alphanumeric fonts and cannot be scaled(just one size)
Font Methods:
| Font num | Method name | Size parameter | Notes |
|---|---|---|---|
| 1-6 | drawChar | Yes | draws single character |
| 1-6 | drawText | Yes | draws character array |
| 7-12 | drawChar | No | draws single character |
| 7-12 | drawText | No | draws character array |
| All | ~ | Polymorphic print class which will print out most data types |
These methods return a enum( OLED_Return_Codes_e), non-zero in event of an error, see API doc., such as wrong font chosen , ASCII character outside chosen fonts range, character out of screen bounds and invalid character array pointer object.
Two different bitmaps methods can be used.
| num | Method name | data addressing | Notes |
|---|---|---|---|
| 1 | OLEDBitmap() | horizontal | Draws bitmaps to the buffer |
| 2 | OLEDBuffer() | vertical | Write a full screen bitmap direct to screen, used internally |
Bitmaps can be turned to data here at link See example file "BITMAP" for more details.
Output of the example file "CLOCK_DEMO".
- To test on a different size of display edit the myOLEDwidth & myOLEDheight variables in examples files.
| Display size | Supported | Tested |
|---|---|---|
| 128x64 | Yes | Yes |
| 128x32 | Yes | Yes |
| ???x16 | Yes | NO |
