TKK CSV Injector — Référence du format de fichier
1. Périmètre
Cette spécification définit le format CSV accepté par l’importeur Trakkit de Track CSV.
Ce document est destiné aux développeurs et contient des informations et des spécifications techniques. Il n’a pas vocation à constituer la source principale de documentation. Pour une introduction et des indications d’utilisation générales, veuillez vous référer à la TKK – Trakkit General Documentation.
Un fichier CSV représente une séquence de positions GPS associées à un bateau existant. Chaque enregistrement doit contenir un horodatage, une latitude et une longitude. Des données de navigation telles que la vitesse, le cap, le vent, le heading, la profondeur, la température, la pression, le régime moteur (RPM) et l’altitude peuvent être fournies en option.
2. Exigences du fichier
| Propriété | Exigence |
|---|---|
| Type de fichier | CSV texte |
| Encodage | UTF-8 ou UTF-8 avec BOM |
| Séparateur de champs | virgule (,), point-virgule (;), barre verticale (|), ou TAB |
| En-tête | Requis |
| Colonnes minimales | 3 |
| Champs requis | DATE, LAT, LON |
| Séparateur décimal | . ou , |
Le fichier DOIT contenir au moins un enregistrement avec une date, une latitude et une longitude valides.
3. Fichier minimal valide
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. Correspondance des en-têtes
Les noms d’en-tête ne sont pas sensibles à la casse.
Avant de faire correspondre un en-tête, l’importeur :
- supprime les espaces en début et fin ;
- convertit le nom en minuscules ;
- supprime les espaces ;
- supprime les underscores (
_) ; - supprime les tirets (
-).
Les noms d’en-tête suivants sont donc équivalents :
SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND
Chaque nom de champ canonique est lui-même un en-tête valide.
5. Champs requis
DATE
Horodatage de la position GPS (UTC implicite en l’absence de fuseau horaire)
Noms d’en-tête acceptés :
DATE
date
ts
timestamp
datetime
time
horaire
utc
LAT
Latitude.
Noms d’en-tête acceptés :
LAT
lat
latitude
LON
Longitude.
Noms d’en-tête acceptés :
LON
lon
long
longitude
lng
Un enregistrement est rejeté si DATE, LAT ou LON ne peut pas être analysé.
6. Champs de navigation optionnels
| Champ | Description | Alias acceptés |
|---|---|---|
AWS |
Vitesse du vent apparent | aws, apparentwindspeed, windspeedapparent |
AWA |
Angle du vent apparent | awa, apparentwindangle, windangleapparent |
COG |
Route sur le fond (COG) | cog, courseoverground |
SOG |
Vitesse sur le fond (SOG) | sog, speedoverground |
TWA |
Angle du vent réel | twa, truewindangle |
TWS |
Vitesse du vent réel | tws, truewindspeed |
MTW |
Température de l’eau | mtw, watertemperature, tempwater, seatemperature |
MTA |
Température de l’air | mta, airtemperature, tempair |
HDG |
Heading | hdg, heading |
AWSMIN |
Vitesse minimale du vent apparent | awsmin, minaws, apparentwindspeedmin |
AWSMAX |
Vitesse maximale du vent apparent | awsmax, maxaws, apparentwindspeedmax |
TWD |
Direction du vent réel | twd, truewinddirection |
CTW |
Route dans l’eau (CTW) | ctw, coursethroughwater |
MBP |
Pression barométrique | mbp, baropressure, pressure, pressurebaro, barometer |
STW |
Vitesse dans l’eau (STW) | stw, speedthroughwater |
DEPTH |
Profondeur d’eau | depth, profondeur, waterdepth, sonde |
RPM |
Régime moteur (RPM) | rpm, enginerpm, motorrpm |
ELEV |
Élévation / altitude | elev, elevation, alt, altitude |
Tous les champs listés ci-dessus sont acceptés pour l’import en base de données.
Une valeur optionnelle vide ou non numérique est stockée comme une valeur nulle et n’entraîne pas le rejet de l’enregistrement.
7. Formats de date et d’heure
DATE accepte les timestamps Unix, les timestamps ISO 8601 et plusieurs formats de date conventionnels.
7.1 Timestamp Unix
Époque Unix en secondes :
1786694400
Époque Unix en millisecondes :
1786694400000
Les chaînes de timestamp numériques contenant 10 à 17 chiffres sont reconnues.
Les valeurs supérieures à 10^12 sont traitées comme des millisecondes.
7.2 ISO 8601
Exemples :
2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00
Les valeurs avec fuseau horaire sont converties en UTC.
Les timestamps ISO sans information de fuseau horaire sont interprétés comme UTC.
7.3 Formats conventionnels
Les formats suivants sont acceptés :
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
Exemples :
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
Les dates conventionnelles sans information de fuseau horaire sont interprétées comme UTC.
8. Valeurs numériques
Les champs numériques acceptent soit un point soit une virgule comme séparateur décimal, mais cela ne DOIT PAS entrer en conflit avec le séparateur de champs.
Les champs peuvent être protégés par des guillemets doubles (").
Exemples valides :
5.7
5,7
"43.69520"
43,69520
9. Coordonnées
La latitude et la longitude doivent être numériques.
Les coordonnées négatives sont acceptées.
Exemple :
DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000
Les coordonnées sont arrondies à cinq décimales avant stockage.
Exemple :
43.6952347 -> 43.69523
7.2846128 -> 7.28461
10. Valeurs manquantes
Les champs requis doivent contenir des valeurs valides.
Invalide :
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;
Les champs optionnels peuvent être vides :
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;;
Une valeur numérique optionnelle invalide est traitée comme nulle.
11. Colonnes inconnues
Les colonnes qui ne correspondent pas à un champ ou à un alias reconnu sont ignorées pour l’import des données de navigation.
Exemple :
DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure
COMMENT est un champ inconnu.
Les noms d’en-tête inconnus sont enregistrés par l’importeur dans :
fields_unknown.txt
Le fichier est conservé dans le même répertoire que le CSV importé.
12. Validation du fichier
Un fichier est accepté uniquement si toutes les conditions suivantes sont satisfaites :
| Vérification | Exigence |
|---|---|
| Le fichier existe | Requis |
| Non vide | Requis |
| Détection binaire | Doit être du texte |
| Encodage | Doit pouvoir être lu en UTF-8 |
| Délimiteur | virgule (,), point-virgule (;), barre verticale (|), ou TAB sans conflit |
| En-tête | Au moins 3 colonnes |
| Champs requis | DATE, LAT, LON doivent se résoudre via des noms canoniques ou des alias |
| Data | Au moins un enregistrement doit contenir une date, une latitude et une longitude valides |
Un fichier ne contenant aucun enregistrement GPS valide est rejeté.
13. Validation des enregistrements
Pour chaque enregistrement CSV :
| Condition | Résultat |
|---|---|
| DATE + LAT + LON valides | Enregistrement accepté |
| DATE invalide | Enregistrement rejeté |
| LAT invalide | Enregistrement rejeté |
| LON invalide | Enregistrement rejeté |
| Champ optionnel invalide | Enregistrement accepté ; champ stocké à null |
| Champ optionnel vide | Enregistrement accepté ; champ stocké à null |
14. Exemples de formats
14.1 Position uniquement
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 Vitesse et cap 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 et vent apparent
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 Noms d’en-tête longs
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 Variantes d’en-tête lisibles par un humain
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 Virgules décimales
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 Timestamps Unix
timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85
14.8 Données de navigation étendues
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. Lot d’import
Si au moins deux enregistrements sont acceptés, l’importeur crée un lot avec :
name = Uploaded from CSV
L’heure de début du lot est l’horodatage le plus ancien parmi les enregistrements acceptés.
L’heure de fin du lot est l’horodatage le plus récent parmi les enregistrements acceptés.
Tous les enregistrements acceptés d’un même import CSV partagent le même identifiant de lot.