# PSV 

**Repository Path**: MagicBude/PSV

## Basic Information

- **Project Name**: PSV 
- **Description**: 轻量级周期信号验证器 - 基于变异系数统计检测真实周期信号，过滤随机干扰。适用于流量计、转速、心率等传感器应用。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-07
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 嵌入式, 信号处理, stm32, 传感器, 滤波器

## README

# PSV - Periodic Signal Validator

> **PSV = Periodic Signal Validator**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Language: C](https://img.shields.io/badge/Language-C-blue.svg)](https://en.wikipedia.org/wiki/C_(programming_language))
[![Platform: Embedded](https://img.shields.io/badge/Platform-Embedded-green.svg)]()

English | [简体中文](README.md)

A lightweight periodic signal quality detector that distinguishes real periodic signals from random noise.

## ✨ Features

- ✅ **Lightweight**: ~60 bytes RAM, no dynamic memory allocation
- ✅ **Cross-platform**: STM32, Arduino, Linux, etc.
- ✅ **Easy Integration**: 3 API functions, simple to use
- ✅ **Configurable**: All parameters in config.h
- ✅ **Low Overhead**: CPU usage <1% (72MHz MCU, 1kHz signal)

## 🔬 Algorithm

### Core: Coefficient of Variation (CV)

```
CV = Standard Deviation / Mean

Real periodic signal:  CV < 0.1  (very regular)
Slight fluctuation:    CV = 0.1 ~ 0.15
Obvious fluctuation:   CV = 0.15 ~ 0.25
Noise signal:          CV > 0.3  (chaotic)
```

### Detection Flow

```
For each frequency pulse:
├─ 1. Within frequency range? ──No──> Reject
├─ 2. Change rate normal?     ──No──> Reject
├─ 3. Period regularity good? ──No──> Reject
├─ 4. Stable ≥N times?        ──No──> Wait for more data
└─ Yes ──> Accept signal
```

## 🎯 Applications

### Flow Sensors
- ✅ Vortex flowmeters (piezoelectric ceramic)
- ✅ Turbine flowmeters (Hall sensor)
- ✅ Gear flowmeters (photoelectric sensor)
- ✅ Electromagnetic flowmeters (frequency output)

### Speed Measurement
- ✅ Motor speed sensors
- ✅ Wheel speed (ABS)
- ✅ Fan speed monitoring

### Biological Signals
- ✅ Heart rate monitoring (PPG)
- ✅ Pulse oximetry
- ✅ ECG signal processing

### Vibration Monitoring
- ✅ Piezoelectric sensors
- ✅ Seismic monitoring
- ✅ Equipment vibration analysis

## 🚀 Quick Start

### 1. Copy Files to Your Project

```
your_project/
└── psv/
    ├── psv.h
    ├── psv.c
    └── psv_config.h
```

### 2. Configure Platform (psv_config.h)

```c
/* Modify timestamp function (required) */
#define PSV_GET_TICK_MS()       HAL_GetTick()  // Change to your platform

/* Set frequency range (required) */
#define PSV_FREQ_MIN_HZ         10      // Minimum frequency
#define PSV_FREQ_MAX_HZ         1000    // Maximum frequency
```

### 3. Use in Your Code

```c
#include "psv.h"

/* Initialize */
psv_init();

/* Detect in frequency callback */
void frequency_callback(uint32_t freq)
{
    if (psv_check(freq))  /* 1 = valid signal */
    {
        /* Process valid signal */
        process_valid_signal(freq);
    }
    /* Returns 0 for noise, automatically ignored */
}
```

Done! It's that simple.

## 📚 Documentation

- [Quick Start](docs/QUICK_START.md) - 5-minute tutorial
- [API Reference](docs/API.md) - Complete API documentation
- [Porting Guide](docs/PORTING.md) - Multi-platform porting

## 🔧 Configuration

### Frequency Range

```c
#define PSV_FREQ_MIN_HZ         10      /* Minimum valid frequency */
#define PSV_FREQ_MAX_HZ         1000    /* Maximum valid frequency */
```

### CV Threshold (Most Important!)

```c
#define PSV_PERIOD_CV_THRESHOLD     0.15f
```

Typical values:
- `0.10`: High stability requirement
- `0.15`: Standard application (recommended)
- `0.20~0.25`: Signals with large fluctuation

## 📖 Examples

### Example 1: Vortex Flowmeter (STM32)

```c
#include "psv.h"

void flowmeter_init(void)
{
    psv_init();
    /* Configure timer input capture... */
}

void TIM_Capture_IRQHandler(void)
{
    uint32_t freq = calculate_frequency();
    
    if (psv_check(freq))  /* PSV detection */
    {
        /* Valid signal, update flow rate */
        update_flow_rate(freq);
    }
}
```

### Example 2: Motor Speed (Arduino)

```c
#include "psv.h"

void setup() {
    psv_init();
    pinMode(HALL_PIN, INPUT_PULLUP);
    attachInterrupt(digitalPinToInterrupt(HALL_PIN), hall_isr, FALLING);
}

void hall_isr() {
    uint32_t rpm = calculate_rpm();
    if (psv_check(rpm)) {
        display_motor_speed(rpm);
    }
}
```

### Example 3: Signal Simulator (Linux)

```c
#include "psv.h"

/* Verify PSV algorithm on PC */
int main() {
    psv_init();
    
    /* Generate and test signals */
    for (int i = 0; i < 100; i++) {
        uint32_t freq = generate_signal();
        
        if (psv_check(freq)) {
            printf("Freq %u Hz: Valid\n", freq);
        }
    }
    
    /* Get statistics */
    PSV_Statistics_t stats;
    psv_get_statistics(&stats);
    printf("Accuracy: %.1f%%\n", calculate_accuracy(&stats));
}
```

**Full examples**: See `examples/` directory

## 💡 FAQ

### Q1: Stable signal rejected?
**A**: Increase `PSV_PERIOD_CV_THRESHOLD` to 0.20

### Q2: Noise not filtered?
**A**: Decrease `PSV_PERIOD_CV_THRESHOLD` to 0.10

### Q3: Response too slow?
**A**: Decrease `PSV_STABLE_COUNT_MIN` to 2

### Q4: How to debug?
**A**: Enable logging (`PSV_USE_LOG=2`), observe CV values

## 📊 Performance

| Metric | Value |
|--------|-------|
| RAM Usage | ~60 bytes |
| Flash Usage | ~1.5KB |
| CPU Usage | <1% (72MHz, 1kHz signal) |
| Response Delay | 0.5~1 second (initial lock) |

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🌟 Star Support

If this project helps you, please give it a ⭐Star!

## 📮 Contributing

- 💡 **Submit Issue**: [Issues](../../issues)
- 🔀 **Pull Request**: Contributions are welcome
- 📧 **Discussion**: Feel free to discuss in Issues

## 🙏 Acknowledgments

Thanks to all contributors and users!

---

**Version**: v1.0.0  
**Updated**: 2025-11-07  
**Status**: ✅ Production Ready  
**License**: MIT License