VIB::VIBSystem Class Reference

Detailed Description

The factory for devices.

See also Device Factory for a detailed description.

Classes
struct	Version4Parts
	Version information. More...

Public Member Functions
bool	CloseDevice (iDevice *pDevice)
	Closes a device.
bool	GetAPIVersion (Version4Parts &APIVersion)
	Returns the version of this library.
bool	GetDeviceInfo (DeviceInfo *pDeviceInfoList, unsigned int MaxNumberItems, unsigned int &NumberOfListItems)
	Returns a list of available devices for this hardware component.
bool	GetFirmwareVersion (Version4Parts &FirmwareVersion, unsigned int Index=0)
	Returns the firmware version for this hardware component.
bool	GetHardwareType (eHardwareType &HardwareType)
	Returns the type of the underlying hardware platform for this factory.
bool	GetNumberOfDeviceTypes (unsigned int &NumberOfDeviceTypes)
	Returns the number of different device types for this hardware component.
bool	GetVersionString (char *pText, unsigned int MaxStringSize)
	Returns a string with version data from all components. (DLL, driver, FPGA, ...)
bool	IsOpen (eDeviceType Type, int Index, bool &DeviceState)
	Checks if the device open.
bool	OpenDevice (class CameraLinkIn *&pCameraLinkIn, int Index=0)
	Opens a CameraLinkIn device and returns the new device object.
bool	OpenDevice (class CameraTrigger *&pCameraTrigger, int Index=0)
	Opens a CameraTrigger device and returns the new device object.
bool	OpenDevice (class DigitalInput *&pDigitalInput, int Index=0)
	Opens a DigitalInput device and returns the new device object.
bool	OpenDevice (class DigitalOutput *&pDigitalOutput, int Index=0)
	Opens a DigitalOutput device and returns the new device object.
bool	OpenDevice (class IOScheduler *&pIOScheduler, int Index=0)
	Opens a IOScheduler device and returns the new device object.
bool	OpenDevice (class LCD *&pLCD)
	Opens a LCD device and returns the new device object.
bool	OpenDevice (class Led *&pLed)
	Opens a Led device and returns the new device object.
bool	OpenDevice (class Multiplexer *&pMultiplexer, int Index=0)
	Opens a Multiplexer device and returns the new device object.
bool	OpenDevice (class PowerOverEthernet *&pPowerOverEthernet)
	Opens a PowerOverEthernet device and returns the new device object.
bool	OpenDevice (class Rs232 *&pRs232, int Index=0)
	Opens a Rs232 device and returns the new device object.
bool	OpenDevice (class Rs422 *&pRs422, int Index=0)
	Opens a Rs422 device and returns the new device object.
bool	OpenDevice (class Service *&pService)
	Opens a Service device and returns the new device object.
bool	OpenDevice (class Strobe *&pStrobe, int Index=0)
	Opens a Strobe device and returns the new device object.
bool	OpenDevice (class TriggerGenerator *&pTriggerGenerator)
	Opens a TriggerGenerator device and returns the new device object.
bool	OpenDevice (class TriggerOverEthernet *&pTriggerOverEthernet)
	Opens a TriggerOverEthernet device and returns the new device object.
bool	OpenDevice (eDeviceType Type, int Index, iDevice **ppNewDevice)
	Opens a device and returns a new device object.

Static Public Member Functions
static bool	CreateInstance (VIBSystem **ppVIBSystem)
	Creates a factory instance for the mainboard.
static bool	CreateInstance (VIBSystem **ppVIBSystem, const eSystemType SysType, const unsigned int Index)
	Creates a factory instance for the specified hardware component.
static bool	CreateInstance (VIBSystem **ppVIBSystem, eHardwareType HardwareType, unsigned int Index)
	Creates a factory instance for a specific hardware component.
static bool	DeleteInstance (VIBSystem *pObj)
	Releases the device object.
static void	GetLastErrorString (char &pText, unsigned int MaxStringSize)
	Returns the last error message.
static bool	GetNumberOfSystemTypes (unsigned int &NumberOfSystemTypes)
	Gets number of different system types.
static bool	GetSystemInfo (SystemInfo *pSystemInfoList, unsigned int MaxNumberItems, unsigned int &NumberOfListItems)
	Returns information about the installed system types.

Member Function Documentation

CloseDevice()

bool VIB::VIBSystem::CloseDevice

(

iDevice *

pDevice

)

Closes a device.

Theoretically it is possible to use another factory to clean up the device as previously used for creation.

Parameters

pDevice

Previously opened device class object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

CreateInstance() [1/3]

bool VIB::VIBSystem::CreateInstance ( VIBSystem ** ppVIBSystem )

static

Creates a factory instance for the mainboard.

This function call is identical to CreateInstance(ppVIBSystem, SYST_BASEBOARD, 0).

Parameters

ppVIBSystem

Double pointer which contains the pointer to the new VIBSystem instance.

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

CreateInstance() [2/3]

bool VIB::VIBSystem::CreateInstance ( VIBSystem ** ppVIBSystem, const eSystemType SysType, const unsigned int Index )

static

Creates a factory instance for the specified hardware component.

See Supported hardware components for a mapping of eSystemType to the actual hardware component for each platform.

Parameters

ppVIBSystem	Double pointer which is used to store the pointer to the new instance
SysType	Desired system type
Index	Index for the specified system type, 0 ... (SystemInfo::GetNumberEntities() - 1)

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::VIBSystem *pVIBSystem = NULL;
char ErrorText[1024] = {0};
 
// create a factory instance for the mainboard
if (!VIB::VIBSystem::CreateInstance(&pVIBSystem, VIB::SYST_BASEBOARD, 0))
{
    //print a readable error description
    VIB::VIBSystem::GetLastErrorString(*ErrorText, sizeof(ErrorText));
    printf("Error: %s\n", ErrorText);
    return -1;
}

CreateInstance() [3/3]

bool VIB::VIBSystem::CreateInstance ( VIBSystem ** ppVIBSystem, eHardwareType HardwareType, unsigned int Index )

static

Creates a factory instance for a specific hardware component.

This overloaded method is less generic than CreateInstance(VIBSystem **, const eSystemType, const unsigned int). Also see Supported hardware components.

Parameters

ppVIBSystem	Double pointer which is used to store the pointer to the new instance
HardwareType	Desired hardware type
Index	Index for the specified hardware type

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::VIBSystem *pVIBSystem = NULL;
char ErrorText[1024] = {0};
 
// create a factory instance for the AGE-X5 Smart NIC
if (!VIB::VIBSystem::CreateInstance(&pVIBSystem, VIB::HWT_AGEX5_POETOE, 0))
{
    //print a readable error description
    VIB::VIBSystem::GetLastErrorString(*ErrorText, sizeof(ErrorText));
    printf("Error: %s\n", ErrorText);
    return -1;
}

DeleteInstance()

bool VIB::VIBSystem::DeleteInstance ( VIBSystem * pObj )

static

Releases the device object.

The function deletes only the factory. The call will not fail or block until all open devices are closed.

Parameters

pObj	Pointer to VIBSystem object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetAPIVersion()

bool VIB::VIBSystem::GetAPIVersion

(

Version4Parts &

APIVersion

)

Returns the version of this library.

Parameters

APIVersion

Version data (major/minor/patch/build)

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetDeviceInfo()

bool VIB::VIBSystem::GetDeviceInfo	(	DeviceInfo *	pDeviceInfoList,
		unsigned int	MaxNumberItems,
		unsigned int &	NumberOfListItems )

Returns a list of available devices for this hardware component.

The function returns an array of DeviceInfo containing all devices for the associated system (hardware component).

Parameters

pDeviceInfoList	Device list
MaxNumberItems	Maximum number of list items
NumberOfListItems	Number of returned items

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

//get the number of device types
unsigned int NumTypes;
if ( !pVIBSystem->GetNumberOfDeviceTypes(NumTypes) )
    goto error;
 
//acquire information of all supported device types
unsigned int NumberOfListItems;
VIB::DeviceInfo *pDeviceList = new VIB::DeviceInfo[NumTypes];
if ( !pVIBSystem->GetDeviceInfo(pDeviceList, NumTypes, NumberOfListItems) )
    goto error;
 
//search for the strobe(s)
for(unsigned int i=0; i<NumberOfListItems; i++)
{
    if (pDeviceList[i].GetDeviceType() == VIB::DT_STROBE)
        printf("Number of strobe devices: %d\n", pDeviceList[i].GetNumberEntities());
}

GetFirmwareVersion()

bool VIB::VIBSystem::GetFirmwareVersion	(	Version4Parts &	FirmwareVersion,
		unsigned int	Index = 0 )

Returns the firmware version for this hardware component.

There can be a different number of firmware components for each hardware component. The following table lists the different firmware components:

Platform	Hardware component (see eHardwareType)	Firmware component index	Firmware description
VisionBox AGE-X1	Mainboard	0	FPGA (RTCC)
VisionBox AGE-X2	Mainboard	0	FPGA (RTCC)
	Smart NIC	0	Microcontroller
	Camera Link	0	FPGA
VisionBox AGE-X3	Mainboard	0	FPGA (RTCC)
		1	Microcontroller
VisionBox AGE-X4	Mainboard	not available, only VisionBoards are supported (see below)
VisionBox AGE-X5 / AGE-X6	Mainboard	0	FPGA (RTCC)
	Smart NIC	0	Microcontroller
	Camera Link	0	FPGA
VisionBox LE MANS	Mainboard	0	FPGA (RTCC)
VisionBox DAYTONA	Mainboard	0	FPGA (RTCC)
VisionBoards	Machine Vision Controller	0	FPGA (RTCC)
	PCIe Smart NIC board	0	Microcontroller
	PCIe Camera Link board	0	FPGA
VisionCam XM	Mainboard	0	FPGA (RTCC)
VisionSensor PV / PV2	Mainboard	0	PRU (programmable real-time unit)
VisionSensor PV3	Mainboard	0	FPGA
Machine Vision Manager	Mainboard	0	FPGA (RTCC)
		1	Microcontroller

Parameters

FirmwareVersion	Firmware version structure
Index	Index of the firmware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetHardwareType()

bool VIB::VIBSystem::GetHardwareType

(

eHardwareType &

HardwareType

)

Returns the type of the underlying hardware platform for this factory.

Parameters

HardwareType

Hardware type

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetLastErrorString()

void VIB::VIBSystem::GetLastErrorString ( char & pText, unsigned int MaxStringSize )

static

Returns the last error message.

All library functions return a bool to indicate the status of a call. In the case of an error, this function returns a readable error description.
See CreateInstance() for an example.

Parameters

pText	Array of char for storing the string
MaxStringSize	Maximum string length

GetNumberOfDeviceTypes()

bool VIB::VIBSystem::GetNumberOfDeviceTypes

(

unsigned int &

NumberOfDeviceTypes

)

Returns the number of different device types for this hardware component.

For example, if the VisionBox has two Strobe units and one RS-422 interface, the function returns a value of 2.

Parameters

NumberOfDeviceTypes

Number of unique device types

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetNumberOfSystemTypes()

bool VIB::VIBSystem::GetNumberOfSystemTypes ( unsigned int & NumberOfSystemTypes )

static

Gets number of different system types.

For example, a VisionBox with two smart network cards returns the value 2, one for the mainboard and one for both NICs.

Parameters

NumberOfSystemTypes

Number of system types

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetSystemInfo()

bool VIB::VIBSystem::GetSystemInfo ( SystemInfo * pSystemInfoList, unsigned int MaxNumberItems, unsigned int & NumberOfListItems )

static

Returns information about the installed system types.

The function returns an array of SystemInfo objects containing all installed systems or hardware entities. Each item holds information about a different system type.

Parameters

pSystemInfoList	Valid pointer for storing the list
MaxNumberItems	Maximum number of list items
NumberOfListItems	Number of valid items returned

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

//get the number of system types
unsigned int NumTypes;
if ( !VIBSystem::GetNumberOfSystemTypes(NumTypes) )
    goto error;
 
//acquire information of all supported device types
unsigned int NumberOfListItems;
VIB::SystemInfo *pSystemList = new VIB::SystemInfo[NumTypes];
if ( !VIBSystem::GetSystemInfo(pSystemList, NumTypes, NumberOfListItems) )
    goto error;
 
//search for the CL-Card
for(unsigned int i=0; i<NumberOfListItems; i++)
{
    if (pSystemList[i].GetSystemType() == VIB::SYST_CL)
        printf("Number of CL-Cards: %d\n", pSystemList[i].GetNumberEntities());
}

GetVersionString()

bool VIB::VIBSystem::GetVersionString	(	char *	pText,
		unsigned int	MaxStringSize )

Returns a string with version data from all components. (DLL, driver, FPGA, ...)

Do not parse or interpret this string to do any assumption. Use the string only to give the user a human readable overview about the versions. The layout and 'keywords' can be different for each hardware type.

Parameters

pText	String for version data
MaxStringSize	Maximum size of pText

Returns

Since API version 1.2.x.x the call returns false if the buffer is to short, earlier releases generate a structured exception.

Example:

char VerText[4096] = "?";
if( !pVIBSystem->GetVersionString(VerText, sizeof(VerText) ) )
    goto error;
printf("\t<== Versions ==>\n%s", VerText);

IsOpen()

bool VIB::VIBSystem::IsOpen	(	eDeviceType	Type,
		int	Index,
		bool &	DeviceState )

Checks if the device open.

The function returns the system wide state of the device. If a program has opened the device the function will return true.

Note

• This function does not work with VIB::DT_SERVICE.
• Even if the result indicates that the device is closed, it's possible that another thread or process opens the device immediately after the call.

Parameters

Type	Type of device
Index	Index of device
DeviceState	Device state, true for open

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

OpenDevice() [1/16]

bool VIB::VIBSystem::OpenDevice	(	class CameraLinkIn *&	pCameraLinkIn,
		int	Index = 0 )

Opens a CameraLinkIn device and returns the new device object.

Parameters

pCameraLinkIn	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::CameraLinkIn *pCameraLinkIn = NULL;
if (!pVIBSystem->OpenDevice(pCameraLinkIn))
    return -1;

OpenDevice() [2/16]

bool VIB::VIBSystem::OpenDevice	(	class CameraTrigger *&	pCameraTrigger,
		int	Index = 0 )

Opens a CameraTrigger device and returns the new device object.

Parameters

pCameraTrigger	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::CameraTrigger *pCameraTrigger = NULL;
if (!pVIBSystem->OpenDevice(pCameraTrigger))
    return -1;

OpenDevice() [3/16]

bool VIB::VIBSystem::OpenDevice	(	class DigitalInput *&	pDigitalInput,
		int	Index = 0 )

Opens a DigitalInput device and returns the new device object.

Parameters

pDigitalInput	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::DigitalInput *pDigitalInput = NULL;
if (!pVIBSystem->OpenDevice(pDigitalInput))
    return -1;

OpenDevice() [4/16]

bool VIB::VIBSystem::OpenDevice	(	class DigitalOutput *&	pDigitalOutput,
		int	Index = 0 )

Opens a DigitalOutput device and returns the new device object.

Parameters

pDigitalOutput	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::DigitalOutput *pDigitalOutput = NULL;
if (!pVIBSystem->OpenDevice(pDigitalOutput))
    return -1;

OpenDevice() [5/16]

bool VIB::VIBSystem::OpenDevice	(	class IOScheduler *&	pIOScheduler,
		int	Index = 0 )

Opens a IOScheduler device and returns the new device object.

Parameters

pIOScheduler	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::IOScheduler *pIOScheduler = NULL;
if (!pVIBSystem->OpenDevice(pIOScheduler))
    return -1;

OpenDevice() [6/16]

bool VIB::VIBSystem::OpenDevice

(

class LCD *&

pLCD

)

Opens a LCD device and returns the new device object.

Parameters

pLCD	Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::LCD *pLCD = NULL;
if (!pVIBSystem->OpenDevice(pLCD))
    return -1;

OpenDevice() [7/16]

bool VIB::VIBSystem::OpenDevice

(

class Led *&

pLed

)

Opens a Led device and returns the new device object.

Parameters

pLed	Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Led *pLed = NULL;
if (!pVIBSystem->OpenDevice(pLed))
    return -1;

OpenDevice() [8/16]

bool VIB::VIBSystem::OpenDevice	(	class Multiplexer *&	pMultiplexer,
		int	Index = 0 )

Opens a Multiplexer device and returns the new device object.

Parameters

pMultiplexer	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Multiplexer *pMultiplexer = NULL;
if (!pVIBSystem->OpenDevice(pMultiplexer))
    return -1;

OpenDevice() [9/16]

bool VIB::VIBSystem::OpenDevice

(

class PowerOverEthernet *&

pPowerOverEthernet

)

Opens a PowerOverEthernet device and returns the new device object.

Parameters

pPowerOverEthernet

Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::PowerOverEthernet *pPowerOverEthernet = NULL;
if (!pVIBSystem->OpenDevice(pPowerOverEthernet))
    return -1;

OpenDevice() [10/16]

bool VIB::VIBSystem::OpenDevice	(	class Rs232 *&	pRs232,
		int	Index = 0 )

Opens a Rs232 device and returns the new device object.

Parameters

pRs232	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Rs232 *pRs232 = NULL;
if (!pVIBSystem->OpenDevice(pRs232))
    return -1;

OpenDevice() [11/16]

bool VIB::VIBSystem::OpenDevice	(	class Rs422 *&	pRs422,
		int	Index = 0 )

Opens a Rs422 device and returns the new device object.

Parameters

pRs422	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Rs422 *pRs422 = NULL;
if (!pVIBSystem->OpenDevice(pRs422))
    return -1;

OpenDevice() [12/16]

bool VIB::VIBSystem::OpenDevice

(

class Service *&

pService

)

Opens a Service device and returns the new device object.

Parameters

pService

Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Service *pService = NULL;
if (!pVIBSystem->OpenDevice(pService))
    return -1;

OpenDevice() [13/16]

bool VIB::VIBSystem::OpenDevice	(	class Strobe *&	pStrobe,
		int	Index = 0 )

Opens a Strobe device and returns the new device object.

Parameters

pStrobe	Pointer for storing the new device object
Index	Index of the device on this hardware component

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::Strobe *pStrobe = NULL;
if (!pVIBSystem->OpenDevice(pStrobe))
    return -1;

OpenDevice() [14/16]

bool VIB::VIBSystem::OpenDevice

(

class TriggerGenerator *&

pTriggerGenerator

)

Opens a TriggerGenerator device and returns the new device object.

Parameters

pTriggerGenerator

Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::TriggerGenerator *pTriggerGenerator = NULL;
if (!pVIBSystem->OpenDevice(pTriggerGenerator))
    return -1;

OpenDevice() [15/16]

bool VIB::VIBSystem::OpenDevice

(

class TriggerOverEthernet *&

pTriggerOverEthernet

)

Opens a TriggerOverEthernet device and returns the new device object.

Parameters

pTriggerOverEthernet

Pointer for storing the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

VIB::TriggerOverEthernet *pTriggerOverEthernet = NULL;
if (!pVIBSystem->OpenDevice(pTriggerOverEthernet))
    return -1;

OpenDevice() [16/16]

bool VIB::VIBSystem::OpenDevice	(	eDeviceType	Type,
		int	Index,
		iDevice **	ppNewDevice )

Opens a device and returns a new device object.

After this call there is no relationship between the factory and the device instance. Closing the factory will not close the device, it must be closed manually.

Each hardware device can only be opened once at the same time, except for the VIB::Service device. This is ensured for all processes running on the system. A device must be closed before it can be reopened again.

Parameters

Type	Type of the device
Index	Index of the device on this hardware component, use GetDeviceInfo() to obtain the number of available devices
ppNewDevice	Double pointer for storing the pointer to the new device object

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Example:

//create the instance
VIB::Strobe *pStrobe = NULL;
if ( !pVIBSystem->OpenDevice(VIB::DT_STROBE, 1, (VIB::iDevice**)&pStrobe) )
    goto error;
 
//... use the device object
 
//clean up
if ( !pVIBSystem->CloseDevice(pStrobe) )
    goto error;