libRBR  v1.2.3
RBR instrument communication API
Data Structures | Macros | Typedefs | Enumerations | Functions
RBRInstrumentStreaming.h File Reference

Instrument commands and structures pertaining to real-time data acquisition. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  RBRInstrumentChannelsList
 Response to the outputformat channelslist command. More...
 
struct  RBRInstrumentLabelsList
 Response to the outputformat labelslist command. More...
 
struct  RBRInstrumentAuxOutput
 Instrument streamserial command parameters relating to the auxiliary output signal functionality. More...
 
struct  RBRInstrumentSample
 An instrument sample. More...
 

Macros

#define RBRINSTRUMENT_OUTPUT_FORMAT_NAME_MAX   15
 The maximum number of characters in an output format name (e.g., “caltext01”).
 

Typedefs

typedef struct RBRInstrumentChannelsList RBRInstrumentChannelsList
 Response to the outputformat channelslist command. More...
 
typedef struct RBRInstrumentLabelsList RBRInstrumentLabelsList
 Response to the outputformat labelslist command. More...
 
typedef enum RBRInstrumentOutputFormat RBRInstrumentOutputFormat
 Instrument output formats. More...
 
typedef enum RBRInstrumentAuxOutputActiveLevel RBRInstrumentAuxOutputActiveLevel
 Possible levels of the auxiliary output signal during the setup time, data transmission, and hold time. More...
 
typedef enum RBRInstrumentAuxOutputSleepLevel RBRInstrumentAuxOutputSleepLevel
 Possible levels of the auxiliary output signal while the instrument is asleep. More...
 
typedef struct RBRInstrumentAuxOutput RBRInstrumentAuxOutput
 Instrument streamserial command parameters relating to the auxiliary output signal functionality. More...
 
typedef enum RBRInstrumentReadingFlag RBRInstrumentReadingFlag
 A flag set on a sample reading.
 
typedef struct RBRInstrumentSample RBRInstrumentSample
 An instrument sample.
 

Enumerations

enum  RBRInstrumentOutputFormat {
  RBRINSTRUMENT_OUTFORMAT_NONE = 0, RBRINSTRUMENT_OUTFORMAT_CALTEXT01 = 1 << 0, RBRINSTRUMENT_OUTFORMAT_CALTEXT02 = 1 << 1, RBRINSTRUMENT_OUTFORMAT_CALTEXT03 = 1 << 2,
  RBRINSTRUMENT_OUTFORMAT_CALTEXT04 = 1 << 3, RBRINSTRUMENT_OUTFORMAT_CALTEXT07 = 1 << 4, RBRINSTRUMENT_OUTFORMAT_MAX = RBRINSTRUMENT_OUTFORMAT_CALTEXT07
}
 Instrument output formats. More...
 
enum  RBRInstrumentAuxOutputActiveLevel { RBRINSTRUMENT_ACTIVE_HIGH, RBRINSTRUMENT_ACTIVE_LOW, RBRINSTRUMENT_ACTIVE_COUNT, RBRINSTRUMENT_UNKNOWN_ACTIVE }
 Possible levels of the auxiliary output signal during the setup time, data transmission, and hold time. More...
 
enum  RBRInstrumentAuxOutputSleepLevel {
  RBRINSTRUMENT_SLEEP_TRISTATE, RBRINSTRUMENT_SLEEP_HIGH, RBRINSTRUMENT_SLEEP_LOW, RBRINSTRUMENT_SLEEP_COUNT,
  RBRINSTRUMENT_UNKNOWN_SLEEP
}
 Possible levels of the auxiliary output signal while the instrument is asleep. More...
 
enum  RBRInstrumentReadingFlag {
  RBRINSTRUMENT_READING_FLAG_NONE, RBRINSTRUMENT_READING_FLAG_UNCALIBRATED, RBRINSTRUMENT_READING_FLAG_ERROR, RBRINSTRUMENT_READING_FLAG_COUNT,
  RBRINSTRUMENT_UNKNOWN_READING_FLAG
}
 A flag set on a sample reading. More...
 

Functions

RBRInstrumentError RBRInstrument_getChannelsList (RBRInstrument *instrument, RBRInstrumentChannelsList *channelsList)
 Report a list of names and units for active channels, in order. More...
 
RBRInstrumentError RBRInstrument_getLabelsList (RBRInstrument *instrument, RBRInstrumentLabelsList *labelsList)
 Report a list of labels for active channels, in order. More...
 
const char * RBRInstrumentOutputFormat_name (RBRInstrumentOutputFormat format)
 Get a human-readable string name for an output format. More...
 
RBRInstrumentError RBRInstrument_getAvailableOutputFormats (RBRInstrument *instrument, RBRInstrumentOutputFormat *outputFormats)
 Report a list of available output formats. More...
 
RBRInstrumentError RBRInstrument_getOutputFormat (RBRInstrument *instrument, RBRInstrumentOutputFormat *outputFormat)
 Get the current output format. More...
 
RBRInstrumentError RBRInstrument_setOutputFormat (RBRInstrument *instrument, RBRInstrumentOutputFormat outputFormat)
 Set the current output format. More...
 
RBRInstrumentError RBRInstrument_getUSBStreamingState (RBRInstrument *instrument, bool *enabled)
 Get the USB streaming state. More...
 
RBRInstrumentError RBRInstrument_setUSBStreamingState (RBRInstrument *instrument, bool enabled)
 Set the USB streaming state. More...
 
RBRInstrumentError RBRInstrument_getSerialStreamingState (RBRInstrument *instrument, bool *enabled)
 Get the serial streaming state. More...
 
RBRInstrumentError RBRInstrument_setSerialStreamingState (RBRInstrument *instrument, bool enabled)
 Set the serial streaming state. More...
 
const char * RBRInstrumentAuxOutputActiveLevel_name (RBRInstrumentAuxOutputActiveLevel level)
 Get a human-readable string name for a signal level of an active auxiliary output. More...
 
const char * RBRInstrumentAuxOutputSleepLevel_name (RBRInstrumentAuxOutputSleepLevel level)
 Get a human-readable string name for a signal level of a sleeping auxiliary output. More...
 
RBRInstrumentError RBRInstrument_getAuxOutput (RBRInstrument *instrument, RBRInstrumentAuxOutput *auxOutput)
 Get the instrument auxiliary output signal parameters. More...
 
RBRInstrumentError RBRInstrument_setAuxOutput (RBRInstrument *instrument, const RBRInstrumentAuxOutput *auxOutput)
 Set the instrument auxiliary output signal parameters. More...
 
const char * RBRInstrumentReadingFlag_name (RBRInstrumentReadingFlag flag)
 Get a human-readable string name for a reading flag. More...
 
RBRInstrumentReadingFlag RBRInstrumentReading_getFlag (double reading)
 Get the error flag from a reading. More...
 
uint8_t RBRInstrumentReading_getError (double reading)
 Get the error value from a reading. More...
 
double RBRInstrumentReading_setError (RBRInstrumentReadingFlag flag, uint8_t value)
 Synthesize a reading with an error set. More...
 
RBRInstrumentError RBRInstrument_readSample (RBRInstrument *instrument)
 Retrieve and parse data streamed from the instrument. More...
 

Detailed Description

Instrument commands and structures pertaining to real-time data acquisition.

See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data

Typedef Documentation

◆ RBRInstrumentAuxOutput

Instrument streamserial command parameters relating to the auxiliary output signal functionality.

See also
RBRInstrument_getAuxOutput()
RBRInstrument_setAuxOutput()
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrumentAuxOutputActiveLevel

Possible levels of the auxiliary output signal during the setup time, data transmission, and hold time.

See also
RBRInstrumentAuxOutput
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrumentAuxOutputSleepLevel

Possible levels of the auxiliary output signal while the instrument is asleep.

See also
RBRInstrumentAuxOutput
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrumentChannelsList

◆ RBRInstrumentLabelsList

◆ RBRInstrumentOutputFormat

Enumeration Type Documentation

◆ RBRInstrumentAuxOutputActiveLevel

Possible levels of the auxiliary output signal during the setup time, data transmission, and hold time.

See also
RBRInstrumentAuxOutput
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial
Enumerator
RBRINSTRUMENT_ACTIVE_COUNT 

The number of active output levels.

RBRINSTRUMENT_UNKNOWN_ACTIVE 

An unknown or unrecognized active output level.

◆ RBRInstrumentAuxOutputSleepLevel

Possible levels of the auxiliary output signal while the instrument is asleep.

See also
RBRInstrumentAuxOutput
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial
Enumerator
RBRINSTRUMENT_SLEEP_COUNT 

The number of sleep output levels.

RBRINSTRUMENT_UNKNOWN_SLEEP 

An unknown or unrecognized sleep output level.

◆ RBRInstrumentOutputFormat

Instrument output formats.

See also
RBRInstrument_getAvailableOutputFormats()
RBRInstrument_getOutputFormat()
RBRInstrument_setOutputFormat()
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat
Enumerator
RBRINSTRUMENT_OUTFORMAT_NONE 

No format.

RBRINSTRUMENT_OUTFORMAT_CALTEXT01 

Physical units to 4 decimal places.

RBRINSTRUMENT_OUTFORMAT_CALTEXT02 

Physical units to 4 decimal places with units.

RBRINSTRUMENT_OUTFORMAT_CALTEXT03 

Physical units with sufficient significant digits to ensure no resolution loss.

RBRINSTRUMENT_OUTFORMAT_CALTEXT04 

Physical units expressed as “engineering-notation” floating point.

RBRINSTRUMENT_OUTFORMAT_CALTEXT07 

Physical units to 4 decimal places. The output starts with the keyword "RBR" followed by the serial number. This format is available for LOGGER3 with fw 1.109 or later

RBRINSTRUMENT_OUTFORMAT_MAX 

Corresponds to the largest output format enum value.

◆ RBRInstrumentReadingFlag

A flag set on a sample reading.

Enumerator
RBRINSTRUMENT_READING_FLAG_NONE 

No flag.

RBRINSTRUMENT_READING_FLAG_UNCALIBRATED 

The channel is uncalibrated.

RBRINSTRUMENT_READING_FLAG_ERROR 

The reading is an error.

RBRINSTRUMENT_READING_FLAG_COUNT 

The number of reading flags.

RBRINSTRUMENT_UNKNOWN_READING_FLAG 

An unknown or unrecognized reading flag.

Function Documentation

◆ RBRInstrument_getAuxOutput()

RBRInstrumentError RBRInstrument_getAuxOutput ( RBRInstrument instrument,
RBRInstrumentAuxOutput auxOutput 
)

Get the instrument auxiliary output signal parameters.

RBRInstrumentAuxOutput.aux must be set to the index of the auxiliary output for which signal parameters are to be retrieved. Currently, it can only ever be set to 1 (AUX1). For example:

auxOutput.aux = 1;
RBRInstrument_getAuxOutput(instrument, &auxOutput);
Parameters
[in]instrumentthe instrument connection
[in,out]auxOutputthe auxiliary output signal parameters
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when the auxiliary output signal is unavailable
RBRINSTRUMENT_INVALID_PARAMETER_VALUE when the auxiliary output signal index is not 1
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrument_getAvailableOutputFormats()

RBRInstrumentError RBRInstrument_getAvailableOutputFormats ( RBRInstrument instrument,
RBRInstrumentOutputFormat outputFormats 
)

Report a list of available output formats.

outputFormats will be treated as a bit field representation of available output formats as defined by RBRInstrumentOutputFormat. For details, consult Working with Bit Fields.

Parameters
[in]instrumentthe instrument connection
[out]outputFormatsavailable output formats
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat

◆ RBRInstrument_getChannelsList()

RBRInstrumentError RBRInstrument_getChannelsList ( RBRInstrument instrument,
RBRInstrumentChannelsList channelsList 
)

Report a list of names and units for active channels, in order.

Helpful for identifying the channel corresponding to each value in the transmitted data.

RBRInstrumentChannelsList.channels will be populated in the order reported by the instrument. Unpopulated entries will have zero-length name and unit members.

This parameter is unavailable for Logger2 instruments. Use RBRInstrument_getChannels() and RBRInstrument_getChannel().

Parameters
[in]instrumentthe instrument connection
[out]channelsListthe channels list
Returns
RBRINSTRUMENT_UNSUPPORTED for Logger2 instruments
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when the command is unavailable
See also
RBRInstrument_getLabelsList()
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat

◆ RBRInstrument_getLabelsList()

RBRInstrumentError RBRInstrument_getLabelsList ( RBRInstrument instrument,
RBRInstrumentLabelsList labelsList 
)

Report a list of labels for active channels, in order.

Helpful for identifying the channel corresponding to each value in the transmitted data.

RBRInstrumentLabelsList.channels will be populated in the order reported by the instrument. Unpopulated entries will be zero-length.

This parameter is unavailable for Logger2 instruments. Use RBRInstrument_getChannels() and RBRInstrument_getChannel().

Parameters
[in]instrumentthe instrument connection
[out]labelsListthe channel labels list
Returns
RBRINSTRUMENT_UNSUPPORTED for Logger2 instruments
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when the command is unavailable
See also
RBRInstrument_getChannelsList()
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat

◆ RBRInstrument_getOutputFormat()

RBRInstrumentError RBRInstrument_getOutputFormat ( RBRInstrument instrument,
RBRInstrumentOutputFormat outputFormat 
)

Get the current output format.

Parameters
[in]instrumentthe instrument connection
[out]outputFormatthe current output format
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat

◆ RBRInstrument_getSerialStreamingState()

RBRInstrumentError RBRInstrument_getSerialStreamingState ( RBRInstrument instrument,
bool *  enabled 
)

Get the serial streaming state.

Parameters
[in]instrumentthe instrument connection
[out]enabledwhether serial streaming is enabled
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when serial streaming is unavailable
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrument_getUSBStreamingState()

RBRInstrumentError RBRInstrument_getUSBStreamingState ( RBRInstrument instrument,
bool *  enabled 
)

Get the USB streaming state.

Parameters
[in]instrumentthe instrument connection
[out]enabledwhether USB streaming is enabled
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when USB streaming is unavailable
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamusb

◆ RBRInstrument_readSample()

RBRInstrumentError RBRInstrument_readSample ( RBRInstrument instrument)

Retrieve and parse data streamed from the instrument.

This function waits for a streamed sample to arrive, parses it, then calls the RBRInstrumentSampleCallback provided to the instrument via RBRInstrumentCallbacks.sample.

Parameters
[in]instrumentthe instrument connection
Returns
RBRINSTRUMENT_SUCCESS when a streaming sample has been read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
See also
RBRInstrument_fetchSample() for on-demand sample fetching

◆ RBRInstrument_setAuxOutput()

RBRInstrumentError RBRInstrument_setAuxOutput ( RBRInstrument instrument,
const RBRInstrumentAuxOutput auxOutput 
)

Set the instrument auxiliary output signal parameters.

Hardware errors may occur if:

  • the auxiliary output signal is not available for the instrument
  • you set an out-of-bounds parameter the library fails to detect
Parameters
[in]instrumentthe instrument connection
[out]auxOutputthe auxiliary output signal parameters
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully written
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when the settings cannot be changed
RBRINSTRUMENT_INVALID_PARAMETER_VALUE when parameter values are out of range
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrument_setOutputFormat()

RBRInstrumentError RBRInstrument_setOutputFormat ( RBRInstrument instrument,
RBRInstrumentOutputFormat  outputFormat 
)

Set the current output format.

Parameters
[in]instrumentthe instrument connection
[in]outputFormatthe current output format
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when an unavailable output format is selected
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/outputformat

◆ RBRInstrument_setSerialStreamingState()

RBRInstrumentError RBRInstrument_setSerialStreamingState ( RBRInstrument instrument,
bool  enabled 
)

Set the serial streaming state.

Parameters
[in]instrumentthe instrument connection
[in]enabledwhether serial streaming is enabled
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when serial streaming is unavailable
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamserial

◆ RBRInstrument_setUSBStreamingState()

RBRInstrumentError RBRInstrument_setUSBStreamingState ( RBRInstrument instrument,
bool  enabled 
)

Set the USB streaming state.

Parameters
[in]instrumentthe instrument connection
[in]enabledwhether USB streaming is enabled
Returns
RBRINSTRUMENT_SUCCESS when the settings are successfully read
RBRINSTRUMENT_TIMEOUT when a timeout occurs
RBRINSTRUMENT_CALLBACK_ERROR returned by a callback
RBRINSTRUMENT_HARDWARE_ERROR when USB streaming is unavailable
See also
https://docs.rbr-global.com/L3commandreference/commands/real-time-data/streamusb

◆ RBRInstrumentAuxOutputActiveLevel_name()

const char* RBRInstrumentAuxOutputActiveLevel_name ( RBRInstrumentAuxOutputActiveLevel  level)

Get a human-readable string name for a signal level of an active auxiliary output.

Parameters
[in]levelthe signal level
Returns
a string name for the signal level
See also
RBRInstrumentError_name() for a description of the format of names

◆ RBRInstrumentAuxOutputSleepLevel_name()

const char* RBRInstrumentAuxOutputSleepLevel_name ( RBRInstrumentAuxOutputSleepLevel  level)

Get a human-readable string name for a signal level of a sleeping auxiliary output.

Parameters
[in]levelthe signal level
Returns
a string name for the signal level
See also
RBRInstrumentError_name() for a description of the format of names

◆ RBRInstrumentOutputFormat_name()

const char* RBRInstrumentOutputFormat_name ( RBRInstrumentOutputFormat  format)

Get a human-readable string name for an output format.

Parameters
[in]formatthe output format
Returns
a string name for the output format
See also
RBRInstrumentError_name() for a description of the format of names

◆ RBRInstrumentReading_getError()

uint8_t RBRInstrumentReading_getError ( double  reading)

Get the error value from a reading.

If the reading is not a NaN, returns the error value encoded within the NaN. Otherwise, returns 0.

Parameters
readingthe reading
Returns
the error value of the reading, if present
See also
RBRInstrumentReading_getFlag() to get the error flag, if present
RBRInstrumentReading_setError() to create a reading with an error set

◆ RBRInstrumentReading_getFlag()

RBRInstrumentReadingFlag RBRInstrumentReading_getFlag ( double  reading)

Get the error flag from a reading.

If the reading is not a NaN, returns the error flag encoded within the NaN. Otherwise, returns RBRINSTRUMENT_READING_FLAG_NONE.

Parameters
readingthe reading
Returns
the error flag of the reading, if present
See also
RBRInstrumentReading_getError() to get the error value, if present
RBRInstrumentReading_setError() to create a reading with an error set

◆ RBRInstrumentReading_setError()

double RBRInstrumentReading_setError ( RBRInstrumentReadingFlag  flag,
uint8_t  value 
)

Synthesize a reading with an error set.

Parameters
flagthe error flag
valuethe error value
Returns
the error reading
See also
RBRInstrumentReading_getFlag() to get the error flag, if present
RBRInstrumentReading_getError() to get the error value, if present

◆ RBRInstrumentReadingFlag_name()

const char* RBRInstrumentReadingFlag_name ( RBRInstrumentReadingFlag  flag)

Get a human-readable string name for a reading flag.

Parameters
[in]flagthe reading flag
Returns
a string name for the reading flag
See also
RBRInstrumentError_name() for a description of the format of names
RBRInstrument_getAuxOutput
RBRInstrumentError RBRInstrument_getAuxOutput(RBRInstrument *instrument, RBRInstrumentAuxOutput *auxOutput)
Get the instrument auxiliary output signal parameters.
RBRInstrumentAuxOutput
Instrument streamserial command parameters relating to the auxiliary output signal functionality.
Definition: RBRInstrumentStreaming.h:332
RBRInstrumentAuxOutput::aux
uint8_t aux
Which auxiliary output signal settings to retrieve or configure.
Definition: RBRInstrumentStreaming.h:339