ADCP-ISI Use Cases Revision 3 22-Jun-01 R.Schramm

Revision History:

Revision 1. 28-Feb-01 Original draft 1, circulated for comment to ISI and DM teams and M.Kelly (Observatory Support).

Revision 2. 28-Feb-01 Reformat and incorporate comments from draft 1- Circulated and presented at a regular ISI team mtg.

Revision 3. 22-Jun-01 Revised Use Case 8 – Send_Commands to reflect need to batch commands into transactions which can be rolled-back on failure. Changes are in sub-sections ‘General Description’ and ‘Exceptional flow of events 2’ –R.Schramm

 

 

The use cases below apply to some models of RD Instruments Acoustic Doppler Current Profilers. Specifically they apply to narrow-band models of vintage 1993. They have been developed from the perspective of a user responsible for data acquisition and archive and as such they are likely not all-inclusive. Additional use cases most certainly exist for the technicians responsible for deployment, recovery and calibration of the instrument. An attempt has been made to highlight some of the vendor specific peculiarities that have been observed with this generation of instrument. –R.Schramm

ADCP Background

An ADCP is an instrument which measures water current velocities using sound processing techniques. Data are typically as profiles of X,Y,Z components of water velocity in depth bins (actually distance bins) away from the instrument. Additional profile parameters are measured such as signal strength which is required for data processing and quality control. There are many parameters measured or reported by the instrument itself such as temperature at the instrument head and most of it’s current configuration. ADCPs send pings out into the water and process returns off of the particles drifting in currents. Typically many pings are required to be averaged over a period of several minutes to obtain reasonable readings. These ping averages are termed ‘ensembles’ which are what is reported out of the instrument. ADCP’s can be mounted on ships or cabled to shore for continuous sampling ‘direct reading’ or may be ‘self-contained’ for use on moorings. ADCP’s may be configured to report ensembles automatically, when polled, or to buffer data for a longer period and then ‘dump’ it on command.

Since pinging is a relatively power hungry operation and ocean currents do not change all that quickly, for moored installations the instrument can be configured to automatically sleep and then sample in bursts according to it’s internal program. (eg. 1 minute of pinging, once-per-second, repeated every 15 minutes). This may require a listner to be there all the time, or scheduled to listen during the time window it is expecting a report.

ADCP’s require frequent instrument change-outs due to limited battery and data storage capacity as well as the near surface bio-fouling problem.

Some past problems include:

Useful References:

OASIS_ADCP –Software for unpacking OASIS_ADCP Data. MBARI Software Archive Document 5022 –R.Schramm

RD Instruments Self Contained ADCP Technical Manual

RD Instruments – Principles of Operatation: A practical Primer

 

SOME ISI ADCP USE CASES

  1. ADD_INSTRUMENT
  2. REMOVE_INSTRUMENT
  3. CHECK_INSTRUMENT
  4. SCHEDULE_LISTENING
  5. LISTEN_DATA
  6. POLL_DATA
  7. DUMP_DATA
  8. SEND_COMMANDS
  9. RESET

 

USE CASE 1: ADD_INSTRUMENT

Main flow of events:

This use case starts when operations technicians physically install an ISI compliant ADCP instrument package to a mooring platform at some depth. The off-shore component of the ISI system detects the new instrument and logs a time-stamped record about the event. The off-shore component of ISI sets up a schedule as needed to communicate with it the instrument to capture it’s data. The off-shore component of the ISI system enters into a dialog with the on-shore component to propagate the configuration changes so that the on-shore current state of the observatory is correct and the historical catalog can be maintained. The on-shore component automatically notifies the appropriate observatory human staff that an ‘add-instrument’ event has occurred.

This use case ends when:

  1. the on-shore observatory human staff has been sent notification of the time-stamped change events
  2. the off-shore component of ISI has:
    1. Properly set the state of all necessary parameters.
    2. Properly set up to listen for instrument data
    3. Received acknowledgement that the time-stamped notification of all required parameters was successfully received on-shore.
    4. Returned the ADCP to its proper sleep mode.

 

Exceptional flow of events 1:

The instrument is already known to the system. The off-shore platform state has not yet responded to a prior instrument removal event.

Exceptional flow of events 2:

The instrument is not fully or correctly ISI compliant, some important piece of the meta-data is missing .

Exceptional flow of events 3:

The off-shore component of ISI is never able to complete a notification transaction with the on-shore component. This could be due to such things as a link is never established to shore or the off-shore component of ISI looses the event information due to power or hardware failure.

Other action 1:

The ISI system may need to compute new power drains or capacities for the platform.

Other action 2:

In response to an Add_Instrument event notification, certain information may need to be entered into the system manually. Items such as final deployment nominal depth, lat/lon, access permissions etc. may need to be added by the operations technician. See Use Case #######.

Mainflow of events - Scenario Detail:

  1. ISI updates the off-shore configuration state for the platform is modified to reflect the addition of a new instrument – including :
    1. A type identifying it as an RD-Instruments ADCP
    2. A sub-type identifying as a 150Khz narrow-band with vsn 17.xx firmware.
  2. ISI updates the off-shore configuration state for the instrument is modified to show the following:
    1. The manufacturer’s instrument serial number
    2. Current data reporting rate (this is not necessarily the instruments internal sampling rate).
    3. Capacity
      1. Power
        1. How much does it draw from the system
          1. Awake
          2. Sampling
          3. Sleeping
      2. Data
        1. How much data it has stored
        2. How much can it hold
        3. When will it fill up
    4. Number of sensors
    5. For each sensor.
      1. A sensor type
      2. A sensor sub-type

    6. Number of special ‘constants’ for the instrument (e.g. deployment depth or upward or downward configured ADCP)
      1. For each special constant
        1. Name
        2. Value
  3. ISI updates the off-shore configuration state for each sensor of the instrument is modified to show the following:
    1. The manufacturer’s sensor serial number
    2. Number of data fields reported by the sensor
    3. For each data field of the sensor
      1. A data field type (e.g. current U,V,W or ERR velocity components)
      2. A data field sub-type (e.g. earth reference or instrument referenced)
      3. The units of the field (e.g. counts or cm/sec)
      4. Missing or BadValue for the field.
      5. Number of special ‘constants’ (e.g. upward or downward looking ADCP)
      6. For each special constant
        1. Name
        2. Value
  4. A schedule is set for when to listen for data based on the data reporting rate of the instrument.
    1. See use case ‘Schedule ADCP’ below.
  5. State change notification of ISI on-shore component is initiated (retry until successful).
    1. Contact shore
    2. Transmit all state data.
    3. On-shore component accepts state data – sends acknowledgment.
    4. Receive acknowledgement
  6. End of case
    1. Remove from on-shore notification list

 

USE CASE 2: REMOVE_INSTRUMENT

General Description:

ADCP is removed from a platform for maintenance.

Main flow of events:

Reverse case of ‘Add ADCP’ use case.

This use case ends when:

  1. the on-shore observatory human staff has been sent notification of the time-stamped change events
  2. the off-shore component of ISI has:
    1. Properly cleared the state of all parameters related to the instrument (including descheduling any listening events)
    2. Received acknowledgement that the time-stamped notification of the removal of the instrument.

 

 

Exceptional flow of events 1:

ADCP instrument is added back to platform ‘shortly’ after it was removed. Should it’s configuration be checked/updated to the previous?

Exceptional flow of events 2:

The instrument is not known to the system. The off-shore platform state has not yet responded to a prior instrument add event or is otherwise out of sync.

Exceptional flow of events 3:

The off-shore component of ISI is never able to complete a notification transaction with the on-shore component.

 

USE CASE 3: CHECK_INSTRUMENT

General Description:

Off-shore ISI component should periodically check that a specific instrument in it’s state table is still there according to some schedule.

Main flow of events:

This use case begins when some actor (human or software) initiates a request to verify the instuments existence. The action causes the instrument to wake-up (if needed) and commands (if needed) it to send it’s ISI identification data. The instrument is then returned to its prior state. This use case ends when the status is returned to the actor, the instrument is returned to its prior state, and the next check is scheduled (if needed).

Exceptional flow of events 1:

The instrument doesn’t respond indicating it may have gone away. The remove instrument use case should follow after any retry interval. See also – Reset and Remove_Instrument use cases.

 

 

USE CASE 4: SCHEDULE_LISTENING

General Description:

One mode of operation for an ADCP is to ‘auto-report’ its data ensemble at a fixed interval over a serial line. This is an asyncronous event that must be listened for by a receiver without handshake. Some previous implementations, (eg OASIS) have scheduled themselves to only listen in a time-window in order to preserve power and bandwidth. If the ISI system has similar requirements, this use case will need to be considered.

Main flow of events:

This use case begins when the off-shore ISI component adds an ADCP instrument to the platform. ISI system schedules the next appropriate time window to listen for data according to reporting rate parameters set in the instrument state info. This use case ends when the schedule is properly set.

Exceptional flow of events 1:

Reporting rate of parameters incorrectly set or impossible to meet given bandwith.

 

USE CASE 5: LISTEN_ DATA

General Description:

One mode of operation for an ADCP is to ‘auto-report’ its data ensemble at a fixed interval over a serial line. This is an asyncronous event that must be listened for by a receiver without handshake. This use case is repeated over-and-over again as records come in from the instrument. This use case is more likely used case for a ‘self-contained’ ADCP as opposed to the Poll_Data use case.

Main flow of events:

This use case begins when the ISI system begins to listen to the serial line associated with an ADCP instrument. (This may be continuous or scheduled). Some timeout mechanism should be established for the receiver. Each record received from the instrument is time-stamped with master clock data, checked for validity and then queued for transmission to the archive. If this use case is in response to some sort of scheduling event, the next event must be scheduled. This use case ends when the off-shore component of ISI receives acknowledgement that the data ensemble is accepted at the archive point and when the next event schedule (if any) is properly set.

Exceptional flow of events 1:

Incoming data over-flows the archive queuing mechanism. Possibly due to loss of communications to the archive port or bandwidth limitations. Human notification procedures are required.

Exceptional flow of events 2:

Data ensembles are not received within a set timeout period. This could be caused by many things including instrument or cable failure, scheduling failure, clock drift, internal instrument reset, baud-rate etc. The off-shore ISI component should include robust reset capabilities (soapbox comment). See Reset and Remove_Instrument use cases. Human notification procedures are required

USE CASE 6: POLL_DATA

General Description:

One mode of operation for an ADCP is to collect and report a single data ensemble on command. This involves a transaction with the instrument which involves a handshake protocol. Some period of seconds may pass to complete the sampling required to build the ensemble so there are handshake timeout issues to be dealt with. This use case is more likely used case for a ‘direct-connect’ ADCP as opposed to the Listen_Data use case.

 

Main flow of events:

This use case begins when some actor such as the ISI system ‘decides’ it is time to obtain a new ensemble from the instrument. The off-shore component of ISI will wake-up the adcp. It may need to verify the configuration parameters, then command the instrument to collect an ensemble and set up some timeout mechanism. After some number of seconds the instrument will report the ensemble of data. The record will be received from the instrument and is time-stamped with master clock data, checked for validity and then queued for transmission to the archive. The ADCP is then put back to sleep. If this use case is in response to some sort of scheduling event, the next event must be scheduled. This use case ends when the off-shore component of ISI receives acknowledgement that the data ensemble is accepted at the archive point, the next event schedule (if any) is properly set, and the instrument is in proper sleep condition.

Exceptional flow of events 1:

Communication is lost during the transaction resulting in a timeout. Human notification procedures are required

Exceptional flow of events 1:

Incoming data over-flows the archive queuing mechanism. Possibly due to loss of communications to the archive port or bandwidth limitations. Human notification procedures are required.

The off-shore ISI component should include robust reset capabilities (soapbox comment). See Reset and Remove_Instrument use cases. Human notification procedures are required

 

USE CASE 7: DUMP_DATA

General Description:

Primary technician on-shore requests a dump of all internally recorded data from a self-contained ADCP on a mooring that is ‘on-line’ – ie that has a real-time connection to the shore. This may require more bandwidth than is available. It is not clear at this time whether this is a use case that must be supported by the system. It is included here as a place-holder.

Main flow of events: This use case is a specialized version of use case 8 – Send_Commands. In this case the user would follow the same flow as that use case except the response from the instrument would be to send Kbytes to Mbytes of ensembles.

Exceptional flow of events 1:

Main flow of events – detailed scenario:

 

USE CASE 8: SEND_COMMANDS

General Description:

The ADCP is controlled by settings of it’s many internal parameters. The instrument must be ‘woken-up’ by sending a 200ms serial line ‘break’ and reading out it’s wakeup message. Commands can then be sent to change it’s internal settings or have it report it’s current configuration. Each command sent to it is acknowledged with some kind of response. Typically several commands must be sent to the instrument and it is inefficient to wake-up and sleep the instrument for each command. The entire batch of commands must be successfully acted upon for the correct operation of the instrument. In other words - there is a set of commands that must execute as a transaction with the instrument which is atomic – if a single command in the batch fails, the transaction must be rolled-back to leave the instrument in a known and valid (prior?) configuration. (Revision 3)

Improper or un-authorized commands can result in the complete loss of data – while others can render data unusable in ways that are difficult to spot and may go undetected for long periods of time. Some commands can instruct the instrument to download megabytes of internal data. Waking up the ADCP causes it to stop sampling data and may consume extra power if left in that state. Care must be taken to put the instrument back into correct sample/sleep mode on all exit and error paths. All of these actions must be protected operations.

Main flow of events:

This use case begins when an actor (human or machine) initiates a dialog with the ISI system directing it to contact an ADCP that is known to the system. The actor is then validated to ensure that the actor is authorized to connect to that specific instrument. After validation the instrument is sent a wake-up signal. The instrument response to the wake-up signal is returned to the user. The off-shore component of IS registers the fact that this instrument is now awake and sets a timeout period to check for lack of activity. Any pending ISI scheduled listening period is cancelled. The user then enters a command in the form required by the instrument’s firmware. The ISI system checks that it is a valid (properly formed) and legal (user is authorized to perform) command. The off-shore component of the ISI system forwards the command to the instrument and sets a timeout for the response. The instrument response is received and tested for success. Any effected off-shore ISI system parameters such as data update rate are modified and a time-stamped log entry record about the parameter change is made. The instrument response is forwarded to the actor. Additional commands may continue to be sent by the actor, repeating the sequence as needed (with the exception of the wake-up). Upon actor closing its connection or a timeout expiring on activity, the off-shore component of ISI sets up a new listening schedule as needed to communicate with the instrument to capture it’s data and then returns the instrument to it’s correct sleep mode. The off-shore component of the ISI system enters into a dialog with the on-shore component to propagate the time-stamped configuration changes so that the on-shore state of the observatory is correct and the historical catalog can be maintained.

This use case ends when:

  1. the on-shore observatory human staff has been sent notification of the time-stamped change events
  2. the off-shore component of ISI has:
    1. Properly set the state of all necessary parameters.
    2. Properly set up to listen for instrument data
    3. Received acknowledgement that the time-stamped notification of all required parameters was successfully received on-shore.
    4. Returned the ADCP to its proper sleep mode.

 

Exceptional flow of events 1:

Adcp doesn’t respond to wakeup or actor requested connection to instrument the doesn’t exist.

Exceptional flow of events 2:

Actor connection to ISI system is lost or goes inactive ( times-out) before actor has properly completed all steps. The ISI system must return the instrument to a known and valid state (roll-back) and notify the on-shore component of the changes. (Revision 3)

Exceptional flow of events 3:

ISI connection to instrument is lost or goes inactive – eg no response(time-out) after sending a valid command.

Exceptional flow of events 4:

Invalid comand or Actor is not authorized to perform command

 

 

 

Exceptional flow of events 1:

 

Main flow of events – detailed scenario:

 

USE CASE 9: RESET

General Description: An ADCP may fail to communicate in a number of ways which will require trying to re-contact the instrument and reset the instrument to its prior ISI system state (not the instrument’s default internal settings). This may be an extention and re-combination of other use cases including CHECK_INSTRUMENT, SEND_COMMAND and REMOVE_INSTRUMENT where the commands are sent to wake-up the instrument, set all parameters to the correct state, sent the instrument to sleep, set-up to listen for data, and notify shore side systems.

Main flow of events: This use case begins when an actor (human or machine) initiates a reset request of an ADCP instrument. This use case ends when the off-shore component of ISI has:

  1. Properly set the state of all necessary parameters from previous ISI states.
  2. Properly set up to listen for instrument data
  3. Received acknowledgement that the time-stamped notification of all required parameters was successfully received on-shore.
  4. Returned the ADCP to its proper sleep mode.

And when the on-shore observatory human staff has been sent notification of the change events.

Exceptional flow of events 1:

Connection cannot be established with the instrument. See use case REMOVE_INSTRUMENT.

Exceptional flow of events 2:

Exceptional flows for use cases CHECK_INSTRUMENT, SEND_COMMAND and REMOVE_INSTRUMENT all apply.