This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new e959e0062e 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.
e959e0062e is described below
commit e959e0062e97cb5c4ddb7afeea6b2b07019e648a
Author: Matteo Golin <[email protected]>
AuthorDate: Thu Oct 3 13:36:14 2024 -0400
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 ++----------
.../components/drivers/special/sensors/adt7320.rst | 7 ++
.../components/drivers/special/sensors/adxl345.rst | 13 +++
.../components/drivers/special/sensors/adxl362.rst | 4 +
.../components/drivers/special/sensors/adxl372.rst | 15 +++
.../components/drivers/special/sensors/aht10.rst | 4 +
.../components/drivers/special/sensors/ak09912.rst | 4 +
.../components/drivers/special/sensors/lsm330.rst | 17 +++
.../components/drivers/special/sensors/mpl115a.rst | 7 ++
.../components/drivers/special/sensors/sht4x.rst | 127 +++++++++++++++++++++
10 files changed, 205 insertions(+), 63 deletions(-)
diff --git a/Documentation/components/drivers/special/sensors.rst
b/Documentation/components/drivers/special/sensors.rst
index 55ed308e4a..53dff63e27 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 0000000000..1c371d4b9e
--- /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 0000000000..062ce2ccb2
--- /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 0000000000..7926cdbca0
--- /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 0000000000..222819ddf2
--- /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 0000000000..7af72236b4
--- /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 0000000000..b641eb2eba
--- /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 0000000000..8dbebb9ad6
--- /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 0000000000..e5c0cad172
--- /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 0000000000..56991b3061
--- /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 <nuttx/sensors/sht4x.h>
+
+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);
