Device Communication

Contents

• Overview
• USB
  • Control
  • Streaming
• Ethernet
  • Control
  • Streaming

Overview

When connecting to a thermal camera the SDK establishes two separate communication channels:

• Control - a bidirectional channel that the SDK uses to send commands to the device. It is also utilized to retrieve small sized bits of information.
• Streaming - a unidirectional channel that is used to stream the thermal data from the device to the SDK.

Communication channels between the SDK and the thermal camera.

Depending on your chosen connection type, USB or Ethernet, these channels use different protocols/mechanisms to transfer data. In the case of Linux this may also depend on the type of your device.

The data stream from the device is uncompressed for both the USB and Ethernet connections. Please keep this in mind because this poses some demands on your USB and network hardware especially if you are operating multiple devices at once.

Another hardware requirement to be aware of is the power draw of the devices when connected via USB. This is typically not an issue with your average computer or laptop but can pose a limiting factor when working with embedded devices.

USB

Control

The SDK uses the Human Interface Device protocol (HID) to send commands to your device. The HID protocol is, for example, used by input devices like your mouse and keyboard.

Streaming

Once you connect a device to your computer via USB it is recognized by the operating system as a USB camera. You can access its data stream with programs like the VLC media player or guvcview. When you open it as a capture device you will, however, get something like this:

Data stream from a PI640.

Note

On Linux you will not be able to access the data stream of Xi 80, Xi 410(MT) and Xi 1M devices in this way. This is due to the USB transfer mode used by these devices which is not supported by Video for Linux v2 (V4L2) kernel driver.

There are several important points to note:

• The raw data needs to be processed by the SDK in order to get useful thermal information. This can then be converted into false color images.
• The frame dimensions (width and height) are slightly larger than those specified in the Supported Cameras section in the Features chapter. These additional rows or columns contain the frame metadata that also requires decoding by the SDK.

Note

You can use the frame dimensions from above to estimate the USB bandwidth required by the device with the chosen video format:
bandwidth in bytes per second = (width x height x 2) / framerate

As an alternative, you can take a look at the format definitions file. It is a text file that contains all the available video formats for the different device types. It specifies the output formats Out with their corresponding input formats In as a tuple of in the form of width height framerate.

The devices use two different USB transfer methods to stream the thermal data:

• The Xi 80, Xi 410(MT) and the Xi 1M use the USB bulk transfer mode
• while all other devices use the USB isochronous transfer mode.

This has no implications on Windows since the used Direct Show layer seamlessly supports both transfer modes. On Linux, however, the default Video for Linux v2 (V4L2) kernel driver for such applications just supports isochronous USB data transfer. Because of this the SKD accesses the data stream of the bulk transfer devices through the lower level USB kernel driver instead of V4L2. This is also the reason why you are not able to open their data streams with programs like the VLC player.

Linux video driver hierarchy.

Ethernet

Before you can use your Ethernet capable device you first have to adjust the on-device configuration to your network environment. Please note, that this configuration can only handle static IP addresses. To set the configuration you need the following pieces of information:

• Device IP address that the device assigns to itself on the network.
• Destination IP address & destination port as the socket the device sends its data to. This is typically the machine that runs the SDK based application.
• Subnet mask of the network in which the device and destination machine are located.

You can either utilize the tool otc_configure_ethernet or the PixConnect to change these on-device settings.

Attention

Take care when adjusting the on-device network configuration. Make sure the input is correct and you are not using the same IP address multiple times. The only way to correct a completely faulty configuration is to connect the device to your computer via USB and use either the the otc_configure_ethernet tool or the PixConnect to rectify it.

From the perspective of the machine running the SDK the following network connections are established:

• Outgoing TCP connection to <Device IP>:2000.
• Incoming UDP connection from <Device IP> on the <Destination Port>.

Please make sure that any firewall on the machine allows these connections.

Note

On Windows the first connection attempt of a SDK based application to an Ethernet capable device may fail because the Windows firewall initially blocks the communication.

Control

In order to send commands to your device and to retrieve small bits of information the SDK establishes a TCP to the device IP address specified in the configuration file. It will always address the port 2000 on the device.

Note

The port 2000 is required by the firmware and can not be changed by the SDK.

Attention

Avoid establishing Ethernet connections to the same device from multiple clients at the same time. If one client disconnects, the control TCP connection will be closed for all other clients by the firmware. As a result, the SDK can no longer send commands to the device. This impacts, for example, the automatic triggering of flag cycles that ensure the thermal data does not drift over time.

Streaming

Once the device is powered and its firmware is running it tries to locate the configured destination IP address. On success it starts sending the thermal data via UDP datagrams to the set destination socket (destination IP address + destination port). Typically, a thermal frame is comprised out of multiple datagrams that are pieced together by the SDK.

Note

The SDK has no means to influence this behavior nor can it reset the firmware, if it stops to send UDP datagrams.

As mentioned before the data stream is uncompressed and thus poses some demands on the network hardware. To clarify those Optris released technical notes detailing the Network Requirements for Optris Imager in Industrial Applications.