gripper_contribution.h

Go to the documentation of this file.

#ifndef AUBO_SCOPE_GRIPPER_CONTRIBUTION_H
#define AUBO_SCOPE_GRIPPER_CONTRIBUTION_H
 
#include <aubo_caps/contribution/driver/gripper/gripper_api_provider.h>
#include <aubo_caps/contribution/driver/gripper/gripper_configuration.h>
#include <aubo_caps/contribution/driver/gripper/release_action_parameters.h>
#include <aubo_caps/contribution/driver/gripper/grip_action_parameters.h>
 
#include <aubo_caps/domain/system_api.h>
#include <aubo_caps/domain/script/script_writer.h>
 
namespace arcs {
namespace aubo_scope {
ARCS_CLASS_FORWARD(GripperContribution);
 
/**
 * \chinese
 * 夹爪贡献
 * 此接口定义了向 AuboScope 添加夹爪设备功能的 API。
 *
 * 实现此接口将创建程序节点贡献、安装贡献和工具栏贡献，向终端用户暴露夹爪功能。
 * 请注意，工具栏贡献在 CB3 机器人上不受支持。
 *
 * 程序节点贡献允许终端用户编程夹取和释放操作。终端用户可用的配置选项基于夹爪
 * 支持的属性和功能。至少，所有夹爪必须支持"默认"夹取和释放操作。所有其他功能
 * 是可选的，可以在调用 {@link GripperContribution#configureGripper(GripperConfiguration,
 * GripperAPIProvider)} 方法时注册。
 *
 * 安装节点贡献可在需要终端用户提供任何自定义输入来设置夹爪时使用（例如指定 IP 地址）。
 * 相应的生成 UI 将在安装节点中可访问。此功能是可选的，因为此类配置属性是特定于
 * 每个夹爪的。当调用
 * {@link GripperContribution#configureInstallation(CustomUserInputConfiguration,
 * SystemConfiguration, TCPConfiguration, GripperAPIProvider)} 方法时，提供创建
 * 基于用户输入的自定义配置的访问权限。如果没有定义自定义用户输入、文本等，安装节点
 * 将不会在 AuboScope 中可见。前言脚本代码（由
 * {@link #generatePreambleScript(ScriptWriter)} 生成）仍将添加到机器人程序中。
 *
 * 工具栏贡献为终端用户提供快速访问，以使用"默认"夹爪操作参数执行夹取和释放操作。
 * \endchinese
 * \english
 * GripperContribution
 * This interface defines an API for adding functionality for gripping devices
 * to AuboScope.
 *
 * Implementing this interface will create a program node contribution, an
 * installation contribution and a toolbar contribution exposing gripper
 * functionality to the end user. Note that the toolbar contribution is not
 * supported on CB3 robots.
 *
 * The program node contribution allows the end user to program grip and release
 * actions. The configuration options available to the end user are based on the
 * properties and capabilities supported by the gripper. As a minimum, all
 * grippers must support "default" grip and release actions. All other
 * capabilities are optional to support and can be registered when the {@link
 * GripperContribution#configureGripper(GripperConfiguration,
 * GripperAPIProvider)} method is called.
 *
 * The installation node contribution can be used, if any custom input from the
 * end user is required to setup the gripper, e.g. specifying an IP address. The
 * corresponding generated UI will be accessible in the installation node. This
 * functionality is optional, since such configuration properties are specific
 * for each gripper. Access to create a custom configuration based on user
 * inputs is provided when the method
 * {@link
 * GripperContribution#configureInstallation(CustomUserInputConfiguration,
 * SystemConfiguration, TCPConfiguration, GripperAPIProvider)} is called. If no
 * custom user inputs, texts, etc. are defined, the installation node will not
 * be visible in AuboScope. Preamble script code (generated by {@link
 * #generatePreambleScript(ScriptWriter)}) will still be added to the robot
 * program.
 *
 * The toolbar contribution provides the end user quick access to perform grip
 * and release actions using "default" gripper action parameters.
 * \endenglish
 */
class GripperContribution
{
public:
    virtual ~GripperContribution() = default;
 
    /**
     * \chinese
     * 此方法必须返回夹爪贡献的标题。标题显示在以下位置：
     * <ul>
     * <li>程序标签页的"结构"区域中此类夹爪程序节点的显示（可从此处插入夹爪程序节点）</li>
     * <li>此夹爪贡献的程序节点画面</li>
     * <li>程序树中此夹爪贡献程序节点的标题</li>
     * <li>安装标签页左侧导航中此夹爪贡献的显示</li>
     * <li>此夹爪贡献的安装节点画面</li>
     * <li>此夹爪的工具栏贡献。注意：工具栏贡献在 CB3 机器人上不可用</li>
     * </ul>
     *
     * <p>此方法的返回值不能为 <code>null</code>，也不能为空字符串。</p>
     * 此方法在启动时调用一次。
     *
     * @param locale AuboScope 的当前语言环境，可用于支持多种语言的标题
     * @return 此夹爪贡献的标题，不能为 <code>null</code> 也不能为空字符串
     * \endchinese
     * \english
     * This method must return the title of the gripper contribution. The title
     * is displayed in: <ul> <li>The Structure section of the Program Tab for
     * this type of gripper program node (from which the Gripper program node
     * can be inserted)</li> <li>The program node screen for this gripper
     * contribution.</li> <li>The Program Tree as title for the program node for
     * this gripper contribution</li> <li>The left-hand side navigation of the
     * Installation Tab for this gripper contribution.</li> <li>The installation
     * node screen for this gripper contribution.</li> <li>The toolbar
     * contribution for this gripper. Note: The toolbar contribution is not
     * available on CB3 robots.</li>
     * </ul>
     *
     * <p>
     * The return value of this method cannot be <code>null</code> nor an empty
     * string.
     * </p>
     *
     * This method is called once upon startup.
     *
     * @param locale The current locale of AuboScope. Can be used for supporting
     * titles in several languages.
     * @return The title of this gripper contribution, not <code>null</code> nor
     * an empty string.
     * \endenglish
     */
    virtual std::string getTitle(/*Locale locale*/) = 0;
 
    /**
     * \chinese
     * <p>当调用此方法时，使用 configuration 参数注册或设置夹爪的可选属性和功能。</p>
     * <p>此方法在夹爪配置阶段调用，在贡献注册后、新安装被加载或创建时调用。</p>
     * <b>注意：</b>如果夹爪仅支持基本的"默认"夹取和释放操作，请将此方法的实现留空。
     *
     * @param gripperConfiguration 可用于注册或设置夹爪属性和功能的配置实例
     * @param apiProvider 提供对 AuboScope 中可用于设置夹爪功能的相关功能和服务访问
     * \endchinese
     * \english
     * <p>
     * When this method is called, use the configuration parameter to register
     * or setup optional properties and capabilities of the gripper.
     * </p>
     *
     * <p>
     * The method is called in the Gripper Configuration phase after this
     * contribution has been registered when a new installation is loaded or
     * created.
     * </p>
     *
     * <b>Note:</b> If the gripper only supports basic "default" grip and
     * release actions, leave the implementation of this method empty.
     *
     * @param gripperConfiguration A configuration instance that can be used for
     * registering or setting up the properties and capabilities of the gripper.
     * @param apiProvider Provides access to functionality and services
     * available from within AuboScope which can be relevant for setting up the
     * gripper capabilities (e.g. the {@link SystemAPI} interface with
     * functionality for querying information about the robot).
     * \endenglish
     */
    virtual void configureGripper(GripperConfigurationPtr gripperConfiguration,
                                  GripperApiProviderPtr apiProvider) = 0;
 
    /**
     * \chinese
     * <p>当调用此方法时，必须生成使用夹爪执行夹取动作的脚本代码。</p>
     * <p>终端用户定义/配置的已注册可选夹爪功能参数将作为脚本生成的输入。</p>
     * <p>此方法在以下场景中调用：</p>
     * <ul>
     * <li>当配置了夹取动作的夹爪程序节点应作为要执行的机器人程序的一部分生成脚本代码时</li>
     * <li>当终端用户测试夹爪程序节点的夹取配置时</li>
     * <li>当使用工具栏操作夹爪时</li>
     * </ul>
     *
     * <b>注意：</b>
     * <ul>
     * <li>夹取物体后应用新的总负载<b>不是</b>夹爪的职责，因为这是 AuboScope 自动处理的。</li>
     * <li>当终端用户指定了新的负载时，用户定义的负载值将在夹取动作的生成脚本代码完成
     * 执行后立即由 AuboScope 应用。因此脚本代码不应在适当应用新负载值之前完成。
     * </li>
     * </ul>
     *
     * @param scriptWriter 使用此脚本编写器实例生成夹取脚本代码
     * @param parameters 终端用户定义/配置的夹爪动作参数
     * \endchinese
     * \english
     * <p>
     * When this method is called, the script code for performing a grip action
     * with the gripper must be generated.
     * </p>
     *
     * ...
     * @param scriptWriter Use this script writer instance to generate the
     * script code for gripping
     * @param parameters The parameters for the gripper action
     * defined/configured by the end user
     * \endenglish
     */
    virtual void generateGripActionScript(
        ScriptWriterPtr scriptWriter, GripActionParametersPtr parameters) = 0;
 
    /**
     * \chinese
     * <p>当调用此方法时，必须生成使用夹爪执行释放动作的脚本代码。</p>
     * <p>终端用户定义/配置的已注册可选夹爪功能参数将作为脚本生成的输入。</p>
     * <p>此方法在以下场景中调用：</p>
     * <ul>
     * <li>当配置了释放动作的夹爪程序节点应作为要执行的机器人程序的一部分生成脚本代码时</li>
     * <li>当终端用户测试夹爪程序节点的释放配置时</li>
     * <li>当使用工具栏操作夹爪时</li>
     * </ul>
     *
     * <b>注意：</b>
     * <ul>
     * <li>释放物体后应用新的总负载<b>不是</b>夹爪的职责，因为这是 AuboScope 自动处理的。</li>
     * <li>当终端用户指定了新的负载时，用户定义的负载值将在释放动作的生成脚本代码完成
     * 执行后立即由 AuboScope 应用。因此脚本代码不应在适当应用新负载值之前完成。</li>
     * </ul>
     *
     * @param scriptWriter 使用此脚本编写器实例生成释放夹爪的脚本代码
     * @param parameters 终端用户定义/配置的夹爪动作参数
     * \endchinese
     * \english
     * <p>
     * When this method is called, the script code for performing a release
     * action with the gripper must be generated.
     * </p>
     * ...
     * @param scriptWriter Use this script writer instance to generate the
     * script code for releasing the gripper
     * @param parameters The parameters for the gripper action
     * defined/configured by the end user
     * \endenglish
     */
    virtual void generateReleaseActionScript(
        ScriptWriterPtr scriptWriter,
        ReleaseActionParametersPtr parameters) = 0;
};
} // namespace aubo_scope
} // namespace arcs
#endif