valve

Usage

>> valve [ id | scheduled | powerondelay | poweroffdelay | interval | duration | command | timetoepisode | startimmediate | episodelog | operationcount | scheduletype]

Security

Unsafe.

Description

This is a specialized command that has previously appeared only in specific firmware versions (1.119, 1.118, 1.115) used in BPR|zero logger systems.  This documentation now describes the command as implemented in all firmware versions 1.132 or later; there will be some differences from the earlier implementations.

The command returns information about the valve controller used in BPR|zero logger systems, and also allows some control over it.

• id reports (read-only) the type of valve configured to be used with the instrument.
  

• scheduled [= true | false] reports or sets whether or not the valve schedule is enabled for use.  The valve can always be operated by user commands at any time, provided adequate external power is available.

  • true: this is the factory default; the valve schedule is enabled for the current or next deployment

  • false: the valve schedule is not enabled.

Note:

The valve schedule operates only when the instrument is enabled for logging.  It will not operate before the logging start-time, after the logging end-time, or in any other situation where logging is disabled.  Simply setting scheduled = true will not immediately start the valve schedule if logging is not enabled.

• powerondelay reports (read-only) the startup time for the valve in milliseconds.  

• poweroffdelay reports (read-only) the shut down time for the valve in milliseconds.  

• interval [= <milliseconds>] reports or sets the interval between valve episodes in milliseconds, for a uniform schedule (see scheduletype below).

  • The minimum interval is 120000, or 2 minutes. 

  • For firmware versions prior to 1.142, the maximum interval is 3888000000, corresponding to 45 days.  For firmware versions 1.142 or later, the limit has been extended to the equivalent of 45000 days, which in practice is no limit at all.

  • Only values rounded to the minute are valid, so the number must be a multiple of 60000. 

  • The interval must be greater than the duration. 

  • The factory default value is 3600000ms, or 1 hour.

• duration [= <milliseconds>] reports or sets the duration of a valve episode in milliseconds.

  • The minimum duration is 60000 (1 minute).

  • The maximum duration is 86400000 milliseconds, which corresponds to 1 day.

  • The duration must be less than the interval period. 

  • Only values rounded to the minute are valid, so the number must be a multiple of 60000.

  • The factory default value is 60000ms, or 1 minute.

• command [= <command>] sends a particular command to the valve; in the case of a BPR|zero instrument, <command> can be one of the following options.  In all cases, the system may take up to 3000 milliseconds (nominally) to respond with the valve position or return an error message, in addition to the powerondelay and poweroffdelay times.

  • setpositionM, moves the valve to Position M (Marine).

  • setpositionA, moves the valve to Position A (Atmospheric).

  • getposition, reports the current position or status of the valve.  In the event of a fault, the status may indicate the error.
    - positionM
    - positionA
    - <specific_error_message>

Note:

Moving the valve, or activating it to request its position, requires a significant amount of power which can not be provided by the instrument's internal batteries.  Before these operations, the instrument checks that the external power is available and meets the minimum specified voltage threshold (approximately 9V).  If it does not, the response to these commands is an error message of the form valve status = powerfail.

When possible, the instrument remembers the valve position, and so getposition may respond with a valid position even when there is no power.  The reasoning is that if there is no power, the valve can not have moved since its position was last known.

• timetoepisode reports (read-only) the time remaining until the start of the next scheduled episode.  The value is reported in milliseconds, but only to a resolution of one second.  If the valve schedule is not enabled, the response is valve timetoepisode = n/a.  During an active schedule, the value reported can range from 1000 up to interval milliseconds.  If the schedule is enabled but logging has not yet started, the reported value will reflect the time until the start of the first episode, correctly accounting for the setting of the startimmediate parameter (see below).  This reported value may be longer than the interval, of course.

• startimmediate [= true | false] reports or sets the point in a uniform schedule (see scheduletype below) at which the first valve episode will occur:

  • true: this is the factory default; a valve episode will occur immediately at the start of the schedule, or following a reset.

  • false: the first valve  episode will be delayed by one interval after the start of the schedule or a reset. 

• operationcount reports (read-only) the number of valve movements that have been performed or attempted since the instrument was configured in the Factory.  This can be used to determine whether the valve is approaching its specified number of guaranteed operations.  To be conservative, attempted movements resulting in some form of error are also included in the count, as there is no way of telling whether these contribute more or less to general wear and tear than successful movements.

• episodelog [= on | off ] can be used to enable, disable, or report whether valve events will be recorded in the instrument's memory when data logging is enabled.  Events occurring outside the data logging deployment are never recorded.  When episodelog = on, an event will be recorded in memory during the deployment each time an attempt is made to change the state of the valve, whether successful or not.  This applies to both scheduled events and manually commanded events.  Each event contains information to show which position the valve was moved to, or whether some error occurred in the attempt.  The default setting of this parameter is episodelog = on, and it is recommended to keep this setting in normal circumstances so that a record of valve activity is preserved.  If desired, it can be turned off for testing or other purposes.

• scheduletype [= uniform | segmented ] is an option available in firmware versions 1.142 or later.  The default setting is uniform, in which the occurrence of episodes within the schedule is governed by the interval, duration, and startimmediate parameters discussed above (this also applies to all firmware versions prior to 1.142 that support the valve controller).  Alternatively, selecting segmented allows the schedule of valve episodes to be divided into a series of segments.  Each segment effectively has its own "start time", and an interval between episodes that can be specified independently of other segments.  Refer to the valvesegments and valvesegment commands for further details.  For a segmented schedule, the startimmediate and interval parameters discussed above do not apply; currently however, the duration parameter always applies to the entire schedule, whether segmented or uniform.

Examples

>> valve id
<< valve id = valveA

>> valve scheduled
<< valve scheduled = false
>> valve scheduled = true
<< valve scheduled = true

>> valve powerondelay, poweroffdelay
<< valve powerondelay = 1300, poweroffdelay = 50

>> valve command = getposition
<< valve status = positionM

>> valve command = setpositionA
<< valve status = positionA

>> valve command = getposition
<< valve  status = positionA

>> valve command = setpositionA
<< valve status = powerfail

There is not adequate external power available to move the valve.

>> valve interval, duration
<< valve interval = 3600000, duration = 300000

Errors

Error E0114 feature not supported by hardware 
An attempt was made to use the command with a logger that does not have the BPR|zero valve controller installed.

Error E0105 command prohibited while logging 
Some settings may not be modified while logging is in progress; reading them is permitted.

Error E0107 expected argument missing
The attempted operation requires an additional argument that was not specified with the command.

Error E0108 invalid argument to command 
The argument supplied is not recognized as a valid argument, or an attempt was made to set the value of a read-only parameter.

Error E0111 command failed
An unidentified problem prevented the operation from being completed.

Error E0702 no devices configured 
The configuration of the valve controller interface on this instrument is not correct.

Error E0703 device schedule inconsistent
The interval period is not greater than the duration.

Error E0704 device is not enabled
The attempted operation could not be performed because the device is disabled.

Error E0705 multiple operations not supported: '<extra_operation>'
Some valve operations can not be combined in a single command; try sending them separately.

Error E0701 device error: 
An internal error occurred. Please contact RBR Ltd for help.