Skip to main content

Introduction

Kinematrix provides a comprehensive dual-sensor framework supporting both legacy (V1) and modern (V2) sensor implementations. The framework enables unified sensor data collection, processing, and management across 50+ sensor types with advanced features including real-time filtering, alert systems, and calibration management.

Architecture

The sensor framework consists of two parallel implementations:
lib/sensors/
├── SensorModuleV1/          # Legacy sensor system (40+ sensors)
│   ├── base/               # Core V1 framework
│   ├── calibration/        # Calibration system
│   ├── addons/            # Filtering and debugging
│   └── [sensor]-sens.h    # Individual sensors
└── SensorModuleV2/         # Modern sensor framework (14+ sensors)
    ├── SensorModule/       # Core V2 framework
    │   ├── Systems/       # Alert and Filter systems
    │   └── Tools/         # Calibration tools
    └── SensorList/        # V2 sensor implementations

Key Features

Type Safety

Template-based type-safe data retrieval with compile-time checking (V2)

Real-Time Filtering

Moving Average, Kalman, Median, and Exponential filters for signal processing

Alert System

Threshold-based monitoring with customizable callbacks and debouncing

Calibration

Interactive calibration with EEPROM persistence and multi-point support

Framework Comparison

FeatureV1 (Legacy)V2 (Modern)
Sensors40+ sensors14+ sensors (expanding)
Data AccessDirect gettersTemplate-based
Type SafetyRuntimeCompile-time
FilteringBasic filteringAdvanced multi-algorithm
AlertsManual implementationBuilt-in alert system
CalibrationEEPROM-basedInteractive + EEPROM
MemoryModerateOptimized
APIFunction-basedTemplate + callback

Supported Sensor Categories

Environmental Monitoring

  • Temperature/Humidity: DHT11/22, AHT20, BME280, BME680, SCD30
  • Pressure: BME280, BME680 barometric sensors
  • Air Quality: Dust sensors, gas sensors (MQ series), CO2 sensors
  • Light: Analog light sensors, color sensors (TCS3200)

Industrial Sensors

  • Flow Measurement: Flow meters (V1/V2/V3 variants), water flow
  • Weight/Load: HX711 load cell sensors
  • Power Monitoring: INA219, PZEM004T energy meters
  • Temperature: DS18B20, MAX31865 (RTD), MAX6675, MLX90614 (IR)

Position & Motion

  • Distance: Ultrasonic sensors
  • GPS: NEO-6M/7M/8M GPS modules with TinyGPS++
  • RPM: Hall effect and optical RPM sensors
  • Orientation: Compass and tilt sensors

Identification & Input

  • RFID: MFRC522 card readers
  • Barcode: GM67 barcode scanners
  • Input: I2C keypads, rotary encoders
  • Time: RTC modules (DS1307, DS3231, PCF8523, PCF8563)

Analog & Digital I/O

  • Analog Sensors: Voltage, pH, TDS, turbidity, soil moisture
  • Digital Sensors: General digital input/output

Biometric

  • Pulse Oximeter: MAX30100, MAX3010x heart rate and SpO2

Quick Start

V1 Basic Usage

#define ENABLE_SENSOR_MODULE_V1
#define ENABLE_SENSOR_DHT_V1
#include "Kinematrix.h"

SensorModule sensors;
DHTSens dht(2, DHT22);

void setup() {
    sensors.addModule("temperature", &dht);
    sensors.init();
}

void loop() {
    sensors.update();
    float temp = sensors["temperature"]["temperature"];
    float humidity = sensors["temperature"]["humidity"];
}

V2 Basic Usage

#define ENABLE_SENSOR_MODULE_V2
#define ENABLE_SENSOR_DHT_V2
#include "Kinematrix.h"

SensorModuleV2 sensors;
DHTSensV2 dht(2, DHT22);

void setup() {
    dht.setUpdateInterval(2000);
    sensors.addSensor("temperature", &dht);
    sensors.init();
}

void loop() {
    sensors.update();
    
    if (sensors.isUpdated("temperature")) {
        float temp = sensors.getValue<float>("temperature", "temperature");
        float humidity = sensors.getValue<float>("temperature", "humidity");
    }
}

Core Classes

BaseSens (V1)

Base class for all V1 sensors:
class BaseSens {
public:
    virtual bool init() = 0;
    virtual bool update() = 0;
    virtual void getValue(float *output);
    virtual JsonVariant getVariant(const char *searchName);
};

BaseSensV2 (V2)

Modern base class with type safety:
class BaseSensV2 {
public:
    virtual bool init() = 0;
    virtual bool update() = 0;
    virtual bool isUpdated() const;
    
    template<typename T> T getValue(const char *key) const;
    void updateValue(const char *key, float value);
    void addValueInfo(const char *key, const char *label, 
                     const char *unit, uint8_t precision, bool calibrable);
};

Platform Support

ESP32

Full feature support with WiFi/BLE

ESP8266

Complete support with optimization

Arduino

Uno, Nano, Mega compatibility

Migration Guide

From V1 to V2

While V1 remains fully supported, V2 offers enhanced features: V1 Code:
DHTSens dht(2, DHT22);
sensors.addModule("temp", &dht);
float temp = sensors["temp"]["temperature"];
V2 Equivalent:
DHTSensV2 dht(2, DHT22);
dht.setUpdateInterval(2000);
sensors.addSensor("temp", &dht);
float temp = sensors.getValue<float>("temp", "temperature");

Advanced Features

Real-Time Filtering (V2)

FilterParams params;
params.movingAverage.windowSize = 10;
sensors.attachFilter("temp", "temperature", FILTER_MOVING_AVERAGE, params);
float filtered = sensors.getFilteredValue("temp", "temperature");

Alert System (V2)

// Alert when temperature exceeds range
sensors.setThreshold("temp", "temperature", 20.0, 30.0, ALERT_OUTSIDE);
sensors.setGlobalAlertCallback([](AlertInfo info) {
    Serial.print("Alert: ");
    Serial.println(info.currentValue);
});

Calibration (V2)

SensorCalibrationModuleV2 calibrator;
calibrator.addSensor("temp", &tempSensor);
calibrator.startCalibrationMode(&Serial, 300000);
calibrator.saveAllCalibrations(0);

Next Steps

Sensor Module V1

Explore the legacy sensor framework with 40+ sensors

Sensor Module V2

Learn about the modern sensor framework

Calibration

Interactive sensor calibration with EEPROM

Filtering

Real-time signal processing algorithms

Best Practices

Memory Management: Use sensor creation callbacks in V2 for automatic memory management:
sensors.addSensor("temp", []() -> BaseSensV2* {
    return new DHTSensV2(2, DHT22);
});
Update Intervals: Set appropriate intervals based on sensor characteristics:
  • Fast sensors (analog): 100-500ms
  • I2C sensors: 1000-2000ms
  • Complex sensors: 3000-5000ms
Coexistence: Both V1 and V2 frameworks can coexist in the same project, allowing gradual migration.

Build docs developers (and LLMs) love