FarSync BERT

FarSync BERT - API Support

As well as supporting GUI and scripting modes, the FarSync BERT also includes native API support. This enables the BERT to be configured and executed directly from within customer applications.

The FarSync BERT API is a COM-based API that enables support from any COM-compatible host application. This includes, for example, applications developed in Python, C#, Java, VBS and LabVIEW.

The same BERT engine, BertClient.exe, is used in API mode as is used in GUI and script modes.

Installation

To install the FarSync BERT API support



Being a COM-based API, the FarSync BERT API appears very similar in all the different types of applications from which it can be used. It really only varies with regard to the specifics of the application environment itself.

Sample, illustrative Python, C#, VBS and LabVIEW applications are included in the BERT_API\examples folder.


Methods

The following methods are available to applications using the FarSync BERT Interface. These all map onto the corresponding operations that are supported by the FarSync BERT GUI itself.

Method Parameters Description
Start None Once the interface instance has been configured (i.e. via its port and pattern properties) the Start method should be called to start an actual BERT test
InjectError newVal - I16: Number of error bits to inject Whilst a BERT test is running, errors can be injected into the outbound datastream via the InjectError method
Reset None Whilst a BERT test is running, the statistics can be reset at any time via the Reset method i.e. without needing to stop the test
Stop None Use the Stop method to stop BERT test that is currently running

These methods are demonstrated in the supplied samples.

 

Properties

The following properties are available to applications using the FarSync BERT Interface. These map onto the corresponding configuration and statistical properties that are supported by the FarSync BERT GUI itself.

Property Type Description
Device I16 (R/W) Specifies the FarSync device instance to be used - this number is the same as the # identified in Device Manager in FarSync WAN Adapters - FarSync Flex/T2Ee (SDCI#).
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 0
Port I16 (R/W) Specifies the port number of the selected FarSync device
Default = 0
Interface FsBertInterfaceConstants (R/W):
FsBertInterface_V24 (1)
FsBertInterface_X21 (2)
FsBertInterface_V35 (3) FsBertInterface_RS530 (6) FsBertInterface_RS449 (6) FsBertInterface_RS485 (7)
Specifies the interface type of the FarSync port.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = V24
Rate I32 (R/W) Specifies the rate of the line connected to the FarSync port.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 9600
Clocking FsBertClockingConstants (R/W):
FsBertClocking_Internal (0)
FsBertClocking_External (1)
FsBertClocking_Internal_TT (2)
FsBertClocking_External_TT (3)
FsBertClocking_Bidirect (4)
Specifies the Clocking mode the FarSync port will use.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FsBertClocking_Internal
Async BOOLEAN (R/W) Specifies whether the FarSync port will be configured for Sync or Async mode
TRUE ==> The FarSync port will use Async mode
FALSE ==> The FarSync port will use Sync mode
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE i.e. use Sync mode
Termination BOOLEAN (R/W) Specifies whether termination is used on the FarSync port.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
Encoding FsBertEncodingConstants (R/W): FsBertEncoding_NRZ (0x80) FsBertEncoding_NRZI (0xa0) FsBertEncoding_FM0 (0xc0) FsBertEncoding_FM1 (0xd0) FsBertEncoding_MAN (0xe0) FsBertEncoding_DMAN (0xf0) Specifies the encoding mode used by the FarSync port.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = NRZ
InvertRxClock BOOLEAN (R/W) Specifies whether the port should change the phase of the internal clock by 180 degrees (for received data) - (see Invert Rx Clock).
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
NRZIClocking BOOLEAN (R/W) Specifies whether the port provides a separate one times clock with the (NRZI) encoded data - (see NRZI Clocking).
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
AdvancedClocking BOOLEAN (R/W) Specifies whether Advanced Clocking is used on the FarSync port.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
DataBits I16 (R/W) Specifies the number of async data bits (8,7,6 or 5) in each character.
This is only applicable when the BERT is set in ASYNC mode.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 8
StopBits I16 (R/W) Specifies the number of async stop bits (1 or 2) in each character.
This is only applicable when the BERT is set in ASYNC mode.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 1
Parity FsBertParityConstants (R/W):
FsBertParity_NONE (0) FsBertParity_ODD (1) FsBertParity_EVEN (2) FsBertParity_MARK (3) FsBertParity_SPACE (4)
Specifies the async parity setting for the port.
This is only applicable when the BERT is set in ASYNC mode.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = NONE
FlowControl FsBertFlowControlConstants (R/W):
FsBertFlowControl_NONE (1) FsBertFlowControl_RTS (2) FsBertFlowControl_XON (3)
Specifies the async flow control setting for the port.
This is only applicable when the BERT is set in ASYNC mode.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = NONE
InvertTx BOOLEAN (R/W) Specifies whether the BERT should invert its transmit data (See InvertTx (TIV)).
This property value can be optionally updated by the VI during the test.
Default = FALSE
AutoInvert BOOLEAN (R/W) Specifies whether the BERT should automatically invert the received data (if still in LOS after 2 secs) to determine if synchronisation can then be established (See AutoInvert (RIV)).
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
Pattern FsBertPatternConstants (R/W):
FsBertPattern_63 (1)
FsBertPattern_511 (2)
FsBertPattern_2047 (3)
FsBertPattern_2_15 (4)
FsBertPattern_2_20 (5)
FsBertPattern_2_23 (6)
FsBertPattern_QRSS (7)
FsBertPattern_1_7 (8)
FsBertPattern_1_16 (9)
FsBertPattern_2_8 (10)
FsBertPattern_3_24 (11)
FsBertPattern_ALT_1_0 (13)
FsBertPattern_FOX (14)
FsBertPattern_MK (15)
FsBertPattern_SP (16)
Specifies the pattern to be used for the next test to be started.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 2047
TestLength I32 (R/W) Determines how many bits to test in the received datastream before completing the test - (see Length).
A value of 0 implies the test will run continuously until the Stop method is called (or until, for example, the FarSync port is disconnected)
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 0
BurstMode BOOLEAN (R/W) Specifies whether the test should use Burst Mode or not.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE (i.e. don't use Burst Mode)
LoggingMode BOOLEAN (R/W) Specifies whether the test should perform logging or not.
This property is read by the FarSync BERT whenever a BERT test is started.
Default = FALSE
MaxLogFileSize I32 (R/W) Specifies maximum log file size to be used - (see MaxLogFileSize)
This property is read by the FarSync BERT whenever a BERT test is started.
Default = 1000000
DTR BOOLEAN (R/W) Indicates the state of the DTR (output) signal.
TRUE ==> Asserted; FALSE ==> Deasserted.
This property value can be optionally updated by the VI during the test.
Default = FALSE
RTS BOOLEAN (R/W) Indicates the state of the RTS (output) signal.
TRUE ==> Asserted; FALSE ==> Deasserted.
This property value can be optionally updated by the VI during the test.
Default = FALSE
CTS BOOLEAN (RO) Indicates the state of the CTS (input) signal.
TRUE ==> Asserted; FALSE ==> Deasserted.
DCD BOOLEAN (RO) Indicates the state of the DCD (input) signal.
TRUE ==> Asserted; FALSE ==> Deasserted.
InSync BOOLEAN (RO) Indicates whether the current test is in sync or not.
Status FsBertStatusConstants (RO):
FsBertStatus_Starting (1) FsBertStatus_Started (2) FsBertStatus_Stopped (3) FsBertStatus_StartError (4) FsBertStatus_AccessError (5)
Indicates the state of the current test.
softwareMode BOOLEAN (R/W) Specifies whether the test should run in hardware or software mode (see BERT Support). This property is read by the FarSync BERT whenever a BERT test is started. Default = FALSE (i.e. use Hardware Mode if supported by device)
RIV BOOLEAN (RO) Indicates whether the BERT is currently inverting its received data - (see Auto Invert (RIV))
Duration DBL (RO) Reports how long the current test has been running (usecs).
BitCount DBL (RO) Reports the number of bits received during the current test.
BlockCount DBL (RO) Reports the number of blocks received during the current test.
BitErrorCount DBL (RO) Reports the number of errored bits received during the current test.
BlockErrorCount DBL (RO) Reports the number of errored blocks received during the current test.
ESCount DBL (RO) Reports the number of errored seconds (ES) during the current test.
SESCount DBL (RO) Reports the number of seriously errored seconds (SES) during the current test.
ASCount DBL (RO) Reports the number of available (non-errored) seconds (AS) during the current test.
LOSCount DBL (RO) Reports the number of times synchronisation has ben lost during the current test.
LOSDuration DBL (RO) Reports how long synchronisation has been lost for during the current test.
BitRate DBL (RO) Reports the received bit rate achieved during the current test.
BlockRate DBL (RO) Reports the received block rate achieved during the current test.
BitErrorRate DBL (RO) Reports the received bit error rate calculated over the duration of the current test.
BlockErrorRate DBL (RO) Reports the received block error rate calculated over the duration of the current test.
ESRate DBL (RO) Reports the proportion of seconds that were errored seconds (ES) during the current test.
SESRate DBL (RO) Reports the proportion of seconds that were seriously errored seconds (SES) during the current test.
ASRate DBL (RO) Reports the proportion of seconds that were available seconds (AS) during the current test.
LOSRate DBL (RO) Reports the proportion of seconds where synchronisation was lost during the current test.
StopType FsBertStopTypeConstants (R/W):
FsBertStop_LENGTH (0) FsBertStop_TIME (1)
Specifies whether the test should terminate when the specified number of bits have been received or after the specified number of seconds have elapsed.
TestTime I32 (R/W) If StopType is set to TIME, this specifies the length of the test in seconds. The duration of the test starts after Sync is first achieved.
SyncTime I32 (R/W) Specifies how long the test should run without Sync being achieved.
PatternFilename SAFEARRAY(BYTE) I16 Specifies the filename of the User Pattern Filename. The length is specified by length(I16)
PatternFiletype FsBertUserPatternTypeConstants (R/W):
FsBertUserPatternType_BIN (0) FsBertUserPatternType_HEX (1)
Specifies the filetype of the User Pattern File. See UserPatterns for the correct format of HEX based text files.
MultiDropMode BOOLEAN (R/W) Specifies whether a Multi-Drop mode test should be run (see Multi-Drop for details). Default = FALSE.
MultiDropDesignation FsBertMultiDropConstants (R/W):
FsBertMultiDropDesignation- MASTER (0) FsBertMultiDropDesignation_SLAVE (1)
Specifies if this node should be configured as a Master or a Slave node.
MultiDropSlaveList SAFEARRAY(BYTE) I16 In Master mode, specifies the list of slaves to be polled. Slaves can be entered individually i.e. 3,4,5 or as a range i.e. 3-5, or a combination of both i.e. 3,4-6,8 10 11. The length is specified by Length (I16).
MultiDropSlaveId I32 (R/W) In Slave mode, specifies the Id of the slave.
MultiDropPollQuietSlaves BOOLEAN (R/W) In Master mode, specifies if unresponsive slaves continue to be polled. Default = FALSE.
MultiDropPayloadLength I32 (R/W) In Master mode, specifies the size (in bytes) of the payload sent in each packet.
MultiDropSlaveSelect I32 (R/W) Specifies the slave from which to read results and status information. If MultiDrop mode is TRUE, this should be called before calling BitCount, BlockCount etc. and before MultiDropSlaveDuration, MultiDropActive, MultiDropSync, MultiDropRIV and MultiDropTIV.
MultiDropSlaveDuration DBL (RO) Reports the specified slave’s share of time (in µsecs), since the test began.
MultiDropRIV BOOLEAN (RO) Reports the receiver inversion status of the specified slave.
MultiDropTIV BOOLEAN (RO) Reports the transmitter inversion status of the specified slave.
MultiDropSync BOOLEAN (RO) Reports the state of synchronisation of the specified slave.
MultiDropActive BOOLEAN (RO) Reports if the specified slave is actively echoing back messages.
RoundTripDelayMode BOOLEAN (R/W) Specifies whether a Round Trip Delay test should be run (see Round Trip Delay for details). Default = FALSE.
RTDPayloadLength I32 (R/W) Specifies the size of the Round Trip Delay packet payload.
RTDTransmitDelay I32 (R/W) Specifies the delay between receiving one packet and transmitting the next packet.
RTDReceiveTimeout I32 (R/W) Specifies the timeout to wait for a transmitted packet to be received.
RTDLostPackets DBL (RO) Reports the number of packets which have been transmitted but not received.
RTDTxPackets DBL (RO) Reports the number of packets which have been transmitted.
RTDRxPackets DBL (RO) Reports the number of packets which have been received.
RTDTime DBL (RO) Reports the Round Trip Delay time of the last packet received at the sampling time.
RTDMin DBL (RO) Reports the minimum Round Trip Delay time received.
RTDMax DBL (RO) Reports the maximum Round Trip Delay time received.
RTDAverage DBL (RO) Reports the average Round Trip Delay time received.
RTDTrend DBL (RO) Reports the average of the last 10 Round Trip Delay packets received.
RTDTimes SAFEARRAY(I32,I32), I16 A 2-dimensional array containing the Round Trip Delay times and the number of each occurrence. Returns the array size as RTDTimes (I16).

A range of these properties are demonstrated in the supplied samples.


Logging

As in the GUI and Command Line Modes, if logging is enabled, the BERT's log file (see the Logging section) is updated with each test that is run from the BERT-enabled application. The maximum log file size can be configured programmatically via the MaxLogFileSize property.


A number of additional points, relating to use of the FarSync BERT API specifically from LabVIEW applications (VIs), are detailed in the following section.


LabVIEW Support

The FarSync BERT LabVIEW support has been developed and tested using LabVIEW 2010-2020.

Opening the Interface

To utilise the FarSync BERT interface from a LabVIEW VI, it firstly needs to open the interface.

To do this, create a Automation Refnum control which is located on LabVIEW’s Controls:Classic»Classic Refnum palette - see http:/one.ni.com/reference/en-XX/help/371361H-01/lvhowto/pes_of_refnum_controls/

Right-click and use the ActiveX Class menu option to select the FSBERTIFLib2.IFsBert2 interface.

If the FSBERTIFLib2.IFsBert2 option is not available then you need to use the Browse option to use the Select Object From Type Library dialog to point LabVIEW at the fsbertif.dll in the BERT_API\install folder where you installed the FarSync BERT files in the installation step above.

Now that the interface type has been set, add an Automation Open function which is located on LabVIEW’s Functions:Connectivity»ActiveX palette - see http://zone.ni.com/reference/en-XX/help/371361H-01/lvcomm/automation_open/ and assign its Automation Refnum input to the output from the Automation Refnum control.

The reference output from the Automation Open function can then be used for all subsequent FarSync BERT interface calls.

Note that the ActiveX palette can be quickly located via the context menu of the Automation Refnum node. As you create additional nodes for the FarSync BERT interface, an ActiveX palette menu option will also appear in their context menus.

 

To read/write a FarSync BERT property just create a Property Node (which is located on LabVIEW’s Functions:Connectivity»ActiveX palette) and wire it up to use the interface reference and select the required property/properties to read/write e.g.

 

To use a FarSync BERT method just create a Invoke Node (which is located on LabVIEW’s Functions:Connectivity»ActiveX palette) and wire it up to use the interface reference and select the required method e.g.

 

Closing the Interface

Once the VI has finished using the interface it should close it using the Close Reference function which is located on LabVIEW’s Functions:Connectivity»ActiveX palette - see http://zone.ni.com/reference/en-XX/help/371361H-01/glang/close_lv_object_reference/).

Sample VIs

Two sample VI’s, have been provided, fsbert.vi and RTD.vi. They both demonstrate how to interface to the FarSync BERT from a VI. These examples can be extended/modified to meet your specific requirements.

fsbert.vi

This VI demonstrates how to implement some of the features of the FarSync BERT's standard GUI:

 

The sample configures the BERT port using the following:

The sample configures the BERT test using the following:

These property values are merely examples and can be set statically or dynamically by the user's own VI as required (note: a modified port configuration will not take effect until the next time the Start Method is called).

The sample's signals/LEDs are maintained using:

The sample's statistics are maintained via:

RTD.vi

rtd.vi

The Round Trip Delay VI sample demonstrates the features of the FarSync BERT’s Round Trip Delay Mode.

Before running the test, the following parameters should be set:

The RTD test is started automatically when the VI is run. Whilst the test is running the results table and chart are updated twice a second. The test can be stopped by stopping the VI or by pressing the Stop button.

The configuration is:

RTD.vi configuration

The results are maintained by:

RTD.vi stats

For more details about the RTD results, see the Round Trip Delay Results section.

Troubleshooting

1) If, when you run the sample fsbert VI, the following dialog is displayed:

it implies that the BERT interface has not been registered successfully. Please quit LabVIEW and check the installation step above

2) If, when you run the sample fsbert VI, the following dialog is displayed:

it implies that the FarSync port is not accessible. This could be, for example, because

Note that the Status value shown here corresponds to the Status property value,  FsBertStatus_AccessError (5), as listed in the Property table.

3) If, when you run the sample fsbert VI, the following dialog is displayed:

it implies that the BERT engine components themselves are not accessible. Please quit LabVIEW and check the installation step above.

Note that the Status value shown here corresponds to the Status property value, FsBertStatus_StartError (4) as listed in the Property table.

 

Copyright © FarSite Communications Ltd. 2009-2020