Re: [PATCH v11 8/8] docs: iio: describe inactivity and free-fall detection on the ADXL345

[Jonathan Cameron <jic23@kernel.org>]

On Wed,  2 Jul 2025 23:03:15 +0000
Lothar Rubusch <l.rubusch@gmail.com> wrote:

> Describe the inactivity detection additionally using the free-fall
> register. Due to the controversial discussions on the mailing list, this
> section of the documentation will be committed separately to allow for a
> more focused and detailed elaboration of the topic.
> 
> Signed-off-by: Lothar Rubusch <l.rubusch@gmail.com>
> ---
>  Documentation/iio/adxl345.rst | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/Documentation/iio/adxl345.rst b/Documentation/iio/adxl345.rst
> index 8ee01b8b87f4..c5525267ea12 100644
> --- a/Documentation/iio/adxl345.rst
> +++ b/Documentation/iio/adxl345.rst
> @@ -150,6 +150,31 @@ functions, so that one follows the other. The auto-sleep function puts the
>  sensor into sleep mode when inactivity is detected, reducing power consumption
>  to the sub-12.5 Hz rate.
>  
> +The inactivity time is configurable between 1 and 255 seconds. In addition to
> +inactivity detection, the sensor also supports free-fall detection, which, from
> +the IIO perspective, is treated as a fall in magnitude across all axes. In
> +sensor terms, free-fall is defined using an inactivity period ranging from 0.000
> +to 1.000 seconds.
> +
> +The driver behaves as follows:
> +* If the configured inactivity period is 1 second or more, the driver uses the
> +  sensor's inactivity register. This allows the event to be linked with
> +  activity detection, use auto-sleep, and be either AC- or DC-coupled.
> +
> +* If the inactivity period is less than 1 second, the event is treated as plain
> +  inactivity or free-fall detection. In this case, auto-sleep and coupling
> +  (AC/DC) are not applied.
> +
> +* If an inactivity time of 0 seconds is configured, the driver selects a
> +  heuristically determined default period (greater than 1 second) to optimize
> +  power consumption. This also uses the inactivity register.
> +
> +Note: It is recommended to use the activity, inactivity, or free-fall registers
> +when operating with an ODR between 12.5 Hz and 400 Hz.

This seems a tiny bit backwards.   It is recommend that the activity, inactivity or
free-fall registers are only used when operating with an ODR...

As currently written it seems to be recommending that if you want those sampling
frequencies you should also enable one of these detectors.

Reminds me of the classic London underground sign that said "Dogs must be
carried." which raised the question of how people with out dogs were meant to travel.

Otherwise this new section looks good to me.  Thanks,

Jonathan


> According to the
> +datasheet, the recommended free-fall threshold is between 300 mg and 600 mg
> +(register values 0x05 to 0x09), and the suggested free-fall time ranges from
> +100 ms to 350 ms (register values 0x14 to 0x46).
> +
>  In DC-coupled mode, the current acceleration magnitude is directly compared to
>  the values in the THRESH_ACT and THRESH_INACT registers to determine activity or
>  inactivity. In contrast, AC-coupled activity detection uses the acceleration