Interface for simplified communication with RBR instruments. More...

#include <inttypes.h>
#include <stdbool.h>
#include <stdlib.h>
#include "RBRInstrumentHardwareErrors.h"
#include "RBRInstrumentCommands.h"

Include dependency graph for RBRInstrument.h:

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

Go to the source code of this file.

Data Structures
struct	RBRInstrumentId
	Instrument `id` command parameters. More...

struct	RBRInstrumentCallbacks
	A set of callbacks from library to user code. More...

struct	RBRInstrumentResponse
	A command response returned by the instrument. More...

struct	RBRInstrument
	Core library context object. More...

Macros
#define	RBRINSTRUMENT_COMMAND_BUFFER_MAX 120
	The size of the buffer storing commands destined for the instrument. More...

#define	RBRINSTRUMENT_RESPONSE_BUFFER_MAX 1024
	The size of the buffer storing instrument responses. More...

#define	RBRINSTRUMENT_CHANNEL_MAX 32
	The maximum number of channels present on an instrument. More...

#define	xstr(s) str(s)
	Stringize the result of macro expansion.

#define	str(s) #s
	Stringize the macro argument.

#define	RBRINSTRUMENT_CHANNEL_MAX_LEN sizeof(xstr(RBRINSTRUMENT_CHANNEL_MAX))
	The string length of the maximum number of instrument channels.

#define	RBRINSTRUMENT_CHANNEL_NAME_MAX 31
	The maximum number of characters in a channel name (e.g., “Temperature”). More...

#define	RBRINSTRUMENT_CHANNEL_TYPE_MAX 11
	The maximum number of characters in a channel type (e.g., “temp09”). More...

#define	RBRINSTRUMENT_CHANNEL_UNIT_MAX 7
	The maximum number of characters in a channel unit name (e.g., “C”). More...

#define	RBRINSTRUMENT_CHANNEL_LABEL_MAX 31
	The maximum number of characters in a channel label. More...

#define	RBRINSTRUMENT_DATETIME_MIN 946684800000LL
	The minimum date and time which the instrument can handle. More...

#define	RBRINSTRUMENT_DATETIME_MAX 4102444799000LL
	The minimum date and time which the instrument can handle. More...

#define	RBRINSTRUMENT_ID_MODEL_MAX 14
	The maximum number of characters in the instrument model name. More...

#define	RBRINSTRUMENT_ID_VERSION_MAX 7
	The maximum number of characters in the instrument firmware version. More...

#define	RBRINSTRUMENT_ID_MODE_MAX 10
	The maximum number of characters in the instrument mode. More...

Typedefs
typedef int64_t	RBRInstrumentDateTime

typedef int32_t	RBRInstrumentPeriod
	A periodic parameter. More...

typedef enum RBRInstrumentError	RBRInstrumentError
	Errors which can be returned from library functions. More...

typedef struct RBRInstrumentId	RBRInstrumentId
	Instrument `id` command parameters. More...

typedef enum RBRInstrumentGeneration	RBRInstrumentGeneration
	Generations of RBR instruments.

typedef RBRInstrumentError(*	RBRInstrumentTimeCallback) (const struct RBRInstrument instrument, RBRInstrumentDateTime time)
	Callback to get the current platform time in milliseconds. More...

typedef RBRInstrumentError(*	RBRInstrumentSleepCallback) (const struct RBRInstrument *instrument, RBRInstrumentDateTime time)
	Callback to suspend instrument activity for a fixed amount of time. More...

typedef RBRInstrumentError(*	RBRInstrumentReadCallback) (const struct RBRInstrument instrument, void data, int32_t *size)
	Callback to read data from the physical instrument. More...

typedef RBRInstrumentError(*	RBRInstrumentWriteCallback) (const struct RBRInstrument instrument, const void const data, int32_t size)
	Callback to write data to the physical instrument. More...

typedef RBRInstrumentError(*	RBRInstrumentSampleCallback) (const struct RBRInstrument instrument, const struct RBRInstrumentSample const sample)
	Callback to feed streaming sample data into user code. More...

typedef struct RBRInstrumentCallbacks	RBRInstrumentCallbacks
	A set of callbacks from library to user code. More...

typedef enum RBRInstrumentResponseType	RBRInstrumentResponseType
	The types of responses returned by the instrument. More...

typedef struct RBRInstrumentResponse	RBRInstrumentResponse
	A command response returned by the instrument.

typedef struct RBRInstrument	RBRInstrument
	Core library context object. More...

Enumerations
enum	RBRInstrumentError { RBRINSTRUMENT_SUCCESS, RBRINSTRUMENT_ALLOCATION_FAILURE, RBRINSTRUMENT_BUFFER_TOO_SMALL, RBRINSTRUMENT_MISSING_CALLBACK, RBRINSTRUMENT_CALLBACK_ERROR, RBRINSTRUMENT_TIMEOUT, RBRINSTRUMENT_UNSUPPORTED, RBRINSTRUMENT_HARDWARE_ERROR, RBRINSTRUMENT_CHECKSUM_ERROR, RBRINSTRUMENT_INVALID_PARAMETER_VALUE, RBRINSTRUMENT_SAMPLE, RBRINSTRUMENT_COMMUNICATION_ERROR, RBRINSTRUMENT_ERROR_COUNT, RBRINSTRUMENT_UNKNOWN_ERROR }
	Errors which can be returned from library functions. More...

enum	RBRInstrumentGeneration { RBRINSTRUMENT_LOGGER1, RBRINSTRUMENT_LOGGER2, RBRINSTRUMENT_LOGGER3, RBRINSTRUMENT_GENERATION_COUNT, RBRINSTRUMENT_UNKNOWN_GENERATION }
	Generations of RBR instruments. More...

enum	RBRInstrumentResponseType { RBRINSTRUMENT_RESPONSE_INFO, RBRINSTRUMENT_RESPONSE_WARNING, RBRINSTRUMENT_RESPONSE_ERROR, RBRINSTRUMENT_RESPONSE_TYPE_COUNT, RBRINSTRUMENT_RESPONSE_UNKNOWN_TYPE }
	The types of responses returned by the instrument. More...

Functions
const char *	RBRInstrumentError_name (RBRInstrumentError error)
	Get a human-readable string name for a library error. More...

const char *	RBRInstrumentGeneration_name (RBRInstrumentGeneration generation)
	Get a human-readable string name for a generation. More...

const char *	RBRInstrumentResponseType_name (RBRInstrumentResponseType type)
	Get a human-readable string name for a response type. More...

RBRInstrumentError	RBRInstrument_open (RBRInstrument *instrument, const RBRInstrumentCallbacks callbacks, RBRInstrumentDateTime commandTimeout, void *userData)
	Establish a connection with an instrument and initialize the context. More...

RBRInstrumentError	RBRInstrument_close (RBRInstrument *instrument)
	Terminate the instrument connection and release any held resources. More...

RBRInstrumentGeneration	RBRInstrument_getGeneration (const RBRInstrument *instrument)
	Get the generation of an instrument. More...

RBRInstrumentDateTime	RBRInstrument_getCommandTimeout (const RBRInstrument *instrument)
	Get the command timeout. More...

void	RBRInstrument_setCommandTimeout (RBRInstrument *instrument, RBRInstrumentDateTime commandTimeout)
	Set the command timeout. More...

void *	RBRInstrument_getUserData (const RBRInstrument *instrument)
	Get the pointer to arbitrary user data. More...

void	RBRInstrument_setUserData (RBRInstrument instrument, void userData)
	Change the arbitrary user data pointer. More...

RBRInstrumentHardwareError	RBRInstrument_getLastHardwareError (const RBRInstrument *instrument)
	Get the error which resulted from the last instrument command, if applicable. More...

const char *	RBRInstrument_getLastHardwareErrorMessage (const RBRInstrument *instrument)
	Get the error message which resulted from the last instrument command, if applicable. More...

Variables
const char *	RBRINSTRUMENT_LIB_NAME
	The library name. More...

const char *	RBRINSTRUMENT_LIB_VERSION
	The library version. More...

const char *	RBRINSTRUMENT_LIB_BUILD_DATE
	The library build date. More...

Detailed Description

Interface for simplified communication with RBR instruments.

This file contains declarations and constants relevant throughout the library. Command-specific declarations are stored in categorical headers which are included by this one. As the end user, your include directives need reference only this file.

Copyright: Copyright (c) 2018 RBR Ltd. Licensed under the Apache License, Version 2.0.

Macro Definition Documentation

◆ RBRINSTRUMENT_CHANNEL_LABEL_MAX

#define RBRINSTRUMENT_CHANNEL_LABEL_MAX 31

The maximum number of characters in a channel label.

Does not include any null terminator. Must be at least 4 (to hold “none”, the default value).

◆ RBRINSTRUMENT_CHANNEL_MAX

#define RBRINSTRUMENT_CHANNEL_MAX 32

The maximum number of channels present on an instrument.

The default maximum of 32 channels is reflective of the maximum number of channels supported by RBR instruments, but most instruments have far fewer. Adjusting this value will dramatically affect the size of some structures; notably RBRInstrumentSample, but also RBRInstrumentChannels (used by RBRInstrument_getChannels()) and RBRInstrumentChannelsList (used by RBRInstrument_getChannelsList()).

◆ RBRINSTRUMENT_CHANNEL_NAME_MAX

#define RBRINSTRUMENT_CHANNEL_NAME_MAX 31

The maximum number of characters in a channel name (e.g., “Temperature”).

Does not include any null terminator.

◆ RBRINSTRUMENT_CHANNEL_TYPE_MAX

#define RBRINSTRUMENT_CHANNEL_TYPE_MAX 11

The maximum number of characters in a channel type (e.g., “temp09”).

Does not include any null terminator.

◆ RBRINSTRUMENT_CHANNEL_UNIT_MAX

#define RBRINSTRUMENT_CHANNEL_UNIT_MAX 7

The maximum number of characters in a channel unit name (e.g., “C”).

Does not include any null terminator.

◆ RBRINSTRUMENT_COMMAND_BUFFER_MAX

#define RBRINSTRUMENT_COMMAND_BUFFER_MAX 120

The size of the buffer storing commands destined for the instrument.

Must be large enough to hold the largest command you will want to send to the instrument plus the trailing line termination (\r\n\0).

A buffer of this size is included in RBRInstrument. Whether you let RBRInstrument_open() perform its own allocation or you perform your own allocation based on sizeof(RBRInstrument), a buffer of this size is included.

◆ RBRINSTRUMENT_DATETIME_MAX

#define RBRINSTRUMENT_DATETIME_MAX 4102444799000LL

The minimum date and time which the instrument can handle.

Specified in milliseconds since the Unix epoch (1970-01-01T00:00:00.000Z). Represents 2099-12-31T23:59:59.000Z.

◆ RBRINSTRUMENT_DATETIME_MIN

#define RBRINSTRUMENT_DATETIME_MIN 946684800000LL

The minimum date and time which the instrument can handle.

Specified in milliseconds since the Unix epoch (1970-01-01T00:00:00.000Z). Represents 2000-01-01T00:00:00.000Z.

◆ RBRINSTRUMENT_ID_MODE_MAX

#define RBRINSTRUMENT_ID_MODE_MAX 10

The maximum number of characters in the instrument mode.

Does not include any null terminator.

◆ RBRINSTRUMENT_ID_MODEL_MAX

#define RBRINSTRUMENT_ID_MODEL_MAX 14

The maximum number of characters in the instrument model name.

Does not include any null terminator.

◆ RBRINSTRUMENT_ID_VERSION_MAX

#define RBRINSTRUMENT_ID_VERSION_MAX 7

The maximum number of characters in the instrument firmware version.

Does not include any null terminator.

◆ RBRINSTRUMENT_RESPONSE_BUFFER_MAX

#define RBRINSTRUMENT_RESPONSE_BUFFER_MAX 1024

The size of the buffer storing instrument responses.

Must be large enough to hold the largest command response you will want to receive. This does not include download data, which is read directly into a user-managed buffer.

A buffer of this size is included in RBRInstrument. Whether you let RBRInstrument_open() perform its own allocation or you perform your own allocation based on sizeof(RBRInstrument), a buffer of this size is included.

Typedef Documentation

◆ RBRInstrument

typedef struct RBRInstrument RBRInstrument

Core library context object.

Users are strongly discouraged from accessing the fields of this structure directly as layout and field availability maybe unstable from version to version. Getter and setter functions are available for safely reading from and writing to fields where necessary.

See also: RBRInstrument_open() to open an instrument connection; RBRInstrument_close() to close an instrument connection

◆ RBRInstrumentCallbacks

typedef struct RBRInstrumentCallbacks RBRInstrumentCallbacks

A set of callbacks from library to user code.

RBRInstrument_open() requires all callbacks to be populated except for RBRInstrumentCallbacks.sample, which may be NULL when undesired.

◆ RBRInstrumentDateTime

typedef int64_t RBRInstrumentDateTime

A date and time in milliseconds since the Unix epoch (1970-01-01T00:00:00.000Z). Instrument functions operating on time (e.g., RBRInstrument_getClock(), RBRInstrument_setClock()) will automatically convert to and from the instrument's string time representation.

The valid range for any instrument date/time parameter is 2000-01-01T00:00:00.000Z to 2099-12-31T23:59:59.000Z, inclusive. Passing a value outside of this range will be detected by the library and will cause a RBRINSTRUMENT_INVALID_PARAMETER_VALUE error, not a hardware error.

◆ RBRInstrumentError

typedef enum RBRInstrumentError RBRInstrumentError

Errors which can be returned from library functions.

Generally speaking, library functions will return error codes in lieu of data values; data will be passed back to the caller via out pointers. This allows for predictable and consistent error checking by the caller.

◆ RBRInstrumentId

typedef struct RBRInstrumentId RBRInstrumentId

Instrument id command parameters.

Externalized from RBRInstrumentOther.h to facilitate inclusion by RBRInstrument.

See also: RBRInstrument_getId(); https://docs.rbr-global.com/L3commandreference/commands/other-information/id

◆ RBRInstrumentPeriod

typedef int32_t RBRInstrumentPeriod

A periodic parameter.

Specified in milliseconds. Generally, parameters of this type must be greater than 0, may not be greater than 86,400,000 (24 hours), and must be multiples of 1,000 when greater than 1,000. See specific parameter documentation for details.

◆ RBRInstrumentReadCallback

typedef RBRInstrumentError(* RBRInstrumentReadCallback) (const struct RBRInstrument *instrument, void *data, int32_t *size)

Callback to read data from the physical instrument.

Library functions will call this user code to read data from the instrument. This function should block until data is available (even if only a single byte) or until the timeout has elapsed, then return. It will be called multiple times in quick succession if the library requires more data.

The library will provide a destination for data read from the instrument via the data argument. The maximum amount of data which can be written to this location is given by the size argument. Before returning RBRINSTRUMENT_SUCCESS, the value of size should be updated by the callback to reflect the number of bytes written to data. When a value other than RBRINSTRUMENT_SUCCESS is returned, any new value of size is ignored, as is any data written to data.

The function should return RBRINSTRUMENT_SUCCESS when data is successfully read from the instrument. In the event of any other value being returned, the calling library function will treat that value as indicative of an error, immediately perform any necessary cleanup, and then return that same value to its caller. On Posix systems, the library will avoid doing anything which might disturb the value of errno before returning to user code. It is strongly suggested that RBRINSTRUMENT_TIMEOUT be returned in the event of a timeout and that RBRINSTRUMENT_CALLBACK_ERROR be returned under any other circumstance; that way a clear distinction can be made between errors occurring in user code versus library code.

Because communication is handled by user code, and because communication only occurs at the behest of the user, it is up to the user to define the semantics of communication timeouts and to implement them. This could be a constant read/write timeout, or a per-connection timeout tied to the instrument by the user data pointer; the library is unopinionated.

Parameters

[in]	instrument	the instrument for which data is being requested
[in,out]	data	where up to size bytes of data can be written
[in,out]	size	initially, the maximum amount of data which can be written to data; set by the callback to the number of bytes actually written

Returns: RBRINSTRUMENT_SUCCESS when data is successfully read; RBRINSTRUMENT_TIMEOUT when a timeout occurs; RBRINSTRUMENT_CALLBACK_ERROR when an unrecoverable error occurs

◆ RBRInstrumentResponseType

typedef enum RBRInstrumentResponseType RBRInstrumentResponseType

The types of responses returned by the instrument.

Used by RBRInstrumentResponse.

◆ RBRInstrumentSampleCallback

typedef RBRInstrumentError(* RBRInstrumentSampleCallback) (const struct RBRInstrument *instrument, const struct RBRInstrumentSample *const sample)

Callback to feed streaming sample data into user code.

Library functions will call this user code when a streaming sample has been received.

The sample pointer will be the same as given via RBRInstrumentCallbacks.sampleBuffer. The sample value will be overwritten every time sample parsing is attempted, which will be at least once per command exchanged with the instrument. If you want to use the sample after your callback has returned, make a copy of it.

This function is typically called as a side effect of parsing an instrument response to some other command, and may be called several times in succession if multiple samples have been received since the last instrument activity. As such, this callback should execute quickly to avoid blocking anything else.

Parameters

[in]	instrument	the instrument from which the sample was received
[in]	sample	the sample received from the instrument

Returns: RBRINSTRUMENT_SUCCESS when the sample data is successfully consumed; RBRINSTRUMENT_CALLBACK_ERROR when an unrecoverable error occurs

◆ RBRInstrumentSleepCallback

typedef RBRInstrumentError(* RBRInstrumentSleepCallback) (const struct RBRInstrument *instrument, RBRInstrumentDateTime time)

Callback to suspend instrument activity for a fixed amount of time.

Library functions will call this user code when they know the instrument will be unavailable particularly when waking the instrument from sleep.

Library functions will call this user code to suspend activity for a fixed amount of time.

Parameters

[in]	instrument	the instrument for which sleep is being requested
[in]	time	the duration for which a sleep is requested in milliseconds

Returns: RBRINSTRUMENT_SUCCESS when the time is successfully retrieved; RBRINSTRUMENT_CALLBACK_ERROR when an unrecoverable error occurs

See also: RBRInstrumentReadCallback() for details on how the values returned from user callback functions are used

◆ RBRInstrumentTimeCallback

typedef RBRInstrumentError(* RBRInstrumentTimeCallback) (const struct RBRInstrument *instrument, RBRInstrumentDateTime *time)

Callback to get the current platform time in milliseconds.

Return values must be positive and monotonically increasing.

Library functions will call this user code to determine whether an instrument has likely gone to sleep (based on time of last communication). The time returned should be independent of any instrument (i.e., a real system time) and, while it must return a number of milliseconds, that number need be relative only to other values returned by the callback (i.e., doesn't need to be an RTC time). On POSIX systems, the value can easily be based on CLOCK_BOOTTIME (or CLOCK_MONOTONIC on older systems where CLOCK_BOOTTIME is unavailable).

Parameters

[in]	instrument	the instrument for which the time is being requested
[out]	time	the current platform time in milliseconds

Returns: RBRINSTRUMENT_SUCCESS when the time is successfully retrieved; RBRINSTRUMENT_CALLBACK_ERROR when an unrecoverable error occurs

See also: RBRInstrumentReadCallback() for details on how the values returned from user callback functions are used

◆ RBRInstrumentWriteCallback

typedef RBRInstrumentError(* RBRInstrumentWriteCallback) (const struct RBRInstrument *instrument, const void *const data, int32_t size)

Callback to write data to the physical instrument.

Library functions will call this user code to write data to the instrument. This function should block until all data has been written or until the timeout has elapsed.

The data pointer should not be used after the callback returns. Do not store copies of it; if you want to use it after your callback has returned (perhaps for logging), copy the data instead.

The library will attempt to call this function only for complete commands (i.e., will try to avoid segmenting a single command over multiple callback invocations). Depending on the transport layer, this may be useful (e.g., for a IP transport, to know that each callback payload could be sent as an individual packet).

Parameters

[in]	instrument	the instrument for which data is being sent
[in]	data	the data to be written to the instrument
[in]	size	the size of the data given by data

Returns: RBRINSTRUMENT_SUCCESS when the data is successfully written; RBRINSTRUMENT_TIMEOUT when a timeout occurs; RBRINSTRUMENT_CALLBACK_ERROR when an unrecoverable error occurs

See also: RBRInstrumentReadCallback() for details on how the values returned from user callback functions are used

Enumeration Type Documentation

◆ RBRInstrumentError

enum RBRInstrumentError

Errors which can be returned from library functions.

Generally speaking, library functions will return error codes in lieu of data values; data will be passed back to the caller via out pointers. This allows for predictable and consistent error checking by the caller.

Enumerator
RBRINSTRUMENT_SUCCESS	No error.
RBRINSTRUMENT_ALLOCATION_FAILURE	An error occurred while allocating memory. This is typically fatal.
RBRINSTRUMENT_BUFFER_TOO_SMALL	The command buffer was too small to hold the outbound command.
RBRINSTRUMENT_MISSING_CALLBACK	A required callback function was not provided.
RBRINSTRUMENT_CALLBACK_ERROR	An unrecoverable error from within a user callback function.
RBRINSTRUMENT_TIMEOUT	A timeout occurred.
RBRINSTRUMENT_UNSUPPORTED	The instrument or command is unsupported by the library.
RBRINSTRUMENT_HARDWARE_ERROR	The physical instrument reported a warning or error. See also RBRInstrument_getLastHardwareError()
RBRINSTRUMENT_CHECKSUM_ERROR	A CRC check failed.
RBRINSTRUMENT_INVALID_PARAMETER_VALUE	The given value is out of bounds or otherwise unsuitable.
RBRINSTRUMENT_SAMPLE	Used internally when the parser encounters a sample. See also RBRInstrument_fetch() RBRInstrument_readSample()
RBRINSTRUMENT_COMMUNICATION_ERROR	Communication error.
RBRINSTRUMENT_ERROR_COUNT	The number of specific errors. Should not be used as an error value.
RBRINSTRUMENT_UNKNOWN_ERROR	An unknown or unrecognized error.

◆ RBRInstrumentGeneration

enum RBRInstrumentGeneration

Generations of RBR instruments.

Enumerator
RBRINSTRUMENT_LOGGER1	Logger1 (XR/XRX/TR/DR/TDR/HT).
RBRINSTRUMENT_LOGGER2	Logger2 (RBRvirtuoso/duo/concerto/maestro/solo/duet/coda).
RBRINSTRUMENT_LOGGER3	Logger3 (RBRvirtuoso³/duo³/concerto³/maestro³/solo³/duet³/coda³).
RBRINSTRUMENT_GENERATION_COUNT	The number of known generations.
RBRINSTRUMENT_UNKNOWN_GENERATION	An unknown or unrecognized instrument generation.

◆ RBRInstrumentResponseType

enum RBRInstrumentResponseType

The types of responses returned by the instrument.

Used by RBRInstrumentResponse.

Enumerator
RBRINSTRUMENT_RESPONSE_INFO	A success indicator or informational response.
RBRINSTRUMENT_RESPONSE_WARNING	Typically indicates that the command succeeded but with caveats.
RBRINSTRUMENT_RESPONSE_ERROR	A command failure.
RBRINSTRUMENT_RESPONSE_TYPE_COUNT	The number of specific types.
RBRINSTRUMENT_RESPONSE_UNKNOWN_TYPE	The response has been incorrectly or incompletely populated.

Function Documentation

◆ RBRInstrument_close()

RBRInstrumentError RBRInstrument_close ( RBRInstrument * instrument )

Terminate the instrument connection and release any held resources.

Frees the buffer allocated by RBRInstrument_open() if necessary. Does not perform any communication with the instrument.

Parameters

[in,out] instrument the instrument connection to terminate

Returns: RBRINSTRUMENT_SUCCESS if the instrument was closed successfully

See also: RBRInstrument_open()

◆ RBRInstrument_getCommandTimeout()

RBRInstrumentDateTime RBRInstrument_getCommandTimeout ( const RBRInstrument * instrument )

Get the command timeout.

Parameters

[in] instrument the instrument connection

Returns: the command timeout

See also: RBRInstrument_setCommandTimeout()

◆ RBRInstrument_getGeneration()

RBRInstrumentGeneration RBRInstrument_getGeneration ( const RBRInstrument * instrument )

Get the generation of an instrument.

Parameters

[in] instrument the instrument connection

Returns: the instrument generation

◆ RBRInstrument_getLastHardwareError()

RBRInstrumentHardwareError RBRInstrument_getLastHardwareError ( const RBRInstrument * instrument )

Get the error which resulted from the last instrument command, if applicable.

If the instrument responded with an error or a warning to the last command, this function returns that error. Otherwise, and before any commands have been issued to the instrument, it returns RBRINSTRUMENT_HARDWARE_ERROR_NONE.

Note that this information is not recorded by the instrument: it is recorded by the library as responses are parsed. Accordingly, the value will not persist across instrument connections.

Error messages can be quite long: in particular, errors E0102 (“invalid command '<unknown-command-name>'”) and E0108 (“invalid argument to command: '<invalid-argument>'”) both include user-provided data. Make sure you perform bounds-checking as necessary when consuming them.

Parameters

[in] instrument the instrument connection

Returns: the last error

See also: RBRInstrument_getLastHardwareErrorMessage() for the error message

◆ RBRInstrument_getLastHardwareErrorMessage()

const char* RBRInstrument_getLastHardwareErrorMessage ( const RBRInstrument * instrument )

Get the error message which resulted from the last instrument command, if applicable.

If the last instrument command returned RBRINSTRUMENT_HARDWARE_ERROR and an error message is available, this function returns the verbatim error message. Otherwise, and before any commands have been issued to the instrument, it returns NULL.

This function differs from RBRInstrumentHardwareError_name() in that it returns the literal message produced by the instrument. This may include instance-specific error details (e.g., in the case of an invalid parameter, exactly which parameter was invalid). However, the enum name is a good fallback for cases where no message is available (e.g., warnings).

Note that this information is not recorded by the instrument: it is recorded by the library as responses are parsed. Accordingly, the value will not persist across instrument connections.

The buffer into which the return value points will change whenever instrument communication occurs. The message should be considered invalid after making any subsequent calls to the same instrument instance. If you need to retain a copy of the message, you should strcpy() it to your own buffer.

Error messages can be quite long: in particular, errors E0102 (“invalid command '<unknown-command-name>'”) and E0108 (“invalid argument to command: '<invalid-argument>'”) both include user-provided data. Make sure you perform bounds-checking as necessary when consuming them.

Parameters

[in] instrument the instrument connection

Returns: the last error message

See also: RBRInstrument_getLastHardwareError() for the error number/presence

◆ RBRInstrument_getUserData()

void* RBRInstrument_getUserData ( const RBRInstrument * instrument )

Get the pointer to arbitrary user data.

Returns whatever arbitrary pointer the user has most recently provided, either via RBRInstrument_open() or RBRInstrument_setUserData().

Parameters

[in] instrument the instrument connection

Returns: the arbitrary user data pointer

See also: RBRInstrument_setUserData()

◆ RBRInstrument_open()

RBRInstrumentError RBRInstrument_open	(	RBRInstrument **	instrument,
		const RBRInstrumentCallbacks *	callbacks,
		RBRInstrumentDateTime	commandTimeout,
		void *	userData
	)

Establish a connection with an instrument and initialize the context.

What this library calls a “connection” concerns purely the state tracking and management of an instrument: the underlying physical communication with that instrument (via serial, TCP/IP socket, RFC 1149, whatever) must be managed externally and exposed to the library via callbacks.

If the instrument pointer is NULL, enough memory will be allocated (via malloc(3)) to satisfy the requirements of all instrument communications.

For example:

RBRInstrument *instrument = NULL;

RBRInstrument_open(&instrument, ...);

Do not pass an uninitialized pointer to this constructor! It will be dereferenced, which is undefined behaviour; and if a non-NULL value is read, the constructor will think memory has been preallocated and will attempt to write through the pointer.

/​* Don't do this! *​/
RBRInstrument *instrument;
RBRInstrument_open(&instrument, ...);

If you would rather allocate this memory yourself (perhaps statically), you can use the size of RBRInstrument to inform your allocation then pass a pointer to that memory.

For example:

RBRInstrument instrumentBuf;
RBRInstrument *instrument = &instrumentBuf;
RBRInstrument_open(&instrument, ...);

If you pass pre-allocated memory, its contents will be discarded.

The callbacks structure will be copied into the RBRInstrument structure; no reference to it is retained, so any subsequent modifications will not affect the connection. All callbacks must be given except for RBRInstrumentCallbacks.sample. If any others are given as null pointers, RBRINSTRUMENT_MISSING_CALLBACK is returned and the instrument connection will not be opened. RBRInstrumentCallbacks.sample is given, then RBRInstrumentCallbacks.sampleBuffer must also be given; if it is not, RBRINSTRUMENT_MISSING_CALLBACK is returned.

Whenever callbacks are called, the data passed to them should be handled immediately. The pointers passed will coincide with buffers within the RBRInstrument instance, and may be overwritten as soon as the callback returns.

This library supports 3rd-generation RBR instruments and, to a lesser extent, 2nd-generation instruments. 1st-generation and third-party instruments are not supported. If the library detects an unsupported instrument during connection, RBRINSTRUMENT_UNSUPPORTED is returned.

In the event of any return value other than RBRINSTRUMENT_SUCCESS, any memory allocated by this constructor is freed. That is, in the event of failure, no cleanup of library resources is required. In the event of a successful result, RBRInstrument_close() should be used to terminate the instrument connection.

Parameters

[in,out]	instrument	the context object to populate
[in]	callbacks	the set of callbacks to be used by the connection
[in]	commandTimeout	the command timeout in milliseconds
[in]	userData	arbitrary user data; useful in callbacks

Returns: RBRINSTRUMENT_SUCCESS if the instrument was opened successfully; RBRINSTRUMENT_ALLOCATION_FAILURE if memory allocation failed; RBRINSTRUMENT_MISSING_CALLBACK if a callback was not provided; RBRINSTRUMENT_TIMEOUT if an instrument communication timeout occurs; RBRINSTRUMENT_CALLBACK_ERROR returned by a callback; RBRINSTRUMENT_UNSUPPORTED if the instrument is unsupported

See also: RBRInstrument_close()

◆ RBRInstrument_setCommandTimeout()

void RBRInstrument_setCommandTimeout	(	RBRInstrument *	instrument,
		RBRInstrumentDateTime	commandTimeout
	)

Set the command timeout.

Parameters

[in,out]	instrument	the instrument connection
[in]	commandTimeout	the new command timeout

See also: RBRInstrument_getCommandTimeout()

◆ RBRInstrument_setUserData()

void RBRInstrument_setUserData	(	RBRInstrument *	instrument,
		void *	userData
	)

Change the arbitrary user data pointer.

Parameters

[in,out]	instrument	the instrument connection
[in]	userData	the new user data

See also: RBRInstrument_getUserData()

◆ RBRInstrumentError_name()

const char* RBRInstrumentError_name ( RBRInstrumentError error )

Get a human-readable string name for a library error.

Names are a “friendlier” version of the error enum constant names: they have the RBRINSTRUMENT_ prefix removed, are converted to lower-case, and words are space-separated instead of underscore-separated.

For example:

RBRInstrumentError error = ...;
if (error != RBRINSTRUMENT_SUCCESS)
{
    fprintf(stderr,
            "Encountered an error: %s!\n",
            RBRInstrumentError_name(error));
}

...might print something like:

Encountered an error: timeout!

Parameters

[in] error the error

Returns: a string name for the error

◆ RBRInstrumentGeneration_name()

const char* RBRInstrumentGeneration_name ( RBRInstrumentGeneration generation )

Get a human-readable string name for a generation.

Contrary to convention for values returned by other enum _name functions, the generation names returned by this function are capitalized: “Logger3” instead of “logger3”.

Parameters

[in] generation the generation

Returns: a string name for the generation

See also: RBRInstrumentError_name() for a description of the format of names

◆ RBRInstrumentResponseType_name()

const char* RBRInstrumentResponseType_name ( RBRInstrumentResponseType type )

Get a human-readable string name for a response type.

Parameters

[in] type the response type

Returns: a string name for the response type

See also: RBRInstrumentError_name() for a description of the format of names

Variable Documentation

◆ RBRINSTRUMENT_LIB_BUILD_DATE

const char* RBRINSTRUMENT_LIB_BUILD_DATE

The library build date.

Stored in ISO 8601 format (“YYYY-mm-ddTHH:MM:SS±hhmm”).

◆ RBRINSTRUMENT_LIB_NAME

const char* RBRINSTRUMENT_LIB_NAME

The library name.

As shipped by RBR, this builds with the value “libRBR”. Project forks might like to change this at build time to easily identify which library variant is in use. See the Makefile for details.

◆ RBRINSTRUMENT_LIB_VERSION

const char* RBRINSTRUMENT_LIB_VERSION

The library version.

As shipped by RBR, this builds with a value based on the contents of the VERSION file. Project forks might also like to override this at build time.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RBRINSTRUMENT_CHANNEL_LABEL_MAX

◆ RBRINSTRUMENT_CHANNEL_MAX

◆ RBRINSTRUMENT_CHANNEL_NAME_MAX

◆ RBRINSTRUMENT_CHANNEL_TYPE_MAX

◆ RBRINSTRUMENT_CHANNEL_UNIT_MAX

◆ RBRINSTRUMENT_COMMAND_BUFFER_MAX

◆ RBRINSTRUMENT_DATETIME_MAX

◆ RBRINSTRUMENT_DATETIME_MIN

◆ RBRINSTRUMENT_ID_MODE_MAX

◆ RBRINSTRUMENT_ID_MODEL_MAX

◆ RBRINSTRUMENT_ID_VERSION_MAX

◆ RBRINSTRUMENT_RESPONSE_BUFFER_MAX

Typedef Documentation

◆ RBRInstrument

◆ RBRInstrumentCallbacks

◆ RBRInstrumentDateTime

◆ RBRInstrumentError

◆ RBRInstrumentId

◆ RBRInstrumentPeriod

◆ RBRInstrumentReadCallback

◆ RBRInstrumentResponseType

◆ RBRInstrumentSampleCallback

◆ RBRInstrumentSleepCallback

◆ RBRInstrumentTimeCallback

◆ RBRInstrumentWriteCallback

Enumeration Type Documentation

◆ RBRInstrumentError

◆ RBRInstrumentGeneration

◆ RBRInstrumentResponseType

Function Documentation

◆ RBRInstrument_close()

◆ RBRInstrument_getCommandTimeout()

◆ RBRInstrument_getGeneration()

◆ RBRInstrument_getLastHardwareError()

◆ RBRInstrument_getLastHardwareErrorMessage()

◆ RBRInstrument_getUserData()

◆ RBRInstrument_open()

◆ RBRInstrument_setCommandTimeout()

◆ RBRInstrument_setUserData()

◆ RBRInstrumentError_name()

◆ RBRInstrumentGeneration_name()

◆ RBRInstrumentResponseType_name()

Variable Documentation

◆ RBRINSTRUMENT_LIB_BUILD_DATE

◆ RBRINSTRUMENT_LIB_NAME

◆ RBRINSTRUMENT_LIB_VERSION