From e959e0062e97cb5c4ddb7afeea6b2b07019e648a Mon Sep 17 00:00:00 2001 From: Matteo Golin Date: Thu, 3 Oct 2024 13:36:14 -0400 Subject: [PATCH] Create a documentation folder to list sensor drivers that are available. This way each sensor added/implemented can have its own space to define any unique ioctl commands that it uses, unique error codes and programming examples. --- .../components/drivers/special/sensors.rst | 70 +--------- .../drivers/special/sensors/adt7320.rst | 7 + .../drivers/special/sensors/adxl345.rst | 13 ++ .../drivers/special/sensors/adxl362.rst | 4 + .../drivers/special/sensors/adxl372.rst | 15 +++ .../drivers/special/sensors/aht10.rst | 4 + .../drivers/special/sensors/ak09912.rst | 4 + .../drivers/special/sensors/lsm330.rst | 17 +++ .../drivers/special/sensors/mpl115a.rst | 7 + .../drivers/special/sensors/sht4x.rst | 127 ++++++++++++++++++ 10 files changed, 205 insertions(+), 63 deletions(-) create mode 100644 Documentation/components/drivers/special/sensors/adt7320.rst create mode 100644 Documentation/components/drivers/special/sensors/adxl345.rst create mode 100644 Documentation/components/drivers/special/sensors/adxl362.rst create mode 100644 Documentation/components/drivers/special/sensors/adxl372.rst create mode 100644 Documentation/components/drivers/special/sensors/aht10.rst create mode 100644 Documentation/components/drivers/special/sensors/ak09912.rst create mode 100644 Documentation/components/drivers/special/sensors/lsm330.rst create mode 100644 Documentation/components/drivers/special/sensors/mpl115a.rst create mode 100644 Documentation/components/drivers/special/sensors/sht4x.rst diff --git a/Documentation/components/drivers/special/sensors.rst b/Documentation/components/drivers/special/sensors.rst index 55ed308e4ab..53dff63e272 100644 --- a/Documentation/components/drivers/special/sensors.rst +++ b/Documentation/components/drivers/special/sensors.rst @@ -1,66 +1,10 @@ -.. warning:: this list is incomplete. See drivers/sensors for ar full list of - supported sensors +.. warning:: This list is incomplete. See drivers/sensors for a full list of + supported sensors ============== Sensor Drivers ============== -ADXL345 -======= - -Contributed by Alan Carvalho de Assis - -The ADXL345 accelerometer can operate in I2C or SPI mode. To operate in I2C -mode just connect the CS pin to Vddi/o. - -In order to operate in SPI mode CS need to use connected to microcontroller, -it cannot leave unconnected. - -In SPI mode it works with clock polarity (CPOL) = 1 and clock phase (CPHA) -= 1. - -ADXL372 -======= - -Contributed by Bob Feretich - -The ADXL372 is a 200g tri-axis accelerometer that is capable of detecting -and recording shock impact impact events. Recording trigger -characteristics are programmed into the sensor via multiple threshold and -duration registers. The ADXL372 is a SPI only device that can transfer -data at 10 MHz. The data transfer performance of this part permits the -sensor to be sampled "on demand" rather than periodically sampled by a -worker task. - -See the description of the "Common Sensor Register Interface" below for more -details. It also implements the "Sensor Cluster Driver Interface". - -LSM330_SPI -========== - -Contributed by Bob Feretich - -The LSM330 consists of a multi-range tri-axis accelerometer and a -multi-range tri-axis gyroscope. The tri-axis accelerometer features two -state machines that can be firmware programmed for event detection. The -tri-axis gyroscope features threshold and duration registers for event -detection. - -This driver supports the LSM330 in SPI mode. In this mode, the LSM330 -that can transfer data at 10 MHz. The data transfer performance of -this part permits the sensor to be sampled "on demand" rather than -periodically sampled by a worker task. See the description of the "Common -Sensor Register Interface" below for more details. It also implements the -"Sensor Cluster Driver Interface". - -MPL115A -======= - -Contributed by Alan Carvalho de Assis - -This driver has support only for MPL115A1 (SPI), but support to MPL115A2 -(I2C) can be added easily. - Common Sensor Register Interface ================================ @@ -487,10 +431,10 @@ shared worker task that collects the data. The cluster driver close() function calls the close functions of the leaf drivers. -ADT7320 -======= +Implemented Drivers +=================== -Contributed by Augusto Fraga Giachero +.. toctree:: + :glob: -The ADT7320 is a SPI temperature sensor with a temperature range of -−40°C to +150°C. + sensors/* diff --git a/Documentation/components/drivers/special/sensors/adt7320.rst b/Documentation/components/drivers/special/sensors/adt7320.rst new file mode 100644 index 00000000000..1c371d4b9ee --- /dev/null +++ b/Documentation/components/drivers/special/sensors/adt7320.rst @@ -0,0 +1,7 @@ +ADT7320 +======= + +Contributed by Augusto Fraga Giachero + +The ADT7320 is a SPI temperature sensor with a temperature range of +−40°C to +150°C. diff --git a/Documentation/components/drivers/special/sensors/adxl345.rst b/Documentation/components/drivers/special/sensors/adxl345.rst new file mode 100644 index 00000000000..062ce2ccb2d --- /dev/null +++ b/Documentation/components/drivers/special/sensors/adxl345.rst @@ -0,0 +1,13 @@ +ADXL345 +======= + +Contributed by Alan Carvalho de Assis + +The ADXL345 accelerometer can operate in I2C or SPI mode. To operate in I2C +mode just connect the CS pin to Vddi/o. + +In order to operate in SPI mode CS need to use connected to microcontroller, +it cannot leave unconnected. + +In SPI mode it works with clock polarity (CPOL) = 1 and clock phase (CPHA) += 1. diff --git a/Documentation/components/drivers/special/sensors/adxl362.rst b/Documentation/components/drivers/special/sensors/adxl362.rst new file mode 100644 index 00000000000..7926cdbca0f --- /dev/null +++ b/Documentation/components/drivers/special/sensors/adxl362.rst @@ -0,0 +1,4 @@ +ADXL362 +======= + +Accelerometer with support for SPI interfaces. Has UORB support. diff --git a/Documentation/components/drivers/special/sensors/adxl372.rst b/Documentation/components/drivers/special/sensors/adxl372.rst new file mode 100644 index 00000000000..222819ddf27 --- /dev/null +++ b/Documentation/components/drivers/special/sensors/adxl372.rst @@ -0,0 +1,15 @@ +ADXL372 +======= + +Contributed by Bob Feretich + +The ADXL372 is a 200g tri-axis accelerometer that is capable of detecting +and recording shock impact impact events. Recording trigger +characteristics are programmed into the sensor via multiple threshold and +duration registers. The ADXL372 is a SPI only device that can transfer +data at 10 MHz. The data transfer performance of this part permits the +sensor to be sampled "on demand" rather than periodically sampled by a +worker task. + +See the description of the "Common Sensor Register Interface" below for more +details. It also implements the "Sensor Cluster Driver Interface". diff --git a/Documentation/components/drivers/special/sensors/aht10.rst b/Documentation/components/drivers/special/sensors/aht10.rst new file mode 100644 index 00000000000..7af72236b49 --- /dev/null +++ b/Documentation/components/drivers/special/sensors/aht10.rst @@ -0,0 +1,4 @@ +AHT10 +===== + +A temperature and humidity sensor using an I2C interface. diff --git a/Documentation/components/drivers/special/sensors/ak09912.rst b/Documentation/components/drivers/special/sensors/ak09912.rst new file mode 100644 index 00000000000..b641eb2eba5 --- /dev/null +++ b/Documentation/components/drivers/special/sensors/ak09912.rst @@ -0,0 +1,4 @@ +AK09912 +======= + +Magnetic compass IC with an I2C interface. diff --git a/Documentation/components/drivers/special/sensors/lsm330.rst b/Documentation/components/drivers/special/sensors/lsm330.rst new file mode 100644 index 00000000000..8dbebb9ad61 --- /dev/null +++ b/Documentation/components/drivers/special/sensors/lsm330.rst @@ -0,0 +1,17 @@ +LSM330_SPI +========== + +Contributed by Bob Feretich + +The LSM330 consists of a multi-range tri-axis accelerometer and a +multi-range tri-axis gyroscope. The tri-axis accelerometer features two +state machines that can be firmware programmed for event detection. The +tri-axis gyroscope features threshold and duration registers for event +detection. + +This driver supports the LSM330 in SPI mode. In this mode, the LSM330 +that can transfer data at 10 MHz. The data transfer performance of +this part permits the sensor to be sampled "on demand" rather than +periodically sampled by a worker task. See the description of the "Common +Sensor Register Interface" below for more details. It also implements the +"Sensor Cluster Driver Interface". diff --git a/Documentation/components/drivers/special/sensors/mpl115a.rst b/Documentation/components/drivers/special/sensors/mpl115a.rst new file mode 100644 index 00000000000..e5c0cad1723 --- /dev/null +++ b/Documentation/components/drivers/special/sensors/mpl115a.rst @@ -0,0 +1,7 @@ +MPL115A +======= + +Contributed by Alan Carvalho de Assis + +This driver has support only for MPL115A1 (SPI), but support to MPL115A2 +(I2C) can be added easily. diff --git a/Documentation/components/drivers/special/sensors/sht4x.rst b/Documentation/components/drivers/special/sensors/sht4x.rst new file mode 100644 index 00000000000..56991b3061f --- /dev/null +++ b/Documentation/components/drivers/special/sensors/sht4x.rst @@ -0,0 +1,127 @@ +SHT4X +===== + +Contributed by Matteo Golin. + +The SHT4x is a family of temperature and humidity sensors created by Sensirion +which operates over I2C. They include a small heating element. + +The driver provided allows interfacing with the sensor over I2C. It has been +tested against the SHT41. + +Application Programming Interface +================================= + +The header file for the SHT4X driver interface can be included using: + +.. code-block:: c + + # include + +The SHT4x registration function allows the driver to be registered as a POSIX +character driver. + +The standard POSIX `read()` operation will return the temperature and humidity +measurements in plain-text, which is useful when debugging/testing the driver +using `cat` from the shell. + +The `write()` operation is not implemented for this sensor. + +Specific operations the sensor offers can be performed via the POSIX `ioctl` +operation. The supported commands are: + + * :c:macro:`SNIOC_RESET` + * :c:macro:`SNIOC_WHO_AM_I` + * :c:macro:`SNIOC_READ_RAW_DATA` + * :c:macro:`SNIOC_MEASURE` + * :c:macro:`SNIOC_READ_CONVERT_DATA` + * :c:macro:`SNIOC_HEAT` + * :c:macro:`SNIOC_CONFIGURE` + +.. c:macro:: SNIOC_RESET + + This will perform the SHT4X's soft reset command. + +.. code-block:: c + + err = ioctl(sensor, SNIOC_RESET); + if (err) { + fprintf(stderr, "SNIOC_RESET: %s\n", strerror(errno)); + } else { + puts("RESET success!"); + } + +.. c:macro:: SNIOC_WHO_AM_I + +This command reads the serial number of the SHT4X sensor. The serial number is +returned in the argument to the command, which must be a `uint32_t` pointer. + +.. code-block:: c + + uint32_t serialno = 0; + err = ioctl(sensor, SNIOC_WHO_AM_I, &serialno); + +.. c:macro:: SNIOC_READ_RAW_DATA + +This command allows the caller to read the raw data returned from the sensor, +without the driver performing any calculation to convert it into familiar units +(i.e. degrees Celsius for temperature). + +The argument to this command must be a pointer to a `struct sht4x_raw_data_s` +structure. The raw data will be returned here. + +.. code-block:: c + + struct sht4x_raw_data_s raw; + err = ioctl(sensor, SNIOC_READ_RAW_DATA, &raw); + +.. c:macro:: SNIOC_MEASURE + +This command will measure temperature and humidity, and return it in familiar +units to the user. Temperature will be in degrees (Fahrenheit or Celsius depends +on the Kconfig options selected during compilation) and humidity will be %RH. + +The argument to this command must be a pointer to a `struct sht4x_conv_data_s`. +This is where the converted data will be returned. + +.. code-block:: c + + struct sht4x_conv_data_s data; + err = ioctl(sensor, SNIOC_MEASURE, &data); + +.. c:macro:: SNIOC_READ_CONVERT_DATA + +Same as `SNIOC_MEASURE`. + +.. c:macro:: SNIOC_HEAT + +This command will instruct the SHT4X to turn on its heater unit for the +specified time. Afterwards, a measurement of temperature and humidity is taken, +and the converted data is returned to the caller. + +The argument to this command must be a pointer to a `struct sht4x_conv_data_s`. +This is where the converted data will be returned. The `temperature` field of +the struct must contain a value from the `enum sht4x_heater_e`, which will +indicate the duration the heater is on and the power used. + +Heating commands are not allowed more than once per second to avoid damaging the +sensor. If a command is issued before this one second cool-down period is over, +`EAGAIN` is returned. + +.. code-block:: c + + struct sht4x_conv_data_s data; + data.temp = SHT4X_HEATER_200MW_1; + err = ioctl(sensor, SNIOC_HEAT, &data); + +.. c:macro:: SNIOC_CONFIGURE + +This command allows the caller to configure the precision of the SHT4X sensor +used by subsequent measurement commands. By default, the sensor starts at high +precision. + +The argument to this command is one of the values in `enum sht4x_precision_e`. + +.. code-block:: c + + err = ioctl(sensor, SNIOC_CONFIGURE, SHT4X_PREC_LOW);