RBRInstrument.h

Go to the documentation of this file.

 
#ifndef LIBRBR_RBRINSTRUMENT_H
#define LIBRBR_RBRINSTRUMENT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <inttypes.h>
#include <stdbool.h>
#include <stdlib.h>
 
#include "RBRInstrumentHardwareErrors.h"
 
extern const char *RBRINSTRUMENT_LIB_NAME;
extern const char *RBRINSTRUMENT_LIB_VERSION;
extern const char *RBRINSTRUMENT_LIB_BUILD_DATE;
 
#ifndef RBRINSTRUMENT_COMMAND_BUFFER_MAX
#define RBRINSTRUMENT_COMMAND_BUFFER_MAX 120
#endif
 
#ifndef RBRINSTRUMENT_RESPONSE_BUFFER_MAX
#define RBRINSTRUMENT_RESPONSE_BUFFER_MAX 1024
#endif
 
#ifndef RBRINSTRUMENT_CHANNEL_MAX
#define RBRINSTRUMENT_CHANNEL_MAX 32
#endif
 
#define xstr(s) str(s)
 
#define str(s) #s
 
#define RBRINSTRUMENT_CHANNEL_MAX_LEN sizeof(xstr(RBRINSTRUMENT_CHANNEL_MAX))
 
#define RBRINSTRUMENT_CHANNEL_NAME_MAX 31
 
#define RBRINSTRUMENT_CHANNEL_TYPE_MAX 11
 
#define RBRINSTRUMENT_CHANNEL_UNIT_MAX 7
 
#define RBRINSTRUMENT_CHANNEL_LABEL_MAX 31
 
#define RBRINSTRUMENT_DATETIME_MIN  946684800000LL
 
#define RBRINSTRUMENT_DATETIME_MAX 4102444799000LL
 
#define RBRINSTRUMENT_ID_MODEL_MAX 14
 
#define RBRINSTRUMENT_ID_VERSION_MAX 7
 
#define RBRINSTRUMENT_ID_MODE_MAX 10
 
typedef int64_t RBRInstrumentDateTime;
 
typedef int32_t RBRInstrumentPeriod;
 
typedef 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
} RBRInstrumentError;
 
const char *RBRInstrumentError_name(RBRInstrumentError error);
 
typedef struct RBRInstrumentId
{
    char model[RBRINSTRUMENT_ID_MODEL_MAX + 1];
    char version[RBRINSTRUMENT_ID_VERSION_MAX + 1];
    uint32_t serial;
    uint16_t fwtype;
    char mode[RBRINSTRUMENT_ID_MODE_MAX + 1];
} RBRInstrumentId;
 
typedef enum RBRInstrumentGeneration
{
    RBRINSTRUMENT_LOGGER1,
    RBRINSTRUMENT_LOGGER2,
    RBRINSTRUMENT_LOGGER3,
    RBRINSTRUMENT_GENERATION_COUNT,
    RBRINSTRUMENT_UNKNOWN_GENERATION
} RBRInstrumentGeneration;
 
const char *RBRInstrumentGeneration_name(RBRInstrumentGeneration generation);
 
struct RBRInstrument;
 
typedef RBRInstrumentError (*RBRInstrumentTimeCallback)(
    const struct RBRInstrument *instrument,
    RBRInstrumentDateTime *time);
 
typedef RBRInstrumentError (*RBRInstrumentSleepCallback)(
    const struct RBRInstrument *instrument,
    RBRInstrumentDateTime time);
 
typedef RBRInstrumentError (*RBRInstrumentReadCallback)(
    const struct RBRInstrument *instrument,
    void *data,
    int32_t *size);
 
typedef RBRInstrumentError (*RBRInstrumentWriteCallback)(
    const struct RBRInstrument *instrument,
    const void *const data,
    int32_t size);
 
struct RBRInstrumentSample;
 
typedef RBRInstrumentError (*RBRInstrumentSampleCallback)(
    const struct RBRInstrument *instrument,
    const struct RBRInstrumentSample *const sample);
 
typedef struct RBRInstrumentCallbacks
{
    RBRInstrumentTimeCallback time;
 
    RBRInstrumentSleepCallback sleep;
 
    RBRInstrumentReadCallback read;
 
    RBRInstrumentWriteCallback write;
 
    RBRInstrumentSampleCallback sample;
 
    struct RBRInstrumentSample *sampleBuffer;
} RBRInstrumentCallbacks;
 
typedef enum RBRInstrumentResponseType
{
    RBRINSTRUMENT_RESPONSE_INFO,
    RBRINSTRUMENT_RESPONSE_WARNING,
    RBRINSTRUMENT_RESPONSE_ERROR,
    RBRINSTRUMENT_RESPONSE_TYPE_COUNT,
    RBRINSTRUMENT_RESPONSE_UNKNOWN_TYPE
} RBRInstrumentResponseType;
 
const char *RBRInstrumentResponseType_name(RBRInstrumentResponseType type);
 
typedef struct RBRInstrumentResponse
{
    RBRInstrumentResponseType type;
    RBRInstrumentHardwareError error;
    char *response;
} RBRInstrumentResponse;
 
typedef struct RBRInstrument
{
    struct RBRInstrumentId id;
 
    RBRInstrumentGeneration generation;
 
    RBRInstrumentCallbacks callbacks;
 
    RBRInstrumentDateTime commandTimeout;
 
    void *userData;
 
    int32_t commandBufferLength;
 
    int32_t responseBufferLength;
 
    RBRInstrumentDateTime lastActivityTime;
 
    int32_t lastResponseLength;
 
    uint8_t commandBuffer[RBRINSTRUMENT_COMMAND_BUFFER_MAX];
 
    uint8_t responseBuffer[RBRINSTRUMENT_RESPONSE_BUFFER_MAX];
 
    RBRInstrumentResponse response;
 
    bool managedAllocation;
} RBRInstrument;
 
RBRInstrumentError RBRInstrument_open(RBRInstrument **instrument,
                                      const RBRInstrumentCallbacks *callbacks,
                                      RBRInstrumentDateTime commandTimeout,
                                      void *userData);
 
RBRInstrumentError RBRInstrument_close(RBRInstrument *instrument);
 
RBRInstrumentGeneration RBRInstrument_getGeneration(
    const RBRInstrument *instrument);
 
RBRInstrumentDateTime RBRInstrument_getCommandTimeout(
    const RBRInstrument *instrument);
 
void RBRInstrument_setCommandTimeout(RBRInstrument *instrument,
                                     RBRInstrumentDateTime commandTimeout);
 
void *RBRInstrument_getUserData(const RBRInstrument *instrument);
 
void RBRInstrument_setUserData(RBRInstrument *instrument, void *userData);
 
RBRInstrumentHardwareError RBRInstrument_getLastHardwareError(
    const RBRInstrument *instrument);
 
const char *RBRInstrument_getLastHardwareErrorMessage(
    const RBRInstrument *instrument);
 
/* To help keep declarations and documentation organized and discoverable,
 * instrument commands and structures are broken out into individual
 * categorical headers. */
#include "RBRInstrumentCommands.h"
 
#ifdef __cplusplus
}
#endif
 
#endif /* LIBRBR_RBRINSTRUMENT_H */