ESP-IDF里抓WiFi时间戳：三步拿到微秒级TSF，告别“大概几毫秒“

ESP-IDF里抓WiFi时间戳：三步拿到微秒级TSF，告别"大概几毫秒"

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

上次抓包排查"设备上报时间戳抖动"时，抓包软件给的只是主机侧的近似值，根本看不出抖动发生在空口还是协议栈。后来把 ESP-IDF 的 WiFi TSF 时间戳用起来，才发现抖动压根不在链路层——TSF 是设备在射频侧对齐的信标时间，拿它做基线，延迟测量才有意义。

TSF到底在记什么时间

把 TSF 理解成"WiFi 网络里的公共秒表"最贴切：路由器周期性发信标，每个信标都携带一个全局递增的时间计数器，所有 STA 连上后都对齐到同一把"表"上。你调esp_wifi_get_tsf_time()，拿到的就是本机同步后的这个计数器值。

关键参数只需要记三点，声明在components/esp_wifi/include/esp_wifi.h：

• 输入：一个接口枚举，WIFI_IF_STA、WIFI_IF_AP，同时开 AP+STA 时选对应接口
• 输出：int64_t，单位微秒
• 边界：STA 未连接、或连接后还没收到至少一个信标，返回 0

它不是esp_timer_get_time()那种本地时钟，而是"网络时间"，同一 BSS 内所有设备读到的值彼此可比，这是它最值钱的地方。

最小可用链路

整个链路四件事，每步只干一件事，下面只给核心几行。

先把WiFi拉起来

TSF 依赖信标，WiFi 不初始化就什么都没有。标准三件套：

esp_netif_create_default_wifi_sta(); esp_wifi_init(&cfg); esp_wifi_set_mode(WIFI_MODE_STA); esp_wifi_start();

等连接事件，别急着取值

esp_wifi_connect()发出后别立刻读时间戳，在WIFI_EVENT_STA_CONNECTED事件回调里再往下走。注意头文件注释特意提醒：连上之后还要再收到一个信标，TSF 才真正就绪。

取值

int64_t tsf = esp_wifi_get_tsf_time(WIFI_IF_STA);

一行完事，微秒级。

用0做哨兵校验

返回 0 不代表"时间是 0"，它只表示"没同步上"。所以拿到值先判 0，是 0 就别参与计算，退避重试即可。

把时间戳嵌进真实场景

测空口延迟。背景：怀疑某次卡顿出在空口。做法：发送帧前记一个 TSF，收到对应应答帧（或下一个信标对齐事件）后再记一个，差值就是这段链路的耗时，全程不碰主机时钟。效果：延迟数字和抓包软件对得上，排除了主机侧测量噪声。

周期性采样对齐。背景：传感器数据要和网络事件做因果分析。做法：每次采集时顺手记一个 TSF，本地业务时间戳和 TSF 一起入日志，离线再做线性映射。效果：两类时间轴能对齐到微秒级，不用再靠"大概同一毫秒"猜。

扫描计时。背景：评估esp_wifi_scan_start的耗时分布。做法：扫描前后各取一次 TSF 相减，仓库里wpa_supplicant组件的扫描实现就是记这个起点时间戳的模式。效果：能看到慢扫描慢在信道驻留还是结果上报。

TSF返回0的三种排查思路

• 症状：刚连上就取值，永远是 0。→根因：连接完成 ≠ 同步完成，还没吃到第一个信标。→解法：在 CONNECTED 事件后再延迟一个信标周期（约 100ms 级）再读。

• 症状：时间戳走着走着突然"回跳"或走得不稳。→根因：开了深度省电（light sleep / modem sleep），射频周期性断电，同步状态被打断。→解法：精度敏感路径上至少确认只用 modem sleep，或临时关省电复测对比；状态切换逻辑可参考官方的自动轻睡眠时序图：

• 症状：两个设备各自读 TSF，差值忽大忽小。→根因：两个设备不在同一 BSS，或其中一个在重连/漫游中重新同步。→解法：先确认双方 SSID/BSSID 一致，再取差值；漫游期间的数据丢弃或打标记。

💡 还有个隐性坑：AP 模式下 STA 未连入时同样返回 0，WIFI_IF_AP接口的值反映的是 AP 自己的信标时钟，别拿它和 STA 侧混着比。

下次调试网络延迟时，试试先抓一个 TSF 基线再动手改代码。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf