MSP430™ USB HID Windows APIプログラミングの手 … 2 TMMSP430 USB HID Windows APIプログラミングの手引き 2 実装以降のセクションでは、 Windows MSP430

JAJA452

この資料は、Texas Instruments Incorporated（TI）が英文で記述した資料を、皆様のご理解の一助

として頂くために日本テキサス・インスツルメンツ（日本TI）が英文から和文へ翻訳して作成した

ものです。資料によっては正規英語版資料の更新に対応していないものがあります。日本TI による

和文資料は、あくまでもTI 正規英語版をご理解頂くための補助的参考資料としてご使用下さい。製

品のご検討およびご採用にあたりましては必ず正規英語版の最新資料をご確認下さい。 TI および日本TI は、正規英語版にて更新の情報を提供しているにもかかわらず、更新以前の情報に

基づいて発生した問題や障害等につきましては如何なる責任も負いません。

SLAA453 翻訳版

最新の英語版資料 http://www.ti.com/lit/slaa453

MSP430TM USB HID Windows API プログラミングの手引き

William Goh, Keith Quiring MSP430 Applications

1 はじめに USB Human Interface Device (HID) クラスは、オペレーティング・システムで最も広くサポートされているデバイス・クラス

のひとつです。最初はマウスとキーボード用に開発されましたが、汎用使用においても多くの利点があります。一般的に、汎用USBアプリケーションには仮想COMポートが使用されます。仮想COMポートは、Communications Device Class(CDC)を使用して実装できます。COMポートはホストのプラットフォームへの実装が容易であり、また開発者にもよく理

解されています。短所は、Windowsマシン用のUSB仮想COMポートのソリューションでは、デバイスのインストール・プロセ

スをエンド・ユーザーが全部行わなければいけないことです。これだけでも少し手間がかかる上に、もしユーザーが不適切なオ

プションを選択してしまうと、インストール・プロセス自体が失敗する可能性があります。加えて、ユーザーの開発環境が企業

内にある場合は、ユーザーに管理者権限がないために、ネットワーク管理者の支援がないとデバイスのインストールを行えない

可能性があります。これに対して、HIDデバイスの場合には以上のような問題がすべて回避され、スムーズなインストールが可

能です。 HIDにもいくつか短所はあります。仮想COMポートと比較すれば、HIDの使用に慣れているソフトウェア・エンジニアの数は

あまり多くありません。HIDでは、データの送信(carry)を「レポート」に頼っていますが、レポートのように複雑なフォー

マットを使用すると、汎用アプリケーションの真の価値が発揮できない場合が多くなります。基本的なHID実装での帯域幅は、

64KB/秒に制限されています。このような短所を補うものとして、TIではWindows HID APIとデモ・プロジェクトを提供しています。このWindows HID APIは、MSP430のHID APIスタックにより実装できるデータパイプ・インターフェイスとの併用目的で簡素化されています。

そのため、HIDレポートを作成する必要がありません。Windows HID APIは複合HIDデバイスとともに機能するため、帯域幅

を拡大する一方で、複数のHIDインターフェイスをUSBデバイス内で容易に組み合わせることが可能になります。 MSP430 HID APIのスタックとWindows HID APIを併用することにより、多くの汎用アプリケーションにとって仮想COMポートよりもメリットの多くなる、徹底したソリューションが形成されます。 MSP430 MCUのUSBサポート・ソフトウェアについては、下記サイトのMSP430 USB 開発者パッケージ(Developers Package)を参照してください。 http://focus.ti.com/docs/toolsw/folders/print/msp430usbdevpack.html.

参考資料

http://focus.ti.com/docs/toolsw/folders/print/msp430usbdevpack.html

JAJA452 www.tij.co.jp

2 MSP430TM USB HID Windows APIプログラミングの手引き

2 実装以降のセクションでは、 Windows MSP430 HID APIを「Windows API」と表記します。

2.1 概要図1に、このAPIのWindowsソフトウェア・スタック内での位置と、MSP430デバイス上のUSB HID APIとの関係を示します。

図 1 WindowsとMSP430のソフトウェア・スタック

ソフトウェアは、MSP430用のUSB HID APIスタックのファームウェア、特にAPIスタックにより提供されるデータパイプ・

インターフェイスとともに使用するように設計されています。APIスタックとWindows APIをともに使用することで、ソフト

ウェア開発者がHIDレポートを使用する必要がなくなるため、開発者側ではデータ・インターフェイスを、COMポートと同様

のフォーマットされていないデータ・ストリームとして認識できるようになります。 HIDレポートを完全に不要にするために、データパイプ・インターフェイスでは非常にシンプルなHIDレポート構造体を実装

します。開発者側で、この構造体を変更する必要はありません。開発者側ではシンプルなコマンドを使用して任意のサイズの

データ・ブロックの送受信を行い、APIではこのデータを転送するためのデータ・パケットとしてレポートを使用します。デー

タパイプ・インターフェイスの詳細については、MSP430 USB CDC/HID API Stack Programmer's Guideを参照してくださ

い。)

www.tij.co.jp JAJA452

MSP430TM USB HID Windows APIプログラミングの手引き 3

2.2 ファイルの構成表1は、APIとデモ・アプリケーション内のファイルです。

表 1 ソース・コードのファイル

ファイル説明

デモ・アプリケーション

*.cpp C++ ファイル各種

API

hiddevice.c API 関数呼び出しと補助関数呼び出しのコード実装

hiddevice.h アプリケーションが使用できる API 関数呼び出しの定義

2.3 システム要件配布されているWindows APIは、Microsoft Foundation Class (MFC)ライブラリを使用して、Visual Studio 2008用に作成さ

れています。それ自体は、Windows Vista/XP/7を始めとする様々なWindowsプラットフォーム上で使用できます。APIはＣ言

語、デモ・アプリケーションはC++で書かれています。APIをコンパイルするにはVisual StudioのExpress Editionでも十分で

すが、デモ・アプリケーションのコンパイルには完全版が必要になります。 APIを使用するには、Windows Driver Kit (WDK)のインストールも必要になります。これは、Microsoftから無償で入手できま

す。以前のバージョンよりも高速になった、Ver. 7が推奨されます。 APIを WDKにリンクさせる手順は、次の通りです。

1. Microsoftのサイトから、最新版のWDKをダウンロードしてインストールします。 2. HidDevice.cというファイルを右クリックして、Properties を表示します。 3. 次のように項目をたどります。C/C++ → General → Additional Include Directories 4. 次の2つのディレクトリをインクルードします。

(a) c:\<WinDDK Install>\<Build Version>\inc\api\ (b) c:\<WinDDK Install>\<Build Version>\inc\crt\

5. 次のように項目をたどります。Linker → General → Additional Include Directories 6. 次のディレクトリをインクルードします。 c:\<WinDDK Install>\<Build Version>\lib\wxp\i386

2.4 MSP430 USB API のスタック MSP430 USB APIは、USBについての詳しい知識がなくてもUSBデバイスを容易に生成できるように設計されています。 MSP430 USB API に付属しているMSP430 USB Descriptor Toolでは、自動的に次の動作を行います。

- USBインターフェイス(単一または複合)の任意の組み合わせ用に、APIスタックを構成する。 - 最初に動作するUSB記述子を生成する。

HID用のAPIでは、2種類のHID実装が可能です。ひとつは従来のHIDデバイスであり、HIDレポートについての詳細な知識が

必須になります。もうひとつはデータパイプ HIDデバイスです。これは、HIDをシンプルなデータ・キャリア(data carrier)として使用するメソッドの、TI版の実装です。これにより、設計者側でHIDレポートを作成する必要がなくなります。 MSP430アプリケーションから見ると、HID-データパイプ間のインターフェイスのルック＆フィールは、次のようにCOMポー

トに非常によく似ています。 - 比較的フォーマットがシンプルなため(It is relatively unformatted)、設計者側で希望するフォーマットを適用できます。 - 任意のサイズのデータ・チャンクを処理できます。 (USBパケット・サイズに限定されません)



実際、HID-データパイプ用のAPIは、(ホスト上で仮想COMポートを生成するために使用される)CDC用のAPIとほとんど同一

です。 MSP430 USB API スタックの詳細な情報は、http://www.ti.com/430usbにあるリンクからダウンロードしてご覧になれます。

2.5 Windows が物理 USB の HID デバイスをホスト・アプリケーションにマッピングする) 方法 USBデバイスはどれでも、1つずつベンダーID(VID: vendor ID)と製品ID(PID: product ID)を持っています。USBホストで

は、製品のタイプを識別するために、VID/PIDの組み合わせを利用します。当然ですが、任意のVIDのベンダーで製造された、

任意のPIDを持つすべての製品は機能的に同一です。ホストでは、あるVID/PIDを持つすべてのデバイスを、特定のUSBデバ

イス・クラス -- 例えば、HIDまたはCDCと関連付けます。このVID/PIDを発見すると、ホストでは必ず上記の特定のドライバ

をロードします。上記のWindows HIDドライバに関しては、少し事情が違ってきます。HIDドライバでは、汎用インデックス(generic index)で選択可能な"HID デバイス"のリストをバス上に保持しており、ホスト・アプリケーションがこのリストを使用できるようにし

ています。このリスト内の "HID デバイス" は論理エンティティ(logical entities)であり、物理USBデバイスではありません。

これらの論理エンティティは必ずしも、バス上の物理デバイスに直接マッピングされているわけではありません。例えば、任意のVID/PIDを持つひとつ以上の"HIDデバイス"がホスト・アプリケーションにレポートされる可能性もあります。

このことは、任意の製品タイプの複数の物理デバイスがこのホストに接続されていると解釈することも、また(論理デバイスと

思われる)複数のHIDインターフェイスを持つ複合デバイスが存在すると解釈することも可能です。さらに、4個以上の(4+) "HIDデバイス" が存在する場合は、図2に示すように、これらの要因が両方とも関係している可能性もあります。

図 2 "HID インターフェイス"を Windowsシステム上の"HID デバイス"にマッピングする

この図では、これらの"HIDデバイス"が実世界の何を表しているのかを、Windowsアプリケーション側で即座に識別することが

できなくなっています。

http://www.ti.com/430usb



複数デバイスが存在するこのような状況で、ホスト・アプリケーションが正しく機能するには -- それだけでなく、物理デバイ

ス上の複数のHIDデータパイプを活用できるようにするには – ホスト・アプリケーション側で、さらに徹底的な調査が必要に

なります。ホスト・アプリケーションが各HIDデバイスから収集する必要がある情報の中でも重要なのが、(図2で"sernum"と表されている)シリアル番号です。USBデバイスでは、同じVID/PIDを持つすべての物理的機器の中の、ある特定の物理機器を

識別するシリアル番号をレポートすることがオプションとして可能になっています。(Descriptor Toolでシリアル番号の自動レ

ポートが選択されている場合は、MSP430 USB APIスタックではシリアル番号を自動的にレポートできます。) ホスト・アプリケーションが、バス上で見えている各HIDデバイスのVID、PID、シリアル番号を認識した後は、ホスト・アプ

リケーション側でバス上の状態を理解できるようになります。あるVID/PIDを持ち、しかもシリアル番号も同じである2つの

HIDデバイスを見つけた場合は、それが2つのHIDインターフェイスを持つ複合HIDデバイスであると認識できます。そうでは

なく、これら2つのHIDデバイスのシリアル番号が異なる場合は、アプリケーションには単一のインターフェイスを持つ2つの

物理HIDデバイスが接続されていることになります。これらの技術を使用すれば、開発者は複数のHIDインターフェイスを使用してデバイスを設計できます。その場合、各HIDイ

ンターフェイスは、特定の種類の情報用のデータパイプ -- 複数のCOMポートと同じものとして利用されます。複数のHIDイン

ターフェイスを使用する利点としては、単一のHIDインターフェイス(64kbps)を使用する場合のような帯域幅制限がなくなる可

能性があることも挙げられます。ひとつのMSP430上で8個ものHIDインターフェイスを並行して動作させながら、512kbpsという帯域幅を提供することも可能です。付け加える必要があるのは、最初のエニュメレーション中にWindowsがUSB記述子を読み取って、このデバイスがマウスか

キーボードであると認識した場合は、Windows自体がこのHIDデバイスの"ホスト・アプリケーション"となることです。 Windowsではレポート・リクエストを発行し、データを使用して、画面上のマウスの制御や、テキスト入力用のデータの入力

を行います。

2.6 システム上の特定の HID デバイス/インターフェイスを探してオープンするこのアプリケーション・ノートでは、このセクション以降、次の用語を使用します。

- HIDデバイス: Windows HID デバイス・リストにあるデバイス - 物理USBデバイス: 実世界のUSBハードウェアの一部分。USBバス上に、それ自体の固有アドレスを持つ。 - HIDインターフェイス: 物理USBデバイスのUSB記述子内で宣言されたインターフェイス。デバイス上の唯一のインター

フェイスであることもあれば、複数のインターフェイスのひとつとして、複合USBデバイスの一部を構成していること

もある。ひとつのHIDインターフェイスは、ひとつのWindowsのHIDデバイスに関連づけられている。

ホスト・アプリケーションの開発者は、USBデバイスへのアクセスを開始する際に、そのUSBデバイスが関連付けられている

VID/PIDのペアを知っているのが普通です。通常は、どちらのIDも同じメーカーによって指定されるためです。したがって、

プロセスはHID_GetSerNums()の呼び出しから始まります。この関数(function)はVID/PIDをパラメータとして受信し、シリア

ル番号のリストを返します。各シリアル番号は、VID/PIDと関連付けられたバス上の物理USBデバイスを表しています。アプ

リケーションでは、これらの物理デバイスのどれかひとつとのみ交信することを選択ことも、複数のデバイスと交信する機能を

持つこともできます。アプリケーションの開発者側ではまた、これらの各物理デバイスが持つインターフェイスの数も知っているのが普通です。何ら

かの理由でインターフェイスの数が分からない場合は、関数HID_GetNumOfInterfaces()を呼び出すことができます。

HID_Open() を呼び出してデバイスをオープンする場合は、物理デバイス上のHIDインターフェイスの総数を関数側が知ってい

る必要があります。 VID、PID、シリアル番号を使用してHIDデバイスのリストをフィルタリングすると、それらのパラメータによって記述される

物理USB デバイス内のすべてのHID インターフェイスを表すリストだけが残ります。このリストは通常は1つか2つですが、ひ

とつのMSP430上では最大で8つ存在できます。このリストの順序は、物理デバイスのUSB記述子内でHIDインターフェイスが



リストされていた順序と同じです。このようにして、ホスト・アプリケーションと、APIスタックを使用するMSP430 アプリ

ケーションは互いを「発見して」、完全なデータ・リンクを形成します。 VID/PID、シリアル番号、USB デバイス内の必要なHIDインターフェイスのインデックスを装備することにより、アプリケー

ションではHID_Open()を呼び出して、物理USB デバイス上のHID インターフェイスへの接続をオープンすることができま

す。 (たとえばプログラムから抜ける時に)アプリケーションによるデバイスの使用が終わると、アプリケーションではHID_Close()を使用して、オープンしているHID デバイスをすべてクローズする必要があります。

2.7 データの送信/受信 (このインターフェイスがMSP430 HID API上の"データパイプ" インターフェイスとしてセットアップされると仮定した場合

に)HIDインターフェイスがオープンされると、HID_writeFile()呼び出しとHID_readFile()呼び出しを使用して、任意のサイズ

のデータ・チャンクを送信/受信することがAPIで可能になります。呼び出しでは、データをひとつ以上のHIDレポートにパ

ケット化する処理を自動的に行います。 "データパイプ"ではなく"従来の" HID デバイスを実装する場合、つまりレポートのフォーマットがカスタマイズされていて、

HIDに従来から備わっている関数呼び出しがMSP430 HID アプリケーションで使用されている場合でも、このAPIを一例とし

て使用することは可能ですが、APIのコードをカスタマイズする必要があります。

2.8 HID デバイスの動的接続/切断の検出従来のCOMポートとは異なり、USBアプリケーションでは、ユーザー側でデバイスが切断(または接続)される可能性があるこ

とを、どの時点においても認識している必要があります。これが、USBの持つ動的(ダイナミック)な「プラグ・アンド・プレ

イ」という側面です。Windowsでは、MFCライブラリに実装されている通知(notifications)を介して、動的接続/切断を処理し

ています。通知はアプリケーションのウィンドウ・オブジェクトに直接送られるため、動的接続/切断はAPIの外部で発生しま

すが、これらの通知が受信されると、アプリケーションでは特にこの目的のために提供されたAPIハンドラを呼び出すことがで

きます。デモ・アプリケーションでは、動的接続/切断がどのように行われるかを示しています。以下は、アプリケーションで上記の通知を処理するために必須の手順です。

1. デバイスの変更通知を受信するために、アプリケーションでは開始時にHID_RegisterFoDeviceNotification()を使用し

て、アプリケーション自体のウィンドウを登録しておく必要があります。 2. そのウィンドウ用のメッセージ・マップにON_WM_DEVICECHANGEを入れます。(確実に、AFX_MSG_MAPのコメ

ント部分の外側に入れるようにしてください) 3. そのウィンドウ用のパブリック関数(public function)として、OnDeviceChange()という関数を作成します。このメッ

セージ・ハンドラは、ON_WM_DEVICECHANGE 通知に応答して、MFCフレームワークに呼び出されます。

関数の定義は次の通りです。

この関数では、このアプリケーションに使用される"HID デバイス"のどれかがシステムから除去されたかどうかを判定する必

要があります。その目的のために、この関数ではオープンしている各HIDデバイス用にHID_IsDeviceAffected()を呼び出して、

それらが除去されているかどうかを判定できます。アプリケーションを抜けた時は、アプリケーション側でHID_UnregisterForDeviceNotification()を使用して、必ずウィンドウ

の登録を解除しておく必要があります。



3 関数呼び出しのリファレンス

3.1 デバイスの接続管理と初期化呼び出し表 2に、デバイス接続管理呼び出しをまとめてあります。

表 2 デバイス接続管理呼び出しのまとめ

関数説明

VOID HID_Init() HID デバイス/インターフェイスに関する情報の格納に使用される HID デバイスのデータ

構造体を初期化します。

DWORD HID_GetNumOfInterfaces() 特定の VID/PID とシリアル番号と関連付けられたシステム上の HID デバイスの数を返し

ます。

BYTE HID_Open() 特定のデバイスに対するハンドルをオープンします。

BYTE HID_Close() 特定のデバイスに対するハンドルをクローズします。

BYTE HID_GetSerNums() 特定の VID/PID と関連付けられたシリアル番号を取得します。

3.1.1 VOID HID_Init(struct strHidDevice* pstrHidDevice)

説明この関数は、pstrHidDeviceを初期化します。これは、使用される前に、strHidDevice 構造体のインスタンス1つにつき1回呼

び出される必要があります。パラメータ

表 3 HID_Init()のパラメータ

strHidDevice* pstrHidDevice 初期化対象の構造体です。

3.1.2 DWORD HID_GetSerNums(WORD vid, WORD pid, struct strTrackSerialNumbers *serialNumList)

説明このvidとpidの組み合わせと関連付けられたシステム上の物理USB デバイスの数を返します。(これらのデバイスは、HID型で

あることも、そうでないこともあります。) 接続されたデバイスがない場合は、ゼロを返します。デバイスが接続されている場合は、渡されたstrTrackSerialNumbers 構造体に、検索された物理デバイスに対応するシリアル

番号が追加され、関数がリスト内のシリアル番号の総数を返します。返された結果がひとつ以上の場合は、そのvid/pidの組み合わせについて複数の物理デバイスが存在することになります。パラメータ

表 4 HID_GetSerNums()用のパラメータ

WORD vid 検索対象となるデバイスの、16 ビットのベンダーID です。

WORD pid 検索対象となるデバイスの、16 ビットの製品 ID です。

struct strTrackSerialNumbers

*serialNumList

vid/pid と関連付けられたシリアル番号のリストを含む構造体です。

この関数は、検索されたシリアル番号を構造体に追加します。

戻り値 0: この VID/PID を持つ物理 USB デバイスがない場合。

0 以外: システム上の、この VID/PID を持つ物理 USB デバイスの数

表 5 strTrackSerialNumbers 構造体の定義

フィールド説明

DWORD DeviceNum 物理 USB デバイスを表すインデックス番号です。

char serialNum[SERNUM_LEN]; 検出された物理デバイスのシリアル番号を含むストリングです。



3.1.3 DWORD HID_GetNumOfInterfaces(WORD vid, WORD pid, DWORD numSerNums)

説明 vidとpidによって識別される各物理USBデバイス内に存在するHIDインターフェイスの数を返します。そのようなデバイスが

接続されていない場合は、関数はゼロを返します。 numSerNumsは、このVID/PIDで関連付けられたシステム上の物理デバイスの数です。この関数では、目的を達成するため

に、Windows HID デバイスのリスト(つまり、システム上に登録された論理HID デバイス)をスキャンして、このVID/PIDと関

連付けられた HID デバイスの数をカウントした後、その数を numSerNums で除算します。 numSerNums は、

HID_GetSerNums()を呼び出すことで検索できます。単一インターフェイス HID デバイスの場合には、常に1という値が返されるようになっています。パラメータ

表 6 HID_GetNumOfInterfaces()用のパラメータ

UINT vid 検索対象となるデバイスの、16 ビットのベンダーID です。

UINT pid 検索対象となるデバイスの、16 ビットの製品 ID です。

DWORD numSerNums VID/PID を持つ、接続された物理デバイスの総数です。

戻り値 0: この VID/PID を持つ USB デバイスが接続されていない場合。

0 以外: システム上の、この VID/PID を持つ USB デバイスの数

3.1.4 BYTE HID_Open(struct strHidDevice* pstrHidDevice, WORD vid, WORD pid, DWORD

DeviceIndex, char serialNumber[SERNUM_LEN], DWORD totalDevNum, DWORD totalSerNum)

説明システム上の、VID/PIDとシリアル番号と関連付けられたデバイスのリスト内にある、インデックス DeviceIndex のデバイス

を探します。見つかった場合は、デバイスへのハンドルをオープンし、pstrHidDevice 構造体内にそれを格納します。また、構

造体内の他のフィールドもロードします。目的を達成するために、HID_Open()は2つの追加パラメータを必要とします。ひとつはtotalDevNumです。これはvidとpidによって記述される、デバイス上のHID インターフェイスの数であり、通常はすでに開発者側も知っている情報です。そうでな

い場合は、HID_GetNumOfInterfaces() を呼び出すことができます。もうひとつの必須パラメータはtotalSerNumです。これ

はシステム上の、このVID/PIDとマッチするシリアル番号 (物理デバイス)の総数です。 deviceIndexは、「0」から「totalDevNum－1」までの範囲の数字です。vid、pid、serialNumberを使用してWindows のHID デバイスのリストをフィルタリングすると、リストが効率的に、ある特定の物理USBデバイス内に含まれるHIDインターフェ

イスを表すHIDデバイスに要約されます。あとはそれらのインターフェイスのひとつを選択するだけで済みますが、この選択を

行うのがDeviceIndexです。これらのHID デバイスの順序(ゼロ～totalDevNum)は、デバイスのUSB記述子内でHIDインター

フェイスが宣言された順序と同じです。(セクション2.5参照). vidとpidによって記述されたデバイス内にHIDインターフェイスがひとつしかない場合は、DeviceIndexは「0」となります。この関数は、このデバイスが実際にHIDデバイスであり、もうひとつのタイプであるUSBデバイスではないことを前提として

います。パラメータ

表 7 HID_Open()用のパラメータ

strHidDevice* pstrHidDevice 新規にオープンされたデバイスを含む構造体です。

WORD vid オープンする対象となるデバイスの、16 ビットのベンダーID です。

WORD pid オープンする対象となるデバイスの、16 ビットの製品 ID です。

DWORD DeviceIndex この VID/PID とシリアル番号の、使用可能なデバイス内のインデックスです。

char serialNumber[SERNUM_LEN] 検索対象のデバイスのシリアル番号のサイズ SERNUM_LEN (40)の Char ストリングです。

DWORD totalDevNum この VID/PID とシリアル番号によって記述される物理デバイスの HID インターフェイスの

総数です。



DWORD totalSerNum この VID/PID についての、使用可能な物理 USB デバイスの総数です。

戻り値 HID_DEVICE_SUCCESS. デバイスが検索されてオープンされました。

HID_DEVICE_ALREADY_OPENED. デバイスはすでにオープンされています。

HID_DEVICE_NOT_FOUND. この VID/PID/インデックスによって識別されるデバイスが見つ

かりませんでした。

3.1.5 BYTE HID_Close(struct strHidDevice* pstrHidDevice)

説明このpstrHidDevice 構造体と関連付けられたデバイスをクローズし、システムに命令してハンドルをクローズします。この動作

をデバイスに行う場合は、必ずアプリケーションがこの動作を実行する必要があります。パラメータ

表 8 HID_Close()用のパラメータ

strHidDevice* pstrHidDevice 新規にオープンされたデバイスを含む構造体です。

戻り値 HID_DEVICE_HANDLE_ERROR デバイスのハンドルが無効です。

HID_DEVICE_SUCCESS デバイスのハンドルが正常にクローズされます。

HID_DEVICE_NOT_OPENED それまでオープンされていなかったデバイスのハンドルをク

ローズすることが試みられました。

3.1.6 BYTE HID_GetVersionNumber(struct strHidDevice* pstrHidDevice, USHORT * VersionNumber)

説明 pstrHidDeviceと関連付けられたデバイスのリリース番号をVersionNumber内に配置します。これは、物理 USB デバイスのデ

バイス記述子のbcdDeviceフィールド内でレポートされた値です。パラメータ

表 9 HID_ GetVersionNumber()用のパラメータ

strHidDevice* pstrHidDevice HID デバイス情報を含む構造体です。

USHORT* VersionNumber デバイスのリリース番号です。

戻り値 HID_DEVICE_HANDLE_ERROR デバイスのハンドルが無効です。

HID_DEVICE_SUCCESS

3.2 データの送信/受信表 10の呼び出しは、データの送信/受信に関連しています。

表 10 デバイス接続管理呼び出しのまとめ

関数説明

BYTE HID_WriteFile() デバイスにデータを送信します。

BYTE HID_ReadFile() デバイスからデータを受信します。



3.2.1 BYTE HID_WriteFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize,

DWORD* bytesSent)

説明バッファに格納されたbufferSize バイトのデータを、pstrHidDeviceによって指定されたHID デバイスに送信します。この関数は、「パケット」としてHIDレポートを使用することでデータを送信します。HIDレポートを送信するための試みが

タイムアウトになった場合は、関数によりHID_DEVICE_TRANSFER_TIMEOUTが返されます。 DWORD値であるbufferSizeによって課された制限以外には、送信可能なバイト数に固有の(inherent)制限はありません。パケット化は自動的に処理(ハンドリング)されます。パラメータ

表 11 HID_WriteFile()用のパラメータ


BYTE* buffer 送信されるデータの配列です。

DWORD bufferSize アドレス・バッファから始まる、送信されるバイト数です。

DWORD bytesSent (エラーが発生した場合に)実際に送信されたバイト数です。

戻り値 HID_DEVICE_NOT_OPENED HID デバイスをオープンするのに失敗しました。

HID_DEVICE_TRANSFER_TIMEOUT レポート・リクエストがタイムアウトになりました。

HID_DEVICE_TRANSFER_FAILED.特定できない理由で送信が失敗しました。

HID_DEVICE_SUCCESS. 全データが正常に送信されました。

3.2.2 BYTE HID_ReadFile(struct strHidDevice* pStrHidDevice, BYTE* buffer, DWORD bufferSize,

DWORD* bytesReturned)

説明 pStrHidDeviceに指定されたHID デバイスからペイロード・データのbufferSizeバイトを取得し、バッファに格納します。これ

は、bufferSizeバイトが返されるまで、必要なだけの数のHIDレポートを読み出すことで行われます。関数がHID_DEVICE_SUCCESSを返した場合は、 bytesReturnedがbufferSizeと等しくなります。 bytesReturnedは、他の戻りコードのうちどれかひとつの場合にのみ、bufferSizeよりも小さくなります。この関数は、「パケット」としてHIDレポートを使用することでデータを受信します。pStrHidDevice.uGetReportTimeoutの値に従って、 USB デバイスからパケットをフェッチする試みがタイムアウトになった場合は、関数により

HID_DEVICE_TRANSFER_TIMEOUTが返されます。 DWORD値であるbufferSizeによって課された制限以外には、受信可能なバイト数に固有の(inherent)制限はありません。パ

ケット化は自動的に処理(ハンドリング)されます。パラメータ

表 12 HID_ReadFile()用のパラメータ


BYTE* buffer 受信されるデータを含む配列です。

DWORD bufferSize 受信予定のバイト量の最大値を示す、バッファのサイズです。

DWORD* bytesReturned (エラーが発生した場合に)実際に受信されたバイト数です。

戻り値 HID_DEVICE_NOT_OPENED. HID デバイスをオープンするのに失敗しました。

HID_DEVICE_TRANSFER_TIMEOUT. レポート・リクエストがタイムアウトになりました。

HID_DEVICE_TRANSFER_FAILED. 特定できない理由で送信が失敗しました。

HID_DEVICE_SUCCESS. 正しいバイト数が受信されました。



3.3 プラグ・アンド・プレイの管理表13にある呼び出しでは、アプリケーションによるUSB デバイスの動的接続/切断の管理を補助します。

表 13 デバイス接続管理の呼び出しのまとめ

関数説明

BYTE HID_RegisterFoDeviceNotification() デバイスをデータに送信します。

BYTE HID_UnregisterForDeviceNotification() デバイスからデータを受信します。

BYTE HID_IsDeviceAffected() 特定のデバイスがまだシステム上に存在しているかどうかを判定します。

3.3.1 BYTE HID_RegisterForDeviceNotification(HWND hWnd, HDEVNOTIFY* diNotifyHandle)

説明デバイスがシステムに追加されたり、システムから除去されたりするときに通知を受信するために、ハンドルhWndによってポ

イントされたウィンドウを登録します。アプリケーションがシステムの通知に応答できるようにするために、セクション2.6で説明されている手順を実行する必要があります。デバイスの通知ハンドルが、diNotifyHandleで返されます。これは、HID_UnregisterForDeviceNotification()を呼び出す際に

使用するために、アプリケーションによって格納される必要があります。パラメータ

表 14 HID_RegisterForDeviceNotification()用のパラメータ

HWND hWnd メイン・ウィンドウに対するハンドルです。

HDEVNOTIFY* diNotifyHandle デバイスの通知ハンドルです。

戻り値 HID_Device_HANDLE_ERROR. デバイスのハンドルが無効です。

HID_Device_SUCCESS

3.3.2 BYTE HID_UnregisterForDeviceNotification(HDEVNOTIFY* diNotifyHandle)

説明デバイスの通知ハンドルdiNotifyHandleによってポイントされたウィンドウの登録を解除します。diNotifyHandleは、 HID_RegisterForDeviceNotificationによって返されます。この呼び出しの後は、デバイスがシステムに追加されてもシステム

から除去されても、Windowsからアプリケーションにそれが通知されることはなくなります。関数は、ハンドルが有効である

かどうかに関係なくtrueを返します。パラメータ

表 15 HID_UnregisterForDeviceNotification()用のパラメータ

HDEVNOTIFY* diNotifyHandle デバイスの通知ハンドルです。

戻り値 HID_Device_SUCCESS

3.3.3 BOOL IsDeviceAffected(struct strHidDevice* pstrHidDevice)

説明アプリケーションでは、システムから受信されたON_WM_DeviceCHANGE通知に応答して、この関数を呼び出す必要があり

ます。この関数は、イベントが、pstrHidDeviceと関連付けられたデバイスを参照するかどうかを示します。パラメータ

表 16 HID_IsThisDeviceAffected()用のパラメータ


戻り値 TRUE または FALSE



4 デモ・アプリケーション APIの使い方を示す目的で、シンプルなデモ・アプリケーションが提供されています。アプリケーションは、Hyperterminalのような、COMポートのターミナル・アプリケーションと似たものと考えることができます。HIDインターフェイスでの送受信

以外の場合には、COMポートのターミナル・アプリケーションと同様の方法でデータ・チャンクの送受信を行います。

図 3 デモ・アプリケーションのウィンドウ

プログラムを動作させるには、データパイプ関数呼び出しを使用して、HID APIスタックを動作させているMSP430を接続しま

す。プログラム例のいくつかには、API スタックのディストリビューションが付いています。単一インターフェイスHID、

CDC+HID複合デバイス、HID+HID複合デバイスの例がそれぞれひとつずつあり、どれもこのデモ・アプリケーションで使用

できます。 GUIにあるVIDフィールドとPIDフィールドでは、アプリケーションの検索対象となるVID/PIDを選択します。VID/PIDを入力

した後、"Set VID/PID"ボタンを押します。 VID/PIDが設定されると、アプリケーションでは、このVID/PIDとマッチするシステムに接続されている物理デバイスの数を

判定し、それらのデバイスのシリアル番号を検索して、"Serial Number"コンボ・ボックスに記載します。リスト中の最初のシ

リアル番号が自動的に選択され、続いてそのデバイス上に存在するHIDインターフェイスの数が判定されます。"Interface" コンボ・ボックスに、これらの各インターフェイスに対応する文字列("HID 0"、"HID 1"等)がロードされます。 HID インター

フェイスが見つかった場合は、デフォルトで"HID 0"が選択されます。 "Connect" ボタンを押すと、USBデバイスとのデータ接続がオープンされます。成功した場合には、ボタンの下の文字列でそう

示されます。失敗の場合は、次の手順を試みてください。



- Windowsのデバイス・マネージャをチェックして、デバイスがシステム上でHIDデバイスとして正常にエニュメレート

(列挙)されているかどうかを確認します。 - デバイスに、HID-データ・パイプ・アプリケーションを動作させているMSP430 HID API スタックが備わっているかど

うかを確認します。 - descriptors.hに示されているVID/PIDが、デモ・アプリのフィールドに入力されたのと同じペアであることと、"Set

VID/PID"ボタンが押されたかどうかを確認します。接続が初期化されると、テキストを入力して"Send"を押すことにより、デバイスにデータを送信できるようになります。任意の時点でアプリケーションにより受信された、デバイスからのデータは、大きなテキスト・フィールドに表示されます。受

信ウィンドウは、"Clear" ボタンでクリアできます。他のデバイスがアクセスされている間にHIDデバイスがバスから除去された場合、あるいはこのVID/PIDを持つ他のHIDデバ

イスが追加された場合は、アプリケーションでは自動的にプルダウン・メニューのリストを更新します。

5 MSP430 USB Tool Suite このAPIは、MSP430上でのUSBの使用を容易にするためにTIが提供する完全なツール一式(suite of tools)の一部であり、次の

ような構成になっています。 MSP430 USB API スタック

- CDC (Communications Device Class[通信デバイス・クラス]) - HID (Human Interface Device class[ヒューマン・インターフェイス・デバイス・クラス]) - MSC (Mass Storage Class[大容量記憶クラス])

MSP430 USB Descriptor Tool 最初に機能するUSB記述子を使用して、任意の組み合わせのUSBインターフェイス(単一または複合USB デバイス)用に、

USB API スタックを自動的に構成します。 MSP430 USB Field Firmware Update Starter Project

PCから、MSP430上のフィールド内のファームウェアをUSBに関して更新するための、 Windows Visual Studio Expressプロジェクトです。

6 参考文献 1. MSP430 USB API Stack Programmer's Guide (accompanies the API Stack download; see the link to the MSP430

USB Developer's Package, located at http://www.ti.com/430usb) 2. Microsoft Developers Network reference for HID: 3. http://msdn.microsoft.com/en-us/library/dd446410.aspx 4. If support is needed, go to http://www.ti.com/msp430 and see the support options.



付録 A HID インターフェイスのデータ構造体: strHidDevice APIでは、データ構造体を使用して、hidDevice.h (表17参照)で定義されたHID デバイスに関連するすべての情報を格納

(contain)します。構造体のインスタンスは、デバイスの関与する任意のAPI呼び出しに渡されます。

表 17 strHidDevice 構造体の定義

フィールド説明データ発信元

HANDLE hndHidDevice この HID デバイスに対するハンドルです。 HID_Open()で作成されています。HID_Close()

の間は、 INVALID_HANDLE_VALUE に設定

されています。

BOOL bDeviceOpen デバイスがオープンされており、

hndHidDevice 内のハンドルが有効であるこ

とを示すブール値(Boolean)です。

HID_Open() および HID_Close()で作成されて

います。

UINT uGetReportTimeout データ読み出しの、ミリ秒単位のタイムアウ

ト値です。これは、データ読み出し動作の間

に、デバイスからの任意のレポートを

HID_ReadFile()が待機する時間の長さです。

アプリケーションにより初期化される必要が

あります。デモ・アプリケーションは、

UsbAppDlg.cpp 内でこれを行います。

UINT uSetReportTimeout データ書き込みの、ミリ秒単位のタイムアウ

ト値です。これは、データ送信動作の間に、

デバイスが任意のレポートを受信するのを

HID_WriteFile()が待機する時間の長さです。

アプリケーションにより初期化される必要が

あります。デモ・アプリケーションは、

UsbAppDlg.cpp 内でこれを行います。

OVERLAPPED oRead 非同期 I/O 構造体です。 HID_Init()によって初期化されます。

OVERLAPPED oWrite 非同期 I/O 構造体です。 HID_Init()によって初期化されます。

WORD wInReportBufferLength 入力レポートの最大長です。 HID_Init()によって初期化され、デバイスの

USB 記述子から導き出されます。

WORD wOutReportBufferLength 出力レポートの最大長です。 HID_Init()によって初期化され、デバイスの

USB 記述子から導き出されます。

BYTE inBuffer[256] 着信データを受信するためのバッファです。 HID_readFile()によって作成され、アプリケー

ションによって読み出されます。

WORD inBufferUsed inBuffer[]内のバイト数です。 HID_readFile()によって作成され、アプリケー

ションによって読み出されます。



付録 B HID-データパイプ・デバイス上のフォーマット・レポート MSP430 USB API スタックを動作させ、HID-データパイプ・インターフェイスを作成するUSB デバイスでは、表 18に示すよ

うにフォーマットされたHIDレポートを使用します。これは、物理USB デバイス内にあるUSB記述子内で定義されています。このWindows APIでは同じフォーマットを使用しており、そして実際に、HID デバイスがこのフォーマットを使用しているこ

とを前提としています。

表 18 HID データパイプのレポートの構造体

フィールドサイズ

Report ID

(レポート ID)

1 バイト(0x3F)

サイズ

(Size)

1 バイト

データ

(Data)

N～2 バイト。ここで、N は USB パケットのペイロードのサイ

ズ(つまり、USB API スタック内の descriptors.h ファイルに

定義された MAX_PACKET_SIZE 値)です。

IMPORTANT NOTICE

Documents

MSP430™ USB HID Windows APIプログラミングの手 … 2 TMMSP430 USB HID Windows APIプログラミングの手引き 2 実装 以降のセクションでは、 Windows MSP430

MSP430™ USB HID Windows APIプログラミングの手 … 2 TMMSP430 USB HID Windows APIプログラミングの手引き 2 実装以降のセクションでは、 Windows MSP430