Add functions to set the range and rate

[sandeepmistry]

Feedback from @tigoe.

Would be good to add functions to set the range and rate, like with the old CurieIMU.

@cmaglie was there any reason why this wasn't included in the original MotionSense.h spec?

[cmaglie]

No, we just didn't think about it.

BTW, what's the use-case for those functions?

[tigoe]

For one, to make it compatible with the madgwick library. It requires you to set sensitivity and resolution -- or at least to know them. For another, say you want a different sensitivity. For example, boxing punches terminate in 10-100G deceleration. A project using these as boxing gloves sensors, like one I had in class last year, would benefit from being able to change the sensitivity. For the tap feature, there are lots of applications where you might want to tap the board to initiate action. Tap to wake up lights, tap to start a musical sequence, etc. In general though, if a part has a major feature like these, a public API will make them more valuable.

[cmaglie]

we can add a method like:

IMU.setAccelerometerRange(5.5)

that would give you the best sensitivity available for the given range (the sensor may have fixed ranges available say, 2G, 4G, 8G, in this case 8G will be selected to achieve the requested 5.5).

[cmaglie]

About setting the reading frequency, we have a similar problem: the possible reading frequencies available may not match the requested one. This may lead to some troubles if you do calculations that involve time and you expect, say, 100 samples per second but you instead get 125.

The only way that comes to mind is to make two methods, one to set the desired frequency and another to query the real one:

IMU.setReadingFrequency(100.0);
float hz = IMU.getReadingFrequency();  // hz maybe be very different from 100.0

maybe it's worth using a name that implies that setting the frequency may not be accurate:

IMU.setReadingFrequencyAsCloseAsPossibleTo(100.0);

[tigoe]

Why not just do it like it's done in CurieIMU? If they give a value that's not acceptable, throw an error or round to the closest acceptable. T

[tigoe]

Or give them constants for the acceptable values

[cmaglie]

We can surely include the specific values for the LSM6DS3 in the Arduino_LSM6DS3 library (and we could probably do that right now without much thinking).

What I want to achieve here is to find a "common" base class like the MotionSense.h, otherwise all the examples we make for the LSM6DS3 will be usable only on this sensor with this library (unless we start to tweak constants and values to make it work with another sensor/library).

So here I'm basically following Sandeep's question:

was there any reason why this wasn't included in the original MotionSense.h spec?

the reason is that we should basically think about a generic API that fits well on all sensors, so:

• the measuring range could be surely approximated, the sensor would always return the best value it can within the requested range
• about the sampling frequency there isn't much we can do, probably the sensor has his own sampling frequency (or just a few to choose from), so we could probably set the closest one but this could be very different from the one requested.

[tigoe]

One way to look at it: many IMUs have similar ranging patrenrs. For example, I've seen many where the options were 4, 4, 8, 16G for acceleration. Maybe a way to take advantage of that. There's another library with a similar constraints problem: Serial. Even though you can set any rate theoretically, only certain rates work. With that library, we rely on documentation and well-known standards to make sure people do the right thing. We could take the same approach here. For example, make the common API permissive in what it takes, but set good examples by making good constants for the specific IMUs we write for. Then encourage others to do the same for other IMUs that would use the same common library. You can't protect the user from doing some things wrong if you want to support flexibility. But you can show them a few ways to do things right. That usually has good effect. T