share/man/man4/gpioths.4

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2019 Ian Lepore <ian@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. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd December 8, 2019
  30 .Dt GPIOTHS 4
  31 .Os
  32 .Sh NAME
  33 .Nm gpioths
  34 .Nd driver for DHTxx and AM320x temperature and humidity sensors
  35 .Sh SYNOPSIS
  36 To compile this driver into the kernel,
  37 place the following line in your
  38 kernel configuration file:
  39 .Bd -ragged -offset indent
  40 .Cd "device gpioths"
  41 .Ed
  42 .Pp
  43 Alternatively, to load the driver as a
  44 module at boot time, place the following line in
  45 .Xr loader.conf 5 :
  46 .Bd -literal -offset indent
  47 gpioths_load="YES"
  48 .Ed
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 driver supports the DHTxx and AM320x family of
  53 temperature and humidity sensors.
  54 The driver automatically reads the values from the sensor
  55 once every 5 seconds, and makes the results available via
  56 .Xr sysctl 8
  57 variables.
  58 .Sh HARDWARE
  59 The
  60 .Nm
  61 driver provides support for the following devices:
  62 .Pp
  63 .Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX"
  64 .It DHT11  Ta DHT12
  65 .It DHT21  Ta DHT22
  66 .It AM3201 Ta AM3202
  67 .El
  68 .Pp
  69 The supported devices are all similar to each other, varying
  70 primarily in accuracy and resolution.
  71 The devices require a single wire for data communications, using a
  72 custom protocol which is not compatible with Maxim's 1-wire(tm).
  73 The AM320x devices also support connection to an i2c bus,
  74 but this driver supports only the single-wire connection option.
  75 .Sh SYSCTL VARIABLES
  76 Sysctl variables are used to access the most recent temperature and
  77 humidity measurements.
  78 .Bl -tag -width indent
  79 .It Va dev.gpioths.<unit>.temp
  80 The current temperature in integer deciKelvins.
  81 Note that
  82 .Xr sysctl 8
  83 will convert those units to display in decimal degrees Celcius.
  84 .It Va dev.gpioths.<unit>.hum
  85 The current relative humidity, as an integer percentage.
  86 .It Va dev.gpioths.<unit>.fails
  87 The number of failed attempts to communicate with the sensor since
  88 the last good access.
  89 Cleared whenever a set of measurements is successfully retrieved.
  90 .El
  91 .Sh FDT CONFIGURATION
  92 On an
  93 .Xr fdt 4
  94 based system, a
  95 .Nm
  96 device node is typically defined directly under the root node, or under
  97 a simplebus node that represents a collection of devices on a board.
  98 .Pp
  99 The following properties are required in the
 100 .Nm
 101 device subnode:
 102 .Bl -tag -width indent
 103 .It Va compatible
 104 Must be "dht11".
 105 .It Va gpios
 106 A reference to the gpio device and pin for data communications.
 107 .El
 108 .Ss Example of adding a sensor with an overlay
 109 .Bd -unfilled -offset indent
 110 /dts-v1/;
 111 /plugin/;
 112 #include <dt-bindings/gpio/gpio.h>
 113
 114 / {
 115     compatible = "wand,imx6q-wandboard";
 116 };
 117
 118 &{/} {
 119     dht0 {
 120         compatible = "dht11";
 121         gpios = <&gpio5 15 GPIO_ACTIVE_HIGH>;
 122     };
 123 };
 124 .Ed
 125 .Sh HINTS CONFIGURATION
 126 On a
 127 .Xr device.hints 5
 128 based system, such as
 129 .Li MIPS ,
 130 these values are configurable for
 131 .Nm :
 132 .Bl -tag -width indent
 133 .It Va hint.gpioths.<unit>.at
 134 The
 135 .Xr gpiobus 4
 136 instance the
 137 .Nm
 138 instance is attached to.
 139 .It Va hint.gpioths.pins
 140 A bitmask with a single bit set to indicate which gpio pin on the
 141 .Xr gpiobus 4
 142 to use for data communications.
 143 .El
 144 .Sh SEE ALSO
 145 .Xr fdt 4 ,
 146 .Xr gpiobus 4 ,
 147 .Xr sysctl 8
 148 .Sh HISTORY
 149 The
 150 .Nm
 151 driver first appeared in
 152 .Fx 11.1 .