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.\" $FreeBSD$ 25.\" 26.Dd July 20, 2015 27.Dt OW_TEMP 4 28.Os 29.Sh NAME 30.Nm ow_temp 31.Nd Dallas Semiconductor 1-Wire Temperature sensor 32.Sh SYNOPSIS 33.Cd device ow_temp 34.Sh DESCRIPTION 35The 36.Nm 37module supports many of the 1-Wire temperature sensors. 38.Pp 39The sensor is read periodically and the results returned via a 40.Xr sysctl 3 41as described below. 42.Sh HARDWARE 43These temperature sensors are supported by the 44.Nm 45driver: 46.Bl -tag -width MAX31820 -compact 47.It DS1820 481-Wire Digital Thermometer 49.It DS18S20 50High-Precision 1-Wire Digital Thermometer 51.It DS18B20 52Programmable Resolution 1-Wire Digital Thermometer 53.It DS1822 54Econo 1-Wire Digital Thermometer 55.It DS1825 56Programmable Resolution 1-Wire Digital Thermometer with 4-bit ID 57.It MAX31820 581-Wire, Parasite-Power, Ambient Temperature Sensor 59.El 60.Pp 61The driver supports Family codes 0x10, 0x22, 0x28, and 0x3b. 62.Sh SYSCTL 63The 64.Nm 65driver reports data via 66.Xr sysctl 8 67entries in the device's node in the 68.Xr sysctl 8 69tree: 70.Bl -tag -width xxxxxxxxxx 71.It temperature 72The last temperature read, in milli-Kelvin. 73.It badcrc 74The number of CRC errors in reading the temperature form the 75device. 76Some CRC errors are to be expected. 77High rates of CRC errors, however, generally indicate a noisy 78environment, cabling issues, or too many devices on the bus. 79.It badread 80The number of times a non-CRC error was encountered reading the temperature 81from the card. 82This type of error is very rare. 83.It reading_interval 84The time, in ticks, between successive reads of the sensor. 85.It parasite 86This item is non-zero when the device is connected using its parasitic 87power mode. 88It can also indicate a wiring error. 89.El 90.Pp 91Temperatures are reported in milli-Kelvin, even though the absolute 92accuracy is around 0.2 degrees for the good devices and around 1 93degree for cheaper devices. 94The devices report in steps of 0.0625 degrees. 95The driver preserves the precision of the device's measurements 96in its 97.Xr sysctl 8 98reports. 99These devices often have a much higher relative accuracy and 100repeatability than their absolute accuracy. 101This makes them well suited for control loops that strive for 102stability and become possible if the full precision is preserved. 103.Sh SEE ALSO 104.Xr ow 4 , 105.Xr owc 4 , 106.Xr sysctl 8 , 107.Xr owll 9 , 108.Xr own 9 109.Sh LEGAL 110.Tn 1-Wire 111is a registered trademark of Maxim Integrated Products, Inc. 112.Sh HISTORY 113The 114.Nm 115driver first appeared in 116.Fx 11.0 . 117.Sh AUTHORS 118The 119.Nm 120device driver and this manual page were written by 121.An Warner Losh . 122.Sh BUGS 123The parasitic mode of the devices does not work. 124It requires support from the 125.Xr owc 4 126driver that is unimplemented. 127.Pp 128The ID bits from the 129.Em DS1825 130are not recognized or reported. 131.Pp 132The type of the device is not reported via 133.Xr sysctl 8 . 134.Pp 135Alarm mode is not supported. 136It is not possible to set the low and high alarm temperatures. 137.Pp 138There is no way to write to the EEPROM. 139.Pp 140.Dq Convert Temperature 141requests are sent directly to the device. 142There is no way to use the broadcast ability of the 1-Wire bus to do 143all the conversions in parallel. 144.Pp 145It is not possible to set the precision on those devices that support 146it. 147.Pp 148The time to convert is fixed at 1 second, even though some devices are 149faster. 150.Pp 151There is no character device to supply a stream of readings to a 152program. 153Programs interested in the temperature must poll the sysctl to get the 154temperature. 155