From 45461f7b9e51649ba559f24a3584edca979d169b Mon Sep 17 00:00:00 2001 From: Agathe Porte Date: Fri, 27 Mar 2020 14:23:35 +0100 Subject: populate README and include it in module-level doc --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- src/lib.rs | 3 +++ 2 files changed, 63 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). diff --git a/src/lib.rs b/src/lib.rs index 17738a3..f00fed0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,6 @@ +#![feature(external_doc)] +#![doc(include = "../README.md")] + mod codes; pub mod custom_char; mod of_node; -- cgit v1.2.3