summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorAgathe Porte <microjoe@microjoe.org>2020-03-27 14:23:35 +0100
committerAgathe Porte <microjoe@microjoe.org>2020-03-27 20:37:22 +0100
commit45461f7b9e51649ba559f24a3584edca979d169b (patch)
treed0dc8206ac5a2de065b860d994cd94192c72a73f /README.md
parent7ef0bae79a2e25fad5e67237c316a908ec6705a7 (diff)
downloadcharlcd-45461f7b9e51649ba559f24a3584edca979d169b.tar.gz
charlcd-45461f7b9e51649ba559f24a3584edca979d169b.zip
populate README and include it in module-level doc
Diffstat (limited to 'README.md')
-rw-r--r--README.md62
1 files changed, 60 insertions, 2 deletions
diff --git a/README.md b/README.md
index db1ce13..d96972d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,61 @@
-# charlcd
+A rust crate to interact with the mainline Linux charlcd.c driver.
-Rust library for charlcd.c Linux driver.
+Or, said boldly: _a crate to **correctly** interact with HD44780 LCD
+screens on embedded Linux devices_.
+
+![Photo of a test on HD44780 20x4
+screen](https://crates.microjoe.org/charlcd/media/docs/test.jpg)
+
+A lot of developers are relying on userspace libraries to interact with the
+very popular HD44780 LCD screens, but these implementations are lacking
+proper abstractions and usually all reimplement the same communication
+protocol to interact with the screen over and over.
+
+This approach seems just wrong if you consider what the Linux kernel can
+provide in comparison. Indeed, it is the role of device drivers to properly
+abstract the access to the hardware from userspace perspective. For this,
+the Linux kernel uses an absraction mechanism to declare the hardware:
+the *device-tree*.
+
+The *device-tree* nodes for a screen behind an I2C GPIO expander would look
+like the following:
+
+```dts
+&i2c0 {
+ status = "okay";
+
+ pcf8574a: i2c0@3f {
+ compatible = "nxp,pcf8574a";
+ reg = <0x3f>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+};
+
+auxdisplay: auxdisplay {
+ compatible = "hit,hd44780";
+
+ data-gpios = <&pcf8574a 4 GPIO_ACTIVE_HIGH>,
+ <&pcf8574a 5 GPIO_ACTIVE_HIGH>,
+ <&pcf8574a 6 GPIO_ACTIVE_HIGH>,
+ <&pcf8574a 7 GPIO_ACTIVE_HIGH>;
+ rs-gpios = <&pcf8574a 0 GPIO_ACTIVE_HIGH>;
+ rw-gpios = <&pcf8574a 1 GPIO_ACTIVE_HIGH>;
+ enable-gpios = <&pcf8574a 2 GPIO_ACTIVE_HIGH>;
+ backlight-gpios = <&pcf8574a 3 GPIO_ACTIVE_LOW>;
+
+ display-height-chars = <2>;
+ display-width-chars = <16>;
+};
+```
+
+Once the device-tree is correctly configured, the `charlcd` driver will
+create a `/dev/lcd` character device.
+
+The role of this library is to provide an astraction over this character
+device entry, while letting the kernel driver implement the communication
+with the screen — instead of going from scratch and using ioctl over
+`/dev/i2c-*` like many other libraries do.
+
+For more information about this and a demo on *real hardware*, see [this blog
+article](https://blog.microjoe.org/2019/hd44780-lcd-i2c-screen-using-linux-mainline-charlcd-driver.html).