PLEASE NOTE: This library has now been replaced by the HCDisplay library and will no longer be supported. For new projects please use the HCDisplay library instead which can be found at this forum thread:
viewtopic.php?f=58&t=2827

This Arduino library will allow you to display various text, graphics and and bitmaps on SSD1307 and SH1106 based uOLED displays. The library has been written specifically for our own uOLED displays including the following:
Hobby Components 0.96" uOLED displays (HCMODU0050 & HCMODU0052)
Hobby Components 1.3" uOLED displays (HCMODU0058 & HCMODU0059)
WeMos D1 mini OLED shield (HCWEMO0007)
Hobby Components 0.9" 128x32 uOLED displays (HCMODU0118 & HCMODU0119)
The library makes use of the Arduino's SPI interface (V0.2 now additionally support displays in I2C mode) to drive the displays in their default SPI configuration. However, the library is capable of driving multiple displays with a mix of previously mentioned controller types all from one Arduino. Each additional display will only require 3 additional digital pins.
You will need to download (please log in to download the library) and unzip this library to the Arduino development environments library area.
On Windows:
My Documents\Arduino\libraries\
On Mac:
Documents/Arduino/libraries/
or similarly for Linux.
Using the library
To use the library just include the HCuOLED.h header file and the standard SPI.h header file and then create an instance of the library for each display. E.g:
For SPI mode:
Code: Select all
#include <HCuOLED.h>
#include <SPI.h>
HCuOLED HCuOLED(DisplayType, CS, DC, RST);
DisplayType is the driver version of the display. Valid values are
SSD1306
SH1106
CS is the digital pin number used for the modules chip select pin (CS)
DC is the pin number used for the modules Data/Command pin (DC)
RST is the pin number used for the modules reset pin (RST)
For I2C mode:
Code: Select all
#include <HCuOLED.h>
#include <Wire.h>
HCuOLED HCuOLED(DisplayType, I2C_ADD, RST);
Where:
DisplayType is the driver version of the display. Valid values are
SSD1306
SH1106
WEMOS_D1_MINI_OLED
SSD1306_128_32
I2C_ADD is the I2C address of the display. This is normally either 0x3C or 0x3D.
RST is the pin number used for the modules reset pin (RST). This is an optional parameter and may be omitted if your display has internal reset circuitry (e.g. WeMos OLED).
The display buffer:
Because it is not possible to read the status of the screens display, the library will create a display buffer in RAM. Most of the functions outlined below will not write directly to the display but instead write to the display buffer. Nothing will be displayed on the module until the refresh function is executed which will write the entire contents of the displaybuffer to the display.
Note when using the library with multiple displays:
Due to tight RAM constraints of most Arduinos it is not possible to store a separate display buffer for each display. Therefore only one display buffer is created and is shared by each display. Therefore, when writing to a different display you will need to first clear the display buffer with the ClearBuffer() command to avoid display information from the previous screen being copied to the new screen.
The following functions are available with this library:
Code: Select all
HCuOLED.Reset();
Code: Select all
HCuOLED.Init();
Note: This function is called by the above Reset() function. It has been added(V0.6) to allow multiple displays to be initialised when reset via the same digital pin. This function is not required when driving a single display or when multiple displays are reset using separate digital pins.
Code: Select all
HCuOLED.Refresh();
Code: Select all
HCuOLED.ClearBuffer();
Code: Select all
HCuOLED.Flip_H();
Code: Select all
HCuOLED.Flip_V();
Code: Select all
HCuOLED.Brightness(byte Level);
Level is the brightness level of the display. Valid values for Level are
1 = Lowest brightness
255 = Highest brightness
Code: Select all
HCuOLED.Bitmap(Cols, ByteRows, BitmapData[]);
Cols is the X axis dimension of the bitmap in pixels.
ByteRows is the Y axis dimension of the bitmap in 8 pixel chunks.
BitmapData[] is a 1 dimensional array of type const byte containing the bitmap data. Each byte of the array represents on 8 pixel column of the bitmap.
Code: Select all
HCuOLED.Cursor(byte X, byte Y);
X is the X axis location where the bitmap or text will start from. Valid values are between 0 and 127
Y is the Y axis location where the bitmap or text will start from. Valid values are between 0 and 63
Code: Select all
HCuOLED.SetFont(Font);
Font is the required font. Valid options are:
Terminal_8pt (a small fixed width 8x8 font)
MedProp_11pt (a medium proportional 2 row font)
LCDLarge_24pt (a large LCD style 4 row font)
sharpsharp_5pt (A tiny 5pt proportional font thanks to forum user ChrisSharp for creating this)
sharpsharp_6pt (A tiny 6pt proportional font thanks to forum user ChrisSharp for creating this)
Code: Select all
HCuOLED.Plot(X, Y);
X is the X axis of the pixel. Valid values are between 0 and 127
Y is the Y axis of the pixel. Valid values are between 0 and 63
Code: Select all
HCuOLED.Line(X1, Y1, X2, Y2);
X1 is the start X axis coordinate of the line. Valid values are between 0 and 127
Y1 is the start Y axis coordinate of the line. Valid values are between 0 and 63
X2 is the end X axis coordinate of the line. Valid values are between 0 and 127
Y3 is the end Y axis coordinate of the line. Valid values are between 0 and 63
Code: Select all
HCuOLED.Rect(X1, Y1, X2, Y2, FillMode);
X1 is the X axis coordinate for the first corner. Valid values are between 0 and 127
Y1 is the Y axis coordinate for the first corner. Valid values are between 0 and 63
X2 is the X axis coordinate for the opposite corner. Valid values are between 0 and 127
Y2 is the Y axis coordinate for the opposite corner. Valid values are between 0 and 63
FillMode specifies if the rectangle should be filled or not. Valid values are:
OUTLINE (draws a single pixel wide outlined rectangle)
SOLID (draws a filled rectangle)
Code: Select all
HCuOLED.Erase(X1, Y1, X2, Y2);
X1 is the X axis coordinate for the first corner. Valid values are between 0 and 127
Y1 is the Y axis coordinate for the first corner. Valid values are between 0 and 63
X2 is the X axis coordinate for the opposite corner. Valid values are between 0 and 127
Y2 is the Y axis coordinate for the opposite corner. Valid values are between 0 and 63
Code: Select all
HCuOLED.DrawMode(DrawMode);
DrawMode sets the drawing mode. Valid values are:
NORMAL (pixels are set to the foreground colour)
CLEAR (Pixels are set to the background colour)
INVERT (pixels are set to the opposite of their current state)
Code: Select all
HCuOLED.Print(TextString[])
TextString[] is a string of text.
Code: Select all
HCuOLED.Print(Value)
Value is a signed integer number of type long.
Code: Select all
HCuOLED.Print(Value, DecimalPlaces)
Value is a signed integer number of type long.
DecimalPlaces is position of the decimal point starting from the right hand side
Code: Select all
HCuOLED.Print(value, digits, DecimalPlaces);
value is a signed floating point number of type float
digits is the number of digits (including decimal places) to crop the number to. Maximum is 10 digits
DecimalPlaces is the number of decimal places to crop the number to.
Code: Select all
HCuOLED.GetPixel(X, Y);
X is the x axis coordinate of the pixel
Y is the Y axis coordinate of the pixel
Returns: A boolean value representing the state of the pixel at coordinate X,Y

- /* FILE: HCuOLED_Things_Example
- DATE: 16/04/15
- VERSION: 0.1
- AUTHOR: Andrew Davies
- REVISIONS:
- 12/03/15 Created version 0.1
- This example uses the line, rectangle and bitmap graphic functions together with
- the INVERT DrawMode to create a simple animation.
- To use this example connect your uOLED display to the following pins of your
- Arduino:
- MODULE..........ARDUINO
- GND.............GND
- VCC.............3.3V
- D0 (CLK)........D13
- D1 (DATA).......D11
- RST (RESET).....D8
- DC..............D9
- CS (SS).........D10
- You may copy, alter and reuse this code in any way you like, but please leave
- reference to HobbyComponents.com in your comments if you redistribute this code.
- This software may not be used directly for the purpose of promoting products that
- directly compete with Hobby Components Ltd's own range of products.
- THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES,
- WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED
- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR
- LACK OF NEGLIGENCE. HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE
- FOR ANY DAMAGES INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR
- CONSEQUENTIAL DAMAGES FOR ANY REASON WHATSOEVER. */
- #include "HCuOLED.h"
- #include "SPI.h"
- /* Example bitmap */
- const PROGMEM byte Tiny_Logo_Resistor[] =
- {
- 0xC0, 0xE0, 0x30, 0x30, 0xF0, 0xE0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0x00, 0x00, 0x00, 0x00, 0x80, 0xE0, 0x38, 0x0E, 0x07, 0x1E, 0x78, 0xE0, 0x80, 0x00, 0x00, 0x00, 0x00, 0xC0, 0x70, 0x1C, 0x07, 0x0F, 0x3C, 0xF0, 0x80, 0x00, 0x00, 0x00, 0x00, 0x80, 0xF0, 0x3C, 0x0F, 0x07, 0x1C, 0x70, 0xC0, 0x00, 0x00, 0x00, 0x00, 0x80, 0xE0, 0x78, 0x1E, 0x07, 0x0E, 0x38, 0xE0, 0x80, 0x00, 0x00, 0x00, 0x00, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xC0, 0xE0, 0xF0, 0x30, 0x30, 0xE0, 0xC0,
- 0x00, 0x01, 0x03, 0x03, 0x03, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x0F, 0x3C, 0x38, 0x0E, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x07, 0x1E, 0x38, 0x1C, 0x07, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x0E, 0x38, 0x38, 0x0E, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x07, 0x1C, 0x38, 0x1E, 0x07, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x0E, 0x38, 0x3C, 0x0F, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x03, 0x03, 0x03, 0x01, 0x00,
- };
- /* Digital pin number for the displays chip select pin */
- #define CS_DI 10
- /* Digital pin number for the displays data/command pin */
- #define DC_DI 9
- /* Digital pin number for the displays reset pin */
- #define RST_DI 8
- /* Array indexes for the X and Y coordinates */
- #define X1 0
- #define Y1 1
- #define X2 2
- #define Y2 3
- /* Arrays to store coordinates and direction for the line, rectangle and bitmap */
- byte Box[4] = {1,1,20,20};
- byte BoxDir[4] = {1,1,1,1};
- byte Line[4] = {100,25,120,55};
- byte LineDir[4] = {-1,-1,-1,-1};
- byte Bitmap[2] = {40,40};
- byte BitmapDir[2] = {-1,-1};
- /* Create an instance of the library (uncomment one of the lines below) */
- //HCuOLED HCuOLED(SSD1307, SS_DI, DC_DI, RST_DI); // For SSD1307 displays (HCMODU0050 & HCMODU0052)
- HCuOLED HCuOLED(SH1106, CS_DI, DC_DI, RST_DI); // For SH1106 displays (HCMODU0058 & HCMODU0059)
- void setup()
- {
- /* Reset the display */
- HCuOLED.Reset();
- }
- void loop()
- {
- /* Display some text using a small 8x8 fixed width font */
- HCuOLED.SetFont(Terminal_8pt);
- HCuOLED.Cursor(44,0);
- HCuOLED.Print("HOBBY");
- HCuOLED.Cursor(20,10);
- HCuOLED.Print("COMPONENTS");
- /* Display a number using a large 4 line LCD style font */
- HCuOLED.Cursor(20,24);
- HCuOLED.SetFont(LCDLarge_24pt);
- HCuOLED.Print("HCuOLED");
- /* Change the draw mode from NORMAL to INVERT */
- HCuOLED.DrawMode(INVERT);
- while(1)
- {
- /* Move the positions of the 3 objects */
- MoveRect();
- MoveLine();
- MoveBitmap();
- /* Draw the objects to the display buffer */
- HCuOLED.Rect(Box[X1],Box[Y1],Box[X2],Box[Y2], SOLID);
- HCuOLED.Line(Line[X1],Line[Y1],Line[X2],Line[Y2]);
- HCuOLED.Cursor(Bitmap[X1],Bitmap[Y1]);
- HCuOLED.Bitmap(84, 2, Tiny_Logo_Resistor);
- /* Write the display buffer to the screen */
- HCuOLED.Refresh();
- /* Draw the objects again. As we are in INVERT mode this will remove them */
- HCuOLED.Rect(Box[X1],Box[Y1],Box[X2],Box[Y2], SOLID);
- HCuOLED.Line(Line[X1],Line[Y1],Line[X2],Line[Y2]);
- HCuOLED.Cursor(Bitmap[X1],Bitmap[Y1]);
- HCuOLED.Bitmap(84, 2, Tiny_Logo_Resistor);
- }
- }
- /* Update the X and Y coordinates for the box */
- void MoveRect(void)
- {
- if(Box[X1] == 0 || Box[X1] == 127)
- BoxDir[X1] *= -1;
- Box[X1] += BoxDir[X1];
- if(Box[Y1] == 0 || Box[Y1] == 63)
- BoxDir[Y1] *= -1;
- Box[Y1] += BoxDir[Y1];
- if(Box[X2] == 0 || Box[X2] == 127)
- BoxDir[X2] *= -1;
- Box[X2] += BoxDir[X2];
- if(Box[Y2] == 0 || Box[Y2] == 63)
- BoxDir[Y2] *= -1;
- Box[Y2] += BoxDir[Y2];
- }
- /* Update the X and Y coordinates for the Line */
- void MoveLine(void)
- {
- if(Line[X1] == 0 || Line[X1] == 127)
- LineDir[X1] *= -1;
- Line[X1] += LineDir[X1];
- if(Line[Y1] == 0 || Line[Y1] == 63)
- LineDir[Y1] *= -1;
- Line[Y1] += LineDir[Y1];
- if(Line[X2] == 0 || Line[X2] == 127)
- LineDir[X2] *= -1;
- Line[X2] += LineDir[X2];
- if(Line[Y2] == 0 || Line[Y2] == 63)
- LineDir[Y2] *= -1;
- Line[Y2] += LineDir[Y2];
- }
- /* Update the X and Y coordinates for the bitmap */
- void MoveBitmap(void)
- {
- if(Bitmap[X1] == 0 || Bitmap[X1] == 43)
- BitmapDir[X1] *= -1;
- Bitmap[X1] += BitmapDir[X1];
- if(Bitmap[Y1] == 0 || Bitmap[Y1] == 47)
- BitmapDir[Y1] *= -1;
- Bitmap[Y1] += BitmapDir[Y1];
- }

The latest version (V1.0) of the library can be downloaded here:
Older versions
V0.9: V0.8: V0.7: V0.6: V0.5: V0.4: V0.3: V0.2: V0.1:
Change Log:
16/04/15 version 0.1: Original version
06/12/16 version 0.2: Added compatibility with ESP8266
Added support for uOLED displays in I2C mode
Added support for WeMos D1 mini OLED shield (see item HCWEMO0007)
Made speed improvement to erase function (thanks to vladyslav-savchenko)
22/05/17 version 0.3: Added support for 128x32 OLED display (see items HCMODU0118 & HCMODU0119)
02/11/18 version 0.4: Fixed issue which cause the integer value of 0 not to be printed.
06/01/19 version 0.5: Change unsigned int to uint16_t in font.h file to fix error when compiling for Wemos boards
18/05/19 version 0.6: Added Brightness() function to allow adjustment of displays brightness level
Removed initialisation code from Reset() and added a new Init() function to allow multiple displays to be reset from the same pin
Added command to pull CS pin high in the Init() function.
24/02/21 version 0.7: Add 2 additonal tiny fonts: sharpsharp_5pt & sharpsharp_6pt thanks to Chris Sharp for creating the fonts.
Also added different font spacing for each font.
22/03/21 version 0.8: Added GetPixel() function to get the current state of a pixel at a specified coordinate.
Updated font description in Fonts.h file from 'const unsigned int' to 'const short unsigned int' to remove compile error when compiling for WeMos D1
11/01/22 version 0.9: Updated Bitmap() and Cursor() functions to allow bitmaps and text to be printed partially off screen
14/01/22 version 1.0: Fixed bug that caused the Flip_H() & Flip_V() functions to not work.
Libraries, example code, and diagrams are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no provide any guarantees or warranties as to their accuracy or fitness for purpose.
Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.