Page cover

Welcome to ThingESP

Table of Contents

  1. Introduction

  2. Architecture Overview

  3. Getting Started

  4. ESP32 Integration

  5. Raspberry Pi Integration

  6. REST API Reference

  7. MQTT Topics & Payloads

  8. Authentication & Security

  9. Web Dashboard Guide

  10. FAQs

  11. Troubleshooting

  12. Contributing

Introduction

Welcome to ThingESP, the WhatsApp-controlled IoT messaging platform. ThingESP bridges your IoT devices and WhatsApp, enabling two-way messaging via a simple MQTT backbone and Twilio WhatsApp integration. This documentation will guide you through platform concepts, setup, and development examples.

Privacy & Data: ThingESP is a personal project developed and maintained solely by me. No user data is ever shared with third parties, stored beyond necessary transient message processing, or logged for analytics. All messages are relayed in real-time and NEVER persisted, ensuring complete privacy and control remain with you.

Architecture Overview

ThingESP Architecture consists of three primary components:

  • WhatsApp API (Twilio): Secure, encrypted transport for user-device messages.

  • ThingESP: Handles device authentication, message routing, MQTT broker connection, and dashboard services.

  • Client Libraries: Lightweight SDKs for ESP32/ESP8266 (Arduino/C++) and Raspberry Pi (Python) that subscribe to MQTT topics and relay messages.

Getting Started

  1. Sign Up & Login: Register on our portal and verify your email.

  2. Create a Project: Navigate to the dashboard and click Add New Project. Note your Project ID & Secret.

  3. Configure Twilio: In Twilio Console, set the incoming webhook for your WhatsApp number to your project’s callback URL.

  4. Install SDK: Choose your platform (ESP32 or Raspberry Pi) and follow the examples below.

ESP32 Integration

The ESP32 client library allows your device to connect over Wi-Fi, subscribe to MQTT topics, and handle incoming WhatsApp commands. Below is a complete example demonstrating LED control.

#include <WiFi.h>
#include <ThingESP.h>

ThingESP32 thing("username", "project_name", "credentials");

int LED = 2;

unsigned long previousMillis = 0;
const long INTERVAL = 6000;

void setup()
{
    Serial.begin(115200);

    pinMode(LED, OUTPUT);

    thing.SetWiFi("wifi_ssid", "wifi_password");

    thing.initDevice();
}

String HandleResponse(String query)
{

    if (query == "led on")
    {
        digitalWrite(LED, 1);
        return "Done: LED Turned ON";
    }

    else if (query == "led off")
    {
        digitalWrite(LED, 0);
        return "Done: LED Turned OFF";
    }

    else if (query == "led status")
        return digitalRead(LED) ? "LED is ON" : "LED is OFF";

    else
        return "Your query was invalid..";
}

void loop()
{

   // Handle incoming messages and callbacks
    thing.Handle(HandleResponse);
    
    
// Optional: send periodic status updates via WhatsApp
    // if (millis() - previousMillis >= INTERVAL)
    // {
    //     previousMillis = millis();
    //     String msg = digitalRead(LED) ? "LED is ON" : "LED is OFF";
    //     thing.sendMsg("PHONE_NUMBER", msg);
    // }

 // similarly device initialted messages can be sent using thing.sendMsg().
}

Code Explanation

  • Library Initialization: You provide your ThingESP username, project_name, and project_secret.

  • Wi-Fi Setup: SetWiFi(ssid, password) configures your network.

  • MQTT Connection: initDevice() registers the device and connects to the broker.

  • Message Handling: HandleResponse parses incoming text commands and returns appropriate responses.

  • Loop Logic: thing.Handle() polls for new messages and routes them through your callback.

  • Optional Status Updates: Uncomment the periodic block to push device state on a timer.

Raspberry Pi Integration

Coming up: Python example code for Raspberry Pi messaging client.

REST API Reference

Coming up: Detailed endpoints, request/response schemas, and examples.

MQTT Topics & Payloads

Coming up: Topic structure and JSON payload definitions.

Authentication & Security

Coming up: How tokens work, API keys, and best practices.

Web Dashboard Guide

Coming up: Using the portal to manage devices, view logs, and set up alerts.

FAQs

  • Can I use my own MQTT broker? Coming up in next version.

  • How many devices can I connect? Depends on your plan; default is 2.

Troubleshooting

Coming up: Common issues and steps for resolution.

Contributing

Coming up: We welcome contributions! Please see our [CONTRIBUTING.md] for guidelines on reporting issues, proposing features, and submitting pull requests.

Last updated