Skip to content

Two-Wire Interface#

The Two-Wire Interface camera feature allows you to transmit data between the camera and one or multiple external devices via a two-wire interface (TWI) bus.

You can, e.g., use the camera to control the focus of a TWI-compatible lens.

Using the Feature#

How It Works#

The TWI bus is a two-wire bus, consisting of one serial data line (SDA) and one serial clock line (SCL). These are bidirectional lines.

The camera (master) and the external devices (slaves) are connected to both the data and the clock lines. Data is sent or requested and retrieved by the camera via the data line. The clock line is used for sending clock signals and is controlled by the camera.

Two-Wire Interface Diagram

To make use of the TWI interface outlined above, the camera's GenICam parameters must comply with the specifications of the slave devices.

Camera parameters that help you implement a suitable communication protocol are listed below.

Configuring TWI Communication#

To configure TWI communication between the camera and an external device:

  1. Set the BslTwiBitrate parameter to the bit rate you want to use for TWI, e.g., 50 kbps.
  2. Configure the camera's input-output signals.
    1. Set the LineSelector parameter to the I/O line that should write and read serial data, e.g., Line2. The line must be configured as an input-output line.
    2. Set the BslLineConnection parameter to TwiSda.
    3. Set the LineSelector parameter to the I/O line that should be used for sending clock signals, e.g., Line3. The line must be configured as an input-output line.
    4. Set the BslLineConnection parameter to TwiScl.

Writing and Reading Data#

After you have configured TWI communication, you can write data to the external device and read data from it.

Write and Read Parameters#

The following parameters are involved in both writing and reading data:

  • BslTwiTransferBuffer: The transfer buffer holds the data to be written, and also contains the data that has been read. It can hold up to 16 bytes.
  • BslTwiTransferLength: Indicates the number of bytes that should be transmitted from or to the transfer buffer. When writing, the transfer length specifies the number of bytes the camera should transmit per transaction. When reading, it specifies the number of bytes the camera has received during the last transaction. The maximum value is 16.
  • BslTwiTargetAddress: Indicates the 7-bit target address of the external slave device.

The following parameter is involved in writing data:

  • BslTwiWrite: Execute this command to write the number of bytes specified by the transfer length from the transfer buffer to the target address of the slave device.

The following parameter is involved in reading data:

  • BslTwiRead: Execute this command to read or retrieve the data from the target address of the slave device. The number of bytes read is specified by the transfer length.

Transfer Status#

The transfer status indicates the current status of the data transmission. When the transmission has been completed successfully, the transfer status indicates Success. To retrieve the current transfer status, update the transfer status by executing the BslTwiUpdateTransferStatus command and then get the value of BslTwiTransferStatus.

If the value of BslTwiTransferStatus is Pending, you repeatedly have to update and read the transfer status until the transfer status indicates Success. New data can only be written or read if the transfer status indicates Success.

The transfer status can take the following values:

  • Success: The latest data transmission was successful.
  • Pending: A data transmission is pending.
  • NAKAddress: The camera didn't receive an acknowledge bit that confirms the target address after the latest write or read command. In this case, data transmission failed.
  • NAKData: The camera didn't receive an acknowledge bit for successful data transmission after the latest write command. In this case, data transmission failed.

Pulling I/O Lines Low#

Some TWI slave devices require pulling the I/O lines low before starting operation. If you need to pull an I/O line low, set the BslTwiPullSdaLow parameter or the BslTwiPullSclLow parameter or both to true. While one of them is true, data transmission is disabled.

Sample Code#

// Configure TWI communication
// Set the bit rate to 50 kbps
camera.BslTwiBitrate.SetValue(BslTwiBitrate_Bitrate50kbps);
// Set line 2 to input-output and use it for TWI SDA
camera.LineSelector.SetValue(LineSelector_Line2);
camera.LineMode.SetValue(LineMode_InOut);
camera.BslLineConnection.SetValue(BslLineConnection_TwiSda);
// Set line 3 to input-output and use it for TWI SCL
camera.LineSelector.SetValue(LineSelector_Line3);
camera.LineMode.SetValue(LineMode_InOut);
camera.BslLineConnection.SetValue(BslLineConnection_TwiScl);
// Now, you must implement a suitable communication protocol.
// Camera parameters that help you implement the protocol are listed
// in the "Writing and Reading and Data" section above.

INodeMap& nodemap = camera.GetNodeMap();
// Configure TWI communication
// Set the bit rate to 50 kbps
CEnumParameter(nodemap, "BslTwiBitrate").SetValue("Bitrate50kbps");
// Set line 2 to input-output and use it for TWI SDA
CEnumParameter(nodemap, "LineSelector").SetValue("Line2");
CEnumParameter(nodemap, "LineMode").SetValue("InOut");
CEnumParameter(nodemap, "BslLineConnection").SetValue("TwiSda");
// Set line 3 to input-output and use it for TWI SCL
CEnumParameter(nodemap, "LineSelector").SetValue("Line3");
CEnumParameter(nodemap, "LineMode").SetValue("InOut");
CEnumParameter(nodemap, "BslLineConnection").SetValue("TwiScl");
// Now, you must implement a suitable communication protocol.
// Camera parameters that help you implement the protocol are listed
// in the "Writing and Reading and Data" section above.

// Configure TWI communication
// Set the bit rate to 50 kbps
camera.Parameters[PLCamera.BslTwiBitrate].SetValue(PLCamera.BslTwiBitrate.Bitrate50kbps);
// Set line 2 to input-output and use it for TWI SDA
camera.Parameters[PLCamera.LineSelector].SetValue(PLCamera.LineSelector.Line2);
camera.Parameters[PLCamera.LineMode].SetValue(PLCamera.LineMode.InOut);
camera.Parameters[PLCamera.BslLineConnection].SetValue(PLCamera.BslLineConnection.TwiSda);
// Set line 3 to input-output and use it for TWI SCL
camera.Parameters[PLCamera.LineSelector].SetValue(PLCamera.LineSelector.Line3);
camera.Parameters[PLCamera.LineMode].SetValue(PLCamera.LineMode.InOut);
camera.Parameters[PLCamera.BslLineConnection].SetValue(PLCamera.BslLineConnection.TwiScl);
// Now, you must implement a suitable communication protocol.
// Camera parameters that help you implement the protocol are listed
// in the "Writing and Reading and Data" section above.

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
/* Configure TWI communication */
/* Set the bit rate to 50 kbps */
errRes = PylonDeviceFeatureFromString(hdev, "BslTwiBitrate", "Bitrate50kbps");
CHECK(errRes);
/* Set line 2 to input-output and use it for TWI SDA */
errRes = PylonDeviceFeatureFromString(hdev, "LineSelector", "Line2");
CHECK(errRes);
errRes = PylonDeviceFeatureFromString(hdev, "LineMode", "InOut");
CHECK(errRes);
errRes = PylonDeviceFeatureFromString(hdev, "BslLineConnection", "TwiSda");
CHECK(errRes);
/* Set line 3 to input-output and use it for TWI SCL */
errRes = PylonDeviceFeatureFromString(hdev, "LineSelector", "Line3");
CHECK(errRes);
errRes = PylonDeviceFeatureFromString(hdev, "LineMode", "InOut");
CHECK(errRes);
errRes = PylonDeviceFeatureFromString(hdev, "BslLineConnection", "TwiScl");
CHECK(errRes);
/* Now, you must implement a suitable communication protocol. */
/* Camera parameters that help you implement the protocol are listed */
/* in the "Writing and Reading and Data" section above. */

# Configure TWI communication
# Set the bit rate to 50 kbps
camera.BslTwiBitrate.Value = "Bitrate50kbps"
# Set line 2 to input-output and use it for TWI SDA
camera.LineSelector.Value = "Line2"
camera.LineMode.Value = "InOut"
camera.BslLineConnection.Value = "TwiSda"
# Set line 3 to input-output and use it for TWI SCL
camera.LineSelector.Value = "Line3"
camera.LineMode.Value = "InOut"
camera.BslLineConnection.Value = "TwiScl"
# Now, you must implement a suitable communication protocol.
# Camera parameters that help you implement the protocol are listed
# in the "Writing and Reading and Data" section above.

You can also use the pylon Viewer to easily set the parameters.