Installation

Prerequisites

Before installing Kinematrix, ensure you have one of the following development environments:

PlatformIO

Recommended - Advanced build system with better dependency management and multi-platform support.

Arduino IDE

Traditional Arduino development environment with library manager support.

Supported Platforms

ESP32
ESP8266
Arduino AVR

ESP32 DevKit v1
ESP32-WROOM-32
ESP32-S2/S3/C3
Any ESP32-based board

Features: Full framework support including WiFi, Bluetooth, Firebase, MQTT, and all 156+ modules.

Installation Methods

PlatformIO (Recommended)
Arduino IDE
Manual Installation

Install PlatformIO

If you haven’t installed PlatformIO yet:

# Install PlatformIO Core (CLI)
pip install platformio

# Or use VS Code extension
# Search for "PlatformIO IDE" in VS Code extensions

Clone Kinematrix Repository

Clone the repository to your Arduino libraries folder:

# For Linux/macOS
cd ~/.platformio/lib
git clone https://github.com/iwandwip/Kinematrix.git

# For Windows
cd %USERPROFILE%\.platformio\lib
git clone https://github.com/iwandwip/Kinematrix.git

Alternatively, you can clone to your project’s lib/ directory for project-specific installation.

Configure platformio.ini

Add Kinematrix and required dependencies to your platformio.ini:

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

; Build flags for enabling specific modules
build_flags = 
    -DENABLE_SENSOR_MODULE_V2
    -DENABLE_MODULE_WIFI_HANDLER_V2
    -DENABLE_MODULE_MQTT_MANAGER

; Common dependencies
lib_deps = 
    bblanchon/ArduinoJson@^7.0.0
    adafruit/Adafruit Unified Sensor@^1.1.0
    adafruit/Adafruit BME680 Library@^2.0.0
    knolleary/PubSubClient@^2.8.0

monitor_speed = 115200

Verify Installation

Build a simple test project:

pio run

You should see compilation messages:

[INFO]: compiling Kinematrix started
[INFO]: compiling Kinematrix done

Clone to Libraries Folder

Clone Kinematrix to your Arduino libraries directory:

# For Linux/macOS
cd ~/Arduino/libraries
git clone https://github.com/iwandwip/Kinematrix.git

# For Windows
cd %USERPROFILE%\Documents\Arduino\libraries
git clone https://github.com/iwandwip/Kinematrix.git

Install Dependencies

Open Arduino IDE and install required libraries via Library Manager (Sketch → Include Library → Manage Libraries):

ArduinoJson (by Benoit Blanchon)
Adafruit Unified Sensor
Adafruit BME280/BME680 Library (depending on your sensors)
PubSubClient (for MQTT)

Make sure to install compatible versions. Kinematrix works best with ArduinoJson v7+.

Select Board and Port

Configure your board:

Go to Tools → Board and select your microcontroller
Go to Tools → Port and select the correct COM port
Verify board-specific settings (CPU frequency, flash size, etc.)

Test Installation

Create a new sketch and include Kinematrix:

#include "Kinematrix.h"

void setup() {
    Serial.begin(115200);
    Serial.println("Kinematrix installed successfully!");
}

void loop() {
    delay(1000);
}

Click Verify to compile. You should see successful compilation.

Download Repository

Download Kinematrix as a ZIP file from GitHub:

wget https://github.com/iwandwip/Kinematrix/archive/refs/heads/main.zip
unzip main.zip

Copy to Libraries

Copy the extracted folder to your libraries directory and rename it to Kinematrix:

# For PlatformIO
cp -r Kinematrix-main ~/.platformio/lib/Kinematrix

# For Arduino IDE
cp -r Kinematrix-main ~/Arduino/libraries/Kinematrix

Install Dependencies

Manually install all required dependencies listed in the PlatformIO tab above.

Common Dependencies

Depending on which modules you enable, you may need these libraries:

Core Dependencies (Always Required)

bblanchon/ArduinoJson@^7.0.0

Used for JSON document handling in sensor framework and data serialization.

Sensor Dependencies

adafruit/Adafruit Unified Sensor@^1.1.0
adafruit/Adafruit BME280 Library@^2.2.0
adafruit/Adafruit BME680 Library@^2.0.0
adafruit/DHT sensor library@^1.4.0
adafruit/Adafruit INA219@^1.2.0
dallas/DallasTemperature@^3.9.0

Communication Dependencies

knolleary/PubSubClient@^2.8.0          # MQTT
sandeepmistry/LoRa@^0.8.0              # LoRa communication

Display Dependencies

adafruit/Adafruit SSD1306@^2.5.0       # OLED displays
adafruit/Adafruit GFX Library@^1.11.0  # Graphics primitives
marcoschwartz/LiquidCrystal_I2C@^1.1.4 # LCD I2C

WiFi/Cloud Dependencies

mobizt/Firebase ESP32 Client@^4.4.0    # Firebase integration

WiFi libraries (WiFi.h for ESP32, ESP8266WiFi.h for ESP8266) are included in the board packages.

Module Configuration

Kinematrix uses conditional compilation to include only the modules you need. There are two ways to configure modules:

Method 1: Edit `lib/enable.h` (Global Configuration)

// lib/enable.h - Enable modules globally
#define ENABLE_SENSOR_MODULE_V2
#define ENABLE_SENSOR_BME680_V2
#define ENABLE_MODULE_WIFI_HANDLER_V2
#define ENABLE_MODULE_MQTT_MANAGER
#define ENABLE_MODULE_PID_CONTROLLER

// Then in your sketch:
#include "Kinematrix.h"

Editing lib/enable.h affects all projects using this Kinematrix installation. Use this for consistent project configurations.

Method 2: Define Before Include (Per-Sketch Configuration)

// Your sketch.ino - Define modules per sketch
#define ENABLE_SENSOR_MODULE_V2
#define ENABLE_SENSOR_BME680_V2
#define ENABLE_MODULE_MQTT_MANAGER

#include "Kinematrix.h"

// Your code here

This method is recommended for project-specific module selection and keeps your global installation clean.

Verification

Test your installation with this complete example:

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

SensorModuleV2 sensors;
AnalogSensV2 analog(A0);

void setup() {
    Serial.begin(115200);
    delay(1000);
    
    Serial.println("=== Kinematrix Installation Test ===");
    Serial.println("Version: 0.0.28 Beta");
    
    // Initialize sensor
    JsonDocument doc;
    analog.setDocumentValue(&doc);
    analog.setDocument("analog");
    
    if (analog.init()) {
        Serial.println("✓ Sensor initialized successfully");
    } else {
        Serial.println("✗ Sensor initialization failed");
    }
    
    sensors.addSensor("test", &analog);
    Serial.println("✓ Installation verified!");
}

void loop() {
    sensors.update();
    Serial.print("Analog Value: ");
    Serial.println(analog.getFloatValue("value"));
    delay(1000);
}

Expected output:

=== Kinematrix Installation Test ===
Version: 0.0.28 Beta
✓ Sensor initialized successfully
✓ Installation verified!
Analog Value: 512.34
Analog Value: 513.12
...

Troubleshooting

Compilation Error: 'Kinematrix.h' file not found

Solution: Ensure Kinematrix is in the correct libraries folder:

PlatformIO: ~/.platformio/lib/Kinematrix or project/lib/Kinematrix
Arduino IDE: ~/Arduino/libraries/Kinematrix

Restart your IDE after installation.

Compilation Error: Multiple definition of [module name]

Cause: Module enabled in both lib/enable.h and sketch with different configurations.Solution: Choose one configuration method (either global or per-sketch) and stick with it.

Out of Memory / Stack Overflow

Cause: Too many modules enabled for your platform.Solution:

Disable unused modules
Use lighter module variants (e.g., SerialDebuggerLite instead of SerialDebugger)
Upgrade to a platform with more memory (ESP32 instead of ESP8266 or AVR)

Upload Failed / Port Not Found

Solution:

Check USB cable connection
Install CH340/CP2102 drivers if needed
Verify correct port selection in IDE
Press BOOT button on ESP32 during upload if auto-reset fails

Next Steps

Quick Start Guide

Build your first complete IoT project with Kinematrix

Architecture Overview

Learn about the modular compilation system and framework design

Getting Started

Core Concepts

Sensor Framework

Communication

Control Algorithms

WiFi & Cloud Services

AutoLight System

Guides

Prerequisites

PlatformIO

Arduino IDE

Supported Platforms

Installation Methods

Common Dependencies

Module Configuration

Method 1: Edit `lib/enable.h` (Global Configuration)

Method 2: Define Before Include (Per-Sketch Configuration)

Verification

Troubleshooting

Next Steps

Quick Start Guide

Architecture Overview

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Sensor Framework

Communication

Control Algorithms

WiFi & Cloud Services

AutoLight System

Guides

​Prerequisites

PlatformIO

Arduino IDE

​Supported Platforms

​Installation Methods

​Common Dependencies

​Module Configuration

​Method 1: Edit lib/enable.h (Global Configuration)

​Method 2: Define Before Include (Per-Sketch Configuration)

​Verification

​Troubleshooting

​Next Steps

Quick Start Guide

Architecture Overview

Build docs developers (and LLMs) love

Prerequisites

Supported Platforms

Installation Methods

Common Dependencies

Module Configuration

Method 1: Edit `lib/enable.h` (Global Configuration)

Method 2: Define Before Include (Per-Sketch Configuration)

Verification

Troubleshooting

Next Steps