https://github.com/camilleg/clockkit
Sub-msec accurate distributed timestamps.
https://github.com/camilleg/clockkit
clock-synchronization linux-app raspi sensors timestamp windows-app
Last synced: 2 months ago
JSON representation
Sub-msec accurate distributed timestamps.
- Host: GitHub
- URL: https://github.com/camilleg/clockkit
- Owner: camilleg
- License: mit
- Created: 2020-03-09T21:43:25.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-02T22:57:47.000Z (5 months ago)
- Last Synced: 2025-03-31T06:01:44.803Z (2 months ago)
- Topics: clock-synchronization, linux-app, raspi, sensors, timestamp, windows-app
- Language: C++
- Homepage:
- Size: 607 KB
- Stars: 85
- Watchers: 3
- Forks: 14
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](dsceu04.pdf).
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](https://github.com/Infrasonics/rust-clockkit).
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](https://web.archive.org/web/20170517201424/http://www.isl.uiuc.edu/Labs/Driving%20Simulator/Driving%20Simulator.html) 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](https://web.archive.org/web/20041205064911/http://zx81.isl.uiuc.edu/camilleg/dsceu04.pdf) (defunct).
It was revised and moved to GitHub in 2020.
The source code is licensed under the [MIT License](https://mit-license.org/).
## 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`](https://pkgs.org/download/ruby2.5-dev) vanished after Debian 10 "Buster" and Ubuntu 18.)
#### Windows 10
Install [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10), using the [Ubuntu 20](https://www.microsoft.com/store/apps/9n6svws3rx71) 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 `
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](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#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.