简介这是一份基于Holtek BS84C12C单片机的触摸按键开发资源包面向需要快速实现触摸输入的嵌入式开发者与电子工程师。BS84C12C为8位低功耗触摸MCU资源包采用官方LIBV413库提供从底层驱动到应用层的完整参考适合作为触控产品研发或学习合泰单片机时的基础工程。压缩包共51个文件体积仅77KB包含asm/inc等汇编与头文件、h/c源文件、obj/lst编译中间文件、pjt/opt工程配置以及map/dbg调试信息覆盖项目从编辑、编译到调试的完整链路便于直接移植或二次修改。已有671人学习下载主要面向需要快速验证触摸按键方案的中高级开发者也可作为初学者熟悉BS84C12C内部结构与库函数的入门范例。资源中保留了主程序、UART测试及触摸库的工程组织关系可帮助理解合泰触摸检测、参数配置和中断处理的实现思路节省从零搭建工程的时间。1. 触摸按键比想象中更依赖库的边界拿到 BS84C12C_20180221_LIBV413_V3 这个包第一反应可能是一个普通例程实际上它是合泰官方针对 BS84C12C 触摸检测功能发布的完整软件库工程。BS84C12C 是带电容触摸模拟前端的 8 位单片机硬件上只要接出感应焊盘和串联电阻触摸检测这件事就交给内部外设完成。但外设怎么配置扫描周期、怎么滤除电源纹波、怎么跟踪环境温漂这部分逻辑如果全自己写工作量不比业务逻辑小。LIBV413 V3 的价值在于把触摸扫描状态机、基线更新、按键阈值比较都封装成了库函数用户工程只需要关心通道映射、事件读取和灵敏度修正。这个包适合两类开发者一类是用 BS84C12C 做智能家电触控面板想尽快把触摸键跑起来另一类是已经在用 Holtek 其他触摸 MCU想看 V3 库相对老版本在扫描时序和滤波参数上有什么变化。下面直接从工程文件的真实结构拆起。2. LIBV413 库文件结构与触摸通道初始化2.1 工程目录里哪些文件不能动把压缩包解开后能看到 BS84C12C_LIBRARY.pjw 和 USER_PROGRAM 两个并行部分。pjw是 Holtek HT-IDE3000 的工程文件双击它会载入整个触摸库工程。这里先要分清库区和用户区的边界。文件或目录归属作用BS84C12C_LIBRARY.pjw / .pjt库工程触摸库主工程编译后生成库文件BS84B12C_LIBRARY.OPT / .pjt库配置工程选项与编译器配置TKS_GLOBE_VARIES.inc库核心触摸全局变量、常量和通道使能定义TKS_GLOBE_VARIES.H库接口给 C 语言调用头文件声明触摸数据缓冲startup1_l.asm库启动复位后初始化 RAM、堆栈和寄存器USER_PROGRAM / UART_TEST用户区示例主程序包含 UART 测试代码OUTPUT编译输出生成的 .OD、.HTB 等烧录文件TKS_GLOBE_VARIES.inc和TKS_GLOBE_VARIES.H是触摸库的“全局数据契约”不要擅自改名。startup1_l.asm属于库启动部分普通用户不用改真正要动的是 USER_PROGRAM 下的主程序。我一般会把工程里的库部分保持原样只在用户区写自己的应用逻辑。这样后续如果合泰放出 LIBV413 的补丁版本可以直接替换库文件夹业务代码不受影响。2.2 TKS_GLOBE_VARIES.inc 中的通道宏定义触摸通道不是拿到板子就能全部工作的BS84C12C 的触摸输入通道需要先在TKS_GLOBE_VARIES.inc里把对应位打开。这个文件看起来像普通汇编头文件但它同时影响库内部的中断向量和扫描表生成。以下是一个常见配置写法; TKS_GLOBE_VARIES.inc 局部片段 ; 触摸通道使能位1 使能0 关闭 TKS_CH0_EN EQU 01H ; KEY0 - PA0 TKS_CH1_EN EQU 02H ; KEY1 - PA1 TKS_CH2_EN EQU 04H ; KEY2 - PA2 TKS_CH4_EN EQU 10H ; KEY4 - PA4跳过PA3不用 ; 汇总到通道使能寄存器 TKS_CH_ENABLE EQU TKS_CH0_EN | TKS_CH1_EN | TKS_CH2_EN | TKS_CH4_EN这里的逻辑是每个触摸通道对应一个位TKS_CH_ENABLE决定库扫描哪些通道。未使能的通道不会参与扫描也不会出现在触摸数据缓冲里。这样能降低扫描周期对功耗敏感的设备尤其关键。需要提醒的是PA3 如果用作其他功能比如 ADC 采样就必须把对应位置 0否则库每次扫描都会占用这个引脚导致外部功能冲突。修改完这个文件后重新编译库工程再编译用户工程触摸通道的扫描表才会更新。2.3 从 startup1_l.asm 到 TKS_Timer 的初始化顺序BS84C12C 的触摸库不是一调用就立即出结果它依赖一个周期性的调度源。startup1_l.asm在复位后先完成 RAM 清零和堆栈指针设置然后跳转到主程序的main。触摸库的初始化在主程序里通常遵循固定顺序// main.c 中触摸库初始化顺序 void main(void) { WDT_Disable(); // 先关看门狗防止长初始化过程被复位 System_Clock_Config(); // 配置 HIRC触摸扫描需要稳定时钟 TKS_Initial(); // 1. 触摸库初始化配置扫描引脚和内部寄存器 TKS_Baseline_Capture(); // 2. 捕获上电基线值 TKS_Scan_Start(); // 3. 启动周期扫描 UART_Init(115200); // 串口用于调试输出 ENABLE_GLOBAL_INT; // 触摸扫描依赖定时中断调度 while(1) { DEBUG_Task(); // 用户主循环读取键值、上报数据 } }这段代码里TKS_Initial负责把TKS_CH_ENABLE里的通道配置到硬件寄存器同时初始化内部状态机。TKS_Baseline_Capture是很多人容易漏掉的一步它会在上电后一段时间内连续采样每个通道形成初始基准线。如果不调用库会以零值为基线第一次触摸就会被误判为环境突变。TKS_Scan_Start之后触摸扫描由库内部的定时器中断驱动主循环不需要干预扫描过程。这样设计的好处是触摸采样周期稳定在毫秒级不会因为主循环里有耗时的串口发送而抖动。3. 触摸扫描寄存器配置与事件读取3.1 原始触摸值存在哪LIBV413 库会把每个通道的原始触摸值、基准值和当前差值都放在TKS_GLOBE_VARIES.H声明的全局数组中。用户程序直接引用这些变量不需要关心触摸外设寄存器地址。以下是常用数据项// TKS_GLOBE_VARIES.H 中触摸数据缓冲相关声明 extern volatile uint16_t TKS_CH0_DATA; // 通道0当前原始值 extern volatile uint16_t TKS_CH0_BASE; // 通道0当前基线值 extern volatile uint16_t TKS_CH0_DIFF; // 通道0差值 原始值 - 基线值 extern volatile uint8_t TKS_KEY_STATUS; // 触摸键状态位bit0对应通道0TKS_CH0_DATA是电容充放电时间计数值数值越大说明感应到的电容越大。手指靠近焊盘时对地电容增大TKS_CH0_DATA会比TKS_CH0_BASE高出几十到几百。TKS_CH0_DIFF是库里做按键判断的直接依据它已经减去了基线。我在调试时会把这三个值同时通过串口发出来光看位状态很难判断阈值设置是否合理。3.2 轮询和中断两种取键方式触摸库产生按键事件后用户代码有两种方式拿结果。最简单的办法是主循环轮询TKS_KEY_STATUS// 主循环轮询方式读取触摸按键 while(1) { uint8_t key TKS_KEY_STATUS; // 读取当前键状态位图 if(key 0x01) { LED_On(0); // 通道0按下 } else { LED_Off(0); } if(key 0x02) { LED_On(1); // 通道1按下 } else { LED_Off(1); } Delay_Ms(5); }轮询适合按键数量少、扫描周期快的场景。TKS_KEY_STATUS不是电平信号它是由触摸库在每次扫描结束后按“差值超过阈值”的条件刷新。所以即使库内部没有做防抖这个值也已经包含了一次完整的扫描判断。另一种方式是让触摸库在按键状态变化时触发中断标记然后在中断里置位用户标志位主循环只处理变化事件。这种方式能减少主循环频繁读取全局变量的开销适合同时处理多个触摸键和 UART 协议控制的场景。3.3 防抖、阈值与基线更新参数LIBV413 V3 库里与灵敏度相关的参数通常在TKS_GLOBE_VARIES.inc顶部集中定义。V3 版本相比早期 Lib 包的改进是增加了基线自动跟随的滤波深度选项以下参数是量产时会反复调整的参数名典型值范围作用TKS_THRESHOLD_LEVEL20 ~ 200触摸判定阈值基于差值绝对值TKS_DEBOUNCE_CNT2 ~ 6连续多少次扫描才确认按键有效TKS_BASELINE_FILTER8 / 16 / 32基线更新滤波深度越大越抗漂移TKS_NOISE_THRESHOLD5 ~ 30小于该差值视为噪声不触发状态变化阈值并不是越大越稳定。阈值设大手指离开焊盘后差值回落慢容易产生长按误判阈值设小电源纹波和61Hz 干扰可能直接穿过防抖窗口。我一般先设置TKS_THRESHOLD_LEVEL 60、TKS_DEBOUNCE_CNT 3然后把板子放在正常桌面上跑 10 分钟观察原始差值峰值。如果基线在不触摸时漂移超过 20就把TKS_BASELINE_FILTER从 16 改到 32让基线跟随得更慢。这里有个容易混淆的点基线滤波变慢刚上电时稳定到真实环境的时间也会变长所以TKS_Baseline_Capture阶段的时间也要相应延长。4. 从触摸值到串口调试改造 UART_TEST 工程4.1 UART_TEST 工程是现成的调试起点压缩包里带了 USER_PROGRAM/UART_TEST 这个独立工程它不是触摸示例而是 BS84C12C 的硬件 UART 通信测试代码。因为触摸库的最终表现要看原始值和差值UART 就成了最直接的调试输出通道。UART_TEST 工程里的串口初始化代码可以直接复用到触摸项目里。BS84C12C 的 UART 使用内部高中频时钟作为波特率发生器初始化时要注意 Baund 参数的误差。115200 波特率在大部分批次里误差小于 1%跑调试日志足够如果要做低功耗产品调试版建议用 9600 或者干脆只在测试板上启串口。4.2 把触摸原始数据通过串口定时上报改造 UART_TEST 工程时我会把每秒输出固定字符串的测试代码删掉换成定时上报触摸差值。下面是一段可用的发送函数// 串口格式化发送触摸键值 void Debug_Send_TouchData(void) { char buf[32]; sprintf(buf, K0:%05u/%05u/%05d\r\n, (unsigned int)TKS_CH0_DATA, (unsigned int)TKS_CH0_BASE, (int)TKS_CH0_DIFF); // 打印原始值、基线值、差值 UART_SendString(buf); }这段代码放在主循环里定时调用比如每 20ms 调用一次。输出格式用字符串拼接上位机可以直接用串口助手打开也可以接入串口波形工具。注意%05d格式化有符号差值时负号会占一位所以只保留三位差值位宽更合适。如果串口发送耗时较长可以在发送前后关闭全局中断避免触摸扫描中断被长时间阻塞。触摸库的扫描中断如果被卡住超过一个扫描周期基线更新会异常按键响应会突然变慢。4.3 实际调参时看的几个关键指标把触摸差值实时打出来后重点观察三条曲线。第一是按下瞬间的差值上升率好的焊盘设计在 10ms 内差值从 0 冲到 100 以上如果上升斜率很缓说明串联电阻太大或焊盘面积偏小。第二是松开后的回落值差值应回到基线附近如果回不到零说明手指残留电荷或 PCB 表面有水分。第三是不触摸时基线本身的波动正常情况下波动幅值应该低于触摸阈值的五分之一。看到基线阶梯状跳变时优先检查电源BS84C12C 的触摸扫描对 VDD 纹波很敏感开关电源供电时需要把触摸供电引脚单独加 100nF 4.7uF 滤波电容。UART 发送线上的振铃也会耦合到触摸电极调试时尽量用短线连接 USB 转串口工具。5. 用 HXT_Editor_V100 校准触摸灵敏度5.1 校准文件从哪里得到库工程里附带的 HXT_Editor_V100 是合泰触摸校准工具它的作用是根据实际 PCB 焊盘和覆盖介质生成一份灵敏度修正参数。运行 HXT_Editor 前先把编译好的烧录文件下载到 BS84C12C保持触摸感应面朝上不要用手指碰触。打开 HXT_Editor 后选择对应的 COM 口点击 Connect工具会通过 UART 读取库内部校准参数。这个过程要求 MCU 侧的 UART_TEST 工程里保留接收命令的处理代码否则工具无法和库通信。5.2 校准对阈值系数的修正校准界面一般会让操作者按顺序点击每个触摸键工具会自动记录每个通道按下时最大差值、松开后最小差值和环境噪声。校准完成后HXT_Editor 会输出一组修正系数这组系数是乘到每个通道差值上的。为什么要乘系数而不是直接改阈值因为不同通道的焊盘走线长度不同导致灵敏度天然不一致走线长的通道差值衰减大走线短的通道差值偏大。修正系数把各通道差值拉到同一水平之后用统一的TKS_THRESHOLD_LEVEL才有意义。校准完成后生成的数据通常以头文件或寄存器值数组形式保存我会把它复制到用户工程中在TKS_Initial之后覆盖对应通道的校准寄存器。5.3 批量生产时把校准参数固化到 Flash单板校准只适合测试阶段量产时不可能每块板都打开 HXT_Editor 人工校准。我一般会在产线烧录时做一次“免校准”处理先用标准覆盖介质厚度比如 2mm 亚克力做一块样板把所有通道的校准参数保存到 MCU 的 Data Flash 区域。对于触摸按键数量固定的产品直接把这些参数作为常量表写入程序每块板出厂时的灵敏度一致性完全取决于 PCB 加工公差。如果 PCB 厂家的板厚和绿油厚度批次波动大可以在测试工装上跑一段自动校准脚本用串口命令触发TKS_Baseline_Capture和阈值系数回读再把回读值写入 Data Flash。这样生产现场只需要治具不需要人工敲键盘。触摸库在这种模式下仍然正常工作因为库启动时会读取 Data Flash 中的修正系数而不是重新捕获一组临时参数。本文还有配套的精品资源点击获取