OPC UA
Concept
It is possible to communicate with the edge API in real-time via variables on an OPC-UA server. The concept is best explained at hand of the default configuration of Vathos’ OPC UA client app:
{
"url": "opc.tcp://boschrexroth:boschrexroth@192.168.2.120:4840",
"nodes": {
"error": "ns=2;s=plc/app/Application/sym/GVL/vathos_error",
"heartbeat": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_heartbeat",
"interval": 30
},
"trigger": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_trigger",
"args": {
"workflow": {
"value": "votenet"
},
"wait_for_camera": {
"value": true
},
"modality": {
"value": "depth"
}
}
},
"load_configuration": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_load_configuration",
"args": {
"product": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_product_id"
},
"workflow": {
"value": "votenet"
}
}
},
"patch_configuration": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/patch_configuration",
"args": {
"config_id": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_config_id"
},
"key": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_key"
},
"value": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_value"
}
}
},
"rpc": {
"get_pose": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_get_pose",
"group": "votenet",
"args": {
"representation": {
"value": "ZYX"
},
"degrees": {
"value": true
},
"timeout": {
"value": 5
}
},
"return_value": [
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_X",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Y",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Z",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_A",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_B",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_C",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_state",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_product"
]
},
"save_image": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_save_image",
"group": "depth",
"args": {
"stream_no": {
"value": 1
},
"pose": {
"node": [
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_X",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Y",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Z",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_A",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_B",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_C"
]
},
"representation": {
"value": "ZYX"
},
"degrees": {
"value": true
}
}
},
"start_streaming": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_start_streaming"
},
"handeye_calibration": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_handeye_calibration",
"args": {
"session": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_session"
},
"product_id": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_product_id"
},
"representation": {
"value": "ZYX"
},
"degrees": {
"value": true
},
"eye_in_hand": {
"value": false
},
"pattern_side_length": {
"value": 0.025
},
"pattern_width": {
"value": 10
},
"pattern_height": {
"value": 7
},
"service": {
"value": "3d.handeye.calibration.vathos.net"
}
},
"return_value": [
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_X",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Y",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Z",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_A",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_B",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_C"
]
}
}
}
}
The default configuration shown above must be adjusted to the OPC-UA server through which you wish to call functions from the Vathos API. Let’s walk you through the different parts to explain possible customizations.
Variable Summary
| Name | Data Type | Purpose |
|---|---|---|
vathos_error | String | Stores information in case of server-side errors. |
vathos_heartbeat | String | Stores the last instance in time in ISO format the Vathos client successfully contacted the server. |
vathos_trigger | Boolean | Triggers image capture. |
vathos_load_configuration | Boolean | Triggers arming the currently selected product. |
vathos_product_id | String | Contains the id of the product to arm. |
vathos_patch_configuration | Boolean | Triggers setting a certain configuration value. |
vathos_patch_config_by_product | Boolean | Triggers setting a certain configuration value for a certain product. |
vathos_config_id | String | Contains the id of the configuration to patch. |
vathos_key | String | Contains the name of the parameter to patch. |
vathos_value | String | Reference to the id of the node holding the new parameter value. |
vathos_service | String | Contains the name of the service to configure. |
vathos_get_pose | Boolean | Starts retrieval of the next pose from the last image. |
vathos_pose_X | Float | First position coordinate. |
vathos_pose_Y | Float | Second position coordinate. |
vathos_pose_Z | Float | Third position coordinate. |
vathos_pose_A | Float | First rotation coordinate. |
vathos_pose_B | Float | Second rotation coordinate. |
vathos_pose_C | Float | Third rotation coordinate. |
vathos_pose_state | Float | State index. |
vathos_pose_product | Float | Product index. |
vathos_save_image | Boolean | Triggers a capture and associates the pose from the list of pose variables with it. |
vathos_submit_pose | Boolean | Sends the current pose to the vision system. |
vathos_start_streaming | Boolean | Controls camera flash mode. |
vathos_handeye_calibration | Boolean | Starts hand-eye calibration. |
vathos_session | String | Stores a session id for hand-eye calibration. |
vathos_get_projection_matrix | Boolean | Starts intrinsic calibration. |
vathos_flashing | Boolean | Puts camera in flashing mode. |
vathos_workflow | String | Workflow. |
Data types are specified according to the official list of supported types.
Server Address
The only required configuration value is stored under the key "url" and contains the URL of your OPC-UA server in the format opc.tcp://${USERNAME}:${PASSWORD}@${IP}:${PORT}.
Error Messages
The key "error" points to a node on your server representing a string variable:
{
"error": "ns=2;s=plc/app/Application/sym/GVL/vathos_error"
}
If an error occurs during execution of any of the API functions, a message describing the error will be written to this variable. Make sure that the variable can hold strings consisting of at least 80 characters. Note that on some platforms, this coincides with the maximum available string length, and thus all error messages written by the client service are truncated to meet this requirement. Also note that it is the responsibility of the caller to reset the error message, e.g., to an empty string, after the message has been processed and countermeasures have been taken.
Connection Monitoring
The key "heartbeat" points to two variables controlling periodic health checks of the connection between OPC UA server and client. Every "interval" seconds, the client will write the current time/date in ISO format into the string variable with node name specified under "node". By comparing the current value of the node the current time, the client is able to detect if the edge device has become unresponsive (due to a power loss or interruption of the network connection).
Global RPCs
The definition of the heartbeat variable is followed by that of the globally available RPCs, e.g., of the function to arm a product:
{
"load_configuration": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_load_configuration",
"args": {
"product": {
"node": "ns=2;s=plc/app/Application/sym/GVL/vathos_product_id"
},
"workflow": {
"value": "votenet"
}
}
}
}
The function configuration consist of two entries: First, the Boolean trigger variable, which is monitored by the client service for a change from value false to true. When this change occurs, the function load_configuration is executed. Second, under "args", the arguments of the function are specified, either by a constant value as for the workflow in the example above, indicated by a key "value", or by a reference to another node on the OPC UA server which contains the value to be passed to the function. In order to arm the vision system to detect a different product, the client would write the product id into the node of the configured id, then set the trigger variable to true, and wait until the client service has set it back to false once the function has completed (successfully or unsuccessfully; possible exceptions are written into the error variable explained above).
Service-Specific RPCs
The configuration for service-specific functions are stored under the key "rpc". The structure of each configuration looks almost as that for globally available functions. Let’s have a look at the following example:
{
"get_pose": {
"trigger": "ns=2;s=plc/app/Application/sym/GVL/vathos_get_pose",
"group": "votenet",
"args": {
"representation": {
"value": "ZYX"
},
"degrees": {
"value": true
},
"timeout": {
"value": 5
}
},
"return_value": [
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_X",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Y",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_Z",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_A",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_B",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_C",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_state",
"ns=2;s=plc/app/Application/sym/GVL/vathos_pose_product"
]
}
There are two additional keys: First, the key "group" whose value must match the workflow for which you want to execute the specific function. Keep in mind you can run two or more services at the same time (e.g., plane picking and plane picking of rods), each with their own workflow identifier (e.g. "votenet" or "rods"), and all of those service may deliver poses to be retrieved by the client/robot by invoking get_pose. Second, the key "return_value" which points to one or multiple nodes on the OPC UA server where the result of the function shall be written. The value can be a single string (if the return value is of an atomic data type) or a list of string (in case, the return value is a list). Make sure that the data type of the specified nodes on the OPC UA server matches that of the return value of the corresponding function.
Customization
If you use the OPC-UA app on a ctrlX device, you will likely not need to change any default value except for the server URL. To partially override the default configuration issue the following request against the REST-API running on the edge device:
POST http://${EDGE_DEVICE_IP}:30000/v1/configurations
content-type: application/json
{
"service": "opcua.vathos.net",
"device": "661f6848ff867373c00f90b7",
"workflow": "votenet",
"data": {
"url": "opc.tcp://boschrexroth:boschrexroth@192.168.2.120:4840"
}
}
The device id can be easily copied from the device page in the web frontend or obtained under the URL http://${EDGE_DEVICE_IP}:30000/v1/deviceid. The object stored under the key "data" must contain a (possibly incomplete) document of the same structure as the example configuration shown above. The workflow variable must match the one associated with the inference service you plan to run on the device controlled by your OPC UA server.