Wahoo Fitness API  3.2.0
Documentation for the iPhone version of the Wahoo Fitness API.
Wahoo Fitness API Documentation
Version:
3.2.0
Date:
12/19/2013
Author:
Michael Moore

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.

Note:
All references to Xcode settings and configuration are specific to Xcode 4.

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:

  1. Open Xcode Preferences.
  2. Select the Documentation tab.
  3. Click the "+" button to add a new documentation publisher.
  4. Enter   http://api.wahoofitness.com/wf_api/wf_api.xml   into the URL Field.
  5. Click the Add button.
  6. Click the Get button next to the Wahoo Fitness API Documentation item in the list.
  7. Xcode should download and install the Wahoo Fitness API.

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.



Required Project Settings

Project Settings

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.

project_settings.png
Project Settings Screen Shot

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:

  1. Locate and click on the project in the Xcode navigator.
  2. Locate the "TARGETS" section, and click on your application target.
  3. Click on the "Build Phases" tab.
  4. Expand the "Link With Libraries" item.
  5. Click the "+" button to add a new item.
  6. Click the "Add Other..." button.
  7. Navigate to the location of the Wahoo Fitness API and select "WFConnector.framework".
framework_import.png
Framework Import Screen Shot

Required iOS SDK Frameworks

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

  • ExternalAccessory.framework
  • CoreBluetooth.framework
  • libstdc++6.dylib (iOS 7 SDK projects)

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

As of iOS 7 SDK Apple has removed support for CoreBluetooth in the iOS simulator. Please ensure you do not enable BTLE if you are running in the simulator.

Application Bundle Settings

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

info.png
Bundle Settings Screen Shot

Notes on Background Mode

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:

  • Add the external-accessory and bluetooth-central values to the UIBackgroundModes key in the application's info.plist.
  • In the 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.
  • In the 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.
  • When returning from background in iOS prior to 5.0, it is the responsibility of the application to restore any disired sensor connections.

In iOS 5.0 (or higher), data retrieval and storage should work as when the application is in the foreground.



Wahoo Fitness API v3.2.0

This release expands and improves support for the Wahoo Fitness RFLKT/RFLKT+ and and Magellan Echo and also brings many improvements to the Wahoo Fitness KICKR.

The Wahoo Fitness display SDK now supports multiple external display types that are all controled via a single API with layouts controlled via easy to read JSON configuration files. Each configuration allows developers to add support for new external displays and form factors without having to make any changes to the control code or adding additional third party APIs.

Please see the DisplayDocs folder in the API download for more detailed documentation of the display SDK and differences in supported features between devices.

Additions and improvements

  • Expanded support for the Wahoo KICKR Power Trainer.
  • Expanded support for the Wahoo RFLKT Bike Display including many bug fixes and perfomance improvements
  • Added support for RFLKT+ (ANT+ / BTLE bridge + Altimeter)
  • Added support for the Magellan Echo watch.
  • Added support for BTLE Power profile
  • Added automatic support for password protects MIO ALPHA HR monitors





Wahoo Fitness API v3.1_beta2 Release Notes

This release expands support for the Wahoo KICKR Power Trainer and the RFLKT Bike Display. The implementation is fairly stable now, and should be almost ready for the upcoming release of these products. We do not expect any major changes in the public interface prior to the next stable release. However, please be aware that this is a beta version. There may be some minor changes made before the implementation is finallized.

Additions and improvements

  • Expanded support for the Wahoo KICKR Power Trainer.
  • Expanded support for the Wahoo RFLKT Bike Display.





Wahoo Fitness API v3.0 Release Notes

This release includes support for several new BTLE Bike Power based profiles.

Additions and improvements

  • Added support for the Wahoo KICKR Power Trainer.
  • Added support for the Kurt InRide Bike Trainer.
  • Added support for the Stages StageOne Bike Power Meter.
  • Added support for the Wahoo RFLKT Bike Display.
Note:
The WFBikePowerData class has been modified to support the BTLE CPM profile data. The changes should simplify communication with power meters and help to abstract the data from the particular source (BTLE or ANT+). The new WFBikePowerData class will contain the same data for ANT+ and BTLE power meters. The BTLE CPM profile is currently supported in beta. Methods marked DEPRECATED will be removed in the next beta release (see WFBikePowerData_Deprecated for properties effected by this change). Please update any existing code accordingly. This should be a simple matter of renaming a few property accesses. This will be a breaking change in the next beta release.

Bug Fixes

  • Removed a call to UIDevice::uniqueIdentifier which was deprecated by Apple (this call was used to generate the serial number for ANT FS Client profile).





Wahoo Fitness API v2.3.2 Release Notes

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.

Overview of Changes

  • iOS 6 support added.
  • Bug fixes in the BTLE integration.
  • Added support for the Wahoo BTLE Weight Scale profile.

Additions and improvements

  • Added support for the Wahoo BTLE Weight Scale profile.
  • Added support for iOS 6.
  • The library now includes armv6, armv7 and armv7s slices, as well as an i386 slice for the simulator.
  • Added support for BTLE devices with 128-bit UUIDs.
  • Added prerequisite support for the upcoming BTLE CPM (Cycling Power Meter) profile.
Note:
The WFBikePowerData class has been modified to support the BTLE CPM profile data. The changes should simplify communication with power meters and help to abstract the data from the particular source (BTLE or ANT+). The new WFBikePowerData class will contain the same data for ANT+ and BTLE power meters. The BTLE CPM profile is currently supported in beta. Methods marked DEPRECATED will be removed in the next stable release (see WFBikePowerData_Deprecated for properties effected by this change). Please update any existing code accordingly. This should be a simple matter of renaming a few property accesses. This will be a breaking change in the next stable release.

Breaking Changes


Bug Fixes

  • Fixed several BTLE bugs.
  • Fixed a threading issue in the BTLE discovery and connection process.
  • Fixed minor bugs in the BTLE connection process for paired peripherals.
  • Fixed a bug where receiving Wahoo BlueSC odometer history was inconsistent under iOS 6
  • Added a work-around for a rare problem which occurs when CoreBluetooth unexpectedly resets.






Wahoo Fitness API v2.2.0 Release Notes

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.

Overview of Changes

  • Several new BTLE and ANT+ profiles were added.
  • Implemented the missing connection search timeout.
  • Added device discovery for ANT+ and BTLE.
  • Numerous bug fixes and improvements.
  • Added BTLE support for iPad3 and the iDevice simulators.


Additions and improvements

  • Added support for the following BTLE Profiles
    • Proximity Profile
    • Battery Service
    • Health Thermometer Profile
    • Bike Speed and Cadence Profile
    • Blood Pressure Profile
    • BTLE Glucose Monitor Profile
  • Added support for the ANT+ Continuous Glucose Beta Profile.
  • Added support for Suunto heart rate monitors.
  • Added BTLE support for iPad3 and the iDevice simulators.
  • Refined and improved the BTLE search and connect process.
  • Added an iOS version check to background methods - they do nothing if iOS 5 or higher.
  • Updated FIT SDK to version 2.0.
  • Added peripheral discovery for BTLE devices.
  • Added device discovery for ANT+ devices.
  • Implemented hash and isEqual in WFDeviceParams.
  • Added error handling to the requestSensorConnection: (WFHardwareConnector) method.
  • Full implemtation of the BTLE BP profile, including intermediate pressure.
  • Full implemtation of the CSC profile, including BlueSC extensions.
  • Added hasDeviceUUID: (WFConnectionParams) for BTLE support.
  • Added the ability to wildcard search on a specific network.
  • Fixed the broken ANT+ connection timeout and added missing BTLE connection timeout (see note below).
Note:
The WFHardwareConnectorDelegate::hardwareConnector:searchTimeout: method was removed. To use search timeout, implement the WFHardwareConnectorDelegate::connectionDidTimeout: method.

Bug Fixes

  • Fixed various BTLE bugs.
  • Added work-around for CoreBluetooth bug where bonding message causes UI to hang (see enableBTLE:inBondingMode: (WFHardwareConnector)).
  • Fixed bug where hardwareConnector:connectedSensor: (WFHardwareConnectorDelegate-p) and hardwareConnector:disconnectedSensor: (WFHardwareConnectorDelegate-p) passed an innernal connection reference to app.
  • Fixed issue with BTLE battery service causing radio lockup with newco device.
  • Fixed a bug where scanning for multiple BTLE devices would stop when the first type is found.
  • Fixed performance bug in ANT FS host and client.
  • Fixed bug in ANT FS host and client channel close sequence.
  • Fixed bug where hwConn delegate was not called on enableBTLE:FALSE
  • Fixed a bug which caused the BT to lock up when a wildcard connection request was initiated while another device was already connected.
  • Fixed a bug where removing fisica dongle caused BT to stop updating data.
  • Added check for sensor support and network availability to device discovery request.
  • Fixed several bugs related to BTLE connection process, mostly affecting multiple connections.
  • Fixed several bugs related to BTLE proximity search.
  • Fixed an issue where the Battery Level State characteristic was not received for some devices.


Revision Change Log

Version 2.2.4

Version 2.2.3

  • Fixed a bug where BTLE communication was attempted before connection process was ccomplete.

Version 2.2.2

  • Fixed a bug in the BTLE disconnect process which could put CoreBluetooth into a corrupted state.

Version 2.2.1

  • Fixed a bug where proximity profile locked up outgoing BT with TX Power read requests.





Wahoo Fitness API v2.1.4 Release Notes

This release includes some bug fixes and minor revisions.

Overview of Changes

  • Moved settings file from /Documents directory to /Library/wahoo directory. When upgrading existing app installations to a new version built with 2.1.4, the settings file is automatically moved to the new location. No change is required in the application.
  • Bug fixes.



Bug Fixes

  • Fixed some BTLE connection issues.
  • Fixed an issue where disabling BTLE (enableBTLE:FALSE) would cause the app to crash if BTLE devices were connected at the time.
  • Fixed a bug in the accumBeatCount property for BTLE devices.





Wahoo Fitness API v2.1.3 Release Notes

This release includes some bug fixes and minor revisions.

Overview of Changes

  • 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.

  • Combined the ANT FS device request and release - no longer separate methods for host device or client device. Request is dependent on ANT FS device type.
  • Added WFAntFSDevice as the base class for all ANT FS device types.



Breaking Changes



Bug Fixes

  • 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.





Wahoo Fitness API v2.1.2 Release Notes

This version makes minor internal modifications and improvements. There are no breaking changes to the public interface from v2.1.1.

Overview of Changes





Wahoo Fitness API v2.1.1_beta Release Notes

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.

Overview of Changes

BUG FIXES

  • Fixed an issue introduced in 2.1.0 where connecting using wildcard parameters would cause a crash in some situations.

  • Fixed a bug where API would crash on devices with iOS prior to 5.0.





Wahoo Fitness API v2.1_beta Release Notes

Overview of Changes

  • Added support for BTLE Heart Rate Monitor.

Notes

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.

  • Hardware Support - Bluetooth 4.0 (required for BTLE) is only available on the iPhone 4S.
  • iOS Support - CoreBluetooth, the underlying iOS framework required for BTLE support, is only available on iOS 5.0 (or higher).
  • Differences between how ANT+ and BTLE uniquely identify devices.

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.





Wahoo Fitness API v2.0 Release Notes

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.

Overview of Changes