The full kit can be downloaded from here: ftp://ftp.dalsemi.com/pub/auto_id/public/owapi_1.10.tgz

1-Wire^(R) API for Java^(TM)

Version 1.10

Contents

• Introduction
• Installation
• Examples
• 1-Wire API Primer
• Documentation
• TINI
• License
• Long Lines
• Changes

Introduction

The 1-Wire API for Java contains classes and interfaces that enable rapid development of 1-Wire applications in the Java language on a variety of platforms. Current platforms tested are Win32, TINI^(TM), Linux, and Solaris. Support for particular 1-Wire device types (including iButtons^(R)) is provided through ‘containers’. This kit has 28 different ‘container’ types. All desktop 1-Wire adapters are supported on the Win32 platform through a native driver. TINI has its own native 1-Wire ports. All other platforms are supported through the DS9097U serial adapter using RXTX Serial Communications API. The DS9097U serial adapter information can be found on the Dallas Semiconductor web site:

http://www.maxim-ic.com/DS9097U-009

ALL Java source code for this kit is provided in the ‘src’ directory. See the ‘License’ section.

More information about using the 1-Wire API for Java can be found in Chapter 4 of the TINI Specification and Developer’s Guide by Don Loomis. The book is published by Addison-Wesley is available for purchase at most book retailers. Alternatively, the entire contents of the book is available for a free download in PDF format at the following URL:

http://www.maxim-ic.com/TINIplatform.cfm

The following list highlights the most significant additions to the 1-Wire API since the previous release.

Added Version Info to OneWireAPI.jar

To help eliminate confusion about released versions of the 1-Wire API and the "latest" version which is downloadable with OneWireViewer (on its live WebStart page), version info was added to the manifest file for the OneWireAPI.jar. Further, a default main method is defined in OneWireAccessProvider which will display the version number on the console with the following command:

java -jar OneWireAPI.jar

Current Output:

1-Wire API for Java (Desktop), v1.10
Copyright (C) 1999-2006 Dallas Semiconductor Corporation, All Rights Reserved.

Default Adapter: {DS9490}
   Default Port: USB1

Download latest API and examples from:
http://www.maxim-ic.com/products/ibutton/software/1wire/1wire_api.cfm

New OneWireContainers Added

• OneWireContainer1C for the DS28E04, 4K-bit EEPROM.
• OneWireContainer2D for the DS2431, 1K-bit protected EEPROM.
• OneWireContainer3A for the DS2413, Single addressable switch.

Removed support for Java-powered iButton

Support for the Java-powered iButton has been deprecated from the API. Old releases of the API will still contain the container and other supporting classes, but they will not be included in this release or any future releases.

Numerous bug fixes

See "changes.txt" in the root folder of your 1-Wire API directory for a full list of changes. Considerable updates were made to the DS1977 (OneWireContainer37 and DS2422/DS1923/DS1922[L/T] (OneWireContainer41).

Older Changes

HygroChron Container

A new container for supporting the DS1922H HygroChron iButton is now available. The DS1922H is capable of storing up to 8k of logging data of either Temperature or Humidity, or up to 4k of each. The DS1922T, DS1922L, and DS2422 are also supported by this new container.

Robust Device Network Monitor API

A new implementation of the device network monitoring API is now in the com.dalsemi.onewire.application.monitor package. Both the branched and branchless networks are supported. New API supports running the Device Monitor in a separate thread or single-stepping the search iterations in your main application thread.

8-Channel Addressable Switch Demo

A new demo app to demonstrate the specific capabilities of the DS2408, 1-Wire 8-channel Addressable Switch.

RXTX Serial Communications API

The serial adapter implementation now uses the RXTX Serial Communications API (see below for installation instructions). This allows the serial adapter to work on more platforms and makes support easier since it’s an open source app. The binaries for Win32 are included with the 1-Wire API download and are freely re-distributable under the LGPL license.

NanoXML Library

The nanoxml library was added to the standard 1-Wire API jar, for supporting the parsing of XML files representing descriptions of tagged devices, as in the com.dalsemi.onewire.application.tag package. The 1-Wire Tagging library will still allow for a user specified library, but nanoxml is now the default.

OneWireViewer GUI Application

The OneWireViewer (intended as a replacement for the iButtonViewer) was added under the example applications. It is a graphical application which supports all sensor (temperature, humidity, a/d), clocks, switches, and memory devices (including support for the 1-Wire File system). It also includes device-specific support for the HygroChron, the Thermochron, the DS1961S/DS2432, and the DS1963S.

Network DSPortAdapter

Support classes were added to the package com.dalsemi.onewire.adapter to provide support for accessing a DSPortAdapter over a TCP/IP network. The class NetAdapterHost contains the server-side, for hosting the actual hardware. The NetAdapter (a subclass of DSPortAdapter) is then used to connect to the NetAdapterHost. If multicasting is enabled (see JavaDocs for NetAdapter), the getPortNames() method will return an enumeration of all NetAdapterHosts found on your LAN (or whatever is reachable by multicast from your LAN). A lists of hosts can also be added to the onewire.properties file (see JavaDocs for NetAdapter).

Thermochron Container

The 1-Wire Container for the Thermochron device has been updated to distinguish between different models of Thermochron devices. These include the DS1921H and the DS1921Z.

SHA Transaction API

The package com.dalsemi.onewire.application.sha was added to provide better support classes for SHA iButtons and SHA transactions in general. The classes in this package implement an entirely new architecture for SHA applications. Besides decoupling the protocol for SHA transactions from the user token's support classes, the new architecture greatly simplifies the process of adding new user tokens as well as new types of transactions. Two sample transactions included with the package are a "money" debit application with both signed and unsigned account data. In addition, the SHA Transaction API supports both the DS1961S/DS2432 (SHA EEPROM) and the DS1963S (SHA NVRAM) devices as user tokens. The use of a hardware coprocessor (DS1963S) is now optional and can be replaced by a software-simulated coprocessor.

1-Wire XML Tagging and demo

The package com.dalsemi.onewire.application.tag was added for the 1-Wire XML Tagging support classes. 1-Wire Tagging allows for the grouping, sensing, and automatic association of 1-Wire devices. Using XML, devices can be grouped together into clusters and can be dealt with by applications based on their purpose, not just their device type. A GUI demo application, TagViewer, is included to demonstrate the dynamic loading and configuring of XML tagged 1-Wire devices. Another GUI demo application, TagCreator, is also included to create the tags and save them onto a 1-Wire device’s file structure. See the documentation included with the demo applications for details on the XML 1-Wire tagging format.

1-Wire File Structure – Multi-device Support

The 1-Wire File Structure classes (com.dalsemi.onewire.utils.OWFile*) now support file structures that span multiple 1-Wire devices. See Application Note 114 for the 1-Wire File Structure details:
http://pdfserv.maxim-ic.com/arpdf/AppNotes/app114.pdf

Hygro iButton, HumidityContainer, and demo

A HumidityContainer type was added to support the DS1910 Hygro iButton. A demo application was added to demonstrate its use.

New OneWireContainers Added

• OneWireContainer41 for the DS1922/DS2422, 1-Wire Temperature and Humidity Logger.
• OneWireContainer37 for the DS1977, 1-Wire 64kbytes EEPROM.
• OneWireContainer27 for the DS2417, 1-Wire Time Chip with Interrupt.

Uncompress the kit file into a directory on your development system. The Kit is currently ~5mB. The development system must be able to run the javac compiler. See your JDK (or equivalent) for minimum system requirements. For every platform except TINI, put the OneWireAPI.jar file found in the ‘lib’ directory of this kit in your classpath or in the ‘ext’ directory (for JDK 1.2 and later). If you have a previous version of this file, make sure it is replaced or removed.

TINI

This kit supports firmware version 1.02h of the TINI OS. The application and interface layer are compiled together to produce a ‘tini’ file. Installation of the application then consists of FTP-ing the file to the TINI system and running it. See the ‘TINI’ section of this README for details on creating 1-Wire applications on the TINI platform.

WIN32

There are two ways to read the 1-Wire network under Win32 (Win95,98,NT,2K): RXTX 2.1 Serial Communications API with the DS9097U or the native 1-Wire drivers.

Native (Recommended Method)

The native drivers for Win32 are the TMEX Runtime Environment 32-bit drivers. Install the standard drivers from here:
http://www.maxim-ic.com/products/ibutton/software/tmex/index.cfm

The latest version 3.21X of the 1-Wire native drivers automatically copies the JNI connection layer to Java ‘ibtmjava.dll’ into <windows>\system (or <windows>\system32).

By default the 1-Wire port will be the one selected during the installation of the TMEX Runtime Environment and changed with the ‘Default 1-Wire Net’ application.

RXTX Serial Communications API/DS9097U

Install the RXTX Serial Communications API. RXTX is available for a number of platforms or you can build from the source for your specific platform. The latest builds of RXTX 2.1 require Java 1.4.1 or newer to function properly on win32 platforms. More information about RXTX can be found here:

http://www.rxtx.org/

A build of the RXTX 2.1 Serial Communications API for Win32 is included with the 1-Wire API. After extracting the 1-Wire API to the folder of your choice, look at the subfolder labeled "rxtx\Windows\i368-mingw32." In this subfolder you will find "rxtxSerial.dll". In the root folder, "rxtx", you will find "rxtxComm.jar". The .dll file should be copied into the bin path that you run java.exe from. The .jar file should be added to your classpath.

Note that this is a different serial communications API than what was recommended in previous versions of the 1-Wire API. Previously, the Sun javax.comm API was used, and the two are not compatible. Sun’s javax.comm uses classes in the javax.comm.* namespace while RXTX 2.1 uses classes in the gnu.io.* namespace. So, if you have a previous installation of the 1-Wire API which uses javax.comm, you will still need to install RXTX 2.1.

The RXTX 2.1 binaries included with this release are distributed under the terms of LGPL license. Please see "rxtxLicense.txt" in the "rxtx" subfolder for more information.

The DS9097U adapter class in this kit should work with any platform that has the RXTX Serial Communications API, however only Win32 and Linux were tested.

Note: The Native Drivers are the recommended means of communicating with 1-Wire adapters on Win32 platforms, so the RXTX support is not fully enabled. When using the OneWireViewer (or other 1-Wire apps) to query the list of available adapters, the RXTX driver will not be shown as an option. To access the RXTX driver, simply provide the adapter name "DS9097U" (not "{DS9097U}"). From the command-line, you can add the following switch:

-Donewire.adapter.default=DS9097U -Donewire.port.default=COM1

Linux and other Unixes

This build of the 1-Wire API includes pre-built binaries for a variety of different Unixes (Linux 32/x64/ia64, sparc32/64, Mac OS X), however it is recommended that you build your own binary for your specific platform if possible. This ensures that you've linked against the appropriate libraries for your system and you've got the best optimizations possible on your platform. More information about RXTX can be found here:

http://www.rxtx.org/

This release of the 1-Wire API was tested against version 2.1-7r2 of rxtx, which can be downloaded from here:

ftp://ftp.qbang.org/pub/rxtx/rxtx-2.1-7r2.zip

After downloading the file, follow these steps to build and install:

unzip rxtx-2.1-7r2.zip
cd rxtx-2.1-7r2
./configure && make && sudo make install


If all goes well, you will have a librxtxSerial.so link in your <jre>/lib/i386 folder and a RXTXcomm.jar in your <jre>/lib/ext folder. If all doesn’t go well, the 1-Wire discussion forum or the RXTX mailing list might be able to help.

Note that this is a different serial communications API than what was recommended in previous versions of the 1-Wire API. Previously, the Sun javax.comm API was used, and the two are not compatible. Sun’s javax.comm uses classes in the javax.comm.* namespace while RXTX 2.1 uses classes in the gnu.io.* namespace. So, if you have a previous installation of the 1-Wire API which uses javax.comm, you will still need to install RXTX 2.1.

RXTX 2.1 is distributed under the terms of LGPL license. Please see "rxtxLicense.txt" in the "rxtx" subfolder for more information.

The DS9097U adapter class in this kit should work with any platform that has the RXTX Serial Communications API, however only Win32 and Linux were tested.

Note: for better serial performance (but more CPU utilization) use the ‘setserial’ utility to set the latency of the port to low.

Here are the command we used in Linux:

setserial /dev/ttyS0 autoconfig
setserial /dev/ttyS0 uart 16450
setserial /dev/ttyS0 uart 16550
setserial /dev/ttyS0 low_latency


To return your port to it's default state:

setserial /dev/ttyS0 autoconfig

Types of Containers

Memory

The base class of all containers ‘OneWireContainer’ has a method called ‘getMemoryBanks()’ that returns an enumeration of memory bank instances. A memory bank is a section of memory on a 1-Wire device that has specific properties. For example the 1-Wire Network Address of a device is a read-only bank of 8 bytes. This technique is used to get a handle on the diverse types of memory that comprise 1-Wire devices. There are three interfaces that the memory bank may implement. These interfaces are hierarchical:

MemoryBank – basic read/write (getSize(), read(), write()..)
PagedMemoryBank (extends MemoryBank) – paged read/write with packets (getNumberPages(), readPage(), writePagePacket()..)
OTPMemoryBank (extents PagedMemoryBank) – One-Time-Programmable, usually EPROM (canRedirectPage(), lockPage())

See the examples ‘OWDump’ and ‘OWMemUtil’ for applications that utilize memory banks.

Any 1-Wire devices that contain memory can also use the 1-Wire File system. The following classes in the com.dalsemi.onewire.utils package can be used just like the Java equivalient:

OWFile – Like java.io.File
OWFileInputStream – Like java.io.FileInputStream
OWFileOutputSTream – Like java.io.FileInputStream
OWFileDescriptor – Like java.io.FileDescriptor

See the example ‘OWFish’ to demonstrate using the 1-Wire file system. The specification for the 1-Wire file system can be found in Application Note 114:
http://pdfserv.maxim-ic.com/arpdf/AppNotes/app114.pdf

Sensor

A 1-Wire Sensor is a device that can make a reading or change the state of something physical (such as a DS2406 switch). Typically the operations of 1-Wire Sensors is memory mapped so writing to a particular location causes the state to change. To accommodate this type of architecture and reduce the number of 1-Wire operations that need to take place, a ‘read-modify-write’ technique is used. Each Sensor interface is derived from a super-interface (com.dalsemi.onewire.container.OneWireSensor) that contain just two methods: readDevice(), writeDevice(). The read returns a byte array and the write takes a byte array. The byte array is the state of the device. The interfaces that extend this interface have ‘get’ and ‘set’ methods that manipulate the byte array. So a OneWireSensor operation is:

1. readDevice()
2. ‘get’ and ‘set’ methods
3. writeDevice()

The following is a list of the interfaces and a brief description. Note that the container list above indicates the interfaces used.

ADContainer - A/D sensor
ClockContainer – clock
SwitchContainer – switch
TemperatureContainer – temperature reading sensor
PotentiometerContainer - digital potentiometer device
HumidityContainer – humidity reading sensor


Overdrive Speed with 1-Wire Containers

Most 1-Wire devices support Overdrive speed, a 1-Wire Net communication speed that supports up to 142 k-bits/second of 1-Wire data. The method getMaxSpeed(), defined in OneWireContainer, will tell you if you're device can support Overdrive speed.

Communicating with a device in Overdrive speed just requires that you call the setSpeed(int,boolean), defined in OneWireContainer. The boolean value indicates whether or not it is okay for the device to fall back to a slower speed if communication fails. The DSPortAdapter object also has a setSpeed(int) method, but it is not advisable to call this one directly. Instead, allowing the container itself to be the only entity who manipulates the DSPortAdapter's state, you can be assured that the two will not be out of sync.

Also, if you're in a situation where you have devices on the 1-Wire Net who support Overdrive and devices that don't, it's important to remember that regular speed communication will cause devices in Overdrive mode to revert to regular speed. This change of 1-Wire speed could potentially cause I/O errors on the devices that were in Overdrive the first time they are accesses after the speed change. The opposite situation (Overdrive communication on the same network with devices in regular speed) is harmless. Calling the OneWireContainer’s doSpeed() method will force a re-negotiation of the 1-Wire speed. However this can be a slow procedure on some platforms so it should not be called indiscriminately. The OneWireContainer’s implementation specific methods (clock methods, temperature methods, memory methods ...) will automatically call doSpeed() at appropriate times.

Dallas Semiconductor has selected the least restrictive license it could find to apply to the Java source code in this kit. It is based almost word for word on the Xfree86 license (http://www.xfree86.org/4.0/LICENSE1.html). It basically says you can do anything you want with this code. If you distribute the source then just leave the license blurb at the top of the source files. That’s it. See the license in the ‘COPYRIGHT’ file and at the top of all of the source files.