Skip to content

docs: document PCAN timestamp drift after macOS sleep #2107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
timothyanderson096-ocdealcheck wants to merge 1 commit into
base: main
Choose a base branch
from
+34 −0
Open

docs: document PCAN timestamp drift after macOS sleep #2107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/changelog.d/2092.changed.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Document the reported PCBUSB 0.13 timestamp offset after macOS system sleep,
including diagnostic steps and capture limitations.
32 changes: 32 additions & 0 deletions doc/interfaces/pcan.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/mac-can/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 <https://github.com/mac-can/PCBUSB-Library/issues/26>`__
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
---

Expand Down