franzbischoff/mpx

Readme

# Mpx ESP-IDF Component

Streaming Matrix Profile and FLOSS time series analysis for ESP32 projects
built with ESP-IDF.

## Features

- Streaming Matrix Profile motif discovery.
- FLOSS semantic segmentation for change detection.
- Small-footprint implementation for embedded systems.
- No external component dependencies.
- C++17 implementation with ESP-IDF logging support.

## Requirements

- ESP-IDF installed and configured.
- An ESP32 target supported by the selected ESP-IDF version.
- C++17 support in the ESP-IDF toolchain.

## Add the component to a project

Add the component as a dependency in the project's `idf_component.yml`:

```yaml
dependencies:
  mpx:
    version: "*"
    git: https://github.com/franzbischoff/mpx-esp-idf.git
```

For a local component, copy or link this repository into the project's
`components/mpx/` directory.

## Basic usage

```cpp
#include "mpx/Mpx.hpp"

using MatrixProfile::Mpx;

extern "C" void app_main(void)
{
    Mpx mpx(64, 0.5F, 0U, 2000U);
    float samples[256] = {};

    const uint16_t remaining = mpx.compute(samples, 256U);
    if (mpx.is_valid()) {
        mpx.floss();
        const float *matrix_profile = mpx.get_matrix();
        const int16_t *profile_indexes = mpx.get_indexes();
        const float *floss = mpx.get_floss();
        (void)remaining;
        (void)matrix_profile;
        (void)profile_indexes;
        (void)floss;
    }
}
```

Input samples passed to `compute()` must be finite `float` values. Do not pass
`NaN`, positive infinity, or negative infinity.

## API

### Construction

```cpp
Mpx(uint16_t window_size,
    float ez = 0.5F,
    uint16_t time_constraint = 0U,
    uint16_t buffer_size = 5000U);
```

`window_size` must be greater than zero and no larger than `buffer_size`.
`buffer_size` must not exceed 32767 samples. `ez` is the non-negative,
finite exclusion-zone ratio.

### Processing

```cpp
uint16_t compute(const float data[], uint16_t size);
void floss();
void prune_buffer();
```

`compute()` returns the remaining capacity of the internal streaming buffer.
Call `floss()` after processing data to calculate semantic segmentation values.

### Results and state

```cpp
const float *get_matrix();
const int16_t *get_indexes();
const float *get_floss();
const float *get_iac();
uint16_t get_profile_len() const;
bool is_valid() const;
```

The returned arrays are views owned by the `Mpx` object. Do not free them or use
them after the object is destroyed. Additional views and state accessors are
documented in `include/mpx/Mpx.hpp`.

## Component metadata

This repository contains the files required by the ESP Component Registry:

- `CMakeLists.txt` for component registration.
- `idf_component.yml` for package metadata and versioning.
- `include/mpx/Mpx.hpp` and `src/Mpx.cpp` for the component implementation.
- `LICENSE` for the MIT license.

## License

Mpx is distributed under the [MIT License](LICENSE).