Louwrentius

Introduction

Update September 2023: A small horizontal and large vertical row of pixels died. Demo of defective display here.

I'm running a solar-powered blog and I wanted to add a low-power display to show the daily solar 'harvest'¹ and maybe some additional information.

So I decided to use an e-paper display. I wanted a display that would be readable from a distance, so bigger would be better. I therefore chose the Waveshare 12.48 inch e-paper display².

an example based on data from the summer, generated with Graphite

This particular display costs $179 excluding taxes and shipping at the time this article was written.

Specifications

Waveshare sells a two-color (black and white) and a three-color version (black, white, red). I bought the three-color version. The three-color version is the (B) model.

Specifications:

Screen size     :      12.48 inches
Resolution      :      1304 x 984
Colors          :      black, white, red
Greyscale       :      2 levels
Refresh rate    :      16 seconds
Partial refresh :      Not supported
Interfaces      :      Raspberry Pi, ESP32, STM32, Arduino

The two-color variant of this display has a refresh rate of 8 seconds.

This display is clearly quite slow. Furthermore, the lack of partial refresh support could make this display unsuitable for some applications. I was OK with this slow refresh rate.

The image below demonstrates different fonts and sizes. I think DejaVuSansMono-Bold looks really well on the display, better than the font supplied by Waveshare.

The Interfaces

The display includes a microcontroller that in turn can be driven through one of four interfaces:

1. A Raspberry Pi (Worked)
2. An ESP32 (Not tested)
3. An Arduino (Didn't work)
4. An STM32 (Not tested)

I've tried the Arduino header with an Arduino Uno, but the supplied demo code didn't work. I did not investigate further why this was the case. It could be a problem with voltage regulation.

In the image above, the black plastic backplate is removed.

Image quality

These e-paper displays are mostly sold as product information displays for supermarkets and other businesses. However, the quality is good enough to display images. Especially the support for red can make an image stand out.

Below is an example of an image that incorporates the third (red) color.

The display seems suitable to display art.

It looks quite good in real life (sorry for the glare).

How the display shows three colors

The display acts like it is actually two displays in one. A black and white display, and a red and white display.

First, the black and white image is drawn. Next, the red and white image is put on top.

Because the display has to draw two images in succession, it takes 16 seconds to refresh the screen. This explains why the black-and-white version of this screen does a refresh in eight seconds: it doesn't have to refresh the red color.

Please note that the entire process of displaying content on the screen takes much longer.

A demonstration:

Displaying an image is cumbersome (On Raspberry Pi 3B+)

At the time this article was written, I could not find any information or tools for this display³.

Many Waveshare e-paper displays are popular and have a decent community support. However, it seems that this display is rather unknown.

Therefore, it seems that there are no tools available to display an arbitrary image on this display. You can use the example Python code to display an image but you have to follow these steps:

1. Create a black-and-white version of the image
2. Create a red-and-white version of the image, that contains only data for the red parts of the image
3. If the source image doesn't match the required resolution, you have to resize, crop and fill the image where appropriate.

Both 'black' and 'red' images need to exactly match the resolution of the display (1304x984) or the library will abort with an error.

As I found this proces tedious, I automated it.

A new tool to make displaying an image easy

I've used the python library as supplied by Waveshare and created a command-line tool (Github) on top of it to perform all the required steps as described in the previous section. I'm using Imagemagick for all the image processing.

The script works like this:

./display -i <image file> [--rotate 90] [--fuzz 35] [--color yellow]

The --fuzz and --color parameters may require some clarification.

The color red is extracted from an image but it's not always perfect. By applying the --fuzz parameter (the argument is a percentage), it is possible to capture more of the red (or selected color) of an image.

The --color option specifies which color should be 'converted' to red. By default this color is 'red' (obviously). The 'solar chart' (at the start of this article) is an example where a yellow line was converted to red.

Very slow: it takes about 55 seconds to display an image using the Raspberry Pi 3B+. Half of that minute is spend converting the images to the appropriate format using Imagemagick.

Informational: The Python program includes a modified version of the Waveshare Python library. This library has been altered to prevent double conversion of images, which significantly degrades image quality.

Slow performance

If you use the provided Python library (Python3 compatible) it takes about 30+ seconds to draw an image on the screen. (This excludes the image processing performed with the 'display' tool.)

Further testing showed that the Python library converts and dithers the image before it is sent to the display. And it does so for both black and red. Dithering is performed by looping in Python over every of the 1.3 milion pixels.

Each of these loops (for black and red) take about 10 seconds on the Raspberry Pi 3B+, which explains why it takes so long to update the display. Therefore, I think the combination of Python + the Raspberry Pi 3B+ is not ideal in this case.

Evaluation

I wanted to share my experience with this display to make other people aware of its existence. The tool I created should make it simple to get up and running and display an image.

It clearly has some drawbacks but due to the size, resolution and third color, it seems to be unique and may therefore be interesting.

Although I never tried the display with an ESP32, I think its an ideal for the purpose of a low-power picture frame.

This article was discussed on Hacker News (briefly). This resulted in about 9000 unique visitors for this article.

Appendix A - Remark on other displays

Please note: Waveshare also sells a smaller 10.3 inch black-and-white e-paper display for a similar price with some significant benefits:

Screen size     :      10.3 inches
Resolution      :      1872 x 1404
Colors          :      black and white
Greyscale       :      16 levels
Refresh rate    :      450 miliseconds
Partial refresh :      Supported

This particular display is smaller but has a higher resolution, supports 16 grayscale levels and updates in half a second. This display may better suit your particular needs. For example, I believe that this display may have been used in this project, a solar-powered digital photo frame.

Appendix B - How to make the display work on a Raspberry Pi

This information is straight from the Waveshare site but I include it for completeness and ease of use.

PART I: Enable the SPI interface with raspi-config

1. sudo raspi-config
2. select Interfacing Options
3. Select SPI
4. Select Yes
5. Reboot the Raspberry Pi

PART II: Install the required libraries

Install BCM283

Website

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

Install wiringPi

website

sudo apt-get install wiringpi
cd /tmp
wget https://project-downloads.drogon.net/wiringpi-latest.deb
sudo dpkg -i wiringpi-latest.deb
gpio -v

Caution: The library seems to be deprecated. The Raspberry Pi 4 is supported but future versions of the Raspberry Pi may not.

The wiringPi library is used as part of a compiled library called "DEV_Config.so" as found in the ./lib directory.

@raspberrypi:~/epaper_display $ ldd lib/DEV_Config.so 
    linux-vdso.so.1 (0x7ee0d000)
    /usr/lib/arm-linux-gnueabihf/libarmmem-${PLATFORM}.so => /usr/lib/arm-linux-gnueabihf/libarmmem-v7l.so (0x76f1e000)
    libwiringPi.so => /usr/lib/libwiringPi.so (0x76f00000)
    libm.so.6 => /lib/arm-linux-gnueabihf/libm.so.6 (0x76e7e000)
    libc.so.6 => /lib/arm-linux-gnueabihf/libc.so.6 (0x76d30000)
    libpthread.so.0 => /lib/arm-linux-gnueabihf/libpthread.so.0 (0x76d06000)
    librt.so.1 => /lib/arm-linux-gnueabihf/librt.so.1 (0x76cef000)
    libcrypt.so.1 => /lib/arm-linux-gnueabihf/libcrypt.so.1 (0x76caf000)
    /lib/ld-linux-armhf.so.3 (0x76f46000)

Install Python3 and required libraries

sudo apt-get update
sudo apt-get install python3-pip
sudo apt-get install python3-pil
sudo pip3 install RPi.GPIO
sudo pip3 install spidev

Apendix C - E-paper hacking

I see myself as a consumer and I don't have any desire to hack the display for lower refresh-rates or partial refresh support, with the risk of damaging the display in the process.

However one resource about this topic I find very informative is a video from the Youtube Channel "Applied Science" (By Ben Krasnow), called "E-paper hacking: fastest possible refresh rate".

Apendix D - Available libraries

Example code for all supported platforms can be found in this github location.

I also found this github repository that may support this display. This code (also) didn't work for me on my Arduino uno. This could be due to a voltage mismatch, but I'm not willing to solder and potentially destroy the display.

Apendix E - Links to other e-paper projects

Very large and expensive display (Medium paywall)

E-paper calendar

Solar-powered digital photo frame

Introduction

I made an offhand remark about technical debt to a friend and he interrupted me, saying: "technical debt is just bullshit". In his experience, people talking about technical debt were mostly trying to:

• cover up bad code
• cover up unfinished work

source¹

Calling these issues 'technical debt' seems to be a tactic of distancing oneself from these problems. A nice way of avoiding responsibility. To sweep things under the rug.

Intrigued, I decided to take a better look at the metaphor of techical debt, to better understand what is actually meant.

Tip: this article on Medium by David Vandegrift also tackles this topic.

A definition of technical debt

Right off the bat, I realised that my own understanding of technical debt was wrong. Most people seem to understand technical debt as:

"cut a corner now, to capture short-term business value (taking on debt), and clean up later (repaying the debt)".

I think that's wrong.

Ward Cunningham, who coined the metaphor of technical debt, wrote:

You know, if you want to be able to go into debt that way by developing software that you don't completely understand, you are wise to make that software reflect your understanding as best as you can, so that when it does come time to refactor, it's clear what you were thinking when you wrote it, making it easier to refactor it into what your current thinking is now.

In some sense, this reads to me as a form of prototyping. To try out and test design/architecture to see if it fits the problem space at hand. But it also incorporates the willingness to spend extra time in the future to change the code to better reflect the current understanding of the problem at hand.

... if we failed to make our program align with what we then understood to be the proper way to think about our financial objects, then we were gonna continually stumble over that disagreement and that would slow us down which was like paying interest on a loan.

The misalignment of the design/architecture and the problem domain creates a bottleneck, slowing down future development.

So I think it's clearly not about taking shortcuts for a short-term business gain.

It is more a constant reinvestment in the future. It may temporary halt feature work, but it should result in more functionality and features in the long run. It doesn't seem short-term focussed at all to me. And you need to write 'clean' code and do your best because it is likely that you will have to rewrite parts of it.

These two articles by Ron Jeffries already discuss this in great detail.

• Technical Debt
• Technical Debt? Probably not.

A logical error

Reading up on the topic, I noticed something very peculiar. Somehow along the way, everything that hinders software development has become 'technical debt'.

Anything that creates a bottleneck, is suddenly put into the basket of technical debt. I started to get a strong sense that a lot of people are somehow making a logical fallacy.

If you have technical debt, you'll experience friction when trying to ignore it and just plow ahead. The technical debt creates a bottleneck.

But then people reason the wrong way around: I notice a bottleneck in my software development process, so we have 'technical debt'.

However, because technical debt creates a bottleneck, it doesn't follow that every bottleneck is thus technical debt.

I think it's this flawed reasoning that turns every perceived obstacle into technical debt².

Maybe I'm creating a straw man argument, but I think I have some examples that show that people are thinking the wrong way around.

If we look at the wikipedia page about technical debt, there is a long list of possible causes of technical debt.

To site some examples:

• Insufficient up-front definition
• Lack of clear requirements before the start of development
• Lack of documentation
• Lack of a test suite
• Lack of collaboration / knowledge sharing
• Lack of knowledge/skills resulting in bad or suboptimal code
• Poor technical leadership
• Last minute specification changes

Notice that these issues are called 'technical debt' because they can have a similar outcome as technical debt. They can create a bottleneck.

But why the hell would we call these issues technical debt?

These issues are self-explanatory. Calling them technical debt not only seems inappropriate, it just obfuscates the cause of these problems and it doesn't provide any new insight. Even in conversations with laypeople.

A mess is not a Technical Debt

A blogpost by Uncle Bob with the same title³ also hits on this issue that a lot of issues are incorrectly labeled as 'technical debt'.

Unfortunately there is another situation that is sometimes called “technical debt” but that is neither reasoned nor wise. A mess.

...

A mess is not a technical debt. A mess is just a mess. Technical debt decisions are made based on real project constraints. They are risky, but they can be beneficial. The decision to make a mess is never rational, is always based on laziness and unprofessionalism, and has no chance of paying of in the future. A mess is always a loss.

Cunningham's definition of technical debt shows that it's a very conscious and deliberate process. Creating a mess isn't. It's totally inappropriate to call that technical debt. It's just a mess.

I think that nicely relates back to that earlier list from wikipedia. Just call things out for what they actually are.

Is quibbling over 'technical debt' as a metaphor missing the point?

In this blogpost, Martin Fowler addresses the blogpost by Uncle Bob and argues that technical debt as a metaphor is (still) very valuable when communicating with non-technical people.

He even introduces a quadrant:

This quadrant makes me extremely suspicious. Because in this quadrant, everything is technical debt. He just invents different flavours of technical debt. It's never not technical debt. It's technical debt all the way down.

It seems to me that Martin Fowler twists the metaphor of technical debt into something that can never be falsified, like psychoanalysis.

It's not 'bad code', a 'design flaw' or 'a mess', it's 'inadvertent & reckless technical debt'. What is really more descriptive of the problem?

Maybe it's just my lack of understanding, but I fail to see why it is in any way helpful to call every kind of bottleneck 'technical debt'. I again fail to see how this conveys any meaning.

In the end, what Fowler does is just pointing out that bottlenecks in software development can be due to the four stages of competence.

I don't think we need new metaphors for things we (even laypeople) already understand.

Does technical debt (even) exists?

The HFT Guy goes as far as to argue that technical debt doesn't really exists, it isn't a 'real' concept.

After decades of software engineering, I came to the professional conclusion that technical debt doesn’t exist.

His argument boils down to the idea that what people call technical debt is actually mostly maintenance.

So reincorporating a better understanding of the problem at hand into the code (design) is seen as an integral and natural part of software development, illustrated by the substitute metaphor of mining (alternating between digging and reinforcing). At least that's how I understand it.

Substituting one metaphor with another, how useful is that really? But in this case it's at least less generic and more precise.

Closing words

Although Cunningham meant well, I think the metaphor of technical debt started to take on a life of its own. To a point where code that doesn't conform to some Platonic ideal is called technical debt⁴.

Every mistake, every changing requirement, every tradeoff that becomes a bottleneck within the development process is labeled 'technical debt'. I don't think that this is constructive.

I think my friend was right: the concept of technical debt has become bullshit. It doesn't convey any better insight or meaning. On the contrary, it seems to obfuscate the true cause of a bottleneck.

At this point, when people talk about technical debt, I would be very sceptical and would want more details. Technical debt doesn't actually explain why we are where we are. It has become a hollow, hand-wavy 'explanation'.

With all due respect to Cunningham, because the concept is so widely misunderstood and abused, it may be better to retire it.