JeVois  1.16
JeVois Smart Embedded Machine Vision Toolkit
Share this page:

#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. More...
 
virtual ~ICM20948 ()
 Virtual destructor for safe inheritance. More...
 
bool ready ()
 Returns true if this camera indeed has a working ICM20948. More...
 
int dataReady ()
 Returns the amount of new data that had not previously been obtained. More...
 
IMUrawData getRaw (bool blocking=true)
 Get one round of raw data. More...
 
IMUdata get (bool blocking=true)
 Get one round of scaled raw data. More...
 
DMPdata getDMP (bool blocking=true)
 Get one packet of DMP data. More...
 
- Public Member Functions inherited from jevois::Component
 Component (std::string const &instance)
 Constructor. More...
 
virtual ~Component ()
 Virtual destructor for safe inheritance. More...
 
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. More...
 
template<class Comp >
void removeSubComponent (std::shared_ptr< Comp > &component)
 Remove a sub-Component from this Component, by shared_ptr. More...
 
void removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
 Remove a sub-Component from this Component, by instance name. More...
 
template<class Comp = jevois::Component>
std::shared_ptr< Comp > getSubComponent (std::string const &instance) const
 Get a sub-component by instance name. More...
 
bool isTopLevel () const
 Returns true if this component is top-level, i.e., its parent is jevois::Manager. More...
 
Engineengine () const
 Get a handle to our Engine, or throw if we do not have an Engine as root ancestor. More...
 
bool initialized () const
 Has this component been initialized yet? More...
 
const std::string & className () const
 The class name of this component. More...
 
const std::string & instanceName () const
 The instance name of this component. More...
 
template<typename T >
std::vector< std::string > setParamVal (std::string const &paramdescriptor, T const &val)
 Set a parameter value. More...
 
template<typename T >
void setParamValUnique (std::string const &paramdescriptor, T const &val)
 Set a parameter value, simple version assuming only one parameter match. More...
 
template<typename T >
std::vector< std::pair< std::string, T > > getParamVal (std::string const &paramdescriptor) const
 Get parameter(s) value(s) by descriptor. More...
 
template<typename T >
getParamValUnique (std::string const &paramdescriptor) const
 Get a parameter value, simple version assuming only one parameter match. More...
 
std::vector< std::string > setParamString (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value, by string. More...
 
void setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value by string, simple version assuming only one parameter match. More...
 
std::vector< std::pair< std::string, std::string > > getParamString (std::string const &paramdescriptor) const
 Get a parameter value, by string. More...
 
std::string getParamStringUnique (std::string const &paramdescriptor) const
 Get a parameter value by string, simple version assuming only one parameter match. More...
 
void freezeParam (std::string const &paramdescriptor)
 Freeze a parameter, by name, see ParameterBase::freeze() More...
 
void unFreezeParam (std::string const &paramdescriptor)
 Unfreeze a parameter, by name, see ParameterBase::unFreeze() More...
 
void freezeAllParams ()
 Freeze all parameters. More...
 
void unFreezeAllParams ()
 Unfreeze all parameters. More...
 
std::string descriptor () const
 Get our full descriptor (including all parents) as [Instancename]:[...]:[...]. More...
 
void setParamsFromFile (std::string const &filename)
 Set some parameters from a file. More...
 
std::istream & setParamsFromStream (std::istream &is, std::string const &absfile)
 Set some parameters from an open stream. More...
 
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. More...
 
void foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
 Run a function on every param we hold. More...
 
void setPath (std::string const &path)
 Assign a filesystem path to this component. More...
 
std::string absolutePath (std::string const &path="")
 If given path is relative (not starting with /), prepend the Component path to it. More...
 
- Public Member Functions inherited from jevois::ParameterRegistry
virtual ~ParameterRegistry ()
 Virtual destructor for safe inheritance. More...
 

Protected Member Functions

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

Related Functions

(Note that these are not member functions.)

 JEVOIS_DEFINE_ENUM_CLASS (Mode,(RAW)(FIFO)(DMP)) JEVOIS_DECLARE_PARAMETER(mode
 Enum for Parameter. More...
 
 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. More...
 
 JEVOIS_DECLARE_PARAMETER (pktdbg, bool, "Send raw FIFO or DMP packets to console for debug/hacking purposes.", false, ParamCateg)
 Parameter. More...
 
 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. More...
 
 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. More...
 
 JEVOIS_DEFINE_ENUM_CLASS (MagRate,(Off)(Once)(M10Hz)(M20Hz)(M50Hz)(M100Hz)) JEVOIS_DECLARE_PARAMETER_WITH_CALLBACK(mrate
 Enum for Parameter. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 

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 ( )
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 690 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.

References jevois::imu::get().

◆ devid()

uint32_t jevois::ICM20948::devid ( )
protected

Read device ID.

Definition at line 701 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.

References jevois::imu::get().

◆ 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::imu::get(), 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::imu::get(), 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 jevois::imu::get(), and 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 ( )
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 675 of file ICM20948.C.

Friends And Related Function Documentation

◆ JEVOIS_DECLARE_PARAMETER()

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/8]

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/8]

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/8]

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/8]

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/8]

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/8]

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/8]

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/8]

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.

Parameter

◆ JEVOIS_DEFINE_ENUM_CLASS() [2/2]

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

Enum for Parameter.

Parameter


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