# glcd_sh1106

Library for GLCD using the SH1106 display controller.

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

Description

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

Sources

    Library glcd_ssd1306.jal used as starting point.
             SH1106 Data Sheet from Sino wealth version 2.6

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 _SH1106_SET_VCOMDETECT = 0xDB`
- `const byte _SH1106_SET_DISPLAY_CLOCKDIV = 0xD5`
- `const byte _SH1106_SET_CHARGEPUMP = 0x8D`
- `const byte GLCD_COLOR_BITS = 1`
- `const byte _SH1106_COLUMN_ADDRESS_LOW = 0x00`
- `const byte _SH1106_DISPLAY_RESUME = 0xA4`
- `const byte _SH1106_SET_MULTIPLEX = 0xA8`
- `const bit _SH1106_COMMAND_TRANSMISSION = 0`
- `const byte _SH1106_DISPLAY_INVERSE = 0xA7`
- `var byte glcd_background_color = GLCD_WHITE`
- `const byte _SH1106_SET_DISPLAY_OFFSET = 0xD3`
- `const byte _SH1106_DISPLAY_NORMAL = 0xA6`
- `const byte _SH1106_DISPLAY_ON = 0xAF`
- `const byte _SH1106_COMSCANDEC = 0xC8`
- `const byte _SH1106_SET_SEGMENTREMAP = 0xA1`
- `const byte _SH1106_DISPLAY_OFF = 0xAE`
- `const byte _SH1106_SET_STARTLINE = 0x40`
- `const byte _SH1106_SET_CONTRAST = 0x81`
- `const byte _SH1106_DISPLAY_ALL_ON = 0xA5`
- `const GLCD_WHITE = 0xFF`
- `const byte GLCD_Y_PIXELS = SH1106_MAX_Y_PIXELS`
- `var byte glcd_pen_color = GLCD_BLACK`
- `const GLCD_XOR = 0x01`
- `const byte SH1106_MAX_X_PIXELS = 128`
- `const byte GLCD_X_PIXELS = SH1106_MAX_X_PIXELS`
- `const byte SH1106_MAX_PAGES = 8`
- `const byte _SH1106_SET_PRECHARGE = 0xD9`
- `const bit _SH1106_DATA_TRANSMISSION = 1`
- `const byte _SH1106_PAGE_START_ADDRESS = 0xB0`
- `const GLCD_BLACK = 0x00`
- `const byte _SH1106_SET_COMPINS = 0xDA`
- `const byte _SH1106_COLUMN_ADDRESS_HIGH = 0x10`

### Procedures

- `sh1106_set_start_line(byte in start_line)`
- `sh1106_write_pixel(byte in x, byte in y)`
- `sh1106_display_resume()`
- `sh1106_update_display()`
- `sh1106_set_contrast(byte in contrast)`
- `sh1106_clear_cache()`
- `sh1106_display_off()`
- `sh1106_goto_pixel(byte in x, byte in y)`
- `sh1106_display_all_on()`
- `sh1106_send_command(byte in command)`
- `sh1106_display_on()`
- `sh1106_goto(byte in x, byte in y)`
- `sh1106_display_normal()`
- `sh1106_display_inverse()`
- `sh1106_init()`
- `sh1106_write_char(byte in x, byte in y, byte in char)`
- `sh1106_send_command_parameter(byte in command, byte in parameter)`
- `sh1106_clear_screen()`

Private

- `_sh1106_stop_transmission()`
- `_sh1106_start_transmission(bit in transmission)`
- `_sh1106_write_byte(byte in data)`
- `_sh1106_write_one_data_byte(byte in data)`

### Functions

Private

- `_sh1106_spi_sw_exchange(byte in data) return byte`

## API details

### Global variables/contants

- `const byte _SH1106_SET_VCOMDETECT = 0xDB`

      Parameter 0x00..0xFF. POR = 0x35

- `const byte _SH1106_SET_DISPLAY_CLOCKDIV = 0xD5`

      Parameter 0x00..0xFF. POR = 0x50

- `const byte _SH1106_SET_CHARGEPUMP = 0x8D`

  No documentation found

- `const byte GLCD_COLOR_BITS = 1`

      Monochrome display.

- `const byte _SH1106_COLUMN_ADDRESS_LOW = 0x00`

      SH1106 commands.

- `const byte _SH1106_DISPLAY_RESUME = 0xA4`

      Normal display status (POR)

- `const byte _SH1106_SET_MULTIPLEX = 0xA8`

  No documentation found

- `const bit _SH1106_COMMAND_TRANSMISSION = 0`

  No documentation found

- `const byte _SH1106_DISPLAY_INVERSE = 0xA7`

  No documentation found

- `var byte glcd_background_color = GLCD_WHITE`

      Default background color.

- `const byte _SH1106_SET_DISPLAY_OFFSET = 0xD3`

      Parameter 0..63. POR = 0

- `const byte _SH1106_DISPLAY_NORMAL = 0xA6`

  No documentation found

- `const byte _SH1106_DISPLAY_ON = 0xAF`

  No documentation found

- `const byte _SH1106_COMSCANDEC = 0xC8`

  No documentation found

- `const byte _SH1106_SET_SEGMENTREMAP = 0xA1`

      Reverse direction (POR is A0)

- `const byte _SH1106_DISPLAY_OFF = 0xAE`

  No documentation found

- `const byte _SH1106_SET_STARTLINE = 0x40`

  No documentation found

- `const byte _SH1106_SET_CONTRAST = 0x81`

      Parameter 0x00..0xFF (POR is 0x80)

- `const byte _SH1106_DISPLAY_ALL_ON = 0xA5`

      Counterpart of display resume.

- `const GLCD_WHITE = 0xFF`

  No documentation found

- `const byte GLCD_Y_PIXELS = SH1106_MAX_Y_PIXELS`

  No documentation found

- `var byte glcd_pen_color = GLCD_BLACK`

      Default pen color.

- `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 SH1106_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 GLCD_X_PIXELS = SH1106_MAX_X_PIXELS`

      GLCD specifications.

- `const byte SH1106_MAX_PAGES = 8`

      Vertically the device uses pages of 8 pixels high.

- `const byte _SH1106_SET_PRECHARGE = 0xD9`

      Parameter 0x00..0xFF. POR = 0x22

- `const bit _SH1106_DATA_TRANSMISSION = 1`

  No documentation found

- `const byte _SH1106_PAGE_START_ADDRESS = 0xB0`

      Address 0xB0..0xB7

- `const GLCD_BLACK = 0x00`

      Colors constants. Black & white are official values for the display controller.

- `const byte _SH1106_SET_COMPINS = 0xDA`

      Parameter 0x02 or 0x12. POR = 0x02

- `const byte _SH1106_COLUMN_ADDRESS_HIGH = 0x10`

      Address 0x10..0x1F

### Procedures

- `sh1106_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..SH1106_MAX_Y_PIXELS - 1

- `sh1106_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.

- `sh1106_display_resume()`

      Description: Resume the display
      Parameters:
       None

- `sh1106_update_display()`

      Description: Copy the changed area of the graphics cache to the display
      Parameters:
       None
      Notes:
       Only used for graphics mode. This procedure is to be used when using
       graphics features like pixes, lines, circles, etc. to send the contents
       of the cache to the display.

- `sh1106_set_contrast(byte in contrast)`

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

- `sh1106_clear_cache()`

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

- `sh1106_display_off()`

      Description: Switch the display off
      Parameters:
       None

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

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

- `sh1106_display_all_on()`

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

- `sh1106_send_command(byte in command)`

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

- `sh1106_display_on()`

      Description: Switch the display on
      Parameters:
       None

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

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

- `sh1106_display_normal()`

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

- `sh1106_display_inverse()`

      Description: Put the display in inverse mode
      Parameters:
       None

- `sh1106_init()`

      Description: Initialize the SH1106 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.

- `sh1106_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..SH1106_MAX_X_PIXELS - 1
       y    - y-coordinate in range 0..SH1106_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.

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

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

- `sh1106_clear_screen()`

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

Private

- `_sh1106_stop_transmission()`

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

- `_sh1106_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

- `_sh1106_write_byte(byte in data)`

      Description: Write a byte to the SH1106
      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 _sh1106_start_transmission() and
       must be stopped when done by using _sh1106_stop_transmission().

- `_sh1106_write_one_data_byte(byte in data)`

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

### Functions

Private

- `_sh1106_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_glcd_sh1106_font.jal
16f18857 | 16f18857_glcd_sh1106_font.jal
16f18857 | 16f18857_glcd_sh1106_font_graphics.jal