How To Build ESPaper Content In Less Time

Do you have these moments when you start to realize that something you just created is gonna be a game changer, at least for you but maybe also for others? Last week I had such a moment when I decided to follow up on an idea which was spinning in my head for quite a while now.

I really got frustrated about how complicated, time-consuming and error-prone it was to develop on the Arduino IDE for the 3 ESP8266 based products I have created so far. In my professional life as a Java programmer we have great tools which allow us to do a change in the code and then check the results only a moment later on the compiled software. If we’re developing a web application I usually just have to click the refresh button of the browser to see the changes I did to the code.

The Arduino IDE on the other hand is quite another game. You click the compile button, you get some syntax errors, you fix them, you compile again, then you try to upload but you get a communication error, you do some mambo jambo do upload it again, then you realize that the change you did doesn’t actually look the way you wanted it to look. And then the loop starts over. Wouldn’t it be nice if programming new content for the TFT, OLED or e-paper displays would have a much shorter feedback loop? Something that would work similarly to a web application?


Why not use the Server/Client Pattern of HTML?

I’ve been in the software industry long enough to see that there are barely completely new inventions but rather new versions of the same concept, adapted to a new device or platform. A fairly successful architecture is that of HTML provided by a server over HTTP(S) and rendered in your browser with beautiful images, colors  and fonts. So I thought why not apply this concept to the world of embedded devices. For a short moment I considered to write a parser for HTML & CSS (style sheets) but abandoned the idea quickly due to the memory constraints on an embedded device. But I thought I could quite quickly come up with a similar concept using JSON and the JSON streaming parser I had implemented a while back. The streaming parser doesn’t have to keep the whole JSON object in memory but can process it on the go! This ideal for processing a JSON object containing drawing instructions and keeps the memory foot print on a minimal level.

As an added benefit I wanted to have faster way to test the result created on the server. Refreshing the embedded device and the display takes several seconds. Wouldn’t it be great to have a way to validate the result? To test the concept I quickly put together a script in the easiest server language I know: PHP. I also added a way to switch the output to SVG instead of JSON in order to test the output and visualize it before it’s being rendered on the device. This turned out to be a really powerful concept: fetch all data on the (PHP) server and just send the drawing commands (or even just the bitmap) to the ESP. Hard tasks like going through a OAuth2 process can now be done on the server where good client libraries exist and programming is much easier and faster.

Here is a sample of how a JSON command looks like:

 "command": "drawString",
 "params": {
   "x1": "2",
   "y1": "-2",
   "text": "Updated: 2017-11-09 11:35:28"

And this is how sample code in PHP looks like:

$canvas = new Canvas(296, 128);
$canvas->registerFont($baseUrl . "/fonts/", "Arial", "Plain", 10, "ArialPlain10");
$canvas->drawString(2, -2, "Updated: ".date("Y-m-d H:i:s"));
$canvas->drawLine(0, 11, 296, 11);
$canvas->drawString(274, -1, $voltage. "V ".$percentage."%");
$canvas->drawRect(274, 0, 18, 10);
$canvas->drawRect(293, 2, 1, 6);
$canvas->fillRect(276, 2, round(14 * $percentage / 100), 6);

After I showed first results Fabrice Weinberg (@FWeinb) approached me and showed me his JavaScript parser which tests the the actual produced JSON object and THEN renders the SVG. This is a great addition to the tool set of this approach and we’ll certainly have a look at it how we can use it.

The JavaScript based ESPaper-Json emulator by Fabrice Weinberg


Thanks to this good tooling it is now much easier to build applications for the ESPaper or other similar displays. This is another example where I connected to my Google Calendar to display upcoming events:

ESPaper Applicaton with Google Calendar Access – JSON rendered on the server


If you are interested have a look at the beta version of the code here:


The ESPaper modules are available here:

Posted by Daniel Eichhorn

Daniel Eichhorn is a software engineer and an enthusiastic maker. He loves working on projects related to the Internet of Things, electronics, and embedded software. He owns two 3D printers: a Creality Ender 3 V2 and an Elegoo Mars 3. In 2018, he co-founded ThingPulse along with Marcel Stör. Together, they develop IoT hardware and distribute it to various locations around the world.


  1. Interesting concept with the espaper-client … makes for very flexible setup …
    Any chance of seeing any other displays being (easily) supported than just the 2.9″ one? I have both a smaller (2.7 3-color) and a larger one I’d like to play around with, they both work fine with the GxEPD library … configuring the right size and correct pins in your client library did not get me any output … I’ve not dug into the libraries and functions, but given that the displays are from the same manufacturer, and GxEPD (apparently) also supporting the 2.9″ you use, what would need to be done to adapt it to the other displays?

    • Just this week I received a 3-color version. I will have a look at it. If they are just using 2-bit per pixel as compared to 1-bit in the monochrome then the adaptation should be easy. Also the library as well as the ESPaper server are built with other display sizes and bit depths in mind, so it should not be hard to extend it to those…

      • Tnx for the feedback … I was just wondering how different the addressing of the different boards are, as the 2.7″ doesn’t do anything, not even clear the screen … willing to do some tests and give you feedback if you want me to try any code …

  2. Hi, I just found this project and looks amazing. Do you have the Calendar project documentation? I would like to attach something similar to this to my fridge so I see it every morning.

Leave a Reply