tca8418

https://docs.rs/tca8418/0.2.2/tca8418/
Admin
tca8418 is a platform-agnostic Rust driver for the Texas Instruments TCA8418 I²C keypad scan IC,...
Tokens:6,091
Snippets:78
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Handling Keypad Events

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeyEvent.html

Examples demonstrating how to process keypad events, including filtering for keypad presses and matching on specific key types.

```rust
// Handle only keypad presses, most common case
for event in keypad.events()? {
    if let Some(key) = event.pressed_keypad() {
        let _ = (key.row, key.col);
    }
}

// Handle different events separately
for event in keypad.events()? {
    // Is event a press or release?
    let pressed = event.pressed;
     
    match event.key {
        // Event is from a key in the configured keypad matrix
        Key::KeypadMatrix(k) => { /* k.row, k.col */}
        // Event is from a row pin configured as GPI
        Key::RowGpi(g)       => { /* g.index */ }
        // Event is from a column pin configured as GPI
        Key::ColGpi(g)       => { /* g.index */}
    }
}
```

--------------------------------

### Configure Mixed Keypad and GPIO

Source: https://docs.rs/tca8418/0.2.2/tca8418/index.html

Shows how to configure a keypad matrix while using remaining pins as GPIO inputs or outputs.

```rust
use tca8418::{Tca8418, PinMask};
// R0-R3 and C0-C3 as keypad matrix
let matrix_pins = PinMask::rows(0x0F) | PinMask::cols(0x0F);
keypad.configure_keypad(matrix_pins).unwrap();
  
// C4 as GPIO output
keypad.set_gpio_direction(PinMask::C4).unwrap();
  
// Set C4 high
keypad.write_gpio(PinMask::C4).unwrap();
  
// Read-modify-write: toggle C4 without affecting other pins
let current = keypad.read_gpio().unwrap();
keypad.write_gpio(current ^ PinMask::C4).unwrap();
```

--------------------------------

### Initialize and Poll Keypad Events

Source: https://docs.rs/tca8418/0.2.2/tca8418/index.html

Demonstrates basic driver initialization and active polling for keypad events.

```rust
use tca8418::{Tca8418, PinMask, InterruptFlags};
 
// Create the driver
let mut keypad = Tca8418::new(i2c);
 
// Configure rows 0–6 and columns 0–8 as the keypad matrix
let pins = PinMask::rows(0b0111_1111) | PinMask::cols(0b0001_1111_1111);
keypad.configure_keypad(pins).unwrap();
 
// Poll for events
loop {
    for event in keypad.events() {
        if let Some(key) = event.pressed_keypad() {
            // key.row, key.col
        }
    }
}
```

--------------------------------

### Configure Keypad and Read Events

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Set up the keypad matrix using a pin mask and poll the FIFO for key events.

```rust
use tca8418::{Tca8418, PinMask};
let mut keypad = Tca8418::new(i2c);

// Assign rows 0–2 and columns 0–3 to the keypad matrix
let mask = PinMask::rows(0b0000_0111) | PinMask::cols(0b0000_0000_1111);
keypad.configure_keypad(mask).unwrap();

// Read a single event from the FIFO
if let Some(event) = keypad.read_event().unwrap() {
    // Do something...
}
```

--------------------------------

### Construct and Manipulate PinMasks

Source: https://docs.rs/tca8418/0.2.2/tca8418/index.html

Illustrates how to create, modify, and query PinMask bitmasks for row and column pin configuration.

```rust
use tca8418::PinMask;
  
// Individual pins
let mask = PinMask::R0 | PinMask::R1 | PinMask::C0 | PinMask::C1;
  
// Row/column helpers
let mask = PinMask::rows(0x0F) | PinMask::cols(0x03FF);
  
// Predefined constants
let all = PinMask::ALL;
let no_pins = PinMask::NONE;
let all_rows = PinMask::ALL_ROWS;
  
// Modify existing masks
let with_c4 = mask.with(PinMask::C4);
let without_r0 = mask.without(PinMask::R0);
  
// Query
if mask.contains(PinMask::R0) { /* R0 is set */ }
if mask.intersects(PinMask::ALL_ROWS) { /* at least one row is set */ }
```

--------------------------------

### GPIO Configuration and Control

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Methods for setting pin directions, writing output values, and reading current GPIO states.

```APIDOC
## pub fn set_gpio_direction(&mut self, pins: PinMask) -> Result<(), Error<E>>
Set GPIO direction according to the provided pin mask. Bit = 0: input, Bit = 1: output. Only affects pins NOT configured as keypad pins.

## pub fn write_gpio(&mut self, pins: PinMask) -> Result<(), Error<E>>
Write GPIO output values according to the provided pin mask. Bit = 0: output low, Bit = 1: output high. Only affects pins configured as GPIO output.

## pub fn read_gpio(&mut self) -> Result<PinMask, Error<E>>
Read GPIO data status for all pins, returning a `PinMask` with the current states of all row and column pins.
```

--------------------------------

### Key::from_key_number

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Key.html

Creates a Key instance from a raw key number (1–80 for keypad matrix, 97–104 for row GPIO, 105–114 for column GPIO).

```APIDOC
## pub fn from_key_number(key_number: u8) -> Option<Self>

### Description
Creates a `Key` from a raw key number.

### Parameters
- **key_number** (u8) - Required - The raw key number (1–80 for keypad matrix, 97–104 for row GPIO, 105–114 for column GPIO).

### Returns
- **Option<Self>** - Returns the Key if the number is valid, otherwise None.
```

--------------------------------

### Write GPIO output values

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Demonstrates how to set specific pins high or low using PinMask. Note that write_gpio only affects pins configured as GPIO outputs.

```rust
// Only set C9 high, every other pin will be set low
keypad.write_gpio(PinMask::C9)?;

// Set C3 high, everything else stays as-is
let current = keypad.read_gpio()?;
keypad.write_gpio(current.with(PinMask::C3))?;

// Set C3 low
keypad.write_gpio(current.without(PinMask::C3))?;
```

--------------------------------

### Initialize the TCA8418 Driver

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Create a new driver instance using the default I2C address.

```rust
use tca8418::Tca8418;
let mut keypad = Tca8418::new(i2c);
```

--------------------------------

### Tca8418::new

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Creates a new instance of the Tca8418 driver using the default I2C address (0x34).

```APIDOC
pub fn new(i2c: I2C) -> Self
```

--------------------------------

### Async Keypad Handling with Embassy

Source: https://docs.rs/tca8418/0.2.2/tca8418/index.html

Utilizes async GPIO interrupts to handle keypad events without busy-polling.

```rust
use tca8418::{Tca8418, PinMask, InterruptFlags};

#[embassy_executor::task]
async fn keyboard_task(
    mut keypad: Tca8418<I2c<'static>>,
    mut int_pin: ExtiInput<'static>,
) {
    let pins = PinMask::rows(0x7F) | PinMask::cols(0xFF);
    keypad.configure_keypad(pins).unwrap();

    // Key event interrupts need to be enabled to listen to events from the keypad matrix
    keypad.enable_key_event_interrupt(true).unwrap();

    // If pins are configured as GPI pins, the GPI interrupt needs to be enabled as well
    // keypad.enable_gpi_interrupt(true).unwrap();
  
    loop {
        int_pin.wait_for_falling_edge().await;
        for event in keypad.events()? {
            if let Some(key) = event.pressed_keypad() {
                // handle keypress
            }
        }
        keypad.clear_interrupts(InterruptFlags::K_INT).unwrap();
    }
}
```

--------------------------------

### Configure unlock keys

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Sets the two-key combination required to unlock the keypad. Ensure the keys are valid positions within the keypad matrix.

```rust
use tca8418::{Key,Tca8418};

// Set the keys at positions 0,1 and 3,3 in the keypad matrix as the unlock sequence
keypad.set_unlock_keys(Key::from_row_col(0, 1).unwrap(), Key::from_row_col(3, 3).unwrap()).unwrap();
```

--------------------------------

### Tca8418::release

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Consumes the driver and returns the underlying I2C peripheral.

```APIDOC
pub fn release(self) -> I2C
```

--------------------------------

### Keypad Locking and Security

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Methods for managing the keypad lock state, unlock sequences, and associated timers.

```APIDOC
## pub fn is_locked(&mut self) -> Result<bool, Error<E>>
Check if the keypad is currently locked.

## pub fn lock(&mut self) -> Result<(), Error<E>>
Lock the keypad, preventing key event interrupts and FIFO recording.

## pub fn unlock(&mut self) -> Result<(), Error<E>>
Manually unlock the keypad.

## pub fn set_unlock_keys(&mut self, key1: Key, key2: Key) -> Result<(), Error<E>>
Set the unlock key combination (two key numbers).

## pub fn set_unlock_timer(&mut self, seconds: u8) -> Result<(), Error<E>>
Set the unlock key sequence timer (0–7 seconds).
```

--------------------------------

### Create a column PinMask

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.PinMask.html

Create a Pins bitmask from a u16 defining the columns, where bit 0 corresponds to C0 and bit 9 to C9.

```rust
// Create a Pins bitmask for columns C2, C4 and C9:
let mask = PinMask::cols(0b0000_0010_0001_0100);
```

--------------------------------

### Key::get_key_number

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Key.html

Returns the raw key number associated with the key instance.

```APIDOC
## pub fn get_key_number(&self) -> u8

### Description
Return the raw key number (1–80 for keypad matrix, 97–104 for row GPIO, 105–114 for column GPIO) associated with this key.

### Returns
- **u8** - The raw key number.
```

--------------------------------

### Key::col_gpi

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Key.html

Creates a column GPI key from a column index.

```APIDOC
## pub fn col_gpi(col: u8) -> Option<Self>

### Description
Create a column gpi key from column index (0-9).

### Parameters
- **col** (u8) - Required - The column index (0-9).

### Returns
- **Option<Self>** - Returns the Key if the index is valid, otherwise None.
```

--------------------------------

### Key::row_gpi

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Key.html

Creates a row GPI key from a row index.

```APIDOC
## pub fn row_gpi(row: u8) -> Option<Self>

### Description
Create a row gpi key from row index (0-7).

### Parameters
- **row** (u8) - Required - The row index (0-7).

### Returns
- **Option<Self>** - Returns the Key if the index is valid, otherwise None.
```

--------------------------------

### KeypadMatrixKey::from_row_col

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeypadMatrixKey.html

Creates a new KeypadMatrixKey instance from the specified row and column indices.

```APIDOC
## pub fn from_row_col(row: u8, col: u8) -> Option<Self>

### Description
Creates a key representing an element in the keypad matrix from row and column indices.

### Parameters
- **row** (u8) - The row index (0–7).
- **col** (u8) - The column index (0–9).

### Returns
- **Option<Self>** - Returns Some(KeypadMatrixKey) if the indices are valid, otherwise None.
```

--------------------------------

### Tca8418::with_address

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Creates a new instance of the Tca8418 driver with a custom I2C address.

```APIDOC
pub fn with_address(i2c: I2C, addr: u8) -> Self
```

--------------------------------

### KeypadMatrixKey Struct Definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeypadMatrixKey.html

The primary structure definition for representing a key in the keypad matrix.

```rust
pub struct KeypadMatrixKey {
    pub row: u8,
    pub col: u8,
}
```

--------------------------------

### Tca8418::configure_keypad

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Configures which pins participate in the keypad matrix. Pins set to 1 are keypad pins; pins set to 0 are GPIO.

```APIDOC
pub fn configure_keypad(&mut self, pins: PinMask) -> Result<(), Error<E>>
```

--------------------------------

### Define Config struct

Source: https://docs.rs/tca8418/0.2.2/tca8418/registers/struct.Config.html

The base definition of the Config struct used for register bit masks.

```rust
pub struct Config;
```

--------------------------------

### Create a row PinMask

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.PinMask.html

Create a Pins bitmask from a u8 defining the rows, where bit 0 corresponds to R0 and bit 7 to R7.

```rust
// Create a Pins bitmask for rows R0, R2, and R4:
let mask = PinMask::rows(0b0001_0101);
```

--------------------------------

### Key::from_row_col

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Key.html

Creates a key representing an element in the keypad matrix from row and column indices.

```APIDOC
## pub fn from_row_col(row: u8, col: u8) -> Option<Self>

### Description
Creates a key representing an element in the keypad matrix from row and col index.

### Parameters
- **row** (u8) - Required - The row index.
- **col** (u8) - Required - The column index.

### Returns
- **Option<Self>** - Returns the Key if the indices are valid, otherwise None.
```

--------------------------------

### Read GPIO status

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Retrieves the current state of all pins. If debouncing is enabled, registers return default values until a state change occurs.

```rust
let gpio_status = keypad.read_gpio()?;
if gpio_status.contains(PinMask::R0) {
    // R0 is high
}
```

--------------------------------

### KeyEvent::pressed_keypad

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeyEvent.html

Returns the keypad matrix key if the event represents a key press.

```APIDOC
## pub fn pressed_keypad(&self) -> Option<KeypadMatrixKey>

### Description
Returns Some(KeypadMatrixKey) if the event was a key press and the pressed key is part of the keypad matrix.
```

--------------------------------

### KeyEvent::released_keypad

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeyEvent.html

Returns the keypad matrix key if the event represents a key release.

```APIDOC
## pub fn released_keypad(&self) -> Option<KeypadMatrixKey>

### Description
Returns Some(KeypadMatrixKey) if the event was a key release and the pressed key is part of the keypad matrix.
```

--------------------------------

### KeypadMatrixKey::get_key_number

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeypadMatrixKey.html

Retrieves the raw key number associated with the keypad matrix key.

```APIDOC
## pub fn get_key_number(&self) -> u8

### Description
Returns the raw key number (1-80) as reported by the TCA8418 for this specific key.

### Returns
- **u8** - The raw key number.
```

--------------------------------

### KeyEvent Struct Definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.KeyEvent.html

The structure definition for KeyEvent, containing the raw key number, key variant, and press status.

```rust
pub struct KeyEvent {
    pub key_number: u8,
    pub key: Key,
    pub pressed: bool,
}
```

--------------------------------

### Tca8418::read_event

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Reads a single key event from the FIFO. Returns None if the FIFO is empty.

```APIDOC
pub fn read_event(&mut self) -> Result<Option<KeyEvent>, Error<E>>
```

--------------------------------

### Define PinMask Structure

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.PinMask.html

The internal representation of the PinMask struct.

```rust
pub struct PinMask(pub u32);
```

--------------------------------

### GpiKey struct definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/struct.GpiKey.html

The structure used to represent an input on a row or column pin configured as a GPI.

```rust
pub struct GpiKey {
    pub index: u8,
}
```

--------------------------------

### Interrupt Management

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Methods for reading, clearing, and configuring interrupt behavior on the TCA8418 device.

```APIDOC
## pub fn interrupt_status(&mut self) -> Result<InterruptFlags, Error<E>>
Read the interrupt status register.

## pub fn has_pending_key_event(&mut self) -> Result<bool, Error<E>>
Check if there is a pending key event interrupt.

## pub fn clear_interrupts(&mut self, interrupts: InterruptFlags) -> Result<(), Error<E>>
Clear specific interrupt flags by writing 1 to the corresponding bits.

## pub fn clear_all_interrupts(&mut self) -> Result<(), Error<E>>
Clear all interrupt flags.
```

--------------------------------

### Define Key Enum

Source: https://docs.rs/tca8418/0.2.2/tca8418/events/enum.Key.html

The Key enum structure used to represent different event sources in the TCA8418.

```rust
pub enum Key {
    KeypadMatrix(KeypadMatrixKey),
    RowGpi(GpiKey),
    ColGpi(GpiKey),
}
```

--------------------------------

### Tca8418 Struct Definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

The primary structure for the TCA8418 driver.

```rust
pub struct Tca8418<I2C> { /* private fields */ }
```

--------------------------------

### Accessing DEFAULT_ADDRESS

Source: https://docs.rs/tca8418/0.2.2/tca8418/constant.DEFAULT_ADDRESS.html

The constant represents the default 7-bit I²C address for the TCA8418, which is 0x34.

```rust
pub const DEFAULT_ADDRESS: u8 = 0x34;
```

--------------------------------

### Register Enum Definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/registers/enum.Register.html

Defines the Register enum with variants representing the TCA8418 register map, annotated with repr(u8) for direct byte mapping.

```rust
#[repr(u8)]
pub enum Register {
Show 47 variants    Reserved = 0,
    Cfg = 1,
    IntStat = 2,
    KeyLckEc = 3,
    KeyEventA = 4,
    KeyEventB = 5,
    KeyEventC = 6,
    KeyEventD = 7,
    KeyEventE = 8,
    KeyEventF = 9,
    KeyEventG = 10,
    KeyEventH = 11,
    KeyEventI = 12,
    KeyEventJ = 13,
    KpLckTimer = 14,
    Unlock1 = 15,
    Unlock2 = 16,
    GpioIntStat1 = 17,
    GpioIntStat2 = 18,
    GpioIntStat3 = 19,
    GpioDatStat1 = 20,
    GpioDatStat2 = 21,
    GpioDatStat3 = 22,
    GpioDatOut1 = 23,
    GpioDatOut2 = 24,
    GpioDatOut3 = 25,
    GpioIntEn1 = 26,
    GpioIntEn2 = 27,
    GpioIntEn3 = 28,
    KpGpio1 = 29,
    KpGpio2 = 30,
    KpGpio3 = 31,
    GpiEm1 = 32,
    GpiEm2 = 33,
    GpiEm3 = 34,
    GpioDir1 = 35,
    GpioDir2 = 36,
    GpioDir3 = 37,
    GpioIntLvl1 = 38,
    GpioIntLvl2 = 39,
    GpioIntLvl3 = 40,
    DebounceDis1 = 41,
    DebounceDis2 = 42,
    DebounceDis3 = 43,
    GpioPullDis1 = 44,
    GpioPullDis2 = 45,
    GpioPullDis3 = 46,
}
```

--------------------------------

### Tca8418::read_all_events

Source: https://docs.rs/tca8418/0.2.2/tca8418/struct.Tca8418.html

Drains all pending events from the FIFO and returns them as a fixed-size array with the count.

```APIDOC
pub fn read_all_events(&mut self) -> Result<([Option<KeyEvent>; 10], u8), Error<E>>
```

--------------------------------

### InterruptFlags struct definition

Source: https://docs.rs/tca8418/0.2.2/tca8418/registers/struct.InterruptFlags.html

The internal structure of the InterruptFlags type.

```rust
pub struct InterruptFlags(/* private fields */);
```

--------------------------------

### Define Error Enum

Source: https://docs.rs/tca8418/0.2.2/tca8418/enum.Error.html

The Error enum wraps an I2C bus error of type E.

```rust
pub enum Error<E> {
    I2c(E),
}
```
Tokens:
Raw