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.
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 22
sudo apt install g++ libpython3.10-dev make pkgconf ruby ruby3.0-dev swig tcl8.6-dev
cd ClockKit && make
Ubuntu 20
sudo apt install g++ libpython3.8-dev make pkg-config psmisc ruby ruby2.7-dev swig tcl8.6-dev
cd ClockKit && make
Ubuntu 18
Raspberry Pi 3 and 4 (Debian/Raspbian)
sudo apt install g++ libpython3.8-dev make pkg-config psmisc ruby ruby2.5-dev swig tcl tcl8.6-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 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 theserverto host A, e.g.,192.168.1.1ormyhost.example.com. Set theportto 4567, or whatever port you told ckserver to use. ./ckphaselock my-clockkit.conf
(make test-remoteautomates 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 useclang-formatthrough 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 alsoman 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.