Decoder Microservice - Architecture & Flow
Overview
Il Decoder è il microservizio che riceve dati GPS dai dispositivi tracker, li decodifica e li pubblica su Redis per il processing downstream.
📂 Struttura Package
com.visla.decoder/
├── Main.java # Entry point
├── MainModule.java # Dependency Injection
│
├── server/ # Gestione server TCP/UDP
│ ├── ServerManager.java # Registra tutti i protocolli
│ ├── TrackerServer.java # Server TCP/UDP per protocollo
│ ├── TrackerConnector.java # Interfaccia connettore
│ └── TrackerClient.java # Client outbound (opzionale)
│
├── pipeline/ # Pipeline Netty
│ ├── BasePipelineFactory.java # Costruisce pipeline handler
│ ├── PipelineBuilder.java # Builder per pipeline
│ ├── ProcessingHandler.java # Pubblica su Redis
│ ├── NetworkMessage.java # Wrapper messaggio rete
│ ├── BufferingManager.java # Riordino posizioni
│ ├── MediaManager.java # Gestione foto/video
│ └── network/ # Handler Netty
│ ├── MainEventHandler.java
│ ├── AcknowledgementHandler.java
│ └── ...
│
├── frame/ # Frame decoders
│ ├── BaseFrameDecoder.java # Base per split messaggi
│ ├── CharacterDelimiterFrameDecoder.java
│ └── ExtendedObjectDecoder.java
│
├── protocol/ # Protocolli GPS
│ ├── base/ # Classi base
│ │ ├── Protocol.java
│ │ ├── BaseProtocol.java
│ │ ├── BaseProtocolDecoder.java
│ │ └── BaseProtocolEncoder.java
│ │
│ ├── s21l/ # S21L (porta 5052) ✅
│ ├── g11lse/ # G11L-SE (porta 5058) ✅
│ ├── c059/ # C059 (porta 5059) ✅
│ ├── p5/ # P5 (porta 5054) ✅
│ ├── huabao/ # Base per S21L, P5, C003...
│ ├── gt06/ # Base per G11LSE, R12L...
│ └── ... # Altri protocolli
│
├── model/ # Modelli dati
│ ├── Position.java # Posizione GPS
│ ├── Device.java # Dispositivo
│ ├── Command.java # Comando da inviare
│ ├── Event.java # Evento rilevato
│ └── ...
│
├── session/ # Gestione sessioni
│ ├── DeviceSession.java # Sessione per device
│ ├── ConnectionManager.java # Manager connessioni
│ └── cache/ # Cache device/position
│
├── command/ # Gestione comandi
│ └── CommandConsumer.java # Riceve comandi da Redis
│
├── config/ # Configurazione
│ ├── Config.java
│ ├── Keys.java # Chiavi configurazione
│ └── ...
│
└── util/ # Utility
├── Checksum.java
├── Parser.java
├── DateBuilder.java
└── ...
🔄 Data Flow: Device → Redis
┌──────────────┐
│ GPS Device │
│ (S21L, G11L) │
└──────┬───────┘
│ TCP/UDP (porta 5052, 5054, 5058, 5059)
▼
┌──────────────────────────────────────────────────────────────┐
│ 1. TrackerServer (server/) │
│ - Accetta connessione │
│ - Crea pipeline Netty │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 2. FrameDecoder (frame/) │
│ - Split stream TCP in messaggi singoli │
│ - Ogni protocollo ha il suo frame decoder │
│ Input: [0x78][0x78][...data...][0x0D][0x0A] │
│ Output: ByteBuf con messaggio completo │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 3. ProtocolDecoder (protocol/) │
│ - Decodifica bytes → Position object │
│ - Estrae: lat, lon, speed, course, attributes │
│ │
│ Input: ByteBuf │
│ Output: Position { │
│ deviceId: 123, │
│ latitude: 41.9028, │
│ longitude: 12.4964, │
│ speed: 45.5, │
│ attributes: {ignition: true, alarm: null} │
│ } │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 4. ProcessingHandler (pipeline/) │
│ - Serializza Position in JSON │
│ - Pubblica su Redis Pub/Sub │
│ │
│ Redis PUBLISH "positions" → JSON │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 5. Downstream Microservices │
│ - position-filter (filtra posizioni invalide) │
│ - position-enricher (calcola distance, motion) │
│ - db-persister (salva su PostgreSQL) │
│ - event-detector (rileva eventi) │
└──────────────────────────────────────────────────────────────┘
🔙 Command Flow: Redis → Device
┌──────────────────────────────────────────────────────────────┐
│ API/Frontend │
│ POST /api/commands {deviceId: 123, type: "engineStop"} │
└──────────────────────────────────────────────────────────────┘
│
▼ Redis PUBLISH "commands"
┌──────────────────────────────────────────────────────────────┐
│ 1. CommandConsumer (command/) │
│ - Sottoscritto a Redis channel "commands" │
│ - Riceve comando JSON │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 2. ConnectionManager (session/) │
│ - Trova sessione attiva per deviceId │
│ - Recupera Netty Channel │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 3. ProtocolEncoder (protocol/) │
│ - Codifica Command → bytes │
│ - Formatta secondo protocollo device │
└──────────────────────────────────────────────────────────────┘
│
▼ TCP/UDP
┌──────────────────────────────────────────────────────────────┐
│ GPS Device │
│ - Riceve comando │
│ - Esegue azione (stop engine, unlock doors, etc.) │
└──────────────────────────────────────────────────────────────┘
📊 Protocolli Attivi
| Protocollo | Porta | Device Supportati |
|---|---|---|
| S21L | 5052 | S21L series |
| P5 | 5054 | P5 series |
| G11L-SE | 5058 | G11L-SE |
| C059 | 5059 | C059 series |
🔧 Configurazione
Le porte e i protocolli sono configurati tramite variabili d'ambiente o file di configurazione:
# Porta per protocollo S21L
s21l.port=5052
# Porta per protocollo G11L-SE
g11lse.port=5058
# Redis
redis.host=localhost
redis.port=6379
🔗 Dipendenze
- Netty - Framework I/O asincrono per TCP/UDP
- Redis (Jedis) - Pub/Sub per comunicazione inter-service
- Jackson - Serializzazione JSON
- Guice - Dependency Injection