serial-sync/README.md

Serial Sync

Serial Sync is a python library that handles clock synchronization between an external device (ie Arduino) and a computer, the object handles calibration which determines the clock offset and clock drift to correct over time.

Note

Serial especially over USB has inherent jitter which cannot be easily corrected for, this library is a best effort synchronization method but should not be trusted for sub millisecond sync.

Installation

To install the library with uv:

uv add git+https://git.h3cx.dev/Exergie/serial-sync.git --tag v0.1.1

Usage

Here is a simple usage example, the SerialSync object takes a Serial object as an input. Here the synchronization is done over a 30 second period

with Serial(
    port="/dev/ttyUSB0",
    baudrate=115200,
    timeout=1,
) as serial:

    sync = SerialSync(serial)

    sync.calibrate_sync(30)

Once the sync is complete, you can use the convert_timestamp(timestamp_ns: int) API to convert an incoming timestamp from the external device into a timestamp on the same time-base as python's time.monotonic_ns()