From Waveshare Wiki
Jump to: navigation, search

e-Paper IoT Driver HAT for Raspberry Pi, Supports NB-IoT/eMTC/GPRS





This is a Raspberry Pi IoT driver board for e-Paper raw panels. It allows getting text/image data from IoT clouds through NB-IoT/eMTC/EDGE/GPRS network connection, and then display them on the e-Paper.


  • Onboard SIM7000E module, controlled via UART, supports NB-IoT/eMTC/EDGE/GPRS communication.
  • e-Paper interface, controlled via SPI, compatible with various Waveshare SPI e-Paper raw panels.
  • Standard Raspberry Pi 40PIN GPIO extension header, supports Raspberry Pi series boards.
  • Breakout SIM7000E and e-Paper control pins, for connecting with host control boards like STM32.
  • 3.7V lithium battery port and charging circuit, provide power to SIM7000E module or external 3.3V system (5V system like Raspberry Pi requires another power supply).
  • Onboard voltage translator, select 3.3V/5V operating voltage by switch.
  • Provides Windows host code (based on Alibaba Cloud), making it easy to study/develop, or integrate it into IoT applications.
  • Comes with online development resources and manual (examples for Raspberry Pi/STM32).


  • Communication interface: UART + SPI (4-wire SPI by default, switch to 3-wire SPI by soldering)
  • Communication module: SIM7000E
    • Quad-Band LTE-FDD B3/B8/B20/B28
    • GPRS/EDGE 900/1800Mhz
    • GNSS (GPS, GLONASS, BeiDou, and Galileo, GNSS antenna is required and NOT included)
  • Support SIM card: NB-IoT specific card, or 1.8V/3V normal SIM card
  • Applicable region: China mainland, Southeast Asia, Europe, Africa, Australia, etc. (for reference only, please check the supported bands according to your local service provider)
  • Power supply voltage: 5V
  • Logic level: 5V / 3.3V
  • Applicable battery: 3.7V lithium battery via PH2.0 connector (NOT included)
  • Dimensions: 56.5mm x 65mm

Supported e-Paper

  • 1.54inch e-Paper, 1.54inch e-Paper (B), 1.54inch e-Paper (C)
  • 2.13inch e-Paper, 2.13inc e-Paper (B), 2.13inch e-Paper (C), 2.13inch e-Paper (D)
  • 2.7inch e-Paper, 2.7inc e-Paper (B)
  • 2.9inch e-Paper, 2.9inc e-Paper (B), 2.9inch e-Paper (C)
  • 4.2inch e-Paper, 4.2inc e-Paper (B), 4.2inch e-Paper (C)
  • 5.83inch e-Paper, 5.83inch e-Paper (B), 5.83inch e-Paper (C)
  • 7.5inch e-Paper, 7.5inc e-Paper (B), 7.5inch e-Paper (C)



PIN Raspberry (BCM2835) Description
5V 5V 5V Power input
3V3 3.3V 3.3V Power input
GND GND Ground
DIN MOSI MOSI of SPI interface
CLK 11 SCK of SPI interface
CS CE0 Chip selection of SPI interface
DC 25 Data/Command selection
RESET 17 Reset (Low active)
BUSY 24 Busy Pin
TXD 14 TX pin of NB-IOT module
RXD 15 RX pin of NB-IoT module
DTR 19 Sleep/Wake up Pin of NB-IoT Module
Set AT+CSCLK=1, then you can pull-high DTR to make module sleep, and pull-down DTR to wakeup.
PWR 4 Power on/off pin of NB-IoT Module (high active)
RST 18 Reset oub of NB-IoT pin (high active)

How it work?

This product use Alibaba Clound platform to refresh image to e-Paper, it included cloud side and device side.
Cloud: Use client software, transmit the image data to Alibaba Cloud.
Device: Use NB-IoT, get image data from Alibaba Could and update e-Paper.

E Paper NB-IOT HAT manual 1.png

If you are the first time to use this module, we recommend you to follow the guides below step by step.

Setup Cloud side

The flow of the Cloud side: Client software sends data(image, string) to the Alibaba cloud platform, and then devices get data from the cloud.

In this chapter, we will use client software and Alibaba Cloud, you can read Document of Alibaba Cloud for reference.


Before you begin the project, you need to sign up for Alibaba Cloud and settings.

1. Download and install client software
Please download ePaperTools-4.0 software from #Resource. Unzip and install it.
2. Create an Alibaba Cloud account. Active the IoT platform.
Go to Alibaba Could website to make an account and log in.
3. Create API AccessKey.
Enter Accesskey page, and click "Continue to manage AccessKey"
E Paper NB-IOT HAT manual 2.png
4. Click Create AccessKey to create an access key.
E Paper NB-IOT HAT manual 3.png
5. Save the access key
The AccessKey ID and Accesskey Secret are the API keys for accessing Alibaba Cloud, they are important for our whole demo. Please keep it safe for future use.
6. Enter the AccessKey to the e-Paper Tool software
E Paper NB-IOT HAT manual 5.png

Register product

Enter the ProductName (it is configurable) and click register to register the product.

E Paper NB-IOT HAT manual 4.png

Import object model

The object model defines the drawing functions of e-Paper.

1. Download the model from wiki, unzip it, and modify the model.json file. Change the ProductKey to the one you registered. If you close it by accident, you can search on the Console of Alibaba Cloud website.
E Paper NB-IOT HAT manual 6.png
2. Enter the IoT Platform console, you can check the registered product
Choose Devices -> Products.
3. Click the product and choose define feature. Import TSL.
E Paper NB-IOT HAT manual 8.png
4. Import the model that we modified before.
E Paper NB-IOT HAT manual 9.png
5. After importing, you can find that there are self-defined features.
E Paper NB-IOT HAT manual 10.png

Register Devices

We take one kind of e-Paper as one device, to control the e-Paper, we also need to register devices for e-Paper. The Device Name is definable.

E Paper NB-IOT HAT manual 11.png

After registering, you need to save the register information

E Paper NB-IOT HAT manual 12.png

Push message

Open the e-Paper tool software. Select the device (设备选择), for example, 4.2inch e-Paper. Enter the ProductKey and DevicesName. Then choose Update (刷图) or Clear (清屏).

1. Update mode
  • The coordination value cannot be bigger than the resolution of the e-paper.
  • If you enable Chinese string and English string at the same time, it supports about 100 Chinese characters or 200 English characters.
  • If you only enable a Chinese string, it supports about 200 Chinese characters.
  • If you only enable English string, it supports about 400 English characters.
  • The image should be able to download via HTTP protocol online. It only supports monochrome bitmap files, and the resolution should be less or equal to the resolution of the e-paper.
  • You should type the whole link of the image.
  • If the e-Paper you use is a 3-color e-Paper, you should prepare two images, one is for the Black-white part, and another is for the Red part.
2. Clear mode
In this mode, the e-paper will be clear to white.
3. Operations
Set the image you want to update on the right operation area and then click setting (设置). The image data will be pushed to Alibaba Cloud, you can check the push message on the website.
E Paper NB-IOT HAT manual 14.png
E Paper NB-IOT HAT manual 15.png
The data is pushed to the cloud as the expected value, you can check it in Form format.

How to make bitmap

Here we show you how to make the proper bitmap file.

1. How to make a correct resolution?
Open the picture with Paint software. Resize it as 400x300 and save it as a monochrome bitmap.
E Paper NB-IOT HAT manual 16.png
2. How to push the bitmap to the network?
Here we use the OSS tool of Alibaba Cloud. Note that this e-paper HAT could only support HTTP but not the HTTP protocol.
Download the OSS browser software from the wiki, and unzip it. Open the OSS-Browser software, you need to log in with the access key.
The first time you use OSS, you need to enable it. Please click here to enable
Then you can click "Create Bucke" to create a bucket first.
Now you can push your pictures to the cloud. And get the address.
E Paper NB-IOT HAT manual 17.png
E Paper NB-IOT HAT manual 18.png

Setup Raspberry Pi

1. About the image.
We only test Raspbian OS, in this case, we recommend you to use Raspbian as well.
2. Enable serial port
Use sudo raspi-config command to enter the configuration page, choose Interfacing Options -> Serial -> No -> Yes,
3. Enable SPI interface.
Use sudo raspi-config command to enter the configuration page, choose Interfacing Options -> SPI -> Yes.
4. Install BCM2835 libraries.
Open the terminal and install BCM2835 libraries.
wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.60.tar.gz
tar -zxvf bcm2835-1.60.tar.gz
cd bcm2835-1.60
sudo ./configure
sudo make
sudo make check
sudo make install
5. Hardware setup
1. To use this demo, you should prepare a SIM card that supports the NB-IoT network. And insert it into the SIM card slot.
2. Connect the antenna to the LTE interface of the e-Paper NB-IoT GPRS HAT.
3. Connect your e-Paper to the e-Paper NB-IoT GPRS HAT.
4. Set switches.
BS welding
1 0
3V3 5V
3.3V working-level 5V working-level
Display Config
1.54inch e-Paper (B) 1.54inch e-Paper
2.13inch e-Paper (B) 2.13inch e-Paper
2.7inch e-Paper 2.9inch e-Paper
2.7inch e-Paper (B)
2.9inch e-Paper (B)
4.2inch e-Paper
4.2inch e-Paper (B)
7.5inch e-Paper
7.5inch e-Paper (B)
5V power input (USB interface or GPIO) Batteries
To use it with Raspberry Pi, you should set it to
BS/Switch/Jumper Description
BS weld Set it to 0 sides (default)
VCCIO switch Set it to 3V3
Display Config Set it according to the e-Paper you use
POWER jumper set it to 5V
6. Download demo codes from the wiki, unzip and copy it to Raspberry PI
You can also directly clone it from github by command
git clone https://github.com/waveshare/ePaper-NB-IoT-GPRS-HAT.git
7. Modify the device information
E Paper NB-IOT HAT manual 13.jpg
8. Compile codes and run it
cd ePaper-NB-IoT-GPRS-HAT
sudo make
sudo ./epd
E Paper NB-IOT HAT manual 28-1.jpg
9 Expected result
(1) The module is set to NB-IoT mode
E Paper NB-IOT HAT manual 29-1.jpg
(2) Connect to Aliyun platform
E Paper NB-IOT HAT manual 30-1.jpg
(3) Get data from Aliyun by MQTT protocol
E Paper NB-IOT HAT manual 31-1.jpg
(4) Get image data from the network by HTTP protocol
E Paper NB-IOT HAT manual 32-1.jpg
(5) Update e-Paper
E Paper NB-IOT HAT manual 33-1.jpg


If you don't stop the code, it will update the e-Paper every 5 seconds. If you want to modify the interval, you can modify the main.c file
E Paper NB-IOT HAT manual 35-1.jpg
The log.txt file is saved under the log directory.
E Paper NB-IOT HAT manual 36-1.jpg
variables of log.txt
Variables Description Note
tryTime Try times that get image data from the network
successTime Times that success to get image data from network The times of e-Paper update
mqttConnectFailTime The fail time that connects to the Aliyun platform
httpDiwnloadFailTime The fail time that downloads data from the network
noneMqttPackageTime The amount that none MQTT packages are received
duplicatePackageTime The amount of receiving duplicate MQTT package
duplicatePackageWaitTime The wait time for receiving a duplicate MQTT package

Flow of the demo codes

E Paper NB-IOT HAT manual 19.png



Demo codes


SIM7000 Related





Technical Support

If you need technical support or have any feedback/review, please click the Submit Now button to submit a ticket, Our support team will check and reply to you within 1 to 2 working days. Please be patient as we make every effort to help you to resolve the issue.
Working Time: 9 AM - 6 PM GMT+8 (Monday to Friday)