espressif/bmi270_sensor

Readme

# BMI270 Sensor Component for ESP-IDF

Official Espressif BMI270 integration for ESP32 applications: **6-axis motion sensing, Bosch Base wrist gestures, custom Circle/Toy gesture firmware, native I2C integration, and AUX sensor expansion**. Public C APIs and eleven complete examples cover circle, tap, throw, push, shake, rolling, and rotation detection.

## What's new in v0.4.0

- Add `bmi270_sensor_create_from_master_bus_with_address()` for 0x68/0x69 selection.

## v0.3.0

- Add `aux_bmm150` and `raw_data` examples.
- Add `bmi270_sensor_create_from_master_bus()`; keep the existing create API.
- Release I2C devices per instance; the caller keeps the bus.
- Fix AUX manual transfers and `bmi2_delay_us`.
- Remove unimplemented `bmi270_toy_*` declarations.

## Custom firmware, delivered as a binary component

**The bundled Bosch Base firmware supports standard watch and wearable features**, including wrist gestures, wrist-wear wake-up, step counting, and step activity recognition. Choose Base for these features, or Circle/Toy for the custom capabilities below.

**Circle and Toy are BMI270 sensor firmware variants jointly developed by Espressif and Bosch Sensortec for ESP32 applications.** They are not included in the [public Bosch BMI270 SensorAPI repository](https://github.com/boschsensortec/BMI270_SensorAPI).

These variants and their ESP-IDF integration are delivered together as precompiled static libraries (`.a`), one per supported ESP-IDF version and target chip. Your application links the matching library, and the driver loads the selected firmware image into the BMI270 during sensor initialization. The library implementation is binary; **public headers, configuration types, C APIs, and example application source are available to read and use.** Start with [bmi270_api.h](include/bmi270_api.h) and the [examples below](#examples).

## Choose a firmware variant

One BMI270 runs one firmware variant at a time, and the three feature sets are not combined. Pass the variant's configuration symbol to either create API, then use the matching feature APIs.

| Variant | Configuration passed to create | Main capabilities | Feature API family |
| --- | --- | --- | --- |
| **Base (standard Bosch firmware)** | `bmi270_config_file` or `NULL` | Accelerometer/gyroscope, any/no/significant motion, step detection/counting, step activity recognition, wrist gestures and wrist-wear wake-up | `bmi270_*` |
| **Circle** | `bmi270_circle_config_file` | Clockwise/counterclockwise circles, selectable rotation axis, single/double/triple taps, any/no motion | `bmi270_circle_*` |
| **Toy** | `bmi270_toy_config_file` | Pick-up/put-down, throw up/down/catch, push, shake, rolling, rotation angle; any/no motion, high/low-g and tap controls | `bmi270_enable_toy_*`, `bmi270_get_toy_*`, and common `bmi2_*` calls |

Base decodes five wrist gestures: **`push_arm_down`, `pivot_up`, `wrist_shake_jiggle`, `flick_in`, and `flick_out`**. The [wrist gesture test](test_apps/main/bmi270_test.c) shows feature configuration, interrupt mapping, and result reading.

Toy features use the `bmi270_enable_toy_*` and `bmi270_get_toy_*` helpers, with `bmi270_enable_toy_tap()` for single/double/triple taps and `bmi2_set_regs()` plus `bmi2_set_int_pin_config()` for feature interrupt mapping. [toy_motion_main.c](examples/toy_motion/main/toy_motion_main.c) shows the complete sequence.

Pass `BMI2_GYRO_CROSS_SENS_ENABLE | BMI2_CRT_RTOSK_ENABLE` as `variant_feature` for Base and Circle, and `0` for Toy, matching the supplied examples.

All three variants expose the common six-axis data and AUX interfaces: `bmi2_get_sensor_config()` / `bmi2_set_sensor_config()` for measurement settings, `bmi2_sensor_enable()` for accelerometer/gyroscope activation, and `bmi2_get_sensor_data()` for readings.

## Get started

### Package and hardware requirements

- **ESP-IDF 5.3 or later**, with a prebuilt library available for your IDF major/minor version and target chip. The package selects the matching library automatically; ESP32-P4 also has revision-specific libraries. Check the published package for the combinations it supplies.
- BMI270 connected by I2C, with suitable power and SDA/SCL pull-ups. The default create APIs use address **`0x68`**; native-master callers may select **`0x69`** with the address-selectable create API.
- INT1/INT2 connected as required by the selected interrupt-driven gesture example.
- `CONFIG_I2C_BUS_BACKWARD_CONFIG` disabled. The supported hardware backend is ESP-IDF's current I2C master driver.

Add this dependency to your application's `idf_component.yml`:

```yaml
dependencies:
  espressif/bmi270_sensor: "^0.4.0"
```

### Select the bus entry point

| Your application already has | Create API | Device transfer speed |
| --- | --- | --- |
| `i2c_bus_handle_t` | `bmi270_sensor_create()` | Inherits the caller's bus speed |
| `i2c_master_bus_handle_t`, including a Board Manager bus | `bmi270_sensor_create_from_master_bus()` | 400 kHz, 200 ms transfer timeout |

Both entry points return the same `bmi270_handle_t` for sensor and AUX operations. The two bus handle types are distinct; pass each to its matching create API.
The native API uses 0x68 by default; use `bmi270_sensor_create_from_master_bus_with_address()` when SDO selects 0x69.

### Read one six-axis sample

Create a native bus with `i2c_new_master_bus()` using your board's pins, or obtain one from Board Manager. Pass that caller-owned bus to the function below. It selects Base firmware, enables the accelerometer and gyroscope with their default measurement configuration, waits for fresh data, prints raw signed counts, and deletes only its sensor device.

```c
#include "bmi270_api.h"
#include "esp_log.h"

void read_motion_once(i2c_master_bus_handle_t master_bus)
{
    bmi270_handle_t sensor = NULL;
    ESP_ERROR_CHECK(bmi270_sensor_create_from_master_bus(
        master_bus, &sensor, bmi270_config_file,
        BMI2_GYRO_CROSS_SENS_ENABLE | BMI2_CRT_RTOSK_ENABLE));

    const uint8_t sensors[] = {BMI2_ACCEL, BMI2_GYRO};
    int8_t result = bmi2_sensor_enable(sensors, 2, sensor);
    bool received = false;
    for (unsigned attempt = 0; attempt < 100 && result == BMI2_OK; attempt++) {
        bmi2_delay_us(10000, NULL);
        struct bmi2_sens_data data = {0};
        result = bmi2_get_sensor_data(&data, sensor);
        if (result == BMI2_OK && (data.status & BMI2_DRDY_ACC) &&
                (data.status & BMI2_DRDY_GYR)) {
            ESP_LOGI("motion", "acc=(%d,%d,%d) gyro=(%d,%d,%d)",
                     data.acc.x, data.acc.y, data.acc.z,
                     data.gyr.x, data.gyr.y, data.gyr.z);
            received = true;
            break;
        }
    }
    bmi2_error_codes_print_result(result);
    if (!received) {
        ESP_LOGW("motion", "No fresh six-axis sample received");
    }
    ESP_ERROR_CHECK(bmi270_sensor_del(&sensor));
}
```

For an existing `i2c_bus_handle_t`, use `bmi270_sensor_create()` with the same firmware and feature arguments. Configure sampling rate and range before enabling measurements, then convert raw counts using the configured ranges. [raw_data](examples/raw_data/README.md) is a complete buildable project covering configurable ODR/ranges, physical-unit conversion, and CSV output.

## Examples

Each example is a complete project with application source and board/pin setup.

| Application task | Firmware | Complete example |
| --- | --- | --- |
| Read six-axis raw data and physical units | Base | [raw_data](examples/raw_data/README.md) |
| Control BMM150 registers and read raw magnetic data through AUX | Base (Circle/Toy selectable) | [aux_bmm150](examples/aux_bmm150/README.md) |
| Recognize clockwise/counterclockwise circles | Circle | [circle_gesture](examples/circle_gesture/README.md) |
| Detect single, double, and triple taps | Circle | [multi_tap](examples/multi_tap/README.md) |
| Explore combined toy motion events | Toy | [toy_motion](examples/toy_motion/README.md) |
| Detect movement with interrupts | Toy | [any_motion](examples/any_motion/README.md) |
| Detect a push while held in the air | Toy | [push_in_air](examples/push_in_air/README.md) |
| Detect a push on a table | Toy | [push_on_table](examples/push_on_table/README.md) |
| Detect shaking | Toy | [shake](examples/shake/README.md) |
| Detect rolling | Toy | [rolling](examples/rolling/README.md) |
| Read rotation angle | Toy | [rotation](examples/rotation/README.md) |

## Expand with AUX sensors

The BMI270 AUX interface connects an external sensor, such as a BMM150 magnetometer, through the BMI270:

```text
ESP32 -- I2C --> BMI270 -- AUX I2C --> external sensor
```

AUX configuration and manual register access are available through the same handle with Base, Circle, or Toy firmware, and through either bus entry point.

| API | Purpose |
| --- | --- |
| `bmi270_aux_set_config()` | Configure AUX address, manual mode, output data rate, and burst settings |
| `bmi270_aux_get_config()` | Read back the AUX configuration |
| `bmi270_aux_read()` | Read external sensor registers in AUX manual mode |
| `bmi270_aux_write()` | Write external sensor registers in AUX manual mode |
| `bmi270_get_dev()` | Obtain `struct bmi2_dev *` for adapters using Bosch BMI2 APIs |

Configure AUX manual mode with `bmi270_aux_config_t` before calling the register read/write helpers, then initialize and operate the external sensor with its own driver through that transport. The public [AUX API declarations](include/bmi270_api.h) describe the parameters and provide a BMM150 configuration reference.

The [aux_bmm150 example](examples/aux_bmm150/README.md) shows the four public AUX APIs on AtomS3R and outputs raw counts. External sensor initialization, compensation, calibration, and any orientation or sensor-fusion algorithm belong to the external driver or application.

## API and resource lifecycle

The public headers are the integration reference:

- [bmi270_api.h](include/bmi270_api.h): creation/deletion, firmware symbols, gesture configuration, Toy helpers, and AUX APIs.
- [bmi2.h](include/bmi2.h): common measurement, register, FIFO, interrupt, and sensor-control APIs.
- [bmi2_defs.h](include/bmi2_defs.h): data structures, configuration constants, and Bosch return codes.

**Return codes:** create/delete return `esp_err_t`; success is `ESP_OK`. Bosch sensor, gesture, and AUX calls return `int8_t`; success is `BMI2_OK`, errors are negative, and some calls can report positive warnings. Use `bmi2_error_codes_print_result()` to diagnose these results and handle warnings according to the called API. `bmi270_get_dev()` returns a device pointer.

**Ownership:** the caller owns the bus. `bmi270_sensor_del()` removes that instance's device, frees its handle, and sets the handle to NULL on success. Delete all sensor instances before deleting the bus. Use synchronous native transfers, with no asynchronous callbacks registered, and serialize each instance's operations with deletion.

**Error recovery:** the short example uses `ESP_ERROR_CHECK()` for fail-fast handling of ESP-IDF errors. Applications that recover from errors should check the returned handle as well: creation normally leaves a NULL handle on failure, but if initialization and device removal both fail, a non-NULL handle is returned **only for retrying `bmi270_sensor_del()`**. A failed delete likewise retains its handle. Retry cleanup after other transfers on the shared bus finish; use sensor operations only after a successful create.

## Further reading

- [Changelog](CHANGELOG.md)
- [Bosch BMI270 product information](https://www.bosch-sensortec.com/products/motion-sensors/imus/bmi270.html)
- [Bosch public BMI270 SensorAPI](https://github.com/boschsensortec/BMI270_SensorAPI)