Merge branch 'master' into test_10.13

Author: urfeex

CHANGELOG.rst

@@ -2,6 +2,19 @@
 Changelog for package ur_client_library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+2.13.0 (2026-06-17)
+-------------------
+* [ScriptCommandInterface] Add set_target_payload support to ScriptCommandInterface (`#515 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/515>`_)
+* [Primary] sendScriptBlocking: Restart interface and resend script on readOnlyInterfaceException (`#522 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/522>`_)
+* [DashboardClientX] Apply httplib timeouts; wire setReceiveTimeout() (`#518 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/518>`_)
+* [Docs] Remove section about URCapX in development (`#521 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/521>`_)
+* [Primary] Send script blocking return refactor (`#520 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/520>`_)
+* Add missing robot types to helper functions (`#513 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/513>`_)
+* [RTDE] Add new controller_step RTDE field (`#514 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/514>`_)
+* [Primary] Primary client script execution feedback (`#484 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/484>`_)
+* Add robotSeriesString function (`#510 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/510>`_)
+* Contributors: Felix Exner, Sergi Romero, URJala, Vinicius de Oliveira, dependabot[bot]
+
 2.12.0 (2026-05-19)
 -------------------
 * [CI] Make circular motion in example more compatible (`#508 <https://github.com/UniversalRobots/Universal_Robots_Client_Library/issues/508>`_)

doc/architecture/primary_client.rst

@@ -26,17 +26,21 @@ Method signature:
 .. code-block:: c++
 
    bool sendScriptBlocking(
-     std::string program,
-     std::string script_name = "",
-     std::chrono::milliseconds timeout = std::chrono::seconds(1),
-     bool fail_on_warnings = true
+     const std::string& program,
+     const std::string& script_name = "",
+     const std::chrono::milliseconds start_timeout = std::chrono::seconds(1),
+     const bool fail_on_warnings = true,
+     const bool retry_on_readonly_interface = true
    );
 
 | The ``sendScriptBlocking`` method will also accept valid URScript code, but blocks until the execution result of the given program is available.
-| Prior to transferring the program it will first check that the robot is in a state where it can execute programs, if not it returns false.
+| Prior to transferring the program it will first check that the robot is in a state where it can execute programs, otherwise an exception is thrown.
 | If the robot is ready, the program is then transferred, and the method will wait for the robot to report that the program has either started, finished or encountered an error.
-| If the program has not started within the given ``timeout``, the method returns false.
-| If the robot encounters an error or runtime exception during program execution the method also returns false.
-| If ``fail_on_warnings`` is true, it will also return false, if the robot reports a warning during program execution. Note: protective stops are reported as warnings by the robot.
-| The method only returns true if the program is successfully executed on the robot.
+| If the program has not started within the given ``start_timeout``, the method throws an exception.
+| If the robot encounters an error or runtime exception during program execution the method also throws an exception.
+| If ``fail_on_warnings`` is true, it will also throw an exception, if the robot reports a warning during program execution. Note: protective stops are reported as warnings by the robot.
+| If ``retry_on_readonly_interface`` is true, the method will restart the primary interface and retry sending the program, if the primary interface is read-only. It will retry once, and if the interface is still read-only, an exception will be thrown. If false, the exception will be thrown, without restarting/retrying.
+| If no exceptions are thrown, the script has been executed successfully.
 | This method also accepts secondary programs, but no feedback is available for those, so it will behave similarly to the ``sendScript`` method in those cases, except for the pre-transfer checks.
+| The exact exceptions that are thrown in various cases can be seen in the `primary client header file <https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/include/ur_client_library/primary/primary_client.h>`_.
+| Note: This method clears all stored error codes in the client during execution.

doc/architecture/script_command_interface.rst

@@ -25,6 +25,7 @@ At the time of writing the ``ScriptCommandInterface`` provides the following fun
 - ``setGravity()``: Set the gravity vector for the robot.
 - ``setTcpOffset()``: Set the TCP offset of the robot.
 - ``setFrictionScales()``: Set viscous and Coulomb friction scale factors for direct torque control.
+- ``setTargetPayload()``: Set the active payload mass, center of gravity, inertia matrix and transition time.
 
 Communication protocol
 ----------------------
@@ -58,6 +59,7 @@ The robot reads from the "script_command_socket" expecting a 32 bit integer repr
            - 9: setGravity
            - 10: setTcpOffset
            - 11: setFrictionScales
+           - 12: setTargetPayload
    1-27   data fields specific to the command
    =====  =====
 
@@ -77,7 +79,7 @@ The robot reads from the "script_command_socket" expecting a 32 bit integer repr
    index  meaning
    =====  =====
    1      Payload mass in kg (floating point)
-   2-4    Payload center of gravity in m, displacement from the toolmpount (floating point)
+   2-4    Payload center of gravity in m, displacement from the tool mount (floating point)
    =====  =====
 
 .. table:: With setToolVoltage command
@@ -180,6 +182,18 @@ The robot reads from the "script_command_socket" expecting a 32 bit integer repr
    7-12   Coulomb friction scale factors. One number per joint, range [0-1]. 0 means no compensation for that joint. 1 means full compensation. Default is [0.8, 0.8, 0.7, 0.8, 0.8, 0.8]. (floating point)
    =====  =====
 
+.. table:: With setTargetPayload command
+   :widths: auto
+
+   =====  =====
+   index  meaning
+   =====  =====
+   1      Payload mass in kg (floating point)
+   2-4    Payload center of gravity in m, displacement from the tool mount (floating point)
+   5-10   Payload inertia matrix [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] in kg·m² (floating point)
+   11     Payload transition time in seconds (floating point)
+   =====  =====
+
 .. note::
    In URScript the ``socket_read_binary_integer()`` function is used to read the data from the
    script command socket. The first index in that function's return value is the number of integers read,
@@ -188,9 +202,9 @@ The robot reads from the "script_command_socket" expecting a 32 bit integer repr
    function. E.g. reading the boolean value for friction compensation in the
    ``setFrictionCompensation`` command would be done by accessing index 2 of the result array.
 
-   All floating point data 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.
+   All floating point data is encoded into an integer representation and has to be divided by either the
+   ``MULT_JOINTSTATE`` or ``MULT_TIME`` constant to get the actual floating point value. These constants
+   are defined in the ``ReverseInterface`` class.
 
 Data sent from the robot
 ^^^^^^^^^^^^^^^^^^^^^^^^

doc/images/initial_setup_images/services_polyscope5.png

@@ -46,9 +46,6 @@ table below or checkout the latest tag before the breaking changes were introduc
        replacing the Dashboard Server in version 10.11.0. It covers robot state control and loading
        and playing programs.
        From version 10.12, it also supports uploading programs to the robot and downloading programs from the robot, as well as listing existing programs on the robot.
-     - 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>`_
 
 .. |polyscope| replace:: PolyScope
 

doc/polyscope_compatibility.rst

@@ -80,6 +80,9 @@ void sendScriptCommands()
     run_cmd("Disabling tool contact mode", []() { g_my_robot->getUrDriver()->endToolContact(); });
     run_cmd("Setting TCP offset to [0.0, 0.0, 0.10, 0.0, 0.0, 0.0]",
             []() { g_my_robot->getUrDriver()->setTcpOffset({ 0.0, 0.0, 0.10, 0.0, 0.0, 0.0 }); });
+    run_cmd("Setting payload to 2.0kg with custom inertia and 0.5s transition time", []() {
+      g_my_robot->getUrDriver()->setTargetPayload(2.0, { 0.0, 0.0, 0.1 }, { 0.003, 0.003, 0.003, 0.0, 0.0, 0.0 }, 0.5);
+    });
 
     if (g_support_set_friction_scales)
     {

examples/script_command_interface.cpp

@@ -45,13 +45,10 @@ def example_fun():
   relative_move = p[0,-0.1,0,0,0,0]
   movel(pose_trans(current_pose, relative_move), t=1)
 end)""";
-
-  if (client.sendScriptBlocking(fully_defined_script))
-  {
-    // The function definition can also be omitted
-    // A function name will then be auto generated
-    client.sendScriptBlocking(R"(textmsg("Successful program execution"))");
-  }
+  client.sendScriptBlocking(fully_defined_script);
+  // The function definition can also be omitted
+  // A function name will then be auto generated
+  client.sendScriptBlocking(R"(textmsg("Successful program execution"))");
   // A script-function name can also be passed to the method
   // A timeout can also be given to limit the wait for the passed function to start. If timeout = 0, it will
   // wait indefinitely.
@@ -66,18 +63,26 @@ end
 )";
   client.sendScriptBlocking(secondary_script);
 
-  // Sending wrong script code will result in a clear error
+  // Sending wrong script code will result in an exception with a clear explanation
   const std::string bad_script_code = R"""(
 def bad_code():
   current_pose = get_target_tcp_pose()
   movel(current_pos) # note pose vs pos
 end)""";
   URCL_LOG_INFO("Sending bad script code...");
-  bool success = client.sendScriptBlocking(bad_script_code);
+  try
   {
-    std::stringstream ss;
-    ss << "Execution of bad code successful? " << std::boolalpha << success;
-    URCL_LOG_INFO("%s", ss.str().c_str());
+    client.sendScriptBlocking(bad_script_code);
+  }
+  catch (const RobotRuntimeException& exc)
+  {
+    URCL_LOG_INFO("Caught expected runtime exception from sendScriptBlocking");
+    URCL_LOG_INFO(exc.what());
+  }
+  catch (const UrException& exc)
+  {
+    URCL_LOG_ERROR("Caught unexpected exception from sendScriptBlocking");
+    URCL_LOG_ERROR(exc.what());
   }
 
   // We can also send script code without any checks
@@ -87,7 +92,7 @@ end)""";
   // E.g. sending the bad script here will not give us any information
   // The return value will only tell us that the script code has been sent to the robot.
   URCL_LOG_INFO("Sending bad script code without feedback...");
-  success = client.sendScript(bad_script_code);
+  bool success = client.sendScript(bad_script_code);
   {
     std::stringstream ss;
     ss << "Bad code sent to robot successfully? " << std::boolalpha << success;

examples/send_script.cpp

@@ -82,6 +82,7 @@ class ReverseInterface
 {
 public:
   static const int32_t MULT_JOINTSTATE = 1000000;
+  static const int32_t MULT_TIME = 1000000;
 
   ReverseInterface() = delete;
   /*!

include/ur_client_library/control/reverse_interface.h

@@ -91,6 +91,20 @@ class ScriptCommandInterface : public ReverseInterface
    */
   bool setPayload(const double mass, const vector3d_t* cog);
 
+  /*!
+   * \brief Set the target payload mass, center of gravity and inertia matrix
+   *
+   * \param mass mass in kilograms
+   * \param cog  Center of Gravity, a vector [CoGx, CoGy, CoGz] specifying the displacement (in meters) from the
+   * toolmount
+   * \param inertia Inertia matrix elements [Ixx, Iyy, Izz, Ixy, Ixz, Iyz]
+   * \param transition_time Duration of the payload property changes in seconds
+   *
+   * \returns True, if the write was performed successfully, false otherwise.
+   */
+  bool setTargetPayload(const double mass, const vector3d_t* cog, const vector6d_t* inertia,
+                        const double transition_time = 0.0);
+
   /*!
    * \brief Set the gravity vector
    *
@@ -264,6 +278,7 @@ class ScriptCommandInterface : public ReverseInterface
     SET_GRAVITY = 9,                ///< Set gravity vector
     SET_TCP_OFFSET = 10,            ///< Set TCP offset
     SET_FRICTION_SCALES = 11,       ///< Set viscous and Coulomb friction scales for direct_torque
+    SET_TARGET_PAYLOAD = 12,        ///< Set target payload
   };
 
   /*!

include/ur_client_library/control/script_command_interface.h

@@ -63,7 +63,6 @@ std::string trajectoryResultToString(const TrajectoryResult result);
 class TrajectoryPointInterface : public ReverseInterface
 {
 public:
-  static const int32_t MULT_TIME = 1000000;
   static const int MESSAGE_LENGTH = 21;
 
   TrajectoryPointInterface() = delete;