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

Public Member Functions
	okCFrontPanel ()
	Default constructor.
	~okCFrontPanel ()
	Default destructor.
ErrorCode	ActivateTriggerIn (int epAddr, int bit)
	Activates a given trigger.
ErrorCode	ConfigureFPGA (const std::string strFilename, void(callback)(int, int, void )=NULL, void *arg=NULL)
	Download an FPGA configuration from a file.
ErrorCode	ConfigureFPGAFromMemory (unsigned char data, const unsigned long length, void(callback)(int, int, void )=NULL, void arg=NULL)
	Download an FPGA configuration from memory.
void	EnableAsynchronousTransfers (bool enable)
	Enables (or disables) asynchronous bulk transfer queueing.
BoardModel	GetBoardModel ()
	Returns the open board model enumerated type.
std::string	GetBoardModelString (BoardModel m)
	Returns the board model string from a 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.
int	GetDeviceMajorVersion ()
	Returns the board model of a device in the devices list.
int	GetDeviceMinorVersion ()
	Retrieves the device firmware minor version.
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.
UINT32	GetWireOutValue (int epAddr)
	Gets the value of a particular Wire Out from the internal wire data structure.
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 ()
	Returns true if a device is currently open.
bool	IsTriggered (int epAddr, UINT32 mask)
	Returns true if the trigger has been triggered.
ErrorCode	LoadDefaultPLLConfiguration ()
	Configures the PLL from settings stored in EEPROM.
ErrorCode	OpenBySerial (std::string str="")
	Opens the specified device by serial number.
ErrorCode	ReadI2C (const 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	ResetFPGA ()
	Send RESET signal to FPGA design (via okHostInterface).
ErrorCode	SetBTPipePollingInterval (int interval)
	Set the BTPipe polling interval for completion.
void	SetDeviceID (const std::string str)
	Set the device ID in EEPROM.
ErrorCode	SetPLL22150Configuration (okCPLL22150 &pll)
	Store the PLL configuration via the I2C bus (PLL22150).
ErrorCode	SetPLL22393Configuration (okCPLL22393 &pll)
	Store the PLL configuration via the I2C bus (PLL22393).
ErrorCode	SetEepromPLL22150Configuration (okCPLL22150 &pll)
	Store PLL configuration on the on-board EEPROM (PLL22150).
ErrorCode	SetEepromPLL22393Configuration (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.
void	UpdateTriggerOuts ()
	Reads Trigger Out endpoints.
void	UpdateWireIns ()
	Transfers current Wire In values to the FPGA.
void	UpdateWireOuts ()
	Transfers current Wire Out values from the FPGA.
ErrorCode	WriteI2C (const int addr, int length, unsigned char *data)
	Sends I2C data to an arbitrary I2C device.
long	WriteToBlockPipeIn (int epAddr, int blockSize, long length, unsigned char *data)
	Writes data to a BlockPipeIn endpoint.
long	WriteToPipeIn (int epAddr, long length, unsigned char *data)
	Writes a block to a Pipe In endpoint.

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

okCFrontPanel::ErrorCode okCFrontPanel::ActivateTriggerIn	(	int	epAddr,
		int	bit
	)

Parameters:

`[in]`	epAddr	The address of the Trigger In to activate.
`[in]`	bit	The specific bit of the trigger to activate.

Returns:: ErrorCode

This method activates the specified Trigger In on the XEM.

Error Codes: NoError, InvalidEndpoint

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGA	(	const std::string	strFilename,
		void()(int, int, void )	callback = `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:: ErrorCode

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

The arguments length and count represent the total file length and current progress count, respectively. The arg parameter is the same parameter passed to this method.

ErrorCodes:

NoError - Configuration has occurred 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.

okCFrontPanel::ErrorCode okCFrontPanel::ConfigureFPGAFromMemory	(	unsigned char *	data,
		const unsigned long	length,
		void()(int, int, void )	callback = `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

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

ErrorCodes: See ConfigureFPGA for details on error responses.

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.

okCFrontPanel::BoardModel okCFrontPanel::GetBoardModel ( )

Returns:: The board model of the currently-open device. If the device is unknown, brdUnkown is returned.

std::string okCFrontPanel::GetBoardModelString ( BoardModel m )

Returns:: A string representing the board model enumeration.

int okCFrontPanel::GetDeviceCount ( )

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.

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.

int okCFrontPanel::GetDeviceMajorVersion ( )

Returns the serial number of a device in the devices list. Retrieves the device firmware major version.

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

int okCFrontPanel::GetDeviceMinorVersion ( )

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

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

Parameters:

[out] pll A reference to an okCPLL22150 object.

Returns:: ErrorCode

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

ErrorCodes: NoError, DeviceNotOpen

okCFrontPanel::ErrorCode okCFrontPanel::GetEepromPLL22393Configuration ( okCPLL22393 & pll )

Parameters:

[out] pll A reference to an okCPLL22393 object.

Returns:: ErrorCode

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

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.

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

Parameters:

[in] pll A reference to an okCPLL22150 object.

Returns:: ErrorCode

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

ErrorCodes: NoError, DeviceNotOpen

okCFrontPanel::ErrorCode okCFrontPanel::GetPLL22393Configuration ( okCPLL22393 & pll )

Parameters:

[in] pll A reference to an okCPLL22393 object.

Returns:: ErrorCode

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

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();

UINT32 okCFrontPanel::GetWireOutValue ( int epAddr )

Parameters:

[in] epAddr The Wire Out address to query.

Returns:: The value of the Wire Out.

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

 // First, query all XEM Wire Outs.
 xem->UpdateWireOuts();
 // Now, get values from endpoints 0x21 and 0x27.
 a = xem->GetWireOutValue(0x21);
 b = xem->GetWireOutValue(0x27);

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

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.

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.

bool okCFrontPanel::IsOpen ( )

Returns:: true if the device is open. false otherwise.

bool okCFrontPanel::IsTriggered	(	int	epAddr,
		UINT32	mask
	)

Parameters:

`[in]`	epAddr	The Trigger Out 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 Trigger Out 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();

okCFrontPanel::ErrorCode okCFrontPanel::LoadDefaultPLLConfiguration ( )

Returns:: ErrorCode

Configures the on-board PLL using the default configuration setup in the EEPROM. If the specific device does not support this, the method returns error code UnsupportedFeature.

ErrorCodes: NoError, UnsupportedFeature, DeviceNotOpen

okCFrontPanel::ErrorCode okCFrontPanel::OpenBySerial ( std::string str = "" )

Parameters:

[in] str The serial number of the device to open.

Returns:: ErrorCode

Before any communication with the device can proceed, the device must be opened using this method. A Close() method is not provided and is not necessary.

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.

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.

This method transfers data from a specified BlockPipeOut endpoint to the given buffer. The maximum length of a transfer (per call to this method) is 16,777,214 bytes.

The block size is specified in bytes. Length is rounded down to the nearest multiple of the block size specified. Block size must be even in the range 2...1024 (inclusive). (2...64 for full-speed connections)

Performance Note: Optimum bandwidth performance is achieved when blockSize is a power of 2: 2, 4, 8, 16, 32, ... 512, 1024.

Error Codes: NoError, InvalidEndpoint, InvalidBlockSize, Failed, Timeout

PCIeNote: blockSize is ignored.

PCIeNote: length must be a multiple of 8.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is a string buffer. For example,

 buf = "\x00"*1536
 xem.ReadFromBlockPipeOut(0xa0, 1024, buf)

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.

This method transfers data from a specified Pipe Out endpoint to the given buffer. The maximum length of a transfer (per call to this method) is 16,777,214 bytes.

Error Codes: NoError, InvalidEndpoint, Failed, Timeout

Note: For 16-bit boards (all but the XEM3001v1), the transfer length must be even. Odd transfers will be shortened by one byte.

PCIeNote: length must be a multiple of 8.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is a string buffer. For example,

 buf = "\x00"*1076
 xem.ReadFromPipeOut(0xa0, buf)

okCFrontPanel::ErrorCode okCFrontPanel::ReadI2C	(	const 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:: ErrorCode

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.

ErrorCodes:

NoError - Write has completed successfully.
DeviceNotOpen - Communication with a XEM is not established.
CommunicationError - Communication error with the firmware.
I2CRestrictedAddress - Read from a restricted I2C address.
I2CBitError - I2C bit error occurred.
I2CNack - I2C device responded with NACK.
I2CUnknownStatus - Unknown result status.

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

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.

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.

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.

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

Parameters:

[in] pll A reference to an okCPLL22150 object.

Returns:: ErrorCode

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

ErrorCodes: NoError, DeviceNotOpen

okCFrontPanel::ErrorCode okCFrontPanel::SetEepromPLL22393Configuration ( okCPLL22393 & pll )

Parameters:

[in] pll A reference to an okCPLL22393 object.

Returns:: ErrorCode

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

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

Parameters:

[in] pll A reference to an okCPLL22150 object.

Returns:: ErrorCode

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

ErrorCodes: NoError, DeviceNotOpen

okCFrontPanel::ErrorCode okCFrontPanel::SetPLL22393Configuration ( okCPLL22393 & pll )

Parameters:

[in] pll A reference to an okCPLL22393 object.

Returns:: ErrorCode

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

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.

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

Parameters:

`[in]`	ep	The address of the Wire In endpoint to update.
`[in]`	val	The new value of the Wire In.
`[in]`	mask	A mask to apply to the new value.

Returns:: ErrorCode

Wire In 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.

Error Codes: NoError, InvalidEndpoint

 // 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();

void okCFrontPanel::UpdateTriggerOuts ( )

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

void okCFrontPanel::UpdateWireIns ( )

This method is called after all Wire In 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.

void okCFrontPanel::UpdateWireOuts ( )

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

okCFrontPanel::ErrorCode okCFrontPanel::WriteI2C	(	const 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 to data to be written.

Returns:: ErrorCode

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.

ErrorCodes:

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.

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

long okCFrontPanel::WriteToBlockPipeIn	(	int	epAddr,
		int	blockSize,
		long	length,
		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.

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.

The block size is specified in bytes. Length is rounded down to the nearest multiple of the block size specified. Block size must be even in the range 2...1024 (inclusive). (2...64 for full-speed connections)

Error Codes: NoError, InvalidEndpoint, InvalidBlockSize, Failed, Timeout

PCIeNote: blockSize is ignored.

PCIeNote: length must be a multiple of 8.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is a string buffer. For example,

 buf = "\x00"*1536
 xem.WriteToBlockPipeIn(0x80, 512, buf)

long okCFrontPanel::WriteToPipeIn	(	int	epAddr,
		long	length,
		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.

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.

Error Codes: NoError, InvalidEndpoint, Failed, Timeout

Note: For 16-bit boards (all but the XEM3001v1), the transfer length must be even. Odd transfers will be shortened by one byte.

PCIeNote: length must be a multiple of 8.

Python Note: Within Python, the 'length' parameter is not used and the 'data' parameter is a string buffer. For example,

 buf = "\x00"*1076
 xem.WriteToPipeIn(0x80, buf)

okCFrontPanel Class Reference

Public Member Functions

Detailed Description

Member Function Documentation