RA8875: 4" to 8" (WQVGA, WVGA, Multi-Touch, Keypad)

4-Wire SPI interface to a TFT Display with some HW acceleration, and other options: capacitive or resistive touch, keypad, more...

Hello World

Import programRA8875_Demo

Simple demo for the Raio RA8875 Based Display with a 4-wire SPI interface.

Library

Import libraryRA8875

Library to control a Graphics TFT connected to 4-wire SPI - revised for the Raio RA8875 Display Controller.

Datasheet

http://www.buydisplay.com/download/ic/RA8875.pdf

Notes

RA8875 Based Display

This component is an inexpensive display module, and with a lot of options; different sizes, with and without touch, support for external font chips, scanning keypad, various micro interface types, and more.
WiredHome - As the author of this library, let me say that I am not affiliated with BuyDisplay.com, simply a satisfied user.

/media/uploads/WiredHome/r8875_buydisplayimage_clip.jpg

Supported Chips

  • RA8875 Display Controller - there are variants of this that have not been tested (e.g. RA8876).
  • FT5206 Capacitive Touch Controller - found on many of the RA8875-based displays.
  • GSL1680 Capacitive Touch Controller - found on some RA8875-based displays..

Library Features

  • Support for 480x272x16-bit color, and up to 800x480x16,
  • Simple 4-wire SPI interface (Hardware Reset signal is not necessary),
    It supports other interface options for which this library currently has no support.
  • 2-drawing layers (in 480x272x8/16 mode and 800x480x8) which permits several operations (transparency and more),
  • Hardware font support (in multiple sizes),
  • Software font support (import your own fonts),
  • Many drawing commands (Line, Circle, Rectangle, Triangle, with Filled option),
  • Touch-Screen support (Resistive and Capacitive using FT5206 Controller),
  • Capacitive Touch-Screen supports up to 5 fingers (FT5206) or 10 fingers (GSL1680) and limited gestures (new in library v125),
  • Keypad support (4 x 5 matrix of physical keys),
  • Render BMP, JPG, and ICO files to the screen (PNG requires too much memory to decompress),
  • PrintScreen API to create a BMP file of the current screen image,
  • Backlight brightness control,
  • and much more...

The supporting library is for a display using an RA8875 Display Controller chip. The referenced web site Buy Display has several different displays, many of which are based on the RA8875 Display Controller - and therefore should be compatible with this library. More details are shown in the "Compatibility" section.

The driver has a "PrintScreen" function,
which extracts the current image
and saves it as a BMP file. Here is a sample
from a network appliance using this display.

This sample shows:
an NTP-sync'd clock,
a shared family calendar,
the current weather conditions,
and a real-time energy meter.
/media/uploads/WiredHome/couchcalendarexample.png

SDO Defect

CAUTION: There is an undocumented defect in the RA8875 controller. The defect is that the controller does not always release its SPI data output pin when the chip is deselected.

Information is a bit vague, and mostly from users having discovered this. It may be that SDO continues controlling that pin while an operation is in process, but this is not entirely clear what releases it back into tri-state. This creates a severe problem if you use that same SPI interface on your host to communicate to another devices (e.g. the micro SD interface).

The communications to the 2nd device will fail because of the RA8875 behavior. Best advice, keep those interfaces on separate SPI ports. Several users have added an external tristate buffer, gated by the chip select pin.

If you find any more specific detail about the RA8875 errata, please contact the author of this library to update this page.

Compatibility

Display Compatibility

"Buy-Display" has several displays that have the RA8875. This library currently has a default setting of 480 x 272 definition in it, but it is designed to support the 800 x 480 display as well.

DisplaySizeResolutionPowerTouch(1)
ER-TFTM043A2-3-41704.3"WQVGA480x272x16230 mA (3.3v), 180 mA (5.0v)Cap
ER-TFTM043-34.3"WQVGA480x272x16230 mA (3.3v), 180 mA (5.0v)Res/Cap
ER-TFTM050-25"WVGA480x272x16230 mA (3.3v), 180 mA (5.0v)Res/Cap
ER-TFTM050-35"WVGA800x480x16(2)480 mA (3.3v)Res/Cap (3)
ER-TFTM070-57"WVGA800x480x16(2)480 mA (3.3v), 300 mA (5.0v)Res/Cap
ER-TFTM080-28"WVGA800x480x16(2)950 mA (3.3v), 600 mA (5.0v)Res
ER-TFTM090-29"WVGA800x480x16(2)930 mA (3.3v), 580 mA (5.0v)Res

(1) Indicates that this unit has options for no touch, resistive touch, or capacitive touch. See the detailed notes about touch screen further below.
(2) To access the 800x480 mode, at a minimum, the init() function call in your code should be revised to init(800,480). You should not need to modify the library.
(3) Newer versions of this model have a different Cap sense touch controller (GSL1680), for which support was added (in library version 171).

mbed Platform Compatibility

This library uses a basic 4-wire SPI interface, so should work on most/all platforms that support SPI. That said, platforms listed below are those where users have confirmed it operating properly.

mbed ModuleCompatibleNotes
LPC1768 PlatformYesThe platform on which the original and most ongoing development was based.
Seeeduino Arch ProYesNotes in Question 54047, Capacitive touch, ER3304-1 font chip
Teensy3.1Yestested by another user
FRDM-K22FYestested by another user
FRDM-K64FYestested by another user
other?If you have used this with other modules, please contact the author or update this page.

4-Wire SPI

This library uses the 4-wire SPI interface, however the RA8875 controller chip, and the referenced display module support I2C, 3-Wire SPI, 4-Wire SPI, 8-bit Parallel and 16-bit Parallel. The RA8875 has on-board RAM sufficient for most needs, and it includes some fonts built-in. It supports an external serial flash for additional fonts (including UNICODE) and graphics, and has a micro SD interface, also for graphics. The RA8875 has integrated support for backlight control, resistive touch screen, and a matrix keypad. These options can simplify the system design.

Display Pictures

BMP and JPG formats are supported. There are "variants" of each, so possibly not all variants will render. But it has been tested for BMP with monochrome, 4-bit, 8-bit, and 24-bit color.

Import programPUB_RA8875_Bitmap

Demonstration of the Bitmap rendering - reads BMP and JPG files in many format variants and renders to the screen.

And a small collection of test-images.

/media/uploads/WiredHome/testimages.zip

Hardware Settings

With careful study of the image below, you can see a number of solder-blob jumpers. These jumpers are described quite well in the manual, and configure the many different options. The specific unit shown here is the "entry point" model, it does not have touchscreen, SD card, extra font memory, or the key pad interface. As you see in the top left, it is wired with an 8-signal ribbon cable (but note in the schematic that it only needs 6 as the two power and two ground are internally connected together in the module). The display can be powered from 5v or 3.3v; 5v as shown on this page.

/media/uploads/WiredHome/ra8875displaymodulerr.jpg

Also note, that some configuration changes go beyond the jumpers. I decided to switch my as-purchased configuration to 4-Wire SPI and had to apply some changes (e.g. solder-blob jumpers). Had I ordered the display with the support for 4-Wire SPI, that would not have been necessary. The buydisplay web site makes the option selection quite easy.

Schematic

CAUTION: Be sure to review the troubleshooting section.

The library should be able to work with any SPI port, and the Chip Select is a simple DigitalOut pin, shown here from the unallocated pins on this baseboard. The library also permits a definition for a reset pin, but in the initial work, this was unnecessary as a display reset function is easily activated via the SPI interface.

Schematic for the display module - I have not found a schematic for the display module itself, and by working through the various datasheets, it has not been necessary. For educational reasons, I wish I did have that to study.

Example for 4 inch Display

/media/uploads/WiredHome/ra8875_display_schematic.png

Example for 7 inch Display with Capacitive Touch

/media/uploads/WiredHome/ra8875_captouch_wiring.png

NOTE In this second example, the display power requirements can be well over 300 mA. When combined with an LPC1768 (which can consume up to 200 mA), it can exceed the capacity of most USB ports. I have found that if you keep the brightness setting quite low, your PC source may adequately support this. If you don't init( ) it with a low brightness level, you may see a blank white (or black) screen and try to troubleshoot the wrong issue.

Very Simple Example

/media/uploads/WiredHome/ra8875display.640x380.png

Here is a full program that uses this library. As you can see, it is very simple to use. Be sure to have the mbed and the RA8875 libraries in your project.

#include "mbed.h"
#include "RA8875.h"
RA8875 lcd(p5, p6, p7, p12, NC, "tft");

int main()
{
    lcd.init();      // defaults to 480x272. use parameters for 800x480
    lcd.printf("printing 3 x 2 = %d", 3*2);
    lcd.circle(       400,25,  25,               BrightRed);
    lcd.fillcircle(   400,25,  15,               RGB(128,255,128));
    lcd.ellipse(      440,75,  35,20,            BrightBlue);
    lcd.fillellipse(  440,75,  25,10,            Blue);
    lcd.triangle(     440,100, 475,110, 450,125, Magenta);
    lcd.filltriangle( 445,105, 467,111, 452,120, Cyan);
    lcd.rect(         400,130, 475,155,          Brown);
    lcd.fillrect(     405,135, 470,150,          Pink);
    lcd.roundrect(    410,160, 475,190, 10,8,    Yellow);
    lcd.fillroundrect(415,165, 470,185,  5,3,    Orange);
    lcd.line(         430,200, 460,230,          RGB(0,255,0));
    for (int i=0; i<=30; i+=5) 
        lcd.pixel(435+i,200+i, White);
}

Performance

"How fast is it?" is a valid question, and one I sought to answer.

This information is based on 4-wire SPI, where the answer is, "it depends". The driver is configured for 5 MHz by default, and the chip can support a faster clock rate. But be forewarned, this interface is not suitable for streaming video. That said, the RA8875 has a number of hardware accelerator features built-in - to draw text (using the internal fonts or optional external fonts), lines, circles, rectangles, triangles - all filled or unfilled. And it does this very fast. Because it supports these in the hardware, this can greatly reduce the memory footprint in the host micro. For displayable "information", the performance of this part is most likely more than good enough.

If your interest is in "picture" presentation (like an electronic photo frame), here is data from not very scientific tests.

Starting with a 24-bit color picture, scaled to about 350 pixels wide by 272 tall, and saved as a 24-bit BMP file of about 382KB. The driver library parses the 24-bit data, down-scales it to 16-bit, and streams it to the RA8875 and therefore to the screen. Keeping in mind that the LPC1768 has less than 32KB of usable memory, the driver buffers only a single scanline as it does this processing.

MeasurementImage LocationRendering Method
34 seclocalfilesystempure software pixel by pixel
9 seclocalfilesystemleveraged hardware enhancement in RA8875
3 secrandomly selected USB stickleveraged hardware enhancement in RA8875
2.5 secrandomly selected uSD cardusing same SPI port and SDFileSystem (1)
0.25 secFlashFileSystemsame image placed in flash file system (2)(3)

(1) SDFileSystem v22 from https://developer.mbed.org/users/neilt6/code/SDFileSystem/ [On my hardware, I could only set the FileSystem to 17 MHz, and the RA8875 is set for the default of 5 MHz.

(2) FlashFileSystem from Andy Green, if you have the flash space, is a great, and very high performance, way to save "read-only" resources, like images, icons, and other resources.

(3) ROFS - Read Only File System builder. Andy Green provides source code for a simple utility (fsbld - file system builder). I started with his code and enhanced it significantly. On my Windows PC, this version is ~ 10 x faster and is bidirectional - which can be handy in some rare circumstances. This version also generates more internal documentation in the .h file. After downloading, remove the trailing .bin and then you can open the zip. Run it from the command line w/o any parameters for instructions.

Before adding the FlashFileSystem driver, I had questions -

  • How much of the 3 seconds is the file system? (there's a lot going on there to open, read, and seek)
    • Answer: Most of it, as you can see by the update above showing the FlashFileSystem.
  • How much is inefficient software? (There may remain potential optimizations)
  • How much is the SPI frequency? (and the limits of the display hardware)
  • How much is the USB interface? (the software driving that interface, and the randomly selected drive)
  • How much is attributed to the BMP file format (which is stored upside down, causing heavy processing)

Here is another not very scientific analysis:

  • 350 px x 272 px x 16 bpp => 1.5 M bits delivered to the display
  • At 2 MHz SPI, a 2 M bit transfer would take 1 second.
  • This suggests that 2 of the 3 seconds is "overhead" in software, and additional optimization may be helpful.

Future Considerations

Burst SPI is another library on the site that may provide a significant performance boost. This has not been investigated, but note that while this RA8875 library mostly writes to the display, it also reads from the display. The Burst SPI library does not currently support reading. With some careful work it should be possible to integrate this performance enhancement.

Keypad

The RA8875 has built-in support for a 4 x 5 matrix keypad. The library was updated to provide support for that interface. This has not been tested to any strong degree.

Import programPUB_RA8875_Keypad

Demo of the RA8875 Keypad to enter a username and password.

Touch Screen

Example Program for either Resistive or Capacitive touch.

NOTE: New in driver library 125 the support for the capacitive touch screen is integrated.

Import programPUB_RA8875_Touch

A Touchscreen example program showing the RA8875 driver library. This is easily configured for either the Resistive touch panel or the Capacitive touch panel.

Resistive Touch Screen

The RA8875 has built-in support for a 4-wire resistive touch screen. This library was updated to support that interface, including methods for calibration.

Capacitive Touch Screen

Several of the RA8875 compatible displays on the buydisplay web site have capacitive touch as an alternative to a resistive touch screen.

Those using the FT5206 capacitive touch controller supports tracking from one to five fingers simultaneously.
Those using the GSL1680 capacitive touch controller will find two options, one supporting five fingers and the other supporting ten fingers simultaneously. Note that documentation for the GSL1680 is "limited", and the controller is a micro. The micro is booted from a binary image hosted by the RA8875 library, for which no source has been found.

Capacitive touch has numerous advantages, typically a "cleaner" and brighter looking display among them as there are fewer front-side layers. Take care if you choose one of those displays - since the RA8875 _does not_ have native support for this technology, the display module adds another chip set to it. This in itself is no problem, but this additional chip requires another interface to the mbed - that being I2C. Be sure your hardware design can support giving up 4 more pins!

Another major advantage is that a capacitive display requires a simple touch, where a resistive display requires sufficient "pressure" to be applied to close the contacts.

Fonts

As noted above, the RA8875 has some fonts built-in to the chip. And with basic scaling of 1x or 2x, it may serve most of your basic needs.

When you need to go past the built-in font support, there are two options.

Soft Fonts

Additionally, with soft fonts, using the GLCD font tool, you can create your own fonts quite easily. A December 2015 update to this library more directly supports the GLCD fonts. See the Soft Fonts Instructions page for a step-by-step tutorial. Take note that this update is not backward compatible with the prior font support, but it requires less memory, and the time to create the soft fonts is reduced.

<< http://developer.mbed.org/users/WiredHome/code/PUB_RA8875_SoftFonts/ >>

External Font Chip

Another developer implemented support for the external font chip which you can purchase with this display (the driver software does not provide support at this time). See that work at External Font Chip

microSD Card Interface

The display modules have an optional micro SD Card Interface. This is not wired into the display controller, but is made available on another connector, which you would then wire to the mbed. Thus, there is no support in the display driver library for this - instead find an mbed library that supports SD Cards.

Please take note of the cautionary statement regarding the sharing of the RA8875 SDO with any other SPI device.

Power Considerations

Take note that some of these displays require significant power. Some of the mbed modules have an onboard regulator, and that power is provided on one of the available interface pins. In general, you should not try to power the display from the mbed regulator, as the display may require more than is available from the mbed. In some cases, it may appear to work, but it may also lead to power dips, and instability of the software on the mbed. If you have a USB wall adapter that is a higher power module, the 5v from it, coupled with a 5v display (or an additional 3.3v regulator) may be a good configuration. The mbed modules themselves can run from this same power source.

Recommendation: Choose a 5v display module after ensuring that your mbed module has 5v tolerant IO pins (the LPC1768 does, the others have not been evaluated). Use a high power USB power adapter, and run both the display and the mbed from that power supply.

Trouble Shooting

Power Source & the FT5205 Touch Controller

CAUTION If you don't wire power correctly, you may destroy the display's touch controller. In the author's experience, the display remains functional, but touch becomes non-functional. The I2C controller is no longer detected by the host micro.

The following series of figures is intended to show what's happening.

https://os.mbed.com/media/uploads/WiredHome/ft5206power.png

mbed library version

OSv2

Most of the development, and ongoing use of this library (by the library author), is based on mbed os v2. Unfortunately, some of the newer versions have "decayed", so most applications use OS 2 version 127 or 128. With newer versions of OS 2, and when using a multi file system (sdCard and USB) it is difficult to get it to work, and with even newer versions the display will not properly initialize - suspecting it is related to the SPI driver. That said, it has been proven to work with several newer versions of the OS 2 library.

OSv5

The author has run some of the demo's with OS version 5.10 quite successfully. There are some API changes in the RA8875 Library that accommodate the newer OS version. Some of those are configured in the library against a specific minor version change in OSv5, and not all minor version changes have been tested. What this means is that in some of the v5.x versions, it might fail to compile properly, and in the newer 5.x versions it will. Contact the author if you have trouble with a specific combination.

OS Version Adaptation

If you detect a specific version incompatibility and cannot change to a newer (or older) OS version that works, look at the source for this library. Here's an example of this adaptation:

MBED OS Version adaptations

    #if MBED_VERSION >= MBED_ENCODE_VERSION(5,8,0)
    eventThread.start(callback(&queue, &EventQueue::dispatch_forever));
    m_irq->fall(queue.event(callback(this, &RA8875::TouchPanelISR)));
    #elif (MBED_MAJOR_VERSION >= 5) || (MBED_LIBRARY_VERSION > 128)   // Is this the right version?
    m_irq->fall(callback(this, &RA8875::TouchPanelISR));
    #else
    m_irq->fall(this, &RA8875::TouchPanelISR);
    #endif

If you can apply a change that improves the compatibility, please communicate that change so the library can be improved.

Power

Powering an mbed and the 4" display from an under-powered USB port is one of the first things to check. The default init() function turns the backlight to the max, which may be more than your port can provide. And if you have the larger displays, they will take even more power. In the example below, try reducing the backlight value (its permissible range is 0 to 255) to something quite low - perhaps 20 or 40.

  // default init constructor
  RetCode_t init(int width = 480, int height = 272, int color_bpp = 16, 
      uint8_t poweron = 255, bool keypadon = true, bool touchscreeenon = true);

  // common implementation in main.cpp
  lcd.init();

  // simple adjustment to reduce power
  lcd.init(480,272,16,128);  // configure for small lcd, at 50% backlight

  // alternate init for a large screen version
  //  lcd.init(800,480,16,128);

Pin-out

Aside from power and ground being miswired, the next most common is properly wiring the SPI port. Several users had MISO and MOSI swapped. Others didn't correctly wire the chip select pin. Double, even triple-check these signals.

Other RA8875-based Display Modules

One user acquired a display module from another source. It had the RA8875 controller, and it was wired for 4-wire SPI. And yet it did not work with this library. We exchanged quite a few emails in an attempt to solve this compatibility issue. I had compared the source in the other library but it was so dramatically different that it was a challenging effort. The user found another library that met their needs. This went unsolved. If others find themselves in a similar situation, I am more than willing to collaborate.

Examples

Soft Fonts

A simple demo of the soft font presentation. The fonts were generated from an open source TTF file, and with just a few lines of code this is produced.

Soft Font

Import programRA8875_Demo

Simple demo for the Raio RA8875 Based Display with a 4-wire SPI interface.

Game of Life

A simple simulation of the game of life on the display. This was put together before the touchscreen support was added - that might be an interesting update.

Game of Life

Import programGameOfLife

Conway's game of life applied to the mbed and an RA8875 LCD.

Touch Colors

This is more of a demo program that shows 3 bars (one each for Red, Green, and Blue). As you touch on the color bars, it creates a composite RGB value and shows that color to you. With a "Screen Capture" option, you can extract the image to a BMP on the local file system, and then compare the colors on your display with the actual values.

Touch

Import programPUB_RA8875_TouchColors

An example program using the RA8875 Display controller with the touch-screen option.

mPaint

This too is more of a demo program, and exploits the touch screen support recently added.

mPaint

Import programPUB_RA8875_mPaint

mbed Paint for the RA8875 display with based touch screen.

mandelbrot

One more demo, shows graphics, touch, touch-hold application. Derived from the work of Bob Stone and ported to this display.

mandelbrot

Import programPUB_RA8875_Mandelbrot

Example drawing mandelbrot on the RA8875 with touch to zoom in or out. Touch and hold > 4s to zoom out, touch to zoom in.