Overview

Program to show Linux desktop environment over Waveshare Eink screen.

Partial updates and partial pixel content transfer are supported.

Support of:

• showing remote screen (client) content using a TCP server running on Raspberry (YouTube example)
• showing Raspberry screen in standalone mode (YouTube example)

In standalone mode Raspberry is configured with 24bit dummy Xorg driver. In client/server mode remote screen (client) must run Linux and have 24 bit screen.

For quick info how-to run each program check: README_how_to_run.md

Info about how to setup touch panel

Tested devices:

• Waveshare 9.7" 1200x825 panel
• Raspberry 2 B - SPI speed range 15625000 - 17850000 Hz
• Raspberry 3 B+ - SPI speed configured only by divider /32, see also INSTALL_RPI3B_PLUS.md

Gray scale pixel depths 2bit, 4bit and 8bit are supported and configurable.

Other Waveshare screens might work as well as Eink screen dimensions are nowhere hardcoded.

Forked from https://github.com/waveshare/IT8951

Setup

• Setup BCM2835 library - http://www.airspayce.com/mikem/bcm2835/
• Setup SPI/GPIO connection and BCM2835 library as described in Waveshare WIKI: https://www.waveshare.com/wiki/9.7inch_e-Paper_HAT
• Install libx11-dev and libxext-dev needed to capture X11 screenshot
• Install libxfixes-dev needed to capture X11 mouse cursor

1. Setup Xorg dummy display driver /etc/X11/xorg.conf

Section "Monitor"
  Identifier "Monitor0"
  HorizSync 28.0-80.0
  VertRefresh 48.0-75.0

  # Generate by command `cvt 1200 825`
  Modeline "1200x825_60.00"   80.50  1200 1264 1384 1568  825 828 838 857 -hsync +vsync
EndSection

Section "Device"
  Identifier "Card0"
  Driver "dummy"
  VideoRam 4000
EndSection

Section "Screen"
  DefaultDepth 24
  Identifier "Screen0"
  Device "Card0"
  Monitor "Monitor0"
  SubSection "Display"
    Depth 24
    Modes "1200x825_60.00"
  EndSubSection
EndSection

2. /boot/config.txt - adjust values in framebuffer_* keys

/boot/config.txt
# For more options and information see
# http://rpf.io/configtxt
# Some settings may impact device functionality. See link above for details

# uncomment if you get no picture on HDMI for a default "safe" mode
#hdmi_safe=1

# uncomment this if your display has a black border of unused pixels visible
# and your display can output without overscan
disable_overscan=1

# uncomment the following to adjust overscan. Use positive numbers if console
# goes off screen, and negative if there is too much border
overscan_left=0
overscan_right=0
overscan_top=0
overscan_bottom=0

# uncomment to force a console size. By default it will be display's size minus
# overscan.

# Framebuffer console filling up whole eink display
#framebuffer_width=1700
#framebuffer_height=3600
#max_framebuffer_height=4000

# Framebuffer 1200x825
framebuffer_width=1200
framebuffer_height=825
framebuffer_depth=32
framebuffer_ignore_alpha=1

# uncomment if hdmi display is not detected and composite is being output
#hdmi_force_hotplug=1

# uncomment to force a specific HDMI mode (this will force VGA)
#hdmi_group=1
#hdmi_mode=1

# uncomment to force a HDMI mode rather than DVI. This can make audio work in
# DMT (computer monitor) modes
#hdmi_drive=2

# uncomment to increase signal to HDMI, if you have interference, blanking, or
# no display
#config_hdmi_boost=4

# uncomment for composite PAL
#sdtv_mode=2

#uncomment to overclock the arm. 700 MHz is the default.
#arm_freq=800

# Uncomment some or all of these to enable the optional hardware interfaces
#dtparam=i2c0=on
dtparam=i2c1=on
dtparam=i2c_arm=on
#dtparam=i2s=on
dtparam=spi=on

# Uncomment this to enable infrared communication.
#dtoverlay=gpio-ir,gpio_pin=17
#dtoverlay=gpio-ir-tx,gpio_pin=18

# Additional overlays and parameters are documented /boot/overlays/README

# Enable audio (loads snd_bcm2835)
dtparam=audio=on

[pi4]
# Enable DRM VC4 V3D driver on top of the dispmanx display stack
dtoverlay=vc4-fkms-v3d
max_framebuffers=2

[all]
#dtoverlay=vc4-fkms-v3d

dtoverlay=i2c-rtc,ds1307
dtoverlay=w1–gpio

3. Setup sudo visudo to allow just executables installed under /opt to be executed without password. And adjust according to example file sudoers.example.

4. Should be enough to setup once, it is needed to take X11 screenshots from program running as root and X running for normal user:

ssh -X [email protected]

# as `pi` user
startx &

echo $DISPLAY
xauth list $DISPLAY

# raspberrypi/unix:0  MIT-MAGIC-COOKIE-1  87dd8f57c6cb48312b65a0729c1f5a61

sudo su

# as root
xauth list $DISPLAY

# raspberrypi/unix:0  MIT-MAGIC-COOKIE-1  2e953f9f784a51c1c72beeb2457e332a

xauth add raspberrypi/unix:0 MIT-MAGIC-COOKIE-1 87dd8f57c6cb48312b65a0729c1f5a61

5. Add a line to /home/pi/.profile

[[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && exec startx

6. Create a Systemd service to start X, honoring ~/.xinitrc at boot up:

sudo systemctl edit getty@tty1

And paste following:

[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin pi --noclear %I $TERM

7. Switch to multi-user.target as graphical.target prefers to use display manager absent in our case:

sudo systemctl enable multi-user.target --force
sudo systemctl set-default multi-user.target

8. Replace /home/pi/.xinitrc from _.xinitrc.example

Development

SSH to Raspberry preferably with ssh -X pi@HOST

Edit ~/.xinitrc to start just the window manager session by setting EINK_ENABLE=0.

Kill the X server and/or mate-session, and eink processes. Mate session will restart automatically according to ~/.xinitrc

sudo killall Xorg
sudo killall eink_rpi_standalone
sudo killall eink_rpi_server

Enter sources directory and upload/compile both standalone and server version:

cd ~/projects/<project dir>
./upload.sh <raspberry IP>

Nice to have public key authentication instead of password, refer to https://serverpilot.io/docs/how-to-use-ssh-public-key-authentication/

Run the program standalone over SSH connection:

For detailed program arguments see: README_how_to_run.md

ssh <raspberry IP>
...
cd /home/pi/projects/<project dir>
DISPLAY=":0" sudo ./eink_rpi_standalone ...arguments...
...
# or install any of executables:
cd /home/pi/projects/<project dir>/rpi_standalone
sudo make install

cd /home/pi/projects/<project dir>/rpi_server
sudo make install

When changes are stable install new version in /opt by sudo make install from sources directory on Raspberry and change EINK_ENABLE=1 in ~/.xinitrc

Kill the Xorg/program before installing new version if EINK_ENABLE=1. Killing should make Xorg to restart automatically.

Single instance check should probably be added.

Additional config (dconf)

dconf dump / >dconf.conf

Edit in file dconf.conf

[org/mate/marco/general]
reduced-resources=true
theme='HighContrast'

Load custom dconf file:

dconf load / < dconf.conf

Increase system SPI buffer size

That might help to optimize performance while sending bigger arrays of pixel data over SPI. In 4 bit mode that size can be up to around 500KB for 1200x825 screen.

On Raspberry PI edit /boot/cmdline.txt and append spidev.bufsiz=65536 argument and restart. That configures the SPI buffer size to the maximum. Actual size can be queried with cat /sys/module/spidev/parameters/bufsiz.

Troubleshoot

Eink display of the desktop sometimes is not starting reason unsure at the moment might be VCOM setting related or other.

It can help to click Reset button on IT8951 board a few times for a few seconds.

If does not help try to halt Raspberry over SSH power off Raspberry/IT8951 and restart.

Check /home/pi/eink.log also.

If nothing helps try to run as described in Development paragraph to see exact program output

Resources

Waveshare official demo code Github repository https://github.com/waveshareteam/IT8951-ePaper/tree/master/Raspberry

Wiki page of the device used by this poject https://www.waveshare.com/wiki/9.7inch_e-Paper_HAT

Technical specification of IT8951 chip https://www.waveshare.net/w/upload/1/18/IT8951_D_V0.2.4.3_20170728.pdf