diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_pause.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_pause.h index 5c4f13c..2b3d6dc 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_pause.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_pause.h @@ -34,23 +34,49 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the robot's response to a requested stop in RTDE data package + * communication. + */ class ControlPackagePause : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackagePause object. + */ ControlPackagePause() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_PAUSE) { } virtual ~ControlPackagePause() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t accepted_; }; +/*! + * \brief This class is used to request a stop in RTDE data package communication. + */ class ControlPackagePauseRequest : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackagePauseRequest object. + */ ControlPackagePauseRequest() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_PAUSE) { } diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_inputs.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_inputs.h index ddd4672..7b7b975 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_inputs.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_inputs.h @@ -34,29 +34,62 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the robot's response to a requested input recipe setup. + */ class ControlPackageSetupInputs : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageSetupInputs object. + */ ControlPackageSetupInputs() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_SETUP_INPUTS) { } virtual ~ControlPackageSetupInputs() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t input_recipe_id_; std::string variable_types_; }; +/*! + * \brief This class is used to setup the input recipe as part of the initial RTDE handshake. + */ class ControlPackageSetupInputsRequest : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageSetupInputsRequest object. + */ ControlPackageSetupInputsRequest() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_SETUP_INPUTS) { } virtual ~ControlPackageSetupInputsRequest() = default; + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * \param variable_names The input recipe to set + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer, std::vector variable_names); std::string variable_names_; diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_outputs.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_outputs.h index 3d2fd61..8a85b1b 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_outputs.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_setup_outputs.h @@ -35,32 +35,74 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the robot's response to a requested output recipe setup. + */ class ControlPackageSetupOutputs : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageSetupOutputs object. + */ ControlPackageSetupOutputs() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_SETUP_OUTPUTS) { } virtual ~ControlPackageSetupOutputs() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t output_recipe_id_; std::string variable_types_; }; +/*! + * \brief This class is used to setup the output recipe as part of the initial RTDE handshake. + */ class ControlPackageSetupOutputsRequest : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageSetupOutputsRequest object. + */ ControlPackageSetupOutputsRequest() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_SETUP_OUTPUTS) { } virtual ~ControlPackageSetupOutputsRequest() = default; + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * \param output_frequency Frequency of data packages to be sent by the robot + * \param variable_names The output recipe to set + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer, double output_frequency, std::vector variable_names); + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * \param variable_names The output recipe to set + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer, std::vector variable_names); double output_frequency_; diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_start.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_start.h index 8db2c74..12c45e9 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_start.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/control_package_start.h @@ -34,28 +34,61 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the robot's response to a requested start in RTDE data package + * communication. + */ class ControlPackageStart : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageStart object. + */ ControlPackageStart() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_START) { } virtual ~ControlPackageStart() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t accepted_; }; +/*! + * \brief This class is used to request a stop in RTDE data package communication. + */ class ControlPackageStartRequest : public RTDEPackage { public: + /*! + * \brief Creates a new ControlPackageStartRequest object. + */ ControlPackageStartRequest() : RTDEPackage(PackageType::RTDE_CONTROL_PACKAGE_START) { } virtual ~ControlPackageStartRequest() = default; + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer); private: diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/data_package.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/data_package.h index 47a2adc..84060d7 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/data_package.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/data_package.h @@ -83,6 +83,10 @@ struct SerializeVisitor : public boost::static_visitor } }; +/*! + * \brief The DataPackage class handles communication in the form of RTDE data packages both to and + * from the robot. It contains functionality to parse and serialize packages for arbitrary recipes. + */ class DataPackage : public RTDEPackage { public: @@ -90,16 +94,44 @@ public: vector6int32_t, vector6uint32_t, std::string>; DataPackage() = delete; + /*! + * \brief Creates a new DataPackage object, based on a given recipe. + * + * \param recipe The used recipe + */ DataPackage(const std::vector& recipe) : RTDEPackage(PackageType::RTDE_DATA_PACKAGE), recipe_(recipe) { } virtual ~DataPackage() = default; + /*! + * \brief Initializes to contained list with empty values based on the recipe. + */ void initEmpty(); + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; + /*! + * \brief Serializes the package. + * + * \param buffer Buffer to fill with the serialization + * + * \returns The total size of the serialized package + */ size_t serializePackage(uint8_t* buffer); /*! @@ -177,6 +209,11 @@ public: return true; } + /*! + * \brief Setter of the recipe id value used to identify the used recipe to the robot. + * + * \param recipe_id The new value + */ void setRecipeID(const uint8_t& recipe_id) { recipe_id_ = recipe_id; diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/get_urcontrol_version.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/get_urcontrol_version.h index 3b5f564..4791f6b 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/get_urcontrol_version.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/get_urcontrol_version.h @@ -35,15 +35,34 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the package detailing the UR control version sent by the robot. + */ class GetUrcontrolVersion : public RTDEPackage { public: + /*! + * \brief Creates a new GetUrcontrolVersion object. + */ GetUrcontrolVersion() : RTDEPackage(PackageType::RTDE_GET_URCONTROL_VERSION) { } virtual ~GetUrcontrolVersion() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; VersionInformation version_information_; @@ -54,14 +73,27 @@ public: uint32_t build_; }; +/*! + * \brief This class is used to request the used UR control version from the robot. + */ class GetUrcontrolVersionRequest : public RTDEPackage { public: + /*! + * \brief Creates a new GetUrcontrolVersionRequest object. + */ GetUrcontrolVersionRequest() : RTDEPackage(PackageType::RTDE_GET_URCONTROL_VERSION) { } virtual ~GetUrcontrolVersionRequest() = default; + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer); private: diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/package_header.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/package_header.h index e365381..b9f89df 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/package_header.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/package_header.h @@ -50,6 +50,9 @@ enum class PackageType : uint8_t RTDE_CONTROL_PACKAGE_PAUSE = 80 // ascii P }; +/*! + * \brief This class represents the header for RTDE packages. + */ class PackageHeader { public: @@ -57,11 +60,27 @@ public: virtual ~PackageHeader() = default; using _package_size_type = uint16_t; + /*! + * \brief Reads a buffer, interpreting the next bytes as the size of the contained package. + * + * \param buf The given byte stream containing a serialized package + * + * \returns The size of the given serialized package + */ static size_t getPackageLength(uint8_t* buf) { return be16toh(*(reinterpret_cast<_package_size_type*>(buf))); } + /*! + * \brief Creates a serialization of a header based on given values. + * + * \param buffer The buffer to write the serialization to + * \param package_type The type of the package + * \param payload_length The length of the package's payload + * + * \returns + */ static size_t serializeHeader(uint8_t* buffer, PackageType package_type, uint16_t payload_length) { uint16_t header_size = sizeof(_package_size_type) + sizeof(PackageType); diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/request_protocol_version.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/request_protocol_version.h index 3082d3c..515f2a1 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/request_protocol_version.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/request_protocol_version.h @@ -35,29 +35,63 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles the robot's response after trying to set the used RTDE protocol version. + */ class RequestProtocolVersion : public RTDEPackage { public: + /*! + * \brief Creates a new RequestProtocolVersion object. + */ RequestProtocolVersion() : RTDEPackage(PackageType::RTDE_REQUEST_PROTOCOL_VERSION) { } virtual ~RequestProtocolVersion() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t accepted_; }; +/*! + * \brief This class handles producing a request towards the robot to use a specific RTDE protocol + * version. + */ class RequestProtocolVersionRequest : public RTDEPackage { public: + /*! + * \brief Creates a new RequestProtocolVersionRequest object. + */ RequestProtocolVersionRequest() : RTDEPackage(PackageType::RTDE_REQUEST_PROTOCOL_VERSION) { } virtual ~RequestProtocolVersionRequest() = default; + /*! + * \brief Generates a serialized package. + * + * \param buffer Buffer to fill with the serialization + * \param version RTDE protocol version to request usage of + * + * \returns The total size of the serialized package + */ static size_t generateSerializedRequest(uint8_t* buffer, uint16_t version); uint16_t protocol_version_; diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_client.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_client.h index 3264870..6b417fa 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_client.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_client.h @@ -48,22 +48,64 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief The RTDEClient class manages communication over the RTDE interface. It contains the RTDE + * handshake and read and write functionality to and from the robot. + */ class RTDEClient { public: RTDEClient() = delete; + /*! + * \brief Creates a new RTDEClient object, including a used URStream and Pipeline to handle the + * communication with the robot. + * + * \param robot_ip The IP of the robot + * \param notifier The notifier to use in the pipeline + * \param output_recipe_file Path to the file containing the output recipe + * \param input_recipe_file Path to the file containing the input recipe + */ RTDEClient(std::string robot_ip, comm::INotifier& notifier, const std::string& output_recipe_file, const std::string& input_recipe_file); ~RTDEClient() = default; + /*! + * \brief Sets up RTDE communication with the robot. The handshake includes negotiation of the + * used protocol version and setting of input and output recipes. + * + * \returns Success of the handshake + */ bool init(); + /*! + * \brief Triggers the robot to start sending RTDE data packages in the negotiated format. + * + * \returns Success of the requested start + */ bool start(); + /*! + * \brief Reads the pipeline to fetch the next data package. + * + * \param data_package Pointer to set to the next data package + * \param timeout Time to wait if no data package is currently in the queue + * + * \returns True, if a package was fetched successfully + */ bool getDataPackage(std::unique_ptr>& data_package, std::chrono::milliseconds timeout); + /*! + * \brief Getter for the frequency the robot will publish RTDE data packages with. + * + * \returns The used frequency + */ double getMaxFrequency() const { return max_frequency_; } + /*! + * \brief Getter for the UR control version received from the robot. + * + * \returns The VersionInformation received from the robot + */ VersionInformation getVersion() { return urcontrol_version_; @@ -76,6 +118,12 @@ public: */ std::string getIP() const; + /*! + * \brief Getter for the RTDE writer, which is used to send data via the RTDE interface to the + * robot. + * + * \returns A reference to the used RTDEWriter + */ RTDEWriter& getWriter(); private: diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_package.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_package.h index a921e96..f0533d5 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_package.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_package.h @@ -51,7 +51,20 @@ public: } virtual ~RTDEPackage() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; protected: diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_parser.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_parser.h index d7bf220..8b91a12 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_parser.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_parser.h @@ -38,15 +38,33 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief The RTDE specific parser. Interprets a given byte stream as serialized RTDE packages + * and parses it accordingly. + */ class RTDEParser : public comm::Parser { public: RTDEParser() = delete; + /*! + * \brief Creates a new RTDEParser object, registering the used recipe. + * + * \param recipe The recipe used in RTDE data communication + */ RTDEParser(const std::vector& recipe) : recipe_(recipe) { } virtual ~RTDEParser() = default; + /*! + * \brief Uses the given BinParser to create package objects from the contained serialization. + * + * \param bp A BinParser holding one or more serialized RTDE packages + * \param results A vector of pointers to created RTDE package objects + * + * \returns True, if the byte stream could successfully be parsed as RTDE packages, false + * otherwise + */ bool parse(comm::BinParser& bp, std::vector>>& results) { diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_writer.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_writer.h index 02506e8..add96e3 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_writer.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/rtde_writer.h @@ -39,19 +39,78 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief The RTDEWriter class offers an abstraction layer to send data to the robot via the RTDE + * interface. Several simple to use functions to create data packages to send exist, which are + * then sent to the robot in an additional thread. + */ class RTDEWriter { public: RTDEWriter() = delete; + /*! + * \brief Creates a new RTDEWriter object using a given URStream and recipe. + * + * \param stream The URStream to use for communication with the robot + * \param recipe The recipe to use for communication + */ RTDEWriter(comm::URStream* stream, const std::vector& recipe); ~RTDEWriter() = default; + /*! + * \brief Starts the writer thread, which periodically clears the queue to write packages to the + * robot. + * + * \param recipe_id The recipe id to use, so the robot correctly identifies the used recipe + */ void init(uint8_t recipe_id); + /*! + * \brief The writer thread loop, continually serializing and sending packages to the robot. + */ void run(); + /*! + * \brief Creates a package to request setting a new value for the speed slider. + * + * \param speed_slider_fraction The new speed slider fraction as a value between 0.0 and 1.0 + * + * \returns Success of the package creation + */ bool sendSpeedSlider(double speed_slider_fraction); + /*! + * \brief Creates a package to request setting a new value for one of the standard digital output pins. + * + * \param output_pin The pin to change + * \param value The new value + * + * \returns Success of the package creation + */ bool sendStandardDigitalOutput(uint8_t output_pin, bool value); + /*! + * \brief Creates a package to request setting a new value for one of the configurable digital output pins. + * + * \param output_pin The pin to change + * \param value The new value + * + * \returns Success of the package creation + */ bool sendConfigurableDigitalOutput(uint8_t output_pin, bool value); + /*! + * \brief Creates a package to request setting a new value for one of the tool output pins. + * + * \param output_pin The pin to change + * \param value The new value + * + * \returns Success of the package creation + */ bool sendToolDigitalOutput(uint8_t output_pin, bool value); + /*! + * \brief Creates a package to request setting a new value for one of the standard analog output pins. + * + * \param output_pin The pin to change + * \param value The new value + * + * \returns Success of the package creation + */ bool sendStandardAnalogOuput(uint8_t output_pin, double value); private: diff --git a/ur_rtde_driver/include/ur_rtde_driver/rtde/text_message.h b/ur_rtde_driver/include/ur_rtde_driver/rtde/text_message.h index 9daf783..4a8cd27 100644 --- a/ur_rtde_driver/include/ur_rtde_driver/rtde/text_message.h +++ b/ur_rtde_driver/include/ur_rtde_driver/rtde/text_message.h @@ -34,15 +34,34 @@ namespace ur_driver { namespace rtde_interface { +/*! + * \brief This class handles RTDE text messages sent by the robot. + */ class TextMessage : public RTDEPackage { public: + /*! + * \brief Creates a new TextMessage object. + */ TextMessage() : RTDEPackage(PackageType::RTDE_TEXT_MESSAGE) { } virtual ~TextMessage() = default; + /*! + * \brief Sets the attributes of the package by parsing a serialized representation of the + * package. + * + * \param bp A parser containing a serialized version of the package + * + * \returns True, if the package was parsed successfully, false otherwise + */ virtual bool parseWith(comm::BinParser& bp); + /*! + * \brief Produces a human readable representation of the package object. + * + * \returns A string representing the object + */ virtual std::string toString() const; uint8_t message_length_;