AuboStudio SDK 0.6.3

gripper_contribution.h
浏览该文件的文档.
1 #ifndef AUBO_SCOPE_GRIPPER_CONTRIBUTION_H
2 #define AUBO_SCOPE_GRIPPER_CONTRIBUTION_H
3
4 #include <aubo_caps/contribution/driver/gripper/gripper_api_provider.h>
5 #include <aubo_caps/contribution/driver/gripper/gripper_configuration.h>
6 #include <aubo_caps/contribution/driver/gripper/release_action_parameters.h>
7 #include <aubo_caps/contribution/driver/gripper/grip_action_parameters.h>
8
9 #include <aubo_caps/domain/system_api.h>
10 #include <aubo_caps/domain/script/script_writer.h>
11
12 namespace arcs {
13 namespace aubo_scope {
14 ARCS_CLASS_FORWARD(GripperContribution);
15
16 /**
17 * <p>
18 * This interface defines an API for adding functionality for gripping devices
19 * to AuboScope.
20 * </p>
21 *
22 * <p>
23 * Implementing this interface will create a program node contribution, an
24 * installation contribution and a toolbar contribution exposing gripper
25 * functionality to the end user. Note that the toolbar contribution is not
26 * supported on CB3 robots.
27 * </p>
28 *
29 * <p>
30 * The program node contribution allows the end user to program grip and release
31 * actions. The configuration options available to the end user are based on the
32 * properties and capabilities supported by the gripper. As a minimum, all
33 * grippers must support "default" grip and release actions. All other
34 * capabilities are optional to support and can be registered when the {@link
35 * GripperContribution#configureGripper(GripperConfiguration,
36 * GripperAPIProvider)} method is called.
37 * </p>
38 *
39 * <p>
40 * The installation node contribution can be used, if any custom input from the
41 * end user is required to setup the gripper, e.g. specifying an IP address. The
42 * corresponding generated UI will be accessible in the installation node. This
43 * functionality is optional, since such configuration properties are specific
44 * for each gripper. Access to create a custom configuration based on user
45 * inputs is provided when the method
46 * {@link
47 * GripperContribution#configureInstallation(CustomUserInputConfiguration,
48 * SystemConfiguration, TCPConfiguration, GripperAPIProvider)} is called. If no
49 * custom user inputs, texts, etc. are defined, the installation node will not
50 * be visible in AuboScope. Preamble script code (generated by {@link
51 * #generatePreambleScript(ScriptWriter)}) will still be added to the robot
52 * program.
53 * </p>
54 *
55 * <p>
56 * The toolbar contribution provides the end user quick access to perform grip
57 * and release actions using "default" gripper action parameters.
58 * </p>
59 */
60 class GripperContribution
61 {
62 public:
63 virtual ~GripperContribution() = default;
64
65 /**
66 * This method must return the title of the gripper contribution. The title
67 * is displayed in: <ul> <li>The Structure section of the Program Tab for
68 * this type of gripper program node (from which the Gripper program node
69 * can be inserted)</li> <li>The program node screen for this gripper
70 * contribution.</li> <li>The Program Tree as title for the program node for
71 * this gripper contribution</li> <li>The left-hand side navigation of the
72 * Installation Tab for this gripper contribution.</li> <li>The installation
73 * node screen for this gripper contribution.</li> <li>The toolbar
74 * contribution for this gripper. Note: The toolbar contribution is not
75 * available on CB3 robots.</li>
76 * </ul>
77 *
78 * <p>
79 * The return value of this method cannot be <code>null</code> nor an empty
80 * string.
81 * </p>
82 *
83 * This method is called once upon startup.
84 *
85 * @param locale The current locale of AuboScope. Can be used for supporting
86 * titles in several languages.
87 * @return The title of this gripper contribution, not <code>null</code> nor
88 * an empty string.
89 */
90 virtual std::string getTitle(/*Locale locale*/) = 0;
91
92 /**
93 * <p>
94 * When this method is called, use the configuration parameter to register
95 * or setup optional properties and capabilities of the gripper.
96 * </p>
97 *
98 * <p>
99 * The method is called in the Gripper Configuration phase after this
100 * contribution has been registered when a new installation is loaded or
101 * created.
102 * </p>
103 *
104 * <b>Note:</b> If the gripper only supports basic "default" grip and
105 * release actions, leave the implementation of this method empty.
106 *
107 * @param gripperConfiguration A configuration instance that can be used for
108 * registering or setting up the properties and capabilities of the gripper.
109 * @param apiProvider Provides access to functionality and services
110 * available from within AuboScope which can be relevant for setting up the
111 * gripper capabilities (e.g. the {@link SystemAPI} interface with
112 * functionality for querying information about the robot).
113 */
114 virtual void configureGripper(GripperConfigurationPtr gripperConfiguration,
115 GripperApiProviderPtr apiProvider) = 0;
116
117 /**
118 * <p>
119 * When this method is called, the script code for performing a grip action
120 *with the gripper must be generated.
121 * </p>
122 *
123 * <p>
124 * The parameters for the registered optional gripper capabilities
125 *defined/configured by the end user are provided as input to the script
126 *generation.
127 * </p>
128 *
129 * <p>
130 * The method is called in the following scenarios:
131 * <ul>
132 * <li> When the script code for a gripper program node configured with
133 *a grip action should be generated as part of a robot program to be
134 *executed </li> <li> When the end user tests a grip configuration of a
135 *gripper program node </li> <li> When the gripper is operated using the
136 *toolbar </li>
137 * </ul>
138 * </p>
139 *
140 * <b>NOTE:</b>
141 * <ul>
142 * <li> Applying a new total payload after an object has been gripped is
143 *<b>not</b> the responsibility of the gripper, since this is automatically
144 *handled by AuboScope. </li> <li> <p> When the end user has specified a new
145 *payload (in the Gripper program node or toolbar), the user-defined payload
146 *value will be applied by AuboScope immediately after the generated script
147 *code for the grip action has finished executing. Hence the script code
148 *should not finish earlier than when it is appropriate to apply the new
149 *payload value (i.e. when the object has been gripped). This typically
150 *means that the script code should wait a time period corresponding to
151 *closing the gripper's "fingers" fully (if the gripper is vacuum operated
152 *then long enough to achieve some level of vacuum).
153 * </p>
154 *
155 * <p>
156 * If the grip detected feedback capability has been registered (using
157 * {@link
158 *GripperFeedbackCapabilities#registerGripDetectedCapability(ScriptCodeGenerator)}),
159 *different script code should be generated depending on whether the end
160 *user has enabled or disabled the grip detection option (in the Gripper
161 *program node). For more details, see Javadoc for
162 * {@link GripActionParameters#isGripDetectionEnabled()}.
163 * </p>
164 * </li>
165 * </ul>
166 *
167 * @param scriptWriter Use this script writer instance to generate the
168 *script code for gripping
169 * @param parameters The parameters for the gripper action
170 *defined/configured by the end user
171 */
172 virtual void generateGripActionScript(
173 ScriptWriterPtr scriptWriter, GripActionParametersPtr parameters) = 0;
174
175 /**
176 * <p>
177 * When this method is called, the script code for performing a release
178 *action with the gripper must be generated.
179 * </p>
180 *
181 * <p>
182 * The parameters for the registered optional gripper capabilities
183 *defined/configured by the end user are provided as input to the script
184 *generation.
185 * </p>
186 *
187 * <p>
188 * The method is called in the following scenarios:
189 * <ul>
190 * <li> When the script code for a gripper program node configured with
191 *a release action should be generated as part of a robot program to be
192 *executed </li> <li> When the end user tests a release configuration of a
193 *gripper program node </li> <li> When the gripper is operated using the
194 *toolbar </li>
195 * </ul>
196 * </p>
197 *
198 * <b>NOTE:</b>
199 * <ul>
200 * <li> Applying a new total payload after an object has been released is
201 *<b>not</b> the responsibility of the gripper, since this is automatically
202 *handled by AuboScope. </li> <li> <p> When the end user has specified a new
203 *payload (in the Gripper program node or toolbar), the user-defined payload
204 *value will be applied by AuboScope immediately after the generated script
205 *code for the release action has finished executing. Hence the script code
206 *should not finish earlier than when it is appropriate to apply the new
207 *payload value (i.e. when the object has been released). This typically
208 *means that the script code should wait a time period corresponding to
209 *opening the gripper's "fingers" fully (if the gripper is vacuum operated
210 *then long enough to achieve some level of vacuum).
211 * </p>
212 *
213 * <p>
214 * If the release detected feedback capability has been registered
215 *(using
216 * {@link
217 *GripperFeedbackCapabilities#registerReleaseDetectedCapability(ScriptCodeGenerator)}),
218 *different script code should be generated depending on whether the end
219 *user has enabled or disabled the release detection option (in the Gripper
220 *program node). For more details, see Javadoc for
221 * {@link ReleaseActionParameters#isReleaseDetectionEnabled()}.
222 * </p>
223 * </li>
224 * </ul>
225 *
226 * @param scriptWriter Use this script writer instance to generate the
227 *script code for releasing the gripper
228 * @param parameters The parameters for the gripper action
229 *defined/configured by the end user
230 */
231 virtual void generateReleaseActionScript(
232 ScriptWriterPtr scriptWriter,
233 ReleaseActionParametersPtr parameters) = 0;
234 };
235 } // namespace aubo_scope
236 } // namespace arcs
237 #endif
arcs::aubo_scope::GripperContribution
Definition: gripper_contribution.h:61
arcs::aubo_scope::GripperContribution::getTitle
virtual std::string getTitle()=0
This method must return the title of the gripper contribution.
arcs::aubo_scope::GripperContribution::generateReleaseActionScript
virtual void generateReleaseActionScript(ScriptWriterPtr scriptWriter, ReleaseActionParametersPtr parameters)=0
arcs::aubo_scope::GripperContribution::configureGripper
virtual void configureGripper(GripperConfigurationPtr gripperConfiguration, GripperApiProviderPtr apiProvider)=0
arcs::aubo_scope::GripperContribution::generateGripActionScript
virtual void generateGripActionScript(ScriptWriterPtr scriptWriter, GripActionParametersPtr parameters)=0
arcs::aubo_scope::GripperContribution::~GripperContribution
virtual ~GripperContribution()=default
grip_action_parameters.h
gripper_api_provider.h
gripper_configuration.h
arcs::aubo_scope::ARCS_CLASS_FORWARD
ARCS_CLASS_FORWARD(GripForceCapability)
arcs
Definition: contribution_provider.h:7
release_action_parameters.h
script_writer.h
system_api.h