⚡ Inicio Rápido en 3 Minutos

Conecta tu primer microcontrolador ESP32 o sensor a la Plataforma IoT & SCADA Industrial y visualiza telemetría en tiempo real con aislamiento Multi-Tenant estricto.

💡 Requisitos Previos: Solo necesitas una placa ESP32 (DevKit v1), cable USB y tener instalado el Arduino IDE o PlatformIO.

Paso 1: Descargar la Librería Oficial

Descarga el paquete comprimido de la librería cliente desde el botón superior o el siguiente enlace:

📥 Descargar IotPlatformClient.zip (v1.0.0)

En Arduino IDE ve a: Programa > Incluir Librería > Añadir biblioteca .ZIP... y selecciona el archivo descargado.

Paso 2: Código Base de Conexión (C++)

#include <WiFi.h>
#include <IotPlatformClient.h>

// Reemplaza con tu red Wi-Fi y tus credenciales de Tenant
const char* WIFI_SSID = "TU_RED_WIFI";
const char* WIFI_PASS = "TU_CONTRASEÑA";

IotPlatformClient iot("smarthingsiot.vacup.online", 1883);

void setup() {
  Serial.begin(115200);
  WiFi.begin(WIFI_SSID, WIFI_PASS);

  // Iniciar cliente con Tenant, Device ID y Token
  iot.begin("casajr", "esp32-casajr-01", "sec_casajr_tok_8c1deb");
}

void loop() {
  iot.loop(); // FSM No-Bloqueante
  
  // Enviar métrica de temperatura con deadband de 0.2 °C
  iot.sendMetric("temperature", 24.5, 0.2);
  delay(1000);
}
        

Paso 3: Abre tu Consola y Dashboard

Accede a /t/casajr/hub para ver tu dispositivo en verde (🟢 ONLINE) con latencia menor a 1.0ms.

📘 Manual Oficial del Usuario

Guía operativa completa para la gestión de empresas, dispositivos, constructores visuales y automatizaciones.

1. Torre de Control de Empresa (Tenant Hub)

La consola central (/t/{slug}/hub) permite monitorear los KPIs globales de flota, rotar tokens de seguridad MQTT en caliente y personalizar la identidad de marca blanca (logotipos y colores).

2. Constructor Visual SCADA (Visual Studio)

Accede a /builder o /t/{slug}/builder para componer tableros industriales con arrastrar y soltar. Cada widget cuenta con manipulación directa: puedes arrastrar verticalmente sobre el líquido del silo o el dial del termostato para regular consignas.

3. Motor de Reglas IFTTT en Tiempo Real

Permite crear automatizaciones del tipo "Si la temperatura supera 28°C durante 3 segundos, encender el ventilador" con aislamiento estricto por Tenant.

4. Exportación de Informes de Calidad (PDF / CSV)

Descarga series temporales crudas en CSV o informes formales ejecutivos en PDF vectorial con sello de inmutabilidad criptográfica SHA-256.

🛠️ Librería Oficial Arduino (`IotPlatformClient`)

Biblioteca C++ ligera optimizada para microcontroladores ESP32, ESP8266 y microcontroladores compatibles con FreeRTOS.

Características de Ingeniería

Cero Bloqueos: Sin bucles while(!WiFi.isConnected()) que provoquen reseteos por Watchdog Timer (WDT).
Reconexión Inteligente: Backoff exponencial con jitter aleatorio (2s → 4s → 8s → máx 60s).
Filtrado Deadband: Ahorro de ancho de banda descartando micro-ruido en lecturas analógicas.
Recepción Bidireccional de Actuadores: Control instantáneo de relés y salidas PWM.

Ejemplo de Control de Actuador / Relé

void onActuatorReceived(const char* actuatorId, const char* action, float value) {
  if (strcmp(action, "on") == 0 || value > 0.0) {
    digitalWrite(RELAY_PIN, HIGH);
  } else {
    digitalWrite(RELAY_PIN, LOW);
  }
}

void setup() {
  pinMode(RELAY_PIN, OUTPUT);
  iot.onActuatorCommand(onActuatorReceived);
  iot.begin("casajr", "esp32-casajr-01", "token_secreto");
}
        

☁️ Compilador Cloud Dinámico & Resolutor de Dependencias

Genera y compila automáticamente firmware para ESP32 a la medida de tu proyecto, resolviendo únicamente las librerías necesarias según los sensores y actuadores seleccionados.

⚡ Cero-Hardcoded: El compilador inyecta tokens criptográficos, tenant_slug, mapa de pines GPIO y drivers específicos en un proyecto PlatformIO listo para compilar.

Endpoint de Compilación bajo Demanda:

POST /api/v1/projects/{project_id}/build-firmware
Content-Type: application/json

{
  "project_name": "Invernadero Inteligente",
  "tenant_slug": "agrofrio",
  "device_id": "esp32-invernadero-01",
  "target_mcu": "esp32dev",
  "peripherals": ["dht22", "oled", "relay", "hmi"],
  "offline_hmi": true,
  "deadband": 0.2
}
        

🎛️ Micro-HMI Autónomo en el Borde (Offline Standalone SCADA)

Aloja el dashboard SCADA construido online directamente en la memoria Flash/LittleFS del ESP32, permitiendo operación táctil completa y ejecución de reglas locales sin conexión a internet.

📶 Modos Duales de Conectividad: Funciona en la red Wi-Fi de planta (STA) o emite su propio SoftAP de emergencia (http://192.168.4.1) con WebSocket local (< 0.5ms de latencia).

Descarga Directa del Bundle para LittleFS:

Puedes obtener el bundle optimizado monolítico (< 60 KB) desde el endpoint:

GET /api/v1/tenants/{tenant_slug}/export-edge-bundle

📄 Integración con ESPHome (YAML)

Plantillas pre-configuradas para usuarios que prefieren el ecosistema declarativo de ESPHome.

substitutions:
  devicename: "esp32-casajr-01"
  company: "casajr"

esphome:
  name: ${devicename}

esp32:
  board: esp32dev
  framework:
    type: arduino

mqtt:
  broker: "smarthingsiot.vacup.online"
  port: 1883
  topic_prefix: "tenants/${company}/devices/${devicename}"

sensor:
  - platform: internal_temperature
    name: "Temperatura Interna"
    update_interval: 5s
    filters:
      - delta: 0.5
        

🌐 Publicación en Arduino Manager, PlatformIO y PyPI

Instrucciones para indexar las librerías en los repositorios globales de código abierto.

1. Arduino Library Manager

El archivo library.properties ya está estructurado bajo la especificación de Arduino 1.5+. Para registrarlo oficialmente, abre un Issue en arduino/library-registry con la URL de tu repositorio GitHub.

2. PlatformIO Registry

pio package publish libraries/IotPlatformClient

3. Python SDK en PyPI (`pip install iot-platform-sdk`)

python3 -m build
twine upload dist/*
        

🔒 Conexión MQTT 5.0 & Patrones ACL

Parámetros de conexión al broker MQTT industrial con autenticación aislada por empresa.

Broker Host: smarthingsiot.vacup.online
Puerto TCP:  1883
Puerto WSS:  8080 (WebSockets Secure)
Usuario:     {device_id}  (ej. esp32-casajr-01)
Password:    {device_token}

Estructura de Tópicos Autorizados:
• Telemetría:  tenants/{company_slug}/devices/{device_id}/telemetry
• Actuadores:  tenants/{company_slug}/devices/{device_id}/actuators/{actuator_id}/command
• Estado:      tenants/{company_slug}/devices/{device_id}/status
        

🌐 Referencia de API REST

Endpoints HTTP disponibles para ingesta, aprovisionamiento y administración de flota.

GET /health: Estado de salud del motor en Rust y microservicios.
POST /api/v1/provisioning/claim: Enrolamiento Zero-Touch con Claiming Token.
GET /api/v1/companies/:slug/firmware/manifest.json: Manifiesto para ESP Web Tools.
GET /api/v1/companies/:slug/reports/export?format=pdf: Descarga de reporte PDF.

🩺 Diagnóstico & Resolución de Problemas (FAQs)

Soluciones directas a los problemas más frecuentes en despliegues reales.

🔴 Mi ESP32 se reinicia constantemente

Verifica que no tengas bucles while(!WiFi.isConnected()) bloqueando la ejecución. Utiliza la librería oficial IotPlatformClient que gestiona la máquina de estados de forma no-bloqueante.

🔴 El Broker rechaza la conexión con código 5 (Unauthorized)

Entra a tu Tenant Hub y pulsa en 🔄 Rotar Token Secreto para generar un nuevo token y sincronizar la tabla ACL.