nostraquedeo / clockkit

Sub-msec accurate distributed timestamps.

Clockkit provides timestamps to distributed networked PCs with guaranteed bounds on latency and jitter, typically under 10 microseconds, as described in the conference paper Synchronous data collection from diverse hardware.

It runs on Linux, Windows, and Raspi, and needs neither extra hardware nor elevated privileges.

It includes bindings for Python, Ruby, and TCL. It also has a Rust API and a Rust FFI.

It can measure a system's realtime behavior, by providing a common time reference for events recorded by different sensors (audio, video, gamepad, GPS, SMS, MIDI, biometrics), and for triggering outputs (audio, video, LEDs, servos, motion bases).
It did this originally for a full-motion driving simulator with eye tracking and a quickly churning set of other sensors and outputs, for over a decade.

Clockkit was published in 2004 on http://zx81.isl.uiuc.edu/camilleg/clockkit (defunct).
It was revised and moved to GitHub in 2020.

The source code is licensed under the MIT License.

To install:

Ubuntu 20:

sudo apt install make g++ psmisc swig tcl8.6-dev libpython3.8-dev pkg-config ruby ruby2.7-dev
cd ClockKit && make

Ubuntu 18:
Raspberry Pi 3 and 4 (Debian/Raspbian):

sudo apt install make g++ psmisc swig tcl tcl8.6-dev libpython3.8-dev pkg-config ruby ruby2.5-dev
cd ClockKit && make

Windows 10:

Install Windows Subsystem for Linux, using the Ubuntu 18 or Ubuntu 20 distro.
sudo apt install tcl
Proceed as with Ubuntu 18 or 20.
(Native builds for older versions of Windows may return, but no older than XP.)

To run a test on localhost:

cd ClockKit && make test

To sync host B to host A:

On host A, ckserver <address to bind to> <port>
On host B:

• cp clockkit.conf my-clockkit.conf
• Edit my-clockkit.conf. Set the server to host A, e.g., 192.168.1.1 or myhost.example.com. Set the port to 4567, or whatever port you told ckserver to use.
• ./ckphaselock my-clockkit.conf
  (make test-remote automates this, using an ssh key.)

Of course, these steps for host B can be repeated on other hosts C, D, E,... to sync them all. Remember that "syncing" here means providing synchronized timestamps, not adjusting the hosts' own clocks.

To plot performance:

sudo apt install gnuplot
cd simulation && make

To cite:

Camille Goudeseune and Braden Kowitz. 2004. "Synchronous data collection from diverse hardware."
Driving Simulation Conference - Europe (Conférence Simulation de Conduite), pp. 245-252.

Contributing

The project is currently undergoing significant changes. Contributions of any form are welcome nonetheless.

• To maintain the formatting style, sudo apt install clang-format, and use clang-format through the provided git hook:
  git config core.hooksPath .git_managed_hooks
• New code should follow the C++ Core Guidelines.
• For profiling and code coverage, sudo apt install gcovr. See also man gcovr.
  To collect and print statistics, make clean && make profile, run some tests (but not test-bindings), gcovr.
  To reset statistics before another profile, make purge.
  To cease profiling, make purge && make.

Roadmap

When this software launched in 2004, lab software was pretty much restricted to desktop OSes. But by now, labs and makerspaces use many more software development environments, especially for hardware I/O: Arduino, musl, Raspi, and smartphones to name a few. The choice of mature scripting languages has grown similarly.

Also, private wired 10baseT subnets have been pretty much replaced by WLAN, with much more bandwidth but less predictable performance.

Finally, since 2004, C++ standards have improved and software engineering in general has matured.

Therefore, these steps are proposed.

• Keep modernizing the code.
• Clean up the interface to other languages.
• Implement integration testing.
• Make reproducible performance tests for some use cases.
• Extend multiplatform support beyond POSIX, for other microarchitectures.
• For some use cases, reduce energy consumption, file size, bandwidth.
• To better exploit the strengths and manage the weaknesses of WLAN, replace the generic network stack's lower OSI layers with specific ones for Wi-Fi, Bluetooth LE, Zigbee, 6LoWPAN, etc.
• Throughout all these, insert optimization passes.
• Explore more distant use cases that need clock sync, such as high performance computing, logfile evaluation, and security breach detection.