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