# 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.

The OPC UA Service of Franka robots enables a certain set of functions on the robot, that can be accessed through the following means:

1. Via OPC UA Apps in Desk
2. Via racecom operation calls
3. 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. If a task is currently running it will be stopped automatically before closing the brakes.
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. Closes the brakes and by doing so stops any running task.
Shutdown | Method | Shuts the master controller down. Closes the brakes and by doing so stops any running task.
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). Succeeds if the mode already is Execution and fails if a task is currently running.
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