【代码库】MCXN 上的触摸键盘调节_电路方案

MCXN 上的触摸键盘调节

该演示展示了如何使用 NXP 触摸感应库和 Python 工具来调整电容式触摸键盘的灵敏度
NXP 合作伙伴可以通过其 NXP 代表获取 TSI EVB 板
为了精确调整键盘灵敏度，建议使用“人造手指”探头。

板材：定制板材

类别：HMI、触摸感应

外围设备：TSI

工具链：IAR、MCUXpresso IDE

1.软件

该软件演示了如何在支持 TSI 外设的 MCXN 设备上运行 NXP 触摸库。该示例还展示了如何使用基于 Python 脚本的工具进行触摸感应键盘的灵敏度校准。
至少需要 NXP Touch 库 SW 版本 2.11 和修改后的按键检测器“MBW”来支持由 Python 调校工具计算的校准值。
检查文件“nt.h”NXP TOUCH 版本。

2.硬件

对于此演示，您将需要以下硬件。

X-MCX-N9XX-TSI 板。

MCX-TSI 板框图。

3. 设置

3.1 步骤 1

克隆存储库并将其导入工作区后，使用 J8 连接器中的 micro-USB 线将开发板连接到电脑。将 J-Link 调试器线连接到板载 SWD 接头 J1。

3.2 第 2 步

尝试将演示应用程序下载到开发板并测试其功能。我们将使用基于 Python 的调优工具进行灵敏度调优。

3.3 步骤 3

基于 Python 的触摸调节工具提供了调节 NXP TSI 库的多个参数的程序，并生成“nt_setup.c”文件，其中包含针对每个按键单独调整的硬件灵敏度调节以及按键检测器 MBW 所需的特定校准值。
调优工具假设 NSTEP 值以与 TSI 库相同的速率记录到串行总线 (UART) 或 J-Link 连接。NSTEP 值对应于原始 TSI 计数器值，其在按钮“触摸事件”下的变化反映了通道灵敏度，而“释放状态”下的 NSTEP 抖动反映了系统噪声水平。
从嵌入式软件的角度来看，通信由源文件“tsitrace.c”管理。测量信号以短数据包的形式传递到 UART 缓冲区，而 J-Link 访问的数据则以结构体的形式存储在 RAM 表中，起始地址为“tsispecificrw”，该地址在 ARM 内存映射中对应于 0x20000000。有关详细信息，请参阅“tsitrace.c”、结构体 TsiTraceData 和设备链接器文件（即 IAR EWARM 项目的 *.icf 文件）。j-Link 的 Python 通信要求数据表位于此地址。

4. 触摸调音

单个 Python 脚本 url{tuningGuide.py} 可指导用户完成调优过程。调用方式如下：

Python tuningGuide.py -h
用法：tuningGuide.py [-h] [-p PROTOCOL] [-s SNRTARGET] [-f FILENAME] 选项：
-h，--help 显示此帮助消息并退出
-p PROTOCOL，--protocol PROTOCOL
协议（jlink 或 uart）
-s SNRTARGET，--snrTarget SNRTARGET
目标 SNR
-f FILENAME，--filename FILENAME
JSON 文件名，包含基本 HW 分配和参数

支持的连接是 J-Link 调试器 (SWD) 或 UART。J-Link 接口可能适用于大多数情况。
filename 是 JSON 配置文件的名称，其中包含基本的 TSI 输入名称和通道分配，这些内容根据 SDK 示例和 SDK“board.h”文件中的定义进行配置。
这些定义将被工具用于生成“nt_setup.c”文件。
在调整的第 3 阶段使用 SNR（信噪比）目标。
请参阅示例 *.bat 文件以了解运行脚本的正确命令行格式。

4.1 JSON配置文件（引脚配置文件）

除了 TSI 通道分配外，该文件还包含更多关于主动屏蔽使用情况、给定输入的自模式或互模式以及与所需灵敏度和软件阈值相关的重要硬件配置值的参数。文件底部包含软件项目文件“nt_setup.c”的路径，该文件将在调试过程中多次重新生成和更新。

详情请见“pinConfigXXX.json”文件内容，部分参数将在后续章节中进一步讲解。

4.2 初始 TSI 硬件配置

Python 脚本会提示用户输入所需的时钟频率，并设置主时钟和 PRBS 参数，使其尽可能接近该时钟频率。在每个描述的阶段之后，该工具都会生成一个文件“ntsetuptuningX.c”，用于生成映像并将其烧录。该工具还会生成输出 JSON 文件“tuning_output.json”，其中包含大多数测量值和计算值（适合分析）。
TSI 工作时钟频率需要尽可能高：最高时钟频率和最小时钟分频器是最佳选择。这样的设置可以获得较高的 NSTEP 值，从而实现最佳的数值精度。此外，应禁用 SSC 模式（从而提高时钟速度）。增量电压“DVOLT”应尽可能大（2.0V），这也能最大化 NSTEP。
然而TSI的最高时钟频率会受到PCB物理因素的限制，主要是信号走线的寄生电容。
使用有源屏蔽时，应启用 SSC（扩频调制时钟）以降低 EMI。对于板载有源屏蔽，实际时钟限制约为 2MHz。
建议禁用“灵敏度提升”。（“enableSensitivity = false”）
应禁用关键检测器中的传统平滑方法“signal_filter.coeff1=0”
一开始，TSI HW“抽取”设置为最小值
可以在 Python 脚本中手动仔细编辑“nt_setup.c”的生成内容。
电流放大器应设置为最小输入电流增益，配置为

SXIN=$frac{1}{8}$, SXCH=116

4.3 运行调优脚本

启动调优工具时，会显示“控制台菜单”，供用户选择所需的调优阶段。调优过程包含 4 个连续阶段，每个阶段结束后，“ntsetup”配置文件都会使用新参数进行更新。JSON 配置文件必须指向正确的 SW 项目目录，才能更新“ntsetup.c”文件。该工具会指导用户在每个阶段结束后使用更新后的设置重新编译并刷新 SW 项目。建议一次性运行所有调优阶段并按照要求的步骤操作，无需关闭控制台窗口。

控制台菜单出现，用户按下相应键即可继续。控制台窗口必须处于焦点状态。

控制台菜单

调整阶段 0

首先，用户应从菜单中选择阶段 0，这将生成基本的“根”设置文件。该工具会要求用户选择 TSI 开关频率，并考虑到 PRBS 时钟调制和有源屏蔽使用的已知物理限制。开关频率越高，NSTEP 分辨率就越高，但根据 PCB 设计，应检查 TSI 通道和有源屏蔽信号的波形是否正确。该工具会自动计算最接近的频率，并选择合适的时钟设置生成到根设置文件中。抽取参数全部设置为 1，这意味着一开始不使用抽取。项目重新编译并包含根“nt_setup.c”文件后，并重新刷新软件，用户需要按 Enter 键继续执行以下阶段 1。

调整阶段 1

在此阶段开始时，将确定传感器数量并测量采样率（扫描时间的倒数）。接下来，测量基线 PETSN 值。在此步骤中，请勿触摸面板。对所有电极进行 1 秒的记录，并计算平均 NSTEP 值。在此阶段，用户不得触摸任何按钮！取最小 NSTEP 值来确定 PETSN 值的数值余量，然后使用该余量来确定 TSICNT_SHIFT。PETSN 值与 NSTEP 值的倒数成正比。PETSN 值的计算公式如下：

磷埃T秒北=

'_' 仅在数学模式下允许

$frac{2^{(20+text{TSICNT_SHIFT})}}{text{NSTEP}}$

注意：对于互电容模式输入，不使用 PETSN 值，而是使用非反转 NSTEP 值。

测量基线后，用户必须触摸所有按键一次，以确定各个按键的最大 NSTEP 增量激活值。对结果进行平均，并捕获平均最大激活值，根据 JSON 配置文件中“minnstep”的期望值，估算各个按键所需的合适抽取因子。这意味着，对于灵敏度较低的按键，建议使用更高的抽取率，以累积更高的 NSTEP 增量值，并提高此类按键的信噪比 (SNR)。捕获所有按键激活值后，即可关闭图表，并使用针对各个输入端建议的抽取值更新“ntsetup.c”文件。该工具会指示用户重新编译并刷新应用程序。完成此操作后，用户即可继续进行第 2 阶段。

橙色：平均峰值激活，蓝色：即时信号/噪声

这意味着，对于灵敏度较低的按钮，建议使用更高的抽取率，以累积更高的 NSTEP 增量值并提高此类按钮的信噪比 (SNR)。一旦捕获到所有按钮激活，即可关闭图表，并使用针对各个输入的建议抽取率值更新“nt_setup.c”文件。该工具会指示用户重新编译并刷新应用程序。完成此操作后，用户可以继续进行第 2 阶段。

调整阶段 2

在此阶段，将确定每个按钮的激活阈值以及整数“deltamultiplier”和“deltadivider”值。为此，需要确定预期的 PETSN 增量值。首先，为每个按钮确定一个粗略的激活阈值，并将阈值设置为第 1 阶段测量的基线信号估计抖动的 4 倍（硬编码在 Python 脚本中）。在此阶段，需要触摸每个按钮。该工具将自动检测哪个电极被触摸，并确定平均激活值。蓝色表示瞬时激活，橙色表示平均峰值。获取正确的平均值可能需要更长时间，因此用户应仔细监控平均激活值，因为不正确的测量可能会混淆平均值。

为了进行更精确的调整，用户可以只选择一个需要调整的输入，并在各个输入校准之间使用 GUI 菜单中“暂停”按钮。此阶段对于精确测量和正确的手指定位至关重要。如果出现错误，可以再次选择测量错误的按钮并重新校准。收集到所有激活值后，即可手动关闭图表。在此阶段，这些信息将用于生成“actMat”数组以减少串扰。使用平均激活值，计算“deltamultiplier”和“deltadivider”值，以达到目标值 2500。使用这些值，预计 delta PETSN 值在操作过程中的幅度会均衡。接下来，为每个按钮确定一个阈值，即预期（平均）均衡值的 80%。ΔPETSN值。在此阶段，工具自动切换到第 3 阶段，计算其余参数。获取的参数将添加到输出 JSON 文件中。

红色：即时（峰值）激活，橙色：平均峰值激活，蓝色：按钮即时噪音，

调整阶段 3

标准化的 PETSN 信号可以通过时间常数为τ时间常数应根据所需的信噪比进行设置。较高的时间常数会增加信噪比，但会减慢从基线到活动水平的转换速度，从而增加检测延迟。信噪比定义为ΔPETSN无触摸时 PETSN 信号的触摸抖动（峰峰值）期间的电平。

在 Python 工具的第三阶段，将针对每个按钮分别优化时间常数，以达到目标信噪比（默认值为 10）。它还将测量“最小噪声限值 (minnoiselimit)”。图中显示了“最小噪声限值 (minnoiselimit)”和信噪比与平滑时间常数的关系。在这种情况下，无需平滑即可达到所需的信噪比。在参数文件中，“信号噪声比 (signaltonoiseratio)”设置为目标信噪比的 80%。请注意，此参数与“最小噪声限值 (minnoise_limit)”共同定义检测阈值。

参数文件生成

关闭图形后，“ntsetup.c”文件最终更新，应用程序可以重新编译。生成的文件“ntsetuptuning2.c”包含最终的软件设置。文件“tuningoutput.json”包含在各个调优阶段测量的所有重要值以及用于校准的计算值。这些值可以进一步处理或用于统计。

Python 工具的输出

调优结果

为了验证调优结果，可以使用 Python 脚本“traceTsi”来追踪键盘信号。运行“trace.bat”进行信号追踪。查看批处理文件内容，了解可能的参数。

Python traceTsi.py -p jlink -t 0 -l 15 -f 信号.txt

追踪键盘信号

5. 生成的设置

Python 调优工具根据 Python 硬编码模板设置和用户定义的 JSON 引脚配置文件生成输出“nt_setup.c”文件。
为所有电极生成默认和单独的关键探测器 MBW 参数。
为所有电极生成默认和单独的“nt_electrode”设置。
硬件配置源自默认配置，各个参数（抽取、屏蔽配置）均由 Python 工具进行微调。抽取因子由 Python 工具根据通道灵敏度和 JSON 引脚配置文件中所需的“min_nstep”值进行调整。
请参阅“nt_setup.c”以了解详情。

硬件配置

const tsiconfigt tsihwconfigEl1 = {
DEFAULTHWCONFIG，
.configSelfCap.commonConfig.decimation = kTSISincDecimationValue8，
.configSelfCap.enableShield = kTSI_shieldAllOff
};

Keydetector MBW 配置

定义 DEFAULTMBW

.signalfilter.coef1 = 0,
.baseavrg.n2order = 12,
.nonactivityavrg.n2order = 15,
.entryeventcnt = 0,
.deadbandcnt = 0,
.baselinetrackwindow = 4000,
.baselinetrackwindowtouch = 16000,
.touchlimit = 3,
.tausmoothbaseline = 5000,
.debouncelength = 0,
.baselinedebouncelength = 20

baseline_track_window - 基线跟踪窗口长度，单位为[ms]（例如，2000 表示 50Hz 频率的 2s 窗口，或 20ms 时间周期）。不能为零。
baseline_track_window_touch - 触摸事件的基线跟踪窗口长度（较长，即较慢的自适应窗口），单位为[ms]（例如，2000 表示 50Hz 频率下 2s 的窗口，或 20ms 的时间段）。设置为零表示触摸期间基线自适应冻结。
touch_limit - 如果使用无触摸事件或低触摸事件正常基线适应，则在使基线适应更快之前的最大触摸次数（过多的触摸可能是意外的）。
tau_smooth_baseline - 基线跟踪的平滑时间常数（以[ms]为单位）。
debounce_length - 信号去抖动窗口的大小 [numofsamples]，运行时毛刺滤波器用于提高 EMC 免疫力（0 = no_debounce，3-5 = 推荐用于 EMC）。
baseline_debounce_length - 重置后仅用于基线建立时间的初始中值滤波（毛刺滤波器）的长度 [numofsamples]（0 = no_debounce）。

const struct ntkeydetectormbw ntkeydetectormbwEl1 = {
DEFAULTMBW，
.tausmoothsignal = 11，
.minnoiselimit = 108，
.signaltonoise_ratio = 8
};

tau_smooth_signal - 信号初始固定平滑的平滑时间常数（以 [ms] 为单位），可以取代传统 uSAFA keydec 中的传统 iir 信号滤波，从而实现更快的响应。
min_noise_limit - 用于噪声基底适应的最小噪声值
signal_to_noise_ratio - 用于计算触摸阈值，公式为：(signaltonoiseratio) * (minnoise_limit)。用户可以根据需要手动调整这两个值，以改善按钮的响应。

电极配置

const struct ntelectrode El1 = {
.multiplier = 73,
.divider = 3,
.offset = 1791,
.deltamultiplier = 64,
.deltadivider = 64,
.keydetectorparams.mbw = &ntkeydetectormbwEl1,
.keydetectorinterface= &ntkeydetectormbwinterface,
.pininput = BOARDTSISELFELECTRODE1,
.tsicntshift = 3,
.tsihwconfig = ( void* )&tsihwconfigEl_1
};

?乘数?- 应用于完整测量信号的乘数
?分频器?- 应用于完整测量信号的分频器
?偏移量?- 为实现通道均衡，需要从测量信号中减去的偏移量
delta_multiplier - 均衡增量信号的乘数
delta_divider - 用于均衡的 Delta 信号的分频器
tsicnt_shift - 从原始 TSICNT (NSTEP) 值计算 (反转) PETSN 的比例因子

6. Pin 配置 JSON 文件

以下是引脚配置 JSON 文件的示例内容，用户必须在运行 Python 调试脚本之前定义该文件。附带的 JSON 文件可供参考。某些设备可能不支持某些硬件功能，例如相邻信道屏蔽。

{
“inputlabel”：[
“El1”，
“El2”
]，
“pininput”：[
“EVBBOARDTOUCHPAD1ELECTRODE”，
“EVBBOARDTOUCHPAD2ELECTRODE”
]，
“gpioinput”：[
“{GPIOPTD16，NULL}”，
“{GPIOPTE3，NULL}”
]，
“shieldcfg”：[
“kTSIshieldAllOff”，
“kTSIshieldAllOff”
]， “mutualinput”：[
“false”，
“false”
]， “timeperiodpercentualheadroom”：15，
“minnstep”：50，
“dvoltoption”：3，
“maxdecimation”：20，
“mindecimation”：2，
“deltathreshold”：0.8，
“debouncelength”：0，
“deltatarget”：2500，
“相邻电极”：“kAdjgrounding”，
“输出名称”：“c:/GIT/touchsensing/sw/examples/evbke17z512/ntsetup.c”
}

input_label - SW 中使用的通道电极的逻辑名称
pin_input - 电极 TSI 通道号分配，使用“board.c”中的 SDK 定义
gpio_input - 启用后，与 TSI 通道共享相应的 GPIO 引脚，用于相邻通道接地方法
shield_cfg - 为扫描通道选择哪个屏蔽输出。请参阅设备 RM 和 SDK 了解支持的屏蔽功能。注意：对于 KE17z512 设备，屏蔽可以连接到所有 TSI 输入（请参阅相应的引脚配置以供参考）。
mutual_input - 表示哪个输入是“相互模式”（真）或自限制（假）
time_period_percentual_headroom - 整体键盘扫描时间百分比余量，以允许由于物理原因引起的一些安全裕度。
min_nstep - 在每个通道上测量的最小 NSTEP 值作为灵敏度阈值水平，使用 py Python 工具通过增加抽取来调整灵敏度
dvolt_option - Dvolt 选项寄存器值应根据硬件版本设置为最大值，用法：3 - 对于 Kinetis，5 - 对于 MCXN，请检查设备参考手册。
max_decimation - 抽取调整的上限，值越高，扫描时间越长。
min_decimation - 用于实现“minnstep”值的抽取下限，默认值为 Decimation = 1，工具据此计算适当的值，当默认灵敏度较差时，用户可以在运行调整之前调整 mindecimation。
delta_threshold - 通常设置为最大通道激活的 0.7 到 0.8（即 70-80%），用于按钮触摸阈值计算，允许一些公差。
debounce_length - 样本数量，由按键检测器 MBW 用于消除故障。
delta_target - Python 使用的 Delta 目标激活，用于均衡所有通道激活并计算 SW 均衡的“乘数”和“除数”。
?相邻电极?- 如何处理未扫描的通道以提高触摸应用程序的性能。可用选项：“kAdjdisable”、“kAdjgrounding”和“kAdj_shielding”。某些功能可能在某些设备上不受支持。
output_name在 3 个阶段中由 Python 工具生成和更新的项目“nt_setup.c”文件的路径。

7. 启用 FreeMASTER 支持

可以选择性地启用用于触摸的 FreeMASTER GUI 工具，以允许监控所有可用的触摸感应相关信号并访问负责应用程序“微调”的所有变量并验证正确的功能。
FreeMASTER 源文件已从项目构建中排除。
为了使 Freemaster 运行：- 必须从https://nxp.com/freemaster安装 FreeMASTER PC GUI 应用程序，并遵循许可条款。- 可以将 FreeMASTER 项目文件“*.pmpx”（用于“touch”）作为相应 SDK 包（适用于所需设备）的一部分下载到可选中间件“touch”中。SDK 还包含 FreeMASTER 驱动程序源代码。- 可以单独下载 FreeMASTER 驱动程序源代码，并将其放置在本示例的“middlewarefreemastersrc”项目文件夹中。然后可以在“nttypes.h”中启用 (1) NTFREEMASTER_SUPPORT。
本示例未描述如何使用 FreeMASTER。
注意：项目使用 IAR EWARM 6.40.2 编译