Introduction¶
What is OPC UA?¶
OPC UA stands for Open Platform Communications Unified Architecture and is becoming one of the largest standards for platform-independent service-oriented machine-to-machine communication. In OPC UA, you can not only send and receive data in a very efficient way. OPC UA also contains semantic information about the data, including human-readable descriptions about each data point and the relationships between the different types and objects available via OPC UA.
In OPC UA, communication happens between servers and clients. An OPC UA server is the owner of a certain set of data and/or functionality, which is made available to OPC UA clients. An OPC UA client interacts with a server. It can for example read and write a server’s variables and call certain methods.
Franka Emika’s OPC UA Service enables a certain set of functions on the robot, that can be accessed through the following means:
- Via OPC UA Apps in Desk
- Via racecom operation calls
- Via an OPC UA client like uaExpert
OPC UA Functionality Overview¶
The following figure shows an overview of the OPC UA interface, as seen in the software uaExpert.
OPC UA Interface as seen in uaExpert
Execution Control¶
Due to Single Point of Control, a control token needs to be requested before certain actions, such as opening of brakes or starting task execution, can be triggered. The sequence to obtain the control token is:
- Call RequestControlToken.
- If no one else is holding on to the control token, it will immediately become active.
- If someone else is holding on to the control token, they can choose if they want to free it. During this period, ControlTokenRequestPending is true and ControlTokenOwner will show an identifier of the current owner.
- The control token can also be forced by setting the parameter force in RequestControlToken to true, e.g. when an other user or session did not release the token before going inactive. When this is called, a user needs to press the blue circle on the robot pilot within a predefined time to confirm physical access to the robot. The currently configured time is available in ControlTokenForceTimeout. If the control token is not received it could be either due to the token holder denied the (forced) request or the pilot button was not pressed within time.
- When a RequestControlToken is sent and ControlTokenRequestPending is still true, it is allowed to send another RequestControlToken with the force parameter set to true.
- A pending request for the control token can be cancelled at any time by calling CancelControlTokenRequest.
- When ControlTokenActive is true, the requested control token is now active and methods like OpenBrakes and StartTask can be executed.
- When the control token is no longer needed, FreeControlToken can be called.
Note
The control token will automatically be freed when terminating the OPC UA user session or if someone else is sending a control token request (e.g. a user in Desk). A running execution is paused when the token is freed!
| Name | Type | Description |
|---|---|---|
| ActivateFCI | Method | Activates the Franka Control Interface (FCI). Only available for FR3. |
| BrakesOpen | Variable | Shows the status (opened/closed) of the robot’s brakes |
| CancelControlTokenRequest | Method | Cancels a control token request. |
| CartesianPose | Variable | Shows the current end-effector pose as 4x4 transformation matrix |
| CloseBrakes | Method | Closes the robot’s brakes. Note that this will also stop any running task. |
| ControlTokenActive | Variable | Shows if the logged in user has the control token |
| ControlTokenForceTimeout | Variable | Shows the configured time a user has when forcing the control token to confirm physical access to the robot. |
| ControlTokenOwner | Variable | Shows the current control token owner (if any) |
| ControlTokenRequestPending | Variable | Shows if a control token request is pending |
| DeactivateFCI | Method | Deactivates the Franka Control Interface (FCI). Only available for FR3. |
| EstimatedForces | Variable | Shows the estimated wrench at the end-effector in (x, y, z) in N and (R, P, Y) in Nm |
| EstimatedTorques | Variable | Shows the estimated torques in Nm for each joint |
| ExecutionStatus | Variable | Shows the robot’s execution status (HasError, IsRunning, ErrorMessage, ActiveTaskName, ActiveTaskId) |
| FCIActive | Variable | Shows the status (activated/deactivated) of the Franka Control Interface (FCI). Only available for FR3. |
| FreeControlToken | Method | Frees the control token |
| JointAngles | Variable | Shows the robot’s joint angles in rad |
| OpenBrakes | Method | Opens the robot’s brakes (requires control token). As this method could take a significant amount of time, consider increasing your client’s Call Timeout. |
| RequestControlToken | Method | Requests the control token |
| Reboot | Method | Reboots the master controller |
| Shutdown | Method | Shuts the master controller down |
| StartTask | Method | Starts a task, identified by its ID (requires control token) |
| StopTask | Method | Stops the currently running task |
| SwitchToExecution | Method | Switches the operating mode to Execution (requires control token) |
| Tasks | Variable | Shows the IDs of all available tasks |
Self Tests¶
For executing the self tests a control token is needed, see above for details.
| Name | Type | Description |
|---|---|---|
| CanExecute | Variable | Shows if the self tests can be executed |
| RemainingTime | Variable | Shows the remaining time in seconds until the self tests will have to be executed |
| Status | Variable | Shows the current status of the self tests: Ok, Warning (self tests have to be executed soon), or Elapsed (self tests have to be executed now) |
| Execute | Method | Executes the self tests |
Key-Value-Maps¶
These Key-Value-Maps (sometimes called dictionaries) are named values which are stored on the robot’s OPC UA server in a non-permanent way, i.e. they will be cleared after a restart of the robot.
The KeyIntMap object is a Key-Integer-Storage, storing pairs of String and Int32 values. The KeyPoseMap object is a Key-Pose-Storage, storing pairs of String and 16 Double values. Those 16 double values represent a robot pose, described by a 4x4 (hence 16 values) transformation matrix in column-major notation.
This interface of the OPC UA server is mostly symmetrical with the interface of the racecom OPC UA service.
| Name | Type | Description |
|---|---|---|
| ClearMap | Method | Clears the entire map, deletes all keys and values |
| Delete | Method | Deletes the key-value-pair specified by the given key |
| Map | Variable | Shows all entries of the key-value-map in an array |
| Read | Method | Shows the value of a single key-value-pair specified by the given key |
| ReadKeys | Method | Shows only the keys of the key-value-map |
| ReadMap | Method | Returns all entries of the key-value-map in an array |
| Replace | Method | Changes the key-value-pair specified by the given key |