Provides I2C bus communication interface for device serial ports. More...

#include <PvDeviceI2CBus.h>

Public Member Functions
	PvDeviceI2CBus ()
	Constructor.

	~PvDeviceI2CBus ()
	Destructor.

PvResult	Open (IPvDeviceAdapter *aDevice, PvDeviceSerial aPort=PvDeviceSerialBulk0)
	Opens the I2C bus on the specified device serial port. More...

PvResult	Close ()
	Closes the I2C bus connection. More...

bool	IsOpened ()
	Checks if the I2C bus is currently opened. More...

PvResult	BurstWrite (unsigned char aSlaveAddress, const unsigned char *aBuffer, uint32_t aBufferSize, bool aFastMode=true)
	Performs a burst write operation to an I2C slave device. More...

PvResult	IndirectBurstWrite (unsigned char aSlaveAddress, unsigned char aOffset, const unsigned char *aBuffer, uint32_t aBufferSize, bool aFastMode=true)
	Performs an indirect burst write operation with offset addressing. More...

PvResult	BurstRead (unsigned char aSlaveAddress, unsigned char *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true)
	Performs a burst read operation from an I2C slave device. More...

PvResult	IndirectBurstRead (unsigned char aSlaveAddress, unsigned char aOffset, unsigned char *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true, bool aUseCombinedFormat=true)
	Performs an indirect burst read operation with offset addressing. More...

PvResult	MasterTransmitter (uint8_t aSlaveAddress, const uint8_t *aBuffer, uint32_t aBufferSize, bool aFastMode=true, bool aGenerateStopCondition=true)
	Transmits data as I2C master. More...

PvResult	MasterReceiverAfterFirstByte (uint8_t aSlaveAddress, uint8_t *aBuffer, uint32_t aBufferSize, uint32_t &aBytesRead, bool aFastMode=true, bool aGenerateStopCondition=true)
	Receives data as I2C master after the first byte has been sent. More...

Static Public Member Functions
static bool	IsSupported (IPvDeviceAdapter *aDevice, PvDeviceSerial aPort=PvDeviceSerialBulk0)
	Checks if I2C bus communication is supported on the specified device port. More...

Detailed Description

Provides I2C bus communication interface for device serial ports.

I2C serial controller.

Remarks: This class enables I2C protocol communication through a device's serial port, supporting various transfer modes including burst read/write and master transmit/receive.

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:

PC calls BurstWrite.
PC passes entire message to the device via Ethernet.
BurstWrite blocks.
Device to camera: [Start condition] aSlaveAddress [Write - SDA low]
Camera to device: Acknowledge
Device to camera: [First 8 bits of aBuffer]
Camera to device: Acknowledge
Device to camera: [Next 8 bits of aBuffer]
Camera to Device: Acknowledge
...
Device to camera: [Last 8 bits of aBuffer]
Camera to device: Acknowledge
Device to camera: [Stop condition]
Device reports the successful transmission of the message to the PC (via Ethernet).
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:

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

Member Function Documentation

◆ BurstRead()

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

Performs a burst read operation from an I2C slave device.

Retrieve a reply from a camera.

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[out]	aBuffer	Buffer to receive the read data.
[in]	aBufferSize	Maximum number of bytes to read.
[out]	aBytesRead	Number of bytes actually read.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.

Returns: Result of the operation.

Parameters

[in]	aSlaveAddress	See BurstWrite.
[out]	aBuffer	A pointer to the data being received from the camera.
[in]	aBufferSize	The buffer's anticipated size. BurstRead never returns with a buffer size larger than the originally specified aBufferSize.
[out]	aBytesRead	The number of bytes read.
[in]	aFastMode	See BurstWrite.

Returns: PvResult

◆ BurstWrite()

PvResult PvDeviceI2CBus::BurstWrite	(	unsigned char	aSlaveAddress,
		const unsigned char *	aBuffer,
		uint32_t	aBufferSize,
		bool	aFastMode = `true`
	)

Performs a burst write operation to an I2C slave device.

Send a command to the camera.

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[in]	aBuffer	Buffer containing data to write.
[in]	aBufferSize	Number of bytes to write.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.

Returns: Result of the operation.

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]	aSlaveAddress	The camera's I2C slave address (7-bits).
[in]	aBuffer	A pointer to the data being sent to the camera.
[in]	aBufferSize	The buffer's size.
[in]	aFastMode	The I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).

Returns: PvResult

◆ Close()

PvResult PvDeviceI2CBus::Close ( )

Closes the I2C bus connection.

Close the I2C channel to the device.

Returns: Result of the operation.; PvResult

◆ IndirectBurstRead()

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

Performs an indirect burst read operation with offset addressing.

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

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[in]	aOffset	The register offset/address to read from.
[out]	aBuffer	Buffer to receive the read data.
[in]	aBufferSize	Maximum number of bytes to read.
[out]	aBytesRead	Number of bytes actually read.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.
[in]	aUseCombinedFormat	If true, use combined format for address and data. Default is true.

Returns: Result of the operation.

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

Parameters

[in]	aSlaveAddress	See BurstRead.
[in]	aOffset	See IndirectBurstWrite.
[out]	aBuffer	See BurstRead.
[in]	aBufferSize	See BurstRead.
[in]	aBytesWritten	See BurstRead.
[in]	aFastMode	See BurstRead.
[in]	aUseCombinedFormat	True if a stop should be issued between the write and read sequence; false if no stop is required.

Returns: PvResult

◆ IndirectBurstWrite()

PvResult PvDeviceI2CBus::IndirectBurstWrite	(	unsigned char	aSlaveAddress,
		unsigned char	aOffset,
		const unsigned char *	aBuffer,
		uint32_t	aBufferSize,
		bool	aFastMode = `true`
	)

Performs an indirect burst write operation with offset addressing.

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

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[in]	aOffset	The register offset/address to write to.
[in]	aBuffer	Buffer containing data to write.
[in]	aBufferSize	Number of bytes to write.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.

Returns: Result of the operation.

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]	aSlaveAddress	See BurstWrite.
[in]	aOffset	The address offset of the slave in question.
[in]	aBuffer	See BurstWrite.
[in]	aBufferSize	See BurstWrite.
[in]	aFastMode	See BurstWrite.

Returns: PvResult

◆ IsOpened()

bool PvDeviceI2CBus::IsOpened ( )

Checks if the I2C bus is currently opened.

Test whether this class has been setup/opened properly.

Returns: True if opened, false otherwise.; true if opened, false otherwise

◆ IsSupported()

bool PvDeviceI2CBus::IsSupported	(	IPvDeviceAdapter *	aDevice,
		PvDeviceSerial	aPort = `PvDeviceSerialBulk0`
	)

static

Checks if I2C bus communication is supported on the specified device port.

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]	aDevice	The device adapter to check.
[in]	aPort	The serial port to check. Default is PvDeviceSerialBulk0.

Returns: True if supported, false otherwise.

Parameters

[in]	aDevice	a connected device to test support for I2C on
[in]	aPort	which port to test I2C support for (default Bulk0 if not specified)

Returns: true if I2C is supported and available

◆ MasterReceiverAfterFirstByte()

PvResult PvDeviceI2CBus::MasterReceiverAfterFirstByte	(	uint8_t	aSlaveAddress,
		uint8_t *	aBuffer,
		uint32_t	aBufferSize,
		uint32_t &	aBytesRead,
		bool	aFastMode = `true`,
		bool	aGenerateStopCondition = `true`
	)

Receives data as I2C master after the first byte has been sent.

Receive 2nd gen Bulk or I2C as master.

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[out]	aBuffer	Buffer to receive the data.
[in]	aBufferSize	Maximum number of bytes to receive.
[out]	aBytesRead	Number of bytes actually received.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.
[in]	aGenerateStopCondition	If true, generate stop condition after reception. Default is true.

Returns: Result of the operation.

Parameters

[in]	aSlaveAddress	The camera's I2C slave address (7-bits).
[in]	aBuffer	A pointer to the data being sent to the camera.
[in]	aBufferSize	The buffer's size.
[in]	aBytesRead	Number of bytes read.
[in]	aFastMode	The I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).
[in]	aGenerateStopCondition	True if stop condition must be set

Returns: PvResult

◆ MasterTransmitter()

PvResult PvDeviceI2CBus::MasterTransmitter	(	uint8_t	aSlaveAddress,
		const uint8_t *	aBuffer,
		uint32_t	aBufferSize,
		bool	aFastMode = `true`,
		bool	aGenerateStopCondition = `true`
	)

Transmits data as I2C master.

Transmit Bulk or I2C as master.

Parameters

[in]	aSlaveAddress	The 7-bit I2C slave address.
[in]	aBuffer	Buffer containing data to transmit.
[in]	aBufferSize	Number of bytes to transmit.
[in]	aFastMode	If true, use fast mode (400 kHz), otherwise standard mode (100 kHz). Default is true.
[in]	aGenerateStopCondition	If true, generate stop condition after transmission. Default is true.

Returns: Result of the operation.

Parameters

[in]	aSlaveAddress	The camera's I2C slave address (7-bits).
[in]	aBuffer	A pointer to the data being sent to the camera.
[in]	aBufferSize	The buffer's size.
[in]	aFastMode	The I2C bus speed. True for I2C's Fast mode (400 Kbits/s); false for Standard mode (100 kbits/s).
[in]	aGenerateStopCondition	true if stop condition must be set

Returns: PvResult

◆ Open()

PvResult PvDeviceI2CBus::Open	(	IPvDeviceAdapter *	aDevice,
		PvDeviceSerial	aPort = `PvDeviceSerialBulk0`
	)

Opens the I2C bus on the specified device serial port.

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]	aDevice	The device adapter providing access to the device.
[in]	aPort	The serial port to use for I2C communication. Default is PvDeviceSerialBulk0.

Returns: Result of the operation.

Parameters

[in]	aDevice	A pointer to connected device to open an I2C channel to
[in]	aPort	Port 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:

PvDeviceI2CBus.h
PvDeviceI2CBus.cpp

eBUS SDK v7.0.1.7536 API

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ BurstRead()

◆ BurstWrite()

◆ Close()

◆ IndirectBurstRead()

◆ IndirectBurstWrite()

◆ IsOpened()

◆ IsSupported()

◆ MasterReceiverAfterFirstByte()

◆ MasterTransmitter()

◆ Open()