摘要

包括iButton^®器件在内，Maxim目前生产的1-Wire^®器件已有30多种。如何选择已有的应用程序接口API、软件范例及其它资源与这一类器件进行通信或为某个器件选择正确的资源是一件非常令人头疼的事。本文提供了该类资源的概述和选择指南。另外，还提供了一个目前1-Wire器件的功能说明和家族代码列表，便于用户查询。

所提供的API包括：TMEX (Microsoft Windows^® API)、1-Wire公共文件资源(一种跨平台API)、Java^™ 1-Wire API (OWAPI)及其变形.NET 1-Wire API (OW.NET)和精简型.NET 1-Wire API (OW.NET.Compact)。本文所描述的所有API都是免费的，而且大多数情况下还包括完整的源代码。

引言

包括iButton在内，Maxim目前生产的1-Wire器件已有30多种。如何选择已有的应用程序接口(API)、软件范例及其它资源与这一类器件进行通信，或为某个器件选择正确的资源是一件非常令人头疼的事。本应用笔记提供了该类资源的概述和选择指南。本文中所描述的所有API都是免费的，而且大多数情况下还包括完整的源代码。

1-Wire概述

1-Wire总线是一种简单的信号交换架构，通过一条线路在主机与外围器件之间进行双向通信。所有的1-Wire总线都具有一个共同的特征：无论是芯片内还是iButton内，每个器件都有一个互不重复的、工厂光刻的序列号，因此，每个器件都是唯一的。这样就允许从众多连到同一总线的器件中独立选择任何一个器件。当1个、2个甚至多个1-Wire器件能共用一条线路进行通信，可以采用二进制位检索法依次查找每一个器件。一旦器件的序列号已知，通过寻址该序列号，就可以唯一地选出该器件进行通信。

所有通信的第一步都需要总线控制器发出一个复位信号以使总线同步，然后选择一个受控器件进行随后的通信，这可以通过选择所有的受控器件或者选择一个特定的受控器件(利用该器件的序列号进行选择)，或者通过对半检索法找到总线上的下一个受控器件来实现。上文所提到的这些指令都是网络指令或者只读存储器(ROM)指令。一旦一个特定的器件被选中，那么在下次复位信号发出之前，所有其它器件都被挂起而忽略随后的通信。

一旦一个器件被用于总线通信，主机就能向它发出特定的器件指令，对它进行数据读写。这是因为每类器件具有不同的功能和不同的用途，而且一旦器件被选定，就有了唯一的协议。虽然每类器件具有不同的协议和特征，但其工作过程却是相同的并且遵循如图1所示的工作流程。

每个受控器件的序列号的整数部分是一个8位的家族代码。这个代码对器件模型来说是特定的。因为每种器件模型执行不同的功能，所以可以用代码来选择用于控制或者查询器件的协议。表1是Maxim 1-Wire器件型号家族代码。

*该表没有列出Maxim的全部1-Wire器件(家族)，这些仅是Automatic Information事业部(BU)提供的软件库可直接支持的器件。
¹不推荐在新的设计中使用这些器件。

API基础

1-Wire通信器件的不同应用程序接口(API)有着许多共性，反映了协议的基本数据通信原理。图2是根据不同API功能进行的分类。因为大多数1-Wire器件具有存储器，尽管存储器输入输出功能并不适用于所有的器件，我们还是把它们视为一个通用API集。其它所有不具备存储器专用功能的划分为一类-专用器件集。

图3概括了使用这些功能的典型顺序。SESSION功能围绕着调用器件进行通信，具有代表性的是先使用一个NETWORK功能，然后运行存储器或DEVICE的特定操作。

iButton通信实质上是通过与其触头相‘接触’来实现的。这意味着与器件的联系有时是不可靠的。iButton也可能被安装到阅读器里，在阅读的时候弹出，从而必须有一个相容的纠错方法紧跟其后。当检测到虚假错误时必须重发数据并在数据通信中进行CRC校验。API中的文件输入输出功能所利用的标准文件结构在应用笔记114：“1-Wire File Structure”中的1-Wire File Structure部分进行了详细说明。这种结构在每页数据上都使用CRC16，以快速地校验所读数据的正确性。大多数1-Wire API功能很少或者不能自动重发。重发受应用软件控制，请参见应用笔记159：“在iButton^®应用中通过软件方法实现可靠的1-Wire®通信”，其中讲述了纠错方法和1-Wire通信的风险评估。

API的选择

本文主要列举了五种不同的应用程序接口(API)。这些API运行在不同的工作平台上，使用不同的语言，具有不同的性能。表2简要地描述了这五种API；表3说明了按语言划分的可利用API及其操作系统。

*MxTNI™是由Maxim研制的带有基于Java的操作系统的嵌入式平台。

¹不再进行支持，之前的驱动程序仍可从Maxim网站下载。

API不同，器件族的支持亦不同。表4列出了目前所有可利用的1-Wire器件，并用标志说明它们受哪种API支持。标志的注释在表4的底部。注：表中无阴影的器件单元全部受API支持。浅色阴影的单元表示部分地受API支持，而深色阴影单元表示受API支持最少。

¹不推荐在新的设计中使用这些器件。

1-Wire公共文件(PD)资源概述

1-Wire PD API提供的功能都是用C语言写的，用于TMEX API所不支持的平台。‘1-Wire网络’(或者MicroLAN™)是一种在主机和一个或多个外设之间只有一条数据线和地线的网络。这个API创建了用于识别从机器件、并与从机通信的1-Wire主机。它提供所有的1-Wire、传输和文件操作类服务，可以与包括iButton在内的1-Wire器件进行通信。该类API软件包和平台示例可从iButton网站下载。

用‘C’语言设计的API是可移植的。提供专用平台上完成的‘TODO’模板，也提供了几种平台范例的实现：包括64位Windows、32位Windows和Linux。还有用这些平台实现的几个应用。

有三类可移植的源文件：分别定义为‘通用’、‘userial’和‘其它’。第一类是通用源文件，适用于已经与1-Wire通信功能建立了基本连接的平台(通用)，是与硬件有关的最底层源文件。第二类是假设用户已经有了一个串口(RS-232)，并请求使用‘通用串行1-Wire总线驱动程序：DS2480B’ (userial)。这种芯片从串口读入命令后，执行1-Wire操作，然后再把结果送回串口。源代码把预期的1-Wire操作转换为串行通信包传送给DS2480B。唯一需要提供给平台的参数就是串口的读写初始值。所有DS9097U系列的串行适配器的接口芯片用的都是DS2480B。最后，第三类是处理特定1-Wire适配器功能的可移植的源文件和/或不属于上述前两类的源文件(其它)。比如用来处理USB端口例子，是特定利用DS2490 USB至1-Wire桥接芯片。多数情况下，这一类源文件很像通用类的源文件，只不过已经过特定DS2490的改进。不管所用到的是哪类源文件(通用、userial或其它)，最终，同一API是要公布给软件开发者的。

值得注意的是，这篇应用笔记还提供完全开放源代码、1-Wire公用工具包的跨平台libusb构件(归在‘其它’源文件类里)。Libusb是源代码完全开放的USB库，可在多种不同操作系统间移植。1-Wire PD API的特定源文件在必要的libusb功能中编译，然后用于构建1-Wire PD API 。

有关可用的各类文件可参考下表，表中的这些文件均已在每个平台上建立，并提供下载。

注：关于最新的平台源文件可从1-Wire公用工具包网站获得。
¹不推荐在新设计中使用DS1410E并行端口适配器。

这些不同类的可移植源代码文件执行同样的1-Wire API，而且可以互换。图4所示API为可用于1-Wire公用代码基础的第3.xx版。要注意的是考虑到非存储器器件的特定功能数量过多，所以未详细列出。图4列出了为新平台提供的功能和所需模块的源文件。

除了能够下载可移植的公用套件‘C’语言模块外，还可以下载有限数量的微处理器(µP)汇编实例，进行1-Wire通信。

该API中的文件功能实现了1-Wire的‘AA’类文件结构，应用笔记114："1-Wire File Structure "定义了这种文件结构。

顾名思义，API所提供的源代码有一个尽可能接近公用文件资源的许可证。开发者可以自由使用，并可与他们的应用软件不受任何限制地结合为一体。

下面的例1就是一段PD编码示例，它遵循图3所概括的API使用流程。简便起见，在程序的每次循环中找到一个1-Wire网络上的器件。更复杂的应用一次可能找到一类器件或者可能选定一个在上次查找过程中找到的器件。

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 
  // . . .
}

图5a和5b列出了C语言模块，它们分别构成了1-Wire的两个公用程序库。同时也列出了必需的‘TODO’功能，以把程序库传送到新平台。在这个软件包里也有执行‘TODO’功能的几个平台链接文件的例子。

安装

由于1-Wire PD API是一套C模块，所以没有正规的安装程序。正如示例构件那样，所需模块直接编译到应用程序。当然这并不排除开发者把模块组合到可加载的程序库里，比如Windows动态链接库。

一些构件需要本地1-Wire适配器驱动程序或等效程序。因为多数操作系统平台具有内置的串口驱动程序，1-Wire PD API的‘userial’源文件无需任何其它驱动程序。但对于支持USB和并口的1-Wire适配器，就需要安装本地或跨平台驱动程序。参考对应的驱动程序，这些驱动程序可从网上以现行的1-Wire公用程序工具包构件文件格式下载。

Java的1-Wire API (OWAPI)概述

为创建1-Wire在Java中的应用，适用于Java的1-Wire API从一开始就被设计成一种高度面向对象的基础牢靠的API。它增强了程序员设计可移植的交互平台软件的能力，并缩短了基于1-Wire器件设计开发的产品进入市场的时间。

API由很多Java类和接口构成。1-Wire API的Java类中有一个特殊的库：容器(OneWireContainer类)。容器支持包括iButton在内的特殊1-Wire器件。API有30多种容器类型，代表了大多数1-Wire器件。每个容器都可以压缩和执行单一器件的功能。

容器通过1-Wire物理适配器(DSPortAdapter类)和1-Wire器件进行通信。适配器由提供者类(OneWireAccessProvider类)生产。1-Wire适配器由于平台的不同而不同，但是它们都有同样的接口。有一些平台使用本地适配器，但大多数都至少支持通过使用RXTX (一种跨平台的串行COM端口API)来实现的DS9097U-XXX串行适配器。这种API可以从RXTX网站找到。

Java软件开发包1-Wire API可从iButton网站上找到。与1-Wire公共文件资源工具包一样，通过公共文件资源许可证也可以得到OWAPI的完整的Java源程序。

图6所示为API对象生成的典型顺序。‘提供者’提供一个‘适配器’实例(或枚举)，反过来它又生成器件‘容器’实例。然后与器件的通信几乎直接通过容器来进行。

图7说明了容器的共同特征。具有存储器的器件将为每个存储区生成一个存储区实例。根据特征可以把存储器划分成几组。比如：一组存储器是易失的，而另一组却是非易失的，或者一个区域能够作通用存储器，或能够进行存储器映射，以改变器件功能。

图8说明了基于OWAPI类库的方法。类或包用粗体字表示。注：因为每个容器都有操作器件类型的高级方法，所以一般不直接访问适配器中链路层的方法。

下面的例2是OWAPI的代码段，它也遵循图3所概括的API使用流程。和例1中的公用代码实例一样，每次循环只找出一个1-Wire网络的器件；复杂点的应用程序一次循环中可以找出一类器件或是上次循环中找到的器件。

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 
  // . . .
}

1-Wire标记

随着1-Wire传感器数量和种类的增多，1-Wire网络的管理也越来越困难。比如，ADC可以测量各种不同的值，所以给这种检测器加上标签说明它的功能也很重要。一种用XML标记1-Wire的方案已经确定并应用于Java的1-Wire API。这些标志允许应用程序动态的载入和设置传感器并赋给它一定的环境。详细内容可参考应用笔记158："用XML实现1-Wire标签"。

安装

图8所提到的调用API所需的任何模块都包含在一个jar文件里：OneWireAPI.jar。将模块导入正确的位置或类路径可提供全部的API。但有两个特例：一个是本地或通信API需要安装在特定的平台上，另一个是平台有容量的限制以致不能满足所有API的需要。这两个特例将在OWAPI软件包里进行详细的说明。

1-Wire .NET (OW.NET)概述

处于全面考虑，我们提供的.NET支持是对应Java的1-Wire API，仅用Microsoft的J#语言编译。所有的.NET 1-Wire应用程序仅需参考OneWire.NET.dll。这包括支持最新的.NET语言，如：C#、J#和VB.NET。有关1-Wire .NET的实例请参考iButton网站的软件开发包(SDK)下载。

注意：OneWire.NET.dll还需要在1-Wire应用程序正常工作前将以下发行程序安装在PC上：

1. 本地1-Wire端口适配器驱动程序。该驱动程序是1-Wire驱动程序，且可从iButton网站下载。
2. Microsoft .NET 2.0框架。
3. Visual J# .NET 2.0发行版本。

1-Wire驱动包提供了OW.NET API及TMEX API。关于1-Wire驱动定制安装的详细信息，请参考应用笔记1740，"White Paper 6: 1-Wire Drivers Installation Guide for Windows"。

精简型1-Wire .NET (OW.NET Compact)概述

该对象的接口与1-Wire .NET (OW.NET)相同，但只使用了会话、链路和网络层。该对象没有正式的发行安装版本，而是采用单个动态连接库(OneWireLinkLayer.dll)的形式，直接与32位和64位Windows平台上的TMEX API通信。动态连接库文件可以包含在2.0 .NET应用中，以支持低级1-Wire。该对象用C#语言编写，无需J# 2.0 .NET发行包。

TMEX API (TMEX)概述

TMEX API是一套独立于Windows动态链接库的语言，它提供所有1-Wire器件的基本功能，包括用以支持存储器件的有限的1-Wire文件结构。这种API被设计为在多进程、多线程程序争用同一或不同1-Wire端口时工作。它可以支持16种不同的1-Wire适配器，每种适配器又有16个截然不同的端口。它支持Maxim生产的所有1-Wire适配器。

这种API的最底层用作Windows平台(1-Wire驱动程序)下Java 1-Wire API的本地驱动程序。由于1-Wire .NET API同样基于Java的1-Wire API，因此也被使用。图9给出了其它API是如何利用TMEX API提供的本地支持的。图中也包括实际驱动程序的文件名和它们是如何分层的。

1-Wire驱动器安装包(包括TMEX API、OW.NET库)和包含了许多链接到TMEX (以及配合API)的程序实例的软件开发工具在Maxim网站上均可找到。

TMEX SDK所提供的例子都有源代码，但还未提供低级驱动程序的源代码。驱动程序可自由发布。

表6出了目前支持的1-Wire适配器以及每种适配器的特征。

¹不推荐在新设计中使用这些适配器。

TMEX支持的Windows平台

TMEX支持以下Microsoft Windows平台：Windows 2008、Windows 2003、Windows Vista以及Windows XP SP2，包含x86 (32位)和x64 (64位)两种操作系统。请注意，如果需要使用更早版本的Windows操作系统的驱动程序，Maxim网站还提供有TMEX继承版本(但不是主要支持的版本)。请下载4.00或更低版本的1-Wire驱动程序(将安装TMEX API库)。1-Wire驱动安装包可以从iButton：针对Windows的1-Wire驱动程序获得。

图10列出了TMEX API提供的功能。注：这种API不提供任何无存储器件的专用功能。

下面的例4是TMEX的代码段，它遵循图3所概括的API使用流程。和上面的三个例子一样，一个简单的程序允许每次循环期间只找出一个1-Wire网络上的器件。复杂点的应用程序一次循环中可以找出一类器件或者可以选定在上次循环中找到的器件。

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 
  // . . .
}

安装

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公用工具包之上的软件授权 API就是专门为这种应用程序开发的，且它用可链接的模块代替了外部驱动。

软件授权API的设计是以使用最简单为中心目的，以便更容易地移植到软件开发者现有的代码中。API主要提供三种服务：

• 初始化一个1-Wire器件
• 验证器件
• 清除器件(因此系统中不再有有效器件)

有关1-Wire软件授权工具的信息可在iButton网站上找到。

软件实例搜索引擎

Maxim不断开发1-Wire实例应用程序，用于演示本文中提到的API。未包含在SDKs中的实例可通过在线软件实例搜索引擎找到。其中很多实例(带源代码)在加载到对应的SDK之前首先会被添加到搜索引擎(作为独立的一部分来供下载)。搜索引擎可按下列软件实例来搜索：

• 1-Wire器件(Thermochron、SHA iButton等)
• 平台(Win32、Linux、MxTNI等)
• API (TMEX、1-Wire公共资源、1-Wire .NET等)
• 编程语言(C、Java、C#、Visual Basic、Delphi等)

搜索结果包括：程序的详细说明和其对应的下载链接。

第三方

有大量的适用于1-Wire器件的第三方软件。其中有一些应用程序是购买Maxim授权方案开发者(ASD)的解决方案。iButton网站给出了完整的ASD和方案列表，讨论组也有开源程序，如SourceForge.net。

结束语

本文对各种1-Wire API的特性做了概括性论述。详细介绍了几种不同的API，包括支持它们的平台及编程语言。速查表概括了每种器件类型的API，使我们很容易选出所要的API。有了正确的API，使用1-Wire可以很容易地设计应用程序。