Precision Time Protocol#

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

The IEEE 1588 standard defines the protocol. Basler cameras support IEEE 1588-2008, also known as PTP Version 2.

Using the Feature#

Why Use PTP#

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

• Periodic Signal
• Scheduled Action Commands
• Synchronous Free Run

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 criterion with the highest precedence is the device's Priority 1 setting.

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. For Basler cameras, this means that their TimestampLatchValue parameter values will be as identical as possible. The precision highly depends on your network hardware and setup.

If no device in the network is synchronized to a coordinated world time (e.g., TAI or 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.

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. Make sure that all cameras that you want to synchronize via PTP are properly configured.
3. On all cameras that you want to synchronize via PTP, set the GevIEEE1588 parameter to true.
4. 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 PTP-enabled camera features.

Configuring PTP Clock Synchronization#

Depending on your camera model, the following settings are available:

Priority 1#

In a PTP-enabled network, 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 ace 2 and dart M cameras, you can change the Priority 1 setting to force a camera to be the master clock, or to prevent a camera from being the master clock. To do so, set the BslPtpPriority1 parameter to a value between 0 (highest priority) and 255 (lowest priority).

On other cameras, the Priority 1 setting is preset to 128 and can't be changed.

PTP Delay Mechanism#

The delay measurement mechanism defines how PTP delay measurement messages are sent and received within the network. The PTP standard defines two mechanisms: end-to-end (E2E, also "delay request-response") and peer-to-peer (P2P). For more information, see this article.

On ace 2 and dart M cameras, you can change the delay measurement mechanism. To do so, set the BslPtpProfile parameter to DelayRequestResponseDefaultProfile (default) or PeerToPeerDefaultProfile.

On other cameras, the delay measurement mechanism is preset to end-to-end and can't be changed.

Network Mode#

The network mode setting defines how PTP messages are transferred within the network.

On ace 2 cameras, you can change the network mode. To do so, set the BslPtpNetworkMode parameter to one of the following values:

• Multicast: PTP messages are sent to all devices in the local network that are configured for PTP multicasting. This is the default mode and sufficient for most use cases.
• Hybrid: PTP messages are sent using multicast and unicast messages. This saves network load because fewer messages have to be processed. For more information, see this article.
• Unicast: PTP messages are sent to one or more specified devices in the local network. Other devices can't receive PTP messages.
  To configure unicast:
  1. Make sure that the BslPtpNetworkMode is set to Unicast.
  2. Set the BslPtpUcPortAddrIndex parameter to 0.
  3. Set the BslPtpUcPortAddr parameter to the IP address of the first receiving device.
  4. Increase the BslPtpUcPortAddrIndex parameter by 1.
  5. Set the BslPtpUcPortAddr parameter to the IP address of the next receiving device.
  6. Repeat steps 3 and 4 for all PTP devices involved.

On other cameras, the network mode is preset to multicast. However, these cameras can also receive unicast messages and respond accordingly.

PTP Management#

The PTP Management Protocol allows you to read the settings of any PTP device via management messages, i.e., without using the pylon API. If permitted, the settings can also be written.

On ace 2 and dart M cameras, you can enable or disable PTP management. To do so:

1. Enable PTP clock synchronization.
2. Set the BslPtpManagementEnable parameter to one of the following values:
   • true: You can read settings (GET), write settings (SET), and execute commands (COMMAND) using management messages with the message IDs listed below.
   • false (default): The PTP Management Protocol is disabled, and settings can neither be read nor written.

On other cameras, PTP management is always enabled and preset to read-only access.

Supported Management Messages#

For information about the default values and ranges of these attributes, see the IEEE 1588-2008 specification, annex J.

One-Step or Two-Step Clock#

This setting defines how many messages are generated for any PTP event message that requires an egress timestamp:

• In one-step operation, one message is sent. The message includes the message data and the egress timestamp.
• In two-step operation, two messages are sent. The first message includes the message data. The second message includes the egress timestamp.

For more information, see this article.

On ace 2 and dart M cameras, two-step operation is disabled by default. If another PTP device in the network explicitly requires two-step event messages, you can enable them by setting the BslPtpTwoStep parameter to true.

On other cameras, two-step operation is always enabled.

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.

A typical implementation of a PTP status check involves the following steps:

1. Execute the GevIEEE1588DataSetLatch command.
   The command allows you to take a "snapshot" of the camera's current PTP state. The "snapshot" implementation ensures that all parameter values in the latched data set refer to exactly the same point in time.
2. Wait until the GevIEEE1588Status parameter value is no longer Initializing.

3. Depending on the camera model, read the following parameter values from the device:

   • On ace 2 and dart M cameras, read the PtpServoStatus parameter from all slave cameras. If the parameter value is Locked, the respective device should be sufficiently synchronized. If you need a more refined status check, follow the "other cameras" procedure below instead.

   • On other cameras, read the GevIEEE1588OffsetFromMaster parameter value from all slave cameras until the highest offset from master is below a certain threshold (according to your requirements, 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:

     

4. Repeat steps 1 and 2 until the devices are sufficiently synchronized.

What's In A Latched Data Set?#

After executing the GevIEEE1588DataSetLatch command, you can read the following parameter values from the device:

• GevIEEE1588ClockId: Indicates the unique ID of the current PTP device (the "clock ID").
• GevIEEE1588OffsetFromMaster: Indicates the estimated temporal offset between the master clock and the clock of the current PTP device in ticks (1 tick = 1 nanosecond).
• GevIEEE1588ParentClockId: Indicates the clock ID of the PTP device that currently serves as the master clock (the "parent clock ID").
• GevIEEE1588Status: Indicates the state of the current PTP device, e.g., whether it is a master or a slave clock. The returned values match the 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.
• GevIEEE1588StatusLatched: If this parameter is available, Basler recommends using it instead of the GevIEEE1588Status parameter. This is because the GevIEEE1588Status parameter is not tied to the GevIEEE1588DataSetLatch command. Therefore, if you read multiple PTP-related values from a device, the device state will not relate to the same point in time as the other values.

Additional Parameters#

On ace 2 and dart M cameras, after executing the PtpDataSetLatch command, you can read the following additional parameter values from the device:

• BslPtpDelayMechanism: Indicates the delay mechanism used by the PTP network. A value of E2E indicates that the Delay Request-Response mechanism is used. A value of P2P indicates that the peer-to-peer mechanism is used.
• PtpClockAccuracy: Indicates the expected accuracy of the PTP device clock when it is or becomes the grandmaster. On Basler cameras, the expected accuracy is preset to Unknown. This is because Basler cameras don't synchronize to a coordinated world time, e.g., UTC.
• PtpGrandmasterClockID: Indicates the clock ID of the PTP device that currently serves as the grandmaster clock.
• PtpServoStatus: Indicates the state of the clock servo, i.e., the state of the PTP clock synchronization. If the state is Locked, the clock of the current device is successfully synchronized with the master clock. In all other cases, the state is Unknown.

External Links#

• End-to-End Versus Peer-to-Peer (Time Synchronization Blog)
• Hybrid Mode PTP: Mixed Multicast and Unicast (Time Synchronization Blog)
• IEEE 1588-2008 Specification (IEEE Standards Association)
• One-step or Two-step? (Time Synchronization Blog)
• Precision Time Protocol (Wikipedia)
• White Paper: Synchronous and in Real Time: Multi-Camera Applications in the GigE Network (Basler)

Sample Code#

ace 2 Cameras#

// ** Configure PTP **
// Set Priority 1 to 128
camera.BslPtpPriority1.SetValue(128);
// Enable end-to-end delay measurement
camera.BslPtpProfile.SetValue(BslPtpProfile_DelayRequestResponseDefaultProfile);
// Set the network mode to unicast
camera.BslPtpNetworkMode.SetValue(BslPtpNetworkMode_Unicast);
// Set the IP address of the first unicast device to 192.168.10.12
// (0xC0 = 192, 0xA8 = 168, 0x0A = 10, 0x0C = 12)
camera.BslPtpUcPortAddrIndex.SetValue(0);
camera.BslPtpUcPortAddr.SetValue((0xC0A80A0C);
// Enable PTP Management Protocol
camera.BslPtpManagementEnable.SetValue(true);
// Disable two-step operation
camera.BslPtpTwoStep.SetValue(false);
// ** Enable PTP on the current device **
camera.PtpEnable.SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see "Checking the Status of
// the PTP Clock Synchronization" in this topic.

INodeMap& nodemap = camera.GetNodeMap();
// ** Configure PTP **
// Set Priority 1 to 128
CIntegerParameter(nodemap, "BslPtpPriority1").SetValue(128);
// Enable end-to-end delay measurement
CEnumParameter(nodemap, "BslPtpProfile").SetValue("DelayRequestResponseDefaultProfile");
// Set the network mode to unicast
CEnumParameter(nodemap, "BslPtpNetworkMode").SetValue("Unicast");
// Set the IP address of the first unicast device to 192.168.10.12
// (0xC0 = 192, 0xA8 = 168, 0x0A = 10, 0x0C = 12)
CIntegerParameter(nodemap, "BslPtpUcPortAddrIndex").SetValue(0);
CIntegerParameter(nodemap, "BslPtpUcPortAddr").SetValue(0xC0A80A0C);
// Enable PTP Management Protocol
CBooleanParameter(nodemap, "BslPtpManagementEnable").SetValue(true);
// Disable two-step operation
CBooleanParameter(nodemap, "BslPtpTwoStep").SetValue(false);
// ** Enable PTP on the current device **
CBooleanParameter(nodemap, "PtpEnable").SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see "Checking the Status of
// the PTP Clock Synchronization" in this topic.

// ** Configure PTP **
// Set Priority 1 to 128
camera.Parameters[PLCamera.BslPtpPriority1].SetValue(128);
// Enable end-to-end delay measurement
camera.Parameters[PLCamera.BslPtpProfile].SetValue(PLCamera.BslPtpProfile.DelayRequestResponseDefaultProfile);
// Set the network mode to unicast
camera.Parameters[PLCamera.BslPtpNetworkMode].SetValue(PLCamera.BslPtpNetworkMode.Unicast);
// Set the IP address of the first unicast device to 192.168.10.12
// (0xC0 = 192, 0xA8 = 168, 0x0A = 10, 0x0C = 12)
camera.Parameters[PLCamera.BslPtpUcPortAddrIndex].SetValue(0);
camera.Parameters[PLCamera.BslPtpUcPortAddr].SetValue(0xC0A80A0C);
// Enable PTP Management Protocol
camera.Parameters[PLCamera.BslPtpManagementEnable].SetValue(true);
// Disable two-step operation
camera.Parameters[PLCamera.BslPtpTwoStep].SetValue(false);
// ** Enable PTP on the current device **
camera.Parameters[PLCamera.PtpEnable].SetValue(true);
// To check the status of the PTP clock synchronization,
// implement your own check method here.
// For guidelines, see "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 */
/* ** Configure PTP ** */
/* Set Priority 1 to 128 */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslPtpPriority1", 128);
CHECK(errRes);
/* Enable end-to-end delay measurement */
errRes = PylonDeviceFeatureFromString(hdev, "BslPtpProfile", "DelayRequestResponseDefaultProfile");
CHECK(errRes);
/* Set the network mode to unicast */
errRes = PylonDeviceFeatureFromString(hdev, "BslPtpNetworkMode", "Unicast");
CHECK(errRes);
/* Set the IP address of the first unicast device to 192.168.10.12 */
/* (0xC0 = 192, 0xA8 = 168, 0x0A = 10, 0x0C = 12) */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslPtpUcPortAddrIndex", 0);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslPtpUcPortAddr", 0xC0A80A0C);
CHECK(errRes);
/* Enable PTP Management Protocol */
errRes = PylonDeviceSetBooleanFeature(hdev, "BslPtpManagementEnable", 1);
CHECK(errRes);
/* Disable two-step operation */
errRes = PylonDeviceSetBooleanFeature(hdev, "BslPtpTwoStep", 0);
CHECK(errRes);
/* ** Enable PTP on the current device ** */
errRes = PylonDeviceSetBooleanFeature(hdev, "PtpEnable", 1);
CHECK(errRes);
/* To check the status of the PTP clock synchronization, */
/* implement your own check method here. */
/* For guidelines, see "Checking the Status of */
/* the PTP Clock Synchronization" in this topic. */

# ** Configure PTP **
# Set Priority 1 to 128
camera.BslPtpPriority1.Value = 128
# Enable end-to-end delay measurement
camera.BslPtpProfile.Value = "DelayRequestResponseDefaultProfile"
# Set the network mode to unicast
camera.BslPtpNetworkMode.Value = "Unicast"
# Set the IP address of the first unicast device to 192.168.10.12
# (0xC0 = 192, 0xA8 = 168, 0x0A = 10, 0x0C = 12)
camera.BslPtpUcPortAddrIndex.Value = 0
camera.BslPtpUcPortAddr.Value = 0xC0A80A0C
# Enable PTP Management Protocol
camera.BslPtpManagementEnable.Value = True
# Disable two-step operation
camera.BslPtpTwoStep.Value = False
# ** Enable PTP on the current device **
camera.PtpEnable.Value = True
# To check the status of the PTP clock synchronization,
# implement your own check method here.
# For guidelines, see "Checking the Status of
# the PTP Clock Synchronization" in this topic.

Other Cameras#

// 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 "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 "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 "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 "Checking the Status of */
/* the PTP Clock Synchronization" in this topic. */

# Enable PTP on the current device
camera.GevIEEE1588.Value = True
# To check the status of the PTP clock synchronization,
# implement your own check method here.
# For guidelines, see "Checking the Status of
# the PTP Clock Synchronization" in this topic.

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