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/default/4-3-tft-lcd-display-module-controller-board-w-serial-spi-i2c-mcu.html

Notes

RA8875 Based Display

This component is an inexpensive display module, and with a lot of options.
[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

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),
  • Capacitive Touch-Screen supports up to 5 fingers and limited gestures (new in library v125),
  • Keypad (4 x 5 keys) support,
  • 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 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

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 scale up to support the 800 x 480 display.

DisplaySizeResolutionPowerTouch(1)
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
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.

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 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 onboard RAM sufficient for most needs, and it includes some fonts built-in. It supports an external serial flash for additonal fonts (including UNICODE) and graphics, and has an SD interface, also for graphics. The RA8875 even supports onboard backlight control, touch screen, and a 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. And likewise some testing with JPG.

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

For a more "Data-centric" display

Given the API set, something a little more data-centric was the primary target.

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

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 configuration to 4-Wire SPI and had to remove R1, R2, and R3 (as well as changing some of the solder-blob jumpers). Had I ordered the display with the support for 4-Wire SPI, that would not have been necessary.

Schematic

The library should be able to work with any SPI port, and the Chip Select is a simple DigitalOut pin, shown here from the unused 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.

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 over 300 mA. If you do not set it to full brightness, your PC source should adequately support this.

Very Simple Example

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)

(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.

So, from here, there remain questions -

  • How much of the 3 seconds is the file system? (there's a lot going on there to open, read, and seek)
    • 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)
  • 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. The capacitive touch supports tracking from one to five fingers simultaneously.

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!

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 his 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 the libraries that support the SD Cards.

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 module.

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

mbed library version

Most of the development, and ongoing use of this library, used mbed os v2. Unfortunately, I have found that newer versions have "decayed", so most commonly I use version 127 or 128. When I use newer versions than that, I find that my use of a multi file system (sdCard and USB) won't work, and with even newer versions the display will not properly initialize - suspecting it is related to the SPI driver.

If you can, roll back to an earlier version of the mbed library.

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.

Power

Powering an mbed and the 4" display from an underpowered 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.

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

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

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.


Please log in to start a discussion or ask a question.

Questions

See more related questions