The 1-Wire API for JavaTM


This page provides more information about the 1-Wire API for Java.


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:

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).

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(boolean) 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(), 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 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
PagedMemoryBank
OTPMemoryBank
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
PagedMemoryBank
OTPMemoryBank
DS1920
DS1820
DS18S20
10 Temperature and alarm trips TemperatureContainer
DS2406
DS2407
12 1K EPROM memory, dual switch SwitchContainer MemoryBank
PagedMemoryBank
OTPMemoryBank
DS1983
DS2503
13 4K EPROM memory MemoryBank
PagedMemoryBank
OTPMemoryBank
DS1971 14 265 bit EEPROM memory and OTP register MemoryBank
PagedMemoryBank
OTPMemoryBank
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 Thermocron temperature logger TemperatureContainer
ClockContainer
MemoryBank
PagedMemoryBank
DS1973 23 4K EEPROM memory MemoryBank
PagedMemoryBank
DS2438 26 Temperature, A/D ClockContainer
ADContainer
TemperatureContainer
DS18B20 28 Adjustable resolution temperature TemperatureContainer
DS2890 2C Single channel digital potentiometer PotentiometerContainer
DS2760 30 Temperature, current, A/D ADContainer
TemperatureContainer
DS1961S
DS2432
33 1K EEPROM memory with SHA-1 Engine MemoryBank
PagedMemoryBank

Types of Containers