Add reverse_interface docuemtnation

Author: urfeex

doc/architecture.rst

@@ -17,31 +17,16 @@ fully functioning robot interface. For details on how to use it, please see the
    :maxdepth: 1
 
    architecture/dashboard_client
+   architecture/reverse_interface
    architecture/rtde_client
    architecture/script_command_interface
    architecture/script_sender
+   architecture/trajectory_point_interface
 
 
 The ``UrDriver``'s modules will be explained in the following.
 
 
-ReverseInterface
-----------------
-
-The ``ReverseInterface`` opens a TCP port on which a custom protocol is implemented between the
-robot and the control PC. The port can be specified in the class constructor.
-
-It's basic functionality is to send a vector of floating point data together with a mode. It is
-meant to send joint positions or velocities together with a mode that tells the robot how to
-interpret those values (e.g. ``SERVOJ``, ``SPEEDJ``). Therefore, this interface can be used to do
-motion command streaming to the robot.
-
-In order to use this class in an application together with a robot, make sure that a corresponding
-URScript is running on the robot that can interpret the commands sent. See `this example
-script <../resources/external_control.urscript>`_ for reference.
-
-Also see the :ref:`ScriptSender` for a way to define the corresponding URScript on the
-control PC and sending it to the robot upon request.
 
 Other public interface functions
 --------------------------------

doc/architecture/reverse_interface.rst

@@ -0,0 +1,69 @@
+.. _reverse_interface:
+
+ReverseInterface
+================
+
+
+The ``ReverseInterface`` opens a TCP port on which a custom protocol is implemented between the
+robot and the control PC. The port can be specified in the class constructor.
+
+It's basic functionality is to send a vector of floating point data together with a mode. It is
+meant to send joint positions or velocities together with a mode that tells the robot how to
+interpret those values (e.g. ``SERVOJ``, ``SPEEDJ``). Therefore, this interface can be used to do
+motion command streaming to the robot.
+
+In order to use this class in an application together with a robot, make sure that a corresponding
+URScript is running on the robot that can interpret the commands sent. See `this example
+script <https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/resources/external_control.urscript>`_ for reference.
+
+The ``ReverseInterface`` together with the :ref:`script_command_interface`, the
+:ref:`trajectory_point_interface` and the
+`external_control.urscript
+<https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/resources/external_control.urscript>`_
+creates a communication protocol in order to control many of the robot's functionalities.
+
+Also see the :ref:`ScriptSender` for a way to define the corresponding URScript on the
+control PC and sending it to the robot upon request.
+
+Communication protocol
+----------------------
+
+
+The ``ReverseInterface``'s "reverse_socket" on the robot is expecting 32 bit integer
+representations 8 datafields frequently. The timeout with which new data is expected can vary depending
+on the current control mode and is set as part of the message. The data fields have the following
+meaning:
+
+.. table:: reverse_socket message format
+   :widths: auto
+
+   =====  =====
+   index  meaning
+   =====  =====
+   0      read timeout in milliseconds. The next read from the socket will use this timeout.
+   1-6    Current motion target. depending on the control mode, this can be interpreted as joint
+          positions or velocities or a Cartesian pose.
+   7      Control mode. Can be either of
+           - -2: STOPPED
+           - -1: UNINITIALIZED
+           - 0: IDLE -- no motion
+           - 1: SERVOJ -- High-frequent joint position control
+           - 2: SPEEDJ -- Low-frequent joint velocity control
+           - 3: FORWARD -- Trajectory interpolation on the robot
+           - 4: SPEEDL
+           - 5: POSE
+           - 6: FREEDRIVE
+           - 7: TOOL_IN_CONTACT
+   =====  =====
+
+.. note::
+   In URScript the ``socket_read_binary_integer()`` function is used to read the data from the
+   reverse socket. The first index in that function's return value is the number of integers read,
+   so the actual data starts at index 1. The indices in the table above are shifted by one when
+   accessing the result array of the URScript function.
+
+   The motion target is encoded into an integer representation and has to be divided by the
+   ``MULT_JOINTSTATE`` constant to get the actual floating point value. This constant is defined in
+   ``ReverseInterface`` class.
+
+Depending on the control mode one can use the ``write()`` (SERVOJ, SPEEDJ, SPEEDL, POSE), ``writeTrajectoryControlMessage()`` (FORWARD) or ``writeFreedriveControlMessage()`` (FREEDRIVE) function to write a message to the "reverse_socket".