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:

  1. rimuove gli spazi iniziali e finali;
  2. converte il nome in minuscolo;
  3. rimuove gli spazi;
  4. rimuove gli underscore (_);
  5. 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.