Maxim>Products> iButton > Software Resources > iButton: 1-Wire Public Domain Kit

iButton: 1-Wire Public Domain Kit

The 1-Wire® Public Domain Kit is a software development kit (SDK) containing a 1-Wire API written entirely in C. The API source included in the kit is portable across multiple PC operating systems, handheld operating systems, and microcontroller platforms. The kit also contains over 20 sample 1-Wire/iButton applications, all written in C. For microcontroller platforms without an available C compiler, the kit also includes assembly code functions representing low-level 1-Wire bus protocol algorithms such as reset/presence detect, byte I/O, and bit I/O. The following download is source code only, and contains the Public Domain Kit's API, the example programs, different platform-specific link files, and assembly language files for microcontrollers without a C compiler.

Download Version 3.10—source code only. (Now supports the DS9490 USB 1-Wire Adapter.)
*See the table below to download precompiled binary builds for specific platforms and 1-Wire adapters.

Kit Advantages

  1. The 1-Wire Public Domain Kit enables the developer to create a 1-Wire master in software that can identify and communicate with slave devices. The 1-Wire protocol is a single-wire-and-ground network with one master and one or more slave devices (such as iButtons and 1-Wire chips). The kit provides all the 1-Wire transport and file-level services to communicate with any 1-Wire device, including iButtons.
  2. The developer can easily port 1-Wire programs to multiple PC and microprocessor platforms. There are provided "TODO" templates (link files) to be completed for a specific platform. The kit provides several platform example implementations with their source code.
  3. The kit contains higher level API functions, such as ReadAtoDResults() and ReadTemperature() for different 1-Wire sensors, along with MemoryBank and File functions for writing and reading 1-Wire memory.

A Note On Portability

All the platform-specific code in the Public Domain 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 apps) should compile and run nicely.

There are three standard ways to code the lowest level of the API. The first method is called "general" and the second is called "userial". The general build requires an implementation of the primitive link-level 1-Wire communication functions (see Application Note 126). The userial build assumes that the user has a serial port (RS-232) and wants to utilize Maxim's DS2480B, a Universal Serial 1-Wire Line Driver Master. The DS2480B receives commands over the serial port, performs 1-Wire operations, and then sends the results back to the serial port. The source code converts the intended 1-Wire operations into serial communications packets to the DS2480B. The only components that must be provided for a userial platform are the serial port read/write primitives (see Application Note 192). Maxim sells several DS2480B-based serial adapters, such as the ds9097U-009, DS9097U-S09, DS9097U-E25 or DS1411. A third, 'other' implementation category provides the standard 1-Wire Public Domain basic API, but can diverge in API implementation by taking advantage of particular system or adapter features.

Example Programs

To demonstrate the 1-Wire Public Domain API, several example applications have been provided. These applications are described below.
Program Description of Program
atodtst Finds and displays the value for channels A, B, C, and D on the DS2450 quad ADC.
counter Reads DS2423 1-Wire Counter values.
coupler Tests the DS2409 1-Wire Coupler (switch) commands and searches for DS2409s and any devices on a branch of the specified DS2409.
fish Read, write, format, and display the file system on a 1-Wire memory device.
gethumd Measures the humidity using a DS2438-based humidity sensor.
humalog Sets and/or stops mission for recording temperature and humidity (or voltage) for the DS1923 Hygrochron, an iButton that logs humidity. The application will also set the device's passwords, and will read the current data if a mission is not in progress. This application also works with the DS1922T, DS1922L, or DS2422.
memutil Reads and writes 1-Wire memory devices. Memory for each device is divided by feature into different 'banks'. Memutil reads and writes using 'banks'.
mweather Reads the 1-Wire Weather Station. Supports both versions of the weather station.
sa_ps
(2 programs)
Test applications (ps_init and ps_check) for software authentication using the DS1991 iButton and its password-protected memory areas.
sa_sha
(2 programs)
Test applications (sha_init and sha_chck) for software authentication using the DS1963S/DS1961S SHA iButtons.
sa_time
(2 programs)
Test applications (tm_init and tm_check) for an example of software authentication using timed trials. The application relies on the real-time clock in the DS1994 iButtons.
shaapp Test application for exercising the DS2432, and DS1961S on a 1-Wire network.
shadebit
(3 programs)
Test program to debit the DS1963S/DS1961S SHA iButton in an e-cash/vending application that requires secure authentication. The application requires the initcopr and initrov programs to set up a DS1963S as a SHA coprocessor (initcopr) and a DS1963S or DS1961S as a roving token (with a small electronic change purse).
swtduo Test application to perform various operations on the DS2413 Dual Addressable Switch.
swtloop Test application to perform various operations on the DS2406 Dual Addressable Switch.
swtmain1c Test application to perform various operations on the DS28E04 1-Wire EEPROM with PIO.
swtmulti This application is for accessing and controlling the DS2408. A list of options will be provided when the program starts and finds the first DS2408.
swtsngl Test application to turn the DS2405 on and off, and read the on/off status of the DS2405 Addressable Switch.
temp Finds and displays the temperature measurement for the DS18S20/DS1920 1-Wire Digital Thermometer.
thermo
(2 programs)
These utilities are used to download (thermodl) and mission (thermoms) a DS1921G Thermochron iButton. (Application does not currently support the H or Z versions of the Thermochron.)
tstfind Simple application that finds all 1-Wire devices on the network.
assembly language routines Assembly language routines that represent low-level 1-Wire bus protocol algorithms such as reset/presence detect, byte I/O, and bit I/O. The routines are available for the following types of microcontrollers: 6303, 8051, 808X, ATMEL (ATmega103), and PIC (16C54, 12C508A).

What's New in Version 3.10

  1. Added Macintosh OSX builds for serial and usb (libusb) 1-Wire adapters.
  2. Removed 16-bit DOS, 16-bit Windows, and Windows CE/PocketPC builds.
  3. Updated humutil.c with fixes for convert errors.
  4. Added the applications swtduo, swtmain1c, and swtmulti to support the DS2413, DS28E04-100, and the DS2408 respectively.
  5. Changed the search CRC calculation to account for the changing DS28E04-100 serial number.
  6. Fixed owRelease() in the "multiport" and the "DS9490" builds. The code should now release the adapter correctly.

Precompiled Binary Builds

The Public Domain Kit was ported to several platforms, which are available for download below. Each build contains the source code, the make files or project files, and the executables. Note that the userial implementations require a DS2480B-based serial adapter such as the DS9097U-009, DS9097U-S09, DS9097U-E25, or DS1411.
Platform Port Library Compiler Download
Win32® COM userial Visual C++® All standard examples (ZIP, 2.2MB)
Win32 USB other
(DS9490)
Visual C++ All standard examples (ZIP, 2.1MB)
Win32 USB other
(DS9490 + libusb)
Visual C++ All standard examples (ZIP, 2.2MB)
Win32 USB LPT COM other
(multi-port)
Visual C++ All standard examples, search example only across multiple adapters (ZIP, 2.6MB)
Win64 (x64 and IA64) USB USB other (DS9490 + libusb) WDK All standard examples (ZIP, 4.8MB)
* version 3.11 beta (pre-release)
Mac OS® X USB USB other (DS9490 + libusb) GNU C All standard examples (ZIP, 2.9MB)
* universal binaries (PPC/Intel)
Mac OS X COM userial GNU C All standard examples (ZIP, 3.2MB)
* universal binaries (PPC/Intel)
Linux COM userial GNU C All standard examples (ZIP, 1.9MB)
Linux USB other
(DS9490 + libusb)
GNU C All standard examples (ZIP, 1.9MB)
Win32 LPT general
(DS1410E)
Visual C++ All standard examples (ZIP, 1.8MB)
Win32 TMEX other
(wrapper)
Visual C++ All standard examples (ZIP, 1.7MB) *see errata page for updates
Win32 COM userial GNU C All standard examples (ZIP, 2.0MB)
DS550 Active Pull-up Pin general Keil™ All standard examples (ZIP, 809kB)
DS550 COM userial Keil All standard examples (ZIP, 817kB)
* Visor®, Palm®, DOS, Win16, Windows CE, and other platform binaries can be built from the link files available in the PDK 3.00 source code download (ZIP, 1.3MB).
* For a running list of known issues with the 1-Wire Public Domain Kit 3.10, please review the errata page.
The following binary builds are preliminary version 3.11 beta 2. This update incorporates the WinUSB support and 64-bit Windows operating systems (Window Vista® x64, Windows XP x64, and Windows 2003 x64).

Precompiled Binary Builds (Preliminary Version 3.11 Beta 2)

Platform Port Library Compiler Download
Win32 USB other
(DS9490 + WinUSB)
Visual Studio® All standard examples (ZIP, 6.6MB)
Win32 USB LPT COM other
(multiport with WinUSB)
Visual Studio All standard examples (ZIP, 2.6MB)
Win64 USB other
(DS9490 + WinUSB)
Visual Studio All standard examples (ZIP, 6.9MB)
Win64 COM userial Visual Studio All standard examples (ZIP, 2.6MB)
Win64 LPT general
(DS1410E)
Visual Studio All standard examples (ZIP, 2.6MB)
Win64 USB LPT COM other
(multiport with WinUSB)
Visual Studio All standard examples (ZIP, 3.1MB)

Legacy Software

Older/alternate Public Domain Kits are still available

Support Resources

If a developer has support questions, needs code examples, or has specific hardware questions, he/she is encouraged to take advantage of the following resources:
  1. Read our White Papers and Application Notes on a wide range of iButton and 1-Wire topics.
  2. Use our Examples Search Engine. A developer can search for a software example that suits design requirements based on 1-Wire device, platform, API, and programming language.
  3. An iButton FAQs page is available for finding quick answers to common questions.
  4. An e-mail archive exists for several years of previous e-mail discussion topics. A search engine helps retrieve support answers from this valuable resource.
  5. 1-Wire Public Domain Kit White Paper: "White Paper 2: Using The 1-Wire Public Domain Kit"
  6. 1-Wire Device Datasheets
  7. iButton Data sheets
  8. Still need help? Just ask an applications engineer.