GeoPulse™ Tracker GPS Avançat

1. Introducció

Benvingut al GeoPulse GPS Tracker versió 3.0.5, un dispositiu de seguiment d'alt rendiment dissenyat per a un monitoratge de localització robust i fiable. Aquesta versió incorpora nombroses millores avançades incloent actualitzacions remotes de firmware, gestió intel·ligent de portals captius i un sistema de geofencing expandit.

Ja sigui que estigueu rastrejant actius marins, vehicles o altres equips, GeoPulse proporciona dades de posició, velocitat i estat del sistema en temps real directament al vostre tauler de control mitjançant MQTT.

Novetats de la Versió 3.0.5:

• Operació Contínua: El dispositiu es manté sempre actiu per garantir un seguiment constant.
• Geofencing Avançat: Sistema de zones virtuals amb categories, àlies i control granular de notificacions.
• Actualitzacions OTA Remotes: Capacitat d'actualitzar firmware remotament via HTTP/HTTPS.
• Gestió Intel·ligent de Portals Captius: Autenticació automàtica per xarxes "Crew" amb rotació de credencials.
• Sistema de Registres Filtrable: Control granular dels nivells de registre MQTT.
• Anàlisi de Satèl·lits Avançat: Informes detallats amb diagnòstics del parser GPS.
• Planificador de Tasques Cooperatiu: 13 tasques concurrents amb control dinàmic d'intervals.
• Monitorització Avançada del Sistema: Supervisió contínua de memòria i connectivitat.

Aquest manual cobreix el maquinari, les funcions de programari i els procediments operatius del vostre dispositiu actualitzat.

2. Maquinari i Perifèrics

El tracker GeoPulse està construït amb components seleccionats amb cura per garantir precisió, longevitat i un rendiment fiable en el camp.

2.1. Controlador Central: NodeMCU (ESP8266)

El cor del tracker és una placa NodeMCU, alimentada pel SoC Wi-Fi ESP8266. Gestiona tots els perifèrics, s'ocupa de la connectivitat de xarxa, processa les dades GPS i executa la lògica del sistema.

• Processador: Tensilica L106 32-bit
• Wi-Fi: 2.4 GHz, 802.11 b/g/n
• Memòria RAM: ~80KB disponibles per l'aplicació
• Característiques: Actualitzacions OTA locals i remotes, capacitats de son profund.

2.2. Mòdul GPS: Mateksys GNSS SAM-M10Q

Aquest és un mòdul GNSS d'última generació que compta amb la plataforma u-blox M10, proporcionant una sensibilitat excepcional i temps d'adquisició ràpids.

• Constel·lacions: Recepció concurrent de 4 sistemes GNSS (GPS, GLONASS, Galileo i BeiDou) per a una màxima disponibilitat de posició, fins i tot en entorns difícils com els canyons urbans.
• Antena: Antena de ceràmica d'alt guany integrada de 15x15mm.
• Consum d'Energia: Ultra-baix, ~10mA durant el seguiment actiu.
• Taxa d'Actualització: Fins a 10Hz (La configuració per defecte en aquest firmware és d'1Hz).
• Pins de Connexió: RX=Pin 14, TX=Pin 15, Baud Rate=9600
• Característiques Especials:
  • Tecnologia Super-S: Millora la precisió de la posició dinàmica en escenaris sense línia de visió directa.
  • LED PPS: Un LED blau al mòdul parpelleja a 1Hz un cop s'estableix una posició 3D.

2.3. Sistema d'Alimentació: DFRobot DFR0208 i LiPo de 6000mAh

Carregador de Bateria de Liti DFRobot V1.0 (SKU: DFR0208)

Aquesta placa gestiona la càrrega de la bateria de liti, garantint seguretat i eficiència.

• Entrada: Accepta 5V estàndard mitjançant un connector USB Type-C, fent-lo compatible amb bancs d'energia i adaptadors USB estàndard.
• Corrent de Càrrega: El firmware assumeix la taxa de càrrega per defecte de 1000mA.
• Seguretat: Incorpora un circuit de càrrega dedicat amb protecció contra sobrecàrrega.
• LEDs d'Estat:
  • LED Vermell: Càrrega en progrés.
  • LED Verd: Càrrega completada.

Bateria de Polímer de Liti de 6000mAh

Una bateria d'alta capacitat proporciona una vida operativa estesa, permetent que el tracker funcioni durant llargs períodes entre càrregues en mode d'operació contínua.

2.4. Sensor de Bateria: ADC ADS1115

Per proporcionar un monitoratge precís del nivell de bateria, s'utilitza un ADS1115 de Texas Instruments connectat via I2C.

• Resolució: Convertidor Analògic-Digital (ADC) de precisió de 16 bits.
• Interfície: Es comunica amb l'ESP8266 mitjançant I2C.
• Canal Utilitzat: ADC Channel 3 (ADS1115)
• Calibratge: Factor de conversió de 1586.0 per obtenir voltatge
• Funció: Mesura el voltatge de la bateria amb alta precisió. El firmware converteix aquesta lectura de voltatge (calibrada per a un rang de 3.2V a 4.2V) en un percentatge de nivell de bateria del 0 al 100%.

3. Primers Passos

1. Carregueu Completament el Dispositiu: Abans del primer ús, connecteu un cable USB Type-C estàndard de 5V al port de la placa carregadora DFRobot. El LED vermell s'encendrà. Deixeu-lo carregar fins que el LED verd s'il·lumini, indicant una bateria plena.
2. Enceneu-lo: El dispositiu s'encendrà automàticament quan s'actuï damunt l'interruptor.
3. Estat Inicial: En arrencar, el dispositiu intentarà connectar-se immediatament a una xarxa Wi-Fi preconfigurada.

4. Entendre els Indicadors LED

El tracker GeoPulse utilitza dos LEDs per proporcionar informació visual sobre el seu estat.

5. Modes d'Operació

5.1. Mode Estació (Operació Normal)

Aquest és el mode per defecte. El dispositiu es connecta a una xarxa Wi-Fi existent per obtenir accés a Internet.

• Obté l'hora actual mitjançant NTP.
• Es connecta al broker MQTT.
• Adquireix una posició GPS i comença a transmetre dades a un interval establert.
• Escolta comandes remotes a través de MQTT.

5.2. Mode Punt d'Accés (AP) (Configuració)

Si el dispositiu no pot connectar-se a cap de les seves xarxes Wi-Fi preconfigurades, entra automàticament en Mode AP. Aquest mode us permet configurar una nova xarxa Wi-Fi.

• El dispositiu crea la seva pròpia xarxa Wi-Fi amb les següents credencials:
  • SSID: geopulse_AP
  • Contrasenya: gps12345
• S'inicien un servidor web i un servidor DNS per crear un portal captiu.

Com Configurar una Nova Xarxa WiFi:

1. Quan el dispositiu estigui en Mode AP (indicat pels LEDs alternants lents), utilitzeu el vostre telèfon o ordinador per buscar xarxes Wi-Fi.
2. Connecteu-vos a la xarxa geopulse_AP utilitzant la contrasenya gps12345.
3. Després de connectar-vos, una pàgina d'inici de sessió de portal captiu hauria d'obrir-se automàticament al vostre navegador. Si no ho fa, obriu un navegador i navegueu a qualsevol lloc web (p. ex., http://192.168.4.1).
4. Veureu la pàgina "Configuració WiFi de GeoPulse".
5. Introduïu el SSID (Nom de la WiFi) i la Contrasenya de la xarxa que voleu que utilitzi el tracker.
6. Feu clic a "Desar i Connectar".
7. El dispositiu desarà les noves credencials a la seva memòria interna i es reiniciarà, intentant connectar-se a la xarxa que acabeu de proporcionar.

6. Protocol de Comunicació MQTT

El dispositiu utilitza el protocol MQTT per a tota la comunicació de dades i comandament i control.

• Broker: moscard.cloud.shiftr.io
• Port: 1883
• Usuari: moscard
• Contrasenya: Definida al firmware
• Client ID: geopulse
• Buffer MQTT: 1024 bytes

6.1. Tòpics Publicats

6.2. Tòpic de Comandament

Totes les comandes remotes s'envien al tòpic: geopulse/commands

6.3. Formats de Dades

JSON (tòpic barca) per Home Assistant:

{
  "latitude": 41.123456,
  "longitude": 2.123456,
  "gps_accuracy": 85,  // Percentatge de bateria (mapejat per compatibilitat)
  "battery_level": "12.34"  // Velocitat en nusos/kmh (mapejat per compatibilitat)
}

Nota Important: Els camps gps_accuracy i battery_level estan mapejats de forma no intuïtiva per mantenir compatibilitat amb sistemes existents:

• gps_accuracy conté el percentatge de bateria (0-100)
• battery_level conté la velocitat en les unitats configurades

CSV (tòpic gps/data):

"GeoPulse",lat,lng,speed,units,course,sats,batt%,field,field,field,day,mon,yr,hr,min,field

6.4. Formats de Dades Addicionals (v3.0+)

JSON de Satèl·lits (tòpic geopulse/satellites):

{
  "sats_in_view": 12,
  "timestamp_utc": 1678886400,
  "satellites": [
    {
      "prn": 10,
      "system": "G",
      "ele": 75,
      "azi": 180,
      "snr": 45
    }
  ],
  "sats_tracked_by_parser": 9
}

JSON d'Esdeveniment de Geofence (tòpic geopulse/geofence):

{
  "event": "enter",
  "fence": "Port_Olimpic",
  "lat": 41.3851,
  "lon": 2.1960
}

6.5. Llista de Comandes Remotes

Podeu enviar les següents comandes com a missatges de text pla al tòpic geopulse/commands:

Comandes Crítiques (sempre disponibles)

Comandes Generals (requereixen >8000 bytes de memòria lliure)

Comandes de Gestió de Tasques

Comandes de Geofencing

Comandes de Gestió de Registres

Comandes de Portal Captiu (només per a xarxa "Crew")

Comandes d'Actualització Remota

Comandes de Diagnòstic

7. Resolució de Problemes

7.1. Diagnòstic Avançat per la Versió 3.0.5

La versió 3.0.5 incorpora eines de diagnòstic significativament millorades:

• Estat del Sistema: get_status proporciona informació detallada sobre memòria, xarxa, GPS i configuració.
• Monitorització de Tasques: task_status mostra l'estat detallat de totes les 13 tasques del sistema.
• Diagnòstic de Satèl·lits: satellite_debug i get_satellite_report per a anàlisi complet del GPS.
• Verificació de Memòria: Monitorització contínua amb alertes automàtiques.
• Registres Filtrables: Control granular amb set_log_level_* per optimitzar diagnòstic.
• Portal Captiu: credentials_status i force_captive_login per diagnòstic de xarxa.

7.2. Comandes d'Emergència i Recuperació

En cas de comportament anòmal, aquestes comandes poden restaurar l'operació normal:

• reboot - Reinici immediat del dispositiu (sempre disponible)
• enable_power_save - Redueix drasticament l'ús de memòria
• set_standby - Atura tasques no essencials temporalment
• resume - Reprèn l'operació normal des del mode standby
• task_enable_GPS_READ - Reactiva la lectura GPS si s'ha desactivat
• set_log_level_error - Minimitza el tràfic MQTT en emergències

7.3. Procediment de Diagnòstic Complet

Per a un diagnòstic sistemàtic, seguiu aquesta seqüència:

1. Estat General: Envieu get_status per obtenir una vista general
2. Tasques del Sistema: Utilitzeu task_status per verificar el planificador
3. GPS i Satèl·lits: Executeu satellite_debug per diagnòstic detallat
4. Xarxa i Connectivitat: Si esteu a "Crew", utilitzeu credentials_status
5. Memòria: La informació de memòria s'inclou automàticament en get_status
6. Registres Detallats: Configureu set_log_level_debug per màxima informació

8. Característiques Avançades i Detalls Tècnics

8.1. Planificador de Tasques Cooperatiu

El firmware del GeoPulse utilitza un planificador de tasques cooperatiu avançat que permet l'execució eficient de múltiples funcions sense bloqueig. Aquest sistema ha estat completament optimitzat a la versió 2.0 per oferir major capacitat de resposta i eficiència energètica.

Nota: Per a informació detallada sobre el planificador de tasques, intervals i control dinàmic, consulteu la secció 8.4 - Planificador de Tasques Cooperatiu Avançat.

8.2. Gestió Automàtica de Portals Captius

El dispositiu té lògica integrada per gestionar automàticament els portals captius, especialment per a xarxes anomenades "Crew". Quan es connecta a aquesta xarxa, el firmware intentarà automàticament autenticar-se utilitzant una llista predefinida de credencials. Això permet que el dispositiu accedeixi a Internet en entorns de xarxa restringits, com els que es troben a bord de vaixells o en xarxes públiques.

8.3. Sistema Simplificat de Gestió de Memòria

Operació Sempre Activa (Versió 3.0+)

El GeoPulse ara opera en mode continu, eliminant la complexitat del sistema de son/vigília per garantir un seguiment constant i fiable.

Característiques Clau:

• Operació Contínua: El dispositiu es manté sempre actiu per un seguiment constant.
• Gestió Simplificada: Eliminació dels tòpics de son/vigília per evitar complexitat innecessària.
• Comportament Predictible: No hi ha possibilitat de bucles de son o estats ambigus.
• Resposta Immediata: Totes les comandes es processen immediatament.
• Estat Consistent: El dispositiu sempre està disponible per rebre comandes i enviar dades.

Gestió Intel·ligent de la Memòria

• Monitorització Contínua: L'ESP8266 té memòria limitada (~80KB utilitzable). El firmware supervisa contínuament la memòria lliure disponible.
• Degradació Gradual: Quan la memòria baixa:
  • > 8000 bytes: Funcionament normal, totes les comandes disponibles.
  • 5000-8000 bytes: Només comandes crítiques (reboot, standby/resume).
  • < 5000 bytes: Ignora comandes no essencials, registres de baixa prioritat.
  • < 2000 bytes: Reinici automàtic per evitar inestabilitat.
• Optimització de Publicacions MQTT: El firmware utilitza buffers fixos i evita la concatenació de strings per minimitzar la fragmentació de memòria.

Intervals de Verificació Optimitzats

El sistema s'ha optimitzat per a una major capacitat de resposta:

• Verificació de Tasques: Cada tasca s'executa segons el seu interval configurat.
• Resposta Immediata: Les comandes MQTT es processen immediatament sense esperar cicles.
• Monitorització Constant: El sistema supervisa contínuament la connectivitat i l'estat del GPS.

8.4. Planificador de Tasques Cooperatiu Avançat

El GeoPulse utilitza un sistema de planificació de tasques que permet l'execució quasi simultània de 13 funcions diferents sense bloqueig. Això millora significativament la capacitat de resposta del dispositiu.

Tasques del Sistema i els Seus Intervals:

Control Dinàmic de Tasques:

Podeu modificar el comportament del planificador en temps real:

• Mode Alta Freqüència: enable_high_freq - Configura GPS_DATA a 1000ms per màxima resposta.
• Mode Estalvi d'Energia: enable_power_save - Configura GPS_DATA a 30000ms per estalviar bateria.
• Control Granular: Utilitzeu task_enable/disable/interval per ajustar tasques individuals.
• Monitorització: task_status mostra l'estat actual i detecta tasques sobrecarregades.

Gestió Automàtica en Mode AP:

Quan el dispositiu entra en Mode AP, el planificador es reconfigura automàticament:

• Desactivades: WIFI_MGMT, INTERNET, MQTT, GPS_DATA, LOG_PUBLISH, LED_BLINK, GPS_READ
• Actives: AP_MODE, OTA (local)
• Restauració: Totes les tasques es reactiven automàticament quan es restableix la connectivitat

8.5. Intervals d'Enviament de Dades GPS Intelligents

El dispositiu ajusta automàticament la freqüència d'enviament de dades per equilibrar precisió i estalvi d'energia:

Mode per Defecte ("Tranqui Mode")

Utilitza intervals dinàmics basats en la velocitat detectada:

• Velocitat ≥ 2.5 nusos: Enviament cada 5 segons - Per seguiment precís en moviment ràpid.
• 1 nus ≤ Velocitat < 2.5 nusos: Enviament cada 1 minut - Adequat per moviments lents.
• Velocitat < 1 nus: Enviament cada 2 minuts - Mode d'estalvi d'energia quan està gairebé estàtic.

Mode d'Alta Freqüència

Activat amb set_interval_2s: interval fix de 2 segons per a màxima precisió de seguiment.

8.6. Geofencing Intel·ligent i Persistent (Versió 3.0.5)

El sistema de geofencing ha estat completament redessencat per oferir funcionalitats avançades d'empresa.

Característiques Avançades:

• Categories Organitzatives: Agrupa geofences per tipus (Port, Perill, Pesca, etc.)
• Sistema d'Àlies: Noms curts per a referència ràpida
• Control Granular de Notificacions: Configuració independent per entrada i sortida
• Emmagatzematge Persistent: Les geofences es guarden al sistema de fitxers LittleFS
• Detecció d'Estat Inicial: Determina automàticament si ja està dins de la zona al crear-la

Format de Comanda Expandit:

geofence_add [categoria] [nom] [lat] [lon] [radi_m] [notif_entrada] [notif_sortida] [àlies_opcional]

Exemples d'Ús:

# Crear zona de port amb notificacions d'entrada i sortida
geofence_add Port Port_Olimpic 41.385 2.196 200 1 1 PortOli

# Crear zona de perill només amb notificació d'entrada
geofence_add Perill Escolls_Nord 41.400 2.210 150 1 0 EscollsN

# Zona de pesca amb àlies buit
geofence_add Pesca Zona_Pesca_A 41.350 2.180 500 1 1

Format JSON d'Esdeveniments:

{
  "event": "enter",
  "fence": "Port_Olimpic",
  "category": "Port",
  "alias": "PortOli",
  "lat": 41.3851,
  "lon": 2.1960
}

8.7. Gestió Intel·ligent de Portals Captius

El dispositiu incorpora gestió automàtica especialitzada per a xarxes amb portal captiu, especialment optimitzada per a la xarxa "Crew".

Característiques:

• Detecció Automàtica: Reconeix automàticament la xarxa "Crew" i inicia el procés d'autenticació
• Credencials Múltiples: Suport per múltiples credencials amb rotació automàtica
• Gestió de Quota: Detecta quan s'exhaureix la quota d'un usuari i canvia automàticament
• Desconnexió Intel·ligent: Desconnecta proactivament usuaris abans de canviar credencials
• Verificació de Connectivitat: Comprova l'accés real a Internet després de l'autenticació

Credencials Configurades:

• Usuari 1: aaffhrd/aaffhrd
• Usuari 2: stenacrew/stenacrew

8.8. Sistema de Monitorització de Memòria

El firmware implementa un sistema sofisticat de gestió de memòria per garantir l'estabilitat en l'entorn limitat de l'ESP8266.

Nivells de Protecció:

• > 8000 bytes: Funcionament normal, totes les comandes disponibles
• 5000-8000 bytes: Només comandes crítiques (reboot, standby/resume)
• < 5000 bytes: Ignora comandes no essencials, registres de baixa prioritat
• < 2000 bytes: Reinici automàtic per evitar inestabilitat

Optimitzacions Implementades:

• Buffers Fixos: Evita fragmentació de memòria
• Alliberament Temporal: Desactiva tasques durant operacions intensives
• Monitorització Contínua: Supervisió constant amb informes automàtics

8.9. Anàlisi de Satèl·lits Avançat

El sistema de satèl·lits ha estat completament redessencat per oferir diagnòstics professionals.

Capacitats de Diagnòstic:

• Informe Complet: get_satellite_report genera un JSON detallat al tòpic geopulse/satellites
• Diagnòstic Tècnic: satellite_debug proporciona informació del parser intern
• Parser Dinàmic: Processament en temps real de missatges GPGSV
• Detecció d'Estat: Identifica automàticament problemes del parser vs. problemes de senyal

Format d'Informe JSON Expandit:

{
  "sats_in_view": 12,
  "timestamp_utc": 1678886400,
  "satellites": [
    {
      "prn": 10,
      "system": "G",
      "ele": 75,
      "azi": 180,
      "snr": 45
    }
  ],
  "sats_tracked_by_parser": 9,
  "gps_read_task_enabled": true,
  "status": "ok",
  "message": "Satellite data processed successfully"
}

Estats de Diagnòstic:

• "ok": Tot funciona correctament
• "no_satellite_data": No hi ha dades de satèl·lits disponibles
• "parser_issue": GPS reporta satèl·lits però el parser no els troba

9. Gestió de Nivells de Registre

El GeoPulse incorpora un sistema avançat de filtrat de registres que permet controlar quins missatges s'envien a MQTT, optimitzant l'ús de l'ample de banda i reduint el soroll en els registres.

9.1. Nivells de Registre Disponibles

9.2. Comportament del Sistema

• Registres Locals: Tots els missatges sempre s'escriuen al port sèrie local per a depuració directa.
• Filtrat MQTT: Només els missatges que compleixin el nivell establert s'envien a MQTT.
• Prioritat Alta: Els missatges de WARNING i ERROR sempre s'envien immediatament a MQTT.
• Configuració per Defecte: El sistema arrenca amb nivell WARNING per optimitzar l'ús de l'ample de banda.

9.3. Exemples d'Ús

• set_log_level_debug - Per obtenir informació completa durant la resolució de problemes
• set_log_level_warning - Per a operació normal amb alertes importants
• set_log_level_error - Per minimitzar el tràfic en entorns amb connectivitat limitada

10. Actualitzacions Remotes de Firmware

El GeoPulse suporta actualitzacions remotes de firmware via HTTP i HTTPS, permetent desplegar noves versions sense accés físic al dispositiu.

10.1. Capacitats d'OTA Remota

• Protocols Suportats: HTTP i HTTPS
• Verificació de Fitxer: Validació automàtica de headers binaris
• Informes de Progrés: Actualitzacions de progrés cada 10% via MQTT
• Gestió d'Errors: Informes detallats d'errors amb codis específics
• Seguretat: Verificació de compatibilitat de flash i validació MD5

10.2. Requisits del Sistema

• Memòria Mínima: 20,000 bytes lliures abans de començar l'actualització
• Connectivitat: Connexió estable a Internet
• Format del Fitxer: Fitxer .bin compatible amb ESP8266
• Optimització: Durant l'OTA es desactiven tasques no essencials per alliberar memòria

10.3. Procediment d'Actualització

1. Preparació: Assegureu-vos que el fitxer firmware estigui accessible via HTTP/HTTPS
2. Test Previ: Utilitzeu test_url [URL] per verificar l'accessibilitat
3. Inici: Executeu remote_ota_update [URL]
4. Monitorització: Observeu els informes de progrés via MQTT
5. Reinici: El dispositiu es reiniciarà automàticament si l'actualització és exitosa

10.4. Gestió d'Errors

El sistema proporciona codis d'error detallats per facilitar la resolució de problemes:

• Espai Insuficient: La flash no té prou espai per al nou firmware
• Fitxer No Trobat (404): La URL no conté un fitxer vàlid
• Accés Prohibit (403): Problemes de permisos o autenticació
• Verificació MD5 Fallida: El fitxer està corrupte o no és vàlid
• Header Binari Invàlid: El fitxer no és un firmware vàlid per ESP8266

10.5. Exemples d'Ús

# Verificar URL abans de l'actualització
test_url https://servidor.com/firmware/geopulse_v3.0.6.bin

# Iniciar actualització remota
remote_ota_update https://servidor.com/firmware/geopulse_v3.0.6.bin

# Comprovar estat de l'actualització
ota_status