jevois::ICM20948 Class Reference

#include <jevois/Core/ICM20948.H>

TDK InvenSense ICM-20948 9DOF IMU high-level driver.

This driver communicates with a kernel-side driver that is integrated with the camera sensor driver on some optional JeVois sensors only. Currently, on JeVois-A33, only the OnSemi (Aptina) AR0135 global shutter optional camera sensor is equipped with an IMU. On JeVois-Pro, all camera sensors are equipped with an IMU.

The specifications of this chip are quite impressive:

• 3-axis 16-bit accelerometer with full-range sensitivity selectable to +/-2g, +/-4g, +/-8g, and +/-16g.
• Accelerometer data rate from 4 Hz to 1125 Hz.
• 3-axis 16-bit gyroscope with full-range sensitivity selectable to +/-250dps (degrees/s), +/-500dps, +/-1000dps, and +/-2000dps.
• Gyroscope data rate from 4 Hz to 1125 Hz.
• 3-axis 16-bit magnetometer (compass) with wide range of +/-4900uT (micro Tesla).
• Magnetometer data rates 10 Hz, 20 Hz, 50 Hz, or 100 Hz.
• 16-bit temperature sensor with readout rate of up to 8 kHz.
• RAW data mode (get current sensor values at any time), buffered (FIFO) data mode (sensor values accumulate into a FIFO at a fixed rate), and digital motion processing mode (DMP; raw data is processed on-chip).
• On-chip digital motion processor (DMP) can compute, inside the IMU chip itself:
  • quaternion 6 (uses accel + gyro),
  • quaternion 9 (uses accel + gyro + compass),
  • geomag quaternion (uses accel + compass),
  • flip/pickup detection,
  • step detection and counting,
  • basic activity recognition: drive, walk, run, bike, tilt, still.

With quaternions computed on-chip, with an algorithm that gets sensor data at a highly accurate, fixed rate, and applies various calibrations, drift corrections, and compensations on the fly, one gets highly accurate real-time estimate of the sensor's pose in the 3D world and of how it is moving.

Note that on JeVois-A33 communication with the IMU is over a 400kHz I2C bus, which may limit data readout rate depending on which data is requested from the IMU. On JeVois-Pro, communication is over SPI at 7MHz.

This IMU has 3 basic modes of operation (parameter mode, which can only be set in params.cfg):

• RAW: One can access the latest raw sensor data at any time using the getRaw() or get() functions. This is the simplest mode of operation. One disadvantage is that if you are not calling get() at a perfectly regular interval, there will be some time jitter in your readouts. The IMU does not provide any time stamps for its data.
• FIFO: In this mode, data from the sensor is piled up into a 1 kbyte FIFO buffer at a precise, constant rate (when all three of accelerometer, gyroscope, and magnetometer are on, the gyro rate determines the FIFO buffering rate). Main advantage is that you can then read out the data without having to worry about calling getRaw() or get() at a highly precise interval. But you need to be careful that the FIFO can fill up and overflow very quickly when using high sensor data rates.
• DMP: In this mode, data is captured from the sensor at an accurate, fixed rate, and is fed to the on-chip digital motion processor (DMP). The DMP then computes quaternions, activity recognition, etc and pushes data packets into the FIFO as results from these algorithms become available.

CAUTION: This class has state and is not re-entrant. Namely, we store the current register bank of the IMU chip in a class member variable. This could get out of sync if several member functions of this class are called concurrently. Because we assume this will not be the case in normal operation, we do not protect chip access with a mutex. Users should use an external mutex to protect this class if used in a multithreaded manner.

Definition at line 199 of file ICM20948.H.

Inheritance diagram for jevois::ICM20948:

Collaboration diagram for jevois::ICM20948:

Public Member Functions
	ICM20948 (std::string const &instance)
	Constructor, low-level communication driver is null.
virtual	~ICM20948 ()
	Virtual destructor for safe inheritance.
bool	ready ()
	Returns true if this camera indeed has a working ICM20948.
int	dataReady ()
	Returns the amount of new data that had not previously been obtained.
IMUrawData	getRaw (bool blocking=true)
	Get one round of raw data.
IMUdata	get (bool blocking=true)
	Get one round of scaled raw data.
DMPdata	getDMP (bool blocking=true)
	Get one packet of DMP data.
Public Member Functions inherited from jevois::Component
	Component (std::string const &instance)
	Constructor.
virtual	~Component ()
	Virtual destructor for safe inheritance.
template<class Comp , typename... Args>
std::shared_ptr< Comp >	addSubComponent (std::string const &instance, Args &&...args)
	Pseudo-constructor: construct and add another component as a subcomponent of this one.
template<class Comp >
void	removeSubComponent (std::shared_ptr< Comp > &component)
	Remove a sub-Component from this Component, by shared_ptr.
void	removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
	Remove a sub-Component from this Component, by instance name.
template<class Comp = jevois::Component>
std::shared_ptr< Comp >	getSubComponent (std::string const &instance) const
	Get a sub-component by instance name.
bool	isTopLevel () const
	Returns true if this component is top-level, i.e., its parent is jevois::Manager.
bool	initialized () const
	Has this component been initialized yet?
std::string const &	className () const
	The class name of this component.
std::string const &	instanceName () const
	The instance name of this component.
template<typename T >
std::vector< std::string >	setParamVal (std::string const &paramdescriptor, T const &val)
	Set a parameter value.
template<typename T >
void	setParamValUnique (std::string const &paramdescriptor, T const &val)
	Set a parameter value, simple version assuming only one parameter match.
template<typename T >
std::vector< std::pair< std::string, T > >	getParamVal (std::string const &paramdescriptor) const
	Get parameter(s) value(s) by descriptor.
template<typename T >
T	getParamValUnique (std::string const &paramdescriptor) const
	Get a parameter value, simple version assuming only one parameter match.
std::vector< std::string >	setParamString (std::string const &paramdescriptor, std::string const &val)
	Set a parameter value, by string.
void	setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
	Set a parameter value by string, simple version assuming only one parameter match.
std::vector< std::pair< std::string, std::string > >	getParamString (std::string const &paramdescriptor) const
	Get a parameter value, by string.
std::string	getParamStringUnique (std::string const &paramdescriptor) const
	Get a parameter value by string, simple version assuming only one parameter match.
void	freezeParam (std::string const &paramdescriptor, bool doit)
	Freeze/unfreeze a parameter, by name, see ParameterBase::freeze()
void	freezeAllParams (bool doit)
	Freeze all parameters.
std::string	descriptor () const
	Get our full descriptor (including all parents) as [Instancename]:[...]:[...].
void	setParamsFromFile (std::string const &filename)
	Set some parameters from a file.
std::istream &	setParamsFromStream (std::istream &is, std::string const &absfile)
	Set some parameters from an open stream.
virtual void	paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
	Get machine-oriented descriptions of all parameters.
void	foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
	Run a function on every param we hold.
template<typename T >
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
	Add a new parameter after the Component has already been constructed.
template<typename T , template< typename > class ValidValuesSpec>
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
	Add a new parameter after the Component has already been constructed.
template<typename T >
void	setDynamicParameterCallback (std::string const &name, std::function< void(T const &)> cb, bool callnow=true)
	Register a callback with a previously created dynamic parameter.
void	removeDynamicParameter (std::string const &name, bool throw_if_not_found=true)
	Remove a previously added dynamic parameter.
void	setPath (std::string const &path)
	Assign a filesystem path to this component.
std::filesystem::path	absolutePath (std::filesystem::path const &path="")
	If given path is relative (not starting with /), prepend the Component path to it.
Public Member Functions inherited from jevois::ParameterRegistry
virtual	~ParameterRegistry ()
	Virtual destructor for safe inheritance.

Protected Member Functions
void	preInit () override
	Connect to and initialize the IMU chip.
void	postInit () override
	Configure RAW vs DMP mode:
void	preUninit () override
	Unfreeze any previously frozen parameters.
void	reset ()
	Reset the IMU chip - not recommended in normal operation.
void	sleep (bool enable)
	Turn on/off sleep mode.
void	cycle (bool enable)
	Turn on/off cycle mode vs continuous for accel, gyro and compass.
uint32_t	devid ()
	Read device ID.
Protected Member Functions inherited from jevois::Component
virtual void	postUninit ()
	Called after all sub-Components are uninit()ed.
Protected Member Functions inherited from jevois::ParameterRegistry
void	addParameter (ParameterBase *const param)
	The Parameter class uses this method to register itself on construction with its owning Component.
void	removeParameter (ParameterBase *const param)
	The Parameter class uses this method to un-register itself on destruction with its owning Component.
void	callbackInitCall ()
	For all parameters that have a callback which has never been called, call it with the default param value.

Related Symbols
(Note that these are not member symbols.)
	JEVOIS_DEFINE_ENUM_CLASS (Mode,(RAW)(FIFO)(DMP))
	Enum for Parameter.
	JEVOIS_DECLARE_PARAMETER (mode, Mode, "Data collection mode. RAW means that the latest available raw " "data is returned each time get() is called, hence timing may not be very " "accurate depending on how regularly get() is called. FIFO collects accel and gyro data " "at the exact rates specified by parameters arate, grate into a 1kb FIFO queue, and " "get() takes that data back from the FIFO. DMP runs the embedded " "digital motion processor on raw data, and accumulates resulting output " "data into the IMU's internal FIFO buffer at a precise, fixed rate. This " "parameter can only be set in a module's params.cfg file.", Mode::RAW, Mode_Values, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (dmp, std::string, "Requested DMP data. Only valid when mode is DMP. " "Use any string of letters including:" "A=acceleration, " "G=gyro, " "M=magnetometer (compass), " "R=quaternion 6 (uses accel + gyro), " "Q=quaternion 9 (uses accel + gyro + compass), " "E=geomag (uses accel + compass), " "P=flip/pickup detection, " "S=step detection, " "T=activity recognition, " "F=frame sync from video sensor, " "w=configure activity recognition for wearable, " "g=gyro calibration (always on when gyro used), " "m=compass calibration (always on when compass used), " "b=accel accuracy (always on when accel used), " "h=gyro accuracy (always on when gyro used), " "n=compass accuracy (always on when compass used).", "QSPT", ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (pktdbg, bool, "Send raw FIFO or DMP packets to console for debug/hacking purposes.", false, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (arate, float, "Accelerometer sampling rate (Hz), or 0.0 to disable " "accelerometer. Actual sample rate may differ because of finite and " "discrete divider settings. In FIFO mode, grate controls the data rate.", 30.0F, jevois::Range< float >(0.0F, 1125.0F), ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (grate, float, "Gyroscope sampling rate (Hz), or 0.0 to disable " "gyroscope. Actual sample rate may differ because of finite and " "discrete divider settings. In FIFO mode, grate controls the data rate.", 30.0F, jevois::Range< float >(0.0F, 1125.0F), ParamCateg)
	Parameter.
	JEVOIS_DEFINE_ENUM_CLASS (MagRate,(Off)(Once)(M10Hz)(M20Hz)(M50Hz)(M100Hz))
	Enum for Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (mrate, MagRate, "Magnetometer sampling rate (Hz), or Off to disable " "magnetometer, or Once to only get one measurement. You can repeatedly " "set this parameter to Once to obtain repeated measurements " "at your own pace. In JeVois Inventor, you need to alternate between " "Off and Once. In FIFO mode, grate controls the data rate.", MagRate::M50Hz, MagRate_Values, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (abw, unsigned int, "Accelerometer bandwidth rate (Hz), or 0 for no " "low-pass filter on accelerometer data.", 50, { 0, 6, 12, 24, 50, 111, 246, 470, 1210 }, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (gbw, unsigned int, "Gyroscope bandwidth rate (Hz), or 0 for no low-pass " "filter on gyroscope data.", 51, { 0, 6, 12, 24, 51, 120, 150, 200, 360, 12100 }, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (tbw, unsigned int, "Temperature bandwidth rate (Hz), or 0 to turn off " "temperature sensor. Temperature sampling rate is always 1125Hz unless " "tbw is 7932, in which case sampling is at 9kHz.", 34, { 0, 9, 17, 34, 66, 123, 218, 7932 }, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (arange, unsigned int, "Accelerometer full-scale range (+/-g for example, " "2 means +/-2g)).", 4, { 2, 4, 8, 16 }, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK (grange, unsigned int, "Gyroscope full-scale range (+/-dps for example, " "500 means +/-500 degrees per second)).", 500, { 250, 500, 1000, 2000 }, ParamCateg)
	Parameter.

Constructor & Destructor Documentation

ICM20948()

jevois::ICM20948::ICM20948

(

std::string const &

instance

)

Constructor, low-level communication driver is null.

Definition at line 62 of file ICM20948.C.

~ICM20948()

jevois::ICM20948::~ICM20948 ( void  )

virtual

Virtual destructor for safe inheritance.

Definition at line 67 of file ICM20948.C.

Member Function Documentation

cycle()

void jevois::ICM20948::cycle ( bool  enable )

protected

Turn on/off cycle mode vs continuous for accel, gyro and compass.

Definition at line 684 of file ICM20948.C.

dataReady()

int jevois::ICM20948::dataReady

(

)

Returns the amount of new data that had not previously been obtained.

In RAW mode, this is either 0 or 1. In FIFO or DMP mode, returns length in bytes of new data in the FIFO.

Definition at line 258 of file ICM20948.C.

devid()

uint32_t jevois::ICM20948::devid ( )

protected

Read device ID.

Definition at line 695 of file ICM20948.C.

get()

jevois::IMUdata jevois::ICM20948::get

(

bool

blocking = true

)

Get one round of scaled raw data.

In RAW or DMP mode, this is the latest available, and blocking has no effect as some latest data always is available immediately. In FIFO mode, this is the oldest data in the FIFO, and we may block if the FIFO is currently empty.

Definition at line 375 of file ICM20948.C.

getDMP()

jevois::DMPdata jevois::ICM20948::getDMP

(

bool

blocking = true

)

Get one packet of DMP data.

Will throw if mode is not set to DMP. If blocking is true, will block until one new data packet is available from the IMU; otherwise, may return DMPdata with contents set to zero.

Definition at line 381 of file ICM20948.C.

References jevois::DMPpacketSize(), JEVOIS_DMP_HEADER2, LFATAL, LINFO, and jevois::DMPdata::parsePacket().

getRaw()

jevois::IMUrawData jevois::ICM20948::getRaw

(

bool

blocking = true

)

Get one round of raw data.

In RAW or DMP mode, this is the latest available, and blocking has no effect as some latest data always is available immediately. In FIFO mode, this is the oldest data in the FIFO, and we may block if the FIFO is currently empty.

Definition at line 280 of file ICM20948.C.

References jevois::IMUrawData::ax(), jevois::IMUrawData::ay(), jevois::IMUrawData::az(), jevois::IMUrawData::gx(), jevois::IMUrawData::gy(), jevois::IMUrawData::gz(), LERROR, LINFO, jevois::IMUrawData::mst2(), jevois::IMUrawData::mx(), jevois::IMUrawData::my(), jevois::IMUrawData::mz(), jevois::IMUrawData::temp(), and jevois::IMUrawData::v.

postInit()

void jevois::ICM20948::postInit ( )

overrideprotectedvirtual

Configure RAW vs DMP mode:

Reimplemented from jevois::Component.

Definition at line 164 of file ICM20948.C.

References LINFO.

preInit()

void jevois::ICM20948::preInit ( )

overrideprotectedvirtual

Connect to and initialize the IMU chip.

Reimplemented from jevois::Component.

Definition at line 114 of file ICM20948.C.

References LFATAL, and LINFO.

preUninit()

void jevois::ICM20948::preUninit ( )

overrideprotectedvirtual

Unfreeze any previously frozen parameters.

Reimplemented from jevois::Component.

Definition at line 246 of file ICM20948.C.

ready()

bool jevois::ICM20948::ready

(

)

Returns true if this camera indeed has a working ICM20948.

Definition at line 252 of file ICM20948.C.

reset()

void jevois::ICM20948::reset ( void  )

protected

Reset the IMU chip - not recommended in normal operation.

Definition at line 462 of file ICM20948.C.

sleep()

void jevois::ICM20948::sleep ( bool  enable )

protected

Turn on/off sleep mode.

Definition at line 669 of file ICM20948.C.

Friends And Related Symbol Documentation

JEVOIS_DECLARE_PARAMETER() [1/2]

JEVOIS_DECLARE_PARAMETER ( mode  , Mode  , "Data collection mode. RAW means that the latest available raw " "data is returned each time get() is  called, hence timing may not be very " "accurate depending on how regularly get() is called. FIFO collects accel and gyro data " "at the exact rates specified by parameters  arate, grate into a 1kb FIFO  queue, and " "get() takes that data back from the FIFO. DMP runs the embedded " "digital motion processor on raw  data, and accumulates resulting output " "data into the IMU 's internal FIFO buffer at a  precise, fixed rate. This " "parameter can only be set in a module 's params.cfg file."  , Mode::RAW  , Mode_Values  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [2/2]

JEVOIS_DECLARE_PARAMETER ( pktdbg  , bool  , "Send raw FIFO or DMP packets to console for debug/hacking purposes."  , false  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [1/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( abw  , unsigned int  , "Accelerometer bandwidth rate   Hz, or 0 for no " "low-pass filter on accelerometer data."  , 50  , { 0, 6, 12, 24, 50, 111, 246, 470, 1210 }  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [2/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( arange  , unsigned int  , "Accelerometer full-scale range   +/-g for example, " "2 means +/-2g  )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [3/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( arate  , float  , "Accelerometer sampling rate   Hz, or 0.0 to disable " "accelerometer. Actual sample rate may differ because of finite and " "discrete divider settings. In FIFO  mode, grate controls the data rate."  , 30.  0F, jevois::Range< float >  0.0F, 1125.0F, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [4/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( dmp  , std::string  , "Requested DMP data. Only valid when mode is DMP. " "Use any string of letters including:" "  A = acceleration, " "  G = gyro, " "  M = magnetometer (compass), " "  R = quaternion 6 (uses accel + gyro), " "  Q = quaternion 9 (uses accel + gyro + compass), " "  E = geomag (uses accel + compass), " "  P = flip/pickup detection, " "  S = step detection, " "  T = activity recognition, " "  F = frame sync from video sensor, " "  w = configure activity recognition for wearable, " "  g = gyro calibration (always on when gyro used), " "  m = compass calibration (always on when compass used), " "  b = accel accuracy (always on when accel used), " "  h = gyro accuracy (always on when gyro used)  )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [5/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( gbw  , unsigned int  , "Gyroscope bandwidth rate   Hz, or 0 for no low-pass " "filter on gyroscope data."  , 51  , { 0, 6, 12, 24, 51, 120, 150, 200, 360, 12100 }  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [6/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( grange  , unsigned int  , "Gyroscope full-scale range   +/-dps for example, " "500 means +/-500 degrees per second  )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [7/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( grate  , float  , "Gyroscope sampling rate   Hz, or 0.0 to disable " "gyroscope. Actual sample rate may differ because of finite and " "discrete divider settings. In FIFO  mode, grate controls the data rate."  , 30.  0F, jevois::Range< float >  0.0F, 1125.0F, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [8/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( mrate  , MagRate  , "Magnetometer sampling rate   Hz, or Off to disable " "  magnetometer, or Once to only get one measurement. You can repeatedly " "set this parameter to Once to obtain repeated measurements " "at your own pace. In JeVois  Inventor, you need to alternate between " "Off and Once. In FIFO  mode, grate controls the data rate."  , MagRate::M50Hz  , MagRate_Values  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK() [9/9]

JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK ( tbw  , unsigned int  , "Temperature bandwidth rate   Hz, or 0 to turn off " "temperature sensor. Temperature sampling rate is always 1125Hz unless " "tbw is  7932, in which case sampling is at 9kHz."  , 34  , { 0, 9, 17, 34, 66, 123, 218, 7932 }  , ParamCateg    )

related

Parameter.

JEVOIS_DEFINE_ENUM_CLASS() [1/2]

JEVOIS_DEFINE_ENUM_CLASS ( MagRate  , (Off)(Once)(M10Hz)(M20Hz)(M50Hz)(M100Hz)    )

related

Enum for Parameter.

JEVOIS_DEFINE_ENUM_CLASS() [2/2]

JEVOIS_DEFINE_ENUM_CLASS ( Mode  , (RAW)(FIFO)(DMP)    )

related

Enum for Parameter.

---

The documentation for this class was generated from the following files:

• include/jevois/Core/ICM20948.H
• src/jevois/Core/ICM20948.C