Differential D2956 Diff 6852 share/man/man4/ow_temp.4

Changeset View

Standalone View

share/man/man4/ow_temp.4

This file was added.

				.\"
				.\" Copyright (c) 2015 M. Warner Losh
				.\" All rights reserved.
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. The name of the author may not be used to endorse or promote products
				.\" derived from this software without specific prior written permission.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd July 6, 2015
				.Dt OW_TEMP 4
				.Os
				.Sh NAME
				.Nm ow_temp
				.Nd Dallas Semiconductor 1-Wire Temperature sensor
				.Sh DESCRIPTION
				The
				.Nm
				module supports many of the 1-Wire temperature sensors.
				.Pp
				The sensor is read periodically and the results returned via a
				.Xr sysctl 3
				as described below.
				.Sh HARDWARE
				The following families of temperature sensors are supported by the
				wblockUnsubmitted Not Done Inline Actions s/The following/These wblock: s/The following/These
				.Nm
				driver:
				.Bl -tag -width MAX31820 -compact
				.It DS1820
				1-Wire Digital Thermometer
				.It DS18S20
				High-Precision 1-Wire Digital Thermometer
				.It DS18B20
				Programmable Resolution 1-Wire Digital Thermometer
				.It DS1822
				Econo 1-Wire Digital Thermometer
				.It DS1825
				Programmable Resolution 1-Wire Digital Thermometer with 4-bit ID
				.It MAX31820
				1-Wire, Parasite-Power, Ambient Temperature Sensor
				.El
				.Pp
				The Family Codes for these devices are reused for many variants of
				wblockUnsubmitted Not Done Inline Actions Avoid redundancy by avoiding redundancy (see also: redundancy). Probably not necessary to capitalize "family codes": The family codes for these devices are reused by many variants marketed under different names. wblock: Avoid redundancy by avoiding redundancy (see also: redundancy). Probably not necessary to…
				these devices marketed under different names.
				The variants are software compatible with earlier chips, though they
				may have different operating characteristics (such as accuracy or
				wblockUnsubmitted Not Done Inline Actions Avoid the aside: might have different operating characteristics like accuracy or temperature range. wblock: Avoid the aside: might have different operating characteristics like accuracy or temperature…
				temperature range).
				This driver supports the 0x10, 0x22, 0x28 and 0x3b family codes.
				wblockUnsubmitted Not Done Inline Actions Rearrange to avoid the repetitive "This driver". Also add a serial comma: Family codes 0x10, 0x22, 0x28, and 0x3b are supported. wblock: Rearrange to avoid the repetitive "This driver". Also add a serial comma: Family codes 0x10…
				.Sh SYSCTL
				This driver supports a number of
				wblockUnsubmitted Not Done Inline Actions "Supports" is not really the right word here. The driver provides those entries. Probably better to use .Nm than "this driver", too: .Nm provides several entries in the device's node in the .Xr sysctl 8 tree: wblock: "Supports" is not really the right word here. The driver provides those entries. Probably…
				.Xr sysctl 8
				entries in the device's node in the
				.Xr sysctl 8
				tree.
				.Bl -tag -width xxxxxxxxxx
				.It temperature
				The last temperature read, in milli-Kelvin.
				.It badcrc
				wblockUnsubmitted Done Inline Actions Clearer as "The last temperature read". wblock: Clearer as "The last temperature read".
				The number of CRC errors in reading the temperature form the
				device.
				Some CRC errors are to be expected.
				High rates of CRC errors, however, generally indicate a noisy
				environment, cabling issues, or too many devices on the bus.
				wblockUnsubmitted Done Inline Actions s/indicates/indicate/ wblock: s/indicates/indicate/
				.It badread
				wblockUnsubmitted Done Inline Actions Seems like just "or" is adequate, and simpler than "and/or". wblock: Seems like just "or" is adequate, and simpler than "and/or".
				wblockUnsubmitted Not Done Inline Actions Needs serial comma: s/issues/issues,/ wblock: Needs serial comma: s/issues/issues,/
				The number of times an non-CRC error was encountered reading the temperature
				from the card.
				wblockUnsubmitted Not Done Inline Actions Typo: s/an/a/ wblock: Typo: s/an/a/
				This type of error is very rare.
				wblockUnsubmitted Done Inline Actions "apart from CRC errors" is a little unclear. Maybe "... not counting CRC errors." is better. wblock: "apart from CRC errors" is a little unclear. Maybe "... not counting CRC errors." is better.
				wblockUnsubmitted Not Done Inline Actions "counting from CRC errors" is still unclear. I originally thought this meant "the number of non-CRC errors." Not so sure now. wblock: "counting from CRC errors" is still unclear. I originally thought this meant "the number of…
				.It reading_interval
				wblockUnsubmitted Done Inline Actions Try to use "should" for permission. For probability, "might" is usually better, but here: This type of error is rare. wblock: Try to use "should" for permission. For probability, "might" is usually better, but here…
				The time, in ticks, between successive reads of the sensor.
				.It parasite
				This item is non-zero when the device is connected using its parasitic
				power mode.
				It can also indicate a wiring error.
				.El
				wblockUnsubmitted Done Inline Actions Avoid contractions: s/doesn't/does not/ But also... "likely does not work" kind of leaves the reader hanging. Can it be used in certain situations? Is there a way to tell when it will or will not work, or why? wblock: Avoid contractions: s/doesn't/does not/ But also... "likely does not work" kind of leaves the…
				wblockUnsubmitted Not Done Inline Actions "may" is generally used for permission. "might" or "can" is better for probability: It can also indicate a wiring error. wblock: "may" is generally used for permission. "might" or "can" is better for probability: It can…
				.Sh SEE ALSO
				.Xr ow 4 ,
				.Xr owc 4 ,
				.Xr sysctl 8 ,
				.Xr owll 9 ,
				.Xr own 9
				.Sh LEGAL
				wblockUnsubmitted Done Inline Actions sysctl(3) is mentioned in the text and should be included in the SEE ALSO. Maybe sysctl(8) too? wblock: sysctl(3) is mentioned in the text and should be included in the SEE ALSO. Maybe sysctl(8) too?
				.Tn 1-Wire
				is a registered trademark of Maxim Integrated Products, Inc.
				wblockUnsubmitted Done Inline Actions Avoid contractions: s/doesn't/does not/ Above, it said "likely does not work", but here it just says it definitely does not work. Which is right? wblock: Avoid contractions: s/doesn't/does not/ Above, it said "likely does not work", but here it…
				.Sh BUGS
				The parasitic mode of the devices does not work. It requires support
				from the
				.Xr owc 4
				driver that is unimplemented.
				.Pp
				The ID bits from the
				.Em DS1825
				are not recognized or reported.
				.Pp
				The type of the device is not reported via
				wblockUnsubmitted Done Inline Actions Contraction: s/There's/There is/ wblock: Contraction: s/There's/There is/
				.Xr sysctl 8 .
				.Pp
				wblockUnsubmitted Done Inline Actions Feels like there should be some markup on "Convert Temperature". Maybe just quotes? .Dq Convert Temperature requests are sent directly to the device. wblock: Feels like there should be some markup on "Convert Temperature". Maybe just quotes? .Dq…
				wblockUnsubmitted Not Done Inline Actions Low and high temperature... what? Limits? Ranges? Alarms? "either" is probably not needed. wblock: Low and high temperature... what? Limits? Ranges? Alarms? "either" is probably not needed.
				Alarm mode is not supported.
				It is not possible to set the low and high alarm temperatures.
				.Pp
				There is no way to write to the EEPROM.
				.Pp
				.Dq Convert Temperature
				requests are sent directly to the device.
				There is no way use the 1-Wire bus' broadcast ability to do all the
				conversions in parallel.
				.Pp
				wblockUnsubmitted Done Inline Actions s/There's/There is/ wblock: s/There's/There is/
				It is not possible to set the precision on those devices that support
				it.
				.Pp
				The time to convert is fixed at 1 second, even though some devices are
				faster.
				.Pp
				There is no character device to supply a stream of readings to a
				program.
				Programs interested in the temperature must poll the sysctl to get the
				temperature.
				.Sh HISTORY
				The
				.Nm
				driver first appeared in
				.Fx 11.0 .
				.Sh AUTHORS
				The
				.Nm
				device driver and this manual page were written by
				.An Warner Losh .