calibration

Usage

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

Security

Unsafe and protected.

Description

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 (eg. 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: 

1. Some parameters are read only; n0… .

2. datetime = <YYYYMMDDhhmmss> must accompany any changes to coefficient values, so that the reported date and time reflects the most recent change.

3. a single calibration command can set coefficient values in only one of the groups at a time; c0…, x0…, Coefficients from different groups can not be mixed in a single command when setting.

Descriptions of the individual parameters are given below. 

1. datetime is reported and set using a <YYYYMMDDhhmmss> format. It is the date and time of the most recent calibration change for the channel, and is a required parameter when setting any of the calibration coefficients.

2. c0, c1… are the primary coefficient values, reported as floating point numbers using a format with a mantissa and exponent; for example 3.3910000e+003. When setting coefficients, any simple format compatible with floating point representation may be used; for example 11, 11.000 or 1.10e+1 would all be accepted.
   These coefficients apply to a 'core' equation which yields a basic value for the parameter. In many cases this is all that is needed, and the x and n groups are not required. The exact function of each coefficient depends on the equation used.

3. x0, x1… are required and reported for only some equation types, namely those which employ cross-channel compensation or correction of the primary value using one or more inputs from other channels in the logger. x0, x1… are also coefficient values which follow the same rules as the c group. The exact function of each coefficient depends on the equation used.

4. n0, n1… apply only to some equation types, those using cross-channel compensation or correction. They are only ever reported; they are set at the factory and can not be changed. They are not coefficients, but (in general) the indices of other logger channels whose data are also inputs to the equation for channel <index>. This permits output data to depend on more than one channel; for example, to be corrected for temperature dependencies. The values of n0, n1, etc. are simple integer numbers, remembering that the index of the first channel is 1; zero is not valid.

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. 

Examples

>> calibration 1
<< calibration 1 label = voltage_01, datetime = 20171218175005, c0 = 9.9876543e+000, c1 = 7.5642301e+000

>> calibration voltage_01
<< calibration voltage_01 index = 1, datetime = 20171218175005, c0 = 9.9876543e+000, c1 = 7.5642301e+000

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

>> calibration allindices
<< calibration 1 label = voltage_01, datetime = 20171203134201, c0 = 9.9873456e+000, c1 = 7.5640000e+000 || calibration 2 label = voltage_02, datetime = 20171203134201, c0 = 9.9873456e+000, c1 = 7.5640000e+000

>> calibration alllabels
<< calibration voltage_01 index = 1, datetime = 20171203134201, c0 = 9.9873456e+000, c1 = 7.5640000e+000 || calibration voltage_02 index = 2, datetime = 20171203134201, c0 = 9.9873456e+000, c1 = 7.5640000e+000

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

>> permit command = calibration
<< permit command = calibration
>> calibration 1 datetime = 20171203134201, c0 = 9.9873456, c1 = 7.564
<< calibration 1 datetime = 20171203134201, c0 = 9.9873456e+000, c1 = 7.5640000e+000

Setting the calibration for a channel.

Errors

Error E0103 protected command, use 'permit command = <command>' 
permit command = calibration must immediately precede the command if setting coefficients.

Error E0105 command prohibited while logging 
Coefficients may not be modified while logging is in progress.

Error E0107 expected argument missing 
An argument expected by the logger was not given with the command; for example, there must always be an <index> argument, and if setting coefficients then all fields required must be supplied.

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

The supplied argument was not valid; examples include:

• <index|label> out of range; channels are numbered from 1 to N; zero is not valid, or no channel exists with this label.

• improperly formatted or invalid <datetime> argument.

• invalid coefficient name.

• improperly specified value for a coefficient.

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

Error E0505 no channels configured 
Indicates a serious fault with the logger; please contact RBR Ltd for help.