Precision Time Protocol#

The Precision Time Protocol (PTP) camera feature allows you to synchronize multiple GigE cameras in the same network.

The protocol is defined in the IEEE 1588 standard. Basler cameras support the revised version of the standard (IEEE 1588-2008, also known as PTP Version 2).

Info

The precision of the PTP synchronization depends to a large extent on your network hardware and setup. For maximum precision, choose high-quality network hardware, use PTP-enabled network switches, and add an external PTP clock device with a GPS receiver to your network.

Using the Feature#

Why Use PTP#

The Precision Time Protocol (PTP) feature enables a camera to use the following features:

How it Works#

Through PTP, multiple devices (e.g., cameras) are automatically synchronized with the most accurate clock found in a network, the so-called master clock or best master clock.

The protocol enables systems within a network to do the following:

  • Synchronize with the master clock, i.e., set the local clock as precisely as possible to the time of the master clock.
  • Syntonize with the master clock, i.e., adjust the frequency of the local clock to the frequency of the master clock. You want the duration of a second to be as identical as possible on both devices.

The master clock is determined by several criteria. The most important criterion is the device's Priority 1 setting. The network device with the lowest Priority 1 setting is the master clock. On all Basler cameras, the Priority 1 setting is preset to 128 and can't be changed. If your PTP network setup consists only of Basler cameras, the master clock will be chosen based on the device's MAC address.

For more information about the master clock criteria, see the IEEE 1588-2008 specification, clause 7.6.2.2.

Timestamp Synchronization#

The basic concept of the Precision Time Protocol (IEEE 1588) is based on the exchange of PTP messages. These messages allow the slave clocks to synchronize their timestamp value with the timestamp value of the master clock. When the synchronization has been completed, the TimestampLatchValue parameter value on all GigE devices will be as identical as possible. The precision highly depends on your network hardware and setup.

IEEE 1588 defines 80-bit timestamps for storing and transporting time information. Because GigE Vision uses 64-bit timestamps, the PTP timestamps are mapped to the 64-bit timestamps of GigE Vision.

If no device in the network is synchronized to a coordinated world time (e.g., UTC), the network will operate in the arbitrary timescale mode (ARB). In this mode, the epoch is arbitrary, as it is not bound to an absolute time. The timescale is relative and only valid in this network.

Info

  • A PTP-enabled device that operates in a network with no other PTP-enabled devices does not discipline its local clock. The precision of its local clock is identical to a non-PTP-enabled device.
  • If you use a PTP-enabled switch in two-step boundary mode, in rare cases, no camera clock may reach the master state. If this happens, Basler recommends that you set Priority 1 in the switch settings to a value greater than 128. This priority setting ensures that a PTP port is able to be in the slave state and a connected camera is able to become a master.
  • For more information about the Precision Time Protocol, see the Synchronous and in Real Time: Multi-Camera Applications in the GigE Network white paper.

Enabling PTP Clock Synchronization#

When powering on the camera, PTP is always disabled. If you want to use PTP, you must enable it.

To enable PTP:

  1. If you want to use an external device as the master clock (e.g., a GPS receiver), configure the external device as the master clock. Basler recommends an ANNOUNCE interval of 2 seconds and a SYNC interval of 0.5 seconds.
  2. On all cameras that you want to synchronize via PTP, set the GevIEEE1588 parameter to true.
  3. Wait until all PTP network devices are sufficiently synchronized. Depending on your network setup, this may take a few seconds or minutes. You can determine when the devices are synchronized by checking the status of the PTP clock synchronization.

Now, you can use the Scheduled Action Commands feature and the Synchronous Free Run feature.

Info

Enabling PTP clock synchronization changes the camera's internal tick frequency from 125 MHz (= 8 ns tick duration) to 1 GHz (= 1 ns tick duration).

The Inter-packet Delay and the Frame Transmission Delay parameter values are adjusted automatically.

Checking the Status of the PTP Clock Synchronization#

To check the status of the PTP clock synchronization, you must develop your own check method using the pylon API.

These guidelines may help you in developing a suitable method:

  • The GevIEEE1588DataSetLatch command allows you to take a "snapshot" of the camera's current PTP clock synchronization status. The "snapshot" implementation ensures that all parameter values specified (see below) refer to exactly the same point in time.
  • After executing the GevIEEE1588DataSetLatch command, you can read the following parameter values from the device:
    • GevIEEE1588OffsetFromMaster: A 32-bit number. Indicates the temporal offset between the master clock and the clock of the current IEEE 1588 device in ticks.
    • GevIEEE1588ClockId: A 64-bit number. Indicates the unique ID of the current IEEE 1588 device (the "clock ID").
    • GevIEEE1588ParentClockId: A 64-bit number. Indicates the clock ID of the IEEE 1588 device that currently serves as the master clock (the "parent clock ID").
    • GevIEEE1588StatusLatched: An enumeration. Indicates the state of the current IEEE 1588 device, e.g., whether it is a master or a slave clock. The returned values match the IEEE 1588 PTP port state enumeration (Initializing, Faulty, Disabled, Listening, Pre_Master, Master, Passive, Uncalibrated, and Slave). For more information, refer to the pylon API documentation and the IEEE 1588-2008 specification.
    • GevIEEE1588Status: An enumeration. Serves as an alternative to the GevIEEE1588StatusLatched parameter. Returns the same values, but does not require executing the GevIEEE1588DataSetLatch command beforehand. However, if you read multiple PTP-related values from a device, the GevIEEE1588Status parameter value will not relate to the same point in time as the other values.
  • A typical implementation of a PTP status check involves executing the GevIEEE1588DataSetLatch command and checking the GevIEEE1588OffsetFromMaster parameter value repeatedly on all slave cameras until the highest offset from master is below a certain threshold (defined by you, e.g., 1 millisecond).
  • Due to the fact that the clock is continuously adjusted by a control mechanism, the offset is not decreasing monotonically. Basler recommends that you check the maximum GevIEEE1588OffsetFromMaster parameter value within a given time window:
    PTP Offset From Master Amplitude

Sample Code#

// Enable PTP on the current device
camera.GevIEEE1588.SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see section "Checking the Status of
// the PTP Clock Synchronization" in this topic.
INodeMap& nodemap = camera.GetNodeMap();
// Enable PTP on the current device
CBooleanPtr(nodemap.GetNode("GevIEEE1588"))->SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see section "Checking the Status of
// the PTP Clock Synchronization" in this topic.
INodeMap& nodemap = camera.GetNodeMap();
// Enable PTP on the current device
CBooleanParameter(nodemap, "GevIEEE1588").SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see section "Checking the Status of
// the PTP Clock Synchronization" in this topic.
// Enable PTP on the current device
camera.Parameters[PLCamera.GevIEEE1588].SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see section "Checking the Status of
// the PTP Clock Synchronization" in this topic.
// Enable PTP on the current device
Pylon.DeviceSetBooleanFeature(hdev, "GevIEEE1588", true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see section "Checking the Status of
// the PTP Clock Synchronization" in this topic.
/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
/* Enable PTP on the current device */
errRes = PylonDeviceSetBooleanFeature(hdev, "GevIEEE1588", 1);
CHECK(errRes);
/* To check the status of the PTP clock synchronization, */
/* implement your own check method here. */
/* For guidelines, see section "Checking the Status of */
/* the PTP Clock Synchronization" in this topic. */

You can also use the pylon Viewer to easily set the parameters.