Accurate time synchronization on low-energy, microcontroller based embedded systems is not a feat of the future anymore with the flexPTP library on our side.

flexPTP has been designed with low resource utilization in mind. The library can easily fit into 20K program and 10K data memory space with all features enabled. The library has been ported to and tested on ARM Cortex-M4 and Cortex-M7 based microcontrollers from several manufacturers (e.g. STM32F4xx, STM32F7xx, STM32H7xx, TM4C1294 etc.). According to simple measurements published in several papers of ours, with the help of the library even low-power systems achieved a synchronization precision of tens of nanoseconds.

The library is released under the MIT license with the endeavour to provide quick and compact solution for embedded time synchronization.

Quick intro

Clueless where to start first? We recommend newcomers to start playing around with some complete Examples, then continue with the Software structure chapter and finally read Porting and configuration guide.

Features

flexPTP offers the following capabilities:

IEEE 1588 compatible slave and master OC implementation
supports E2E and P2P delay mechanisms
supports L2 and L4 transport mechanisms
supports one-step and two-step signaling modes
can operate as a IEEE 802.1AS clock (slave or master)
supports lwIP and EtherLib as underlying network stack
features a rich set of runtime-configurable options
features numerous logging features
provides operational statistics
provides means to compensate hardware layer delays
provides CMake-support, compiles into a library
provides a simple servo (controller) interface
automatically cooperates with certain CLI terminals

Platforms and examples

The library package ships with hardware ports for several platforms, including:

TM4C1294 (lwIP)
- Example: EK-TM4C1294XL Connected LaunchPad flexPTP demo
STM32F4xx (EtherLib/_lwip_)
- Example: STM32 NUCLEO-F439ZI flexPTP demo
STM32F7xx (EtherLib/_lwip_)
- Example: STM32 NUCLEO-F746ZG flexPTP demo
STM32H7xx (EtherLib/_lwip_)
- Example: STM32 NUCLEO-H743ZI flexPTP demo, STM32 dual-core NUCLEO-H745ZI-Q flexPTP demo

Requirements

Apart from the access to a working C compiler, only the following two criteria must be met to compile flexPTP:

The library relies on the services of the FreeRTOS embedded operating system thus it is required to integrate the library.
A compatible network stack library and target platform Ethernet driver is required. Currently Lightweight IP (lwip) and EtherLib are supported.

Porting and options

For elaborate information on porting and options refer to Porting and configuration.

Network stack requirements

The network stack (lwIP or EtherLib) must provide tools to communicate receive and transmit timestamps along the PTP messages. It's the developers responsibility to make the timestamps captured in the hardware available to the flexPTP module.

For better understanding how timestamps are fed into flexPTP, refer to ptp_receive_enqueue() in task_ptp.c.

lwIP

The lwIP (up to v2.2.0) is not designed for support timestamp propagation right away. A possible workaround is the extension of the pbuf structure so that it can carry the timestamps and the usual packet data as well through defining the LWIP_PBUF_CUSTOM_DATA macro.

// Main packet buffer struct
struct pbuf {
  /* ... */
 
  // Contents of LWIP_PBUF_CUSTOM_DATA>>
  /* PTP timestamp fields */
  u32_t time_s, time_ns;
 
  /* Transmit callback function */
  void (*tx_cb)(struct pbuf * pPbuf);
  // <<Contents of LWIP_PBUF_CUSTOM_DATA
};

The low level lwIP-Ethernet driver must be instrumented to communicate receive and transmit timestamps. Fortunately, developing such an extension is not that difficult, at all. As an example you can find a guide here that showcases our amendments to the vendor-provided ethernetif.c low level lwIP Ethernet driver file for the STM32H743 platform. You can also find examples on PTP-compatible lwip low-level drivers among the example projects.

EtherLib

EtherLib provides immediate support for passing timestamp with packet data. For more information, visit the EtherLib repository.

Compile-time options

The flexPTP library expects hardware constants and parameters as well as default settings passed in a flexptp_options.h header file.

Building

The preferred and encouraged way to compile the library is to harness the built-in CMake support, although, building using any IDE is possible. The only requirement is a working a C (cross-)compiler (e.g. arm-none-eabi-gcc). More, detailed description on this topic: Compiling the library.

Usage

Startup and shutdown

The flexPTP module can be started/stopped by calling reg_task_ptp() and unreg_task_ptp().

Runtime operation

The library has an extensive interface for manipulating the PTP operation mode during runtime (e.g. change profile, enable logging etc.), learn more here. The flexPTP includes a CLI interface as well, if a suitable CLI library is given, flexPTP offers the following multitude of CLI commands:

ptp servo params [Kp Kd]                           Set or query K_p and K_d servo parameters
ptp servo log internals {on|off}                   Enable or disable logging of servo internals
ptp reset                                          Reset PTP subsystem
ptp servo offset [offset_ns]                       Set or query clock offset
ptp log {def|corr|ts|info|locked|bmca} {on|off}    Turn on or off logging
time [ns]                                          Print time
ptp master [[un]prefer] [clockid]                  Master clock settings
ptp info                                           Print PTP info
ptp domain [domain]                                Print or set PTP domain
ptp addend [addend]                                Print or set addend
ptp transport [{ipv4|802.3}]                       Set or get PTP transport layer
ptp delmech [{e2e|p2p}]                            Set or get PTP delay mechanism
ptp transpec [{def|gPTP}]                          Set or get PTP transportSpecific field (majorSdoId)
ptp profile [preset [<name>]]                      Print or set PTP profile, or list available presets
ptp tlv [preset [name]|unload]                     Print or set TLV-chain, or list available TLV presets
ptp pflags [<flags>]                               Print or set profile flags
ptp period <delreq|sync|ann> [<lp>|matched]        Print or set log. periods
ptp coarse [threshold]                             Print or set coarse correction threshold
ptp priority [<p1> <p2>]                           Print or set clock priority fields

The library can load a previously stored or save the current configuration from and to a non-volatile storage with the help of some glue code.

Performance measurements

Our library achieves decent synchronization performance, usually better than 100ns timing precision even on low-power microcontrollers. The below measurements were made using the nowadays common gPTP (802.1AS) profile. Logs corresponding to each plot are located in the "manual/dumps/" folder.