.\"-
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org>
.\"
.\" 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. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 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 December 8, 2019
.Dt GPIOTHS 4
.Os
.Sh NAME
.Nm gpioths
.Nd driver for DHTxx and AM320x temperature and humidity sensors
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following line in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device gpioths"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
gpioths_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver supports the DHTxx and AM320x family of
temperature and humidity sensors.
The driver automatically reads the values from the sensor
once every 5 seconds, and makes the results available via
.Xr sysctl 8
variables.
.Sh HARDWARE
The
.Nm
driver provides support for the following devices:
.Pp
.Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX"
.It DHT11  Ta DHT12
.It DHT21  Ta DHT22
.It AM3201 Ta AM3202
.El
.Pp
The supported devices are all similar to each other, varying
primarily in accuracy and resolution.
The devices require a single wire for data communications, using a
custom protocol which is not compatible with Maxim's 1-wire(tm).
The AM320x devices also support connection to an i2c bus,
but this driver supports only the single-wire connection option.
.Sh SYSCTL VARIABLES
Sysctl variables are used to access the most recent temperature and
humidity measurements.
.Bl -tag -width indent
.It Va dev.gpioths.<unit>.temp
The current temperature in integer deciKelvins.
Note that
.Xr sysctl 8
will convert those units to display in decimal degrees Celsius.
.It Va dev.gpioths.<unit>.hum
The current relative humidity, as an integer percentage.
.It Va dev.gpioths.<unit>.fails
The number of failed attempts to communicate with the sensor since
the last good access.
Cleared whenever a set of measurements is successfully retrieved.
.El
.Sh FDT CONFIGURATION
On an
.Xr fdt 4
based system, a
.Nm
device node is typically defined directly under the root node, or under
a simplebus node that represents a collection of devices on a board.
.Pp
The following properties are required in the
.Nm
device subnode:
.Bl -tag -width indent
.It Va compatible
Must be "dht11".
.It Va gpios
A reference to the gpio device and pin for data communications.
.El
.Ss Example of adding a sensor with an overlay
.Bd -unfilled -offset indent
/dts-v1/;
/plugin/;
#include <dt-bindings/gpio/gpio.h>

/ {
    compatible = "wand,imx6q-wandboard";
};

&{/} {
    dht0 {
        compatible = "dht11";
        gpios = <&gpio5 15 GPIO_ACTIVE_HIGH>;
    };
};
.Ed
.Sh HINTS CONFIGURATION
On a
.Xr device.hints 5
based system, such as
.Li MIPS ,
these values are configurable for
.Nm :
.Bl -tag -width indent
.It Va hint.gpioths.<unit>.at
The
.Xr gpiobus 4
instance the
.Nm
instance is attached to.
.It Va hint.gpioths.pins
A bitmask with a single bit set to indicate which gpio pin on the
.Xr gpiobus 4
to use for data communications.
.El
.Sh SEE ALSO
.Xr fdt 4 ,
.Xr gpiobus 4 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 11.1 .