Technical Documentation V1.0

Overview

The MakerBuddy IoT Kit is a comprehensive ESP32-based development platform featuring:

• ESP32 microcontroller with built-in Wi-Fi and Bluetooth
• 12+ integrated sensors for environmental monitoring
• Multiple actuators for control and output
• RESTful API for easy web-based control
• Web dashboard for real-time monitoring
• Automation rules engine for intelligent responses

Hardware Specifications

🛠️ Hardware/Components Requirements

If you do not have the complete MakerBuddy IoT Kit, please ensure that all the following components are procured and assembled before proceeding.

Sensors

DHT11

Temp: 0-50°C | Hum: 20-90%

DS18B20

-55 to 125°C | Waterproof

HC-SR04

2-400cm Range | Ultrasonic

MQ-2

Gas/Smoke | Analog Output

Soil Moisture

Capacitive | Analog Output

PIR Motion

Digital Output | Infrared

Actuators

LED

PWM Control

RGB LED

Full Color | PWM

Buzzer

Active | Digital

Relay

5V/10A | Isolation

Servo

0-180° | SG90

LCD 1602

I2C Interface | 16x2 Chars

Pin Configuration

Detailed pin mapping for the ESP32 IoT Kit:

REST API Reference

All API endpoints use HTTP protocol. Replace {ESP32_IP} with your device's IP address.

GET /api/sensors

Retrieves current readings from all sensors and device states.

GET http://{ESP32_IP}/api/sensors

{
    "temperature": 25.5,
    "humidity": 65.0,
    "ds18b20Temp": 24.8,
    "lightLevel": 75,
    "potValue": 50,
    "gasLevel": 15,
    "soilMoisture": 45,
    "distance": 123.5,
    "motionDetected": false,
    "buttonPressed": false,
    "ledState": true,
    "ledPWM": 255,
    "rgbR": 255,
    "rgbG": 0,
    "rgbB": 0,
    "servoPosition": 90,
    "freeHeap": 234567
}

Response Fields

POST /api/led

Controls the single LED.

Parameters

POST http://{ESP32_IP}/api/led

state=true&pwm=200&blink=false

JavaScript Example

fetch('http://192.168.1.100/api/led', {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: 'state=true&pwm=200&blink=false'
});

POST /api/rgb

Controls the RGB LED color.

Parameters

POST http://{ESP32_IP}/api/rgb

r=255&g=0&b=128

Common Colors

• Red: r=255, g=0, b=0
• Green: r=0, g=255, b=0
• Blue: r=0, g=0, b=255
• White: r=255, g=255, b=255
• Yellow: r=255, g=255, b=0
• Purple: r=255, g=0, b=255
• Cyan: r=0, g=255, b=255
• Off: r=0, g=0, b=0

POST /api/potmapping

Maps the potentiometer to control different actuators in real-time.

Mapping Modes

Request Examples

// Map to LED
POST http://{ESP32_IP}/api/potmapping
mode=led

// Map to Servo
POST http://{ESP32_IP}/api/potmapping
mode=servo

// Disable Mapping
POST http://{ESP32_IP}/api/potmapping
mode=none

JavaScript Example

// Map potentiometer to control LED brightness
fetch('http://192.168.1.100/api/potmapping', {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: 'mode=led'
});
// Now turning the physical potentiometer will adjust LED brightness
// from 0 (off) to 255 (full brightness)

Reading Mapped Values

The current mapping mode and values are included in the /api/sensors response:

{
  "potValue": 50,        // Raw potentiometer percentage (0-100)
  "potMapping": "led",   // Current mapping mode
  "potMappedValue": 127  // Converted output value (0-255 for LED)
}

Use Cases

• LED Mode: Create a physical dimmer switch for lighting control
• RGB Mode: Adjust ambient lighting brightness
• Servo Mode: Manually control servo position (door opener, camera angle, etc.)
• None Mode: Use potentiometer value as a sensor input for automation rules

POST /api/relay

Controls the relay module for switching high-power devices.

POST http://{ESP32_IP}/api/relay

state=true&onDelay=0&offDelay=0

POST /api/servo

Controls the servo motor position.

POST http://{ESP32_IP}/api/servo

position=90

POST /api/buzzer

Activates the buzzer.

POST http://{ESP32_IP}/api/buzzer

state=true

POST /api/lcd

Controls the LCD display mode and custom text.

POST http://{ESP32_IP}/api/lcd

mode=custom&text1=Hello%20World&text2=ESP32%20IoT%20Kit

Automation Rules API

Manage automation rules for the device.

POST /api/rules (Add Rule)

Creates a new automation rule.

{
  "action": "add",
  "name": "Temp Alert",
  "condition": "temperature",
  "operator": ">",
  "threshold": 30.0,
  "actionType": "buzzer_on",
  "actionValue": 0,
  "enabled": true
}

Available Conditions

• temperature, humidity, ds18b20Temp
• lightLevel, gasLevel, soilMoisture
• distance, potValue

GET /api/device

Retrieves device information and status.

{
  "deviceName": "ESP32 IoT Kit",
  "version": "1.0",
  "ip": "192.168.1.100",
  "mac": "AA:BB:CC:DD:EE:FF",
  "uptime": 3600,
  "freeHeap": 234567
}

Arduino Code Structure

Understanding the firmware architecture and key components for the MakerBuddy IoT Kit.

Complete Code Overview

The firmware is built on the Arduino framework for ESP32 and consists of several integrated systems:

• Sensor Management System: Real-time data acquisition from 12+ sensors
• Web Server: RESTful API for remote control and monitoring
• Automation Engine: Rule-based decision making and automated responses
• Network Management: Wi-Fi connectivity with AP fallback mode
• Display System: LCD interface for local status display

1. Required Libraries

Install these libraries through Arduino IDE Library Manager before uploading:

// Core ESP32 & System
#include <WiFi.h>
#include <ESPAsyncWebServer.h>
#include <AsyncTCP.h>
#include <ArduinoJson.h>
#include <Preferences.h>

// Sensor Libraries
#include <DHT.h>
#include <OneWire.h>
#include <DallasTemperature.h>

// Actuators
#include <LiquidCrystal_I2C.h>
#include <ESP32Servo.h>
#include <Ticker.h>

2. Pin Configuration

#define PUSH_BUTTON_PIN 5
#define PIR_SENSOR_PIN 18
#define ULTRASONIC_TRIG_PIN 15
#define ULTRASONIC_ECHO_PIN 2
#define LDR_PIN 35
#define POTENTIOMETER_PIN 34
#define MQ2_GAS_PIN 33
#define SOIL_MOISTURE_PIN 32
#define SINGLE_LED_PIN 12
#define RGB_LED_R_PIN 13
#define RGB_LED_G_PIN 14
#define RGB_LED_B_PIN 27
#define SERVO_PIN 19
#define BUZZER_PIN 4
#define RELAY_PIN 23

3. Core Functions

setup() - System Initialization

Initializes all hardware, connects to Wi-Fi (or starts AP mode) and starts the web server. Loops through sensors to ensure valid types.

void setup() {
  Serial.begin(115200);
  pinMode(PUSH_BUTTON_PIN, INPUT_PULLUP);
  // ... Init other pins
  
  connectToWiFi(); // Tries STA then AP
  setupWebServer();
  
  // Start Tickers
  sensorTicker.attach(1.0, readSensors);
  ruleTicker.attach(2.0, processRules);
}

loop() - Main Loop

Handles button presses and LED blinking. Most heavy lifting is done by Ticker callbacks to prevent blocking.

4. Sensor & Rules Engine

readSensors() runs every second to update the global state. processRules() evaluates user-defined automation logic.

readSensors() - Data Acquisition

This function is the heart of the sensor monitoring system. It reads data from all 12+ sensors and updates the global sensorData structure.

void readSensors() {
  // Read DHT11 Sensor
  sensorData.temperature = dht.readTemperature();
  sensorData.humidity = dht.readHumidity();

  // Read DS18B20 Temperature
  ds18b20.requestTemperatures();
  sensorData.ds18b20Temp = ds18b20.getTempCByIndex(0);

  // Read Analog Sensors (map to 0-100%)
  sensorData.lightLevel = map(analogRead(LDR_PIN), 0, 4095, 0, 100);
  sensorData.potValue = map(analogRead(POTENTIOMETER_PIN), 0, 4095, 0, 100);
  sensorData.gasLevel = map(analogRead(MQ2_GAS_PIN), 0, 4095, 0, 100);
  sensorData.soilMoisture = map(analogRead(SOIL_MOISTURE_PIN), 0, 4095, 0, 100);

  // Read Ultrasonic Distance
  digitalWrite(ULTRASONIC_TRIG_PIN, LOW);
  delayMicroseconds(2);
  digitalWrite(ULTRASONIC_TRIG_PIN, HIGH);
  delayMicroseconds(10);
  digitalWrite(ULTRASONIC_TRIG_PIN, LOW);
  long duration = pulseIn(ULTRASONIC_ECHO_PIN, HIGH, 30000);
  sensorData.distance = duration * 0.034 / 2;

  // Read Digital Sensors
  sensorData.motionDetected = digitalRead(PIR_SENSOR_PIN);
  sensorData.buttonPressed = !digitalRead(PUSH_BUTTON_PIN);
}

processRules() - Automation Engine

The intelligent automation engine that makes your IoT kit "smart." Called every 2 seconds, it evaluates user-defined rules and automatically triggers actions.

void processRules() {
  for (int i = 0; i < ruleCount; i++) {
    if (!rules[i].enabled) continue;
    float sensorValue = getSensorValue(rules[i].condition);
    bool conditionMet = false;

    // Evaluate condition
    if (rules[i].operator_type == ">") {
      conditionMet = (sensorValue > rules[i].threshold);
    } else if (rules[i].operator_type == "<") {
      conditionMet = (sensorValue < rules[i].threshold);
    }

    // Execute action if condition is met
    if (conditionMet) {
      executeAction(rules[i].action, rules[i].actionValue);
    }
  }
}

5. Wi-Fi Management

void connectToWiFi() {
  if (ssid.length() > 0) {
    WiFi.mode(WIFI_STA);
    WiFi.begin(ssid.c_str(), password.c_str());
    lcd.clear();
    lcd.print("Connecting WiFi");
    
    int attempts = 0;
    while (WiFi.status() != WL_CONNECTED && attempts < 20) {
      delay(500);
      attempts++;
    }
    
    if (WiFi.status() == WL_CONNECTED) {
      lcd.clear();
      lcd.print("WiFi Connected");
      lcd.setCursor(0, 1);
      lcd.print(WiFi.localIP());
      return;
    }
  }
  startAPMode();
}

void startAPMode() {
  WiFi.mode(WIFI_AP);
  WiFi.softAP("ESP32-IoT-Kit", "12345678");
  lcd.clear();
  lcd.print("AP Mode");
  lcd.setCursor(0, 1);
  lcd.print(WiFi.softAPIP());
}

void resetWiFi() {
  preferences.clear();
  lcd.clear();
  lcd.print("WiFi Reset!");
  delay(2000);
  ESP.restart();
}

6. Uploading the Code

Arduino Sketch: MakerBuddy V1-0.ino

The complete ESP32 firmware with advanced features for sensor monitoring, web server, automation rules and Wi-Fi management.

Key Features

Firmware Specifications

Dashboard Application: index.html

A complete web-based IoT dashboard for real-time monitoring and control. No installation required - just open in your browser!

Dashboard Features

How to Use the Dashboard

Step 1: Connect to ESP32

1. Open app/index.html in your web browser
2. Enter your ESP32's IP address (shown on LCD display)
3. Click "Connect" button
4. Dashboard will display device info and sensor data

Step 2: Monitor Sensors

The top row displays real-time sensor readings: Temperature (DHT), Humidity, DS18B20 temp, Light Level, Gas Level, Soil Moisture, Potentiometer, Distance, Motion and Button state.

Step 3: Control Actuators

Use the control cards to interact with your IoT kit: LED (toggle + brightness), RGB LED (color sliders), Relay, Servo Motor, Buzzer and LCD Display.

Step 4: Create Automation Rules

1. Scroll to "Add Automation Rule" section
2. Enter rule name (e.g., "High Temperature Alert")
3. Select sensor condition (e.g., Temperature > 30)
4. Choose action (e.g., LED On, Buzzer, RGB color)
5. Click "Add Rule"

Step 5: Potentiometer Mapping

Select mapping mode (None, LED PWM, RGB LED or Servo) and turn the physical potentiometer to control actuators in real-time.

Example Projects

Ready-to-use examples to get you started quickly.

Example 1: Temperature Alert System

Automatically turn on LED and buzzer when temperature exceeds threshold.

// Add temperature alert rule
fetch('http://192.168.1.100/api/rules', {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: 'action=add&name=Temperature+Alert&condition=temperature&operator=>&threshold=30&actionType=led_on&actionValue=255'
});

Example 2: Automatic Night Light

Turn on LED when light level drops below 30%.

Example 3: Smart Plant Watering Alert

Alert when soil moisture is too low.

Example 4: Motion-Activated Servo (Python)

Rotate servo when motion is detected.

import requests
import time

ESP32_IP = "192.168.1.100"

while True:
    response = requests.get(f"http://{ESP32_IP}/api/sensors")
    data = response.json()
    
    if data['motionDetected']:
        print("Motion detected! Moving servo...")
        requests.post(f"http://{ESP32_IP}/api/servo", data={'position': 180})
        time.sleep(2)
        requests.post(f"http://{ESP32_IP}/api/servo", data={'position': 0})
    
    time.sleep(1)

Example 5: Gas Leak Detector

Alert system for gas detection with multiple outputs.

// Rule 1: Turn on red LED
action=add&name=Gas+Alert+LED&condition=gasLevel&operator=>&threshold=50&actionType=led_on

// Rule 2: Set RGB to red
action=add&name=Gas+Alert+RGB&condition=gasLevel&operator=>&threshold=50&actionType=rgb_red

// Rule 3: Activate buzzer
action=add&name=Gas+Alert+Sound&condition=gasLevel&operator=>&threshold=50&actionType=buzzer_on

Example 6: IoT Dashboard with Node.js

Create a simple Node.js server to monitor sensors.

const express = require('express');
const axios = require('axios');
const app = express();
const ESP32_IP = '192.168.1.100';

app.get('/sensors', async (req, res) => {
  try {
    const response = await axios.get(`http://${ESP32_IP}/api/sensors`);
    res.json(response.data);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch sensor data' });
  }
});

app.post('/led/:state', async (req, res) => {
  const state = req.params.state === 'on';
  await axios.post(`http://${ESP32_IP}/api/led`, `state=${state}&pwm=255`);
  res.json({ success: true });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Troubleshooting

Connection Issues

• Verify ESP32 and computer are on the same network
• Check IP address on LCD or serial monitor
• Ensure firewall isn't blocking port 80
• Try accessing http://{IP}/api/device to test

Sensor Reading Issues

• Check sensor connections to correct GPIO pins
• Verify sensor power (3.3V or 5V as required)
• DHT11/DHT22 may need warm-up time (2 seconds)
• DS18B20 requires 4.7kΩ pull-up resistor on data line

Upload Issues

• Install USB drivers (CH340 or CP2102)
• Hold BOOT button while uploading
• Lower upload speed in Arduino IDE
• Ensure correct board and port are selected

Wi-Fi Reset

To reset Wi-Fi credentials and return to setup mode:

1. Power on the ESP32
2. Press and hold the button for 10 seconds
3. LCD will show "WiFi Reset!"
4. Device will restart in AP mode
5. Connect to "ESP32-IoT-Kit" network and configure

Next Steps