Automatic "safe display mode" for e-ink devices

[david-allison]

There is a growing number of e-ink devices which are Android based, and AnkiDroid is a common use-case for these devices.

We should look into a library (or roll our own) to detect e-ink devices, and enable "safe display mode" by default

We should take care around backing up this preference, as restores from phone <-> e-ink would produce undesired functionality

Sample - Viwoods AiPaper

Manufacturer = Viwoods

Model = Viwoods AiPaper

Hardware = mt8788

Webview User Agent = Mozilla/5.0 (Linux; Android 13; Viwoods AiPaper Build/TP1A.220624.014; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/101.0.4951.74 Safari/537.36

[Aditya13s]

@david-allison There is no method present in the Display class to check the display type, but the refresh rate of an e-ink display is very low, and Android provides a method to fetch the screen refresh rate.

https://stackoverflow.com/questions/15221787/android-how-to-detect-an-e-ink-screen

[david-allison]

@Aditya13s Check the comments on the answer:

I get 16.0, 46.0, 68.0, 90.0 on four different Eink devices. I haven't ever seen anything lower.

[Aditya13s]

We can show an option on the onboarding screen to check if the display is e-ink or not

[david-allison]

Don't ask the user anything during onboarding which they don't need. They're already facing information overload and it should be due to high-value knowledge.

Question 1: Is there a library which already exists?
Question 2: If not, do we have the capacity to quickly build one which works for the majority of our users?

• IMO: yes. All it would take is a small allowlist of known devices/manufacturers (Boox), you could get reasonably good coverage in a day, and offload a lot of the long-term maintenance to the community
• It takes a few minutes to add a device, and a few years to make one

[mikehardy]

seems like a "likely e-ink device" list from some mix of android.os.Build items is reasonable

It will likely be small. I haven't seen any library, I imagine just a lookup table in our repo is fine

What's the feature look like?

• if we have no e-ink prefs entry indicating we've presented this dialog to the user yet or we have one but the associated hardware elements have changed
• and we detect it is likely an e-ink device by lookup in our list or we are set to e-ink but the hardware no longer seems like e-ink
• then pop a dialog to the user at some point (maybe first thing?) saying:
  • if it seems like e-ink it looks like you are using an e-ink device and we recommend enabling e-ink mode? checkbox default enabled
  • if it seems like it is no longer e-ink: it looks like you are no longer using an e-ink device, and we recommend disabling e-ink mode? checkbox default disabled
• store both the selected setting and some sort of representation of the various android.os.Build elements that identifies the device

That way on first install on e-ink we get the user into the right mode, or if there is some backup/restore and the setting no longer seems appropriate in either direction we prompt again

Testing the feature could be done with an advanced prefs developer options toggle that sets a preference indicating the Android emulator should be detected as e-ink or not. That way a tester could check "altering the hardware" to switch from e-ink and back to see how the dialog shows up ?

[Scapesfear]

@david-allison can you assign this issue to me ?

[david-allison]

@Scapesfear what's your plan of action here?

[Scapesfear]

1. I will use Display.getRefreshRate() to get the screen refresh rate.
   E-ink devices typically have low refresh rates (e.g., below 50Hz).

2. I will create a method (isEinkDevice()) that checks if the refresh rate is below a defined threshold (e.g., 50Hz).
   If the refresh rate is below the threshold, I will return true indicating it’s an e-ink device.

3. If isEinkDevice() returns true, I will enable safe display mode.
   I will adjust the UI for e-ink devices by disabling animations, using high contrast, etc.
   Store Preferences:

and anything more that will be wanted

[david-allison]

As discussed above. 1 isn't feasible

[Scapesfear]

okay so we have few options then

1. we can prompt user in the start of the application to ask if it is an e-ink device and then remeber that
2. we can create our own simple lookup file for most used e-ink device( but this is not a very scalable idea ig ) , and if it is in the lookup table then enablesafemode and if not just ask
3. we can make a library or a class which tracks different attribute , such as refresh rate ,the model and manufature using the lookup table ,or other attributes like Responsetime(sensitivity and latency) , colorsupport, DPI etc.

[Scapesfear]

or maybe a hybrid of all of these , first lookup table if not found , try to track , if not clear form that ask , and if user says its e-ink save that to the lookup or database

[BrayanDSO]

How much impactful are animations under displays with higher refresh rates? Is it enough for people to prefer having them disabled?

Are the app animations disabled when the system global animations setting is disabled?

[Scapesfear]

@BrayanDSO speaking from user prespective , i think animation make the user expierience better for high end devices and it feels smooth

[david-allison]

How much impactful are animations under displays with higher refresh rates? Is it enough for people to prefer having them disabled?

Anecdotally, and from memory: yes. I'd also be concerned that the OS is misreporting the value here. e-ink doesn't have a refresh rate in the same way that an LCD would. You're not going to get 60/90 FPS on an e-ink and this these values are reported above

Longer-term: I want to push for a few e-ink specific improvements to the whiteboard/drawing, which will further increase the utility of this setting

Are the app animations disabled when the system global animations setting is disabled?

Some: navigation drawer still opens and closes with animation regardless of the system setting. It opens better with safe display, but still closes with an animation

[Scapesfear]

Hi @david-allison ,

I’ve been reflecting on this issue, and I wanted to check if you think the hybrid approach I suggested—using a lookup table first, attempting to infer attributes like refresh rate, DPI, or manufacturer, and prompting the user as a fallback—is practical and aligns with your vision.

Would you recommend refining this idea further, or do you have specific guidance or areas you think I should explore to make this solution more robust? I’d love to hear your thoughts and improve on this!

[BrayanDSO]

IMO, just make a list of eink devices based on the manufacturer and/or model and set the preference to true after installing the app. AFAIK, it's the most reliable approach, since Android apparently doesn't provide any kind of API for knowing that (and manufacturers may not comply to one if there was one).

I'm still against any kind of prompt. 99.9% of people don't use a Eink device, and the eink users may not even get bothered enough with the animations

[Scapesfear]

okay so i will make a list of eink devices based on the manufaturer and model set the the preference true , so can you assign me this issue to work on ?

[david-allison]

Copied my thoughts from Discord:

Ok... list of Boox models: https://github.com/Hagb/decryptBooxUpdateUpx/blob/162c29f99bc6b725d1be265cfc17359aa5b55150/BooxKeys.csv#L46
The manufacturer list [provided in the PR] might not be perfect, but that's enough for a good first shot at the issue, I'm fine with that as a heuristic

Now we have:

• List of manufacturers which have e-ink devices (maybe incorrect)
• List of models for ONYX, without manufacturer (imprecise)
• Two known 'good' devices

If I were a betting man...

• If device matches (manufacturer, model): it's an e-ink
• If device matches EITHER (_, model), or (manufacturer, _), then report it as a silent exception to our crash reporting, for a developer to evaluate and fix the inclusion/exclusion criteria. Crash reports like this are only sent once, and I expect we don't have that many e-ink devices (maybe ~30k)?
• If a device doesn't match. Do nothing

This also seems like a goldmine to bootstrap our list of devices: https://github.com/koreader/android-luajit-launcher/blob/6bba3f4bb4da8073d0f4ea4f270828c8603aa54d/app/src/main/java/org/koreader/launcher/device/DeviceInfo.kt#L427