利用API控制DS1WM 1-Wire总线主机

利用API控制DS1WM1-Wire总线主机摘要：本应用笔记提供了一些利用MaximAPI控制DS1WM1-Wire总线主机的C语言例程。本文讨论的内容基于DS1WM已经设计到FPGA或ASIC内，主控CPU通过API调用控制DS1WM。DS1WM通过两个文件(DS1WM.c和DS1WM.h)进行通信，这两个文件构成了API。本文讨论的例程包括：初始化、1-Wire复位、ROM搜索算法，说明了1-Wire常见功能的使用。假设读者已经了解1-Wire器件、DS1WM1-Wire主机以及1-Wire总线协议。引言DS1WM1-Wire总线主机内部生成1-Wire时序和控制信号，无需CPU产生逐位控制时序。该控制功能使系统程序设计人员能够使用API函数进行程序开发。DS1WMAPI采用ANSIC语言编写，可以为多种支持ANSIC的微处理器平台所用。以下例程介绍了如何在网络中识别、选择1-Wire从设备，并与其进行通信。

图1.1-Wire网络总线示例电路

图1所示的电路配置适用于以下所有示例程序。主机CPU利用DS1WM与带有链路模式和GPIO的1-Wire数字温度传感器DS28EA00以及1-Wire1KbEEPROMDS2431进行通信。示例程序重点演示API，而非从设备功能。16MHz的系统时钟通过CLK引脚提供1-Wire主机时序。1-Wire主机的端口引脚需要映射到应用微处理器的引脚。API文件DS1WM.h中包含了引脚映射功能。API头文件中的MaxNumberDevices宏必须更改为实际可能的最大器件数。DS1WM.cAPI文件中的ReadByteFromRegister和WriteByte2Register函数也需要进行修改，以便正确触发微处理器端口。VPUP电压典型值为5.0V，RPUP不大于2.2kΩ。概述通过Maxim支持中心，可以申请免费的DS1WM和API。下面讨论了初始化和1-Wire复位控制的DS1WM代码。此外还提供了一个示例，用于演示如何使用DS1WMROM搜索引擎确定每个器件的唯一注册码(ROMID)。使用存储的注册码以及家族码，可以识别每个1-Wire从设备，并通过匹配ROM命令进行访问。家族码列表，请参见应用笔记155：“1-Wire®软件资源指南”。DS28EA00示例演示了如何进行温度转换。第二个示例给出了高速读写DS2431暂存器的两种方法。总线主机基本操作微处理器通过触发复位引脚初始化DS1WM，API接口执行所有1-Wire通信。示例程序通过调用DS1WMAPI函数进行工作。由于响应中断时会改变微处理器代码，因此后续示例中采用轮询方式替代中断方式通信。

后续的示例程序中用到了表1所示的1-Wire操作。

表1.1-Wire操作Operation*DescriptionOWResetSendsthe1-Wireresetstimulusandchecksforthepulsesof1-Wireslavedevicesthatarepresentonthebus.OWWriteByte/OWReadByteSendsorreceivesasinglebyteofdatafromthe1-Wirebus.OWWriteBytes/OWReadBytesSendsorreceivesmultiplebytesofdatafromthe1-Wirebus.OWSearchPerformsthe1-WireSearchAlgorithm(seeapplicationnote187,"1-WireSearchAlgorithm").OverdriveEnableSetsthe1-WirecommunicationspeedfortheDS1WMtooverdrive.NotethatthisonlychangesthecommunicationspeedoftheDS1WM;the1-Wireslavedevicemustbeinstructedtomaketheswitchwhengoingfromnormaltooverdrive.The1-Wireslavewillalwaysreverttostandardspeedwhenitencountersastandard-speed1-Wirereset.OverdriveDisableSetsthe1-WirecommunicationspeedfortheDS1WMtostandard.NotethatthisonlychangesthecommunicationspeedoftheDS1WM;astandard-speed1-Wireresetisrequiredforslavedevicestoexitoverdrive.MatchROMSelectsdevicebyissuingtheMatchROMcommandfollowedbythe64-bitROMIDselected.SetClockFrequencySetstheclockfrequencyfortheDS1WM.InterruptEnableRegisterWriteWritesasinglebyteofdatatotheDS1WMInterruptEnableregister.InterruptRegisterReadReadsasinglebyteofdatafromtheDS1WMInterruptregister.ReceiveBufferReadReadsasinglebyteofdatafromtheDS1WMReceiveBufferregister.*该表涵盖了示例中用到的子程序，详细说明请参见DS1WM.c文件。初始化通过初始化DS1WM，启动主机，提供正确的1-Wire总线时序。主机将数值16(代表频率值)传递至SetClockFrequency函数，将0x90h写入时钟分频寄存器(请参见DS1WM数据资料)。中断使能寄存器设置为0x00h，防止INTR引脚产生中断。上电时，接收缓存可能包含无效值，因此在发送1-Wire命令之前，最好对接收缓存进行清理。启动时对中断寄存器和接收缓存器的读操作将清除其中的各个位。//----------------------------------------------------------------------------------------------------//StartofinitializationexampleSetClockFrequency(16);//Setclockfrequencyto16MHz(power-ondefault)InterruptEnableRegisterWrite(0x00);//Clearinterrupts//FlushreceivebufferInterruptRegisterData=InterruptRegisterRead();ReceiveBufferRead();//Endofinitializationexample//----------------------------------------------------------------------------------------------------1-Wire复位(OWResetAPI函数)初始化完成后，主机必须确定1-Wire总线上是否接有设备。主机调用OWReset函数，以实现该目的。如果检测到器件存在脉冲，该函数返回1；如果没有检测到器件或发送错误，则函数返回0。如果返回值为0，需要检查ErrorStatus变量，以确定故障状态。1-Wire复位的优先级高于所有1-Wire命令(例如，MatchROM、SkipROM、ReadROM)，但调用OWSearch函数时除外，该函数自身带有复位。软件设计人员应当在程序中加入适当的故障处理代码，在发生故障时能够触发执行这些代码。ErrorStatus值意味着发生了如下错误中的一种：没有进行在线检测；没有检测到器件；存在1-Wire短路；1-Wire总线始终处于低电平状态。Result=OWReset();if(!Result){switch(ErrorStatus){case-1://DS1WMdidnotrecognize1-Wirereset(PD=0)//Todaddyourerrorcodeherebreak;case-2://Nodevicefound(PDR=1)//Todaddyourerrorcodeherebreak;case-7://1-WireIOisshorted(OW_SHORT=1)//Todaddyourerrorcodeherebreak;case-8://1-WireIOisshorted(OW_LOW=1)//Todaddyourerrorcodeherebreak;}}利用ROM搜索引擎确定ROMID总线上的每个1-Wire设备都必须进行识别。存储在每个1-Wire器件中的唯一64位ROMID用于选择各个器件，并根据家族码识别器件类型。为降低例程的复杂度，采用8位家族码识别DS28EA00和DS2431。

注意：如果1-Wire总线上连接了不止一种器件类型(例如，具有相同的家族码)，则后续的方法无法对器件进行识别。不对总线上的多个1-Wire器件进行识别，则无法对特定的1-Wire器件发送功能命令。如果使用了两个或更多的类似器件，则必须通过查找表才能正确访问特定器件。

调用OWSearch函数可以识别总线上所有的1-Wire器件，该函数将8字节ROMID排成一列。这期间无需调用OWReset函数，因为该函数已经包含在OWSearch函数中。OWSearch函数例外的包含了OWReset函数，是因为其搜索算法具有迭代过程。OWSearch函数的返回值为搜索到的1-Wire器件个数，并将每个64位ROMID写入一个名为ROMCodes的二维数组。

下列例程仅演示了调用一次OWSearch的情况，因此后续连接至该1-Wire总线的器件将无法通过该代码进行识别。OWSearch函数成功执行后将返回搜索到的器件个数。如果搜索失败，ErrorStatus变量将返回错误值，其中包括产生OWReset的故障条件。搜索成功后，对ROMCodes数组进行了遍历，并保存每个器件的数组索引。这种器件索引方式是通过比较搜索到的每个器件的家族码实现的。随后调用数组索引，可以实现与搜索到的特定1-Wire器件进行通信。这相当于创建了一个简单的链表(注：可以通过指针进行操作)。//----------------------------------------------------------------------------------------------------//StartofDS1WMsearchROMacceleratorexample//Devicesonthe1-WireIOare://DS28EA00FamilyCode=42h(6900000004E8C842)//DS2431FamliyCode=2Dh(5A0000000FDE052D)//Findalldeviceson1-WirelineandpopulateROMCodesarrayResult=OWSearch(ROMCodes);//Returnsnumberofdevicesfoundifsuccessful//Setnumberof1-Wiredevicesfoundif(Result)NumberOfDevices=Result;if(!Result){switch(ErrorStatus){case-1://DS1WMdidnotrecognize1-WireReset(PD=0)//Todaddyourerrorcodeherebreak;case-2://Nodevicefound(PDR=1)//Todaddyourerrorcodeherebreak;case-7://1-WireIOisshorted(OW_SHORT=1)//Todaddyourerrorcodeherebreak;case-8://1-WireIOisshorted(OW_LOW=1)//Todaddyourerrorcodeherebreak;case-9://InvalidCRCfordevice//Todaddyourerrorcodeherebreak;case-10://ROMCodesarraytoosmall(EditMaxNumberDevicesinDS1WM.h)//Todaddyourerrorcodeherebreak;}}//Note:Thisfunctionisintendedtobeusedwhenthereisonlyonedevicewiththesame//FamilyCodepresentonthelinefor(i=0;i<NumberOfDevices;i++){if(ROMCodes[i][0]==0x42){DS28EA00=i;//SaveoffarrayindexforDS28EA00continue;}if(ROMCodes[i][0]==0x2D){DS2431=i;//SaveoffarrayindexforDS2431continue;}}利用DS1WMAPI函数控制DS28EA00该示例利用之前搜索到的ROMID与DS28EA00进行通信。OWReset之后发送MatchROM命令。ROM码数组连同被访问的器件索引一起，传递到MatchROM函数。1-Wire总线上的器件会在MatchROM命令0x55h之后收到一个64位ROM码，可以使总线主机在多点总线上寻址到特定的DS28EA00。只有与64位ROM序列完全匹配的DS28EA00才能响应接下来的命令，其它的从器件将等待下一个复位脉冲。

OWWriteByte和OWReadByteAPI函数用来产生存储器命令(例如，Write/Copy/ReadScratchpad命令)。DS1WM通过发送WriteScratchpad命令(0x4Eh)以及随后的高温、低温和配置寄存器设置值，来设定温度报警以及分辨率。上述操作完成后，发送OWReset以及MatchROM命令、ROMID和CopyScratchpad命令(0x48h)(将暂存器的内容复制到寄存器存储器)，完成温度分辨率设置。必须为CPU主机增加10ms的延时，以完成复制操作。考虑到微处理器延时子程序的差异，API仅提供了注释伪码。

复制操作完成后，再次执行OWReset，然后发送MatchROM、ROMID和转换温度命令(0x44h)。需要增加100ms的延时，以完成温度转换。最后，发送OWReset和MatchROM、ROMID和ReadScratchpad命令(0xBEh)，读取两字节温度数据。需要注意的是，选择DS28EA00时，必须始终遵循OWReset之后发送MatchROM命令和ROMID的命令格式。当总线上仅有一个器件时，才能够使用SkipROM命令(即无需SearchROM)。//----------------------------------------------------------------------------------------------------//StartofDS28EA00exampleResult=OWReset();if(!Result){switch(ErrorStatus){case-1://DS1WMdidnotrecognize1-Wirereset(PD=0)//Todaddyourerrorcodeherebreak;case-2://Nodevicefound(PDR=1)//Todaddyourerrorcodeherebreak;case-7://1-WireIOisshorted(OW_SHORT=1)//Todaddyourerrorcodeherebreak;case-8://1-WireIOisshorted(OW_LOW=1)//Todaddyourerrorcodeherebreak;}}//SettemperatureresolutionResult=MatchROM(ROMCodes,DS28EA00);//SelectdeviceResult=OWWriteByte(0x4E);//IssueWriteScratchpadcommandResult=OWWriteByte(0x00);//THregisterdataResult=OWWriteByte(0x00);//TLdegisterdataResult=OWWriteByte(0x1F);//Config.reg.data(set9-bittemp.resolution)OWReset();//ErrorcoderemovedforconcisenessMatchROM(ROMCodes,DS28EA00);//SelectdeviceOWWriteByte(0x48);//IssueCopyScratchpadcommand//Todaddmicroprocessor-specificcodedelaytoallowcopytocomplete//Delay(10MS);//PsuedocodeOWReset();//1-WireresetMatchROM(ROMCodes,DS28EA00);//SelectdeviceOWWriteByte(0x44);//IssueConvertTemperaturecommand//Todaddmicroprocessor-specificcodedelaytoallowtemperatureconversiontocomplete//Delay(100MS);//Psuedocode//ReadtemperatureresultsfromscratchpadOWReset();//1-WireresetMatchROM(ROMCodes,DS28EA00);//SelectdeviceOWWriteByte(0xBE);//IssueReadScratchpadcommandTempLSB=OWReadByte(); //ReadbyteTempMSB=OWReadByte(); //Readbyte//EndofDS28EA00example//----------------------------------------------------------------------------------------------------利用DS1WMAPI函数控制高速模式下的DS2431该示例利用之前搜索到的ROMID与DS2431进行通信。OWReset之后发送OverdriveSkipROM命令(0x3Ch)，将所有支持高速模式的1-Wire器件置于高速模式。调用OverdriveEnable函数激活DS1WM高速时序。此时所有1-Wire器件工作在高速模式。标准速率模式和高速模式下的1-Wire时序请参见应用笔记126：“用软件实现1-Wire®通信”。使用目标地址TA1和TA2变量在第一个示例方法中，变量TA1和TA2设置为DS2431期望的存储器地址。发送OWReset，之后是MatchROM、DS2431ROMID、WriteScratchpad命令(0x0Fh)、目标地址1&2以及要写入DS243164位暂存器的8字节数据。推荐进行回读及CRC16校验操作。关于CRC16的详细讨论，请参考应用笔记27：“理解和运用MaximiButton®产品中的循环冗余校验(CRC)”。OWWriteBytes和OWReadBytes在第二个示例方法中，调用了两个新的API函数：OWWriteBytes和OWReadBytes。这两个API函数简化了大量数据至暂存器的读写操作。

写暂存器的方法是：设置目标地址1&2、将数据写入WriteBytes数组、执行OWReset、然后发送MatchROM、DS2431ROMID、WriteScratchpad命令(0x0Fh)、目标地址1&2、利用OWWriteBytes函数写入保存在WriteBytes的所有10个字节、回读CRC16并对CRC16进行校验。

读暂存器的方法是：执行OWReset、发送MatchROM、DS2431ROMID、ReadScratchpad命令(0xAAh)、利用OWReadBytes函数读取所有13个字节(TA1、TA2、ES、CRC16&8字节数据)并保存到ReadBytes。

调用API函数OverdriveDisable，并随后发送标准OWReset，可以退出高速模数，使所有器件返回至标准速率。//----------------------------------------------------------------------------------------------------//StartofDS2431exampleResult=OWReset();//ErrorcoderemovedforconcisenessResult=OWWriteByte(0x3C);//OverdriveSkipROM(alldevicesarenowinoverdrive)OverdriveEnable();//EnableOverdriveMode//Writescratchpadwithdata//FirstmethodTA1=0x00;TA2=0x00;Result=OWReset();//1-WireresetResult=MatchROM(ROMCodes,DS2431);//SelectdeviceResult=OWWriteByte(0x0F);//IssueWriteScratchpadcommandResult=OWWriteByte(TA1);//Sendtargetaddress1(TA1)Result=OWWriteByte(TA2);//Sendtargetaddress2(TA2)//Write8BytesofDataResult=OWWriteByte(0x11);//SendDataByteforallResult=OWWriteByte(0x22);Result=OWWriteByte(0x33);Result=OWWriteByte(0x44);Result=OWWriteByte(0x55);Result=OWWriteByte(0x66);Result=OWWriteByte(0x77);Result=OWWriteByte(0x88);//ItisrecommendedthattheCRC16bereadbackandverified//CRC16codewasleftoutforconcisenessResult=OWReset();//1-WireResetResult=MatchROM(ROMCodes,DS2431);//SelectdeviceResult=OWWriteByte(0xAA);//IssueReadScratchpadcommandResult=OWReadByte();//ReadTA1if(Result!=TA1){//TodAddyourerrorcodehere}Result=OWReadByte();//ReadTA2if(Result!=TA2){//TodAddyourerrorcodehere}ES=OWReadByte();//ReadES//TodaddyourerrorcodeafterreadsResult=OWReadByte();//ReadDataByte(0x11)Result=OWReadByte();//ReadDataByte(0x22)Result=OWReadByte();//ReadDataByte(0x33)Result=OWReadByte();//ReadDataByte(0x44)Result=OWReadByte();//ReadDataByte(0x55)Result=OWReadByte();//ReadDataByte(0x66)Result=OWReadByte();//ReadDataByte(0x77)Result=OWReadByte();//ReadDataByte(0x88)//ItisrecommendedthattheCRC16bereadbackandverified//CRC