icm20948

Connect to ICM-20948 sensor on Arduino hardware I2C bus

Since R2022a

Add-On Required: This feature requires the MATLAB Support Package for Arduino Hardware add-on.

Description

The icm20948 object reads acceleration, angular velocity, magnetic field, and temperature using the TDK ICM-20948 sensor. The ICM-20948 is a 9 degree of freedom (DOF) inertial measurement unit (IMU) used to read acceleration, angular velocity, and magnetic field in all three dimensions.

The icm20948 object represents a connection to the device on the Arduino^® hardware I2C bus. Attach an ICM-20948 sensor to the I2C pins on the Arduino hardware. You can read the data from your sensor in MATLAB^®using the object functions.

Before you use the icm20948 object, create an Arduino object using arduino and set its properties. When you create the Arduino object, make sure that you include the I2C library. For more information, see Connect to Arduino Hardware.

Creation

Syntax

imu = icm20948(a)

imu = icm20948(a,Name,Value)

Description

imu = icm20948(a) creates a sensor object with default property values. The object represents the connection to the sensor on the Arduino hardware, a.

imu = icm20948(a,Name,Value) creates a sensor object with properties using one or more Name,Value pair arguments.

Input Arguments

a — Arduino hardware connection

arduino object

Arduino hardware connection created using arduino, specified as an object.

Example: imu = icm20948(a) creates a connection to the ICM-20948 sensor on the Arduino object, a.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: imu = icm20948(a,Bus=1);

You can specify any of the properties on this page as name-value pairs.

Properties

Note

• All the properties except SamplesRead and SamplesAvailable can be set by specifying as name-value pair arguments while creating an icm20948 object.

• The properties I2CAddress and Bus are immutable (the property value is set during construction; you cannot change the value of an immutable property after the object is created).

• The TimeFormat property is tunable, which means you can change the value anytime. The SampleRate, SamplesPerRead, ReadMode, and OutputFormat properties are non-tunable, which means you cannot change their values once the object is locked. Objects are locked when you call the read function, and the release function unlocks them. If a property is tunable, you can change its value at any time.

I2CAddress — Specify I2C address of sensor

[0x68, 0x0C] | [0x69, 0x0C]

Specify the I2C address of the sensors when multiple I2C devices with the expected address for ICM-20948 are connected to the same hardware board. ICM-20948 can have multiple I2C addresses depending on the logic level on pin AD0 of the sensor.

Pin Name	Pin State	I2C Address
AD0	Low	[0x68, 0x0C]
	High	[0x69, 0x0C]

You can specify the I2C address in:

• Numeric array of hexadecimal, decimal, or binary format of I2C Addresses

• String array of hexadecimal value of I2C Addresses

• Cell array of character vector of hexadecimal value of I2C Addresses

Example: imu = icm20948(a,I2CAddress=[0x69, 0x0C])

'0x69' is the I2C address of the accelerometer and gyroscope of ICM-20948. '0x0C' is the I2C address of the magnetometer of ICM-20948.

If not specified, the object will be created with one of the available I2C device address in the table. Availability of I2C device with the expected address will be determined by using scanI2CBus.

Bus — I2C Bus Number

0 (default) | 1

I2C bus number, specified as 0 or 1. The default value is 0.

Example: imu = icm20948(a, Bus=1) creates the icm20948 sensor object if ICM-20948 sensor is connected to bus 1 of Arduino Due board.

Data Types: double

SampleRate — Rate at which sample is read during the execution of read function

100 (default) | positive integer in the range [11, 200]

The rate in Samples/s at which data is read from the sensor during execution of read function.

Note

Real-time data rate acquisition from ICM-20948 sensor can be achieved by using the SampleRate property and read function.

Tunable: No

Data Types: double

SamplesPerRead — Number of samples read in a single execution of the read function

10 (default) | [1 500]

Number of samples read from the sensor in a single execution of the read function.

Tunable: No

Data Types: double

ReadMode — Specify which data samples to be returned during the execution of read function

'latest' (default) | 'oldest'

Specify whether to return the latest or the oldest data samples during execution of read function. The number of samples depends on the SamplesPerRead value. The data read from the sensor is stored in the MATLAB buffer.

• latest —

  Provides the latest data samples available in the buffer. All previous data samples in the buffer are discarded. For example, if SamplesPerRead = 3, the latest three data samples read by the sensor are returned.

  The following figure illustrates how latest data samples are returned assuming S1 is the first sensor data stored in the buffer, S2 is the second data and so on and Sn is the last data stored in the buffer and SamplesPerRead property is set to 3 during sensor object creation.

  

• oldest —

  Provides the oldest data samples available in the buffer. In this case, no data samples are discarded. For example, if SamplesPerRead = 3, the first three data samples read are returned for the first read, the next three data samples are returned for the second read, and so on.

  The following figure illustrates how oldest data samples are returned assuming S1 is the first sensor data stored in the buffer, S2 is the second data and so on and Sn is the last data stored in the buffer and SamplesPerRead property is set to 3 during sensor object creation.

  

Tunable: No

Data Types: character vector | string

SamplesRead — Samples read which gets updated with the execution of read

double

This property is read-only.

Samples read from the first read. This property gets updated with the execution of read function. When you release the object, SamplesRead is set to 0.

Data Types: double

SamplesAvailable — Samples in the host buffer which gets updated with the execution of read

double

This property is read-only.

Samples available in the host buffer. This property gets updated with the execution of read function. The data read from the sensor is stored in the MATLAB buffer. SamplesAvailable property shows the number of SamplesAvailable in this host buffer. When you release the object, SamplesAvailable is set to 0. When the ReadMode of sensor is set as latest, SamplesAvailable will always be 0.

Data Types: double

OutputFormat — Set output format returned after the execution of read function

'timetable' (default) | 'matrix'

Set the output format of the data returned by executing the read function.

When the OutputFormat is set to timetable, the data returned has the following fields:

• Time — Time stamps in datetime or duration format

• Acceleration — N-by-3 array in units of m/s²

• AngularVelocity — N-by-3 array in units of rad/s

• MagneticField — N-by-3 array in units of µT (microtesla)

• Temperature — N-by-1 array in units of celsius

When the OutputFormat is set to matrix, the data is returned as matrices of acceleration, angular velocity, magnetic field, temperature, and time stamps. The units for the sensor readings are the same as the timetable format. The size of each matrix is N-by-3.

N is the number of samples per read specified by SamplesPerRead. The three columns of each field represent the measurements in x, y, and z axes.

Tunable: No

Data Types: character vector | string

TimeFormat — Set time format during the execution of read function

'datetime' (default) | 'duration'

Set the format of the time displayed when the sensor data is read using read function.

• datetime — Displays the date and time at which the data is read.

• duration — Displays the time elapsed in seconds after the sensor object is locked. The sesnor object gets locked at the first call of the read function either after the object creation or after the execution of the release function.

Tunable: Yes

Data Types: character vector | string

Usage

Create ICM-20948 Sensor Connection

Create an Arduino object and include the I2C library.

a = arduino();

Or, you can explicitly specify it in the Libraries Name-Value pair while creating the Arduino object.

clear a;
a = arduino('COM4', 'Uno', Libraries='I2C');

Create the sensor object.

imu = icm20948(a)

imu = 

  icm20948 with properties: 

                 I2CAddress: 104  ("0x68")
                           : 12   ("0xC")
                     SCLPin: "A5" 
                     SDAPin: "A4" 

                 SampleRate: 100  (Samples/s)
             SamplesPerRead: 10  
                   ReadMode: 'latest'            
                SamplesRead: 0      
           SamplesAvailable: 0 
Show all properties, functions

      

Create ICM-20948 Sensor Connection with Additional Name-Value Pair Arguments

Create a sensor object with additional properties specified as name-value pair arguments.

clear imu;
imu = icm20948(a,SampleRate=50,SamplesPerRead=5,ReadMode='latest')

imu = 

  icm20948 with properties: 

                 I2CAddress: 104  ("0x68")
                           : 12   ("0xC")
                     SCLPin: "A5" 
                     SDAPin: "A4" 

                 SampleRate: 50  (Samples/s)
             SamplesPerRead: 5  
                   ReadMode: 'latest'            
                SamplesRead: 0      
           SamplesAvailable: 0 
Show all properties, functions
 

Object Functions

readAcceleration	Read one sample of acceleration from sensor
readAngularVelocity	Read one sample of angular velocity from sensor
readMagneticField	Read one sample of magnetic field from sensor
readTemperature	Read one sample of temperature from sensor
read	Read real-time sensor data at a specified rate
release	Release the sensor object
flush	Flush the host buffer
info	Read information related to sensor

More About

Code Generation Using MATLAB Function Block

• Use icm20948 in a MATLAB Function block with the Simulink^® Support Package for Arduino Hardware to generate code that can be deployed on Arduino Hardware.

• The property ReadMode cannot be changed and is always set to latest.

• The property SamplesPerRead cannot be changed and is always set to 1. So, no framing is provided.

• The property OutputFormat is always set to matrix.

• The property TimeFormat is always set to duration.

• The property SamplesAvailable is not accessible from sensor object.

• The default value of I2C address will be taken as [0x69, 0x0C]. Specify I2C address if the sensor has a different I2C address. The possible values of I2C Addresses are mentioned in the table under I2Caddress section in this page.

Version History

Introduced in R2022a