LibPTP is an implementation of the Precision Time Protocol (PTP) as it is specified in IEEE 1588-2008 in the simulation framework OMNeT++. LibPTP uses models of standare network components from the INET library, and extends them with PTP functionality.

This library is one of the outcomes of my master thesis, Simulation of Time-synchronized Networks using IEEE 1588-2008, published at the University of Technology in 2016.

The current version of this library can be found on the author's Github site.

Feature list of LibPTP:

• Models for Ordinary, Boundary and Transparent Clocks
• Support for both End-to-End (E2E) as wells as Peer-to-Peer (P2P) delay measurement
• Debugging and tracing support
• Suport for PTP/Ethernet as specified in Annex F of IEEE 1588-2008
• A model for a PI clock servo, and support for implementing custom clock servos
• Support for different kinds of filters
• Realistic clock noise can optionally be provided by using LibPLN, a library for efficient powerlaw noise generation.

The goal of LibPTP is it to provide an easy to use simulation tool for PTP networks. OMNeT++ was chosen as the development environment because it provides a powerful tool with support for all stages of simulation development, from inital model design to carrying out sophisticated parameter studies.

For an example for what is possible with LibPTP see the following image, which shows a parameter study for the sync interval:

The images shows the mean offset value a PTP slave node that is directly connected to its master, depending on the configured sync interval. The same simulation was carried out with two different oscillators, and LibPTP allows to study the behavior of each of them.

Another advantage of LibPTP are its sophisticated debugging and tracing capabilities. For example it is easy to trace all state decisions of a PTP node, as shown in the following image:

Additionally, it would be possible to log every single step during the Best Master Clock Algorithm (BMCA) or the dataset comparison algorithm.

The LibPTP repository contains only the actual simulation model for PTP nodes. It does not contain any simulatons networks. Example simulations can be found in the PTP Simulations repository.

OMNeT++ provides a powerful Graphical User Interface (GUI). To make full use of it, LibPTP uses custom icons for all PTP related models.

PTP Nodes:

The example components that come with LibPTP use an icon scheme to visualize there attributes:

The node icons have a symbol in each corner:

• Upper left: Node type

  • N = End node (Ordinary Clock)
  • B = Boundary Clock
  • T = Transparent Clock

• Upper right: Delay mechanism

  • P = Peer-to-Peer (P2P)
  • E = End-to-End (E2E)

• Lower left: Timestamping capability

  • 1 = 1-step clock (on-the-fly timestamps)
  • 2 = 2-step clock

• Lower right: Clock attributes for Best Master Clock Algorithm (BMCA)

  • Golden star: Excellent clock attributes, such a node will prefer its ports to be passive rather than slave
  • Silver star: Average clock attributes, such a clock will loose in the BMCA against a clock with golden star
  • Brozne star: Bad clock attributes, such a clock will loose in the BMCA against a clock with silver star
  • No icon: Slave only

The image in the center shows a boundary clock, with P2P delay mechanism, which is 1-step capable and has average clock attributes.

Example network:

The folloing images shows an example network to visualize the example icons used by LibPTP:

All nodes in the PTP network use the P2P delay mechanism (blue P). The left-most node is a 1-step capable (1) ordinary clock (E) with excellent clock attributes (golden star). It is connected to a 1-step capble boundary clock (B) with average clock attributes (silver star). The boundary clock is connected to two daisy chains to the right. The upper chain consist of two slave only (no icon) transparent clocks (T), where the second one is only 2-step capable (2), followed by an ordinary clock with bad clock attributes. The lower chain consists of a transparent, a boundary and an ordinary clock.

As only one clock has a golden star, we can safely assume that it will win the BMCA and become the grand master of the PTP network.

PTP Messages:

As with the PTP nodes, LibPTP also provides custom icons for PTP messages:

Remark: While icons for Management and Signaling messages are provided, these two message types are currently not implemented.

The src directory contains most of the project relevant contents. It structured as follwos: Most of the individual parts of a PTP system are loosely grouped into the folders Hardware, Firmware and Sotware. These individual parts are then plugged to together to form network components, which are placed in the Components directory. The Utils folder contains generic utilities.

The other directories are the following:

• doc: Documentation for the project, mainly doxygen generated files.
• Docs: Various documents, mainly related to measuremnt results.
• images: The image files for the OMNeT++ models.
• Tools: This the place for generic tools like shell scripts.

The documentation files in this repository are written in Markdown (line ending *.md). They can be either read in a text editor, are converted to HTML using the markdown utility.

Documentation:

• Doxygen files can be found in the doc directory
• The Docs contains various files with additional information (e.g. how to use LibPTP together with LibPLN)
• Both LibPLN and LibPTP have been developed as part of my master thesis:

Wolfgang Wallner, Simulation of Time-synchronized Networks using IEEE 1588-2008, 2016, Vienna University of Technology

This document contains an in-depth description on the various design decitions of both libraries, and would be the definitive source of information. As of April 2016, it is not yet published. Expected publication date: May or June 2016

Supported platforms:

LibPTP has been tested on Linux and Windows. Non-Portable libraries have been avoided, thus it is likely that it will work (maybe with small adjustments) also on other platforms.

Requirements:

• The Boost C++ library
• The OMNeT++ simulation framework, in a version before 5.x, preferrably 4.6
• The INET library, in a version before 3.x, preferrably 2.6
• The OMNeT_Utils project
• (optionally) The LibPLN library, for realistic clock noise

Getting started:

• Install OMNeT++ 4.6 and INET 2.6
• Install the Boost C++ library
• Get the OMNeT Utils repository, and add it in your OMNeT++ workspace
• Get LibPTP, and add it in your OMNeT++ workspace
• Create a new OMNeT++ project, and add LibPTP as project reference
  • You can now use PTP nodes in your network simulation
  • For an example on how to create PTP simulation networks, have a look at the examples in the PTP Simulations repository
• (Optional) Install LibPLN, and provide information about its installation in the provided makefrag file
  • This enables you to simulate network nodes with realistic clock noise, and thus make PTP simulations more plausible

The implementation of LibPTP would not have been possible without the availability of the following components:

• The Buttonized icon theme
• The OMNeT++ simulation framework
• The INET library, which provides a large set of models for standard network components
• The Boost C++ library

Most parts of this project are licensed under the GPLv3 license. See the COPYING file for details.

As stated, the icons use by LibPTP are based on the Buttonized icon theme, which is licensed unter the GPLv2 license. The images of LibPTP keep this license, and are thus also licensed unter the GPLv2 license. See the images/LICENSE.txt file for details.

Wolfgang Wallner (wolfgang-wallner [AT] gmx.at)