.. _Sync:

====================
Time synchronization
====================

Blickfeld devices currently support NTPv4 time synchronization. It can achieve synchronization accuracy below one millisecond for measurement results in local networks.
Additionally, the user can synchronize the start of a frame (SOF) to a level of accuracy below 8 milliseconds (will be reduced in the next hardware generation).
Please note that this only applies to the actual movement of the mirror and pulse emissions, not to the time accuracy of each single measurement.
An individual timestamp in nanoseconds is available for each measurement result.

Working principle
=================

The Blickfeld devices use an NTPv4 client to synchronize the local device time and FPGA counters to synchronize the time server.
The synchronized time is then used to plan the SOFs.

Currently, the only parameter required to enable synchronization is the target frame rate in Hz.
The Unix time, starting from 00:00:00 UTC on January 1, 1970, combined with the target frame rate (:math:`f_t`) is used to calculate the SOFs.

:math:`SOF_n = 00:00:00` UTC on January 1, 1970 + :math:`f_t * n \pm 4 ms`

For a constant frame rate of 20Hz, this would result in the repeating series [0 ms, 50 ms, 100ms, 150ms, ..., 950 ms].
For processing algorithms, it is recommended to use the start_time_ns field in the frame message and the start_offset_ns field in each single point for post-processing synchronization.

Usage
=====

Configuring the NTP server
--------------------------

To achieve accurate synchronization, it is recommended to set up a local network with a local NTP server.
Use the web interface of the device (Configuration -> Network -> IPv4) to configure a static IP address.
Compile and install the blickfeld-scanner-lib in the environment using python3.
Use the following python commands to configure the NTP server:

.. code-block:: python

    import blickfeld_scanner
    device = blickfeld_scanner.scanner("<local IP address of device>")
    device.set_ntp_server("<local IP address of the NTP server>")
 
Please power-cycle the device after configuration.

Activating time synchronization
-------------------------------

Connect the device to the local network, power it up, and make sure that the local NTP server is active.
Run these commands on the NTP server to check the status of the time the NTP server is publishing:

.. code-block::

    ntpq -p

This shows a list of servers. In our case we need to have the LOCAL in the list

.. code-block::

    ntpq -c rv

This shows the info of the time on the server.

In the local network, the time provided can be checked with ``ntpdate -u <local IP address of the NTP server>``.

Use the sync method of the python library to activate the synchronization:

.. code-block:: python

    import blickfeld_scanner
    device = blickfeld_scanner.scanner("<local IP address of device>")
    blickfeld_scanner.scanner.sync(devices=[device], target_frame_rate=<desired target frame rate>)

This has to be called once before a point cloud stream is requested.
The target frame rate and the scan pattern can be configured during operation.
The new configuration is applied after a few seconds. The number of scan lines in the scan pattern directly influences the maximum frame rate.
The frame rate displayed in the scan pattern designer of the web interface can be used as a reference.

It is recommended to look at the python example in :py:meth:`sync.example`.
To retrieve and process point-clouds, follow the C++ example in ``examples/cpp/fetch_clouds/main.cpp``.
Follow the instructions for installing protobof as a system dependency, which allows access to the ``start_offset_ns`` field of the points.