Manual Mode

This sample application note describes keyscan manual scan mode to implement matrix keyboard scanning.

Key press debounce and key release debounce are realized by a software timer.

When the single scan is completed, the Keyscan single scan completion interrupt is entered and the key information is read within the interrupt handler function.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

For more requirements, please refer to Quick Start.

Wiring

The EVB is connected to a matrix keyboard module, connect P2_3 to ROW0, P2_4 to ROW1, P4_0 to COLUMN0, and P4_1 to COLUMN1.

External matrix keyboard is shown below:

Here should be a picture of the external matrix keyboard — External Matrix keyboard

Building and Downloading

This sample can be found in the SDK folder:

Keil

Project file: samples\peripheral\keyscan\keyscan_manual\proj\rtl87x2g\mdk

GCC

Project file: samples\peripheral\keyscan\keyscan_manual\proj\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

Open sample project file.
To build the target, follow the steps listed on the Generating App Image in Quick Start.
After a successful compilation, the app bin app_MP_xxx.bin will be generated in the directory mdk\bin or gcc\bin.
To download app bin into EVB board, follow the steps listed on the MP Tool Download in Quick Start.
Press reset button on EVB board and it will start running.

Experimental Verification

When the EVB starts, observe the following log within the Debug Analyzer.
```
Start keyscan manual test!
```

Initialize the keyscan software timer, print log.

[io_keyscan] timer_keyscan_init: keyscan timer init

Print key information when a key press is detected.
1. If a single key press is detected, print the following log.
```
[io_keyscan] io_keyscan_handle_keys: Single key press. key: (x, x)
```
2. If two key presses are detected, print the following log.
```
[io_keyscan] io_keyscan_handle_keys: Two key press. key0: (x, x), key1: (x, x)
```

When all keys are released, print the following log.

[io_keyscan] io_keyscan_handle_keys: All keys release.

Code Overview

This chapter will be introduced according to the following several parts:

Source Code Directory.
Peripheral initialization will be introduced in chapter Initialization.
Functional implementation after initialization will be introduced in chapter Functional Implementation.

Source Code Directory

Project Directory: sdk\samples\peripheral\keyscan\keyscan_manual\proj
Source Code Directory:: sdk\samples\peripheral\keyscan\keyscan_manual\src

Source files are currently categorized into several groups as below.

└── Project: keyscan_manual
    └── secure_only_app
        └── Device                   includes startup code
            ├── startup_rtl.c
            └── system_rtl.c
        ├── CMSIS                    includes CMSIS header files
        ├── CMSE Library             Non-secure callable lib
        ├── Lib                      includes all binary symbol files that user application is built on
            └── rtl87x2g_io.lib
        ├── Peripheral               includes all peripheral drivers and module code used by the application
            ├── rtl_rcc.c
            ├── rtl_pinmux.c
            ├── rtl_nvic.c
            └── rtl_keyscan.c
        └── APP                      includes the ble_peripheral user application implementation
            ├── main_ns.c
            └── io_keyscan.c

Initialization

The initialization process includes global_data_keyscan_init board_keyboard_init driver_keyboard_init and timer_keyscan_init.

global_data_keyscan_init contains the initialization of the key information storage array.

board_keyboard_init contains the PAD and PINMUX settings.

Config PAD: Set pin as PINMUX mode, PowerOn, no internal Pull-Up or Pull-Down.
Configure PINMUX: multiplex pins to KEY_ROW_0, KEY_ROW_1, KEY_COL_0 and KEY_COL_1 separately.

driver_keyboard_init contains the initialization of the Keyscan peripheral.

Enable PCC clock.
Set the rowSize and colSize to a 2*2 matrix keyboard.
Set scan mode to manual scan mode.
Enable the hardware debounce function of keyscan.
Enable KEYSCAN_INT_SCAN_END interrupt.

RCC_PeriphClockCmd(APBPeriph_KEYSCAN, APBPeriph_KEYSCAN_CLOCK, ENABLE);
...
KEYSCAN_InitStruct.rowSize  = KEYBOARD_ROW_SIZE;
KEYSCAN_InitStruct.colSize  = KEYBOARD_COLUMN_SIZE;
KEYSCAN_InitStruct.scanmode = KeyScan_Manual_Scan_Mode;
KEYSCAN_InitStruct.debounceEn = ENABLE;
...
KeyScan_INTConfig(KEYSCAN, KEYSCAN_INT_SCAN_END, ENABLE);
...

timer_keyscan_init contains the initialization of the software timer.

Execute os_timer_create to create a software timer, set the time interval to 200ms with a callback function called timer_keyscan_callback, which is used to simulate debounce for Keyscan key presses.

os_timer_create(&KeyScan_Timer_Handle, "keyscan_timer",  1, KEYSCAN_SW_INTERVAL, false, timer_keyscan_callback);

Functional Implementation

The program will start a 200ms software timer and enable the Keyscan peripheral to perform a manual scan. In the KEYSCAN_INT_SCAN_END ISR, if a key press is detected, set Key_Pressed_Flag to 1, restart the 200ms timer, and re-enable Keyscan to start the next scan.

Repeat the above process, when the 200ms timer expires, restart a 10ms software timer to simulate debouncing the key release. After the 10ms timer expires, check the Key_Pressed_Flag. If it is 0, it means that all keys have been released during the scan, otherwise it means that there are still keys being pressed.

Execute os_sched_start to start task scheduling.
Enable manual scan mode when a key is pressed. When a single scan is completed, enter the interrupt handler.
1. Mask KEYSCAN_INT_SCAN_END interrupt.
2. Execute KeyScan_GetFifoDataNum() to read the data length in Keyscan FIFO.
3. Execute KeyScan_Read() to read the value of data in Keyscan FIFO.
4. Set Key_Pressed_Flag to true, which indicates that a key is currently pressed.
5. Restart the software timer for 200ms debounce time to check press status.
6. Print the scan result.
7. Unmask the KEYSCAN_INT_SCAN_END interrupt.

KeyScan_INTMask(KEYSCAN, KEYSCAN_INT_SCAN_END, ENABLE);
fifo_length = (uint32_t)KeyScan_GetFifoDataNum(KEYSCAN);
KeyScan_Read(KEYSCAN, (uint16_t *)&Current_Key_Data.key[0], fifo_length);
Key_Pressed_Flag = true;
if (!os_timer_restart(&KeyScan_Timer_Handle, KEYSCAN_SW_INTERVAL))
{
  ...
}
...
KeyScan_INTMask(KEYSCAN, KEYSCAN_INT_SCAN_END, DISABLE);

When the 200ms timer ends, enter the callback function timer_keyscan_callback, check the Key_Pressed_Flag.

If the flag bit is true, it indicates that a key is currently being pressed.
1. Set the flag bit to false.
2. Execute driver_keyboard_init to initialize the Keyscan peripheral, enable the Keyscan to restart keyboard scanning.
3. Restart the software timer for 10ms debounce release time.
If the flag bit is false, no key is currently pressed.
1. Print all key release information.
2. Execute global_data_keyscan_init to reinitialize the keyscan global data.
3. Execute driver_keyboard_init to initialize the Keyscan peripheral driver.

if (true == Key_Pressed_Flag)
{
    Key_Pressed_Flag = false;
    driver_keyboard_init(ENABLE);

    /* Start timer to check key status */
    os_timer_restart(&p_xTimer, KEYSCAN_SW_RELEASE_TIMEOUT);
}
else
{
    /* Keyscan release event detected */
    DBG_DIRECT("[io_keyscan] io_keyscan_handle_keys: All keys release.");

    global_data_keyscan_init();
    driver_keyboard_init(ENABLE);
}