Skip to end of metadata
Go to start of metadata

Table of Contents

Interface Overview for "Instrument State Models"

Subsystem MI
Giver Instrument Agent, Instrument Driver
Receiver Instrument Agent, ION Services (SA)
Release Introduced R2
Document Number None
Interface Description  
Technical Notes  
Source Code [xxx]


Each physical sensor in the ION Cyberinfrastructure is represented logically by an Instrument Agent, which in turn employs a device specific Instrument Driver to control the sensor hardware it is responsible for. Coupled agent and driver state models are used as high- and low-level control mechanisms, respectively, with the agent state model providing a unified common behavior to external user services and the instrument state models providing a more finely grained model for use by the agent in hardware command and control. This page describes the these state models and details of their use. Flow of control between agent user services, the instrument agent, the instrument driver, and the driver communications framework is illustrated below.

Figure 1. Instrument state machine flow of control.

The CI state models described on this page can be compared to the SIAM instrument service state machine.

Instrument Agent State Machine

The agent state model, shown below, consists of the following states

Agent State Superstate Description
POWERED DOWN None The device is powered down.
POWERED UP None The device is powered up.
UNINITIALIZED POWERED UP The agent's internal driver is not configured.
INACTIVE POWERED UP The agent's internal driver is configured but has not established communication with the device hardware.
ACTIVE POWERED UP The agent's internal driver has established communication with the device hardware.
IDLE ACTIVE The device has been cleared of any context that may have built up during operations, and is ready to start again from the beginning.
STOPPED ACTIVE The device has some sort of context built up (likely due to having collected data). This context is sufficient to checkpoint for the purpose of resuming where it left off...possibly after a process has been moved to another execution environment.
RUNNING ACTIVE The device is in a running state and can be commanded and controlled.
COMMAND RUNNING The device is available for interactive command and response.
STREAMING RUNNING The device is streaming data.
TEST RUNNING The device is running a self test.
CALIBRATE RUNNING The device is running a calibration routine.
DIRECT ACCESS RUNNING The device is in an exclusive direct access session with a qualified user.
BUSY RUNNING The device is busy performing an unspecified activity.

Figure 2. Instrument agent common finite state model.

Handlers are defined in the instrument agent for all non-enclosing states (implemented as a flat finite state machine), that allow the agent to respond to events in a state specific manner. Typical logical control of flow initiated by a user service can be described as follows:

  1. A user service makes an RPC call against the agent interface.
  2. Upon receipt of the PRC, the agent fires an eponymous event representing the command at the agent state machine.
  3. The agent FSM intercepts the event. If the event can be processed in the current state a handler for the operation is invoked. If the event cannot be processed in the current state, a state conflict exception is raised.
  4. Upon completion, the handler returns any result and agent state transition that should occur as a result of the action.
  5. The agent FSM transitions state if necessary.
  6. The agent RPC function returns the handler result to the calling service.

Agent FSM command events illustrate the transition arrows in Figure 2. RUNNING substates STREAMING, TEST, CALIBRATE and BUSY are not directly invoked by agent logic, as they depend on the success of interactions with the device that occur at the driver level. Therefore, these transitions are invoked via an execute resource command, whose result includes any appropriate agent state transition. For example, devices that are capable of streaming data will export an execute resource "go autosample" command in their driver interface. In COMMAND mode, an agent accepts execute resource commands and forwards them to the driver for handling. The driver interactively commands the device to enter streaming mode, and if successful, replies to the agent to transition to STREAMING when the agent execute resource handler concludes. A similar control flow exists for exiting streaming mode, which returns the agent to COMMAND. This properly couples the agent and driver transitions without the possibility of a race condition (for example if some communication outside the execute handlers were used to synchronize states, allowing for a possibility of subtle or stochastic state misalignment). It also allows drivers to reflect themselves in the agent state model without the agent having to maintain any knowledge of driver internals or their specific states.

In addition to this control flow, the agent may also respond in a state specific manner to spontaneous events from the driver, such as samples, lost connections, asynchronous results or errors. A typical sequence can be described as follows:

  1. A driver event occurs.
  2. The driver sends an asynchronous message to the agent representing the event.
  3. An event handler within the agent processes the driver event, and fires an event at the agent FSM.
  4. A handler in the agent FSM processes the related event and takes appropriate actions, such as agent state transitions.

Variations on these themes occur as sensible within the agent framework. In this two-way flow of information, the agent and driver state machines can be easily synchronized and coordinated to carry out the required functions as described in the agent interface.

Instrument Driver Connection and Protocol State Machines

Drivers introduce two additional state machines as fine grained device control systems. The first is a simple connection state machine that manages the status of communications with the device and is common across many drivers. The second is a protocol state machine that characterizes the behavior of the device hardware and is specific to that driver and device. States and diagrams for these two state machines are shown below, where we give an example of a SBE37 CTD for the protocol state machine.

Connection State Description
UNCONFIGURED The driver is not configured for communication with the device.
DISCONNECTED The driver has not established communication with the device.
CONNECTED The driver has established communication with the device and is in some protocol state.
Protocol State Description
UNKNOWN The device is in an unknown state, for example upon initial connection.
COMMAND The device is in an interactive command and response mode.
AUTOSAMPLE The device is streaming samples at some configured rate.
DIRECT ACCESS The device is being controlled without driver command translation, for example manually or with 3rd party software.

Figure 3. Driver state machines. Single connection instrument driver connection fsm (left), and SBE37 protocol fsm (right).

Logical flow of control in the driver state models is similar to that of the agent above, including RPC and asynchronous processing mechanisms. The driver state machines are layered, with all driver RPC commands resulting in connection state machine events. Handlers in the connection state machine either take actions related to changing the connection status, or if they are device command events, are forwarded to the protocol state machine where device specific handlers translate commands and responses into device specific formats.


interfacespec interfacespec Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.