screw_driver_contribution.h

浏览该文件的文档.

#ifndef AUBO_SCOPE_SCREW_DIRVER_CONTRIBUTION_H
#define AUBO_SCOPE_SCREW_DIRVER_CONTRIBUTION_H
 
#include <aubo_caps/domain/system_api.h>
#include <aubo_caps/domain/script/script_writer.h>
#include <aubo_caps/contribution/driver/screw_driver/screw_driver_configuration.h>
#include <aubo_caps/contribution/driver/screw_driver/screw_driver_parameters.h>
#include <aubo_caps/contribution/driver/screw_driver/screw_driver_api_provider.h>
 
namespace arcs {
namespace aubo_scope {
ARCS_CLASS_FORWARD(ScrewdriverContribution);
 
/**
 * \chinese
 * 螺丝刀贡献
 * 此接口定义了向 AuboScope 添加螺丝刀功能的 API。
 *
 * 实现此接口将把螺丝刀贡献"集成"（挂钩）到内置（原生）AuboScope 螺丝刀程序节点
 * 和螺丝刀安装画面中。这将向终端用户暴露螺丝刀支持的螺丝驱动功能。
 *
 * <b>注意：</b>内置（原生）AuboScope 螺丝刀程序节点和螺丝刀贡献在 CB3 机器人上
 * 均不受支持。如果 AuboCap 在 CB3 机器人上注册了螺丝刀贡献，AuboCap 将无法激活。
 *
 * 螺丝刀程序节点允许终端用户编程螺丝驱动操作。终端用户可用的参数基于螺丝刀支持的
 * 属性和功能。至少，所有螺丝刀必须支持"默认"拧紧（启动螺丝刀）和停止（停止螺丝刀）
 * 操作。所有其他功能是可选的，可以在调用
 * {@link ScrewdriverContribution#configureScrewdriver(ScrewdriverConfiguration,
 * ScrewdriverApiProvider)} 方法时注册。
 *
 * 螺丝刀安装画面中的集成允许用户选择螺丝刀来进行拧紧操作编程（使用螺丝刀程序节点）。
 * 它还提供了定义终端用户所需的任何自定义输入来设置螺丝刀的可能性，例如指定 IP 地址。
 * 此功能是可选的，因为此类配置属性是特定于每个螺丝刀设备的。相应的生成自定义 UI 将在
 * 用户选择螺丝刀时在画面中可访问，并替换默认的螺丝刀安装 UI。当调用
 * {@link ScrewdriverContribution#configureInstallation(CustomUserInputConfiguration,
 * SystemConfiguration, TCPConfiguration, ScrewdriverApiProvider)} 方法时，提供创建
 * 基于用户输入的自定义配置的访问权限。
 * \endchinese
 * \english
 * ScrewdriverContribution
 * This interface defines an API for adding functionality for screwdrivers to
 * AuboScope.
 *
 * Implementing this interface will "integrate" (hook) this screwdriving
 * contribution into the builtin (native) AuboScope Screwdriving program node
 * and Screwdriving installation screen. This will expose the screwdriving
 * functionality supported by the screwdriver to the end user.
 *
 * <b>Note:</b> Both the builtin (native) AuboScope Screwdriving program node
 * and Screwdriver contributions are not supported on CB3 robots. If a AuboCap
 * registers a Screwdriver contribution on a CB3 robot, the AuboCap will fail to
 * be activated.
 *
 * The Screwdriving program node allows the end user to program screwdriving
 * operations. The configuration options available to the end user are based on
 * the properties and capabilities supported by the screwdriver. As a minimum,
 * all screwdrivers must support "default" screw (start screwdriver) and stop
 * (stop screwdriver) operations. All other capabilities are optional to support
 * and can be registered when the method
 * {@link ScrewdriverContribution#configureScrewdriver(ScrewdriverConfiguration,
 * ScrewdriverApiProvider)} is called.
 *
 * The integration in the Screwdriving installation screen allows the user to
 * select the screwdriver for programming screwing operations (using the
 * Screwdriving program node). It also offers the possibility to define any
 * custom inputs from the end user that are required to setup the screwdriver,
 * e.g. specifying an IP address. This functionality is optional, since such
 * configuration properties are specific for each screwdriver device. The
 * corresponding generated custom UI will be accessible in the screen when the
 * screwdriver is selected (by the end user) and replace the default
 * Screwdriving installation UI. Access to create a custom configuration based
 * on user inputs is provided when the method
 * {@link
 * ScrewdriverContribution#configureInstallation(CustomUserInputConfiguration,
 * SystemConfiguration, TCPConfiguration, ScrewdriverApiProvider)} is called.
 * \endenglish
 */
class ScrewdriverContribution
{
public:
    virtual ~ScrewdriverContribution() = default;
 
    /**
     * \chinese
     * 此方法必须返回螺丝刀贡献的标题。标题显示在以下位置：
     * <ul>
     * <li>内置 AuboScope 螺丝驱动安装画面顶部选择螺丝刀的位置</li>
     * <li>内置 AuboScope 螺丝驱动程序节点的画面（如果已在螺丝驱动安装画面中选择了
     * 此螺丝刀）</li>
     * </ul>
     * 此方法在启动时调用一次。
     *
     * @param locale AuboScope 的当前语言环境，可用于支持多种语言的标题
     * @return 此螺丝刀贡献的标题，不能为 <code>null</code> 也不能为空字符串
     * \endchinese
     * \english
     * This method must return the title of the screwdriver contribution. The
     * title is displayed in: <ul> <li>The builtin (native) AuboScope
     * Screwdriving installation screen at the top where the screwdriver is
     * selected
     *     </li>
     *     <li>The screen for the builtin (native) AuboScope Screwdriving
     * program node (if this screwdriver has been selected in the Screwdriving
     * installation screen)
     *     </li>
     * </ul>
     *
     * 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 screw driver 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 screwdriverConfiguration 可用于注册或设置螺丝刀属性和功能的配置实例
     * @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 screwdriver.
     * </p>
     * ...
     * @param screwdriverConfiguration a configuration instance that can be used
     * for registering or setting up the properties and capabilities of the
     * screwdriver.
     * @param apiProvider provides access to functionality and services
     * available from within AuboScope which can be relevant for setting up the
     * screwdriver capabilities (e.g. the {@link SystemAPI} interface with
     * functionality for querying information about the robot).
     * \endenglish
     */
    virtual void configureScrewdriver(
        ScrewdriverConfiguration screwdriverConfiguration,
        ScrewdriverAPIProviderPtr apiProvider);
 
    /**
     * \chinese
     * <p>当调用此方法时，必须生成驱动螺丝的脚本代码。</p>
     * 终端用户定义/配置的已注册可选螺丝刀功能/要求的参数将作为脚本代码生成的输入。
     *
     * @param scriptWriter 使用此脚本编写器实例生成驱动螺丝的脚本代码
     * @param parameters 终端用户定义/配置的螺丝驱动操作参数
     * \endchinese
     * \english
     * <p>
     * When this method is called, the script code for driving the screw must be
     * generated.
     * </p>
     * The relevant parameters for the registered optional screwdriver
     * capabilities/requirements defined/configured by the end user are provided
     * as input to the script code generation.
     *
     * @param scriptWriter use this script writer instance to generate the
     * script code for driving the screw
     * @param parameters the parameters for the screwdriving operation
     * defined/configured by the end user
     * \endenglish
     */
    virtual void generateStartScrewdriverScript(
        ScriptWriterPtr scriptWriter, ScrewdriverParametersPtr parameters) = 0;
 
    /**
     * \chinese
     * <p>当调用此方法时，必须生成停止螺丝刀的脚本代码（即螺丝刀必须停止当前的
     * 螺丝驱动操作）。</p>
     * 终端用户定义/配置的已注册可选螺丝刀功能/要求的参数将作为脚本代码生成的输入。
     *
     * @param scriptWriter 使用此脚本编写器实例生成停止螺丝刀的脚本代码
     * @param parameters 终端用户定义/配置的螺丝驱动操作参数
     * \endchinese
     * \english
     * <p>
     * When this method is called, the script code for stopping the screw driver
     * must be generated (i.e. the screwdriver must stop the current
     * screwdriving operation).
     * </p>
     * The relevant parameters for the registered optional screwdriver
     * capabilities/requirements defined/configured by the end user are provided
     * as input to the script code generation.
     *
     * @param scriptWriter use this script writer instance to generate the
     * script code for stopping the screwdriver
     * @param parameters the parameters for the screwdriving operation
     * defined/configured by the end user
     * \endenglish
     */
    virtual void generateStopScrewdriverScript(
        ScriptWriterPtr scriptWriter, ScrewdriverParametersPtr parameters) = 0;
    ;
};
} // namespace aubo_scope
} // namespace arcs
 
#endif