comment improvements

Author: acmorrow

examples/trajectory_streaming.cpp

@@ -53,18 +53,32 @@
 //
 // Caller contract:
 //
-//   1. Do not starve the controller. Once trajectory execution begins, the
-//      URScript-side reader times out reads after one step time (~8 ms once
-//      moving). A timeout while streaming is treated as a producer fault and
-//      yields TRAJECTORY_RESULT_FAILURE via the trajectory-done callback.
-//      The producer must keep at least one point in flight on the trajectory
-//      socket at all times until STREAM_END has been sent.
+//   1. The next point must be in the OS socket buffer before the
+//      currently-executing point's spline finishes. The URScript reader
+//      only attempts a socket read after finishing each spline segment;
+//      the read uses a short timeout (~8 ms on PolyScope 5, ~2 ms on
+//      PolyScope X), and if no point is available within that window
+//      the trajectory ends with TRAJECTORY_RESULT_FAILURE.
+//
+//      The implication: the time you have between consecutive writes is
+//      essentially the in-progress point's tmptime. Dense trajectories
+//      (8 ms per point) demand 8 ms-paced production. Sparse trajectories
+//      (1 s per point) give you 1 s. A single point with tmptime = 60 s
+//      gives you a full minute to produce the next one.
+//
+//      The simplest correct producer pattern is "write as fast as you
+//      can": call writeTrajectorySplinePoint in a tight loop. The OS
+//      send/receive buffer absorbs ~760 spline points; TCP backpressure
+//      naturally throttles the producer when the buffer fills, blocking
+//      writeTrajectorySplinePoint until the consumer has drained enough
+//      to make room. No manual pacing is required. Starvation only
+//      arises if the producer's average production rate falls below the
+//      consumer's average consumption rate over a window longer than
+//      what the OS buffer can absorb.
 //
 //   2. Send STREAM_END while at least one streamed point is still
-//      unconsumed. This is implied by rule 1 but worth stating: if the
-//      producer pauses long enough after the last spline point that the
-//      consumer drains the buffer before STREAM_END arrives, rule 1 will
-//      have already failed.
+//      unconsumed. This is implied by rule 1: if the consumer drained the
+//      buffer before STREAM_END arrived, rule 1 already failed.
 //
 //   3. Make the last streamed point a controlled-stop terminal:
 //      qd = (0, ..., 0), qdd = (0, ..., 0). URScript's spline runner applies

include/ur_client_library/control/reverse_interface.h

@@ -124,15 +124,37 @@ class ReverseInterface
                      const RobotReceiveTimeout& robot_receive_timeout = RobotReceiveTimeout::millisec(20));
 
   /*!
-   * \brief Writes needed information to the robot to be read by the URScript program.
+   * \brief Sends a trajectory-control message to the URScript program over the reverse socket.
    *
-   * \param trajectory_action 1 if a trajectory is to be started, -1 if it should be stopped
-   * \param point_number The number of points of the trajectory to be executed
-   * \param robot_receive_timeout The read timeout configuration for the reverse socket running in the external
-   * control script on the robot. If you want to make the read function blocking then use RobotReceiveTimeout::off()
-   * function to create the RobotReceiveTimeout object
+   * \param trajectory_action One of the values of TrajectoryControlMessage. The value selects which
+   * trajectory-control action the URScript dispatcher takes, and dictates how \p point_number is
+   * interpreted:
+   * - TRAJECTORY_CANCEL (-1): Cancels the currently executing trajectory. \p point_number is unused.
+   * - TRAJECTORY_NOOP (0): No-op; serves as a keepalive on the reverse socket while a trajectory
+   *   executes. The producer must send these (or another trajectory-control message) periodically
+   *   while waiting for trajectory completion so that the URScript dispatcher's read does not
+   *   time out and exit the external_control program. \p point_number is unused.
+   * - TRAJECTORY_START (1): Begins a finite trajectory of declared length. \p point_number is the
+   *   total number of subsequent writeTrajectoryPoint / writeTrajectorySplinePoint / writeMotionPrimitive
+   *   calls the producer will issue on the trajectory socket. URScript reads exactly that many points
+   *   and then completes.
+   * - TRAJECTORY_STREAM_START (2): Begins an open-ended (streaming) trajectory. The producer streams
+   *   spline points and signals end-of-stream with TRAJECTORY_STREAM_END. \p point_number is unused.
+   * - TRAJECTORY_STREAM_END (3): Ends an open-ended streaming trajectory started by
+   *   TRAJECTORY_STREAM_START. \p point_number must equal the total number of spline points the
+   *   producer wrote on the trajectory socket since TRAJECTORY_STREAM_START.
    *
-   * \returns True, if the write was performed successfully, false otherwise.
+   * \param point_number Mode-dependent point-count argument. See the description of \p
+   * trajectory_action for the per-mode semantics.
+   *
+   * \param robot_receive_timeout The read timeout configuration for the reverse socket running in the
+   * external control script on the robot. If you want to make the read function blocking then use
+   * RobotReceiveTimeout::off() function to create the RobotReceiveTimeout object.
+   *
+   * \returns True if the write was performed successfully, false otherwise.
+   *
+   * \see examples/trajectory_point_interface.cpp for a finite-trajectory usage example, or
+   * examples/trajectory_streaming.cpp for an open-ended streaming trajectory example.
    */
   bool
   writeTrajectoryControlMessage(const TrajectoryControlMessage trajectory_action, const int point_number = 0,

include/ur_client_library/ur/ur_driver.h

@@ -585,13 +585,23 @@ class UrDriver
   /*!
    * \brief Writes a control message in trajectory forward mode.
    *
-   * \param trajectory_action The action to be taken, such as starting a new trajectory
-   * \param point_number The number of points of a new trajectory to be sent
-   * \param robot_receive_timeout The read timeout configuration for the reverse socket running in the external
-   * control script on the robot. If you want to make the read function blocking then use RobotReceiveTimeout::off()
-   * function to create the RobotReceiveTimeout object
+   * Selects which trajectory-control action the URScript dispatcher takes (start a finite
+   * trajectory, begin or end an open-ended streaming trajectory, cancel, or no-op keepalive)
+   * and, where applicable, communicates a point count. See
+   * control::ReverseInterface::writeTrajectoryControlMessage for the per-mode semantics of
+   * \p trajectory_action and \p point_number.
+   *
+   * \param trajectory_action The trajectory-control action to take.
+   * \param point_number Mode-dependent point-count argument; see the underlying interface.
+   * \param robot_receive_timeout The read timeout configuration for the reverse socket running in
+   * the external control script on the robot. If you want to make the read function blocking
+   * then use RobotReceiveTimeout::off() function to create the RobotReceiveTimeout object.
    *
    * \returns True on successful write.
+   *
+   * \see control::ReverseInterface::writeTrajectoryControlMessage
+   * \see examples/trajectory_point_interface.cpp (finite trajectory)
+   * \see examples/trajectory_streaming.cpp (open-ended streaming trajectory)
    */
   bool
   writeTrajectoryControlMessage(const control::TrajectoryControlMessage trajectory_action, const int point_number = 0,