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

Public Member Functions
	okCFrontPanel ()
	Default constructor.

	~okCFrontPanel ()
	Default destructor.

ErrorCode	GetLastError () const

const char *	GetLastErrorMessage () const

ErrorCode	ActivateTriggerIn (int epAddr, int bit)
	Activates a given trigger.

void	Close ()
	Close the device.

ErrorCode	ClearFPGAConfiguration ()
	Clear the current FPGA configuration.

ErrorCode	ConfigureFPGA (const std::string strFilename, void(callback)(int, int, void )=NULL, void *arg=NULL)
	Download an FPGA configuration from a file.

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.

ErrorCode	ConfigureFPGAFromMemory (const unsigned char data, unsigned long length, void(callback)(int, int, void )=NULL, void arg=NULL)
	Download an FPGA configuration from memory.

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.

ErrorCode	ConfigureFPGAFromFlash (const unsigned long configIndex, void(callback)(int, int, void ), void *arg)
	Download an FPGA configuration from on-board flash.

void	EnableAsynchronousTransfers (bool enable)
	Enables (or disables) asynchronous bulk transfer queueing.

BoardModel	GetBoardModel ()
	Returns the open board model enumerated type.

int	GetDeviceCount ()
	Returns the number of attached Opal Kelly devices.

std::string	GetDeviceID ()
	Retrieve the device ID string stored in EEPROM.

ErrorCode	GetDeviceInfo (okTDeviceInfo *info)
	Fills a device information structure.

ErrorCode	GetFPGAResetProfile (okEFPGAConfigurationMethod method, okTFPGAResetProfile *profile)
	Retrieve the current FPGA configuration reset profile for the given method.

BoardModel	GetDeviceListModel (int num)
	Returns the board model of a device in the devices list.

std::string	GetDeviceListSerial (int num)
	Returns the serial number of a device in the devices list.

int	GetDeviceMajorVersion ()
	Retrieves the device firmware major version.

int	GetDeviceMinorVersion ()
	Retrieves the device firmware minor version.

ErrorCode	GetDeviceSensors (okCDeviceSensors &sensors) const
	Fill the array with the available sensors.

ErrorCode	GetDeviceSettings (okCDeviceSettings &settings)
	Initialize the object allowing to access the device settings.

ErrorCode	GetEepromPLL22150Configuration (okCPLL22150 &pll)
	Read PLL configuration from the on-board EEPROM (PLL22150).

ErrorCode	GetEepromPLL22393Configuration (okCPLL22393 &pll)
	Read PLL configuration from the on-board EEPROM (PLL22393).

int	GetHostInterfaceWidth ()
	Returns the width of the host interface, in bits.

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).

ErrorCode	GetPLL22393Configuration (okCPLL22393 &pll)
	Read the PLL configuration via the I2C bus (PLL22393).

std::string	GetSerialNumber ()
	Retrieve the iSerialNumber of the device.

ErrorCode	GetWireInValue (int epAddr, UINT32 *val)
	Gets the value of a particular Wire In from the internal wire data structure.

UINT32	GetWireOutValue (int epAddr)
	Gets the value of a particular Wire Out from the internal wire data structure.

bool	HasDeviceSettingsSupport () const
	Returns true if the device supports settings.

bool	HasDeviceSensorsSupport () const
	Returns true if the device supports sensors.

bool	IsHighSpeed ()
	Returns true if the device is High-Speed.

bool	IsFrontPanel3Supported ()
	Returns true if FrontPanel-3 is firmware-supported.

bool	IsFrontPanelEnabled ()
	Reads a byte from the host interface to see if FrontPanel support is built in.

bool	IsOpen () const
	Returns true if a device is currently open.

bool	IsRemote () const
	Returns true if the device is connected to a remote server.

bool	IsTriggered (int epAddr, UINT32 mask)
	Returns true if the trigger has been triggered.

UINT32	GetTriggerOutVector (int epAddr) const
	Returns the value of the given trigger.

ErrorCode	LoadDefaultPLLConfiguration ()
	Configures the PLL from settings stored in EEPROM.

ErrorCode	OpenBySerial (std::string str="")
	Opens the specified device by serial number.

ErrorCode	ReadI2C (int addr, int length, unsigned char *data)
	Reads I2C data from an arbitrary I2C device.

long	ReadFromBlockPipeOut (int epAddr, int blockSize, long length, unsigned char *data)
	Reads data from a BlockPipeOut endpoint.

long	ReadFromPipeOut (int epAddr, long length, unsigned char *data)
	Reads a block from a Pipe Out endpoint.

ErrorCode	ReadRegister (UINT32 addr, UINT32 *data)
	Reads a single register.

ErrorCode	ReadRegisters (okTRegisterEntries &regs)
	Reads a set of registers.

ErrorCode	ResetFPGA ()
	Send RESET signal to FPGA design (via okHostInterface).

ErrorCode	SetBTPipePollingInterval (int interval)
	Set the BTPipe polling interval for completion.

ErrorCode	SetFPGAResetProfile (okEFPGAConfigurationMethod method, const okTFPGAResetProfile *profile)
	Set the current FPGA configuration reset profile for the given method.

void	SetDeviceID (const std::string &str)
	Set the device ID in EEPROM.

ErrorCode	SetPLL22150Configuration (const okCPLL22150 &pll)
	Store the PLL configuration via the I2C bus (PLL22150).

ErrorCode	SetPLL22393Configuration (const okCPLL22393 &pll)
	Store the PLL configuration via the I2C bus (PLL22393).

ErrorCode	SetEepromPLL22150Configuration (const okCPLL22150 &pll)
	Store PLL configuration on the on-board EEPROM (PLL22150).

ErrorCode	SetEepromPLL22393Configuration (const okCPLL22393 &pll)
	Store PLL configuration on the on-board EEPROM (PLL22393).

void	SetTimeout (int timeout)
	Set the USB timeout duration (in milliseconds).

ErrorCode	SetWireInValue (int ep, UINT32 val, UINT32 mask=0xffffffff)
	Sets a wire value in the internal wire data structure.

ErrorCode	UpdateTriggerOuts ()
	Reads Trigger Out endpoints.

ErrorCode	UpdateWireIns ()
	Transfers current Wire In values to the FPGA.

ErrorCode	UpdateWireOuts ()
	Transfers current Wire Out values from the FPGA.

ErrorCode	FlashEraseSector (UINT32 address)
	Erases the sector at the specified address of System Flash memory.

ErrorCode	FlashWrite (UINT32 address, UINT32 length, const UINT8 *buf)
	Writes data to System Flash starting at the specified address.

ErrorCode	FlashRead (UINT32 address, UINT32 length, UINT8 *buf)
	Reads data from System Flash starting at the specified address.

ErrorCode	WriteI2C (int addr, int length, const unsigned char *data)
	Sends I2C data to an arbitrary I2C device.

ErrorCode	WriteRegister (UINT32 addr, UINT32 data)
	Writes a single register.

ErrorCode	WriteRegisters (const okTRegisterEntries &regs)
	Writes a set of registers.

long	WriteToBlockPipeIn (int epAddr, int blockSize, long length, const unsigned char *data)
	Writes data to a BlockPipeIn endpoint.

long	WriteToPipeIn (int epAddr, long length, const unsigned char *data)
	Writes a block to a Pipe In endpoint.

Static Public Member Functions
static const char *	GetErrorMessage (ErrorCode error)

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]	epAddr	The address of the TriggerIn to activate.
[in]	bit	The 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().

◆ ClearFPGAConfiguration()

okCFrontPanel::ErrorCode okCFrontPanel::ClearFPGAConfiguration ( )

Returns: NoError - Configuration clear completed successfully.; DeviceNotOpen - Communication with a device is not established.; 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 clears the current configuration of the FPGA.

◆ 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.

Referenced by OpenBySerial().

◆ ConfigureFPGA()

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGA	(	const std::string	strFilename,
		void(*	callback )(int, int, void *) = NULL,
		void *	arg = NULL )

Parameters

[in]	strFilename	A string containing the filename of the configuration file.
[in]	callback	An optional progress callback function.
[in]	arg	An 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(*	callback )(int, int, void *),
		void *	arg )

Parameters

[in]	configIndex	Storage index to the FPGA configuration to load.
[in]	callback	An optional progress callback function.
[in]	arg	An 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(*	callback )(int, int, void *) = NULL,
		void *	arg = NULL )

Parameters

[in]	data	Pointer to a memory buffer containing the configuration.
[in]	length	Length of the configuration memory.
[in]	callback	An optional progress callback function.
[in]	arg	An 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(*	callback )(int, int, void *) = NULL,
		void *	arg = NULL )

Parameters

[in]	data	Pointer to a memory buffer containing the configuration.
[in]	length	Length of the configuration memory.
[in]	reset	Pointer to an FPGA Reset Profile to perform after configuration.
[in]	callback	An optional progress callback function.
[in]	arg	An 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(*	callback )(int, int, void *) = NULL,
		void *	arg = NULL )

Parameters

[in]	strFilename	A string containing the filename of the configuration file.
[in]	callback	An optional progress callback function.
[in]	reset	FPGA Reset profile to perform after configuration.
[in]	arg	An 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] enable true 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] address Address 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]	address	Byte address to begin read operation.
[in]	length	Length of data to read (in bytes).
[in]	buf	Pointer 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.

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.FlashRead(0x0, buf)

okCFrontPanel::FlashRead

ErrorCode FlashRead(UINT32 address, UINT32 length, UINT8 *buf)

Reads data from System Flash starting at the specified address.

Definition okCFrontPanel_NVRAM.cpp:119

See also: FlashEraseSector; FlashWrite

◆ FlashWrite()

okCFrontPanel::ErrorCode okCFrontPanel::FlashWrite	(	UINT32	address,
		UINT32	length,
		const UINT8 *	buf )

Parameters

[in]	address	Byte address to begin write operation.
[in]	length	Length of data to write (in bytes).
[in]	buf	Pointer 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.

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.FlashWrite(0x0, buf)

okCFrontPanel::FlashWrite

ErrorCode FlashWrite(UINT32 address, UINT32 length, const UINT8 *buf)

Writes data to System Flash starting at the specified address.

Definition okCFrontPanel_NVRAM.cpp:81

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.

Use GetLastError() or GetLastErrorMessage() to get more information about the error if brdUnknown 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 GetDeviceInfo(), and 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.

If the returned string is empty, use GetLastError() to check whether an error has occurred.

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, and GetDeviceInfo().

◆ GetDeviceInfo()

okCFrontPanel::ErrorCode okCFrontPanel::GetDeviceInfo ( okTDeviceInfo * info )

Parameters

[in] info Pointer 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 which is too small. The latter can realistically only happen when using C API and passing incorrect size argument to okFrontPanel_GetDeviceInfoWithSize() function.; UnsupportedFeature - The application uses a version of the library which is too old and doesn't have all the fields present in okTDeviceInfo struct. Either a newer version of the library must be used or the application must be recompiled with the older version of the SDK.

Fills the okTDeviceInfo structure with information about the device.

Referenced by GetBoardModel(), GetDeviceID(), GetDeviceMajorVersion(), and GetDeviceMinorVersion().

◆ 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] num Device 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] num Device 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.

If the returned value is -1, use GetLastError() to get more information about the error.

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, and GetDeviceInfo().

◆ GetDeviceMinorVersion()

int okCFrontPanel::GetDeviceMinorVersion ( )

Returns: The firmware's minor version number or -1 if the query failed.

If the returned value is -1, use GetLastError() to get more information about the error.

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, and GetDeviceInfo().

◆ GetDeviceSensors()

okCFrontPanel::ErrorCode okCFrontPanel::GetDeviceSensors ( okCDeviceSensors & sensors ) const

Parameters

[out] sensors An 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;
okCDeviceSensors sensors;
okTDeviceSensor  sensor;
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] settings An 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] pll A 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] pll A 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

◆ GetErrorMessage()

const char * okCFrontPanel::GetErrorMessage ( ErrorCode error )

static

Return the error message corresponding to the given error code.

This method can be used to get a human-readable message corresponding to the given FrontPanel error code.

Note that GetLastErrorMessage() should be preferred to calling this function as the last error message may contain additional details not present in the generic message returned by this function.

Returns NULL if the error code is not recognized.

See also: GetLastErrorMessage()

Referenced by GetLastErrorMessage().

◆ GetFPGAResetProfile()

okCFrontPanel::ErrorCode okCFrontPanel::GetFPGAResetProfile	(	okEFPGAConfigurationMethod	method,
		okTFPGAResetProfile *	profile )

Parameters

[in]	method	Indicates which reset profile should be retrieved.
[out]	profile	Boot 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

◆ GetLastError()

ErrorCode okCFrontPanel::GetLastError ( ) const

inline

Get the error code of the last operation.

Returns one of ErrorCode values, possibly NoError.

Note that GetLastErrorMessage() should be preferred to calling this function and GetErrorMessage(), as the last error message may contain additional details not present in the generic error message returned from GetErrorMessage().

See also: GetLastErrorMessage()

◆ 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).

See also: GetLastError(), GetErrorMessage()

References GetErrorMessage().

◆ GetLastTransferLength()

long okCFrontPanel::GetLastTransferLength ( )

Returns: Returns the length of the last transfer, possibly 0 if it failed.

The last transfer length is updated by pipe-related functions, i.e. WriteToBlockPipeIn(), WriteToPipeIn(), ReadFromBlockPipeOut() and ReadFromPipeOut().

This function doesn't change the last error if it was set by a previously called pipe IO function, but does set it to DeviceNotOpen if the device is not currently open.

◆ GetPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::GetPLL22150Configuration ( okCPLL22150 & pll )

Parameters

[in] pll A 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] pll A 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();

If the returned string is empty, use GetLastError() to check whether an error has occurred.

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] epAddr The 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]	epAddr	The address of the WireIn to query.
[in]	val	Pointer 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] epAddr The 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);

If the device is not open or an invalid address is given, the return value is 0, use GetLastError() to check for error in this case.

See also: GetWireInValue; SetWireInValue; UpdateWireIns; UpdateWireOuts

◆ HasDeviceSensorsSupport()

bool okCFrontPanel::HasDeviceSensorsSupport ( ) const

Returns: true If the device supports sensors.

◆ HasDeviceSettingsSupport()

bool okCFrontPanel::HasDeviceSettingsSupport ( ) const

Returns: true If the device supports settings.

◆ 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]	epAddr	The TriggerOut address to query.
[in]	mask	A 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();

Use GetLastError() to check for error after calling this method.

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:

okCPLL22150 pll;
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] str The 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.

References Close().

◆ ReadFromBlockPipeOut()

long okCFrontPanel::ReadFromBlockPipeOut	(	int	epAddr,
		int	blockSize,
		long	length,
		unsigned char *	data )

Parameters

[in]	epAddr	The address of the source Pipe Out.
[in]	length	The length of the transfer (in bytes).
[in]	blockSize	Block size (in bytes).
[in]	data	A 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)

okCFrontPanel::ReadFromBlockPipeOut

long ReadFromBlockPipeOut(int epAddr, int blockSize, long length, unsigned char *data)

Reads data from a BlockPipeOut endpoint.

Definition okCFrontPanel_Pipe.cpp:175

◆ ReadFromPipeOut()

long okCFrontPanel::ReadFromPipeOut	(	int	epAddr,
		long	length,
		unsigned char *	data )

Parameters

[in]	epAddr	The address of the source Pipe Out.
[in]	length	The length of the transfer (in bytes).
[in]	data	A 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)

okCFrontPanel::ReadFromPipeOut

long ReadFromPipeOut(int epAddr, long length, unsigned char *data)

Reads a block from a Pipe Out endpoint.

Definition okCFrontPanel_Pipe.cpp:215

◆ ReadI2C()

okCFrontPanel::ErrorCode okCFrontPanel::ReadI2C	(	int	addr,
		int	length,
		unsigned char *	data )

Parameters

[in]	addr	I2C address of the target device.
[in]	length	Length of data (in bytes).
[in]	data	Pointer 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]	addr	Register address
[out]	data	Pointer 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] regs Vector 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: Error code.

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] interval Polling 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] str A 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.

GetLastError() can be used to check whether an error has occurred after calling this method.

◆ SetEepromPLL22150Configuration()

okCFrontPanel::ErrorCode okCFrontPanel::SetEepromPLL22150Configuration ( const okCPLL22150 & pll )

Parameters

[in] pll A 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 ( const okCPLL22393 & pll )

Parameters

[in] pll A 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]	method	Indicates which reset profile should be set.
[in]	profile	Boot 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.
okTFPGAResetProfile p;
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 ( const okCPLL22150 & pll )

Parameters

[in] pll A 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 ( const okCPLL22393 & pll )

Parameters

[in] pll A 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] timeout Timeout 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.

Use GetLastError() to check whether timeout was set successfully.

◆ SetWireInValue()

okCFrontPanel::ErrorCode okCFrontPanel::SetWireInValue	(	int	ep,
		UINT32	val,
		UINT32	mask = 0xffffffff )

Parameters

[in]	ep	The address of the WireIn endpoint to update.
[in]	val	The new value of the WireIn.
[in]	mask	A 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 ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating TriggerOuts failed.; UnsupportedFeature - Host interface error. 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 ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating WireIns failed.; UnsupportedFeature - Host interface error. 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 ( )

Returns: NoError - Operation completed successfully.; DeviceNotOpen - Device is not open.; Failed - Updating WireOuts failed.; UnsupportedFeature - Host interface error. 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	(	int	addr,
		int	length,
		const unsigned char *	data )

Parameters

[in]	addr	I2C address of the target device.
[in]	length	Length of data (in bytes).
[in]	data	Pointer 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]	addr	Register address
[in]	data	Pointer 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] regs Vector 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]	epAddr	The address of the destination Pipe In.
[in]	length	The length of the transfer (in bytes).
[in]	blockSize	Block size (in bytes).
[in]	data	A 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)

okCFrontPanel::WriteToBlockPipeIn

long WriteToBlockPipeIn(int epAddr, int blockSize, long length, const unsigned char *data)

Writes data to a BlockPipeIn endpoint.

Definition okCFrontPanel_Pipe.cpp:83

◆ WriteToPipeIn()

long okCFrontPanel::WriteToPipeIn	(	int	epAddr,
		long	length,
		const unsigned char *	data )

Parameters

[in]	epAddr	The address of the destination Pipe In.
[in]	length	The length of the transfer (in bytes).
[in]	data	A 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)

okCFrontPanel::WriteToPipeIn

long WriteToPipeIn(int epAddr, long length, const unsigned char *data)

Writes a block to a Pipe In endpoint.

Definition okCFrontPanel_Pipe.cpp:123

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ActivateTriggerIn()

◆ AddCustomDevice()

◆ ClearFPGAConfiguration()

◆ Close()

◆ ConfigureFPGA()

◆ ConfigureFPGAFromFlash()

◆ ConfigureFPGAFromMemory()

◆ ConfigureFPGAFromMemoryWithReset()

◆ ConfigureFPGAWithReset()

◆ EnableAsynchronousTransfers()

◆ FindUSBDeviceModel()

◆ FlashEraseSector()

◆ FlashRead()

◆ FlashWrite()

◆ GetBoardModel()

◆ GetDeviceCount()

◆ GetDeviceID()

◆ GetDeviceInfo()

◆ GetDeviceListModel()

◆ GetDeviceListSerial()

◆ GetDeviceMajorVersion()

◆ GetDeviceMinorVersion()

◆ GetDeviceSensors()

◆ GetDeviceSettings()

◆ GetEepromPLL22150Configuration()

◆ GetEepromPLL22393Configuration()

◆ GetErrorMessage()

◆ GetFPGAResetProfile()

◆ GetHostInterfaceWidth()

◆ GetLastError()

◆ GetLastErrorMessage()

◆ GetLastTransferLength()

◆ GetPLL22150Configuration()

◆ GetPLL22393Configuration()

◆ GetSerialNumber()

◆ GetTriggerOutVector()

◆ GetWireInValue()

◆ GetWireOutValue()

◆ HasDeviceSensorsSupport()

◆ HasDeviceSettingsSupport()

◆ IsFrontPanel3Supported()

◆ IsFrontPanelEnabled()

◆ IsHighSpeed()

◆ IsOpen()

◆ IsRemote()

◆ IsTriggered()

◆ LoadDefaultPLLConfiguration()

◆ OpenBySerial()

◆ ReadFromBlockPipeOut()

◆ ReadFromPipeOut()

◆ ReadI2C()

◆ ReadRegister()

◆ ReadRegisters()

◆ RemoveCustomDevice()

◆ ResetFPGA()

◆ SetBTPipePollingInterval()

◆ SetDeviceID()

◆ SetEepromPLL22150Configuration()

◆ SetEepromPLL22393Configuration()

◆ SetFPGAResetProfile()

◆ SetPLL22150Configuration()

◆ SetPLL22393Configuration()

◆ SetTimeout()

◆ SetWireInValue()

◆ UpdateTriggerOuts()

◆ UpdateWireIns()

◆ UpdateWireOuts()

◆ WriteI2C()

◆ WriteRegister()

◆ WriteRegisters()

◆ WriteToBlockPipeIn()

◆ WriteToPipeIn()