The full kit can be downloaded from here: ftp://ftp.dalsemi.com/pub/auto_id/public/owapi_1.00.tgz 1-Wire(R) API for Java(TM) Version 1.00 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://pdfserv.maxim-ic.com/arpdf/DS9097U.pdf 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.ibutton.com/TINI/book.html What's New in 1.00 The following list highlights the most significant additions to the 1- Wire API since 0.01. 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. OpenCard support classes for Java iButton The classes in package com.dalsemi.onewire.jib provide a means for applications using the OpenCard API (www.opencard.org) to communicate with Java iButtons. OpenCard provides an API to abstract communication with SmartCards and JavaCards like the Java Powered iButton. These classes are not required for Java Powered iButton development. See the examples distributed with the iB-IDE for examples on how to use these classes. 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. Installation 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.11 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.ibutton.com/software/tmex/index.html The latest version 3.21X of the 1-Wire native drivers automatically copies the JNI connection layer to Java 'ibtmjava.dll' into \system (or \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." In this subfolder you will find 2 files of interest. "rxtxSerial.dll" and "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. This version of RXTX 2.1 (2.1-7pre16) has intermittent problems when run in a version of Java older than 1.4.1. 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. Linux and other Unixes Build and 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. 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-6 of rxtx, which can be downloaded from here: http://www.frii.com/~jarvi/rxtx/download/rxtx-2.1-6.tar.gz After downloading the file, follow these steps to build and install: tar -xzf rxtx-2.1-6.tar.gz cd rxtx-2.1-6 ./configure && make && make install If all goes well, you will have a librxtxSerial.so link in your /lib/i386 folder and a RXTXcomm.jar in your /lib/ext folder. If all doesn't go well, the 1-Wire mailing list 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 Examples The following is a list of the provided examples in the /examples directory of this kit and a brief explanation. A more detailed explanation will be found in the individual directories under 'examples' in this kit. Each example has the following support files and directories: * EXAMPLE_NAME.class - compiled example * readme.txt - detailed information on the example * src - sub-directory containing the example source * tini - sub-directory containing a TINI platform 1.02 or later build of the example * build.xml - ant build file for the desktop ('ant build') or TINI ('ant buildTINI') or running the desktop binary ('ant run'). * run.bat - batch file to run the example using a fixed classpath pointing to the OneWireAPI.jar file in the /lib directory. * build.bat - batch file to rebuild the example using a fixed classpath pointing to the OneWireAPI.jar file in the /lib directory. * tini_build.bat - batch file to rebuild the example for the TINI platform. Note the environment TINI_HOME must be set BEFORE running this batch file. ADContainerDemo Find the first 1-Wire device that implement the ADContainer interface (A/D). It has a simple text/menu that allows most of the A/D features to be explored. DemoSHAEE Utility to exercise the DS1961S/DS2432 EEPROM 1- Wire device with SHA engine. FindiButtons- Find all 1-Wire devices (and iButtons) on all Console available 1-Wire adapters. Note that this application is almost identical to the example of the same name in previous 1-Wire kits. Humidity Find and read all 1-Wire devices that implement the HumidityContainer interface and display the current humidity. ListOW Minimal 1-Wire application to list the devices found on the default 1-Wire Network. OneWireViewer GUI application (similar to iButtonViewer) which supports all parts supported by the 1- Wire API and exercises most of the features of each part. OWC16Test Java iButton demo. It has a simple text/menu driven interface that allows applets to be loaded and tested. OWDump Dump the memory contents of all 1-Wire devices (and iButtons) that contain Memory Banks (see 1- Wire Container Documentation for a description of Memory Banks) on the default 1-Wire Network. OWFish 1-Wire File System Shell. Read, write, format and display the file system on a 1-Wire memory device. See the com.dalsemi.onewire.utils.OWFile* classes. OWMemUtil Text/menu driven utility to read and write the memory of virtually all 1-Wire devices and iButtons (see 1-Wire Container Documentation for a description of Memory Banks). OWNetWatch Monitor the arrival and departure of all 1-Wire devices on a complex network utilizing the DS2409 Coupler to create branches. Also starts a thread to read the temperature of any DS1920/DS1820 devices found on the network. OWWatch Monitor the arrival and departure of all 1-Wire devices on a simple 1-Wire Network. This application does not implement sub-branches but has been optimized and is very fast. ReadClock Find and read all 1-Wire devices that implement the ClockContainer interface. ReadDigPot Find and read all 1-Wire devices that implement the PotentiometerContainer interface. ReadSwitch Find and read all 1-Wire devices that implement the SwitchContainer interface. ReadTemp Find and read all 1-Wire devices that implement the TemperatureContainer interface. SetDefault Set the default 1-Wire Network by selecting the adapter/port combination. This will write a 'onewire.properties' file in a platform specific location. RemoteAuth DS1963S/DS1961S (SHA iButton) demo showing how to authenticate a user token over a network. SHADebitDemo DS1963S/DS1961S (SHA iButton) demo that consists of three applications. Two applications to set up a 'co-processor' and 'roving' device and then a 'debit' application to demo a secure monetary transaction. StartNetAdapter A simple 'launcher' for the host component of Host the new network DSPortAdapter. SwitchDemo Get the status and set the latches on any 1- Wire switch. TagViewer Java Swing application that dynamically displays and reads XML tagged 1-Wire sensors, actuators, and branches TagCreator Java Swing application creates XML 1-Wire tags for sensors, actuators, and branches Temperature- Text/menu driven application to read any 1-Wire ContainerDemo device that implements the TemperatureContainer interface. Thermochron DS1921 temperature gathering demo consisting of two applications. One application 'missions' a DS1921 to collect data and the other 'dumps' the mission data. 1-Wire API Primer Communication with the 1-Wire Network is through an 'adapter' (com.dalsemi.onewire.adapter.DSPortAdapter class). The static class, 'com.dalsemi.onewire.OneWireAccessProvider' is used to get an adapter class instance. All of the adapters can be enumerated or a particular or the default adapter can be retrieved (enumerateAllAdapters(), getAdapter(), and getDefaultAdapter()). Each adapter may support multiple 'ports' so a 1-Wire Network consists of an adapter/port combination. Here is a brief list of the operations needed to access and use the 1-Wire network 1. Get an adapter instance 2. Get exclusive use of the 1-Wire network 3. Find a 1-Wire device 4. Perform operations through the device's container 5. End exclusive use of the 1-wire network 6. Free the port when ending application Note that '1.' and '6.' are performed only once at the beginning and end of the application. '2.' through '5.' comprise the bulk of the 1-Wire operations and are performed multiple times during the execution of an application. Default 1-Wire Network The default 1-Wire Network is specified with two properties: onewire.adapter.default - the adapter name, for example DS9097U onewire.port.default - the port name, for example COM1 The values for properties are retrieved in the following search order: 1) System.properties (use -D option on java command line) 2) onewire.properties file in current directory 3) onewire.properties file /lib/ (Desktop) or /etc/ (TINI) If these properties cannot be found then a platform dependent "Smart default" is used. For Win32 native it is the TMEX default 1-Wire Net, for TINI it is TINIExternalAdapter/serial1, and for all other platforms it is DS9097U/(first serial communications port). See the example application 'SetDefault' to set the default 1-Wire Network adapter/port. To add other adapters to the list of available 1-Wire adapters, you'll need to register the adapter class with the following property: onewire.register.adapterX - the class name of the adapter In the above property, X is any number from 0 to 15. For example, to add support for the DS9097E adapter, you would use the following property: onewire.register.adapter0=com.dalsemi.onewire.adapter.LSerialAdapter Access to 1-Wire Network To allow for multi-thread access to the 1-Wire network, a pair of methods are provided in the adapter class to give exclusive access. They are 'beginExclusive()' and 'endExclusive()'. It is recommended that this pair wrap any access to the 1-Wire network. These methods do not maintain a stack of any sort, so it is innappropriate to nest calls. All successive calls to 'beginExclusive()' will succeed if made by the same thread and the thread will still maintain exclusive access after each call. All successive calls to 'endExclusive()' will be pointless after the first since the thread will have already given up exclusive access. Finding 1-Wire devices (and iButtons) Each 1-Wire device type is identified with a 1 byte 'family code'. This family code is used to provide the appropriate container and can also be used to limit the search of the 1-Wire Network to one or more device types. For example the following code fragment will search for devices with 0x10 family code. Note that 'adapter' is a working instance of DSPortAdapter. // clear any previous search restrictions adapter.setSearchAllDevices(); adapter.targetAllFamilies(); adapter.setSpeed(adapter.SPEED_REGULAR); // target 0x10 family devices adapter.targetFamily(0x10); // enumerate through all the 1-Wire devices found for(Enumeration owd_enum = adapter.getAllDeviceContainers(); owd_enum.hasMoreElements(); ) { OneWireContainer owd = (OneWireContainer)owd_enum.nextElement(); // do something with the container } Note that there are other search methods (findFirstDevice() and findNextDevice()) that do not automatically create a container and may be quicker if speed is essential. Also see these other methods for search options: getAddress(), getDeviceContainer(), excludeFamily(), setSearchOnlyAlarmDevices(), and setNoResetSearch(). 1-Wire Containers As described in the 'Finding 1-Wire Devices' section, each type of 1- Wire device has a 'family code' that indicates its functionality. The adapter uses this family code to provide a 'container' to interface to it. The container (com.dalsemi.onewire.container.OneWireContainer) is then used by the application to manipulate the device. Each container class has the following format OneWireContainerXX where XX is the 'family code'. For example, the DS1920 has a family code of 0x10 so the container to use it is OneWireContainer10. The adapter will automatically provide the correct container. If the family code is unknown then the adapter will provide the super-class generic container. Here is a list of the containers provided in this kit. Device Fa Description Interfaces MemoryBanks Name mi ly DS1990A 01 1-Wire Address DS2401 only DS1991 02 Secure memory DS1425 device DS1994 04 4K NVRAM memory ClockContainer MemoryBank DS2404 and clock, PagedMemoryBank timer, alarms DS2405 05 Single addressable switch DS1993 06 4K NVRAM memory MemoryBank PagedMemoryBank DS1992 08 1K NVRAM memory MemoryBank PagedMemoryBank DS1982 09 1K EPROM memory MemoryBank DS2502 PagedMemoryBankO TPMemoryBank DS1995 0A 16K NVRAM MemoryBank memory PagedMemoryBank DS1985 0B 16K EPROM MemoryBank DS2505 memory PagedMemoryBank OTPMemoryBank DS1996 0C 64K NVRAM MemoryBank memory PagedMemoryBank DS1986 0F 64K EPROM MemoryBank DS2506 memory PagedMemoryBankO TPMMemoryBank DS1920 10 Temperature and Temperature- DS1820 alarm trips Container DS18S20 DS2406 12 1K EPROM SwitchContainer MemoryBank DS2407 memory, dual PagedMemoryBankO switch TPMemoryBank DS1983 13 4K EPROM memory MemoryBank DS2503 PagedMemoryBank OTPMMemoryBank DS1971 14 256bit EEPROM MemoryBank memory and OTP PagedMemoryBankO register TPMMemoryBank DS1954 16 Java Powered Cryptographic iButton DS1963S 18 4K NVRAM memory MemoryBank and SHA-1 PagedMemoryBank engine DS1963L 1A 4K NVRAM memory MemoryBank with write PagedMemoryBank cycle counters DS2423 1D 4K NVRAM memory MemoryBank with external PagedMemoryBank counters DS2409 1F dual switch, SwitchContainer coupler DS2450 20 quad A/D ADContainer MemoryBank PagedMemoryBank DS1921 21 Thermochron Temperature- MemoryBank temperature Container PagedMemoryBank logger ClockContainer DS1822 22 Econo Temperature- temperature Container DS1973 23 4K EEPROM MemoryBank memory PagedMemoryBank DS1904 24 Real-time-clock ClockContainer DS2415 DS2438 26 Temperature, ClockContainer A/D ADContainer Temperature- Container Humidity- Container DS2417 27 Real-time-clock ClockContainer with interrupt DS18B20 28 Adjustable Temperature- resolution Container temperature DS2890 2C single channel Potentiometer- digital pot Container DS2760 30 Temperature, ADContainer current, A/D Temperature- Container DS1961S 33 1K EEPROM MemoryBank DS2432 memory with SHA- PagedMemoryBank 1 engine DS1977 39 64K EEPROM Password- MemoryBank memory with Container PagedMemoryBank password correction DS1922 41 8k Temperature ClockContainer MemoryBank DS2422 and Humidity ADContainer PagedMemoryBank logger with RTC Temperature- and Password Container Protection Humidity- Container Mission- Container Password- Container 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 Other The most celebrated 'other' device Dallas Semiconductor has is the Java Powered Cryptographic iButton. This is a microprocessor in an iButton package that has a Java Virtual Machine that can run Java applets. These applets typically perform highly secure cryptographic operations. See this web page for more information: http://www.ibutton.com/ibuttons/java.html 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. Documentation See the 'docs' directory for a complete javadoc of the com.dalsemi.onewire package. The examples are not javadoc'ed but individual example directories may contain documentation. All of the Java source in this kit is provided so if the documentation is not clear or is non-existent, look in the source. Dallas Semiconductor's 1-Wire device data sheets can be found by part number here: http://dbserv.maxim-ic.com/1-Wire.cfm TINI TINI is a micro-controller with a Java Virtual Machine. See this page for more information. http://www.ibutton.com/TINI/index.html Since its memory resources are limited, only the containers and necessary classes needed for the application are transferred to TINI. The utility 'BuildDependency' is included in the version 1.02 TINI kit to build only the necessary files. The dependency jar used for building 1-Wire applications is provided in /lib/owapi_dependencies_TINI_001.jar. The source to this jar is in /src/owapi_dependencies_TINI_001src.jar. The file that lists the dependencies is in /lib/owapi_dep.txt. See the README's in the example directories and the batch file 'tini_build.bat' for further build information. Detailed documentation on the 'BuildDependency' utility can be found in the TINI distribution. The documentation of the 1-Wire API is the same on the Desktop or TINI. License 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. Long Lines The DS9097U (based on the DS2480B) serial adapter is an excellent 1-Wire master for short and long lines. The DS2480B inside the adapter has line characteristic settings that can be changed through Java by selecting SPEED_REGULAR and SPEED_FLEX 1-Wire speed. The SPEED_FLEX mode selects line settings that work better for long 1-Wire lines. The settings are: SPEED_REGULAR - Slew rate = 1.37V/us, tlow = 10us, tDSO = 8us SPEED_FLEX - Slew rate = 0.83V/us, tlow = 12us, tDSO = 10us These settings were selected by taking the recommendations for a 200 meter and 300 meter 1-Wire cable in Application Note 148: http://pdfserv.maxim-ic.com/arpdf/AppNotes/app148.pdf The datasheet for the DS2480B can be found here: http://pdfserv.maxim-ic.com/arpdf/DS2480B.pdf