Skip to content

Balluff Smart Camera


Make sure to add also the Vision Module component to your component setup. This is required to perform the calibration.


The camera requires firmware version 2.6.0 or newer to have installed to work with drag&bot.

Network Configuration

By default the Balluff Smartcamera can be accessed in a dynamic network, where ip addresses are provided by DHCP. However drag&bot usually works in a network of static ip addresses.

Change the network settings respectively in the camera configurations:

  • In the Network section disable the option Obtain an IP address automatically.
  • In the Network section configure a static IP and subnet mask reachable by the drag&bot system.

Network Configuration

  • In the Communication section set the mode to TCP and activate the option send status information.
  • In the Communication section note the Port for the configuration later in drag&bot.

Communication Configuration

Smart Camera Program

When the smart camera is operating with drag&bot, Balluff programs, which are identified by their ids, are triggered in the smartcamera. Their actual content can be composed freely by the user, but the program always needs to be finished by sending the results to drag&bot with the Balluff 'Send results' tool. The structure of these results follows a defined pattern, depending on the tool(s) used before.

Result structure

Each result message starts by defining the structure of the following message. This is a string containing max. 20 characters, where each character indicates the results for a specific Balluff vision tool. Currently the following Balluff vision tools are supported:

Identifying Character Vision Tool Notes
F Find Object To use with the drag&bot function block 'Balluff - Localize Object'
C Read Code To use with the drag&bot function block 'Balluff - Localize Object'
B Check Brightness Not yet completely supported
T Read Text Not yet completely supported

Each tool needs to send specific information, which builds the rest of the message:

Structure for Find Object

The information for a 'Find Object' tool needs to follow this structure in the result message:

Size Datatype Description Linking Example
1 Byte bool success Find_object.Tool_processing
4 Bytes real32 x (mm) Find_object.Object_1.Position_in_X_direction
4 Bytes real32 y (mm) Find_object.Object_1.Position_in_Y_direction
4 Bytes real32 rotation (deg) Find_object.Object_1.Rotation
2 Bytes int16 quality (0 to 100) Find_object.Object_1.Degree_of_match
2 Bytes int16 quantity_found Find_object.Number_of_found_objects
20 Bytes string object_type Find_object.Object_1.Object_type

Structure for Read Code

The information for a 'Read Code' tool needs to follow this structure in the result message:

Size Datatype Description Linking Example
1 Byte bool success Read_code.Tool_processing
4 Bytes real32 x (mm) Read_code.Code_1.Position_in_X_direction
4 Bytes real32 y (mm) Read_code.Code_1.Position_in_Y_direction
4 Bytes real32 rotation (deg) Read_code.Code_1.Rotation
2 Bytes int16 quantity_found Read_code.Number_of_found_codes
20 Bytes string code_type Read_code.Code_1.Detected_code_type
50 Bytes string content Read_code.Code_1.Included_text

Structure for Check Brightness


The results of the 'Check Brightness' tool will be understood by the drag&bot Balluff driver, but currently can not be processed any further.

The information for a 'Check Brightness' tool needs to follow this structure in the result message:

Size Datatype Description Linking Example
1 Byte bool success Check_brightness.Tool_processing
4 Bytes real32 value Check_brightness.Brightness_value

Structure for Read Text


The results of the 'Read Text' tool will be understood by the drag&bot Balluff driver, but currently can not be processed any further.

The information for a 'Read Text' tool needs to follow this structure in the result message:

Size Datatype Description Linking Example
1 Byte bool success Read_text.Tool_processing
50 Bytes string content Read_text.Output_text

Example: Message structure for 'FC'

Example structure of the complete result message for a operation order of 'FC', which indicates the results of a Find Object tool followed by the information from a Read Code tool.

Byte Index Size Datatype Description Linked Example
0 20 Bytes string structure 'FC'
20 1 Byte bool success_f Find_object.Tool_processing
21 4 Bytes real32 x_f (mm) Find_object.Object_1.Position_in_X_direction
25 4 Bytes real32 y_f (mm) Find_object.Object_1.Position_in_Y_direction
29 4 Bytes real32 rotation_f (deg) Find_object.Object_1.Rotation
33 2 Bytes int16 quality_f (0 to 100) Find_object.Object_1.Degree_of_match
35 2 Bytes int16 quantity_found_f Find_object.Number_of_found_objects
37 20 Bytes string object_type_f Find_object.Object_1.Object_type
57 1 Byte bool success_c Read_code.Tool_processing
58 4 Bytes real32 x_c (mm) Read_code.Code_1.Position_in_X_direction
62 4 Bytes real32 y_c (mm) Read_code.Code_1.Position_in_Y_direction
66 4 Bytes real32 rotation_c (deg) Read_code.Code_1.Rotation
70 2 Bytes int16 quantity_found_c Read_code.Number_of_found_codes
72 20 Bytes string code_type_c Read_code.Code_1.Detected_code_type
92 50 Bytes string content_c Read_code.Code_1.Included_text

The complete message has a length of 142 Bytes.

Setup in drag&bot

  1. Please select the Balluff SmartCamera component from the list of available components in the drag&bot Component Manger.
  2. Configure the parameter IP Address for the camera. It has to match with the IP found in the section Network Configuration.
  3. Configure the parameter Port for the camera. It has to match with the Port found in the section Network Configuration.
  4. Configure the parameter Calibration Program ID with a program id, which will be used by default for the extrinsic calibration process (see Extrinsic Calibration for more information).

Component Setup


Don't forget to add also the Vision Module Component to your setup.

Extrinsic Calibration

To calibrate the balluff extrinsically with drag&bot you can follow the extrinsic calibration procedure, but have to consider some special points regarding the Balluff smartcamera.

  1. You need to create a calibration program on the Balluff Smartcamera, which detects the four patterns and communicates their locations to drag&bot. This program 💾 can serve as template but its recommended to reteach the patterns.

  2. The four calibration patterns Origin, A, B and C of the calibration plate have to be detected by the calibration program, which communicates a structure of four Find Object results 'FFFF' to drag&bot. Each pattern, named as "origin", "A", "B" and "C", needs to be sent as one found object in the message (the order of the results doesn't matter). The patterns should be teached in a way that the center of the detected object is at the intersection of the cross for each pattern.

  3. When choosing whether the camera is mounted to the cell or to the robot flange, ensure that the Calibration program id is correct and the Calibration trigger service is set to '/dnb_driver_balluff/trigger_localization' at Advanced settings.

Calibration Service

Function Blocks

Balluff - Localize Object

This function block triggers a Balluff program and can handle both a 'Find Object' result as well as a 'Read Code' result. It returns the first object returned in the Balluff result message.

Field name Data type Description
Inputs Balluff Program ID Integer The Balluff program id to be triggered.
Timeout Integer Timeout in seconds to wait for the result before a TIMEOUT exception is thrown.
Extrinsic Calibration Name The calibration name to use to recalculate from camera pose into world pose.
Outputs Success Boolean True, if at least one object was found.
Result Pose Pose The worlds pose of the found object.
As the camera is a 2D-camera the distance from camera to object can not be calculated and is thereby always zero.
Object Information String The type of the detected object or the type and content of the detected code.
Quality Float Reported quality for the found object in range 0.0 to 1.0 . A detected code always has a quality of 1.0 .

The function block can throw the following errors:

Error Code Description
ERROR_DEVICE_NOT_AVAILABLE The camera is not setup or not configured properly.
ERROR_LOADING An error occurred while loading the given Balluff program.
TIMEOUT Waiting for the results took longer than the specified timeout value.
CALIBRATION_ERROR No valid calibration was found for the specified calibration name or an error occurred during recalculating the result pose from camera coordinate system into worlds coordinate system.
ERROR_INVALID_FORMAT The format of the received message does not match with the announced message structure.