.. _Sync: ==================== Time synchronization ==================== Blickfeld devices currently support NTPv4 and PTPv2 time synchronization. NTPv4 can achieve synchronization accuracy below one millisecond for measurement results in local networks. PTPv2 can achieve clock synchronization accuracy between microseconds and nanoseconds. Additionally, the user can synchronize the start of a frame (SOF) to a level of accuracy below 4 milliseconds. 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 or PTPv2 slave 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. ------------- Configuration ------------- Blickfeld devices currently support NTPv4 and PTPv2 time synchronization. After a successful configuration, the device will start synchronizing all timestamps. Synchronization status can be retrieved via the BSL. NTPv4 ----- To achieve accurate synchronization, it is recommended to set up a local network with a local NTP server. Use the following python commands to configure the NTP server: .. code-block:: python import blickfeld_scanner device = blickfeld_scanner.scanner("") device.set_time_synchronization(ntp=[""]) PTPv2 ----- To use PTPv2 synchronization, it is required to set up a local network with a local PTP master. The device will always start in a slaveonly mode, but there a several other options to configure the PTP slave on the device, such as: * Delay Mechanism (E2E, P2P) * PTP Domain number * Unicast destinations (will activate unicast mode. Multicast mode is set by default) To configure the PTP synchronization with the default configuration, use the BSL. An example for Python is shown below: .. code-block:: python import blickfeld_scanner device = blickfeld_scanner.scanner("") device.set_time_synchronization(ptp=True) --------------------- Frame synchronization --------------------- This method is useful for synchronizing frame acquisitions of multiple Cube devices or other sensors as a target frame rate can be configured. Connect the device to the local network, power it up, and make sure that the local NTP server or PTP master is active. Use the sync method of the python library to activate the frame synchronization: .. code-block:: python import blickfeld_scanner device = blickfeld_scanner.scanner("") blickfeld_scanner.scanner.sync(devices=[device], target_frame_rate=) 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.