net protocol suite python module api...
TRANSCRIPT
© 2014 Teledyne LeCroy, Inc. v1.02
Net Protocol Suite Python Module API Reference
TELEDYNE LECROY
Page 1 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
Page 2 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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:
Page 3 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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.
Page 4 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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()
Page 5 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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.
Page 6 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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
Page 7 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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.
Page 8 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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
Page 9 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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.
Page 10 of 11 © 2014 Teledyne LeCroy, Inc. v1.02
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
Page 11 of 11 © 2014 Teledyne LeCroy, Inc. v1.02