On Mon, 10 Feb 2025 11:01:19 +0000 Lothar Rubusch <l.rubusch@xxxxxxxxx> wrote: > The documentation describes the ADXL345 driver, IIO interface, > interface usage and configuration. > > Signed-off-by: Lothar Rubusch <l.rubusch@xxxxxxxxx> Hi Lothar, I was running out of time so this was a little more superficial review than I would have liked to have done. I've commented on a few bits that I was confuse about in the driver. Document is showing how useful these are :) Jonathan > + > +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``. > + > ++---------------------------------------------+-----------------------------------------+ > +| 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_suppressedbit_en | Enable double tap suppress bit | > ++---------------------------------------------+-----------------------------------------+ > +| 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_en | Enable free fall detection | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_mag_falling_period | Free fall time in [us] | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_mag_falling_value | Free fall threshold value in 62.5/LSB | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_mag_referenced_falling_en | Set 1 to couple inactivity AC, 0 for DC | That interface doesn't work align with the normal ABI. Should be a selection of either mag_referenced_falling_en or another event to pick between AC and DC. I assume thresh_falling_en though i'll admit to being a little lost in what this hardware is doing! > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_mag_referenced_rising_en | Set 1 to couple activity AC, 0 for DC | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_thresh_falling_en | Enable inactivity detection | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_thresh_falling_period | Inactivity time in seconds | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_thresh_falling_value | Inactivity threshold value in 62.5/LSB | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_thresh_rising_en | Enable activity detection | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_thresh_rising_value | Activity threshold value in 62.5/LSB | > ++---------------------------------------------+-----------------------------------------+ > +| in_accel_x_gesture_singletap_en | Enable single tap detection on X 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 > +for the inactivity time detection, where higher frequencies shall default to > +longer wait periods, and vice versa. It is also possible to explicetly > +configure inactivity wait times, if the defaulting approach does not match > +application requirements. Setting 0 here, will fall back to default setting. > + > +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. > + > +When activity and inactivity events are enabled, the driver automatically will > +set link bit and autosleep bit. The link bit serially links the activity and > +inactivity functions. So this is a sort of hysteresis? We may want to describe that more directly. > On the other side, the autosleep function switches the > +sensor to sleep mode if the inactivity function is enabled. This will reduce > +current consumption to the sub-12.5Hz rate. > + > +In dc-coupled operation, the current acceleration magnitude is compared > +directly with THRESH_ACT and THRESH_INACT registers to determine whether > +activity or inactivity was detected. In ac-coupled operation for activity > +detection, the acceleration value at the start of activity detection is taken > +as a reference value. New samples are then compared to this reference value. That applies for activity - the inactivity description is rather more confusing. > + > +Single tap detection can be configured according to the datasheet by specifying > +threshold and duration. If only the single tap is in use, the single tap > +interrupt is triggered when the acceleration goes above threshold (i.e. DUR > +start) and below the threshold, as long as duration is not exceeded. If single > +tap and double tap are in use, the single tap is triggered when the doulbe tap > +event has been either validated or invalidated. > + > +For double tap configure additionally window and latency in [us]. Latency > +starts counting when the single tap goes below threshold and is a waiting > +period, any spikes here are ignored for double tap detection. After latency, > +the window starts. Any rise above threshold, with a consequent fall below > +threshold within window time, rises a double tap signal when going below > +threshold. > + > +A double tap event can be invalidated in three ways: If the suppress bit is set, > +any acceleration spike above the threshold already during the latency time > +invalidates the double tap detection immediately, i.e. during latence must not > +occur spikes for double tap detection with suppress bit set. > +A double tap event is invalidated if acceleration lies above the threshold at > +the start of the window time for the double tap detection. > +Additionally a double tap event can be invalidated if an acceleration exceeds > +the time limit for taps, set by duration register, since also for the double > +tap the same value for duration counts, i.e. when rising above threshold the > +fall below threshold has to be within duration time. > + > +A free fall event will be detected if the signal goes below the configured > +threshold, for the configured time [us]. > + > +Note, that activity/inactivy, as also freefall is recommended for 12.5 Hz ODR > +up to 400 Hz. > + >
