From f16cc5fc6f74f8c4e142b16960e8b51ef059de84 Mon Sep 17 00:00:00 2001 From: TIM ANDERSON Date: Wed, 21 Oct 2026 17:15:07 +1000 Subject: [PATCH] docs: describe PCAN timestamp drift after macOS sleep --- doc/changelog.d/2092.changed.rst | 2 ++ doc/interfaces/pcan.rst | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 doc/changelog.d/2092.changed.rst diff --git a/doc/changelog.d/2092.changed.rst b/doc/changelog.d/2092.changed.rst new file mode 100644 index 000000000..c9ab62fb0 --- /dev/null +++ b/doc/changelog.d/2092.changed.rst @@ -0,0 +1,2 @@ +Document the reported PCBUSB 0.13 timestamp offset after macOS system sleep, +including diagnostic steps and capture limitations. diff --git a/doc/interfaces/pcan.rst b/doc/interfaces/pcan.rst index 48e7dba05..a7246f873 100644 --- a/doc/interfaces/pcan.rst +++ b/doc/interfaces/pcan.rst @@ -45,6 +45,38 @@ Linux installation Beginning with version 3.4, Linux kernels support the PCAN adapters natively via :doc:`/interfaces/socketcan`, refer to: :ref:`socketcan-pcan`. +macOS timestamps after system sleep +----------------------------------- + +On macOS, the PCAN interface uses the third-party +`PCBUSB library `__. +With PCBUSB 0.13, received message timestamps have been reported to lag +wall-clock time after system sleep. The reported offset grows with the +accumulated sleep duration since boot, including sleep before the bus was +opened. Disconnecting and reconnecting the adapter did not correct the offset +in the reported test. + +When boot time is available, the PCAN backend converts the driver's elapsed +timestamp to Unix time by adding the system boot time. If that elapsed counter excludes system sleep, this +conversion produces an incorrect date. BLF and CSV logging preserve the +received message timestamp, so changing the log format does not correct it. +See :issue:`2092` and the related +`PCBUSB report `__ +for the observations and the library maintainer's response. + +To investigate on an affected Mac, receive continuous traffic from a known +source, consume messages promptly, and compare ``message.timestamp`` with +``time.time()`` before and after a recorded system sleep. Also test a capture +started after the Mac has already slept since boot. Record the macOS, Python, +python-can and PCBUSB versions, the adapter model, and the sleep duration. +Account for receive-queue delays: the time at which an application reads a +message can be later than the time at which the message was received. + +When accurate calendar timestamps are required, avoid system sleep from boot +through the end of the capture and verify the timestamps against an independent +reference. This limitation has been reported on macOS; the linked reports do +not establish the behavior on Windows or Linux. + Bus ---