Architecture

Overview

Kinematrix is built on a modular conditional compilation architecture that allows you to include only the components you need, optimizing memory usage from 50KB (minimal) to 500KB+ (full-featured) depending on your platform and requirements.

This architecture is crucial for embedded systems where memory is limited. On an Arduino Uno with only 2KB of SRAM, you can still use core sensor functionality by enabling only essential modules.

Core Architecture Principles

Modular Design

156+ independent modules that can be selectively included based on project requirements.

Conditional Compilation

Preprocessor directives enable/disable modules at compile time, eliminating unused code from the binary.

Platform Abstraction

Unified API works across ESP32, ESP8266, and AVR platforms with automatic platform detection.

Hierarchical Organization

Logical grouping of functionality into modules, sensors, and add-ons with clear dependency management.

Project Structure

Kinematrix follows a carefully organized directory structure:

KinematrixBeta/
├── src/                          # Main library headers
│   ├── Kinematrix.h             # Master include file
│   ├── KinematrixModules.h      # Production module orchestration
│   ├── KinematrixModulesHelper.h # Development module orchestration
│   ├── KinematrixModulesNoDef.h # Header-only module orchestration
│   ├── KinematrixSensor.h       # Sensor framework orchestration
│   ├── KinematrixSensorHelper.h # Sensor helper functions
│   ├── KinematrixSensorNoDef.h  # Header-only sensor orchestration
│   ├── KinematrixDevelopment.h  # Development modules
│   └── KinematrixAddons.h       # Complete application systems
├── lib/
│   ├── enable.h                 # Master module control (156+ modules)
│   ├── modules/                 # Core functionality modules
│   │   ├── communication/       # Wired/Wireless protocols
│   │   ├── control/             # Control algorithms (PID, Fuzzy, ML)
│   │   ├── wifi/               # Internet/Cloud services
│   │   ├── display/            # Display systems
│   │   ├── driver/             # Hardware drivers
│   │   ├── file/               # File system operations
│   │   ├── filter/             # Signal filtering algorithms
│   │   ├── io/                 # I/O expansion modules
│   │   ├── task/               # Task management
│   │   ├── time/               # Timer systems
│   │   ├── utils/              # Utility functions
│   │   └── debug/              # Debugging tools
│   ├── sensors/                 # Dual sensor framework
│   │   ├── SensorModuleV1/     # V1 sensors (40+ types)
│   │   └── SensorModuleV2/     # V2 sensors (14+ types)
│   └── addons/                  # Complete application systems
│       └── AutoLightv3/         # LED control ecosystem
├── example/                     # 254+ example files
├── platformio.ini              # Build system configuration
└── index.py                    # Development workflow script

Triple Include System

Kinematrix implements a sophisticated three-tier include system for maximum flexibility:

Production Files
Helper Files
Header-Only Files

KinematrixModules.h and KinematrixSensor.hInclude both header (.h) and implementation (.cpp) files:

// KinematrixModules.h pattern
#ifdef ENABLE_MODULE_PID_CONTROLLER
#include "../lib/modules/control/PIDController.h"
#include "../lib/modules/control/PIDController.cpp"
#endif

Use case: Production code with full functionality

88 modules with 97 .cpp includes
Complete implementation included
Ready for deployment

KinematrixModulesHelper.h and KinematrixSensorHelper.hDevelopment and helper utilities with full implementation:

// KinematrixModulesHelper.h pattern
#ifdef ENABLE_MODULE_HELPER_PID_CONTROLLER
#include "../lib/modules/control/PIDController.h"
#include "../lib/modules/control/PIDController.cpp"
#endif

Use case: Development and debugging

Same structure as production (88 modules, 97 .cpp)
Separate enable flags for isolation
Helper utilities and debugging tools

KinematrixModulesNoDef.h and KinematrixSensorNoDef.hInclude only header files without implementation:

// KinematrixModulesNoDef.h pattern
#ifdef ENABLE_MODULE_NODEF_PID_CONTROLLER
#include "../lib/modules/control/PIDController.h"
// No .cpp include
#endif

Use case: Custom build configurations

Header-only inclusion (88 modules, 0 .cpp)
Link implementation separately
Advanced users who manage linking manually

Conditional Compilation System

The heart of Kinematrix’s memory optimization is its conditional compilation system.

How It Works

Define Required Modules

Before including Kinematrix.h, define which modules you need:

#define ENABLE_SENSOR_MODULE_V2
#define ENABLE_SENSOR_BME680_V2
#define ENABLE_MODULE_PID_CONTROLLER

Include Master Header

The master header orchestrates all enabled modules:

#include "Kinematrix.h"

Compilation Process

The preprocessor:

Checks which modules are enabled
Includes only the enabled module headers and implementations
Excludes all disabled modules from the binary
Links only the required dependencies

Result

Final binary contains only the code you use:

Minimal memory footprint
Faster compilation
Smaller flash usage

Module Enable Flags

All 156+ modules are controlled via enable flags defined in lib/enable.h:

Sensor Modules (78 flags)

// Sensor Framework
#define ENABLE_SENSOR_MODULE_V1
#define ENABLE_SENSOR_MODULE_V2

// V1 Sensors (40+ types)
#define ENABLE_SENSOR_DHT_V1
#define ENABLE_SENSOR_BME280_V1
#define ENABLE_SENSOR_DS18B20_V1
#define ENABLE_SENSOR_ANALOG_V1
// ... 36+ more sensors

// V2 Sensors (14+ types)
#define ENABLE_SENSOR_BME680_V2
#define ENABLE_SENSOR_ANALOG_V2
#define ENABLE_SENSOR_DHT_V2
// ... 11+ more sensors

// Calibration & Utilities
#define ENABLE_SENSOR_CALIBRATION_V2
#define ENABLE_SENSOR_UTILITY_V2
#define ENABLE_SENSOR_FILTER_V2
#define ENABLE_SENSOR_ALERT_SYSTEM_V2

Communication Modules (15 flags)

// I2C Communication
#define ENABLE_MODULE_I2C_EXPANDER
#define ENABLE_MODULE_I2C_SCANNER
#define ENABLE_MODULE_IO_EXPANDER

// Modbus
#define ENABLE_MODULE_MODBUS

// Serial Variants
#define ENABLE_MODULE_SERIAL_ENHANCED
#define ENABLE_MODULE_SERIAL_HARD
#define ENABLE_MODULE_SERIAL_SOFT

// LoRa
#define ENABLE_MODULE_LORA_COM
#define ENABLE_MODULE_LORA_COM_V2
#define ENABLE_MODULE_LORA_EBYTE_E220

// ESP-NOW
#define ENABLE_MODULE_ESP_NOW

Control Algorithms (7 flags)

// PID Controllers
#define ENABLE_MODULE_PID
#define ENABLE_MODULE_PID_CONTROLLER

// Fuzzy Logic
#define ENABLE_MODULE_FUZZY_MAMDANI
#define ENABLE_MODULE_FUZZY_SUGENO
#define ENABLE_MODULE_FUZZY_TSUKAMOTO

// Machine Learning
#define ENABLE_MODULE_DECISION_TREE
#define ENABLE_MODULE_KNN

WiFi/Cloud Services (21 flags)

// WiFi Management
#define ENABLE_MODULE_WIFI_HANDLER
#define ENABLE_MODULE_WIFI_HANDLER_V2

// MQTT
#define ENABLE_MODULE_MQTT_MANAGER

// Firebase (3 versions)
#define ENABLE_MODULE_FIREBASE_RTDB_V3
#define ENABLE_MODULE_FIREBASE_FIRESTORE_V3
#define ENABLE_MODULE_FIREBASE_STORAGE_V3
#define ENABLE_MODULE_FIREBASE_MESSAGING_V3

// Cloud Integrations
#define ENABLE_MODULE_GOOGLE_SHEETS
#define ENABLE_MODULE_TELEGRAM_BOT
#define ENABLE_MODULE_WHATSAPP_BOT

// Time Synchronization
#define ENABLE_MODULE_DATETIME_NTP
#define ENABLE_MODULE_DATETIME_NTP_V2

Other Modules (35 flags)

Display systems, file operations, I/O expansion, filters, timers, utilities, and debugging tools.See lib/enable.h for the complete list of 156+ modules.

Platform Abstraction Layer

Kinematrix provides a unified API across different platforms with automatic detection and optimization:

// Platform detection (automatic)
#if defined(ESP32)
    #define PLATFORM_ESP32
    #include <WiFi.h>
    #include <SPIFFS.h>
#elif defined(ESP8266)
    #define PLATFORM_ESP8266
    #include <ESP8266WiFi.h>
    #include <FS.h>
#else
    #define PLATFORM_AVR
    #include <EEPROM.h>
#endif

ESP32
ESP8266
Arduino AVR

Primary Target Platform

CPU: 240MHz dual-core Xtensa LX6
SRAM: 520KB
Flash: 4MB typical
Features: WiFi, Bluetooth, hardware crypto

Module Support:

✓ All 156+ modules supported
✓ Full cloud integration (Firebase, MQTT, Google Sheets)
✓ Advanced ML algorithms (Decision Trees, KNN)
✓ SPIFFS/SD card file systems
✓ FreeRTOS task management

Typical Memory Usage:

Minimal: ~100KB Flash, ~20KB SRAM
Standard: ~300KB Flash, ~60KB SRAM
Full-featured: ~600KB Flash, ~150KB SRAM

Dual Sensor Framework

Kinematrix implements two parallel sensor frameworks for different use cases:

SensorModuleV1

Legacy Framework

Callback-based architecture
40+ sensor implementations
Mature and battle-tested
Lower memory overhead
Simpler API for beginners

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

DHTSens dht(2, DHT22);
dht.init();
float temp = dht.getTemperature();

SensorModuleV2

Modern Framework

Type-safe template-based design
14+ advanced sensor implementations
Real-time filtering (Kalman, MA, Median)
Alert system with callbacks
Interactive calibration
JSON-based data storage

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

SensorModuleV2 sensors;
BME680SensV2 bme;
sensors.addSensor("env", &bme);
sensors.init();
sensors.update();
float temp = bme.getFloatValue("temperature");

When to Use Which Framework

Use V1 When...
Use V2 When...

Memory is severely constrained (AVR platforms)
You need maximum sensor variety (40+ types)
Simple projects without advanced features
Legacy code compatibility required
Learning embedded systems basics

Memory Optimization Strategies

Module Selection

Enable only required modules:

// BAD - All modules enabled
#include "lib/enable.h"  // Enables all 156+ modules
#include "Kinematrix.h"

// GOOD - Selective enabling
#define ENABLE_SENSOR_MODULE_V2
#define ENABLE_SENSOR_ANALOG_V2
#include "Kinematrix.h"

Savings: 400KB+ Flash, 100KB+ SRAM on full vs minimal

Use Lighter Variants

Many modules have lightweight versions:

// Instead of full debugger (12KB)
#define ENABLE_MODULE_SERIAL_DEBUGGER

// Use lite version (3KB)
#define ENABLE_MODULE_SERIAL_DEBUGGER_LITE

Optimize Data Structures

Use appropriate data types:

// BAD - Wastes memory
double temperature;  // 8 bytes

// GOOD - Sufficient precision
float temperature;   // 4 bytes

// BETTER - For whole numbers
int16_t tempC;      // 2 bytes (range: -32768 to 32767)

Platform-Specific Optimization

Use preprocessor directives:

#ifdef PLATFORM_ESP32
    // Use feature-rich implementation
    #define BUFFER_SIZE 1024
#elif defined(PLATFORM_ESP8266)
    // Optimize for ESP8266
    #define BUFFER_SIZE 512
#else
    // Minimal for AVR
    #define BUFFER_SIZE 128
#endif

Build System

Kinematrix supports multiple build systems:

PlatformIO
Arduino IDE
Development Workflow

Recommended for professional development

[env:esp32dev]
platform = espressif32
board = esp32doit-devkit-v1
framework = arduino

# Enable specific modules via build flags
build_flags = 
    -DENABLE_SENSOR_MODULE_V2
    -DENABLE_MODULE_WIFI_HANDLER_V2
    -DENABLE_MODULE_MQTT_MANAGER

lib_deps = 
    bblanchon/ArduinoJson@^7.0.0

monitor_speed = 115200

Commands:

pio run                    # Build
pio run --target upload    # Upload
pio device monitor         # Serial monitor
pio run --target clean     # Clean build

Suitable for beginners and simple projectsModule configuration via sketch defines:

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

Build Process:

Sketch → Verify/Compile
Sketch → Upload
Tools → Serial Monitor

For advanced Kinematrix development

# Main development command
python3 ./index.py

# AutoLight V3 WebClient
cd lib/addons/AutoLightv3/WebClient
npm run dev        # Development server
npm run build      # Production build

# C++ Testing Framework
cd lib/addons/AutoLightv3/WebClient/test
npm run test -- --sequence 2  # Test specific sequence

Best Practices

Start Minimal

Begin with only essential modules and add as needed. Easier to add than remove.

Profile Memory

Use build system tools to monitor Flash and SRAM usage:

pio run --verbose  # Shows memory usage

Test Early

Test on target hardware early. Memory issues appear differently on ESP32 vs ESP8266.

Use Examples

Study the 254+ examples to understand module usage patterns and memory-efficient coding.

Next Steps

Module Reference

Complete reference for all 156+ modules

Sensor Guide

Detailed guide to the dual sensor framework

Examples

Browse 254+ working examples by category

API Documentation

Full API reference for all classes and functions

Getting Started

Core Concepts

Sensor Framework

Communication

Control Algorithms

WiFi & Cloud Services

AutoLight System

Guides

Overview

Core Architecture Principles

Modular Design

Conditional Compilation

Platform Abstraction

Hierarchical Organization

Project Structure

Triple Include System

Conditional Compilation System

How It Works

Module Enable Flags

Platform Abstraction Layer

Dual Sensor Framework

SensorModuleV1

SensorModuleV2

When to Use Which Framework

Memory Optimization Strategies

Build System

Best Practices

Start Minimal

Profile Memory

Test Early

Use Examples

Next Steps

Module Reference

Sensor Guide

Examples

API Documentation

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Sensor Framework

Communication

Control Algorithms

WiFi & Cloud Services

AutoLight System

Guides

​Overview

​Core Architecture Principles

Modular Design

Conditional Compilation

Platform Abstraction

Hierarchical Organization

​Project Structure

​Triple Include System

​Conditional Compilation System

​How It Works

​Module Enable Flags

​Platform Abstraction Layer

​Dual Sensor Framework

SensorModuleV1

SensorModuleV2

​When to Use Which Framework

​Memory Optimization Strategies

​Build System

​Best Practices

Start Minimal

Profile Memory

Test Early

Use Examples

​Next Steps

Module Reference

Sensor Guide

Examples

API Documentation

Build docs developers (and LLMs) love

Overview

Core Architecture Principles

Project Structure

Triple Include System

Conditional Compilation System

How It Works

Module Enable Flags

Platform Abstraction Layer

Dual Sensor Framework

When to Use Which Framework

Memory Optimization Strategies

Build System

Best Practices

Next Steps