1-Wire Software Resource Guide Device Description
Available APIs include TMEX (an API for Microsoft Windows®), 1-Wire Public Domain Kit (a cross-platform API), the 1-Wire API for Java™ (OWAPI) and its variant 1-Wire API for .NET (OW.NET), and 1-Wire API for .NET Compact (OW.NET.Compact). All of the APIs described in this document are free to use without restriction and, in most cases, include the complete source code.
Introduction
There are over 30 different1-Wire Overview
The The first part of any communication involves the bus master issuing a reset, which synchronizes the entire bus. A slave device is then selected for subsequent communications. This can be done by selecting all slaves, selecting a specific slave (using the registration number of the device), or by discovering the next slave on the bus using a binary search algorithm. These commands are referred to collectively as network function or read-only-memory (ROM) commands. Once a specific device has been selected, all other devices drop out and ignore subsequent communications until the next reset is issued.
Once a device is isolated for bus communication, the master can issue device-specific commands to it, send data to it, or read data from it. Because each device type performs different functions and serves a different purpose, each type has a unique protocol once it has been selected. Even though each device type may have different protocols and features, they all have the same selection process and follow the command flow seen in Figure 1.

Figure 1. Typical
An integral part of the unique registration number in each slave is an 8-bit family code. This code is specific to the device model. Because each device model performs different functions, this code is used to select the protocol that will be used to control or interrogate it. See Table 1 for a mapping of family codes for Maxim
Table 1. Family Code Reference
Family Code | Part () - iButton Package |
Description (Memory size in bits unless specified) |
01 (hex) | (DS1990A), (DS1990R), DS2401, DS2411 | |
02 | (DS1991)¹ | Multikey iButton, 1152-bit secure memory |
04 | (DS1994), DS2404 | 4Kb NV RAM memory and clock, timer, alarms |
05 | DS2405¹ | Single addressable switch |
06 | (DS1993) | 4Kb NV RAM memory |
08 | (DS1992) | 1Kb NV RAM memory |
09 | (DS1982), DS2502 | 1Kb EPROM memory |
0A | (DS1995) | 16Kb NV RAM memory |
0B | (DS1985), DS2505 | 16Kb EPROM memory |
0C | (DS1996) | 64Kb NV RAM memory |
0F | (DS1986), DS2506 | 64Kb EPROM memory |
10 | (DS1920) | Temperature with alarm trips |
12 | DS2406, DS2407¹ | 1Kb EPROM memory, 2-channel addressable switch |
14 | (DS1971), DS2430A¹ | 256-bit EEPROM memory and 64-bit OTP register |
1A | (DS1963L)¹ | 4Kb NV RAM memory with write cycle counters |
1C | DS28E04-100 | 4096-bit EEPROM memory, 2-channel addressable switch |
1D | DS2423¹ | 4Kb NV RAM memory with external counters |
1F | DS2409¹ | 2-channel addressable coupler for sub-netting |
20 | DS2450 | 4-channel A/D converter (ADC) |
21 | (DS1921G), (DS1921H), (DS1921Z) | Thermochron® temperature logger |
23 | (DS1973), DS2433 | 4Kb EEPROM memory |
24 | (DS1904), DS2415 | Real-time clock (RTC) |
27 | DS2417 | RTC with interrupt |
29 | DS2408 | 8-channel addressable switch |
2C | DS2890¹ | 1-channel digital potentiometer |
2D | (DS1972), DS2431 | 1024-bit, |
37 | (DS1977) | Password-protected 32KB (bytes) EEPROM |
3A | (DS2413) | 2-channel addressable switch |
41 | (DS1922L), (DS1922T), (DS1923), DS2422 | High-capacity Thermochron (temperature) and Hygrochron™ (humidity) loggers |
42 | DS28EA00 | Programmable resolution digital thermometer with sequenced detection and PIO |
43 | DS28EC20 | 20Kb |
¹These devices are no longer recommended for new designs.
API Fundamentals
The different APIs for communicating withSESSION |
Negotiate exclusive use of the |
LINK |
Primitive |
NETWORK |
Network functions for device discovery and selection. The unique registration number programmed into each |
TRANSPORT |
Block communication and primitive read/write memory functions. This can also include packet read/write memory functions. These functions are constructed from the NETWORK and LINK group functions. |
FILE |
File memory level functions using the |
DEVICE |
Device-specific 'high-level' functions. These functions are often constructed from the NETWORK, TRANSPORT, and LINK group functions and perform operations such as reading temperature values or setting a switch state. |
The typical sequence to use these functions is outlined in Figure 3. The SESSION functions wrap around the communication calls to the device, which typically involve using a NETWORK function followed by a memory or DEVICE-specific operation.

Figure 3. API usage flow.
The nature of iButton communication is inherently 'touch.' This means that contact with the device is not always reliable. The iButton might be inserted into the reader and have intermittent contact during the read. Consequently a consistent methodology of error recovery must be rigorously followed. This usually entails doing retries when a spurious error is detected and utilizing CRC checks in data communication. The file I/O functions in the APIs use a standard file structure detailed in the
API Selection
There are principally five different APIs that are considered in this document. The APIs operate on different platforms, use different languages, and have different capabilities. Table 2 displays these five APIs with a brief description, and Table 3 maps the operating system with the available APIs divided by language.Table 2. API Descriptions
API | Abbreviation | Description |
PD | A completely open-source public domain API written in C and designed to be portable across multiple PC operating systems, handheld operating systems, and microcontroller platforms. For PC platforms, it supports all |
|
OWAPI | Completely open-source, high-level Java API that supports almost ALL |
|
OW.NET | OWAPI code base compiled with J# for the Microsoft .NET Framework. | |
OW.NET.Compact | Compact .NET Framework for Windows CE machines or platforms that do not have the Microsoft Visual J#® Redistributable Package. It currently consists of just the low-level |
|
TMEX API | TMEX | Supports all |
Table 3. API Operating System and Language Coverage
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 |
¹No longer supported. Legacy driver downloads still available from the Maxim web site.
The support of the individual device families also varies from API to API. Table 4 lists all of the currently available
Table 4. API Support by Device
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 | 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 | 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 | 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 |
Support Shading Guide | Support Flags |
Full Support | A. B. C. Transport memory byte read/write support D. Transport memory packet read/write support E. F. G. H. I. Other device-specific support |
Partial Support | |
Minimal Support |
1-Wire Public Domain (PD) Overview
The functions provided in The 'C' source code to this API is designed to be portable. There are provided 'TODO' templates to be completed for a specific platform. Several platform example implementations are provided including: Windows 64-bit, Windows 32-bit, and Linux. There are also several example applications that use these platform implementations.
There are three sets of portable source files defined as 'general,' 'userial,' and 'other.' The first set is general purpose and is intended for platforms that already have the primitive link
In particular, this application note also presents the open-source, cross-platform libusb build of the
See table below for the various file sets available, which have already been built for each platform presented in the table and are available for download.
Table 5.
Portable Source File Set (Builds) | Platform | Port | Description |
userial | Win64, Win32, Linux, (other UNIX), DS550 | COM | Supports the DS9097U |
general | Win64, Win32 | LPT | The LPT build supports the DS1410E¹ parallel port adapter on Windows. |
DS550 | Microprocessor (µP) port pin | The DS550 general build uses a µP port pin. | |
other 'libusb' | Win64, Win32, Linux, Macintosh, (other UNIX) | USB | Supports DS9490 USB |
other 'WinUsb' | Win64, Win32 | USB | Supports DS9490 USB |
other 'wrapper' (TMEX) | Win32 | USB, COM, LPT | Wraps the TMEX API, which gives the ability for multiport support under Windows (DS9490, DS9097U, DS1410E¹, respectively). |
other 'multiport' | Win64, Win32 | USB, COM, LPT | Gives mutliport support by communicating directly with low-level native Windows drivers. |
¹The DS1410E parallel port adapter is not recommended for new designs.
These sets of portable source code files implement the same
In addition to the portable 'C' modules in the PD kit download, there are also a limited number of microprocessor (µP) assembly examples to perform
The file functions in this API implement the
As the name of this API would imply, the source code provided has a license that is as close to being public domain as possible. Developers are free to use and integrate this code into their applications without restriction.
SESSION |
owAcquire - Acquires the owRelease - Releases the previously acquired |
LINK |
owHasOverDrive - Indicates whether the adapter has overdrive capability. owHasPowerDelivery - Indicates whether the adapter can deliver power. owHasProgramPulse - Indicates whether or not EPROM programming voltage is available. owLevel - Sets the owProgramPulse - Sends timed programming pulse for EPROM owReadBitPower - Reads 1 bit and then optionally supplies power. owReadByte - Receives 8 bits from the owSpeed - Sets the speed of the owTouchBit - Sends and receives 1 bit from the owTouchByte - Sends and receives 8 bits from the owTouchReset - Resets all devices on the owWriteByte - Sends 8 bits to the owWriteBytePower - Sends 8 bits of communication to the |
NETWORK |
owAccess - Selects the current device and readies it for a device-specific command. owFamilySearchSetup - Sets up the following search (owNext) to find a specific family type. owFirst - Searches to find the first owNext - Searches to find the next owOverdriveAccess - Selects the current device and sets the speed to Overdrive. owSerialNum - Retrieves or sets the currently selected device registration number (ROM number). owSkipFamily - Skips all of the owVerify - Selects and verifies that the current device is present (alarming option). |
TRANSPORT |
owBlock - Sends and receives a block of data to the owCanLockPage - Checks to see if the given memory bank has pages that can be locked. owCanLockRedirectPage - Checks to see if the given memory bank has pages that can be locked from being redirected. owGetAlternateName - Gets the alternate part numbers or names. owGetBankDescription - Gets a string description of the memory bank. owGetDescription - Gets a short description of the owGetExtraInfoDesc - Gets a description of what is contained in the extra information. owGetExtraInfoLength - Gets the length in bytes of extra information in this memory bank. owGetMaxPacketDataLength - Gets maximum data length in bytes for a packet. owGetName - Gets the part number of the owGetNumberBanks - Gets the number of memory banks for a certain owGetNumberPages - Gets the number of pages in a given memory bank. owGetPageLength - Gets the raw page length in bytes for a given memory bank. owGetSize - Gets the size of a given memory bank in bytes. owGetStartingAddress - Gets the physical starting address of the given memory bank. owHasExtraInfo - Checks to see if this memory bank's pages deliver extra information when read. owHasPageAutoCRC - Checks to see if the memory bank has device-generated CRC verification when reading a page. owIsGeneralPurposeMemory - Checks to see if the memory bank is general-purpose user memory. owIsNonvolatile - Checks to see if current memory bank is nonvolatile. owIsReadOnly - Checks to see if the memory bank is read-only. owIsReadWrite - Checks to see if the memory bank is read/write. owIsWriteOnce - Checks to see if the memory bank is write once, such as with EPROM. owNeedsPowerDelivery - Checks to see if this memory bank requires 'PowerDelivery' to write. owNeedsProgramPulse - Checks to see if this memory bank requires a 'ProgramPulse' to write. owRead - Reads a portion of a memory bank in raw mode (no packets, CRC). owReadPage - Reads an entire page of a memory bank in raw mode (no packets, CRC). owReadPageCRC - Reads an entire page of a memory bank with device-generated CRC verification. owReadPageExtra - Reads an entire raw page of a memory bank including any 'extra' information. (no packets, CRC) owReadPageExtraCRC - Reads an entire raw page of a memory bank including any 'extra' information and with device-generated CRC verification. owReadPagePacket - Reads a Universal Data Packet from a page in a memory bank. (Refer to application note 114, " owReadPagePacketExtra - Reads a Universal Data Packet from a page in a memory bank with 'extra' information. owRedirectPage - Checks to see if the memory bank has pages that can be redirected. owWrite - Writes a portion of a memory bank in raw mode. owWritePagePacket - Writes a Universal Data Packet to a page in a memory bank. |
FILE |
owAttribute - Changes the attributes of a file. owChangeDirectory - Changes the current directory. owCloseFile - Closes a file. owCreateDir - Creates a directory. owCreateFile - Creates a file for writing. owCreateProgramJob - Creates a write buffer for logging EPROM programming pending jobs. owDeleteFile - Deletes a file. owDoProgramJob - Write the pending EPROM programming jobs. owFirstFile - Finds the first file in the current directory. owFormat - Formats the owGetCurrentDir - Gets the current directory. owNextFile - Finds the next file in the current directory. owOpenFile - Opens a file for reading. owReadFile - Reads an opened file. owReadFile - Reads data from a file. owRemoveDir - Removes a directory. owReNameFile - Changes the name of a file. owWriteFile - Writes to a file that has been created. |
DEVICE |
DoAtoDConversion - Does an A/D conversion on DS2450. ReadSwitch12 - Reads the state of the DS2406 switch. readCounter - Reads the counter value associated with a specific memory page on a DS2423 ...(too numerous to list all device-specific functions) |
Example 1 shows a PD code fragment that follows the API usage flow outlined in Figure 3. For simplicity, each device on the
int rslt, portnum=0, doing_work=1; char portString[50]; // set to platform appropriate port string // work loop while (doing_work) { // acquire the |
Figures 5a and 5b list the C-language modules that make up each of the two sets of
SESSION | |||||
owsesu.c | |||||
LINK | |||||
owllu.c![]() ![]() |
|||||
NETWORK | |||||
ownetu.c![]() |
|||||
TRANSPORT | |||||
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 | |||
FILE | |||||
owcache.c | owfile.c | owfile.h | owpgrw.c | owprgm.c | |
DEVICE | |||||
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 |
MISC UTILITY | |||||
ioutil.c | owerr.c | findtype.c | ownet.h | screenio.c | sprintf.c |
crcutil.c | |||||
TODO | |||||
Provided a SERIAL interface module that implements the following functions: BreakCOM* - Sends a 'BREAK' on the serial port for at least 2ms. CloseCOM - Closes the previously opened serial port. (optional for some platforms) FlushCOM* - Allows any pending write operations to complete and clear input buffer. msDelay* - Delays at least the specified number of milliseconds. msGettick - Returns an increment millisecond counter. (optional for some examples) OpenCOM - Opens the specified serial port for communication. (optional for some platforms) ReadCOM* - Reads a specified number of bytes from the serial port. SetCOMBaud - Changes the serial BAUD rate to the rate specified. (optional if needs overdrive) WriteCOM* - Writes a specified number of bytes to the serial port. * Minimum functions required for basic operation. |
SESSION |
(see TODO) |
LINK |
(see TODO) |
NETWORK |
ownet.c![]() |
TRANSPORT |
Same as USERIAL implementation except 'owtrnu.c' is replaced by 'owtran.c'. |
FILE |
Same as USERIAL implementation. |
DEVICE |
Same as USERIAL implementation. |
MISC UTILITY |
Same as USERIAL implementation. |
TODO |
Provided a LINK and SESSION interface module that implements the following functions: owAcquire - Acquires the owRelease - Releases the previously acquired owHasOverDrive - Indicates whether the adapter has overdrive capability. owHasPowerDelivery - Indicates whether the adapter can deliver power. owHasProgramPulse - Indicates whether or not EPROM programming voltage is available. owLevel - Sets the owProgramPulse - Sends timed programming pulse for EPROM owReadBitPower - Reads 1 bit and then optionally supplies power. owReadByte - Receives 8 bits from the owSpeed - Sets the speed of the owTouchBit* - Sends and receives 1 bit from the owTouchByte - Sends and receives 8 bits from the owTouchReset* - Resets all devices on the owWriteByte - Sends 8 bits to the owWriteBytePower - Sends 8 bits of communication to the * Minimum functions required for basic operation. |
Installation
TheKeep in mind that some builds require native
1-Wire API for Java (OWAPI) Overview
The The API consists of many Java classes and interfaces. One special group of Java classes in the
A container interacts with a
The
Figure 6 shows the typical object creation sequence for this API. The 'provider' creates an instance (or enumeration) of an 'adapter,' which in turn can create instances of device 'containers.' Communication to the device is then performed almost exclusively through the container.

Figure 6. OWAPI object creation.
Figure 7 shows the common features of a container. A device that contains memory will create a memory bank instance for each memory bank. The memory is divided up into banks depending on the feature set of the bank. For example, one bank could be volatile while another is nonvolatile. Or, a bank could be general-purpose memory or it could be memory-mapped to change the functionality of the device.

Figure 7. OWAPI ONEWIRECONTAINER features.
Figure 8 shows the methods provided by the base OWAPI classes. The class or package is displayed in bold. Note that, because each container has high level methods to manipulate each device type, the LINK level methods in the adapter are not usually called directly.
SESSION |
com.dalsemi.onewire.adapter.DSPortAdapter beginExclusive - Acquires exclusive use of the endExclusive - Releases the exclusive lock on the |
LINK |
com.dalsemi.onewire.adapter.DSPortAdapter canBreak - Checks if a canDeliverPower - Checks if 'strong-pullup' power delivery is supported by the adapter. canDeliverSmartPower - Checks if 'smart' power delivery is supported by the adapter. 'Smart' power delivery is the ability to sense when power consumption has reduced and automatically stop the power delivery. canFlex - Checks if flexible long-line communication timing is supported by the adapter. canHyperdrive - Checks if hyperdrive communication speed is supported by the adapter. canOverdrive - Checks if overdrive communication speed is supported by the adapter. canProgram - Checks if 12V EPROM programming voltage is supported by the adapter. dataBlock - Sends and receives a block of data to the getBit - Reads a single bit from the getBlock - Reads a block from the getByte - Reads a byte from the getSpeed - Reads the current putBit - Writes a bit to the putByte - Writes a byte to the reset - Resets all of the setPowerDuration - Sets the power delivery duration. setPowerNormal - Turns off the power delivery. setProgramPulseDuration - Sets the program pulse duration. setSpeed - Sets the startBreak - Starts a break (low) on the startPowerDelivery - Starts the power delivery. startProgramPulse - Starts the program pulse. |
NETWORK |
com.dalsemi.onewire.adapter.DSPortAdapter excludeFamily - Excludes a family group from the search. findFirstDevice - Finds the first device on the findNextDevice - Finds the next device on the getAllDeviceContainers - Searches and finds all devices on the getDeviceContainer - Gets a device container for the 'current' device found. getFirstDeviceContainer - Finds the first device and create a container for it. getNextDeviceContainer - Finds the next device and create a container for it. setNoResetSearch - Sets the setSearchAllDevices - Sets the setSearchOnlyAlarmingDevices - Sets the targetAllFamilies - Sets the targetFamily - Targets a particular family group in the (also in com.dalsemi.onewire.container.*) isAlarming - Checks to see if the device is in an alarm state. isPresent - Checks to see if the device is present on the select - Selects the |
TRANSPORT |
com.dalsemi.onewire.container.MemoryBank getBankDescription - Returns a text description of the memory bank. getSize - Gets the size of the memory bank in bytes. getStartPhysicalAddress - Gets the starting physical address of the memory bank. isGeneralPurposeMemory - Checks if the memory bank is general purpose (not memory mapped). isNonVolatile - Checks if the memory bank is nonvolatile. isReadOnly - Checks if the memory bank is read-only. isReadWrite - Checks if the memory bank is read and write capable. isWriteOnce - Checks if the memory bank is write once, such as EPROM. needsPowerDelivery - Checks if this memory bank requires power delivery to write. needsProgramPulse - Checks if this memory bank requires program pulse to write. read - Reads the memory bank without interpretation (no packet structure). setWriteVerification - Sets the API to do an extra verification after writes. write - Writes the memory bank raw (no packet structure). com.dalsemi.onewire.container.PagedMemoryBank getExtraInfoDescription - Gets a description of extra information associated with this bank. getExtraInfoLength - Gets the length in bytes of the extra information in each page. getMaxPacketDataLength - Gets the maximum length of data that can be contained in the 'packet' structure that will fit in each page of this memory bank. getNumberPages - Gets the number of pages in this memory bank. getPageLength - Gets the length in byte of the raw page in this memory bank. hasExtraInfo - Checks if this memory bank has extra information associated with each page. hasPageAutoCRC - Checks if the pages in this memory bank have CRC verification that is supplied by the device. readPage - Reads a page from the memory bank. readPageCRC - Reads a page from the memory bank utilizing the device-generated CRC. readPagePacket - Reads a packet structure from a page in the memory bank. writePagePacket - Writes a packet structure to a page in the memory bank. com.dalsemi.onewire.container.OTPMemoryBank canLockPage - Checks if the pages in the memory bank can be locked from further writes. canLockRedirectPage - Checks to see if the redirection facilities in the memory bank can be locked to prevent further redirection. canRedirectPage - Checks to see if the memory bank can have pages redirected as a way to update write-once pages. getRedirectedPage - Gets the page number that a page is redirected to. isPageLocked - Checks if the page is locked from further writes. isRedirectPageLocked - Checks if the page is locked from further redirection. lockPage - Locks a page. lockRedirectPage - Locks the page from being redirected. redirectPage - Redirects a page to a new page. This is used to update a write-once device. |
FILE |
com.dalsemi.onewire.utils.OWFile Same methods in java.io.File (for version 1.2 of the JDK) plus the following extra methods: close - Closes the file and releases any resources associated with it. format - Formats the getFD - Gets a OWFileDescriptor for this file so the file can be synchronized with the device. getFreeMemory - Gets the available free memory in the getLocalPage - Gets a memory bank local page reference from the getMemoryBankForPage - Gets the memory bank instance that can be used to read/write the provided getOneWireContainer - Gets the container(s) that make up the file system. getPageList - Gets a list of com.dalsemi.onewire.utils.OWFileDescriptor Same methods as in java.io.FileDescriptor (for version 1.2 of the JDK). com.dalsemi.onewire.utils.OWFileOutputStream Same methods as in java.io.FileOutputStream (for version 1.2 of the JDK). com.dalsemi.onewire.utils.OWFileInputStream Same methods as in java.io.FileInputStream (for version 1.2 of the JDK). |
DEVICE |
com.dalsemi.onewire.container.* Over 30 different device-specific container implementations including six different sensor-type interfaces: ADContainer - Analog-to-digital converter ClockContainer - Clock SwitchContainer - Switch TemperatureContainer - Temperature sensor PotentiometerContainer - Digital potentiometer HumidityContainer - Humidity sensor MissionContainer - For missioning temperature and humidity loggers OneWireSensor - PasswordContainer - Password-protected memory com.dalsemi.onewire.application.* SHA and *Minimum functions required for basic operation. |
Example 2 shows a OWAPI code fragment that follows the API usage flow outlined in Figure 3. Like the PD code example in Example 1, each device on the
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 Tagging
As Installation
All of the required modules that make up the API calls described in Figure 8 are contained in a single jar file: OneWireAPI.jar. Placing this one module in the correct location or classpath provides the entire API. There are two noted exceptions to this: there could be native or communication APIs required to be installed for a particular platform, or the platform could have size constraints so that it is undesirable to have the entire API available. These two exceptions are examined in detail in the OWAPI kit.1-Wire .NET (OW.NET) Overview
For all intents and purposes, the .NET support we offer is the Keep in mind that the OneWire.NET.dll also needs the following redistributables installed on a PC before the
- Native
1-Wire port adapter device drivers. These are known as1-Wire Drivers and can be downloaded from the iButton web site. - Microsoft .NET 2.0 Framework
- Visual J# .NET 2.0 Redistributable
The OW.NET API is provided in a
1-Wire .NET Compact (OW.NET Compact) Overview
The interface for this object is identical to the TMEX API (TMEX) Overview
The TMEX API is a set of language-independent Windows DLLs that provides basic functionality to allThe lowest level of this API (the lowest level device-driver layer) is used as the native drivers for the
Both available on the Maxim web site are the
All of the examples provided in the TMEX SDK are provided with source code. However, the source code for the low-level drivers is currently not provided, though the drivers can be redistributed without restriction.
Table 6 lists the currently supported
Table 6. TMEX Adapters Supported
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 |
Windows Platforms Supported by TMEX
The following Microsoft Windows platforms are supported by TMEX: Windows 2008, Windows 2003, Windows Vista, and Windows XP SP2. This includes both x86 (32-bit) and x64 (64-bit) operating system versions. Please note that if drivers for earlier Windows operating system versions are required, legacy versions of TMEX are available, though not actively supported, from Maxim's web site. Please download version 4.00 or below of the
Figure 9. TMEX API drivers and other API connectivity.
Figure 10 lists functions provided by the TMEX API. Note that this API does not provide any nonmemory-device-specific functions.
SESSION |
TMEndSession - Relinquishes the TMExtendedStartSession - Requests exclusive use of the TMValidSession - Checks to see if the current |
LINK |
TMClose - Releases resources for the opened port. (not always applicable) TMOneWireCom - Sets the speed of the TMOneWireLevel - Sets the TMProgramPulse - Sends a timed programming pulse to TMSetup - Checks and verifies the port and adapter is functioning. TMTouchBit - Sends and receives 1 bit from the TMTouchByte - Sends and receives 1 byte from the TMTouchReset - Resets all devices on the |
NETWORK |
TMAccess - Selects the current device and readies it for a device-specific command. TMAutoOverDrive - Sets the driver to automatically get the device in and out of Overdrive speed. TMFamilySearchSetup - Sets the current search state to find a specified family type on the next search. (TMNext or TMNextAlarm) TMFirst - Searches to find the first TMFirstAlarm - Searches to find the first alarming TMNext - Searches to find the next TMNextAlarm - Searches to find the next alarming TMOverAccess - Selects the current device and sets the speed to Overdrive. TMRom - Retrieves or sets the currently selected device registration number (ROM number). TMSkipFamily - Skips all of the family type that was found in the last search. TMStrongAccess - Selects and verifies that the current device is present. TMStrongAlarmAccess - Selects and verifies that the current device is present AND alarming. |
TRANSPORT |
TMBlockIO - Sends and receives a block of data to the TMBlockStream - Sends and receives a block of data to the TMExtendedReadPage - Reads an entire page of a memory bank with device-generated CRC verification (not applicable to all device types). TMProgramByte - Programs a byte into an EPROM-based TMReadPacket - Reads a Universal Data Packet from a page. (See application note 114, " TMWritePacket - Writes a Universal Data Packet to a page. |
FILE |
TMAttribute - Changes file or directory attributes. TMChangeDirectory - Reads or changes the current working directory. TMCloseFile - Closes an opened or created file to release the file handle. TMCreateFile - Creates a file for writing. TMCreateProgramJob - Creates a write buffer for logging EPROM programming pending jobs. TMDeleteFile - Deletes a file. TMDirectoryMR - Makes or removes a subdirectory. TMDoProgramJob - Writes the pending EPROM programming jobs. TMFirstFile - Finds the first file in the current directory. TMFormat - Formats the TMNextFile - Finds the next file in the current directory. TMOpenFile - Opens a file for reading. TMReadFile - Reads an opened file. TMReNameFile - Renames a file or directory. TMTerminateAddFile - Terminates an 'AddFile.' An 'AddFile' is a special file type on an EPROM device that can be appended to without rewriting. TMWriteAddFile - Appends or alters an 'AddFile' on an EPROM device. TMWriteFile - Writes to a file that has been created. |
DEVICE |
none |
OTHER |
TMGetTypeVersion - Gets the version information for the adapter driver. Get_Version - Gets the overall driver version. |
Example 4 shows a TMEX code fragment that follows the API usage flow outlined in Figure 3. Like the last three examples, a simple process allows each device on the
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 |
Installation
The TMEX API gets installed with the previously mentionedMore information on the
Other Tools
While the APIs discussed in this document represent a large part of the available resources for communication withSoftware Authorization API
Software authorization is simply the locking of a software application to require the presence of a hardware token. The token in this case is an iButton connected to the user's workstation. The application polls for the presence and validity of the iButton before running. It can also continuously query while the application executes. In practice, any of the APIs outlined in this document can be used for this type of application; however, there are specific concerns that must be considered. External drivers present a weakness to the security by allowing a user to replace the driver and thereby defeat the lock. The software authorization API, built upon theThe design of the Software Authorization API is centered on the simplest use cases possible, to make integration into the software programmer's existing code easy. There are three main services provided by the API:
- Initializing a
1-Wire device - Authenticating the device
- Clearing a device (so it is no longer a valid part of the system)
Software Example Search Engine
Maxim continually develops1-Wire device (Thermochron, SHA iButton, etc.)- Platform (Win32, Linux, MxTNI, etc.)
- API (TMEX,
1-Wire Public Domain,1-Wire .NET, etc.) - Programming language (C, Java, C#, Visual Basic, Delphi, etc.)