Re: [PATCH v9 11/11] docs: iio: add documentation for adxl345 driver

[Jonathan Cameron <jic23@kernel.org>]

On Tue, 10 Jun 2025 21:59:33 +0000
Lothar Rubusch <l.rubusch@gmail.com> wrote:

> The documentation describes the ADXL345 driver, IIO interface,
> interface usage and configuration.

Trivial but wrap commit descriptions at 75 chars.

The main comment on this is that, when talking about datasheet terms / settings
etc it would be good to reflect them back to the IIO controls that actually allow
us to change them.

Otherwise seems reasonable to me.

> 
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>


> +
> +Sensor Events
> +-------------
> +
> +Particular IIO events will be triggered by the corresponding interrupts. The
> +sensor driver supports no or one active INT line, where the sensor has two
> +possible INT IOs. Configure the used INT line in the devicetree. If no INT line
> +is configured, the sensor falls back to FIFO bypass mode and no events are
> +possible, only X, Y and Z axis measurements are possible.
> +
> +The following table shows the ADXL345 related device files, found in the
> +specific device folder path ``/sys/bus/iio/devices/iio:deviceX/events``.
> +Note, the default activity/inactivity is DC coupled. Thus only AC coupled
> +activity and inactivity are mentioned explicitly.

This paragraph probably wants to talk about the mapping of AC coupled to 'adaptive'
I couldn't relate it directly to the table without that.

> +
> ++---------------------------------------------+---------------------------------------------+
> +| Event handle                                | Description                                 |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_gesture_doubletap_en               | Enable double tap detection on all axis     |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_gesture_doubletap_reset_timeout    | Double tap window in [us]                   |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_gesture_doubletap_tap2_min_delay   | Double tap latent in [us]                   |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_gesture_singletap_timeout          | Single tap duration in [us]                 |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_gesture_singletap_value            | Single tap threshold value in 62.5/LSB      |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_falling_period                 | Inactivity time in seconds                  |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_falling_value                  | Inactivity threshold value in 62.5/LSB      |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_adaptive_rising_en             | Enable AC coupled activity on X axis        |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_adaptive_falling_period        | AC coupled inactivity time in seconds       |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold in 62.5/LSB |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold in 62.5/LSB   |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_rising_en                      | Enable activity detection on X axis         |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_mag_rising_value                   | Activity threshold value in 62.5/LSB        |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_x_gesture_singletap_en             | Enable single tap detection on X axis       |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_x&y&z_mag_falling_en               | Enable inactivity detection on all axis     |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_x&y&z_mag_adaptive_falling_en      | Enable AC coupled inactivity on all axis    |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_y_gesture_singletap_en             | Enable single tap detection on Y axis       |
> ++---------------------------------------------+---------------------------------------------+
> +| in_accel_z_gesture_singletap_en             | Enable single tap detection on Z axis       |
> ++---------------------------------------------+---------------------------------------------+
> +
> +Find a detailed description of a particular functionality in the sensor
> +datasheet.
> +
> +Setting the **ODR** explicitly will result in estimated adjusted default values

Say how to set ODR etc in IIO terms as well perhaps?

> +for the inactivity time detection, where higher frequencies shall default to
> +longer wait periods, and vice versa. It is also possible to explicitly
> +configure inactivity wait times, if the defaulting approach does not match
> +application requirements. Setting 0 here, will fall back to default setting.

I'm not particularly keen on that 0 aspect as it's unintuitive.  Why do we need
a means to go back to the default? 

> +
> +The **g range** configuration also tries to estimate activity and inactivity
> +thresholds when switching to another g range. The default range will be
> +factorized by the relation of old range divided by new range. The value never
> +becomes 0 and will be at least 1 and at most 255 i.e. 62.5g/LSB according to
> +the datasheet. Nevertheless activity and inactivity thresholds can be
> +overwritten by explicit values.