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. 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
-- 
2.39.5

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

Hi

On Sun, Jul 6, 2025 at 6:16 PM Jonathan Cameron <jic23@kernel.org> wrote:
>
> 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...
>

Ehm, Doesn't the sensor always have an ODR? The real question is which
ODR should be configured. There are recommendations for specific
features. I may have either misunderstood or misdocumented this part.

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

Ah, no. The other way around, when someone wants one of events
detected, the recommended frequencies should be used. I'll have a look
at it.

> 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
>...

Best,
Lothar

On Sun, 20 Jul 2025 20:49:48 +0200
Lothar Rubusch <l.rubusch@gmail.com> wrote:

> Hi
> 
> On Sun, Jul 6, 2025 at 6:16 PM Jonathan Cameron <jic23@kernel.org> wrote:
> >
> > 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...
> >  
> 
> Ehm, Doesn't the sensor always have an ODR? 
I was lazy. The ODR... was meant to be ODR between 12.5 Hz and 400 Hz (so original text
for that bit).

> The real question is which
> ODR should be configured. There are recommendations for specific
> features. I may have either misunderstood or misdocumented this part.
> 
> > As currently written it seems to be recommending that if you want those sampling
> > frequencies you should also enable one of these detectors.
> >  
> 
> Ah, no. The other way around, when someone wants one of events
> detected, the recommended frequencies should be used. I'll have a look
> at it.

Sounds like you got my rubbish explanation.

> 
> > 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
> >...  
> 
> Best,
> Lothar