# glcd_ks0108

glcd_ks0108 - Library for KS0108 compatible graphic LCDs

Author | Serkan Ayyldz Copyright © 2006..2026, all rights reserved.
Adapted-by | Sebastien Lelong, Rob Hamerling, Rob Jansen
Compiler | 2.5r9

Description

    Library for KS0108 compatible graphic lcds with 128x64 resolution
                 for example the GDM12864A.

Sources

    LCD MODULE SPECIFICATION, BG12864A series Bolymin, Inc. 2005-05-21.

Notes

    - A 128x64 graphic LCD consists with 2 controllers (KS0108_LEFT and
             KS0108_RIGHT), each take care of 64x64 bits.
           - Addressing: upper left corner is coordinate (0,0)
           - A byte of data represents a column of 8 pixels, so the vertical
             64 pixels are represented by 8 bytes (a row of 8 bits is called
             'page' in the datasheet).

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte GLCD_WHITE = 0x00`
- `const byte GLCD_DI_DATA = high`
- `const byte KS0108_CMD_PAGE = 0xB8`
- `const byte GLCD_COLOR_BITS = 1`
- `var byte glcd_pen_color = GLCD_BLACK`
- `const byte KS0108_CMD_ON = 0x3F`
- `const bit KS0108_RIGHT = 1`
- `const byte KS0108_CMD_COLUMN = 0x40`
- `const byte GLCD_Y_PIXELS = 64`
- `var byte glcd_background_color = GLCD_WHITE`
- `const byte GLCD_BLACK = 0x01`
- `const byte GLCD_X_PIXELS = 128`
- `const byte GLCD_DI_INST = low`
- `const bit KS0108_LEFT = 0`
- `const byte KS0108_CMD_TOP_RAM = 0xC0`
- `const byte KS0108_CMD_OFF = 0x3E`

### Procedures

- `glcd_fill(byte in data)`
- `glcd_clear_screen()`
- `ks0108_page_(bit in side, byte in page)`
- `ks0108_goto(byte in x, byte in y)`
- `glcd_init()`
- `ks0108_inst_()`
- `glcd_write_pixel(byte in x, byte in y)`
- `ks0108_write_byte_(byte in x, byte in y, byte in data)`
- `ks0108_write_(bit in side, byte in data)`
- `ks0108_on_()`
- `ks0108_data_()`
- `ks0108_off_()`
- `ks0108_column_(bit in side, byte in column)`

### Functions

- `remap_bits(byte in data) return byte`
- `ks0108_read_byte_(byte in x, byte in y) return byte`
- `ks0108_read_(bit in side) return byte`

## API details

### Global variables/contants

- `const byte GLCD_WHITE = 0x00`

      alternate pen color

- `const byte GLCD_DI_DATA = high`

      data/instruction selection of DI line

- `const byte KS0108_CMD_PAGE = 0xB8`

      command to select page (y-coord / 8)

- `const byte GLCD_COLOR_BITS = 1`

      monochrome display

- `var byte glcd_pen_color = GLCD_BLACK`

      default pen color

- `const byte KS0108_CMD_ON = 0x3F`

      command to enable the display

- `const bit KS0108_RIGHT = 1`

      select right part of display

- `const byte KS0108_CMD_COLUMN = 0x40`

      command to select column (x-coord)

- `const byte GLCD_Y_PIXELS = 64`

      display y-dimension

- `var byte glcd_background_color = GLCD_WHITE`

      default background color

- `const byte GLCD_BLACK = 0x01`

      constant colors

- `const byte GLCD_X_PIXELS = 128`

      display x-dimension

- `const byte GLCD_DI_INST = low`

      select command

- `const bit KS0108_LEFT = 0`

      select left part of display

- `const byte KS0108_CMD_TOP_RAM = 0xC0`

      command to set startline

- `const byte KS0108_CMD_OFF = 0x3E`

      command to disable the display

### Procedures

- `glcd_fill(byte in data)`

      Purpose:    Fill the whole GLCD with a pixel pattern (horizontal lines!)
      Arguments:  bit pattern (8 pixel column, usually 0x00 or 0xFF)
      Notes:      Uses auto-increment of x-coordinate for fast write of rows

- `glcd_clear_screen()`

      Purpose:    Clear the screen
      Arguments:  none
      Notes:      Resets the display with the RST line
      Uses current glcd_background_color setting as fill character

- `ks0108_page_(bit in side, byte in page)`

      Purpose:   Set the page number
      Arguments: - side
       page number (y-coordinate) 0..7

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

      Purpose:   Goto the given pixel coordinates.
      Arguments: - x, 0..127
       y, 0..63

- `glcd_init()`

      Purpose:   Initialize the graphic LCD.
      Arguments: none
      Notes:     to be called before using any other GLCD function.

- `ks0108_inst_()`

      Purpose:   Specify subsequent reads and writes are instructions
      Arguments: none

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

      Purpose:    Write a single pixel to the display
      Arguments:  - x-coordinate of the pixel
       y-coordinate of the pixel

- `ks0108_write_byte_(byte in x, byte in y, byte in data)`

      Purpose:   Write byte (column of 8 pixels) to display
      Arguments: - x-coordinate of the pixel
       y-coordinate of the pixel (not necessarily on page boundary)
       pattern of 8 vertically aligned pixels
      Notes:     When data on page boundary (y-coordinate multiple of 8): single write
      When the data is crossing page boundary: two read-modify-write
      operations have to be performed, which is considerably slower.

- `ks0108_write_(bit in side, byte in data)`

      Purpose:   Low level write a byte to the specified chip
      Arguments: - side: which chip to write the data to: 0 = left, 1 = right)
       data: the byte of data to write)
      Notes:     The 'data' byte may be display data or a command.
      When it is data to be displayed its coordinates must
      have been been set on beforehand (column,page).
      GLCD_E is set low for 1/4 cycle upon call and kept low
      for 1/4 cycle before returning such that successive calls
      to read or write have GLCD_E low for at least 1/2 cycle
      between calls.

- `ks0108_on_()`

      Purpose:   Turn the display on
      Arguments: none
      Notes:     both sides are activated

- `ks0108_data_()`

      Purpose:   Specify subsequent reads and writes are data
      Arguments: none

- `ks0108_off_()`

      Purpose:   Turn the display off
      Arguments: none
      Notes:     both sides are de-activated

- `ks0108_column_(bit in side, byte in column)`

      Purpose:   Set the column number
      Arguments: - cide
       column number (x-coordinate) 0..63

### Functions

- `remap_bits(byte in data) return byte`

      Purpose: Remap bits of a byte.
      Input:   Byte of which bits must be remapped.
      Returns: Byte with rempapped bits of input byte.
      Notes:   - Supports currently only reversing the bits in a byte.
      (may add support for other types of mapping later).
       Reverse is only done when const bit GLCD REVERSE_DATABITS = TRUE

- `ks0108_read_byte_(byte in x, byte in y) return byte`

      Purpose:    read byte (column of pixels) from display
      Arguments:  x = pixel column
      y = pixel row (not necessarily on page boundary)
      Returns:    byte, row of pixels on current location

- `ks0108_read_(bit in side) return byte`

      Purpose:   Low level read of a byte from the specified chip.
      Arguments: side: which chip to read, 0 = left, 1 = right)
      Returns:   A byte of data read from the chip (row of 8 vertical pixels).
      The coordinates (column,page) must have been been set on
      beforehand.
      Notes:     GLCD_E is set low for 1/4 cycle upon call and kept low
      for 1/4 cycle before returning such that successive calls
      to read or write have GLCD_E low for at least 1/2 cycle
      between calls.

## Related samples

Here are the list of samples which use this library:

16f1829 | 16f1829_glcd_ks0108.jal
16f877a | 16f877a_glcd_ks0108.jal
18f2580 | 18f2580_rtc_ds1302_glcd.jal
18f6310 | 18f6310_glcd_ks0108.jal
18f6310 | 18f6310_glcd_ks0108_math.jal