pc_keyboard/

lib.rs

//! Driver for a PS/2 PC keyboard.
//!
//! Supports PS/2 Scan Code Set 1 and 2, on a variety of keyboard layouts. See
//! [the OSDev Wiki](https://wiki.osdev.org/PS/2_Keyboard).
//!
//! There are three basic steps to handling keyboard input. Your application may bypass some of these.
//!
//! * [`Ps2Decoder`] - converts 11-bit PS/2 words into bytes, removing the start/stop
//!   bits and checking the parity bits. Only needed if you talk to the PS/2
//!   keyboard over GPIO pins and not required if you talk to the i8042 PC keyboard
//!   controller.
//! * [`ScancodeSet`] - converts from Scancode Set 1 (i8042 PC keyboard controller) or
//!   Scancode Set 2 (raw PS/2 keyboard output) into a symbolic [`KeyCode`] and an
//!   up/down [`KeyState`].
//! * [`EventDecoder`] - converts symbolic [`KeyCode`] and [`KeyState`] into a Unicode
//!   characters (where possible) according to the currently selected `KeyboardLayout`.
//!
//! There is also [`Keyboard`] which combines the above three functions into a single object.

#![cfg_attr(not(test), no_std)]

// ****************************************************************************
//
// Modules
//
// ****************************************************************************

pub mod layouts;

mod scancodes;
pub use crate::scancodes::{ScancodeSet1, ScancodeSet2};

// ****************************************************************************
//
// Public Types
//
// ****************************************************************************

/// Encapsulates decode/sampling logic, and handles state transitions and key events.
#[derive(Debug)]
pub struct Keyboard<L, S>
where
    S: ScancodeSet,
    L: KeyboardLayout,
{
    ps2_decoder: Ps2Decoder,
    scancode_set: S,
    event_decoder: EventDecoder<L>,
}

/// Handles decoding of IBM PS/2 Keyboard (and IBM PC/AT Keyboard) bit-streams.
#[derive(Debug)]
pub struct Ps2Decoder {
    register: u16,
    num_bits: u8,
}

/// Converts KeyEvents into Unicode, according to the current Keyboard Layout
#[derive(Debug)]
pub struct EventDecoder<L>
where
    L: KeyboardLayout,
{
    handle_ctrl: HandleControl,
    modifiers: Modifiers,
    layout: L,
}

/// Indicates different error conditions.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
#[non_exhaustive]
pub enum Error {
    BadStartBit,
    BadStopBit,
    ParityError,
    UnknownKeyCode,
}

/// Keycodes that can be generated by a keyboard.
///
/// We use this enum to abstract over Scan Code Set 1 and Scan Code Set 2.
///
/// See <https://kbdlayout.info/kbduk/shiftstates+virtualkeys/base>
#[derive(Debug, PartialEq, Eq, Copy, Clone, PartialOrd, Ord)]
#[repr(u8)]
pub enum KeyCode {
    // ========= Row 1 (the F-keys) =========
    /// Top Left of the Keyboard
    Escape,
    /// Function Key F1
    F1,
    /// Function Key F2
    F2,
    /// Function Key F3
    F3,
    /// Function Key F4
    F4,
    /// Function Key F5
    F5,
    /// Function Key F6
    F6,
    /// Function Key F7
    F7,
    /// Function Key F8
    F8,
    /// Function Key F9
    F9,
    /// Function Key F10
    F10,
    /// Function Key F11
    F11,
    /// Function Key F12
    F12,

    /// The Print Screen Key
    PrintScreen,
    /// The Sys Req key (you get this keycode with Alt + PrintScreen)
    SysRq,
    /// The Scroll Lock key
    ScrollLock,
    /// The Pause/Break key
    PauseBreak,

    // ========= Row 2 (the numbers) =========
    /// Symbol key to the left of `Key1`
    Oem8,
    /// Number Line, Digit 1
    Key1,
    /// Number Line, Digit 2
    Key2,
    /// Number Line, Digit 3
    Key3,
    /// Number Line, Digit 4
    Key4,
    /// Number Line, Digit 5
    Key5,
    /// Number Line, Digit 6
    Key6,
    /// Number Line, Digit 7
    Key7,
    /// Number Line, Digit 8
    Key8,
    /// Number Line, Digit 9
    Key9,
    /// Number Line, Digit 0
    Key0,
    /// US Minus/Underscore Key (right of 'Key0')
    OemMinus,
    /// US Equals/Plus Key (right of 'OemMinus')
    OemPlus,
    /// Backspace
    Backspace,

    /// Top Left of the Extended Block
    Insert,
    /// Top Middle of the Extended Block
    Home,
    /// Top Right of the Extended Block
    PageUp,

    /// The Num Lock key
    NumpadLock,
    /// The Numpad Divide (or Slash) key
    NumpadDivide,
    /// The Numpad Multiple (or Star) key
    NumpadMultiply,
    /// The Numpad Subtract (or Minus) key
    NumpadSubtract,

    // ========= Row 3 (QWERTY) =========
    /// The Tab Key
    Tab,
    /// Letters, Top Row #1
    Q,
    /// Letters, Top Row #2
    W,
    /// Letters, Top Row #3
    E,
    /// Letters, Top Row #4
    R,
    /// Letters, Top Row #5
    T,
    /// Letters, Top Row #6
    Y,
    /// Letters, Top Row #7
    U,
    /// Letters, Top Row #8
    I,
    /// Letters, Top Row #9
    O,
    /// Letters, Top Row #10
    P,
    /// US ANSI Left-Square-Bracket key
    Oem4,
    /// US ANSI Right-Square-Bracket key
    Oem6,
    /// US ANSI Backslash Key / UK ISO Backslash Key
    Oem5,
    /// The UK/ISO Hash/Tilde key (ISO layout only)
    Oem7,

    /// The Delete key - bottom Left of the Extended Block
    Delete,
    /// The End key - bottom Middle of the Extended Block
    End,
    /// The Page Down key - -bottom Right of the Extended Block
    PageDown,

    /// The Numpad 7/Home key
    Numpad7,
    /// The Numpad 8/Up Arrow key
    Numpad8,
    /// The Numpad 9/Page Up key
    Numpad9,
    /// The Numpad Add/Plus key
    NumpadAdd,

    // ========= Row 4 (ASDF) =========
    /// Caps Lock
    CapsLock,
    /// Letters, Middle Row #1
    A,
    /// Letters, Middle Row #2
    S,
    /// Letters, Middle Row #3
    D,
    /// Letters, Middle Row #4
    F,
    /// Letters, Middle Row #5
    G,
    /// Letters, Middle Row #6
    H,
    /// Letters, Middle Row #7
    J,
    /// Letters, Middle Row #8
    K,
    /// Letters, Middle Row #9
    L,
    /// The US ANSI Semicolon/Colon key
    Oem1,
    /// The US ANSI Single-Quote/At key
    Oem3,

    /// The Return Key
    Return,

    /// The Numpad 4/Left Arrow key
    Numpad4,
    /// The Numpad 5 Key
    Numpad5,
    /// The Numpad 6/Right Arrow key
    Numpad6,

    // ========= Row 5 (ZXCV) =========
    /// Left Shift
    LShift,
    /// Letters, Bottom Row #1
    Z,
    /// Letters, Bottom Row #2
    X,
    /// Letters, Bottom Row #3
    C,
    /// Letters, Bottom Row #4
    V,
    /// Letters, Bottom Row #5
    B,
    /// Letters, Bottom Row #6
    N,
    /// Letters, Bottom Row #7
    M,
    /// US ANSI `,<` key
    OemComma,
    /// US ANSI `.>` Key
    OemPeriod,
    /// US ANSI `/?` Key
    Oem2,
    /// Right Shift
    RShift,

    /// The up-arrow in the inverted-T
    ArrowUp,

    /// Numpad 1/End Key
    Numpad1,
    /// Numpad 2/Arrow Down Key
    Numpad2,
    /// Numpad 3/Page Down Key
    Numpad3,
    /// Numpad Enter
    NumpadEnter,

    // ========= Row 6 (modifers and space bar) =========
    /// The left-hand Control key
    LControl,
    /// The left-hand 'Windows' key
    LWin,
    /// The left-hand Alt key
    LAlt,
    /// The Space Bar
    Spacebar,
    /// The right-hand AltGr key
    RAltGr,
    /// The right-hand Win key
    RWin,
    /// The 'Apps' key (aka 'Menu' or 'Right-Click')
    Apps,
    /// The right-hand Control key
    RControl,

    /// The left-arrow in the inverted-T
    ArrowLeft,
    /// The down-arrow in the inverted-T
    ArrowDown,
    /// The right-arrow in the inverted-T
    ArrowRight,

    /// The Numpad 0/Insert Key
    Numpad0,
    /// The Numppad Period/Delete Key
    NumpadPeriod,

    // ========= JIS 109-key extra keys =========
    /// Extra JIS key (0x7B)
    Oem9,
    /// Extra JIS key (0x79)
    Oem10,
    /// Extra JIS key (0x70)
    Oem11,
    /// Extra JIS symbol key (0x73)
    Oem12,
    /// Extra JIS symbol key (0x7D)
    Oem13,

    // ========= Extra Keys =========
    /// Multi-media keys - Previous Track
    PrevTrack,
    /// Multi-media keys - Next Track
    NextTrack,
    /// Multi-media keys - Volume Mute Toggle
    Mute,
    /// Multi-media keys - Open Calculator
    Calculator,
    /// Multi-media keys - Play
    Play,
    /// Multi-media keys - Stop
    Stop,
    /// Multi-media keys - Increase Volume
    VolumeDown,
    /// Multi-media keys - Decrease Volume
    VolumeUp,
    /// Multi-media keys - Open Browser
    WWWHome,
    /// Sent when the keyboard boots
    PowerOnTestOk,
    /// Sent by the keyboard when too many keys are pressed
    TooManyKeys,
    /// Used as a 'hidden' Right Control Key (Pause = RControl2 + Num Lock)
    RControl2,
    /// Used as a 'hidden' Right Alt Key (Print Screen = RAlt2 + PrntScr)
    RAlt2,
}

/// The new state for a key, as part of a key event.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
pub enum KeyState {
    /// Key has just been released
    Up,
    /// Key has just been pressed
    Down,
    /// Key was pressed and then released as an atomic action. Or it's like a
    /// PowerOnSelfTest event which doesn't have an 'Up' or a 'Down'.
    SingleShot,
}

/// Options for how we can handle what happens when the Ctrl key is held down
/// and a letter is pressed.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
pub enum HandleControl {
    /// If either Ctrl key is held down, convert the letters A through Z into
    /// Unicode chars U+0001 through U+001A. If the Ctrl keys are not held
    /// down, letters go through normally.
    MapLettersToUnicode,
    /// Don't do anything special - send through the Ctrl key up/down events,
    /// and leave the letters as letters.
    Ignore,
}

/// A event describing something happen to a key on your keyboard.
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct KeyEvent {
    /// Which key this event is for
    pub code: KeyCode,
    /// The new state for the key
    pub state: KeyState,
}

/// Describes a Keyboard Layout.
///
/// Layouts might include "en_US", or "en_GB", or "de_GR".
pub trait KeyboardLayout {
    /// Convert a `KeyCode` enum to a Unicode character, if possible.
    /// `KeyCode::A` maps to `DecodedKey::Unicode('a')` (or
    /// `DecodedKey::Unicode('A')` if shifted), while `KeyCode::LAlt` becomes
    /// `DecodedKey::RawKey(KeyCode::LAlt)` because there's no Unicode equivalent.
    fn map_keycode(
        &self,
        keycode: KeyCode,
        modifiers: &Modifiers,
        handle_ctrl: HandleControl,
    ) -> DecodedKey;
}

/// A mechanism to convert bytes from a Keyboard into [`KeyCode`] values.
///
/// This conversion is stateful.
pub trait ScancodeSet {
    /// Handles the state logic for the decoding of scan codes into key events.
    fn advance_state(&mut self, code: u8) -> Result<Option<KeyEvent>, Error>;
}

/// The set of modifier keys you have on a keyboard.
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
pub struct Modifiers {
    /// The left shift key is down
    pub lshift: bool,
    /// The right shift key is down
    pub rshift: bool,
    /// The left control key is down
    pub lctrl: bool,
    /// The right control key is down
    pub rctrl: bool,
    /// The Num Lock toggle is on
    pub numlock: bool,
    /// The caps lock toggle is on
    pub capslock: bool,
    /// The left alt key is down
    pub lalt: bool,
    /// The right alt key is down
    pub ralt: bool,
    /// Special 'hidden' control key is down (used when you press Pause)
    pub rctrl2: bool,
}

/// Contains either a Unicode character, or a raw key code.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
pub enum DecodedKey {
    RawKey(KeyCode),
    Unicode(char),
}

// ****************************************************************************
//
// Public Data
//
// ****************************************************************************

// None

// ****************************************************************************
//
// Private Types
//
// ****************************************************************************

/// Tracls
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
enum DecodeState {
    Start,
    Extended,
    Release,
    ExtendedRelease,
    Extended2,
    Extended2Release,
}

// ****************************************************************************
//
// Private Data
//
// ****************************************************************************

const KEYCODE_BITS: u8 = 11;
const EXTENDED_KEY_CODE: u8 = 0xE0;
const EXTENDED2_KEY_CODE: u8 = 0xE1;
const KEY_RELEASE_CODE: u8 = 0xF0;

// ****************************************************************************
//
// Public Functions and Implementation
//
// ****************************************************************************

impl<L, S> Keyboard<L, S>
where
    L: KeyboardLayout,
    S: ScancodeSet,
{
    /// Make a new Keyboard object with the given layout.
    pub const fn new(scancode_set: S, layout: L, handle_ctrl: HandleControl) -> Keyboard<L, S> {
        Keyboard {
            ps2_decoder: Ps2Decoder::new(),
            scancode_set,
            event_decoder: EventDecoder::new(layout, handle_ctrl),
        }
    }

    /// Get the current key modifier states.
    pub const fn get_modifiers(&self) -> &Modifiers {
        &self.event_decoder.modifiers
    }

    /// Change the Ctrl key mapping.
    pub fn set_ctrl_handling(&mut self, new_value: HandleControl) {
        self.event_decoder.set_ctrl_handling(new_value);
    }

    /// Get the current Ctrl key mapping.
    pub const fn get_ctrl_handling(&self) -> HandleControl {
        self.event_decoder.get_ctrl_handling()
    }

    /// Clears the bit register.
    ///
    /// Call this when there is a timeout reading data from the keyboard.
    pub fn clear(&mut self) {
        self.ps2_decoder.clear();
    }

    /// Processes a 16-bit word from the keyboard.
    ///
    /// * The start bit (0) must be in bit 0.
    /// * The data octet must be in bits 1..8, with the LSB in bit 1 and the
    ///   MSB in bit 8.
    /// * The parity bit must be in bit 9.
    /// * The stop bit (1) must be in bit 10.
    pub fn add_word(&mut self, word: u16) -> Result<Option<KeyEvent>, Error> {
        let byte = self.ps2_decoder.add_word(word)?;
        self.add_byte(byte)
    }

    /// Processes an 8-bit byte from the keyboard.
    ///
    /// We assume the start, stop and parity bits have been processed and
    /// verified.
    pub fn add_byte(&mut self, byte: u8) -> Result<Option<KeyEvent>, Error> {
        self.scancode_set.advance_state(byte)
    }

    /// Shift a bit into the register.
    ///
    /// Call this /or/ call `add_word` - don't call both.
    /// Until the last bit is added you get Ok(None) returned.
    pub fn add_bit(&mut self, bit: bool) -> Result<Option<KeyEvent>, Error> {
        if let Some(byte) = self.ps2_decoder.add_bit(bit)? {
            self.scancode_set.advance_state(byte)
        } else {
            Ok(None)
        }
    }

    /// Processes a `KeyEvent` returned from `add_bit`, `add_byte` or `add_word`
    /// and produces a decoded key.
    ///
    /// For example, the KeyEvent for pressing the '5' key on your keyboard
    /// gives a DecodedKey of unicode character '5', unless the shift key is
    /// held in which case you get the unicode character '%'.
    pub fn process_keyevent(&mut self, ev: KeyEvent) -> Option<DecodedKey> {
        self.event_decoder.process_keyevent(ev)
    }
}

impl Ps2Decoder {
    /// Build a new PS/2 protocol decoder.
    pub const fn new() -> Ps2Decoder {
        Ps2Decoder {
            register: 0,
            num_bits: 0,
        }
    }

    /// Clears the bit register.
    ///
    /// Call this when there is a timeout reading data from the keyboard.
    pub fn clear(&mut self) {
        self.register = 0;
        self.num_bits = 0;
    }

    /// Shift a bit into the register.
    ///
    /// Until the last bit is added you get Ok(None) returned.
    pub fn add_bit(&mut self, bit: bool) -> Result<Option<u8>, Error> {
        self.register |= (bit as u16) << self.num_bits;
        self.num_bits += 1;
        if self.num_bits == KEYCODE_BITS {
            let word = self.register;
            self.register = 0;
            self.num_bits = 0;
            let byte = Self::check_word(word)?;
            Ok(Some(byte))
        } else {
            Ok(None)
        }
    }

    /// Process an entire 11-bit word.
    ///
    /// Must be packed into the bottom 11-bits of the 16-bit value.
    pub fn add_word(&self, word: u16) -> Result<u8, Error> {
        Self::check_word(word)
    }

    /// Check 11-bit word has 1 start bit, 1 stop bit and an odd parity bit.
    const fn check_word(word: u16) -> Result<u8, Error> {
        let start_bit = Self::get_bit(word, 0);
        let parity_bit = Self::get_bit(word, 9);
        let stop_bit = Self::get_bit(word, 10);
        let data = ((word >> 1) & 0xFF) as u8;

        if start_bit {
            return Err(Error::BadStartBit);
        }

        if !stop_bit {
            return Err(Error::BadStopBit);
        }

        // We have odd parity, so if there are an even number of 1 bits, we need
        // the parity bit set to make it odd.
        let need_parity = Self::has_even_number_bits(data);

        if need_parity != parity_bit {
            return Err(Error::ParityError);
        }

        Ok(data)
    }

    const fn get_bit(word: u16, offset: usize) -> bool {
        ((word >> offset) & 0x0001) != 0
    }

    const fn has_even_number_bits(data: u8) -> bool {
        (data.count_ones() % 2) == 0
    }
}

impl Default for Ps2Decoder {
    fn default() -> Self {
        Ps2Decoder::new()
    }
}

impl<L> EventDecoder<L>
where
    L: KeyboardLayout,
{
    /// Construct a new event decoder.
    pub const fn new(layout: L, handle_ctrl: HandleControl) -> EventDecoder<L> {
        EventDecoder {
            handle_ctrl,
            modifiers: Modifiers {
                lshift: false,
                rshift: false,
                lctrl: false,
                rctrl: false,
                numlock: true,
                capslock: false,
                lalt: false,
                ralt: false,
                rctrl2: false,
            },
            layout,
        }
    }

    /// Change the Ctrl key mapping.
    pub fn set_ctrl_handling(&mut self, new_value: HandleControl) {
        self.handle_ctrl = new_value;
    }

    /// Get the current Ctrl key mapping.
    pub const fn get_ctrl_handling(&self) -> HandleControl {
        self.handle_ctrl
    }

    /// Processes a `KeyEvent` returned from `add_bit`, `add_byte` or `add_word`
    /// and produces a decoded key.
    ///
    /// For example, the KeyEvent for pressing the '5' key on your keyboard
    /// gives a DecodedKey of unicode character '5', unless the shift key is
    /// held in which case you get the unicode character '%'.
    pub fn process_keyevent(&mut self, ev: KeyEvent) -> Option<DecodedKey> {
        match ev {
            KeyEvent {
                code: KeyCode::LShift,
                state: KeyState::Down,
            } => {
                self.modifiers.lshift = true;
                Some(DecodedKey::RawKey(KeyCode::LShift))
            }
            KeyEvent {
                code: KeyCode::RShift,
                state: KeyState::Down,
            } => {
                self.modifiers.rshift = true;
                Some(DecodedKey::RawKey(KeyCode::RShift))
            }
            KeyEvent {
                code: KeyCode::LShift,
                state: KeyState::Up,
            } => {
                self.modifiers.lshift = false;
                None
            }
            KeyEvent {
                code: KeyCode::RShift,
                state: KeyState::Up,
            } => {
                self.modifiers.rshift = false;
                None
            }
            KeyEvent {
                code: KeyCode::CapsLock,
                state: KeyState::Down,
            } => {
                self.modifiers.capslock = !self.modifiers.capslock;
                Some(DecodedKey::RawKey(KeyCode::CapsLock))
            }
            KeyEvent {
                code: KeyCode::NumpadLock,
                state: KeyState::Down,
            } => {
                if self.modifiers.rctrl2 {
                    // It's a Pause key because we got the 'hidden' rctrl2
                    // sequence first.
                    Some(DecodedKey::RawKey(KeyCode::PauseBreak))
                } else {
                    // It's a numlock toggle
                    self.modifiers.numlock = !self.modifiers.numlock;
                    Some(DecodedKey::RawKey(KeyCode::NumpadLock))
                }
            }
            KeyEvent {
                code: KeyCode::LControl,
                state: KeyState::Down,
            } => {
                self.modifiers.lctrl = true;
                Some(DecodedKey::RawKey(KeyCode::LControl))
            }
            KeyEvent {
                code: KeyCode::LControl,
                state: KeyState::Up,
            } => {
                self.modifiers.lctrl = false;
                None
            }
            KeyEvent {
                code: KeyCode::RControl,
                state: KeyState::Down,
            } => {
                self.modifiers.rctrl = true;
                Some(DecodedKey::RawKey(KeyCode::RControl))
            }
            KeyEvent {
                code: KeyCode::RControl,
                state: KeyState::Up,
            } => {
                self.modifiers.rctrl = false;
                None
            }
            KeyEvent {
                code: KeyCode::LAlt,
                state: KeyState::Down,
            } => {
                self.modifiers.lalt = true;
                Some(DecodedKey::RawKey(KeyCode::LAlt))
            }
            KeyEvent {
                code: KeyCode::LAlt,
                state: KeyState::Up,
            } => {
                self.modifiers.lalt = false;
                None
            }
            KeyEvent {
                code: KeyCode::RAltGr,
                state: KeyState::Down,
            } => {
                self.modifiers.ralt = true;
                Some(DecodedKey::RawKey(KeyCode::RAltGr))
            }
            KeyEvent {
                code: KeyCode::RAltGr,
                state: KeyState::Up,
            } => {
                self.modifiers.ralt = false;
                None
            }
            KeyEvent {
                code: KeyCode::RControl2,
                state: KeyState::Down,
            } => {
                self.modifiers.rctrl2 = true;
                Some(DecodedKey::RawKey(KeyCode::RControl2))
            }
            KeyEvent {
                code: KeyCode::RControl2,
                state: KeyState::Up,
            } => {
                self.modifiers.rctrl2 = false;
                None
            }
            KeyEvent {
                code: c,
                state: KeyState::Down,
            } => Some(
                self.layout
                    .map_keycode(c, &self.modifiers, self.handle_ctrl),
            ),
            _ => None,
        }
    }

    /// Change the keyboard layout.
    ///
    /// Only useful with [`layouts::AnyLayout`], otherwise you can only change a
    /// layout for exactly the same layout.
    pub fn change_layout(&mut self, new_layout: L) {
        self.layout = new_layout;
    }
}

impl KeyEvent {
    pub const fn new(code: KeyCode, state: KeyState) -> KeyEvent {
        KeyEvent { code, state }
    }
}

// ****************************************************************************
//
// Keyboard Layouts
//
// ****************************************************************************

impl Modifiers {
    pub const fn is_shifted(&self) -> bool {
        self.lshift | self.rshift
    }

    pub const fn is_ctrl(&self) -> bool {
        self.lctrl | self.rctrl
    }

    pub const fn is_alt(&self) -> bool {
        self.lalt | self.ralt
    }

    pub const fn is_altgr(&self) -> bool {
        self.ralt | (self.lalt & self.is_ctrl())
    }

    pub const fn is_caps(&self) -> bool {
        self.is_shifted() ^ self.capslock
    }
}

// ****************************************************************************
//
// Tests
//
// ****************************************************************************

#[cfg(test)]
mod test {
    use super::*;

    fn add_bytes<L, S>(keyboard: &mut Keyboard<L, S>, test_sequence: &[(u8, Option<KeyEvent>)])
    where
        L: KeyboardLayout,
        S: ScancodeSet,
    {
        for (byte, expected_key) in test_sequence.iter().cloned() {
            let result = keyboard.add_byte(byte);
            assert_eq!(
                result,
                Ok(expected_key.clone()),
                "0x{:02x} should have given {:?} not {:?}",
                byte,
                expected_key,
                result
            );
        }
    }

    fn process_keyevents<L, S>(
        keyboard: &mut Keyboard<L, S>,
        test_sequence: &[(KeyEvent, Option<DecodedKey>)],
    ) where
        L: KeyboardLayout,
        S: ScancodeSet,
    {
        for (idx, (event, expected_decode)) in test_sequence.iter().cloned().enumerate() {
            let result = keyboard.process_keyevent(event.clone());
            assert_eq!(
                result,
                expected_decode.clone(),
                "Entry {} {:?} should have given {:?} not {:?}",
                idx,
                event,
                expected_decode,
                result
            );
        }
    }

    #[test]
    fn test_f9() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        // start
        assert_eq!(k.add_bit(false), Ok(None));
        // 8 data bits (LSB first)
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        // parity
        assert_eq!(k.add_bit(false), Ok(None));
        // stop
        assert_eq!(
            k.add_bit(true),
            Ok(Some(KeyEvent::new(KeyCode::F9, KeyState::Down)))
        );
    }

    #[test]
    fn test_f9_word() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        assert_eq!(
            k.add_word(0x0402),
            Ok(Some(KeyEvent::new(KeyCode::F9, KeyState::Down)))
        );
    }

    #[test]
    fn test_f9_byte() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );

        let test_sequence = [(0x01, Some(KeyEvent::new(KeyCode::F9, KeyState::Down)))];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_keyup_keydown() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            (0x01, Some(KeyEvent::new(KeyCode::F9, KeyState::Down))),
            (0x01, Some(KeyEvent::new(KeyCode::F9, KeyState::Down))),
            (0xF0, None),
            (0x01, Some(KeyEvent::new(KeyCode::F9, KeyState::Up))),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_f5() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        // start
        assert_eq!(k.add_bit(false), Ok(None));
        // 8 data bits (LSB first)
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        // parity
        assert_eq!(k.add_bit(true), Ok(None));
        // stop
        assert_eq!(
            k.add_bit(true),
            Ok(Some(KeyEvent::new(KeyCode::F5, KeyState::Down)))
        );
    }

    #[test]
    fn test_f5_up() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        // Send F0

        // start
        assert_eq!(k.add_bit(false), Ok(None));
        // 8 data bits (LSB first)
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        // parity
        assert_eq!(k.add_bit(true), Ok(None));
        // stop
        assert_eq!(k.add_bit(true), Ok(None));

        // Send 03

        // start
        assert_eq!(k.add_bit(false), Ok(None));
        // 8 data bits (LSB first)
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(true), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        assert_eq!(k.add_bit(false), Ok(None));
        // parity
        assert_eq!(k.add_bit(true), Ok(None));
        // stop
        assert_eq!(
            k.add_bit(true),
            Ok(Some(KeyEvent::new(KeyCode::F5, KeyState::Up)))
        );
    }

    #[test]
    fn test_shift() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            // A with left shift held
            (
                KeyEvent::new(KeyCode::LShift, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::LShift)),
            ),
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('A')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            (KeyEvent::new(KeyCode::LShift, KeyState::Up), None),
            // A with no shift
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('a')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            // A with right shift held
            (
                KeyEvent::new(KeyCode::RShift, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::RShift)),
            ),
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('A')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            (KeyEvent::new(KeyCode::RShift, KeyState::Up), None),
            // Caps lock ON
            (
                KeyEvent::new(KeyCode::CapsLock, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::CapsLock)),
            ),
            (KeyEvent::new(KeyCode::CapsLock, KeyState::Up), None),
            // Letters are now caps
            (
                KeyEvent::new(KeyCode::X, KeyState::Down),
                Some(DecodedKey::Unicode('X')),
            ),
            (KeyEvent::new(KeyCode::X, KeyState::Up), None),
            // Unless you press shift
            (
                KeyEvent::new(KeyCode::RShift, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::RShift)),
            ),
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('a')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            (KeyEvent::new(KeyCode::RShift, KeyState::Up), None),
            // Numbers are not shifted
            (
                KeyEvent::new(KeyCode::Key1, KeyState::Down),
                Some(DecodedKey::Unicode('1')),
            ),
            (KeyEvent::new(KeyCode::Key1, KeyState::Up), None),
        ];

        process_keyevents(&mut k, &test_sequence);
    }

    #[test]
    fn test_ctrl() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            // Normal
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('a')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            // Left Control
            (
                KeyEvent::new(KeyCode::LControl, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::LControl)),
            ),
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('\u{0001}')),
            ),
            (KeyEvent::new(KeyCode::LControl, KeyState::Up), None),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            // Normal
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('a')),
            ),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
            // Right Control
            (
                KeyEvent::new(KeyCode::RControl, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::RControl)),
            ),
            (
                KeyEvent::new(KeyCode::A, KeyState::Down),
                Some(DecodedKey::Unicode('\u{0001}')),
            ),
            (KeyEvent::new(KeyCode::RControl, KeyState::Up), None),
            (KeyEvent::new(KeyCode::A, KeyState::Up), None),
        ];
        process_keyevents(&mut k, &test_sequence);
    }

    #[test]
    fn test_numlock() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        let test_sequence = [
            // Numlock ON by default so we get digits
            (
                KeyEvent::new(KeyCode::Numpad0, KeyState::Down),
                Some(DecodedKey::Unicode('0')),
            ),
            (KeyEvent::new(KeyCode::Numpad0, KeyState::Up), None),
            // Numlock OFF
            (
                KeyEvent::new(KeyCode::NumpadLock, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::NumpadLock)),
            ),
            (KeyEvent::new(KeyCode::NumpadLock, KeyState::Up), None),
            // Now KP_0 produces INSERT
            (
                KeyEvent::new(KeyCode::Numpad0, KeyState::Down),
                Some(DecodedKey::RawKey(KeyCode::Insert)),
            ),
            (KeyEvent::new(KeyCode::Numpad0, KeyState::Up), None),
        ];
        process_keyevents(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_1_down_up_down() {
        let mut k = Keyboard::new(
            ScancodeSet1::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            (0x1e, Some(KeyEvent::new(KeyCode::A, KeyState::Down))),
            (0x9e, Some(KeyEvent::new(KeyCode::A, KeyState::Up))),
            (0x1f, Some(KeyEvent::new(KeyCode::S, KeyState::Down))),
        ];

        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_1_ext_down_up_down() {
        let mut k = Keyboard::new(
            ScancodeSet1::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            (0xe0, None),
            (
                0x1c,
                Some(KeyEvent::new(KeyCode::NumpadEnter, KeyState::Down)),
            ),
            (0xe0, None),
            (
                0x9c,
                Some(KeyEvent::new(KeyCode::NumpadEnter, KeyState::Up)),
            ),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_2_poweron() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [(
            0xAA,
            Some(KeyEvent::new(KeyCode::PowerOnTestOk, KeyState::SingleShot)),
        )];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_2_toomanykeys() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [(
            0x00,
            Some(KeyEvent::new(KeyCode::TooManyKeys, KeyState::SingleShot)),
        )];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_2_down_up() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Down))),
            (0xF0, None),
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Up))),
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Down))),
            (0xF0, None),
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Up))),
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Down))),
            (0xF0, None),
            (0x29, Some(KeyEvent::new(KeyCode::Spacebar, KeyState::Up))),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_set_2_ext_down_up() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Us104Key,
            HandleControl::MapLettersToUnicode,
        );
        let test_sequence = [
            (0xE0, None),
            (0x6C, Some(KeyEvent::new(KeyCode::Home, KeyState::Down))),
            (0xE0, None),
            (0xF0, None),
            (0x6C, Some(KeyEvent::new(KeyCode::Home, KeyState::Up))),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_pause_set1() {
        let mut k = Keyboard::new(
            ScancodeSet1::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Pause keypress generates this sequence all in one go. There is no
        // 'Break' code for this key.
        let test_sequence = [
            // rctrl2
            (0xE1, None),
            (
                0x1D,
                Some(KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Down,
                }),
            ),
            // Numlock
            (
                0x45,
                Some(KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Down,
                }),
            ),
            // Release rctrl2
            (0xE1, None),
            (
                0x9D,
                Some(KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Up,
                }),
            ),
            // Release Numlock
            (
                0xC5,
                Some(KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Up,
                }),
            ),
        ];

        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_pause_set2() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Pause keypress generates this sequence all in one go. There is no
        // 'Break' code for this key.
        let test_sequence = [
            // rctrl2
            (0xE1, None),
            (
                0x14,
                Some(KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Down,
                }),
            ),
            // Numlock
            (
                0x77,
                Some(KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Down,
                }),
            ),
            // Release rctrl2
            (0xE1, None),
            (0xF0, None),
            (
                0x14,
                Some(KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Up,
                }),
            ),
            // Release Numlock
            (0xF0, None),
            (
                0x77,
                Some(KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Up,
                }),
            ),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_pause_events() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Pause keypress generates this sequence all in one go. There is no
        // 'Break' code for this key.
        let test_sequence = [
            // rctrl2
            (
                KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Down,
                },
                Some(DecodedKey::RawKey(KeyCode::RControl2)),
            ),
            // Numlock
            (
                KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Down,
                },
                Some(DecodedKey::RawKey(KeyCode::PauseBreak)),
            ),
            // Release rctrl2
            (
                KeyEvent {
                    code: KeyCode::RControl2,
                    state: KeyState::Up,
                },
                None,
            ),
            // Release Numlock
            (
                KeyEvent {
                    code: KeyCode::NumpadLock,
                    state: KeyState::Up,
                },
                None,
            ),
        ];
        process_keyevents(&mut k, &test_sequence);
    }

    #[test]
    fn test_print_screen_set1() {
        let mut k = Keyboard::new(
            ScancodeSet1::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Print Screen keypress generates this sequence on make and break.
        let test_sequence = [
            // ralt2
            (0xE0, None),
            (
                0x2A,
                Some(KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Down,
                }),
            ),
            // Print Screen
            (0xE0, None),
            (
                0x37,
                Some(KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Down,
                }),
            ),
            // Release Print Screen
            (0xE0, None),
            (
                0xB7,
                Some(KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Up,
                }),
            ),
            // Release ralt2
            (0xE0, None),
            (
                0xAA,
                Some(KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Up,
                }),
            ),
        ];
        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_print_screen_set2() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Print Screen keypress generates this sequence on make and break.
        let test_sequence = [
            // ralt2
            (0xE0, None),
            (
                0x12,
                Some(KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Down,
                }),
            ),
            // Print Screen
            (0xE0, None),
            (
                0x7C,
                Some(KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Down,
                }),
            ),
            // Release Print Screen
            (0xE0, None),
            (0xF0, None),
            (
                0x7C,
                Some(KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Up,
                }),
            ),
            // Release ralt2
            (0xE0, None),
            (0xF0, None),
            (
                0x12,
                Some(KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Up,
                }),
            ),
        ];

        add_bytes(&mut k, &test_sequence);
    }

    #[test]
    fn test_print_screen_events() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );

        // A Print Screen keypress generates this sequence on make and break.
        let test_sequence = [
            // ralt2
            (
                KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Down,
                },
                Some(DecodedKey::RawKey(KeyCode::RAlt2)),
            ),
            // Print Screen
            (
                KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Down,
                },
                Some(DecodedKey::RawKey(KeyCode::PrintScreen)),
            ),
            // Release Print Screen
            (
                KeyEvent {
                    code: KeyCode::PrintScreen,
                    state: KeyState::Up,
                },
                None,
            ),
            // Release ralt2
            (
                KeyEvent {
                    code: KeyCode::RAlt2,
                    state: KeyState::Up,
                },
                None,
            ),
        ];

        process_keyevents(&mut k, &test_sequence);
    }

    #[test]
    fn test_modifier_state_shift() {
        let mut k = Keyboard::new(
            ScancodeSet2::new(),
            layouts::Uk105Key,
            HandleControl::MapLettersToUnicode,
        );
        assert!(!k.get_modifiers().lshift);

        k.process_keyevent(KeyEvent {
            code: KeyCode::LShift,
            state: KeyState::Down,
        });
        assert!(k.get_modifiers().lshift);

        k.process_keyevent(KeyEvent {
            code: KeyCode::LShift,
            state: KeyState::Up,
        });
        assert!(!k.get_modifiers().lshift);
    }
}

// ****************************************************************************
//
// End Of File
//
// ****************************************************************************