APIs require a device driver of the same generation.
Beyond the APIs (used for the communication between the host computer and the USB FX2 microcontroller), another set of API exists: they are called "API commands". The application sends API commands to the Xilinx MicroBlaze embedded processor by means of the following API functions:
- generation 2: TE0300_SendCommand(…, command, …);
- generation 3: TE_USB_FX2{_}SendCommand(..., command, …).
The Xilinx MicroBlaze soft embedded processor executes then the command. Skilled users can extend the API command set themselves.
Generation 2
DLL files:
Documentation:
This API
- uses a C interface, and therefore can be easily bound to Python;
- uses handles;
- cannot set any time-out for SetData() function. In fact, it is internally set to 1000 ms.
- cannot set the driver buffer dimension;
- is closed source, and therefore cannot be extended or enhanced.
A binding from Python to DEWESoft TE USB API is possible through the ctypes function library.
Generation 3
Trenz Electronic USB FX2 APIs
- TE_USB_FX2_CyAPI API for C/C++
- TE_USB_FX2_CyUSB API for .NET Framework
are based on the Cypress CyUSB.sys device driver (renamed as TE_USB_FX2_xx.sys) and respectively on
- Cypress CyAPI APIs for C/C++
- Cypress CyUSB API for .NET Framework
distributed with the Cypress SuiteUSB 3.4 (or later).
Trenz Electronic USB FX2 APIs do not use handles.
TE_USB_FX2_CyAPI APIs (C++)
API files:
- TE_USB_FX2_CyAPI TE_USB_FX2_CyAPI.dll is open source but CyAPI.lib is not. Nevertheless, its source code can be requested from Cypress under non disclosure agreement.
Documentation:
Cypress CyAPI (CyAPI.lib) APIs for C/C++:
- are static libraries (embedded in TE_USB_FX2_CyAPI.dll and therefore not required by the user program);
- can be used by both managed (with .NET) C++ code and by unmanaged (without .NET) C++ code;
- have one version for Microsoft Windows 32 bit;
- have one version for Microsoft Windows 64 bit;
- have same name to ease code portability.
Trenz Electronic TE_USB_FX2_CyAPI.dll's for C/C++:
- are dynamic libraries;
- can be used by both managed (with .NET) C++ code and by unmanaged (without .NET) C++ code;
- have one version for Microsoft Windows 32 bit;
- have one version for Microsoft Windows 64 bit;
- have same name to ease code portability;
- are open source (can be modified and extended).
TE_USB_FX2_CyAPI APIs are not pure extern C code libraries because an external creation of a class instance defined in CyAPI.h (CyAPI.lib) is required.
Advantage:
- possible to directly access CyAPI.lib classes and functions to extend Trenz Electronic TE_USB_FX2_CyAPI.dll libraries with other classes and functions
- support of multi-thread and multi-process programming.
Disadvantage:
- A binding from Python to TE_USB_FX2_CyAPI APIs is possible by resorting to a wrapper (e.g. through SWIG) rather than just the ctypes function library. This wrapper is not provided by Trenz Electronic.
A pure extern C code library version of TE_USB_FX2_CyAPI APIs (codename: simplified TE_USB_FX2_CyAPI APIs) is available for developers.
Advantage:
- binding to Python requires just the ctypes function library rather than by resorting to a wrapper.
Disadvantages:
- impossible to directly access CyAPI.lib classes and functions to extend Trenz Electronic TE_USB_FX2_CyAPI.dll libraries with other classes and functions;
- no support of multi-thread programming (but still support of multi-process programming).
TE_USB_FX2_CyUSB API (.NET)
API files:
- TE_USB_FX2_CyUSBTE_USB_FX2_CyUSB.dll is open source but CyUSB.dll is not. Nevertheless, its source code can be requested from Cypress under non disclosure agreement.
Documentation:
Cypress CyUSB (CyUSB.dll) API for .NET Framework:
- is a dynamic library (not embedded in TE_USB_FX2_CyAPI.dll and therefore required by the user along with TE_USB_FX2_CyAPI.dll);
- classes and functions can be directly accessed from the application to extend Trenz Electronic TE_USB_FX2_CyUSB.dll libraries with other classes and functions;
- has only one version for both Microsoft Windows 32 and 64 bit.
- is not a COM (Component Object Model) object, so it cannot be called by C++ or Python code;
- is a managed Microsoft .NET class library that can be used with any programming language of the .NET Framework (Visual Basic, Managed C++, C#, …);
Trenz Electronic TE_USB_FX2_CyUSB.dll for .NET Framework:
- is a dynamic library;
- has only one version for both Microsoft Windows 32 and 64 bit;
- is not a COM (Component Object Model) object, so it cannot be called by C++ or Python code;
- is a managed Microsoft .NET class library that can be used with any programming language of the .NET Framework (Visual Basic, Managed C++, C#, …);
- is open source (can be modified and extended).
TE_USB_FX2_CyUSB.dll has no binding to Python because it is pure .NET CLR code that cannot be compiled as a COM object. It is a managed Microsoft .NET class library that can be used with all languages of the NET Framework (Visual Basic, Managed C++, C#, …) or other .NET infrastructures (such as IronPython).
If the user application is mainly made of C# code, it is convenient to use IronPython.If the user application is mainly made of Python, it is convenient to use Python for .NET package.
Differences Between TE_USB_FX2_CyAPI (C++) APIs and TE_USB_FX2_CyUSB (.NET) API
TE_USB_FX2_CyAPI (C++) APIs and TE_USB_FX2_CyUSB (.NET) API do not have the same signature although they are very similar. The signature of the pure extern C code library version of TE_USB_FX2_CyAPI APIs available for developers (codename: simplified TE_USB_FX2_CyAPI APIs) is slightly different from the two signatures above.
TE_USB_FX2_CyUSB (.NET) API is intrinsically cleaner than TE_USB_FX2_CyAPI (C++) APIs because CyUSB.dll is intrinsically cleaner than CyAPI.lib.
Please note that CCyUSBDevice Cypress class in the Cypress CyAPI C++ API is actually the list of all USB devices currently served by a Cypress USB driver derivative (e.g. Cypress generic USB device or Trenz Electronic USB FX2 device). For ease of understanding and convenience, Trenz Electronic named the corresponding variable as USBdevList.
API | Cypress class name | TE USB FX2 variable name |
|---|
C++ API | CCyUSBDevice | USBdevList |
|---|
.NET API | USBDeviceList | USBdevList |
|---|
Table: device list.
API | Cypress class name | TE USB FX2 variable name |
|---|
C++ API | (not available) | (not available) |
|---|
.NET API | CyUSBDevice | TE_USB_FX2_USBDevice |
|---|
Table: single device of the device list above.
Most functions, parameters and variables have maintained name and meaning across APIs. A notable exceptions is recalled in the following table.
TE_USB_FX2_CyAPI (C++) APIs | TE_USB_FX2_CyUSB (.NET) API |
|---|
TE_USB_FX2_SetData_InstanceDriverBuffer()
TE_USB_FX2_SetData() | (not available)
TE_USB_FX2_SetData() |
TE_USB_FX2_GetData_InstanceDriverBuffer()
TE_USB_FX2_GetData() | (not available)
TE_USB_FX2_GetData() |
Table: SetBata/GetDate naming exception.
Possible Future Work
A pure extern C code library version of TE_USB_FX2_CyAPI (C++) APIs and TE_USB_FX2_CyUSB (.NET) API would
- ease binding from Python or another programming language, but also
- make impossible to directly access CyAPI.lib classes and functions to extend Trenz Electronic TE_USB_FX2_CyAPI.dll libraries or CyUSB.lib classes and methods to extend Trenz Electronic TE_USB_FX2_CyUSB.dll library.