michael@0: /* michael@0: * smslib.h michael@0: * michael@0: * SMSLib Sudden Motion Sensor Access Library michael@0: * Copyright (c) 2010 Suitable Systems michael@0: * All rights reserved. michael@0: * michael@0: * Developed by: Daniel Griscom michael@0: * Suitable Systems michael@0: * http://www.suitable.com michael@0: * michael@0: * Permission is hereby granted, free of charge, to any person obtaining a michael@0: * copy of this software and associated documentation files (the michael@0: * "Software"), to deal with the Software without restriction, including michael@0: * without limitation the rights to use, copy, modify, merge, publish, michael@0: * distribute, sublicense, and/or sell copies of the Software, and to michael@0: * permit persons to whom the Software is furnished to do so, subject to michael@0: * the following conditions: michael@0: * michael@0: * - Redistributions of source code must retain the above copyright notice, michael@0: * this list of conditions and the following disclaimers. michael@0: * michael@0: * - Redistributions in binary form must reproduce the above copyright michael@0: * notice, this list of conditions and the following disclaimers in the michael@0: * documentation and/or other materials provided with the distribution. michael@0: * michael@0: * - Neither the names of Suitable Systems nor the names of its michael@0: * contributors may be used to endorse or promote products derived from michael@0: * this Software without specific prior written permission. michael@0: * michael@0: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS michael@0: * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF michael@0: * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. michael@0: * IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR michael@0: * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, michael@0: * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE michael@0: * SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. michael@0: * michael@0: * For more information about SMSLib, see michael@0: * michael@0: * or contact michael@0: * Daniel Griscom michael@0: * Suitable Systems michael@0: * 1 Centre Street, Suite 204 michael@0: * Wakefield, MA 01880 michael@0: * (781) 665-0053 michael@0: * michael@0: */ michael@0: michael@0: #import michael@0: michael@0: #define SMSLIB_VERSION "1.8" michael@0: michael@0: #pragma mark Structure definitions michael@0: michael@0: // Structure for specifying a 3-axis acceleration. 0.0 means "zero gravities", michael@0: // 1.0 means "one gravity". michael@0: typedef struct sms_acceleration { michael@0: float x; // Right-left acceleration (positive is rightwards) michael@0: float y; // Front-rear acceleration (positive is rearwards) michael@0: float z; // Up-down acceleration (positive is upwards) michael@0: } sms_acceleration; michael@0: michael@0: // Structure for specifying a calibration. michael@0: typedef struct sms_calibration { michael@0: float zeros[3]; // Zero points for three axes (X, Y, Z) michael@0: float onegs[3]; // One gravity values for three axes michael@0: } sms_calibration; michael@0: michael@0: #pragma mark Return value definitions michael@0: michael@0: // These are the return values for accelStartup(), giving the michael@0: // various stages where the most successful attempt at accessing michael@0: // the accelerometer failed. The higher the value, the further along the michael@0: // software progressed before failing. The options are: michael@0: // - Didn't match model name michael@0: #define SMS_FAIL_MODEL (-7) michael@0: // - Failure getting dictionary matching desired services michael@0: #define SMS_FAIL_DICTIONARY (-6) michael@0: // - Failure getting list of services michael@0: #define SMS_FAIL_LIST_SERVICES (-5) michael@0: // - Failure if list of services is empty. The process generally fails michael@0: // here if run on a machine without a Sudden Motion Sensor. michael@0: #define SMS_FAIL_NO_SERVICES (-4) michael@0: // - Failure if error opening device. michael@0: #define SMS_FAIL_OPENING (-3) michael@0: // - Failure if opened, but didn't get a connection michael@0: #define SMS_FAIL_CONNECTION (-2) michael@0: // - Failure if couldn't access connction using given function and size. This michael@0: // is where the process would probably fail with a change in Apple's API. michael@0: // Driver problems often also cause failures here. michael@0: #define SMS_FAIL_ACCESS (-1) michael@0: // - Success! michael@0: #define SMS_SUCCESS (0) michael@0: michael@0: #pragma mark Function declarations michael@0: michael@0: // This starts up the accelerometer code, trying each possible sensor michael@0: // specification. Note that for logging purposes it michael@0: // takes an object and a selector; the object's selector is then invoked michael@0: // with a single NSString as argument giving progress messages. Example michael@0: // logging method: michael@0: // - (void)logMessage: (NSString *)theString michael@0: // which would be used in accelStartup's invocation thusly: michael@0: // result = accelStartup(self, @selector(logMessage:)); michael@0: // If the object is nil, then no logging is done. Sets calibation from built-in michael@0: // value table. Returns ACCEL_SUCCESS for success, and other (negative) michael@0: // values for various failures (returns value indicating result of michael@0: // most successful trial). michael@0: int smsStartup(id logObject, SEL logSelector); michael@0: michael@0: // This starts up the library in debug mode, ignoring the actual hardware. michael@0: // Returned data is in the form of 1Hz sine waves, with the X, Y and Z michael@0: // axes 120 degrees out of phase; "calibrated" data has range +/- (1.0/5); michael@0: // "uncalibrated" data has range +/- (256/5). X and Y axes centered on 0.0, michael@0: // Z axes centered on 1 (calibrated) or 256 (uncalibrated). michael@0: // Don't use smsGetBufferLength or smsGetBufferData. Always returns SMS_SUCCESS. michael@0: int smsDebugStartup(id logObject, SEL logSelector); michael@0: michael@0: // Returns the current calibration values. michael@0: void smsGetCalibration(sms_calibration *calibrationRecord); michael@0: michael@0: // Sets the calibration, but does NOT store it as a preference. If the argument michael@0: // is nil then the current calibration is set from the built-in value table. michael@0: void smsSetCalibration(sms_calibration *calibrationRecord); michael@0: michael@0: // Stores the current calibration values as a stored preference. michael@0: void smsStoreCalibration(void); michael@0: michael@0: // Loads the stored preference values into the current calibration. michael@0: // Returns YES if successful. michael@0: BOOL smsLoadCalibration(void); michael@0: michael@0: // Deletes any stored calibration, and then takes the current calibration values michael@0: // from the built-in value table. michael@0: void smsDeleteCalibration(void); michael@0: michael@0: // Fills in the accel record with calibrated acceleration data. Takes michael@0: // 1-2ms to return a value. Returns 0 if success, error number if failure. michael@0: int smsGetData(sms_acceleration *accel); michael@0: michael@0: // Fills in the accel record with uncalibrated acceleration data. michael@0: // Returns 0 if success, error number if failure. michael@0: int smsGetUncalibratedData(sms_acceleration *accel); michael@0: michael@0: // Returns the length of a raw block of data for the current type of sensor. michael@0: int smsGetBufferLength(void); michael@0: michael@0: // Takes a pointer to accelGetRawLength() bytes; sets those bytes michael@0: // to return value from sensor. Make darn sure the buffer length is right! michael@0: void smsGetBufferData(char *buffer); michael@0: michael@0: // This returns an NSString describing the current calibration in michael@0: // human-readable form. Also include a description of the machine. michael@0: NSString *smsGetCalibrationDescription(void); michael@0: michael@0: // Shuts down the accelerometer. michael@0: void smsShutdown(void); michael@0: