SkillProviderInterface.ice

/*
 * This file is part of ArmarX.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @package    RobotAPI::ArmarXObjects::SkillManager
 * @author     Raphael Grimm ( raphael dot grimm at kit dot edu )
 * @date       2020
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */

#pragma once

#include <ArmarXCore/interface/core/time.ice>

#include <RobotAPI/interface/aron.ice>


// We need to prototype the interface
module armarx
{
    module skills
    {
        module callback
        {
            module dti
            {
                interface SkillProviderCallbackInterface;
            }
        }

        module provider
        {
            module dti
            {
                interface SkillProviderInterface;
            }
        }
    }
}

module armarx
{
    module skills
    {
        module core
        {
            module dto
            {
                // The status enum of a skill
                module Execution
                {
                    enum Status
                    {
                        Constructing,
                        Initializing,
                        Preparing,
                        Running,

                        // terminating values
                        Failed,
                        Succeeded,
                        Aborted
                    };
                }
            }
        }
    }
}


module armarx
{
    module skills
    {
        module provider
        {
            module dto
            {

                // A profile is something that is client side!
                //                // A parameterization profile
                //                struct SkillProfile
                //                {
                //                    string profileName;
                //                    string predecessorProfileName; // may be empty
                //                    aron::data::dto::Dict
                //                        parameterization; // may be only a partial set of accepted type
                //                };

                //                // A list of parameterization profiles. Note that the first element is recognized as root. Following elements overwrite the previous.
                //                dictionary<string, SkillProfile> SkillProfileDict;

                // A skill ID. Must be unique within one SkillManager
                struct SkillID
                {
                    string skillName;
                };

                // Description of a skill, independant of a provider
                // A skill is nothing but a executable thing, which can be executed
                struct SkillDescription
                {
                    SkillID skillId;
                    string description;
                    armarx::core::time::dto::Duration timeout;
                    aron::type::dto::AronObject parametersType;
                    aron::type::dto::AronObject resultType;
                    aron::data::dto::Dict rootProfileDefaults;
                };

                dictionary<SkillID, SkillDescription> SkillDescriptionMap;

                // Input to a provider to execute a skill
                struct SkillExecutionRequest
                {
                    SkillID skillId;
                    string executorName;
                    aron::data::dto::Dict parameters;
                    callback::dti::SkillProviderCallbackInterface* callbackInterface;
                };

                // The minimum information that is needed to uniquely identifying a past skill execution
                struct SkillExecutionID
                {
                    SkillID skillId;
                    string executorName;
                    armarx::core::time::dto::DateTime executionStartedTime;
                    string uuid;
                };

                // Status updates of a skill
                struct SkillStatusUpdate
                {
                    SkillExecutionID executionId;
                    aron::data::dto::Dict parameters;
                    callback::dti::SkillProviderCallbackInterface* callbackInterface;
                    core::dto::Execution::Status status;
                    aron::data::dto::Dict result;
                    /// @todo maybe add in future:
                    // aron::data::dto::Dict feedback;
                };

                dictionary<SkillExecutionID, SkillStatusUpdate> SkillStatusUpdateMap;

                struct ParameterUpdateResult
                {
                    bool success; // false if skill is not running (anymore) or already prepared
                };

                struct AbortSkillResult
                {
                    bool success; // false if skill is not running (anymore)
                };
            }

            module dti
            {
                interface SkillProviderInterface
                {
                    optional(1) dto::SkillDescription getSkillDescription(dto::SkillID skill);

                    dto::SkillDescriptionMap getSkillDescriptions();

                    optional(2) dto::SkillStatusUpdate
                        getSkillExecutionStatus(dto::SkillExecutionID executionId);

                    dto::SkillStatusUpdateMap
                    getSkillExecutionStatuses(); // returns all current skill executions

                    // execute skill will ALWAYS fully execute the skill and wait, until the skill is finished.
                    // TODO: Explain skill phases
                    // This method returns a status update where the status is ALWAYS one of the terminating values
                    dto::SkillStatusUpdate executeSkill(dto::SkillExecutionRequest executionInfo);

                    dto::SkillExecutionID
                    executeSkillAsync(dto::SkillExecutionRequest executionInfo);

                    dto::ParameterUpdateResult
                    updateSkillParameters(dto::SkillExecutionID executionId,
                                          aron::data::dto::Dict params); // add params to a skill

                    // try to kill a skill as soon as possible. When the skill is stopped depends on the implementation.
                    dto::AbortSkillResult abortSkill(dto::SkillExecutionID skill);
                    dto::AbortSkillResult abortSkillAsync(dto::SkillExecutionID skill);
                };
            }
        }
    }
}


module armarx
{
    module skills
    {
        module callback
        {
            module dto
            {
                struct ProviderID
                {
                    string providerName;
                };
            }

            module dti
            {
                interface SkillProviderCallbackInterface
                {
                    // used for callbacks from providers to update their skill execution status
                    void updateStatusForSkill(provider::dto::SkillStatusUpdate statusUpdate,
                                              dto::ProviderID providerId);
                }
            }
        }
    }
}