Description

This document explains how to instantiate the Spectracom driver in your RT-LAB simulation. The Spectracom driver controls a Spectracom TSync PCIe card that is connected in one of the PCIe ports of the simulator. This board is a synchronized timecode reader/generator offering flexibility and easy integration of precise timing into an embedded computing application.

The following timestamp information can be received: year, day of the year, hour, minute, second, nanosecond, epoch time and a synchronization flag. The timestamp is in the format provided by the synchronization source and is only valid when the synchronization flag is set. It is recommended to set your synchronization source to always provide a timestamp in UTC format and if required, to perform the appropriate conversion in the model to match your local time.
The synchronization flag is 1 as soon as the board receives a valid reference input. When the reference is lost, the holdover timer is decreased until it reaches zero, then the synchronization flag is set to 0. Therefore, a synchronization flag of 1 means that the reference input signal is valid, or that the board is in holdover state.

You can also make use of the IEEE1588 module installed on board the Spectracom TSync PCIe card. This allows the system to act as an IEEE1588 master, meaning the card can be synchronized by using an external source. It will then broadcast its synchronized timestamp to IEEE1588 slaves that are alive on the same network as the master. The opposite holds true as well: the card can be used as an IEEE1588 slave that is listening on the network for timestamps broadcast by any IEEE1588 master.

Finally, the card can be used to provide external synchronization for the FPGA onboard the Opal-RT simulator. The FPGA can be configured as a master with an external clock.

The configuration of the driver is done in a .opal file. The contents of this file are explained further down in this document.
Below you can find the schematic of an Opal-RT simulator setup using the Spectracom TSync PCIe card.

If you wish to use the Spectracom card in order to synchronize the FPGA in your simulator, your setup should look similar to the schematic below. Check the More Information section to see how to achieve that.

Driver Configuration

A configuration file is required for the following reasons:

• configuring the Spectracom card (without taking into consideration its IEEE1588 capabilities)
• enabling or disabling the IEEE1588 functionality
• configuring the Spectracom card's IEEE1588 module

This section will show you how to configure the Spectracom driver used in your RT-LAB simulation. The fields in the configuration files are mandatory but the values given in the files below are just examples.

Synchronized time source

Below you can find an example of how the configuration file looks like if the IEEE1588 functionality is not enabled:

OPAL-1.0 Object
Spectracom::SpectracomConfig {
deviceParameters {
device_name=tsyncpci
device_id=0
holdover_timeout=20
}
ieee1588_enabled=0
}

The device parameters must be present in each configuration file. They define the following fields:

The value given to the holdover timeout parameter is the number of seconds that the Spectracom card can maintain the synchronized behavior after physically losing its synchronization source.

Example: a synchronization signal is removed from the card's input. Its yellow LED turns on next to the already lit up green LED. This state is known as the holdover state. This means that after the card was synchronized, the synchronization source is removed thus the card enters holdover state, where its internal oscillator continues to keep the time. The timestamp cannot be considered as accurate when this situation occurs.

Once the number of seconds defined in the configuration file as the holdover_timeout have passed, the yellow and green LEDs turn off and the red LED turns on. This means that the holdover state timeout period has expired and now the card is no longer synchronized.
Finally, the ieee1588_enabled field enables or disables the use of the IEEE1588 module within the instantiated Spectracom driver.

Synchronized time source and IEEE1588

An example of the configuration file when the IEEE1588 functionality is enabled can be found below:

OPAL-1.0 Object
Spectracom::SpectracomConfig {
	deviceParameters {
		device_name=tsyncpci
		device_id=0
		holdover_timeout=20
	}
	ieee1588_enabled=1
	ieee1588Cfg {
		dhcp_enabled=1
		communication_mode=MASTER
		static_ip_address=192.168.20.42
		subnet_mask=255.255.224.0
		default_gateway=192.168.0.7
		tai_leap_second=36
		port_settings {
			announce_reception_timeout=3
			announce_interval=1
			sync_interval=0
			delay_request_interval=4
			peer_delay_interval=0
			delay_mechanism=END_TO_END
		}
	}
}

The device parameters field is the same as the one described above in the Synchronized time source; it is mandatory. Please read the above section for a description of what each of its elements represents.

When using the IEEE1588 module of the Spectracom card the ieee1588_enabled field of the configuration must be set to true, i.e. set equal to 1. In this situation, the IEEE1588 module will also have to be configured by using the ieee1588Cfg structure. The structure (and its fields) is mandatory.
The following fields are defined:

It is mandatory to input a static IP address, subnet mask and default gateway even when DHCP is enabled. The values specified at these fields are used by the driver in case DHCP fails.

Configuration File Examples

You can find a configuration file example named "Spectracom_cfg.opal" in the following directories, depending on whether or not you require the card's IEEE1588 functionality:

YOUR_RT_LAB_INSTALLATION_FOLDER/Examples/IO/Spectracom/DiL/Spectracom/simulink

YOUR_RT_LAB_INSTALLATION_FOLDER/Examples/IO/Spectracom/DiL/Spectracom_IEEE1588/simulink

RT-LAB Usage

When using the driver in RT-LAB, the above-described configuration file along with a file named 'connections.opal', must be transferred to the simulator in ASCII mode.

The following screenshot shows how to configure the files to be transmitted to the Opal-RT simulator when the model is loaded.

The 'connections.opal' file is required to bind the model signals to the driver variables. This is how all drivers implemented with the Data Interchange Layer work for the moment. In the future, the user will not have to write this file since the connections will be handled through a special RT-LAB panel.

Here is what a typical connection file looks like for the Spectracom driver:

OPAL-1.0 Object
List {
  item {
    configFile=Spectracom_cfg.opal
    id {
      Spectracom
    }
    outputs {
      item {
        dataInExchanger=IEEE1588/reset_trigger
        dataInProcess=OpOutput:resetTrig_IEEE1588[0]
      }
      item {
        dataInExchanger=IEEE1588/port_state_trigger
        dataInProcess=OpOutput:portStateTrig_IEEE1588[0]
      }
    }
    inputs {
      item {
        dataInExchanger=Timestamp/time_ref_years
        dataInProcess=OpInput:year[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_day
        dataInProcess=OpInput:dayOfYear[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_hours
        dataInProcess=OpInput:hour[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_minutes
        dataInProcess=OpInput:min[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_seconds
        dataInProcess=OpInput:sec[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_ns
        dataInProcess=OpInput:nanosec[0]
      }
      item {
        dataInExchanger=Timestamp/time_ref_utc
        dataInProcess=OpInput:utc[0]
      }
      item {
        dataInExchanger=Status/is_sync
        dataInProcess=OpInput:isSync[0]
      }
      item {
        dataInExchanger=IEEE1588/port_state
        dataInProcess=OpInput:port_state[0]
      }
      item {
        dataInExchanger=Status/error_status
        dataInProcess=OpInput:error_status[0]
      }
    }
  }
}

The items highlighted in bold in the file above are needed only when the IEEE1588 functionality of the driver is used. These are:

• Possible port state values are:
  PTL_PTP_STATE_INITIALIZING = 0,
  PTL_PTP_STATE_FAULTY = 1,
  PTL_PTP_STATE_DISABLED = 2,
  PTL_PTP_STATE_LISTENING = 3,
  PTL_PTP_STATE_PRE_MASTER = 4,
  PTL_PTP_STATE_MASTER = 5,
  PTL_PTP_STATE_PASSIVE = 6,
  PTL_PTP_STATE_UNCALIBRATED = 7,
  PTL_PTP_STATE_SLAVE = 8,
  PTL_PTP_STATE_COUNT = 9

• No connection made on either dataInProcess=OpInput:port_state[0] or dataInProcess=OpOutput:portStateTrig_IEEE1588[0]
  In this situation, the port state monitoring is off. Having the trigger switch and using it in your model will not have any impact on the simulation.
• Connection with dataInProcess=OpOutput:portStateTrig_IEEE1588[0] but not with dataInProcess=OpInput:port_state[0]
  In this situation, the driver will take into account the position of the port state switch. However, due to having no connection on the port state itself, its monitoring will be turned off. Therefore, this setup has no value to you as a user.
• Connection with dataInProcess=OpInput:port_state[0] but not with dataInProcess=OpOutput:portStateTrig_IEEE1588[0]
  In this situation, the port state value will be updated as fast as possible. This means that your model will have overruns. Use this setup only if you are certain that you continuously require to know the status of the IEEE1588 module. Take note that the use of the switch has no impact on the simulation.
• Connection with both dataInProcess=OpInput:port_state[0] and with dataInProcess=OpOutput:portStateTrig_IEEE1588[0]
  Finally, this situation applies when monitoring of the port state is required but only on request. In this case, the driver will update the port state value only when the port state switch is triggered (i.e. moved from 0 to 1). This case will cause the model to have overruns, only a significantly lower number than the situation described at point 3.
  The name used in the 'dataInProcess' must match the name of the respective 'OpInput' or 'OpOutput' blocks in the master subsystem of the Simulink model.

For debugging purposes, three more connections can be made.

These are:

• dataInExchanger=ExtraErrorInfo/err_frequency
  If used, this connection point must be placed in the inputs list of the connections.opal file. By placing it in your simulation, you can monitor the frequency phase error of the external oscillator.
• dataInExchanger=ExtraErrorInfo/err_phase
  If used, this connection point must be placed in the inputs list of the connections.opal file. By placing it in your simulation, you can monitor the estimated phase error of the external oscillator.
• dataInExchanger=ExtraErrorInfo/err_tfom
  If used, this connection point must be placed in the inputs list of the connections.opal file. By placing it in your simulation, you can monitor the current TFOM (Time Figure of Merit).
  However, you must note that using these extra error tracking connection points introduces the risk of having model over-runs during your simulation. This is due to the over-head required by the extra value monitoring. These error statuses are not included in the example models specifically for that reason.

The Spectracom and Spectracom_IEEE1588 example models show how to perform the connections using 'OpInput' and 'OpOutput' blocks.They are located in the following directories:

YOUR_RT_LAB_INSTALLATION_FOLDER/Examples/IO/Spectracom/DiL/Spectracom/simulink

YOUR_RT_LAB_INSTALLATION_FOLDER/Examples/IO/Spectracom/DiL/Spectracom_IEEE1588/simulink

The example models are also accessible from the New Project wizard in RT-LAB. Select the Spectracom or Spectracom_IEEE1588 templates under IO/Spectracom/DiL.
In the Simulink master sub-system, timestamp data and the error status have to be connected to 'OpInput' blocks.
The 'OpOutput' blocks are only required in the case when the IEEE1588 functionality is enabled. These blocks are needed for the reset switch and (if so required by the user) for the port status switch.

Below you can find two screenshots, showing the master subsystem when not using the IEEE1588 functionality (first image) and when IEEE1588 is enabled (second image). OpInput blocks are used to retrieve the timestamp and to have it accessible in the master subsystem of the Simulink model.

The screenshot of the master sub-system when the IEEE1588 functionality is used contains all the possible connections (i.e. the port state and the port state trigger). As mentioned before, the port state connections are not obligatory. If that is the case, you can remove the model components pertaining to them. Take note, however, that if you do not remove them, they will not interfere with your simulation.

More Information

About Spectracom

The Spectracom TSync PCIe board supports multiple prioritized timing inputs. When an input is lost, the unit automatically switches to the next input in order of priority.

The disciplined onboard oscillator is phase-locked to an external timing input, providing 5ns resolution time. This 10 MHz oscillator, central to the TSync-PCIe timing functions, uses the last known reference to increment ("freewheel") in the absence of a timing input.

Synchronizing an FPGA

The Spectracom driver can be used to synchronize the simulator's FPGA and the Spectracom board clocks together. A physical connection between an External Clock Adapter (OP5964) and the Spectracom card (GP Outputs P9 DB9 cable) is required. The FPGA is connected to the External Clock Adapter. The FPGA will be configured as a master with external synchronization.

If the system is composed of multiple FPGAs, another synchronization card (OP5962) is required for each of them. The first OP5962's input will be connected to the External Clock Adapter's (OP5964) output via an audio cable. The following OP5962 cards will be daisy-chained. Each OP5962 will be connected to the FPGA that needs to be synchronized. The FPGAs in this chain will be configured as slaves.