Register • FAQ • Search • Login

View unanswered posts | View active topics It is currently Sat Aug 19, 2017 9:26 am


Board index » Software » Arduino

All times are UTC



Reply to topic  Page 1 of 1
  [ 3 posts ] 
Print view Previous topic | Next topic 
HCuOLED library for SSD1307 & SH1106 based OLED displays 
Author Message
admin
Site Admin

Joined: Sun Aug 05, 2012 4:02 pm
Posts: 650
Post HCuOLED library for SSD1307 & SH1106 based OLED displays
Image

Image

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:
#include <HCuOLED.h>
#include <SPI.h>
HCuOLED HCuOLED(DisplayType, CS, DC, RST);


Where:

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:
#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:
HCuOLED.Reset();

Resets the display and configures it to a default state.


Code:
HCuOLED.Refresh();

Writes the contents of the display buffer to the display.


Code:
HCuOLED.ClearBuffer();

Clears the contents of the display buffer.


Code:
HCuOLED.Flip_H();

Flips the display about its horizontal axis.


Code:
HCuOLED.Flip_V();

Flips the display about its vertical axis.


Code:
HCuOLED.Bitmap(Cols, ByteRows, BitmapData[]);

Copies a 1 dimensional array (of type const byte) containing bitmap information to the display buffer with the top left hand corner of the bitmap starting at the Cursor() coordinates where:

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:
HCuOLED.Cursor(byte X, byte Y);

Sets the current cursor location used for positioning text and bitmaps in the screen where:
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:
HCuOLED.SetFont(Font);

Sets the font to by the Print() function. Where:
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)


Code:
HCuOLED.Plot(X, Y);

Changes the pixel at a specified coordinate where:
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:
HCuOLED.Line(X1, Y1, X2, Y2);

Draws a single pixel width line where:
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:
HCuOLED.Rect(X1, Y1, X2, Y2, FillMode);

Draws a rectangle where:
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:
HCuOLED.Erase(X1, Y1, X2, Y2);

Erases rectangular area of the screen where:
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:
HCuOLED.DrawMode(DrawMode);

Sets the drawing mode for the Print(), Line(), Rect(), Bitmap() functions where:
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:
HCuOLED.Print(TextString[])

Prints an alphanumeric string of text to the output buffer using the current font at the location set by Cursor() where:
TextString[] is a string of text.


Code:
HCuOLED.Print(Value)

Prints a signed integer number to the output buffer using the current font at the location set by Cursor() where:
Value is a signed integer number of type long.


Code:
HCuOLED.Print(Value, DecimalPlaces)

Prints a signed integer number with decimal place to the display buffer using the current font at the location set by Cursor() where:
Value is a signed integer number of type long.
DecimalPlaces is position of the decimal point starting from the right hand side


Code:
HCuOLED.Print(value, digits, DecimalPlaces);

Prints a signed floating point number to the display buffer using the current font at the location set by Cursor() where:
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.


Image

Code:
/* 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];
}




Image

The library files can be downloaded from github here:

https://github.com/HobbyComponents/HCuOLED

Or directly from this forum:

Attachment:
HCuOLED.zip


Older versions

V0.2:
Attachment:
HCuOLED.zip

V0.1:
Attachment:
HCuOLED.zip




Change Log:

16/04/15 version 0.1: Original version
06/12/16 version 0.2: Added comparability 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)


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.


You do not have the required permissions to view the files attached to this post.

Fri Apr 17, 2015 2:13 pm
Profile
pkdkak01

Joined: Sun Dec 25, 2016 12:17 am
Posts: 1
Post Re: HCuOLED library for SSD1307 & SH1106 based OLED displays
hello..
this is best library for monochrome oled with higher FPS (30-40 FPS) on I2C, i have problem with Bitmap, how to convert them to byte?? :roll:
Sun Dec 25, 2016 12:25 am
Profile
andrew
Site Admin

Joined: Sun Aug 05, 2012 4:15 pm
Posts: 649
Post Re: HCuOLED library for SSD1307 & SH1106 based OLED displays
There are a few pieces of software available that are designed for converting bitmaps to byte arrays specifically for use with monochrome LCDs. However you need to that will convert the pixels of the bitmap to an array in the correct order. For the HCuOLED library this needs to be a 1 dimensional array where each byte (8 bits) represents one 8 bit column of pixels. This one should be able to do it:

http://www.avrportal.com/?page=image2glcd

Make sure you save your image as a 2 colour (black and white) bitmap. Make a note of the resolution and enter it into the x & y text boxes in the program.

_________________
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Thu Dec 29, 2016 12:18 pm
Profile
Display posts from previous:  Sort by  
Reply to topic   Page 1 of 1
  [ 3 posts ] 

Board index » Software » Arduino

All times are UTC


Who is online

Users browsing this forum: No registered users and 2 guests

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Thank you to phpBB.com & phpBB.ro.
Design created by Florea Cosmin Ionut.
© 2011 All contents of this site are © Hobby Components LTD