OneWireViewer Tips and Tricks

Abstract

This document gives insight into the operation of the OneWireViewer, its way of displaying errors, and function-viewer-specific peculiarities. It also includes hints on how to test for a bad iButton battery and how to verify whether a mission was started successfully. The second part of the document relates to software installation, port configuration, adapter detection, and changing adapter types and ports. This document, together with application note 4373, "OneWireViewer and iButton® Quick Start Guide," and application note 3358, "OneWireViewer User's Guide," covers all situations that the typical user of 1-Wire and iButton devices is likely to encounter.

Introduction

The OneWireViewer software was originally written to demonstrate the usefulness and effectiveness of the 1-Wire® application program interface (API) for Java®. The software can exercise most iButton® and 1-Wire devices through USB and serial (COM) port adapters. It is available for 32-bit and 64-bit versions of Windows® 10, Windows 7, Windows Server 2008, Windows Vista®, and Windows XP® (service pack 2 and greater).

Thanks to the logger iButton devices, the OneWireViewer has gained popularity with researchers. A user interface that exercises a wide variety of iButton and 1-Wire devices is less intuitive for users focused on setting up a logger and retrieving data after a couple of weeks or months. When the OneWireViewer encounters an abnormal situation, such as logger end-of-life, finding and interpreting the error messages can be a challenge. This document explains how to find and understand error messages, and how to distinguish between a device error (e.g., caused by a drained battery) and an operator error (e.g., a software password not set). It also describes how to test for a bad battery before starting a mission, verify whether a mission was started successfully, and keep track of the logger's battery energy. The second half of this document addresses software aspects, including determining the version of the OneWireViewer and the underlying 1-Wire drivers, initial software installation, software upgrade and uninstallation, as well as changing communication ports and 1-Wire adapters.

Types of iButton and 1-Wire Devices

There are three types of 1-Wire products: iButton devices with a battery (loggers, NV SRAM memories, and real-time clocks (RTCs)), iButton devices without a battery (sensors, EPROMs, and EEPROMs), and 1-Wire chips (various functions with and without memory). All 1-Wire devices have a 64-bit ROM ID with built-in 8-bit cyclic redundancy check (CRC). The memory and/or control functions (everything besides the ROM function commands) can—but need not—implement schemes to safeguard data against communication errors. As Table 1 shows, the vast majority of 1-Wire devices have built-in CRC support. The presence or absence of safeguards, like CRCs, affects the OneWireViewer's abilities to detect and deal with abnormal situations when communicating with 1-Wire devices.

Table 1. 1-Wire Devices Supported by the OneWireViewer
Device Type Memory and/or Control Functions CRC Support
Yes* No
iButtons with Built-In Battery DS1921 series, DS1922 series, DS1923** (Loggers) DS1904 (RTC), DS1992, DS1993, DS1995, DS1996 (Memories)
iButtons without Battery DS1920 (8-bit CRC), DS1972, DS1973, DS1977, DS1982 (8-bit CRC), DS1985 DS1971
1-Wire Chips DS18S20 (8-bit CRC), DS1822 (8-bit CRC), DS18B20 (8-bit CRC), DS2406, DS2408, DS2422, DS2431, DS24B33, DS2438 (8-bit CRC), DS2450, DS2502 (8-bit CRC), DS2505, DS28E04, DS28EA00 (8-bit CRC), DS28EC20 DS2413, DS2415, DS2417, DS2430A, DS2762
*CRC-16 unless otherwise noted.
**Limited support: humidity readings are not compensated for temperature nor corrected for saturation drift.

Failure Mechanisms

Despite their solid appearance, iButton devices are not hermetically sealed. In particular, iButton loggers are often inadvertently exposed to moisture, from condensing water from the air, from rain when the device is underground, or from water when the device is submerged. As the temperature cycles, the iButton product can actually "pump in" moisture.

Once inside the iButton, water creates a conductive path that, over time, drains the battery. The chemical reaction between water and metal on the iButton circuit board leads to corrosion. This can cause a short between the data lid and GND, or break the path from the data lid to the chip and back to GND.

If connected to the 1-Wire bus,

  • A device with a broken communication path does not cause any errors. The OneWireViewer will simply not find it.
  • A device with an internal short does not generate errors either. It will make all other devices disappear from the OneWireViewer's device list.
  • An iButton with a drained battery but without a short between the data lid and GND will cause a variety of error messages in the OneWireViewer. The error message depends largely on the presence or absence of CRC support.

How Errors Are Displayed

The OneWireViewer has two ways of notifying users about errors. The most obvious place is at the bottom of the OneWireViewer's main window (Figure 1). The less obvious place is in the error log window (Figure 2).

Figure 1. The most obvious place for error messages is at the bottom of the main window.

Figure 1. The most obvious place for error messages is at the bottom of the main window.

Figure 2. The same error description in the error log file.

Figure 2. The same error description in the error log file.

To open the error log window, click on the View menu, and select Show Message Log, as indicated in Figure 1. Then, in the message log window, click on Level to verify that Information is check-marked.

Typical Error Messages

When accessing devices without CRC support, the OneWireViewer verifies the success of a write operation by reading back after write. If the data read back does not match the data written, the typical error message ends with Read back of scratchpad had incorrect data or Read back verify had incorrect data. The beginning of the message explains when the error (also referred to as the "exception") occurred.

There are two categories of devices with CRC support: those with password security (logger iButtons of the DS1922 series, DS1923, and DS1977) and those without password security (logger iButtons of the DS1921 series, other iButtons without battery, and 1-Wire chips). In either case, the OneWireViewer determines the success of a read or write operation by reading the CRC that the 1-Wire device generates during the memory/control function command flow.

For devices without password security, the error message ends with Invalid CRC16 read from device. The beginning of the message typically (but not always) explains when the error or exception occurred. For devices with password security, the error signaling is more complex. The message ending could be Invalid CRC16 read from device when accessing the unprotected scratchpad or Invalid CRC16 read from device. Password may be incorrect when accessing other memory areas or Invalid CRC16 read from device. Password may be incorrect or a sample may be in progress when accessing the data log memory of a logger iButton of the DS1922 series or the DS1923.

Function-Viewer-Specific Error Behavior

The OneWireViewer consists of several function-specific viewers: Thermochron, Mission, Temperature, Humidity, A to D, Switch, Clock, Memory, and File. Except for Switch, they all apply to logger iButton devices, which are very popular with nontechnical users. Table 2 summarizes how the various function viewers cope with error situations. The Thermochron and Mission viewers display error conditions only in the message log, a location that is easily missed by an inexperienced user.

Using password protection can have confusing consequences for the user. If passwords are enabled and the software password for a particular device is not set, the viewer cannot read the Device Configuration register. This results in both, the Real-Time Humidity and the A to D tab, being displayed. This is also the case for a DS2422 and a DS1922 or DS1923 with a drained battery.

Table 2. Function-Viewer-Specific Behavior
Function Error Signaling Special Notes
Thermochron® (DS1921) Message log only All tabs can be opened. No tab has data (the right half of the Status tab is empty) if the battery is drained.
Mission (DS1922, DS1923) Message log only Only the Status tab can be opened. The right half of the Status tab is empty if the software password is not set or the battery is drained. See the Distinguishing Between an Incorrect Password and a Drained Battery section to identify the reason.
Temperature Main window, message log The Temperature viewer always generates an error message if a mission is in progress.
A to D (Humidity) Main window only The A to D (Humidity) viewer always generates an error message if a mission is in progress.
Clock Main window only Non-CRC parts: an error is signaled only with Synchronize Clock to PC time and Halt Real-Time Clock.
A date in February 2106 is indicative for a drained battery.
CRC parts: an error is signaled when opening the Clock tab and when executing any of the functions.
Memory Main window, message log Non-CRC parts: an error is signaled only with Commit Changes.
CRC parts: an error is signaled when reading a memory bank; Commit Changes is not executable.
File Main window, message log The file viewer builds on Memory viewer functions. Therefore, error messages explained above apply only to the elementary functions Format Device (all parts) and Create Directory (non-CRC parts).

Distinguishing Between an Incorrect Password and a Drained Battery

Disregarding a bad electrical contact between 1-Wire adapter and iButton, an invalid CRC16 can result from the viewer not knowing the logger's password or a drained logger battery. The current OneWireViewer (version 3.15.50 and older) cannot distinguish between these two conditions. The only memory area that can be accessed without the password is the logger's 32-byte scratchpad. The test is simple: select the logger in question, open the Memory tab, and select memory bank Scratchpad with CRC and Password. In case of a good battery, the CRC16 is valid and the scratchpad contents are displayed in the viewer's main window. If the CRC is invalid, the battery is bad and no scratchpad contents is displayed. In case of a good battery, if desired, one can overwrite one or more of the scratchpad data bytes and then click on the Commit Changes button. The new data will be accepted and can be verified through refresh. This is the good news. The bad news is that one now needs to find the correct passwords. After the passwords are identified, they need to be entered through the Set Software Password function on the Password tab. After this step, refresh the mission results on the Mission tab and all functions of the logger iButton are accessible again. Note that the OneWireViewer does not store passwords in a file; they are lost when the program is closed.

Error Communicating with Adapter

The error situations discussed so far relate to the various function viewers and potentially malfunctioning iButton or 1-Wire devices. The connection between 1-Wire adapter and 1-Wire device was assumed to be reliable. An intermittent contact results in CRC errors or readback verification errors, as discussed above.

Another type of error can occur if the path between the computer's port and the 1-Wire adapter is not reliable. During normal communication this can result in the following error messages:

	ERROR: ThermochronViewer (<ROM ID>) Setup Error:
	com.dalsemi.onewire.OneWireException: 1-Wire Adapter communication exception

e.g., when downloading the data log of a DS1921, or

	ERROR: OneWireViewer (null) 1-Wire exception: 
	com.dalsemi.onewire.adapter.OneWireIOException: native TMEX error -12

while scanning the 1-Wire bus for new arrivals or departures. If such an error appears, check the cable between the computers port (COM or USB), make sure that all connections are solid, restart the OneWireViewer, and repeat the operation that was interrupted by the adapter error.

Testing for a Bad Battery Before Starting a Mission

Especially if an iButton logger has been deployed before, it is wise to check whether it is still functioning properly. As Table 2 shows, there are several function viewers to choose from. If the logger was stored as recommended, i.e., with the real-time clock halted, the Clock viewer is the first choice. Select the logger to be tested on the OneWireViewer's Device List, open the Clock tab, and wait for a few seconds. Then click the Synchronize Clock to PC Time button. If the battery is good, there will be no error message and the difference from PC Time is zero or 1 second. If there is an error message, check whether password protection is enabled for the logger (see the Distinguishing Between an Incorrect Password and a Drained Battery section).

Mission Start with Verification

Instructions on how to start a mission are found in application note 3358, "OneWireViewer User's Guide," sections Thermochron and Mission. For the Thermochron viewer, make sure that the rollover setting, sampling rate (in minutes between samples), and mission start delay (in minutes) are set according to your needs. Synchronizing the RTC does not make any difference if the clock has been tested before starting the mission. Setting the temperature-alarm limits may be useful; in any case, alarming situations can be identified when the temperature log is processed (see application note 3809, "Exporting DS192x Logger Data from the OneWireViewer into Excel®") after the mission is completed. The clock-alarm function does not affect the outcome of a mission and can therefore be disregarded.

For the Mission viewer, make sure that the rollover setting, sampling rate (in seconds between samples), and mission start delay (in minutes) are set according to your needs. Synchronizing the RTC does not make any difference if the clock has been tested before starting the mission. For the channels to be included in the log (always temperature, with the DS1923 also humidity if of interest), check Enable sampling and select the resolution. As before, setting alarm limits is optional.

After the mission parameters are selected, click OK and the mission should begin. If the start was successful, the lower right half of the Status tab (Thermochron and Mission viewers) is filled with data similar to the screen copy in application note 3358. The same is true for the other tabs. If these fields remain empty, the mission did not start. In that case, open the message log and scroll down to the bottom to see the error message.

How to Keep Track of the Battery Energy

The iButton logger data sheets include lifetime curves to estimate the logger lifetime depending on the temperature conditions during the mission. Due to the small memory and 8-bit resolution, the DS1921 series loggers have extremely low energy consumption. Not exceeding +50°C, they can continuously log for 5 years or more at one sample every 10 minutes. At higher temperatures, more attention is required. At +85°C, the battery lifetime is reduced to approximately 6 months, regardless of the sampling rate.

The DS1922 series of loggers and the DS1923 have a higher energy consumption, which depends on the temperature, sampling rate, and temperature resolution. A special calculator has been developed to gauge the remaining battery energy (see application note 3761, "DS1922/DS1923 Battery Gas Gauge"). Note that the calculator is based on worst-case conditions. There may still be life in the battery even if, according to the calculator, its energy reserves are exhausted. For a critical mission, do not count on "hidden reserves."

All iButton loggers have a 24-bit nonresettable Total (Device) Samples counter, which increments whenever a measurement takes place. This counter should not be mistaken for a battery gas gauge. According to the lifetime curves in the data sheet, when used at temperatures of +50°C or lower, the DS1921G can last for 3.8 years when sampling every minute (= 2 million samples), or 5.3 years when sampling every 10 minutes (= 278,000 samples), or 5.5 years when sampling every hour (= 48,000 samples). As these numbers illustrate, the total samples count is only useful for estimating the remaining battery energy when the entire mission history is also known.

How to Identify the Installed OneWireViewer's Version

To identify the viewer's version, start the viewer, open the Help menu and click on About. This opens a new window that displays the version of the OneWireAPI (the underlying API that the OneWireViewer calls on to read or write to 1-Wire devices), the OneWireViewer itself, and its function viewers.

How to Identify the Installed 1-Wire Driver Version

The 1-Wire drivers are the software that establishes communication with the 1-Wire adapter. The driver version information is accessible through the Control Panel.

For Windows 10, type Control Panel in the search bar and press enter (Figure 3). For Windows 7 and older, click on Start, and then click on Control Panel.

Figure 3. Accessing the Control Panel.

Figure 3. Accessing the Control Panel.

A new window opens containing a list of computer settings. In the section Programs, click on Uninstall a program.

Typically, the installed programs are sorted by name. Search for OneWireDrivers (Figure 4).The driver version is part of the program name. A code x64 at the end of the program name indicates that the 64-bit version is installed. With the 32-bit version, the code field is either missing or x86.

Figure 4. Identifying the driver version.

Figure 4. Identifying the driver version.

Initial Installation Pitfalls

The OneWireViewer is available for different Windows operating systems: Windows 10, Windows 7, Windows Server 2008, Windows Vista, and Windows XP. The name of the operating system is displayed during the startup phase after the computer is switched on.

Each of these operating systems exists as a 32-bit version and as a 64-bit version. The OneWireViewer requires Java version 6 or higher to run. Many PCs, but not all, have Java software installed at the factory.

To ensure that the initial installation is successful,

  • Identify whether your PC is configured as a 32-bit or 64-bit system. Test for Java and Java installation/upgrade.
  • Download and install the correct version of the OneWireViewer and 1-Wire drivers.

Identifying the System

To find out whether your PC is configured as a 32-bit or 64-bit system, perform the following steps:

  1. Open the command prompt window:
    Windows 10, Windows 7, Windows Server 2008, Windows Vista start type cmd in the search box and then press Enter.
    Windows XP start click on Run type cmd click OK.
  2. Obtain the system information:
    In the command prompt window, type systeminfo and press enter. After the entire system information is printed to the screen, scroll to the top of the window. Now look for the line that begins with System type. The string X86-based PC indicates a 32-bit system. For a 64-bit system the string is X64-based PC. Note what your system is and close the window.

Testing for Java and Java Installation/Upgrade

Java software is available as 32-bit and as 64-bit versions. If Java is already installed, you can identify the version in the same way as the version of the 1-Wire drivers (see Figure 4 and look for Java).


Alternative Method to Check the Java Version Installed


  1. Open the command prompt window:
    Windows 10, Windows 7, Windows Server 2008, Windows Vista
    start type cmd in the search box and then press Enter.
  2. Obtain the Java version. In the command prompt window type, java -version and press enter. The Java version is printed on the screen. If Java is not installed already, the command should fail or not display any information.

Figure 5. Display installed Java version.

Figure 5. Display installed Java version.

If Java is not installed or your version is older than Version 6, download Java from www.oracle.com, https://adoptopenjdk.net, or any other preferred Java distributor. Next run (i.e., open, double-click) the downloaded file and follow the instructions on the screen.

Downloading and Installing the OneWireViewer

Refer to Application Note 4373: OneWireViewer and iButton Quick Start Guide, Steps 2 and 3. At this point, you must download the version of 1-Wire Drivers that matches your operating system type (32-bit or 64-bit). In Step 3 of the Quick Start Guide, the final window of the driver installation has a Finish button that, when clicked, completes the installation. If you are using a USB to 1-Wire adapter, also execute Step 4 of application note 4373. After that, continue with Running the OneWireViewer for the first time.

Running the OneWireViewer for the First Time

Windows 10, Windows 7, Windows Server 2008, Windows Vista


Click on the Start button, and then put the mouse cursor on All Programs. Within seconds, all installed programs are listed. Click on the 1-Wire Drivers folder. When the folder opens (see Figure 6), move the cursor to OneWireViewer.jar and click.

Initial start of the OneWireViewer

Figure 6. Initial start of the OneWireViewer.

When the OneWireViewer is run for the very first time, the onewireviewer.properties file does not exist. This launches the 1-Wire API for Java Setup Wizard. The initial screen (see Figures 7 and 8) asks for the type of 1-Wire port adapter and the communication port. Verify that the 1-Wire adapter, such as a USB or COM port adapter, is plugged into a functioning port and note the port's number, such as USB1 or COM1.

Figure 7.Java Setup Wizard

Figure 7. Java Setup Wizard, 1-Wire Port Selection showing the USB port selection.

Java Setup Wizard

Figure 8. Java Setup Wizard, 1-Wire Port Selection showing the COM port selection.

Click the correct tab indicating the adapter of choice. For the USB adapter, click the {DS9490} tab if you are using a DS9490R or DS9490B adapter and select the correct port (e.g., USB1) from the Select Port drop -down menu. For serial port adapters, click the {DS9097U_DS948X} tab if you are using the DS9097U, DS1411, or DS948x (USB -to-serial port) adapter and select the correct port. The software also supports passive legacy adapters, which are selected through the {DS9097E} tab. Then, once the correct port has been selected, click Next. If the port selection was successful, you will see the next screen (not shown here), where the device polling rate is selected. If instead you see an error message 1-Wire Net not available, proceed to section Port Selection Help.

Now you are ready to connect 1-Wire devices to the port adapter and continue with the OneWireViewer User's guide.

Figure 9. Java Setup Wizard, 1-Wire Port Selection showing the USB port selection.

Figure 9. The OneWireViewer main window.

Port Selection Help

An unsuccessful port selection causes an error window (Figure 10) to open. In this case click on OK to close the window. After closing the OneWireViewer, run the Default 1-Wire Net.exe program, which is located in the 1-Wire Drivers folder (see Figure 8). This opens the Default 1-Wire Network Settings program (Figure 11).

Port selection error

Figure 10. Port selection error.

Port and adapter detection utility

Figure 11. Port and adapter detection utility.

First, verify that a functioning 1-Wire adapter is properly plugged in. Then click the Auto Detect button. Within seconds, you will see a success message (Figure 12). Click Yes , then OK on the Auto Detect sequence finished window, and then close the detection utility.

Auto Detect success message

Auto Detect success message

Figure 12. Auto Detect success message.

With the next start of the OneWireViewer, the just detected port and adapter information is listed in the Default Port field (see Figure 7 or Figure 8). Just click on Next three times in a row to reach the OneWireViewer main window. The onewireviewer.properties file is created or updated when the OneWireViewer is closed.

How to Change 1-Wire Adapters and Ports

If changing out USB or USB-to-serial adapters, it is safest to close the OneWireViewer, then use the built-in operating system Safely Remove Hardware feature to prepare the system for device removal. Once successful, then physically remove the DS9490 from the PC’s USB port. Next, plug in the new adapter. If it has never been recognized by the PC in question, refer to Step 4 of application note 4373 and then follow the instructions in the Port Selection Help section. Now, rerun the OneWireViewer.

If changing between adapters already present on the PC, simply click on the OneWireViewer’s Tools menu and choose Pick Adapter (Figure 13). This will display a new window titled Please pick an adapter (Figure 14). Simply click on the corresponding adapter tab, select the port number, and click OK.

Figure 13. Pick Adapter menu selection.

Figure 13. Pick Adapter menu selection.

Figure 14. Please pick an adapter window showing serial port selections.

Figure 14. Please pick an adapter window showing serial port selections.

How to Install a Newer OneWireViewer Version

Before installing a new version, the current version must be uninstalled.


Windows 10, Windows 7, Windows Server 2008, Windows Vista


Click on Start, and then click on Control Panel (Figure 6), which opens as a new window containing a list of computer settings. In the section Programs, click Uninstall a program. The 1-Wire drivers, which the OneWireViewer is bundled with, are usually found near the top of the list (Figure 15).

Figure 15. Uninstalling the OneWireViewer and 1-Wire Drivers.

Figure 15. Uninstalling the OneWireViewer and 1-Wire Drivers.

To uninstall, click on 1-Wire Drivers and then on Uninstall. A prompt will appear where you need to confirm the intention to uninstall.

Regardless of the operating system, there is one important file, named onewireviewer.properties, which is not automatically removed. With Windows 10, Windows 7, Windows Server 2008, and Windows Vista, the file is typically located in folder

	C:\Users\<user name>\.OneWireViewer

With Windows XP, the file is typically found in folder

	C:\Documents and Settings\<user name>\.OneWireViewer

This file contains the state of the OneWireViewer, such as window sizes, menu options, and the 1-Wire adapter being used. Unless the new viewer version is supposed to use the current settings, the properties file must be deleted, using an application like Windows Explorer. This ensures that the 1-Wire API for Java Setup Wizard will be launched when the new version is started for the first time. Now continue with the instructions in the Downloading and Installing the OneWireViewer section.

Summary

The OneWireViewer is a convenient tool to work with iButton loggers and to evaluate 1-Wire devices. Due to the nature of the software, its user interface may be less intuitive for the inexperienced or infrequent user. This document gives more insight into the operation of the OneWireViewer, its way of displaying errors, and function-viewer-specific peculiarities. It also includes hints on how to test for a bad iButton battery and how to verify whether a mission was started successfully. The second part of this document relates to software installation, port configuration, adapter detection, and changing adapter types and ports. This document, together with application note 4373, "OneWireViewer and iButton Quick Start Guide," and application note 3358, "OneWireViewer User's Guide," covers all situations that the typical user of 1-Wire devices is likely to encounter.