Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvDeviceI2CBus Class Reference

I2C serial controller. More...

Public Member Functions

 PvDeviceI2CBus ()
 Constructor.
 
 ~PvDeviceI2CBus ()
 Destructor.
 
PvResult Open (IPvDeviceAdapter *aDevice, PvDeviceSerial aPort=PvDeviceSerialBulk0)
 Open an I2C channel to the device on given port I2C should already be setup and configured. Calling open does not setup I2C and configure it, it simply uses it for communication aDevice should be connected already. Will return error if device is not connect or I2C is not supported or unavailable. More...
 
PvResult Close ()
 Close the I2C channel to the device. More...
 
bool IsOpened ()
 Test whether this class has been setup/opened properly. More...
 
PvResult BurstWrite (unsigned char aSlaveAddress, const unsigned char *aBuffer, uint32_t aBufferSize, bool aFastMode=true)
 Send a command to the camera. More...
 
PvResult IndirectBurstWrite (unsigned char aSlaveAddress, unsigned char aOffset, const unsigned char *aBuffer, uint32_t aBufferSize, bool aFastMode=true)
 Send a command to the camera (for cameras with memory offsets). More...
 
PvResult BurstRead (unsigned char aSlaveAddress, unsigned char *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true)
 Retrieve a reply from a camera. More...
 
PvResult IndirectBurstRead (unsigned char aSlaveAddress, unsigned char aOffset, unsigned char *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true, bool aUseCombinedFormat=true)
 Retrieve a reply from a camera (for cameras with memory offsets). More...
 
PvResult MasterTransmitter (uint8_t aSlaveAddress, const uint8_t *aBuffer, uint32_t aBufferSize, bool aFastMode=true, bool aGenerateStopCondition=true)
 Transmit Bulk or I2C as master. More...
 
PvResult MasterReceiverAfterFirstByte (uint8_t aSlaveAddress, uint8_t *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true, bool aGenerateStopCondition=true)
 Receive 2nd gen Bulk or I2C as master. More...
 

Static Public Member Functions

static bool IsSupported (IPvDeviceAdapter *aDevice, PvDeviceSerial aPort=PvDeviceSerialBulk0)
 Test whether the device supports I2C and if it is available Note that this function does not set I2C or the correct BulkSelector For example if I2C is only supported on Bulk1, then before calling this function, set BulkSelector to Bulk1 then test whether I2C is supported on Bulk1. More...
 

Detailed Description

I2C serial controller.

The PvDeviceI2CBus lets you send commands to your camera and receive the camera's replies.

I2C uses the concept of a master and slave, where the master controls the clock and initiates reads and writes. For PvDeviceI2CBus, the device is the I2C master. The I2C slave is typically a camera, but could be any I2C-capable device connected to the device.

The PvDeviceI2CBus methods manage the entire Pleora Video Interface and camera communication required to send a message to the camera, but not the configuration and setup of I2C (those are done through GenICam parameters) Before using this class to communicate, I2C should be setup and configured through GenICam parameters For example BulkMode needs to be set to I2C on the correct serial port The BurstWrite method involves the following transaction:

  1. PC calls BurstWrite.
  2. PC passes entire message to the device via Ethernet.
  3. BurstWrite blocks.
  4. Device to camera: [Start condition] aSlaveAddress [Write - SDA low]
  5. Camera to device: Acknowledge
  6. Device to camera: [First 8 bits of aBuffer]
  7. Camera to device: Acknowledge
  8. Device to camera: [Next 8 bits of aBuffer]
  9. Camera to Device: Acknowledge
  10. ...
  11. Device to camera: [Last 8 bits of aBuffer]
  12. Camera to device: Acknowledge
  13. Device to camera: [Stop condition]
  14. Device reports the successful transmission of the message to the PC (via Ethernet).
  15. BurstWrite method unblocks (returns).

For the complete hardware-level transactions for all PvDeviceI2CBus methods, see your hardware guide.

To send I2C-protocol serial commands to your camera:

  1. Create an I2C serial controller. Use PvDeviceI2CBus::PvDeviceI2CBus.
  2. Send a command to the camera. Use BurstWrite.
  3. Test to ensure the message send succeeded. Check the PvResult returned by BurstWrite.
  4. Retrieve the camera's reply. Use BurstRead.
  5. Test to ensure the message retrieval succeeded. Check the PvResult returned by BurstRead.
  6. Test the content of the message from the camera. Use aBuffer and aBufferSize parameters and your own code.

Member Function Documentation

PvResult PvDeviceI2CBus::BurstRead ( unsigned char  aSlaveAddress,
unsigned char *  aBuffer,
uint32_t  aBufferSize,
uint32_t &  aBytesRead,
bool  aFastMode = true 
)

Retrieve a reply from a camera.

Parameters
[in]aSlaveAddressSee BurstWrite.
[out]aBufferA pointer to the data being received from the camera.
[in]aBufferSizeThe buffer's anticipated size. BurstRead never returns with a buffer size larger than the originally specified aBufferSize.
[out]aBytesReadThe number of bytes read.
[in]aFastModeSee BurstWrite.
Returns
PvResult
PvResult PvDeviceI2CBus::BurstWrite ( unsigned char  aSlaveAddress,
const unsigned char *  aBuffer,
uint32_t  aBufferSize,
bool  aFastMode = true 
)

Send a command to the camera.

Before using BurstWrite, confirm it meets your camera's requirements: If your I2C-capable camera uses a single memory location (for the entire streamed message, use BurstWrite and BurstRead; if it uses sequential memory (storing messages in a series of bytes in memory), use IndirectBurstWrite and IndirectBurstRead.

Note that current limitation of I2C write is for 512 bytes per message

The BurstWrite method sends a message, aBuffer, to the I2C-capable camera defined by aSlaveAddress.

If the camera doesn't acknowledge a byte during the burst write, BurstWrite terminates early, but returns PvResult::Code::OK.

Parameters
[in]aSlaveAddressThe camera's I2C slave address (7-bits).
[in]aBufferA pointer to the data being sent to the camera.
[in]aBufferSizeThe buffer's size.
[in]aFastModeThe I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).
Returns
PvResult
PvResult PvDeviceI2CBus::Close ( )

Close the I2C channel to the device.

Returns
PvResult
PvResult PvDeviceI2CBus::IndirectBurstRead ( unsigned char  aSlaveAddress,
unsigned char  aOffset,
unsigned char *  aBuffer,
uint32_t  aBufferSize,
uint32_t &  aBytesWritten,
bool  aFastMode = true,
bool  aUseCombinedFormat = true 
)

Retrieve a reply from a camera (for cameras with memory offsets).

The IndirectBurstRead is to BurstRead method (for reading) as IndirectBurstWrite is to BurstWrite (for writing).

Parameters
[in]aSlaveAddressSee BurstRead.
[in]aOffsetSee IndirectBurstWrite.
[out]aBufferSee BurstRead.
[in]aBufferSizeSee BurstRead.
[in]aBytesWrittenSee BurstRead.
[in]aFastModeSee BurstRead.
[in]aUseCombinedFormatTrue if a stop should be issued between the write and read sequence; false if no stop is required.
Returns
PvResult
PvResult PvDeviceI2CBus::IndirectBurstWrite ( unsigned char  aSlaveAddress,
unsigned char  aOffset,
const unsigned char *  aBuffer,
uint32_t  aBufferSize,
bool  aFastMode = true 
)

Send a command to the camera (for cameras with memory offsets).

The IndirectBurstWrite method is very similar to the BurstWrite method, with the following exceptions:

  • This method includes a memory offset, aOffset, that lets you write to a series of memory addresses in the camera.

Before using this method, see BurstWrite.

Parameters
[in]aSlaveAddressSee BurstWrite.
[in]aOffsetThe address offset of the slave in question.
[in]aBufferSee BurstWrite.
[in]aBufferSizeSee BurstWrite.
[in]aFastModeSee BurstWrite.
Returns
PvResult
bool PvDeviceI2CBus::IsOpened ( )

Test whether this class has been setup/opened properly.

Returns
true if opened, false otherwise
bool PvDeviceI2CBus::IsSupported ( IPvDeviceAdapter aDevice,
PvDeviceSerial  aPort = PvDeviceSerialBulk0 
)
static

Test whether the device supports I2C and if it is available Note that this function does not set I2C or the correct BulkSelector For example if I2C is only supported on Bulk1, then before calling this function, set BulkSelector to Bulk1 then test whether I2C is supported on Bulk1.

Parameters
[in]aDevicea connected device to test support for I2C on
[in]aPortwhich port to test I2C support for (default Bulk0 if not specified)
Returns
true if I2C is supported and available
PvResult PvDeviceI2CBus::MasterReceiverAfterFirstByte ( uint8_t  aSlaveAddress,
uint8_t *  aBuffer,
uint32_t  aBufferSize,
uint32_t &  aBytesRead,
bool  aFastMode = true,
bool  aGenerateStopCondition = true 
)

Receive 2nd gen Bulk or I2C as master.

Parameters
[in]aSlaveAddressThe camera's I2C slave address (7-bits).
[in]aBufferA pointer to the data being sent to the camera.
[in]aBufferSizeThe buffer's size.
[in]aBytesReadNumber of bytes read.
[in]aFastModeThe I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).
[in]aGenerateStopConditionTrue if stop condition must be set
Returns
PvResult
PvResult PvDeviceI2CBus::MasterTransmitter ( uint8_t  aSlaveAddress,
const uint8_t *  aBuffer,
uint32_t  aBufferSize,
bool  aFastMode = true,
bool  aGenerateStopCondition = true 
)

Transmit Bulk or I2C as master.

Parameters
[in]aSlaveAddressThe camera's I2C slave address (7-bits).
[in]aBufferA pointer to the data being sent to the camera.
[in]aBufferSizeThe buffer's size.
[in]aFastModeThe I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).
[in]aGenerateStopConditiontrue if stop condition must be set
Returns
PvResult
PvResult PvDeviceI2CBus::Open ( IPvDeviceAdapter aDevice,
PvDeviceSerial  aPort = PvDeviceSerialBulk0 
)

Open an I2C channel to the device on given port I2C should already be setup and configured. Calling open does not setup I2C and configure it, it simply uses it for communication aDevice should be connected already. Will return error if device is not connect or I2C is not supported or unavailable.

Parameters
[in]aDeviceA pointer to connected device to open an I2C channel to
[in]aPortPort to use for I2C (Bulk0 default)
Returns
PvResult will return error if device is not connected or I2C is not supported or unavailable

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

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