Making Waveshare 5 inch HDMI LCD work with BeagleBone Black

I've recently bought one of these displays for Raspberry Pi that you can get at cutthroat prices (about 25 USD at the time I'm writing this). [link]

Front

Back

Display in question is usually listed as "5 inch LCD HDMI Touch Screen Display TFT 800*480" in various arrangements. Not 100% sure about relations between them, but most of the cheap units looking like pictures above seem to be clones of Waveshare 5inch HDMI LCD (B). The one I got was from a company called SpotPear [link].

The catch is, manufacturer promises that this display is directly supported on Raspberry Pi (actually, Raspberry Pi 2 and later because of the location of HDMI connector), but the only single-board computer I had at hand was BeagleBone Black.

Well, I thought, judging by the look of it, the display receives its feed over HDMI, and I don't really want touchscreen capability, so how hard can it be?

Things to be aware of:

• There are 2 versions of this display: with touch interface working over GPIO and USB. If you see one microUSB connector on the board - it's GPIO, otherwise it's two for USB.
• Touchscreen is a resistive kind, meaning you'll have to calibrate it before first use.

Some helpful resources on the display:

• Product pages (original and clones)
• Waveshare 5inch HDMI LCD (B)
• Elecrow. HDMI Interface 5 Inch 800x480 TFT Display
• Spotpear Raspberry Pi 5inch HDMI LCD GPIO Touch
• Miscellaneous (usually more helpful than product pages from tech perspective😀)
• LCD-show script GitHub repo
• Adding XPT2046 ( ADS7846 ) Touchscreen Support to Beaglebone Black
• Stackoverflow: preprocessing DTS files before compiling
• BBB device tree (some of it is already obsolete)
• Force Beaglebone Black HDMI resolution

This guide assumes GPIO variation of display (with one USB port) and Debian with X server installed.

You'll need:

• HDMI to miniHDMI cable [link]
• microSD memory card, 4Gb min. BeagleBone Black ships with 4Gb of eMMC memory on-board, that's why all OS images tend to fit into that space. You can actually make it work with 2Gb - older versions of BBB had only that much - but it'll require some elbow grease. Further reading: [link1] [link2] [link3]
• Beagle Bone Black with a 5V 2A power supply. Plus either a USB to mini-USB cable or a 5.5/2.1 mm. barrel jack connector to power it up, whichever is easiest to procure for you.
• Some way to get console access to BBB. If you have a WiFi router at home (of course you do) the simplest option would be to grab an Ethernet cable and patch BBB to the router, making BeagleBone a part of your local network, then SSH into it.
• Evidently, the display in question [link]

Connections:

They say a picture is worth a thousand words.
May not be as true for connection listings,
but I'll at least try.

Close-up with touchscreen GPIO connections

Did you know that you can left-click on any picture to expand it?

BeagleBone	Display
USB Host	micro USB
miniHDMI	HDMI

Quite simple, isn't it? Actually, you'll need to make some more connections to make touchscreen work:

BeagleBone	BB pin header and no.	Display
SPI0_D0	P9 Pin 21	MOSI
SPI0_D1	P9 Pin 18	MISO
SPI0_SCLK	P9 Pin 22	SCK
SPI0_CS0	P9 Pin 17	CE1
P9 Pin 23	P9 Pin 23	P6
DGND (optional)	P9 pins 1, 2, 43 - 46 P8 pins 1, 2	GND (optional)

 Note that we're just powering the display via micro USB, therefore you can hook it to any other 5V power supply (e.g. another wall charger) if you're saving USB host connector on BBB for later. If this other power supply happens to be isolated from main BBB power source, make sure to join the ground terminals as shown in table above.

Enabling the display

 1) If you're not sure what's installed on your Beagle Bone, follow the official guide and install the latest Debian image with LXQT first. Note: on the older revisions with only 2Gb eMMC, the newest image that worked for me was Debian 9.1 2017-08-31 4GB SD LXQT.

2) Power up the board, while holding down the "Boot" button:

 You can release it when all 4 LEDs lit up. Now you've essentially told BeagleBone to boot from memory card instead of eMMC memory, up until power cycle (and only that! When you press "Reset" button it will still boot from SD, whether you hold "Boot" button again or not).

 To no-one's surprise, you are greeted by a glitchey black screen decorated by occasionally repeating horizontal streaks of white, with a blinking underscore during boot-up and something that resembles mouse pointer later:

Booting sequence on unmodified Debian LXDE image

Idle X window after boot-up. All black except a grainy artifact that is a mouse pointer.

3) Log in to BBB - either over SSH or serial connection. The default user is debian, with password temppwd.

4) Every clone of this type of display makes it work on Raspberry Pi by taking a vanilla Raspbian image and launching LCD5-show script from LCD-show GIT repository. By repeating what's listed in that script on Beagle Bone, we'll achieve the same goal here.

First off, we specify the resolution and refresh rate of HDMI screen manually. If we were to look into dmesg logs, we'd see this message: tda998x 0-0070: read edid timeout.
EDID specifies the capabilities of display devices (i.e. what resolutions they can display) - and evidently the engineers behind this display decided to cut corners by not implementing EDID protocol.
Voila! After rebooting you'll see a friendly beagle muzzle peering at you from the screen.

You may stop here if it's just the screen you're after. If you'd like to make use of touchscreen as well, please proceed to the next section.

Bonus section: setting up touchscreen, calibration, on-screen keyboard

Touchscreen

Luckily for us, some guy had already figured out how to enable touchscreen on Waveshare displays. I'll just duplicate his findings here in case that website goes down. [BB-ADS7846-00A0.dts on my Google Drive]

Now the touchscreen is working, but it's not calibrated yet! You'll feel a certain disconnect between the point on the screen you're poking at and the actual pointer position.

Calibration

Virtual keyboard

... and that was it! Just kidding, to make it usable we'll have to do the following:

1) Make keyboard pop up upon entering input fields.

Menu->Universal Accessibility->Florence Virtual Keyboard. Then click the wrench button.

Tick the "Auto hide" option.

 2) Add virtual keyboard to autostart list.

Menu->Preferences->LXQt Settings->Sessions Settings

Your autostart list should look like that.

At this point, I consider the job done and Waveshare display fully configured and usable.

Want to avoid the hassle of configuring a stock image? Download my Debian 9.1 image with all aforementioned modifications!

Just flashing it on a memory card should get you up and running in no time.

Commonly encountered problems

• Noisy picture, horizontal white stripes.

Those might be caused by noise in power supply voltage. If you're powering the display from a different power source than USB host connector on BeagleBone, try a different one. Any additional hardware might contribute to the noise - for example, I once tried to power this display from a no-name USB hub with this outcome:

Plugging USB cord back into BeagleBone's USB host solved the issue.

• Can not get touchscreen to work - DTB is not inserted after reboot.

Are you running an old image of Debian? In Linux, Device Tree files determine how to utilize non-discoverable hardware. To enable a compiled Device Tree file (DTB where B stands for Binary), older Debian images for BeagleBone used something called "Kernel overlays". The typical workflow for adding new hardware was:
Eventually BB maintainers deprecated Kernel overlays in favor of U-Boot overlays. DTBs are loaded at boot time in newer Debian versions, so attempting to load DTBs like you used to has no effect:
Everything device-tree related is now described in /boot/uEnv.txt now, so please follow the code snippet above to find out how to do that in modern BBB Debian distributions.