Crate cardputer_adv_keyboard 

A keyboard driver for the M5Stack Cardputer-Adv, built on top of the tca8418 driver. Handles key press/release events, shift/Fn layer resolution and modifier tracking.

This crate provides a Keyboard type that can be created using any type that implements I2c. This is provided by your HAL. All methods using the underlying I²C bus return a tca8418::Error on I²C failure.

You can get all pending inputs using .inputs() on the created Keyboard. This drains the FIFO of the TCA8418 which can store up to 10 events.

You can either use polling or the TCA8418’s interrupt output to know when events are available.

Examples

Here is a basic example on how to capture user text input. See the examples in the repository for a full example app using esp-hal.

use cardputer_adv_keyboard::{KeyInput, Keyboard};
use heapless::String;

let mut input_string: String<64> = String::new();

// You need to create i2c using your HAL crate.
let mut keyboard = Keyboard::new(i2c).unwrap();

loop {
    for input in keyboard.inputs().unwrap() {
        match input {
            KeyInput::Char(c) => { input_string.push(c).ok(); }
            KeyInput::Backspace => { input_string.pop(); }
            KeyInput::Enter => {
                process_input(&input_string);
                input_string.clear();
            }
            _ => {}
        }
    }
}

KeyInput

A KeyInput represents a resolved key press. This encompasses everything that is printed on the keyboard, including the Shift and Fn layers.

Some examples

Pressed keys	Result
w	KeyInput::Char('w')
Shift + w	KeyInput::Char('W')
;	KeyInput::Char(';')
Shift + ;	KeyInput::Char(':')
Space	KeyInput::Char(' ')

The other character keys work the same. If a key has no Shift or Fn layer, it just returns it’s default character, even when modifiers are pressed.

All special keys have their own KeyInput variant, for example:

Pressed keys	Result
Fn + `	KeyInput::Escape
Fn + ;	KeyInput::Arrow(Arrow::Up)
Fn + Backspace	KeyInput::Delete

Advanced usage

If you need more information about key events (key releases, pressed modifiers) you can directly get the KeyboardEvents using .events(). Using these you can create custom chords (like Ctrl + C) or track if a key is being held.

Listening for custom combinations

use cardputer_adv_keyboard::{PhysicalKey, ModifierState};
for event in keyboard.events().unwrap() {
    // Only act on presses
    if !event.state.is_pressed() {
        continue;
    }

    match (event.physical_key, event.modifiers) {
        (PhysicalKey::C, ModifierState { ctrl: true, .. }) => copy(),
        (PhysicalKey::V, ModifierState { ctrl: true, .. }) => paste(),
        (PhysicalKey::Z, ModifierState { ctrl: true, shift: true, .. }) => redo(),
        (PhysicalKey::Z, ModifierState { ctrl: true, .. }) => undo(),
        _ => {}
    }
}

Tracking held keys

use cardputer_adv_keyboard::{PhysicalKey, KeyState};
let mut w_held = false;

loop {
    for event in keyboard.events().unwrap() {
        match (event.physical_key, event.state) {
            (PhysicalKey::W, KeyState::Pressed) => w_held = true,
            (PhysicalKey::W, KeyState::Released) => w_held = false,
            (PhysicalKey::Space, KeyState::Pressed) => player.jump(),
            _ => {}
        }
    }

    if w_held {
        player.move_forward();
    }
}

Structs

Keyboard

High-level keyboard driver for the Cardputer-Adv.

KeyboardEvent

This type represents a key event (press or release).

KeyboardEventIter

Iterator over processed keyboard events from a single Keyboard::events call.

ModifierState

State that tracks which modifier keys are currently held down.

Enums

Arrow

Arrow key directions.

KeyInput

The semantic meaning of a key press after applying modifiers.

KeyState

Whether a key was pressed or released.

Modifier

Modifier keys.

PhysicalKey

This represents an actual physical key on the Cardputer keyboard.