KlipperLCD (for Elegoo Neptune 3 Pro LCD screen)

Want to run Klipper on your Neptune 3 Pro? And still want to be able to use your Neptune 3 Pro LCD touch screen?

Take a look at this python service for the Elegoo Neptune 3 Pro LCD! Running together with Klipper3d and Moonraker!

Look and feel

What's needed?

• An Elegoo Neptune 3 Pro with LCD screen.
• A Raspberry Pi or similar SBC to run Klipper. I suggest using the Klipper Installation And Update Helper (KIAUH) to setup and install Klipper, Moonraker and the web user interface of choice (Fluidd/Mainsail).
• Some re-wiring of the LCD screen to connect it to one of the UARTs available on your Raspberry Pi / SBC or through a USB to UART converter.
• Then you can follow this guide to enable your Neptune 3 Pro touch screen!

Wire the LCD

When wiring your screen, you can either wire it directly to one of your Raspberry Pi / SBC available UARTs or through a USB to UART converter. Both options are described below.

To a Raspberry Pi UART

1. Remove the back-cover of the LCD by unscrewing the four screws.

2. Connect the LCD to the Raspberry Pi UART according to the table below:

   Raspberry Pi	LCD
   Pin 4 (5V)	5V (Black wire)
   Pin 6 (GND)	GND (Red wire)
   GPIO 14 (TXD)	RX (Green wire)
   GPIO 15 (RXD)	TX (Yellow wire)

   

USB to UART Converter

Quite simple, just remember to cross RX and TX on the LCD and the USB/UART HW.

USB <-> UART HW	LCD
5V	5V (Black wire)
GND	GND (Red wire)
TXD	RX (Green wire)
RXD	TX (Yellow wire)

Update the LCD screen firmware

1. Copy the LCD screen firmware LCD/20240129.tft to the root of a FAT32 formatted micro-SD card.
2. Make sure the LCD screen is powered off.
3. Insert the micro-SD card into the LCD screens SD card holder. Back-cover needs to be removed.
4. Power on the LCD screen and wait for screen to say Update Successed!

A more detailed guide on LCD firmware updates can be found on the Elegoo support page.

Enable the UART

Note: You can safely skip this section if you wired the display through a USB to UART converter

Disable Linux serial console

By default, the primary UART is assigned to the Linux console. If you wish to use the primary UART for other purposes, you must reconfigure Raspberry Pi OS. This can be done by using raspi-config:

• Start raspi-config: sudo raspi-config.
• Select option 3 - Interface Options.
• Select option P6 - Serial Port.
• At the prompt Would you like a login shell to be accessible over serial? answer 'No'
• At the prompt Would you like the serial port hardware to be enabled? answer 'Yes'
• Exit raspi-config and reboot the Pi for changes to take effect.

For full instructions on how to use Device Tree overlays see this page.

In brief, add a line to the /boot/config.txt file to apply a Device Tree overlay.

dtoverlay=disable-bt

Run the KlipperLCD service

SSH into your Raspberry Pi (or other SBC), then follow the steps below.

1. Verify Klipper socket API

Check that Klipper was started with a UNIX socket:

cat ~/printer_data/systemd/klipper.env

KLIPPER_ARGS must include:

-a /home/<user>/printer_data/comms/klippy.sock

2. Install system dependencies

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip git rsync

If you want to run containerized tests (make test-container), also install Podman:

sudo apt-get install -y podman

3. Get the code

git clone https://github.com/ImpBY/KlipperLCD.git
cd KlipperLCD

4. Configure environment

Service/runtime settings are read from:

~/.config/KlipperLCD/service.env

Create/update this file from template:

make config

Key variables:

• KLIPPERLCD_LCD_PORT (for USB-UART typically /dev/ttyUSB0)
• KLIPPERLCD_LCD_BAUDRATE
• KLIPPERLCD_KLIPPY_SOCK
• KLIPPERLCD_MOONRAKER_URL (host or IP only, without http://)
• KLIPPERLCD_API_KEY
• KLIPPERLCD_UPDATE_INTERVAL
• KLIPPERLCD_LOG_LEVEL

Notes:

• The current implementation connects to Moonraker on port 80 internally, so KLIPPERLCD_MOONRAKER_URL should resolve to a host where Moonraker is reachable on port 80.
• Keep KLIPPERLCD_API_KEY synchronized with your Moonraker API key.

5. Install and enable systemd service

make install

This command:

• creates service venv (~/<repo-dir-name>-venv, for this repo: ~/KlipperLCD-venv),
• installs package and dependencies,
• uses service config from ~/.config/<repo-dir-name>/service.env (for this repo: ~/.config/KlipperLCD/service.env),
• generates /etc/systemd/system/<repo-dir-name>.service from service.template (for this repo: /etc/systemd/system/KlipperLCD.service),
• enables and starts the service.

6. Update / restart / remove

make upgrade      # reinstall package + restart service
make uninstall    # disable service + remove unit/venv

7. Development run (without systemd)

make venv
source .venv/bin/activate
python3 main.py
# or, after venv install:
klipperlcd

8. Run tests

Local test run in repository venv:

make test

Containerized test run with Podman:

make test-container

Current test modules:

• tests/test_app_logic.py (application event routing, thumbnail flow, env parsing)
• tests/test_lcd_logic.py (LCD handlers, file navigation/selection, UI-side events)
• tests/test_printer_logic.py (printer command formatting, REST/GCode routing, progress math)

Makefile commands

Show available commands any time:

make help

Console

The console is enabled by default and can be accessed by clicking center top of the main screen or by clicking the thumbnail area while printing.

The console enables sending commands and will display all gcode responses and information from Klipper normally found in the console tab in Mainsail or Fluidd.

Thumbnails

KlipperLCD also supports thumbnails!

Follow this guide to enable thumbnails in your slicer: https://klipperscreen.readthedocs.io/en/latest/Thumbnails/