Using NI-TimeSync to Configure IEEE 1588 and 802.1AS Time References
Overview
Contents
- NI-TimeSync and NI-Sync 18.0 and later with NI Linux RT
- NI-Timesync 14.5 to 18.0 with NI Linux RT
- Configuring a 1588 Time Reference on Controllers Running Phar Lap and VxWorks Real-Time Operating System
NI-TimeSync and NI-Sync 18.0 and later with NI Linux RT
As of NI-Sync 19.0, NI-TimeSync features are included with the NI-Sync driver and NI-TimeSync no longer exists as a standalone download. For versions of NI-Sync and NI-TimeSync later than 18.0, configuration of time references has been greatly simplified through the use of the NI-Sync API. The NI-Sync API is the recommended way of monitoring and configuring time references. For guidance on using the NI-Sync API, please consult the following resources:
- LabVIEW examples. The following shipping examples can be found through the Help tab in LabVIEW >> Find Examples... >> Hardware Input and Output >> Timing and Synchronization >> Time-based. Refer to the instructions on the example front panel to run it properly.
- Monitoring and Configuring Time References.vi - Demonstrates how to use the NI-Sync API to monitor and configure time references in LabVIEW and can be used as a utility program for this purpose
- Monitor Synchronization.vi - Demonstrates how to use the NI-Sync API to monitor synchronization between a master and slave specifically
- Enable and Disable Time References.vi - Demonstrates how to use the NI-Sync API to enable and disable installed time references
NI-Timesync 14.5 to 18.0 with NI Linux RT
NI-TimeSync 14.5 is the first driver with NI Linux OS support. Unlike on VxWorks and Pharlap, IEEE 1588 configuration is not available in MAX or LabVIEW for Linux RT controllers. In order to configure IEEE 1588 or 802.1AS (if available) for the indicated versions, configuration files on the controller must be modified.
The two configuration files you may need to modify are:
- /usr/local/natinst/share/TimeSync/tsm.json
- /usr/local/natinst/share/TimeSync/TimeReferences/ptp.conf
Tables 2 and 3 list the properties that can be modified in each configuration file, as well as the minimum version of NI-TimeSync you will need to have access to the property in that particular configuration file. See the instructions below the tables for details on how to modify these properties.
| Property | Possible Values | Notes | Version Introduced |
|---|---|---|---|
| statusFile | String | Defines the file used to log PTP status information. | 15.5 |
| hwTimestamping | INT (True: 1, False: 0) | Specifies whether hardware timestamping is used on the configured interface. | 15.53 |
| interface1,2 | String (e.g. eth0, eth1)4 | Defines which network adapter is used for synchronization. | 15.5 |
| bmcaMode1 | String (slaveonly, masteronly, masterslave) | A clock that is set to masterslave can be chosen as the master timekeeper, but will otherwise act as a 1588 slave. | 15.5 |
| priority11,2 | INT (Min: 0, Max: 248)4 | A clock with a lower value has a higher priority. | 15.5 |
| priority22 | INT (Min: 0, Max: 248)4 | A clock with a lower value has a higher priority | 15.5 |
1This property has equivalent properties in both tsm.json and ptp.conf in some versions of NI-TimeSync. NI recommends using tsm.json instead of ptp.conf whenever possible. PTP.conf may be replaced by tsm.json in a future release of NI-TimeSync. 2This property applies to both IEEE-1588 and IEEE-802.1AS. Other properties only apply to IEEE-1588 3The hwTimestamping property should only be used on controllers that support hardware timestamping, such as the NI IC-317x, cRIO-9035 (Sync), and cRIO-9039 (Sync) controllers. hwTimestamping for the IC-317x was first introducted in NI-TimeSync 15.5. The hwTimestamping property for cRIO-9035 (Sync) and cRIO-9039 (Sync) was first introduced in NI-TimeSync 17.1. 4This value can only be set to eth0 on cRIO-9035 (Sync) and cRIO-9039 (Sync) 4For 802.1AS, the 0 value for this property is reserved for network management as specified by the IEEE 802.1AS specification | |||
| Property | Possible Values | Notes | Version Introduced |
|---|---|---|---|
| ptpengine:announce_receipt_timeout | INT (Min: 2, Max: 255) | PTP announce receipt timeout announced when in master state. | 15.5 |
| ptpengine:domain | INT (Min: 0, Max: 127) | The PTP domain number. | 15.5 |
| ptpengine:inbound_latency | INT | Specifies latency correction, in nanoseconds, for incoming packets. | 15.5 |
| ptpengine:interface* | String (e.g. eth0, eth1) | Defines which network adapter is used for synchronization. | 14.5 |
| ptpengine:log_announce_interval | INT (Min: -1, Max: 7) | The PTP announce message interval when in master state. It is expressed as log2 (e.g. -1=0.5s, 0=1s, 1=2s, etc.). | 15.5 |
| ptpengine:log_delayreq_interval | INT (Min: -7, Max: 7) | The minimum delay request interval announced when in master state. | 15.5 |
| ptpengine:log_sync_interval | INT (Min: -7, Max: 7) | The PTP sync message interval when in master state. | 15.5 |
| ptpengine:offset_shift | INT | Specifies an arbitrary shift, in nanoseconds, to offset from master when in slave state. | 15.5 |
| ptpengine:outbound_latency | INT | Specifies a latency correction, in nanoseconds, for outgoing packets. | 15.5 |
| ptpengine:preset* | String (slaveonly, masteronly, masterslave) | A clock that is set to masterslave can be chosen as the master timekeeper, but will otherwise act as a 1588 slave. | 14.5 |
| ptpengine:priority1* | INT (Min: 0, Max: 248) | A clock with a lower value has a higher priority. | 14.5 |
*This property has equivalent properties in both tsm.json and ptp.conf in some versions of NI-TimeSync. NI recommends using tsm.json instead of ptp.conf whenever possible. PTP.conf may be replaced by tsm.json in a future release of NI-TimeSync. Configuration of the ptp.conf file is only applicable to the IEEE-1588 time reference | |||
To modify the appropriate configuration file, you can use WebDAV to transfer the file to and from your host computer or you can access and modify the file via the secure shell. Then follow the instructions below based on the configuration file you are modifying:
Configuring Properties with tsm.json.
Tsm.json is located on your controller at /usr/local/natinst/share/TimeSync/tsm.json. On IC-317x controllers, the properties available in tsm.json will be included by default. On all other controllers, you will need to manually add the protocolConfig section to the file in order to modify these properties. The syntax of a time reference in tsm.json is shown below:
{
"timeReferences": {
"IEEE 1588-2008-1": {
"defaults": "/usr/local/natinst/share/TimeSync/TimeReferences/IEEE_1588-2008.json",
"priority": "unknown",
"protocolConfig": {
"priority1": 128,
"priority2": 128,
"interface": "eth1",
"statusFile": "/var/run/ptp_eth1.status"
}
}
},
"timeKeeper": {
"library": "/usr/local/natinst/share/TimeSync/TimeKeepers/liblinuxTimekeeper.so.16.0.0"
},
"servo": {
"library": "/usr/local/natinst/share/TimeSync/Servos/libdefaultServo.so.16.0.0"
}
}
The bolded portion in the text above is the protocolConfig section that will need to be added in order to modify the properties. Once added, you can change the values for each property as explained in Table 2. Then reboot your controller.
| Note If hardware timestamping is supported on the controller, it can be enabled by including "hwTimestamping": 1, in the "protocolConfig": { } section of the tsm.json file. The hwTimestamping property is only valid on controllers that support hardware 1588 with NI-TimeSync, such as NI IC-317x controllers. If your controller does not support hardware timestamping, this line must not be included in order for synchronization to work. |
Also note that correct syntax is critical when modifying tsm.json. If there is a syntax error, the NI-TimeSync daemon will fail to start upon reboot. To verify the daemon was able to start correctly, you can view the log file at /var/log/messages. If there is a syntax error, you will see entries similar to the following:
2010-10-14T14:58:51.000+00:00 NI-cRIO-9031 nitsmd[2304]: Starting TimeSync daemon...
2010-10-14T14:58:51.000+00:00 NI-cRIO-9031 nitsmd[2304]: Failed to load TimeSync daemon, got status: FAIL(-52005,null)
2010-10-14T14:58:51.000+00:00 NI-cRIO-9031 nitsmd[2304]: Error on line: 5, column: 4
Configuring Properties with ptp.conf
Ptp.conf is located on your controller at /usr/local/natinst/share/TimeSync/TimeReferences/ptp.conf. The properties in ptp.conf have syntax similar to the following:
; Network interface (default is eth0).
ptpengine:interface=eth0
By default, all lines in the ptp.conf file are commented out. To alter a configuration setting, remove the semicolon from the beginning of the property's line and modify the property value. Then reboot your controller.
Configuring a 1588 Time Reference on Controllers Running Phar Lap and VxWorks Real-Time Operating System
Note: NI will remove support for Phar Lap for cRIO in the NI 2020 Software Release and for PXI in the NI 2022 Software Release. For more information, please see the Phar Lap RT OS EOL Road Map.
On real-time controllers running VxWorks or Phar Lap, you can configure 1588 Priority One in Measurement & Automation Explorer (MAX) under the Network Settings tab. This functionality is also included with NI-Sync 19.0 and later. Starting with NI-TimeSync 17.0, you can configure additional 1588 settings, shown in Table 1. These settings will not be visible in MAX and can be only modified by adding INI tokens into the ni-timesync.ptp.ini file on the controller.
| Property | INI Token | Possible Values | Notes | Version Introduced |
|---|---|---|---|---|
| Priority One | source.ptp.PriorityOne | INT (Min: 0, Max: 255) | A clock with a lower value has a higher priority. | 1.1 |
| PTP Slave Only | source.ptp.SlaveOnly | String (true, false) | Sets controller to be always a slave. | 17.0 |
| Use UTC Offset | source.ptp.useUtcOffset | String (true, false) | UTC offset is applied to the system time. | 17.0 |
| PTP Time to Live (TTL) | source.ptp.MulticastMsgTTL | INT (Min: 0, Max: 255) | Sets TTL value for multicast PTP messages. | 17.0 |
Modifying the INI Configuration File:
The ni-timesync-ptp.ini file is located in /ni-rt/system/ni-timesync/directory.
- Use WebDAV or FTP to copy the ni-timesync-ptp.ini file from the Real-Time controller to the development computer.
- Open the ni-timesync-ptp.ini file in a text editor (e.x. Notepad).
- By default, the .ini file will already contain the Prority One token.
- Add a desired token after the Priority One token. For example, in the screenshot below, the PTP Slave Only (source.ptp.SlaveOnly) and Use UTC Offset (source.ptp.useUtcOffset) tokens were added based on the INI tokens from the table.
- Save the file and use WebDAV or FTP to transfer the file back to the controller into its original location.
- After the transfer is completed, restart the controller.
Related Links:
- Using WebDAV to Transfer Files to Your Real-Time Target
- What Operating System is my Real-Time Controller Running and Why?
- Monitor and Configure Synchronization on Embedded Devices