This is a sub-page of the FrontPanel API, pasted from the Confluence view.
If you intend to ship a software application based on the FrontPanel SDK, there are a few things you will need to consider in order to improve the user experience of your customers. Please consider the notes below when packaging your software for distribution.
Microsoft Visual C++ Redistributable
The FrontPanel DLL, Python, Java, and C# libraries depend on the Microsoft Visual C++ runtime libraries. These are installed by the Microsoft Visual Studio C++ Redistributable. Please see the FrontPanel release notes to determine which version of the redistributable corresponds to the FrontPanel libraries in that release.
You’ll need to include the following in your software release:
- FrontPanel Library – DLL or corresponding libraries for Python, Java, or C#. Note that the bitness of this must match the bitness of your software application.
- FrontPanel Driver – Use the DriverOnly installer and run this installer during your application installation process.
- Microsoft Visual Studio C++ Redistributable (for FrontPanel) – Install and run this redistributable package. Note that the bitness of this must match the bitness of the FrontPanel Library.
- Microsoft Visual Studio C++ Redistributable (for your application) – Install and run this redistributable package. Note that this may or may not be the same version as the one used for FrontPanel.
It is a good idea to test your software application on a fresh installation of Windows. The recommended way to do this is with a Virtual Machine (e.g. VMWare):
- Install the appropriate version(s) of Windows into one or more virtual machines.
- After the installation and first update of Windows, make a snapshot.
- Test your application installer, making sure to check device enumeration and proper communication with your application.
- Once testing is complete, reset your VM to the snapshot.
This process provides an efficient way to test on a clean installation. Once drivers and libraries are installed, the system can make changes that persist even if you uninstall your application. This makes it difficult to truly test the usability of your installer as the test machine is now “tainted” and may not behave in the same manner as a customer’s system.
The okCFrontPanel Class
This class is the workhorse of the FrontPanel API. It’s methods are organized into three main groups: Device Interaction, Device Configuration, and FPGA Communication.
In a typical application, your software will perform the following steps:
- Create an instance of okCFrontPanel.
- Using the Device Interaction methods, find an appropriate XEM with which to communicate and open that device.
- Configure the device PLL (for devices with an on-board PLL).
- Download a configuration file to the FPGA using ConfigureFPGA(…).
- Perform any application-specific communication with the FPGA using the FPGA Communication methods.
Device Interaction (USB and PCI Express)
As much as the API encapsulates the underlying details of the hardware interface, the fact remains that the module is a USB or PCIe device and therefore must play by the rules. These methods provide a means to iterate all attached FrontPanel devices, query certain information about each one, and ultimately open a particular device for communication. These methods are summarized in the following table. For brevity, arguments have been removed. Please see the API reference manual for more details.
The methods available in the FrontPanelDevices class can be used to enumerate and open devices.
|GetCount||Returns the number of FrontPanel devices attached to the PC. On Windows, this method counts all devices not already open. On Linux and Mac, this counts -all- devices.|
|GetSerial||If multiple devices are connected to a PC this method can be used to retrieve the serial number of a given device. Note that devices will not appear in any particular order when querying their serial numbers so it is necessary to iterate over all devices to find if a specific serial number is present.|
|Open||Open a device (optionally with matching serial number) for communication.|
When using FrontPanel 5.0.0 and above it is recommended to use the methods described above for device interaction. The methods below will still work but will not support the same feature sets.
|GetDeviceCount||Returns the number of FrontPanel devices attached to the PC. On Windows, this method counts all devices not already open. On Linux and Mac, this counts -all- devices. This method also queries information about each device which can be retrieved using the GetDeviceListXXX methods below.|
|GetDeviceListModel||Retrieves the board model of a connected device.|
|GetDeviceListSerial||Retrieves the serial number of a connected devicce.|
|OpenBySerial||Opens a device (with matching serial number) for communication.|
|GetDeviceMinorVersion||Retrieves the current firmware minor version.DEPRECATED: GetDeviceInfo replaces this method. This method will be removed in a future version of FrontPanel.|
|GetDeviceMajorVersion||Retrieves the current firmware major version.DEPRECATED: GetDeviceInfo replaces this method. This method will be removed in a future version of FrontPanel.|
|GetSerialNumber||Returns a 10-digit serial number unique to each device. This serial number may be used to select a specific device among those available. The serial number is set at the factory and is not user-modifiable.DEPRECATED: GetDeviceInfo replaces this method. This method will be removed in a future version of FrontPanel.|
Once an available device has been opened, these methods allow you to configure it’s available features such as PLL settings and EEPROM parameters and to download configuration data to the FPGA.
|GetDeviceID||Returns a device identification string stored in the device. Unlike the serial number, this string may be changed by the user using the API or the FrontPanel application. It is not guaranteed to be unique.DEPRECATED: GetDeviceInfo replaces this method. This method will be removed in a future version of FrontPanel.|
|SetDeviceID||Allows the user to set the device ID.|
|LoadDefaultPLLConfiguration||Configures the PLL with settings stored in EEPROM.|
|GetPLLxxxConfiguration||Retrieves the current on-board PLL configuration. (xxx is either 22150 or 22393)|
|SetPLLxxxConfiguration||Sets the on-board PLL to a given configuration. (xxx is either 22150 or 22393)|
|GetEepromPLLxxxConfiguration||Retrieves the PLL configuration stored in the on-board EEPROM. (xxx is either 22150 or 22393)|
|SetEepromPLLxxxConfiguration||Programs the on-board EEPROM with a PLL configuration for later retrieval. (xxx is either 22150 or 22393)|
|ConfigureFPGA||Downloads a Xilinx configuration bitfile to the FPGA.|
|ConfigureFPGAFromMemory||Similar to above, but with the configuration file contents in memory.|
|ConfigureFPGAWithReset||(USB 3.0 only) Downloads a Xilinx configuration bitfile to the FPGA and provides a reset profile to perform after configuration.|
|ConfigureFPGAFromMemoryWithReset||(USB 3.0 only) Similar to above, but with the configuration file contents in memory.|
|FlashEraseSector||(USB 3.0 only) Erases a single sector in user flash.|
|FlashWrite||(USB 3.0 only) Writes data to user flash.|
|FlashRead||(USB 3.0 only) Reads data from user flash.|
Once the FPGA has been configured, communication between the application and the FPGA hardware is done through these methods. The FPGA is connected directly to the bridge device (USB microcontroller or PCIe bridge) on the XEM. These methods communicate through that connection and require that an instance of the HDL module okHostInterface be installed in the FPGA configuration.
A brief description of the API methods is in the table below. The way the API and FrontPanel HDL modules communicate is described in more detail later.
|IsFrontPanelEnabled||Checks to see that an instance of the okHostInterface is installed in the FPGA configuration.|
|IsFrontPanel3Supported||Returns true if the firmware on the device supports FrontPanel-3.|
|ResetFPGA||Sends a reset signal through the host interface. This is used to reset the host interface or any endpoints. It can also be used to reset user hardware.|
|UpdateWireIns||Updates all wire in values (to FPGA) simultaneously with the values held internally to the API.|
|UpdateWireOuts||Simultaneously retrieves all wire out values (from FPGA) and stores the values internally.|
|UpdateTriggerOuts||Retrieves all trigger out values (from FPGA) and records which endpoints have triggered since the last query.|
|SetWireInValue||Sets a wire in endpoint value. Requires a subsequent call to UpdateWireIns.|
|GetWireOutValue||Retrieves a wire out endpoint value. Requires a previous call to UpdateWireOuts.|
|ActivateTriggerIn||Activates a given trigger in endpoint.|
|IsTriggered||Returns true if a particular trigger out endpoint has been triggered since a previous call to UpdateTriggerOuts.|
|WriteToPipeIn||Writes data (byte array) to a pipe in.|
|ReadFromPipeOut||Reads data (byte array) from a pipe out.|
|WriteToBlockPipeIn||Writes data to a block-throttled pipe in.|
|ReadFromBlockPipeOut||Reads data from a block-throttled pipe out.|
|WriteRegister||(USB 3.0 only) Performs a single write transaction on the Register Bridge.|
|ReadRegister||(USB 3.0 only) Performs a single read transaction on the Register Bridge.|
|WriteRegisters||(USB 3.0 only) Performs multiple write transactions on the Register Bridge.|
|ReadRegisters||(USB 3.0 only) Performs multiple read transactions on the Register Bridge.|