ANT API for Android ドキュメント超訳
ANT API for Androidに含まれる「Creating ANT+ Android Applications」を訳してみました。
いつも(翻訳公開するのは初めてだけど)ながら適当な訳なので、正確を期すためには原文を(それじゃ意味ないか？)読んでくださいね。
「Creating ANT+ Android Applications」
1パッケージコンテンツ
・AntLib
アプリケーションへのInclude用。APIはAntInterfaceで定義されている。AntDefineとAntMesgはANT通信に必要な定数を提供する。
・AntPlusDemo
ANT通信を使った脈拍計、歩数計、体重計からのデータをパースするEclipse用のリファレンスアプリケーション。ANTLibの使い方を示す。また、ANT I/Fの適切な扱い方と、ANT Radio Serviceがインストールされていない状況をハンドリングする。ペアリングされたデバイスは再びペアリングされるまで記憶され、デバイスサーチとイベントバッファリングができる。
2必要環境
ANTハードウェアによる全ての通信は'ANT Radio Service'を通して実現される。このサービスはアプリケーション～システム間のProxyとして機能する。このサービスは、ANT対応したデバイスからAndroid Marketを通じて利用可能である(または、デバイスにプリインストールされている)。その他のデバイスについては、ANT機能はハードウェアメーカーからのアップデートによる対応が必要となる可能性がある。ANT Radio ServiceはANT機能が有効になった端末にしかインストールできない。
ANTLibはANTチップをアプリケーションから制御するAPIを提供する。これはコマンドメッセージのセットによって実現される。ANTを制御するメッセージについては、「ANT Message Protocol and Usage」を参照のこと。Developer's Zone(http://thisisant.com)※
http://thisisant.com/images/Resources/PDF/1204662412_ant%20message%20protocol%20and%20usage.pdf ※
※リンク切れ
ほとんどのANT API関数は9.5章(ANT Message Detail)に対応したメッセージをコールする。ドキュメントと異なる点については、4章(ANT Messaging API Function)以降で記載されている。
※リンク切れてるのでよくわからんｗ
ANT+ ForumはANT関連の開発に関する質問や一般的な問題の詳細に対する答えを提供する場である。
Getting Started with Development of ANT+ Enabled Applications(
http://www.thisisant.com/component/option,com_fireboard/Itemid,146/func,view/catid,25/id,1169/)
※これまたリンク切れ
初心者向けには、ANT General Questions forumを参照のこと。
3Android向けAntInterfaceの利用方法
外部からANTメッセージ関数をコールすることで、ANT Radio Serviceを通じて以下のことを行うことができます。
・サービスへのバインド
・AntInterface.ServiceListenerコールバック
・AntInterfaceIntent
3.1 ANTサポートのチェック
アプリケーションは、ANT Radio Serviceをバインドする前にデバイスがANTをサポートしているかチェックすることができる。これはAntInterface.hasAntSupport()をコールすることで実現できる。
もし、ANTサポートしたデバイス上でのみアプリケーションを有効にしたければ、以下のタグをAndroidManifest.xmlに記述しておくこと。
＜uses-library android:name="com.dsi.ant.antradio_library" /＞
3.2 必要とされるパーミッション
ANTをサポートするデバイス上では以下の新しいパーミッションが定義されています。
3.2.1 com.dsi.ant.permission.ANT
このパーミッションはANT Radio Serviceを利用するアプリケーションに必要です。
ユーザに対しては以下の説明が表示されます。
“Allows the application to communicate with ANT devices using the proxy service. Malicious applications may acquire information from, or transmit to, ANT devices without your knowledge.”
“アプリケーションがProxyサービスを使用してANTデバイスで通信することを許可します。悪意のあるアプリケーションはあなたの知らないところでデバイスの情報を取得したり、ANTデバイスに送信することが可能になります。“
3.2.2 com.dsi.ant.permission.ANT_ADMIN
このパーミッションは、ANT Radioを設定するAntInterfaceを利用する場合に必要です。
ユーザに対しては以下の説明が表示されます。
“Allows the application to directly configure the ANT radio through the proxy service. Malicious applications may prevent other ANT applications from connecting to ANT devices.”
“アプリケーションがProxyサービスを通じて直接ANTを制御することを許可します。悪意のあるアプリケーションは他のANTアプリケーションがデバイスへの接続を妨害することが可能になります。“
3.3 ANT Radio Serviceの初期化
ANT Radio Serviceはアプリケーションがバインドを試みた際に開始されます。これは、AntInterface.getInstance()をコールすることで実現されます。サービスがインストールされていない場合、nullが返却され、バインドには失敗します。
終了時にはアンバインドする必要があります。AntInterface.destroy()を利用することで実現可能です。
3.3.1 ANT Radio Serviceのインストール
必要であれば、AntInterface.goToMarket()をコールしてAndroid Marketからサービスのインストーラを検索して表示することができます。ANTサポートされていないデバイスからはこのサービスは検索できません。
3.4 サービスとの接続状態の監視
サービスが開始されたか否か、初期化されたか否かの状態を知るためには、AntInterface.getInstance()をコールしてAntInterface.ServiceListenerインターフェイスを実装擦る必要があります。サービスとアプリケーション間の通信時に、onServiceConnected()とonServiceDisconnected()コールバックがコールされます。AntInterface.isServiceConnected()を使うことでいつでも状態を取得することができます。
3.5 ANTの有効状態の監視
ANT Radio Serviceに接続していても、ANT通信可能なのはANTが有効な場合のみです。BroadcastReceiverにより、AntInterfaceIntent.ANT_ENABLED_ACTION と ANT_DISABLED_ACTION を監視する必要があります。AntInterface.enable() と disable() の戻り値がtrueを返すのは、その要求が正常に送信されたことだけを意味することに注意してください。そして、その後これらのIntentが送信されてくることを待つ必要があります。
機内モードが有効化された場合、ANTチップはその後の要求は全て失敗します。これをスムーズに管理するためには、Intent.ACTION_AIRPLANE_MODE_CHANGEDをハンドリングしてください。ANT_DISABLED_ACTIONを受信したとしても、enable()のコールで再び有効にすることはできないでしょう。(精確にはよくわからん)
AntInterface.isEnabled()をコールすることで状態をいつでも取得することができます。
3.6 ANTのリセット
いつでもANTチップをリセットすることが可能です。AntInterface.ANT_RESET_ACTION Intentが送信されます。(サービスが投げるのかな？) この時点であなたのアプリケーションは、ANT設定情報をクリアすべきです。ANTは未初期化状態(詳細はANTResetSystemメッセージドキュメントを参照)を返します。そして、チャネルの再設定を行う必要があります。
3.7 ANTメッセージの受信
受信した全てのANTパケットはサービスからAntInterface.Intent.ANT_RX_MESSAGE_ACTION Intentとともに送信されます。生データはIntent.getByteArrayExtra(AntInterfaceIntent.ANT_MESSAGE)により取得することができます。そして、"ANT Message Protocol and Usage" (※上記リンク切れｗ)ドキュメントのように、AntMesgとAntDefineで定義された値でデコードされます。
3.8 複数のアプリケーションの取り扱い
現在は、どのアプリケーションもサービスをバインドすることは可能ですが、同時にひとつのアプリケーションからの要求でのみ制御可能です。アプリケーションは、ANT I/Fにより要求、解放、強制要求が可能です。他のアプリケーションが制御中の場合、ANTメッセージ要求は失敗します。既存のアプリケーションをサポートするためには、I/Fに対して要求しているアプリケーションが存在しないか、要求が受け入れられているかです。(日本語しっくりこないけど、ま、わかるよね)
3.8.1 要求 I/F
ANT I/Fが有効であれば、AntInterface.claimInterface()はtrueを返し、そのアプリケーションが制御権を取得することができます。
ANT I/Fにアプリケーションが要求を送信すると、AntInterfaceIntent.ANT_INTERFACE_CLAIMED_ACTION Intentが送信されます(たぶん、サービスが？)。getIntExtra() で ANT_INTERFACE_CLAIMED_PIDを取得することで、制御しているアプリケーションのプロセスIDを取得することができます。
hasClaimedInterface()をコールすることでいつでも、制御権を持っているか否かをチェックすることができます。
3.8.2 解放 I/F
AntInterface.releaseInterface()はANT I/Fの制御を解放します。また、ANTチップをリセットします。これを行うことで、他のアプリケーションがANT I/Fに要求を行ったり、他のアプリケーションが強制要求を送っていた場合、自動的に制御可能になります(以下参照)。
3.8.3 強制要求 I/F
もし他のアプリケーションがANT I/Fを解放していない状況で、AntInterface.requestForceClaimInterface()をコールすることで強制的に制御権を取得することができます。そして、ユーザに対してはプロンプト(Notification bar内に)が表示されます。もしこれに同意したら、AntInterface.stopRequestForceClaimInterface()を通知を消去する際にコールする必要があります。
強制要求が許可されたら、ANTチップはリセットされ、AntInterfaceIntent.ANT_INTERFACE_CLAIMED_ACTION Intentが送信されます。
ユーザが、制御件の移行を許可しないを選択したら通知は受け取れません。
3.8.4 ANTメッセージの受信
単一のアプリケーションがANT I/Fを制御可能なのに対して、ANT_RX_MESSAGE_ACTIONは全てのアプリケーションに対してブロードキャストされ、ANTメッセージが受信可能です。BroadcastReceiverを登録しておいたアプリケーション全てがメッセージを受信可能なことを念頭においてください。
4 ANTメッセージAPI関数
4.1 ネットワークの選択
4.1.1 ANTAssignChannel
ネットワークにチャネルを割り当てる前にネットワークキー(ANTSetNetworkKey)を割り当てる必要はありません。(何だ、いきなり、意味不明だｒｗ) ネットワーク番号は予めネットワークキーに割り当てられています(表1)。
表.1 ネットワークの選択
ネットワーク番号/ネットワークキー
0/Default public
1/ANT+
2/ANT-FS
3+/Invalid:Do not use
4.1.2 ANTSetNetworkKey
もし、プライベートネットワークベンダーの場合、詳細はDynastreamに問い合せてください。
4.2 イベントバッファリング
4.2.1 ANTConfigEventBuffering
バッテリーパワーの節約をするために、リアルタイムデータを必要としない全てのアプリケーションは、AntInterface.Intent.ANT_RX_MESSAGE_ACTION intentがトリガされる前にイベント(EVENT_TX, EVENT_RX_FAIL, EVENT_CHANNEL_COLLISION, EVENT_RX (Broadcast Only))がチップ上にバッファされる。ANTConfigEventBuffering（）関数は、画面がオフまたはオンになっている間に別の値をすることができます。（は？） 全てのデバイスがタイマーインターバルをサポートしているわけではないことを念頭において、バッファのしきい値を設定してください。バッファされないイベントがトリガされたら、バッファはフラッシュされます。
4.2.2 ANTDisableEventBuffering
ANTDisableEventBuffering() will return the chip to the default setting of all events being forwarded as they arrive.（わかんない）
5 ANT+デバイスとの通信
アプリケーションがANTRadioに対してメッセージの送受信を設定したら、次のステップは、ANT+センサーやデバイスと通信するように設定することです。ANT+のデータフォーマットとチャネルパラメータはANT+デバイスプロファイルに記述されています。ANT+デバイスプロファイルはANT+ Adopter Zone(thisisant.com ※リンク切れ)から取得可能です。ANT+ Adopter Zoneにアクセスするためにはユーザ登録(無料)が必要です。ANT+ Adopter Zoneでは、ANT+ シミュレータ、ソースコード、その他有用な技術ドキュメントを見つけることができます。(ないｗｗｗ)
6 ANT+ロゴの使用と認証
ANTは+のロゴはANT+デバイスとアプリケーションの相互運用性を消費者に知らせるために使用されています。認証されたアプリケーションのみがANT+の名称、ロゴ、アイコンを使用することができます。ANT+を使用してブランド化する前に、アプリケーションはそれを実装するデバイスプロファイルに準拠していることを確認するためのAnt+認証プロセスを完了する必要があります。The process is similar to the certification process for ANT+ sensors and devices but is streamlined for applications. For more details please visit: http://www.thisisant.com/pages/ant/ant-product-certification or contact antalliance@thisisant.com.
Once certification is complete the ANT+ logos can be used on both the application and promotional materials and on the market or other website where the application is available. Logo files will be distributed upon certification.。。。（疲れた。もういいよね。原文読んで）
----
そんなわけで、ざざっと訳して、サンプルアプリを実行させようと思ったけど、ペリア系端末持ってないから試せません。。。買えってことか。くぅ。
いつも(翻訳公開するのは初めてだけど)ながら適当な訳なので、正確を期すためには原文を(それじゃ意味ないか？)読んでくださいね。
「Creating ANT+ Android Applications」
1パッケージコンテンツ
・AntLib
アプリケーションへのInclude用。APIはAntInterfaceで定義されている。AntDefineとAntMesgはANT通信に必要な定数を提供する。
・AntPlusDemo
ANT通信を使った脈拍計、歩数計、体重計からのデータをパースするEclipse用のリファレンスアプリケーション。ANTLibの使い方を示す。また、ANT I/Fの適切な扱い方と、ANT Radio Serviceがインストールされていない状況をハンドリングする。ペアリングされたデバイスは再びペアリングされるまで記憶され、デバイスサーチとイベントバッファリングができる。
2必要環境
ANTハードウェアによる全ての通信は'ANT Radio Service'を通して実現される。このサービスはアプリケーション～システム間のProxyとして機能する。このサービスは、ANT対応したデバイスからAndroid Marketを通じて利用可能である(または、デバイスにプリインストールされている)。その他のデバイスについては、ANT機能はハードウェアメーカーからのアップデートによる対応が必要となる可能性がある。ANT Radio ServiceはANT機能が有効になった端末にしかインストールできない。
ANTLibはANTチップをアプリケーションから制御するAPIを提供する。これはコマンドメッセージのセットによって実現される。ANTを制御するメッセージについては、「ANT Message Protocol and Usage」を参照のこと。Developer's Zone(http://thisisant.com)※
http://thisisant.com/images/Resources/PDF/1204662412_ant%20message%20protocol%20and%20usage.pdf ※
※リンク切れ
ほとんどのANT API関数は9.5章(ANT Message Detail)に対応したメッセージをコールする。ドキュメントと異なる点については、4章(ANT Messaging API Function)以降で記載されている。
※リンク切れてるのでよくわからんｗ
ANT+ ForumはANT関連の開発に関する質問や一般的な問題の詳細に対する答えを提供する場である。
Getting Started with Development of ANT+ Enabled Applications(
http://www.thisisant.com/component/option,com_fireboard/Itemid,146/func,view/catid,25/id,1169/)
※これまたリンク切れ
初心者向けには、ANT General Questions forumを参照のこと。
3Android向けAntInterfaceの利用方法
外部からANTメッセージ関数をコールすることで、ANT Radio Serviceを通じて以下のことを行うことができます。
・サービスへのバインド
・AntInterface.ServiceListenerコールバック
・AntInterfaceIntent
3.1 ANTサポートのチェック
アプリケーションは、ANT Radio Serviceをバインドする前にデバイスがANTをサポートしているかチェックすることができる。これはAntInterface.hasAntSupport()をコールすることで実現できる。
もし、ANTサポートしたデバイス上でのみアプリケーションを有効にしたければ、以下のタグをAndroidManifest.xmlに記述しておくこと。
＜uses-library android:name="com.dsi.ant.antradio_library" /＞
3.2 必要とされるパーミッション
ANTをサポートするデバイス上では以下の新しいパーミッションが定義されています。
3.2.1 com.dsi.ant.permission.ANT
このパーミッションはANT Radio Serviceを利用するアプリケーションに必要です。
ユーザに対しては以下の説明が表示されます。
“Allows the application to communicate with ANT devices using the proxy service. Malicious applications may acquire information from, or transmit to, ANT devices without your knowledge.”
“アプリケーションがProxyサービスを使用してANTデバイスで通信することを許可します。悪意のあるアプリケーションはあなたの知らないところでデバイスの情報を取得したり、ANTデバイスに送信することが可能になります。“
3.2.2 com.dsi.ant.permission.ANT_ADMIN
このパーミッションは、ANT Radioを設定するAntInterfaceを利用する場合に必要です。
ユーザに対しては以下の説明が表示されます。
“Allows the application to directly configure the ANT radio through the proxy service. Malicious applications may prevent other ANT applications from connecting to ANT devices.”
“アプリケーションがProxyサービスを通じて直接ANTを制御することを許可します。悪意のあるアプリケーションは他のANTアプリケーションがデバイスへの接続を妨害することが可能になります。“
3.3 ANT Radio Serviceの初期化
ANT Radio Serviceはアプリケーションがバインドを試みた際に開始されます。これは、AntInterface.getInstance()をコールすることで実現されます。サービスがインストールされていない場合、nullが返却され、バインドには失敗します。
終了時にはアンバインドする必要があります。AntInterface.destroy()を利用することで実現可能です。
3.3.1 ANT Radio Serviceのインストール
必要であれば、AntInterface.goToMarket()をコールしてAndroid Marketからサービスのインストーラを検索して表示することができます。ANTサポートされていないデバイスからはこのサービスは検索できません。
3.4 サービスとの接続状態の監視
サービスが開始されたか否か、初期化されたか否かの状態を知るためには、AntInterface.getInstance()をコールしてAntInterface.ServiceListenerインターフェイスを実装擦る必要があります。サービスとアプリケーション間の通信時に、onServiceConnected()とonServiceDisconnected()コールバックがコールされます。AntInterface.isServiceConnected()を使うことでいつでも状態を取得することができます。
3.5 ANTの有効状態の監視
ANT Radio Serviceに接続していても、ANT通信可能なのはANTが有効な場合のみです。BroadcastReceiverにより、AntInterfaceIntent.ANT_ENABLED_ACTION と ANT_DISABLED_ACTION を監視する必要があります。AntInterface.enable() と disable() の戻り値がtrueを返すのは、その要求が正常に送信されたことだけを意味することに注意してください。そして、その後これらのIntentが送信されてくることを待つ必要があります。
機内モードが有効化された場合、ANTチップはその後の要求は全て失敗します。これをスムーズに管理するためには、Intent.ACTION_AIRPLANE_MODE_CHANGEDをハンドリングしてください。ANT_DISABLED_ACTIONを受信したとしても、enable()のコールで再び有効にすることはできないでしょう。(精確にはよくわからん)
AntInterface.isEnabled()をコールすることで状態をいつでも取得することができます。
3.6 ANTのリセット
いつでもANTチップをリセットすることが可能です。AntInterface.ANT_RESET_ACTION Intentが送信されます。(サービスが投げるのかな？) この時点であなたのアプリケーションは、ANT設定情報をクリアすべきです。ANTは未初期化状態(詳細はANTResetSystemメッセージドキュメントを参照)を返します。そして、チャネルの再設定を行う必要があります。
3.7 ANTメッセージの受信
受信した全てのANTパケットはサービスからAntInterface.Intent.ANT_RX_MESSAGE_ACTION Intentとともに送信されます。生データはIntent.getByteArrayExtra(AntInterfaceIntent.ANT_MESSAGE)により取得することができます。そして、"ANT Message Protocol and Usage" (※上記リンク切れｗ)ドキュメントのように、AntMesgとAntDefineで定義された値でデコードされます。
3.8 複数のアプリケーションの取り扱い
現在は、どのアプリケーションもサービスをバインドすることは可能ですが、同時にひとつのアプリケーションからの要求でのみ制御可能です。アプリケーションは、ANT I/Fにより要求、解放、強制要求が可能です。他のアプリケーションが制御中の場合、ANTメッセージ要求は失敗します。既存のアプリケーションをサポートするためには、I/Fに対して要求しているアプリケーションが存在しないか、要求が受け入れられているかです。(日本語しっくりこないけど、ま、わかるよね)
3.8.1 要求 I/F
ANT I/Fが有効であれば、AntInterface.claimInterface()はtrueを返し、そのアプリケーションが制御権を取得することができます。
ANT I/Fにアプリケーションが要求を送信すると、AntInterfaceIntent.ANT_INTERFACE_CLAIMED_ACTION Intentが送信されます(たぶん、サービスが？)。getIntExtra() で ANT_INTERFACE_CLAIMED_PIDを取得することで、制御しているアプリケーションのプロセスIDを取得することができます。
hasClaimedInterface()をコールすることでいつでも、制御権を持っているか否かをチェックすることができます。
3.8.2 解放 I/F
AntInterface.releaseInterface()はANT I/Fの制御を解放します。また、ANTチップをリセットします。これを行うことで、他のアプリケーションがANT I/Fに要求を行ったり、他のアプリケーションが強制要求を送っていた場合、自動的に制御可能になります(以下参照)。
3.8.3 強制要求 I/F
もし他のアプリケーションがANT I/Fを解放していない状況で、AntInterface.requestForceClaimInterface()をコールすることで強制的に制御権を取得することができます。そして、ユーザに対してはプロンプト(Notification bar内に)が表示されます。もしこれに同意したら、AntInterface.stopRequestForceClaimInterface()を通知を消去する際にコールする必要があります。
強制要求が許可されたら、ANTチップはリセットされ、AntInterfaceIntent.ANT_INTERFACE_CLAIMED_ACTION Intentが送信されます。
ユーザが、制御件の移行を許可しないを選択したら通知は受け取れません。
3.8.4 ANTメッセージの受信
単一のアプリケーションがANT I/Fを制御可能なのに対して、ANT_RX_MESSAGE_ACTIONは全てのアプリケーションに対してブロードキャストされ、ANTメッセージが受信可能です。BroadcastReceiverを登録しておいたアプリケーション全てがメッセージを受信可能なことを念頭においてください。
4 ANTメッセージAPI関数
4.1 ネットワークの選択
4.1.1 ANTAssignChannel
ネットワークにチャネルを割り当てる前にネットワークキー(ANTSetNetworkKey)を割り当てる必要はありません。(何だ、いきなり、意味不明だｒｗ) ネットワーク番号は予めネットワークキーに割り当てられています(表1)。
表.1 ネットワークの選択
ネットワーク番号/ネットワークキー
0/Default public
1/ANT+
2/ANT-FS
3+/Invalid:Do not use
4.1.2 ANTSetNetworkKey
もし、プライベートネットワークベンダーの場合、詳細はDynastreamに問い合せてください。
4.2 イベントバッファリング
4.2.1 ANTConfigEventBuffering
バッテリーパワーの節約をするために、リアルタイムデータを必要としない全てのアプリケーションは、AntInterface.Intent.ANT_RX_MESSAGE_ACTION intentがトリガされる前にイベント(EVENT_TX, EVENT_RX_FAIL, EVENT_CHANNEL_COLLISION, EVENT_RX (Broadcast Only))がチップ上にバッファされる。ANTConfigEventBuffering（）関数は、画面がオフまたはオンになっている間に別の値をすることができます。（は？） 全てのデバイスがタイマーインターバルをサポートしているわけではないことを念頭において、バッファのしきい値を設定してください。バッファされないイベントがトリガされたら、バッファはフラッシュされます。
4.2.2 ANTDisableEventBuffering
ANTDisableEventBuffering() will return the chip to the default setting of all events being forwarded as they arrive.（わかんない）
5 ANT+デバイスとの通信
アプリケーションがANTRadioに対してメッセージの送受信を設定したら、次のステップは、ANT+センサーやデバイスと通信するように設定することです。ANT+のデータフォーマットとチャネルパラメータはANT+デバイスプロファイルに記述されています。ANT+デバイスプロファイルはANT+ Adopter Zone(thisisant.com ※リンク切れ)から取得可能です。ANT+ Adopter Zoneにアクセスするためにはユーザ登録(無料)が必要です。ANT+ Adopter Zoneでは、ANT+ シミュレータ、ソースコード、その他有用な技術ドキュメントを見つけることができます。(ないｗｗｗ)
6 ANT+ロゴの使用と認証
ANTは+のロゴはANT+デバイスとアプリケーションの相互運用性を消費者に知らせるために使用されています。認証されたアプリケーションのみがANT+の名称、ロゴ、アイコンを使用することができます。ANT+を使用してブランド化する前に、アプリケーションはそれを実装するデバイスプロファイルに準拠していることを確認するためのAnt+認証プロセスを完了する必要があります。The process is similar to the certification process for ANT+ sensors and devices but is streamlined for applications. For more details please visit: http://www.thisisant.com/pages/ant/ant-product-certification or contact antalliance@thisisant.com.
Once certification is complete the ANT+ logos can be used on both the application and promotional materials and on the market or other website where the application is available. Logo files will be distributed upon certification.。。。（疲れた。もういいよね。原文読んで）
----
そんなわけで、ざざっと訳して、サンプルアプリを実行させようと思ったけど、ペリア系端末持ってないから試せません。。。買えってことか。くぅ。
コメント
コメントを投稿