Balluff Smart Camera¶
Requirements
Make sure to add also the Vision Module component to your component setup. This is required to perform the calibration.
Requirements
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.
- 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.
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¶
Info
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¶
Info
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¶
- Please select the Balluff SmartCamera component from the list of available components in the drag&bot Component Manger.
- Configure the parameter IP Address for the camera. It has to match with the IP found in the section Network Configuration.
- Configure the parameter Port for the camera. It has to match with the Port found in the section Network Configuration.
- 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).
Info
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.
-
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. -
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.
-
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.
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. |