How to access and use the Web API

From Intrument Element Wiki

Jump to: navigation, search


Accessing the Instrument using Web Service

Web Service API:

The term "Instrument Element" (IE) describes a set of services that provide the needed interface and implementation to enable the remote control and monitoring of physical instruments. The term "Instrument" is used in this context to describe a piece of equipment that needs to be initialized, configured, operated (start, stop, standby, resume, application specific commands), monitored, or reset. An instrument can actually consist of a logical collection of instruments, and it is the responsibility of the instrument owner to decide how to group his or her instruments. An Instrument Manager (IM) is the implementation of a common interface to an instrument, or possibly a group of real instruments or a simulation of real instruments. An IM is completely described by its parameters, attributes, commands, and finite state machine:

  • Parameters hold configuration information
  • Attributes hold instrument variables
  • Commands hold actions
  • Finite state machine adds constraints over the commands

IMs can be organized in a hierarchy, as happens in most of the available control systems (EPICS, TANGO, PVSS, ...):



| |


It is possible to navigate the hierarchy via the getInstrumentManagers methods. If a complex instrument can be controlled in more than one way, the control structures (aka the hierarchy of the IM) can be memorized in the Resource Service in a different folder (named contexts) in order to improve access. It is also possible to navigate the contexts structure via the getContexts methods. This interface represents the proxy service that other software components should use in order to access the Instrument Element services and the instruments.


EXAMPLE: Voltmeter-- If the Instrument Manager represents a virtualization of a voltmeter (a measuring instrument for measuring the voltage between two points in an electric circuit--more information is available at: Voltmeter), then a simplified mapping of the IM's parameters, attributes, commands, and finite state machine could be:

  • Parameters: Maximum Voltage, Minimum voltage
  • Attributes: Measured Voltage
  • Commands: Perform a measure
  • Finite State Machine: IM-Linked (the IM is connected the instrument), IM-Unlinked, Error.

You can refer to this javadoc link for more information.

Below, you will find the UML diagrams related to the objects used in the Web Service APIs.


Please note that commands are used to present generic input to the instrument manager. This input can contain parameters and may change the instrument manager state.



Note that parameters are values used to transfer/retrieve information from external components to one or more Instrument Manager(s). A Parameter is a name-value couple linked as a string. The name is the key: it can not be null (or empty), and objects with the same name are the same object. The field exported is an int that defines whether the parameter is optional, in case of commands, and the read/write mode: 0: required 1: readonly 2: read and write (default value) 3: writeonly



Note that a finite state machine (FSM) or finite automaton is a model of behavior composed of states and transitions. A state stores information about the past, i.e., it reflects the input changes from system start to the present moment. A state machine is represented by a list of transitions and states. More info:



This defines a Finite State Machine Transition. A transition is defined by an initial state (fromState) and the command that has to be executed.



Note that this class represents an exception that can be remotely thrown from the Instrument Element to the users during a command execution.


Using the SOAP Monitor

The Instrument Element is configured to work properly with the SOAP monitor. It may help during the debug of your methods for accessing the service. You can find more information on how to use it at the following link: SOAP Monitor

Pre-generated Stubs

The Current Release contains a pre-generated stub in Java. You can find the classes at the following link: Instrument Element Web Service Stub

Personal tools