View Source

h2. Interface Overview for "{metadata:Interface Name}Instrument Agent{metadata}"

This page documents the implementation and behavior of the resource agent interface as implemented for ION process objects of type instrument agent.
_See the_ _[System Interfaces overview page|syseng:CIAD OV System Interfaces]_ _for a list of all internal and external system interfaces._

{metadata-list}
|| Subsystem | SA ||
|| Giver | Instrument Agent ||
|| Receiver | ION Services ||
|| Release Introduced | R1 ||
|| Document Number | None ||
|| Status | current ||
|| Interface Description | Specification and call side effects for instrument agents ||
|| Dependencies | None ||
|| Technical Notes | ||
|| Source Code | [Current master IA code|https://github.com/ooici/coi-services/blob/master/ion/agents/instrument/instrument_agent.py] ||
{metadata-list}


Resource Agents are an central class of [agents|CIAD SV Integration Strategy] with the purpose of representing and managing (taskable) resources in the ION system. Taskable resources are resources with internal state and potential behavior.

In Release 2, the following types of Resource Agent exist:
* Instrument Agent
* Instrument Agent Proxy
* Platform Agent
* Operational Unit Agent (represents one Virtual Machine Instance)
* Service Agent
* Dataset Agent

The figure below shows the specialization of the agent hierarchy in Release 2 and the respective responsibilities.

!https://docs.google.com/drawings/pub?id=1dZ-WoX0nHvRkOcrQ1bY1Zie0wGcSnBa-YqxCfSy_gsY&w=740&h=700!

_Figure 1. Agent Specialization (OV-1)_


h2. Generic Instrument Agent Interface

|| negotiate(sap_in=None) || Initiate a negotiation with this agent. The subject of this negotiation is the given ServiceAgreementProposal. The response is either a new ServiceAgreementProposal as counter offer, or the same ServiceAgreementProposal indicating the offer has been accepted. NEEDS REFINEMENT. || ||
|| Param || Desc || Type ||
| sap_in | ServiceAgreementProposal | ServiceAgreementProposal |
| return | ServiceAgreementProposal | ServiceAgreementProposal |
|| get_capabilities(current_state=True) || Introspect for agent capabilities. || ||
| current_state | Return capabilities available in current state only | Boolean |
| return | Agent capabilities | List of AgentCapabilities objects |
|| execute_resource(command=None) || Execute command on the resource represented by agent. || ||
|| Param || Desc || Type ||
| command | Command to execute | AgentCommand |
| return | Command result from the resource | AgentCommandResult |
|| get_resource(params=None) || Return the value of the given resource parameter. || ||
|| Param || Desc || Type ||
| params | List of agent parameters to query | list |
| return | Parameter Values | dict |
|| set_resource(params=None) || Set the value of the given resource parameters. || ||
|| Param || Desc || Type ||
| params | Dict of agent parameter-value pairs to set | dict |
| return | None | |
|| get_resource_state() || Return the current resource specific state, if available. || ||
|| Param || Desc || Type ||
| params | Dict of agent parameter-value pairs to set | dict |
| return | The current resource specific state | str |
|| ping_resource() || Ping the resource. || ||
|| Param || Desc || Type ||
| return | A representation of the resource and timestamp. | str |
|| execute_agent(command=None) || Execute command on the agent. || ||
|| Param || Desc || Type ||
| command | An agent command | AgentCommand |
| return | Command result from the agent | AgentCommandResult |
|| get_agent(params=None) || Return the value of the given agent parameters. || ||
|| Param || Desc || Type ||
| params | The parameters names to query | list of str |
| return | Dictionary of name-value pairs | dict |
|| set_agent(params=None) || Return the value of the given agent parameters. || ||
|| Param || Desc || Type ||
| params | Dictionary of name-value agent parameter pairs to set | dict |
| return | None | |
|| get_agent_state() || Return the current resource agent common state. || ||
|| Param || Desc || Type ||
| return | Current agent state | str |
|| ping_agent() || Ping the agent. || ||
|| Param || Desc || Type ||
| return | Representation of the agent and a timestamp | str |


h2. Execute Agent Commands and State Changes Controlling Driver Lifecycle

h2. Command Availability By State

h2. The Agent Capabilities Object and Schema