liblabpro.h

Go to the documentation of this file.

/* liblabpro, a C library for using Vernier LabPro devices.
 * Based on the original FreeLab Ruby implementation by Ben Crowell.
 *
 * * www.lightandmatter.com/freelab
 * * liblabpro.sf.net
 * 
 * Copyright (C) 2018 Matthew Trescott <matthewtrescott@gmail.com>
 * 
 * liblabpro is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * liblabpro is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with liblabpro.  If not, see <http://www.gnu.org/licenses/>.
 * 
 */

#pragma once
#include <stdbool.h>
#include <libusb-1.0/libusb.h>

enum LabPro_Commands {
    LABPRO_RESET                = 0,
    
    LABPRO_CHANNEL_SETUP        = 1,
    
    LABPRO_DATACOLLECT_SETUP    = 3,
    
    LABPRO_CONVERSION_EQN_SETUP = 4,
    
    LABPRO_DATA_CTL             = 5,
    
    LABPRO_SYS_SETUP            = 6,
    LABPRO_SYS_STATUS           = 7,
    
    LABPRO_CHAN_STATUS          = 8,
    
    LABPRO_REQUEST_CHAN_DATA    = 9,
    LABPRO_ADVANCED_DATA_REDUCTION = 10,
    LABPRO_DIGITAL_DATA_CAPTURE = 12,
    
    LABPRO_QUERY_CHANNELS       = 80,
    LABPRO_PORT_POWER_CTL       = 102,
    LABPRO_REQUEST_SETUP_INFO   = 115,
    LABPRO_REQUEST_LONG_SENSOR_NAME = 116,
    LABPRO_REQUEST_SHORT_SENSOR_NAME = 117,
    LABPRO_ARCHIVE              = 201,
    LABPRO_ANALOG_OUT_SETUP     = 401,
    LABPRO_LED_CTL              = 1998,
    LABPRO_SOUND_CTL            = 1999,
    LABPRO_DIGITAL_OUT_CTL      = 2001
};

enum LabPro_Battery_Level {
    LABPRO_BATTERY_OK,
    LABPRO_BATTERY_LOW_WHILE_SAMPLING,
    LABPRO_BATTERY_LOW
};

enum LabPro_Channels {
    LABPRO_CHAN_ALL             = 0,
    LABPRO_CHAN_ANALOG_1        = 1,
    LABPRO_CHAN_ANALOG_2        = 2,
    LABPRO_CHAN_ANALOG_3        = 3,
    LABPRO_CHAN_ANALOG_4        = 4,
    LABPRO_CHAN_SONIC_1         = 11,
    LABPRO_CHAN_SONIC_2         = 12,
    LABPRO_CHAN_DIGITAL_1       = 21,
    LABPRO_CHAN_DIGITAL_2       = 22,
    LABPRO_CHAN_DIGITAL_OUT_1   = 31,
    LABPRO_CHAN_DIGITAL_OUT_2   = 32
};

enum LabPro_Analog_Chan_Operations {
    LABPRO_CHANOP_OFF,
    LABPRO_CHANOP_AUTOID,
    LABPRO_CHANOP_VOLTAGE10V, // Range from -10V to +10V. Same for period, frequency, and transitions ops below.
    LABPRO_CHANOP_CURRENT10A,
    LABPRO_CHANOP_RESISTANCE,
    LABPRO_CHANOP_VOLTAGE10V_PERIOD,
    LABPRO_CHANOP_VOLTAGE10V_FREQUENCY,
    LABPRO_CHANOP_VOLTAGE10V_TRANSITIONS_COUNT,
    LABPRO_CHANOP_TI_TEMP_C = 10,
    LABPRO_CHANOP_TI_TEMP_F = 11,
    LABPRO_CHANOP_TI_LIGHT = 12,
    LABPRO_CHANOP_VOLTAGE_ZERO_TO_FIVE = 14
};

enum LabPro_Sonic_Chan_Operations {
    LABPRO_CHANOP_RESET = 0,
    LABPRO_DISTANCE_AND_DT_METERS = 1,
    LABPRO_DISTANCE_AND_DT_FEET = 3,
    LABPRO_DISTANCE_VELOCITY_AND_DT_METERS = 4,
    LABPRO_DISTANCE_VELOCITY_AND_DT_FEET = 5,
    LABPRO_DISTANCE_VELOCITY_ACCEL_AND_DT_METERS = 6,
    LABPRO_DISTANCE_VELOCITY_ACCEL_AND_DT_FEET = 7
};
enum LabPro_Analog_PostProc {
    LABPRO_POSTPROC_NONE,
    LABPRO_POSTPROC_DERIV1,
    LABPRO_POSTPROC_DERIV1_AND_2
};
enum LabPro_Sampling_Modes {
    LABPRO_SAMPMODE_NON_REALTIME,
    LABPRO_SAMPMODE_REALTIME
};
enum LabPro_System_Status {
    LABPRO_SYSSTATUS_IDLE       = 1,
    LABPRO_SYSSTATUS_ARMED      = 2,
    LABPRO_SYSSTATUS_BUSY       = 3,
    LABPRO_SYSSTATUS_DONE       = 4,
    LABPRO_SYSSTATUS_SELFTEST   = 5,
    LABPRO_SYSSTATUS_INIT       = 99
};

enum LabPro_Errors {
    LABPRO_OK,
    
    LABPRO_ERR_NO_MEM,
    
    LABPRO_ERR_NOT_OPEN,
    
    LABPRO_ERR_BUSY,
    
    LABPRO_ERR_BUSY_COLLECT,
    
    LABPRO_ERR_BUSY_FASTMODE,
    
    LABPRO_ERR_OP_MISMATCH,
    
    LABPRO_ERR_POSTPROC_ON_SONIC,
    
    LABPRO_ERR_POSTPROC_ON_REALTIME
};

enum LabPro_USB_Errors {
    LABPRO_ERR_USB_IO           = LIBUSB_ERROR_IO,
    LABPRO_ERR_USB_ACCESS       = LIBUSB_ERROR_ACCESS,
    LABPRO_ERR_USB_NO_DEVICE    = LIBUSB_ERROR_NO_DEVICE,
    LABPRO_ERR_USB_PIPE         = LIBUSB_ERROR_PIPE,
    LABPRO_ERR_USB_INTERRUPTED  = LIBUSB_ERROR_INTERRUPTED,
    LABPRO_ERR_USB_NO_MEM       = LIBUSB_ERROR_NO_MEM,
    LABPRO_ERR_USB_OTHER        = LIBUSB_ERROR_OTHER
};

typedef struct {
    libusb_context *usb_link;
} LabPro_Context;

typedef struct {
    libusb_device_handle *device_handle;
    
    bool is_open;
    
    bool is_busy;
    
    bool is_fastmode_running;
    
    bool is_collecting_data;
    
    unsigned char in_endpt_addr;
    
    unsigned char out_endpt_addr;
    
    unsigned int timeout;
    
    char software_id[7];
    int errorcode;
    enum LabPro_Battery_Level battery_level;
    
} LabPro;

typedef struct {
    unsigned short num;
    
    LabPro *labpros[5];
} LabPro_List;

typedef struct {
    enum LabPro_Channels channel;
    
    enum LabPro_Analog_Chan_Operations analog_op;
    
    enum LabPro_Sonic_Chan_Operations sonic_op;
    
    enum LabPro_Analog_PostProc postproc;
    
    enum LabPro_Sampling_Modes sampling_mode;
    
    bool use_conversion_eqn;
    char* onboard_conversion_equation;
    bool use_sonic_temp_compensation;
    char* sonic_temp_compensation_equation;
} LabPro_Data_Session;

int LabPro_init(LabPro_Context* context);

void LabPro_exit(LabPro_Context* context);

LabPro_List LabPro_list_labpros(LabPro_Context* context);

void LabPro_close_labpro(LabPro* labpro);

int LabPro_reset(LabPro* labpro, bool force);

int LabPro_check_data_session(LabPro_Data_Session* session, int** errors);

int LabPro_send_raw(LabPro* labpro, char* command, int* length_transferred);

int LabPro_read_raw(LabPro* labpro, char** string, int* length);

int LabPro_trim_response(char* string);

void LabPro_handle_device_disconnect(LabPro* labpro);