Skip to content

Image Connector Applications Interface Specification

Version: 1.0.0

Contents

Interface Definition of Camera Connectors

This document outlines the northbound interface (indicating north in the automation pyramid) of a camera connector application and vision-driven applications. It covers the configuration of a connected camera and the retrieval/streaming of images from this camera for further processing. The southbound interface of the camera connector is defined by the connector provider, dependent on the technology used (GigEVision, Gen<i>Cam, USBVision, etc.), and is therefore not part of this document.

General Definitions

To facilitate data transfer between the camera connector and vision-driven applications, the currently supported communication channels are ZeroMQ (ZMQ) and MQTT. For enhanced integration, such as with Siemens Industrial Edge, supplementary interfaces like REST API could also be considered.

The connector application must possess two bind ZMQ ports and/or MQTT configurable connection parameters. These connections will be utilized for setting up the application, configuring the camera, defining image streaming options, and requesting images via software triggers. Images must adhere to the Vision Connector Image Format.

All used ports and servers must be configurable in the application configuration file (for Siemens Industrial Edge applications) and environment variables. The ZMQ ports (defaults: 5555 to REQ/REP and 5556 to PUB/SUB) must be documented in the application documentation.

In the case of MQTT connections, the server, port, user, password, client id and root topic should be configurable within the application.

The connector should be designed to support one or multiple cameras. This support must be thoroughly detailed in the application documentation and should include a dedicated topic structure for each camera.

The scope of this document is to define the interface protocols between vision-driven applications and camera connectivity applications. Communication specifics, camera protocols, camera setup, and application features are beyond the scope of this document.

Below is a schematic representation of the defined scope:

Messaging scope

Topic Structure

ZMQ

When using ZMQ connections, the expected structure outlined below:

  • To send commands, utilize single-frame messages sent to the REQ/REP port.
  • The image streaming topic on the PUB/SUB port: {DeviceID}/stream
  • For receiving application feedback, subscribe to topic on the PUB/SUB port: logging

MQTT

For MQTT connections, the topic structure is as follows:

  • To send commands, publish messages to: {mqttRoot}/request
  • For receiving application command responses on: {mqttRoot}/response
  • Subscribe to the topic for receiving application feedback: {mqttRoot}/logging

The message content should be formatted in JSON, employing the message field names as property names for each call, as described in the subsequent chapters of this document.

Device Identification

To identify a device, the connector application should specify, in its Camera Discovery documentation, the allowed fields for identification. Typically, expected fields include the serial number (SerialNumber field), user identification (UserDefinedName field), IP address (for GigE devices, in the IPAddress field), and MAC address (for GigE devices, in the mac field). While these fields are commonly used, they are not mandatory, may not be available, and the connector application may introduce additional or alternative identification fields.

In the subsequent documentation, the term "DeviceID" refers to the identifying string that was used for a camera device upon opening the it. This exact string will then be used for identifying the opened camera device while it is used and until it is closed again. Only after that the camera device can be opened and used again with a different DeviceID. The value of the DeviceID can be one of the fields returned during the device info (see more details in chapter Open Camera Connection.

Using a different DeviceID for a camera device while it is open, even if it refers to the same device, may lead to errors. Exceptions to this rule are allowed if documented by the application.

Messaging

The message exchange will be based on JSON messages. The subsequent sections will outline the minimum content for the message payload, where the fields are properties for the payload JSON, and any additional fields might be utilized as specified in the connector application documentation, in accordance with the vendor's requirements.

For ZMQ, the JSON string payload will be encoded into a UTF-8 single-frame message.

In MQTT messages, the JSON payload serves as the content of the message to be sent.

Vision Connector Image Format

To standardize image transfer between camera streaming applications and image-driven applications, the following format shall be used for transferring images. The ZMQ message consists of a multipart message with each frame/part described below.

This message format is prepared to support multiple stream cameras.

Message Envelope

Frame Field Description Type
1 topic Device identification. Binary String (UTF-8) to identify the device in the following syntax: {DeviceID}/stream
2 metadata Metadata Binary Metadata JSON (UTF-8)
3 image Image 1 Binary
4 ... n image Image n – For multi-stream camera Binary

Metadata JSON

Field Optional Type Default Description
version No String 1 Metadata format version
count No Integer 1 Number of images on message
timestamp No String - Date and Time string UTF-8 ISO8601. Application host datetime.
customfields Yes String - Custom field to be defined by the app creator and handled by the consumers. Might be a simple string or JSON string or else.
detail No Image Detail Object Array - Images details

Image Detail Object

Field Optional Type Default Description
id No String - Unique image identifier. Suggested mnemonic format like {camid}_{camstream}_{datetime}
seq No Integer - Sequential number for the camera image. Starting at 1, incremented by 1 on each frame grabbed.
height No / Yes (encoded formats) Integer - Image Height
width No / Yes (encoded formats) Integer - Image Width
formatns Yes String Genicam Image format namespace. For genicam pixelformat use Genicam and Compressed for compressed formats. 2
format No String - Image format 1 2 3
linepadding Yes Integer 0 Number of bytes added on the end of byte stream to reach a multiple of 4 bytes. Eg. an image with 61 pixels, mono8, will have a linepadding of 3, filling the stream to reach 64 bytes.
timestamp Yes String5 - Clock ticks informed by the camera.4
metadata6 Yes String - Image additional metadata field to be defined by the app creator and handled by the consumers. Might be a simple string or JSON string or else.

1 For cameras using a Genicam standardized Pixel Format, it is recommended to use the Genicam Naming Convention as described in section 4.35 GenICam_PFNC_2_4.pdf.

2 Additional values can be supported once described in the application documentation.

3 Compressed formats shall be mentioned in the application documentation, being recommended in the fields corresponding to the file extension (e.g., "png", "jpg", "bmp").

4 Timestamp provided by the cameras are Ticks count. This can be referencing the Unix epoch or the number of Ticks since the camera is on or count of Ticks informed/in sync with the PTP server.

5 A string might be used since, in the PTP standard, the Tick count is expected to be an 80-bit number. However, the current Genicam protocol returns a 64-bit integer. A string will be more reliable for future implementations.

6 Cameras capable and with PTP enabled must inform the PTP synchronization status in the metadata. E.g.,

… 
"metadata": "{'ptpstatus': 'locked'}"
…

Metadata Example:

{
  "version": "1",
  "count": 2,
  "timestamp": "2014-01-09T13:35:34.000000000+0100",
  "customfields": "{'xfield1':1,'xfield2':'abc'}",
  "detail":[
    {
      "id":"mycamera_0_2014-01-09T13:35:34.000000000+0100",
      "seq": 3,
      "height": 60,
      "width": 80,
      "format": "png",
      "formatns": "Compressed",
      "timestamp": "123456",
      "metadata": "{'batchid':'batch1','stream':'lowdef'}"
    },
    {
      "id":"mycamera_1_2014-01-09T13:35:34.000000000+0100",
      "seq": 3,
      "height": 852,
      "width": 1280,
      "formatns": "Genicam",
      "format": "BGR8",
      "timestamp": "123456",
      "linepadding": 0,
      "metadata": "{'batchid':'batch1','stream':'raw'}"
    }
  ]
}

Camera Operation

Camera Discovery

As the initial step to establish communication, it is necessary to check the available cameras on the connector. To achieve this, the connector shall be capable of discovering cameras (e.g., GigE cameras) and listing them for the user.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value EnumerateDevices
{
    "TransactionID": "123456",
    "Action": "EnumerateDevices"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
DeviceList No Array of Camera Devices Array of camera devices.

Camera Object

Field Optional Type Description
SerialNumber1 Yes string Camera identification
UserDefinedName1 Yes String Camera User-defined name
ModelName No String Camera model
VendorName No String Camera vendor
Interface No String Camera interface U3V (USB3 Vision), CXP (CoaXPress), GEV (GigEVision), CamEmu (Emulation)
IPAddress Yes String Camera IP address
{addtional identification fields}1 Yes String Addtional device identification offered by the connector application.

1 Device identification, must be informed on the documentation if they can be used as device identification or if there is additional fields that can be used.

{
    "TransactionID": "123456",
    "ReturnCode": 0,
    "Message": "Cameras found.",
    "DeviceList": [
        {
            "SerialNumber": "548451887",
            "UserDefinedName": "MyCam1",
            "ModelName": "Camera Model 1234",
            "VendorName": "The camera Factory",
            "Interface": "GEV",
            "IPAddress": "192.168.0.1"
        }
    ]
}

Open Camera Connection

Usually, Genicam cameras demand the connection to be open before starting to set parameters and image streaming. This connection is an exclusive access, meaning that no other app can access the camera and change parameters or stream images.

A camera can be opened by specifying an identification string in the DeviceID field. The connector will then try to find a matching camera by searching for this identification string amongst the infos of the available cameras. The order in which it searches is the following:

  1. SerialNumber
  2. IPAddress
  3. UserDefinedName
  4. ModelName
  5. VendorName
  6. Interface

Example: An identification string is provided in the DeviceID field. Then the connector will first try to find a camera with a matching SerialNumber. If none was found it will try to find a camera with a matching IPAddress. It will continue until a matching camera can be found and try to open this camera.

If multiple cameras are found matching the same info then the connector will try to open the first one (it is up to the connector which camera is the first one).

If a camera was opened using a certain identification string then this identification string must be used in all DeviceID fields of all requests regarding this camera until it is closed again. A camera can't be opened with multiple identification strings at the same time.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value OpenDevice
DeviceID No String Device identification.
{
    "TransactionID": "1232156",
    "Action": "OpenDevice",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "123456",
    "ReturnCode": 0,
    "Message": "Camera open."
}

Close Camera Connection

To close the camera connection, releasing the exclusive access and stopping any running image streaming, releasing the camera.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value CloseDevice
DeviceID No String Device identification.
{
    "TransactionID": "1232116",
    "Action": "CloseDevice",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "1232116",
    "ReturnCode": 0,
    "Message": "Camera closed."
}

Camera Parameter Configuration

Retrieving Parameter List

A list of parameters shall be provided when requested by the application user. To request the parameter list, the user shall send the following message.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value GetParameters
DeviceID No String Device identification.
ParameterList No Array of String The list of parameters that shall be read.
{
    "TransactionID": "2345645",
    "Action": "GetParameters",
    "DeviceID": "548451887",
    "ParameterList": [
        "Width",
        "Height"
    ]
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
ParameterList No Parameter Object Array Parameter Object Array containing the parameters details

Parameter Object

Field Optional Type Description
Name No String Unique parameter name.
DisplayName Yes String Displayable name of the parameter for user interface.
Type No String Parameter value type. Possible values: String, Integer, Float, Enumeration, Boolean
Value Yes String/Int/Float/Bool Current defined value. On enumerations, it is the string defined.
IntValue Yes Int On enumerations, it is the integer defined.
Readable No Boolean Flag indicating if the parameter can be read. Be aware that the readable flag depends of the current camera state.
Writable No Boolean Flag indicating if the parameter can be written. Be aware that the writable flag depends of the current camera state.
Minimum Yes Int/Float Minimum allowed value for numeric type parameters
Maximum Yes Int/Float Maximum allowed value for numeric type parameters
Increment Yes Int/Float Allowed increment for the parameter.
EnumEntries Yes Enum Entries Array Array containing the entries available for the parameter. This is used by parameters that use enumerations.

Enum Entries

Field Optional Type Description
DisplayName Yes String This represents the name of the property to the user
Value No String Parameter value that needs to be used to set the parameter value
IntValue No Int Integer value of the enum entry
Description Yes String Enum entry description.
{
  "TransactionID": "2345645",
  "ReturnCode": 0,
  "Message": "Parameters read successfully",
  "ParameterList": [
    {
      "Name": "Width",
      "DisplayName": "Width",
      "Type": "Integer",
      "Value": 1024,
      "Writable": true,
      "Minimum": 1,
      "Maximum": 4096,
      "Increment": 1
    },
    {
      "Name": "PixelFormat",
      "DisplayName": "Pixel Format",
      "Type": "Enumeration",
      "Value": "Mono8",
      "IntValue": 17301505,
      "Writable": true,
      "EnumEntries": [
        {
          "DisplayName": "Mono 8",
          "Value": "Mono8",
          "IntValue": 17301505,
          "Description": "This enumeration value sets the pixel format to Mono 8."
        },
        {
          "DisplayName": "Mono 10",
          "Value": "Mono10",
          "IntValue": 17825795,
          "Description": "This enumeration value sets the pixel format to Mono 10."
        },
        {
          "DisplayName": "Mono 12",
          "Value": "Mono12",
          "IntValue": 17825797,
          "Description": "This enumeration value sets the pixel format to Mono 12."
        },
        {
          "DisplayName": "Mono 16",
          "Value": "Mono16",
          "IntValue": 17825799,
          "Description": "This enumeration value sets the pixel format to Mono 16."
        }
      ]
    }
  ]
}

Setting Camera Parameters

To set the parameters, the user can send the message described in this chapter. It is possible to update a range of parameters; however, any error that may occur shall return the camera to the original state without applying any modification.

Enumerations parameter types might be also defined using the human-readable value. For example, setting the pixel format using the value as Mono8, despite the enumeration integer value.

For String and Integer parameters, the connector expects an exact match for the set value. For float parameters, a difference of no more than 1% is allowed due to floating-point comparison. If the provided value falls outside the expected range, the setting call will return an error.

The list of set values will be returned in the response message.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SetParameters
DeviceID No String Device identification.
ParameterList No Parameter Object Array Object to encapsulate the parameters to update.

Parameter Object

Field Optional Type Description
Name No String Unique Parameter Name2
Value1 No String/Int/Float/Bool New value

1On enumerations, it can be the integer value or can also be the symbolic name, refer to IntValue Retrieving Parameter List. 2While it is recommended to use the unique parameter name, retrieved in Retrieving Parameter List, applications may implement abbreviated parameter names as shortcuts to simplify the parameter settings or shortcuts to access multiple node maps. These shortcuts should be documented in the connector documentation.

{
    "TransactionID": "123567",
    "Action": "SetParameters",
    "DeviceID": "548451887",
    "ParameterList":[
        {"Name": "Width", "Value": 800},
        {"Name": "Height", "Value": 600},
        {"Name": "PixelFormat", "Value": "Mono8"} //Setting using the human readable string. This could be also the correspondent enum integer.
    ]
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
ParameterList No Parameter Object Array Object to encapsulate the parameters to update.

Parameter Object

Field Optional Type Description
Name No String Unique Parameter Name2
Value No String/Int/Float/Bool New value
{
    "TransactionID": "123567",
    "ReturnCode": 0,
    "Message": "Paramters updated.",
    "ParameterList":[
        {"Name": "Width", "Value": 800},
        {"Name": "Height", "Value": 600},
        {"Name": "PixelFormat", "Value": "Mono8"}
    ]
}

Camera Quick Settings

Additionally to the parameters settings, the quick setting feature provides a way to quickly define the most commonly used parameters. These parameters use common known names, and the connector is expected to map them internally to the camera correspondent parameter.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SetQuickParameters
DeviceID No String Device identification.
Width Yes Integer/String Image width1
PixelFormat Yes Integer/String Pixel format1,2
Height Yes Integer/String Image Height1
Gain Yes Float/Int/String Gain1. The string Auto can be used to activate automatic gain.
ExposureTime Yes Float/Int/String Exposure time in microseconds1. The string Auto can be used to activate automatic exposure.

1 Camera dependent values, invalid values shall be informed on the returning error message. 2 Genicam standardized Pixel Format, according with the Genicam Naming Convention as described in section 4.35 GenICam_PFNC_2_4.pdf.

{
    "TransactionID": "23456435",
    "Action": "SetQuickParameters",
    "DeviceID": "548451887",
    "Width": 800,
    "Height": 600,
    "Gain": "Auto",
    "PixelFormat": "Mono8",
    "ExposureTime": 234.5
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "23456435",
    "ReturnCode": 0,
    "Message": "Paramters updated."
}

Camera User Settings

The Genicam protocol allows the user to store parameter sets on the camera, and the connector must allow the user to save, load, and define the default user configuration to be used on camera restart.

Get Available Saved User Sets

Retrieve the available usersets on the camera.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value GetUserSets
DeviceID No String Device identification.
{
    "TransactionID": "1232116",
    "Action": "GetUserSets",
    "DeviceID": "12323454754"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
UserSetList User Set Object Array Object containing the available parameter settings

User Set Object

Field Optional Type Description
DisplayName Yes String This represents the name of the user set to the user
Value No String Parameter value that needs to be used to set the user set value
IntValue No Int Integer value of the user set
Description Yes String User set description.
{
    "TransactionID": "12323454754",
    "ReturnCode": 0,
    "Message": "Userset retrieved.",
    "UserSetList": [
      {
        "DisplayName": "Default User Set",
        "Value": "Default",
        "IntValue": 0,
        "Description": "The default factory set can be loaded."
      },
      {
        "DisplayName": "User Set 1",
        "Value": "UserSet1",
        "IntValue": 1,
        "Description": "User set 1 can be saved, loaded, or configured."
      },
      {
        "DisplayName": "User Set 2",
        "Value": "UserSet2",
        "IntValue": 2,
        "Description": "User set 2 can be saved, loaded, or configured."
      },
      {
        "DisplayName": "User Set 3",
        "Value": "UserSet3",
        "IntValue": 3,
        "Description": "User set 3 can be saved, loaded, or configured."
      }
    ]
}

Load UserSet Configuration

To load a configured UserSet on the camera, the user can send the LoadUserSet message.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value LoadUserSet
DeviceID No String Device identification.
UserSet No Int/String String according with the user setting enumeration or integer when using the integer value.
{
  "TransactionID": "23423423563456",
  "Action": "LoadUserSet",
  "DeviceID": "548451887",
  "UserSet": "UserSet2"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
  "TransactionID": "1232116", 
  "ReturnCode": 0,
  "Message": "Userset loaded."
}

Saving Configuration

After the camera is parametrized, the parameter set can be saved on the camera on user sets. To perform the storage, the user can send the SaveUserSet message.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SaveUserSet
DeviceID No String Device identification.
UserSet No Int/String String according with the user setting enumeration or integer when using the integer value.
{
  "TransactionID": "489494",
  "Action": "SaveUserSet",
  "DeviceID": "548451842342387",
  "UserSet": "UserSet2"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
  "TransactionID": "489494",
  "ReturnCode": 0,
  "Message": "User set updated."
}

Defining Default Configuration

To define the camera default parameter set on the camera to be loaded in case of restart, the user can send the SetDefaultUserSet message.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SetDefaultUserSet
DeviceID No String Device identification.
UserSet No Int/String String according with the user setting enumeration or integer when using the integer value.
{
  "TransactionID": "1232116",
  "Action": "SetDefaultUserSet",
  "DeviceID": "548451887",
  "UserSet": "UserSet2"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
  "TransactionID": "1232116",
  "ReturnCode": 0,
  "Message": "Default userset defined."
}

Download Camera Configuration

The current camera setup might be downloaded to back up and further usages. The file format might be defined on the implementation, it is not meant to be edited externally.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value GetDeviceConfig
DeviceID No String Device identification.
{
    "TransactionID": "23423456",
    "Action": "GetDeviceConfig",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
FileContent No String Base64 string of the configuration file. Containing the mime type prefix.
{
    "TransactionID": "23423456",
    "ReturnCode": 0,
    "Message": "Success",
    "FileContent": "data:text/plain;base64,IyB7MDVEOEMyOTQtRjI5NS00ZGZiLTlEMDEtMDk2QkQwNDA0OUY0fQojIEdlbkFwaSBwZXJzaXN0ZW5jZSBmaWxlICh2ZXJzaW9uIDMuMS4wKQojIERldmljZSA9IEJhc2xlcjo6QmFzbGVyQ2FtRW11IC0tIEJhc2xlciBDYW0gRW11IGludGVyZmFjZSAtLSBEZXZpY2UgdmVyc2lvbiA9IDEuMC4xIC0tIFByb2R1Y3QgR1VJRCA9IEI5N0RFNTQ5LUNCOUEtNDRmOC05MzdELTY0QzQ4QkRFQ0ZBMyAtLSBQcm9kdWN0IHZlcnNpb24gR1VJRCA9IEEyRENERTE0LTczRTQtNDA4YS1BRkE4LTgxODUyRUNCNUQ5QQpHYWluCTAuMDAwZSswMApXaWR0aAkxMDI0CkhlaWdodAkxMDQwClBpeGVsRm9ybWF0CU1vbm84CkV4cG9zdXJlVGltZQkxMDAwMC4wCg=="

}

Upload Camera Configuration

The stored file on section Download Camera Configuration can be provided to the camera restoring the setup. File integrity and validations are recommended and shall be implemented by the connector application.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SetDeviceConfig
DeviceID No String Device identification.
FileContent No String Base64 string of the configuration file. Containing the mime type prefix.
{
    "TransactionID": "234423465465",
    "Action": "SetDeviceConfig",
    "DeviceID": "548451887",
    "FileContent": "data:text/plain;base64,IyB7MDVEOEMyOTQtRjI5NS00ZGZiLTlEMDEtMDk2QkQwNDA0OUY0fQojIEdlbkFwaSBwZXJzaXN0ZW5jZSBmaWxlICh2ZXJzaW9uIDMuMS4wKQojIERldmljZSA9IEJhc2xlcjo6QmFzbGVyQ2FtRW11IC0tIEJhc2xlciBDYW0gRW11IGludGVyZmFjZSAtLSBEZXZpY2UgdmVyc2lvbiA9IDEuMC4xIC0tIFByb2R1Y3QgR1VJRCA9IEI5N0RFNTQ5LUNCOUEtNDRmOC05MzdELTY0QzQ4QkRFQ0ZBMyAtLSBQcm9kdWN0IHZlcnNpb24gR1VJRCA9IEEyRENERTE0LTczRTQtNDA4YS1BRkE4LTgxODUyRUNCNUQ5QQpHYWluCTAuMDAwZSswMApXaWR0aAkxMDI0CkhlaWdodAkxMDQwClBpeGVsRm9ybWF0CU1vbm84CkV4cG9zdXJlVGltZQkxMDAwMC4wCg=="
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
  "TransactionID": "234423465465",
  "ReturnCode": 0,
  "Message": "Configuration loaded."
}

Application Control

The connector application shall allow the user to start and stop the image streaming. The control should not affect any camera property, including the trigger definitions. All camera parameter setups must be done through the parameter setup section.

Starting Streaming

This command is used to initiate image streaming for a specific camera. Upon activation, continuous streaming will publish images to the streaming topic (refer to Topic Structure). For triggered grabbing, the application will send images based on trigger activations configured in the parameters section.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value StartStreaming
DeviceID No String Device identification.
{
    "TransactionID": "12341263412635465",
    "Action": "StartStreaming",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "12341263412635465",
    "ReturnCode": 0,
    "Message": "Stream started."
}

Stop Streaming

This command terminates camera image streaming.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value StopStreaming
DeviceID No String Device identification.
{
    "TransactionID": "32143242356465",
    "Action": "StopStreaming",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "32143242356465",
    "ReturnCode": 0,
    "Message": "Stream stopped."
}

Software Trigger Image Acquisition

This command is used when the camera is in software trigger operation. Upon execution, it triggers image acquisition as configured on the camera. Images will be published on the image streaming topic (refer to Topic Structure).

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value SoftwareTrigger
DeviceID No String Device identification.
{
    "TransactionID": "2342546345",
    "Action": "SoftwareTrigger",
    "DeviceID": "548451887"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
{
    "TransactionID": "2342546345",
    "ReturnCode": 0,
    "Message": "Trigger sent."
}

Get Application Status

Retrieves the connected camera list with status, streaming topic, application version, and implemented specification version.

Message Envelope For ZMQ Message

Frame Field Description Type
1 payload Method payload Binary String (UTF-8)

payload

Field Optional Type Description
TransactionID Yes String Transaction identification.
Action No String Method called. Fixed value GetStatus
{
    "TransactionID": "46543214635244",
    "Action": "GetStatus"
}

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
TransactionID Yes String Transaction identification.
ReturnCode No Integer Message code following Message Codes.
Message Yes String Response message
ApplicationVersion No String Connector application version
SpecificationVersion No String Specification version of the connector
DeviceList No Array of Camera Object Array of camera objects

Camera Object

Field Optional Type Description
DeviceID No String Current camera identification
StreamingTopic No String Topic where the camera streams images
Status No String Camera status. Possible values: Connected, Streaming, Error
{
    "TransactionID": "46543214635244",
    "ReturnCode": 0,
    "Message": "Success.",
    "ApplicationVersion": "1.0.1",
    "SpecificationVersion": "1.0.0",
    "DeviceList":
    [
        {
            "DeviceID": "548451887",
            "StreamingTopic": "548451887/stream",
            "Status": "Streaming"
        }
    ]
}

Application Feedback

Message Codes

For the responses, the following message code are expected.

Info message codes

Value range for info messages: 0x00000000 ... 0x00FFFFFF

Message Codes Meaning
0x00000000 Request was completed successfully
0x00000001 Application is online
0x00000002 Application is offline

Warning message codes

Value range for warning messages: 0x01000000 ... 0x01FFFFFF

Message Codes Meaning
0x01000000 A request was only partially successful

Debug message codes

Value range for debug messages: 0x02000000 ... 0x02FFFFFF

Error message codes

Value range for error messages: 0x03000000 ... 0x03FFFFFF

Message Codes Meaning
0x03000000 Error while parsing a request
0x03000001 Error while handling a request
0x03000002 An opened device was removed

Application Logging

The application log is expected to be published on the logging topic, any general application log which are not direct responses to any given command, like application unhandled errors, cameras error messages and camera connectivity issues.

Response

Frame Field Description Type
1 payload Response object Binary String (UTF-8)

Response Object

Field Optional Type Description
Timestamp Yes String Application host date and time on ISO8601 format, when the message was created.
Code Yes Integer Message code following Message Codes.
Level No String Log level - Debug, Info, Warning, Error
Message No String Response message
{
    "Timestamp":"2014-01-09T13:35:34.000000000+0100",
    "Code": 50331650,
    "Level":"Error",
    "Message":"Lost connection with myCam1"
}