ADDITIONAL SYSTEM INFORMATION :
I propose starting with the Kobo Touch Models N905B and N905C, which have either an NXP i.MX507 or i.MX508 processor based on the ARM Cortex-A8 core. These are the oldest and least powerful devices still supported by Kobo with system updates <https://pgaskin.net/KoboStuff/kobofirmware.html>. Once the implementation is stable, other more powerful models can be added, such as the Kobo Glo HD with an i.MX6SL processor and the Kobo Clara HD with an i.MX6SLL processor, each based on the ARM Cortex-A9 core.

Given that plan, the first test system is a Kobo Touch Model N905C with an 800-MHz i.MX507 Multimedia Application Processor Model MCIMX507CVM8B and 256 MB of RAM. This processor has an ARM Cortex-A8 core implementing the ARMv7-A architecture. The system runs Ubuntu Base 14.04.5 LTS (Trusty Tahr) in a chroot environment.

    $ uname -a
    Linux koboa 2.6.35.3-850-gbc67621+ #619 PREEMPT
    Thu Dec 22 15:29:00 CST 2016 armv7l armv7l armv7l GNU/Linux

    $ ldd --version
    ldd (Ubuntu EGLIBC 2.19-0ubuntu6.14) 2.19

    $ getconf GNU_LIBPTHREAD_VERSION
    NPTL 2.19

    $ $HOME/opt/jdk-12-client/bin/java -version
    openjdk version "12-internal" 2019-03-19
    OpenJDK Runtime Environment (build 12-internal+0-adhoc.ubuntu.jdk)
    OpenJDK Client VM (build 12-internal+0-adhoc.ubuntu.jdk, mixed mode)

The screen is a 6-inch E Ink Pearl display panel with a resolution of 800 x 600 pixels and a density of 167 pixels per inch, supporting up to 16 levels of gray (4-bit grayscale).

A DESCRIPTION OF THE PROBLEM :
Note: This request is an identical copy of the same request on GitHub, edited only for formatting <https://github.com/javafxports/openjdk-jfx/issues/339>.

SUMMARY

This is a request for JavaFX to support devices with electrophoretic displays, commonly known as electronic paper displays, with a new Monocle platform called "EPD."

GOALS

The ultimate goal of this request is to be able to run a JavaFX application on a device with an e-paper display by simply installing the Ubuntu OpenJFX package for the armhf architecture. That goal includes:

- making it easy to develop application software for e-paper that can also run on desktop platforms without having to recompile or modify the source code in any way;

- having a method to enable the black-and-white animation capabilities of e-paper, with frame rates up to eight frames per second (120 ms per frame).

NON-GOALS

The following are specifically out of scope for this request:

- It is not a goal to allow any JavaFX application to work well on e-paper displays. These displays have inherent limits in grayscale levels and frame rates, so some applications written for LCD screens may never be appropriate for them.

- It is not a goal to provide a JavaFX programming interface to the lower-level features of e-paper. These features can be selected based on the application by setting specific system properties when launching it. Allowing for runtime changes to the system properties could be added later.

- It is not a goal to support all classes of devices with e-paper displays, but rather to start with just one. That first implementation can form the basis for others to be added later.

SUCCESS METRICS

One measure of success would be running a JavaFX animation program on an e-paper display at eight frames per second and delivering the correct touch screen input events to the program.

MOTIVATION

The motivation for this request comes from a work of art by Joseph Farbrook exhibited at the SIGGRAPH 2014 Art Gallery and part of a series called Lineographs <http://s2014.siggraph.org/attendees/art-gallery/events/lineographs.html>. See the artist's website for a brief description of the work and a one-minute video demonstration <https://www.farbrook.net/lineographs/>. The video is also available directly on YouTube as Dancer <https://youtu.be/nCKPZuK8XyI>.

The artwork was remarkable in at least two ways. First, it was stunningly simple, using a device that emits no light, makes no sound, and employs the most minimal user interface. Among the bright screens and loud noises of the SIGGRAPH Conference, it was a passive and silent wonder -- an ink drawing that came to life with a touch. Secondly, few people knew at the time that e-paper could display animations. Electronic ink was invented in 1997 <https://www.invent.org/inductees/search?company_tid=1167>, and the first commercial e-reader introduced in 2004, but it wasn't until 2012 that a patent application described the various waveform modes, including one for fast black-and-white animation <https://patents.google.com/patent/US9280955B2>.

When I looked into writing my own software for e-paper, I found the information buried deep in archives of documents for embedded processors. The documents are helpful, and improve with each revision, but they describe only a C-language interface to the Linux frame buffer device and some IOCTL codes. I was looking for a way to write the software in a higher-level language with libraries for graphics, threads, and networking. I was hoping to test the programs on my workstation and run them unmodified on the device without having to use cross-compilers or emulators. In short, I wanted an interface in Java.

DESCRIPTION

The device driver for an Electrophoretic Display Controller supports the programming interface of the Linux frame buffer device with one key caveat: the contents of the frame buffer are not automatically updated to the display. The Monocle Linux platform in JavaFX already provides software rendering to the Linux frame buffer and can be extended to provide support for e-paper displays.

I propose a new Monocle platform, named EPD, that allows a JavaFX application to run on a device with an Electrophoretic Display Controller (EPDC) frame buffer driver. To select the platform, the application is started with the system properties:

    $ java -Dglass.platform=Monocle \
        -Dmonocle.platform=EPD -Dprism.order=sw ...

Additional system properties for the EPD platform are described below in three groups: settings for the Linux frame buffer device, general display update settings, and update flags.

Frame Buffer Device

- monocle.epd.bitsPerPixel

sets the frame buffer color depth and pixel format: 8 for 8-bit grayscale in the Y8 pixel format, 16 for 16-bit color in the RGB565 pixel format, or 32 for 32-bit color in the ARGB32 pixel format. The default is 32.

    Using the 32-bit format allows JavaFX to render directly into the Linux frame buffer, avoiding the step of converting and copying each pixel from an off-screen composition buffer.

- monocle.epd.rotate

sets the frame buffer rotation: 0 for unrotated (UR), 1 for 90 degrees clockwise (CW), 2 for 180 degrees upside-down (UD), and 3 for 90 degrees counter-clockwise (CCW). The default is 0.

    The unrotated and upside-down settings are in landscape mode, while the clockwise and counter-clockwise settings are in portrait.

- monocle.epd.y8inverted

sets an indicator for the frame buffer grayscale value: true to invert the pixels of all updates when using an 8-bit frame buffer in the Y8 pixel format; otherwise false. The default is false.

    The value is ignored when the frame buffer is not set to the Y8 format.

Display Updates

- monocle.epd.noWait

indicates whether to wait for the previous update to complete before sending the next update: true to avoid waiting and send updates as fast as possible; otherwise false. The default is false.

    The number of outstanding updates is limited by the device controller and allows for 16 or 64 concurrent non-colliding updates, depending on the model. A value of true can provide updates exceeding eight frames per second but may result in errors if the frame rates or pixel collisions cause the limit to be exceeded.

- monocle.epd.waveformMode

sets the waveform mode used for updates: 1 for black-and-white direct update (DU), 2 for 16 levels of gray (GC16), 3 for 4 levels of gray (GC4), 4 for pure black-and-white animation (A2), and 257 for the automatic selection of waveform mode based on the number of gray levels in the update (AUTO). The default is 257.

    Automatic selection chooses one of 1 (DU), 2 (GC16), or 3 (GC4). If the waveform mode is set to 2 (GC16), it may be upgraded to a compatible but optimized mode internal to the driver, if one is available.

Update Flags

- monocle.epd.enableInversion

sets the update flag for pixel inversion: true to invert the pixels of each update; otherwise false. The default is false.

- monocle.epd.forceMonochrome

sets the update flag for monochrome conversion: true to convert the pixels of each update to pure black and white using a 50-percent threshold; otherwise false. The default is false.

- monocle.epd.useDitheringY1

sets the update flag for 1-bit dithering: true to dither each update in an 8-bit Y8 frame buffer to 1-bit black and white, if available; otherwise false. The default is false.

- monocle.epd.useDitheringY4

sets the update flag for 4-bit dithering: true to dither each update in an 8-bit Y8 frame buffer to 4-bit grayscale, if available; otherwise false. The default is false.

The EPDC drivers on the NXP i.MX6SL and i.MX6SLL processors support software dithering, while the i.MX7D supports dithering in hardware. Dithering is not available on the i.MX507 and i.MX508 processors.

Messages are logged using the "javafx" system logger with the following levels:

- java.util.logging.Level.SEVERE (java.lang.System.Logger.Level.ERROR)
- java.util.logging.Level.FINE (java.lang.System.Logger.Level.DEBUG)
- java.util.logging.Level.FINER (java.lang.System.Logger.Level.TRACE)

ALTERNATIVES

There are three main alternatives to providing the support in JavaFX:

- Qt for Embedded Linux is a C++ framework for writing user interfaces on embedded devices and is the most common solution for developing applications for e-paper displays. One of the goals of this request is to be able to run software for the device unmodified on the desktop, so this rules out a C++ framework. There is Qt for Python, but it is supported only on the three major desktop platforms, and plans to support embedded platforms are in their earliest stages <https://blog.qt.io/blog/2018/12/18/qt-python-5-12-released/>.

- Java Swing can run in a headless mode <https://www.oracle.com/technetwork/articles/javase/headless-136834.html>, where a JPanel could function as an off-screen buffer that is copied into the Linux frame buffer. Although it's certainly worth exploring, this approach would require changes in the application source code to allow it to run in a window on the desktop. Swing also lacks support for input devices in a headless environment.

- Dart and Flutter could be another alternative, but the work to add desktop support is "an exploratory effort, and is not part of the Flutter project." <https://github.com/google/flutter-desktop-embedding>

Among the popular cross-platform toolkits of Qt, Swing, JavaFX, and Flutter, only JavaFX supports both desktop computers and embedded devices with a single executable file.

TESTING

The closest I have found to an inexpensive general-purpose computer with an e-paper display is one of the Rakuten Kobo e-readers <https://us.kobobooks.com/collections/ereaders>, shown on that page with pricing in U.S. Dollars. (See the Canada website for pricing in Canadian Dollars <https://ca.kobobooks.com/collections/ereaders>.) Older used Kobo e-readers, such as the Kobo Touch, can be found for less than 40 USD, and newer refurbished models sell for less than 70 USD from Rakuten on eBay <https://www.ebay.com/usr/rakutenkobo>.

On the other hand, the E Ink ICE evaluation kit with a 6-inch display costs 449 USD and is not intended for personal or household use <https://www.eink.com/kits.html>. "Orders placed by consumers will not be accepted," says the notice at the E Ink Shop.

The advantage of a Rakuten Kobo over an Amazon Kindle is that you don't need to jailbreak the device for access. A single setting added to a configuration file ("Kobo eReader.conf") enables root access with the telnet command:

    [DeveloperSettings]
    EnableDebugServices=true

Once logged in, it's relatively easy to create a chroot environment with a small Ubuntu Base image and to set up Ethernet over USB. You then have a stable high-speed connection with over 45,000 open-source packages ready to install -- including OpenJDK and OpenJFX -- already compiled for the armhf architecture. If necessary, you can emulate everything but the display on a regular Linux workstation by running Ubuntu in a QEMU virtual machine with the armv7l architecture.

Furthermore, all of the source code for the Linux kernel, the EPDC frame buffer drivers, and related software is posted in the Kobo-Reader repository on GitHub <https://github.com/kobolabs/Kobo-Reader>. Of course, you can also use the Kobo e-reader to read books <https://standardebooks.org/>.

RISKS AND ASSUMPTIONS

There is the risk of Kobo devices being locked down or discontinued, making the development of this enhancement more difficult and expensive. In addition, this request is tied to the current technology for electronic paper <https://en.wikipedia.org/wiki/Electronic_paper>, the microencapsulated electrophoretic display, creating the risk of a new technology taking over the market and making the implementation obsolete.

In the long run, both of these events are likely to occur as companies, markets, and technologies change. Meanwhile, the Kobo e-reader is distributed globally, has the leading market share in Canada, and is second to the Kindle in market share worldwide. The current E Ink technology was invented in 1997 and has yet to be replaced, despite many well-funded efforts to do so.

DEPENDENCIES

The implementation of this request should avoid making changes to the current JavaFX source code so that it may be added without any risk of causing errors in the existing features.