Updated documentation and tests

Author: urfeex

doc/architecture/trajectory_point_interface.rst

@@ -41,28 +41,53 @@ representations in 21 datafields. The data fields have the following meaning:
    =====  =====
    index  meaning
    =====  =====
-   0-5    trajectory point positions (Multiplied by ``MULT_JOINTSTATE``)
-   6-11   trajectory point velocities (Multiplied by ``MULT_JOINTSTATE``). For MOVEC, this contains the "via pose".
-   12-17  trajectory point accelerations (Multiplied by ``MULT_JOINTSTATE``).
-
-          For MOVEC:
-
-          - 12: velocity (Multiplied by ``MULT_JOINTSTATE``)
-          - 13: acceleration (Multiplied by ``MULT_JOINTSTATE``)
-          - 14: mode (Multiplied by ``MULT_JOINTSTATE``)
-
-   18     trajectory point type
-
-          - 0: MOVEJ
-          - 1: MOVEL
-          - 2: MOVEP
-          - 3: MOVEC
-          - 51: SPLINE)
+   0-5    trajectory point positions (multiplied by ``MULT_JOINTSTATE``).
+
+          Interpreted as joint positions [rad] or as a Cartesian pose ([m, m, m, rad, rad, rad])
+          depending on the motion type at index 18 (see below).
+
+   6-11   trajectory point velocities (multiplied by ``MULT_JOINTSTATE``).
+
+          For all MOVEC variants this field is repurposed to carry the via point (same
+          joint-vs-pose interpretation as the target at indices 0-5, see the motion type at
+          index 18).
+
+   12-17  trajectory point accelerations (multiplied by ``MULT_JOINTSTATE``).
+
+          For all MOVEC variants:
+
+          - 12: velocity (multiplied by ``MULT_JOINTSTATE``)
+          - 13: acceleration (multiplied by ``MULT_JOINTSTATE``)
+          - 14: mode (multiplied by ``MULT_JOINTSTATE``)
+
+   18     trajectory point type. The base values below use the URScript command's "natural"
+          target type (joints for ``movej`` / ``optimovej``, Cartesian pose for ``movel`` /
+          ``movep`` / ``movec`` / ``optimovel``). The ``*_POSE`` / ``*_JOINT`` variants indicate
+          that the other target kind is being sent instead.
+
+          - 0: MOVEJ – ``movej`` to a joint target
+          - 1: MOVEL – ``movel`` to a pose target
+          - 2: MOVEP – ``movep`` to a pose target
+          - 3: MOVEC – ``movec`` with pose via and pose target
+          - 4: OPTIMOVEJ – ``optimovej`` to a joint target
+          - 5: OPTIMOVEL – ``optimovel`` to a pose target
+          - 6: MOVEJ_POSE – ``movej`` to a pose target (IK on the robot controller)
+          - 7: MOVEL_JOINT – ``movel`` to the pose implied by a joint target (FK on the
+            robot controller)
+          - 8: MOVEP_JOINT – ``movep`` to the pose implied by a joint target (FK on the
+            robot controller)
+          - 9: MOVEC_JOINT – ``movec`` with joint via and joint target
+          - 10: MOVEC_JOINT_POSE – ``movec`` with pose via and joint target
+          - 11: MOVEC_POSE_JOINT – ``movec`` with joint via and pose target
+          - 12: OPTIMOVEJ_POSE – ``optimovej`` to a pose target
+          - 13: OPTIMOVEL_JOINT – ``optimovel`` to the pose implied by a joint target
+          - 51: SPLINE
 
    19     trajectory point time (in seconds, multiplied by ``MULT_TIME``)
    20     depending on trajectory point type
 
-          - MOVEJ, MOVEL, MOVEP and MOVEC: point blend radius (in meters, multiplied by ``MULT_TIME``)
+          - All MOVE* and OPTIMOVE* variants: point blend radius (in meters, multiplied by
+            ``MULT_TIME``)
           - SPLINE: spline type (1: CUBIC, 2: QUINTIC)
    =====  =====
 
@@ -75,3 +100,13 @@ where
    With ``MULT_TIME`` being 1000000, the maximum duration that can be sent is 2147 seconds, while
    precision is cut off at 1 microsecond. (The same applies to the blend radius, respectively being
    max 2147 m and 1 μm precision.)
+
+.. note::
+   The ``*_POSE`` / ``*_JOINT`` motion-type variants let callers mix joint-space and Cartesian
+   targets freely through the high-level APIs (see :ref:`instruction_executor` and the
+   ``urcl::MotionTarget`` type). On the wire the positions are always packed as a 6-tuple of
+   ``MULT_JOINTSTATE``-scaled integers; which physical quantity they represent (joint angles or
+   Cartesian pose components) is determined solely by the motion type field at index 18. The
+   corresponding mapping back to ``movej`` / ``movel`` / ``movep`` / ``movec`` / ``optimovej`` /
+   ``optimovel`` calls with either ``q`` or ``p[...]`` arguments is performed on the robot side
+   by ``resources/external_control.urscript``.

doc/examples/instruction_executor.rst

@@ -50,20 +50,37 @@ functions, so the parameter descriptions for them apply, as well. Particularly,
 choose between either a time-based execution or an acceleration / velocity parametrization
 for some move functions. The latter will be ignored if a time > 0 is given.
 
+Each motion primitive can be constructed either with its "native" target type (``vector6d_t`` for
+``MoveJ`` / ``OptimoveJ``, ``urcl::Pose`` for ``MoveL`` / ``MoveP`` / ``MoveC`` / ``OptimoveL``)
+or with a ``urcl::MotionTarget``, which can hold either a ``urcl::Q`` (joint configuration) or a
+``urcl::Pose`` (Cartesian pose). This makes it possible, for example, to use a
+``MoveLPrimitive`` with a joint configuration – the robot will then compute the forward
+kinematics on the controller and linearly interpolate in tool space towards the resulting pose.
+
 Please refer to the script manual for details.
 
 Execute a single motion
 -----------------------
 
-To run a single motion, the ``InstructionExecutor`` provides the methods ``moveJ(...)`` and
-``moveL(...)``:
+To run a single motion, the ``InstructionExecutor`` provides the methods ``moveJ(...)``,
+``moveL(...)``, ``moveP(...)``, ``moveC(...)``, ``optimoveJ(...)`` and ``optimoveL(...)``:
 
 .. literalinclude:: ../../examples/instruction_executor.cpp
    :language: c++
    :caption: examples/instruction_executor.cpp
    :linenos:
    :lineno-match:
    :start-at: double goal_time_sec = 2.0;
-   :end-before: g_my_robot->getUrDriver()->stopControl();
+   :end-before: return 0;
 
 Again, time parametrization has priority over acceleration / velocity parameters.
+
+Each motion function has two overloads: one taking the "natural" target type
+(``vector6d_t`` for ``moveJ`` / ``optimoveJ``, ``urcl::Pose`` for the other motions), and one
+taking a ``urcl::MotionTarget``. Passing a braced-initializer-list of six doubles selects the
+natural overload, so ``moveJ({ ... })`` continues to be interpreted as joint positions and
+``moveL({ ... })`` as a Cartesian pose. To select the other interpretation, wrap the values in
+``urcl::Q{...}`` or ``urcl::Pose{...}`` explicitly – for example,
+``moveJ(urcl::Pose{...})`` performs a ``movej`` towards a Cartesian target and
+``moveL(urcl::Q{...})`` performs a ``movel`` towards the pose implied by a joint configuration.
+The same rules apply to ``moveP``, ``moveC``, ``optimoveJ`` and ``optimoveL``.

include/ur_client_library/control/motion_primitives.h

@@ -42,22 +42,36 @@ namespace urcl
 namespace control
 {
 
+/*!
+ * \brief Discriminator for the motion primitive type sent over the trajectory interface.
+ *
+ * The base values (``MOVEJ``, ``MOVEL``, ``MOVEP``, ``MOVEC``, ``OPTIMOVEJ``, ``OPTIMOVEL``) use
+ * their "natural" target type for the URScript command (joint configuration for ``movej`` /
+ * ``optimovej``, Cartesian pose for ``movel`` / ``movep`` / ``movec`` / ``optimovel``). The
+ * additional ``*_POSE`` and ``*_JOINT`` entries indicate that the *other* target kind was
+ * requested, e.g. ``MOVEJ_POSE`` performs a ``movej`` towards a Cartesian pose, and
+ * ``MOVEC_POSE_JOINT`` performs a ``movec`` whose via point is a Cartesian pose and whose target
+ * is a joint configuration.
+ *
+ * These values must stay in sync with the ``MOTION_TYPE_*`` constants in
+ * ``resources/external_control.urscript``.
+ */
 enum class MotionType : uint8_t
 {
-  MOVEJ = 0,
-  MOVEL = 1,
-  MOVEP = 2,
-  MOVEC = 3,
-  OPTIMOVEJ = 4,
-  OPTIMOVEL = 5,
-  MOVEJ_POSE = 6,
-  MOVEL_JOINT = 7,
-  MOVEP_JOINT = 8,
-  MOVEC_JOINT = 9,
-  MOVEC_JOINT_POSE = 10,
-  MOVEC_POSE_JOINT = 11,
-  OPTIMOVEJ_POSE = 12,
-  OPTIMOVEL_JOINT = 13,
+  MOVEJ = 0,              //!< ``movej`` towards a joint configuration.
+  MOVEL = 1,              //!< ``movel`` towards a Cartesian pose.
+  MOVEP = 2,              //!< ``movep`` towards a Cartesian pose.
+  MOVEC = 3,              //!< ``movec`` with via and target as Cartesian poses.
+  OPTIMOVEJ = 4,          //!< ``optimovej`` towards a joint configuration.
+  OPTIMOVEL = 5,          //!< ``optimovel`` towards a Cartesian pose.
+  MOVEJ_POSE = 6,         //!< ``movej`` towards a Cartesian pose.
+  MOVEL_JOINT = 7,        //!< ``movel`` towards a joint configuration.
+  MOVEP_JOINT = 8,        //!< ``movep`` towards a joint configuration.
+  MOVEC_JOINT = 9,        //!< ``movec`` with via and target both as joint configurations.
+  MOVEC_JOINT_POSE = 10,  //!< ``movec`` with a Cartesian via and a joint target.
+  MOVEC_POSE_JOINT = 11,  //!< ``movec`` with a joint via and a Cartesian target.
+  OPTIMOVEJ_POSE = 12,    //!< ``optimovej`` towards a Cartesian pose.
+  OPTIMOVEL_JOINT = 13,   //!< ``optimovel`` towards a joint configuration.
   SPLINE = 51,
   UNKNOWN = 255
 };
@@ -96,6 +110,14 @@ struct MoveJPrimitive : public MotionPrimitive
     this->velocity = velocity;
     this->blend_radius = blend_radius;
   }
+  /*!
+   * \brief Construct a MoveJ primitive from a \ref urcl::MotionTarget.
+   *
+   * If ``target`` holds a \ref urcl::Q, ``type`` is set to \ref MotionType::MOVEJ and
+   * ``target_joint_configuration`` is populated. If ``target`` holds a \ref urcl::Pose, ``type``
+   * is set to \ref MotionType::MOVEJ_POSE and ``target_pose`` is populated instead; the robot
+   * will internally solve inverse kinematics to reach the pose with a ``movej``.
+   */
   MoveJPrimitive(const urcl::MotionTarget& target, const double blend_radius = 0,
                  const std::chrono::duration<double> duration = std::chrono::milliseconds(0),
                  const double acceleration = 1.4, const double velocity = 1.04)
@@ -139,6 +161,15 @@ struct MoveLPrimitive : public MotionPrimitive
     this->velocity = velocity;
     this->blend_radius = blend_radius;
   }
+  /*!
+   * \brief Construct a MoveL primitive from a \ref urcl::MotionTarget.
+   *
+   * If ``target`` holds a \ref urcl::Pose, ``type`` is set to \ref MotionType::MOVEL. If it
+   * holds a \ref urcl::Q, ``type`` is set to \ref MotionType::MOVEL_JOINT and the configuration
+   * is stored in ``target_joint_configuration``. The robot will still execute a tool-space
+   * linear motion, resolving the joint configuration to its forward kinematics pose on the
+   * controller.
+   */
   MoveLPrimitive(const urcl::MotionTarget& target, const double blend_radius = 0,
                  const std::chrono::duration<double> duration = std::chrono::milliseconds(0),
                  const double acceleration = 1.4, const double velocity = 1.04)
@@ -179,6 +210,12 @@ struct MovePPrimitive : public MotionPrimitive
     this->velocity = velocity;
     this->blend_radius = blend_radius;
   }
+  /*!
+   * \brief Construct a MoveP primitive from a \ref urcl::MotionTarget.
+   *
+   * Analogous to \ref MoveJPrimitive / \ref MoveLPrimitive: a \ref urcl::Pose selects
+   * \ref MotionType::MOVEP, a \ref urcl::Q selects \ref MotionType::MOVEP_JOINT.
+   */
   MovePPrimitive(const MotionTarget& target, const double blend_radius = 0, const double acceleration = 1.4,
                  const double velocity = 1.04)
   {
@@ -220,6 +257,18 @@ struct MoveCPrimitive : public MotionPrimitive
     this->mode = mode;
   }
 
+  /*!
+   * \brief Construct a MoveC primitive from two \ref urcl::MotionTarget values.
+   *
+   * Every combination of \ref urcl::Pose and \ref urcl::Q for the via point and the target is
+   * supported and mapped to the corresponding \ref MotionType (``MOVEC``,
+   * ``MOVEC_JOINT``, ``MOVEC_POSE_JOINT``, or ``MOVEC_JOINT_POSE``). When a joint configuration
+   * is used for either role, only the corresponding joint member is populated and the pose
+   * member is set to a default-constructed \ref urcl::Pose.
+   *
+   * \throws urcl::UrException if either variant is ever extended with an alternative that is
+   * not handled here.
+   */
   MoveCPrimitive(const MotionTarget& via_point, const MotionTarget& target, const double blend_radius = 0,
                  const double acceleration = 1.4, const double velocity = 1.04, const int32_t mode = 0)
   {
@@ -326,6 +375,12 @@ struct OptimoveJPrimitive : public MotionPrimitive
     this->velocity = velocity_fraction;
   }
 
+  /*!
+   * \brief Construct an OptimoveJ primitive from a \ref urcl::MotionTarget.
+   *
+   * A \ref urcl::Q selects \ref MotionType::OPTIMOVEJ, a \ref urcl::Pose selects
+   * \ref MotionType::OPTIMOVEJ_POSE.
+   */
   OptimoveJPrimitive(const MotionTarget& target, const double blend_radius = 0,
                      const double acceleration_fraction = 0.3, const double velocity_fraction = 0.3)
   {
@@ -366,6 +421,12 @@ struct OptimoveLPrimitive : public MotionPrimitive
     this->acceleration = acceleration_fraction;
     this->velocity = velocity_fraction;
   }
+  /*!
+   * \brief Construct an OptimoveL primitive from a \ref urcl::MotionTarget.
+   *
+   * A \ref urcl::Pose selects \ref MotionType::OPTIMOVEL, a \ref urcl::Q selects
+   * \ref MotionType::OPTIMOVEL_JOINT.
+   */
   OptimoveLPrimitive(const MotionTarget& target, const double blend_radius = 0,
                      const double acceleration_fraction = 0.3, const double velocity_fraction = 0.3)
   {

include/ur_client_library/exceptions.h

@@ -217,6 +217,13 @@ class UnsupportedMotionType : public UrException
   }
 };
 
+/*!
+ * \brief Thrown when data received from or passed through the library does not match the
+ * expected structure or value range.
+ *
+ * Examples include motion targets whose variant alternative is not handled by the corresponding
+ * primitive constructor.
+ */
 class InvalidData : public UrException
 {
 public:

include/ur_client_library/types.h

@@ -34,6 +34,17 @@ using vector6d_t = std::array<double, 6>;
 using vector6int32_t = std::array<int32_t, 6>;
 using vector6uint32_t = std::array<uint32_t, 6>;
 
+/*!
+ * \brief A joint configuration (6 joint positions in radians).
+ *
+ * This is a strong type around a \ref vector6d_t meant to unambiguously express "this 6-tuple
+ * represents joint values", as opposed to a Cartesian pose. It is primarily used together with
+ * \ref MotionTarget to select between joint-space and Cartesian-space targets when calling
+ * motion functions that can accept either.
+ *
+ * Unlike raw initializer lists (``{...}``) which may bind to either \ref vector6d_t or
+ * \ref Pose, wrapping values in ``urcl::Q{...}`` always forces a joint-target interpretation.
+ */
 struct Q
 {
   constexpr Q(double q1, double q2, double q3, double q4, double q5, double q6) : values{ q1, q2, q3, q4, q5, q6 }
@@ -65,6 +76,20 @@ struct Pose
   }
 };
 
+/*!
+ * \brief A tagged union representing either a joint target (\ref Q) or a Cartesian target
+ * (\ref Pose).
+ *
+ * ``MotionTarget`` is used throughout the motion API (e.g.
+ * \ref InstructionExecutor::moveJ "InstructionExecutor::moveJ" and the ``Move*Primitive``
+ * constructors) to let callers choose at call site whether a motion should be parametrized in
+ * joint space or in Cartesian space without needing separate overloads for every combination.
+ *
+ * The overloads that take a ``MotionTarget`` are provided alongside explicit \ref vector6d_t and
+ * \ref Pose overloads so that plain braced-initializer calls keep binding to the previous
+ * behaviour; only explicitly constructed \ref Q or \ref Pose values (or an already-built
+ * ``MotionTarget``) select the variant-based path.
+ */
 using MotionTarget = std::variant<Q, Pose>;
 
 template <class T, std::size_t N>