Skip to content

ktheindifferent/QwiicLCD-Rust

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

QwiicLCD I2C screen library for Rust

Description

This library aims at controlling QwiicLCD screens using I2C from Linux. It primary target is ARM devices such as RaspberryPi or FriendlyARM's NanoPi Neo. It should nonetheless work on other Linux distributions with access to an I2C bus.

Currently I only have access to the 20x4 LCD for testing purposes. If you have issues with other Qwiic LCDs please submit an issue or a pull request.

How to use library

Add the following line to your cargo.toml:

qwiic-lcd-rs = "0.1.11"

Or for the most recent commit on the master branch use:

qwiic-lcd-rs = { git = "https://github.com/PixelCoda/QwiicLCD-Rust.git", version = "*" }

Error Handling

This library now provides comprehensive error handling with automatic retry logic for transient I2C failures:

Custom Error Types

  • QwiicLcdError::I2CError - Wraps underlying I2C communication errors
  • QwiicLcdError::InvalidPosition - Invalid cursor position for screen dimensions
  • QwiicLcdError::InvalidCharacter - Non-ASCII character in print string
  • QwiicLcdError::CommunicationTimeout - Device didn't respond after retries
  • QwiicLcdError::InitializationFailed - Failed to initialize the LCD
  • QwiicLcdError::InvalidCustomCharIndex - Custom character index out of range (0-7)

Retry Configuration

Configure automatic retry behavior for I2C operations:

use qwiic_lcd_rs::{ScreenConfig, RetryConfig};

let retry_config = RetryConfig {
    max_retries: 5,           // Try up to 5 times
    initial_delay_ms: 20,      // Start with 20ms delay
    backoff_multiplier: 1.5,   // Multiply delay by 1.5 each retry
    max_delay_ms: 500,         // Cap delay at 500ms
};

let config = ScreenConfig::new_with_retry(4, 20, retry_config);

Example:

extern crate qwiic_lcd_rs;

use qwiic_lcd_rs::*;
use std::thread;
use std::time::Duration;

fn main() {
    // Default LCDSize is 4x20
    let mut config = ScreenConfig::default();

    // Uncomment and modify the values below to use different screen sizes
    // config.max_rows = 2;
    // config.max_columns = 16;

    // Default Qwiic address is 0x72
    let mut screen = Screen::new(config, "/dev/i2c-1", 0x72).expect("Could not init device");

    // Set backlight to green and wait 1 second
    screen.change_backlight(0, 255, 0).unwrap();
    thread::sleep(Duration::from_secs(1));

    // Set backlight to bright white
    screen.change_backlight(255, 255, 255).unwrap();

    // Clear the screen
    screen.clear().unwrap();
    
    // Move the cursor to 0,0
    screen.move_cursor(0,0).unwrap();

    // Print text
    screen.print("Hello from Rust!").unwrap();

    // Move to the next line
    screen.move_cursor(1,0).unwrap();

    // Print text
    screen.print("It works! :)").unwrap();
}

Error Handling Example

use qwiic_lcd_rs::{Screen, ScreenConfig, QwiicLcdError};

fn main() -> Result<(), QwiicLcdError> {
    let config = ScreenConfig::default();
    let mut screen = Screen::new(config, "/dev/i2c-1", 0x72)?;
    
    // Handle specific error types
    match screen.move_cursor(10, 10) {
        Ok(_) => println!("Cursor moved"),
        Err(QwiicLcdError::InvalidPosition { row, col, .. }) => {
            println!("Invalid position: ({}, {})", row, col);
            screen.move_cursor(0, 0)?; // Move to valid position
        },
        Err(e) => return Err(e),
    }
    
    // Print with character validation
    match screen.print("Hello 😀") {
        Ok(_) => println!("Text printed"),
        Err(QwiicLcdError::InvalidCharacter(c)) => {
            println!("Invalid character: {}", c);
            screen.print("Hello :)")?; // Use ASCII alternative
        },
        Err(e) => return Err(e),
    }
    
    // Create custom character
    let heart = [
        0b00000,
        0b01010,
        0b11111,
        0b11111,
        0b01110,
        0b00100,
        0b00000,
        0b00000,
    ];
    screen.create_character(0, heart)?;
    
    // Set contrast
    screen.set_contrast(128)?;
    
    Ok(())
}

Advanced Features

The library now supports all LCD control features through the previously unused enums:

Entry Mode and Shift Control

// Control text entry direction
screen.set_entry_mode(EntryMode::Left).unwrap();  // Text flows left-to-right (default)
screen.set_entry_mode(EntryMode::Right).unwrap(); // Text flows right-to-left

// Control cursor advancement
screen.set_entry_shift(EntryShift::Increment).unwrap(); // Cursor moves forward
screen.set_entry_shift(EntryShift::Decrement).unwrap(); // Cursor moves backward

Cursor and Display Shifting

// Shift cursor without changing display
screen.shift_cursor(MoveDirection::Right).unwrap();
screen.shift_cursor(MoveDirection::Left).unwrap();

// Shift entire display (useful for scrolling text)
screen.shift_display(MoveDirection::Right).unwrap();
screen.shift_display(MoveDirection::Left).unwrap();

Backlight Control

// Simple on/off control
screen.set_backlight_state(Backlight::On).unwrap();
screen.set_backlight_state(Backlight::Off).unwrap();

// RGB color control (existing method)
screen.change_backlight(255, 0, 0).unwrap(); // Red
screen.change_backlight(0, 255, 0).unwrap(); // Green
screen.change_backlight(0, 0, 255).unwrap(); // Blue

Display Configuration

// Set contrast level (0-255)
screen.set_contrast(128).unwrap(); // Medium contrast
screen.set_contrast(255).unwrap(); // Maximum contrast

// Configure bit mode (4-bit or 8-bit communication)
screen.configure_bit_mode(BitMode::B8).unwrap(); // 8-bit mode
screen.configure_bit_mode(BitMode::B4).unwrap(); // 4-bit mode

Custom Characters

// Define custom character patterns (8 bytes, 5x8 pixels)
let heart = [0x00, 0x0A, 0x1F, 0x1F, 0x0E, 0x04, 0x00, 0x00];
let smiley = [0x00, 0x00, 0x0A, 0x00, 0x11, 0x0E, 0x00, 0x00];

// Create custom characters (locations 0-7)
screen.create_character(0, heart).unwrap();
screen.create_character(1, smiley).unwrap();

// Display custom characters
screen.write_byte(0).unwrap(); // Display heart
screen.write_byte(1).unwrap(); // Display smiley

References

License

Released under Apache 2.0.

Support and follow my work by:

Buying my dope NTFs:

Checking out my Github:

Following my facebook page:

Subscribing to my Patreon:

Or donating crypto:

  • ADA: addr1qyp299a45tgvveh83tcxlf7ds3yaeh969yt3v882lvxfkkv4e0f46qvr4wzj8ty5c05jyffzq8a9pfwz9dl6m0raac7s4rac48
  • ALGO: VQ5EK4GA3IUTGSPNGV64UANBUVFAIVBXVL5UUCNZSDH544XIMF7BAHEDM4
  • ATOM: cosmos1wm7lummcealk0fxn3x9tm8hg7xsyuz06ul5fw9
  • BTC: bc1qh5p3rff4vxnv23vg0hw8pf3gmz3qgc029cekxz
  • ETH: 0x7A66beaebF7D0d17598d37525e63f524CfD23452
  • ERC20: 0x7A66beaebF7D0d17598d37525e63f524CfD23452
  • XLM: GCJAUMCO2L7PTYMXELQ6GHBTF25MCQKEBNSND2C4QMUPTSVCPEN3LCOG
  • XTZ: tz1SgJppPn56whprsDDGcqR4fxqCr2PXvg1R

About

An un-official port in progress for using Qwiic LCD's + rust-lang + pi

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 5

Languages