Copyright 2023 Travis J. West, Input Devices and Music Interaction Laboratory (IDMIL), Centre for Interdisciplinary Research in Music Media and Technology (CIRMMT), McGill University, Montréal, Canada, and Univ. Lille, Inria, CNRS, Centrale Lille, UMR 9189 CRIStAL, F-59000 Lille, France
SPDX-License-Identifier: MIT
The ICM20948 is interacted with via its control registers according to the concept of a byte-wise serial interface described elsewhere.
Before proceeding with the rest of the implementation, we consider a couple of very simple tests to ensure that the above serial interface appears to be working.
In the first test, we simply read the WHO_AM_I register of the ICM20948 and confirm that it has the expected value. This test confirms that the ICM20948 is connected and the serial interface read functions seem to be implemented correctly.
In the second test, we reset SRAM, then read the USER_CTRL register to confirm that it has the expected value following a reset. We then toggle a switch in the USER_CTRL register, confirm that the change was recorded, then finally reset SRAM again. This test confirms that the write function seems to be implemented correctly.
Now that we have a way to read and write the control registers, most of what remains is to simply define constant values for the addresses, allowed values, bit masks, etc. needed to actually manipulate the registers. All of this data is contained in the datasheet and need to be rendered in source code form. This is commonly accomplished using plain C style enumerations, preprocessor definitions, and simple structs, but these methods don't provide much compile-time safety, and generally don't take advantage of the affordances of C++ to help us avoid errors, so we wish to employ a more elaborate approach that can make better use of the language.
Our first thought is to transcribe the datasheet so that each register description becomes a struct that contains all the relevant data; this can potentially make it impossible to use e.g. a bit mask meant for one register with another one, e.g.:
We want to declare a function that will let us set one bit field atomically given only the bit field as an argument; we want to make C++ do the tedious work of associating that bit field value with the relevant register address, bank, and bit mask, which shouldn't be too difficult if we structure our transcription of the datasheet appropriately.
My first thought is to try to define something like this:
On reflection, it's clear that there will be no way to access e.g. USER_CTRL from an unsigned integer value such as USER_CTRL::SRAM_RST::reset, as structured above. My next thought is to make SRAM_RST::reset a type that has a using directive that points back to the register, e.g.:
This turns out to be cumbersome for several reasons. Accessing the values, such as address, requires manually traversing the links implemented by the using directives. This also involves writing a lot of static constexpr.
Another possibility is to use inheritance to propagate and protect register-level information when moving down to bit-fields, instead of trying to use nested scopes or using directives. This might reduce the amount of writing we have to do, make the implementation of read_modify_write simpler, and it may also allow us to propagate functionality through inheritance, which might be convenient.
So we rewrite the above listing such that USER_CTRL is struct of type Register that only defines its address, bank, etc., and then each bit field is an independent struct that inherits these values from the register type and adds a static member for its bit mask, and each possible bit field state, e.g. enabled or disabled for I2C_MST_EN is another independent type that inherits from the bit field and declares an API for manipulating that bit field in a certain way.
This seems like a nice approach, and we can use templates to further reduce the amount of writing we have to do, saving ourselves from having to write static constexpr so many times.
We realize this approach with the following set of base class templates:
Then we can transcribe a few registers from the datasheet like this:
And use them like this:
The description is highly declarative, with each bit field declared in terms of how it should be interpreted. There is relatively little repetition; we tolerate the repeated register type since we can highlight the repetition through formatting so that it's easier to catch typos and otherwise ignore the repetition. We also generate an imperative API for interacting with the registers as, it feels like, a side effect of declaring their semantics. Very nice!
Here is the complete register description header. Many registers are not yet transcribed from the datasheet, as they aren't in use in the current version of the driver.
The ICM20948 has hardware support for controlling external sensors attached to an auxiliary I2C bus. There are five controllers. The first four are suited for continuously reading up to 15 bytes from I2C devices on the auxiliary bus, while the final controller is suited for single byte read and write operations. None of these controller is capable of multi-byte writes.
Presently we only make use of the final controller. It registers are declared thus:
We implement the serial interface API using this controller:
As well as its accelerometer and gyroscope, the ICM20948 also includes an embedded magnetometer with a seperate I2C address and register space. The AK09916 doesn't have use banks like the ICM20948, but otherwise its API is very similar. We define a seperate register base class for this sub-device, and document its registers as above.
The test here sets up the ICM20948 so that the magnetometer can be accessed via the main I2C bus. Then the device ID is checked and a self-test measurement is performed. The test serves to demonstrate that the register definitions and bases are working, and that the magnetometer self-test is in the expected range.
The main API then ties these resources together, along with the MIMU endpoints.
We begin initialization by checking that all tests are passing. If this fails for some reason, the device is disabled via a flag that is checked in the main subroutine.
Assuming all the tests pass, we set up the device.
Finally, we set the sensitivity output endpoints to their default values.
In the main subroutine, we read from the sensors.
The number of bytes to read is fixed at compile time based on the addresses of the range of registers that should be read. We statically allocate a buffer on the stack for reading the data.
The sensor fusion algorithm requires knowledge of the time between measurements. We statically record an initial timestamp, and in each loop note the time before attempting to read data. If a new measurement is read, then we update the time elapsed since the previous measurement and adjust the timestamp of the previous measurement.
We poll the status registers of the two sensor modules (the ICM20948 and its built-in magnetometer). When data is available, we proceed to read it and update the relevant endpoints.
Updating the endpoints proceeds according to the endianness of the data as read from the registers of the devices. We shuffle the upper and lower bytes appropriately, transiting from uint8_ts to int16_ts to ints. The explicit conversion ensure that the sign of the 16-bit values is preserved when converting them to int; a more elegant expression of this conversion may be possible, but this works for now. We then convert the raw data to more meaningful units according to the current sensitivity of the sensors.
Note that the y and z axes of the magnetometer are flipped; this brings them into agreement with those of the accelerometer and gyroscope, so that all three coordinate systems are right-handed and (in principle) aligned.
A software subcomponent is provided that collects various tests into a static method that is called while initializing the MIMU to make sure everything seems to be working as expected. Several tests are filled in above.
The various sub-components are collected together into one CMake library.
1.9.8