Understanding waveform

The waveform is a look up table for the EPDC to determine how to drive the pixels.

The waveform file is independent to the resolution. So for example the device has a 1024x758 screen, and one could drive the screen with a waveform designed for a 800x600 screen. As we would see later the waveform had nothing to do with the resolution, it only cares about single pixel. With an incorrect or un-optimal waveform, the screen should at least display some recognizable image.

Waveform modes

The waveform provided by Eink has many modes. There is a good document from Eink describing the modes:

https://www.waveshare.net/w/upload/c/c4/E-paper-mode-declaration.pdf

It provides a good overview of the modes. I am just going to add some comments.

• These is no 16 level greyscale modes without flashing. DU4 is the only greyscale mode that's non-flashing. However it is considerably slower than A2 (monochrome) mode.
• GL16 mode, as described, only works for black text on white background. When refreshing greyscale images, GL16 is bascially the same as GC16.
• GLR16 mode is also called REGAL mode, and GLD16 mode is also called as REGAL-D mode.
• KOReader calls the REGAL mode as the REAGL mode. Not sure if it was on purpose or just mistake. (Google search REAGL site:eink.com returned nothing, while REGAL site:eink.com returned several product information, so I am assuming REGAL is the correct spelling.)
• Eink provided waveform usually implements all these modes, however it is not always required. For example, reMarkable 1's waveform doesn't follow that list.
• It is kind of sad most Eink monitors would only utilize GC16 mode and A2 mode, and uses A2 for the most of the time. Even though they could use GL16/GLR16/GLD16 mode when displaying text, but it seems like no one is doing that. But again, this usually requires the software to be aware of these modes and pick the right mode, which is hard for a generic Eink monitor.

Waveform formats

The waveform distributed by Eink is usually in .wbf format, while the i.MX SoC uses a converted binary format. There are several generations of EPDC:

EPDC in i.MX50 EPDCv1/ EPDC in i.MX6DL/SL EPDCv2 in i.MX6SLL/ULL, i.MX7D, and i.MX8ULP

Note: NXP's documentation suggests that the EPDC in i.MX6ULL is not as powerful as the one in i.MX6SLL/ i.MX7D, but it still uses the EPDCv2 driver. EPDCv2 driver also supports EPDCv1. The main difference between EPDC driver and EPDCv2 driver is that the v2 driver doesn't use IPU.

NXP has tool to convert from .wbf to .fw, which (I assume) could be obtained after signing an NDA with NXP.

The .fw in EPDCv1 and EPDCv2 are not compatible. The tool provided in the repo could handle both.

There are also difference in terms of bit depth. There are 4bpp waveform and 5bpp waveform. Note 5bpp waveform doesn't mean it supports 32 level of greyscale, it only means it uses 5bpp internally to represent pixel states. Usually 5bpp waveforms only supports 4bpp (16 level) greyscale.

5bpp waveform is natively supported on i.MX7D EPDCv2 drivers, but not in eariler i.MX6 EDPC drivers. Technically this could be done: https://github.com/reMarkable/linux/commit/1817e72e30bfb426dcd7f9139610e6e98f3f7d77#diff-9ae293778274bb0c250df114b514f6f703586a613f1309b380fdf640c7651d99. Note it seems like all new waveforms released by Eink is 5bpp.

Waveform details

Now looking deeper into the waveform. It's a LUT with 3 dimensions: old greyscale value, new greyscale value, and time. Typically a system would have multiple waveform tables for different temperatures and waveform modes.

There are several sample waveform tables provided in the project repo. Take the GC16 (Greyscale clearing 16-level) waveform of GDEW101C01 as an example: https://github.com/zephray/NekoInk/blob/master/waveform/gdew101_gd/test_M2_T0.csv

Take one line from that file:

6,13,0,0,0,0,0,0,0,0,0,2,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,0

This means from greyscale level 6 to level 13, it needs to go through the following sequence. Each number means the operation on that frame, 0 is no-operation, 1 is darken, and 2 is lighten. In this case, there are 38 frames, first 9 frames do nothing, then lighten for 1 frame, darken for 10 frames, lighten for 16 frames, and finally darken for 1 frame and no-operation for the last frame. This is the sequence to change a pixel from level 6 to level 13. Such lookup is done for every pixel on every frame.

Building waveform

Contact the screen vendor for the screen waveform. Or you might be able to modify based on the GDEW101C01 waveform provided. Alternatively, NXP provided serveral waveforms in their demo package release. Some might work for your screen.

To assemble the waveform from human readable format (iwf and csv) to binary fw file, use the mxc_wvfm_asm tool provided in the repo