This is a port of Henning Kralsen's UTFT library for Arduino/chipKIT to mbed, refactored to make full use of C++ inheritance and access control, in order to reduce work when implementing new drivers and at the same time make the code more readable and easier to maintain. As of now supported are SSD1289 (16-bit interface), HX8340-B (serial interface) and ST7735 (serial interface). Drivers for other controllers will be added as time and resources to acquire the displays to test the code permit.

Dependents:   test SDCard capstone_display capstone_display_2 ... more

TFTLCD Library

NOTE (2013-03-25) Tested with both mbed LPC1768 and Freedom KL25Z. -todor

A TFT LCD driver library, which at the moment provides support for the following display controllers: HX8340-B (serial interface), SSD1289 (16-bit interface), ST7735-R (serial interface), ILI9325/ILI9328 (16-bit interface).

As I am acquiring and testing out new displays, I decided to combine all ported drivers into one library as with the original work done by Henning. However I also had as a goal to make the code maintenance and readability easier/better, so the code has been heavily refactored to make full use of C++ facilities as inheritance and access control. I extracted the common pieces of code into a base class, which every driver inherits and only the controller-specific side is provided in the actual driver - things like initialization, addressing, data transfer, etc.

Another nice extension is that the display's backlight can now be controlled through the driver. Either a simple on/off method of control could be selected, or the brightness can be set through use of PWM (the latter placing some restrictions on which pins can be used for this, as mbed offers hardware PWM on only 6 pins).

I also plan to add support for touch screens as part of the library. The goal is to grow this piece of software into a lightweight graphics widgets library, which can be used to construct control screens with buttons or menus in a speedy and intuitive way.



  • Fixed the sleep/wake-up functions of the ILI9328 driver.


  • Added driver for ILI9328 (works with ILI9325) controller, 16-bit data bus. Screen rotation works as usual with the TFTLCD library, but for now only RGB565 color depth is working and you can use both 65K and 262K color space with this driver. But for some reason the sleep function is not behaving as expected; I am working on this.
  • This is only on my to-do list for now - haven't really had the time yet - but I am going to refactor the library a bit to allow use of GPIO ports for data transfers instead of DigitalOut: faster and cleaner that way. For those who are using it already in a working design and cannot repurpose the pins anymore, the current way it's working will still be available; I am hoping not to tear up the public interfaces of the library (... too much). Anyway, since I am at it, I will also try to add support for multiple bus interfaces to drivers that support it (i.e. both 8bit and 16bit use of ILI932x or SSD1289). Thought this might be a good place to give you guys the heads-up.


  • Replaced all existing fonts from the UTFT library with the free Terminus font. Two different sizes are provided: 8x12 pixels and 16x28 pixels. I found the old fonts not so good looking and then they supported only the ASCII codes in the range 30 (space) to 126 (the tilde ). The 7segment font didn't even implement anything else than the numbers from 0 to 9 - so it was unusable for anything (one couldn't even display the time or date as it lacked the colon [:] or the period [.] or the slash [/] or the space [ ] characters). So I completely revamped the fonts and added Terminus as the new default with its 2 sizes. Further more I added in both sizes most of the characters up to ASCII code 255. For any code not in there, the space character is substituted. In the case, when you already have provided your own fonts, please have a look at the API changes in the files <terminus.h> and <terminus.cpp>: I promise you whatever time you spent designing your own font, it is not wasted; you merely need to add a second array, which describes which ASCII codes are available in your font, and their byte offset in the original character bitmap array; and a struct to tie all parts together and describe the character size. I am sorry for breaking the old API, but you will like the change and new options it brings you. Now you can insert any char above 127 up to code 255 (if available, of course) with its hex representation, e.g displaying the current temperature would look something like 85\xB0 F or 26\xB0 C (the space in between degree and F or C is needed because both F and C are used in hex numbers, so \xB0F is interpreted as ASCII code 2831 instead of ASCII code 176, followed by the temperature scale denomination; if you insist on avoiding the space, you could write 85\xB0\x46 which will be displayed correctly as 85°F). You can either look up the ASCII code you need on Google or Bing, or just look at what's available - how it looks and its hex value - in the comments in <terminus.cpp>.
  • Added PWM backlight control. If you intend to use this, please make sure that control pin is either one of p21, p22, p23, p24, p25, or p26, as only they support hardware PWM. Please be aware that the mbed pins do not have much juice behind them, so if your display's backlight requires a lot of current, you are better off interfacing through as small signal transistor or a MOSFET. For the rest please consult the updated Doxygen documentation. NOTE The addition of PWM-controlled backlight will not break your existing code, the new options have default values, which initialize the used driver to behave as prior to PWM. Only if you want to use the new feature, some changes need to be made. The PWM is configured to be 120Hz (period of 8.33 milliseconds), in order to avoid noticeable flicker in the backlight. If in your opinion this value is too fine, then you can reduce the frequency in the LCD constructor in <lcd_base.cpp> by increasing the period value. My recommendation is to avoid frequencies lower than 60Hz.


  • Internal-only changes in the way drivers transmit colors - done to simplify the bitmap drawing routines; client API remains unchanged.


  • Added the driver for the ST7735 display controller.
  • Added the RGB18 color mode: choose between 16-bit (65K distinct colors) and 18-bit (262K distinct colors) color space [supported by all drivers]. NOTE This feature requires the image drawing functions to be changed, in order to account for differences between configured display color depth and the color depth of the image. Please review the API docs, in particular the new type bitmap_t and the DrawBitmap functions.
  • Changed display rotation to be achieved through the correspondent settings in the respective controller registers: no more software translation between width and height in different display orientations.
  • Extended the orientation options: PORTRAIT (top line to 12 o'clock/upright) and LANDSCAPE (top line to 9 o'clock) positions are the old options, PORTRAIT_REV (top line to 6 o'clock/upside-down) and LANDSCAPE_REV (top line to 3 o'clock) are the new orientations.


  • Finish implementing PWM-controlled backlight (current-sink configuration).
  • Add a driver for the HX8352-A controller (ITDB02-3.2WD 16:9 240x400 pixel resolution display).

How to Use

The code is documented, so please review the API docs. There is a simple example to get you started...

Mon Jul 22 01:48:06 2013 +0000
- fix sleep/wakeup of ILI9328 driver

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ttodorov 4:3ac4239f6c9c 1 /** \file ssd1289.h
ttodorov 0:881ff0b71102 2 * \brief mbed TFT LCD controller for displays with the SSD1289 IC.
ttodorov 0:881ff0b71102 3 * \copyright GNU Public License, v2. or later
ttodorov 0:881ff0b71102 4 *
ttodorov 0:881ff0b71102 5 * A known display with this type of controller chip is the ITDB02-3.2S
ttodorov 0:881ff0b71102 6 * from
ttodorov 0:881ff0b71102 7 *
ttodorov 0:881ff0b71102 8 * This library is based on the Arduino/chipKIT UTFT library by Henning
ttodorov 0:881ff0b71102 9 * Karlsen,
ttodorov 0:881ff0b71102 10 *
ttodorov 0:881ff0b71102 11 * Copyright (C)2010-2012 Henning Karlsen. All right reserved.
ttodorov 5:09b6d228ceea 12 *
ttodorov 0:881ff0b71102 13 * Copyright (C)2012 Todor Todorov.
ttodorov 0:881ff0b71102 14 *
ttodorov 0:881ff0b71102 15 * This library is free software; you can redistribute it and/or
ttodorov 0:881ff0b71102 16 * modify it under the terms of the GNU Lesser General Public
ttodorov 0:881ff0b71102 17 * License as published by the Free Software Foundation; either
ttodorov 0:881ff0b71102 18 * version 2.1 of the License, or (at your option) any later version.
ttodorov 0:881ff0b71102 19 *
ttodorov 0:881ff0b71102 20 * This library is distributed in the hope that it will be useful,
ttodorov 0:881ff0b71102 21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ttodorov 0:881ff0b71102 23 * Lesser General Public License for more details.
ttodorov 0:881ff0b71102 24 *
ttodorov 0:881ff0b71102 25 * You should have received a copy of the GNU Lesser General Public
ttodorov 0:881ff0b71102 26 * License along with this library; if not, write to:
ttodorov 0:881ff0b71102 27 *
ttodorov 0:881ff0b71102 28 * Free Software Foundation, Inc.
ttodorov 0:881ff0b71102 29 * 51 Franklin St, 5th Floor, Boston, MA 02110-1301, USA
ttodorov 0:881ff0b71102 30 *
ttodorov 0:881ff0b71102 31 *********************************************************************/
ttodorov 3:64a5b67d5b51 32 #ifndef TFTLCD_SSD1289_H
ttodorov 3:64a5b67d5b51 33 #define TFTLCD_SSD1289_H
ttodorov 0:881ff0b71102 34
ttodorov 0:881ff0b71102 35 #include "lcd_base.h"
ttodorov 0:881ff0b71102 36
ttodorov 6:059ca1648211 37 #ifdef __cplusplus
ttodorov 6:059ca1648211 38 extern "C" {
ttodorov 6:059ca1648211 39 #endif
ttodorov 6:059ca1648211 40
ttodorov 3:64a5b67d5b51 41 /** Represents a LCD instance.
ttodorov 3:64a5b67d5b51 42 *
ttodorov 3:64a5b67d5b51 43 * This is the utility class, through which the display can be manipulated
ttodorov 3:64a5b67d5b51 44 * and graphics objects can be shown to the user. A known display, which
ttodorov 3:64a5b67d5b51 45 * works with this library is the ITDB02-3.2S from iTeadStudio - a RGB TFT
ttodorov 3:64a5b67d5b51 46 * with 240x320 pixels resolution and 65K colors, using 16-bit interface.
ttodorov 3:64a5b67d5b51 47 *
ttodorov 4:3ac4239f6c9c 48 * The display needs 20 to 22 pins to work with mbed, so it is possibly not
ttodorov 3:64a5b67d5b51 49 * the best of choices out there, but other than that it uses +3.3V for
ttodorov 3:64a5b67d5b51 50 * power and logic, as well as the backlight, thus can be interfaced directly
ttodorov 3:64a5b67d5b51 51 * to the mbed without the need of shields or level shifters as with Arduino.
ttodorov 3:64a5b67d5b51 52 *
ttodorov 3:64a5b67d5b51 53 * How to use:
ttodorov 3:64a5b67d5b51 54 * \code
ttodorov 3:64a5b67d5b51 55 * // include the library, this will also pull in the header for the provided fonts
ttodorov 3:64a5b67d5b51 56 * #include "ssd1289.h"
ttodorov 3:64a5b67d5b51 57 *
ttodorov 3:64a5b67d5b51 58 * // prepare the data bus for writing commands and pixel data
ttodorov 3:64a5b67d5b51 59 * BusOut dataBus( p30, p29, p28, p27, p26, p25, p24, p23, p22, p21, p20, p19, p18, p17, p16, p15 ); // 16 pins
ttodorov 3:64a5b67d5b51 60 * // create the lcd instance
ttodorov 4:3ac4239f6c9c 61 * SSD1289_LCD lcd( p14, p13, p12, p11, &dataBus ); // control pins and data bus
ttodorov 3:64a5b67d5b51 62 *
ttodorov 3:64a5b67d5b51 63 * int main()
ttodorov 3:64a5b67d5b51 64 * {
ttodorov 3:64a5b67d5b51 65 * // initialize display - place it in standard portrait mode and set background to black and
ttodorov 3:64a5b67d5b51 66 * // foreground to white color.
ttodorov 3:64a5b67d5b51 67 * lcd.Initialize();
ttodorov 3:64a5b67d5b51 68 * // set current font to the smallest 8x12 pixels font.
ttodorov 3:64a5b67d5b51 69 * lcd.SetFont( Font8x12 );
ttodorov 3:64a5b67d5b51 70 * // print something on the screen
ttodorov 3:64a5b67d5b51 71 * lcd.Print( "Hello, World!", CENTER, 25 ); // align text to center horizontally and use starndard colors
ttodorov 3:64a5b67d5b51 72 *
ttodorov 3:64a5b67d5b51 73 * while ( 1 ) { }
ttodorov 3:64a5b67d5b51 74 * }
ttodorov 3:64a5b67d5b51 75 *
ttodorov 3:64a5b67d5b51 76 * \endcode
ttodorov 3:64a5b67d5b51 77 * \version 0.1
ttodorov 3:64a5b67d5b51 78 * \author Todor Todorov
ttodorov 3:64a5b67d5b51 79 */
ttodorov 4:3ac4239f6c9c 80 class SSD1289_LCD : public LCD
ttodorov 0:881ff0b71102 81 {
ttodorov 0:881ff0b71102 82 public:
ttodorov 0:881ff0b71102 83 /** Creates a new instance of the class.
ttodorov 0:881ff0b71102 84 *
ttodorov 0:881ff0b71102 85 * \param CS Pin for the ChipSelect signal.
ttodorov 0:881ff0b71102 86 * \param RESET Pin for the RESET line.
ttodorov 0:881ff0b71102 87 * \param RS Pin for the RS signal.
ttodorov 0:881ff0b71102 88 * \param WR Pin for the WR signal.
ttodorov 0:881ff0b71102 89 * \param DATA_PORT Address of the data bus for transfer of commands and pixel data.
ttodorov 4:3ac4239f6c9c 90 * \param BL Pin for controlling the backlight. By default not used.
ttodorov 0:881ff0b71102 91 * \param RD Pin for the RD signal. This line is not needed by the driver, so if you would like to
ttodorov 0:881ff0b71102 92 * use the pin on the mbed for something else, just pull-up the respective pin on the LCD high,
ttodorov 0:881ff0b71102 93 * and do not assign a value to this parameter when creating the controller instance.
ttodorov 22:4c169297f374 94 * \param blType The backlight type, the default is to utilize the pin - if supplied - as a simple on/off switch
ttodorov 22:4c169297f374 95 * \param defaultBacklightLevel If using PWM to control backlight, this would be the default brightness in percent after LCD initialization.
ttodorov 0:881ff0b71102 96 */
ttodorov 22:4c169297f374 97 SSD1289_LCD( PinName CS, PinName RESET, PinName RS, PinName WR, BusOut* DATA_PORT, PinName BL = NC, PinName RD = NC, backlight_t blType = Constant, float defaultBackLightLevel = 1.0 );
ttodorov 0:881ff0b71102 98
ttodorov 0:881ff0b71102 99 /** Initialize display.
ttodorov 0:881ff0b71102 100 *
ttodorov 0:881ff0b71102 101 * Wakes up the display from sleep, initializes power parameters.
ttodorov 0:881ff0b71102 102 * This function must be called first, befor any painting on the
ttodorov 0:881ff0b71102 103 * display is done, otherwise the positioning of graphical elements
ttodorov 0:881ff0b71102 104 * will not work properly and any paynt operation will not be visible
ttodorov 0:881ff0b71102 105 * or produce garbage.
ttodorov 0:881ff0b71102 106 *
ttodorov 0:881ff0b71102 107 * \param oritentation The display orientation, landscape is default.
ttodorov 12:d0978272a340 108 * \param colors The correct color depth to use for the pixel data. Value is disregarded.
ttodorov 0:881ff0b71102 109 */
ttodorov 12:d0978272a340 110 virtual void Initialize( orientation_t orientation = LANDSCAPE, colordepth_t colors = RGB16 );
ttodorov 0:881ff0b71102 111
ttodorov 4:3ac4239f6c9c 112 /** Puts the display to sleep.
ttodorov 4:3ac4239f6c9c 113 *
ttodorov 4:3ac4239f6c9c 114 * When the display is in sleep mode, its power consumption is
ttodorov 4:3ac4239f6c9c 115 * minimized. Before new pixel data can be written to the display
ttodorov 4:3ac4239f6c9c 116 * memory, the controller needs to be brought out of sleep mode.
ttodorov 4:3ac4239f6c9c 117 * \sa #WakeUp( void );
ttodorov 4:3ac4239f6c9c 118 * \remarks The result of this operation might not be exactly as
ttodorov 4:3ac4239f6c9c 119 * expected. Putting the display to sleep will cause the
ttodorov 4:3ac4239f6c9c 120 * controller to switch to the standard color of the LCD,
ttodorov 4:3ac4239f6c9c 121 * so depending on whether the display is normally white,
ttodorov 4:3ac4239f6c9c 122 * or normally dark, the screen might or might not go
ttodorov 4:3ac4239f6c9c 123 * dark. Additional power saving can be achieved, if
ttodorov 4:3ac4239f6c9c 124 * the backlight of the used display is not hardwired on
ttodorov 4:3ac4239f6c9c 125 * the PCB and can be controlled via the BL pin.
ttodorov 4:3ac4239f6c9c 126 */
ttodorov 4:3ac4239f6c9c 127 virtual void Sleep( void );
ttodorov 4:3ac4239f6c9c 128
ttodorov 4:3ac4239f6c9c 129 /** Wakes up the display from sleep mode.
ttodorov 4:3ac4239f6c9c 130 *
ttodorov 4:3ac4239f6c9c 131 * This function needs to be called before any other, when the
ttodorov 4:3ac4239f6c9c 132 * display has been put into sleep mode by a previois call to
ttodorov 4:3ac4239f6c9c 133 * #Sleep( void ).
ttodorov 4:3ac4239f6c9c 134 */
ttodorov 4:3ac4239f6c9c 135 virtual void WakeUp( void );
ttodorov 4:3ac4239f6c9c 136
ttodorov 0:881ff0b71102 137 protected:
ttodorov 4:3ac4239f6c9c 138 /** Sends a command to the display.
ttodorov 4:3ac4239f6c9c 139 *
ttodorov 4:3ac4239f6c9c 140 * \param cmd The display command.
ttodorov 4:3ac4239f6c9c 141 * \remarks Commands are controller-specific and this function needs to
ttodorov 4:3ac4239f6c9c 142 * be implemented separately for each available controller.
ttodorov 4:3ac4239f6c9c 143 */
ttodorov 2:81ed304b7e9b 144 virtual void WriteCmd( unsigned short cmd );
ttodorov 4:3ac4239f6c9c 145
ttodorov 4:3ac4239f6c9c 146 /** Sends pixel data to the display.
ttodorov 4:3ac4239f6c9c 147 *
ttodorov 4:3ac4239f6c9c 148 * \param data The display data.
ttodorov 24:ac6e35658037 149 * \remarks Sending data is controller-specific and this function needs to
ttodorov 4:3ac4239f6c9c 150 * be implemented separately for each available controller.
ttodorov 4:3ac4239f6c9c 151 */
ttodorov 2:81ed304b7e9b 152 virtual void WriteData( unsigned short data );
ttodorov 4:3ac4239f6c9c 153
ttodorov 4:3ac4239f6c9c 154 /** Assigns a chunk of the display memory to receive data.
ttodorov 4:3ac4239f6c9c 155 *
ttodorov 4:3ac4239f6c9c 156 * When data is sent to the display after this function completes, the opertion will
ttodorov 4:3ac4239f6c9c 157 * start from the begining of the assigned address (pixel position) and the pointer
ttodorov 4:3ac4239f6c9c 158 * will be automatically incremented so that the next data write operation will continue
ttodorov 4:3ac4239f6c9c 159 * with the next pixel from the memory block. If more data is written than available
ttodorov 4:3ac4239f6c9c 160 * pixels, at the end of the block the pointer will jump back to its beginning and
ttodorov 4:3ac4239f6c9c 161 * commence again, until the next address change command is sent to the display.
ttodorov 4:3ac4239f6c9c 162 *
ttodorov 4:3ac4239f6c9c 163 * \param x1 The X coordinate of the pixel at the beginning of the block.
ttodorov 4:3ac4239f6c9c 164 * \param y1 The Y coordinate of the pixel at the beginning of the block.
ttodorov 4:3ac4239f6c9c 165 * \param x2 The X coordinate of the pixel at the end of the block.
ttodorov 4:3ac4239f6c9c 166 * \param y2 The Y coordinate of the pixel at the end of the block.
ttodorov 4:3ac4239f6c9c 167 * \remarks Addressing commands are controller-specific and this function needs to be
ttodorov 4:3ac4239f6c9c 168 * implemented separately for each available controller.
ttodorov 4:3ac4239f6c9c 169 */
ttodorov 20:4bdca8d8dadc 170 virtual void SetXY( unsigned short x1, unsigned short y1, unsigned short x2, unsigned short y2 );
ttodorov 0:881ff0b71102 171
ttodorov 10:69571adcfad5 172 /** Sets the color of the pixel at the address pointer of the controller.
ttodorov 10:69571adcfad5 173 *
ttodorov 10:69571adcfad5 174 * This function is to be provided by each implementation separately in
ttodorov 10:69571adcfad5 175 * order to account for different color depth used by the controller.
ttodorov 10:69571adcfad5 176 * \param color The color of the pixel.
ttodorov 20:4bdca8d8dadc 177 * \param mode The depth (palette) of the color.
ttodorov 10:69571adcfad5 178 */
ttodorov 20:4bdca8d8dadc 179 virtual void SetPixelColor( unsigned int color, colordepth_t mode = RGB24 );
ttodorov 10:69571adcfad5 180
ttodorov 0:881ff0b71102 181 private:
ttodorov 4:3ac4239f6c9c 182 DigitalOut _lcd_pin_wr;
ttodorov 4:3ac4239f6c9c 183 BusOut* _lcd_port;
ttodorov 4:3ac4239f6c9c 184 DigitalOut* _lcd_pin_bl;
ttodorov 0:881ff0b71102 185 DigitalOut* _lcd_pin_rd;
ttodorov 0:881ff0b71102 186 };
ttodorov 0:881ff0b71102 187
ttodorov 6:059ca1648211 188 #ifdef __cplusplus
ttodorov 6:059ca1648211 189 }
ttodorov 6:059ca1648211 190 #endif
ttodorov 6:059ca1648211 191
ttodorov 3:64a5b67d5b51 192 #endif /* TFTLCD_SSD1289_H */