Saltar a contenido

DOCUMENTACIÓN TÉCNICA - OCTOPUS

1. DESCRIPCIÓN GENERAL

El Octopus es un dispositivo IoT multifuncional basado en ESP32 que integra múltiples sensores y actuadores para aplicaciones de monitoreo y control remoto. El dispositivo incluye GPS, RFID, PIR, relés, y comunicación MQTT segura.

2. ARQUITECTURA DEL SISTEMA

2.1 Hardware Principal

  • Microcontrolador: ESP32
  • Pantalla: LCD TFT 237x133 píxeles
  • LEDs: 7 LEDs NeoPixel RGB para indicadores de estado
  • Botones: 3 botones físicos (A, B, C)
  • Batería: 2 celdas Li-ion 18650 en paralelo (5Ah total)

2.2 Módulos Integrados

  • GPS: Módulo GPS con comunicación serial
  • RFID: 2 lectores UHF RFID (antenas duales)
  • PIR: Sensor de movimiento infrarrojo pasivo
  • Relés: 4 relés controlados por I2C
  • WiFi: Conectividad inalámbrica 802.11n

3. FLUJO DE INICIALIZACIÓN Y CONFIGURACIÓN

3.4 Proceso de Configuración Inicial del Dispositivo

Para configurar el WiFi por primera vez o restablecer la configuración:

  1. Mantén presionados los botones izquierdo (A) y derecho (C) al encender o reiniciar el dispositivo.
  2. El Octopus creará una red WiFi llamada Octopus (modo AP) y mostrará en pantalla instrucciones para conectarse.
  3. En la pantalla del dispositivo aparecerá un mensaje y un código QR para facilitar la conexión. Escanea el QR o conéctate manualmente a la red WiFi Octopus con la contraseña octopus123.
  4. Abre un navegador y accede a la página http://192.168.4.1 desde tu teléfono o PC.
  5. Completa el formulario con el nombre y contraseña de tu red WiFi. Importante: la red WiFi debe ser de 2.4GHz (no es compatible con 5GHz).
  6. Guarda la configuración. El dispositivo se reiniciará automáticamente y tratará de conectarse a la red WiFi configurada.

Si necesitas reconfigurar el WiFi en el futuro, repite el proceso manteniendo presionados los botones A y C durante el arranque.

3.1 Secuencia de Arranque

1. Cargar preferencias almacenadas
2. Verificar credenciales WiFi
3. Si no hay credenciales → Modo AP
4. Si hay credenciales → Conectar a red WiFi
5. Configurar MQTT con certificados TLS
6. Obtener licencia del servidor
7. Inicializar todos los módulos
8. Iniciar bucle principal

3.2 Modo Punto de Acceso (AP)

Cuando el dispositivo no tiene credenciales WiFi configuradas: - SSID: Octopus - Contraseña: octopus123 - IP: 192.168.4.1 - Servidor Web: Puerto 80 - Página: Formulario de configuración HTML

3.3 Configuración WiFi

  • Endpoint: GET /config?username=SSID&password=PASSWORD
  • Almacenamiento: Preferences ESP32 (NVS)
  • Reinicio: Automático después de guardar credenciales

4. SISTEMA DE LICENCIAS

4.1 Verificación de Licencia

  • Endpoint: https://main.dzd5pzd1l3nl1.amplifyapp.com/api/devices/mac/{MAC}
  • Frecuencia: Cada 10 segundos
  • Formato: JSON con campos license y license_name

4.2 Estados de Licencia

  • Sin licencia: license = "", license_name = "no license"
  • Con licencia: license = "ID_LICENCIA", license_name = "NOMBRE_LICENCIA"
  • Error: Retorna -1, mantiene licencia anterior

4.3 Topics MQTT por Licencia

/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/in      # Comandos entrantes (control de relés, o solicitud de foto.)
/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/out     # Estado del dispositivo (publicación periódica)
/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/event   # Eventos (botones, PIR)

5. COMUNICACIÓN MQTT

5.1 Configuración de Seguridad

  • Broker: a8p6o8w3qii41-ats.iot.us-east-1.amazonaws.com
  • Puerto: 8883 (TLS)
  • Certificados:
  • AmazonRootCA1.pem
  • certificate.pem
  • sc.private.key
  • Cliente ID: Dirección MAC del dispositivo

5.2 Topics de Publicación

5.2.1 Estado del Dispositivo (/out)

El dispositivo publica periódicamente su estado en el topic /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/out con el siguiente formato: 

{
  "mac": "MAC_ADDRESS",
  "latitude": "LAT",
  "longitude": "LON",
  "altitude": "ALT",
  "gps_accuracy": "ACCURACY",
  "hdop": "HDOP",
  "speed_kmh": "SPEED",
  "valid_location": "FIX_STATUS",
  "timestamp": "ISO8601_DATETIME",
  "battery_level": "PERCENTAGE",
  "battery_charging": "BOOLEAN",
  "battery_current": "CURRENT_A",
  "battery_voltage": "VOLTAGE_V",
  "battery_remaining_time": "HOURS",
  "battery_charging_time": "HOURS",
  "rfid": "RFID_DATA_ARRAY", // Array JSON de tags RFID detectados
  "parked": "BOOLEAN",
  "pir": "BOOLEAN",
  "relay0": "BOOLEAN",
  "relay1": "BOOLEAN",
  "relay2": "BOOLEAN",
  "relay3": "BOOLEAN"
}

Notas: - El campo rfid es un string JSON con un array de objetos EPC/PC/RSSI. - El campo parked indica si el vehículo está estacionado (detección automática). - Los campos de batería se calculan en tiempo real y pueden incluir estimaciones de tiempo restante/carga.

5.2.2 Eventos (/event)

Los eventos (botones, PIR, RFID, etc.) se publican en /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/event: 

{
  "event_key": "EVENT_TYPE", // Ej: "button_a", "movement", "rfid_detected"
  "timestamp": "ISO8601_DATETIME",
  "latitude": "LAT",
  "longitude": "LON",
  "altitude": "ALT",
  "gps_accuracy": "ACCURACY",
  "mac": "MAC_ADDRESS"
}

5.3 Topics de Suscripción (/in)

El dispositivo escucha comandos en /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/in. Ejemplo de comando para relés: 

{
  "type": "relay",
  "index": 0-3,
  "state": true|false
}
Otros comandos pueden ser agregados en el futuro (ej: reset, configuración, etc.).

6. FUNCIONALIDADES DE LOS BOTONES

6.1 Botón A (Mantener 3s)

  • Función: Configuración especial (evento button_a)

6.2 Botón B (Mantener 3s)

  • Función: Función secundaria (evento button_b)

6.3 Botón C (Mantener 3s)

  • Función: Función terciaria (evento button_c)

6.4 Combinación A+C (Mantener 3s)

  • Función: Restaurar configuración por defecto
  • Acción: Limpia credenciales WiFi y reinicia dispositivo

7. MÓDULOS Y SENSORES

7.1 Sistema GPS

  • Hardware: Módulo GPS
  • Puertos: RX=36, TX=26
  • Baudrate: 115200 bps
  • Datos: Latitud, longitud, altitud, velocidad, HDOP, estado de fix
  • Frecuencia: Actualización continua
  • Detección de Estacionamiento: Algoritmo basado en velocidad y distancia (ver campo parked en JSON)

7.2 Sistema RFID

  • Hardware: 2 lectores UHF RFID
  • Puertos:
  • Antena 1: RX=13, TX=14
  • Antena 2: RX=16, TX=17
  • Frecuencia: Polling cada 200ms
  • Datos: EPC, PC, RSSI
  • Formato: Array JSON de tags detectados

7.3 Sensor PIR

  • Puerto: GPIO 35
  • Timeout: 5 segundos entre eventos
  • Evento: movement (publicado en topic /event)
  • Debounce: Implementado para evitar falsos positivos

7.4 Sistema de Relés

  • Hardware: Módulo 4-RELAY I2C
  • Dirección: 0x73
  • Control: 4 relés independientes (controlados vía MQTT y localmente)
  • Estados: ON/OFF con indicadores LED
  • Comunicación: I2C (SDA=32, SCL=33)

8. MONITOREO DE BATERÍA

8.1 Parámetros de Batería

  • Voltaje máximo: 4.2V por celda
  • Voltaje mínimo: 3.2V por celda
  • Capacidad: 5000mAh (2x 2500mAh)
  • Corriente de carga: 1320mA

8.2 Cálculos Inteligentes

  • Nivel: Basado en voltaje con mapeo lineal
  • Tiempo restante: Estimación basada en corriente y capacidad
  • Suavizado: Filtros para estabilizar lecturas

10. INTERFAZ DE USUARIO

10.1 Pantalla LCD

  • Resolución: 237x133 píxeles
  • Regiones: 7 áreas de información
  • Logo: Logo de Netsocs en la parte central
  • Información: Estado de todos los módulos en tiempo real

10.2 Regiones de Información

  • Región 0: Estado de energía y batería
  • Región 1: Estado del sensor PIR
  • Región 2: Datos GPS y coordenadas
  • Región 3: Estado WiFi y licencia
  • Región 4: Estado de los relés
  • Región 5: Datos RFID y botones
  • Región 6: Logo central

11. CONFIGURACIÓN Y DESPLIEGUE

11.1 Requisitos del Sistema

  • Framework: Arduino
  • Plataforma: ESP32
  • Librerías: FastLED, ArduinoJson, PubSubClient, ESPAsyncWebServer
  • Certificados: Archivos PEM para MQTT TLS

11.2 Archivos de Configuración

  • SPIFFS: Almacenamiento de certificados y página HTML
  • Preferences: Credenciales WiFi y configuración
  • platformio.ini: Dependencias y configuración de compilación

11.3 Variables de Entorno

  • Servidor MQTT: Configurado para AWS IoT Core
  • API Hub: Endpoint para verificación de licencias
  • Driver Hub: Endpoint para configuración adicional

12. CONSIDERACIONES DE SEGURIDAD

12.1 Comunicación MQTT

  • TLS 1.2: Certificados X.509
  • Autenticación: Certificados cliente
  • Autorización: Basada en licencias

12.2 WiFi

  • Modo AP: Solo para configuración inicial
  • Credenciales: Almacenadas en NVS seguro
  • Restauración: Función de reset a configuración por defecto

12.3 Datos Sensibles

  • Certificados: Almacenados en SPIFFS
  • Credenciales: Encriptadas en NVS
  • MAC Address: Identificador único del dispositivo

13. INSTALACIÓN Y COMPILACIÓN

13.1 Requisitos Previos

  • PlatformIO IDE
  • Python 3.7+
  • Git

13.2 Pasos de Instalación

# Clonar el repositorio
git clone <repository-url>
cd firmware

# Instalar dependencias
pio lib install

# Compilar el proyecto
pio run

# Subir al dispositivo
pio run --target upload

# Monitorear serial
pio device monitor

13.3 Configuración de Certificados

  1. Colocar los archivos de certificados y recursos en la carpeta data/:
  2. AmazonRootCA1.pem
  3. certificate.pem
  4. sc.private.key
  5. page.html (página de configuración WiFi)
  6. logo.bmp (logo mostrado en pantalla)
  7. Subir todos los archivos al SPIFFS: pio run --target uploadfs

14. TROUBLESHOOTING

14.1 Problemas Comunes

  • Error de conexión WiFi: Verificar credenciales y señal, en la parte superior derecha puede ver el nombre de la red asi como la IP local si hay conexion.
  • Error de licencia: El dispositivo esta conectado al Wi-Fi pero no esta asociado a ninguna licencia de Netsocs, contacte al equipo de ventas o soporte.
  • GPS sin señal: El dispositivo se encuentra en un lugar con poca o nula recepción, tan pronto sea posible la triangulación el dispositivo fijará la posición, no hace falta algún reinicio o manipulación del modulo de GPS.
  • RFID no detecta: Si no se muestra detección del RFID en las antenas del octopus es posible que estas no esten lo suficientemente cerca (idealmente menos de 2 metros) el protocolo soportado es EPCglobal UHF Class 1 Gen 2, ISO 18000-6C

14.2 Logs y Debug

  • Monitor Serial: 115200 baudios
  • Indicadores LED: Estado visual de cada módulo
  • Pantalla LCD: Información en tiempo real

15. MANTENIMIENTO

15.1 Actualizaciones

  • Firmware: Compilar y subir nuevo código
  • Certificados: Reemplazar archivos PEM cuando expiren
  • Configuración: Modificar variables en el código

15.2 Calibración

  • GPS: Ajustar timeout y precisión según aplicación
  • RFID: Configurar potencia de transmisión
  • PIR: Ajustar sensibilidad y timeout

Nota: Esta documentación está basada en el Firmware por defecto del Octopus. Para soporte de firmware personalizados (sensores adaptados, RS232 pullup etc), consulte con el equipo de desarrollo de Netsocs.