stmicroelectronics / iis3dwb-pid

iis3dwb platform independent driver based on Standard C language and compliant with MISRA standard

1 - Introduction

Sensor driver for IIS3DWB sensor written in C programming language. This repository contains the sensor driver files (.h and .c) to be included, or linked directly as a git submodule, in your project. The driver is MISRA compliant and the documentation can be generated using the Doxygen tool.

In order to clone the complete content of the repository folder, use the command:

git clone https://github.com/STMicroelectronics/IIS3DWB-PID/

Some examples of driver usage can be found here.

---

2 - Integration details

The driver is platform-independent, you only need to define two functions for read and write transactions from the sensor hardware bus (ie. SPI or I²C). A few devices integrate an extra bit in the communication protocol in order to enable multi read/write access, this bit must be managed in the read and write functions defined by the user. Please refer to the read and write implementation in the reference examples.

2.a Source code integration

• Include in your project the driver files of the sensor (.h and .c)
• Define in your code the read and write functions that use the I²C or SPI platform driver like the following:

/** Please note that is MANDATORY: return 0 -> no Error.**/
int32_t platform_write(void *handle, uint8_t Reg,const uint8_t *Bufp, uint16_t len)
int32_t platform_read(void *handle, uint8_t Reg, uint8_t *Bufp, uint16_t len)

• Declare and initialize the structure of the device interface:

xxxxxxx_ctx_t dev_ctx; /** xxxxxxx is the used part number **/
dev_ctx.write_reg = platform_write;
dev_ctx.read_reg = platform_read;

• If needed by the platform read and write functions, initialize the handle parameter:

dev_ctx.handle = &platform_handle;

Some integration examples can be found here.

2.b Required properties

• A standard C language compiler for the target MCU
• A C library for the target MCU and the desired interface (ie. SPI, I²C)

---

More Information: http://www.st.com

Copyright (C) 2021 STMicroelectronics

iis3dwb-pid's Issues

'const' missing in README.md

In README.md there is the following snippet of code

/** Please note that is MANDATORY: return 0 -> no Error.**/
int32_t platform_write(void *handle, uint8_t Reg, uint8_t *Bufp, uint16_t len)
int32_t platform_read(void *handle, uint8_t Reg, uint8_t *Bufp, uint16_t len)

If you look to the examples here, you can see that the prototype for platform_write needs a const uint8_t *Bufp parameter.

The const is missing from README.md
The const is mandatory, because the function signature must match
typedef int32_t (*stmdev_write_ptr)(void *, uint8_t, const uint8_t *, uint16_t);
defined here
https://github.com/STMicroelectronics/iis3dwb/blob/f356f14b41285146fe628559656ea4fc0c3d11ea/iis3dwb_reg.h#L112

SPI issue with STM32CubeH7 MCU Firmware Package v1.11.1

I've just discovered that even if iis3dwb driver works well with STM32H7 if MCU Firmware Package is v1.10.0, after I upgraded the firmware packgae to v1.11.1 - and no other change to my source code - iis3dwb device started having some issues on the SPI communication.
Basically, there are some conditons that stops then device from answering on the SPI.
One of them is using another SPI peripheral on the MCU to write into an external EEPROM.

After my investigation, what happens is similar to the issue described STMicroelectronics/STM32CubeH7#249 but it's 10 months old and no patch has been provided.

I had to switch back to v1.10.0

Wrong description for some functions

Based on what I understand from the datashhet, some of the functions have wrong description.
As an example:

iis3dwb-pid/iis3dwb_reg.c

Line 1119 in a48eeaf

* @brief Software reset. Restore the default values in user registers.[set]

should be
* @brief Software reset.[set]

iis3dwb-pid/iis3dwb_reg.c

Line 1122 in a48eeaf

* @param val Change the values of sw_reset in reg CTRL3_C

should be something like
* @param val Value of sw_reset in reg CTRL3_C

iis3dwb-pid/iis3dwb_reg.c

Line 1142 in a48eeaf

* @brief Software reset. Restore the default values in user registers.[get]

should be
* @brief Software reset.[get]

iis3dwb-pid/iis3dwb_reg.c

Line 1145 in a48eeaf

* @param val Change the values of sw_reset in reg CTRL3_C

should be
* @param val Value of sw_reset in reg CTRL3_C

Maybe there are other functiuons, but this ones are those that I was looking to

Doubt on iis3dwb_xl_hp_path_on_out_set()

Looking to source code for iis3dwb_xl_hp_path_on_out_set here
https://github.com/STMicroelectronics/iis3dwb/blob/d825d34bb3310b13dbce0cb7c3a67cb6c5d82ebd/iis3dwb_reg.c#L1376-L1382
I see one difference from iis3dwb datasheet.

Paragraph 9.17 of the datasheet descriibes how to configure CTRL8_XL register.
In particular HP_REF_MODE_XL fields states

Enables accelerometer high-pass filter reference mode (valid for high-pass path - FDS bit must be ‘1’ and HPCF_XL_[2:0] must be set to “111”).

But the following line
https://github.com/STMicroelectronics/iis3dwb/blob/d825d34bb3310b13dbce0cb7c3a67cb6c5d82ebd/iis3dwb_reg.c#L1379
is responsible to set this field.
Looking to the allowed values for iis3dwb_hp_slope_xl_en_t
https://github.com/STMicroelectronics/iis3dwb/blob/d825d34bb3310b13dbce0cb7c3a67cb6c5d82ebd/iis3dwb_reg.h#L882-L901
you can see that the only value that sets ctrl8_xl.hp_ref_mode_xl to 1 is
https://github.com/STMicroelectronics/iis3dwb/blob/d825d34bb3310b13dbce0cb7c3a67cb6c5d82ebd/iis3dwb_reg.h#L884

But with this value, ctrl8_xl.hpcf_xl is set to 0.
This is not what is described in the datasheet.

Can you clarify, please?
I started looking into the source code because it seems that there is some unexpected behavior with some of the HPF/LPF2 configurations. I can be wrong, but I need to investigate deeper.

Thanks in advance

Potential array overflow in iis3dwb_fifo_out_raw_get

This snippet of code

iis3dwb-pid/iis3dwb_reg.c

Lines 919 to 920 in 7dac6d5

	ret = iis3dwb_read_reg(ctx, IIS3DWB_FIFO_DATA_OUT_TAG, buff,
	sizeof(iis3dwb_fifo_out_raw_t));

reads sizeof(iis3dwb_fifo_out_raw_t) bytes from the FIFO and stores them into buf (which is 7 bytes large).
I suppose that the purpose is to read 7 bytes from the FIFO, because from the datasheet every FIFO item is 7 bytes large (1 byte of tag + 6 bytes of data).
The problem is that iis3dwb_fifo_out_raw_t is declared as

iis3dwb-pid/iis3dwb_reg.h

Lines 1110 to 1119 in 7dac6d5

	typedef struct
	{
	enum
	{
	IIS3DWB_XL_TAG = 2,
	IIS3DWB_TEMPERATURE_TAG,
	IIS3DWB_TIMESTAMP_TAG,
	} tag;
	uint8_t data[6];
	} iis3dwb_fifo_out_raw_t;

but in C (not C++) the sizeof of th enum is not defined by the standard.
As an example, you can read here.

If you use ARM Compiler with -fshort-enums option (see here) or GCC (I haven't tried), probably the sizeof of the tag enum is 1 byes (based on the values declared for tag), but this is not guaranteed.
And so, sizeof(iis3dwb_fifo_out_raw_t) can be larger than 7 bytes.
In this case, buf is written beyond its boundary.

I see only one clean and safe possibility to fix this:
changing iis3dwb_fifo_out_raw_t declaration so that it's 7 bytes long. In this case it cannot include an enum anymore, but it should be

typedef struct
{
  uint8_t tag;
  uint8_t data[6];
} iis3dwb_fifo_out_raw_t;

But even in this way, I'm not sure if the starting address of a iis3dwb_fifo_out_raw_t variable would remain byte-aligned, or it would be chnaged to int-aligned.

The problem is that

iis3dwb-pid/iis3dwb_reg.c

Lines 961 to 973 in 7dac6d5

	int32_t iis3dwb_fifo_out_multi_raw_get(stmdev_ctx_t *ctx,
	iis3dwb_fifo_out_raw_t *fdata,
	uint16_t num)
	{
	int32_t ret;
	/* read out all FIFO entries in a single read */
	ret = iis3dwb_read_reg(ctx, IIS3DWB_FIFO_DATA_OUT_TAG,
	(uint8_t *)fdata,
	sizeof(iis3dwb_fifo_out_raw_t) * num);
	return ret;
	}

reads 7 * num bytes and stores them into fdata which is an array of num iis3dwb_fifo_out_raw_t variables.
This massive read works only if iis3dwb_fifo_out_raw_t are stored into memory byte-aligned.

The topic is quite technical, and I hope I've been able to describe it.

FIFO mode with watermark

Hi, I'm trying to use the iis3dwb as FIFO mode with a watermark.

I'm using a custom board. I double checked the hardware and guaranteed this board works well. I'm able to read/write the sensor using SPI interface and generate interrupt with wake-up int source.

In this mode the interrupt INT1 not works. This is my init code:

// Reset the sensor
response = iis3dwb_reset_set(&hAcc, PROPERTY_ENABLE);

do
{
	response = iis3dwb_reset_get(&hAcc, &reset);
	HAL_Delay(BOOT_TIME);
} while (reset);

iis3dwb_xl_data_rate_set(&hAcc, IIS3DWB_XL_ODR_26k7Hz);
iis3dwb_xl_full_scale_set(&hAcc, IIS3DWB_2g);
iis3dwb_fifo_mode_set(&hAcc, IIS3DWB_STREAM_MODE);
iis3dwb_fifo_watermark_set(&hAcc, 256);
iis3dwb_fifo_xl_batch_set(&hAcc, IIS3DWB_XL_BATCHED_AT_26k7Hz);
iis3dwb_block_data_update_set(&hAcc, 1);

int1_route.fifo_th = 1;
int1_route.fifo_ovr = 1;
int1_route.fifo_full = 1;
int1_route.fifo_bdr = 1;
iis3dwb_pin_int1_route_set(&hAcc, &int1_route);

Please, could you guide me to find where is my mistake?
If possible, can anyone add a sample code for fifo mode with watermark? It will be nice!

Many thanks for this library.

missing "user offset correction block" feature

The current version lib (latest commit version) does not implement the accelerometer user offset correction block feature, that can be enabled by setting the USR_OFF_ON_OUT bit of the CTRL7_C register and is mandatory in order to be able to apply offset correction. see #14 pullrequest

Typo in iis3dwb_fifo_status_get

I think that the documentation of iis3dwb_fifo_status_get has a little typo.
After commit f19da2b it reads both FIFO_STATUS1 and FIFO_STATUS2 registers

iis3dwb-pid/iis3dwb_reg.c

Line 3129 in b85e3d2

ret = iis3dwb_read_reg(ctx, IIS3DWB_FIFO_STATUS1, (uint8_t *)&buff[0], 2);

and combines their content into the struct iis3dwb_fifo_status_t.

I suggest to change

iis3dwb-pid/iis3dwb_reg.c

Line 3118 in b85e3d2

* @param val Registers FIFO_STATUS2

into
* @param val Registers FIFO_STATUS1 and FIFO_STATUS2

Missing IIS3DWB_HP_ODR_DIV_4 option

After commit e97f730 no more IIS3DWB_HP_ODR_DIV_4 option is available
https://github.com/STMicroelectronics/iis3dwb/blob/e97f730f81edc59ee16d0ce4b856f8da9c40bc12/iis3dwb_reg.h#L879-L898

Looking to paragraph 9.17 of the datasheet this config seems be available - SLOPE/(ODR/4)

I think it should be defined with a value of 10.
I can be wrong.

iis3dwb_fifo_out_multi_raw_get dont work

Unfortunately, the iis3dwb_fifo_out_multi_raw_get function does not work correctly. Most likely it is due to sizeof(iis3dwb_fifo_out_raw_t).

  typedef struct
  {
    enum
    {
      IIS3DWB_XL_TAG = 2,
      IIS3DWB_TEMPERATURE_TAG,
      IIS3DWB_TIMESTAMP_TAG,
    } tag;
    uint8_t data[6];
  } iis3dwb_fifo_out_raw_t;

int32_t iis3dwb_fifo_out_multi_raw_get(stmdev_ctx_t *ctx,
                                       iis3dwb_fifo_out_raw_t *fdata,
                                       uint16_t num)
{
  int32_t ret;

  /* read out all FIFO entries in a single read */
  ret = iis3dwb_read_reg(ctx, IIS3DWB_FIFO_DATA_OUT_TAG,
                         (uint8_t *)fdata,
                         sizeof(iis3dwb_fifo_out_raw_t) * num);

  return ret;
}

The enum has the size 4 byte. Probably the size 1 byte was expected.
The flag "-fshort-enums" is not a option for me.

Cppcheck issues

I used cppcheck tool to do a static analysis of the source code, and I get some potential issues.
As an example, in the following snippet of code

iis3dwb-pid/iis3dwb_reg.c

Lines 438 to 449 in b85e3d2

	iis3dwb_ctrl4_c_t ctrl4_c;
	iis3dwb_ctrl6_c_t ctrl6_c;
	int32_t ret;
	ret = iis3dwb_read_reg(ctx, IIS3DWB_CTRL4_C, (uint8_t *)&ctrl4_c, 1);
	if (ret == 0)
	{
	ret = iis3dwb_read_reg(ctx, IIS3DWB_CTRL6_C, (uint8_t *)&ctrl6_c, 1);
	}
	switch ((ctrl4_c._1ax_to_3regout << 4) + ctrl6_c.xl_axis_sel)

if the first iis3dwb_read_reg() fails (and returns ret != 0), the second iis3dwb_read_reg() is not executed, and so the switch() accesses to ctrl6_c.xl_axis_sel uninitialized.
I suggest to change this snippet into

  *val = IIS3DWB_ENABLE_ALL;  /* so that it's always set to "the default" */

  ret = iis3dwb_read_reg(ctx, IIS3DWB_CTRL4_C, (uint8_t *)&ctrl4_c, 1);
  if (ret != 0) { return ret; }

  ret = iis3dwb_read_reg(ctx, IIS3DWB_CTRL6_C, (uint8_t *)&ctrl6_c, 1);
  if (ret != 0) { return ret; }

  switch ((ctrl4_c._1ax_to_3regout << 4) + ctrl6_c.xl_axis_sel)

Cppcheck gives a list of potential issues in the files and I suggest to fix all of them.
@avisconti if you agree I can make a PR.
Let me know

Broken links on README.md

In the main README.md the following two links are broken and they bring to 404 page not found error.

The driver is platform-independent, you only need to define two functions for read and write transactions from the sensor hardware bus (ie. SPI or I²C). A few devices integrate an extra bit in the communication protocol in order to enable multi read/write access, this bit must be managed in the read and write functions defined by the user. Please refer to the read and write implementation in the reference examples.

Some integration examples can be found here.