GCBASIC documentation
GLCD Overview

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

The SSD1309 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 SSD1309 is command-compatible and pin-compatible with the SSD1306 — the same wiring and the same GCBASIC commands apply, just using GLCD_TYPE_SSD1309 in place of GLCD_TYPE_SSD1306. It embeds 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. Typically operates at VCC 3.3v — always check the voltage specification of the specific module in use.

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

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

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

The SSD1309 is a monochrome device.

The SSD1309 can operate in three modes: Full GLCD mode, Low Memory GLCD mode, or Text/JPG mode. Full GLCD mode requires a minimum of 1k bytes, 512 bytes, or 256 bytes of RAM for the 128x64, 128x32, and 64x32 devices respectively. For microcontrollers with limited memory, use the third mode of operation — Text mode. These are selected by setting the correct constant.

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

    'An I2C configuration
    #include <glcd.h>

    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1309          ' <<< the constant that selects this controller driver
    #define GLCD_I2C_Address 0x78
    '#define GLCD_TYPE_SSD1309_LOWMEMORY_GLCD_MODE       'select Low Memory mode of operation
    '#define GLCD_TYPE_SSD1309_CHARACTER_MODE_ONLY       'select Text mode of operation


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

Key line: #define GLCD_TYPE GLCD_TYPE_SSD1309 — tells <glcd.h> to compile in the SSD1309 driver; the commented-out GLCD_TYPE_SSD1309_LOWMEMORY_GLCD_MODE and GLCD_TYPE_SSD1309_CHARACTER_MODE_ONLY lines trade GLCD buffer size against available functionality on RAM-constrained microcontrollers.

or,

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

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

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

    #define MOSI_SSD1309 PortB.1
    #define SCK_SSD1309  PortB.2
    #define DC_SSD1309   PortB.3
    #define CS_SSD1309   PortB.4
    #define RES_SSD1309  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.

This example shows how to drive a SSD1309 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_SSD1309  'for 128 * 64 pixels support
    #define GLCD_I2C_Address 0x78

    dim outString as string * 21

    GLCDCLS
    GLCDPrint 0, 0, "GCBASIC"          ' <<< the GLCDPrint instruction
    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

Key line: GLCDPrint 0, 0, "GCBASIC" — draws the string at pixel column 0, row 0 using the standard GCBASIC font set; the loop that follows demonstrates numeric formatting helpers such as hex() and pad() alongside Box, Circle, and Line.

This example shows how to drive a SSD1309 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 constraining of all GLCD commands within the transaction commands. To use Low Memory Mode GLCD the two defines GLCD_TYPE_SSD1309_LOWMEMORY_GLCD_MODE and GLCD_TYPE_SSD1309_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_SSD1309  'for 128 * 64 pixels support
    #define GLCD_I2C_Address 0x78
    #define GLCD_TYPE_SSD1309_LOWMEMORY_GLCD_MODE
    #define GLCD_TYPE_SSD1309_CHARACTER_MODE_ONLY

    dim outString as string * 21

    GLCDCLS

    'To clarify - page updates
    '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 SSD1309 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_SSD1309.h for proper startup
    #define MOSI_SSD1309 PortB.1
    #define SCK_SSD1309 PortB.2
    #define DC_SSD1309 PortB.3
    #define CS_SSD1309 PortB.4
    #define RES_SSD1309 PortB.5
    ; ----- Define GLCD Hardware settings
    #define GLCD_TYPE GLCD_TYPE_SSD1309   '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!")          ' <<< the GLCDPrint instruction, over the SPI (S4Wire) interface
        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

Key line: GLCDPrint (30, 0, "Hello World!") — identical usage to the I2C examples above; only the interface constants (MOSI_SSD1309, SCK_SSD1309, etc.) and ` S4Wire_DATA ` change to select SPI instead of I2C.
This example shows how to drive a SSD1309 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_SSD1309_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 smaller SSD1309 based Graphic I2C LCD module with 64 * 32 pixel support — typically the size used on 0.96inch-class small OLED panels.

    #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_SSD1309_64x32  'for 64 * 32 pixels support          ' <<< the constant that selects the smaller panel size
    #define GLCD_I2C_Address 0x78

    GLCDCLS
    GLCDPrint 0, 0, "GCBASIC"

Key line: #define GLCD_TYPE GLCD_TYPE_SSD1309_64x32 — selects the smaller 64x32 panel geometry; the driver automatically places the active memory region in the middle columns (32 to 96) of the controller’s native 128-pixel-wide RAM, so no other code changes are needed versus the 128x64 example above.
This example shows how to drive a SSD1309 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:  SSD1309" )
    GLCDPrint ( 0, 34, "Size: 128x64" )

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

This example shows how to set the SSD1309 OLED to the lowest contrast level by using an OLED chip specific command.

    'Use the GCB command to set the lowest contrast
    GLCDSetContrast ( 0 )
      'Then, use the Write command to set the output between 0 and 255
      Write_Command_SSD1309(SSD1309_SETVCOMDETECT)
      Write_Command_SSD1309(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:  SSD1309" )
    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:  SSD1309" )
    GLCDPrint ( 0, 34, "Size: 128x64" )

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

See Also:

Supported in <GLCD.H>