# Welcome to ThingESP

### Table of Contents

1. [Introduction](#introduction)
2. [Architecture Overview](#architecture-overview)
3. [Getting Started](#getting-started)
4. [ESP32 Integration](#esp32-integration)
5. [Raspberry Pi Integration](#raspberry-pi-integration)
6. [REST API Reference](#rest-api-reference)
7. [MQTT Topics & Payloads](#mqtt-topics-and-payloads)
8. [Authentication & Security](#authentication-and-security)
9. [Web Dashboard Guide](#web-dashboard-guide)
10. [FAQs](#faqs)
11. [Troubleshooting](#troubleshooting)
12. [Contributing](#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.

```cpp
#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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thingesp.com/docs/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.