APPLICATION NOTE 1097

White Paper 2: Using the 1-Wire® Public Domain Kit


Abstract: This document describes how to use the 1-Wire Public Domain (PD) Kit. The kit is a completely open source, portable C library to create a 1-Wire master using the DS2480B serial to 1-Wire line driver or a custom 1-Wire interface. The kit also includes numerous example applications covering a variety of 1-Wire and iButton® devices. This document explains how to combine the files in the kit to form applications on both supported and unsupported operating systems.

Introduction

This document describes how to use the 1-Wire Public Domain (PD) Kit. The kit was built to assist any developer creating an application that uses Maxim's 1-Wire devices. The kit is also a learning tool to understand how to communicate to the 1-Wire network.

This article explains how to combine the files in the kit to form an application. It also shows how to build custom applications for a different OS platform, even if one is not already supported.

The source code in the 1-Wire PD kit was written in C. This language was selected because it is one of the most common programming languages and is highly portable to different operating systems. Application note 155, "1-Wire® Software Resource Guide Device Description," describes the 1-Wire PD kit and other software development kits that are available.

API Function Grouping

The software functions in the 1-Wire PD kit API are grouped together (usually into separate files) according to their intended purpose.
  • The Session group acquires and releases exclusive use of the 1-Wire so that no other application can interfere with communication.
  • The Link group is a set of primitive 1-Wire communication functions, which include reset, reading/writing bits, EPROM programming pulse, and power delivery. These Link functions are platform-dependent.
  • The Network function group performs device discovery and selection operations. Each 1-Wire device has a 1-Wire network address for individual selection.
  • The Transport group performs block communication and primitive read/write memory functions, which include packet read/write functions to 1-Wire devices.
  • The File group contains memory-level functions that use the 1-Wire File Structure (see application note 114, "1-Wire File Structure"). The File group can be used on 1-Wire devices with more than one page of memory.
  • The Device group uses the above functional groups to perform specific operations on 1-Wire devices. These operations include SHA operations, temperature readings, voltage readings, and setting switch states.

Organization of Source Files

The platform-specific code in the 1-Wire PD kit is organized into a few files (TODO templates) for easy porting to different platforms. These files represent the lowest level of the API that is hardware dependent. As long as these few files are coded correctly, the rest of the API (and sample applications) should compile and run.

There are three standard methods to build the lowest level of the API for a particular platform. The first method is called "general" and the second is called "userial." The general build method requires the developer to implement the primitive link-level 1-Wire communication functions. See application note 126, "1-Wire Communication Through Software," for more details. The userial build method is strictly for the RS-232 serial port and assumes that the developer will utilize Maxim's DS2480B, the Universal Serial 1-Wire Line Driver Master. The only software functionality to implement for a userial platform build is the serial-port read/write primitives. See application note 192, "Using the DS2480B Serial 1-Wire Line Driver," for more details. Maxim sells several DS2480B-based PC serial adapters, such as the DS9097U-009, DS9097U-S09, DS9097U-E25, DS1411-009, and DS1411-S09.

A third, "other" implementation category provides the standard 1-Wire PD kit basic API, but can diverge in API implementation by taking advantage of particular system or adapter features. For example, implementations of the API using a 1-Wire USB adapter, such as the DS9490R, require this category to take advantage of the USB port and special features built into the adapter.

The Figure 1 flow-chart steps through the decisions that ensure optimal use of the kit.

Figure 1. Usage flowchart for the 1-Wire PD kit.
Figure 1. Usage flowchart for the 1-Wire PD kit.

How to Create an Application

The kit files are organized into several subdirectories.
  • The files in the \apps directory can be used with the files in the \common directory to form an application basis for any port or platform.
  • The files in the lib\general and the lib\userial are the two sets of portable source files discussed earlier.
  • The last task for putting the application together is the Link file, which can be found in either \lib\userial\link or \lib\general\link. If the link file does not exist for the target platform, then you must complete the source code template files (for example, the TODO.C file for "userial" builds) provided with the kit. These link files have functions for your port and platform that need to be filled in correctly to get the 1-Wire PD kit working. Figure 2 illustrates gathering all the files together with an existing Link file.
Figure 2. Files needed to construct an application.
Figure 2. Files needed to construct an application.

Table 1 shows the various platforms currently supported by the kit. The platforms can be downloaded from the 1-Wire Public Domain kit main page.

Table 1. Software Platforms Supported by the 1-Wire PD kit
Platform Compiler Library Port Interface Name
Win32® MS Visual C other USB DS9490 + WinUSB winusb32vc
Win32 MS Visual C other USB DS9490 + libusb libusbw32vc
Win32 MS Visual C userial COM DS2480B uwin32vc
Win32 GNU C userial COM DS2480B uwin32gnu
Win32 MS Visual C general LPT DS1410E* gpw32vc
Win32 MS Visual C other USB
COM
LPT
multiport multiw32vc
Win64 MS Visual C other USB DS9490 + WinUSB winusb64vc
Win64 MS Visual C other USB DS9490 + libusb libusbw64vc
Win64 MS Visual C userial COM DS2480B uwin64vc
Win64 MS Visual C general LPT DS1410E* gpw64vc
Win64 MS Visual C other USB
COM
LPT
multiport multiw64vc
Mac OS® X GNU C other USB DS9490 + libusb libusbmacosx
Mac OS X GNU C userial COM DS2480B umacosxgnu
Linux® GNU C other USB DS9490 + libusb libusblinux
Linux GNU C userial COM DS2480B ulinuxgnu
DS550 Keil® general Micro Active pullup pin gds550keil
DS550 Keil userial Micro DS2480B uds550keil
*The DS1410E is no longer recommended for new designs.

1-Wire is a registered trademark of Maxim Integrated Products, Inc.

iButton is a registered trademark of Maxim Integrated Products, Inc.

Keil Software is a trademark of ARM Limited.

Linux is a registered trademark of Linus Torvalds.

Mac OS is a registered trademark of Apple Inc.

Win32 is a registered trademark of Microsoft Corporation.



Related Parts
DS1411-009 Serial Port iButton Holder  
DS1411-S09 Serial Port iButton Holder  
DS18S20 1-Wire Parasite-Power Digital Thermometer Free Samples  
DS18S20-PAR Parasite-Power Digital Thermometer  
DS1920 Temperature iButton  
DS1963S iButton Monetary Device with SHA-1 Function  
DS1971 iButton 256-Bit EEPROM  
DS1973 iButton 4Kb EEPROM Free Samples  
DS1982 iButton 1Kb Add-Only Free Samples  
DS1985 iButton 16Kb Add-Only Free Samples  
DS1990A iButton Serial Number Free Samples  
DS1992 iButton 1Kb/4Kb Memory Free Samples  
DS1993 iButton 1Kb/4Kb Memory Free Samples  
DS1995 iButton 16Kb Memory Free Samples  
DS1996 iButton 64Kb Memory Free Samples  
DS2401 Silicon Serial Number Free Samples  
DS2406 Dual Addressable Switch Plus 1Kb Memory Free Samples  
DS2431 1024-Bit 1-Wire EEPROM Free Samples  
DS2432 1Kb Protected 1-Wire EEPROM with SHA-1 Engine Free Samples  
DS2438 Smart Battery Monitor Free Samples  
DS2450 1-Wire Quad A/D Converter  
DS2480B Serial to 1-Wire Line Driver Free Samples  
DS2502 1Kb Add-Only Memory Free Samples  
DS2505 16Kb Add-Only Memory Free Samples  
DS28E05 1-Wire EEPROM Free Samples  
DS9097U-009 Universal 1-Wire COM Port Adapter  
DS9097U-E25 Universal 1-Wire COM Port Adapter  
DS9097U-S09 Universal 1-Wire COM Port Adapter  


Next Steps
EE-Mail Subscribe to EE-Mail and receive automatic notice of new documents in your areas of interest.
Download Download, PDF Format (76kB)  

© Jul 16, 2008, Maxim Integrated Products, Inc.
The content on this webpage is protected by copyright laws of the United States and of foreign countries. For requests to copy this content, contact us.

APP 1097: Jul 16, 2008
APPLICATION NOTE 1097, AN1097, AN 1097, APP1097, Appnote1097, Appnote 1097