Skip to content

Commit 05620e1

Browse files
urfeexurfeex
committed
Add API documentation for ExampleRobotWrapper
1 parent 14f7d50 commit 05620e1

File tree

2 files changed

+156
-4
lines changed

2 files changed

+156
-4
lines changed

‎include/ur_client_library/example_robot_wrapper.h‎

Lines changed: 126 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,33 @@
1+
// -- BEGIN LICENSE BLOCK ----------------------------------------------
2+
// Copyright 2025 Universal Robots A/S
3+
//
4+
// Redistribution and use in source and binary forms, with or without
5+
// modification, are permitted provided that the following conditions are met:
6+
//
7+
// * Redistributions of source code must retain the above copyright
8+
// notice, this list of conditions and the following disclaimer.
9+
//
10+
// * Redistributions in binary form must reproduce the above copyright
11+
// notice, this list of conditions and the following disclaimer in the
12+
// documentation and/or other materials provided with the distribution.
13+
//
14+
// * Neither the name of the {copyright_holder} nor the names of its
15+
// contributors may be used to endorse or promote products derived from
16+
// this software without specific prior written permission.
17+
//
18+
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19+
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20+
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21+
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22+
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23+
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24+
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25+
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26+
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27+
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28+
// POSSIBILITY OF SUCH DAMAGE.
29+
// -- END LICENSE BLOCK ------------------------------------------------
30+
131
#ifndef UR_CLIENT_LIBRARY_EXAMPLE_ROBOT_WRAPPER_H_INCLUDED
232
#define UR_CLIENT_LIBRARY_EXAMPLE_ROBOT_WRAPPER_H_INCLUDED
333

@@ -7,36 +37,128 @@
737

838
namespace urcl
939
{
40+
/*!
41+
* \class ExampleRobotWrapper
42+
* \brief This class is a high-level abstraction around UrDriver and DashboardClient. It's main
43+
* purpose is to help us avoiding repetitive robot initialization code in our examples and tests.
44+
*
45+
* It is therefore not intended to be used in production code, but rather as a helper class for
46+
* developers. If you want to use this wrapper in your own code, please make sure to understand the
47+
* logic behind it and adjust it to your needs.
48+
*
49+
* Since this is mainly intended for internal use, don't count on the API being stable for this
50+
* class!
51+
*/
1052
class ExampleRobotWrapper
1153
{
1254
public:
1355
inline static const std::string DEFAULT_ROBOT_IP = "192.168.56.101";
1456
inline static const std::string SCRIPT_FILE = "resources/external_control.urscript";
1557

1658
ExampleRobotWrapper() = delete;
59+
/*!
60+
* \brief Construct a new Example Robot Wrapper object
61+
*
62+
* This will connect to a robot and initialize it. In headless mode the program will be running
63+
* instantly, in teach pendant mode the from \p autostart_program will be started.
64+
*
65+
* Note: RTDE communication has to be started separately.
66+
*
67+
* \param robot_ip IP address of the robot to connect to
68+
* \param output_recipe_file Output recipe file for RTDE communication
69+
* \param input_recipe_file Input recipe file for RTDE communication
70+
* \param headless_mode Should the driver be started in headless mode or not?
71+
* \param autostart_program Program to start automatically after initialization when not in
72+
* headless mode. This flag is ignored in headless mode.
73+
* \param script_file URScript file to send to the robot. That should be script code
74+
* communicating to the driver's reverse interface and trajectory interface.
75+
*/
1776
ExampleRobotWrapper(const std::string& robot_ip, const std::string& output_recipe_file,
1877
const std::string& input_recipe_file, const bool headless_mode = true,
1978
const std::string& autostart_program = "", const std::string& script_file = SCRIPT_FILE);
2079
~ExampleRobotWrapper();
2180

81+
/**
82+
* @brief Initializes the robot in order to be able to start a program.
83+
*
84+
* The robot will be power-cycled once and end up switched on, breaks released.
85+
*/
2286
void initializeRobotWithDashboard();
2387

88+
/**
89+
* @brief Starts RTDE communication with the robot.
90+
*
91+
* @param consume_data Once the RTDE client is started, it's data has to be consumed. If you
92+
* don't actually care about that data, this class can silently consume RTDE data when `true` is
93+
* passed. This can be stopped and started at any time using the startConsumingRTDEData() and
94+
* stopConsumingRTDEData() methods.
95+
*/
2496
void startRTDECommununication(const bool consume_data = false);
97+
98+
/**
99+
* @brief Start consuming RTDE data in the background.
100+
*/
25101
void startConsumingRTDEData();
102+
103+
/**
104+
* @brief Stop consuming RTDE data in the background. Note that data has to be consumed manually
105+
* using readDataPackage().
106+
*/
26107
void stopConsumingRTDEData();
108+
109+
/**
110+
* @brief Get the latest RTDE package.
111+
*
112+
* Do not call this, while RTDE data is being consumed in the background. In doubt, call
113+
* stopConsumingRTDEData() before calling this function.
114+
*
115+
* @param[out] data_pkg The data package will be stored in that object
116+
* @return true on a successful read, false if no package can be read or when RTDE data is
117+
* already being consumed in the background.
118+
*/
27119
bool readDataPackage(std::unique_ptr<rtde_interface::DataPackage>& data_pkg);
28120

121+
/**
122+
* @brief Blocks until there is a robot program connected to the driver's reverse interface or
123+
* until the timeout is hit.
124+
*
125+
* @param milliseconds How long to wait for a successful connection.
126+
* @return True on a successful connection, false if not connection could be detected before the
127+
* timeout.
128+
*/
29129
bool waitForProgramRunning(int milliseconds = 100);
130+
131+
/**
132+
* @brief Blocks until there is a disconnection event from the driver's reverse interface
133+
* detected or until the timeout is hit.
134+
*
135+
* @param milliseconds How long to wait for a disconnection.
136+
* @return True on a disconnection event has been detected, false if no event could be detected before the
137+
* timeout.
138+
*/
30139
bool waitForProgramNotRunning(int milliseconds = 100);
31140

32-
// Depending on whether it is headless or not start autostart_program or call driver's
33-
// resendRobotProgram function.
141+
/**
142+
* @brief Depending on whether it is headless or not start autostart_program or call driver's resendRobotProgram
143+
* function.
144+
*
145+
* @return True on successful program start, false otherwise.
146+
*/
34147
bool resendRobotProgram();
35148

149+
/**
150+
* @brief Start the program \p program_file_name on the robot.
151+
*
152+
* The program has be be present on the robot, otherwise this call does not succeed. The robot
153+
* needs to be in remote_control mode for this to work properly.
154+
*
155+
* @param program_file_name Filename on the robot including the ".urp" extension.
156+
* @return True on successful program start, false otherwise.
157+
*/
36158
bool startRobotProgram(const std::string& program_file_name);
37159

38-
std::shared_ptr<urcl::DashboardClient> dashboard_client_;
39-
std::shared_ptr<urcl::UrDriver> ur_driver_;
160+
std::shared_ptr<urcl::DashboardClient> dashboard_client_; /*!< Dashboard client to interact with the robot */
161+
std::shared_ptr<urcl::UrDriver> ur_driver_; /*!< UR driver to interact with the robot */
40162

41163
private:
42164
void handleRobotProgramState(bool program_running);

‎src/example_robot_wrapper.cpp‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,33 @@
1+
// -- BEGIN LICENSE BLOCK ----------------------------------------------
2+
// Copyright 2025 Universal Robots A/S
3+
//
4+
// Redistribution and use in source and binary forms, with or without
5+
// modification, are permitted provided that the following conditions are met:
6+
//
7+
// * Redistributions of source code must retain the above copyright
8+
// notice, this list of conditions and the following disclaimer.
9+
//
10+
// * Redistributions in binary form must reproduce the above copyright
11+
// notice, this list of conditions and the following disclaimer in the
12+
// documentation and/or other materials provided with the distribution.
13+
//
14+
// * Neither the name of the {copyright_holder} nor the names of its
15+
// contributors may be used to endorse or promote products derived from
16+
// this software without specific prior written permission.
17+
//
18+
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19+
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20+
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21+
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22+
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23+
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24+
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25+
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26+
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27+
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28+
// POSSIBILITY OF SUCH DAMAGE.
29+
// -- END LICENSE BLOCK ------------------------------------------------
30+
131
#include <ur_client_library/example_robot_wrapper.h>
232
#include <iostream>
333

0 commit comments

Comments
 (0)