当前文档版本为 v0.8.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不需要太快的进行按键操作，防止同一周期内按键两次变化导致不上报