# glcd_ks0108

glcd_ks0108 - Library for KS0108 compatible graphic LCDs

Author | Serkan Ayyldz Copyright © 2006..2009, all rights reserved.
Adapted-by | Sebastien Lelong, Rob Hamerling.
Compiler | 2.4o

Description

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

Notes

    Modifications by Rob Hamerling (nov/dec 2011):
           - Minor timing changes in ks0108_read_() and ks0108_write_()
             according to datasheet schemes for MPU Write timing and Read timing.
             Replaced hard coded ASM NOPs by _usec_delay()
           - Private procedures/function prefixed with underscore
           - Added procedure glcd_clear_screen() and use it in glcd_init().
             Uses the reset line to set Z-address to zero.
           - Modified procedures to be able to write characters with
             y-coordinates NOT on page (8-bit) boundaries.
             Works probably only with max 8 bits high font (5x7 and 6x8)
           - Replaced absolute values for loops and offsets by symbolic values
           - Code optimisations, incl add/remove of some 'pragma inline'
           - Fixed some bugs with external fonts
           - Comments extended, corrected, aligned (for JALAPI docs)
           Modifications by Rob Hamerling (May 2015)
           - Added procedure to support remap (reverse) databit sequence
             for more wiring flexibility (pin sequence: D7..D0 in stead of D0..D7)
             Controlled by constant GLCD_REVERSE_DATABITS = FALSE / TRUE.
    .
           Technical (library internal) details
           - 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 bit KS0108_RIGHT = 1`
- `const byte GLCD_BLACK = 0x01`
- `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 byte font_5x7_table_[] = {`
- `const byte KS0108_CMD_COLUMN = 0x40`
- `const byte GLCD_Y_PIXELS = 64`
- `var byte glcd_background_color = GLCD_WHITE`
- `const byte GLCD_DI_DATA = high`
- `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)`
- `glcd_init()`
- `ks0108_write_(bit in side, byte in data)`
- `ks0108_inst_()`
- `glcd_write_pixel(byte in x, byte in y)`
- `ks0108_write_byte_(byte in x, byte in y, byte in data)`
- `ks0108_on_()`
- `glcd_write_char(byte in x, byte in y, byte in ch )`
- `ks0108_data_()`
- `ks0108_off_()`
- `ks0108_write_char_(byte in x, byte in y, byte in ch)`
- `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 bit KS0108_RIGHT = 1`

      select right part of display

- `const byte GLCD_BLACK = 0x01`

      constant colors

- `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 byte font_5x7_table_[] = {`

      font_5x7_table_[] - character table

- `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_DI_DATA = high`

      data/instruction selection of DI line

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

- `glcd_init()`

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

- `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_inst_()`

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

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

      Purpose:    Write (modify) a single pixel of 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_on_()`

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

- `glcd_write_char(byte in x, byte in y, byte in ch )`

      Purpose:   Same as ks0108_write_char_(), but uses external font.
      Arguments: - x-coordinate (in pixels) of left most pixel columm (range 0..127)
       y-coordinate (in pixels) of upper most pixel-row (range 0..63)
       character (binary value in range 32..122)
      Notes:     When y-coordinate is a multiple of 8 (0,8,16,etc.): single write,
      otherwise two read-modify-write cycles needed: slower!

- `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_write_char_(byte in x, byte in y, byte in ch)`

      Purpose:   Write character to the display using internal font definition.
      Arguments: - x- and y-coordinates (upper left corner of character pattern)
       character to display
      Notes:     For characters the display is 8 lines, each 8 bits high;
      specify for y-coordinate a multiple of 8.

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

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