Net Protocol Suite Python Module API...

© 2014 Teledyne LeCroy, Inc. v1.02

Net Protocol Suite Python Module API Reference

TELEDYNE LECROY

of 11 © 2014 Teledyne LeCroy, Inc. v1.02

1 Table of Contents

1. Introduction .......................................................................................................................................... 2

2. Setup Requirements ............................................................................................................................. 2

3. Definitions ............................................................................................................................................. 3

4. API Reference ........................................................................................................................................ 3

4.1. TLNetAPI ........................................................................................................................................ 3

4.2. Trace Object .................................................................................................................................. 4

4.3. Packet Object ................................................................................................................................ 5

4.4. Project Object ............................................................................................................................... 6

4.5. AnalyzerSettings Object ................................................................................................................ 7

5. Memory Management and Garbage Collection ................................................................................... 8

5.1. API Initialization and Unitialization ............................................................................................... 8

5.2. API Object Garbage Collection ...................................................................................................... 8

6. Module Limitation ................................................................................................................................. 9

6.1. Test Platform ................................................................................................................................. 9

6.2. API Unitialization Order ................................................................................................................ 9

6.3. API Return Code ............................................................................................................................ 9

6.4. Analyzer Connection over Ethernet .............................................................................................. 9

6.5. Event Handler ................................................................................................................................ 9

6.6. StartJammers and StopJammers .................................................................................................. 9

7. Examples ............................................................................................................................................. 10

7.1. Open a project, record something, wait for trace .......................................................................... 10

7.2. Open a trace file and retrieve packet count ................................................................................... 10


1. Introduction Net Protocol Suite contains a python module library, TLNetAPI, that wraps the Net Protocol Suite C API

implementation, providing automation features for the Python language.

The module is built on boost python 1.56.0. Since the Net Protocol Suite only provides 32-bit DLL, the

module can only be imported by 32-bit Python.

2. Setup Requirements OS: Windows

Python version: 2.7.x 32-bit

Net Protocol Suite version: Net Protocol Suite 1.90 or later must be installed.

Python module location: The “TLNetAPI.pyd” module must be located in the \API\SDK\Bin directory

e.g., C:\Users\Public\Documents\LeCroy\Net Protocol Suite\API\SDK\Bin\TLNetAPI.pyd

Environment variables:

PATH – Add the \API\SDK\Bin directory to the PATH variable

QT_PLUGIN_PATH – Set this to the \API\SDK\Bin directory

Example (DOS):

C:\> set PATH=%PATH%;C:\Users\Public\Documents\LeCroy\Net Protocol Suite\API\SDK\Bin

C:\> set QT_PLUGIN_PATH=C:\Users\Public\Documents\LeCroy\Net Protocol Suite\API\SDK\Bin

Alternatively, you can set them from the Windows Environment Variables dialog:


3. Definitions The following is a list of some terms frequently used in this document. Refer to the Net Protocol Suite

User Manual for descriptions of other terms not listed here.

Trace – This is the file that contains the data captured by the analyzer.

Project – This is a configuration file that defines the following parameters of your test setup:

- One or more analyzer hardware chains (models and serial numbers)

- Ports configuration

- Analyzer hardware settings

- Analyzer recording, triggering, and filtering settings

- Jammer scenarios

Chain – This is a set of analyzer hardware units. A chain of 1 unit is valid and most common. A chain of

multiple units would be linked together with a CATC Sync cable. Refer to the Net Protocol Suite User

Manual for details on the hardware’s expansion capabilities. Each chain in a Project operates

independently from other chains in the Project.

Analyzer – This is the function of the analyzer hardware that captures traffic at line rate and stores it in a

dedicated capture buffer.

Jammer – This is the function of the analyzer hardware that injects errors into traffic at line rate.

Scenario – This is the user-defined program that specifies the Jammer behavior.

4. API Reference

4.1. TLNetAPI The package name is TLNetAPI, which can be imported by python. TLNetAPI contains all functions and

classes for Net Protocol Suite.

enum TLNetAPI.EDataType

This enumeration describes the type of packet.

enum TLNetAPI.EAPIErrorCode

This enumeration describes the returned error code from API execution.

enum TLNetAPI.ELinkConfiguration

This enumeration describes the analyzer port configuration.

enum TLNetAPI.EConnectionType

This enumeration describes the analyzer connection type.

enum TLNetAPI.ERecordingStatus

This enumeration describes the analyzer’s recording status which returned by status report event.


enum TLNetAPI.EJammerSessionStatus

This enumeration describes the jammer’s status which return by status report event.

enum TLNetAPI.ETriggerMode

This enumeration describes the trigger mode.

enum TLNetAPI.EAnalyzerSpeed

This enumeration describes the analyzer link speed.

enum TLNetAPI.EICActionType

This enumeration describes the jammer scenario’s action.

TLNetAPI.APIError_GetDescription(error_code)

Returns the error description for error_code. The input error_code is the EAPIErrorCode which

returned by last API called.

TLNetAPI.OpenFile(filename)

Returns APITrace object which represents a trace file.

TLNetAPI.OpenProject(filename)

Returns APIProject object which represents a project file.

TLNetAPI.GetVersion()

Returns software version and build number in x.y.z format, while x is major version number, y is

minor version number and z is build number.

TLNetAPI.GetHardwareInfo(serial_number)

Returns hardware ID for connected device.

4.2. Trace Object This class represents an opened trace file.

class TLNetAPI.APITrace

The APITrace has the following methods:

Close()

Close the opened trace file. Note: This will not release the memory.

GetStartDateTimestamp()

Returns the start date timestamp for the trace.

GetEndDateTimestamp()


Returns the end date timestamp for the trace.

GetTriggerDateTimestamp()

Returns the trigger date timestamp for the trace.

GetCount()

Returns the number of packets in the trace.

GetPacket(index)

Return APITracePacket object by a given index. The index is 0 based.

ExportToCSV(file_name, OnExportStatus)

Export the opened trace file to csv format. The second parameter is the callback for status

reporting. You can use None if you don’t need status events.

4.3. Packet Object This class represents a packet from opened trace.

class TLNetAPI.APITracePacket

The APITracePacket has the following methods:

GetTimeStamp()

Returns time stamp of the packet in picoseconds resolution.

GetChannel()

Returns analyzer channel which the packet is captured by.

GetSpeed()

Returns protocol data rate or speed.

GetType()

returns type of the packet.

GetData()

It returns a MemoryView object which contains raw packet data. The buffer is managed

by packet object, it is valid as long as the packet object is alive and the trace is open.

GetBookmark()

Returns packet bookmark strings (only bookmark title).

SetBookmark(new_bookmark)

Set the packet bookmark. If the packet already has an existing bookmark, it is replaced

with the new one.


4.4. Project Object This class represents an opened project file.

class TLNetAPI.APIProject

The APIProject has the following methods:

Close()

Close the opened project file. Note: This will not release the memory.

Save()

Save the project file.

GetChainCount()

Returns number of included chains in the project.

GetDeviceCount(chain_index)

Returns number of devices in a chain of a project.

GetPairPortCount(chain_index, device_index)

Returns number of pair ports supported by a device in a chain of project.

GetAnalyzerSettings(chain_index)

Returns APIAnalyzerSettings object for a specific chain in the opened project.

GetPortConfiguration(chain_index, device_index)

Returns the port configuration of a device in a chain.

Assign(serial_number, connection_type, chain_index, device_index)

Connects to a board and assigns it to a device of a chain in project. If board needs any

update, it returns error code. You must make sure to Assign an appropriate board to the

project before calling StartRecording or StartJammer.

StartRecording(chain_index, trigger_settings_count, trigger_settings_names, OnTraceCreated,

OnReportRecordingStatus, OnError, time_out)

It starts capturing process.

chain_index is the index of chain. It is zero base indexes.

trigger_settings_count is the number of trigger setting names, 0 for no trigger.

trigger_setting_names is the trigger/filter setting in current opened project. If there is no

trigger, use “”.

Event handler OnTraceCreated, OnReportRecordingStatus and OnError refer to callback

functions to handle the events. If it is None, the events won’t be sent to the client. If user


wants follow or do any process during status of recoding, OnReportRecordingStatus

callback function is defined in this structure that can be used. Meanwhile,

OnError callback function will be called when any error happens during recording or

uploading process. When a trace is created, OnTraceCreated will be called.

APIProject_StopRecording will be called after timeout is elapsed. If it is zero, it never calls

APIProject_StopRecording(). It is supposed that this timer just stops recording process. It

cannot stop uploading process.

StopRecording(chain_index, do_not_upload)

Stops recording or uploading process.

WaitForTraces(chain_index) ****Available in Net Protocol Suite 1.75 and later

This function blocks until the running recording operation finishes.

chain_index parameter should contain which chain index analyzer is running on and the

user wants to wait for it.

In an environment without event-loop, like console applications for example, you must

call WaitForTraces after start recording, otherwise the callbacks won’t get invoked.

After you call WaitForTraces, then client will received OnTraceCreated notification.

StartJammer(chain_index, device_index, pair_port_index, scenario_name,

OnReportMonitoringStatus, OnReportJammerStatus, OnJammerError)

Starts the jammer process.

Event handler OnReportMonitoringStatus, OnReportJammerStatus and OnJammerError

refer a callback function to handle the events. If it is None, the events won’t be sent to

the client.

StopJammer(chain_index, device_index, pair_port_index)

Stops the jammer process.

4.5. AnalyzerSettings Object This class represents the AnalyzerSettings from an opened project.

class TLNetAPI. APIAnalyzerSettings

The APIAnalyzerSettings has the following methods:

GetSegmentBufferSize(device_index)

Returns size of the segment buffer.

SetSegmentBufferSize(device_index, segment_size)

It sets the size of segment buffer.


SetTraceFileName(file_name)

It sets the file name of the analyzer settings.

GetTraceFileName()

Returns the trace file name of analyzer settings object.

SetNumberOfSegment(segment_number)

It sets number of segment. Furthermore, if segment buffer size is not valid according to

the device property and new segment number, it will change to the valid max segment

buffer size according to the current segment number.

GetNumberOfSegment()

Returns number of segments.

SetTrigMode(trig_mode)

Sets trigger mode.

GetTrigMode()

Returns trigger mode.

SetTrigFilterSetting(device_index, trig_setting_name)

Sets trigger filter setting.

SetTrigPosition(device_index, trig_position)

Sets trigger position.

GetTrigPosition(device_index)

Returns the trigger position.

5. Memory Management and Garbage Collection In C application, you have to explicitly call create and destroy against the object you want to use, otherwise

the object memory will not be released, this will cause memory leak in your automation application.

Python's memory allocation and deallocation method is automatic. The TLNetAPI implements memory

management into Python garbage collection, user should not need to worry about memory management.

5.1. API Initialization and Unitialization The TLNetAPI will get initialized when the module is imported into python. API unitialization process is

registered as module cleanup function. Usually the cleanup function is invoked when the module is out of

scope or during the python interpreter termination.

5.2. API Object Garbage Collection Memory management for API object is integrated into python garbage collection. The API object such as

APITrace and APIPacket will be deleted and memory will be released when the object is out of scope. The


cleanup function is registered as class __del__ function. User can also use del function to explicitly delete

and release an object.

6. Module Limitation

6.1. Test Platform The Net Protocol Suite only provides a 32-bit DLL for automation, the python module can only be imported

in 32-bit python interpreter.

6.2. API Unitialization Order Since object deletion is managed by python garbage collection, there is no guarantee when it will happen.

In order to ensure the release, APIUnitialization() must be the latest function to be called. If you are

running the module in python script, the garbage collection is invoked when the script finished.

APIUnitialization() will be called after all scripts get executed, and python is ready to be terminated.

If you import the module in python.exe without script, when you exit the interpreter, APIUnitialization()

is invoked immediately, then garbage collection will run. This will cause an exception on unitialize API

objects.

6.3. API Return Code All APIs will return an error code to indicate if the API is executed successfully. In TLNetAPI, the APIs will

return error code if you do not expect any other value to be returned. If the API returns any useful value

to the user, the error code will no return. Instead if the API fails (error code is not API_OK), a python

runtime exception will be raised, and error description will be returned.

6.4. Analyzer Connection over Ethernet Net Protocol Suite uses Windows message loop to discover devices on network. In order to connect

analyzer over Ethernet, your application must implement MFC message loop. Ethernet connection is not

available on TLNetAPI.

6.5. Event Handler Only OnReportMonitoringStatus event is fired in a separated thread, all other events are fired in the same

thread as your main thread.

6.6. StartJammers and StopJammers StartJammers and StopJammers functions are not implemented in the python module.


7. Examples

7.1. Open a project, record something, wait for trace import sys

sys.path.append("C:\Users\Public\Documents\LeCroy\Net Protocol Suite\API\SDK\Bin")

import TLNetAPI

# OnTraceCreated callback for StartRecording

def OnTraceCreated():

# ====

# Do your own callback logic here...

# ====

project = TLNetAPI.OpenProject("myproject.gep")

# Assign board with serial number 9 and connection USB to the project

project.Assign(9, TLNetAPI.EConnectionType.CONNECTION_TYPE_USB, 0, 0)

# Start chain 0, no triggers, OnTraceCreated callback, and no timeout

project.StartRecording(0,0,"", OnTraceCreated,None,None,0)

# ====

# Do your own program logic here...

# ====

# Stop chain 0 and start the trace upload

project.StopRecording(0,False)

# Wait until trace uploading is done. Note that this method requires Net 1.75 or later.

project.WaitForTraces(0)

del project

7.2. Open a trace file and retrieve packet count import sys

sys.path.append("C:\Users\Public\Documents\LeCroy\Net Protocol Suite\API\SDK\Bin")

import TLNetAPI

trace = TLNetAPI.OpenFile("mytrace.get")

trace.GetCount()

del trace

Net Protocol Suite Python Module API...

Documents

Transcript of Net Protocol Suite Python Module API...