Skip to content

Latest commit

 

History

History
114 lines (89 loc) · 5.48 KB

README.md

File metadata and controls

114 lines (89 loc) · 5.48 KB
Raw

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.

Installing

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 and older

Install a g++ that supports C++20: sudo apt install g++-8.
Change the Makefile's -std=c++20 to -std=c++2a.
Proceed as with Raspberry Pi.

Raspberry Pi 3 and 4 (Debian/Raspbian)

sudo apt install g++ libpython3.8-dev make pkg-config psmisc ruby ruby-dev swig tcl tcl8.6-dev
cd ClockKit && make
(The package ruby-2.5dev vanished after Debian 10 "Buster" and Ubuntu 18.)

Windows 10

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

Using Python, Ruby, or TCL

make bindings builds the modules used by python/ckphaselock.py, ruby/ckphaselock.rb, and tcl/ckphaselock.tcl.
To build for only one language, e.g. Python, make python/_clockkit.so. For details, in the Makefile look for SWIGEXES.

Running

To test on localhost:

cd ClockKit && make test

To sync host B to host A:

On host A, ckserver <IP 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. Here, "syncing" means providing synchronized timestamps, not adjusting the hosts' own clocks.

To plot performance:

sudo apt install gnuplot
cd simulation && make

Citing

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

  • 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.