Skip to content

Waveshare 1.3" LCD HAT

The Waveshare 1.3-inch LCD HAT is a 240×240 color display based on the ST7789 controller. It communicates over SPI and includes three physical buttons (KEY1–KEY3) plus a 5-way joystick (up, down, left, right, press).

CyberHUD provides a single panel definition for this board.

Quick Start

sudo ./cyberhudd -panel waveshare-1.3hat

In your /etc/cyberhudd.json:

{
  "display": {
    "panel": "waveshare-1.3hat"
  }
}

Display Characteristics

Property Value
Resolution 240 × 240 pixels
Color format RGB565
Controller ST7789
Interface SPI
Input 3 buttons + 5-way joystick

Pin Assignments

Function GPIO Pin Notes
SPI MOSI GPIO10 SPI0 data out
SPI SCLK GPIO11 SPI0 clock
SPI CS GPIO8 SPI0 chip-select (CE0)
DC (Data/Command) GPIO25 High = data, Low = command
RST (Reset) GPIO27 Active-low reset
Backlight GPIO24 PWM-capable; high = on
KEY1 GPIO5 Physical button 1
KEY2 GPIO6 Physical button 2
KEY3 GPIO13 Physical button 3
Joystick Up GPIO19 Active-low
Joystick Down GPIO21 Active-low
Joystick Left GPIO16 Active-low
Joystick Right GPIO20 Active-low
Joystick Press GPIO26 Active-low

SPI communication uses /dev/spidev0.0 (CE0).

Input Details

Buttons

Input GPIO Pin Location / Label
KEY1 GPIO5 Top button
KEY2 GPIO6 Middle button
KEY3 GPIO13 Bottom button

Joystick

Input GPIO Pin Direction
Joystick Up GPIO19 Joystick pushed upward
Joystick Down GPIO21 Joystick pushed downward
Joystick Left GPIO16 Joystick pushed left
Joystick Right GPIO20 Joystick pushed right
Joystick Press GPIO26 Joystick pressed inward (center click)

All inputs are active-low with internal pull-ups enabled by the HAT hardware.

Troubleshooting

CyberHUD emits detailed diagnostic logs during panel initialization. Check them with:

sudo journalctl -u cyberhudd.service -n 50

Common Issues

Symptom Likely Cause Fix
spi device ... open=error SPI not enabled on the Raspberry Pi Run sudo raspi-config → Interface Options → SPI → Enable, then reboot
Display is white/blank but backlight is on DC or RST pin not accessible, or wrong panel name Verify GPIO25 and GPIO27 are not claimed by another overlay; check panel name spelling
Colors appear inverted (BGR vs RGB) MADCTL mismatch for your panel batch Override MADCTL in JSON config to adjust color order bit
Image is offset or clipped at edges X/Y offset mismatch for your panel batch Override xOffset and yOffset in JSON config