Kobo Clara HD (kobo-clara)

== Contributors ==
* MartijnBraam
* Andi
== Users owning this device ==
== Warning == 
There seem to be different versions out there with different pmic setup, apparently even at the same i2c address, so make
sure you know what you are doing. Approved board revisions are at least: 37NB-E60K00+4A4. 
See 
The devicetree in the downstream kernel is imx6sll-e60k02.
For 37NB-E60K00+4B0 it is imx6sll-e60k02b00. There is now autodetection code in u-boot to sort that out, so
no mixing up of 3.3V vs. 1.8V and similar regulators should happen.
Report anything else appearing in the wild.
== Installation ==
An original Kobo Clara SD card or a copy (e.g. via dd) is recommended. The unpartitioned space at the beginning of the SD card contains the E-ink panel waveform information. This information is device specific and is copied to /lib/firmware/imx/epdc/epdc.fw on boot. See the original Pull Request for more information.
=== Replacing internal µSD ===
Internal µSD card can be replaced by something bigger. 
A recommended practice to install software is to clone the SD card and keep the old one as backup or have at least the hidden waveform partition in place. before doing pmbootstrap install
So basically pull out µSD and connect to your PC and do:
 dd if=/dev/sdX of=clara-backup.img
replace with something bigger (in reality only the waveform is needed but for simplicity) and do:
 dd if=clara-backup.img of=/dev/sdX
and then use that sdcard with pmbootstrap install --sdcard
== Hardware ==
=== Wireless ===
The Kobo Clara contains the Realtek RTL8189FTV, a 802.11bgn 2.4G single-chip solution. Using the mainline kernel this is supported by the RTL8189fs branch of this repo. Note this prints a lot of information to dmesg (prefixed with 'RTL871X').
=== Display ===
The Kobo Clara features "ComfortLight PRO" which allows you to adjust the brightness or temperature of your screen. This is supported in the mainline kernel under /sys/class/backlight which exposes backlight_warm and backlight_cold. The brightness can be adjusted by echoing a value (0 to 255) to brightness in these directories.
 echo 10 | sudo tee /sys/class/backlight/backlight_warm/brightness
With mainline kernel, a drm interface is created, it should work out of the box, even textmode console should work. Waveform needs to be available before module is probed which might not be the case on first boot. With vendor kernel, only /dev/fb0 is created and special userspace is required to call vendor ioctls for refreshes.
=== USB ===
By default the USB port is in gadget mode. This enables rdnis (USB networking) and storage when plugged into a PC.
The USB can be changed to host mode, allowing a keyboard or storage to be plugged in. This requires a Micro USB OTG adapter. As root, you can change the USB role.
 echo gadget > /sys/bus/platform/devices/ci_hdrc.0/role
Note: For some devices, external power may be required via the USB adapter.
=== UART ===
UART (3.3V) is available on J4. This is located near the edge of the PCB on the top right (with the USB at bottom). The default baudrate is 115200 (8N1).
There is a second UART next to it (TP198)
== Software ==
=== GUI support ===
==== Display servers ====
Xorg is recommended for now - Gnome Shell and at least some wlroots-based DMs share the issue described here
==== Display managers ====
TinyDM is recommended and just works.
GDM can work if you make it use Xorg (due to earlier mentioned Wayland bug).
SDDM (Xorg mode) does not seem to start.
==== SXMO ====
Recommended - for configuration details, see Using_ebook_reader_hardware
Device profile (WIP):
 export SXMO_DISABLE_LEDS="1"
 export SXMO_MONITOR="Unknown-1"
 export SXMO_POWER_BUTTON="1:1:gpio-keys"
 export SXMO_SWAY_SCALE="2.5"
 export SXMO_TOUCHSCREEN_ID="2"
Recommended to set Xorg DPI to 300.
==== AIR ====
Recommended - a set of customized scripts for AwesomeWM, the author uses them on a Clara HD. See here
==== Gnome ====
Runs but too heavy on CPU to work properly, when trying to do basic operations.
==== Plasma Desktop ====
Does not run, looks like it's short on RAM.
==== Other ====
Mobile DEs need to be tested, but they likely require GPU acceleration.
== See also ==
=== Sources ===
* U-boot and kernel source
* Upstream Devicetree Source (dts) 
* branches kobo/merged-5.X Patched mainline kernels (includes EPD), currently kobo/merged-5.14
* branch kobo-2020-10 more recent u-boot behaving more normal, see corresponding wiki for details
* Wi-Fi driver, branch rtl8189fs
=== Applications ===
* InkBox, Open-source Alpine based firmware for Kobo E-readers, mirror on Github.
=== Other ===
* Archived Kobo Firmware
* Blog with Kobo Clara information
* Xorg on Kobo default firmware
* E-reader information
* Some installation notes/mainlining status information
* Electronic Paper Displays (EPD) / E-ink introduction
* E-ink waveforms
== Almost identical device ==
* Tolino_Shine_3 - this has the same board, uses the I.MX6 SoloLite SoC instead of the I.MX6 SLL, which has some subtle differences, like different version of the EPDC inside
== Similar devices ==
* Tolino_Shine_2HD_(tolino-shine2hd) - similar mainline status with above-mentioned kernel
* Kobo Glo HD - will probably be in a similar state with above mentioned kernel if a devicetree is created