Template:4inch DSI LCD User Manual

Features

• 4inch IPS capacitive touch screen with a hardware resolution of 480 × 800ch capacitive touch screen.
• Capacitive touch panel, support 5-point touch.
• Tempered glass capacitive touch panel, hardness up to 6H.
• Drive LCD directly through Raspberry Pi's DSI interface with a refresh rate of up to 60Hz.
• Working with Raspberry Pi, supports Raspberry Pi OS system.
• Supports Pi 4B/3B+/3A+, Another adapter cable is required for CM3+/4.
• Support backlight adjusted by software.

Working with Raspberry Pi

Hardware connection

1. Set the DIP switch on the back of the LCD to I2C0 or I2C1 mode, the Bullseye branch uses I2C0, and the Buster branch uses I2C1. The default is I2C0 mode.
Note: If you don't know the difference between the two branches of Raspberry Pi OS, you can check the following introduction #Introducing the Raspberry Pi OS fork

2. Use a 15PIN FPC cable to connect the 4inch DSI LCD to the DSI interface of the Raspberry Pi.
3. Fix the 4inch DSI LCD to the Raspberry Pi through copper posts. Then the 5V, GND, SCL, SDA of the 4inch DSI LCD will be connected to the 40PIN GPIO of the Raspberry Pi through the thimble. The 5V and GND interfaces can be connected to low-power consumption devices, such as a fan.
Note: For the use of I2C0 mode, the 4inch DSI LCD and Raspberry Pi can be used without fixing, but the 5V and GND interfaces of the LCD will not be able to supply external power.
The final connection is shown below:

Software settings

1) Download the image from the Raspberry Pi website.
2) Download the compressed file to the PC, and unzip it to get the .img file.
3) Connect the TF card to the PC, use SDFormatter software to format the TF card.
4) Open the Win32DiskImager software, select the system image downloaded in step 2, and click‘Write’ to write the system image.
5) After the image has finished writing, save, and quit the TF card safely.
6) Connect the TF card to the Raspberry Pi, start the Raspberry Pi, and log in to the terminal of the Raspberry Pi (you can connect the Raspberry Pi to an HDMI display or log in remotely with ssh).

#Step 1: Download and enter the Waveshare-DSI-LCD driver folder
git clone https://github.com/waveshare/Waveshare-DSI-LCD
cd Waveshare-DSI-LCD

#Step 2: Enter uname -a in the terminal to view the kernel version and input cd to find the corresponding file directory
#5.15.61 runs the following command
cd 5.15.61
#5.15.32 runs the following command
cd 5.15.32
#5.15.56 runs the following command
#cd 5.15.56
#5.10.103 runs the following command
#cd 5.10.103

#Step 3: Please check the number of bits of the system currently in use as the 32-bit system should enter the 32 directory and the 64-bit system should enter the 64 directory
cd 32
#cd 64

#Step 4: Enter the command corresponding to your model to install the driver, pay attention to the selection of the I2C DIP switch
#7inch DSI LCD (C) 1024 × 600 Driver:
sudo bash ./WS_xinchDSI_MAIN.sh 7INCH I2C1
#7.9ich DSI LCD 400 × 1280 Driver:
#sudo bash ./WS_xinchDSI_MAIN.sh 7_9INCH I2C0
#11.9inch DSI LCD 320 × 1480 Driver:
#sudo bash ./WS_xinchDSI_MAIN.sh 11_9INCH I2C0
#2.8inch DSI LCD 480 × 640 Driver:
#sudo bash ./WS_xinchDSI_MAIN.sh 2_8INCH I2C0
#4inch DSI LCD 480 × 800 Driver:
#sudo bash ./WS_xinchDSI_MAIN.sh 4INCH I2C0

#Step 5: Wait for a few seconds, when the driver installation is complete and no error is prompted, restart and load the DSI driver and it can be used normally
sudo reboot

Note: The above steps need to ensure that the Raspberry Pi can be connected to the Internet normally.
7) Wait for the system to restart, it will be able to display and touch normally.

Rotation

Method 1

In the start menu, select: Preferences->Screen Configuration->Configure->Screens->DSI-1->Orientation, select the corresponding angle in it, click "√", select Yes, and restart.

2022/2/10 Note:
Known bugs in the current Bullseye branch:
1. If you use the above method to rotate after opening VNC, the rotation direction of the touch will be wrong.
2. The above rotation method will also rotate abnormally on Pi3. These two bugs will be fixed in later versions.
If you need to open VNC and rotate at the same time, or use it on Pi3, you can use method 2.

Method 2

Display rotation:

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart
#Enter the command corresponding to the display rotation angle at the end of the autostart file, and it will take effect after restarting
#display rotated 90 degrees
xrandr --output DSI-1 --rotate right
#display rotated 180 degrees
xrandr --output DSI-1 --rotate inverted
#display rotated 270 degrees
xrandr --output DSI-1 --rotate left

Touch rotation:

sudo nano /boot/config.txt
#Modify the instruction of the touch rotation angle at the end of the config.txt file, and it will take effect after restarting (there is a 0° touch direction instruction by default)
#90°:
dtoverlay=WS_xinchDSI_Touch,invertedx,invertedy
#180°:
dtoverlay=WS_xinchDSI_Touch,invertedy,swappedxy
#270°:
dtoverlay=WS_xinchDSI_Touch
#0°:
dtoverlay=WS_xinchDSI_Touch,invertedx,swappedxy

Backlight Controlling

• Method one

sudo nano /boot/config.txt
#In config.txt, change dtoverlay=WS_4inchDSI480x800_Screen to the following command, the range of the x is 0-255, 0 is the darkest, 255 is the brightest, and the default is the brightest)
dtoverlay=WS_4inchDSI480x800_Screen,Backlight=x
#Such as:
dtoverlay=WS_4inchDSI480x800_Screen,Backlight=100
#Then restart
reboot

• Method two

We provide the application (this program is only used for Raspberry Pi OS system), users can download, install and use it in the following method:

#Find the original driver directory
cd 4inch-DSI-LCD
#Determine the number of bits of the system currently in use. If you are using the 32-bit system please enter the 32 directory, and if you are using the 64-bit system please enter the 64 directory.
cd 32
#cd 64
cd Backlight
sudo ./install.sh

After the installation is complete, you can open the program in the Start menu -> Accessories -> Brightness, as shown below:

Extended reading: Buster branch uses CSI camera

Note: If you don't know the difference between the two branches of Raspberry Pi OS, you can check the following introduction #Introducing the Raspberry Pi OS fork

• Instruction

When the DSI LCD is used, the KMS display driver needs to be loaded, which will conflict with the default camera subsystem raspicam of the Buster branch.
The libcamera camera subsystem needs to be compiled and installed before the CSI camera related to the Raspberry Pi can be used normally.
If the user uses the Bullseye branch, then no action is required to use the Raspberry Pi-related CSI camera.

• Hardware connection

First turn off the Raspberry Pi ,and then connect the Raspberry Pi camera, and then power on the Raspberry Pi.
Note: It is not allowed to plug and unplug the Raspberry Pi camera with power on, otherwise it may cause the related circuit to be burned out.

• Update and open the camera interface

The libcamera-apps application supports Pi3 and Pi4. Before installing, you need to update your Raspberry Pi software:

sudo apt update

Set the correct dtoverlay in /boot/config.txt according to the actual camera

sudo nano /boot/config.txt

Add at the end of the document:

#Take RPi Camera V2 as an example, the photosensitive chip is Sony IMX219, then add the following code:
dtoverlay=imx219
#Similarly, OV5647 chip:
#dtoverlay=ov5647
#IMX477 chip:
#dtoverlay=imx477

Open the camera interface and execute the following commands:

sudo raspi-config

Select 3 Inteface Options -> P1 Camera -> Enter -> Yes -> Finish -> Yes, then the Raspberry Pi will restart.

Install libcamera method 1

Note 1: It is recommended to use Pi4 to install and compile libcamera-apps instead of Pi3, because Pi4 has stronger performance and compilation is not prone to errors. The compiled image can also be used on Pi3.
Note 2: In the process of installing libcamera, it is very likely that some steps will go wrong. If you are a novice, it is recommended to directly burn #Method 1: Use a pre-installed driver image, in which we have installed libcamera.
Install all required dependencies for libcamera:

sudo apt install libboost-dev -y
sudo apt install libgnutls28-dev openssl libtiff5-dev -y
sudo apt install qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 -y
sudo apt install meson -y
sudo pip3 install pyyaml ply
sudo pip3 install --upgrade meson

Now we can download and build libcamera:

git clone git://linuxtv.org/libcamera.git
cd libcamera
meson build
cd build
meson configure -Dpipelines=raspberrypi -Dtest=false
cd ..
ninja -C build
sudo ninja -C build install

• libepoxy

Libcamera-apps requires libepoxy to be installed. First install its prerequisites:

sudo apt install libegl1-mesa-dev

Then download and build libepoxy:

cd
git clone https://github.com/anholt/libepoxy.git
cd libepoxy
mkdir _build
cd _build
meson
ninja
sudo ninja install

• libcamera-apps

Libcamera-apps further operates as follows:

sudo apt install cmake libboost-program-options-dev libdrm-dev libexif-dev

To build libcamera-apps, enter:

cd
git clone https://github.com/raspberrypi/libcamera-apps.git
cd libcamera-apps
mkdir build
cd build
cmake ..
make -j4

Finally, use the libcamera-hello command to open a 5-second preview camera screen:

./libcamera-hello

Introduction to related instructions:

libcamera-still # can be used to replace raspistill.
libcamera-vid # can be used to replace raspivid.
libcamera-raw # A version of libcamera-vid that saves uncompressed raw video files.
libcamera-hello # Startup command, run to see the camera screen on the display.
libcamera-jpeg # A stripped-down version of libcamera - can still run preview and capture JPEG, uninterrupted by other options.

Note: After installing libcamera-apps, the original DSI driver will be overwritten. In order to make the DSI LCD work normally, you need to reinstall the driver:

#For 7inch DSI LCD (C):
cd 7inch-DSI-LCD-C
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7inchDSI1024x600_MAIN.sh
sudo reboot
#For 4inch DSI LCD use:
cd 4inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_4inchDSI480x800_MAIN.sh
sudo reboot
#For 2.8inch DSI LCD use:
cd 2.8inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_2_8inchDSI480x640_MAIN.sh
sudo reboot
#For 7.9inch DSI LCD use:
cd 7.9inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7_9inchDSI400x1280_MAIN.sh
sudo reboot
#For 11.9inch DSI LCD use:
cd 11.9inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_11_9inchDSI320x1480_MAIN.sh
sudo reboot

Install libcamera method 2

Since there are many steps to install libcamera, it takes a long time. We provide a script for direct installation.
The specific operation steps are as follows:
1.Update the list of available packages

sudo apt update

2.Download libcamera-install file and install

git clone https://github.com/waveshare/libcamera-install.git
cd libcamera-install
sudo chmod +x install_libcamera_all.sh
sudo ./install_libcamera_all.sh

3. When echo "install Succeed" appears, the installation is successful. When echo "install Fail" appears, the installation failed.
After successful installation, three folders: libcamera, libcamera-apps and libepoxy will be generated in the libcamera-install directory. If you need to reinstall, you should delete these three folders first, and then reinstall.
Affected by the network, the installation may be unsuccessful if you run it once, and you can run it several times.
Note: After installing libcamera-apps, the original DSI driver will be overwritten. In order to make the DSI LCD work normally, you need to reinstall the driver:

#For 7inch DSI LCD (C) use:
cd 7inch-DSI-LCD-C
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7inchDSI1024x600_MAIN.sh
sudo reboot
#For 4inch DSI LCD use:
cd 4inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_4inchDSI480x800_MAIN.sh
sudo reboot
#For 2.8inch DSI LCD use:
cd 2.8inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_2_8inchDSI480x640_MAIN.sh
sudo reboot
#For 7.9inch DSI LCD use:
cd 7.9inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_7_9inchDSI400x1280_MAIN.sh
sudo reboot
#For 11.9inch DSI LCD use:
cd 11.9inch-DSI-LCD
cd xxx/xxx #Use different kernels, different interfaces, need to enter different directories
sudo ./WS_11_9inchDSI320x1480_MAIN.sh
sudo reboot

4. Restart

sudo reboot

5. Test, and display 5 seconds camera image

cd /home/pi/libcamera-install/libcamera-apps/build
./libcamera-hello

• Advanced

For more instructions on using libcamera, please refer to:
https://www.raspberrypi.org/documentation/linux/software/libcamera/README.md https://github.com/raspberrypi/libcamera-apps/blob/main/README.md https://www.raspberrypi.org/documentation/linux/software/libcamera/rpi_SOFT_libcamera_1p2.pdf

Introducing the Raspberry Pi OS fork

On December 2, 2021, the Raspberry Pi OS for Raspberry Pi split into two branches, the Buster branch and the Bullseye branch.

The Buster branch is a continuation of the old system, which is more stable and uses raspicam as the default camera subsystem.

The Bullseye branch adds some new features, including KMS as the default display driver and libcamera as the default camera subsystem.

For the project used with this display, we recommend users to use the Bullseye branch system, because on this system, it can be used normally with simple configuration, and Communication can be used by the default I2C0 in the DSI interface without occupying the raspberry Send I2C1 in 40PIN GPIO.

For users who must use the Buster branch, we currently also provide related drivers, but because the DSI driver needs to load the KMS display driver by default, the default camera subsystem of raspicam under the Buster branch cannot be used, and needs to be recompiled and installed. The libcamera camera subsystem (for beginners, it is difficult), and in order to make the raspicam camera subsystem not conflict with the DSI driver, the DSI driver will occupy the I2C1 in the 40PIN GPIO of the Raspberry Pi.

For the Bullseye branch, Waveshare R&D team will maintain the update for a long time. For the Buster branch, we will continue to support it until June 2024 (because the Raspberry Pi Foundation will not support the Buster branch after this time).

The following is a list of system support for this display:

System Name	Branch	Operating System Bits
2022-01-28-raspios-bullseye-arm64	bullseye	64 bits
2022-01-28-raspios-bullseye-armhf	bullseye	32 bits
2022-01-28-raspios-buster-armhf	buster	32 bits
2021-10-30-raspios-bullseye-armhf	bullseye	32 bits
2021-12-02-raspios-buster-armhf	buster	32 bits

Image download address

Raspberry Pi OS and Raspberry Pi OS (64-bit) are the Bullseye branch, and Raspberry Pi OS (Legacy) is the Buster branch.
More detailed information can be found at:

Raspberry Pi Branch Details

Buster Release Notes

Bullseye Release Notes

Notes:The above information was updated on February 10, 2022. Due to the frequent update of the Raspberry Pi image, when you see this information, the relevant information may be out of date. The actual performance of the image shall prevail. This is for reference only.

Note

1. Update the system, such as executing the following command

sudo apt-get update
sudo apt-get full-upgrade

After updating the system, some files of the originally installed driver may be overwritten, and the driver needs to be reinstalled to display normally.

2. Replace the motherboard
If the driver originally installed on the Raspberry Pi 4 Model B, the user replaces the motherboard, such as modifying it to a Raspberry Pi 3 Model B+, the display will not display properly.
Because Pi4 and Pi3 need to load different driver files, you need to reinstall the driver on the new motherboard to display properly.