Description

The goal of this class is to simplify using multiple DSFamily 1-Wire thermometers from an Arduino. Particularly when the number of attached devices is unknown, quite a bit of valuable variable memory is consumed when allocating an array of {n} times the 8 Byte (64bit) Unique address; e.g. 128Bytes of storage would normally be reserved if there can be up to 16 1-Wire devices.

This class stores this address information at the end of the EEPROM memory, optionally reserving space at the beginning of EEPROM for other applications. Thus the maximum number of devices that can be processed depends upon the space reserved and the space available on the given Atmel processor. While the number of write-cycles to EEPROM should be limited to 10,000; the order of the 1-Wire devices is deterministic and the EEPROM.h library calls will check to make sure that no writes are performed if the data hasn't changed, so using EEPROM for this functionality is not an issue as few, if any, writes are done after the program has been run with a given configuration.

Access to the devices is done with an index number rather than the 64-Bit unique address, simplifying using the device. Several methods are built into the library to simplify basic operations on multiple thermometers, including allowing one of the thermometer readings to be ignored - important if one of the devices is placed elsewhere - i.e. one thermometer is on the board to measure ambient temperature, or one thermometer is placed directly on the evaporator plate in a refrigerator or freezer and is thus much colder than the others.

While the DS Family of thermometers are quite accurate, there can still be significant variations between readings. The class contains a calibration routine which assumes that all of the devices are at the same temperature and will use the DS-Family's 2 User-definable bytes to store offset calibration information which ensures a significant improvement in accuracy.

The Maxim DSFamily of thermometers use the 1-Wire microLAN protocol. There is an excellent library for 1-Wire, written by Paul Stoffregen and located at http://www.pjrc.com/teensy/td_libs_OneWire.html. There is also an informative page at http://playground.arduino.cc/Learning/OneWire describing how to use the library. As there are parts of the code that are unnecessary for this DS implementation and in order to make this library self- sufficient, the code from version 2.0 (extracted 2016-11-23), has been included in this library.

doxygen configuration

This library is built with the standard "Doxyfile", which is located at https://github.com/Zanduino/Common/blob/main/Doxygen. As described on that page, there are only 5 environment variables used, and these are set in the project's actions file, located at https://github.com/Zanduino/DSFamily/blob/master/.github/workflows/ci-doxygen.yml Edit this file and set the 5 variables - PRETTYNAME, PROJECT_NAME, PROJECT_NUMBER, PROJECT_BRIEF and PROJECT_LOGO so that these values are used in the doxygen documentation. The local copy of the doxyfile should be in the project's root directory in order to do local doxygen testing, but the file is ignored on upload to GitHub.

clang-format

Part of the GitHub actions for CI is running every source file through "clang-format" to ensure that coding formatting is done the same for all files. The configuration file ".clang-format" is located at https://github.com/Zanduino/Common/tree/main/clang-format and this is used for CI tests when pushing to GitHub. The local file, if present in the root directory, is ignored when committing and uploading.

GNU General Public License v3.0

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Author

Written by Arnd Arnd@.nosp@m.Zand.nosp@m.uino..nosp@m.Com at https://www.github.com/SV-Zanshin

Changelog