hal/cocoa/smslib.h

   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);