GCBASIC documentation
GLCD Overview

This section covers GLCD devices that use the SSD1306 graphics controller.

The SSD1306 is a single-chip CMOS OLED/PLED driver with controller for organic / polymer light emitting diode dot-matrix graphic display system. It consists of 128 segments and 64 commons. This IC is designed for Common Cathode type OLED panel.

The SSD1306 embeds with contrast control, display RAM and oscillator, which reduces the number of external components and power consumption. It has 256-step brightness control. Data/Commands are sent from general MCU through the hardware selectable 6800/8000 series compatible Parallel Interface, I2C interface or Serial Peripheral Interface. It is suitable for many compact portable applications, such as mobile phone sub-display, MP3 player and calculator, etc.

The GCBASIC constants shown below control the configuration of the SSD1306 controller.    GCBASIC supports SPI and I2C hardware & software connectivity - this is shown in the tables below.

To use the SSD1306 driver simply include the following in your user code. This will initialise the driver.

The SSD1306 library supports 128 * 64 pixels or 128 * 32 pixels. The default is 128 * 64 pixels.

The SSD1306 is a monochrome device.

The SSD1306 can operate in three modes. Full GLCD mode, Low Memory GLCD mode or Text/JPG mode the full GLCD mode requires a minimum of 1k bytes or 512 bytes for the 128x64 and the 128x32 devices respectively in Full GLCD mode. For microcontrollers with limited memory the third mode of operation - Text mode. These can be selected by setting the correct constant.

To use the SSD1306 drivers simply include one of the following configuration. You can select Full Mode GLCD, Low Memory Mode GLCD or Text mode these require 1024, 128 or 0 byte GLCD buffer respectively - you microcontroller requires sufficient RAM to support the selected mode of GLCD operation.

Performance of the SSD1306 has been validated at 16Mhz and 400Hz I2C baud.  Using other frequencies should be fully tested.

    'An I2C configuration
    #include <glcd.h>

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306
    #define GLCD_I2C_Address 0x78
    '#define GLCD_TYPE_SH1306_LOWMEMORY_GLCD_MODE       'select Low Memory mode of operation
    '#define GLCD_TYPE_SH1306_CHARACTER_MODE_ONLY       'select Text mode of operation


    ; ----- Define Hardware settings
    ' Define I2C settings
    #define HI2C_BAUD_RATE 400
    #define HI2C_DATA
    HI2CMode Master

or,

    'An SPI configuration'
    #include <glcd.h>

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306

    ; ----- Define Hardware settings
    #define S4Wire_DATA

    #define MOSI_SSD1306 PortB.1
    #define SCK_SSD1306  PortB.2
    #define DC_SSD1306   PortB.3
    #define CS_SSD1306   PortB.4
    #define RES_SSD1306  PortB.5

The GCBASIC constants for control display characteristics are shown in the table below.

The GCBASIC constants for SPI/S4Wire control display characteristics are shown in the table below.

The GCBASIC constants for control display characteristics are shown in the table below.

The GCBASIC variables for control display characteristics are shown in the table below. These variables control the user definable parameters of a specific GLCD.

The GCBASIC commands supported for this GLCD are shown in the table below.

The GCBASIC specific commands for this GLCD are shown in the table below.

For a SSD1306 datasheet, please refer here.

This example shows how to drive a SSD1306 based Graphic I2C LCD module with the built in commands of GCBASIC using Full Mode GLCD

    #chip mega328p,16
    #include <glcd.h>

    ; ----- Define Hardware settings
    ' Define I2C settings
    #define HI2C_BAUD_RATE 400
    #define HI2C_DATA
    HI2CMode Master

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306  'for 128 * 64 pixels support
    #define GLCD_I2C_Address 0x78

    dim outString as string * 21

    GLCDCLS
    GLCDPrint 0, 0, "GCBASIC"
    GLCDPrint (0, 16, "Anobium 2021")

    wait 3 s
    GLCDCLS

    ' Prepare the static components of the screen
    GLCDPrint ( 0,   0, "PrintStr") ; Print some text
    GLCDPrint ( 64,  0, "@")
    ; Print some more text
    GLCDPrint ( 72,  0, ChipMhz) ; Print chip speed
    GLCDPrint ( 86, 0, "Mhz") ; Print some text
    GLCDDrawString( 0,8,"DrawStr") ; Draw some text
    box 0,0,GLCD_WIDTH-1, GLCD_HEIGHT-1 ; Draw a box
    box GLCD_WIDTH-5, GLCD_HEIGHT-5,GLCD_WIDTH-1, GLCD_HEIGHT-1 ; Draw a box
    Circle( 44,41,15) ; Draw a circle
    line 64,31,0,31 ; Draw a line

    DO forever
       for CCount = 31 to 127
            GLCDPrint ( 64 ,  36,  hex(longNumber_E ) ) ; Print a HEX string
            GLCDPrint ( 76 ,  36,  hex(longNumber_U ) ) ; Print a HEX string
            GLCDPrint ( 88 ,  36,  hex(longNumber_H ) ) ; Print a HEX string
            GLCDPrint ( 100 ,  36, hex(longNumber   ) ) ; Print a HEX string
            GLCDPrint ( 112 ,  36, "h" ) ; Print a HEX string

            GLCDPrint ( 64 ,  44, pad(str(wordNumber), 5 ) ) ; Print a padded string
            GLCDPrint ( 64 ,  52, pad(str(byteNumber), 3 ) ) ; Print a padded string

            box (46,9,56,19) ; Draw a Box
            GLCDDrawChar(48, 9, CCount ) ; Draw a character
            outString = str( CCount ) ; Prepare a string
            GLCDDrawString(64, 9, pad(outString,3) ) ; Draw a string

            filledbox 3,43,11,51, wordNumber ; Draw a filled box

            FilledCircle( 44,41,9, longNumber xor 1) ; Draw a filled box
            line 0,63,64,31 ; Draw a line

            ; Do some simple maths
            longNumber = longNumber + 7 : wordNumber = wordNumber + 3 : byteNumber++
        NEXT
    LOOP
    end

This example shows how to drive a SSD1306 based Graphic I2C LCD module with the built in commands of GCBASIC using Low Memory Mode GLCD.
Note the use of GLCD_Open_PageTransaction and GLCD_Close_PageTransaction to support the Low Memory Mode of operation and the contraining of all GLCD commands with the transaction commands. The use Low Memory Mode GLCD the two defines GLCD_TYPE_SSD1306_LOWMEMORY_GLCD_MODE and GLCD_TYPE_SSD1306_CHARACTER_MODE_ONLY are included in the user program.

    #chip mega328p,16
    #include <glcd.h>

    ; ----- Define Hardware settings
    ' Define I2C settings
    #define HI2C_BAUD_RATE 400
    #define HI2C_DATA
    HI2CMode Master

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306  'for 128 * 64 pixels support
    #define GLCD_I2C_Address 0x78
    #define GLCD_TYPE_SSD1306_LOWMEMORY_GLCD_MODE
    #define GLCD_TYPE_SSD1306_CHARACTER_MODE_ONLY

    dim outString as string * 21

    GLCDCLS

    'To clarify - page udpates
    '0,7 correspond with the Text Lines from 0 to 7 on a 64 Pixel Display
    'In this example Code would be GLCD_Open_PageTransaction 0,1 been enough
    'But it is allowed to use GLCD_Open_PageTransaction 0,7 to show the full screen update
    GLCD_Open_PageTransaction 0,7
       GLCDPrint 0, 0, "GCBASIC"
       GLCDPrint (0, 16, "Anobium 2021")
    GLCD_Close_PageTransaction
    wait 3 s
    DO forever

      for CCount = 31 to 127

        outString = str( CCount ) ; Prepare a string

        GLCD_Open_PageTransaction 0,7

           ' Prepare the static components of the screen
           GLCDPrint ( 0,   0, "PrintStr") ; Print some text
           GLCDPrint ( 64,  0, "@")
           ; Print some more text
           GLCDPrint ( 72,  0, ChipMhz) ; Print chip speed
           GLCDPrint ( 86, 0, "Mhz") ; Print some text
           GLCDDrawString( 0,8,"DrawStr") ; Draw some text
           box 0,0,GLCD_WIDTH-1, GLCD_HEIGHT-1 ; Draw a box
           box GLCD_WIDTH-5, GLCD_HEIGHT-5,GLCD_WIDTH-1, GLCD_HEIGHT-1 ; Draw a box
           Circle( 44,41,15) ; Draw a circle
           line 64,31,0,31 ; Draw a line

           GLCDPrint ( 64 ,  36,  hex(longNumber_E ) ) ; Print a HEX string
           GLCDPrint ( 76 ,  36,  hex(longNumber_U ) ) ; Print a HEX string
           GLCDPrint ( 88 ,  36,  hex(longNumber_H ) ) ; Print a HEX string
           GLCDPrint ( 100 ,  36, hex(longNumber   ) ) ; Print a HEX string
           GLCDPrint ( 112 ,  36, "h" ) ; Print a HEX string

           GLCDPrint ( 64 ,  44, pad(str(wordNumber), 5 ) ) ; Print a padded string
           GLCDPrint ( 64 ,  52, pad(str(byteNumber), 3 ) ) ; Print a padded string

           box (46,8,56,19) ; Draw a Box
           GLCDDrawChar(48, 9, CCount ) ; Draw a character

           GLCDDrawString(64, 9, pad(outString,3) ) ; Draw a string

           filledbox 3,43,11,51, wordNumber ; Draw a filled box

           FilledCircle( 44,41,9, longNumber xor 1) ; Draw a filled box
           line 0,63,64,31 ; Draw a line

        GLCD_Close_PageTransaction

        ; Do some simple maths
        longNumber = longNumber + 7 : wordNumber = wordNumber + 3 : byteNumber++
       NEXT
    LOOP
    end

This example shows how to drive a SSD1306 based Graphic SPI LCD module with the built in commands of GCBASIC.

    'Chip model
    #chip mega328p, 16
    #include <glcd.h>

    'Defines for a 7 pin SPI module
    'RES pin is pulsed low in glcd_SSD1306.h for proper startup
    #define MOSI_SSD1306 PortB.1
    #define SCK_SSD1306 PortB.2
    #define DC_SSD1306 PortB.3
    #define CS_SSD1306 PortB.4
    #define RES_SSD1306 PortB.5
    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306   'for 128 * 64 pixels support
    #define S4Wire_DATA

    dim longnumber as Long
    longnumber = 123456
    dim wordnumber as word
    wordnumber = 62535
    dim bytenumber as Byte
    bytenumber =255

    #define led PortB.0
    dir led out


    Do
         SET led ON
         wait 1 s
         SET led OFF

        GLCDCLS
        GLCDPrint (30, 0, "Hello World!")
        Circle (18,24,10)
        FilledCircle (48,24,10)
        Box (70,14,90,34)
        FilledBox (106,14,126,34)
        GLCDDrawString (32,35,"Draw String")
        GLCDPrint (0,46,longnumber)
        GLCDPrint (94,46,wordnumber)
        GLCDPrint (52,55,bytenumber)
        Line (0,40,127,63)
        Line (0,63,127,40)
        wait 3 s

    Loop

This example shows how to drive a SSD1306 based Graphic I2C LCD module with 128 * 32 pixel support.

    #chip mega328p,16
    #include <glcd.h>

    ; ----- Define Hardware settings
    ' Define I2C settings
    #define HI2C_BAUD_RATE 400
    #define HI2C_DATA
    HI2CMode Master

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1306_32  'for 128 * 32 pixels support
    #define GLCD_I2C_Address 0x78

    GLCDCLS
    GLCDPrint 0, 0, "GCBASIC"
    GLCDPrint (0, 16, "Anobium 2021")

This example shows how to drive a SSD1306 with the OLED fonts. Note the use of the GLCDfntDefaultSize to select the size of the OLED font in use.

    #define GLCD_OLED_FONT

    GLCDfntDefaultSize = 2
    GLCDFontWidth = 5
    GLCDPrint ( 40, 0, "OLED" )
    GLCDPrint ( 0, 18, "Typ:  SSD1306" )
    GLCDPrint ( 0, 34, "Size: 128x64" )

    GLCDfntDefaultSize = 1
    GLCDPrint(20, 56,"https://goo.gl/gjrxkp")

This example shows how to set the SSD1306 OLED the lowest constrast level by using a OLED chip specific command.

    'Use the GCB command to set the lowest constrast
    GLCDSetContrast ( 0 )
      'Then, use the Write command to set the output between 0 and 255
      Write_Command_SSD1306(SSD1306_SETVCOMDETECT)
      Write_Command_SSD1306(15)      ' 0x40 default, to lower the contrast, put 0 for lowest and 255 for highest.


    GLCDfntDefaultSize = 2
    GLCDFontWidth = 5
    GLCDPrint ( 40, 0, "OLED" )
    GLCDPrint ( 0, 18, "Typ:  SSD1306" )
    GLCDPrint ( 0, 34, "Size: 128x64" )

    GLCDfntDefaultSize = 1
    GLCDPrint(20, 56,"https://goo.gl/gjrxkp")

This example shows how to disable the large OLED Fontset. This disables the font to reduce memory usage.

When the large OLED fontset is disabled every character will be shown as a block character.

    #define GLCD_OLED_FONT                'The constant is required to support OLED fonts
    #define GLCD_Disable_OLED_FONT2       'The constant to disable the large fontset.

    GLCDfntDefaultSize = 2
    GLCDFontWidth = 5
    GLCDPrint ( 40, 0, "OLED" )
    GLCDPrint ( 0, 18, "Typ:  SSD1306" )
    GLCDPrint ( 0, 34, "Size: 128x64" )

    GLCDfntDefaultSize = 1
    GLCDPrint(20, 56,"https://goo.gl/gjrxkp")

For more help, see GLCDCLS, GLCDDrawChar, GLCDPrint, GLCDReadByte, GLCDWriteByte or Pset

Supported in <GLCD.H>