share/man/man4/ow_temp.4

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