OW.NET Primer

OW.NET API Primer    1-Wire SDK Help

Communication with the 1-Wire network is through an ‘adapter’ (com.dalsemi.onewire.adapter.DSPortAdapter class).  Physically speaking, an adapter is a hardware device through which the 1-Wire master communicates to the network of 1-Wire devices (1-Wire network).  Many adapters exist for the different kinds of ports on a PC such as the serial, parallel, or USB ports.  Please see the OW.NET Adapter List for a comprehensive list of adapters available for the PC.  The software implementation of the adapter is DSPortAdapter().   The static class, ‘com.dalsemi.onewire.OneWireAccessProvider’ is used to get an adapter class instance. All of the adapters can be enumerated or a specifc (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

For .NET applications, the default 1-Wire Network (adapter on a specific port) is retrieved
through the OneWireAccessProvider method "getDefaultAdapter":

Dim adapter As com.dalsemi.onewire.adapter.DSPortAdapter
adapter = com.dalsemi.onewire.OneWireAccessProvider.getDefaultAdapter

This method actually retrieves the default 1-Wire Network from the Windows system
registry. More information on what these keys are, see White Paper 6: 1-Wire Drivers
Installation Guide for Windows:
http://www.maximintegrated.com/an1740

Alternatively, the programmer can also retrieve a specific adapter using
OneWireAccessProvider's "getAdapter" method. Here's an example that retrieves the
DS9490 adapter on port 1:

Dim adapter As com.dalsemi.onewire.adapter.DSPortAdapter
adapter = com.dalsemi.onewire.OneWireAccessProvider.getAdapter("{DS9490}", "USB1")

The current adapter list is (brackets required):
{DS9490}
{DS9097U}
{DS1410E}
{DS9097E}

Since the adapters being used currently in the .NET version of the 1-Wire API are through TMEX, they need the brackets. Also, the port numbers are a name/number combination.  The names can be USB, COM, or LPT. The numbers can be 0-15. Examples are:
USB1
COM1
LPT1

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.

The beginExclusive method is invoked on an adapter object to obtain a lock on the underlying physical adapter. Once the lock is owned by a particular adapter, no other adapter instance can invoke methods that result in communication with either the port adapter directly or the 1-Wire network it controls. Any attempt to do so results in a OneWireException being thrown. The lock applies to other processes as well as other threads within the same process. The lock can be freed by either of two mechanisms. Typically, the adapter instance that owns the lock will invoke endExclusive, voluntarily releasing the lock. Also, the lock will automatically be freed in the event that the owning process terminates without invoking endExclusive.

The boolean value passed to beginExclusive specifies whether the caller wishes to wait until the lock is free or return immediately regardless of the lock’s state. If block is false, beginExclusive will immediately return true in the event that the lock was successfully acquired and false otherwise. If block is true, beginExclusive will attempt to acquire the lock; if it is already owned by another adapter instance, beginExclusive blocks indefinitely until the lock has been freed and it can claim ownership. When block is true and beginExclusive returns normally (that is, non-abruptly), it will always return true.

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 (see family code list below). For example the following code fragment will search for devices with 0x10 family code. Note that ‘adapter’ is a working instance of DSPortAdapter.

Dim owd_enum As java.util.Enumeration
Dim owd As com.dalsemi.onewire.container.OneWireContainer

Try
' get exclusive use of 1-Wire network
adapter.beginExclusive(True)
' clear any previous search restrictions
adapter.setSearchAllDevices()
adapter.targetAllFamilies()
adapter.setSpeed(com.dalsemi.onewire.adapter.DSPortAdapter.SPEED_REGULAR)
' enumerate through all the 1-Wire devices found (with Java-style enumeration)
owd_enum = adapter.getAllDeviceContainers
ResultsTextBox.AppendText(Environment.NewLine() & "1-Wire List:" &
   Environment.NewLine())
' enumerate through all the 1-Wire devices found (with Java-style enumeration)
'
While owd_enum.hasMoreElements()
' retrieve OneWireContainer
owd = owd_enum.nextElement()
' do something with the 1-Wire device
ResultsTextBox.AppendText(Environment.NewLine())
ResultsTextBox.AppendText("Address = " & owd.getAddressAsString &
   Environment.NewLine())
ResultsTextBox.AppendText("Description = " & owd.getDescription &
   Environment.NewLine())
End While
' end exclusive use of 1-Wire net adapter
adapter.endExclusive()

Catch ex As Exception
ResultsTextBox.AppendText(Environment.NewLine() & Environment.NewLine() &
   "Error: " & ex.ToString)
End Try

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

For a list of the containers (and family codes) provided in this API, see Application Note 155:  "1-Wire Software Resource Guide Device Description" (specifically, Table 1).

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 example ‘MemoryBanks’ for an example application that utilizes 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 ‘FileApp’ to demonstrate using the 1-Wire file system. The specification for the 1-Wire file system can be found in Application Note 114:
http://www.maximintegrated.com/an114

Sensor

A 1-Wire Sensor is a device that can make a reading or change the state of something physical (such as a DS2413 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 (or for .NET users, an array of SBytes). 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 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.

License
Maxim Integrated 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.