L3 Command Reference

A potential command is considered to begin when its first character is received. For the serial port this is straightforward; for the USB it is hard or impossible for the CPU to 'see' how the messages are packaged, but the overall effect is similar. In both cases the potential command has been received once the logger sees a termination character; either one of <CR> (0x0D) or <LF> (0x0A). Combinations of the two characters are dealt with as follows:

In the first two cases, the second character is considered redundant and is discarded; only one Ready: prompt is sent. For the last two cases, the second character is treated as a second empty command, so it also provokes the logger’s prompt, and a total of two prompts are sent (see also the prompt command).

In general, the logger is not sensitive to the case of the input; for example, ID, Id, iD, and id are all acceptable forms for the id command. Any exceptions to this rule are highlighted when necessary. However, when handling logger responses, do not assume that the case of the output will match the case of the input: see also Parsing logger responses.

The received message may or may not form a valid command; errors detectable by the logger will vary from one command to another, but some of the common, general errors include:

See Error messages for a complete list.

All RBR instruments sleep as much as possible. Interaction requires that the instrument be woken up first, then a series of commands issued. After a 10-second idle timer elapses, the instrument will return to the low-power sleep mode.

The wakeup procedure is to send a single character; carriage return <CR> (0x0D) is the recommended choice. Over the USB link, the response is usually immediate. Over the Serial link, this first character may not be completely received by the instrument due to the non-zero wakeup time required, and it may be seen as a garbage character. However, the instrument itself ignores all garbage characters received immediately after wakeup, and so will not return any errors.

After the initial <CR> character, a 10ms pause should be used. Following this, the instrument is fully ready to receive any valid command.

In the RBR Ruskin software which is used by end-customers, the following is an example of the wakeup sequence used:

When the first character of a potential command is received, a 10-second timeout is started. This timeout serves two purposes: output blanking and power saving.

As soon as the logger knows it may be about to receive a command, any output which it could autonomously generate (such as streamed sample data) is suppressed. This is to avoid confusing the host, which has just sent a command and may be expecting a particular form of response. Until the logger has processed the command and sent the response, any other outputs will be suppressed. Output such as streamed data may appear in between received commands, but not while a command is being received or processed.

This 'output-blanking' state does not persist forever; if the 10-second timeout expires before a command terminator is seen, outputs such as streamed data are permitted again. This poses no problem for machine generated commands, but can be limiting for commands typed manually at a terminal.

The output blanking behaviour does not apply to the very first (potential) command received after the logger is woken from a quiescent state. For this command, outputs such as streamed data may continue to appear while the command is being received. This exception prevents, for example, random noise input from suppressing required data output. The logger will not invoke the output blanking behaviour until it has seen at least one valid command, at which point it can reasonably assume that a valid host is genuinely trying to communicate with it. Empty commands (isolated <CR> and/or <LF>) do not count as "valid commands" for this purpose.

The second purpose of the 10-second timeout is to minimize power consumption. If no valid, terminated command is received within the timeout, the communication returns to a quiescent state. This means that it discards any incomplete input, restarts the "valid command" timeout, and will start afresh with the next input character.

In the case of the serial port, it also allows the transmit hardware to be turned off to save power; indeed, if the logger has no other tasks to perform the entire instrument will enter a low power sleep mode.

The USB port is different in this respect, because the logger can draw enough power from the connection to run most of its basic functions. As long as the USB is connected the logger remains 'awake' and responsive to commands; no hardware is shut down. However, expiry of the 10-second timeout still resets the command processor’s behaviour with respect to its 'memory' of valid commands, incomplete input and output blanking.

The timeout referred to in the above sections has a default value of 10 seconds in all instruments. As noted, this is short enough to make manual typing of commands difficult in some cases. This timeout can be changed; refer to the description of the inputtimeout parameter for the settings command for more details.

If Ts is the number of milliseconds reported by the logger as the period (see sampling command), then the corresponding sampling rate Fs in Hz, is calculated as (using integer division):

If the logger needs to be deployed at 13Hz, and this sampling rate is available, then the period to be used would be 77 ms. If the logger is deployed with a period of 53 ms, the effective sampling rate is 19Hz.

If the instrument stops responding to any commands, first apply a full hardware reset (as described above).
Send the command id followed by the command disable, if the instrument is still not responding repeat the same procedure with a baudrate of 115200 bps (default baudrate if configured baudrate lost).

If the instrument is reporting a hardware failure error code as described in Error messages, one course of action is to apply a full hardware reset (as described in Power management and power cycling behaviour).

Most of the error codes reported (see EasyParse "calbin00" format) reflect a hardware failure of some sort except for Error-14 which could just reflect a value outside of an equation.
Sometimes, this error can be transient and resolves by itself.
However, if the instrument is always reporting the same error for some period of time, one possible course of action is to disable logging/scheduling, do not issue any fetch for 10 seconds, and enable again the unit.
If this does not resolve the issue, a full hardware reset (as described above), is advised. If one full hardware reset does not resolve the issue, it is unlikely that performing other full hardware reset will do.

In any case, only channels reported as Error should be discarded. A classical example is an instrument carrying cabled sensors. If a cable is damaged, the measurements associated with the sensor are likely to be reported as errors. Applying previous methods won’t help and measurements from other channels are still valid and useful.

>> pause

Open

This command is available in firmware versions 1.116 or later. It pauses an enabled deployment.

If successful, the command reports its status:

Error conditions that would prevent the successful execution of the command are:

When a pause is issued, the following will happen:

Deployment is now paused and no more samples will be taken once the current, if any, acquisition finishes.

Cannot pause deployment before deployment is enabled.

Assuming that either the wet switch or twist activation has been enabled the pause and resume feature cannot be used.

>> clock [ datetime | offsetfromutc ]

Unsafe.

Retrieve or set the logger’s current date and time:

>> deployment [ starttime | endtime | status ]

Unsafe.

Allows various parameters to be reported or set for the current deployment.

Most of these are self-explanatory. In the very unlikely event that they occur at all, the states failed, notblank and unknown arise from serious internal errors, and ideally the instrument should be returned to RBR Ltd for further analysis. However, if it would be preferable to attempt deployment anyway, try these recovery procedures.

If the failed status resulted from an attempt to enable the logger, then either it failed to store a deployment header in memory, or the alarm time for the next sample could not be correctly loaded into the Real Time Clock/Calendar. If the logger does have a fault, the second case could happen again at any time during a deployment, so there is a risk that the logger may fail again and the deployment will terminate early.

In any event, the instrument should be returned to RBR Ltd for further analysis at the earliest available opportunity, with as much detail as possible about the circumstances of the failure.

>> resume

Open

This command is available in firmware versions 1.116 or later. It resumes an enabled deployment which was previously paused using the pause command.

If successful, the command reports its status:

Error conditions that would prevent the successful execution of the command are:

When a resume is issued, the following will happen:

Deployment has resumed running as scheduled.

Deployment has resumed running as scheduled.

>> pauseresume

Open

This command is available in firmware versions 1.116 or later. It allows the host to determine if the pause/resume feature is available on the instrument. It allows an elevated host to allow and deny the feature for the instrument.

If successful, the command reports its state:

Error conditions that would prevent the successful execution of the command are:

The feature is not allowed on this instrument.

The instrument firmware is older and does not recognize this feature.

Either the deployment has not been enabled or the sampling mode is 'regimes'.

The deployment has been enabled and is not paused.

The deployment has been enabled and is paused.

>> sampling [ mode | period | availablefastperiods | userperiodlimit | burstinterval | burstlength | gate ]

Unsafe.

Allows various parameters to be reported or set for the next deployment. The <parameter>s currently supported are:

For further information about gated sampling, see the section Gated Sampling.

The logger has been programmed for continuous 8Hz sampling. It supports 2Hz, 4Hz, 8Hz, and 16Hz operation. The programmed values of the burst parameters are reported but do not apply to continuous sampling. No gating condition is in force.

Averaging enabled without changing the other parameters; the logger is now programmed to take a burst of 60 measurements at 8Hz every five minutes, and store the average of the 60 measurements.

The mode is changed to burst recording and the burst interval to ten minutes; the logger is now programmed to take a burst of 60 measurements at 8Hz every ten minutes, storing all measurements in memory.

The logger has been programmed for continuous 4Hz sampling. This logger does not support any of the other modes, so the parameters are not reported.

The first example shows support for sampling at 2Hz, 4Hz, 8Hz and 16Hz in at least one of the available modes; the second example shows that no sampling faster than 1Hz is supported.

>> thresholding [ enabled | state | channelindex | channellabel | condition | value | interval ]

Unsafe.

Reports or sets the parameters which control threshold gated sampling. The <parameter>s currently supported are:

The basic validity checks on parameters indicated above are performed immediately. Further checks may result in error messages at the time the logger is enabled; for example, setting a threshold check interval shorter than the logger can achieve in its programmed operating mode is not permitted.

Threshold gating is not enabled; if it were, the logger would check the value read from Channel 1 every 15 seconds, and start normal sampling if above 20.0.

The gating parameters are changed so that the logger would check Channel 1 every 10 seconds, and start normal sampling if the value were above 17.5.

Threshold gated control of sampling is enabled.

>> twistactivation [ enabled | state ]

Unsafe.

Reports or sets the parameters which control twist-activation-gated sampling. The <parameter>s currently supported are:

The basic validity checks on parameters indicated above are performed immediately. Further checks may result in error messages at the time the logger is enabled; for example, thresholding and twist activation gating features may not be enabled simultaneously.

Twist-activation-gated logging is not enabled. If it were, the logger would sample data depending on the position of the end cap.

Twist-activation-gated control of sampling is enabled, and logging is paused pending twist activation.

>> regimes [ direction | count | reference ]

Unsafe.

Sets and returns information about the regimes. These are only used if the regimes mode is in use (see sampling). This is intended for use when the instrument is integrated into moving platforms.

Note: the boundary values specified for each individual regime are the first boundary in the regime; so if the instrument is ascending, the boundary specified is the lower boundary; and vice-versa.

There are three specified regimes with the individual boundary values being interpreted as the lower values as the instrument ascends through the water column.

>> regime <index> [ boundary | binsize | samplingperiod ]

Unsafe.

Returns information about the specified <index> regime. The first regime has an <index> of 1. <index> should be lower or equal to the number or regimes reported by the regimes command at the time of issuing the command. If direction (regimes command) is set to descending, the first regime corresponds to the regime the closest to the surface. If direction is set to ascending, the first regime is the closest to the seabed. Depending on how is set reference (regimes command), the logger use the absolute pressure or the sea pressure to determine the current regime and the current bin.

The following parameters give the basic information available for all regimes.

When the vehicle is not in a defined regime, the logger will sample internally at the same rate as the first regime in order to check when it has entered this regime. Measurements acquired during this period will not be stored or streamed.

The average for each bin is stored as soon as the vehicle enters the next bin in the direction set by the regimes command. In the following figure the regime 2 bin 1 is stored as soon as the vehicle enters the regime 2 bin 2. When the vehicle goes back into the defined regime 2 bin 1 range, the measurements acquired are then discarded but all the measurements acquired in the regime 2 bin 2 range are taken into consideration as long as the vehicle has not entered yet the regime 2 bin 3.

The bin average is calculated without any kind of interpolation. In the case of a binsize set to 0.0, there is no averaging whatsoever.

Assuming the instrument is ascending, this indicates that the regime should commence as the sensor passes upwards through 2000dbar, and that bins inside the regime should be 100dbar in size. For each bin, an average of all samples will be made, with the sampling period of the instrument set to 1000ms. This regime will continue until another comes into force.

This sets the third regime to commence at 1000dbar, with a bin size of 5.1dbar and a sampling rate of 2Hz (500ms). As there are no other regimes defined, this one has no second boundary, so the instrument would continue measuring indefinitely and will only stop when the endtime is reached, or the stop command is issued.

Assuming the instrument is ascending, this indicates that the regime should commence as the sensor passes upwards through 20 dbar, and that during this regime, every measurements will be recorded (sampled at 6Hz). As there are no other regimes defined, this one has no second boundary, so the instrument would continue measuring indefinitely and will only stop when the endtime is reached, or the stop command is issued.

>> ddsampling [ direction | fastperiod | slowperiod | fastthreshold | slowthreshold ]

Unsafe.

Sets and returns information about the directional dependent sampling mode. These settings apply only if the ddsampling mode is in active use (see sampling). This mode is intended for use when the instrument is integrated into a moving platform.

The following picture gives a global overview of how the logger would behave with the previous example on a 20 dbar profile setup after it has been started.

The next picture shows how the directional dependent sampling would behave in the case of a profile much shorter than the previous one. In such a case the logger would detect an upcast while slow sampling and would then go back to the fast sampling mode.

>> verify [ erasememory = true ]

Open.

This command performs all the same deployment consistency checks which the enable command performs. It then reports the same response which the enable command would produce, whether this is an updated logger status, a warning or an error message. It does not, however, actually enable the logger for sampling.

In other words, it performs a "dry run" of the enable command to allow the programmed schedule parameters to be verified.

As with the enable command, it takes the option:

As with the enable command, it reports two parameters:

The programmed schedule is valid and the logger would, if enabled, begin collecting data at the start time.

The programmed schedule is valid and the logger would, if enabled, begin collecting data at the next scheduled sample time.

Memory is not cleared, logging would not be enabled. Except in the case of the erasememory = true option.

>> enable [ erasememory ]

Open.

Enables a logger to sample according to the programmed schedule.
An option is available to erase the memory and enable the logger with a single command, otherwise the memclear command must be used to erase the memory beforehand if necessary.

Although the enable command is always available, a number of checks are made before logging is actually enabled. If any check fails, the logger is not enabled and an error message is sent as described below. The most severe error found causes immediate failure of the command; a single attempt to enable the logger will not detect multiple errors. If all required conditions are satisfied, an internal error may still prevent sampling from being enabled when the logger attempts it. This also will provoke an error message.

If successful, the command reports two parameters:

The programmed schedule is valid and the logger will begin collecting data at the start time.

The programmed schedule is valid and the logger will begin collecting data at the next scheduled sample time.

The programmed schedule is valid and the logger will begin collecting data at the start time; however, the memory may fill before the end time.

>> disable

Open.

If the instrument is logging, this command will terminate the current deployment. If the instrument was not logging when the command is issued, its status does not change.
This command reports:

If the disable command is sent while a measurement is in progress, the measurement will be completed before logging is stopped. Consequently, depending on the channels installed in the logger and the sampling mode, the logger’s response to the command may be delayed. If the logger is sampling in any averaging or burst recording mode, the burst currently in progress will be interrupted and abandoned.

If the logger is recording data to memory, a 'stop event' will be appended to the data after the last sample stored.

The instrument was logging, and has now been stopped.

The instrument had previously been stopped and its data memory erased; its status has not changed.

>> simulation [state | period ]

Unsafe and protected.

This command controls whether the simulation mode is used, and if so how it will operate. It is an Unsafe command, meaning that parameters cannot be modified while the instrument is enabled for logging. Modification of parameters is also Protected, meaning that the command must be immediately preceded by a permit command if parameters are to be changed.

The command’s parameters are:

When state = on, the measured values from the selected channels are replaced by artificially generated values. These values follow an approximately linear ramp which travels up and down between predefined limits, taking period = <milliseconds> to complete one full cycle. All simulated channels cycle at the same rate. The channel types supported and the limits which apply are listed below.

^*If a pressure channel’s calibration coefficients indicate that 2000dbar is beyond the measurement range, a limit corresponding to the sensor’s maximum output will be used instead.

The simulated values are used both for scheduled samples (whether stored in memory, streamed, or both) and for on-demand samples obtained using the fetch command. Both types of sample should confirm closely to the same linear ramp; if scheduled and on-demand samples are required simultaneously, there may be some small deviations due to the computation’s attempts to satisfy both.

A logger programmed to generate simulated data can be identified in one of two ways: request the setting of the simulation state, or check the response to the id command for the indicator as shown below.

>> meminfo [ dataset | used | remaining | capacity | size ]

Open.

Reports information about the usage and characteristics of the data memory.

The dataset argument is present to support the EasyParse data storage format, which assigns different types of deployment data to different datasets as follows:

In Standard data storage format, everything is in dataset 1. For a full discussion of data storage formats, refer to the section Format of Stored Data.

If the dataset argument is omitted then dataset 1 is assumed, and no <dataset> value is reported in the command’s response, either: it is assumed that dataset 1 is implicitly understood.

In Standard format, only one dataset is used, and so the remaining parameters have physical interpretations which are not too hard to understand. The size parameter is a fixed number for a given flash memory device. Because of the way these devices store data, it is sometimes not possible to use the entire device in order to reliably store small amounts of information. In such cases small areas of the device are not used to store data, but are no longer available for storage, either. Over the course of a deployment these uncommitted areas can accumulate, so (used + remaining) < size. However, (used + remaining) = capacity should always be true.

In EasyParse format, the relationship between the parameter values and the characteristics of the physical storage device become more complicated. For the curious, this is discussed in detail in the "Technical note" below, but this should not be considered required reading. Although the numbers will not be completely accurate, a reasonable guide to the state of the memory can be obtained by looking at the values for dataset 1 alone, since it contains the sample data, and there will typically be far more sample data than anything else.

>> memclear

Unsafe and protected.

Clears the data storage area of the flash memory. Currently, all datasets are erased, regardless of the data storage format in use.

The logger responds by reporting that the memory used is zero if successful, as shown in the Example below; an error message is sent if the operation fails.

>> memformat [ type | newtype | availabletypes ]

Unsafe.

This command reports or sets the format used to store deployment data in memory. The available parameters and their usage are described below.

If no argument is given to the command, all arguments are reported. Currently supported types are as follows:

For a full discussion of the data storage formats available, refer to the section Format of Stored Data.

>> readdata [ dataset | size | offset ]

Open.

This command allows you to read data from the datasets.

The command replies as any other command by confirming the key values pairs dataset, size and offset effectively reported followed by a <CR><LF>. Then send a binary stream composed of:

No acknowledge mechanism is implemented; failed transfers can simply be requested again.

For the Standard data storage format, the dataset number is always 1; all deployment information is stored in a single dataset.

For the EasyParse format, the three major components of deployment data are each assigned a dataset as follows:

The readdata command knows nothing of the structure of the retrieved data in any of these cases, it is simply transferring a block of bytes of unknown content.
Internally, requests for very large amounts of data in a single instance of the readdata command are broken down into smaller blocks. Such a transfer could take a considerable time, and if necessary it may be aborted by sending the pseudo-command abort, followed by a <cr> character. The transfer then stops at the next internal block boundary, and terminates with the message operation aborted.

>> postprocessing [ channels | mode | status | command | dc_alpha | dc_tau | dc_tdelay | dc_ctcoeff ]

None.

The postprocessing feature enables the logger to perform various post-processing operations on data measured and stored by the logger. It operates on data stored in EasyParse format in dataset-1 and writes EasyParse format into dataset-4 based on the channels and parameters requested. The postprocessing can occur as soon as there is an EasyParse dataset available (even if logging is in progress). If the instrument is powered cycle while performing the postprocessing, it will continue the postprocessing after power cycling.

A maximum of 24 channels is supported. The generated dataset-4 channels order will follow the same order as <listofchannelsstats>.

The command reset will not discard the dataset. However, if the memory is cleared (either via memclear or via enable erasememory = true), dataset-4 will be discarded once the memory is erased: the dataset is always associated with the relevant dataset-1. Changing postprocessing parameters is not allowed while status is processing or finished. In order to change any parameters, a reset needs to be issued to go back to the disabled status.

>> postprocessing_regimes [ direction | count | reference ]

None.

Sets and returns regimes parameters for use with postprocessing command. These are only used if the regimes postprocessing mode is in use. This is intended for use when the instrument is integrated into moving platforms.

Changing postprocessing_regimes parameters is not allowed while postprocessing status is processing or finished.

>> postprocessing_regime <index> [ boundary | binsize ]

None.

Returns information about the specified <index> regime for postprocessing. The first regime has an <index> of 1. <index> should be lower or equal to the number of regimes reported by the postprocessing_regimes command at the time of issuing the command. If the direction (postprocessing_regimes command) is set to descending, the first regime corresponds to the regime the closest to the surface. If the direction is set to ascending, the first regime is the closest to the seabed. Depending on how is set the reference (postprocessing_regimes command), the logger use the absolute pressure or the sea pressure to determine the current regime and the current bin.

Changing postprocessing_regime parameters is not allowed while postprocessing status is processing or finished.

The following parameters give the basic information available for all regimes.

>> channels [ count | on | settlingtime | readtime | minperiod ]

Open.

A read-only command which returns general channel information for the logger.

>> channel <indexorlabel> [ type | module | status | settlingtime | readtime | equation | userunits | gain | availablegains | derived | label | index ]

Unsafe.

Returns information about the channel at the specified <indexorlabel>. Channels can be identified either by an index (an integer) or by their label (a meaningful string, for example temperature_00 or conductivity_00). The first channel has an index of 1.

A special value of allindices or alllabels may be given for <indexorlabel> causing the requested parameters to be reported for all channels. The output for each channel is terminated by ||, except for the last channel which is terminated by a <cr><lf> pair as normal.

The following parameters give the basic information available for all channels. None of these values may be modified by end users. All parameters might be obtained using the all in lieu of parameter names.

For storage of data in standard format (rawbin00):

For storage of data in EasyParse format (calbin00):

>> settings [ fetchpoweroffdelay | sensorpoweralwayson | castdetection | inputtimeout | speccondtempco | altitude | temperature | pressure | atmosphere | density | salinity | avgsoundspeed ]

Unsafe.

Reports or sets the values of miscellaneous settings in the logger as described below.

>> calibration <indexorlabel> [ datetime | c0 | …​ | cn | x0 | …​ | xn | n0 | …​ | xn ]

Unsafe and protected.

Reports or sets information regarding the most recent calibration for the channel specified by <indexorlabel>, which is a required parameter in all cases (see channel). The number and types of coefficients reported, or required when setting, will vary depending on the channel type (see channel).

A special value of allindices or alllabels may be given for <indexorlabel> causing the requested parameters to be reported for all channels. The output for each channel is terminated by ||, except for the last channel which is terminated by a <cr><lf> pair as normal.

Some sensor types have complicated equations with many coefficients, and the equation may also use the output of one or more of the other channels in the logger for correction or compensation purposes. This is a powerful facility, but requires a lot of information; the calibration command helps to manage that information.

Coefficients are arranged in three groups, c0…, x0…, and there is a further group n0… of cross-channel reference indices. The purpose and function of each group will be described below. The groups may also be referred to by name; c, x or n.
All parameters might be obtained using the all keyword in lieu of parameter names. Parameters may also be requested individually, or in any combination, by name. Coefficients in each group may be requested all together by using one of the group names, c, x or n. Requesting an item which does not exist (e.g., c3 for a linear sensor) may result in either an error message, or a response such as c3 = n/a.

When setting parameters, there are further restrictions which must be followed:

Descriptions of the individual parameters are given below.

Equations which use the x0, x1… coefficients will require at least one 'n' index. The logger may also have 'derived parameter' channels, which have no measurement channel of their own, but an output value which is computed from other measured channels: a good example would be salinity, which is a function of conductivity, temperature and pressure. In such cases n0, n1, n2 are required to tell the logger which input channels to use.

There is one special case when the value of an 'n' index may be the text field "value". This can be set only at the factory, and applies when an equation requires a correction term using a parameter which the logger does not measure. In this case the default parameter set by the command settings will be used.

Please refer to the section Calibration Equations and Cross-channel Dependencies for a complete list of the equations which the logger uses, and for further discussion of cross channel dependencies.

Querying the calibration for a single channel by index and by label.

Querying the calibration for all channels by indices and by labels.

Setting the calibration for a channel.

Error E0501 item is not configured
There is a problem with the configuration of the specified channel; please contact RBR Ltd for help.

>> sensor <indexorlabel> [ param1 | …​ | paramn]

Unsafe.

Returns information about the sensor attached to the channel at the specified <indexorlabel> (see channel)

A special value of allindices or alllabels may be given for <indexorlabel> causing the requested parameters to be reported for all channels. The output for each channel is terminated by ||, except for the last channel which is terminated by a <cr><lf> pair as normal.
All parameters might be obtained using the all keyword in lieu of parameter names but this one is optional.

The purpose of this command is to manage miscellaneous information relating to the sensor associated with a given logger channel, as opposed to any property of the channel itself; the distinction is rather fine. In general the sensor command is used for information which belongs with a particular sensor, but which the logger does not need to know; a good example would be the sensor’s serial number. For information common to all sensors of this type which the logger does need to know, the channel command is used; a good example would be the settlingtime, or power-on settling delay.

In principle any channel type could make use of the sensor command; in practice the channels which use it and the parameters which are supported are defined by the instrument’s Factory configuration. End users may change the values of existing parameters, but they cannot add new parameters or add the capability to channels which do not already have it. Attempting to use the sensor command with a channel not configured to support it will provoke an error message, as detailed below.

Retrieve all information pertaining to channel 3. In this example, only the "serial" parameter is available.

Request a specific parameter.

Change the value of a parameter.

No sensor information is available for channel 4.

The "serial" parameter is unavailable for channel 4.

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

Unsafe.

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.

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

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

>> valvesegments [ count ]

Unsafe.

This is a specialized command available in firmware versions 1.142 or later. It is used in BPR|zero logger systems to help implement a more flexible schedule of valve episodes than was previously available.

If desired, the schedule of valve episodes can now 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. This command sets or reports the number of segments that will be used during the schedule.

Refer to the valvesegment command for information on accessing the parameters for each segment.

>> valvesegment <segment_number> [ delay | interval ]

Unsafe.

This is a specialized command available in firmware versions 1.142 or later. It is used in BPR|zero logger systems to help implement a more flexible schedule of valve episodes than was previously available.

If desired, the schedule of valve episodes can now be divided into a series of segments. Each segment effectively has its own "start time", specified by the delay, and an interval between episodes that can be specified independently of other segments. This command sets or reports the parameters associated with the requested segment <segment_number>.

Segment parameters can be read and modified while the scheduletype is uniform, and values will be retained even if a uniform schedule is in use; however, segment parameter settings will not become effective until the scheduletype is changed to segmented.

When querying or specifying segment parameters, the <segment_number> (or all) is always required and must be specified first. When setting values, the logger will do some basic error checking, but it is the user’s responsibility to ensure that all three time parameters (delay, interval, and universal duration) are consistent with a valid schedule. It is not possible to update parameters for multiple segments at once; each segment must be updated separately. The logger will perform a final check on the consistency of all parameter values before the instrument is enabled.

All time parameters are in milliseconds, to be consistent with other time parameters for the valve command and many other logger commands. All values can be specified to a resolution of 1 minute (60000ms). The minimum delay for Segment 1 is zero; for other segments the minimum value is 60000 (1 minute). The minimum interval is 120000 (2 minutes), since the interval must be greater than the duration, and the minimum for the universal duration is one minute. The maximum value for both <delay_ms> and <interval_ms> is the equivalent of 45000 days, which in practice is no restriction at all. The maximum duration is 86400000, corresponding to 1 day.

As the deployment progresses, the instrument evaluates which segment is applicable at the start of each valve episode, and not continuously between or during episodes. Thus specifying a delay which expires between intervals would mean that the <new_interval> value does not take effect immediately, but at the start of the next episode scheduled according to the <current_interval>.

The diagram below should help to clarify the relationships between the parameters for different segments.

>> uvled

[ id | scheduled | powerondelay | poweroffdelay | interval | duration | command | timetoepisode | startimmediate | operatingtime | episodelog ]

Unsafe.

This is a specialized command available in firmware versions 1.130 or later. It is used to return information about, and to allow some control over, the UV-LED antifouling device used in the RBRconcerto³ CTD|UV data logger, and other instruments equipped with the UV antifouling feature. If the command is sent to an instrument that does not have the UV antifouling feature, the instrument will respond with an error message:

There is no power source available to activate the UV-LEDs; USB alone cannot be used.

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

>> link [ type ]

Open.

Returns the name of the communications link over which the command was received, allowing the host to determine

whether a genuine serial link is in use, or the CDC serial profile of a USB connection, or Wi-Fi connection.

It reports a single parameter:

None.

>> serial [ baudrate | mode | availablemodes | availablebaudrates]

Open.

This command can be used to either report or set the parameters which apply to the serial link. The command can be issued over either the USB or serial links, but care must obviously be taken if the serial link is used to change its own operating parameters. In this case, new settings are acknowledged while the old parameters are still in force, then the changes are applied. The next command sent must use the new configuration of the link if the logger is to recognize it. The individual parameters are described below.

>> sleep [ confirmation = true | false ]

Open.

Immediately shuts down communications and implements any power saving measures which are possible, over-riding the 10-second timeout which normally invokes these actions (see Section Timeouts, output blanking and power saving). Power saving measures typically include:

Any scheduled sampling activity is not affected. The sleep command does not attempt to power down a USB link, because there is always enough power available via USB to run the logger’s basic functions; sensor channels used for a fetch command will still be shut down.

If used without any parameters, the command generates no error messages, and always succeeds silently; there is no prompt or confirmation message.

Firmware versions 1.116 or later support an optional confirmation parameter. If this is used with a value of true, a confirmation message is generated, but no prompt.

>> wifi [ enabled | state| timeout | commandtimeout | baudrate ]

Unsafe.

This command allows the user to retrieve information about the Wi-Fi link, and to control some aspects of its behaviour. Please note that some instruments may not have a Wi-Fi link available.

The parameters currently supported are:

>> id [ model | version | serial | fwtype ]

Open.

This is a read-only command which report basic information about the instrument:

Refer to the command simulation for more details.

None.

>> help [<command-name>]

Open.

The help command, without arguments, generates a list of all known commands along with possible parameters and a short description of functionality. If a single valid command name is passed to the help command, only the description for that command is returned.

>> hwrev [ pcb | cpu | bsl ]

Open.

Reports various pieces of information about the revision status of the logger’s main circuit card. Not usually of interest except for diagnostic purposes, or to determine whether hardware-dependent features may or may not be available in advance of trying to use them.

The parameters reported are:

None.

>> power [ source | int | ext | reg ]

Open.

Support for short instruments starts with firmware version 1.080; earlier firmware versions do not report the reg parameter. A short instrument is one which takes only four AA cells instead of the standard eight. In a short instrument, a direct measurement of the internal battery cannot be made, and the output of an internal voltage regulator is reported instead. Standard instruments do not have an equivalent regulator, but can monitor the battery voltage directly.

>> powerinternal [ batterytype | capacity | used ]

Open.

Allows various parameters to be reported or set for the current deployment.

Error E0108 invalid argument to command: '<invalid-argument>'

>> powerexternal [batterytype | capacity | used ]

Open.

Allows various parameters to be reported or set for the current deployment.

Error E0108 invalid argument to command: '<invalid-argument>'

>> info [ pn ]

Open.

This is a read-only command which reports more information about the logger. Currently it reports:

The fwlock parameter is set at the factory, and for most instruments it is off, which means that the standard method of updating instrument firmware using the Ruskin software can be used. For some OEM applications requiring that the version of firmware does not change, the fwlock is set to on, which prevents firmware updates by the standard method.

If necessary, a special procedure can be used to override this 'locked' state; please contact RBR Ltd if you believe you need to do this.

For firmware versions 1.094 or higher.

None.

>> getall

Open.

None.

>> fetch [ channels | sleepafter ]

Open.

Requests an 'on-demand' sample set from the logger. If a recent scheduled sample set is available, those values may be returned to satisfy the fetch request. 'Recent' in this context currently means less than 500ms old. Otherwise, a sample set is explicitly acquired for the benefit of the fetch. A sample set acquired only for fetch is never stored in memory.

The logger simply responds with the <sample-data>; depending on the configured settling time (or power-on settling delay) for the attached sensors, there may be a noticeable delay before the <sample-data> appears. Refer to the channels command for further discussion of settling time.

Fetch a sample from all channels.

Fetch a sample from some specific channels.

Fetch command reporting error for channel 1 (timeout) and channel 3 (unable to compute value). Channel 2 is not calibrated. List of error code can be found in within Sample data standard format.

>> permit [ command ]

Open. Permitted commands may have further restraints (i.e., may be unsafe).

Permits a protected command to be executed immediately after this one; receipt of anything else removes the permission again. Any other constraints on executing a particular command will still apply. It is not an error to 'permit' a command which does not need it, merely unnecessary.

It takes as a mandatory parameter:

Successfully clears the data memory.

Fails because memclear is a protected command.

Fails because permit must immediately precede the protected command.

>> prompt [ state ]

Open.

Returns the state of the "Ready: " prompt, which is normally sent by the logger in response to almost any command after any other output generated by the command is complete.

A change of the on/off state takes place immediately, so for example there will be no prompt following the command which turns it off. Turning the prompt off is not normally recommended, unless there is a very good reason for doing so.

For example, if it is interfering with the parsing of responses by an automated system, it may be necessary to suppress it.

>> confirmation [ state ]

Open.

Returns the state of the logger’s confirmation responses, normally sent after a parameter has been modified if the state is on. If the state is off, successful parameter modifications occur without confirmation messages.

A change of the on/off state takes place immediately, so for example there will be no confirmation of the command which turns it off.

There are several situations in which the suppression does not occur even if the state is off, here are some points to note:

Turning confirmation off is not normally recommended, unless there is a very good reason for doing so.

Confirmation of a parameter change is immediately suppressed.

All commands are with confirmation state = off. A request for information always provokes a response.

A failed attempt to set a parameter still provokes a response.

Response suppressed if parameter is successfully changed.

>> reboot [ <milliseconds-delay> ]

Protected.

This command executes a logger CPU reset. The reset will apply only to the CPU itself and any hardware directly under its control; there is no guarantee that every component in the logger system will be reset in the same way that cycling power to the logger would achieve.

The optional delay argument in milliseconds is useful when using the command over a USB-CDC communication link. When the logger CPU resets, any USB-CDC link between it and the host will be torn down and then re-established, meaning that the virtual serial port associated with the CDC profile temporarily disappears for a brief time. Most communications software is unable to cope with such an event, so providing some time to disconnect the software from the logger before the port disappears allows the operation to be performed gracefully.

This does not apply to a true Serial link, so there are no side effects if the logger is reset without specifying a delay. The link command can be used to verify the type of communications link if there is any doubt.

Except in the case of the error message reported if the permit mechanism is not used, there is no response to the command: once the reset occurs the logger no longer has any memory of receiving the command, so it cannotrespond.

Successfully resets the logger CPU.

Fails because reboot is a protected command.

Successfully resets the logger CPU after a delay of five seconds.

>> streamserial [state | aux1_state | aux1_setup | aux1_hold | aux1_active | aux1_sleep | aux1_all ]

Open.

If the logger is configured to support streamed data over the serial link, this command can turn the feature on or off, and also configure the behaviour of an auxiliary RS-232 control output, AUX1. If the command is given with no parameters, the value of the state parameter is reported. The operating parameters of the serial link, such as baud rate and mode, are accessed using the serial command. This commands reports the state of the streamed data feature, and optionally turns it on or off. When the feature is on, acquired data is sent over the serial link at the same time it is stored in memory. Refer to the outputformat command for descriptions of the data formats which may be available. When the feature is off, data is not sent. Changing the state of serial streaming while logging is in progress is permitted, but will cause a time-stamped event to be recorded in memory with the sample data.

The signal can be used to control an external device such as a modem, but is intended only for the purpose of transmitting streamed data. The logger may activate the signal during other transmissions on the serial link, but it is intended only for enabling a transmitting device for remote monitoring of send-data-only installations. It is not intended to be, and should not be used as, a general purpose flow control signal. Below are the descriptions of the individual command parameters.

>> outputformat [ type | availabletypes | channelslist | labelslist ]

Unsafe.

Reports or sets the format used to transmit data over the communications link; this format applies to both 'Fetched' data, and live 'Streamed' data if available. If no arguments are given, the current setting of the type parameter is reported.

The parameters currently supported are:

Note that for all the caltext formats, any individual channel value may be replaced by one of the following:

>> streamusb [ state ]

Open.

This command can turn on or off the USB streaming. When USB streaming is on, acquired data is sent over the USB link at the same time it is stored in memory. Refer to the outputformat command for descriptions of the data formats which may be available.

Changing the state of USB streaming while logging is in progress is permitted, but will cause a time-stamped event to be recorded in memory with the sample data.

This command takes a single parameter: