https://github.com/gagath/charlcd

Rust library for charlcd.c Linux driver.
https://github.com/gagath/charlcd

linux-kernel rust rust-embedded

Last synced: about 1 month ago
JSON representation

Rust library for charlcd.c Linux driver.

• Host: GitHub
• URL: https://github.com/gagath/charlcd
• Owner: gagath
• License: apache-2.0
• Created: 2020-03-22T21:24:21.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2024-03-11T12:02:31.000Z (8 months ago)
• Last Synced: 2024-09-29T15:04:56.699Z (about 2 months ago)
• Topics: linux-kernel, rust, rust-embedded
• Language: Rust
• Homepage:
• Size: 31.3 KB
• Stars: 4
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# charlcd

[![Latest version](https://img.shields.io/crates/v/charlcd.svg)](https://crates.io/crates/charlcd)

[![Documentation](https://docs.rs/charlcd/badge.svg)](https://docs.rs/charlcd)

[![License](https://img.shields.io/crates/l/charlcd.svg)](https://crates.io/crates/charlcd)

A rust crate to interact with the mainline Linux charlcd.c driver.

Or, said boldly: _a crate to **correctly** interact with HD44780 LCD

screens on embedded Linux devices_.

# Demo

![Photo of a test on HD44780 20x4

screen](https://crates.microjoe.org/charlcd/media/docs/test.jpg)

The use of these kinds of photographies is used all over the

[documentation](https://docs.rs/charlcd) to explain the before and

after of every available function. Be sure to check them all!

# Rationale

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 abstraction 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 abstraction 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.

# Known bugs

The charlcd driver is currently not able to report screen size to userspace.

This is mitigated in the library by having a look at the *device-tree* entries

directly.

# Going further

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).

# License

Apache v2.