FrontPanel API  5.1.0
Public Member Functions | Static Public Member Functions | List of all members
okCFrontPanel Class Reference

This class encapsulates the functionality of an Opal Kelly FrontPanel-enabled device including FPGA configuration, PLL configuration, and FrontPanel endpoint access. More...

Inherits okCFrontPanelTypes.

Public Member Functions

 okCFrontPanel ()
 Default constructor.
 
 ~okCFrontPanel ()
 Default destructor.
 
const char * GetLastErrorMessage () const
 
ErrorCode ActivateTriggerIn (int epAddr, int bit)
 Activates a given trigger. More...
 
void Close ()
 Close the device. More...
 
ErrorCode ConfigureFPGA (const std::string strFilename, void(*callback)(int, int, void *)=NULL, void *arg=NULL)
 Download an FPGA configuration from a file. More...
 
ErrorCode ConfigureFPGAWithReset (const std::string strFilename, const okTFPGAResetProfile *reset, void(*callback)(int, int, void *)=NULL, void *arg=NULL)
 Download an FPGA configuration from a file and reset. More...
 
ErrorCode ConfigureFPGAFromMemory (const unsigned char *data, unsigned long length, void(*callback)(int, int, void *)=NULL, void *arg=NULL)
 Download an FPGA configuration from memory. More...
 
ErrorCode ConfigureFPGAFromMemoryWithReset (const unsigned char *data, unsigned long length, const okTFPGAResetProfile *reset, void(*callback)(int, int, void *)=NULL, void *arg=NULL)
 Download an FPGA configuration from memory. More...
 
ErrorCode ConfigureFPGAFromFlash (const unsigned long configIndex, void(*callback)(int, int, void *), void *arg)
 Download an FPGA configuration from on-board flash. More...
 
void EnableAsynchronousTransfers (bool enable)
 Enables (or disables) asynchronous bulk transfer queueing. More...
 
BoardModel GetBoardModel ()
 Returns the open board model enumerated type. More...
 
int GetDeviceCount ()
 Returns the number of attached Opal Kelly devices. More...
 
std::string GetDeviceID ()
 Retrieve the device ID string stored in EEPROM. More...
 
ErrorCode GetDeviceInfo (okTDeviceInfo *info)
 Fills a device information structure. More...
 
ErrorCode GetFPGAResetProfile (okEFPGAConfigurationMethod method, okTFPGAResetProfile *profile)
 Retrieve the current FPGA configuration reset profile for the given method. More...
 
BoardModel GetDeviceListModel (int num)
 Returns the board model of a device in the devices list. More...
 
std::string GetDeviceListSerial (int num)
 Returns the serial number of a device in the devices list. More...
 
int GetDeviceMajorVersion ()
 Retrieves the device firmware major version. More...
 
int GetDeviceMinorVersion ()
 Retrieves the device firmware minor version. More...
 
ErrorCode GetDeviceSensors (okCDeviceSensors &sensors) const
 Fill the array with the available sensors. More...
 
ErrorCode GetDeviceSettings (okCDeviceSettings &settings)
 Initialize the object allowing to access the device settings. More...
 
ErrorCode GetEepromPLL22150Configuration (okCPLL22150 &pll)
 Read PLL configuration from the on-board EEPROM (PLL22150). More...
 
ErrorCode GetEepromPLL22393Configuration (okCPLL22393 &pll)
 Read PLL configuration from the on-board EEPROM (PLL22393). More...
 
int GetHostInterfaceWidth ()
 Returns the width of the host interface, in bits. More...
 
long GetLastTransferLength ()
 Returns the length of the last transfer (successful or not).
 
ErrorCode GetPLL22150Configuration (okCPLL22150 &pll)
 Read the PLL configuration via the I2C bus (PLL22150). More...
 
ErrorCode GetPLL22393Configuration (okCPLL22393 &pll)
 Read the PLL configuration via the I2C bus (PLL22393). More...
 
std::string GetSerialNumber ()
 Retrieve the iSerialNumber of the device. More...
 
ErrorCode GetWireInValue (int epAddr, UINT32 *val)
 Gets the value of a particular Wire In from the internal wire data structure. More...
 
UINT32 GetWireOutValue (int epAddr)
 Gets the value of a particular Wire Out from the internal wire data structure. More...
 
bool IsHighSpeed ()
 Returns true if the device is High-Speed. More...
 
bool IsFrontPanel3Supported ()
 Returns true if FrontPanel-3 is firmware-supported. More...
 
bool IsFrontPanelEnabled ()
 Reads a byte from the host interface to see if FrontPanel support is built in. More...
 
bool IsOpen () const
 Returns true if a device is currently open. More...
 
bool IsRemote () const
 Returns true if the device is connected to a remote server. More...
 
bool IsTriggered (int epAddr, UINT32 mask)
 Returns true if the trigger has been triggered. More...
 
UINT32 GetTriggerOutVector (int epAddr) const
 Returns the value of the given trigger. More...
 
ErrorCode LoadDefaultPLLConfiguration ()
 Configures the PLL from settings stored in EEPROM. More...
 
ErrorCode OpenBySerial (std::string str="")
 Opens the specified device by serial number. More...
 
ErrorCode ReadI2C (const int addr, int length, unsigned char *data)
 Reads I2C data from an arbitrary I2C device. More...
 
long ReadFromBlockPipeOut (int epAddr, int blockSize, long length, unsigned char *data)
 Reads data from a BlockPipeOut endpoint. More...
 
long ReadFromPipeOut (int epAddr, long length, unsigned char *data)
 Reads a block from a Pipe Out endpoint. More...
 
ErrorCode ReadRegister (UINT32 addr, UINT32 *data)
 Reads a single register. More...
 
ErrorCode ReadRegisters (okTRegisterEntries &regs)
 Reads a set of registers. More...
 
ErrorCode ResetFPGA ()
 Send RESET signal to FPGA design (via okHostInterface). More...
 
ErrorCode SetBTPipePollingInterval (int interval)
 Set the BTPipe polling interval for completion. More...
 
ErrorCode SetFPGAResetProfile (okEFPGAConfigurationMethod method, const okTFPGAResetProfile *profile)
 Set the current FPGA configuration reset profile for the given method. More...
 
void SetDeviceID (const std::string str)
 Set the device ID in EEPROM. More...
 
ErrorCode SetPLL22150Configuration (okCPLL22150 &pll)
 Store the PLL configuration via the I2C bus (PLL22150). More...
 
ErrorCode SetPLL22393Configuration (okCPLL22393 &pll)
 Store the PLL configuration via the I2C bus (PLL22393). More...
 
ErrorCode SetEepromPLL22150Configuration (okCPLL22150 &pll)
 Store PLL configuration on the on-board EEPROM (PLL22150). More...
 
ErrorCode SetEepromPLL22393Configuration (okCPLL22393 &pll)
 Store PLL configuration on the on-board EEPROM (PLL22393). More...
 
void SetTimeout (int timeout)
 Set the USB timeout duration (in milliseconds). More...
 
ErrorCode SetWireInValue (int ep, UINT32 val, UINT32 mask=0xffffffff)
 Sets a wire value in the internal wire data structure. More...
 
ErrorCode UpdateTriggerOuts ()
 Reads Trigger Out endpoints. More...
 
ErrorCode UpdateWireIns ()
 Transfers current Wire In values to the FPGA. More...
 
ErrorCode UpdateWireOuts ()
 Transfers current Wire Out values from the FPGA. More...
 
ErrorCode FlashEraseSector (UINT32 address)
 Erases the sector at the specified address of System Flash memory. More...
 
ErrorCode FlashWrite (UINT32 address, UINT32 length, const UINT8 *buf)
 Writes data to System Flash starting at the specified address. More...
 
ErrorCode FlashRead (UINT32 address, UINT32 length, UINT8 *buf)
 Reads data from System Flash starting at the specified address. More...
 
ErrorCode WriteI2C (const int addr, int length, const unsigned char *data)
 Sends I2C data to an arbitrary I2C device. More...
 
ErrorCode WriteRegister (UINT32 addr, UINT32 data)
 Writes a single register. More...
 
ErrorCode WriteRegisters (const okTRegisterEntries &regs)
 Writes a set of registers. More...
 
long WriteToBlockPipeIn (int epAddr, int blockSize, long length, const unsigned char *data)
 Writes data to a BlockPipeIn endpoint. More...
 
long WriteToPipeIn (int epAddr, long length, const unsigned char *data)
 Writes a block to a Pipe In endpoint. More...
 

Static Public Member Functions

static ErrorCode AddCustomDevice (const okTDeviceMatchInfo &matchInfo, const okTDeviceInfo *devInfo=NULL)
 
static ErrorCode RemoveCustomDevice (int productID)
 
static BoardModel FindUSBDeviceModel (unsigned usbVID, unsigned usbPID)
 
static std::string GetBoardModelString (BoardModel m)
 Returns string describing the given board model or "Unknown" if not found.
 

Detailed Description

This is the class that encapsulates the functionality of the FPGA boards as well as the FrontPanel extensions such as wire and trigger endpoints.

Member Function Documentation

◆ ActivateTriggerIn()

okCFrontPanel::ErrorCode okCFrontPanel::ActivateTriggerIn ( int  epAddr,
int  bit 
)
Parameters
[in]epAddrThe address of the TriggerIn to activate.
[in]bitThe specific bit of the trigger to activate.
Returns
NoError - Operation completed successfully.
InvalidEndpoint - Endpoint address outside the range for a TriggerIn.

This method activates the specified TriggerIn on the XEM.

See also
UpdateTriggerOuts
IsTriggered

◆ AddCustomDevice()

okCFrontPanel::ErrorCode okCFrontPanel::AddCustomDevice ( const okTDeviceMatchInfo &  matchInfo,
const okTDeviceInfo devInfo = NULL 
)
static

Adds a custom device description.

This method can used to indicate that a custom device with the IDs specified in matchInfo should be recognized as a FrontPanel device. Opening the device with these identifiers will succeed after a call to this function.

Please use OK_PRODUCT_OEM_START as offset for the product ID field, all product ID values below it are reserved for internal use.

Notice that it can be called more than once for the devices with different IDs but it is not needed to ever call it again for the same device. Typically, you would call it on the program startup before creating any okCFrontPanel objects.

The devInfo parameter is optional. If specified, some of its fields will override the values that would normally be returned from GetDeviceInfo().

◆ Close()

void okCFrontPanel::Close ( )

This method can be used to close the device to release the corresponding device at the system level, e.g. to allow another process to use it, without destroying this object itself but keeping it to be reopened later.

◆ ConfigureFPGA()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGA ( const std::string  strFilename,
void(*)(int, int, void *)  callback = NULL,
void *  arg = NULL 
)
Parameters
[in]strFilenameA string containing the filename of the configuration file.
[in]callbackAn optional progress callback function.
[in]argAn optional argument to the callback function.
Returns
NoError - Configuration completed successfully.
DeviceNotOpen - Communication with a device is not established.
FileError - File error occurred during open or read.
InvalidBitstream - The bitstream is not properly formatted.
DoneNotHigh - FPGA DONE signal did not assert after configuration.
TransferError - USB error has occurred during download.
CommunicationError - Communication error with the firmware.
UnsupportedFeature - Configuration call not supported on this device or in this configuration.

This method downloads a configuration file to the FPGA. The filename should be that of a valid Xilinx bitfile (generated from bitgen). The callback is optional and used to track progress. The prototype for a valid callback would look like:

void downloadCallback(int length, int count, void *arg);
See also
ConfigureFPGAFromMemory
ConfigureFPGAFromMemoryWithReset (USB 3.0 only)
ConfigureFPGAWithReset (USB 3.0 only)

References ConfigureFPGAFromMemory().

◆ ConfigureFPGAFromFlash()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGAFromFlash ( const unsigned long  configIndex,
void(*)(int, int, void *)  callback,
void *  arg 
)
Parameters
[in]configIndexStorage index to the FPGA configuration to load.
[in]callbackAn optional progress callback function.
[in]argAn optional argument to the callback function.
Returns
ErrorCode - See ConfigureFPGA for details.

This method downloads a configuration file to the FPGA that has been and stored in on-board Flash memory.

Device Support: This method is only available for USB 3.0 devices.

See also
ConfigureFPGA
ConfigureFPGAFromMemory
ConfigureFPGAFromMemoryWithReset (USB 3.0 only)
ConfigureFPGAWithReset (USB 3.0 only)

◆ ConfigureFPGAFromMemory()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGAFromMemory ( const unsigned char *  data,
unsigned long  length,
void(*)(int, int, void *)  callback = NULL,
void *  arg = NULL 
)
Parameters
[in]dataPointer to a memory buffer containing the configuration.
[in]lengthLength of the configuration memory.
[in]callbackAn optional progress callback function.
[in]argAn optional argument to the callback function.
Returns
ErrorCode - See ConfigureFPGA for details.

This method downloads a configuration file to the FPGA that has been read and stored in memory. The data buffer must contain a loaded Xilinx bitfile (generated from bitgen).

See also
ConfigureFPGA
ConfigureFPGAFromMemoryWithReset (USB 3.0 only)
ConfigureFPGAWithReset (USB 3.0 only)

Referenced by ConfigureFPGA().

◆ ConfigureFPGAFromMemoryWithReset()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGAFromMemoryWithReset ( const unsigned char *  data,
unsigned long  length,
const okTFPGAResetProfile reset,
void(*)(int, int, void *)  callback = NULL,
void *  arg = NULL 
)
Parameters
[in]dataPointer to a memory buffer containing the configuration.
[in]lengthLength of the configuration memory.
[in]resetPointer to an FPGA Reset Profile to perform after configuration.
[in]callbackAn optional progress callback function.
[in]argAn optional argument to the callback function.
Returns
ErrorCode - See ConfigureFPGA for details.

This method downloads a configuration file to the FPGA that has been read and stored in memory. The data buffer must contain a loaded Xilinx bitfile (generated from bitgen). After successful configuration, the FPGA is reset according to the provided reset profile.

Device Support: This method is only available for USB 3.0 devices.

See also
ConfigureFPGA
ConfigureFPGAFromMemory
ConfigureFPGAWithReset (USB 3.0 only)

◆ ConfigureFPGAWithReset()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGAWithReset ( const std::string  strFilename,
const okTFPGAResetProfile reset,
void(*)(int, int, void *)  callback = NULL,
void *  arg = NULL 
)
Parameters
[in]strFilenameA string containing the filename of the configuration file.
[in]callbackAn optional progress callback function.
[in]resetFPGA Reset profile to perform after configuration.
[in]argAn optional argument to the callback function.
Returns
NoError - Configuration completed successfully.
DeviceNotOpen - Communication with a device is not established.
FileError - File error occurred during open or read.
InvalidBitstream - The bitstream is not properly formatted.
DoneNotHigh - FPGA DONE signal did not assert after configuration.
TransferError - USB error has occurred during download.
CommunicationError - Communication error with the firmware.

This method downloads a configuration file to the FPGA and performs the specified Reset Profile after configuration. The filename should be that of a valid Xilinx bitfile (generated from bitgen). The callback is optional and used to track progress. The prototype for a valid callback would look like:

void downloadCallback(int length, int count, void *arg);

After successful configuration, the FPGA is reset according to the provided Reset Profile, an example of which is below:

okTFPGAResetProfile resetProfile;
resetProfile.u32DoneWaitUS = 1000;
resetProfile.u32ResetWaitUS = 10000;
resetProfile.u32RegisterWaitUS = 10000;
resetProfile.u32WireInValues[0] = 0xFEEDA55A;
resetProfile.u32WireInValues[1] = 0x12345678;
resetProfile.u32NumTriggerEntries = 2;
resetProfile.u32NumRegisterEntries = 1;
resetProfile.trigEntries[0].u32Trigger = 0x40;
resetProfile.trigEntries[0].u32Mask = 0x00000002;
resetProfile.trigEntries[1].u32Trigger = 0x40;
resetProfile.trigEntries[1].u32Mask = 0x00000002;
resetProfile.regEntries[0].u32Address = 0x0;
resetProfile.regEntries[0].u32Data = 0xBEEFF00D;
xem->ConfigureFPGAWithReset("counters.bit", &resetProfile);

Device Support: This method is only available for USB 3.0 devices.

See also
ConfigureFPGA
ConfigureFPGAFromMemory
ConfigureFPGAFromMemoryWithReset (USB 3.0 only)

◆ EnableAsynchronousTransfers()

void okCFrontPanel::EnableAsynchronousTransfers ( bool  enable)
Parameters
[in]enabletrue to enable async transfers, false to disable them.

Asynchronous queueing of bulk transfer requests is a technique used to increase the throughput of the USB stack. This technique is known to cause problems on some operating systems (notably Windows 2000 with certain USB drivers).

If you experience problems with configuration and/or pipe transfers, try disabling async transfers. There will be a performance penalty.

◆ FindUSBDeviceModel()

okCFrontPanel::BoardModel okCFrontPanel::FindUSBDeviceModel ( unsigned  usbVID,
unsigned  usbPID 
)
static

Find the board model corresponding to the USB device with the given IDs.

Find the board model of a FrontPanel device with the given IDs or returns brdUnknown if there is no such device.

◆ FlashEraseSector()

okCFrontPanel::ErrorCode okCFrontPanel::FlashEraseSector ( UINT32  address)
Parameters
[in]addressAddress within the sector to erase.
Returns
NoError - The operation was successful.
Failed - The operation could not be completed.
DeviceNotOpen - A device is not open.
UnsupportedFeature - Method not supported on this device or configuration.
InvalidParameter - Address specified is invalid for erase operation.
Timeout - The operation did not complete in the expected time.

Erases a single sector in System Flash memory. The sector to erase is determined based on the provided address. Any address within the sector will specify that the entire sector be erased. The sector specified must be in the acceptable range for the user area of Flash memory for the device. See the device User's Manual for Flash memory layout details.

The method blocks and returns when the operation completes. Sector erase times vary, but are approximately one second per sector.

Refer to the device-specific User's Manual for Flash layout and restrictions.

Note
This method is only supported for USB 3.0 devices.
See also
FlashWrite
FlashRead

◆ FlashRead()

okCFrontPanel::ErrorCode okCFrontPanel::FlashRead ( UINT32  address,
UINT32  length,
UINT8 *  buf 
)
Parameters
[in]addressByte address to begin read operation.
[in]lengthLength of data to read (in bytes).
[in]bufPointer to data buffer.
Returns
NoError - The operation was successful.
Failed - The operation could not be completed.
DeviceNotOpen - A device is not open.
UnsupportedFeature - Method not supported on this device or configuration.
InvalidParameter - Address or length specified is invalid.
Timeout - The operation did not complete in the expected time.

Reads data from System Flash memory starting at the specified address. The address and length must both be integer multiples of the System Flash page size.

Refer to the device-specific User's Manual for Flash layout and restrictions.

Note
This method is only supported for USB 3.0 devices.
See also
FlashEraseSector
FlashWrite

◆ FlashWrite()

okCFrontPanel::ErrorCode okCFrontPanel::FlashWrite ( UINT32  address,
UINT32  length,
const UINT8 *  buf 
)
Parameters
[in]addressByte address to begin write operation.
[in]lengthLength of data to write (in bytes).
[in]bufPointer to data to write.
Returns
NoError - The operation was successful.
Failed - The operation could not be completed.
DeviceNotOpen - A device is not open.
UnsupportedFeature - Method not supported on this device or configuration.
InvalidParameter - Address or length specified is invalid.
Timeout - The operation did not complete in the expected time.

Writes data to System Flash memory starting at the specified address. The address and length must both be integer multiples of the System Flash page size. This method will not erase the sector prior to writing. You must use FlashEraseSector to erase a sector prior to writing.

Refer to the device-specific User's Manual for Flash layout and restrictions.

Note
This method is only supported for USB 3.0 devices.
See also
FlashEraseSector
FlashRead

◆ GetBoardModel()

okCFrontPanel::BoardModel okCFrontPanel::GetBoardModel ( )
Returns
The board model of the currently-open device. If the device is unknown, brdUnkown is returned.
Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

References okTDeviceInfo::productID.

◆ GetDeviceCount()

int okCFrontPanel::GetDeviceCount ( )
Deprecated:
Prefer to use OpalKelly::FrontPanelDevices::GetCount() in the new code, see Switching to OpalKelly::FrontPanelDevices for more information.
Returns
The number of devices attached.

Queries to determine how many Opal Kelly devices are attached. This method also builds a list of serial numbers and board models which can subsequently be queried using the methods GetDeviceListSerial() and GetDeviceListModel(), respectively.

◆ GetDeviceID()

std::string okCFrontPanel::GetDeviceID ( )
Returns
A string containing the Device ID. If a device is not open, the string will be empty.

This method retrieves the current XEM Device ID string from the device.

Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

References okTDeviceInfo::deviceID.

◆ GetDeviceInfo()

okCFrontPanel::ErrorCode okCFrontPanel::GetDeviceInfo ( okTDeviceInfo info)
Parameters
[in]infoPointer to an allocated okDeviceInfo structure.
Returns
NoError - Operation completed successfully.
DeviceNotOpen - Device is not open.
InvalidParameter - The provided okTDeviceInfo pointer is null or points to an incorrectly sized structure. The latter can mostly happen only when the application uses a version of the shared library incompatible with the one it was compiled with.

Fills the okTDeviceInfo structure with information about the device.

◆ GetDeviceListModel()

okCFrontPanel::BoardModel okCFrontPanel::GetDeviceListModel ( int  num)
Deprecated:
Prefer to use OpalKelly::FrontPanelDevices::Open() and GetBoardModel() in the new code, see Switching to OpalKelly::FrontPanelDevices for more information.
Parameters
[in]numDevice number to query (0 to count-1)
Returns
The board model (enumerated type) of the specified device.

This method returns the board model of a particular attached device. The device count must have already been queried using a call to GetDeviceCount(). If a board is unknown or num is outside the range of attached devices, okCUsbFrontPanel::brdUnknown will be returned.

◆ GetDeviceListSerial()

std::string okCFrontPanel::GetDeviceListSerial ( int  num)
Deprecated:
Prefer to use OpalKelly::FrontPanelDevices::GetSerial() in the new code, see Switching to OpalKelly::FrontPanelDevices for more information.
Parameters
[in]numDevice number to query (0 to count-1)
Returns
The serial number string of the specified device.

This method returns the serial number of a particular attached device. The device count must have already been queried using a call to GetDeviceCount(). If num is outside the range of attached devices, an empty string will be returned. The serial number may then be used to open the device by calling OpenBySerial().

◆ GetDeviceMajorVersion()

int okCFrontPanel::GetDeviceMajorVersion ( )
Returns
The firmware's major version number or -1 if the query failed.
Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

References okTDeviceInfo::deviceMajorVersion.

◆ GetDeviceMinorVersion()

int okCFrontPanel::GetDeviceMinorVersion ( )
Returns
The firmware's minor version number or -1 if the query failed.
Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

References okTDeviceInfo::deviceMinorVersion.

◆ GetDeviceSensors()

okCFrontPanel::ErrorCode okCFrontPanel::GetDeviceSensors ( okCDeviceSensors sensors) const
Parameters
[out]sensorsAn instance of okCDeviceSensors that will be modified with the sensor information.
Returns
NoError - Write has completed successfully.
Failed - Retrieving sensors from the device failed.
DeviceNotOpen - Communication with a XEM is not established.
UnsupportedFeature - Unless the device supports Device Sensors.

Device Support: This method is only available for USB 3.0 devices.

Example:

int count;
dev.GetDeviceSensors(sensors);
count = sensors.GetSensorCount(); // Returns the number of sensors.
sensor = sensors.GetSensor(0); // Returns the first sensor in the list.

◆ GetDeviceSettings()

okCFrontPanel::ErrorCode okCFrontPanel::GetDeviceSettings ( okCDeviceSettings settings)
Parameters
[out]settingsAn instance of okCDeviceSettings that will operate on device settings.
Returns
NoError - Completed successfully.
DeviceNotOpen - Communication with a device is not established.
UnsupportedFeature - Unless the device supports Device Settings.

Device Support: This method is only available for USB 3.0 devices.

See also
okCDeviceSettings

◆ GetEepromPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::GetEepromPLL22150Configuration ( okCPLL22150 pll)
Parameters
[out]pllA reference to an okCPLL22150 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

This method retrieves the current PLL configuration from the on-board XEM EEPROM. The pll object is then initialized with this configuration.

See also
GetPLL22150Configuration
LoadDefaultPLLConfiguration
SetPLL22150Configuration
SetEepromPLL22150Configuration

◆ GetEepromPLL22393Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::GetEepromPLL22393Configuration ( okCPLL22393 pll)
Parameters
[out]pllA reference to an okCPLL22393 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

This method retrieves the current PLL configuration from the on-board XEM EEPROM. The pll object is then initialized with this configuration.

See also
GetPLL22393Configuration
LoadDefaultPLLConfiguration
SetPLL22393Configuration
SetEepromPLL22393Configuration

◆ GetFPGAResetProfile()

okCFrontPanel::ErrorCode okCFrontPanel::GetFPGAResetProfile ( okEFPGAConfigurationMethod  method,
okTFPGAResetProfile profile 
)
Parameters
[in]methodIndicates which reset profile should be retrieved.
[out]profileBoot FPGA Reset Profile
Returns
NoError - Write has completed successfully.
DeviceNotOpen - Communication with a device is not established.
UnsupportedFeature - Method not supported for this device.
InvalidParameter - Invalid configuration method or NULL profile pointer.
Failed - Request failed.

This method queries the firmware for the current FPGA Boot or JTAG Reset Profile. The result is returned in the Reset Profile pointed to by profile.

Note: This method is only available in the C/C++ DLL.

See also
SetFPGAResetProfile

◆ GetHostInterfaceWidth()

int okCFrontPanel::GetHostInterfaceWidth ( )
Returns
The width of the host interface, in bits. 0 if no device is open.

The host interface width is device dependent. All USB 2.0 devices have a 16-bit host interface except for the XEM3001v1 (very early release) which has an 8-bit interface. All PCI Express devices have a 32-bit host interface. All USB 3.0 devices have a 32-bit host interface.

Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

◆ GetLastErrorMessage()

const char * okCFrontPanel::GetLastErrorMessage ( ) const

Get the message corresponding to the last error, if any.

This method can be used after any of the other methods of this class returning ErrorCode returns an error code different from NoError to check if there is an associated error message further explaining the problem.

Note that the returned pointer only remains valid until the next call to a method of this object or its destruction, so it should be either used immediately or a copy of the string needs to be made by caller.

Returns NULL if there is no error message (which doesn't mean that the error hadn't occurred, but just that there is no additional information about it).

◆ GetPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::GetPLL22150Configuration ( okCPLL22150 pll)
Parameters
[in]pllA reference to an okCPLL22150 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

Reads the current PLL configuration over the I2C bus and modifies the pll argument to reflect that configuration.

See also
GetEepromPLL22150Configuration
LoadDefaultPLLConfiguration
SetPLL22150Configuration
SetEepromPLL22150Configuration

◆ GetPLL22393Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::GetPLL22393Configuration ( okCPLL22393 pll)
Parameters
[in]pllA reference to an okCPLL22393 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

Reads the current PLL configuration over the I2C bus and modifies the pll argument to reflect that configuration.

See also
GetEepromPLL22393Configuration
LoadDefaultPLLConfiguration
SetPLL22393Configuration
SetEepromPLL22393Configuration

◆ GetSerialNumber()

std::string okCFrontPanel::GetSerialNumber ( )
Returns
A string containing the device serial number. If no device is open, the string will be empty.

This method will retrieve the 10-character serial number stored in the EEPROM. This serial number is unique to each device and can therefore be used to discriminate multiple devices. Each character in the serial number is an upper or lower case character.

std::string strSerialNumber;
strSerialNumber = xem->GetSerialNumber();
Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

◆ GetTriggerOutVector()

UINT32 okCFrontPanel::GetTriggerOutVector ( int  epAddr) const
Parameters
[in]epAddrThe TriggerOut address to query.

This method allows to retrieve the full vector of values for a particular TriggerOut endpoint. It is usually preferable to use IsTriggered() to test for a single trigger instead.

Returns 0 in case of error, e.g. an invalid trigger endpoint.

See also
UpdateTriggerOuts

◆ GetWireInValue()

okCFrontPanel::ErrorCode okCFrontPanel::GetWireInValue ( int  epAddr,
UINT32 *  val 
)
Parameters
[in]epAddrThe address of the WireIn to query.
[in]valPointer to a UINT32 to contain the result.
Returns
NoError - Operation completed successfully.
InvalidEnpoint - Endpoint address outside the range for WireIn.
DeviceNotOpen - Device is not open.
UnsupportedFeature - Supported only for USB 3.0 devices.

Note: USB 3.0 device support only.

Gets the value of a particular WireIn from the internal wire data structure. The device firmware maintains a copy of WireIn values that are queried post-configuration and whenever a new instance of okCFrontPanel is created for a device that has an active FrontPanel-enabled configuration.

See also
GetWireOutValue
SetWireInValue
UpdateWireIns
UpdateWireOuts

◆ GetWireOutValue()

UINT32 okCFrontPanel::GetWireOutValue ( int  epAddr)
Parameters
[in]epAddrThe WireOut address to query.
Returns
The value of the WireOut.

This method provides a way to get a particular WireOut value. For example,

// First, query all XEM WireOuts.
xem->UpdateWireOuts();
// Now, get values from endpoints 0x21 and 0x27.
a = xem->GetWireOutValue(0x21);
b = xem->GetWireOutValue(0x27);
See also
GetWireInValue
SetWireInValue
UpdateWireIns
UpdateWireOuts

◆ IsFrontPanel3Supported()

bool okCFrontPanel::IsFrontPanel3Supported ( )
Returns
True if FrontPanel-3 support is provided by the device firmware.

This method checks the firmware device version to determine if FrontPanel-3 methods are supported. These are:

  • WriteToBlockPipeIn
  • ReadFromBlockPipeOut

◆ IsFrontPanelEnabled()

bool okCFrontPanel::IsFrontPanelEnabled ( )
Returns
True if FrontPanel support is present, false otherwise.

This method checks to see if the FrontPanel Host Interface has been instantiated in the FPGA design. If it is detected, FrontPanel support is enabled and endpoint functionality is available.

◆ IsHighSpeed()

bool okCFrontPanel::IsHighSpeed ( )
Returns
true if the device is operating at high-speed. false if full-speed.

Queries the device to determine which USB speed it has enumerated at. It will return true if high-speed (480Mbps), false otherwise (full-speed, 12Mbps).

Note: This method only detects the speed on FrontPanel-3 enabled devices. If the device is not running version 3 firmware, this method always returns true. This method always returns true if a device is not currently open.

Note
This method has been DEPRECATED and will be removed from a future version of the API. The preferred method is GetDeviceInfo.
See also
GetDeviceInfo

◆ IsOpen()

bool okCFrontPanel::IsOpen ( ) const
Returns
true - Device is open.
false - Device is not open.

◆ IsRemote()

bool okCFrontPanel::IsRemote ( ) const
Returns
true If the device is connected to a remote server and, hence, operations with it have much higher latency, requiring the use of server-side scripts for acceptable performance.

◆ IsTriggered()

bool okCFrontPanel::IsTriggered ( int  epAddr,
UINT32  mask 
)
Parameters
[in]epAddrThe TriggerOut address to query.
[in]maskA mask to apply to the trigger value.
Returns
true if any of the bits in the mask have triggered.

This method provides a way to find out if a particular bit (or bits) on a particular TriggerOut endpoint has triggered since the last call to UpdateTriggerOuts(). For example,

// First, query all XEM Trigger Outs.
xem->UpdateTriggerOuts();
// Now, check the trigger on bit 7 of endpoint 0x71
if (true == xem->IsTriggered(0x71, 0x80))
OnMachineDoneTrigger();
See also
ActivateTriggerIn
UpdateTriggerOuts

◆ LoadDefaultPLLConfiguration()

okCFrontPanel::ErrorCode okCFrontPanel::LoadDefaultPLLConfiguration ( )
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.
UnsupportedFeature - The device does not have a supported PLL.

Configures the on-board PLL using the default configuration setup in the EEPROM. For a device with the Cypress CY22150 PLL, this is equivalent to:

xem->GetEepromPLL22150Configuration(pll);
xem->SetPLL22150Configuration(pll);

Similar equivalence exists for devices with the CY22393 PLL.

See also
GetEepromPLL22150Configuration
GetEepromPLL22393Configuration
SetPLL22150Configuration
SetPLL22393Configuration

◆ OpenBySerial()

okCFrontPanel::ErrorCode okCFrontPanel::OpenBySerial ( std::string  str = "")
Deprecated:
Prefer to use OpalKelly::FrontPanelDevices::Open() in the new code, see Switching to OpalKelly::FrontPanelDevices for more information.
Parameters
[in]strThe serial number of the device to open.
Returns
NoError - A device has been opened successfully.
DeviceNotOpen - A device could not be opened.

Before any communication with the device can proceed, the device must be opened using this method. If the device had been already opened, it is closed automatically before opening it again.

A device is opened matching the given serial number string. If no serial number (or an empty string) is provided, then the first appropriate device is opened.

Python and Java Note: To open the first available device, you must provide an empty string.

◆ ReadFromBlockPipeOut()

long okCFrontPanel::ReadFromBlockPipeOut ( int  epAddr,
int  blockSize,
long  length,
unsigned char *  data 
)
Parameters
[in]epAddrThe address of the source Pipe Out.
[in]lengthThe length of the transfer (in bytes).
[in]blockSizeBlock size (in bytes).
[in]dataA pointer to the transfer data buffer.
Returns
The number of bytes read or ErrorCode (<0) if the read failed.
InvalidEndpoint - Invalid endpoint address specified.
InvalidBlockSize - Block size specified is invalid.
Failed - The operation failed.
Timeout - The operation timed out.
UnsupportedFeature - Length specified is invalid.

This method transfers data from a specified BlockPipeOut endpoint to the given buffer.

Block size is specified in bytes and are device-dependent:

  • USB 2.0 FullSpeed - Multiple of two [2..64]
  • USB 2.0 HighSpeed - Multiple of two [2..1024]
  • USB 3.0 FullSpeed - Power of two [16..64]
  • USB 3.0 HighSpeed - Power of two [16..1024]
  • USB 3.0 SuperSpeed - Power of two [16..16384]
  • PCIe: - Not applicable

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of the block size. The length must also be an integer multiple of a minimal transfer size according to the list below:

  • USB 2.0: Multiple of 2
  • USB 3.0: Multiple of 16
  • PCIe: Multiple of 8

Performance Note: Optimum bandwidth performance is achieved when blockSize is a power of two.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(81920)
xem.ReadFromBlockPipeOut(0xa0, 1024, buf)

◆ ReadFromPipeOut()

long okCFrontPanel::ReadFromPipeOut ( int  epAddr,
long  length,
unsigned char *  data 
)
Parameters
[in]epAddrThe address of the source Pipe Out.
[in]lengthThe length of the transfer (in bytes).
[in]dataA pointer to the transfer data buffer.
Returns
The number of bytes read or ErrorCode (<0) if the read failed.
InvalidEndpoint - Invalid endpoint address specified.
InvalidBlockSize - Block size specified is invalid.
Failed - The operation failed.
Timeout - The operation timed out.
UnsupportedFeature - Length specified is invalid.

This method transfers data from a specified Pipe Out endpoint to the given buffer.

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of a minimal transfer size according to the list below:

  • USB 2.0: Multiple of 2
  • USB 3.0: Multiple of 16
  • PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(15360)
xem.ReadFromPipeOut(0xa0, buf)

◆ ReadI2C()

okCFrontPanel::ErrorCode okCFrontPanel::ReadI2C ( const int  addr,
int  length,
unsigned char *  data 
)
Parameters
[in]addrI2C address of the target device.
[in]lengthLength of data (in bytes).
[in]dataPointer receive data buffer.
Returns
NoError - Write has completed successfully.
DeviceNotOpen - Communication with a XEM is not established.
CommunicationError - Communication error with the firmware.
I2CRestrictedAddress - Write to a restricted I2C address.
I2CBitError - I2C bit error occurred.
I2CNack - I2C device responded with NACK.
I2CUnknownStatus - Unknown result status.

This method reads a string of bytes from the target I2C address. This transfer does not utilize the FPGA and can be done prior to configuration.

Note
This method is only available for USB 2.0 devices.

◆ ReadRegister()

okCFrontPanel::ErrorCode okCFrontPanel::ReadRegister ( UINT32  addr,
UINT32 *  data 
)
Parameters
[in]addrRegister address
[out]dataPointer to register data
Returns
NoError - Operation completed successfully.
UnsupportedFeature - Device does not support the RegisterBridge endpoint.
UnsupportedFeature - FrontPanel is not enabled in the FPGA design.
DeviceNotOpen - Device is not open.

Performs a single register read operation and puts the result into data.

Python Note:In Python, the method is called as shown here:

reg.data = device.ReadRegister(reg.address)
Note
The RegisterBridge endpoint is only supported on USB 3.0 devices.
See also
ReadRegisters
WriteRegister
WriteRegisters

References ReadRegisters().

◆ ReadRegisters()

okCFrontPanel::ErrorCode okCFrontPanel::ReadRegisters ( okTRegisterEntries &  regs)
Parameters
[in,out]regsVector of registers to read.
Returns
NoError - Operation completed successfully.
UnsupportedFeature - Device does not support the RegisterBridge endpoint.
UnsupportedFeature - FrontPanel is not enabled in the FPGA design.
DeviceNotOpen - Device is not open.

Performs multiple register reads at addresses provided by the elements of regs

// Read values at register addresses 0x00001234 and 0x00005678.
okTRegisterEntries regs(2);
regs[0].address = 0x1234;
regs[1].address = 0x5678;
if (xem->ReadRegisters(regs) == okCFrontPanel::NoError) {
regs[0].data; // Value at 0x1234
regs[1].data; // Value at 0x5678
}
Note
The RegisterBridge endpoint is only supported on USB 3.0 devices.
See also
ReadRegister
WriteRegister
WriteRegisters

Referenced by ReadRegister().

◆ RemoveCustomDevice()

okCFrontPanel::ErrorCode okCFrontPanel::RemoveCustomDevice ( int  productID)
static

Remove a previously added custom device description.

This method can be used to forget about the device defined by a previous call to AddCustomDevice().

◆ ResetFPGA()

okCFrontPanel::ErrorCode okCFrontPanel::ResetFPGA ( )
Returns
True always.

Performs a RESET of the FPGA internals. This requires that FrontPanel support be present in the FPGA design because the RESET signal actually comes from the FrontPanel Host Interface.

◆ SetBTPipePollingInterval()

okCFrontPanel::ErrorCode okCFrontPanel::SetBTPipePollingInterval ( int  interval)
Parameters
[in]intervalPolling interval (in milliseconds).
Returns
NoError errorcode if the interval was accepted.

At the completion of a BTPipeIn transfer, the host polls the hardware to confirm that all of the data has been consumed by the FPGA before returning from the function. The polling interval is set by this method.

The valid range for this interval is 1 to 100 milliseconds. Values outside this range cause the errorcode Failed to be returned. The default is 25 milliseconds.

◆ SetDeviceID()

void okCFrontPanel::SetDeviceID ( const std::string  str)
Parameters
[in]strA string containing the new Device ID.

This method modifies the XEM Device ID string with the new string. 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.

◆ SetEepromPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::SetEepromPLL22150Configuration ( okCPLL22150 pll)
Parameters
[in]pllA reference to an okCPLL22150 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

This method programs the on-board XEM EEPROM with the PLL configuration in pll.

See also
GetEepromPLL22150Configuration
GetPLL22150Configuration
LoadDefaultPLLConfiguration
SetPLL22150Configuration

◆ SetEepromPLL22393Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::SetEepromPLL22393Configuration ( okCPLL22393 pll)
Parameters
[in]pllA reference to an okCPLL22393 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

This method programs the on-board XEM EEPROM with the PLL configuration in pll.

See also
GetEepromPLL22393Configuration
GetPLL22393Configuration
LoadDefaultPLLConfiguration
SetPLL22393Configuration

◆ SetFPGAResetProfile()

okCFrontPanel::ErrorCode okCFrontPanel::SetFPGAResetProfile ( okEFPGAConfigurationMethod  method,
const okTFPGAResetProfile profile 
)
Parameters
[in]methodIndicates which reset profile should be set.
[in]profileBoot FPGA Reset Profile
Returns
NoError - Write has completed successfully.
DeviceNotOpen - Communication with a device is not established.
UnsupportedFeature - Method not supported for this device.
InvalidParameter - Invalid configuration method or NULL profile pointer.
Failed - Request failed.

The Boot Reset Profile is the Reset Profile that defines how (and if) the firmware should configure the FPGA on boot and the sequence performed after configuration. If a valid Reset Profile is stored, the firmware will use that profile to boot and setup the FPGA at power-on.

The JTAG Reset Profile is the Reset Profile that defines the configuration sequence that should be followed after the FPGA is configured via JTAG. If a valid Reset Profile is stored, the firmware will method that profile to setup the FPGA if it detects completion of a JTAG-based configuration completion.

Example:

okTFPGAResetProfile resetProfile;
memset(&p, 0, sizeof(okTFPGAResetProfile));
resetProfile.u32DoneWaitUS = 1000; // Wait 1ms after DONE before Wire/Register setup
resetProfile.u32WireInValues[0] = 0x000000f0;
resetProfile.u32WireInValues[1] = 0x000000a0;
resetProfile.u32NumRegisterEntries = 1;
resetProfile.regEntries[0].u32Address = 0x1234;
resetProfile.regEntries[0].u32Data = 0xAAAAAAAA;
resetProfile.u32RegisterWaitUS = 10000; // Wait 1ms after Wire/Register setup
resetProfile.u32ResetWaitUS = 10000; // Wait 1ms after RESET deasserts
resetProfile.u32NumTriggerEntries = 2;
resetProfile.trigEntries[0].u32Trigger = 0x40;
resetProfile.trigEntries[0].u32Mask = 0x00000002;
resetProfile.trigEntries[1].u32Trigger = 0x40;
resetProfile.trigEntries[1].u32Mask = 0x00000002;
resetProfile.u32Location = 16; // Bitfile stored at first user sector
resetProfile.u32Length = 689900; // Bitfile size
dev->SetFPGAResetProfile(ok_FPGAConfigurationMethod_NVRAM, &resetProfile);

An empty Reset Profile (with u32Length=0) specifies that an FPGA configuration is not to be loaded on boot. For example:

// Set an empty Reset Profile (u32Length=0) to prevent an FPGA configuration
// from being loaded at power-up.
memset(&p, 0, sizeof(okTFPGAResetProfile));
dev->SetFPGAResetProfile(ok_FPGAConfigurationMethod_NVRAM, &p));

Note: This method is only available in the C/C++ DLL.

See also
GetFPGAResetProfile

◆ SetPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::SetPLL22150Configuration ( okCPLL22150 pll)
Parameters
[in]pllA reference to an okCPLL22150 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

Configures the on-board PLL via the I2C bus using the configuration information in the pll object.

See also
GetEepromPLL22150Configuration
GetPLL22150Configuration
LoadDefaultPLLConfiguration
SetEepromPLL22150Configuration

◆ SetPLL22393Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::SetPLL22393Configuration ( okCPLL22393 pll)
Parameters
[in]pllA reference to an okCPLL22393 object.
Returns
NoError - Operation complete successfully.
DeviceNotOpen - Device is not open.

Configures the on-board PLL via the I2C bus using the configuration information in the pll object.

See also
GetEepromPLL22393Configuration
GetPLL22393Configuration
LoadDefaultPLLConfiguration
SetEepromPLL22393Configuration

◆ SetTimeout()

void okCFrontPanel::SetTimeout ( int  timeout)
Parameters
[in]timeoutTimeout duration specified in milliseconds.

This method sets the timeout value used by USB transactions when communicating with the target device. Note that this is not necessarily the timeout for a particular API call. By default, the timeout is set to 10 seconds).

Note that a timeout is not always provided by the underlying calls nor by the operating system. Most generally, the timeout will apply to pipe transfers and FPGA configuration transfers.

◆ SetWireInValue()

okCFrontPanel::ErrorCode okCFrontPanel::SetWireInValue ( int  ep,
UINT32  val,
UINT32  mask = 0xffffffff 
)
Parameters
[in]epThe address of the WireIn endpoint to update.
[in]valThe new value of the WireIn.
[in]maskA mask to apply to the new value.
Returns
NoError - Operation completed successfully.
InvalidEnpoint - Endpoint address outside the range for WireIn.
DeviceNotOpen - Device is not open.

WireIn endpoint values are stored internally and updated when necessary by calling UpdateWireIns(). The values are updated on a per-endpoint basis by calling this method. In addition, specific bits may be updated independent of other bits within an endpoint by using the optional mask.

// Update Wire In 0x03 with the value 0x35.
xem->SetWireInValue(0x03, 0x35);
// Update only bit 3 of Wire In 0x07 with a 1.
xem->SetWireInValue(0x07, 0x04, 0x04);
// Commit the updates to the XEM.
xem->UpdateWireIns();
See also
GetWireInValue
GetWireOutValue
UpdateWireIns
UpdateWireOuts

◆ UpdateTriggerOuts()

okCFrontPanel::ErrorCode okCFrontPanel::UpdateTriggerOuts ( )

This method is called to query the XEM to determine if any TriggerOuts have been activated since the last call.

See also
ActivateTriggerIn
IsTriggered

◆ UpdateWireIns()

okCFrontPanel::ErrorCode okCFrontPanel::UpdateWireIns ( )

This method is called after all WireIn values have been updated using SetWireInValue(). The latter call merely updates the values held within a data structure inside the class. This method actually commits the changes to the XEM simultaneously so that all wires will be updated at the same time.

See also
GetWireOutValue
GetWireInValue
SetWireInValue
UpdateWireOuts

◆ UpdateWireOuts()

okCFrontPanel::ErrorCode okCFrontPanel::UpdateWireOuts ( )

This method is called to request the current state of all WireOut values from the XEM. All wire outs are captured and read at the same time.

See also
GetWireOutValue
GetWireInValue
SetWireInValue
UpdateWireIns

◆ WriteI2C()

okCFrontPanel::ErrorCode okCFrontPanel::WriteI2C ( const int  addr,
int  length,
const unsigned char *  data 
)
Parameters
[in]addrI2C address of the target device.
[in]lengthLength of data (in bytes).
[in]dataPointer to data to be written.
Returns
NoError - Write has completed successfully.
DeviceNotOpen - Communication with a XEM is not established.
CommunicationError - Communication error with the firmware.
I2CRestrictedAddress - Write to a restricted I2C address.
I2CBitError - I2C bit error occurred.
I2CNack - I2C device responded with NACK.
I2CUnknownStatus - Unknown result status.

This method writes a string of bytes to the target I2C address. This transfer does not utilize the FPGA and can be done prior to configuration.

Note
This method is only available for USB 2.0 devices.

◆ WriteRegister()

okCFrontPanel::ErrorCode okCFrontPanel::WriteRegister ( UINT32  addr,
UINT32  data 
)
Parameters
[in]addrRegister address
[in]dataPointer to register data
Returns
NoError - Operation completed successfully.
UnsupportedFeature - Device does not support the RegisterBridge endpoint.
UnsupportedFeature - FrontPanel is not enabled in the FPGA design.
DeviceNotOpen - Device is not open.

Performs a single register write operation.

Note
The RegisterBridge endpoint is only supported on USB 3.0 devices.
See also
ReadRegister
ReadRegisters
WriteRegisters

References WriteRegisters().

◆ WriteRegisters()

okCFrontPanel::ErrorCode okCFrontPanel::WriteRegisters ( const okTRegisterEntries &  regs)
Parameters
[in,out]regsVector of registers to write.
Returns
NoError - Operation completed successfully.
UnsupportedFeature - Device does not support the RegisterBridge endpoint.
UnsupportedFeature - FrontPanel is not enabled in the FPGA design.
DeviceNotOpen - Device is not open.

Writes values of multiple registers at once.

// Write values to register addresses 0x00001234 and 0x00005678.
okTRegisterEntries regs(2);
regs[0].address = 0x1234;
regs[0].data = 0xABCD; // Value to write to 0x1234
regs[1].address = 0x5678;
regs[1].data = 0xF00D; // Value to write to 0x5678
xem->WriteRegisters(regs);
Note
The RegisterBridge endpoint is only supported on USB 3.0 devices.
See also
ReadRegister
ReadRegisters
WriteRegister

Referenced by WriteRegister().

◆ WriteToBlockPipeIn()

long okCFrontPanel::WriteToBlockPipeIn ( int  epAddr,
int  blockSize,
long  length,
const unsigned char *  data 
)
Parameters
[in]epAddrThe address of the destination Pipe In.
[in]lengthThe length of the transfer (in bytes).
[in]blockSizeBlock size (in bytes).
[in]dataA pointer to the transfer data buffer.
Returns
The number of bytes written or ErrorCode (<0) if the write failed.
InvalidEndpoint - Invalid endpoint address specified.
InvalidBlockSize - Block size specified is invalid.
Failed - The operation failed.
Timeout - The operation timed out.
UnsupportedFeature - Length specified is invalid.

This method transfers a specified buffer of data to the given BlockPipeIn endpoint. If the transfer fails, an ErrorCode is returned. A return value less than 0 indicates an error situation.

Block size is specified in bytes and are device-dependent:

  • USB 2.0 FullSpeed - Multiple of two [2..64]
  • USB 2.0 HighSpeed - Multiple of two [2..1024]
  • USB 3.0 FullSpeed - Power of two [16..64]
  • USB 3.0 HighSpeed - Power of two [16..1024]
  • USB 3.0 SuperSpeed - Power of two [16..16384]
  • PCIe: - Not applicable

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of the block size. The length must also be an integer multiple of a minimal transfer size according to the list below:

  • USB 2.0: Multiple of 2
  • USB 3.0: Multiple of 16
  • PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is of the mutable type bytearray. For example,

buf = bytearray(4096)
xem.WriteToBlockPipeIn(0x80, 512, buf)

◆ WriteToPipeIn()

long okCFrontPanel::WriteToPipeIn ( int  epAddr,
long  length,
const unsigned char *  data 
)
Parameters
[in]epAddrThe address of the destination Pipe In.
[in]lengthThe length of the transfer (in bytes).
[in]dataA pointer to the transfer data buffer.
Returns
The number of bytes written or ErrorCode (<0) if the write failed.
InvalidEndpoint - Invalid endpoint address specified.
InvalidBlockSize - Block size specified is invalid.
Failed - The operation failed.
Timeout - The operation timed out.
UnsupportedFeature - Length specified is invalid.

This method transfers a specified buffer of data to the given Pipe In endpoint. If the transfer fails, an ErrorCode is returned. A return value less than 0 indicates an error situation.

Length is specified in bytes. Firmware restrictions put a limitation on the maximum length per transfer. However, this API will automatically perform multiple transfers, if required, to complete the full length. Length must be an integer multiple of a minimal transfer size according to the list below:

  • USB 2.0: Multiple of 2
  • USB 3.0: Multiple of 16
  • PCIe: Multiple of 8

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is mutable type bytearray. For example,

buf = bytearray(81920)
xem.WriteToPipeIn(0x80, buf)

Copyright (c) 2005-2019 Opal Kelly Incorporated