TKK CSV Injector — Riferimento formato file
1. Ambito
Questa specifica definisce il formato CSV accettato dall’importatore Trakkit CSV track.
Questo documento è destinato agli sviluppatori e contiene informazioni tecniche e specifiche. Non è pensato per fungere da fonte primaria di documentazione. Per un’introduzione e indicazioni generali d’uso, fare riferimento alla TKK – Documentazione generale di Trakkit.
Un file CSV rappresenta una sequenza di posizioni GPS associate a una boat esistente. Ogni record deve contenere un timestamp, latitudine e longitudine. Dati di navigazione come velocità, rotta, vento, prua, profondità, temperatura, pressione, RPM motore ed elevazione possono essere forniti opzionalmente.
2. Requisiti del file
| Property | Requirement |
|---|---|
| Tipo di file | Testo CSV |
| Codifica | UTF-8 o UTF-8 con BOM |
| Separatore di campo | virgola (,), punto e virgola (;), pipe (|), o TAB |
| Intestazione | Obbligatoria |
| Colonne minime | 3 |
| Campi obbligatori | DATE, LAT, LON |
| Separatore decimale | . o , |
Il file DEVE contenere almeno un record con una data, una latitudine e una longitudine valide.
3. File valido minimo
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130
2026-08-14 08:10:00;43.70840;7.29880
4. Corrispondenza dell’intestazione
I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole.
Prima di effettuare la corrispondenza di un’intestazione, l’importatore:
- rimuove gli spazi iniziali e finali;
- converte il nome in minuscolo;
- rimuove gli spazi;
- rimuove gli underscore (
_); - rimuove i trattini (
-).
I seguenti nomi di intestazione sono quindi equivalenti:
SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND
Ogni nome di campo canonico è esso stesso un’intestazione valida.
5. Campi obbligatori
DATE
Timestamp della posizione GPS (UTC implicito se non è presente il fuso orario)
Nomi di intestazione accettati:
DATE
date
ts
timestamp
datetime
time
horaire
utc
LAT
Latitudine.
Nomi di intestazione accettati:
LAT
lat
latitude
LON
Longitudine.
Nomi di intestazione accettati:
LON
lon
long
longitude
lng
Un record viene rifiutato se DATE, LAT o LON non possono essere analizzati.
6. Campi di navigazione opzionali
| Campo | Descrizione | Alias accettati |
|---|---|---|
AWS |
Velocità del vento apparente | aws, apparentwindspeed, windspeedapparent |
AWA |
Angolo del vento apparente | awa, apparentwindangle, windangleapparent |
COG |
Course Over Ground | cog, courseoverground |
SOG |
Speed Over Ground | sog, speedoverground |
TWA |
Angolo del vento reale | twa, truewindangle |
TWS |
Velocità del vento reale | tws, truewindspeed |
MTW |
Temperatura dell’acqua | mtw, watertemperature, tempwater, seatemperature |
MTA |
Temperatura dell’aria | mta, airtemperature, tempair |
HDG |
Prua | hdg, heading |
AWSMIN |
Velocità minima del vento apparente | awsmin, minaws, apparentwindspeedmin |
AWSMAX |
Velocità massima del vento apparente | awsmax, maxaws, apparentwindspeedmax |
TWD |
Direzione del vento reale | twd, truewinddirection |
CTW |
Course Through Water | ctw, coursethroughwater |
MBP |
Pressione barometrica | mbp, baropressure, pressure, pressurebaro, barometer |
STW |
Speed Through Water | stw, speedthroughwater |
DEPTH |
Profondità dell’acqua | depth, profondeur, waterdepth, sonde |
RPM |
RPM motore | rpm, enginerpm, motorrpm |
ELEV |
Elevazione / Altitudine | elev, elevation, alt, altitude |
Tutti i campi elencati sopra sono accettati per l’importazione nel database.
Un valore opzionale vuoto o non numerico viene memorizzato come valore null e non causa il rifiuto del record.
7. Formati di data e ora
DATE accetta timestamp Unix, timestamp ISO 8601 e diversi formati di data convenzionali.
7.1 Timestamp Unix
Epoca Unix in secondi:
1786694400
Epoca Unix in millisecondi:
1786694400000
Sono riconosciute stringhe di timestamp numeriche contenenti da 10 a 17 cifre.
I valori maggiori di 10^12 sono trattati come millisecondi.
7.2 ISO 8601
Esempi:
2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00
I valori con fuso orario vengono convertiti in UTC.
I timestamp ISO senza informazioni sul fuso orario sono interpretati come UTC.
7.3 Formati convenzionali
Sono accettati i seguenti formati:
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM
YYYY/MM/DD HH:MM:SS
YYYY/MM/DD HH:MM
YYYY-MM-DD
YYYY/MM/DD
DD/MM/YYYY HH:MM:SS
DD/MM/YYYY HH:MM
DD/MM/YYYY
YYYYMMDD HHMMSS
YYYYMMDD HHMM
YYYYMMDD
Esempi:
2026-08-14 10:35:12
2026-08-14 10:35
2026/08/14 10:35:12
14/08/2026 10:35:12
14/08/2026 10:35
14/08/2026
20260814 103512
20260814 1035
20260814
Le date convenzionali senza informazioni sul fuso orario sono interpretate come UTC.
8. Valori numerici
I campi numerici accettano sia il punto sia la virgola come separatore decimale, ma questo NON DEVE entrare in conflitto con il separatore di campo.
I campi possono essere protetti da doppi apici (").
Esempi validi:
5.7
5,7
"43.69520"
43,69520
9. Coordinate
Latitudine e longitudine devono essere numeriche.
Le coordinate negative sono accettate.
Esempio:
DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000
Le coordinate vengono arrotondate a cinque decimali prima della memorizzazione.
Esempio:
43.6952347 -> 43.69523
7.2846128 -> 7.28461
10. Valori mancanti
I campi obbligatori devono contenere valori validi.
Non valido:
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;
I campi opzionali possono essere vuoti:
DATE;LAT;LON;SOG;COG;AWS
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;;85;
2026-08-14 08:10:00;43.70840;7.29880;6.0;;
Un valore numerico opzionale non valido viene trattato come null.
11. Colonne sconosciute
Le colonne che non corrispondono a un campo riconosciuto o a un alias vengono ignorate per l’importazione dei dati di navigazione.
Esempio:
DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure
COMMENT è un campo sconosciuto.
I nomi di intestazione sconosciuti vengono registrati dall’importatore in:
fields_unknown.txt
Il file viene mantenuto nella stessa directory del CSV importato.
12. Validazione del file
Un file è accettato solo se sono soddisfatte tutte le seguenti condizioni:
| Check | Requirement |
|---|---|
| Il file esiste | Obbligatorio |
| Non vuoto | Obbligatorio |
| Rilevamento binario | Deve essere testo |
| Codifica | Deve essere leggibile come UTF-8 |
| Delimitatore | virgola (,), punto e virgola (;), pipe (|), o TAB senza conflitti |
| Intestazione | Almeno 3 colonne |
| Campi obbligatori | DATE, LAT, LON devono risolversi tramite nomi canonici o alias |
| Data | Almeno un record deve contenere una data, una latitudine e una longitudine valide |
Un file che non contiene alcun record GPS valido viene rifiutato.
13. Validazione dei record
Per ogni record CSV:
| Condizione | Risultato |
|---|---|
| DATE + LAT + LON validi | Record accettato |
| DATE non valida | Record rifiutato |
| LAT non valida | Record rifiutato |
| LON non valida | Record rifiutato |
| Campo opzionale non valido | Record accettato; campo memorizzato come null |
| Campo opzionale vuoto | Record accettato; campo memorizzato come null |
14. Formati di esempio
14.1 Solo posizione
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130
14.2 Velocità e rotta GPS
DATE;LAT;LON;SOG;COG
2026-08-14 08:00:00;43.69520;7.28460;5.4;82
2026-08-14 08:05:00;43.70110;7.29130;5.7;85
14.3 GPS e vento apparente
DATE;LAT;LON;SOG;COG;AWS;AWA
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2;41
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1;38
14.4 Nomi di intestazione lunghi
datetime;latitude;longitude;speedoverground;courseoverground;apparentwindspeed;apparentwindangle;truewindspeed;truewindangle;truewinddirection
2026-08-14T08:00:00Z;43.69520;7.28460;5.4;82;13.2;41;11.5;36;225
2026-08-14T08:05:00Z;43.70110;7.29130;5.7;85;14.1;38;12.0;34;228
14.5 Varianti dell’intestazione leggibili dall’uomo
Timestamp;Latitude;Longitude;Speed Over Ground;Course-Over-Ground;Apparent_Wind_Speed
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1
14.6 Virgole decimali
DATE;LAT;LON;SOG;COG
14/08/2026 08:00;43,69520;7,28460;5,4;82
14/08/2026 08:05;43,70110;7,29130;5,7;85
14.7 Timestamp Unix
timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85
14.8 Dati di navigazione estesi
DATE;LAT;LON;SOG;COG;STW;HDG;AWS;AWA;TWS;TWA;TWD;MTW;MTA;MBP;DEPTH;RPM;ELEV
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;5.1;80;13.2;41;11.5;36;225;24.7;28.1;1013.2;18.4;1850;0
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;5.4;83;14.1;38;12.0;34;228;24.8;28.2;1013.1;19.1;1870;0
16. Batch di importazione
Se vengono accettati almeno due record, l’importatore crea un batch con:
name = Uploaded from CSV
L’ora di inizio del batch è il timestamp più precoce tra i record accettati.
L’ora di fine del batch è il timestamp più recente tra i record accettati.
Tutti i record accettati da un’importazione CSV condividono lo stesso identificatore di batch.