AuboStudio SDK 0.6.3

payload_contribution_model.h
浏览该文件的文档.
1 #ifndef AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H
2 #define AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H
3
4 #include <aubo_caps/class_forward.h>
5 #include <aubo_caps/domain/payload/payload.h>
6
7 namespace arcs {
8 namespace aubo_scope {
9 ARCS_CLASS_FORWARD(PayloadContributionModel);
10
11 /**
12 * @defgroup PayloadContributionModel PayloadContributionModel (动态负载管理)
13 * \~chinese 动态负载管理
14 * \~english API interface for dynamic payload management
15 */
16
17 class ARCS_ABI_EXPORT PayloadContributionModel
18 {
19 public:
20 PayloadContributionModel(PayloadContributionModel &f);
21 PayloadContributionModel(PayloadContributionModel &&f);
22 ~PayloadContributionModel();
23
24 /**
25 * @ingroup PayloadContributionModel
26 * <p>
27 * Add a payload to the current installation in AuboScope.
28 * </p>
29 *
30 * <p>
31 * This makes the payload selectable by the end user as well as available to
32 * other AuboCap contributions (through the
33 * {@link PayloadModel} interface). The payload is not modifiable by the end
34 * user or other aubo_studio plugins.
35 * </p>
36 *
37 * <p>
38 * A default guess for the inertia matrix for the payload will be computed
39 * based on the specified payload mass and center of gravity. If data for
40 * the payload's inertia matrix is available, the method
41 * {@link #addPayload(String, String, Mass, Position, InertiaMatrix)} can
42 * used instead (this might give better performance of the robot arm).
43 * </p>
44 *
45 * <p>
46 * <b>Note:</b> The specified payload mass must be the total mass of the
47 * payload attached to the tool output flange of the robot.
48 * </p>
49 *
50 * The valid range for the payload mass and the coordinates of the center of
51 * gravity (CoG) are available through the
52 * {@link RobotLimits} interface which can be accessed with {@link
53 * RobotModel#getRobotLimits()} (an instance of the
54 * {@link RobotModel} interface can be retrieved through {@link
55 * SystemAPI#getRobotModel()}).
56 *
57 * @param idKey The key to identify this payload by, not <code>null</code>
58 * nor an empty string. The key is for this AuboCap only, i.e. it only has
59 * to be unique for this AuboCap and not "globally" for other aubo_studio
60 * plugins.
61 * @param suggestedName Suggested name for the payload, not
62 * <code>null</code> nor an empty string. Valid names must match regex
63 * [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name
64 * can be retrieved from the returned payload instance.
65 * @param mass The total mass of the payload attached to the tool output
66 * flange of the robot, not <code>null</code>. Create it using {@link
67 * SimpleValueFactory#createMass(double, Mass.Unit)}.
68 * @param centerOfGravity The center of gravity (CoG), also referred to as
69 * center of mass, for the payload. It is defined as the offset between the
70 * center of the tool output flange and the center of gravity of the
71 * attached payload. Cannot be <code>null</code>. Create it using the {@link
72 * PositionFactory} interface.
73 * @return The payload created and registered in AuboScope.
74 * @throws PayloadAlreadyAddedException If a payload has previously been
75 * added using the same <code>idKey</code> identifier. Use {@link
76 * #getPayload(String)} to check if the payload has already been added to
77 * the current installation. Use {@link #updatePayload(String, Mass,
78 * Position)} or
79 * {@link #updatePayload(String, Mass,
80 * Position, InertiaMatrix)} to update the payload if the payload parameters
81 * have changed.
82 * @throws IllegalPayloadNameException If the suggested name does not match
83 * required regex.
84 * @throws IllegalMassException If the specified mass is not inside the
85 * valid range as defined by AuboScope.
86 * @throws IllegalCenterOfGravityException If any of the values of the
87 * specified center of gravity are not inside the valid range as defined by
88 * AuboScope.
89 */
90 PayloadPtr addPayload(const std::string &id_key,
91 const std::string &suggested_name, double mass,
92 const std::vector<double> &center_of_gravity);
93
94 /**
95 * @ingroup PayloadContributionModel
96 * <p>
97 * Add a payload to the current installation in AuboScope.
98 * </p>
99 *
100 * <p>
101 * This makes the payload selectable by the end user as well as available to
102 * other AuboCap contributions (through the
103 * {@link PayloadModel} interface). The payload is not modifiable by the end
104 * user or other aubo_studio plugins.
105 * </p>
106 *
107 * Use the {@link #addPayload(String, String, Mass, Position,
108 * InertiaMatrix)} method instead if data for the payload's inertia matrix
109 * is not available.
110 *
111 * <p>
112 * <b>Note:</b> The specified payload mass must be the total mass of the
113 * payload attached to the tool output flange of the robot.
114 * </p>
115 *
116 * The valid range for the payload mass and the coordinates of the center of
117 * gravity (CoG) are available through the
118 * {@link RobotLimits} interface which can be accessed with {@link
119 * RobotModel#getRobotLimits()} (an instance of the
120 * {@link RobotModel} interface can be retrieved through {@link
121 * SystemAPI#getRobotModel()}).
122 *
123 * @param idKey The key to identify this payload by, not <code>null</code>
124 * nor an empty string. The key is for this AuboCap only, i.e. it only has
125 * to be unique for this AuboCap and not "globally" for other aubo_studio
126 * plugins.
127 * @param suggestedName Suggested name for the payload, not
128 * <code>null</code> nor an empty string. Valid names must match regex
129 * [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name
130 * can be retrieved from the returned payload instance.
131 * @param mass The total mass of the payload attached to the tool output
132 * flange of the robot, not <code>null</code>. Create it using {@link
133 * SimpleValueFactory#createMass(double, Mass.Unit)}.
134 * @param centerOfGravity The center of gravity (CoG), also referred to as
135 * center of mass, for the payload. It is defined as the offset between the
136 * center of the tool output flange and the center of gravity of the
137 * attached payload. Cannot be <code>null</code>. Create it using the {@link
138 * PositionFactory} interface.
139 * @param inertiaMatrix The inertia matrix of the payload, defined in a
140 * coordinate system with center at the payload's center of gravity and the
141 * axes aligned with the tool output flange coordinate system (axes). Cannot
142 * be <code>null</code>. Create it using
143 * {@link #createInertiaMatrix(double, double, double,
144 * double, double, double, MomentOfInertia.Unit)}.
145 * @return The payload created and registered in AuboScope.
146 * @throws PayloadAlreadyAddedException If a payload has previously been
147 * added using the same <code>idKey</code> identifier. Use {@link
148 * #getPayload(String)} to check if the payload has already been added to
149 * the current installation.
150 * Use {@link #updatePayload(String, Mass,
151 * Position)} or
152 * {@link #updatePayload(String, Mass,
153 * Position, InertiaMatrix)} to update the payload if the payload parameters
154 * have changed.
155 * @throws IllegalPayloadNameException If the suggested name does not match
156 * required regex.
157 * @throws IllegalMassException If the specified mass is not inside the
158 * valid range as defined by AuboScope.
159 * @throws IllegalCenterOfGravityException If any of the values of the
160 * specified center of gravity are not inside the valid range as defined by
161 * AuboScope.
162 * @throws IllegalInertiaMatrixException If any of the values of the
163 * specified inertia matrix are not inside the valid range as defined by
164 * AuboScope.
165 */
166 PayloadPtr addPayload(const std::string &id_key,
167 const std::string &suggested_name, double mass,
168 const std::vector<double> &center_of_gravity,
169 const std::vector<double> &inertiaMatrix);
170
171 /**
172 * @ingroup PayloadContributionModel
173 * Returns the payload previously added by this AuboCap using the same
174 * <code>idKey</code> identifier. Use this to verify if the payload is
175 * present in the current installation.
176 *
177 * @param idKey The key to identify this payload by, not <code>null</code>
178 * nor an empty string.
179 * @return The payload previously added by this AuboCap.
180 * Returns <code>null</code> if no payload exists in current
181 * installation (with the specified <code>idKey</code> identifier).
182 */
183 PayloadPtr getPayload(const std::string &id_key);
184
185 /**
186 * @ingroup PayloadContributionModel
187 * <p>
188 * Update the mass and center of gravity (CoG) of an existing payload added
189 *by this AuboCap.
190 * </p>
191 *
192 * <b>Note:</b> If an inertia matrix has been specified for the payload,
193 *calling this method will replace (overwrite) it with a computed default
194 *guess based the new specified payload mass and center of gravity. To avoid
195 *overwriting an existing inertia matrix (or to update an existing inertia
196 *matrix), instead use the method
197 *{@link #updatePayload(String, Mass, Position, InertiaMatrix)}.
198 *
199 * @param idKey The key to identify the payload, not <code>null</code> nor
200 *an empty string. A payload must have been added using the same key prior
201 *to calling this method.
202 * @param mass The total mass of the payload attached to the tool output
203 *flange of the robot, not <code>null</code>. Create it using {@link
204 *SimpleValueFactory#createMass(double, Mass.Unit)}.
205 * @param centerOfGravity The center of gravity of the payload, not {@code
206 *null}. Create it using the
207 * {@link PositionFactory} interface.
208 * @throws PayloadNotFoundException If no payload exists with the provided
209 *<code>idKey</code> identifier in the current installation.
210 * @throws IllegalMassException If the specified mass is not inside the
211 *valid range as defined by AuboScope.
212 * @throws IllegalCenterOfGravityException If any of the values of the
213 *specified center of gravity are not inside the valid range as defined by
214 *AuboScope.
215 */
216
217 void updatePayload(const std::string &id_key, double mass,
218 const std::vector<double> &center_of_gravity);
219
220 /**
221 * @ingroup PayloadContributionModel
222 * Update the mass, center of gravity (CoG) and inertia matrix of an
223 * existing payload added by this AuboCap.
224 *
225 * @param idKey The key to identify the payload, not <code>null</code> nor
226 * an empty string. A payload must have been added using the same key prior
227 * to calling this method.
228 * @param mass The total mass of the payload attached to the tool output
229 * flange of the robot, not <code>null</code>. Create it using {@link
230 * SimpleValueFactory#createMass(double, Mass.Unit)}.
231 * @param centerOfGravity The center of gravity of the payload, not {@code
232 * null}. Create it using the
233 * {@link PositionFactory} interface.
234 * @param inertiaMatrix The inertia matrix of the payload, not
235 * <code>null</code>. Create it using
236 * {@link #createInertiaMatrix(double, double, double,
237 * double, double, double, MomentOfInertia.Unit)}
238 * @throws PayloadNotFoundException If no payload exists with the provided
239 * <code>idKey</code> identifier in the current installation.
240 * @throws IllegalMassException If the specified mass is not inside the
241 * valid range as defined by AuboScope.
242 * @throws IllegalCenterOfGravityException If any of the values of the
243 * specified center of gravity are not inside the valid range as defined by
244 * AuboScope.
245 * @throws IllegalInertiaMatrixException If any of the values of the
246 * specified inertia matrix are not inside the valid range as defined by
247 * AuboScope.
248 */
249 void updatePayload(const std::string id_key, double mass,
250 const std::vector<double> &center_of_gravity,
251 const std::vector<double> &inertia_matrix);
252
253 /**
254 * @ingroup PayloadContributionModel
255 * Remove a payload added by this AuboCap from AuboScope. Program nodes
256 * using the payload will be become undefined because the payload is no
257 * longer resolvable.
258 *
259 * @param idKey The identifier key used to add the payload with, not {@code
260 * null} nor an empty string.
261 * @throws PayloadNotFoundException If no payload exists with the provided
262 * <code>idKey</code> identifier in the current installation.
263 */
264 void removePayload(const std::string &id_key);
265
266 private:
267 friend class DataSwitch;
268 PayloadContributionModel();
269 void *d_{ nullptr };
270 };
271 } // namespace aubo_scope
272 } // namespace arcs
273
274 #endif // AUBO_SCOPE_PAYLOAD_CONTRIBUTION_MODEL_H
class_forward.h
ARCS_ABI_EXPORT
#define ARCS_ABI_EXPORT
Definition: class_forward.h:16
arcs::aubo_scope::PayloadContributionModel
Definition: payload_contribution_model.h:18
arcs::aubo_scope::PayloadContributionModel::~PayloadContributionModel
~PayloadContributionModel()
arcs::aubo_scope::PayloadContributionModel::PayloadContributionModel
PayloadContributionModel()
arcs::aubo_scope::PayloadContributionModel::PayloadContributionModel
PayloadContributionModel(PayloadContributionModel &&f)
arcs::aubo_scope::PayloadContributionModel::PayloadContributionModel
PayloadContributionModel(PayloadContributionModel &f)
arcs::aubo_scope::PayloadContributionModel::removePayload
void removePayload(const std::string &id_key)
Remove a payload added by this AuboCap from AuboScope.
arcs::aubo_scope::PayloadContributionModel::updatePayload
void updatePayload(const std::string &id_key, double mass, const std::vector< double > &center_of_gravity)
arcs::aubo_scope::PayloadContributionModel::addPayload
PayloadPtr addPayload(const std::string &id_key, const std::string &suggested_name, double mass, const std::vector< double > &center_of_gravity)
arcs::aubo_scope::PayloadContributionModel::updatePayload
void updatePayload(const std::string id_key, double mass, const std::vector< double > &center_of_gravity, const std::vector< double > &inertia_matrix)
Update the mass, center of gravity (CoG) and inertia matrix of an existing payload added by this Aubo...
arcs::aubo_scope::PayloadContributionModel::addPayload
PayloadPtr addPayload(const std::string &id_key, const std::string &suggested_name, double mass, const std::vector< double > &center_of_gravity, const std::vector< double > &inertiaMatrix)
arcs::aubo_scope::PayloadContributionModel::getPayload
PayloadPtr getPayload(const std::string &id_key)
Returns the payload previously added by this AuboCap using the same idKey identifier.
arcs::aubo_scope::ARCS_CLASS_FORWARD
ARCS_CLASS_FORWARD(GripForceCapability)
arcs
Definition: contribution_provider.h:7
payload.h