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 36To compile this driver into the kernel, 37place the following line in your 38kernel configuration file: 39.Bd -ragged -offset indent 40.Cd "device gpioths" 41.Ed 42.Pp 43Alternatively, to load the driver as a 44module at boot time, place the following line in 45.Xr loader.conf 5 : 46.Bd -literal -offset indent 47gpioths_load="YES" 48.Ed 49.Sh DESCRIPTION 50The 51.Nm 52driver supports the DHTxx and AM320x family of 53temperature and humidity sensors. 54The driver automatically reads the values from the sensor 55once every 5 seconds, and makes the results available via 56.Xr sysctl 8 57variables. 58.Sh HARDWARE 59The 60.Nm 61driver 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 69The supported devices are all similar to each other, varying 70primarily in accuracy and resolution. 71The devices require a single wire for data communications, using a 72custom protocol which is not compatible with Maxim's 1-wire(tm). 73The AM320x devices also support connection to an i2c bus, 74but this driver supports only the single-wire connection option. 75.Sh SYSCTL VARIABLES 76Sysctl variables are used to access the most recent temperature and 77humidity measurements. 78.Bl -tag -width indent 79.It Va dev.gpioths.<unit>.temp 80The current temperature in integer deciKelvins. 81Note that 82.Xr sysctl 8 83will convert those units to display in decimal degrees Celsius. 84.It Va dev.gpioths.<unit>.hum 85The current relative humidity, as an integer percentage. 86.It Va dev.gpioths.<unit>.fails 87The number of failed attempts to communicate with the sensor since 88the last good access. 89Cleared whenever a set of measurements is successfully retrieved. 90.El 91.Sh FDT CONFIGURATION 92On an 93.Xr fdt 4 94based system, a 95.Nm 96device node is typically defined directly under the root node, or under 97a simplebus node that represents a collection of devices on a board. 98.Pp 99The following properties are required in the 100.Nm 101device subnode: 102.Bl -tag -width indent 103.It Va compatible 104Must be "dht11". 105.It Va gpios 106A 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 126On a 127.Xr device.hints 5 128based system, such as 129.Li MIPS , 130these values are configurable for 131.Nm : 132.Bl -tag -width indent 133.It Va hint.gpioths.<unit>.at 134The 135.Xr gpiobus 4 136instance the 137.Nm 138instance is attached to. 139.It Va hint.gpioths.pins 140A bitmask with a single bit set to indicate which gpio pin on the 141.Xr gpiobus 4 142to 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 149The 150.Nm 151driver first appeared in 152.Fx 11.1 . 153