# glcd_ili9341

Library for GLCD using the ILI9341 display controller.

Author | Rob Jansen, Copyright © 2022..2023, all rights reserved.
Adapted-by |
Compiler | 2.5r8

Description

    Text and graphics library for the graphic display module using
                 the ILI9341 display controller, controlled via a 4-wire SPI
                 interface. The library supports displays with a resolution of
                 240 x 320 pixels. The default resolution can be overruled.

Sources

    a-Si TFT LCD Single Chip Driver 240RGBx320 Resolution and 262K color
             Specification version: V1.09
             Inspired by the Adafruit ILI9341 library for Arduino.

Notes

    The default display resolution is 240 x 320 pixels If a display with a
           different resolution is used you can overrule these as follows (example):
           const word ILI9341_MAX_X_PIXELS = 128  -- Width
           const word ILI9341_MAX_Y_PIXELS = 160  -- Height

Dependencies

- glcd_common

## Summary

### Global variables/contants

- `const byte GLCD_COLOR_BITS = 16`
- `const ILI9341_ROTATE_0_DEGREES = 0`
- `var word glcd_background_color = ILI9341_BLACK`
- `const byte _ILI9341_RDDST = 0x09`
- `const byte _ILI9341_SWRESET = 0x01`
- `const word ILI9341_OLIVE = 0x7BE0`
- `const word ILI9341_PINK = 0xFC18`
- `const byte _ILI9341_FRMCTR1 = 0xB1`
- `const byte GLCD_X_PIXELS = ILI9341_MAX_X_PIXELS`
- `const byte _ILI9341_NORON = 0x13`
- `const byte MADCTL_BGR = 0x08`
- `const bit _ILI9341_COMMAND_TRANSMISSION = 0`
- `const byte _ILI9341_VMCTR2 = 0xC7`
- `const byte _ILI9341_GAMMASET = 0x26`
- `const byte _ili9341_initialization_data[] =`
- `const byte _ILI9341_DFUNCTR = 0xB6`
- `const byte _ILI9341_RDID4 = 0xDD`
- `const byte _ILI9341_VSCRDEF = 0x33`
- `const byte _ILI9341_PWCTR4 = 0xC3`
- `const ILI9341_ROTATE_180_DEGREES = 2`
- `const word ILI9341_MAGENTA = 0xF81F`
- `const word ILI9341_BLUE = 0x001F`
- `const byte _ILI9341_PIXFMT = 0x3A`
- `const byte _ILI9341_PWCTR3 = 0xC2`
- `const byte _ILI9341_RDID2 = 0xDB`
- `const byte _ILI9341_FRMCTR2 = 0xB2`
- `const word ILI9341_GREEN = 0x07E0`
- `const word ILI9341_GREENYELLOW = 0xAFE5`
- `const word ILI9341_DARKCYAN = 0x03EF`
- `const byte _ILI9341_PWCTR1 = 0xC0`
- `const byte _ILI9341_VMCTR1 = 0xC5`
- `const GLCD_Y_SIZE = 2`
- `const byte _ILI9341_RDID1 = 0xDA`
- `const word ILI9341_NAVY = 0x000F`
- `const byte _ILI9341_RDPIXFMT = 0x0C`
- `const byte MADCTL_MY_BT = 0x80`
- `const GLCD_X_SIZE = 2`
- `const byte _ILI9341_PTLON = 0x12`
- `const word ILI9341_ORANGE = 0xFD20`
- `const byte _ILI9341_PASET = 0x2B`
- `var word glcd_pen_color = ILI9341_WHITE`
- `const word GLCD_Y_PIXELS = ILI9341_MAX_Y_PIXELS`
- `const byte _ILI9341_INVCTR = 0xB4`
- `const byte _ILI9341_RDID3 = 0xDC`
- `const byte _ILI9341_RDIMGFMT = 0x0D`
- `const byte _ILI9341_SLPIN = 0x10`
- `const byte _ILI9341_RDMADCTL = 0x0B`
- `const byte _ILI9341_RAMRD = 0x2E`
- `const word ILI9341_RED = 0xF800`
- `const byte _ILI9341_RDDID = 0x04`
- `const word ILI9341_WHITE = 0xFFFF`
- `const bit _ILI9341_DATA_TRANSMISSION = 1`
- `const GLCD_WHITE = ILI9341_WHITE`
- `const GLCD_BLACK = ILI9341_BLACK`
- `const byte _ILI9341_MADCTL = 0x36`
- `const byte MADCTL_MY_TB = 0x00`
- `const word ILI9341_DARKGREEN = 0x03E0`
- `const byte _ILI9341_PWCTR5 = 0xC4`
- `var bit _ili9341_mirror_x`
- `var bit _ili9341_mirror_y`
- `const ILI9341_ROTATE_90_DEGREES = 1`
- `const byte _ILI9341_NOP = 0x00`
- `const byte _ILI9341_PTLAR = 0x30`
- `const byte _ILI9341_DISPON = 0x29`
- `const word ILI9341_DARKGREY = 0x7BEF`
- `const byte _ILI9341_INVOFF = 0x20`
- `const byte _ILI9341_RDMODE = 0x0A`
- `const byte _ILI9341_PWCTR2 = 0xC1`
- `const byte _ILI9341_GMCTRP1 = 0xE0`
- `const word ILI9341_PURPLE = 0x780F`
- `const byte _ILI9341_SLPOUT = 0x11`
- `const byte MADCTL_MX_LR = 0x00`
- `const word ILI9341_MAROON = 0x7800`
- `const byte _ILI9341_RAMWR = 0x2C`
- `const word ILI9341_BLACK = 0x0000`
- `const byte _ILI9341_DISPOFF = 0x28`
- `const ILI9341_ROTATE_270_DEGREES = 3`
- `const byte _ILI9341_CASET = 0x2A`
- `const byte _ILI9341_VSCRSADD = 0x37`
- `const word ILI9341_CYAN = 0x07FF`
- `const word ILI9341_YELLOW = 0xFFE0`
- `const byte _ILI9341_FRMCTR3 = 0xB3`
- `const byte _ILI9341_INVON = 0x21`
- `const byte MADCTL_MX_RL = 0x40`
- `const word ILI9341_LIGHTGREY = 0xC618`
- `const byte MADCTL_MV = 0x20`
- `const byte _ILI9341_GMCTRN1 = 0xE1`
- `const byte _ILI9341_RDSELFDIAG = 0x0F`
- `const byte _ILI9341_PWCTR6 = 0xFC`

### Procedures

- `ili9341_vertical_scroll_display(word in number_of_pixels)`
- `ili9341_mirror_x_on()`
- `ili9341_clear_screen()`
- `ili9341_display_normal()`
- `ili9341_goto(word in x, word in y)`
- `ili9341_display_sleep()`
- `ili9341_display_off()`
- `ili9341_write_pixel(word in x, word in y)`
- `ili9341_display_inverse()`
- `ili9341_init()`
- `ili9341_mirror_x_off()`
- `ili9341_fill_screen(word in color)`
- `ili9341_mirror_y_on()`
- `ili9341_display_wakeup()`
- `ili9341_display_on()`
- `ili9341_set_vertical_scroll_area(word in top, word in bottom)`
- `ili9341_mirror_y_off()`
- `ili9341_set_display_rotation(byte in rotation)`
- `ili9341_reset()`

Private

- `_ili9341_write_command(byte in command)`
- `_ili9341_write_word(word in data)`
- `_ili9341_write_data_byte(byte in data)`
- `_ili9341_write_data_word(word in data)`
- `_ili9341_start_transmission(bit in transmission_type)`
- `_ili9341_stop_transmission()`

### Functions

Private

- `_ili9341_read_word() return word`

## API details

### Global variables/contants

- `const byte GLCD_COLOR_BITS = 16`

      16 bit colors

- `const ILI9341_ROTATE_0_DEGREES = 0`

      Diplay rotation defintions in degrees

- `var word glcd_background_color = ILI9341_BLACK`

      Variables for storing background color and pen color.

- `const byte _ILI9341_RDDST = 0x09`

      Read Display Status

- `const byte _ILI9341_SWRESET = 0x01`

      Software reset register

- `const word ILI9341_OLIVE = 0x7BE0`

      123, 125,   0

- `const word ILI9341_PINK = 0xFC18`

      255, 130, 198

- `const byte _ILI9341_FRMCTR1 = 0xB1`

      Frame Rate Control (In Normal Mode/Full Colors)

- `const byte GLCD_X_PIXELS = ILI9341_MAX_X_PIXELS`

      GLCD specifications.

- `const byte _ILI9341_NORON = 0x13`

      Normal Display Mode ON

- `const byte MADCTL_BGR = 0x08`

      Blue-Green-Red pixel order (bit 3 = 1)

- `const bit _ILI9341_COMMAND_TRANSMISSION = 0`

  No documentation found

- `const byte _ILI9341_VMCTR2 = 0xC7`

      VCOM Control 2

- `const byte _ILI9341_GAMMASET = 0x26`

      Gamma Set

- `const byte _ili9341_initialization_data[] =`

      Initiazation data for the ILI9341 (many thanks to Adafruit).
      Format is: Command, nr of data bytes, data bytes.

- `const byte _ILI9341_DFUNCTR = 0xB6`

      Display Function Control

- `const byte _ILI9341_RDID4 = 0xDD`

      Read ID 4

- `const byte _ILI9341_VSCRDEF = 0x33`

      Vertical Scrolling Definition

- `const byte _ILI9341_PWCTR4 = 0xC3`

      Power Control 4

- `const ILI9341_ROTATE_180_DEGREES = 2`

  No documentation found

- `const word ILI9341_MAGENTA = 0xF81F`

      255,   0, 255

- `const word ILI9341_BLUE = 0x001F`

        0,   0, 255

- `const byte _ILI9341_PIXFMT = 0x3A`

      COLMOD: Pixel Format Set

- `const byte _ILI9341_PWCTR3 = 0xC2`

      Power Control 3

- `const byte _ILI9341_RDID2 = 0xDB`

      Read ID 2

- `const byte _ILI9341_FRMCTR2 = 0xB2`

      Frame Rate Control (In Idle Mode/8 colors)

- `const word ILI9341_GREEN = 0x07E0`

        0, 255,   0

- `const word ILI9341_GREENYELLOW = 0xAFE5`

      173, 255,  41

- `const word ILI9341_DARKCYAN = 0x03EF`

        0, 125, 123

- `const byte _ILI9341_PWCTR1 = 0xC0`

      Power Control 1

- `const byte _ILI9341_VMCTR1 = 0xC5`

      VCOM Control 1

- `const GLCD_Y_SIZE = 2`

  No documentation found

- `const byte _ILI9341_RDID1 = 0xDA`

      Read ID 1

- `const word ILI9341_NAVY = 0x000F`

        0,   0, 123

- `const byte _ILI9341_RDPIXFMT = 0x0C`

      Read Display Pixel Format

- `const byte MADCTL_MY_BT = 0x80`

      Bottom to top

- `const GLCD_X_SIZE = 2`

      We can rotate the display so we must overrule the default chosen GLCD_X_SIZE
      and GLCD_Y_SIZE (see glcd_common.jal) otherwise the width would be too small.

- `const byte _ILI9341_PTLON = 0x12`

      Partial Mode ON

- `const word ILI9341_ORANGE = 0xFD20`

      255, 165,   0

- `const byte _ILI9341_PASET = 0x2B`

      Page Address Set

- `var word glcd_pen_color = ILI9341_WHITE`

  No documentation found

- `const word GLCD_Y_PIXELS = ILI9341_MAX_Y_PIXELS`

  No documentation found

- `const byte _ILI9341_INVCTR = 0xB4`

      Display Inversion Control

- `const byte _ILI9341_RDID3 = 0xDC`

      Read ID 3

- `const byte _ILI9341_RDIMGFMT = 0x0D`

      Read Display Image Format

- `const byte _ILI9341_SLPIN = 0x10`

      Enter Sleep Mode

- `const byte _ILI9341_RDMADCTL = 0x0B`

      Read Display MADCTL

- `const byte _ILI9341_RAMRD = 0x2E`

      Memory Read

- `const word ILI9341_RED = 0xF800`

      255,   0,   0

- `const byte _ILI9341_RDDID = 0x04`

      Read display identification information

- `const word ILI9341_WHITE = 0xFFFF`

      255, 255, 255

- `const bit _ILI9341_DATA_TRANSMISSION = 1`

      Sending data or commands.

- `const GLCD_WHITE = ILI9341_WHITE`

  No documentation found

- `const GLCD_BLACK = ILI9341_BLACK`

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

- `const byte _ILI9341_MADCTL = 0x36`

      Memory Access Control

- `const byte MADCTL_MY_TB = 0x00`

      Top to bottom (default for module MSP2401)

- `const word ILI9341_DARKGREEN = 0x03E0`

        0, 125,   0

- `const byte _ILI9341_PWCTR5 = 0xC4`

      Power Control 5

- `var bit _ili9341_mirror_x`

      Local variables to support dynamic mirroring.

- `var bit _ili9341_mirror_y`

  No documentation found

- `const ILI9341_ROTATE_90_DEGREES = 1`

  No documentation found

- `const byte _ILI9341_NOP = 0x00`

      ILI9341 command list.

- `const byte _ILI9341_PTLAR = 0x30`

      Partial Area

- `const byte _ILI9341_DISPON = 0x29`

      Display ON

- `const word ILI9341_DARKGREY = 0x7BEF`

      123, 125, 123

- `const byte _ILI9341_INVOFF = 0x20`

      Display Inversion OFF

- `const byte _ILI9341_RDMODE = 0x0A`

      Read Display Power Mode

- `const byte _ILI9341_PWCTR2 = 0xC1`

      Power Control 2

- `const byte _ILI9341_GMCTRP1 = 0xE0`

      Positive Gamma Correction

- `const word ILI9341_PURPLE = 0x780F`

      123,   0, 123

- `const byte _ILI9341_SLPOUT = 0x11`

      Sleep Out

- `const byte MADCTL_MX_LR = 0x00`

      Display orientation. See register _ILI9341_RDMADCT and the datatsheet
      page 208. Depending on the display mirroring may be needed.

- `const word ILI9341_MAROON = 0x7800`

      123,   0,   0

- `const byte _ILI9341_RAMWR = 0x2C`

      Memory Write

- `const word ILI9341_BLACK = 0x0000`

      Color definitions.

- `const byte _ILI9341_DISPOFF = 0x28`

      Display OFF

- `const ILI9341_ROTATE_270_DEGREES = 3`

  No documentation found

- `const byte _ILI9341_CASET = 0x2A`

      Column Address Set

- `const byte _ILI9341_VSCRSADD = 0x37`

      Vertical Scrolling Start Address

- `const word ILI9341_CYAN = 0x07FF`

        0, 255, 255

- `const word ILI9341_YELLOW = 0xFFE0`

      255, 255,   0

- `const byte _ILI9341_FRMCTR3 = 0xB3`

      Frame Rate control (In Partial Mode/Full Colors)

- `const byte _ILI9341_INVON = 0x21`

      Display Inversion ON

- `const byte MADCTL_MX_RL = 0x40`

      Right to left (default for module MSP2401)

- `const word ILI9341_LIGHTGREY = 0xC618`

      198, 195, 198

- `const byte MADCTL_MV = 0x20`

      Reverse Mode (swap x and y)

- `const byte _ILI9341_GMCTRN1 = 0xE1`

      Negative Gamma Correction

- `const byte _ILI9341_RDSELFDIAG = 0x0F`

      Read Display Self-Diagnostic Result

- `const byte _ILI9341_PWCTR6 = 0xFC`

  No documentation found

### Procedures

- `ili9341_vertical_scroll_display(word in number_of_pixels)`

      Scroll the display vertical with the given numer of pixels.

- `ili9341_mirror_x_on()`

      Set mirroring the display in the x-direction.
      Use ili9341_set_display_rotation() to activate.

- `ili9341_clear_screen()`

      Clear the screen.

- `ili9341_display_normal()`

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

- `ili9341_goto(word in x, word in y)`

      Set the current position in pixels for the data to be written. Used for
      writing characters to the screen. Character are written as bitmap so x
      and y must be given as pixel locations.

- `ili9341_display_sleep()`

      Turn the display into sleep mode.

- `ili9341_display_off()`

      Turn the display off.

- `ili9341_write_pixel(word in x, word in y)`

      Plot a pixel at the given absolute (x, y) pixel location.
      Variable 'glcd_pen_color' should be set before calling to plot
      appropriate pixel colors. Color is in RGB format 5-6-5, 65.536 colors.

- `ili9341_display_inverse()`

      Put the display in inverse mode.

- `ili9341_init()`

      Initialize the control pins, the SPI interface and the initialize the
      ILI9341 module. When the reset hardware pin is defined then the module will
      be hardware reset, otherwise it will be software reset.

- `ili9341_mirror_x_off()`

      Reset mirroring the display in the x-direction.
      Use ili9341_set_display_rotation() to activate.

- `ili9341_fill_screen(word in color)`

      Fill the screen with the given color. Color must be in RGB 5-6-5 format.

- `ili9341_mirror_y_on()`

      Set mirroring the display in the y-direction.
      Use ili9341_set_display_rotation() to activate.

- `ili9341_display_wakeup()`

      Wakeup the display from sleep mode.

- `ili9341_display_on()`

      Turn the display on.

- `ili9341_set_vertical_scroll_area(word in top, word in bottom)`

      Set the scroll area of the display. top is the height of the top scroll
      margin and bottom the height of the bottom margin.

- `ili9341_mirror_y_off()`

      Reset mirroring the display in the y-direction.
      Use ili9341_set_display_rotation() to activate.

- `ili9341_set_display_rotation(byte in rotation)`

      Set display rotation to 0, 90, 180 or 270 degrees, see ILI9341_ROTATE.

- `ili9341_reset()`

      Peform a sofware reset. This will reset the commands and puts the registers
      in their default value. The frame memory content is unaffected.

Private

- `_ili9341_write_command(byte in command)`

      Write a command byte to ILI9341 via the SPI interface.

- `_ili9341_write_word(word in data)`

      Write a word to the ILI9341. The MSB of the word is written first.

- `_ili9341_write_data_byte(byte in data)`

      Write a data byte to the ILI9341 via the SPI interface.

- `_ili9341_write_data_word(word in data)`

      Write a data word to the ILI9341 via the SPI interface. The MSB of the
      word is written first.

- `_ili9341_start_transmission(bit in transmission_type)`

      Start an SPI data or command transmission.

- `_ili9341_stop_transmission()`

      Stop an SPI transmission.

### Functions

Private

- `_ili9341_read_word() return word`

      Read a word from the ILI9341. The MSB of the word is read first.

## Related samples

Here are the list of samples which use this library:

16f18857 | 16f18857_glcd_ili9341.jal
16f18857 | 16f18857_touch_ads7843.jal
16f18857 | 16f18857_touch_interrupt_ads7843.jal
16f18857 | 16f18857_glcd_ili9341_fat32_sd_card.jal
18f46q10 | 18f46q10_glcd_ili9341_font.jal