omapi.h

Go to the documentation of this file.

/* 
 * Copyright (c) 2009-2012, Newcastle University, UK.
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met: 
 * 1. Redistributions of source code must retain the above copyright notice, 
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice, 
 *    this list of conditions and the following disclaimer in the documentation 
 *    and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 * POSSIBILITY OF SUCH DAMAGE. 
 */
 
 
 
/*
    @section example_code Example code
    Code examples are included that cover a range of uses of the API.
    See the following files in the "Examples" section:
        -# test     - A command-line tool to self-test all connected devices, and controls the LED to indicate any failures.
        -# deploy   - A command-line tool to batch setup of all fully-charged and cleared devices, includes delayed activation and time synchronization. 
        -# download - A command-line tool to download from all devices that containing data. 
        -# clear    - A command-line tool to clear all attached devices.
        -# convert  - A command-line tool to convert a specified binary data file to a CSV text file.
 
<!--
    A brief overview of each is included below.
    @see \ref introduction
    @see The API header file: omapi.h
 
    \section s_api_init API initialization and device discovery
    \em <b>See main article:</b> \ref api_init
    \copydoc api_init
 
    \section s_device_status Device status
    \em <b>See main article:</b> \ref device_status
    \copydoc device_status
 
    \section s_settings Device settings and metadata
    \em <b>See main article:</b> \ref settings
    \copydoc settings
 
    \section s_download Data download
    \em <b>See main article:</b> \ref data_download
    \copydoc data_download
 
    \section s_return_codes Return codes
    \em <b>See main article:</b> \ref return_codes
    \copydoc return_codes
 
    \section s_datetime Date/time type
    \em <b>See main article:</b> \ref datetime
    \copydoc datetime
 
    \section s_reader Binary data file reader
    \em <b>See main article:</b> \ref reader
    \copydoc reader
-->
 
*/
 
 /* Include guard */
 #ifndef OM_H
 #define OM_H
 
 
/* Plain C for undecorated function names in DLL */
#ifdef __cplusplus
extern "C" {
#endif
 
 
#if defined(_WIN32) && defined(_WINDLL)
    #define OM_EXPORT __declspec(dllexport)         
#elif defined(_WIN32) && defined(OMAPI_DYNLIB_IMPORT)
    #define OM_EXPORT __declspec(dllimport)         
#else
    #define OM_EXPORT                               
#endif
 
#define OM_VERSION 108
 
 
OM_EXPORT int OmStartup(int version);
 
 
OM_EXPORT int OmShutdown(void);
 
 
OM_EXPORT int OmSetLogStream(int fd);
 
 
typedef void(*OmLogCallback)(void *, const char *);
 
 
OM_EXPORT int OmSetLogCallback(OmLogCallback logCallback, void *reference);
 
 
typedef enum
{
    OM_DEVICE_REMOVED,                  
    OM_DEVICE_CONNECTED                 
} OM_DEVICE_STATUS;
 
 
typedef void(*OmDeviceCallback)(void *, int, OM_DEVICE_STATUS);
 
 
OM_EXPORT int OmSetDeviceCallback(OmDeviceCallback deviceCallback, void *reference);
 
 
OM_EXPORT int OmGetDeviceIds(int *deviceIds, int maxDevices);
 
 
/* A single integer value is used to pack the date/time for a simpler, cross-language, API. 
 * (Defined here before its documentation, grouped with the other time functions below)
 */
typedef unsigned long OM_DATETIME;
 
 
 
OM_EXPORT int OmGetVersion(int deviceId, int *firmwareVersion, int *hardwareVersion);
 
 
OM_EXPORT int OmGetDeviceSerial(int deviceId, char *serialBuffer);
 
 
OM_EXPORT int OmGetDevicePort(int deviceId, char *portBuffer);
 
 
OM_EXPORT int OmGetDevicePath(int deviceId, char *pathBuffer);
 
 
OM_EXPORT int OmGetBatteryLevel(int deviceId);
 
 
OM_EXPORT int OmSelfTest(int deviceId);
 
 
OM_EXPORT int OmGetMemoryHealth(int deviceId);
 
#define OM_MEMORY_HEALTH_ERROR   1  
#define OM_MEMORY_HEALTH_WARNING 8  
OM_EXPORT int OmGetBatteryHealth(int deviceId);
 
 
OM_EXPORT int OmGetAccelerometer(int deviceId, int *x, int *y, int *z);
 
 
OM_EXPORT int OmGetTime(int deviceId, OM_DATETIME *time);
 
 
OM_EXPORT int OmSetTime(int deviceId, OM_DATETIME time);
 
 
typedef enum
{
    OM_LED_AUTO = -1,           
    OM_LED_OFF = 0,             
    OM_LED_BLUE = 1,            
    OM_LED_GREEN = 2,           
    OM_LED_CYAN = 3,            
    OM_LED_RED = 4,             
    OM_LED_MAGENTA = 5,         
    OM_LED_YELLOW = 6,          
    OM_LED_WHITE = 7            
} OM_LED_STATE;
 
 
OM_EXPORT int OmSetLed(int deviceId, OM_LED_STATE ledState);
 
 
OM_EXPORT int OmIsLocked(int deviceId, int *hasLockCode);
 
 
OM_EXPORT int OmSetLock(int deviceId, unsigned short code);
 
 
OM_EXPORT int OmUnlock(int deviceId, unsigned short code);
 
 
OM_EXPORT int OmSetEcc(int deviceId, int state);
 
 
OM_EXPORT int OmGetEcc(int deviceId);
 
 
OM_EXPORT int OmCommand(int deviceId, const char *command, char *buffer, size_t bufferSize, const char *expected, unsigned int timeoutMs, char **parseParts, int parseMax);
 
 
OM_EXPORT int OmGetDelays(int deviceId, OM_DATETIME *startTime, OM_DATETIME *stopTime);
 
 
OM_EXPORT int OmSetDelays(int deviceId, OM_DATETIME startTime, OM_DATETIME stopTime);
 
 
OM_EXPORT int OmGetSessionId(int deviceId, unsigned int *sessionId);
 
 
OM_EXPORT int OmSetSessionId(int deviceId, unsigned int sessionId);
 
 
#define OM_METADATA_SIZE 448
 
 
OM_EXPORT int OmGetMetadata(int deviceId, char *metadata);
 
 
OM_EXPORT int OmSetMetadata(int deviceId, const char *metadata, int size);
 
 
OM_EXPORT int OmGetLastConfigTime(int deviceId, OM_DATETIME *time);
 
 
typedef enum
{
    OM_ERASE_NONE = 0,                  
    OM_ERASE_DELETE = 1,                
    OM_ERASE_QUICKFORMAT = 2,           
    OM_ERASE_WIPE = 3                   
} OM_ERASE_LEVEL;
 
 
OM_EXPORT int OmEraseDataAndCommit(int deviceId, OM_ERASE_LEVEL eraseLevel);
 
 
#define OmClearDataAndCommit(_deviceId) OmEraseDataAndCommit((_deviceId), OM_ERASE_QUICKFORMAT)
 
 
#define OmCommit(_deviceId) OmEraseDataAndCommit((_deviceId), OM_ERASE_NONE)
 
 
#define OM_ACCEL_DEFAULT_RATE 100
 
 
#define OM_ACCEL_DEFAULT_RANGE 8
 
 
OM_EXPORT int OmGetAccelConfig(int deviceId, int *rate, int *range);
 
 
OM_EXPORT int OmSetAccelConfig(int deviceId, int rate, int range);
 
 
OM_EXPORT int OmGetMaxSamples(int deviceId, int *value);
 
 
OM_EXPORT int OmSetMaxSamples(int deviceId, int value);
 
 
 
#define OM_MAX_PATH (256)
 
 
typedef enum
{
    OM_DOWNLOAD_NONE,                   
    OM_DOWNLOAD_ERROR,                  
    OM_DOWNLOAD_PROGRESS,               
    OM_DOWNLOAD_COMPLETE,               
    OM_DOWNLOAD_CANCELLED,              
} OM_DOWNLOAD_STATUS;
 
 
typedef void(*OmDownloadCallback)(void *, int, OM_DOWNLOAD_STATUS, int);
 
 
typedef void(*OmDownloadChunkCallback)(void *, int, void *, int, int);
 
 
OM_EXPORT int OmSetDownloadCallback(OmDownloadCallback downloadCallback, void *reference);
 
 
OM_EXPORT int OmSetDownloadChunkCallback(OmDownloadChunkCallback downloadChunkCallback, void *reference);
 
 
OM_EXPORT int OmGetDataFileSize(int deviceId);
 
 
OM_EXPORT int OmGetDataFilename(int deviceId, char *filenameBuffer);
 
 
OM_EXPORT int OmGetDataRange(int deviceId, int *dataBlockSize, int *dataOffsetBlocks, int *dataNumBlocks, OM_DATETIME *startTime, OM_DATETIME *endTime);
 
 
OM_EXPORT int OmBeginDownloading(int deviceId, int dataOffsetBlocks, int dataLengthBlocks, const char *destinationFile);
 
 
OM_EXPORT int OmBeginDownloadingReference(int deviceId, int dataOffsetBlocks, int dataLengthBlocks, const char *destinationFile, void *reference);
 
 
OM_EXPORT int OmQueryDownload(int deviceId, OM_DOWNLOAD_STATUS *downloadStatus, int *downloadValue);
 
 
OM_EXPORT int OmWaitForDownload(int deviceId, OM_DOWNLOAD_STATUS *downloadStatus, int *downloadValue);
 
 
OM_EXPORT int OmCancelDownload(int deviceId);
 
#define OM_TRUE                     1       
#define OM_FALSE                    0       
#define OM_OK                       0       
#define OM_E_FAIL                   -1      
#define OM_E_UNEXPECTED             -2      
#define OM_E_NOT_VALID_STATE        -3      
#define OM_E_OUT_OF_MEMORY          -4      
#define OM_E_INVALID_ARG            -5      
#define OM_E_POINTER                -6      
#define OM_E_NOT_IMPLEMENTED        -7      
#define OM_E_ABORT                  -8      
#define OM_E_ACCESS_DENIED          -9      
#define OM_E_INVALID_DEVICE         -10     
#define OM_E_UNEXPECTED_RESPONSE    -11     
#define OM_E_LOCKED                 -12     
#define OM_SUCCEEDED(value) ((value) >= 0)  
#define OM_FAILED(value) ((value) < 0)      
OM_EXPORT const char *OmErrorString(int status);
 
/*typedef unsigned long OM_DATETIME;*/  /* (defined earlier in the file) */
 
#define OM_DATETIME_FROM_YMDHMS(year, month, day, hours, minutes, seconds) \
                ( (((OM_DATETIME)((year) % 100) & 0x3f) << 26) \
                | (((OM_DATETIME)(month)        & 0x0f) << 22) \
                | (((OM_DATETIME)(day)          & 0x1f) << 17) \
                | (((OM_DATETIME)(hours)        & 0x1f) << 12) \
                | (((OM_DATETIME)(minutes)      & 0x3f) <<  6) \
                | (((OM_DATETIME)(seconds)      & 0x3f)      ) \
                )
#define OM_DATETIME_YEAR(dateTime)    ((unsigned int)((unsigned char)(((dateTime) >> 26) & 0x3f)) + 2000) 
#define OM_DATETIME_MONTH(dateTime)   ((unsigned char)(((dateTime) >> 22) & 0x0f))  
#define OM_DATETIME_DAY(dateTime)     ((unsigned char)(((dateTime) >> 17) & 0x1f))  
#define OM_DATETIME_HOURS(dateTime)   ((unsigned char)(((dateTime) >> 12) & 0x1f))  
#define OM_DATETIME_MINUTES(dateTime) ((unsigned char)(((dateTime) >>  6) & 0x3f))  
#define OM_DATETIME_SECONDS(dateTime) ((unsigned char)(((dateTime)      ) & 0x3f))  
#define OM_DATETIME_MIN_VALID OM_DATETIME_FROM_YMDHMS(2000,  1,  1,  0, 0,   0)     
#define OM_DATETIME_MAX_VALID OM_DATETIME_FROM_YMDHMS(2063, 12, 31, 23, 59, 59)     
#define OM_DATETIME_ZERO (0)                                                        
#define OM_DATETIME_INFINITE ((OM_DATETIME)-1)                                      
#define OM_DATETIME_BUFFER_SIZE (20)
 
OM_EXPORT OM_DATETIME OmDateTimeFromString(const char *value);
 
//#define OmDateTimeToString(value, buffer) (((value) < OM_DATETIME_MIN_VALID) ? "0" : (((value) > OM_DATETIME_MAX_VALID) ? "-1" : (sprintf(buffer, "%04u-%02u-%02u %02u:%02u:%02u", OM_DATETIME_YEAR(value), OM_DATETIME_MONTH(value), OM_DATETIME_DAY(value), OM_DATETIME_HOURS(value), OM_DATETIME_MINUTES(value), OM_DATETIME_SECONDS(value)), buffer)))
OM_EXPORT char *OmDateTimeToString(OM_DATETIME value, char *buffer);
 
 
typedef void * OmReaderHandle;
 
 
#define OM_MAX_SAMPLES (120)
 
 
#define OM_MAX_HEADER_SIZE (2 * 512)
 
 
#define OM_MAX_DATA_SIZE (512)
 
 
OM_EXPORT OmReaderHandle OmReaderOpen(const char *binaryFilename);
 
 
OM_EXPORT int OmReaderDataRange(OmReaderHandle reader, int *dataBlockSize, int *dataOffsetBlocks, int *dataNumBlocks, OM_DATETIME *startTime, OM_DATETIME *endTime);
 
 
OM_EXPORT const char *OmReaderMetadata(OmReaderHandle reader, int *deviceId, unsigned int *sessionId);
 
 
OM_EXPORT int OmReaderDataBlockPosition(OmReaderHandle reader);
 
 
OM_EXPORT int OmReaderDataBlockSeek(OmReaderHandle reader, int dataBlockNumber);
 
 
OM_EXPORT int OmReaderNextBlock(OmReaderHandle reader);
 
 
OM_EXPORT short *OmReaderBuffer(OmReaderHandle reader);
 
 
OM_EXPORT OM_DATETIME OmReaderTimestamp(OmReaderHandle reader, int index, unsigned short *fractional);
 
 
typedef enum
{
    OM_VALUE_DEVICEID = 3, 
    OM_VALUE_SESSIONID = 4, 
    OM_VALUE_SEQUENCEID = 5, 
    OM_VALUE_LIGHT = 7,                 
    OM_VALUE_TEMPERATURE = 8,           
    OM_VALUE_EVENTS = 9, 
    OM_VALUE_BATTERY = 10, 
    OM_VALUE_SAMPLERATE = 11,
    OM_VALUE_LIGHT_LOG10LUXTIMES10POWER3 = 107, 
    OM_VALUE_TEMPERATURE_MC = 108,      
    OM_VALUE_BATTERY_MV = 110,
    OM_VALUE_BATTERY_PERCENT = 210,
    OM_VALUE_AXES = 12,                 
    OM_VALUE_SCALE_ACCEL = 13,          
    OM_VALUE_SCALE_GYRO = 14,           
    OM_VALUE_SCALE_MAG = 15,            
    OM_VALUE_ACCEL_AXIS = 16,           
    OM_VALUE_GYRO_AXIS = 17,            
    OM_VALUE_MAG_AXIS = 18,             
} OM_READER_VALUE_TYPE;
 
 
OM_EXPORT int OmReaderGetValue(OmReaderHandle reader, OM_READER_VALUE_TYPE valueType);
 
 
#pragma pack(push, 1)
typedef struct
{
    unsigned short packetHeader;        
    unsigned short packetLength;        
    unsigned char reserved1;            
    unsigned short deviceId;            
    unsigned int sessionId;             
    unsigned short reserved2;           
    OM_DATETIME loggingStartTime;       
    OM_DATETIME loggingEndTime;         
    unsigned int loggingCapacity;       
    unsigned char reserved3[11];        
    unsigned char samplingRate;         
    unsigned int lastChangeTime;        
    unsigned char firmwareRevision;     
    signed short timeZone;              
    unsigned char reserved4[20];        
    unsigned char annotation[OM_METADATA_SIZE]; 
    unsigned char reserved[512];        
} OM_READER_HEADER_PACKET;
#pragma pack(pop)
 
 
OM_EXPORT OM_READER_HEADER_PACKET *OmReaderRawHeaderPacket(OmReaderHandle reader);
 
 
#pragma pack(push, 1)
typedef struct
{
    unsigned short packetHeader;        
    unsigned short packetLength;        
    unsigned short deviceFractional;    
    unsigned int sessionId;             
    unsigned int sequenceId;            
    OM_DATETIME timestamp;              
    unsigned short light;               
    unsigned short temperature;         
    unsigned char  events;              
    unsigned char  battery;             
    unsigned char  sampleRate;          
    unsigned char  numAxesBPS;          
    signed short   timestampOffset;     
    unsigned short sampleCount;         
    unsigned char rawSampleData[480];   
    unsigned short checksum;            
} OM_READER_DATA_PACKET;
#pragma pack(pop)
 
 
OM_EXPORT OM_READER_DATA_PACKET *OmReaderRawDataPacket(OmReaderHandle reader);
 
 
OM_EXPORT void OmReaderClose(OmReaderHandle reader);
 
#ifdef __cplusplus
}
#endif
 
 
#endif