ATLAS/docs/guias/meshtastic.md

# Integracion Meshtastic

Guia para configurar dispositivos Meshtastic con FlotillasGPS.

## Que es Meshtastic

Meshtastic es una plataforma de comunicacion mesh usando radio LoRa:

- **Largo alcance**: 5-15+ km en condiciones ideales
- **Sin infraestructura**: No requiere torres celulares ni internet
- **Bajo costo**: Dispositivos desde $20 USD
- **Bajo consumo**: Semanas de bateria

### Casos de Uso en Flotillas

- Vehiculos en zonas rurales sin cobertura celular
- Operaciones en minas, campos, areas remotas
- Backup cuando falla la red celular
- Comunicacion en emergencias

---

## Arquitectura

```
    ZONA SIN COBERTURA CELULAR
    ==========================

    [Vehiculo 1]          [Vehiculo 2]
    Meshtastic            Meshtastic
        |                     |
        |    Radio LoRa       |
        +----------+----------+
                   |
                   v
             [Nodo Relay]
             (punto alto)
                   |
                   | Radio LoRa
                   v

    ZONA CON COBERTURA
    ==================

             [Gateway]
        Meshtastic + WiFi/4G
                   |
                   | MQTT / Internet
                   v
             [Tu Servidor]
             FlotillasGPS
```

---

## Hardware Recomendado

### Para Vehiculos (Nodos Moviles)

| Dispositivo | Precio | GPS | Pantalla | Notas |
|-------------|--------|-----|----------|-------|
| LILYGO T-Beam | $35 | Si | No | Popular, bateria 18650 |
| Heltec LoRa 32 V3 | $20 | Si | OLED | Compacto, economico |
| RAK WisBlock | $40 | Si | Opcional | Modular, bajo consumo |

### Para Gateway (Fijo con Internet)

| Dispositivo | Precio | Notas |
|-------------|--------|-------|
| T-Beam + RPi | $70 | DIY, flexible |
| Heltec + ESP32 | $25 | Simple, economico |
| RAK WisGate | $150 | Comercial, robusto |

### Accesorios

- **Antena externa**: Mayor alcance (+3-6 dB)
- **Caja impermeable**: IP65 para exterior
- **Alimentacion 12V**: Adaptador para vehiculo

---

## Configuracion de Nodos

### 1. Instalar Firmware Meshtastic

1. Descargar [Meshtastic Flasher](https://flasher.meshtastic.org/)
2. Conectar dispositivo por USB
3. Seleccionar dispositivo y version
4. Flash

### 2. Configuracion Basica (App Meshtastic)

Descargar app Meshtastic (Android/iOS) y conectar por Bluetooth:

**Device Settings**:
```
Role: ROUTER_CLIENT
```

**Position Settings**:
```
GPS Mode: Enabled
Position Broadcast Interval: 30 seconds
Smart Position: Enabled
```

**LoRa Settings**:
```
Region: US (o tu region)
Modem Preset: LONG_FAST
TX Power: 20 dBm (maximo legal)
```

**Channel Settings**:
```
Name: flotilla
PSK: [generar clave compartida]
```

### 3. Configuracion via CLI (Avanzado)

```bash
# Instalar meshtastic CLI
pip install meshtastic

# Conectar y configurar
meshtastic --set device.role ROUTER_CLIENT
meshtastic --set position.gps_enabled true
meshtastic --set position.position_broadcast_secs 30
meshtastic --set lora.region US
meshtastic --set lora.modem_preset LONG_FAST
meshtastic --ch-set name flotilla --ch-index 0
meshtastic --ch-set psk random --ch-index 0
```

---

## Configuracion del Gateway

El gateway es el nodo que tiene conexion a internet y envia datos al servidor.

### Opcion 1: T-Beam + Raspberry Pi

1. Conectar T-Beam a RPi via USB
2. Instalar meshtastic:
```bash
pip install meshtastic
```

3. Configurar MQTT bridge:
```bash
meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address tu-servidor.com
meshtastic --set mqtt.username mesh_gateway
meshtastic --set mqtt.password tu_password
meshtastic --set mqtt.root_topic flotillas/mesh
meshtastic --set mqtt.encryption_enabled true
meshtastic --set mqtt.json_enabled true
```

### Opcion 2: ESP32 con WiFi

Configurar directamente en el dispositivo:

**MQTT Settings** (via app o CLI):
```
MQTT Enabled: true
MQTT Server: tu-servidor.com:1883
MQTT Username: mesh_gateway
MQTT Password: tu_password
Root Topic: flotillas/mesh
JSON Enabled: true
```

---

## Configuracion del Servidor

### 1. Mosquitto MQTT

Ya instalado por el script de instalacion. Verificar:

```bash
systemctl status mosquitto
```

Crear usuario para gateway:
```bash
mosquitto_passwd -c /etc/mosquitto/passwd mesh_gateway
# Ingresar password
```

Configuracion `/etc/mosquitto/conf.d/flotillas.conf`:
```
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
```

Reiniciar:
```bash
systemctl restart mosquitto
```

### 2. Verificar Recepcion de Mensajes

Suscribirse al topic para ver mensajes:

```bash
mosquitto_sub -h localhost -t "flotillas/mesh/#" -u mesh_gateway -P tu_password
```

Deberian aparecer mensajes JSON cuando los nodos envien posicion.

### 3. Configurar en FlotillasGPS

Variables de entorno en `.env`:
```bash
MQTT_HOST=localhost
MQTT_PORT=1883
MQTT_USER=mesh_gateway
MQTT_PASSWORD=tu_password
MQTT_TOPIC=flotillas/mesh/#
```

---

## Vincular Nodos a Vehiculos

### En el Dashboard

1. Ir a **Meshtastic** o detalle del vehiculo > **Dispositivo**
2. Click **+ Agregar dispositivo Meshtastic**
3. Ingresar:
   - **Node ID**: ID del nodo (ej: !a1b2c3d4)
   - **Nombre**: Identificador amigable
   - **Vehiculo**: Seleccionar vehiculo
4. Click **Guardar**

### Obtener Node ID

En la app Meshtastic:
- Ir a Settings > Device
- El Node ID aparece como "!xxxxxxxx"

O via CLI:
```bash
meshtastic --info | grep "Node"
```

---

## Panel Meshtastic en Dashboard

El panel muestra:

### Estado de Red
- Nodos totales
- Nodos online
- Nodos offline
- Calidad de senal promedio

### Mapa de Cobertura
- Gateway
- Nodos y conexiones
- Alcance estimado

### Lista de Nodos
| Nodo | Vehiculo | Bateria | Senal | Ultimo msg |
|------|----------|---------|-------|------------|
| !a1b2 | Camion-05 | 78% | -72dB | hace 30s |
| !c3d4 | Van-03 | 45% | -89dB | hace 45s |

### Diagnosticos
- Mensajes por minuto
- Paquetes perdidos
- Latencia promedio

---

## Topologia de Red

### Red Simple (Linea de Vista)

```
[Vehiculo] <-- LoRa --> [Gateway] <-- Internet --> [Servidor]
```

Alcance: 5-15 km con linea de vista

### Red con Relays

```
[Vehiculo lejano]
       |
       | LoRa
       v
[Vehiculo relay]  <-- LoRa -->  [Gateway]
       ^
       | LoRa
       |
[Otro vehiculo]
```

Cada vehiculo puede actuar como relay si esta configurado como ROUTER_CLIENT.

### Consejos para Mejor Cobertura

1. **Gateway en punto alto**: Edificio, torre, cerro
2. **Antenas externas**: Mejor ganancia
3. **Evitar obstaculos**: Metal, concreto bloquean senal
4. **Vehiculos como relays**: Configurar ROUTER_CLIENT

---

## Solucion de Problemas

### Nodo no aparece en el sistema

1. Verificar que el gateway recibe mensajes:
```bash
mosquitto_sub -h localhost -t "flotillas/mesh/#" -u mesh_gateway -P password
```

2. Verificar que el nodo esta en el mismo canal:
   - Mismo nombre de canal
   - Misma PSK (clave)

3. Verificar alcance: El nodo debe estar dentro del alcance del gateway o de un relay.

### Ubicaciones no se actualizan

1. Verificar que GPS esta habilitado en el nodo:
```bash
meshtastic --info | grep "GPS"
```

2. Verificar intervalo de broadcast:
```bash
meshtastic --get position.position_broadcast_secs
```

3. El nodo debe tener fix GPS (ver LED o app)

### Conexion MQTT falla

1. Verificar Mosquitto:
```bash
systemctl status mosquitto
```

2. Probar conexion:
```bash
mosquitto_pub -h localhost -t "test" -m "hello" -u mesh_gateway -P password
```

3. Verificar firewall (si gateway es externo):
```bash
ufw allow 1883/tcp
```

### Bateria se agota rapido

Optimizar configuracion:
```bash
# Aumentar intervalo de posicion
meshtastic --set position.position_broadcast_secs 60

# Reducir potencia TX
meshtastic --set lora.tx_power 17

# Habilitar modo ahorro
meshtastic --set power.is_power_saving true
```

---

## Limitaciones

- **No tiempo real**: Latencia de 10-60 segundos
- **Solo ubicacion**: No video ni datos pesados
- **Dependiente de relays**: Necesita nodos intermedios para grandes distancias
- **Interferencia**: Otras redes LoRa pueden afectar

---

## Recursos

- [Documentacion Meshtastic](https://meshtastic.org/docs/)
- [Flasher Web](https://flasher.meshtastic.org/)
- [Comunidad Discord](https://discord.gg/meshtastic)
- [Mapa de Nodos](https://meshtastic.liamcottle.net/)