share/man/man4/ow_temp.4

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