![]() |
Wahoo Fitness API
3.6.1
Documentation for the iPhone version of the Wahoo Fitness API.
|
The WFHardwareConnector represents the bridge between the fisica sensor receiver (dongle or case) and the iPhone application. More...
#import <WFHardwareConnector.h>
Instance Methods | |
(UCHAR) | - availableChannelCount |
Returns the number of unallocated communication channels. More... | |
(NSSet *) | - cancelDiscoveryOnNetwork: |
(WFHardwareConnectorState_t) | - currentState |
Returns the current state of the WFHardwareConnector. More... | |
(BOOL) | - discoverDevicesOfType:onNetwork:searchTimeout: |
(BOOL) | - enableAntBridge: |
Enables or disables the ANT Brige. More... | |
(BOOL) | - enableBTLE: |
Enables BTLE support (when available). More... | |
(BOOL) | - enableBTLE:inBondingMode: |
Enables BTLE support (when available), with the specified mode. More... | |
(NSArray *) | - getSensorConnections: |
Returns an array of WFSensorConnection instances for all connected sensors of the specified type. More... | |
(NSURL *) | - getWahooFinessUtilityAppUrl |
Provides a URL which can be used to navigate the user of the app to the official Wahoo Fitness Utility App, "Wahoo Utility". More... | |
(BOOL) | - initializeAdvancedMode: |
Sets the WFHardwareConnetor to Advanced ANT mode. More... | |
(BOOL) | - openUSBSession: |
Opens a connection to the USB ANT Stick. More... | |
(BOOL) | - openUSBSession:deviceNumber: |
Opens a connection to the USB ANT Stick. More... | |
(void) | - prepareForBackground |
Prepares the WFHardwareConnector for background mode. More... | |
(BOOL) | - releaseAntFSDevice: |
Releases resources used by the specified WFAntFSDevice. More... | |
(BOOL) | - requestAntFSDevice:toDelegate: |
Requests that a WFAntFSDevice instance be created and initialized. More... | |
(WFSensorConnection *) | - requestSensorConnection: |
Initializes a sensor connection request based on the specified parameters. More... | |
(WFSensorConnection *) | - requestSensorConnection:withProximity: |
Initializes a sensor connection request, with limited search range specified. More... | |
(WFSensorConnection *) | - requestSensorConnection:withProximity:error: |
Initializes a sensor connection request, with limited search range specified. More... | |
(BOOL) | - resetAllSensorData |
Resets all accumulated and calculated data for all sensor types. More... | |
(BOOL) | - resetConnections |
Resets all sensor connections and sets the fisica device to IDLE mode. More... | |
(void) | - resetSampleTimer |
Resets the sample timer, based on the current sample rate. More... | |
(void) | - returnFromBackground |
Restores normal operation upon returning from background mode. More... | |
(BOOL) | - sendAntMessage: |
Sends the specified ANT message. More... | |
(void) | - setSampleTimerDataCheck: |
Specifies whether the WFHardwareConnector should invoke the WFHardwareConnectorDelegate::hardwareConnectorHasData method only when new data is available. More... | |
Class Methods | |
(WFHardwareConnector *) | + sharedConnector |
Returns the singleton WFHardwareConnector instance. More... | |
Properties | |
NSString * | apiVersion |
Gets the current Wahoo Fitness API version string. More... | |
BOOL | autoReset |
Gets or sets a boolean value indicating whether sensor connections are reset automatically when the fisica hardware is disconnected. More... | |
id< WFHardwareConnectorDelegate > | delegate |
Gets or sets the WFHardwareConnectorDelegate which will handle delegated methods from the WFHardwareConnector. More... | |
WFFisicaInfo * | fisicaInfo |
Gets a WFFisicaInfo instance describing the properties and capabilities of the currently connected fisica hardware. More... | |
BOOL | hasBTLESupport |
Gets a boolean value indicating whether the device has hardware support for BTLE. More... | |
BOOL | isAntBridgeActive |
Gets a boolean value indicating whether the ANT Bridge is currently active. More... | |
BOOL | isAntBridgeEnabled |
Gets a boolean value indicating whether the ANT Bridge is currently enabled. More... | |
BOOL | isBTLEEnabled |
Gets a boolean value indicating whether the BTLE hardware is enabled and ready for a connection. More... | |
BOOL | isCommunicationHWReady |
Gets a boolean value indicating whether any communication hardware is available. More... | |
BOOL | isFisicaConnected |
Gets a boolean value indicating whether the fisica device is connected. More... | |
NSTimeInterval | sampleRate |
Gets or sets the sample rate in seconds. More... | |
WFConnectorSettings * | settings |
Gets the persistent settings for the Wahoo API. More... | |
The WFHardwareConnector represents the bridge between the fisica sensor receiver (dongle or case) and the iPhone application.
The connector, along with the WFHardwareConnectorDelegate protocol, provide an interface to the fisica device. The connector is used to configure the device and obtain the latest data from the sensors. The delegate protocol updates the delegate of status changes to the sensors and data availability.
- (UCHAR) availableChannelCount |
Returns the number of unallocated communication channels.
- (NSSet*) cancelDiscoveryOnNetwork: | ("Please see WFDiscoveryManager class") | DEPRECATED_MSG_ATTRIBUTE |
Cancels device discovery on the specified network.
eNetworkType | The network on which to cancel discovery. |
NSSet
containing zero or more WFConnectionParams instances representing all devices discovered up to the point the discovery was cancelled. - (WFHardwareConnectorState_t) currentState |
Returns the current state of the WFHardwareConnector.
Value | Description |
WF_HWCONN_STATE_NOT_CONNECTED | The fisica device is not physically connected. |
WF_HWCONN_STATE_CONNECTED | The fisica device is physically connected. |
WF_HWCONN_STATE_ACTIVE | The fisica device is in normal operation mode. |
WF_HWCONN_STATE_RESET | The fisica device is performing a reset operation. |
UCHAR ucNormalState = WF_HWCONN_STATE_CONNECTED | WF_HWCONN_STATE_ACTIVE;
- (BOOL) discoverDevicesOfType: | (WFSensorType_t) | eSensorType | |
onNetwork: | (WFNetworkType_t) | eNetworkType | |
searchTimeout: | ("Please see WFDiscoveryManager class") | DEPRECATED_MSG_ATTRIBUTE | |
Initiates device discovery on the specified network.
To discover devices on a network, the following conditions must be met:
The standard discovery proceedure is as follows:
Implement the WFHardwareConnectorDelegate::hardwareConnector:didDiscoverDevices:searchCompleted: method
Invoke the discoverDevicesOfType:onNetwork:searchTimeout: method with the desired parameters.
The WFHardwareConnectorDelegate::hardwareConnector:didDiscoverDevices:searchCompleted: method will be invoked as soon as a matching device is discovered, for each matching device discovered. The connectionParams
parameter will contain a single WFConnectionParams
instance, and the bCompleted
parameter will be FALSE
.
bCompleted
parameter set to TRUE
. The connectionParams
parameter will contain a WFConnectionParams instance for each matching device which was discovered. If a real-time update is desired, the WFHardwareConnectorDelegate::hardwareConnector:didDiscoverDevices:searchCompleted: may be processed for each device, as it is discovered. If real-time updates are not desired, wait to process WFHardwareConnectorDelegate::hardwareConnector:didDiscoverDevices:searchCompleted: until the bCompleted
parameter is TRUE
. In this case, the connectionParams
parameter will contain all matching sensors discovered during the discovery process.
eSensorType | The WFSensorType_t to discover. If this value is WF_SENSORTYPE_NONE, a wildcard discovery is performed. |
eNetworkType | The network on which to perform the discovery. THIS IS A SINGLE NETWORK TYPE, masking is not supported on this argument. |
timeout | The timeout for the discovery process, in seconds. If this value is 0 the discovery will continue indefinitely. The device discovery continues until the timeout period has elapsed, or the cancelDiscoveryOnNetwork: method is invoked. |
TRUE
if the discovery was successfully initiated, otherwise FALSE
. If a discovery is currently in progress on the specified network, or if any connections exist on the network, or if the specified sensor type is not supported on the specified network type, the return will be FALSE
. Enables or disables the ANT Brige.
The ANT Brige allows the WFHardwareConnector to connect to ANT devices via the ANT radio on an ANT Brige enabled Wahoo Fitness BTLE device, such as the RFLKT+. This method will enable the ANT Bridge if it is availabe, or when it becomes available. If the bridge is immediately available when enabled, it will be activated and used for ANT connections. If the bridge is not available when enabled, it will be configured and activated once it becomes available.
To avoid requiring the application to explicitly enable the ANT Bridge for each session, the WFConnectorSettings::isAntBrigeAutoEnabled property may be used.
bEnable | TRUE to enable the bridge, otherwise FALSE |
TRUE
if the ANT Bridge is ready, otherwise FALSE
. The ANT Bridged enabled state is set, regardless of the return value. The return serves primarily to indicate whether an active state change was required. Enables BTLE support (when available).
bEnable | TRUE to enable BTLE support, FALSE to disable. |
TRUE
if the request was successful, otherwise FALSE
. When bEnable
is FALSE
, the return is TRUE
only if BTLE support is enabled at the time of the request. When bEnable
is TRUE
, the return is TRUE
only if the device is capable of BTLE, and BTLE is not enabled at the time of the request. - (BOOL) enableBTLE: | (BOOL) | bEnable | |
inBondingMode: | (BOOL) | bBondingMode | |
Enables BTLE support (when available), with the specified mode.
bEnable | TRUE to enable BTLE support, FALSE to disable. |
bBondingMode | TRUE to put the BTLE controller in bonding mode, otherwise FALSE |
As of iOS 5.1, there is a bug in CoreBluetooth affecting devices which require bonding. In normal operation, the Wahoo API will run CoreBluetooth on an alternate dispatch queue. This is the default state, and allows for efficient simultaneous connections with multiple BTLE devices. However, when a device requires bonding, CoreBluetooth prompts the user with an alert dispatched on the alternate queue, rather than the main run loop, causing the UI to freeze. To work around this issue, the WF API allows the developer to put the BTLE controller into "bonding" mode. In this mode, the bonding prompt is dispatched on the main run loop, so that the UI performs as expected.
The mode may be switched between normal and bonding via this method. If BTLE is enabled when this method is invoked, and a different mode is specified, the BTLE controller will be reset and then enabled in the specified mode. The application will receive the WFHardwareConnectorDelegate::hardwareConnector:stateChanged: message twice when switching modes. The first will be for the reset, the WF_HWCONN_STATE_BT40_ENABLED flag will be cleared. The second is when the specified mode is enabled, the WF_HWCONN_STATE_BT40_ENABLED flag will be set.
TRUE
if the request was successful, otherwise FALSE
. When bEnable
is FALSE
, the return is TRUE
only if BTLE support is enabled at the time of the request. When bEnable
is TRUE
, the return is TRUE
if the device is capable of BTLE, and BTLE is not enabled at the time of the request. If BTLE is enabled at the time of the request, the return is TRUE
if the specified mode is different than the current mode, otherwise it is FALSE
- (NSArray*) getSensorConnections: | (WFSensorType_t) | sensorType |
Returns an array of WFSensorConnection instances for all connected sensors of the specified type.
sensorType | The type of sensor for which to get connections. If this parameter is WF_SENSORTYPE_NONE , all connections for any type are returned. |
- (NSURL*) getWahooFinessUtilityAppUrl |
Provides a URL which can be used to navigate the user of the app to the official Wahoo Fitness Utility App, "Wahoo Utility".
- (BOOL) initializeAdvancedMode: | (id< WFAntReceiverDelegate >) | rxDelegate_ |
Sets the WFHardwareConnetor to Advanced ANT mode.
In Advanced mode, no internal processing of ANT messages is performed. ANT messages are sent via the sendAntMessage: method and received using the antMessageReceived: (WFAntReceiverDelegate-p) method.
rxDelegate_ | A reference to the WFAntReceiverDelegate instance which will handle the RX messages from ANT. If this parameter is nil , the Advanced mode will be disabled, and the API will return to standard operation mode. |
TRUE
if advanced mode was set successfully, otherwise FALSE
. Provided by category WFHardwareConnector(AntMode).
Opens a connection to the USB ANT Stick.
This method initiates a connection to the first USB device detected on the system. To select a specific device use openUSBSession:deviceNumber instead.
ulBaudRate | The baud rate for the connection. |
TRUE
if the USB session was successfully started, otherwise FALSE
. - (BOOL) openUSBSession: | (ULONG) | ulBaudRate | |
deviceNumber: | (UCHAR) | ucUSBDeviceNumber | |
Opens a connection to the USB ANT Stick.
ulBaudRate | The baud rate for the connection. |
ucUSBDeviceNumber | The zero-indexed USB device number. |
TRUE
if the USB session was successfully started, otherwise FALSE
. - (void) prepareForBackground |
Prepares the WFHardwareConnector for background mode.
This method should be invoked when the application receives notification that the app is entering background mode. When the application returns from background mode, the returnFromBackground method should be invoked.
- (BOOL) releaseAntFSDevice: | (WFAntFSDevice *) | fsDevice |
Releases resources used by the specified WFAntFSDevice.
fsDevice | The WFAntFSDevice instance to be released. |
TRUE
if resources were released successfully, otherwise FALSE
. Provided by category WFHardwareConnector(AntFS).
- (BOOL) requestAntFSDevice: | (WFAntFSDeviceType_t) | deviceType | |
toDelegate: | (id< WFAntFSDeviceDelegate >) | theDelegate | |
Requests that a WFAntFSDevice instance be created and initialized.
deviceType | The type of device for which the WFAntFSDevice is to be created. ANT FS profiles are different among device types, the specific type of ANT FS Device created will be the type which is able to process files for the specified device type. |
theDelegate | The delegate which will be alerted when the ANT FS Device instance is ready. The ANT FS Device creation is an asynchronous operation. This method will return immediately, and the delegate method will be invoked when the operation is complete (see the note on the WFAntFSDevice::delegate property for more details). |
TRUE
if the ANT FS Device creation operation is started successfully, otherwise FALSE
. Provided by category WFHardwareConnector(AntFS).
- (WFSensorConnection*) requestSensorConnection: | (WFConnectionParams *) | params |
Initializes a sensor connection request based on the specified parameters.
This method will initiate a connection request based on the specified parameters, and return a WFSensorConnection instance which may be used to manage the connection. The connection process is asynchronous. Unless a sensor specified in the parameters is already connected, it is likely that the sensor will not have connected when this method returns.
The WFSensorConnection may be used to monitor the connection status. There are two ways to be notified when the sensor connection is established. The WFHardwareConnectorDelegate::hardwareConnector:connectedSensor: is invoked whenever any sensor connection is established. When using this method, the connectionInfo parameter must be checked to determine which sensor has connected (if multiple connections were requested). The other option is to set the WFSensorConnection::delegate property on the instance returned. The delegate will be alerted to any change in the connection status.
The WFSensorConnection class is an abstract base class for sensor connection management. The actual object type returned will be determined by the WFConnectionParams::sensorType value. It is recommended that the instance returned be cast as the specific type, and then cached as an instance member used for managing the connection. The WFSensorConnection is used to retrieve data from the sensor, as well as to disconnect, or monitor the state of the connection.
A best-practices outline for connecting to a heart rate monitor follows:
Create a WFConnectionParams instance and set the WFConnectionParams::sensorType property to WF_SENSORTYPE_HEARTRATE
Create a WFDeviceParams instance and set its values to a previously paired heart rate monitor (see the WFSensorConnection documentation for information about initial pairing).
Assign the WFDeviceParams instance to the WFConnectionParams::device1 property.
Repeat the last two steps for any other previously paired heart rate monitors (up to four). Just use the device2, device3, or device4 property instead of device1 specified in the last step.
Invoke the requestSensorConnection: method.
Cast the return value as a WFHeartrateConnection and cache as an instance member.
Set the WFSensorConnection::delegate property.
Once the connection has been established, use the getHeartrateData (WFHeartrateConnection) method to retrieve a WFHeartrateData instance. This instance will contain the latest heart rate data.
When the heart rate monitor is no longer needed, use the disconnect (WFSensorConnection) method to end the connection.
FALSE
. Release the previously cached WFSensorConnection instance. params | A WFConnectionParams instance which specifies the connection parameters. |
nil
. Otherwise, the value returned is a WFSensorConnection instance which may be used to manage the connection. - (WFSensorConnection*) requestSensorConnection: | (WFConnectionParams *) | params | |
withProximity: | (WFProximityRange_t) | proximity | |
Initializes a sensor connection request, with limited search range specified.
params | A WFConnectionParams instance which specifies the connection parameters. |
proximity | A WFProximityRange_t value which limits the proximity of the search. There are ten range levels available, with WF_PROXIMITY_RANGE_1 being the closest. When WF_PROXIMITY_RANGE_1 is specified, the device must be very close to the fisica key for a connection to be established. The search distance increases with each range level. |
nil
. Otherwise, the value returned is a WFSensorConnection instance which may be used to manage the connection. - (WFSensorConnection*) requestSensorConnection: | (WFConnectionParams *) | params | |
withProximity: | (WFProximityRange_t) | proximity | |
error: | (NSError **) | ppError | |
Initializes a sensor connection request, with limited search range specified.
params | A WFConnectionParams instance which specifies the connection parameters. |
proximity | A WFProximityRange_t value which limits the proximity of the search. There are ten range levels available, with WF_PROXIMITY_RANGE_1 being the closest. When WF_PROXIMITY_RANGE_1 is specified, the device must be very close to the fisica key for a connection to be established. The search distance increases with each range level. |
ppError | If an error occurs, upon returns contains an NSError object that describes the problem. Pass in nil if error handling is not desired. |
nil
. Otherwise, the value returned is a WFSensorConnection instance which may be used to manage the connection. - (BOOL) resetAllSensorData |
Resets all accumulated and calculated data for all sensor types.
This method can be invoked at the beginning of a workout to put the sensors in a known state.
TRUE
if the reset was successful, otherwise FALSE
. - (BOOL) resetConnections |
Resets all sensor connections and sets the fisica device to IDLE mode.
TRUE
if all sensors were disconnected and the fisica device set to IDLE mode, otherwise FALSE
. - (void) resetSampleTimer |
Resets the sample timer, based on the current sample rate.
- (void) returnFromBackground |
Restores normal operation upon returning from background mode.
The prepareForBackground method should be invoked when the application receives notification that the app is entering background mode. When the application returns from background mode, this method should be invoked to restore normal operation.
- (BOOL) sendAntMessage: | (WFAntMessage *) | pstMessage |
Sends the specified ANT message.
pstMessage | A pointer to the ANT message to be sent. |
TRUE
if the message was sent successfully, otherwise FALSE
. Provided by category WFHardwareConnector(AntMode).
- (void) setSampleTimerDataCheck: | (BOOL) | checkData |
Specifies whether the WFHardwareConnector should invoke the WFHardwareConnectorDelegate::hardwareConnectorHasData method only when new data is available.
By default, the WFHardwareConnectorDelegate::hardwareConnectorHasData method is invoked at the sample rate whether or not new data is present. If the checkData value is TRUE
, the delegate method will only be invoked if there is new data present on at least one sensor.
checkData | TRUE if the WFHardwareConnectorDelegate::hardwareConnectorHasData method should only be invoked when new data is present. Otherwise FALSE . |
+ (WFHardwareConnector*) sharedConnector |
Returns the singleton WFHardwareConnector instance.
As of API version 2.0, the WFHardwareConnector is enforced as a singleton. This method may be used to obtain a reference to that instance. If the instance does not yet exist when this method is invoked, it will be created.
|
readnonatomicassign |
Gets the current Wahoo Fitness API version string.
|
readwritenonatomicassigninherited |
Gets or sets a boolean value indicating whether sensor connections are reset automatically when the fisica hardware is disconnected.
When the fisica hardware is disconnected (either by removing physically, or by the application entering background mode in pre-iOS5 devices), the ANT radio loses power, and the established connections are broken. When the fisica is re-connected, if autoReset
is TRUE
, any WFSensorConnection instances established prior to the disconnect are reset, and the WFHardwareConnector is in initialized state. If autoReset
is FALSE
, any WFSensorConnection instances will attempt to re-establish previous connections. In most cases, this should restore the connection and resume the data flow. However, there may be possible data synchronization issues in some situations. Therefore, it is recommended that the autoReset
remain in the default TRUE
condition, and that the application re-estabish desired connections in the same manner as when the WFHardwareConnector is originally initialized.
TRUE
.
|
readwritenonatomicretaininherited |
Gets or sets the WFHardwareConnectorDelegate which will handle delegated methods from the WFHardwareConnector.
|
readnonatomicassign |
Gets a WFFisicaInfo instance describing the properties and capabilities of the currently connected fisica hardware.
|
readnonatomicassign |
Gets a boolean value indicating whether the device has hardware support for BTLE.
|
readnonatomicassign |
Gets a boolean value indicating whether the ANT Bridge is currently active.
This value is TRUE
when the Ant Bridge is available, configured and currently serving as the Serial Transport Layer for ANT Connections. In all other cases, this value is FALSE
.
|
readnonatomicassign |
Gets a boolean value indicating whether the ANT Bridge is currently enabled.
TRUE
, even when the ANT Bridge is not present. The value indicates whether the ANT Bridge will be configured and used if and when it becomes available.
|
readnonatomicassign |
Gets a boolean value indicating whether the BTLE hardware is enabled and ready for a connection.
|
readnonatomicassign |
Gets a boolean value indicating whether any communication hardware is available.
This property will return TRUE
if either the fisica hardware is connected, or the BTLE hardware is enabled, or both. If no hardware is available and enabled, this property returns FALSE
.
|
readnonatomicassign |
Gets a boolean value indicating whether the fisica device is connected.
This property specifies the status of the dongle or case accessory. When the device is physically connected to the iPhone and communication has been established, the value will be true
. To determine the status of remote sensors (heartrate, FootPod, etc.), see the WFHardwareConnector::isSensorConnected: method.
|
readwritenonatomicassign |
Gets or sets the sample rate in seconds.
The value of this property will determine how often data updates are sent to the delegate. The WFHardwareConnectorDelegate::hardwareConnectorHasData method will be invoked at the sample rate.
|
readnonatomicassign |
Gets the persistent settings for the Wahoo API.