smslib.h (6591B)
1 /* 2 * smslib.h 3 * 4 * SMSLib Sudden Motion Sensor Access Library 5 * Copyright (c) 2010 Suitable Systems 6 * All rights reserved. 7 * 8 * Developed by: Daniel Griscom 9 * Suitable Systems 10 * http://www.suitable.com 11 * 12 * Permission is hereby granted, free of charge, to any person obtaining a 13 * copy of this software and associated documentation files (the 14 * "Software"), to deal with the Software without restriction, including 15 * without limitation the rights to use, copy, modify, merge, publish, 16 * distribute, sublicense, and/or sell copies of the Software, and to 17 * permit persons to whom the Software is furnished to do so, subject to 18 * the following conditions: 19 * 20 * - Redistributions of source code must retain the above copyright notice, 21 * this list of conditions and the following disclaimers. 22 * 23 * - Redistributions in binary form must reproduce the above copyright 24 * notice, this list of conditions and the following disclaimers in the 25 * documentation and/or other materials provided with the distribution. 26 * 27 * - Neither the names of Suitable Systems nor the names of its 28 * contributors may be used to endorse or promote products derived from 29 * this Software without specific prior written permission. 30 * 31 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 32 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 33 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 34 * IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR 35 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 36 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 37 * SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. 38 * 39 * For more information about SMSLib, see 40 * <http://www.suitable.com/tools/smslib.html> 41 * or contact 42 * Daniel Griscom 43 * Suitable Systems 44 * 1 Centre Street, Suite 204 45 * Wakefield, MA 01880 46 * (781) 665-0053 47 * 48 */ 49 50 #import <Foundation/Foundation.h> 51 52 #define SMSLIB_VERSION "1.8" 53 54 #pragma mark Structure definitions 55 56 // Structure for specifying a 3-axis acceleration. 0.0 means "zero gravities", 57 // 1.0 means "one gravity". 58 typedef struct sms_acceleration { 59 float x; // Right-left acceleration (positive is rightwards) 60 float y; // Front-rear acceleration (positive is rearwards) 61 float z; // Up-down acceleration (positive is upwards) 62 } sms_acceleration; 63 64 // Structure for specifying a calibration. 65 typedef struct sms_calibration { 66 float zeros[3]; // Zero points for three axes (X, Y, Z) 67 float onegs[3]; // One gravity values for three axes 68 } sms_calibration; 69 70 #pragma mark Return value definitions 71 72 // These are the return values for accelStartup(), giving the 73 // various stages where the most successful attempt at accessing 74 // the accelerometer failed. The higher the value, the further along the 75 // software progressed before failing. The options are: 76 // - Didn't match model name 77 #define SMS_FAIL_MODEL (-7) 78 // - Failure getting dictionary matching desired services 79 #define SMS_FAIL_DICTIONARY (-6) 80 // - Failure getting list of services 81 #define SMS_FAIL_LIST_SERVICES (-5) 82 // - Failure if list of services is empty. The process generally fails 83 // here if run on a machine without a Sudden Motion Sensor. 84 #define SMS_FAIL_NO_SERVICES (-4) 85 // - Failure if error opening device. 86 #define SMS_FAIL_OPENING (-3) 87 // - Failure if opened, but didn't get a connection 88 #define SMS_FAIL_CONNECTION (-2) 89 // - Failure if couldn't access connction using given function and size. 90 // This is where the process would probably fail with a change 91 // in Apple's API. Driver problems often also cause failures here. 92 #define SMS_FAIL_ACCESS (-1) 93 // - Success! 94 #define SMS_SUCCESS (0) 95 96 #pragma mark Function declarations 97 98 // This starts up the accelerometer code, trying each possible sensor 99 // specification. Note that for logging purposes it 100 // takes an object and a selector; the object's selector is then invoked 101 // with a single NSString as argument giving progress messages. Example 102 // logging method: 103 // - (void)logMessage: (NSString *)theString 104 // which would be used in accelStartup's invocation thusly: 105 // result = accelStartup(self, @selector(logMessage:)); 106 // If the object is nil, then no logging is done. Sets calibation from built-in 107 // value table. Returns ACCEL_SUCCESS for success, and other (negative) 108 // values for various failures (returns value indicating result of 109 // most successful trial). 110 int smsStartup(id logObject, SEL logSelector); 111 112 // This starts up the library in debug mode, ignoring the actual hardware. 113 // Returned data is in the form of 1Hz sine waves, with the X, Y and Z 114 // axes 120 degrees out of phase; "calibrated" data has range +/- (1.0/5); 115 // "uncalibrated" data has range +/- (256/5). X and Y axes centered on 0.0, 116 // Z axes centered on 1 (calibrated) or 256 (uncalibrated). 117 // Don't use smsGetBufferLength or smsGetBufferData. Always returns SMS_SUCCESS. 118 int smsDebugStartup(id logObject, SEL logSelector); 119 120 // Returns the current calibration values. 121 void smsGetCalibration(sms_calibration* calibrationRecord); 122 123 // Sets the calibration, but does NOT store it as a preference. If the argument 124 // is nil then the current calibration is set from the built-in value table. 125 void smsSetCalibration(sms_calibration* calibrationRecord); 126 127 // Stores the current calibration values as a stored preference. 128 void smsStoreCalibration(void); 129 130 // Loads the stored preference values into the current calibration. 131 // Returns YES if successful. 132 BOOL smsLoadCalibration(void); 133 134 // Deletes any stored calibration, and then takes the current calibration values 135 // from the built-in value table. 136 void smsDeleteCalibration(void); 137 138 // Fills in the accel record with calibrated acceleration data. Takes 139 // 1-2ms to return a value. Returns 0 if success, error number if failure. 140 int smsGetData(sms_acceleration* accel); 141 142 // Fills in the accel record with uncalibrated acceleration data. 143 // Returns 0 if success, error number if failure. 144 int smsGetUncalibratedData(sms_acceleration* accel); 145 146 // Returns the length of a raw block of data for the current type of sensor. 147 int smsGetBufferLength(void); 148 149 // Takes a pointer to accelGetRawLength() bytes; sets those bytes 150 // to return value from sensor. Make darn sure the buffer length is right! 151 void smsGetBufferData(char* buffer); 152 153 // This returns an NSString describing the current calibration in 154 // human-readable form. Also include a description of the machine. 155 NSString* smsGetCalibrationDescription(void); 156 157 // Shuts down the accelerometer. 158 void smsShutdown(void);