|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||
See:
Description
The full kit can be downloaded from here:
1-Wire(R) API for Java(TM)
Version 1.00Alpha
Contents
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 iButto ns(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 usi ng Java Communications API. The DS9097U serial adapter information can be found on the Dallas Semiconductor web site:
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 fo r a free download in PDF format at the following URL:
http://www.ibutton.com/TINI/book.html
What's New in 1.00 Alpha
The OneWireAPI for Java version 1.00 Alpha adds a lot of new features compared to the 0.01 release. The list that follows highlights the most significant additions.
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 t he 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 T ransaction 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 f ile 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. This is of particular importance to the new DS1996*4 and DS1996*2 devices that contain multiple 1-Wire chips inside a single iButton enclosure. See Applicatio
n Note 114 for the 1-Wire File Structure details:
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
- OneWireContainer22 for the DS1822, 1-Wire Digital Thermometer.
- OneWireContainer24 for the DS2415/DS1904, 1-Wire Real-Time Clock.
- 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 th e ‘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.02 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 detail s 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): Java Communications API with the DS9097U and native drivers.
Java Communications API/DS9097U
Install Java Communications API from Sun. Note that this API does NOT come in the JDK or JRE, it must be installed separately. It can be found here:
The DS9097U adapter class in this kit should work with any platform that has the Java Communications API, however only Win32, Linux and Solaris were tested.
Native
The native drivers for Win32 are the iButton-TMEX Runtime Environment 32-bit drivers. Install the standard drivers from here:
The latest version 3.20 of the 1-Wire native drivers automatically copies the JNI connection layer to Java ‘ibtmjava.dll’ into <windows>\system (or <windows>\system32 for NT).
By default the 1-Wire port will be the one selected during the installation of the iButton-TMEX Runtime Environment and changed with the ‘Default 1-Wire Net’ application.
Linux
Install Java Communications API from Sun. Note that this API does NOT come in the JDK or JRE, it must be installed separately. Retrieve the ‘Solaris’ version from here:
Only the ‘comm.jar’ file will be used from this kit. The ‘native’ part of the Java Communications API for the Linux platform is provided by ‘rxtx’. Info on rxtx can be found here: http://www.rxtx.org
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
Solaris
Install Java Communications API from Sun. Note that this API does NOT come in the JDK or JRE, it must be installed separately. Retrieve the ‘Solaris’ version from here:
The driver has a default mode on Solaris that forces it into single bit at a time mode. This was done due to a bug in the Java Communications API on Solaris. I believe this is now fixed in the current revision so the following setting in the ‘onewire.properties’ file will turn it off:
onewire.serial.forcebitsonly=false
Also the DS2480 (chip in the DS9097U adapter) has the following valid baud rates: 9600, 19200, 57600, 115200. Of these baud rates, the fastest baud rate observed on some Solaris machines is 19200. The maximum baud rate the driver will try is specified by the following flag in the ‘onewire.prope rties’ file:
onewire.serial.maxbaud=19200
See the ‘Default 1-Wire Network’ section for details on the location of the ‘onewire.properties’ file.
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:
|
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-Console |
Find all 1-Wire devices (and iButtons) on all 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. |
|
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. |
|
SHADebitDemo |
DS1963S (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. |
|
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-ContainerDemo |
Text/menu driven application to read any 1-Wire 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 <javahome>/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 iButton-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.
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.
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(), setSearchOnlyAlarmDevic es(), 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 th e 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 Name |
Family |
Description
|
Interfaces |
MemoryBanks |
|
DS1990A DS2401 |
01 |
1-Wire Address only
|
||
|
DS1991 DS1425 |
02 |
Secure memory device
|
||
|
DS1994 DS2404 |
04 |
4K NVRAM memory and clock, timer, alarms |
ClockContainer |
MemoryBank PagedMemoryBank |
|
DS2405 |
05 |
Single addressable switch |
||
|
DS1993 |
06 |
4K NVRAM memory |
MemoryBank PagedMemoryBank |
|
|
DS1992 |
08 |
1K NVRAM memory |
MemoryBank PagedMemoryBank |
|
|
DS1982 DS2502 |
09 |
1K EPROM memory |
MemoryBank PagedMemoryBankOTPMemoryBank |
|
|
DS1995 |
0A |
16K NVRAM memory |
MemoryBank PagedMemoryBank |
|
|
DS1985 DS2505 |
0B |
16K EPROM memory |
MemoryBank PagedMemoryBank OTPMemoryBank |
|
|
DS1996 |
0C |
64K NVRAM memory |
MemoryBank PagedMemoryBank |
|
|
DS1986 DS2506 |
0F |
64K EPROM memory |
MemoryBank PagedMemoryBankOTPMMemoryBank |
|
|
DS1920 DS1820 DS18S20 |
10 |
Temperature and alarm trips
|
Temperature-Container |
|
|
DS2406 DS2407 |
12 |
1K EPROM memory, dual switch |
SwitchContainer |
MemoryBank PagedMemoryBankOTPMemoryBank |
|
DS1983 DS2503 |
13 |
4K EPROM memory |
MemoryBank PagedMemoryBank OTPMMemoryBank |
|
|
DS1971 |
14 |
256bit EEPROM memory and OTP register |
MemoryBank PagedMemoryBankOTPMMemoryBank |
|
|
DS1954 |
16 |
Java Powered Cryptographic iButton |
||
|
DS1963S |
18 |
4K NVRAM memory and SHA-1 engine |
MemoryBank PagedMemoryBank
|
|
|
DS1963L |
1A |
4K NVRAM memory with write cycle counters |
MemoryBank PagedMemoryBank |
|
|
DS2423 |
1D |
4K NVRAM memory with external counters |
MemoryBank PagedMemoryBank |
|
|
DS2409 |
1F |
dual switch, coupler |
SwitchContainer |
|
|
DS2450 |
20 |
quad A/D |
ADContainer |
MemoryBank PagedMemoryBank |
|
DS1921 |
21 |
Thermochron temperature logger |
Temperature-Container ClockContainer |
MemoryBank PagedMemoryBank |
|
DS1822 |
22 |
Econo temperature |
Temperature-Container |
|
|
DS1973 |
23 |
4K EEPROM memory |
MemoryBank PagedMemoryBank |
|
|
DS1904 DS2415 |
24 |
Real-time-clock |
ClockContainer |
|
|
DS2438 |
26 |
Temperature, A/D |
ClockContainer ADContainer Temperature-Container Humidity-Container |
|
|
DS2417 |
27 |
Real-time-clock with interrupt |
ClockContainer |
|
|
DS18B20 |
28 |
Adjustable resolution temperature |
Temperature-Container |
|
|
DS2890 |
2C |
single channel digital pot |
Potentiometer-Container |
|
|
DS2760 |
30 |
Temperature, current, A/D |
ADContainer Temperature-Container |
|
|
DS1961S DS2432 |
33 |
1K EEPROM memory with SHA-1 engine |
MemoryBank PagedMemoryBank |
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-on ly 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:
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 redu ce 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 set Speed(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 th e 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:
TINI
TINI is a micro-controller with a Java Virtual Machine. See this page for more information.
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 applicatio ns 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 informatio n. 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 se ttings 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 132:
The datasheet for the DS2480B can be found here:
|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||