 |
Wahoo Fitness API
3.0
Documentation for the iPhone version of the Wahoo Fitness API.
|
|
Wahoo Fitness API
3.0
Documentation for the iPhone version of the Wahoo Fitness API.
|
To obtain a copy of the API, please visit http://www.wahoofitness.com/api
Jump to Current Release Notes
Welcome to the Wahoo Fitness API Documentation. The primary class of the API is the WFHardwareConnector. It provides a bridge between the application and the underlying fisica hardware. The WFHardwareConnector enables the developer to configure the fisica hardware and retrieve data from available ANT+ and BTLE sensors.
For example usage, please review the Wahoo Demo reference application, available from Wahoo Fitness. This application project, included in the API distribution package, demonstrates the basic configuration and usage of the WFHardwareConnector.
The Wahoo Fitness API documentation can be integrated into Xcode. Documentation for classes and methods can be accessed by holding down the Option key while clicking the identifier. To configure Xcode to use the Wahoo Fitness API documentation, take the following steps:
Below you will find required project settings and the release notes for the latest version of the API, as well as previous versions. The release notes are in descending order, with the latest at the top. Changes in later versions will supersede changes made in previous versions. Changes which will break code written against previous API versions are noted in the "BREAKING CHANGES" section. If you are currently using an API version older than the last release, please review the breaking changes between your version and the current version.
The following values must be added to the Other Linker Flags key in the Linker section of the project settings for all configurations of any project built against the Wahoo Fitness API: -lstdc++ -all_load.
The Wahoo Fitness API is distributed as a static Framework. This is a convenient means of packaging the headers and binaries into a simple logical unit. Since the framework is static, the libraries will be linked into the application build. This is not contrary to Apple policy, and will not cause issues when submitting the application to Apple. Apple forbids the use of dynamic frameworks, where the framework itself must be installed on the device. The Wahoo API framework is not installed independently on the device, but rather linked and compiled into the final application binary.
To import the Wahoo Fitness API Framework into your project:
The following iOS frameworks are required to build with the Wahoo Fitness API. (See the Wahoo Fitness API Framework section above for instructions on how to add a framework to your project).
The CoreBluetooth.framework is a new requirement in version 2.1. This framework is required to support BTLE devices. The framework is only available on devices with iOS 5.0 or greater. Therefore, in order to support devices with earlier iOS versions, the framework should be "weak linked". To accomplish this, locate the CoreBluetooth.framework item in the "Link Binary With Libraries" list and change the requirement to "Optional" (see image above).
The following values must be added to the info.plist for the application:
Key: Supported external accessory protocols (raw key name UISupportedExternalAccessoryProtocols)
Value: com.momentumoftechnology.fisica
Key: Required background modes (raw key name UIBackgroundModes)
Value: external-accessory, and bluetooth-central
The names of these keys are dependent on the bundle plist version. It is recommended that the entire key be copied directly from the Wahoo Demo project distributed with the API. The Required background modes key is only valid for iOS 5.0 or higher (though setting this key in earlier versions should not cause any problems). The purpose of this value is to allow the connection to the fisica accessory to remain open while the application is in the background. This means that starting with iOS 5.0, applications can receive ANT data from the fisica device while the application is running in the background (phone locked, other app on top, in phone call, SMS, etc).
iOS 5.0 added the ability to receive data from a connected accessory while the application is in the background. In previous iOS versions, this was not possible, due to the fact that the operating system killed power to the connected accessory when the application entered the background. The prepareForBackground (WFHardwareConnector) method was designed to clean up resources to prepare a smooth transition to and from background mode. On iOS versions prior to 5.0, this method should be invoked on transition to background mode. For iOS 5.0 or higher, this method (and the accompanying returnFromBackground (WFHardwareConnector)) is no longer necessary. Some tips for successful background mode operation:
external-accessory and bluetooth-central values to the UIBackgroundModes key in the application's info.plist. applicationDidEnterBackground method, check whether the iOS version is less than 5.0. If so, invoke the prepareForBackground (WFHardwareConnector) method. If not, no action is required. applicationWillEnterForeground method, check whether the iOS version is less than 5.0. If so, invoke the returnFromBackground (WFHardwareConnector) method. If not, no action is required. In iOS 5.0 (or higher), data retrieval and storage should work as when the application is in the foreground.
This release includes support for several new BTLE Bike Power based profiles.
This release includes bug fixes and support for new device profiles. The main thrust of this update is to add support for iOS 6 and improve BTLE integration.
This release includes bug fixes, support for several new device profiles, and some additions and improvements. The main thrust of this update is to expand the support for BTLE devices and make it more robust.
hash and isEqual in WFDeviceParams. WFHardwareConnectorDelegate::hardwareConnector:searchTimeout: method was removed. To use search timeout, implement the WFHardwareConnectorDelegate::connectionDidTimeout: method.
Version 2.2.4
Version 2.2.3
Version 2.2.2
Version 2.2.1
This release includes some bug fixes and minor revisions.
enableBTLE:FALSE) would cause the app to crash if BTLE devices were connected at the time. accumBeatCount property for BTLE devices.
This release includes some bug fixes and minor revisions.
Added the enableBTLE: (WFHardwareConnector) method. As of iOS 5.0.1, there is a bug in CoreBluetooth which causes iOS to prompt the user to turn on bluetooth (when it is off) before the bluetooth state may be determined. As of API v2.1.3, BTLE support is disabled by default. The application must explicitly enable BTLE via the enableBTLE: (WFHardwareConnector) method. This allows the application to maintain control of the user experience. This default may change in a future release, once the CoreBluetooth bug is resolved.
Added the WFHardwareConnector::hasBTLESupport property to allow the application to determine whether the device has hardware support for BTLE.
Removed WFHardwareConnector::requestAntFileManager:toDelegate:.
Removed WFHardwareConnector::requestAntFSClient:toDelegate:.
Removed WFHardwareConnector::releaseAntFileManager:.
Removed WFHardwareConnector::releaseAntFSClient:.
These changes combine the request and release methods so that they are no longer different for host mode or client mode. Upgrading to this version should be as simple as changing the method signatures.
Added WFAntFSDeviceDelegate protocol. WFAntFileManagerDelegate and WFAntFSClientDelegate now extend from the WFAntFSDeviceDelegate protocol.
WFAntFileManagerDelegate::antFileManager:instanceCreated protocol method, as well as its WFAntFSClientDelegate equivenent, were moved to the antFSDevice:instanceCreated: (WFAntFSDeviceDelegate-p) method. Upgrading requires changing the method signature and casting the fsDevice parameter.
Fixed a bug where WFHardwareConnector::requestAntFileManager:toDelegate: would cause a crash the first time the returned instance was accessed.
Fixed a bug where sensors would occasionally get hung in the disconnect process.
Fixed a rare issue where disconnecting BTLE sensor caused crash.
This version makes minor internal modifications and improvements. There are no breaking changes to the public interface from v2.1.1.
Fixed an issue where devices running iOS 5.0, without BT4.0 hardware (pre iPhone 4S) prompted the user to turn on bluetooth if it was off.
Improved connection maintenance for BTLE connections (maintains connection until explicitly requested to disconnect - same as ANT connections).
Added support for proximity pairing BTLE devices.
signalEfficiency (WFSensorConnection) for BTLE now represents RSSI value.
Added WFHardwareConnector::isCommunicationHWReady property.
Added WFHardwareConnector::isBTLEEnabled property.
Based on feedback we received regarding the 2.1.0 beta release, we have made some significant changes in the way connections are handled for different network types (ANT+ vs BTLE). The changes make upgrading from 2.0 to 2.1.1 more strait-forward (we apologize to those who have already upgraded to 2.1.0, as these changes will break that build). The changes should also allow for better scalability as more device types become available in the future.
Removed network-specific device types from the WFSensorType_t enum.
Added WF_NETWORKTYPE_UNSPECIFIED and WF_NETWORKTYPE_ANY to the WFNetworkType_t enum.
The WFNetworkType_t is now a bit-field which can be masked to specify multiple network types.
Added the WFConnectionParams::networkType property.
The connection method now uses the WFConnectionParams::networkType property to determine on which network(s) to attempt a connection. This property is read-only, and is based on the WFDeviceParams::networkType for the specified devices. Devices of differing network types may be specified in the WFConnectionParams. In this case, simultaneous connection attempts will be made on the network for each specified device. If no devices are specified (wildcard search), connection attempts will be made for the specified sensor type on all available networks.
WFFitnessEquipmentHRSource_t::WF_FE_HR_SOURCE_ANT_PLUS enum renamed WF_FE_HR_SOURCE_ANTPLUS to maintain naming consistency. Fixed an issue introduced in 2.1.0 where connecting using wildcard parameters would cause a crash in some situations.
Support for BTLE HRM was added in this version. We have attempted to make upgrading to this version as seamless as possible. However, due to the differences between ANT and BTLE, there are some small changes required in the public interface.
The WFSensorConnection and WFDeviceParams now have two additional properties:
In addition, the WF_SENSORTYPE_HEARTRATE_BTLE and WF_SENSORTYPE_HEARTRATE_ANY values were added to the WFSensorType_t enum. The WF_SENSORTYPE_HEARTRATE_ANY value may be specified in the connection request to initiate a connection to either an ANT+ or BTLE HRM. Once a connection is established, pending connections to other HRM types are closed.
These changes should not adversely affect existing implementations. However, there are a couple of things to consider in extending an existing application to support BTLE.
The WFDeviceParams::networkType is now required for connections, whereever WFDeviceParams is used. However, since this property defaults to WF_NETWORKTYPE_ANTPLUS, existing implementations should not be affected. Care should be taken when persisting device parameters for "pairing" a device. If the appropriate parameters are not specified, the device will not be connected. In most cases, however, it is not unreasonable to persist all parameters, regardless of the type of device.
Up until this release, we have endeavored to keep breaking changes to a minimum. However, the additions to this release required a major revision of the architecture. We apologize for the inconvenience. We hope the improvements will be worth the trouble of upgrading.
The WFHardwareConnector singleton is now enforced. It is available through the sharedConnector (WFHardwareConnector) method.
All sensor connections are now managed through the WFSensorConnection object. An instance is obtained via the requestSensorConnection: (WFHardwareConnector) method.
WFSensorConnection and WFConnectionParams facilitate sensor pairing and connecting to previously paired sensors. Up to four previously paird sensors may be specified in the connection request. The API will connect to the first available of the specified devices.
WFSensorConnection derived classes now provide access to sensor-specific commands. For example, the setBikePowerCalibration: (WFBikePowerConnection) method provides a way for the application to set the calibration on the Bike Power sensor.
Sensor data is now provided in the WFSensorData derived classes. Instances are obtained through the getData (WFSensorConnection) method.
Added device pairing and persistence support (see WFConnectorSettings).
Added support for data formatting and stale data handling (see documentation in the WFSensorData derived classes - for example formattedHeartrate: (WFHeartrateData)).
Expanded and improved support for Fitness Watch downloads (FIT files).
Added Proximity pairing support (for fisica models with ANT AP2).
FULL BACKGROUND SUPPORT. Beginning with iOS 5.0, Apple will allow the connection to the fisica accessory to remain open when the application is running in the background. Please see the Application Bundle Settings section for information on enabling this feature.
1.7.5.1