Simple Python Client Tutorial
*****************************

This sample OPC UA client is written using the `FreeOpcUa / python-opcua <https://github.com/FreeOpcUa/python-opcua>`_ library. Using this library, you can very easily set up a OPC UA client with very few lines of code. You can install the library using Python's package manager pip. This tutorial contains installation instructions for the Linux/Ubuntu operating system. On other platforms like Windows or MacOS, the commands will be similar.

1. Install Python
=================

Although the library also runs with older Python versions (2.x), we will be using Python 3. We also need to install Python's distutils as a dependency of Python's package manager. To install both packages, run the following commands.

.. code-block:: bash

  $ sudo apt-get update
  [...]
  $ sudo apt-get install python3 python3-distutils -y
  [...]
  $ python3 --version
  Python 3.6.7

2. Install Pip
==============

`Pip <https://pip.pypa.io>`_ is Python's package manager. You can download it's installation file using the curl command, which therefore also needs to be installed on your machine. Follow the following commands to perform the installation.

.. code-block:: bash

  $ sudo apt-get install curl -y
  [...]
  $ curl --version
  curl 7.58.0 [...]
  $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
  [...]
  $ sudo 
  [...]
  Successfully installed pip-19.1.1 setuptools-41.0.1 wheel-0.33.4

3. Install FreeOpcUa / python-opcua
===================================

.. code-block:: bash

  $ sudo pip install opcua
  [...]
  Successfully installed lxml-4.3.3 opcua-0.98.7 python-dateutil-2.8.0 pytz-2019.1 six-1.12.0

4. Run the Sample Python Client
===============================

With all necessary dependencies installed, we can run the OPC UA sample client to write and read-back a Key-Pose-Pair on the robot's OPC UA server.

.. code-block:: python

  # Import dependencies
  from opcua import Client, ua
  from opcua.common.type_dictionary_buider import get_ua_class

  # Configure and connect the client
  client = Client("opc.tcp://<robot-ip>:4840/") # 4840 is the default OPC UA port
  client.set_user("<username>") # Change to your user name ...
  client.set_password("<password>") # ... and password here
  client.connect() # Connect our client to the robot
  typedefs = client.load_type_definitions() # Load custom type definitions

  # Browse the server
  root = client.get_root_node()
  robot = root.get_child("0:Objects").get_child("2:Robot")
  keyPoseMapObject = robot.get_child("2:KeyValueMaps").get_child("2:KeyPoseMap")
  setKeyPoseMethod = keyPoseMapObject.get_child("2:Replace")
  getKeyPoseMethod = keyPoseMapObject.get_child("2:Read")

  # Create a new Key-Pose-Pair
  myKeyPosePair = get_ua_class("KeyPosePair")()
  myKeyPosePair.Key = "test key"
  myKeyPosePair.Value = [  1.0,  0.0,  0.0,  0.0, \
                           0.0, -1.0,  0.0,  0.0, \
                           0.0,  0.0, -1.0,  0.0, \
                           0.3,  0.0,  0.5,  1.0 ]

  keyPoseMapObject.call_method(setKeyPoseMethod, ua.Variant(myKeyPosePair, ua.VariantType.ExtensionObject))
  print(keyPoseMapObject.call_method(getKeyPoseMethod, "test key"))

This example client can be downloaded :download:`here <_static/download/sampleClient.py>`. Save this file somewhere on your machine, then execute the client from that directory with the following command.

.. code-block:: bash

  $ python3 sampleClient.py
  Sending plain-text password
  [0.9803357124328613, -1.4880852177157067e-06, 0.19733697175979614, 0.0,
  -1.6206167856580578e-06, -1.0, 5.101090323478275e-07, 0.0,
  0.19733697175979614, -8.198857699426298e-07, -0.9803357124328613, 0.0,
  0.3787211775779724, 0.03682789206504822, 0.5469607710838318, 1.0]

The pose named `test pose` is now available on the OPC UA server of the robot. It can now be used by OPC UA apps and other clients.