当前文档版本为 v0.5.0,您可以访问当前页面的 开发中 版本以获取最近可能的更新。

Driver: KSCAN

1 功能概述

kscan sample演示了Zephyr Kscan Driver在PAN1080 SoC上的使用方法,主要包括:

  • 硬件连接 8*8 keyboard 板

  • 软件配置,使能kscan模块,通过按键进行按键信息的上报打印

2 环境准备

  • PAN108XXB5 EVB (1MB Flash、64 Pin)

    • KSCAN 例程仅支持 64pin 封装 SoC

  • USB-TypeC 线一条(用于供电和查看串口打印 Log)

  • 硬件接线:

    • 使用 USB 线,将 PC USB 与 EVB USB-TypeC(USB->UART)相连

    • 将8*8键盘板按照卡槽位置插入开发板MATRIX BUTTON接口位置

      • 需要注意KSCAN配置的特定IO pin如下表,复用接口不要在板上其他接口连接,否则可能引起kscan输入端口被拉动,按键被异常检测

        kscan output pin

        kscan input pin

        p5_0_kscan_o0

        p2_0_kscan_i0

        p5_1_kscan_o1

        p2_1_kscan_i1

        p4_0_kscan_o2

        p2_2_kscan_i2

        p5_3_kscan_o3

        p2_3_kscan_i3

        p5_5_kscan_o4

        p1_4_kscan_i4

        p5_7_kscan_o5

        p1_5_kscan_i5

        p0_0_kscan_o6

        p1_6_kscan_i6

        p0_1_kscan_o7

        p1_7_kscan_i7

  • PC软件: 串口调试助手(UartAssist)或终端工具(SecureCRT),波特率921600

3 编译和烧录

例程位置:zephyr\samples_panchip\drivers\kscan

使用 ZAL 工具可以对其进行编译、烧录、打开 VS Code 调试等操作。关于 ZAL 工具的详细介绍请参考:Zephyr APP Launcher 工具介绍

4 演示说明

本例程中:

  • 8*8 键盘 从左下坐标定义为Key(1,1),右上到Key(8,8),初始复位后无按键信息

  • 对应按键被按下时,如Key(1,1),打印LOG row 1 col 1 pressed 1

  • 对应按键被抬起时,如Key(1,1),打印LOG row 1 col 1 pressed 0

  • 可以检测任意或者全部单个按键的正确性

  • 可以检测组合按键的正确性

5 开发者说明

5.1 KCONFIG说明

使能KSCAN功能需要在prj.conf内使能CONFIG_KSCAN,用来控制KSCAN功能总开关

5.2 API说明

KSCAN API包括以下上层接口

__subsystem struct kscan_driver_api {
	kscan_config_t config;
	kscan_disable_callback_t disable_callback;
	kscan_enable_callback_t enable_callback;
};

调用kscan_config完成接口初始化

/**
 * @brief Configure a Keyboard scan instance.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param callback called when keyboard devices reply to to a keyboard
 * event such as key pressed/released.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
__syscall int kscan_config(const struct device *dev,
			     kscan_callback_t callback);

需要 应用端 注册回调函数,如下函数,作为callback参数传入kscan_config

static void kb_callback(const struct device *dev, uint32_t row, uint32_t col,
			bool pressed)
{
	printk("row %d col %d pressed %d\n", row, col, pressed);
}

最后调用kscan_enable_callback完成回调函数使能

/**
 * @brief Enables callback.
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
__syscall int kscan_enable_callback(const struct device *dev);

或者调用kscan_disable_callback完成回调函数注销

/**
 * @brief Disables callback.
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
__syscall int kscan_disable_callback(const struct device *dev);

5.3 注意事项

  • KSCAN为硬件实现的按键扫描硬件,具有硬件固定配置端口,不能随意更改pin脚,因此KSCAN模块必须选用PAN1080A-AFLD (LQFP封装、1MB Flash、64 Pin)

  • KSCAN硬件可以配置输入接口拉动方式(上拉或者下拉),此8*8 keyboard 模块由于硬件设计需要对应配置管脚下拉、检测上拉,如dts文件配置

    • DT_PAN_PINS(p2, 0, kscan_i0, PAN1080_PIN_FUNC_P20_KSCAN_I0, bias-pull-down, input-enable);
      DT_PAN_PINS(p2, 1, kscan_i1, PAN1080_PIN_FUNC_P21_KSCAN_I1, bias-pull-down, input-enable);
      DT_PAN_PINS(p2, 2, kscan_i2, PAN1080_PIN_FUNC_P22_KSCAN_I2, bias-pull-down, input-enable);
      DT_PAN_PINS(p2, 3, kscan_i3, PAN1080_PIN_FUNC_P23_KSCAN_I3, bias-pull-down, input-enable);
      DT_PAN_PINS(p1, 4, kscan_i4, PAN1080_PIN_FUNC_P14_KSCAN_I4, bias-pull-down, input-enable);
      DT_PAN_PINS(p1, 5, kscan_i5, PAN1080_PIN_FUNC_P15_KSCAN_I5, bias-pull-down, input-enable);
      DT_PAN_PINS(p1, 6, kscan_i6, PAN1080_PIN_FUNC_P16_KSCAN_I6, bias-pull-down, input-enable);
      DT_PAN_PINS(p1, 7, kscan_i7, PAN1080_PIN_FUNC_P17_KSCAN_I7, bias-pull-down, input-enable);
      
  • KSCAN硬件可以配置扫描周期,检测原理为按行扫描(按照行扫描间隔),扫描整个矩阵后,如果有按键变化产生中断,进行按键状态解析,等待帧扫描间隔后,进行下一次扫描

    • 因为扫描周期的缘故,kscan不需要太快的进行按键操作,防止同一周期内按键两次变化导致不上报

6 RAM/Flash资源使用情况

Memory region         Used Size  Region Size  %age Used

FLASH:       16728 B      1020 KB      1.60%

SRAM:        3928 B        64 KB      5.99%