Accurate time synchronization in low-energy, microcontroller based embedded systems is right here 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 manufactured by several vendors (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.
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
Note
The full documentation is available here!
The library package ships with hardware ports for several platforms, including:
- TM4C1294 (lwIP)
- STM32F4xx (EtherLib/lwip)
- Example: STM32 NUCLEO-F439ZI flexPTP demo
- STM32F7xx (EtherLib/lwip)
- Example: STM32 NUCLEO-F746ZG flexPTP demo
- STM32H7xx (EtherLib/lwip)
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.
For elaborate information on porting and options refer to Porting and configuration.
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 understading how timestamps are fed into flexPTP, refer to ptp_receive_enqueue() in task_ptp.c.
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 provides immediate support for passing timestamp with packet data. For more information, visit the EtherLib repository.
The flexPTP library expects hardware constants and parameters as well as default settings passed in a flexptp_options.h header file.
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.
The flexPTP module can be started/stopped by calling reg_task_ptp()/unreg_task_ptp.
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.
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 here.
| TM4C1294 | STM32F407 | STM32H743 |
|---|---|---|
 |
 |
 |
Time Synchronization Extension for the IO-Link Industrial Communication Protocol
Methods of Peripheral Synchronization in Real-Time Cyber-Physical Systems
The flexPTP library has been released under the MIT license.