OPC UA API documentation
************************

Custom Data Types
=================

The OPC UA server defines a few custom data types like ExecutionStatus, KeyIntPair and KeyPosePair. You can find the respective BSD-file :download:`here <_static/download/opcua/opc_ua_service_types.bsd>`.

OPC UA Server Address Space
===========================

You can download the OPC UA nodeset definition XML file :download:`here <_static/download/opcua/opc_ua_service.xml>`. The NodeID definition CSV file can be downloaded :download:`here <_static/download/opcua/opc_ua_service.csv>`.

Execution Control
=================

CloseBrakes
-----------

Closes all brakes. If a task is currently running it will be stopped
automatically before closing the brakes.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+------------------------------------------------------------------------------------------------+
| Name              | Description                                                                                    |
+===================+================================================================================================+
| Good              | The operation succeeded.                                                                       |
+-------------------+------------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                    |
+-------------------+------------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                    |
+-------------------+------------------------------------------------------------------------------------------------+

OpenBrakes
----------

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.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+------------------------------------------------------------------------------------------------+
| Name              | Description                                                                                    |
+===================+================================================================================================+
| Good              | The operation succeeded.                                                                       |
+-------------------+------------------------------------------------------------------------------------------------+
| InvalidState      | The control token is invalid.                                                                  |
+-------------------+------------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                    |
+-------------------+------------------------------------------------------------------------------------------------+
| RequestNotAllowed | The operation is currently not allowed, possible reason: safety error or violation present.    |
+-------------------+------------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                    |
+-------------------+------------------------------------------------------------------------------------------------+

Reboot
------

Reboots the master controller. Closes the brakes and by doing so stops any running task.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+--------------------------------------------------------------------------------------------+
| Name              | Description                                                                                |
+===================+============================================================================================+
| Good              | The operation succeeded.                                                                   |
+-------------------+--------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                |
+-------------------+--------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                |
+-------------------+--------------------------------------------------------------------------------------------+

Shutdown
--------

Shuts the master controller down. Closes the brakes and by doing so stops any running task.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+--------------------------------------------------------------------------------------------+
| Name              | Description                                                                                |
+===================+============================================================================================+
| Good              | The operation succeeded.                                                                   |
+-------------------+--------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                |
+-------------------+--------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                |
+-------------------+--------------------------------------------------------------------------------------------+

StartTask
---------

Starts a task, identified by its ID (requires control token).

All available task IDs can be listed via the `Tasks` variable.
When the task is started successfully the `IsRunning` flag of the
`ExecutionStatus` will be true, `ActiveTaskId` will be the ID of the started
task and `ActiveTaskName` its name.

**Parameter:**

+------+--------+--------------+
| Name | Type   | Description  |
+======+========+==============+
| key  | String | The task ID. |
+------+--------+--------------+

**Status Codes:**

+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name              | Description                                                                                                                                                               |
+===================+===========================================================================================================================================================================+
| Good              | The operation succeeded.                                                                                                                                                  |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| InvalidState      | The control token is invalid, or the task ID parameter is missing.                                                                                                        |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NotFound          | The given task ID does not exist.                                                                                                                                         |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                                                                                               |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| RequestNotAllowed | The operation is currently not allowed, possible reason: a task is running, safe monitored standstill, brakes closed, wrong X4 state or operating mode is not `Execution`.|
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                                                                                               |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

SwitchToExecution
-----------------

Switches the operating mode to Execution (requires control token). Succeeds if the mode already is
Execution and fails if a task is currently running.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
| Name              | Description                                                                                                                                         |
+===================+=====================================================================================================================================================+
| Good              | The operation succeeded.                                                                                                                            |
+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
| InvalidState      | The control token is invalid.                                                                                                                       |
+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                                                                         |
+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
| RequestNotAllowed | The operation is currently not allowed, possible reasons: mode is Programming and x4 is pressed or robot is hand-guided, task is currently running. |
+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                                                                         |
+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+

ActivateFCI
-----------

Activates the Franka Control Interface (FCI). If the FCI is already active, the operation succeeds by default.

.. note::
    Only available for the Franka Research series.

**Parameter:**

No parameters needed.

**Status Codes:**

+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name              | Description                                                                                                                                              |
+===================+==========================================================================================================================================================+
| Good              | The operation succeeded.                                                                                                                                 |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| InvalidState      | The control token is invalid.                                                                                                                            |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                                                                                              |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| RequestNotAllowed | The operation is currently not allowed, possible reasons: mode is Programming, brakes are closed, safe monitored standstill or initiating motion active. |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                                                                                              |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+

Self Tests
==========

Execute
---------

Tries to execute the self tests.

**Status Codes:**

+-------------------+---------------------------------------------------------------------------------------+
| Name              | Description                                                                           |
+===================+=======================================================================================+
| Good              | The operation succeeded.                                                              |
+-------------------+---------------------------------------------------------------------------------------+
| InvalidState      | The control token is invalid.                                                         |
+-------------------+---------------------------------------------------------------------------------------+
| UserAccessDenied  | Insufficient authorization.                                                           |
+-------------------+---------------------------------------------------------------------------------------+
| InternalError     | An internal error occurred.                                                           |
+-------------------+---------------------------------------------------------------------------------------+
