1.\" 2.\" Copyright (c) 2015 M. Warner Losh <imp@FreeBSD.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. The name of the author may not be used to endorse or promote products 10.\" derived from this software without specific prior written permission. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd July 20, 2015 25.Dt OW_TEMP 4 26.Os 27.Sh NAME 28.Nm ow_temp 29.Nd Dallas Semiconductor 1-Wire Temperature sensor 30.Sh SYNOPSIS 31.Cd device ow_temp 32.Sh DESCRIPTION 33The 34.Nm 35module supports many of the 1-Wire temperature sensors. 36.Pp 37The sensor is read periodically and the results returned via a 38.Xr sysctl 3 39as described below. 40.Sh HARDWARE 41These temperature sensors are supported by the 42.Nm 43driver: 44.Bl -tag -width MAX31820 -compact 45.It DS1820 461-Wire Digital Thermometer 47.It DS18S20 48High-Precision 1-Wire Digital Thermometer 49.It DS18B20 50Programmable Resolution 1-Wire Digital Thermometer 51.It DS1822 52Econo 1-Wire Digital Thermometer 53.It DS1825 54Programmable Resolution 1-Wire Digital Thermometer with 4-bit ID 55.It MAX31820 561-Wire, Parasite-Power, Ambient Temperature Sensor 57.El 58.Pp 59The driver supports Family codes 0x10, 0x22, 0x28, and 0x3b. 60.Sh SYSCTL 61The 62.Nm 63driver reports data via 64.Xr sysctl 8 65entries in the device's node in the 66.Xr sysctl 8 67tree: 68.Bl -tag -width xxxxxxxxxx 69.It temperature 70The last temperature read, in milli-Kelvin. 71.It badcrc 72The number of CRC errors in reading the temperature form the 73device. 74Some CRC errors are to be expected. 75High rates of CRC errors, however, generally indicate a noisy 76environment, cabling issues, or too many devices on the bus. 77.It badread 78The number of times a non-CRC error was encountered reading the temperature 79from the card. 80This type of error is very rare. 81.It reading_interval 82The time, in ticks, between successive reads of the sensor. 83.It parasite 84This item is non-zero when the device is connected using its parasitic 85power mode. 86It can also indicate a wiring error. 87.El 88.Pp 89Temperatures are reported in milli-Kelvin, even though the absolute 90accuracy is around 0.2 degrees for the good devices and around 1 91degree for cheaper devices. 92The devices report in steps of 0.0625 degrees. 93The driver preserves the precision of the device's measurements 94in its 95.Xr sysctl 8 96reports. 97These devices often have a much higher relative accuracy and 98repeatability than their absolute accuracy. 99This makes them well suited for control loops that strive for 100stability and become possible if the full precision is preserved. 101.Sh SEE ALSO 102.Xr ow 4 , 103.Xr owc 4 , 104.Xr sysctl 8 , 105.Xr owll 9 , 106.Xr own 9 107.Sh LEGAL 108.Tn 1-Wire 109is a registered trademark of Maxim Integrated Products, Inc. 110.Sh HISTORY 111The 112.Nm 113driver first appeared in 114.Fx 11.0 . 115.Sh AUTHORS 116The 117.Nm 118device driver and this manual page were written by 119.An Warner Losh . 120.Sh BUGS 121The parasitic mode of the devices does not work. 122It requires support from the 123.Xr owc 4 124driver that is unimplemented. 125.Pp 126The ID bits from the 127.Em DS1825 128are not recognized or reported. 129.Pp 130The type of the device is not reported via 131.Xr sysctl 8 . 132.Pp 133Alarm mode is not supported. 134It is not possible to set the low and high alarm temperatures. 135.Pp 136There is no way to write to the EEPROM. 137.Pp 138.Dq Convert Temperature 139requests are sent directly to the device. 140There is no way to use the broadcast ability of the 1-Wire bus to do 141all the conversions in parallel. 142.Pp 143It is not possible to set the precision on those devices that support 144it. 145.Pp 146The time to convert is fixed at 1 second, even though some devices are 147faster. 148.Pp 149There is no character device to supply a stream of readings to a 150program. 151Programs interested in the temperature must poll the sysctl to get the 152temperature. 153