Using NI-TimeSync to Configure IEEE 1588 and 802.1AS Time References

Publish Date: Jun 12, 2018 | 6 Ratings | 5.00 out of 5 | Print

NI-TimeSync is a distribution of time synchronization protocols that can be used with compatible NI hardware. These protocol instances are referred to as "time references", and are used by NI-TimeSync when synchronizing a device's timekeeping clocks. The two most frequently used time references in NI-TimeSync are IEEE 1588 and IEEE 802.1AS. These time references can be used with NI-TimeSync without additional configuration out of the box; use this guide to configure IEEE 1588 and IEEE 802.1AS time references in more detail.

 

Note  Many of the features described in this document were introduced from one NI-TimeSync release to another. Therefore, NI-TimeSync versions will be heavily referenced throughout the document. Make sure that your version of NI-TimeSync is recent enough before attempting to configure a time reference using this document.

 

This document covers following topics:


Configuring a 1588 Time Reference on Controllers Running Phar Lap and VxWorks Real-Time Operating System

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. 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.

Table 1: Additional 1588 Settings
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.

  1. Use WebDAV or FTP to copy the ni-timesync-ptp.ini file from the Real-Time controller to the development computer.
  2. Open the ni-timesync-ptp.ini file in a text editor (e.x. Notepad).
  3. By default, the .ini file will already contain the Prority One token.
  4. 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.
  5. Save the file and use WebDAV or FTP to transfer the file back to the controller into its original location.
  6. After the transfer is completed, restart the controller.


Configuring a 1588 Time Reference on Controllers Running the NI Linux Real-Time Operating System

 

NI TimeSync 18.0 and later  Manually modifying tsm.json is no longer recommended for Linux Real-Time controllers running 18.0 software; instead, use the NI-Sync 18.0 (or later) LabVIEW API included with NI-TimeSync to configure and monitor IEEE 1588 time reference on these controllers. Learn more about using NI-Sync to configure time references with the Monitor and Configure Time References LabVIEW example, accessible by opening LabVIEW and selecting Help >> Find Examples >> Timing and Synchronization >> Time-based >> Monitor and Configure Time References.vi.

 

Modifying IEEE 1588 Configuration with NI-TimeSync 17.1 and NI-TimeSync 17.5

NI-TimeSync 17.1 and NI-TimeSync 17.5 includes a configuration tool, configGen, which allows a user to modify 1588 configuration directly in the command line. ConfigGen is located in /usr/local/natinst/share/TimeSync/Config.

Note  You can use the ./configGen -h command to access the configGen help for additional information.


Configure a property or properties of the 1588 time reference using the following example:

  1. Pick one or more properties from the tsm.json table above.
  2. Navigate to the /usr/local/natinst/share/TimeSync/Config/ directory.

    cd /usr/local/natinst/share/TimeSync/Config/
  3. In the example below, we pick the priority1 property and set it to 12.

    ./configGen --setTRProtocolConfig "IEEE 1588-2008_1" priority1 12 --tsmJsonFile ../tsm.json.

    For multiple properties, simply add the additional property or properties after the first one:

    ./configGen --setTRProtocolConfig "IEEE 1588-2008_1" priority1 12 hwTimestamping 1 --tsmJsonFile ../tsm.json.

  4. To apply the changes, reboot the controller

 

Modifying IEEE 1588 Configuration with from NI-TimeSync 14.5 to NI-TimeSync 17.0

NI-TimeSync 14.5 is the first driver with NI Linux OS support. For Linux RT, changes have been made to NI-TimeSync that allow for more user configuration options. Currently, however, IEEE 1588 configuration is not available in MAX or LabVIEW for Linux RT controllers. In order to configure IEEE 1588, you will need to modify configuration files on the controller.

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.

Table 2: Properties in tsm.json
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.5*
interface String
(e.g. eth0, eth1)
Defines which network adapter is used for synchronization. 15.5
bmcaMode 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
priority1 INT
(Min: 0, Max: 248)
A clock with a lower value has a higher priority. 15.5
priority2 INT
(Min: 0, Max: 248)
A clock with a lower value has a higher priority 15.5

*The 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.

†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.

Table 3: Properties in ptp.conf
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.


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 an 802.1AS Time Reference on Controllers Running the NI Linux Real-Time Operating System

 

NI TimeSync 18.0 and later  Manually modifying tsm.json is no longer recommended for Linux Real-Time controllers running 18.0 software; instead, use the NI-Sync 18.0 (or later) LabVIEW API included with NI-TimeSync to configure and monitor IEEE 802.1AS time reference on these controllers. Learn more about using NI-Sync to configure time references with the Monitor and Configure Time References LabVIEW example, accessible by opening LabVIEW and selecting Help >> Find Examples >> Timing and Synchronization >> Time-based >> Monitor and Configure Time References.vi

 

Modifying 802.1AS Configuration with NI-TimeSync 17.1 and NI-TimeSync 17.5.

NI-TimeSync 17.1 includes a configuration tool, configGen, which allows a user to modify 802.1AS configuration directly in the command line. ConfigGen is located in /usr/local/natinst/share/TimeSync/Config.

Note  You can use the ./configGen -h command to access the configGen help for additional information.


Configure a property or properties of the 802.1AS time reference using the following example:

  1. Pick one or more properties from Table 4.
  2. Navigate to the /usr/local/natinst/share/TimeSync/Config/ directory.

    cd /usr/local/natinst/share/TimeSync/Config/
  3. In the example below, we pick the priority1 property and set it to 12:

    ./configGen --setTRProtocolConfig "IEEE 802.1AS-2011_1" priority1 12 --tsmJsonFile ../tsm.json

    For multiple properties, simply add the additional property or properties after the first one:

    ./configGen --setTRProtocolConfig "IEEE 802.1AS-2011_1" priority1 12 priority2 33 1 --tsmJsonFile ../tsm.json

  4. To apply the changes, reboot the controller

 

Modifying 802.1AS Configuration with NI-TimeSync 17.0

802.1AS support was introduced with NI-TimeSync 17.0 for specific Linux Real-Time Controllers with TSN. The default 802.1AS configuration should be sufficient for the majority of users. However, NI-TimeSync 17.0 allows a user to change some 802.1AS properties by modifying the tsm.json file on the controller.

The tsm.json file is located at /usr/local/natinst/share/TimeSync/tsm.json.

The table below lists the properties that can be modified in this file.

Table 4: Properties in tsm.json.
Property Possible Values Notes
interface String
(e.g. eth0, eth1)*
Defines which network adapter is used for synchronization.
priority1 INT
(Min: 0, Max: 254)
A clock with a lower value has a higher priority.
priority2 INT
(Min: 0, Max: 254)
A clock with a lower value has a higher priority.

*This property can only be set to eth0 on cRIO-9035 (Sync) and cRIO-9039 (Sync).

†The value 0 is reserved for management only as specified by the IEEE 802.1AS specification.


Configuring Properties with tsm.json

To modify the tsm.json 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. To add properties to tsm.json, you will need to add a protocolConfig section with the properties you wish to modify. The syntax of the protocolConfig section is highlighted below:

{

"timeReferences": {

"IEEE 802.1AS-2011_1": {

"defaults": "/usr/local/natinst/share/TimeSync/TimeReferences/IEEE_8021AS-2011.json",

"priority": "unknown",

 "protocolConfig": {

 "priority1": 128, 

 "priority2": 128, 

 "interface": "eth0" 

 } 

}

},

"timeKeeper": {

"library": "/usr/local/natinst/share/TimeSync/TimeKeepers/libfpgaCicada.so.17.0.0"

},

"servo": {

"library": "/usr/local/natinst/share/TimeSync/Servos/libdefaultServo.so.16.1.0"

}

}

Once you are done modifying tsm.json, reboot the controller to apply the new properties.

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


Switching Between 1588 and 802.1AS Time References on Controller Running the NI Linux-Real Operating System

 

NI TimeSync 18.0 and later  Manually modifying tsm.json is no longer recommended for Linux Real-Time controllers running 18.0 software; instead, use the NI-Sync 18.0 (or later) LabVIEW API included with NI-TimeSync to switch between IEEE 1588 or IEEE 802.1AS time references on these controllers. Learn more about using NI-Sync to switch time references with the Monitor and Configure Time References LabVIEW example, accessible by opening LabVIEW and selecting Help >> Find Examples >> Timing and Synchronization >> Time-based >> Switch Time References.vi.

 

NI TimeSync 17.1 is the first release to support both 1588 and 802.1AS time references on selected Linux-Real Time controllers. If the device supports both protocols you can select the time reference(s) to install onto the controller during the MAX software installation. The time reference that you choose will automatically be selected during the controller bootup. If you install both time references (1588 and 802.1AS) onto the controller, 802.1AS will be set as the default time reference.

In order to switch between the two time references using NI TimeSync 17.1 or 17.5, use the configGen tool, located in the /usr/local/natinst/share/TimeSync/Config directory.

Use the following example to switch from the default 802.1AS time reference to the 1588 time reference:

  1. Look up available time references on the controller using the --listTRInstances command. Notice each instance ends with an underscore (_) and a number. The number represents the Ethernet port the instance is running on. For a cRIO (Sync) device, you will only see a reference with _1 since cRIO (Sync) can only run a time reference on a single Ethernet port.

    The IC-317x controller will list four instances (_1 to _4) since IC is capable of a time reference on each of its four Ethernet ports:

    ./configGen --listTRInstances --tsmJsonFile ../tsm.json

  2. Enable the desired time reference:

    ./configGen --enableTRInstance "IEEE 1588-2008_1" --tsmJsonFile ../tsm.json

    Note  You can enable multiple time references in one line by simply adding another reference. In the example below, two 1588 references are enabled on Ethernet port 1 and 2:

    ./configGen --enableTRInstance "IEEE 1588-2008_1" "IEEE 1588-2008_2" --tsmJsonFile ../tsm.json


  3. Explicitly disable the other references:

    ./configGen --disableTRInstance "IEEE 802.1AS-2011_1" --tsmJsonFile ../tsm.json

    As in step two, if you need to disable multiple time references, simply add another reference.

  4. Reboot the controller to apply the changes.


Monitoring a 1588 Time Reference Running on the NI Linux Real-Time Operating System.

 

NI TimeSync 18.0 and later  Use the NI-Sync 18.0 (or later) LabVIEW API included with NI-TimeSync to monitor IEEE 1588 time references on these controllers. Learn more about using NI-Sync to configure time references with the Monitor and Configure Time References LabVIEW example, accessible by opening LabVIEW and selecting Help >> Find Examples >> Timing and Synchronization >> Time-based >> Monitor and Configure Time References.vi.

 

NI-TimeSync 17.1 and NI-TimeSync 17.5:

NI-TimeSync 17.1 creates two log files in the /var/log directory:

nitsmd.log—Contains start up information, the time reference selected at start up, state changes, clock properties, and miscellaneous error messages.

tr_ptp_rt_ethX.log—A log based on the port number (X), indicating state changes, best master MAC address, master changes, and miscellaneous error messages.

 

 

NI-TimeSync 17.0 and earlier:

In order to monitor the performance of the 1588 Time Reference, you can read the values in ptp.status available at the following path: /var/run/ptp.status

Table 5 lists the status values that can be monitored:

Table 5: NI-TimeSync Status Values
Property Possible Values Notes
Interface eth0, eth1, etc. Reports which network adapter is being used for synchronization.
Preset 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.
Port state PTP_SLAVE
PTP_MASTER
PTP_LISTENING
PTP_UNCALIBRATED
PTP_INITIALIZING
PTP_FAULTY
PTP_DISABLED
PTP_PRE_MASTER
PTP_PASSIVE
Describes the current state of the port.
Local port ID The clock ID of the local clock. National Instruments 1588 devices—as well as many others—use the MAC address as part of the clock ID.
Best master ID The clock ID of the best master clock on the network, as determined by the best master clock algorithm. National Instruments 1588 devices—as well as many others—use the MAC address as part of the clock ID.
Best master IP The IP address of the network adapter of the master clock.  
PTP Engine resets Integer value. The amount of times the PTP engine has reset. An abnormal number of resets could indicate that PTP frequently reaches a faulty state, and the cause should be investigated.

You can monitor the values in the ptp.status file by using WebDAV to transfer the file to your host computer, via the secure shell, or by programmatically parsing the file in an application running on the real-time controller.

The status file is recreated periodically (about once per second) and when the PTP Engine resets. Therefore, the file may not be readable at a given instant. Note also that if the network connection is not present, PTP will be unable to start and the creation of the ptp.status file will not complete until a network connection is available again.

NoteThe ptp.status may have a sligthly different naming in different versions of the driver, for example ptp_ethX.status.


Monitoring a 802.1AS Time Reference Running on the NI-Linux Real-Time Operating System.

 

NI TimeSync 18.0 and later  Use the NI-Sync 18.0 (or later) LabVIEW API included with NI-TimeSync to monitor IEEE 802.1AS time references on these controllers. Learn more about using NI-Sync to configure time references with the Monitor and Configure Time References LabVIEW example, accessible by opening LabVIEW and selecting Help >> Find Examples >> Timing and Synchronization >> Time-based >> Monitor and Configure Time References.vi.

 

NI-TimeSync 17.0 and NI-TimeSync 17.5 ship with a LabVIEW VI called 802.1AS Status.vi, which can be used to monitor 802.1AS status directly in LabVIEW. The VI is located in the following directory:

C:\Program Files (x86)\National Instruments\LabVIEW <version>\vi.lib\TSN Toolkit\i210 Tools\802.1AS Status.vi

In addition to the 802.1AS Status VI, NI-TimeSync 17.1 includes two log files in the /var/log directory which store monitoring information:

  • nitsmd.log—Contains start up information, the time reference selected at start up, state changes, clock properties, and miscellaneous error messages.

tr_8021as_rt_ethX.log—A log based on the port number (X), indicating state changes, best master MAC address, master changes, and miscellaneous error messages.

 

Related Links:

KnowledgeBase 69EEMIR4: Using WebDAV to Transfer Files to Your Real-Time Target
KnowledgeBase 6strongCJRR0: How Do I Access the Shell on a NI Linux Real-Time OS Device?
KnowledgeBase 4LRA4IQ0: What Operating System is my Real-Time Controller Running and Why?
KnowledgeBase 773E2KNN: NI-TimeSync 15.0 or Later Does Not Run on Linux RT Targets with NI-Industrial Communications for EtherCAT 14.0 or Earlier Installed

Back to Top

Bookmark & Share


Ratings

Rate this document

Answered Your Question?
Yes No

Submit