Position Fields Reference

Questo documento elenca tutti i campi che il Decoder può estrarre dai dispositivi GPS e inviare tramite Redis ai microservizi downstream (WebSocket, DB, Event Detector, ecc.).

[!NOTE] I campi sono opzionali. Ogni protocollo (S21L, G11L-SE, C059, ecc.) supporta un sottoinsieme di questi campi.

Campi Core

Campo	Tipo	Descrizione
`id`	long	ID univoco della posizione
`deviceId`	long	ID del dispositivo
`protocol`	string	Nome del protocollo (es: "s21l", "g11lse")
`deviceTime`	Instant	Timestamp dal dispositivo
`fixTime`	Instant	Timestamp del fix GPS
`serverTime`	Instant	Timestamp di ricezione sul server
`latitude`	double	Latitudine (gradi decimali)
`longitude`	double	Longitudine (gradi decimali)
`altitude`	double	Altitudine (metri)
`speed`	double	Velocità (nodi, convertire in km/h: × 1.852)
`course`	double	Direzione/heading (gradi, 0-360)
`valid`	boolean	Fix GPS valido

Stato Dispositivo

Campo	Tipo	Descrizione
`ignition`	Boolean	Accensione attiva
`motion`	Boolean	Dispositivo in movimento
`blocked`	Boolean	Dispositivo bloccato
`charging`	Boolean	In carica
`archive`	Boolean	Posizione storica (non real-time)

Batteria e Alimentazione

Campo	Tipo	Descrizione
`batteryLevel`	Integer	Livello batteria (0-100 %)
`battery`	Float	Tensione batteria interna (V)
`power`	Float	Tensione alimentazione esterna (V)

Rete e GPS

Campo	Tipo	Descrizione
`rssi`	Integer	Segnale GSM (dBm)
`satellites`	Integer	Numero satelliti GPS
`network`	Network	Informazioni rete cellulare

Contatori / Odometro

Campo	Tipo	Descrizione
`odometer`	Long	Odometro totale (metri)
`odometerTrip`	Float	Odometro viaggio (metri)
`hours`	Long	Ore di funzionamento

Dati OBD (veicoli)

Campo	Tipo	Descrizione
`obdSpeed`	Integer	Velocità da OBD (km/h)
`obdOdometer`	Long	Odometro da OBD (km)
`rpm`	Integer	Giri motore (RPM)
`throttle`	Float	Acceleratore (%)
`engineLoad`	Float	Carico motore (%)
`coolantTemp`	Integer	Temperatura liquido raffreddamento (°C)
`fuelLevel`	Float	Livello carburante (%)
`fuelConsumption`	Float	Consumo carburante
`fuelUsed`	Float	Carburante usato (L)
`vin`	String	Vehicle Identification Number
`dtcs`	String	Codici errore diagnostici

Allarmi

Campo	Tipo	Descrizione
`alarm`	String	Allarme principale (vedi tipi sotto)
`alarms`	List<String>	Lista di tutti gli allarmi attivi

Tipi di Allarme Supportati

Costante	Valore	Descrizione
`ALARM_SOS`	`sos`	Pulsante SOS premuto
`ALARM_OVERSPEED`	`overspeed`	Velocità eccessiva
`ALARM_LOW_BATTERY`	`lowBattery`	Batteria scarica
`ALARM_LOW_POWER`	`lowPower`	Alimentazione bassa
`ALARM_POWER_OFF`	`powerOff`	Alimentazione staccata
`ALARM_POWER_ON`	`powerOn`	Alimentazione collegata
`ALARM_POWER_CUT`	`powerCut`	Taglio alimentazione
`ALARM_VIBRATION`	`vibration`	Vibrazione rilevata
`ALARM_MOVEMENT`	`movement`	Movimento rilevato
`ALARM_FALL_DOWN`	`fallDown`	Caduta rilevata
`ALARM_SHOCK`	`shock`	Urto rilevato
`ALARM_TOW`	`tow`	Traino/rimozione
`ALARM_GEOFENCE`	`geofence`	Violazione geofence
`ALARM_GEOFENCE_ENTER`	`geofenceEnter`	Ingresso geofence
`ALARM_GEOFENCE_EXIT`	`geofenceExit`	Uscita geofence
`ALARM_GPS_ANTENNA_CUT`	`gpsAntennaCut`	Antenna GPS tagliata
`ALARM_TAMPERING`	`tampering`	Manomissione
`ALARM_REMOVING`	`removing`	Rimozione dispositivo
`ALARM_ACCIDENT`	`accident`	Incidente
`ALARM_JAMMING`	`jamming`	Jamming GPS/GSM
`ALARM_IDLE`	`idle`	Veicolo in sosta prolungata
`ALARM_ACCELERATION`	`hardAcceleration`	Accelerazione brusca
`ALARM_BRAKING`	`hardBraking`	Frenata brusca
`ALARM_CORNERING`	`hardCornering`	Curva brusca
`ALARM_DOOR`	`door`	Porta aperta
`ALARM_LOCK`	`lock`	Bloccato
`ALARM_UNLOCK`	`unlock`	Sbloccato
`ALARM_TEMPERATURE`	`temperature`	Temperatura anomala
`ALARM_FUEL_LEAK`	`fuelLeak`	Perdita carburante

Cell Tower / Localizzazione LBS

Campo	Tipo	Descrizione
`cellId`	Long	ID cella GSM
`lac`	Integer	Location Area Code
`mcc`	Integer	Mobile Country Code
`mnc`	Integer	Mobile Network Code
`cellTowers`	List<Map>	Lista torri cellulari `[{mcc, mnc, lac, cid, rssi}]`
`wifiAccessPoints`	List<Map>	Lista WiFi `[{mac, rssi}]`

I/O e Sensori

Campo	Tipo	Descrizione
`input`	Long	Bitmap ingressi digitali
`adc1`	Float	Valore ADC canale 1
`adc2`	Float	Valore ADC canale 2
`gSensor`	String	Dati accelerometro
`tilt`	String	Dati inclinazione
`temperatures`	Map<Integer, Float>	Sensori temperatura
`geofence`	Integer	ID geofence

Identificativi

Campo	Tipo	Descrizione
`driver`	String	Nome conducente
`driverId`	String	ID conducente (es. RFID)
`card`	String	Numero carta
`iccid`	String	ICCID della SIM

Altri Campi

Campo	Tipo	Descrizione
`event`	Integer	Codice evento numerico
`status`	Integer	Codice stato numerico
`result`	String	Risultato comando
`wakeSource`	Integer	Sorgente risveglio
`batteryAlarm`	Integer	Livello allarme batteria
`fuel1`	Float	Sensore carburante 1
`locks`	Map	Dati blocchi/serrature
`attributes`	Map<String, Object>	Attributi aggiuntivi (chiave-valore)

Esempio JSON Position

{
  "id": 123456,
  "deviceId": 42,
  "protocol": "s21l",
  "deviceTime": "2024-01-15T10:30:00Z",
  "fixTime": "2024-01-15T10:30:00Z",
  "serverTime": "2024-01-15T10:30:01Z",
  "latitude": 41.9028,
  "longitude": 12.4964,
  "altitude": 50.0,
  "speed": 45.5,
  "course": 180.0,
  "valid": true,
  "ignition": true,
  "motion": true,
  "batteryLevel": 85,
  "battery": 4.1,
  "satellites": 8,
  "rssi": -75,
  "alarm": null,
  "attributes": {
    "distance": 150.5,
    "totalDistance": 12500.0
  }
}

Chiavi Attributi Comuni

Questi sono valori che possono apparire nel campo attributes:

Chiave	Tipo	Descrizione
`distance`	double	Distanza dal punto precedente (m)
`totalDistance`	double	Distanza totale calcolata (m)
`hdop`	double	Horizontal Dilution of Precision
`approximate`	boolean	Posizione approssimativa (LBS/WiFi)
`image`	string	URL immagine
`video`	string	URL video
`audio`	string	URL audio
`steps`	int	Contapassi

Campi Core​

Stato Dispositivo​

Batteria e Alimentazione​

Rete e GPS​

Contatori / Odometro​

Dati OBD (veicoli)​

Allarmi​

Tipi di Allarme Supportati​

Cell Tower / Localizzazione LBS​

I/O e Sensori​

Identificativi​

Altri Campi​

Esempio JSON Position​

Chiavi Attributi Comuni​