# stmicroelectronics/stmems_finite_state_machine architecture

> Architecture diagram of the GitHub repository stmicroelectronics/stmems_finite_state_machine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stmicroelectronics/stmems_finite_state_machine
- Repository: https://github.com/stmicroelectronics/stmems_finite_state_machine

## Overview

##### Project type and purpose
- This is an open-source example/tutorial repository, demonstrating how to configure and use the Finite State Machine (FSM) feature built into various STMicroelectronics MEMS sensors.
- It is not a monolithic application but a collection of “application_examples” (C headers + .ucf files you compile into MCU firmware) and “configuration_examples” (.ucf snippets you load into sensors with ST tools).

##### File structure
- Top level
- README.md, CONTRIBUTING.md, LICENSE
- application_examples/…
- configuration_examples/…
- application_examples/:
- One folder per sensor (e.g., asm330lhbx, lsm6dso, st1vafe3bx, etc.)
- Within each, subfolders for individual use-cases (Motion-Stationary, Shake, Freefall, etc.), each containing a C header (example code snippet) and a .ucf file (FSM configuration)
- configuration_examples/:
- Several FSM design examples, each with a utils subfolder of .ucf files

##### README insights
- Explains FSM concept: you offload simple motion-pattern detection to the sensor’s on-chip FSM
- Host CPU loads .ucf into the sensor, then reads results or handles interrupts from the sensor

##### Main components
a. Host MCU or application processor
– Running ST sensor driver library + example code (from application_examples/*.h)
– FSM config loader module (reads .ucf files, writes config registers over bus)
– Main application logic (polls or responds to sensor interrupts)
b. Communication bus
– I²C or SPI link connecting MCU ↔ sensor
c. ST MEMS Sensor
– On-chip elements:
- Sensor data block (accelerometer, gyroscope)
- FSM block (user-defined states/transitions loaded via .ucf)
- Interrupt generator or status registers
d. Configuration tool (optional external component)
– ST’s Unico GUI or MLC/FSM tool that prepares .ucf files

##### Relationships and data flow
- Startup: MCU loads .ucf into sensor FSM via I²C/SPI
- Sensor FSM block continuously processes raw accelerometer/gyro data internally
- When a pattern is detected, FSM sets a status bit and/or fires an interrupt line to MCU
- MCU reads status registers or handles interrupt → runs host logic (e.g., toggles LED, sends message)

##### Architectural patterns and design principles
- Push-down FSM: shift repetitive sensor-data processing out of host into sensor to save power
- Separation of concerns:
- Configuration layer (.ucf files in configuration_examples/)
- Application layer (example C code in application_examples/)
- Hardware abstraction (sensor driver library)
- Reusability: a single bus-driver + config-loader module supports all sensor folders

##### Technologies/frameworks/libraries
- C header files (.h) for snippet examples
- UCF (Universal Configuration Format) files for FSM definitions
- ST sensor driver library (I²C/SPI bus abstraction)
- External FSM/MLC tool (Unico)

##### Elements
- Host MCU (software modules: Bus Driver, Config Loader, Main App)
- Communication Bus (I²C/SPI)
- MEMS Sensor (Sensor Core, FSM Core, Interrupt Line)
- External FSM Configuration Tool (optional)
- Config upload (.ucf → sensor registers)
- Sensor data flow (accelerometer → FSM Core)
- Event notification (FSM → MCU via interrupt/status read)
- Blue for host-side software components
- Green for on-chip sensor blocks
- Gray for configuration files/tools
- Orange for physical connections (bus, interrupt line)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Project Documentation
    subgraph "Project Documentation & Metadata"
        direction TB
        Docs_README["README.md"]:::docs
        Docs_CONTRIBUTING["CONTRIBUTING.md"]:::docs
        Docs_LICENSE["LICENSE"]:::docs
    end

    %% External Tool
    ExternalTool["ST Unico GUI Tool"]:::tools

    %% Configuration Layer
    subgraph "Configuration Layer" 
        direction TB
        ConfigDir["configuration_examples/"]:::config
        Config_Readme["configuration_examples/README.md"]:::config
        FreefallUCF["freefall.ucf"]:::config
        WakeUCF["wake_up_no_filter.ucf"]:::config
        MLCUCF["mlc_motion_intensity.ucf"]:::config
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        AppDir["application_examples/"]:::app
        AppIndex["application_examples/README.md"]:::app
        SensorReadme["application_examples/ism330bx/README.md"]:::app
        ASM_H["asm330lhhx_motion_stationary.h"]:::app
        LSM_Shake["lsm6dso_shake.h"]:::app
        ASM_UCF["asm330lhhx_shake.ucf"]:::app
        LIS_Glance["lis2dux12_glance_detection.ucf"]:::app
    end

    %% Host MCU
    subgraph "Host MCU / Application Processor"
        direction TB
        BusDriver["Bus Driver\n(I2C/SPI)"]:::host
        ConfigLoader["Configuration Loader\n(.ucf reader)"]:::host
        MainApp["Main Application Logic"]:::host
    end

    %% Communication Bus
    Bus["I2C / SPI Bus"]:::bus

    %% Sensor
    subgraph "ST MEMS Sensor"
        direction TB
        SensorCore["Sensor Data Block\n(accel/gyro)"]:::sensor
        FSMCore["FSM Block\n(user FSM)"]:::sensor
        Interrupt["Interrupt / Status"]:::sensor
    end

    %% Relationships
    ExternalTool -->|generates .ucf files| ConfigDir
    ConfigDir --> Config_Readme
    ConfigDir --> FreefallUCF
    ConfigDir --> WakeUCF
    ConfigDir --> MLCUCF

    AppDir --> AppIndex
    AppDir --> SensorReadme
    AppDir --> ASM_H
    AppDir --> LSM_Shake
    AppDir --> ASM_UCF
    AppDir --> LIS_Glance

    FreefallUCF -->|fed into| ConfigLoader
    WakeUCF -->|fed into| ConfigLoader
    MLCUCF -->|fed into| ConfigLoader
    ASM_UCF -->|fed into| ConfigLoader
    LIS_Glance -->|fed into| ConfigLoader

    ConfigLoader -->|write config| Bus
    Bus -->|transmit .ucf| FSMCore
    SensorCore -->|data stream| FSMCore
    FSMCore -->|event| Interrupt
    Interrupt -->|signal| MainApp
    MainApp -->|uses| BusDriver
    MainApp -->|respond| Interrupt

    %% Click events
    click Docs_README "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/README.md"
    click Docs_CONTRIBUTING "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/CONTRIBUTING.md"
    click Docs_LICENSE "https://github.com/stmicroelectronics/stmems_finite_state_machine/tree/master/LICENSE"
    click ExternalTool "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/README.md"
    click ConfigDir "https://github.com/stmicroelectronics/stmems_finite_state_machine/tree/master/configuration_examples/"
    click Config_Readme "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/configuration_examples/README.md"
    click FreefallUCF "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/configuration_examples/example_0_fsm/utils/freefall.ucf"
    click WakeUCF "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/configuration_examples/example_1_fsm_mlc_filter/utils/wake_up_no_filter.ucf"
    click MLCUCF "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/configuration_examples/example_2_fsm_mlc_decision_tree/utils/mlc_motion_intensity.ucf"
    click AppDir "https://github.com/stmicroelectronics/stmems_finite_state_machine/tree/master/application_examples/"
    click AppIndex "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/README.md"
    click SensorReadme "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/ism330bx/README.md"
    click ASM_H "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/asm330lhhx/Motion-Stationary detection/asm330lhhx_motion_stationary.h"
    click LSM_Shake "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/lsm6dso/Shake detection/lsm6dso_shake.h"
    click ASM_UCF "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/asm330lhhx/Shake detection/asm330lhhx_shake.ucf"
    click LIS_Glance "https://github.com/stmicroelectronics/stmems_finite_state_machine/blob/master/application_examples/lis2dux12/Glance detection/lis2dux12_glance_detection.ucf"

    %% Styles
    classDef docs fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef tools fill:#d9d9d9,stroke:#333
    classDef config fill:#e6e6e6,stroke:#333
    classDef app fill:#cce5ff,stroke:#333
    classDef host fill:#b3d7ff,stroke:#333
    classDef bus fill:#ffcc99,stroke:#333
    classDef sensor fill:#d4edda,stroke:#333
```
