HardwareEventProbe

HardwareEventProbe is a Windows Raw Input timing probe for black-box macro cadence tests. It listens for keyboard macro output, timestamps events with QueryPerformanceCounter, and reports interval statistics such as min/max, p50, p95, p99, and p99.9.

这个工具用于黑盒测量雷云或其它宏工具输出到 Windows 应用层后的输入事件间隔。它使用 Windows Raw Input 接收键盘事件，并用 QueryPerformanceCounter 打时间戳。

What It Measures / 测量范围

• Measures the cadence that normal Windows desktop applications receive.

• Useful for comparing 1 ms, 10 ms, and 100 ms macro delays.

• It does not read mouse firmware, device MCU timers, or kernel driver internals.

• 测量普通 Windows 应用最终收到的输入节奏。

• 适合对比 1ms、10ms、100ms 宏延迟是否按预期到达用户态。

• 不等价于读取鼠标固件、设备 MCU 或内核驱动内部的真实时钟。

Requirements / 环境要求

• Windows 10/11 x64.
• .NET 8 SDK for building/running from source.
• Optional: Razer Synapse or another macro tool that can emit F13/F14 key events.

Quick Start / 快速开始

dotnet build .\HardwareEventProbe.sln --configuration Release
powershell -ExecutionPolicy Bypass -File .\scripts\Run-F13F14-1ms.ps1

Then press the key or mouse button that triggers the imported macro.

然后按下你绑定宏的按键或鼠标侧键。

Razer Test Samples / 雷云测试样例

Import one of these XML files into Razer Synapse:

• samples/razer-f13f14-1ms-200loops.xml
• samples/razer-f13f14-10ms-200loops.xml
• samples/razer-f13f14-100ms-20loops.xml

Recommended command:

powershell -ExecutionPolicy Bypass -File .\scripts\Run-F13F14-1ms.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\Run-F13F14-10ms.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\Run-F13F14-100ms.ps1

CSV traces are written to results/.

Report Fields / 报告字段

• actualIntervalUs: actual interval between adjacent captured macro events.
• actualIntervalMin: smallest actual interval.
• actualIntervalMax: largest actual interval.
• actualIntervalRange: max interval minus min interval.
• intervalErrorUs: absolute distance from the expected interval.
• p50: median; 50% of samples are less than or equal to this value.
• p95: 95% of samples are less than or equal to this value.
• p99: 99% of samples are less than or equal to this value.
• p99.9: 99.9% of samples are less than or equal to this value.
• loopLocalDriftAbs: local drift inside each logical macro loop.
• loopEndLocalDriftAbs: end-of-loop local drift.

Notes / 注意事项

• F13/F14 is recommended because visible keys such as E/Q can be affected by IME, terminals, and focused text fields.

• StartupLatency=unavailable usually means the macro tool swallowed the physical trigger event; interval analysis still works.

• If you stop with Ctrl+C, incomplete capture can still be analyzed through interval metrics.

• over2msCount and over5msCount are mainly useful for 1 ms tests; they are naturally high for 10 ms or 100 ms tests.

• 推荐使用 F13/F14，不建议用 E/Q 这类可见字符键，避免输入法、终端、文本框干扰。

• StartupLatency=unavailable 通常表示宏工具吞掉了物理触发键事件，不影响宏输出间隔分析。

• 通过 Ctrl+C 中途停止时，虽然捕获不完整，仍可查看相邻事件间隔。

• over2msCount 和 over5msCount 主要适合 1ms 测试，10ms/100ms 下自然会很高。