アプリケーションノート 155

1-Wireソフトウェアリソースガイドデバイス解説


要約: マキシムが現在製造している1-Wire®製品は、iButton®デバイスを含めて30以上あります。これらの製品と通信を行うための利用可能なAPI、ソフトウェア例、およびその他のリソースを入手したり、ある特定のデバイス用に適当なリソースを見つけるのは大変な作業になることがあります。このアプリケーションノートは、入手可能なリソースと選択ガイドの概要を提供します。最新の1-Wire製品もまた、製品説明とファミリコード早見表のある便利な表で紹介されています。

入手可能なAPIには、TMEX (Microsoft Windows®用API)、1-Wireパブリックドメインキット(クロスプラットフォームAPI)、およびJava™ (OWAPI)用1-Wire APIやそのバリエーション.NET (OW.NET)用1-Wire API、および.NET Compact (OW.NET.Compact)用1-Wire APIなどがあります。このアプリケーションノートにあるAPIはすべて制限なく自由に使用することが可能で、多くの場合完全なソースコードが含まれています。

はじめに

マキシムが現在製造中の1-Wireデバイスは、iButtonデバイスなどを含めて30点を超えます。利用可能なアプリケーションプログラムインタフェース(API)、ソフトウェア事例、およびこの一連の素子と通信する他のリソース、あるいは単一のデバイスタイプ用の適切なリソースを突き止めるのは煩わしい場合があります。そこで、この解説書では、利用可能なリソースの概要と選択ガイドを提供します。この解説書に記載されたすべてのAPIは無制限に自由に利用することが可能で、ほとんどの場合ソースコード一式を備えています。

1-Wireの概要

1-Wireバスは、単一接続で1つのマスタと複数の周辺機器との双方向通信を実行するシンプルな信号方式です。全1-Wireバスデバイスが共有している高機能とは、チップやiButtonのどのデバイスも他のデバイスと重複しない、工場で設定された登録番号を備えていることです。つまり、どのデバイスも他と重複しません。このため、同一バスワイヤに接続できる多数のデバイスの中から、どのデバイスでも個別に選び出すことができます。また、通信用に1本のワイヤを1台、2台、または数十台の1-Wireデバイスでも共有することができるため、バイナリ検索アルゴリズムを使って各デバイスを順次検出することができます。一度各デバイスの登録番号が判明すると、そのデバイスにアドレスするために登録番号を使い、どのデバイスも通信用に一意に選択することができます。

どの通信でも、最初はバス全体を同期させる「リセット」を送出するバスマスタが必要です。次にスレーブデバイスが以降の通信用に選択されます。これは、全スレーブを選択するか、特定のスレーブを選択するか(デバイスの登録番号によって)、またはバイナリ検索アルゴリズムを使用してバス上の次のスレーブを検出することによって実行することができます。こうしたコマンドは、「ネットワーク」機能または読取り専用メモリ(ROM)コマンドと総称されています。特定のデバイスが選択されると、その他のすべてのデバイスは脱落し、次のリセットが送出されるまで以降の通信を無視します。

また、あるデバイスがバス通信のために分離されると、マスタはそのデバイスに固有のコマンドを出したり、データを送信したり、またはそのデバイスからデータを読み込んだりすることができます。それぞれのデバイスタイプは、各種の機能を実行し各種の目的を果たすため、各デバイスタイプがいったん選択されるとそれぞれ固有のプロトコルを確保します。たとえ個々のデバイスタイプが異なったプロトコルと機能を備えていても、すべて同じ選択プロセスになり、図1のようなコマンドフローにしたがいます。

図1. 標準的1-Wireの通信フロー
図1. 標準的1-Wireの通信フロー

各スレーブにおける固有の登録番号の絶対必要な部分は、8ビットのファミリコードです。このコードは、各デバイスモデルに固有のコードです。各デバイスモデルは各種機能を実行しますので、デバイスの制御と信号を送るのに使用するプロトコルを選択するためにこのコードを使用します。マキシム1-Wire製品に対するファミリコードの割当てについては、表1を参照してください。

表1. ファミリコード対照表
ファミリ
コード
製品
() - iButtonパッケージ
説明
(特に指定のない限りメモリのサイズはビットで表記)
01 (16進) (DS1990A), (DS1990R), DS2401, DS2411 1-Wireネットアドレス(登録番号)のみ
02 (DS1991)¹ Multikey iButton、1152ビットの安全なメモリ
04 (DS1994), DS2404 4Kb NV RAMメモリとクロック、タイマ、アラーム
05 DS2405¹ 単一のアドレス可能なスイッチ
06 (DS1993) 4Kb NV RAMメモリ
08 (DS1992) 1Kb NV RAMメモリ
09 (DS1982), DS2502 1Kb EPROMメモリ
0A (DS1995) 16Kb NV RAMメモリ
0B (DS1985), DS2505 16Kb EPROMメモリ
0C (DS1996) 64Kb NV RAMメモリ
0F (DS1986), DS2506 64Kb EPROMメモリ
10 (DS1920) 警報発生付き温度
12 DS2406, DS2407¹ 1Kb EPROMメモリ、2チャネルアドレス可能スイッチ
14 (DS1971), DS2430A¹ 256ビットEEPROMメモリと64ビットOTPレジスタ
1A (DS1963L)¹ 書込みサイクルカウンタ付き4Kb NV RAMメモリ
1C DS28E04-100 4096ビットEEPROMメモリ、2チャネルアドレス可能スイッチ
1D DS2423¹ 外部カウンタ付き4Kb NV RAMメモリ
1F DS2409¹ サブネット用2チャネルアドレス可能カプラ
20 DS2450 4チャネルA/Dコンバータ(ADC)
21 (DS1921G), (DS1921H), (DS1921Z) Thermochron®温度ロガー
23 (DS1973), DS2433 4Kb EEPROMメモリ
24 (DS1904), DS2415 リアルタイムクロック(RTC)
27 DS2417 割込み付きRTC
29 DS2408 8チャネルアドレス可能スイッチ
2C DS2890¹ 単一チャネルのディジタルポテンショメータ
2D (DS1972), DS2431 1024ビット、1-Wire EEPROM
37 (DS1977) パスワードで保護された32KB (バイト) EEPROM
3A (DS2413) 2チャネルのアドレス可能スイッチ
41 (DS1922L), (DS1922T), (DS1923), DS2422 高容量のThermochron (温度)とHygrochron™ (湿度)のロガー
42 DS28EA00 シーケンス検出およびPIO付きプログラマブル分解能ディジタル温度計
43 DS28EC20 20Kb 1-Wire EEPROM
*このリストには、マキシムの1-Wireデバイスの全タイプ(ファミリ)が含まれているわけではなく、Automatic Information Business Unit (BU)のソフトウェアライブラリがサポートしている一つのディレクトリに過ぎません。
¹これらのデバイスは新規設計用に推奨されていません。

APIの基礎

1-Wireデバイスとの通信用の各種アプリケーションプログラムインタフェース(API)は、プロトコルに起因する基礎的な通信課題に対応する共通の機能を備えています。図2は、各種APIの機能を共通グループ化したものを概説しています。ほとんどの1-Wireデバイスはメモリを装備しているため、メモリI/O機能は全デバイスに該当しなくても、共通APIグループとして取り扱われます。すべてのメモリ以外のその他の特殊機能は、デバイス固有のデバイスグループに一括されます。

セッション
1-Wireバスの排他的使用をネゴシエート。これは、複数のプロセスやスレッドが同じ1-Wireバスに同時にアクセスしようとするオペレーティングシステムや環境では特に重要となります。割込み禁止の単一デバイス上で複数の操作を実行する際には、ネットワークの排他的使用が必要です。
リンク
根源となる1-Wireバス通信機能。すべての1-Wire通信は、全デバイスと読取り/書込みビットをリセットする「リセット」に凝縮することができます。また、このグループは、特別なEPROMプログラミングパルスまたは電力を供給するときのバスの電気的特性を設定する機能を含めることもできます。
ネットワーク
デバイス検出および選択用のネットワーク機能。各1-Wireデバイスに設定されている固有の登録番号は、各デバイスのネットワークアドレスとして使用されます。この機能はLINKレベル機能で構成されています。登録番号は読取り専用メモリ(Read-Only Memory)であるため、1-Wireデバイスのデータシートではこの機能をROMコマンドと呼んでいます。一部の1-Wireマスタは、リンク機能よりも効果的なネットワーク機能を内蔵しています。
転送
ブロック通信および基礎的な読取り/書込みメモリ機能。パケットの読取り/書込みメモリ機能を含めることもできます。これらの機能は、「ネットワーク」と「リンク」のグループ機能で構成されています。
ファイル
1-Wireファイル構造を使用したファイルメモリレベル機能(アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」を参照)。これらの機能は、「ネットワーク」と「転送」のレベル機能で構成されており、1ページ以上のメモリを備えたデバイスにのみ有効です。
デバイス
デバイス固有の「ハイレベル」機能。多くの場合、これらの機能は、「ネットワーク」、「転送」、および「リンク」のグループ機能で構成され、温度の読取りやスイッチ状態の設定などの操作を実行します。
図2. API機能グループ

これらの機能を使用するための標準的な手順は、図3に概説されています。「セッション」機能はデバイスへの通信呼び出しを包括し、これは通常、メモリまたは「デバイス」固有の操作の前に来る「ネットワーク」機能を利用することになります。

図3. APIの使用法フロー
図3. APIの使用法フロー

iButton通信の特質は、本質的に「接触」です。これは、デバイスとの接触が常に信頼性があるとは限らないことを意味します。iButtonはリーダに挿入され、読取り時に断続的な接触が生じることがあります。したがって、エラーリカバリに関して一貫した方式を厳格に守る必要があります。これは通常、データ通信でスプリアスエラーが検出されたときに再試行を行うこと、およびCRCチェックを利用することを必要とします。APIのファイルI/O機能は、アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」の箇所に詳述されている標準ファイル構造を使用します。この構造は、読取り中のデータの妥当性を迅速に検証するために、データの全ページでCRC16を使用します。たいていの1-Wire API機能には、自動再試行機能が全くないか少ししかありません。再試行は、アプリケーションが制御します。1-Wire通信実行時のエラー回復とリスク評価の方法については、アプリケーションノート159 「iButton®アプリケーションで堅牢な1-Wire®通信を実現するためのソフトウェア手法」を参照してください。

APIの選択

このアプリケーションノートでは、主として5種類のAPIを取り上げています。これらのAPIは各種プラットフォームで動作し、各種言語を使用し、また各種機能を備えています。表2は5種類のAPIを簡単な説明付きで紹介しており、また表3は、言語で分類された利用可能なAPIをオペレーティングシステムに割り当てています。

表2. APIの概要
API 省略形 概要
1-Wireパブリックドメイン PD Cで記述された完全なオープンソースのパブリックドメインAPIであり、多数のPCオペレーティングシステム、ハンドヘルドオペレーティングシステム、およびマイクロコントローラのプラットフォーム間で移植することができるように設計されています。PCプラットフォームの場合、32ビットMicrosoft Windows上でネイティブドライバのライブラリを通じてすべての1-Wireアダプタ(マスタ)をサポートしており、またクロスプラットフォームライブラリを使用する他のPCオペレーティングシステム上では、特定の1-Wireアダプタ(DS9097UシリアルアダプタやDS9490 USBアダプタ)をサポートしています。
Java用1-Wire API OWAPI ほぼすべての1-Wireデバイスをサポートする完全なオープンソースの高レベルJava API。本来の1-Wireマスタのサポートに加えて、クロスプラットフォームライブラリを通じて、DS9097UシリアルアダプタとDS9490 USBアダプタもサポートしています。
.NET用1-Wire API OW.NET Microsoft .NETフレームワーク用のJ#でコンパイルしたOWAPIコードベース。
.NET Compact用1-Wire API OW.NET.Compact Microsoft Visual J#®再頒布可能パッケージを備えていないWindows CEマシンまたはプラットフォーム用Compact .NET Framework。現在、C#に移植された低レベル1-Wireリンクおよびネットワーク層のみで構成されています。
TMEX API TMEX Windowsプラットフォーム(32および64ビット)で1-Wireマスタアダプタをすべてサポートしています。リンクおよびファイルI/O機能を提供していますが、デバイス機能は提供していません。ドライバはクローズドソースです。このAPIは、すべての1-Wireアダプタタイプにアクセスできるように他のAPIによって呼び出されます。

表3. APIのオペレーティングシステムおよび言語の適用範囲
Language TMEX /OW.NET/OW.NET.Compact
(Microsoft Windows language independent)
C Java
OS
Windows Vista® TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows Vista x64 TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows XP TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows XP x64 TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows 2008 TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows 2008 x64 TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows 2000¹ TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows ME¹ TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows 98¹ TMEX /OW.NET/OW.NET.Compact PD OWAPI
Windows 95¹ TMEX PD OWAPI
Win3.1¹ TMEX PD
DOS¹ TMEX PD
Pocket PC/CE OW.NET.Compact PD
Linux® and other UNIX®-based OSs PD OWAPI
MxTNI* PD - without MxTNI OS OWAPI
*MxTNI™は、マキシムが開発したJavaベースのOSを備えた組み込みプラットフォームです。
¹サポートされていませんが、旧ドライバのダウンロードはマキシムのウェブサイトから入手可能です。

各デバイスファミリのサポートは、APIによっても異なります。表4は、各APIで利用可能なサポートを示すフラグとともに、現在利用可能な1-Wireデバイスをすべて紹介しています。表4のフラグに対する「要点」は、表の下部にあります。濃淡の影がないデバイス欄は、APIによって完全サポートされることに留意してください。淡い影付きの欄は部分的サポートで、濃い影付きの欄は最小限のサポートを示しています。

表4. デバイス別APIサポート
Device FC Description TMEX PD OWAPI OW.NET OW.NET Compact
DS1982 09 1Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS1985 0B 16Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS1986 0F 64Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS1904 24 RTC AB AB ABI ABI AB
DS1920 10 Temperature and alarm trips AB ABI ABCI ABCI AB
DS1921G
DS1921H
DS1921Z
21 Thermochron temperature logger ABDE ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS1922L
DS1922T
DS1923
41 High-capacity Thermochron (temperature) and/or Hygrochron (humidity) loggers AB ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS1963L¹ 1A 4Kb NV RAM memory with write-cycle counters ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1971 14 256-bit EEPROM memory and 64-bit OTP register ABD ABCDI ABCDI ABCDI AB
DS1972 2D 1024-bit EEPROM memory AB ABCDEI ABCDEF
GHI
ABCDEF
GHI
DS1973 23 4Kb EEPROM memory ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1977 37 Password-protected 32KB (bytes) EEPROM AB ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1990A
DS1990R
01 1-Wire address only AB AB AB AB AB
DS1991¹ 02 Multikey iButton, 1152-bit secure memory AB ABC ABC ABC AB
DS1992 08 1Kb NV RAM memory ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1993 06 4Kb NV RAM memory ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1994¹ 04 4Kb NV RAM memory and clock, timer, alarms ABDE ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS1995 0A 16Kb NV RAM memory ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS1996 0C 64Kb NV RAM memory ABDE ABCDE ABCDEF
GH
ABCDEF
GH
AB
DS2401 01 1-Wire address only AB AB AB AB AB
DS2405¹ 05 Single switch AB ABI ABI ABI AB
DS2404¹ 04 4Kb NV RAM memory and clock, timer, alarms ABDE ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS2406
DS2407¹
12 1Kb EPROM memory, 2-channel addressable switch ABCE ABCDEI ABCDEI ABCDEI AB
DS2408 29 8-channel addressable switch AB ABI ABI ABI AB
DS2409¹ 1F Dual switch, coupler AB ABI ABI ABI AB
DS2411 01 1-Wire address only AB AB AB AB AB
DS2413 3A Dual-channel addressable switch AB ABI ABI ABI AB
DS2415 24 RTC AB AB ABI ABI AB
DS2417 27 RTC with interrupt AB AB ABI ABI AB
DS2422 41 High-capacity Thermochron (temperature)/Hygrochron (humidity) logger AB ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS2423¹ 1D 4Kb NV RAM memory with external counters ABDE ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS2430A¹ 14 256-bit EEPROM memory and 64-bit OTP register ABD ABCDI ABCDI ABCDI AB
DS2431 2D 1024-bit EEPROM memory AB ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS2450 20 Quad ADC AB ABI ABI ABI AB
DS2502 09 1Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS2505 0B 16Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS2506 0F 64Kb EPROM memory ABCE ABCDE ABCDE ABCDE AB
DS2890¹ 2C Single-channel digital potentiometer AB AB ABI ABI AB
DS28E04-100 1C 4096-bit EEPROM memory, two-channel addressable switch AB ABCDEI ABCDEF
GHI
ABCDEF
GHI
AB
DS28EA00 42 Programmable-resolution digital thermometer with sequence detect and PIO AB AB AB AB AB
DS28EC20 43 20Kb EEPROM AB AB AB AB AB

欄の濃淡別サポート サポートのフラグ
完全サポート A. 1-Wireリンクの基本サポート
B. 1-Wireネットワークのサポート
C. 転送メモリバイトの読取り/書込みサポート
D. 転送メモリパケットの読取り/書込みサポート
E. 1-Wireファイル構造タイプAAのサポート(ファイル構造タイプについては、アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」を参照)
F. 1-Wireファイル構造タイプABのサポート
G. 1-Wireファイル構造タイプBAのサポート
H. 1-Wireファイル構造タイプBBのサポート
I. その他のデバイス固有のサポート
部分サポート
最小サポート
¹これらの製品は新規設計用に推奨されていません。

1-Wireパブリックドメイン(PD)の概要

1-Wire PD APIで提供される機能は「C」で完全記述され、TMEX APIでサポートされていないプラットフォームでの使用を目的としています。「1-Wireネット」(またはMicroLAN™)は、1つのマスタと1つ以上のスレーブデバイスを備える一本の配線とグランドのネットワークです。このAPIはスレーブデバイスを識別し、スレーブデバイスと通信することが可能な1-Wireマスタを創造します。また、iButtonを含めたすべての1-Wireデバイスと通信するように、あらゆる1-Wire、転送、およびファイルレベルサービスを提供します。このAPIキットおよびプラットフォームの構築(ビルド)例は、iButtonのウェブサイトにあります。

このAPIの「C」ソースコードは、移植することができるように設計されています。特定プラットフォームを完成するための「TODO (要実行事項)」テンプレートが提供されています。Windows 64ビット、Windows 32ビット、およびLinuxなどを含めた複数のプラットフォームの実装例が提供されています。また、こうしたプラットフォーム実装を使用する複数のアプリケーション例もあります。

「general」、「userial」、および「other」などの3つの移植可能なソースファイルのセットがあります。1つ目のセットは汎用的なもので、基本的なリンクの1-Wire通信機能(general)をすでに備えているプラットフォームを対象にしています。これは、ハードウェアに依存する最小レベルのセットです。移植可能なソースファイルの2つ目のセットは、ユーザがシリアルポート(RS232)を備え、「Universal Serial 1-Wire Line Driver Master: DS2480B」 (userial)の利用を望んでいるものと想定しています。このチップはシリアルポートに対するコマンドを受け、1-Wireオペレーションを実行し、その結果をシリアルポートに返送します。ソースコードは、目的の1-Wire操作をDS2480Bへのシリアル通信パケットに変換します。プラットフォームに提供する必要があるモジュールは、シリアルポートの読取り/書込みの基本モジュールだけです。DS2480Bは、すべてのDS9097Uシリーズのシリアルアダプタに使用されているインタフェースチップです。最後に、移植可能なソースファイルの3つ目のセットは、特定の1-Wireアダプタ機能および又は、先の2つのカテゴリにはまったく入らないもの(other)を取り扱っています。この一例として、USBポートを取り扱う例があり、具体的には、USBと1-Wire間のブリッジチップDS2490を利用します。多くの面で、これはgeneralのビルドと似ていますが、DS2490の特異性に合わせて修正されています。いずれのファイルセット(general、userial、またはother)を使用する場合でも、最終的には、同じAPIが実際にソフトウェア開発者に対して公開されます。

特に、このアプリケーションノートでは、1-Wireパブリックドメインキット(「other」ビルドに分類される)の、オープンソース型クロスプラットフォームのlibusbビルドについても取り上げています。libusbは、多くの種類のOSに移植されているオープンソースのUSBライブラリです。この特別な1-Wire PD APIのビルドは、その後1-Wire PD APIを構築するのに必要となるlibusb関数にコンパイルされます。

利用可能なさまざまなファイルセットについては、以下の表を参照してください。これはすでに表に示した各プラットフォーム用にビルドされたものであり、ダウンロードして入手可能です。

表5. 1-Wireファイルセットと事前にビルドされたバイナリ
移植可能なソースファイルのセット(ビルド) プラットフォーム ポート 説明
userial Win64、Win32、Linux、(その他のUNIX)、DS550 COM DS9097U 1-Wireシリアルポートアダプタとその他のDS2480Bベースのソリューションをサポートしています(組み込みを含む)。
general Win64、Win32 LPT LPTビルドは、Windows上でDS1410E¹パラレルポートアダプタをサポートしています。
DS550 マイクロプロセッサ(µP)のポートピン DS550のgeneralビルドは、µPのポートピンを使用しています。
other 'libusb' Win64、Win32、Linux、Macintosh、(その他のUNIX) USB DS9490 USB 1-Wireアダプタと、特に適切なlibusbドライバをインストール済みのその他のDS2490ベースのUSBソリューションをすべてサポートしています。
other 'WinUsb' Win64、Win32 USB DS9490 USB 1-Wireアダプタと、WinUSBデバイスドライバを特別に装備したWindows下で、その他のDS2490ベースのUSBアダプタをすべてサポートしています。
other 'wrapper' (TMEX) Win32 USB、COM、LPT TMEX APIを包括し、これによって、Windowsの下でマルチポートをサポートするようにします(それぞれDS9490、DS9097U、DS1410E¹)。
other 'multiport' Win64、Win32 USB、COM、LPT 低レベルのネイティブWindowsドライバと直接通信することでマルチポートをサポートしています。
注:最新のプラットフォームのビルドについては、1-Wireパブリックドメインキットのウェブサイトを参照してください。
¹DS1410Eパラレルポートアダプタは新規設計用に推奨されていません。

移植可能なソースコードファイルのこれらのセットは、同じ1-Wire API機能を実装し、また互換性を持っています。図4は、1-Wire PDコードベースのバージョン3.xx用の利用可能なAPIを紹介しています。非メモリデバイス固有の機能は多数存在するため、詳述していないことに注意してください。図4は、機能を提供するソースファイルと新規プラットフォームに必要なモジュールを対応付けています。

ダウンロードしたPDキット内の移植可能な「C」モジュールだけでなく、1-Wire通信を実行するための限定されたマイクロプロセッサ(µP)のアセンブリ例もあります。

このAPIのファイル機能は、アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」の規定にある1-Wireファイル構造タイプ「AA」を実装しています。

このAPIの名前が示すように、提供されるソースコードは、できるだけパブリックドメインに近いライセンスを所持しています。開発者は、制限なく自由にこのコードを使用し、自らのアプリケーションに組み込むことができます。

セッション
owAcquire - 1-Wireネットを取得。
owRelease - 以前取得した1-Wireネットを開放。
リンク
owHasOverDrive - アダプタがオーバドライブ能力を備えているかどうかを指定。
owHasPowerDelivery - アダプタが電力を供給可能かどうかを指定。
owHasProgramPulse - EPROMプログラミング電圧が利用可能かどうかを指定。
owLevel - 1-WireネットラインレベルをNormal (5Vの弱プルアップ)、Power Delivery (5Vの強プルアップ)、またはProgram Level (12VのEPROMプログラミングレベル)に設定。
owProgramPulse - EPROM 1-Wireデバイスの書込み用に、時間設定されたプログラミングパルスを送信。
owReadBitPower - 1ビットを読み取り、電力を随意に供給。
owReadByte - オール1 (0xFF)を送信して、1-Wireネットから8ビットを受信。
owSpeed - 1-Wireネットの速度をNormal (16kb)またはOverdrive (142kb)に設定。
owTouchBit - 1-Wireネットで1ビットを送受信。
owTouchByte - 1-Wireネットで8ビットを送受信。
owTouchReset - 1-Wireネット上の全デバイスをリセットし、結果を返す。
owWriteByte - 1-Wireネットに8ビットを送信し、受信したエコーが一致していることを確認。
owWriteBytePower - 1-Wireネットに8ビットの通信を送信し、電力を供給。
ネットワーク
owAccess - 現行デバイスを選択し、デバイス固有のコマンドに対してデバイスを準備させる。
owFamilySearchSetup - 特定のファミリタイプを検出するために次の検索(owNext)を設定。
owFirst - 1-Wireネット上の「最初の」1-Wireデバイスを検出するために検索。
owNext - 1-Wireネット上の「次の」1-Wireデバイスを検出するために検索。
owOverdriveAccess - 現行デバイスを選択し、速度をOverdriveに設定。
owSerialNum - 現在選択中のデバイスの登録番号(ROM番号)を回収、または設定。
owSkipFamily - 最後の検索で検出されたファミリタイプの1-Wireデバイスをすべてスキップ。
owVerify - 現行デバイスを選択し、現行デバイスが存在していることを検証(警報発生はオプション)。
転送
owBlock - リセットはオプションで1-Wireネットに1データブロックを送受信。
owCanLockPage - 特定のメモリバンクにロック可能なページがあるかどうかを確認。
owCanLockRedirectPage - リダイレクトしないようにロック可能なページが特定のメモリバンクにあるかどうかを確認。
owGetAlternateName - 代替の部品番号や部品名を取得
owGetBankDescription - メモリバンクの文字列記述を取得。
owGetDescription - 1-Wireデバイスタイプの短い記述を取得。
owGetExtraInfoDesc - その他情報の内容に関する記述を取得。
owGetExtraInfoLength - このメモリバンク内のその他情報をバイトで表した長さを取得。
owGetMaxPacketDataLength - パケットのバイトで表した最大データ長を取得。
owGetName - 1-Wireデバイスの部品番号を文字列として取得。
owGetNumberBanks - 特定1-Wireファミリグループのメモリバンクの番号を取得。
owGetNumberPages - 特定メモリバンクのページ数を取得。
owGetPageLength - 特定メモリバンクの、バイトで表したロー(raw)ページ長を取得。
owGetSize - バイトで表した特定メモリバンクのサイズを取得。
owGetStartingAddress - 特定メモリバンクの物理開始アドレスを取得。
owHasExtraInfo - 読取り時にこのメモリバンクのページがその他情報を提供するかどうかを確認。
owHasPageAutoCRC - ページ読取り時にメモリバンクがデバイス生成CRC検査を備えているかどうかを確認。
owIsGeneralPurposeMemory - メモリバンクが汎用ユーザメモリであるかどうかを確認。
owIsNonvolatile - 現行メモリバンクが不揮発性であるかどうかを確認。
owIsReadOnly - メモリバンクが読取り専用であるかどうかを確認。
owIsReadWrite - メモリバンクが読取り/書込みであるかどうかを確認。
owIsWriteOnce - メモリバンクがEPROMなどのように追記型であるかどうかを確認。
owNeedsPowerDelivery - このメモリバンクが書込みに「電力供給」を必要とするかどうかを確認。
owNeedsProgramPulse - このメモリバンクが書込みに「プログラムパルス」を必要とするかどうかを確認。
owRead - ローモードでメモリバンクの一部を読み取る(パケット、CRCなし)。
owReadPage - ローモードでメモリバンクの1ページ全体を読み取る(パケット、CRCなし)。
owReadPageCRC - デバイス生成CRC検査付きのメモリバンクの1ページ全体を読み取る。
owReadPageExtra - 「その他」情報を含んだ、メモリバンクの1つのローページ全体を読み取る(パケット、CRCなし)。
owReadPageExtraCRC - 「その他」情報とデバイス生成CRC検査を含んだメモリバンクの1つのローページ全体を読み取る。
owReadPagePacket - メモリバンクの1ページからUniversal Data Packetを読み取る(Universal Data Packet構造の説明については、アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」を参照)。
owReadPagePacketExtra - 「その他」情報付きのメモリバンクの1ページからUniversal Data Packetを読み取る。
owRedirectPage - メモリバンクが転送可能なページを備えているかどうかを確認。
owWrite - ローモードでメモリバンクの一部に書き込む。
owWritePagePacket - メモリバンクの1ページにUniversal Data Packetを書き込む。
ファイル
owAttribute - ファイルの属性を変更。
owChangeDirectory - 現在のディレクトリを変更。
owCloseFile - ファイルを閉じる。
owCreateDir - ディレクトリを作成。
owCreateFile - 書込み用にファイルを作成。
owCreateProgramJob - EPROMプログラミング保留ジョブのロギング用書込みバッファを作成。
owDeleteFile - ファイルを削除。
owDoProgramJob - 保留のEPROMプログラミングジョブを書き込む。
owFirstFile - 現在のディレクトリ内の最初のファイルを検出。
owFormat - 1-Wireファイル構造ファイルシステムをフォーマット。
owGetCurrentDir - 現在のディレクトリを取得。
owNextFile - 現在のディレクトリ内の次のファイルを検出。
owOpenFile - 読取り用にファイルを開く。
owReadFile - 開いたファイルを読み取る。
owReadFile - ファイルからデータを読み取る。
owRemoveDir - ディレクトリを削除。
owReNameFile - ファイル名を変更。
owWriteFile - 作成されたファイルに書き込む。
デバイス
DoAtoDConversion - DS2450でA/D変換を実行。
ReadSwitch12 - DS2406のスイッチ状態を読み取る。
readCounter - DS2423 1-Wireチップ上の特定のメモリページに関連するカウンタ値を読み取る。
... (以上のほかに、多数のデバイス固有の機能があります。)
図4. PD API機能

例1は、図3で概説したAPIの使用法フローにしたがったPDコード部分を紹介しています。簡単にするために、ワークループを通過するごとに1-Wireネットワーク上の各デバイスを検出しています。より高度なアプリケーションであれば、1つのデバイスタイプだけを検出したり、以前の検索で検出されたデバイスを選択したりすることができます。

int rslt, portnum=0, doing_work=1;
char portString[50]; // set to platform appropriate port string

// work loop 
while (doing_work)
{
  // acquire the 1-Wire Net (SESSION)
  if (owAcquire(portnum, portString))
  {
   // find all devices (NETWORK)
   rslt = owFirst(portnum, TRUE, FALSE);
   while (rslt)
   {
     // do SOMETHING with device found (TRANSPORT/FILE/DEVICE)
     // . . .

     // find the next device (NETWORK)
     rslt = owNext(portnum, TRUE, FALSE);
   }

   // release the 1-Wire Net (SESSION)
   owRelease(portnum);
  }
  else
  {
   // Could not acquire 1-Wire network 
   // . . . 
  }

  // do other application work 
  // . . .
}
例1. PDコード例

図5a図5bは、2組の1-Wire PDライブラリで各々構成されるC言語モジュールを列記しています。また、新規プラットフォームへのライブラリ移植のために提供すべき「TODO」機能も紹介しています。「TODO」機能を実装するプラットフォームリンクファイルの数例がキットで提供されています。

セッション
owsesu.c
リンク
owllu.cds2480ut.cds2480.h
ネットワーク
ownetu.ccrcutil.c (コンパイルに必要)
転送
mbappreg.c mbappreg.h mbee.c mbee.h mbee77.c mbee77.h
mbeewp.c mbeewp.h mbeprom.c mbeprom.h mbnv.c mbnv.h
mbnvcrc.c mbnvcrc.h mbscr.c mbscr.h mbscrcrc.c mbscrcrc.h
mbscree.c mbscree.h mbscrex.c mbscrex.h mbscrx77.c mbscrx77.h
mbsha.c mbsha.h mbshaee.c mbshaee.h owtrnu.c pw77.c
pw77.h rawmem.c rawmem.h      
ファイル
owcache.c owfile.c owfile.h owpgrw.c owprgm.c  
デバイス
ad26.c ad26.h atod20.c atod26.c atod26.h cnt1d.c
humutil.c humutil.h jib96.c jib96.h jib96o.c ps02.c
ps02.h sha18.c sha33.c shadbtvm.c shadebit.c shaib.c
shaib.h swt05.c swt12.c swt12.h swt1c.c swt1c.h
swt1f.c swt29.c swt29.h swt3a.c swt3a.h temp10.c
thermo21.c hermo21.h time04.c time04.h weather.c weather.h
その他ユーティリティ
ioutil.c owerr.c findtype.c ownet.h screenio.c sprintf.c
crcutil.c
TODO (要実行事項)
以下の機能を実装するSERIALインタフェースモジュールを提供。
BreakCOM* - 最低2ms間、シリアルポート上に「BREAK」を送信。
CloseCOM - 以前開いたシリアルポートを閉じる(一部プラットフォームではオプション)。
FlushCOM* - 保留中の書込み操作を完了させ、入力バッファをクリアする。
msDelay* - 指定のミリ秒以上遅延させる。
msGettick - 増分ミリ秒カウンタを返す(一部の例ではオプション)。
OpenCOM - 通信用の指定シリアルポートを開く(一部プラットフォームではオプション)。
ReadCOM* - シリアルポートから指定数のバイトを読み取る。
SetCOMBaud - シリアルBAUD速度を指定速度に変更(オーバドライブはオプション)。
WriteCOM* - シリアルポートに指定数のバイトを書き込む。
*基本操作に最低限必要な機能。
図5a. PD 「USERIAL」の実装

セッション
(TODO参照)
リンク
(TODO参照)
ネットワーク
ownet.ccrcutil.c (コンパイルに必要)
転送
「owtrnu.c」が「owtran.c」に置き換えられる以外は、USERIALの実装と同じ。
ファイル
USERIALの実装と同じ。
デバイス
USERIALの実装と同じ。
その他ユーティリティ
USERIALの実装と同じ。
TODO (要実行事項)
以下の機能を実装するLINKおよびSESSIONインタフェースモジュールを提供:
owAcquire - 1-Wireネットを取得。
owRelease - 以前取得した1-Wireネットを開放。
owHasOverDrive - アダプタがオーバドライブ機能を備えるかどうかを指定。
owHasPowerDelivery - アダプタが電力を供給可能かどうかを指定。
owHasProgramPulse - EPROMプログラミング電圧が利用可能かどうかを指定。
owLevel - 1-WireネットラインレベルをNormal (5Vの弱プルアップ)、Power Delivery (5Vの強プルアップ)、またはProgram Level (12VのEPROMプログラミングレベル)に設定。
owProgramPulse - EPROM 1-Wireデバイスの書込み用に、時間設定されたプログラミングパルスを送信。
owReadBitPower - 1ビットを読み取り、随意に電力を供給。
owReadByte - オール1 (0xFF)を送信して、1-Wireネットから8ビットを受信。
owSpeed - 1-Wireネットの速度をNormal (16kb)またはOverdrive (142kb)に設定。
owTouchBit* - 1-Wireネットで1ビットを送受信。
owTouchByte - 1-Wireネットで8ビットを送受信。
owTouchReset* - 1-Wireネット上の全デバイスをリセットし、結果を返す。
owWriteByte - 1-Wireネットに8ビットを送信し、受信したエコーが一致していることを確認。
owWriteBytePower - 1-Wireネットに8ビットの通信を送信し、電力を供給。
*基本操作に最低限必要な機能。
図5b. PD 「GENERAL」の実装

インストール

1-WireのPD APIはCモジュールのセットであるため、正式なインストールがありません。「構築(ビルド)」例で紹介されているように、必要なモジュールはアプリケーションに直接コンパイルされます。これは、開発者がWindows DLLなどのロード可能なライブラリにモジュールを統合することを阻むことはありません。

一部のビルドは、ネイティブの1-Wireアダプタドライバまたはこれに相当するものを必要とすることに留意してください。たいていのOSプラットフォームは組み込まれたシリアルポートドライバを持っているため、1-Wire PD APIのuserialビルドは、他のいずれのドライバも必要としません。ただし、USBとパラレルポートの1-Wireアダプタのサポートについては、ネイティブまたはクロスプラットフォームのドライバをインストールすることが必要となります。適切なドライバのダウンロードについては、オンラインで実際に利用可能な1-Wire PDキットのビルドの資料を参照してください。

Java用1-Wire API (OWAPI)の概要

Java用1-Wire APIは、Javaでの1-Wireアプリケーションの構築を目的として、最初から極めて堅牢で高度なオブジェクト指向の基盤となるように設計されています。このAPIは、移植したりクロスプラットフォームのソフトウェア開発をしたりするプログラマの能力を拡大し、1-Wireが使用された製品の製品化までの時間を短縮します。

このAPIは、多数のJavaクラスとインタフェースから構成されています。1-Wire APIのJavaクラスのひとつの特別なグループがコンテナ(クラスOneWireContainer)です。iButton を含めて特定の1-Wireデバイス用のサポートは、コンテナを通じて提供されています。このAPIは、大部分の1-Wireデバイスを代表する30を超える各種コンテナタイプを備えています。各コンテナは個々のデバイスの機能を要約し、実装します。

「コンテナ」は、物理的な1-Wireアダプタ(クラスDSPortAdapter)である1-Wireアダプタクラスを通じて1-Wireデバイスとやりとりします。アダプタのインスタンス(要求)は、プロバイダのクラス(クラスOneWireAccessProvider)から作成されます。1-Wireアダプタの実際の実装はプラットフォームによって変わりますが、すべて同じインタフェースを持っています。一部のプラットフォームではネイティブなドライバを使用していますが、大部分のプラットフォームは、少なくとも、RXTX (クロスプラットフォームのシリアルCOMポートAPI)を使用してDS9097U-XXXシリアルアダプタをサポートしています。このAPIは、RXTXのウェブサイトから入手することができます。

Java用1-Wire APIソフトウェア開発キットは、iButtonのウェブサイトで入手することができます。1-Wire PDキットのように、OWAPIのJavaソース一式はパブリックドメイン形式のライセンスに基づいて提供されます。

図6は、このAPIの標準的なオブジェクト生成手順を紹介しています。「プロバイダ」は、デバイスの「コンテナ」のインスタンス(要求)を順次作成可能な「アダプタ」のインスタンス(またはエニュメレーション(列挙))を作成します。これによってデバイスとの通信は、ほぼ例外なく「コンテナ」を通じて行われます。

図6. OWAPIオブジェクトの作成
図6. OWAPIオブジェクトの作成

図7は、「コンテナ」の一般的な機能を紹介しています。メモリ搭載のデバイスは、各メモリバンク用にメモリバンクインスタンスを作成します。メモリは、バンクの機能セットに応じて、各バンクに分類されます。たとえば、揮発性バンクもあれば、不揮発性バンクもあります。または、バンクは汎用メモリもあれば、デバイスの機能を変更するメモリ割当ての場合もあります。

図7. OWAPI ONEWIRECONTAINERの機能
図7. OWAPI ONEWIRECONTAINERの機能

図8は、基本OWAPIクラスで提供されたメソッドを紹介しています。クラスまたはパッケージは太字で表示しています。各コンテナは個々のデバイスタイプを操作するハイレベルなメソッドを備えているため、アダプタのLINKレベルメソッドは通常直接呼び出されないことに注意してください。

セッション
com.dalsemi.onewire.adapter.DSPortAdapter
beginExclusive - 1-Wireネットの排他的使用を取得。
endExclusive - 1-Wireネット上で排他的ロックを開放。
リンク
com.dalsemi.onewire.adapter.DSPortAdapter
canBreak - 1-Wire「ブレーク」(long low)操作がアダプタによってサポートされているかどうかを確認。
canDeliverPower - 「強プルアップ」電力供給がアダプタによってサポートされているかどうかを確認。
canDeliverSmartPower - 「スマート」電力供給がアダプタによってサポートされているかどうかを確認。「スマート」電力供給とは、電力消費の低減時を検出し、電力供給を自動停止する機能。
canFlex - フレキシブルな長距離通信タイミングがアダプタによってサポートされているかどうかを確認。
canHyperdrive - ハイパードライブ通信速度がアダプタによってサポートされているかどうかを確認。
canOverdrive - オーバドライブ通信速度がアダプタによってサポートされているかどうかを確認。
canProgram - 12V EPROMプログラミング電圧がアダプタによってサポートされているかどうかを確認。
dataBlock - 1-Wireネットに1データブロックを送受信。
getBit - 1-Wireネットから1ビットを読み取る。
getBlock - オール1 (0xFF)を送信して、1-Wireネットから1ブロックを読み取る。
getByte - オール1 (0xFF)を送信して、1-Wireネットから1バイトを読み取る。
getSpeed - 現在の1-Wire通信速度を読み取る。
putBit - 1-Wireネットに1ビットを書き込む。
putByte - 1-Wireネットに1バイトを書き込み、エコーが正しいことを確認。
reset - 1-Wireネットの全デバイスをリセット。
setPowerDuration - 電力供給時間を設定。
setPowerNormal - 電力供給を停止。
setProgramPulseDuration - プログラムパルス時間を設定。
setSpeed - 1-Wire通信速度を設定。
startBreak - 1-Wireネット上でブレーク(low)を開始。
startPowerDelivery - 電力供給を開始。
startProgramPulse - プログラムパルスを開始。
ネットワーク
com.dalsemi.onewire.adapter.DSPortAdapter
excludeFamily - 検索からファミリグループを除外。
findFirstDevice - コンテナを自動生成せずに1-Wireネット上の最初のデバイスを検出。
findNextDevice - コンテナを自動生成せずに1-Wireネット上の次のデバイスを検出。
getAllDeviceContainers - コンテナとともに1-Wireネット上のすべてのデバイスを検索および検出。
getDeviceContainer - 検出した「現行」デバイス用のデバイスコンテナを取得。
getFirstDeviceContainer - 最初のデバイスを検出し、そのコンテナを生成。
getNextDeviceContainer - 次のデバイスを検出し、そのコンテナを生成。
setNoResetSearch - 1-Wireネット検索が1-Wireリセットを送出しないように設定。
setSearchAllDevices - 1-Wireネット検索が全デバイスを含めるように設定(アラーム専用デバイスは除外)。
setSearchOnlyAlarmingDevices - 1-Wireネット検索がアラームデバイスのみを含めるように設定。
targetAllFamilies - 1-Wireネット検索が全デバイスを含めるように設定(除外なし)。
targetFamily - 1-Wireネット検索で特定のファミリグループを対象とする。
(com.dalsemi.onewire.container.*でも同様)
isAlarming - デバイスがアラーム状態にあるかどうかを確認。
isPresent - デバイスが1-Wireネット上に存在するかどうかを確認。
select - デバイス固有の操作コマンドに対応できるように、1-Wireネットデバイスを選択。
転送
com.dalsemi.onewire.container.MemoryBank
getBankDescription - メモリバンクのテキスト記述を返す。
getSize - バイトで表したメモリバンクのサイズを取得。
getStartPhysicalAddress - メモリバンクの開始物理アドレスを取得。
isGeneralPurposeMemory - メモリバンクが汎用(メモリ割当てでない)かどうかを確認。
isNonVolatile - メモリバンクが不揮発性かどうかを確認。
isReadOnly - メモリバンクが読取り専用かどうかを確認。
isReadWrite - メモリバンクが読取り/書込み可能かどうかを確認。
isWriteOnce - メモリバンクがEPROMのような追記型かどうかを確認。
needsPowerDelivery - このメモリバンクが書込みに電力供給を必要とするかどうかを確認。
needsProgramPulse - このメモリバンクが書込みにプログラムパルスを必要とするかどうかを確認。
read - 解釈なしにメモリバンクを読み取る(パケット構造なし)。
setWriteVerification - APIが書込み後に追加検証を実行するように設定。
write - メモリバンクのローを書き込む(パケット構造なし)。
com.dalsemi.onewire.container.PagedMemoryBank
getExtraInfoDescription - このバンクに関連するその他情報の記述を取得。
getExtraInfoLength - 各ページのその他情報のバイトで表した長さを取得。
getMaxPacketDataLength - このメモリバンクの各ページに収まる、「パケット」構造に収納可能なデータの最大長を取得。
getNumberPages - このメモリバンクのページ数を取得。
getPageLength - このメモリバンク内のローページの、バイトで表した長さを取得。
hasExtraInfo - このメモリバンクが各ページに関連したその他情報を保有しているかどうかを確認。
hasPageAutoCRC - このメモリバンクのページがデバイスによって提供されるCRC検証を備えているかどうかを確認。
readPage - メモリバンクから1ページを読み取る。
readPageCRC - デバイスが生成するCRCを利用して、メモリバンクから1ページを読み取る。
readPagePacket - メモリバンクの1ページからパケット構造を読み取る。
writePagePacket - メモリバンクの1ページにパケット構造を書き込む。
com.dalsemi.onewire.container.OTPMemoryBank
canLockPage - メモリバンクのページは追加書き込みの防止が可能かどうかを確認。
canLockRedirectPage - 追記型ページの更新方法として、メモリバンクはリダイレクトされたページを持てるかどうかを確認。
canRedirectPage - 追加リダイレクト防止のため、メモリバンクのリダイレクト機能をロック可能かどうかを確認。
getRedirectedPage - ページのリダイレクト先のページ番号を取得。
isPageLocked - 追加書込みをすることができないようにページがロックされているかどうかを確認。
isRedirectPageLocked - 追加リダイレクトすることができないようにページがロックされているかどうかを確認。
lockPage - ページをロック。
lockRedirectPage - リダイレクトされないようにページをロック。
redirectPage - ページを新規ページにリダイレクト。これは追記型デバイスの更新に使用。
ファイル
com.dalsemi.onewire.utils.OWFile
java.io.File (JDKのバージョン1.2用)と同じメソッドで、以下の追加メソッドを含みます。
close - ファイルを閉じ、このファイルに関連するリソースを開放。
format - このOWFileに規定されたデバイスに関連する1-Wire File Systemをフォーマット。
getFD - このファイルがデバイスと同期することができるように、ファイルのOWFileDescriptorを取得。
getFreeMemory - 1-Wire File System内の利用可能な空きメモリを取得。
getLocalPage - 1-Wire File Systemのページからメモリバンクのローカルページのリファレンスを取得。
getMemoryBankForPage - 提供された1-Wire File Systemのページの読取り/書込みに使用可能なメモリバンクインスタンスを取得。
getOneWireContainer - ファイルシステムを構成するコンテナを取得。
getPageList - ファイルを構成している1-Wire File Systemのページのリストを取得。
com.dalsemi.onewire.utils.OWFileDescriptor
java.io.FileDescriptor (JDKのバージョン1.2用)と同じメソッド。
com.dalsemi.onewire.utils.OWFileOutputStream
java.io.FileOutputStream (JDKのバージョン1.2用)と同じメソッド。
com.dalsemi.onewire.utils.OWFileInputStream
java.io.FileInputStream (JDKのバージョン1.2用)と同じメソッド。
デバイス
com.dalsemi.onewire.container.*
6種類の「センサ」タイプのインタフェースを含めて、30を超える各種デバイス固有のコンテナの実装。
ADContainer - アナログ-ディジタルコンバータ
ClockContainer - クロック
SwitchContainer - スイッチ
TemperatureContainer - 温度センサ
PotentiometerContainer - ディジタルポテンショメータ
HumidityContainer - 湿度センサ
MissionContainer - 温度と湿度ロガーのミッション用
OneWireSensor - 1-Wireセンサ
PasswordContainer - パスワードで保護されたメモリ
com.dalsemi.onewire.application.*
SHAおよび1-Wireタグ付けユーティリティクラス
*基本操作に最低限必要な機能。
図8. OWAPIの機能

下記の例2は、図3で概説したAPIの使用法フローにしたがったOWAPIコード部分を紹介しています。例1のPDコード例と同様、ワークループを通過するごとに1-Wireネットワーク上の各デバイスが検出され、より高度なアプリケーションであれば、1つのデバイスタイプだけ、あるいは以前の検索で発見されたデバイスを検出することができます。

boolean doing_work=true;

// get the default adapter from the service provider
DSPortAdapter adapter = OneWireAccessProvider.getDefaultAdapter();

// work loop
while (doing_work)
{
  // get exclusive use of adapter (SESSION)
  adapter.beginExclusive(true);

  // clear any previous search restrictions (NETWORK)
  adapter.setSearchAllDevices();
  adapter.targetAllFamilies();
  adapter.setSpeed(adapter.SPEED_REGULAR);

  // enumerate through all the 1-Wire devices found (NETWORK)
  for (Enumeration owd_enum = adapter.getAllDeviceContainers();
    owd_enum.hasMoreElements(); )
  {
   // get a 'container' for each device 
   OneWireContainer owd = ( OneWireContainer ) owd_enum.nextElement();

   // do SOMETHING with device found (TRANSPORT/FILE/DEVICE)
   // . . . 
  }

  // end exclusive use of adapter (SESSION)
  adapter.endExclusive();

  // do other application work 
  // . . .
}
例2. OWAPIのコード例

1-Wireのタグ付け

1-Wireセンサが増加して多種多様になるにつれて、1-Wireネットワークの管理が次第に困難になります。たとえば、ADCのようなセンサは各種数値を測定することができるため、センサの機能を規定するためにセンサにタグ付けできることが重要になります。XMLによる1-Wireのタグ付け機構が作成され、Java用の1-Wire APIに実装されています。これらのタグは、アプリケーションが動的にロードし、センサを環境に適合させることができるようにします。詳細については、アプリケーションノート158 「1-Wire Tagging with XML (XMLによる1-Wireのタグ付け)」を参照してください。

インストール

図8に記載されているAPI呼び出しを構成する必須モジュールのすべては、単一のjarファイルであるOneWireAPI.jarにあります。この単一のモジュールを適切な場所またはクラスパスに配置すると、API全体が提供されます。ただし、以下のようなよく知られた2つの例外があります。すなわち、特定のプラットフォームにインストールされる必要があるネイティブまたは通信APIがあるということ、あるいはプラットフォームにはサイズ制限があるため、API全体を有効にすることは好ましくないということです。こうした2つの例外は、OWAPIキットで詳細に考察されます。

1-Wire .NET (OW.NET)の概要

あらゆる目的や用途に応えるため、ここで提供する.NETサポートは、MicrosoftのJ#言語だけでコンパイルされるJava用1-Wire APIです。すべての.NET 1-Wireアプリケーションは、OneWire.NET.dllへの参照のみを必要とします。これは、C#、J#、およびVB.NETなどのような最新の.NET言語のサポートも含んでいます。1-Wire .NETの例については、iButtonのウェブサイトで該当するソフトウェア開発キット(SDK)をダウンロードして参照してください。

1-Wireアプリケーションが正しく動作するためには、OneWire.NET.dllは、次の再配布可能なモジュールもPCにインストールされている必要があることを忘れないでください。
  1. ネイティブな1-Wireポートアダプタのデバイスドライバ。これらは1-Wireドライバと呼ばれ、iButtonのウェブサイトからダウンロードすることができます。
  2. Microsoft .NET 2.0のフレームワーク
  3. Visual J# .NET 2.0再配布可能モジュール
Pocket PC、パーソナルディジタルアシスタンス(PDA)、携帯電話、およびセットトップボックスなどのデバイス用としてCompact .NETフレームワークの1-Wireが必要な場合には、OneWire.NET.dllの新しいリンク層(専用)バージョンが利用可能です。これは、すべてがC#で記述されています。現時点では、OneWireContainersは記述されていませんが、DSPortAdapterクラスは利用可能です。詳細については、Windows用1-Wire SDK (English only)を参照してください。

OW.NET APIはTMEX APIも備えた1-Wireドライバパッケージで提供されています。1-Wireドライバのカスタムインストールの作成方法の詳細についてはアプリケーションノート1740 「White Paper 6: 1-Wire Drivers Installation Guide for Windows (白書6:Windows用1-Wireドライバインストールガイド)」を参照してください。

1-Wire .NET Compact (OW.NET Compact)の概要

このオブジェクトのインタフェースは1-Wire .NET (OW.NET)と同一ですが、セッション、リンクおよびネットワーク層のみが実装されています。オブジェクトは公式な頒布インストールを備えていませんが、その代わりにシングルDLL (OneWireLinkLayer.dll)です。このオブジェクトは32および64ビットWindowsプラットフォームでTMEX APIと直接通信します。DLLファイルは2.0 .NETアプリケーションとともに付属可能で低レベル1-Wireサポートを実現します。このオブジェクトはC#で書かれたもので、J# 2.0 .NET再頒布パッケージが不要です。

TMEX API (TMEX)の概要

TMEX APIは、メモリデバイスの限定された1-Wire File Structureサポートを含めて、全1-Wireデバイスに基本機能を提供する言語非依存のWindows 32ビットDLLセットです。このAPIは、同じ1-Wireポートまたは異なる1-Wireポートで全面的に競合する多重プロセスのマルチスレッドアプリケーションで機能するように設計されています。このAPIは、それぞれ16個の別個のポートとともに、最大16種類の1-Wireアダプタをサポートすることができます。これはマキシム製のすべての1-Wireアダプタをサポートします。

このAPIの最低レベル(最低レベルのデバイス-ドライバ層)は、Windowsプラットフォーム上でJava用1-Wire API用の「ネイティブ」ドライバとして使用します(1-Wireドライバ)。1-Wire .NET APIは、Java用の1-Wire APIにも基づいているため、Windowsプラットフォーム上でも使用することができます。図9は、TMEX APIが提供するネイティブサポートの利点をその他のAPIが利用する方法を図示しています。実ドライバファイル名およびその階層化方法がこの図に紹介されています。

1-Wireドライバのインストールパッケージ(TMEX APIおよびOW.NETライブラリを含む)、およびTMEX (および付随するAPI)にリンクされた多くのプログラム例を含むソフトウェア開発者キットのどちらも、マキシムのウェブサイトで入手可能です。

TMEX SDKで提供されているすべての例はソースコードを備えていますが、ローレベルのドライバのソースコードは現在提供されていません。ただし、こうしたドライバは無制限に再配布可能です。

表6は、各アダプタの機能とともに、現在サポート中の1-Wireアダプタを紹介しています。


表6. サポート対象のTMEXアダプタ
Adapter Port Features
DS9490R, DS9490B USB Power delivery overdrive RJ-11 or iButton holder DS2401 ID
DS1410E¹ Parallel Power delivery overdrive dual iButton holder DS2401 ID
DS1410D¹ Parallel legacy Dual iButton holder DS2401 ID
DS9097U-009 Serial Power delivery overdrive RJ-11 connector DS2502 ID
DS9097U-S09 Serial Power delivery overdrive RJ-11 connector
DS9097U-E25 Serial Power delivery overdrive RJ-11 connector EPROM write
DS1411 Serial Power delivery overdrive single iButton holder
DS9097E¹ Serial legacy RJ-11 connector EPROM write
DS9097¹ Serial legacy RJ-11 connector
DS1413¹ Serial legacy Single iButton holder
¹これらのアダプタは新規設計用に推奨されていません。

TMEXによってサポートされているWindowsプラットフォーム

これらのMicrosoft WindowsプラットフォームはTMEXによってサポートされています:Windows 2008、Windows 2003、Windows Vista、およびWindows XP SP2。これにはx86 (32ビット)およびx64 (64ビット)両方のオペレーティングシステムバージョンが含まれています。Windowsの初期オペレーティングシステムバージョンのドライバが必要な場合は旧バージョンのTMEXが、積極的にサポートされていませんが、マキシムのウェブサイトで入手可能であることに注意してください。(TMEX APIライブラリをインストールする) 1-Wireドライバの4.00以下のバージョンをダウンロードしてください。1-Wireドライバのインストールパッケージはここから:iButton:Windows用1-Wireドライバ

図9. TMEX APIドライバおよび他のAPIの接続性
図9. TMEX APIドライバおよび他のAPIの接続性

図10は、TMEX API提供の機能を紹介しています。このAPIは非メモリデバイス固有の機能を提供していないことに注意してください。

セッション
TMEndSession - 1-Wireネットを放棄。
TMExtendedStartSession - 1-Wireネットの排他的使用を要求。
TMValidSession - 現行の1-Wireネットセッションが有効かどうかを確認。
リンク
TMClose - 開いているポートのリソースを開放(常時使用可能ではない)。
TMOneWireCom - 1-Wireネットの速度をNormal (16kb)またはOverdrive (142kb)に設定。
TMOneWireLevel - 1-WireネットラインレベルをNormal (5Vの弱プルアップ)、Power Delivery (5Vの強プルアップ)、またはProgram Level (12VのEPROMプログラミングレベル)に設定。
TMProgramPulse - EPROMプログラミング用に、時間設定されたプログラミングパルスを1-Wireネットに送信。
TMSetup - ポートおよびアダプタが機能しているかどうかを確認し、検証。
TMTouchBit - 1-Wireネットで1ビットを送受信。
TMTouchByte - 1-Wireネットで1バイトを送受信。
TMTouchReset - 1-Wireネット上の全デバイスをリセットし、結果を返す。
ネットワーク
TMAccess - 現行デバイスを選択し、デバイス固有のコマンドに対して準備をさせる。
TMAutoOverDrive - デバイスが自動的にオーバドライブ速度の切り替えができるようにドライバを設定。
TMFamilySearchSetup - 次の検索(TMNextまたはTMNextAlarm)で指定されたファミリタイプを検出するために現行の検索状態を設定。
TMFirst - 1-Wireネット上の「最初の」1-Wireデバイスを検出するために検索。
TMFirstAlarm - 1-Wireネット上の「最初の」警報を発生している1-Wireデバイスを検出するために検索。
TMNext - 1-Wireネット上の「次の」1-Wireデバイスを検出するために検索。
TMNextAlarm - 1-Wireネット上の「次の」警報を発生している1-Wireデバイスを検出するために検索。
TMOverAccess - 現行デバイスを選択し、Overdrive速度に設定。
TMRom - 現在選択中のデバイスの登録番号(ROM番号)を回収、または設定。
TMSkipFamily - 最後の検索で検出されたすべてのファミリタイプをキップ。
TMStrongAccess - 現行デバイスを選択し、現行デバイスが存在していることを検証。
TMStrongAlarmAccess - 現行デバイスを選択し、現行デバイスが存在して警報を出していないかを検証。
転送
TMBlockIO - 1-Wireリセットに先行して1-Wireネットに1データブロックを送受信。
TMBlockStream - 1-Wireリセットなしで1-Wireネットに1データブロックを送受信。
TMExtendedReadPage - デバイス生成CRC検査付きのメモリバンクの1ページ全体を読み取る(全デバイスタイプに該当せず)。
TMProgramByte - EPROMベースの1-Wireデバイスに1バイトをプログラミング。
TMReadPacket - ページからUniversal Data Packetを読み取る(Universal Data Packet 構造の説明については、アプリケーションノート114 「1-Wire File Structure (1-Wireファイル構造)」を参照)。
TMWritePacket - ページにUniversal Data Packetを書き込む。
ファイル
TMAttribute - ファイルまたはディレクトリの属性を変更。
TMChangeDirectory - 現在の作業ディレクトリの読取りや変更を行う。
TMCloseFile - ファイルハンドルを解放するために開いたファイルや作成したファイルを閉じる。
TMCreateFile - 書込み用にファイルを作成。
TMCreateProgramJob - EPROMプログラミング保留ジョブのロギング用書込みバッファを作成。
TMDeleteFile - ファイルを削除。
TMDirectoryMR - サブディレクトリを作成または削除。
TMDoProgramJob - EPROMプログラミング保留ジョブを書き込む。
TMFirstFile - 現在のディレクトリの最初のファイルを検出。
TMFormat - 1-Wireファイル構造ファイルシステムをフォーマット。
TMNextFile - 現在のディレクトリ内の次のファイルを検出。
TMOpenFile - 読取り用にファイルを開く。
TMReadFile - 開いたファイルを読み取る。
TMReNameFile - ファイルやディレクトリの名前を変更。
TMTerminateAddFile - 「AddFile」を終了。
「AddFile」は、上書きせずに追加可能なEPROMデバイス上の特殊ファイルタイプです。
TMWriteAddFile - EPROMデバイス上に「AddFile」を追加、または変更。
TMWriteFile - 作成されたファイルに書き込む。
デバイス
なし
その他
TMGetTypeVersion - アダプタドライバ用のバージョン情報を取得。
Get_Version - 全ドライババージョンを取得。
図10. TMEX API機能.

例4は、図3で概説したAPIの使用法フローにしたがったTMEXコード部分を紹介しています。先の3つの例と同様、簡単なプロセスはワークループを通過するごとに1-Wireネットワーク上の各デバイスを検出するようにしており、より高度なアプリケーションであれば、1つのデバイスタイプだけを検出したり、以前の検索で検出されたデバイスを選択したりすることができます。

int PortNum, PortType; // port number and type set for adapter present
long session_handle; // session handle
unsigned char state_buffer[5120];
int doing_work=1, did_setup=0;
short rslt;

// work loop 
while (doing_work)
{
  // aquire the 1-Wire Net (SESSION)
  session_handle = TMExtendedStartSession(PortNum,PortType,NULL);
  if (session_handle > 0)
  {
   // check to see if TMSetup has been done once
   if (!did_setup)
   {
     if (TMSetup(session_handle) == 1)
      did_setup = 1;
     else
     {
      // error setting up port, adapter may not be present
      // . . . 
     }
   }
   else
   {
     // find all devices (NETWORK)
     rslt = TMFirst(session_handle, state_buf);
     while (rslt > 0)
     {
      // do SOMETHING with device found (TRANSPORT/FILE/DEVICE)
      // . . .

      // find the next device (NETWORK)
      rslt = TMNext(session_handle, state_buf);
     }
   }

   // release the 1-Wire Net (SESSION)
   TMEndSession(session_handle);
  }
  else
  {
   // Could not acquire 1-Wire network 
   // . . . 
  }
  
  // do other application work 
  // . . .
}
例4. TMEX 「C」コードの例

インストール

TMEX APIは、前述の1-Wireドライバのインストールパッケージ(OW.NET APIライブラリもインストール)でインストールすることができます。これはMicrosoftのインストーラパッケージであり、サポート対象のあらゆる1-WireアダプタについてWindowsのドライバとレジストリキーのすべてをロードします。ドライバとAPIファイル(インストールなし)は、カスタムインストール用に自由にオンラインで入手することが可能です。OneWireViewerは、ほとんどの1-WireデバイスとiButtonデバイスを実行し1-Wireドライバでインストールされるデモプログラムです。

1-WireドライバとOneWireViewerデモの追加情報については、iButtonのウェブサイトの「ソフトウェアリソース」下にあります。

その他ツール

このドキュメントで取り上げたAPIは、1-Wireデバイスとの通信に利用可能なリソースの大部分を説明していますが、決して唯一のリソースではありません。このセクションでは、その他の利用可能なリソースを概説しています。

ソフトウェア認可API

ソフトウェア認可とは、ハードウェアトークンの存在を必要とするソフトウェアアプリケーションの単なるロックです。この場合のトークンは、ユーザのワークステーションに接続されたiButtonです。アプリケーションは、その実行前にiButtonの存在と妥当性を照会します。これは、アプリケーションの実行中にも連続して問い合わせることができます。実際には、このドキュメントで概説されるどのAPIもこうしたアプリケーション用に使用することができますが、考慮すべき特定の問題があります。ユーザがドライバを交換し、ロックを無効にすることができるため、外部ドライバのセキュリティが脅かされます。1-Wire PDキット上で構築されたソフトウェア認可APIは、特にこうしたアプリケーション用に開発され、外部ドライバの代わりにリンク可能なモジュールを備えています。

ソフトウェア認可APIの設計は、最も簡単に使用することができるという点に重点を置いており、ソフトウェアプログラマの既存のコードに簡単に統合することができるようにしています。次の3つの主要なサービスがAPIによって提供されています。
  • 1-Wireデバイスの初期化
  • デバイスの認証
  • デバイスの消去(これによってシステムの有効な要素ではなくなる)
1-Wireソフトウェア認可キットの情報は、iButtonのウェブサイトにあります。

検索エンジンのソフトウェア例

マキシムは、この解説書で述べたAPIを実証する1-Wireのソフトウェアアプリケーション例を継続的に開発しています。SDKに含まれていない例は、オンラインのソフトウェア例の検索エンジンを利用して見つけることができます。これらの例の多くは (ソースコードを含めて) 、関連するSDKに追加されるまえに最初に検索エンジンに(個別のダウンロードとして)追加されます。検索エンジンは、以下の項目別にソフトウェア例を検索することができます。
  • 1-Wireデバイス(Thermochron、SHA iButtonなど)
  • プラットフォーム(Win32、Linux、MxTNIなど)
  • API (TMEX、1-Wireパブリックドメイン、1-Wire .NETなど)
  • プログラミング言語(C、Java、C#、Visual Basic、Delphiなど)
検索結果の内容は、プログラムの説明と該当するダウンロードのリンクです。

サードパーティ

多くのサードパーティ製のソフトウェアは1-Wireデバイス用に利用することができます。その一部は、ソリューションとともに購入可能な、マキシム認定のソリューション開発者(ASD)が作成したアプリケーションです。SourceForge.netなどのパブリックフォーラムに関するオープンソースプロジェクトはもちろんのこと、ASDおよびソリューションロケータのリスト一式は、iButtonのサイトにあります。

終わりに

この解説書は、すべての1-Wire APIの特徴に関する概要を紹介してきました。また、サポートプラットフォームやプログラミング言語などを含めて、数種類のAPIについても詳述してきました。各デバイスタイプのAPIの適用範囲を紹介する早見表によって、使用するAPIの選択が容易になりました。適切なAPIを入手すると、1-Wire利用のアプリケーションを容易に設計することができます。
次のステップ
EE-Mail EE-Mail配信の登録申し込みをして、興味のある分野の最新ドキュメントに関する自動通知を受け取る。
© , Maxim Integrated Products, Inc.
このウェブサイトのコンテンツは米国および各国の著作権法によって保護されています。コンテンツの複製を希望される場合は お問い合わせください。.
APP 155:
アプリケーションノート 155,AN155, AN 155, APP155, Appnote155, Appnote 155