Re: [v3 13/13] docs: iio: add documentation for BNO055 driver

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 17 Feb 2022 17:27:10 +0100
Andrea Merello <andrea.merello@gmail.com> wrote:

Perhaps a comment on why it's worth having documentation for this device
when we rarely bother?  (complex device etc...)

> Signed-off-by: Andrea Merello <andrea.merello@iit.it>
> ---
>  Documentation/iio/bno055.rst | 53 ++++++++++++++++++++++++++++++++++++

Please add it to an appropriate index such as Docuemntation/iio/index.rst
so that it actually gets linked to in the documentation built.

One comment inline.

>  1 file changed, 53 insertions(+)
>  create mode 100644 Documentation/iio/bno055.rst
> 
> diff --git a/Documentation/iio/bno055.rst b/Documentation/iio/bno055.rst
> new file mode 100644
> index 000000000000..4bb185075325
> --- /dev/null
> +++ b/Documentation/iio/bno055.rst
> @@ -0,0 +1,53 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +==============================
> +BNO055 driver
> +==============================
> +
> +1. Overview
> +===========
> +
> +This driver supports Bosch BNO055 IMUs (on both serial and I2C busses).
> +
> +Accelerometer, magnetometer and gyroscope measures are always provided.
> +When "fusion_enable" sysfs attribute is set to 1, orientation (both Euler
> +angles and quaternion), linear velocity and gravity vector are also
> +provided, but some sensor settings (e.g. low pass filtering and range)
> +became locked (the IMU firmware controls them).
> +
> +IIO attributes for unavailable measurements (e.g. Euler angles when fusion
> +mode is disabled) just read zero.

Hmm. Should probably return -EBUSY as 0 could be a valid value.

> +
> +This driver supports also IIO buffers.
> +
> +2. Calibration
> +==============
> +
> +The IMU continuously performs an autocalibration procedure if (and only if)
> +operating in fusion mode. The magnetometer autocalibration can however be
> +disabled writing 0 in the sysfs in_magn_calibration_fast_enable attribute.
> +
> +The driver provides access to autocalibration flags (i.e. you can known if
> +the IMU has successfully autocalibrated) and to the calibration data blob.
> +
> +The user can save this blob in a firmware file (i.e. in /lib/firmware) that
> +the driver looks for at probe time. If found, then the IMU is initialized
> +with this calibration data. This saves the user from performing the
> +calibration procedure every time (which consist of moving the IMU in
> +various way).
> +
> +The driver looks for calibration data file using two different names: first
> +a file whose name is suffixed with the IMU unique ID (exposed in sysfs as
> +serial_number) is searched for; this is useful when there is more than one
> +IMU instance. If this file is not found, then a "generic" calibration file
> +is searched for (which can be used when only one IMU is present, without
> +struggling with fancy names, that change on each device).
> +
> +Valid calibration file names would be e.g.
> + bno055-caldata-0e7c26a33541515120204a35342b04ff.dat
> + bno055-caldata.dat
> +
> +In non-fusion mode the IIO 'offset' attributes provide access to the
> +offsets from calibration data (if any), so that the user can apply them to
> +the accel, angvel and magn IIO attributes. In fusion mode they are not
> +needed (the IMU firmware internally applies those corrections) and they
> +read as zero.