Summary

Seeed Studio and 52pi got together and announced 2 touch-capable LCDs in May 2016. The first is a 5" display, the other is a 7" display. I purchased one of the 5" models, and have now figured out how to access it from Linux on my BeagleBone.

Features

The 5" display has 800x480 resolution, 5 buttons (left, right, up, down, enter) and as a bonus is a touch screen. When I first hooked it up to my BeagleBone Green Wireless and booted, it showed me the console with a typical login prompt. Hooking up a keyboard to the BeagleBone's USB port, I could login as if it was a normal desktop computer.

Display

I wanted to access the LCD as a graphics device, not just as a text console. I'm certain there are multiple ways to do this, but I discovered I could do what I needed by accessing the frame buffer in /dev/. The simple explanation is to open up /dev/fb0, perform some ioctl(2) calls, memory map /dev/fb0, then write some bytes to indicate various shades of red, green, or blue. Repeat this 800x480 times, and you get an entire screen of colourful pixels.

The LCD uses 16 bits of colour for every pixel. This means RED, GREEN, and BLUE must all fit in 16 bits. Through trial-and-error, I finally figured out the high 5 bits are for red, the middle 6 bits are for green, and the low 5 bits are for blue. So if you have a 24-bit image, with 8 bits for each channel, you have to discard the lower 2 bits of green, and the lower 3 bits of both red & blue. Then pack all 3 colour values into a uint16_t.

R = 0b1111100000000000
G = 0b0000011111100000
B = 0b0000000000011111
    ------------------
    0bRRRRRGGGGGGBBBBB

In summary:

• call int fb = open( "/dev/fb0", O_RDWR ) to get a file descriptor to the frame buffer
• optionally call ioctl( fb, FBIOGET_VSCREENINFO, &vinfo ) to get variable settings on the frame buffer (needed to get the screen resolution and the bytes needed when calling mmap())
• optionally call ioctl( fb, FBIOGET_FSCREENINFO, &finfo ) to get fixed settings on the frame buffer
• call mmap( nullptr, fb_ptr_len, PROT_READ | PROT_WRITE, MAP_SHARED, fb, 0 ) to obtain a memory pointer to the mapped area
• determine what and where you want to draw, and calculate the offset (each screen pixel is 2 bytes)
• pack each colour pixels into 16 bits as described above
• write the 16 bits of each colour pixel to the memory area returned by the call to mmap(2)
• once done writing the pixels, call msync(2)
• when done with the frame buffer, call munmap(2) and close(2)

As a quick example, this is how you'd clear the entire screen:

From a command prompt the screen can be drawn and then cleared with the following commands:

Touch Screen

The touch screen provides the following information:

1. the X coordinate
2. the Y coordinate
3. the pressure
4. key press down (finger touches the screen)
5. key press up (finger no longer touches the screen)

Some details on Linux's input events is available from event-codes.txt.

Ignoring error checks, this is how to initialize reading the touch screen information:

The three ioctl() calls are mostly to obtain the minimum and maximum ranges. The X and Y coordinates returned by the touch screen do NOT correspond to pixels, so you'll have to convert them to make meaningful sense.

For example, if the X range is 0-4095, then a value of 2048 will be 50% of the screen, or 400 pixels on the 800-pixel wide 5" LCD.

Once you've opened the event file and know the ranges, then you start a loop to read from fd:

The event structure in linux/input.h is very simple. There are 4 fields to each event: a timestamp, a type, a code, and a value. The events I found of particular interest were EV_KEY and EV_ABS.

EV_KEY is generated when a finger first hits the touch screen, and again when the finger is removed from the touch screen. It acts as if a button was pushed. The code field should be BTN_TOUCH, and a value of 0 indicates the "button up" event, while a value of 1 indicates the "button down" event.

EV_ABS indicates an absolute value. (Versus EV_REL which is a relative move event generated by a mouse.) The code field is set to ABS_X, ABS_Y, or ABS_PRESSURE. The value field is the actual location or pressure.

Note there is a single value field. This means when a EV_KEY event is sent with a value indicating if it was "push up" or "push down" event, there is no room left in the event to indicate the X and Y coordinates. So you'll need to combine the ABS_X and ABS_Y coordinates with the BTN_TOUCH event to determine where the touch event actually occurred. Or ignore the EV_KEY events completely and only use EV_ABS to determine where the screen was touched.

Buttons

The LEFT, RIGHT, UP, DOWN, and ENTER buttons at the bottom of the LCD are problematic. I'm not yet certain if this is a bad board I have, or if something is preventing it from working correctly. I've asked Seeed Studio for some assistance.

At the moment, I can only get the RIGHT and UP buttons to work. This is the command I ran:

So while it obviously knows about the 5 buttons located on the bottom of the LCD, only 2 of them seem to generate any events:

2016-07-12: I've since discovered that all 5 keys work on BBG. It is only on the BBGW that some of the keys aren't working correctly. I'm hoping someone at Seeed Studio will get back to me to say why some of the keys don't work on BBGW.