By: | Bernhard Linke, Principal Member Technical Staff |
Brian Hindman, Senior Member Technical Staff, Software |
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® 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 |
**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.
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.
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 desired, one can overwrite one or more of the scratchpad data bytes and then click on the Commit Changes button. If battery is good, 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 exceptione.g., when downloading the data log of a DS1921, or
ERROR: OneWireViewer (null) 1-Wire exception: com.dalsemi.onewire.adapter.OneWireIOException: native TMEX error -12while 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.
Windows 7, Windows Server 2008, Windows Vista Click on start, and then click on Control Panel (Figure 3), which opens as a new window containing a list of computer settings. In the section Programs, click on Uninstall a program.
Figure 3. Accessing the Control Panel.
Typically, the installed programs are sorted by name. That puts the 1-Wire drivers, which the OneWireViewer is bundled with, automatically near the top of the list (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.
Windows XP Click on start, move the mouse cursor up to Settings, and then to the right to Control Panel (Figure 5). Then click on Control Panel, which opens as a new window containing a list of utility programs.
Figure 5. Accessing the Control Panel.
Look for the utility Add or Remove Programs and start it by double-clicking. The 1-Wire drivers are typically near the top of the list (Figure 6). The driver version is part of the program name. Since there is no x64 code at the end of the program name, the 32-bit version is installed. Clicking Click here for support information displays the publisher name and driver version number in a separate window.
Figure 6. Identifying the driver version.
Initial Installation Pitfalls The OneWireViewer is available for four versions of the Windows operating system: 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 32-bit version and as 64-bit version. The OneWireViewer requires Java version 5, update 8 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.
- Open the command prompt window:
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 - 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.
There is also an online Java test. If your PC is a 64-bit system, you must use the 64-bit version of Internet Explorer® to get a valid test result. To access the online test, open the appropriate version of the Internet Explorer and go to http://java.com. Click on the Do I have Java? link, then click on the Verify Java version button.
If Java is not installed or your version is older than Version 5, Update 8, click on the Download Java Now button to download and install the latest version. Click the Agree and Start Free Download button, then save the file (e.g., to the desktop in Windows XP, or to the default downloads folder in Windows 7, Windows Server 2008, or Vista). Next run (open, double-click) the downloaded file and follow the instructions on 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 7, Windows Server 2008, Windows Vista Click on 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 7), move the cursor to OneWireViewer.exe and click.
Figure 7. Initial start of the OneWireViewer.
Windows XP Click on the start button, move the mouse cursor up to Programs, and then to the right to the 1-Wire Drivers folder (Figure 8). When the folder opens, move the cursor to OneWireViewer.exe and click.
Figure 8. 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 9 and 10) 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 9. Java Setup Wizard, 1-Wire Port Selection showing the USB port selection.
Figure 10. 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.
The default polling rate setting of 1 second is a good choice and should be accepted. Now click on Next, which takes you to the next screen (not shown here), where the 1-Wire Search Mode is selected. The default setting Show Normal Devices is appropriate for the initial setting and should be accepted. Now click Finish, which completes the setup and opens the OneWireViewer's main window (Figure 11). Now you are ready to connect 1-Wire devices to the port adapter and continue with the OneWireViewer User's guide.
Figure 11. The OneWireViewer main window.
Port Selection Help An unsuccessful port selection causes an error window (Figure 12) 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 Figures 7 and 8). This opens the Default 1-Wire Network Settings program (Figure 13).
Figure 12. Port selection error.
Figure 13. 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 14). Click Yes, then OK on the Auto Detect sequence finished window, and then close the detection utility.
Figure 14. 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 9 or 10). 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 15). This will display a new window titled Please pick an adapter (Figure 16). Simply click on the corresponding adapter tab, select the port number, and click OK.
Figure 15. Pick Adapter menu selection.
Figure 16. 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 7, Windows Server 2008, Windows Vista Click on start, and then click on Control Panel (Figure 3), 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 17).
Figure 17. 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.
Windows XP Click on start, move the mouse cursor up to Settings and then to the right to Control Panel (Figure 5). Then click on Control Panel, which opens as a new window containing a list of utility programs. On the Control Panel, look for Add or Remove Programs and start it, e.g., by double-clicking. The 1-Wire drivers, which the OneWireViewer is bundled with, are usually found near the top of the list (Figure 18). To uninstall, click on Remove. A prompt will appear where you need to confirm the intention to uninstall.
Figure 18. Uninstalling the OneWireViewer and 1-Wire drivers.
Regardless of the operating system, there is one important file, named onewireviewer.properties, which is not automatically removed. With 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.
1-Wire is a registered trademark of Maxim Integrated Products, Inc.
iButton is a registered trademark of Maxim Integrated Products, Inc.
Excel is a registered trademark of Microsoft Corporation.
Internet Explorer is a registered trademark of Microsoft Corporation.
Java is a registered trademark and registered service mark of Oracle and/or its affiliates.
Thermochron is a registered trademark of Maxim Integrated Products, Inc.
Windows is a registered trademark and registered service mark of Microsoft Corporation.
Windows Vista is a registered trademark and registered service mark of Microsoft Corporation.
Windows XP is a registered trademark and registered service mark of Microsoft Corporation.
相关型号 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|