com.dsi.ant
Class AntInterface

java.lang.Object
  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()):

• SetNetworkKey128 (not documented in protocol doc)
• SetTransmitPower
• RxExtMesgsEnable
• LibConfig
• ConfigFrequencyAgility (only supported on some parts)
• SetChannelSearchPriority (since ANT Version AOV1.07)
• OpenRxScanMode
• SendExtBroadcastData
• SendExtAcknowledgedData
• SendExtBurstTransferPacket

Unsupported ANT Message functions (on phone ANT hardware):

• SetNetworkKey
• SetSerialNumChannelId
• EnableLED
• CrystalEnable
• SetUSBDescriptorString
• Sleep
• InitCWTestMode
• SetCWTestMode

See Also:

ANT Message Protocol and Usage

TAG

public static final java.lang.String TAG

The Log Tag.

See Also:

Constant Field Values

AntInterface

public AntInterface()

Instantiates a new ANT Interface.

Since:

3.0

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