Wahoo Fitness API  3.6.1
Documentation for the iPhone version of the Wahoo Fitness API.
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Pages
api_docs.h
Go to the documentation of this file.
1 /*
2  * api_docs.h
3  * WFConnector
4  *
5  * Created by Michael Moore on 1/27/11.
6  * Copyright 2011 Wahoo Fitness. All rights reserved.
7  *
8  */
9 
784 /*
786  *
787  * Welcome to the <b>Wahoo Fitness API Documentation</b>. The primary class of
788  * the API is the WFHardwareConnector. It provides a bridge between the
789  * application and the underlying fisica hardware. The WFHardwareConnector
790  * enables the developer to configure the fisica hardware and retrieve data
791  * from available ANT+ sensors.
792  * <p>
793  *
794  * For example usage, please review the Fisica Demo application, available from
795  * Wahoo Fitness. This application demonstrates the basic configuration and
796  * usage of the WFHardwareConnector.
797  * <p>
798  *
799  * The Wahoo Fitness API documentation can be integrated into Xcode.
800  * Documentation for classes and methods can be accessed by right-clicking the
801  * identifier and selecting <b>Find Text in Documentation</b>. To configure
802  * Xcode to use the Wahoo Fitness API documentation, take the following steps:
803  * <ol>
804  * <li>Open Xcode Preferences.</li>
805  * <li>Select the <b>Documentation</b> tab.</li>
806  * <li>Click the <b>Add Documentation Set Publisher...</b> button.</li>
807  * <li>Enter &nbsp;
808  * @if AntFSMode <b>http://api.wahoofitness.com/wf_api/wf_api_antfs.xml</b>
809  * @elseif AntMode <b>http://api.wahoofitness.com/wf_api/wf_api_ant.xml</b>
810  * @else <b>http://api.wahoofitness.com/wf_api/wf_api.xml</b> @endif &nbsp;
811  * into the URL Field.</li>
812  * <li>Click the <b>OK</b> button.
813  * <li>Click the <b>Get</b> button next to the <b>Wahoo Fitness API Documentation</b> item in the list.</li>
814  * <li>Xcode should download and install the Wahoo Fitness API.</li>
815  * </ol>
816  * <p>
817  * Below you will find reqired project settings and the release notes for the
818  * lastest version of the API, as
819  * well as previous versions. The release notes are in descending order, with
820  * the latest at the top. Changes in later versions will supercede changes
821  * made in previous versions. Changes which will break code written against
822  * previous API versions are noted in the "BREAKING CHANGES" section. If you
823  * are currently using an API version older than the last release, please
824  * review the breaking changes between your version and the current version.
825  * <br /><br /><br /><br />
826  *
827  *
828  *
829  * <h1>Required Project Settings</h1>
830  * <h3>Project Settings</h3>
831  * The following values must be added to the <b>Other Linker Flags</b> key
832  * in the <b>Linker</b> section of the project settings for all configurations
833  * of any project build against the Wahoo Fitness API:
834  * <b>-lstdc++ @ifnot base_api &nbsp;-all_load @endif</b>.
835  * <br /><br />
836  * Three builds of the API are provided in the distribution package (Debug, Release and Simulator).
837  * In order for Xcode to link to the proper API library, the following value must be entered
838  * into the <b>Library Search Paths</b> key:
839  * <b>../WFConnector/\$(CONFIGURATION)\$(EFFECTIVE_PLATFORM_NAME)</b>. Xcode
840  * will expand the macro to the appropriate build configuration. This
841  * setting should be added (same value) for all configurations. The
842  * <b>../WFConnector</b> portion of the path indicates the relative path to
843  * the root folder of the API distribution. This may be changed to the
844  * appropriate location if the API distribution is not on the same level
845  * as the root project folder. This setting should not be overridden at
846  * the target setting level. By default, Xcode will add a path to a
847  * specific build when adding the API library to the target. This target
848  * level setting should be deleted.
849  * <br /><br />
850  * The distribution builds consist of the following:
851  * <br />
852  * <ul>
853  * <li>Debug-iphoneos - Built against the iOS SDK with debug symbols and no optimizations.</li>
854  * <li>Release-iphoneos - Built against the iOS SDK with optimizations and no debug symbols.</li>
855  * <li>Debug-iphonesimulator - Built against the simulator SDK.</li>
856  * </ul>
857  * Any build folder can be copied and renamed to accomodate a specific project
858  * configuration. For example, if the project contains a <b>Distribution</b>
859  * configuration, the <b>Release-iphoneos</b> folder can be copied to
860  * <b>Distribution-iphoneos</b>. When the <b>Distribution</b> configuration
861  * is built, Xcode will then link the API library in the
862  * <b>Distribution-iphoneos</b> folder.
863  *
864  * @image html project_settings2.png "Project Settings Screen Shot"
865  * <p>
866  *
867  * <h3>Application Bundle Settings</h3>
868  * The following values must be added to the info.plist for the application:
869  * Key: <b>Supported external accessory protocols</b>,
870  * Value: <b>com.momentumoftechnology.fisica</b>. The name of this key
871  * is dependent on the bundle plist version. It is recommended that the entire
872  * key be copied directly from the Fisica Demo project distributed with the API.
873  *
874  * @image html info.png "Bundle Settings Screen Shot"
875  * <br /><br /><br /><br />
876  *
877  *
878  *
879  *
880  *
881  * <h1>Wahoo Fitness API v2.0 Release Notes</h1>
882  * <h2>BREAKING CHANGES</h2>
883  * Up until this release, we have endeavored to keep breaking changes to a
884  * minimum. However, the additions to this release required a major revision of
885  * the architecture. We apologize for the inconvenience. We hope the
886  * improvements will be worth the trouble of upgrading.
887  *
888  * <h3>Overview of Changes</h3>
889  * <ul>
890  * <li>The WFHardwareConnector singleton is now enforced. It is available through
891  * the WFHardwareConnector::sharedConnector method.</li>
892  *
893  * <li>All sensor connections are now managed through the WFSensorConnection
894  * object. An instance is obtained via the WFHardwareConnector::requestSensorConnection:
895  * method.</li>
896  *
897  * <li>WFSensorConnection and WFConnectionParams facilitate sensor pairing and
898  * connecting to previously paired sensors. Up to four previously paird sensors
899  * may be specified in the connection request. The API will connect to the
900  * first available of the specified devices.
901  *
902  * <li>WFSensorConnection derived classes now provide access to sensor-specific
903  * commands. For example, the WFBikePowerConnection::setBikePowerCalibration:
904  * method provides a way for the application to set the calibration on the
905  * Bike Power sensor.</li>
906  *
907  * <li>Sensor data is now provided in the WFSensorData derived classes.
908  * Instances are obtained through the WFSensorConnection::getData method.</li>
909  * </ul>
910  * <br /><br /><br /><br /><br />
911  *
912  *
913  *
914  *
915  *
916  * <h1>Wahoo Fitness API v1.6 Release Notes</h1>
917  * <h2>BREAKING CHANGES</h2>
918  * <h3>Renamed Data Types</h3>
919  * The following data types were renamed in this release:
920  * <br >
921  * <ul>
922  * <li>The WFHardwareConnectorState type was renamed to ::WFHardwareConnectorState_t.</li>
923  * <li>The WF_SENSORTYPE_BLOODPRESSURE value was renamed to ::WF_SENSORTYPE_ANT_FS.</li>
924  * </ul>
925  * <p>
926  * <h3>Removed Methods</h3>
927  * The deprecated WFHardwareConnectorDelegate::hardwareConnector:connectionStatus: method
928  * was removed.
929  * <br /><br /><br />
930  *
931  * <h2>BUG FIXES</h2>
932  * <h3>Hang when disconnecting sensor</h3>
933  * In certain situations, the WFHardwareConnector would continue to process data messages
934  * after a request to disconnect the sensor was issued. This would cause the disconnect
935  * to fail. This is fixed in this release.
936  * <h3>Methods returning <c>BOOL</c></h3>
937  * Several of the methods which return <c>BOOL</c> returned a value which did not conform
938  * to the <c>BOOL</c> type. This could cause erroneous results when using the return
939  * value in a comparison. This has been fixed.
940  * <br /><br /><br />
941  *
942  * <h2>ADDITIONS AND MODIFICATIONS</h2>
943  * <h3>New Methods</h3>
944  * The following methods were added in this release:
945  * <br />
946  * <ul>
947  * <li>Added WFHardwareConnector::disconnectSensorsOfType:</li>
948  * <li>Added WFHardwareConnector::setSampleTimerDataCheck:</li>
949  * <li>Added WFHardwareConnector::availableChannelCount:</li>
950  * <li>Added WFHardwareConnector::getStateForSensorType:</li>
951  * <li>Added WFHardwareConnector::resetAllSensorData</li>
952  * <li>Added WFHardwareConnector::prepareForBackground</li>
953  * <li>Added WFHardwareConnector::returnFromBackground</li>
954  * <li>Added WFHardwareConnector::setBikePowerCalibrationOffset:</li>
955  * </ul>
956  * <p>
957  * <h3>Additions to Sensor Data Structures</h3>
958  * The following additions were made to the sensor data structures:
959  * <br />
960  * <ul>
961  * <li>Added timestamp and timestampOverflow to all sensor data structures.</li>
962  * <li>Added WFHeartrateData::accumBeatCount</li>
963  * <li>Added WFBikePowerWheelTorqueData::accumulatedWheelTicks</li>
964  * <li>Added WFBikePowerCrankTorqueData::accumulatedCrankTicks</li>
965  * <li>Added ::WFBikePowerType_t type</li>
966  * <li>Added WFBikePowerData::sensorType</li>
967  * <li>Added WFBikePowerWheelTorqueData::wheelRPM</li>
968  * <li>Added WFBikePowerWheelTorqueData::calculatedCrankTicks</li>
969  * <li>Added WFBikePowerCTFData::accumulatedTorque</li>
970  * <li>Added WFBikePowerCTFData::accumulatedCrankTicks</li>
971  * <li>Added WFBikePowerGenericData_t type</li>
972  * </ul>
973  * <p>
974  * <h3>Data Type Modifications to Sensor Data Structures</h3>
975  * The following modifications were made to data types in sensor data structures:
976  * <br />
977  * <ul>
978  * <li>Added WFBikePowerWheelTorqueData::accumulatedTorque was changed to <c>float</c> type.</li>
979  * <li>Added WFBikePowerCrankTorqueData::accumulatedTorque was changed to <c>float</c> type.</li>
980  * </ul>
981  * <p>
982  * <h3>ANT+ Calorimeter Profile</h3>
983  * This release adds support for the beta version of the ANT+ calorimeter
984  * profile. See the WFHardwareConnector::getCalorieData: method and the
985  * ::WFCalorieData structure for usage details.
986  * @if AntFSMode
987  * <p>
988  * <h3>A&D Medical Pedometer Now Supported</h3>
989  * Support was added for the A&D pedometer. See the WFPedometerManager class
990  * for usage details.
991  * @endif
992  * <br /><br /><br />
993  *
994  * <h2>IPHONE OS 4.0</h2>
995  * <h3>Background Mode</h3>
996  * Beginning in iOS 4.0, applications can be run in the background. This
997  * is not entirely true. Background operations are limited to a few services
998  * provided by the iOS. Otherwise, the application is suspended. It is
999  * kept in memory, but no processing is performed. At this time, Apple does
1000  * not allow an attached accessory (such as the fisica key) to continue
1001  * communication with the application. In the previous release notes, it was
1002  * indicated that the Wahoo Fitness API had been tested and confirmed working
1003  * in the following cases:
1004  * <br />
1005  * <ul>
1006  * <li>Top-lock button is pressed.</li>
1007  * <li>User answers an incoming phone call.</li>
1008  * <li>Incoming SMS pop-up message is dismissed (without replying).</li>
1009  * <li>User accesses iPod controls (without opening full iPod app).</li>
1010  * </ul>
1011  * It turns out that this was incorrect. More detailed tests determined what
1012  * occurs when the top-lock is pressed or a phone call is answered. When the
1013  * incoming call screen or incoming SMS popup is displayed, the application
1014  * receives the applicationWillResignActive message. This indicates that
1015  * the application may be about to enter background mode. If the user
1016  * answers the phone call, or chooses to view the SMS, or presses the top-lock
1017  * button, the application will receive the applicationDidEnterBackground after
1018  * 15 seconds. The bottom line is that if the application is resumed within 15
1019  * seconds, there is no background mode, and no interruption of normal operation
1020  * of the API. After 15 seconds, the application enters background and the
1021  * accessory (fisica key) is disconnected.
1022  *
1023  * Although Apple does not allow communication with the accessory to
1024  * continue in background mode at this time, there may be a workaround to
1025  * keep the data flowing. If a workaround is discovered, or if Apple changes
1026  * the background mode policy, we will post an update.
1027  * <br /><br /><br /><br /><br />
1028  *
1029  *
1030  *
1031  * <h1>Wahoo Fitness API v1.5 Release Notes</h1>
1032  * <h2>BREAKING CHANGES</h2>
1033  * <h3>Method Signature Modifications</h3>
1034  * The signature of the WFHardwareConnector::isSensorConnected:isSearching:
1035  * method was changed in this version to add the status of sensors in "search"
1036  * mode. This is where a connection request has been initiated, but
1037  * communication has not yet been established. The previous version of this
1038  * method would return <c>TRUE</c> only when communication to the sensor had been
1039  * established. Adding <code>isSearching:nil</code> to the previous version
1040  * method call should preform the same as in previous versions, and allow
1041  * existing code to build. To check for a sensor in search mode, pass a pointer
1042  * to a boolean variable.
1043  * <p>
1044  * <h3>Firmware Version</h3>
1045  * The WFHardwareConnector initialization routine in this version requires
1046  * fisica device firmware version 0.9.1 or higher. Devices with earlier
1047  * firmware version will perform unpredictably, at best. If your device
1048  * has an earlier version of the firmware, please contact Wahoo Fitness
1049  * for information about upgrading.
1050  * <br /><br /><br />
1051  *
1052  * <h2>BUG FIXES</h2>
1053  * <h3>Connect Sensor Issue</h3>
1054  * Previous version of the API had an issue where calling
1055  * WFHardwareConnector::connectSensorType:withId: would return success when
1056  * the fisica device was not connected. The enum value
1057  * <c>WF_CONNECT_DEVICE_WRONG_HW_STATE</c> value was added to the
1058  * <c>WFConnectDeviceResult_t</c> enum to handle this situation.
1059  * <h3>Data Notification</h3>
1060  * In previous versions of the API, the
1061  * WFHardwareConnectorDelegate::hardwareConnector:hasData: method was invoked
1062  * at the sample rate regardless of whether new data was avaliable. This has
1063  * been fixed such that the method is invoked only when new data is available
1064  * for one or more of the connected sensors.
1065  * <br /><br /><br />
1066  *
1067  * <h2>ADDITIONS AND MODIFICATIONS</h2>
1068  * <h3>Deprecated Methods</h3>
1069  * The WFHardwareConnectorDelegate::hardwareConnector:connectionStatus: method
1070  * is deprecated in version 1.5 of the API. This method will be removed in the
1071  * next release. Existing code should be modified to use the
1072  * WFHardwareConnectorDelegate::hardwareConnector:stateChanged: method instead.
1073  * This method will provide more information about the current state of the
1074  * WFHardwareConnector. When implementing this method, checking the
1075  * ::WF_HWCONN_STATE_ACTIVE bit of the
1076  * <i>currentState</i> parameter will provide the same information that the
1077  * <i>connected</i> parameter of the
1078  * WFHardwareConnectorDelegate::hardwareConnector:connectionStatus: method
1079  * provides. For example:
1080  * <br /><br />
1081  * <code>
1082  * (void)hardwareConnector:(_WFHardwareConnector*)hwConnector connectionStatus:(BOOL)connected
1083  * <br />
1084  * {
1085  * <br />
1086  * &nbsp;&nbsp;BOOL isDeviceConnected = connected; // this value is the same as...
1087  * <br />
1088  * }
1089  * <br />
1090  * <br />
1091  * (void)hardwareConnector:(_WFHardwareConnector*)hwConnector stateChanged:(WFHardwareConnectorState_t)currentState
1092  * <br />
1093  * {
1094  * <br />
1095  * &nbsp;&nbsp;BOOL isDeviceConnected = (currentState & WF_HWCONN_STATE_ACTIVE); // ...this value.
1096  * <br />
1097  * }
1098  * </code>
1099  * <p>
1100  * <h3>New Methods</h3>
1101  * The WFHardwareConnector::currentState method was added to provide
1102  * information about the state of the WFHardwareConnector.
1103  * <p>
1104  * <h3>Delegate Methods</h3>
1105  * All methods in the WFHardwareConnectorDelegate protocol have now been
1106  * implemented as \@optional. This allows the developer to implement only
1107  * the delegate methods which are needed by the application. This change
1108  * should not affect existing code.
1109  * <br /><br /><br />
1110  *
1111  * <h2>IPHONE OS 4.0</h2>
1112  * <h3>Supported Platforms</h3>
1113  * Version 1.5 of the Wahoo Fitness API is built against iPhone SDK 4.0. The
1114  * target device family is iPhone/iPad, and the OS Deployment Target is iPhone
1115  * OS 3.0. Therefore, the API should build with any application project
1116  * targeting iPhone or iPad with iOS version 3.0 or higher. It has been tested
1117  * with iPhone devices running iOS 3.1.2, 3.1.3 and 4.0, as well as the iPad.
1118  * There is no internal code or methods on the public interface which use
1119  * features specific to the iOS 4.0 SDK.
1120  * <p>
1121  * <h3>Background Mode</h3>
1122  * The iPhone OS 4.0 introduced the ability for applications to run in the
1123  * background. Support for background processing is somewhat limited, and the
1124  * resources available are few. An application which enters background mode
1125  * is typically suspended, and no processing is performed. A select set of
1126  * services may be requested by the application, which when available and
1127  * granted are allowed to be processed in the background. The service which
1128  * is most useful to users of the Wahoo Fitness API is likely the Location
1129  * service. An application may request to have the Location service
1130  * deliver updates while in background mode.
1131  * <br /><br />
1132  * Unfortunately, though receiving Location service updates may keep the
1133  * application from being suspended while in the background, it will not enable
1134  * access to external accessories. At this time, Apple does not provide access
1135  * to external accessories while in the background. So, while the API may be
1136  * accessed from an application running in the background, it will behave the
1137  * same as if the fisica key were not inserted. Therefore, no sensor
1138  * connections or data updates will be available while in the background.
1139  * <br /><br />
1140  * When the application enters background mode, the OS will notify the API that
1141  * the external accessory is not longer available. The API will then invoke
1142  * the WFHardwareConnectorDelegate::hardwareConnector:stateChanged: method
1143  * to inform the application that the fisica key was disconnected.
1144  * (The WFHardwareConnectorDelegate::hardwareConnector:connectionStatus: method
1145  * is also invoked, though this method was deprecated in this API version and
1146  * will not be supported in future API releases). When the application is
1147  * resumed from background, the API will invoke
1148  * the WFHardwareConnectorDelegate::hardwareConnector:stateChanged: method
1149  * again to inform the application that the fisica key is connected (assuming
1150  * that the key is still physically connected to the iPhone).
1151  * <br /><br />
1152  * The Wahoo Fitness API has been tested and confirmed to perform normally
1153  * (connections maintained, and data updated), in several common cases:
1154  * <br />
1155  * <ul>
1156  * <li>Top-lock button is pressed.</li>
1157  * <li>User answers an incoming phone call.</li>
1158  * <li>Incoming SMS pop-up message is dismissed (without replying).</li>
1159  * <li>User accesses iPod controls (without opening full iPod app).</li>
1160  * </ul>
1161  * <br /><br /><br /><br /><br />
1162  *
1163  *
1164  *
1165  * <h1>Wahoo Fitness API v1.4 Release Notes</h1>
1166  * <h2>BREAKING CHANGES</h2>
1167  * There are a few changes to this version of the API
1168  * which will break code written against previous versions.
1169  * <p>
1170  * <h3>Project Settings</h3>
1171  * The following values must be added to the <b>Other Linker Flags</b> field
1172  * in the <b>Linker</b> section of the project settings for all configurations
1173  * of any project build against this version of the API:
1174  * <b>-lstdc++ -all_load</b>.
1175  * @image html project_settings.png "Project Settings Screen Shot"
1176  * <p>
1177  * <h3>Header Files</h3>
1178  * The header file <b>power_types.h</b> from previous version of the API has
1179  * been renamed to <b>wf_ant_types.h</b>. There were slight modifications and
1180  * additions to this file, but renaming any references should be all that is
1181  * required for existing code to build.
1182  * <p>
1183  * <h3>Firmware Version</h3>
1184  * Although older versions of the fisica prototype hardware should work with
1185  * the new API, there may be cases in which performance becomes unpredictable.
1186  * If you have an older hardware version and experience unpredictable behavior,
1187  * please contact Wahoo Fitness about obtaining an updated prototype.
1188  * <p>
1189  * <h3>Advanced ANT Mode</h3>
1190  * @if AntMode
1191  * Advanced ANT Mode now requires including the headers
1192  * WFHardwareConnector+AntMode.h and WFAntReceiverDelegate.h. The method
1193  * signature for the WFHardwareConnector::initializeAdvancedMode: method has
1194  * been changed to include a parameter for a WFAntReceiverDelegate which will
1195  * receive the ANT messages.
1196  *
1197  * @else
1198  * The advanced ANT Mode is no longer available in the public API. This
1199  * functionallity is not required in the majority of applications written
1200  * against the API. To keep things clean and less confusing, the advanced
1201  * ANT mode was removed. If your application uses this functionallity,
1202  * please contact Wahoo Fitness. We can provide you with the appropriate
1203  * code and documentation to enable this feature.
1204  * @endif
1205  * <br /><br /><br />
1206  *
1207  * <h2>BUG FIXES</h2>
1208  * Previous versions of the API had a bug concerning the device ID number. The
1209  * API was internally storing the ID as an 8-bit integer rather than the
1210  * 16-bit integer required. The WFHardwareConnector::getDeviceId: method
1211  * should now perform as expected.
1212  * <br /><br />
1213  * Projects built aginst previous versions of the API would generate several
1214  * compiler warnings due to the configuration of the API header files. The
1215  * header files were fixed to eliminate the compiler warnings.
1216  */
1217