# glcd_ssd1306

Library for GLCD using the SSD1306 display controller.

Author | Rob Jansen, Copyright © 2020..2026, all rights reserved.
Adapted-by |
Compiler | 2.5r9

Description

    Text and graphics library for the graphic display module using
                 the SSD1306 display controller. The library supports displays
                 with a resolution of 128 x 32 or 128 x 64 (default).

Sources

    Library glcd_nokia_5110.jal used as starting point.
             SS1306 Data Sheet Revision 1.1 (April 2008)
             Adafruit_SSD1306 library and some others.

Notes

    This library supports the control of the display via one of two
           interfaces IIC or 4-wire SPI which depends on the interface that is
           included by the main program before including this library.
           This library supports control of the module using I2C software,
           I2C hardware, I2C hardware2, SPI hardware and SPI hardware2.
           Next to that the user can select a software SPI interface. In order
           to use this define the following:
           -) const SSD1306_SOFTWARE_SPI = TRUE

Dependencies

- glcd_common

## Summary

### Global variables/contants

- `const byte _SSD1306_SCROLL_HOR_LEFT = 0x27`
- `const bit _SSD1306_DATA_TRANSMISSION = 1`
- `const byte _SSD1306_SET_MULTIPLEX = 0xA8`
- `const byte _SSD1306_SET_CHARGEPUMP = 0x8D`
- `const byte GLCD_COLOR_BITS = 1`
- `const byte _SSD1306_DISPLAY_INVERSE = 0xA7`
- `const byte _SSD1306_SET_CONTRAST = 0x81`
- `const bit _SSD1306_COMMAND_TRANSMISSION = 0`
- `const byte _SSD1306_DISPLAY_RESUME = 0xA4`
- `var byte glcd_background_color = GLCD_WHITE`
- `const GLCD_WHITE = 0xFF`
- `const byte _SSD1306_STOP_SCROLL = 0x2E`
- `const byte _SSD1306_SET_SEGMENTREMAP = 0xA1`
- `const byte _SSD1306_PAGE_ADDRESS = 0x22`
- `const byte _SSD1306_SET_VCOMDETECT = 0xDB`
- `const byte _SSD1306_MEM_ADDRESS_MODE = 0x20`
- `const byte _SSD1306_SET_DISPLAY_CLOCKDIV = 0xD5`
- `const GLCD_XOR = 0x01`
- `const byte _SSD1306_DISPLAY_OFF = 0xAE`
- `const byte SSD1306_MAX_X_PIXELS = 128`
- `const byte SSD1306_MAX_PAGES = 8`
- `const byte _SSD1306_SCROLL_VER_HOR_LEFT = 0x2A`
- `const byte _SSD1306_SET_PRECHARGE = 0xD9`
- `const byte _SSD1306_SET_VER_SCROLL_AREA = 0xA3`
- `const byte _SSD1306_COLUMN_ADDRESS = 0x21`
- `const byte _SSD1306_DISPLAY_ON = 0xAF`
- `const byte _SSD1306_SET_DISPLAY_OFFSET = 0xD3`
- `const byte _SSD1306_SET_STARTLINE = 0x40`
- `const byte _SSD1306_COMSCANDEC = 0xC8`
- `const byte GLCD_Y_PIXELS = SSD1306_MAX_Y_PIXELS`
- `const byte _SSD1306_SET_COMPINS = 0xDA`
- `const byte _SSD1306_DISPLAY_ALL_ON = 0xA5`
- `const byte _SSD1306_SCROLL_VER_HOR_RIGHT = 0x29`
- `const byte GLCD_X_PIXELS = SSD1306_MAX_X_PIXELS`
- `const byte _SSD1306_START_SCROLL = 0x2F`
- `const GLCD_BLACK = 0x00`
- `const byte _SSD1306_SCROLL_HOR_RIGHT = 0x26`
- `var byte glcd_pen_color = GLCD_BLACK`
- `const byte _SSD1306_DISPLAY_NORMAL = 0xA6`

### Procedures

- `ssd1306_display_resume()`
- `ssd1306_set_contrast(byte in contrast)`
- `ssd1306_send_command(byte in command)`
- `ssd1306_write_char(byte in x, byte in y, byte in char)`
- `ssd1306_write_pixel(byte in x, byte in y)`
- `ssd1306_clear_cache()`
- `ssd1306_goto(byte in x, byte in y)`
- `ssd1306_display_on()`
- `ssd1306_start_scroll_right(byte in start, byte in stop)`
- `ssd1306_init()`
- `ssd1306_send_command_parameter(byte in command, byte in parameter)`
- `ssd1306_display_inverse()`
- `ssd1306_start_scroll_left(byte in start, byte in stop)`
- `ssd1306_start_scroll_diagonal_right(byte in start, byte in stop)`
- `ssd1306_stop_scroll()`
- `ssd1306_set_start_line(byte in start_line)`
- `ssd1306_start_scroll_diagonal_left(byte in start, byte in stop)`
- `ssd1306_display_all_on()`
- `ssd1306_display_off()`
- `ssd1306_display_normal()`
- `ssd1306_goto_pixel(byte in x, byte in y)`
- `ssd1306_clear_screen()`

Private

- `_ssd1306_stop_transmission()`
- `_ssd1306_start_transmission(bit in transmission)`
- `_ssd1306_write_one_data_byte(byte in data)`
- `_ssd1306_write_byte(byte in data)`

### Functions

Private

- `_ssd1306_spi_sw_exchange(byte in data) return byte`

## API details

### Global variables/contants

- `const byte _SSD1306_SCROLL_HOR_LEFT = 0x27`

  No documentation found

- `const bit _SSD1306_DATA_TRANSMISSION = 1`

  No documentation found

- `const byte _SSD1306_SET_MULTIPLEX = 0xA8`

  No documentation found

- `const byte _SSD1306_SET_CHARGEPUMP = 0x8D`

  No documentation found

- `const byte GLCD_COLOR_BITS = 1`

      Monochrome display.

- `const byte _SSD1306_DISPLAY_INVERSE = 0xA7`

  No documentation found

- `const byte _SSD1306_SET_CONTRAST = 0x81`

  No documentation found

- `const bit _SSD1306_COMMAND_TRANSMISSION = 0`

  No documentation found

- `const byte _SSD1306_DISPLAY_RESUME = 0xA4`

  No documentation found

- `var byte glcd_background_color = GLCD_WHITE`

      Default background color.

- `const GLCD_WHITE = 0xFF`

  No documentation found

- `const byte _SSD1306_STOP_SCROLL = 0x2E`

  No documentation found

- `const byte _SSD1306_SET_SEGMENTREMAP = 0xA1`

  No documentation found

- `const byte _SSD1306_PAGE_ADDRESS = 0x22`

  No documentation found

- `const byte _SSD1306_SET_VCOMDETECT = 0xDB`

  No documentation found

- `const byte _SSD1306_MEM_ADDRESS_MODE = 0x20`

      SSD1306 commands.

- `const byte _SSD1306_SET_DISPLAY_CLOCKDIV = 0xD5`

  No documentation found

- `const GLCD_XOR = 0x01`

      This color is a special, internal to this library (not part of the
      controller specs). When using this color, what's black becomes white
      (off), what's white becomes black (on)

- `const byte _SSD1306_DISPLAY_OFF = 0xAE`

  No documentation found

- `const byte SSD1306_MAX_X_PIXELS = 128`

      Number of pixels on the screen. Number of Y pixels is default 64 but can be
      changed to 32 pixels.

- `const byte SSD1306_MAX_PAGES = 8`

      Vertically the device uses pages of 8 pixels high.

- `const byte _SSD1306_SCROLL_VER_HOR_LEFT = 0x2A`

  No documentation found

- `const byte _SSD1306_SET_PRECHARGE = 0xD9`

  No documentation found

- `const byte _SSD1306_SET_VER_SCROLL_AREA = 0xA3`

  No documentation found

- `const byte _SSD1306_COLUMN_ADDRESS = 0x21`

  No documentation found

- `const byte _SSD1306_DISPLAY_ON = 0xAF`

  No documentation found

- `const byte _SSD1306_SET_DISPLAY_OFFSET = 0xD3`

  No documentation found

- `const byte _SSD1306_SET_STARTLINE = 0x40`

  No documentation found

- `const byte _SSD1306_COMSCANDEC = 0xC8`

  No documentation found

- `const byte GLCD_Y_PIXELS = SSD1306_MAX_Y_PIXELS`

  No documentation found

- `const byte _SSD1306_SET_COMPINS = 0xDA`

  No documentation found

- `const byte _SSD1306_DISPLAY_ALL_ON = 0xA5`

  No documentation found

- `const byte _SSD1306_SCROLL_VER_HOR_RIGHT = 0x29`

  No documentation found

- `const byte GLCD_X_PIXELS = SSD1306_MAX_X_PIXELS`

      GLCD specifications.

- `const byte _SSD1306_START_SCROLL = 0x2F`

  No documentation found

- `const GLCD_BLACK = 0x00`

      Colors constants. Black & white are official value for display controller.

- `const byte _SSD1306_SCROLL_HOR_RIGHT = 0x26`

  No documentation found

- `var byte glcd_pen_color = GLCD_BLACK`

      Default pen color.

- `const byte _SSD1306_DISPLAY_NORMAL = 0xA6`

  No documentation found

### Procedures

- `ssd1306_display_resume()`

      Description: Resume the display
      Parameters:
       None

- `ssd1306_set_contrast(byte in contrast)`

      Description: Set the display contrast
      Parameters:
       contrast - 0x00..0xFF

- `ssd1306_send_command(byte in command)`

      Description: Send a command to the
      Parameters:
       command - instruction for the SSD1306 from the datasheet

- `ssd1306_write_char(byte in x, byte in y, byte in char)`

      Description: Write a character at position (x,y)
       It uses the font previously selected with glcd_font_use(FONT_ID) and honors
       glcd_background_color variable, and glcd_pen_color.
      Parameters:
       x    - x-coordinate in range 0..SSD1306_MAX_X_PIXELS - 1
       y    - y-coordinate in range 0..SSD1306_MAX_Y_PIXELS - 1
       char - ASCII character
      Notes:
       Although x and y are given in pixels, the y coordindate will be mapped on
       display lines (pages) using glcd_font_current_height_. So when called y must
       always be defined in steps of glcd_font_current_height_.
       When using glcd_common library, a glcd'put pseudo-variable will be defined,
       and can be called as an OUTPUT device (eg. glcd = "x").
       Only available when using fonts.

- `ssd1306_write_pixel(byte in x, byte in y)`

      Description: Not implemented for text only mode
      Notes:
       Only defined as dummy procedure for the glcd_common library.

- `ssd1306_clear_cache()`

      Description: Clear the graphics cache
      Parameters:
       None
      Notes:
       Only used for graphics mode; sdd1306_update_display() must be called next.

- `ssd1306_goto(byte in x, byte in y)`

      Description: Set the display to given coordinates
      Parameters:
       x - x-coordinate in range 0..SSD1306_MAX_X_PIXELS - 1
       y - page number in range 0..SSD1306_MAX_PAGES - 1
      Notes:
       Used in text mode. Text is positioned on page boundaries.

- `ssd1306_display_on()`

      Description: Switch the display on
      Parameters:
       None

- `ssd1306_start_scroll_right(byte in start, byte in stop)`

      Description: Scroll the whole display right
      Parameters:
       start - starting point
       stop  - ending point
      Notes:
       For scrolling the whole display start must be 0x00 and stop must be 0x07.

- `ssd1306_init()`

      Description: Initialize the SSD1306 library and display
       When SPI is used and the reset pin is defined then the module will also be
       hardware reset.
      Parameters:
       None
      Notes:
       The use IIC interface or SPI interface must be initialized.

- `ssd1306_send_command_parameter(byte in command, byte in parameter)`

      Description: Send a command to the SSD1306 with the given parameter
      Parameters:
       command   - instruction for the SSD1306 from the datasheet
       parameter - data for the SSD1306 as described in the datasheet

- `ssd1306_display_inverse()`

      Description: Put the display in inverse mode
      Parameters:
       None

- `ssd1306_start_scroll_left(byte in start, byte in stop)`

      Description: Scroll the whole display left
      Parameters:
       start - starting point
       stop  - ending point
      Notes:
       For scrolling the whole display start must be 0x00 and stop must be 0x07.

- `ssd1306_start_scroll_diagonal_right(byte in start, byte in stop)`

      Description: Scroll the whole display right diagonal
      Parameters:
       start - starting point
       stop  - ending point
      Notes:
       For scrolling the whole display start must be 0x00 and stop must be 0x07.

- `ssd1306_stop_scroll()`

      Description: Stop scrolling the display
      Parameters:
       None

- `ssd1306_set_start_line(byte in start_line)`

      Description: Set the display start line.
       The procedure can be used to implement a vertical scroll feature.
      Parameters:
       start_line - 0..SSD1305_MAX_Y_PIXELS - 1

- `ssd1306_start_scroll_diagonal_left(byte in start, byte in stop)`

      Description: Scroll the whole display left diagonal
      Parameters:
       start - starting point
       stop  - ending point
      Notes:
       For scrolling the whole display start must be 0x00 and stop must be 0x07.

- `ssd1306_display_all_on()`

      Description: Put all segments of the display on
      Parameters:
       None

- `ssd1306_display_off()`

      Description: Switch the display off
      Parameters:
       None

- `ssd1306_display_normal()`

      Description: Put the display in normal (non-inverse) mode
      Parameters:
       None

- `ssd1306_goto_pixel(byte in x, byte in y)`

      Description: Set the display to given pixel coordinates
      Parameters:
       x - x-coordinate in range 0..SSD1306_MAX_X_PIXELS - 1
       y - y-coordinate in range 0..SSD1306_MAX_Y_PIXELS - 1
      Notes:
       Used in graphics mode. Text is positioned on pixel coordinates.

- `ssd1306_clear_screen()`

      Description: Clear the screen
      Parameters:
       None
      Notes:
       Cursor is set to the position 0,0.

Private

- `_ssd1306_stop_transmission()`

      Description: Stop an IIC transmission or SPI transmission
      Parameters:
       None

- `_ssd1306_start_transmission(bit in transmission)`

      Description: Start an IIC transmission or SPI data or command transmission
      Parameters:
       transmission - TRUE is data transmission, FALSE is command transmission

- `_ssd1306_write_one_data_byte(byte in data)`

      Description: Write one data byte to the SSd1306
      Parameters:
       data - data byte to be written.
      Notes:
       Used to send one data byte in one transmission.

- `_ssd1306_write_byte(byte in data)`

      Description: Write a byte to the SSD1306
      Parameters:
       data - data byte to be written.
      Notes:
       Used to send a number of data bytes in one transmission.
       Transmission must have been started using _ssd1306_start_transmission() and
       must be stopped when done by using _ssd1306_stop_transmission().

### Functions

Private

- `_ssd1306_spi_sw_exchange(byte in data) return byte`

      Description: Software SPI interface.
      Parameters:
       data -  data byte to be transmitted
      Returns:
       0x00
      Notes:
       There is no data read in this SPI variant, only data written.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_dcf77_decoder_ssd1306.jal
16f1825 | 16f1825_nec_rc_decoder_ssd1306.jal
16f1825 | 16f1825_gps_neo_6m_ssd1306_clock.jal
16f1825 | 16f1825_glcd_ssd1306_font.jal
16f1825 | 16f1825_philips_rc_decoder_ssd1306.jal
16f18857 | 16f18857_glcd_ssd1306_font_graphics.jal
16f18857 | 16f18857_glcd_ssd1306_font.jal