# glcd_ssd1306

Library for GLCD using the SSD1306 display controller.

Author | Rob Jansen, Copyright © 2020..2025, 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

No dependency found

## 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_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_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_clear_screen()`

Private

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

### Functions

## 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_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()`

      Resume the display.

- `ssd1306_set_contrast(byte in contrast)`

      Set display contrast, value from 0x00 to 0xFF.

- `ssd1306_send_command(byte in command)`

      Send a command to the ssd1306 without paramater. It is up to the user to
      set the correct command as described in the datasheet.

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

      Set the current position for the data to be written, x = 0->127, y = 0->7.

- `ssd1306_display_on()`

      Put the display on.

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

      Scroll the whole display right. For scrolling the whole display 'start'
      must be 0x00 and 'stop' must be 0x07.

- `ssd1306_init()`

      Initialize the control pins abd the SSD1306. When SPI is used and the reset
      pin is defined then the module will also be hardware reset.

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

      Send a command to the ssd1306 with a paramater. It is up to the user to
      set the correct command and parameter as described in the datasheet.

- `ssd1306_display_inverse()`

      Put the display in inverse mode.

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

      Scroll the whole display left. 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)`

      Scroll the whole display diagonal right. For scrolling the whole display
      'start' must be 0x00 and 'stop' must be 0x07.

- `ssd1306_stop_scroll()`

      Stop the scroll feature.

- `ssd1306_set_start_line(byte in start_line)`

      Set the display start line. The procedure can be used to implement a
      vertical scroll feature. Start line is in range 0..(SSD1306_MAX_Y_PIXELS - 1)

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

      Scroll the whole display diagonal left. For scrolling the whole display
      'start' must be 0x00 and 'stop' must be 0x07.

- `ssd1306_display_all_on()`

      Put all segments of the display on.

- `ssd1306_display_off()`

      Switch the display off.

- `ssd1306_display_normal()`

      Put the display in normal (non-inverse) mode.

- `ssd1306_clear_screen()`

      Clear the screen and move the cursor to position 0,0.

Private

- `_ssd1306_stop_transmission()`

      Stop an IIC or SPI transmission.

- `_ssd1306_start_transmission(bit in data_transmission)`

      Start an IIC or SPI data or command transmission.

- `_ssd1306_write_one_data_byte(byte in data)`

      Write one data byte to the SSD1306. Transmission is not active.

- `_ssd1306_write_byte(byte in data)`

      Write a byte to the SSD1306. Transmission must have been started.

### Functions

## Related samples

Here are the list of samples which use this library:

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