Version 2.004

Introduction

More recent header versions are always backward compatible with previous versions, in the sense that while new material may be added, existing content and the layout of existing content is not changed.   The following table lists all versions of the header, the version of firmware in which it was first introduced, and a brief description of the change.

Notes

1. Prior to Version 1.130, only specific versions of the firmware include support for the BPR|zero product; there will be some versions of firmware that do not include a Section 6 at all, so do not assume that it will be present but empty.

Overview

The header is composed of a series of sections followed by a global CRC. Each section describes some aspect of the instrument configuration or deployment settings.  Sections should be in ascending order by Section Id value. The 'metadata' section describes the data format itself. 

Each section is organized as:

Metadata section content (Section Id 0x01)

Version (4 bytes)
For example, 2002; this is the version of the header format

Total header length (2 bytes)
This length includes all the sections of the header and the CRC at the end. 

Logger section content (Section Id 0x02)

Firmware type
The firmware type code as an 32b integer; see the fwtype parameter under the id command.

Firmware version
Given as an integer; for example version 1.570 would be given as 1570. 

Logger Serial Number
As reported by the id command.

Logger model (16 bytes)
NUL terminated string reflecting the model name. Padded with 0xFF bytes.

Logger P/N length (2 bytes)

Size in bytes of the logger P/N string (including the NUL character).

Logger P/N string (Logger P/N length bytes)

NUL terminated string reflecting the P/N.

Power supply P/N length (2 bytes)
Size in bytes of the power supply P/N string (including the NUL character).

Power supply P/N string (Power supply P/N length bytes)
NUL terminated string reflecting the power supply P/N.

Reserved (8 bytes)

Deployment section content (Section Id 0x03)

Dataset format
0x00000000 rawbin00
0x00000001 calbin00

Logger date/time
This is the date and time at which the enable command was successfully executed by the logger and the Header stored in memory. The value is the number of seconds elapsed since 2000-Jan-01 00:00:00, (946684800 Unix timestamp).

Schedule start time
Programmed by the deployment  starttime command. The value is the number of seconds elapsed since 2000-Jan-01 00:00:00, (946684800 Unix timestamp).

Schedule end time
Programmed by the  deployment  endtime command. The value is the number of seconds elapsed since 2000-Jan-01 00:00:00, (946684800 Unix timestamp).

Measurement interval 
Programmed by the  sampling period command. The value is given in milliseconds.

Logger status 
This is the logger's status when it was successfully enabled, and so can have only a small number of values: 1 = pending, 2 = logging, or 4 = gated. See also the  deployment  status command.

Feature flags
This is a bitmask of user selectable features which were active at the time the logger was enabled.
0x00000001  1 = logger prompt turned on.
0x00000002  1 = logger confirmations turned on.
0x00000004  1 = stream sample data to USB port.
0x00000008  1 = stream sample data to serial port.
0x00000010  1 = store average of burst.
0x00000020  1 = store all measurements in burst.
0x00000040  1 = store tidal average of burst.
0x00000080  1 = store wave burst.
0x00000100  1 = fast (>1Hz) continuous sampling.
0x00000200  Reserved
0x00000400  1 = firmware updates are locked
0x00000800  Reserved
0x00001000  1 = valve schedule started with no delay (if supported by firmware)
0x00002000  1 = valve schedule enabled (if supported by firmware)
0x00004000  1 = sampling was gated by thresholding feature.
0x00008000  1 = logger keeps all sensor channels powered up between samples.
0x00010000  1 = sampling was gated by the twist activation feature.
0x00020000  1 = the regimes sampling mode was enabled.
0x00040000  1 = cast detection for profiling deployments was enabled.
0x00080000  1 = the serial port auxiliary control feature was enabled.
0x00100000  1 = logger was enabled in simulated data mode.
0x00200000  1 = the directional dependent sampling mode was enabled.
0x00400000  1 = the WiFi link was enabled.

Burst/average interval 
Measured in milliseconds, this is the time between recorded bursts.

Burst/average length 
A count of the number of measurements in a recorded burst.

Thresholding channel index
The channel monitored for threshold-gated sampling, if enabled (see Feature flags above). 

Thresholding condition 
The condition which must be satisfied for the logger to record data if threshold-gated sampling was enabled (see the Feature flags above). A value of 0 is used when the reading must be below the threshold for sampling to occur, a value of 1 is used if the reading must be above the threshold.

Thresholding value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer. It is the threshold value in calibrated units, used for comparison with values from the monitored channel, if threshold-gated sampling was enabled (see the Feature flags above).

Thresholding interval
This is the interval in milliseconds between threshold checks when the logger is in the gated state, waiting for a threshold trigger.

Regimes settings
bit 7 : 0 = ascending, 1 = descending
bit 6 : 0 = absolute pressure reference, 1 = sea pressure reference
bits 0..5 : number of regimes (between 1 and 3)

Regime 1 boundary (2 bytes)
The boundary is in dbar.

Regime 1 binsize (2 bytes)
The binsize is in dbar.

Regime 1 period
The sampling period during this regime in milliseconds

Regime 2 boundary (2 bytes)
The boundary is in dbar.

Regime 2 binsize (2 bytes)
The binsize is in dbar.

Regime 2 period
The sampling period during this regime in milliseconds

Regime 3 boundary (2 bytes)
The boundary is in dbar.

Regime 3 binsize (2 bytes)
The binsize is in dbar.

Regime 3 period
The sampling period during this regime in milliseconds.

Reference pressure for WiFi module, if installed
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer. It represents the pressure in dbar assumed to apply at the surface of the water at the start of the deployment.

Offset from Universal Coordinated Time (UTC)

This parameter represents an offset in hours from UTC in the local timezone when the logger was deployed, if that information was provided by the host software.  This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  This format allows offsets which include partial hours, for those time zones which need it.  If the timezone is never explicitly set, or is erased by using the now  command to update the date/time, it will be reported as a NaN ('Not a Number' in IEEE floating point format).

Simulated data cycle period
When a logger is enabled in simulation mode, the simulated data is periodic, with the period usually being much longer than the sampling period.  The cycle period of the simulated data is given as an unsigned 32-bit integer in milliseconds.  For example, a value of 3600000 represents a period of one hour .

Directional  dependent sampling flags
This is a bitmask of settings for directional dependent sampling.
0x00000001  1 = ascending direction, 0 = descending direction.

Directional  dependent fast sampling period
The fast sampling period in milliseconds.

Directional  dependent slow sampling period
The slow sampling period in milliseconds.

Directional  dependent fast sampling threshold
The fast sampling threshold in dbar, this item is a floating point number in IEEE 32-bit (single precision) format, not an integer.

Directional  dependent slow sampling threshold
The slow sampling threshold in dbar, this item is a floating point number in IEEE 32-bit (single precision) format, not an integer.

Battery type, internal
An integer encoding the type of the internal battery as set by the  powerinternal  batterytype command, and as represented in the following table, which also shows the nominal Battery capacity for each battery type.

Battery type, external
An integer encoding the type of the internal battery as set by the powerexternal  batterytype command, and as represented in the following table, which also shows the nominal Battery capacity for each battery type.

Battery capacity, internal
This is an IEEE 32-bit (single precision) floating point number representing  the nominal total energy capacity in Joules of the indicated internal Battery type; see above.

Battery capacity, external
This is an IEEE 32-bit (single precision) floating point number representing  the nominal total energy capacity in Joules of the indicated external Battery type; see above.

Energy used from internal battery
This is an IEEE 32-bit (single precision) floating point number representing  an estimate of the total energy in Joules removed from the internal battery since the value was last reset (zeroed).

Energy used from external battery

This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the  total  energy in Joules used from the external power source since the value was last reset (zeroed).

Energy consumption parameter e1
This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the  energy in Joules required to take a single power-cycled sample .

Energy consumption parameter p1
This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the power  in Watts used by the logger in sleep mode.

Energy consumption parameter p2

This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the power  in Watts used by the logger when sampling while continuously powered on.

Energy consumption parameter p3
This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the power  in Watts used by the logger while using an alternative communications link such as WiFi.

[ Other energy consumption parameters may be present; see below.  They are not grouped together in order to keep the header layout compatible between different firmware versions. ]

Specific Conductivity Temperature Coefficient
This parameter is used when correcting conductivity readings to 25 °C for the specific conductance derived channel.  The value of the coefficient varies slightly depending on the ionic composition of the water, and is typically in the range 0.0191 to 0.0214.  The default value is 0.0191, suitable for standard KCl solutions .  This item is a floating point number in IEEE 32-bit (single precision) format, not an integer .

Temperature default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be Celsius.

Pressure default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be dbar.

Atmospheric pressure default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be dbar.

Density default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be kg/m³.

Salinity default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be PSU.

Average sound speed default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer.  The units must be m/s.

Altitude default value
This item is a floating point number in IEEE 32-bit (single precision) format, not an integer. It represents the height above the sea bed at which the logger is deployed. The units are not specified, although RBR Ltd's host software Ruskin expects the value to be in metres. This parameter is meaningful only for instruments configured to record wave bursts; see also the settings command.

Energy consumption parameter p4
This is  an IEEE 32-bit (single precision) floating point number representing  an estimate of the power  in Watts used by the logger while an installed 'device' is active.  Current examples of 'devices' include the UV-antifouling feature and the valve controller for the BPR|zero system.

Simulated channels mask
This is a 32-bit mask with one bit per channel indicating whether the channel was simulated (bit is 1) or has true measured data (bit is 0).  Only measured channels can be simulated, but the simulated data will be used by any derived channels dependent on the simulated channels.
Channel 1 is represented by bit 0 (the least significant bit), Channel 2 by bit 1, and so on.

Non deployment related settings section content (Section Id 0x04)

Output format 
This is the output format used for streamed or fetched data. See also the outputformat command.
 - 00 caltext01 format,
 - 01 caltext02 format,
 - 02 caltext03 format,
 - 03 caltext04 format

Serial link baudrate 
This is the baudrate in force on the logger's serial link when the logger was enabled.

Serial mode
The operating mode of the Serial port as an integer code; see the mode parameter under the  serial  command:

0: (rs232) standard RS-232.
1: (rs485f) full duplex RS-485.
2: (uart) direct connection to UART 3V logic.
3: (uart_idlelow) inverted connection to UART 3V logic.
4: (rs485h) half duplex RS-485. 

Auxiliary serial control output; polarities
Determines the active polarity of the signal when the logger is awake, and the state of the signal when the logger is asleep:

b0: 0 = logger drives signal low to activate, 1 = logger drives signal high to activate.
b1: 0 = signal is low when logger is asleep, 1 = signal is high when logger is asleep.
b2: 0 = b1 controls signal level when logger is asleep, 1 = signal is high impedance when logger is asleep.

Auxiliary serial control output; setup time
The time in milliseconds for which the control signal is activated before the logger starts to stream data over the Serial link.

Auxiliary serial control output; hold time
The time in milliseconds for which the control signal is held active after the logger has finished streaming data over the Serial link.

Power-on timeout for WiFi module, if installed

After activating the WiFi module,  the logger will wait for  this number of seconds at the most  for a valid command to be received.  If the timeout expires, the WiFi module will be deactivated again.

Command timeout for WiFi module, if installed

After receiving a valid command, the logger will wait for this number of seconds at the most for another.  If the timeout expires, the WiFi module will be deactivated.

Fetch power off delay
This is the timeout in milliseconds before the sensors are powered off after sending the fetch command.

Channel section content (Section Id 0x05)

Number of channels
As reported by the channels command, (1 byte)

Channel 1 offset
Channel 1 details offset from beginning of the channel section structure, (2 bytes)

Channel 2 offset  (2 bytes)

  ...

Channel N offset  (2 bytes)

[Channel_1 details structure]  (variable size, depends on channel type and number of calibration coefficients)

[Channel_2 details structure]  (variable size...)

  ...

[Channel_N details structure]  (variable size...)

Channel details structure

Type (6 bytes)
This is a 6-character ASCII string as reported by the channel command. See  Supported channel types for a list of possible values

Label (32 bytes)

This is a character ASCII string NUL terminated. If label is not set, all bytes are set to 0xFF.

Module fwtype (32 bytes) 

This is a character ASCII string NUL terminated. If the fwtype is unknown, all bytes are set to 0xFF.

Firmware version

Given as an integer; for example version 1.570 would be given as 1570. 

Channel extensions (2 bytes)
This 16-bit field stores specific flags for the channel.
The first five bits are used internally by the logger to control the properties and behaviour of a channel which has been turned off using the channel status command. The bits are assigned as follows:

• • • • bit-0: 0 if the channel is visible, 1 if it is hidden.

      • bit-1: 0 if the channel is sampled, 1 if it is ignored.

      • bit-2: 0 if the channel data is stored in memory, 1 if it is transient.

      • bit-3: 0 if the channel data may be streamed, 1 if it is quiet.

      • bit-4: 0 if the channel is "on", 1 if the user requested it be turned "off".

These bits are not directly accessible to users via the command interface, and are really only for the logger's internal use: not all possible combinations are valid. Turning a channel "off" is not as simple as it may seem; for example, if the user requests a channel is turned off, but its data is required for the correction of another channel, the logger must still sample the channel without necessarily storing or streaming the data. These bits provide the detailed control necessary to deal with such scenarios.

The visible/hidden property is configured at the Factory and can not be changed or read by the user. A channel may be hidden if it is required by the logger but is of no interest to the user; an example might be an internal temperature needed for correction purposes.

Calibration Date (4 bytes)
Retrieved by the calibration command. The value is the number of seconds elapsed since 2000-Jan-01 00:00:00.

Number of coefficients (1 byte)
The number of channel calibration coefficients.

Coefficient 1 (4 bytes)
This item is typically a floating point number in IEEE 32-bit (single precision) format, not an integer.

Coefficient 2 (4 bytes)

  ...

Coefficient N (4 bytes)

All true coefficients are floating point numbers in IEEE 32-bit (single precision) format.
Coefficients appear in ascending order in the following manner: C-coefficients first, then X-coefficients, then N-coefficients.
Refer to the calibration command for more details.

Channel specific structures total size (2 bytes)
Applies to channels with gain settings,  sensor  key/value pairs, or other channel-specific information.  This is the total size of all the channel-specific structures.

Channel specific structures 
Applies to channels with gain settings, sensor  key/value pairs and specific frontends. 

This is a list of specific structures which applies to a channel. Each structure starts with an header:

Device section content (Section Id 0x06)

This section will not appear in header versions earlier than 2.002.  In future, for versions 2.002 or later, if there are no devices configured in the instrument this section may either be a) not present at all, or b) present, but indicate that zero devices are installed, in which case there will be no supporting data to follow.

Number of devices
(1 byte) Number of devices configured in the instrument.

Device 1 offset
(2 bytes) Offset of the details for Device 1, from the beginning of the device section.

Device 2 offset

(2 bytes) Offset of the details for Device 2, from the beginning of the device section.

  ...

Device N offset

(2 bytes) Offset of the details for Device N, from the beginning of the device section.

[Details for device 1]

(Variable size) Depends on the type of device installed.

[Details for device 2]

(Variable size) Depends on the type of device installed.

  ...

[Details for device N]

(Variable size) Depends on the type of device installed.

Padding

Following the Details for device N section there will be from 0 to 3 bytes of padding to bring the total size of the entire deployment header up to a multiple of four bytes, if necessary.  These bytes are included in the size byte-count for this section, as well as the size byte-count for the complete deployment header, but they serve no other purpose and their value is not defined.  Currently, this padding appears only in the Device section, Section 6; deployment headers which do not have this section are not padded in the same way, and in general their size will not be a multiple of four bytes.

Structure of details for each device

Type
(1 byte) This is a byte code which identifies the type of device installed.  An unknown or unidentified device has the code 255 (0xFF).

Module address
(1 byte) This is the internal FE-bus address of the module that interfaces to the device itself.

Reserved
( 2 bytes)

Label
(24 bytes) This is a NUL-terminated ASCII character string.  If no label has been set, all bytes will be 0xFF.

Module firmware type
(32 bytes) This is a NUL-terminated ASCII character string.  If the firmware type is unknown, all bytes are set to 0xFF.

Module firmware version
(4 bytes) Given as a 32b integer; for example version 1.570 would be given as 1570.

Control and status flags
(2 bytes) The following flags are currently defined:

Interval between scheduled device episodes
(4 bytes) An unsigned 32b integer giving the time between scheduled device episodes in milliseconds / seconds (see Bit 5 flag above).

Duration of scheduled device episodes
(4 bytes) An unsigned 32b integer giving the duration of each scheduled device episode in milliseconds / seconds (see Bit 5 flag above).

Power on delay
(4 bytes) An unsigned 32b integer giving the delay in milliseconds between powering up the external device and sending it any commands.

Power off guard time
(4 bytes) An unsigned 32b integer giving the delay in milliseconds between sending the last command to the external device and removing its power.

Size of device
(2 bytes) Indicates how many bytes of additional information follow, if any; these are specific to this particular type of device .

Device-specific details
(N bytes) Additional information specific to this type of device; the value of 'N' is indicated by the preceding size parameter.