com.dsi.ant
Class AntInterface

java.lang.Object
  extended by com.dsi.ant.AntInterface

public class AntInterface
extends java.lang.Object

AntInterface is a proxy object for communicating with the ANT Radio Service. It is recommended you have only one instance, managed from within a local long-running service (to prevent any conflicts during ANT configuration).

Detailed documentation is available in the "ANT Message Protocol and Usage" document under the Developers Zone on http://www.thisisant.com.

Missing ANT Message functions (can be implemented with ANTTxMessage()):

Unsupported ANT Message functions (on phone ANT hardware):

See Also:
ANT Message Protocol and Usage

Nested Class Summary
static interface AntInterface.ServiceListener
          An interface for notifying AntInterface clients when they have been connected to the ANT Radio Service.
 
Field Summary
static java.lang.String TAG
          The Log Tag.
 
Constructor Summary
AntInterface()
          Instantiates a new ANT Interface.
 
Method Summary
 void ANTAddChannelId(byte channelNumber, short deviceNumber, byte deviceType, byte txType, byte listIndex)
          Add channel IDs to the inclusion/exclusion list.
 void ANTAssignChannel(byte channelNumber, byte channelType, byte networkNumber)
          Assign the a channel.
 void ANTCloseChannel(byte channelNumber)
          Close a channel that has been previously opened.
 void ANTConfigEventBuffering(short screenOnFlushTimerInterval, short screenOnFlushBufferThreshold, short screenOffFlushTimerInterval, short screenOffFlushBufferThreshold)
          ANT config event buffering.
 void ANTConfigList(byte channelNumber, byte listSize, byte exclude)
          Configure the inclusion/exclusion list.
 void ANTDisableEventBuffering()
          ANT disable event buffering.
 void ANTOpenChannel(byte channelNumber)
          Open a channel that has been previously assigned and configured.
 void ANTRequestMessage(byte channelNumber, byte messageID)
          Request a specific information message from the device.
 void ANTResetSystem()
          This message is sent to the module to reset the system and put it in a known, low-power state.
 void ANTSendAcknowledgedData(byte channelNumber, byte[] txBuffer)
          Send an acknowledged packet on a channel.
 void ANTSendBroadcastData(byte channelNumber, byte[] txBuffer)
          Send a broadcast packet on a channel.
 int ANTSendBurstTransfer(byte channelNumber, byte[] txBuffer)
          Transmits the given data on a channel as a burst message.
 void ANTSendBurstTransferPacket(byte control, byte[] txBuffer)
          Send a burst packet on a channel (8 bytes).
 int ANTSendPartialBurst(byte channelNumber, byte[] txBuffer, int initialPacket, boolean containsEndOfBurst)
          ANT send partial burst.
 void ANTSetChannelId(byte channelNumber, short deviceNumber, byte deviceType, byte txType)
          Configures the channel ID for a specific channel.
 void ANTSetChannelPeriod(byte channelNumber, short channelPeriod)
          Configures the messaging period of a specific channel.
 void ANTSetChannelRFFreq(byte channelNumber, byte radioFrequency)
          Set the RF frequency for a particular channel.
 void ANTSetChannelSearchTimeout(byte channelNumber, byte searchTimeout)
          Configure the length of time that the receiver will search for a channel before timing out.
 void ANTSetChannelTxPower(byte channelNumber, byte txPower)
          Set the transmit power level for a specified channel.
 void ANTSetLowPriorityChannelSearchTimeout(byte channelNumber, byte searchTimeout)
          Configure the duration the receiver will search for a channel in low priority mode before switching to high priority mode.
 void ANTSetProximitySearch(byte channelNumber, byte searchThreshold)
          This function enables a one-time proximity requirement for searching.
 void ANTTxMessage(byte[] message)
          Write a raw message (8 bytes) to the ANT chip.
 void ANTUnassignChannel(byte channelNumber)
          Unassign a channel.
 boolean claimInterface()
          Take control of the ANT Radio.
 boolean destroy()
          Deprecated. Use a single instance and start/stop connection to ANT Radio Service with initService()/releaseService().
 void disable()
          Disable ANT.
 void enable()
          Enable ANT.
static AntInterface getInstance(Context context, AntInterface.ServiceListener listener)
          Deprecated. Use constructor to create a new instance and initService() to tell it to start connection to the ANT Radio Service.
 int getServiceLibraryVersionCode()
          Returns the version code (eg.
 java.lang.String getServiceLibraryVersionName()
          Returns the version name (eg "1.0") of ANTLib used by the ANT Radio Service
static void goToMarket(Context pContext)
          Go to market.
static boolean hasAntSupport(Context pContext)
          Check if this device has support for ANT.
 boolean hasClaimedInterface()
          Check if the calling application has control of the ANT Radio.
 boolean initService(Context context, AntInterface.ServiceListener listener)
          Binds this activity to the ANT Radio Service.
 boolean isEnabled()
          Checks if ANT is enabled.
 boolean isServiceConnected()
          True if this activity can communicate with the ANT Radio Service.
 boolean releaseInterface()
          Give up control of the ANT Radio.
 void releaseService()
          Unbinds this activity from the ANT Radio Service.
 boolean requestForceClaimInterface(java.lang.String appName)
          Claims the interface if it is available.
 boolean stopRequestForceClaimInterface()
          Clears the notification asking the user if they would like to seize control of the ANT Radio.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TAG

public static final java.lang.String TAG
The Log Tag.

See Also:
Constant Field Values
Constructor Detail

AntInterface

public AntInterface()
Instantiates a new ANT Interface.

Since:
3.0
Method Detail

getInstance

@Deprecated
public static AntInterface getInstance(Context context,
                                                  AntInterface.ServiceListener listener)
Deprecated. Use constructor to create a new instance and initService() to tell it to start connection to the ANT Radio Service.

Gets the single instance of AntInterface, creating it if it doesn't exist.

Note, since version 3.0 this will always create a new instance.

Parameters:
context - the context used to bind to the remote service.
listener - the listener to be notified of status changes.
Returns:
the AntInterface instance.
Since:
1.0

goToMarket

public static void goToMarket(Context pContext)
Go to market.

Parameters:
pContext - the context
Since:
1.2

initService

public boolean initService(Context context,
                           AntInterface.ServiceListener listener)
Binds this activity to the ANT Radio Service.

Returns:
true, if successful. Will fail if already initialised.
Throws:
java.lang.IllegalArgumentException - if context is not provided.
Since:
3.0

releaseService

public void releaseService()
Unbinds this activity from the ANT Radio Service.

Since:
3.0

isServiceConnected

public boolean isServiceConnected()
True if this activity can communicate with the ANT Radio Service.

Returns:
true, if service is connected
Since:
1.2

destroy

@Deprecated
public boolean destroy()
Deprecated. Use a single instance and start/stop connection to ANT Radio Service with initService()/releaseService().

Unbind from the ANT Radio Service.

Returns:
true, if successful
Since:
1.0

enable

public void enable()
            throws AntInterfaceException
Enable ANT.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

disable

public void disable()
             throws AntInterfaceException
Disable ANT.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

isEnabled

public boolean isEnabled()
                  throws AntInterfaceException
Checks if ANT is enabled.

Returns:
true, if is enabled.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTTxMessage

public void ANTTxMessage(byte[] message)
                  throws AntInterfaceException
Write a raw message (8 bytes) to the ANT chip.

Only use this fucntion if the message you want has not been implemented in the API.

See the ANT Message Protocol and Usage document for details.

Parameters:
message - the message to send.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSendPartialBurst

public int ANTSendPartialBurst(byte channelNumber,
                               byte[] txBuffer,
                               int initialPacket,
                               boolean containsEndOfBurst)
                        throws AntInterfaceException
ANT send partial burst.

Parameters:
channelNumber - the channel number
txBuffer - the data to transmit
initialPacket - the initial packet
containsEndOfBurst - the contains end of burst
Returns:
The number of bytes still to be sent (approximately). 0 if success.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTUnassignChannel

public void ANTUnassignChannel(byte channelNumber)
                        throws AntInterfaceException
Unassign a channel. A channel must be unassigned before it may be reassigned using the Assign Channel command.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTAssignChannel

public void ANTAssignChannel(byte channelNumber,
                             byte channelType,
                             byte networkNumber)
                      throws AntInterfaceException
Assign the a channel.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetChannelId

public void ANTSetChannelId(byte channelNumber,
                            short deviceNumber,
                            byte deviceType,
                            byte txType)
                     throws AntInterfaceException
Configures the channel ID for a specific channel.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetChannelPeriod

public void ANTSetChannelPeriod(byte channelNumber,
                                short channelPeriod)
                         throws AntInterfaceException
Configures the messaging period of a specific channel.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetChannelSearchTimeout

public void ANTSetChannelSearchTimeout(byte channelNumber,
                                       byte searchTimeout)
                                throws AntInterfaceException
Configure the length of time that the receiver will search for a channel before timing out. Note that a value of zero will disable high priority search mode, and a value of 255 sets an infinite search time-out.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetChannelRFFreq

public void ANTSetChannelRFFreq(byte channelNumber,
                                byte radioFrequency)
                         throws AntInterfaceException
Set the RF frequency for a particular channel.

A frequency in the 2402 MHz to 2480 MHz range is recommended.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTAddChannelId

public void ANTAddChannelId(byte channelNumber,
                            short deviceNumber,
                            byte deviceType,
                            byte txType,
                            byte listIndex)
                     throws AntInterfaceException
Add channel IDs to the inclusion/exclusion list.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTConfigList

public void ANTConfigList(byte channelNumber,
                          byte listSize,
                          byte exclude)
                   throws AntInterfaceException
Configure the inclusion/exclusion list. The size determines which IDs in the list are to be used (setting a size of 0 disables the include/ exclude list) and the exclude variable determines whether the IDs are to be found or to be ignored when the device is searching.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetChannelTxPower

public void ANTSetChannelTxPower(byte channelNumber,
                                 byte txPower)
                          throws AntInterfaceException
Set the transmit power level for a specified channel.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetLowPriorityChannelSearchTimeout

public void ANTSetLowPriorityChannelSearchTimeout(byte channelNumber,
                                                  byte searchTimeout)
                                           throws AntInterfaceException
Configure the duration the receiver will search for a channel in low priority mode before switching to high priority mode.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSetProximitySearch

public void ANTSetProximitySearch(byte channelNumber,
                                  byte searchThreshold)
                           throws AntInterfaceException
This function enables a one-time proximity requirement for searching.

Only ANT devices within the set proximity bin can be acquired. Search threshold values are not correlated to specific distances as this will be dependent to the system design.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTResetSystem

public void ANTResetSystem()
                    throws AntInterfaceException
This message is sent to the module to reset the system and put it in a known, low-power state.

Execution of this command terminates all channels. All information previously configured in the system can no longer be considered valid.

After a Reset System command has been issued, the application should wait 500ms to ensure that ANT is in the proper, “after-reset” state before any further commands are issued from the host.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTOpenChannel

public void ANTOpenChannel(byte channelNumber)
                    throws AntInterfaceException
Open a channel that has been previously assigned and configured.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTCloseChannel

public void ANTCloseChannel(byte channelNumber)
                     throws AntInterfaceException
Close a channel that has been previously opened.

The host will initially receive a RESPONSE_NO_ERROR message indicating the message was successfully received by ANT. The actual closing of the channel will be indicated by an EVENT_CHANNEL_CLOSED, and the host should wait for this message before performing any other operations on the channel.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTRequestMessage

public void ANTRequestMessage(byte channelNumber,
                              byte messageID)
                       throws AntInterfaceException
Request a specific information message from the device.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSendBroadcastData

public void ANTSendBroadcastData(byte channelNumber,
                                 byte[] txBuffer)
                          throws AntInterfaceException
Send a broadcast packet on a channel.

Note, data payload for a broadcast message is 8 bytes. The host application shall always define the full 8 bytes of the data packet and set unused bytes appropriately. If an application requires less than 8 bytes of data to be transmitted over the air, the remaining unused bytes shall be set to a predefined “unused” value (for example, ANT+ device profiles specify unused byte values, such as 0x00 or 0xFF).

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSendAcknowledgedData

public void ANTSendAcknowledgedData(byte channelNumber,
                                    byte[] txBuffer)
                             throws AntInterfaceException
Send an acknowledged packet on a channel.

Note, data payload for an acknowledged message is 8 bytes. The host application shall always define the full 8 bytes of the data packet and set unused bytes appropriately. If an application requires less than 8 bytes of data to be transmitted over the air, the remaining unused bytes shall be set to a predefined “unused” value (for example, ANT+ device profiles specify unused byte values, such as 0x00 or 0xFF).

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSendBurstTransfer

public int ANTSendBurstTransfer(byte channelNumber,
                                byte[] txBuffer)
                         throws AntInterfaceException
Transmits the given data on a channel as a burst message.

See the ANT Message Protocol and Usage document for details.
NumDataPackets is not required, as this will be calculated.

Returns:
The number of bytes still to be sent (approximately). 0 if success.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTSendBurstTransferPacket

public void ANTSendBurstTransferPacket(byte control,
                                       byte[] txBuffer)
                                throws AntInterfaceException
Send a burst packet on a channel (8 bytes).

When a single packet burst is sent, it behaves identically to an acknowledged message, there are no retries associated with a single packet burst.

See the ANT Message Protocol and Usage document for details.

NOTE: Sending individual burst packets will most likely result in a failure due to the data not arriving at the chip quickly enough for it to continue the burst.

Parameters:
control - Is the combination of sequence number and channel number.
txBuffer - Must be 8 bytes of data to transmit as a bust packet.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.0

ANTConfigEventBuffering

public void ANTConfigEventBuffering(short screenOnFlushTimerInterval,
                                    short screenOnFlushBufferThreshold,
                                    short screenOffFlushTimerInterval,
                                    short screenOffFlushBufferThreshold)
                             throws AntInterfaceException
ANT config event buffering.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.3

ANTDisableEventBuffering

public void ANTDisableEventBuffering()
                              throws AntInterfaceException
ANT disable event buffering.

See the ANT Message Protocol and Usage document for details.

Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.1

getServiceLibraryVersionCode

public int getServiceLibraryVersionCode()
                                 throws AntInterfaceException
Returns the version code (eg. 1) of ANTLib used by the ANT Radio Service

Returns:
the service library version code, or 0 on error.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.2

getServiceLibraryVersionName

public java.lang.String getServiceLibraryVersionName()
                                              throws AntInterfaceException
Returns the version name (eg "1.0") of ANTLib used by the ANT Radio Service

Returns:
the service library version name, or null on error.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.2

claimInterface

public boolean claimInterface()
                       throws AntInterfaceException
Take control of the ANT Radio.

Returns:
True if control has been granted, false if another application has control or the request failed.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.5

releaseInterface

public boolean releaseInterface()
                         throws AntInterfaceException
Give up control of the ANT Radio.

Returns:
True if control has been given up, false if this application did not have control.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.5

requestForceClaimInterface

public boolean requestForceClaimInterface(java.lang.String appName)
                                   throws AntInterfaceException
Claims the interface if it is available. If not the user will be prompted (on the notification bar) if a force claim should be done. If the ANT Interface is claimed, an AntInterfaceIntent.ANT_INTERFACE_CLAIMED_ACTION intent will be sent, with the current applications pid.

Parameters:
appName - The name if this application, to show to the user.
Returns:
false if a claim interface request notification already exists.
Throws:
java.lang.IllegalArgumentException
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.5

stopRequestForceClaimInterface

public boolean stopRequestForceClaimInterface()
                                       throws AntInterfaceException
Clears the notification asking the user if they would like to seize control of the ANT Radio.

Returns:
false if this process is not requesting to claim the interface.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.5

hasClaimedInterface

public boolean hasClaimedInterface()
                            throws AntInterfaceException
Check if the calling application has control of the ANT Radio.

Returns:
True if control is currently granted.
Throws:
AntInterfaceException
AntServiceNotConnectedException
AntRemoteException
Since:
1.5

hasAntSupport

public static boolean hasAntSupport(Context pContext)
Check if this device has support for ANT.

Returns:
True if the device supports ANT (may still require ANT Radio Service be installed).
Since:
1.5