Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvDevice Class Reference

Connect, configure and control a GigE Vision or USB3 Vision device. More...

Public Member Functions

virtual ~PvDevice ()
 Destructor.
 
PvDeviceType GetType () const
 Returns the type of the instantiated device. More...
 
virtual PvResult Connect (const PvDeviceInfo *aDeviceInfo)
 Connect to a GigE Vision or USB3 Vision device. More...
 
virtual PvResult Connect (const PvString &aInfo)
 Connect to a GigE Vision or USB3 Vision device. More...
 
PvResult Disconnect ()
 Disconnect the PvDevice object from the GigE Vision or USB3 Vision device to which it is currently connected. More...
 
PvResult StreamEnable (uint32_t aChannel=0)
 Enables streaming on the device. More...
 
PvResult StreamDisable (uint32_t aChannel=0)
 Disables streaming on the device. More...
 
bool IsConnected () const
 Test if this PvDevice is currently connected to a GigE Vision or USB3 Vision device. More...
 
bool IsPleoraPowered () const
 Test if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device. More...
 
PvResult DumpGenICamXML (const PvString &aFilename)
 Save the GigE Vision or USB3 Visio device's GenICam XML file to disk. More...
 
PvResult GetDefaultGenICamXMLFilename (PvString &aFilename)
 Returns a good default filename to use with DumpGenICamXML. More...
 
PvGenParameterArrayGetParameters ()
 Get the parameters used to control the GigE Vision or USB3 Vision device to which you are connected. More...
 
PvGenParameterArrayGetCommunicationParameters ()
 Get the parameters used to define how PvDevice connects to and communicates with the device. More...
 
PvResult ReadMemory (int64_t aAddress, unsigned char *aDestination, int64_t aByteCount)
 Reads bytes starting at a specific register address on the GigE Vision or USB3 Vision device. More...
 
PvResult WriteMemory (int64_t aAddress, const unsigned char *aSource, int64_t aByteCount)
 Writes bytes starting at a specific register address on the GigE Vision or USB3 Vision device. More...
 
PvResult WaitForMessagingChannelIdle (uint32_t aTimeout)
 Waits for the messaging channel to become idle. More...
 
PvResult RegisterEventSink (PvDeviceEventSink *aEventSink)
 Register an event sink used for callbacks. More...
 
PvResult UnregisterEventSink (PvDeviceEventSink *aEventSink)
 Unregister an event sink. More...
 
uint32_t GetHeartbeatThreadPriority () const
 Get the priority of the heartbeat thread. More...
 
PvResult SetHeartbeatThreadPriority (uint32_t aPriority)
 Set the priority of the heartbeat thread. More...
 
uint32_t GetInterruptLinkThreadPriority () const
 Get the priority of the interrupt link thread. More...
 
PvResult SetInterruptLinkThreadPriority (uint32_t aPriority)
 Set the priority of the interrupt link thread. More...
 
uint32_t GetInterruptQueueThreadPriority () const
 Get the priority of the interrupt queue thread. More...
 
PvResult SetInterruptQueueThreadPriority (uint32_t aPriority)
 Set the priority of the interrupt queue thread. More...
 
uint32_t GetPayloadSize ()
 Returns the payload size the device is currently configured to stream with. More...
 
PvResult GetUniqueID (PvString &aID)
 Returns a unique string identifier for the device. More...
 

Static Public Member Functions

static PvDeviceCreateAndConnect (const PvDeviceInfo *aDeviceInfo, PvResult *aResult)
 Dynamically allocates a PvDevice of the right type. More...
 
static PvDeviceCreateAndConnect (const PvString &aInfo, PvResult *aResult)
 Dynamically allocates a PvDevice of the right type. More...
 
static void Free (PvDevice *aDevice)
 Frees an object allocated with CreateAndConnect. More...
 

Protected Member Functions

 PvDevice ()
 Constructor.
 

Detailed Description

Connect, configure and control a GigE Vision or USB3 Vision device.

It is not possible to instantiate a generic PvDevice. PvDeviceGEV and PvDeviceU3V can be instantiated directly.

If order to write hybrid code one could use the static CreateAndConnect methods. These methods dynamically allocated a PvDevice of the right type to connect to the requested device. Just remember to free the dynamically allocated device object using the static Free method.

Member Function Documentation

PvResult PvDevice::Connect ( const PvDeviceInfo aDeviceInfo)
virtual

Connect to a GigE Vision or USB3 Vision device.

The Connect method connects to a GigE Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.

Parameters
[in]aDeviceInfoThe GigE Vision device's network connectivity information; a PvDeviceInfo object.
Returns
Includes:

Reimplemented in PvDeviceU3V, and PvDeviceGEV.

PvResult PvDevice::Connect ( const PvString aInfo)
virtual

Connect to a GigE Vision or USB3 Vision device.

If you know the GigE Vision device's IP address, MAC address or DeviceUserID, you can use this method to connect to it.

If you know the USB3 Vision device's GUID or DeviceUserID, you can use this method to connect it.

  1. If aInfo contains an IP address, the connection attempt connecting a GigE Vision device is direct.
  2. If aInfo contains a MAC address:
    • An internal PvSystem is used to find all reachable GigE Vision devices
    • Found devices are browsed, looking for a match on the MAC address
    • If the device is found, connection is attempted.
  3. If aInfo contains a USB3 Vision GUID:
    • All USB3 Vision devices are enumerated
    • Found devices are browsed, looking for a match on the GUID
    • If the device is found, connection is attempted.
  4. If aInfo contains a device user ID:
    • All GigE Vision and USB3 Vision are enumerated
    • Found devices are browsed, looking for a match on device user ID
    • If the device is found, connection is attempted.
Parameters
[in]aInfoInformation that uniquely identifies the device. You may use one of the following:
  • GigE Vision device's MAC address. Use the form 00:11:22:33:44:5F.
  • GigE Vision device's IP Address. Use the form 192.168.1.114.
  • GigE Vision or USB3 Vision device's DeviceUserID.
  • USB3 Vision GUID.
Returns
Includes:

Reimplemented in PvDeviceGEV, and PvDeviceU3V.

PvDevice * PvDevice::CreateAndConnect ( const PvDeviceInfo aDeviceInfo,
PvResult aResult 
)
static

Dynamically allocates a PvDevice of the right type.

This static method takes a generic PvDeviceInfo, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.

Objects allocated with CreateAndConnect should be freed with PvDevice::Free.

Parameters
[in]aDeviceInfoPointer to the device information used to connect the device.
[out]aResultOutcome of the operation:
Returns
A pointer to the new object on success, NULL on failure. See aResult for more information on the failure.
PvDevice * PvDevice::CreateAndConnect ( const PvString aInfo,
PvResult aResult 
)
static

Dynamically allocates a PvDevice of the right type.

This static method takes a string identifying a device, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.

Objects allocated with CreateAndConnect should be freed with PvDevice::Free.

Parameters
[in]aInfoString identifying the device. See PvDevice::Connect for more information.
[out]aResultOutcome of the operation.
Returns
A pointer to the new object on success, NULL on failure. See aResult for more information on the failure.
PvResult PvDevice::Disconnect ( )

Disconnect the PvDevice object from the GigE Vision or USB3 Vision device to which it is currently connected.

Returns
Includes:
See also
Connect
PvResult PvDevice::DumpGenICamXML ( const PvString aFilename)

Save the GigE Vision or USB3 Visio device's GenICam XML file to disk.

If the XML is stored in a zip file on the device, the zip file containing the XML is saved on the disk.

Parameters
aFilenameThe file's name.
Returns
Includes:
void PvDevice::Free ( PvDevice aDevice)
static

Frees an object allocated with CreateAndConnect.

Even though calling delete on a PvDevice created with CreateAndConnect should work in most cases, sometime it is necessary to call "delete" in the same context where "new" was called to avoid false positives on memory leaks.

It is a good practice to use this method to free a PvDevice allocated with CreateAndConnect.

Parameters
[in]aDevicePointer to the device object to delete.
PvGenParameterArray * PvDevice::GetCommunicationParameters ( )

Get the parameters used to define how PvDevice connects to and communicates with the device.

For a listing of all the available parameters, refer to GEV Device Communication Parameters or U3V Device Communication Parameters

Returns
The parameters used to define how PvDevice connects to and communicates with the device
PvResult PvDevice::GetDefaultGenICamXMLFilename ( PvString aFilename)

Returns a good default filename to use with DumpGenICamXML.

The filename is built from the URL that was used in order to locate the GenICam XML file of the device.

Parameters
aFilenameA default filename built from the device XML location URL.
Returns
Includes:
uint32_t PvDevice::GetHeartbeatThreadPriority ( ) const

Get the priority of the heartbeat thread.

See SetHeartbeatThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread
uint32_t PvDevice::GetInterruptLinkThreadPriority ( ) const

Get the priority of the interrupt link thread.

See SetInterruptLinkThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread
uint32_t PvDevice::GetInterruptQueueThreadPriority ( ) const

Get the priority of the interrupt queue thread.

See SetInterruptQueueThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread
PvGenParameterArray * PvDevice::GetParameters ( )

Get the parameters used to control the GigE Vision or USB3 Vision device to which you are connected.

Each device provides its own GenICam XML file with parameters describing its behaviour referred to as features. The PvGenParameterArray object returned by this method provides an interface to these features.

Returns
The parameters used to control the GigE Vision device to which you are connected
uint32_t PvDevice::GetPayloadSize ( )

Returns the payload size the device is currently configured to stream with.

This method attempts to read the GenICam PayloadSize parameter of the device. If the operation fails the payload size is computed from width, height and pixel format as a fall back. If even this fails, a value that is still valid to allocate buffers is finally returned.

Returns
The recommended payload size. 0 can only be returned if the device is not connected.
PvDeviceType PvDevice::GetType ( ) const

Returns the type of the instantiated device.

Returns
Type of device controller.
PvResult PvDevice::GetUniqueID ( PvString aID)

Returns a unique string identifier for the device.

Parameters
[out]aIDUnique string identifier for the device.
Returns
Includes:
bool PvDevice::IsConnected ( ) const

Test if this PvDevice is currently connected to a GigE Vision or USB3 Vision device.

Returns
True if this PvDevice is currently connected to a GigE Vision or USB3 Vision device otherwise, false.
bool PvDevice::IsPleoraPowered ( ) const

Test if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device.

Returns
True if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device, false otherwise.
PvResult PvDevice::ReadMemory ( int64_t  aAddress,
unsigned char *  aDestination,
int64_t  aByteCount 
)

Reads bytes starting at a specific register address on the GigE Vision or USB3 Vision device.

See warnings about accessing the register map directly in WriteMemory.

Parameters
[in]aAddressStart address of the read memory operation (mod 4).
[out]aDestinationBuffer where to write data read from the device.
[in]aByteCountBytes to read from the device (mod 4, non 0)
Returns
Includes:
PvResult PvDevice::RegisterEventSink ( PvDeviceEventSink aEventSink)

Register an event sink used for callbacks.

Parameters
[in]aEventSinkA pointer to the event sink.
Returns
Includes:
PvResult PvDevice::SetHeartbeatThreadPriority ( uint32_t  aPriority)

Set the priority of the heartbeat thread.

The heartbeat thread priority is critical to most applications. This thread must never starve against any other system thread to the risk of losing the device connection.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See GetHeartbeatThreadPriority

Parameters
[in]aPrioritySee PvPipeline::SetBufferHandlingThreadPriority for description of the supported values
Returns
Includes:
PvResult PvDevice::SetInterruptLinkThreadPriority ( uint32_t  aPriority)

Set the priority of the interrupt link thread.

Interrupt link thread receives messaging channel packets from the device, sends acknowledge back and queues the message in the interrupt queue. Process and callbacks are not done from this thread.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See GetInterruptLinkThreadPriority

Parameters
[in]aPrioritySee PvPipeline::SetBufferHandlingThreadPriority for description of the supported values
Returns
Includes:
PvResult PvDevice::SetInterruptQueueThreadPriority ( uint32_t  aPriority)

Set the priority of the interrupt queue thread.

This thread is simply used to fire/invoke the OnLinkDisconnected and OnLinkReconnected PvDeviceEventSink events.

This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.

See GetInterruptQueueThreadPriority

Parameters
[in]aPrioritySee PvPipeline::SetBufferHandlingThreadPriority for description of the supported values
Returns
Includes:
PvResult PvDevice::StreamDisable ( uint32_t  aChannel = 0)

Disables streaming on the device.

For GigE Vision devices, this takes care of resetting the TLParamsLocked so that changes to streaming related parameters are possible again.

For USB3 Vision devices, this takes care of the TLParamsLocked and sets the streaming enable bit on the device.

StreamDisable should be called after the AcquisitionStop GenICam command has been executed and all images have been received.

Parameters
[in]aChannelThe channel on which to enable streaming.
Returns
Includes:
PvResult PvDevice::StreamEnable ( uint32_t  aChannel = 0)

Enables streaming on the device.

For GigE Vision devices, this takes care of setting the TLParamsLocked so that changes to streaming related parameters are prevent in the GenICam interface of the device.

For USB3 Vision devices, this takes care of the TLParamsLocked, configures the driver for streaming and sets the streaming enable bit on the device.

After calling StreamEnable, the user must still execute the AcquisitionStart GenICam command of the device to instruct the device to begin acquisition.

Parameters
[in]aChannelThe channel on which to enable streaming.
Returns
Includes:
PvResult PvDevice::UnregisterEventSink ( PvDeviceEventSink aEventSink)

Unregister an event sink.

Parameters
[in]aEventSinkA pointer to the event sink.
Returns
Includes:
PvResult PvDevice::WaitForMessagingChannelIdle ( uint32_t  aTimeout)

Waits for the messaging channel to become idle.

This method returns once the host-side messaging channel in-queue is empty or aTimeout (ms) has elapsed.

Parameters
[in]aTimeoutMaximum time to wait, in ms.
Returns
Includes:
PvResult PvDevice::WriteMemory ( int64_t  aAddress,
const unsigned char *  aSource,
int64_t  aByteCount 
)

Writes bytes starting at a specific register address on the GigE Vision or USB3 Vision device.

This is an advanced method and is rarely needed. In general, most users should instead use the device's GenICam interface which can be obtained through GetParameters.

This method let advanced users control third-party GigE Vision devices with poor or incomplete GenICam XML files. The methods presume detailed working knowledge of the GigE Vision device's register map. Since the WriteMemory method bypasses the GenICam interface and the SDK's cache of values, incorrect use may cause indeterminate results.

Not all GigE Vision devices are supporting the write memory operation. When using this method on a Gig Vision device not supporting write memory operations, the write is broken down in as many write register commands as required.

Parameters
[in]aAddressStart address of the write memory operation (mod 4).
[out]aSourceBuffer holding the data to write to the device.
[in]aByteCountBytes to write to the device (mod 4, non 0)
Returns
Includes:

The documentation for this class was generated from the following files:

Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com