Device Discovery
Device discovery is the process by which a software application determines if any FrontPanel-supporting devices are available and what information is available about them before selecting one (or more) and establishing communication with it (or them). This collection of methods provides a means to enumerate all attached FrontPanel devices, query certain information about each one, and ultimately open a particular device for communication.
FrontPanelDevices Class
The methods available in the FrontPanelDevices class can be used to enumerate and open devices. For brevity, arguments have been removed. Please see the FrontPanel API Reference for more details.
| METHOD | DESCRIPTION |
|---|---|
| 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. |
Legacy Methods
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.
| METHOD | DESCRIPTION |
|---|---|
| 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. |
Device Connection Detection
For the best user experience with USB devices, an application should automatically detect the connection and disconnection of an appropriate device. This can be done with the okCFrontPanelManager class.
For device monitoring to work, the program must be running a message loop (typical for GUI applications). If it does it already, notifications about devices connections and disconnections will be dispatched automatically under Windows and macOS platforms. For other Unix platforms, including Linux, there are two possibilities: either the caller must provide a valid callbackInfo pointer and then register the file descriptor returned via it with an existing event loop, or a null pointer may be passed in which case a separate thread will be used for monitoring the devices.
If the program does not have an existing message loop of its own, EnterMonitorLoop() can be called to run it instead. If any devices are already connected, OnDeviceAdded() is called for each of them. An exception of runtime_error class is thrown if starting monitoring failed.
For an example of this, see the Device Change sample. For a more advanced example, see the Camera Reference Design.
Device Info
Information about each FrontPanel device is stored in the okTDeviceInfo structure. This information can be useful in applications that must support multiple devices or those that depend on the use of specific features of attached devices. The okTDeviceInfo structure can be populated with information on the currently attached device using the GetDeviceInfo() and GetDeviceInfoWithSize() methods. Additional documentation on these methods can be found in the FrontPanel API class reference.
okTDeviceInfo Structure
| TYPE | NAME | DESCRIPTION | VERSION INTRODUCED |
|---|---|---|---|
| String | deviceID | The Device ID string is a user-programmable string of up to 32 characters that can be used to uniquely identify a particular XEM. The string will be truncated if it exceeds 32 characters. This string can be configured with okCFrontPanel::SetDeviceID(). | N/A |
| String | serialNumber | Serial number of the attached device (ex. “1122000ABC”). | N/A |
| String | productName | Product name string of the attached device (ex. “XEM6310-LX45”). | N/A |
| int | productID | Numerical identifier unique to each product (ex. 21 for the XEM6310-LX45″). | N/A |
| okEDeviceInterface | deviceInterface | Enumerated type used to describe the type of FrontPanel interface. Note that a USB3 device running at USB2 speeds is still using a USB3 interface. | N/A |
| okEUSBSpeed | usbSpeed | Enumerated type used to describe the USB speed of the FrontPanel interface. Note that a USB3 device running at USB2 speeds is still using a USB3 interface. | N/A |
| int | deviceMajorVersion | Device firmware major version. | N/A |
| int | deviceMinorVersion | Device firmware minor version. | N/A |
| int | hostInterfaceMajorVersion | Device host interface (HDL) major version. | N/A |
| int | hostInterfaceMinorVersion | Device host interface (HDL) minor version. | N/A |
| bool | isPLL22150Supported | true if device contains a Cypress CY22150 PLL. | N/A |
| bool | isPLL22393Supported | true if device contains a Cypress CY22393 PLL. | N/A |
| bool | isFrontPanelEnabled | true if device indicates FrontPanel support in FPGA. | N/A |
| int | wireWidth | Wire width in bits. | N/A |
| int | triggerWidth | Trigger width in bits. | N/A |
| int | pipeWidth | Pipe width in bits. | N/A |
| int | registerAddressWidth | RegisterBridge address width in bits (0 if unsupported, as in USB2 devices) | N/A |
| int | registerDataWidth | RegisterBridge data width in bits (0 if unsupported, as in USB2 devices) | N/A |
| okTFlashLayout | flashSystem | System Flash layout. | N/A |
| okTFlashLayout | flashFPGA | FPGA Flash layout | N/A |
| bool | hasFMCEEPROM | True if the device can have an attached FMC EEPROM | N/A |
| bool | hasResetProfiles | True if the device supports reset profiles. | N/A |
| okEFPGAVendor | fpgaVendor | Vendor of the FPGA | 5.2.0 |
| int | interfaceCount | Total number of FrontPanel interfaces present on the device for devices with multiple USB interfaces available. | 5.2.0 |
| int | interfaceIndex | Index of the FrontPanel interface associated with this Device Info | 5.2.0 |
oKEDeviceInterface values:
- OK_INTERFACE_UNKNOWN = 0
- OK_INTERFACE_USB2 = 1
- OK_INTERFACE_PCIE = 2
- OK_INTERFACE_USB3 = 3
okEUSBSpeed values:
- OK_USBSPEED_UNKNOWN = 0
- OK_USBSPEED_FULL = 1
- OK_USBSPEED_HIGH = 2
- OK_USBSPEED_SUPER = 3
okEFPGAVendor values:
- okFPGAVENDOR_UNKNOWN = 0
- okFPGAVENDOR_XILINX = 1
- okFPGAVENDOR_INTEL = 2
okTFlashLayout Structure
| TYPE | NAME | DESCRIPTION |
|---|---|---|
| int | sectorCount | Number of sectors in the flash device. |
| int | sectorSize | Sector size (in bytes). |
| int | pageSize | Page size (in bytes). |
| int | minUserSector | First available user sector. |
| int | maxUserSector | Last available user sector. |
User sectors are continuous from minUserSector to maxUserSector. All other sectors are reserved for system use and unavailable.
When manually loading functions from the FrontPanel shared library, okFrontPanel_GetDeviceInfoWithSize() should be used instead of okFrontPanel_GetDeviceInfo() which exists only for compatibility and doesn’t provide access to okTDeviceInfo fields added in FrontPanel v5.2 or later.