Update documentation for PolyScope X dashboard client

Author: urfeex

doc/architecture/dashboard_client.rst

@@ -5,25 +5,78 @@
 DashboardClient
 ===============
 
-The ``DashboardClient`` wraps the calls on the `Dashboard server <https://www.universal-robots.com/articles/ur-articles/dashboard-server-e-series-port-29999/>`_
+For CB3 robots and PolyScope 5 the ``DashboardClient`` wraps the calls on the `Dashboard server <https://www.universal-robots.com/articles/ur-articles/dashboard-server-e-series-port-29999/>`_
 directly into C++ functions.
 
-After connecting to the dashboard server by using the ``connect()`` function, dashboard calls can be
-sent using the ``sendAndReceive()`` function. Answers from the dashboard server will be returned as
-string from this function. If no answer is received, a ``UrException`` is thrown.
+For PolyScope X the so-called Robot API `released with PolyScope X 10.11.0
+<https://www.universal-robots.com/articles/ur/release-notes/release-note-software-version-1011x/>`_
+is used. It offers a subset of the Dashboard Server from previous software versions.
 
-Some functions are also wrapped into ``command...()`` functions such as
-``commandCloseSafetyPopup()``. These functions are blocking and will wait for the necessary action
-being done. This can involve querying another call to the dashboard server until the action is
-done. For example, ``commandPowerOn()`` will block until the robot reports "Robotmode: RUNNING" or
-the given timeout is reached.
+After connecting to the dashboard server by using the ``connect()`` function, dashboard calls can
+be done using the ``command...()`` functions such as ``commandCloseSafetyPopup()``. These functions
+are blocking and will wait for the necessary action being done. This can involve querying another
+call to the dashboard server until the action is done. For example, ``commandPowerOn()`` will block
+until the robot reports "Robotmode: RUNNING" or the given timeout is reached.
 
-The `dashboard_example.cpp <https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/examples/dashboard_example.cpp>`_ shows how to use this class:
+The return value of those functions indicate whether or not the call was successful. If you want to
+get the call's full response, use the ``command...WithResponse()`` calls, instead. They will return
+a response struct
+
+.. literalinclude:: ../../include/ur_client_library/ur/dashboard_client_implementation.h
+   :language: c++
+   :caption: urcl::DashboardResponse
+   :start-at: struct DashboardResponse
+   :end-at: };
+
+The ``data`` dictionary of that response struct is populated by each command individually. See the
+commands' docstrings for details.
+
+The `dashboard_example.cpp <https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/examples/dashboard_example.cpp>`_ shows how to use the dashboard client:
 
 .. literalinclude:: ../../examples/dashboard_example.cpp
    :language: c++
    :caption: examples/dashboard_example.cpp
    :linenos:
    :lineno-match:
    :start-at: std::make_unique<DashboardClient>
-   :end-at: my_dashboard->commandCloseSafetyPopup();
+   :end-at: return 0
+
+CB 3 and PolyScope 5 only
+-------------------------
+
+All commands are blocking and will wait for the necessary action being done. The dashboard server's
+response will be compared with an expected response. For example, when calling
+``commandPowerOn(timeout)``, it is checked that the dashboard server is answering ``"Powering on"`` and
+then it is queried until the robot reports ``"Robotmode: IDLE"`` or until the timeout is reached.
+The example contains more commands that follow the same scheme.
+
+
+If you want to send a query / command to the dashboard server and only want to receive the
+response, you can use the ``sendAndReceive()`` function:
+
+.. literalinclude:: ../../examples/dashboard_example.cpp
+   :language: c++
+   :caption: examples/dashboard_example.cpp
+   :linenos:
+   :lineno-match:
+   :start-at: // Make a raw request and save the response
+   :end-at: URCL_LOG_INFO("Program state: %s", program_state.c_str());
+
+For checking the response against an expected regular expression use ``sendRequest()``:
+
+.. literalinclude:: ../../examples/dashboard_example.cpp
+   :language: c++
+   :caption: examples/dashboard_example.cpp
+   :linenos:
+   :lineno-match:
+   :start-at: // The response can be checked with a regular expression
+   :end-at: URCL_LOG_INFO("Power off command success: %d", success);
+
+PolyScope X only
+----------------
+
+Internally, the dashboard client makes calls against a RESTful (**Re**\ presentational **S**\ tate **T**\ ransfer) API. Hence, all responses contain a JSON-encoded string of the received answer. For example, an answer to a pause request could be
+
+.. code-block:: json
+
+    {"state":"PAUSED","message":"Program state changed: PAUSED","details":"Pause successful"}

doc/examples/dashboard_client.rst

@@ -7,26 +7,30 @@ This example shows how to use the builtin `Dashboard server <https://www.univers
 
 .. note::
 
-   The Dashboard Server is only available on CB3 and e-Series robots. It is not available on
-   PolyScope X.
+   The Dashboard Server euqivalent for PolyScope X is called the Robot API. In the client library
+   it is accessed through the DashboardClient, as well, as it is meant as a replacement for the
+   Dashboard Server. It doesn't offer full feature parity at the time of writing and is available
+   only from Software 10.11.0 on.
 
 
 The `dashboard_example.cpp <https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/examples/dashboard_example.cpp>`_ shows how to use this class:
 
-.. note:: For the following example to work on an e-Series (PolyScope 5) robot, the robot has to be
-   in *remote control mode*.
+.. note:: For the following example to work, the robot has to be in *remote control mode*. CB3
+   robots don't require that.
 
 .. literalinclude:: ../../examples/dashboard_example.cpp
    :language: c++
    :caption: examples/dashboard_example.cpp
    :linenos:
    :lineno-match:
-   :start-at: std::make_unique<DashboardClient>
+   :start-at: // Query the robot information
    :end-at: my_dashboard->commandCloseSafetyPopup();
 
-At first, a ``DashboardClient`` object is created with the IP address of the robot. Then, the
-client is connected to the robot. After that, the client sends a command to the robot and receives
-the answer.
+At first, a ``DashboardClient`` object is created with the IP address of the robot and a
+DashboardClient implementation policy. That policy can be either ``POLYSCOPE_X`` or ``G5``. To
+generalize this, the robot's sofware version is queried using the primary interface beforehand.
+Then, the client is connected to the robot. After that, the client sends a command to the robot and
+receives the answer.
 
 Some commands support getting the response from the robot. For example, the
 ``commandPolyScopeVersion()`` function:
@@ -49,34 +53,5 @@ initialization:
    :linenos:
    :lineno-match:
    :start-at: // Power it on
-   :end-at: // Load existing program
-
-All commands are blocking and will wait for the necessary action being done. The dashboard server's
-response will be compared with an expected response. For example, when calling
-``commandPowerOn(timeout)``, it is checked that the dashboard server is answering ``"Powering on"`` and
-then it is queried until the robot reports ``"Robotmode: IDLE"`` or until the timeout is reached.
-The example contains more commands that follow the same scheme.
-
-
-If you want to send a query / command to the dashboard server and only want to receive the
-response, you can use the ``sendAndReceive()`` function:
-
-.. literalinclude:: ../../examples/dashboard_example.cpp
-   :language: c++
-   :caption: examples/dashboard_example.cpp
-   :linenos:
-   :lineno-match:
-   :start-at: // Make a raw request and save the response
-   :end-at: URCL_LOG_INFO("Program state: %s", program_state.c_str());
-
-For checking the response against an expected regular expression use ``sendRequest()``:
-
-.. literalinclude:: ../../examples/dashboard_example.cpp
-   :language: c++
-   :caption: examples/dashboard_example.cpp
-   :linenos:
-   :lineno-match:
-   :start-at: // The response can be checked with a regular expression
-   :end-at: URCL_LOG_INFO("Power off command success: %d", success);
-
+   :end-before: // Load existing program
 

doc/polyscope_compatibility.rst

@@ -41,7 +41,9 @@ table below or checkout the latest tag before the breaking changes were introduc
    |polyscope| X doesn't support all features supported by this library for |polyscope| 5.
    Currently, the following components are known not to be supported:
 
-     - Dashboard client -- |polyscope| X doesn't have a dashboard server.
+     - Dashboard client -- |polyscope| X received the first implementation of the Robot API
+       replacing the Dashboard Server in version 10.11.0. It covers robot state control and loading
+       and playing programs.
      - Using external control on |polyscope| X requires another URCapX for making external control
        work. This is currently in the process of being created.
        See `Universal Robots External Control URCapX <https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCapX>`_

examples/dashboard_example.cpp

@@ -59,19 +59,28 @@ int main(int argc, char* argv[])
     robot_ip = std::string(argv[1]);
   }
 
+  // Query the robot information from the primary interface in order to select the correct
+  // implementation policy.
   urcl::comm::INotifier notifier;
   urcl::primary_interface::PrimaryClient primary_client(robot_ip, notifier);
   primary_client.start();
   auto version_information = primary_client.getRobotVersion();
+  DashboardClient::ClientPolicy policy = DashboardClient::ClientPolicy::POLYSCOPE_X;
+  if (version_information->major < 10)
+  {
+    policy = DashboardClient::ClientPolicy::G5;
+  }
 
   // Connect to the robot Dashboard Server
-  auto my_dashboard = std::make_unique<DashboardClient>(robot_ip, DashboardClient::ClientPolicy::POLYSCOPE_X);
+  auto my_dashboard = std::make_unique<DashboardClient>(robot_ip, policy);
   if (!my_dashboard->connect())
   {
     URCL_LOG_ERROR("Could not connect to dashboard");
     return 1;
   }
 
+  // Bring the robot to a defined state being powered off. We're ignoring errors here since
+  // powering off an already powered off robot will return an error.
   if (version_information->major < 10)
   {
     if (!my_dashboard->commandPowerOff())