diff --git a/BeagleBone.gif b/BeagleBone.gif new file mode 100644 index 0000000..e19ed7b Binary files /dev/null and b/BeagleBone.gif differ diff --git a/CMakeLists.txt b/CMakeLists.txt index 7dc2e62..3516ec2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -12,16 +12,16 @@ add_executable(${PRJ} Inc/flexptp_options.h ) +set(DEFS "_GNU_SOURCE=1") + +target_compile_definitions(${PRJ} PUBLIC ${DEFS}) target_include_directories(${PRJ} PUBLIC Modules) +set(FLEXPTP_COMPILE_DEFS ${DEFS}) set(FLEXPTP_INCLUDES ${CMAKE_CURRENT_LIST_DIR}/Inc ${CMAKE_CURRENT_LIST_DIR}/Src ${CMAKE_CURRENT_LIST_DIR}/Modules) set(FLEXPTP_HWPORT LINUX) set(FLEXPTP_NSD LINUX) set(FLEXPTP_SERVO KALMAN) add_subdirectory(Modules/flexPTP) target_link_libraries(${PRJ} flexptp) -target_include_directories(${PRJ} PUBLIC ${FLEXPTP_INCLUDE_EXPORT} ${FLEXPTP_INCLUDES}) - -if (${HAVE_CLOCK_ADJTIME}) - target_compile_definitions(flexptp PUBLIC HAVE_CLOCK_ADJTIME=1) -endif () \ No newline at end of file +target_include_directories(${PRJ} PUBLIC ${FLEXPTP_INCLUDE_EXPORT} ${FLEXPTP_INCLUDES}) \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..a75d515 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020-2025 András Wiesner + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/Modules/flexPTP b/Modules/flexPTP index 5ef4860..e1c9e73 160000 --- a/Modules/flexPTP +++ b/Modules/flexPTP @@ -1 +1 @@ -Subproject commit 5ef4860ba7df9b42583b1a0fe0bee54cc66e2202 +Subproject commit e1c9e739a50c178f422ec3688233f824b7b1e9ca diff --git a/README.md b/README.md new file mode 100644 index 0000000..05502cd --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# flexPTP Linux demo + +![flexPTP CLI](BeagleBone.gif) + +## What's this? + +> **This is a [flexPTP](https://github.com/epagris/flexPTP) demo project showcasing the capabilities of the flexPTP [IEEE 1588 Precision Time Protocol](https://ieeexplore.ieee.org/document/9120376) implementation on Linux systems.** + +Still not clear what is it useful for? No worries, it's a behind-the-scenes support technology that you use unaware every day if you have a smartphone or when you are connected to the internet. Modern telecommunication and measurement systems often rely on precise time synchronization down to the nanoseconds' scale. Methods got standardized by the IEEE and now it's known by the name of the Precision Time Protocol. This software project is an evaluation environment to showcase the capabilities of our IEEE 1588 PTP implementation named `flexPTP` on Linux systems. + +> [!NOTE] +> The primary goal of the flexPTP library is supporting microcontroller, this project and the Linux port is an exceptional, experimental project for the time being. This project has been inspired by the [linuxptp](https://github.com/richardcochran/linuxptp) application. Want to learn more about the implementation? Head to [Under the hood...](#under-the-hood)! + +### Get the sources + +> [!NOTE] +> To acquire the full source tree after cloning the repo, please fetch the linked *submodules* as well: + +``` +git clone https://github.com/epagris/flexPTP-demo-linux/ +cd flexPTP-demo-linux +git submodule init +git submodule update +``` + +## Building + +### Prerequisites + +The following two pieces of software are necessary for building: +- `gcc` (v12+): the GCC C +- `cmake` (v3.22+): KitWare's build management system + +### Compiling + +The project is fully CMake managed. Configure and invoke the cross-compiler using the commands below: + +``` +cmake . -B build +cmake --build build --target flexptp_linux -- +``` +Once the building has concluded the output binary will be deposited in the `build` directory: `flexptp_linux`. + +## Running + +Start the `flexptp_linux` application with superuser right so it can execute privileged socket- and PHC-related commands. Pass the targeted network interface using the `-i` parameter, e.g. `sudo flexptp_linux -i eth0` +Connect your device to any PTP-compliant equipment (e.g. another Linux-based machine or embedded system with [flexPTP](https://github.com/epagris/flexPTP) or [linuxptp](https://github.com/richardcochran/linuxptp)) to test the flexPTP library. The application has an all-around CLI implemented. Startup configuration can be passed using the `-c` parameter (e.g. `sudo flexptp_linux -i eth0 -c flexptp_startup.cfg`) which should contain one command per line (like typing commands on the CLI). + +The flexPTP parameters are defined in the [flexptp_options.h](Inc/flexptp_options.h) header. + +### CLI commands + +The software offers you with the following multitude, most flexPTP-related of commands: + +``` +? Print this help +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 get 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 []] 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 [] Print or set profile flags +ptp period [|matched] Print or set log. periods +ptp coarse [threshold] Print or set coarse correction threshold +ptp priority [ ] Print or set clock priority fields +``` + +> [!TIP] +> The above hint can be listed by typing '?'. + +## Under the hood + +The porting layer used in this project is very much different compared to a conventional port supporting a specific microcontroller. The [Network Stack Driver](https://epagris.github.io/flexPTP/porting.html#network-stack-driver) and the Hardware Port got unified into the single [nsd_linux.c](https://github.com/epagris/flexPTP/blob/master/src/flexptp/port/example_netstack_drivers/nsd_linux.c) source file. The port uses the Linux kernel's built-in PHC-adjustment functions and standard POSIX socket operations. Each major step is documented in the NSD source file. + + +## Related papers and references + +[Time Synchronization Extension for the IO-Link Industrial Communication Protocol](https://ieeexplore.ieee.org/document/10747727) + +[Distributed Measurement System for Performance Evaluation of Embedded Clock Synchronization Solutions](https://ieeexplore.ieee.org/document/9805958/) + +[Portable, PTP-based Clock Synchronization Implementation for Microcontroller-based Systems and its Performance Evaluation](https://ieeexplore.ieee.org/document/9615250) + +[Synchronization of Sampling in a Distributed Audio Frequency Range Data Acquisition System Utilizing Microcontrollers](https://ieeexplore.ieee.org/document/9918455/) + +[Methods of Peripheral Synchronization in Real-Time Cyber-Physical Systems](https://ieeexplore.ieee.org/document/10178979/) + + +## License + +The project was created by András Wiesner (Epagris) in 2025 and published under the MIT license. Contributions are welcome! :) + + + diff --git a/Src/main.c b/Src/main.c index 3b87dbc..1da8cb5 100644 --- a/Src/main.c +++ b/Src/main.c @@ -135,6 +135,9 @@ int main(int argc, char *argv[]) { // unregister PTP task unreg_task_ptp(); + // clean up the network driver + linux_nsd_cleanup(); + return 0; }