coreSNTP Library

API Documentation Pages for current and previous releases of this library can be found here

This repository contains the coreSNTP library, a client library to use Simple Network Time Protocol (SNTP) to synchronize device clocks with internet time. This library implements the SNTPv4 specification defined in RFC 4330.

An SNTP client can request time from both NTP and SNTP servers. According to the SNTPv4 specification, "To an NTP or SNTP server, NTP and SNTP clients are indistinguishable; to an NTP or SNTP client, NTP and SNTP servers are indistinguishable.", thereby, allowing SNTP clients to request time from NTP servers.

This library has gone through code quality checks including verification that no function has a GNU Complexity score over 10, and checks against deviations from mandatory rules in the MISRA coding standard. Deviations from the MISRA C:2012 guidelines are documented under MISRA Deviations. This library has also undergone both static code analysis from Coverity static analysis, and validation of memory safety through the CBMC automated reasoning tool.

See memory requirements for this library here.

coreSNTP v1.3.1 source code is part of the FreeRTOS 202406.00 LTS release.

Documentation

The API reference documentation for the coreSNTP library version released in FreeRTOS/FreeRTOS can be viewed from the freertos.org website.

Cloning this repository

This repo uses Git Submodules to bring in dependent components.

To clone using HTTPS:

git clone https://github.com/FreeRTOS/coreSNTP.git --recurse-submodules

Using SSH:

git clone [email protected]:FreeRTOS/coreSNTP.git --recurse-submodules

If you have downloaded the repo without using the --recurse-submodules argument, you need to run:

git submodule update --init --recursive

Building the library

You can build the coreSNTP source files that are in the source directory, and add source/include to your compiler's include path.

If using CMake, the coreSntpFilePaths.cmake file contains the above information of the source files and the header include path from this repository.

Reference Example

A reference example of using the coreSNTP library can be viewed in the FreeRTOS/FreeRTOS repository here. The demo application showcases use of the library in order to create an SNTP client for periodic time synchronization of the system clock.

Building Unit Tests

The unit tests for the library use CMock/Unity unit testing framework.

Checkout CMock Submodule

To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule:

git submodule update --checkout --init --recursive test/unit-test/CMock

Unit Test Platform Prerequisites

• For running unit tests
  • C90 compiler like gcc
  • CMake 3.13.0 or later
  • Ruby 2.0.0 or later is additionally required for the CMock test framework (that we use).
• For running the coverage target, gcov and lcov are additionally required.

Steps to build Unit Tests

1. Go to the root directory of this repository. (Make sure that the CMock submodule is cloned as described above)

2. Run the cmake command: cmake -S test -B build -DUNITTEST=ON

3. Run this command to build the library and unit tests: make -C build all

4. The generated test executables will be present in build/bin/tests folder.

5. Run cd build && ctest to execute all tests and view the test run summary.

CBMC proofs

To learn more about CBMC and proofs specifically, review the training material here.

The test/cbmc/proofs directory contains CBMC proofs.

In order to run these proofs you will need to install CBMC and other tools by following the instructions here.

Generating documentation

The Doxygen references were created using Doxygen version 1.9.6. To generate the Doxygen pages, please run the following command from the root of this repository:

doxygen docs/doxygen/config.doxyfile

Contributing

See CONTRIBUTING.md for information on contributing.

License

This library is licensed under the MIT License. See the LICENSE file.