TKK CSV Injector — Dateiformat-Referenz
1. Geltungsbereich
Diese Spezifikation definiert das CSV-Format, das vom Trakkit CSV Track-Importer akzeptiert wird.
Dieses Dokument richtet sich an Entwickler und enthält technische Informationen und Spezifikationen. Es ist nicht als primäre Dokumentationsquelle gedacht. Für eine Einführung und allgemeine Hinweise zur Nutzung siehe bitte die TKK – Trakkit General Documentation.
Eine CSV-Datei stellt eine Sequenz von GPS-Positionen dar, die einem bestehenden Boat zugeordnet sind. Jeder Datensatz muss einen Zeitstempel, Breitengrad und Längengrad enthalten. Navigations-Data wie Geschwindigkeit, Kurs, Wind, Steuerkurs, Tiefe, Temperatur, Druck, Motordrehzahl und Höhe können optional mitgeliefert werden.
2. Dateianforderungen
| Eigenschaft | Anforderung |
|---|---|
| Dateityp | Text-CSV |
| Kodierung | UTF-8 oder UTF-8 mit BOM |
| Feldtrenner | Komma (,), Semikolon (;), Pipe (|) oder TAB |
| Header | Erforderlich |
| Minimale Spaltenanzahl | 3 |
| Pflichtfelder | DATE, LAT, LON |
| Dezimaltrennzeichen | . oder , |
Die Datei MUSS mindestens einen Datensatz mit gültigem Datum, Breitengrad und Längengrad enthalten.
3. Minimal gültige Datei
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. Header-Abgleich
Header-Namen sind nicht case-sensitiv.
Vor dem Abgleich eines Headers führt der Importer Folgendes aus:
- entfernt führende und nachfolgende Whitespaces;
- konvertiert den Namen in Kleinbuchstaben;
- entfernt Leerzeichen;
- entfernt Unterstriche (
_); - entfernt Bindestriche (
-).
Die folgenden Header-Namen sind daher äquivalent:
SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND
Jeder kanonische Feldname ist selbst ein gültiger Header.
5. Pflichtfelder
DATE
Zeitstempel der GPS-Position (UTC implizit, wenn keine Zeitzone angegeben ist)
Akzeptierte Header-Namen:
DATE
date
ts
timestamp
datetime
time
horaire
utc
LAT
Breitengrad.
Akzeptierte Header-Namen:
LAT
lat
latitude
LON
Längengrad.
Akzeptierte Header-Namen:
LON
lon
long
longitude
lng
Ein Datensatz wird abgelehnt, wenn DATE, LAT oder LON nicht geparst werden können.
6. Optionale Navigationsfelder
| Feld | Beschreibung | Akzeptierte Aliase |
|---|---|---|
AWS |
Scheinbare Windgeschwindigkeit | aws, apparentwindspeed, windspeedapparent |
AWA |
Scheinbarer Windwinkel | awa, apparentwindangle, windangleapparent |
COG |
Kurs über Grund | cog, courseoverground |
SOG |
Geschwindigkeit über Grund | sog, speedoverground |
TWA |
Wahrer Windwinkel | twa, truewindangle |
TWS |
Wahre Windgeschwindigkeit | tws, truewindspeed |
MTW |
Wassertemperatur | mtw, watertemperature, tempwater, seatemperature |
MTA |
Lufttemperatur | mta, airtemperature, tempair |
HDG |
Steuerkurs | hdg, heading |
AWSMIN |
Minimale scheinbare Windgeschwindigkeit | awsmin, minaws, apparentwindspeedmin |
AWSMAX |
Maximale scheinbare Windgeschwindigkeit | awsmax, maxaws, apparentwindspeedmax |
TWD |
Wahre Windrichtung | twd, truewinddirection |
CTW |
Kurs durchs Wasser | ctw, coursethroughwater |
MBP |
Barometrischer Druck | mbp, baropressure, pressure, pressurebaro, barometer |
STW |
Geschwindigkeit durchs Wasser | stw, speedthroughwater |
DEPTH |
Wassertiefe | depth, profondeur, waterdepth, sonde |
RPM |
Motordrehzahl (RPM) | rpm, enginerpm, motorrpm |
ELEV |
Höhe / Altitude | elev, elevation, alt, altitude |
Alle oben aufgeführten Felder werden für den Datenbankimport akzeptiert.
Ein leerer oder nicht-numerischer optionaler Wert wird als Null-Wert gespeichert und führt nicht dazu, dass der Datensatz abgelehnt wird.
7. Datums- und Zeitformate
DATE akzeptiert Unix-Timestamps, ISO-8601-Timestamps und mehrere konventionelle Datumsformate.
7.1 Unix Timestamp
Unix-Epoche in Sekunden:
1786694400
Unix-Epoche in Millisekunden:
1786694400000
Numerische Timestamp-Strings mit 10 bis 17 Ziffern werden erkannt.
Werte größer als 10^12 werden als Millisekunden behandelt.
7.2 ISO 8601
Beispiele:
2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00
Werte mit Zeitzone werden nach UTC konvertiert.
ISO-Timestamps ohne Zeitzoneninformation werden als UTC interpretiert.
7.3 Konventionelle Formate
Die folgenden Formate werden akzeptiert:
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
Beispiele:
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
Konventionelle Datumsangaben ohne Zeitzoneninformation werden als UTC interpretiert.
8. Numerische Werte
Numerische Felder akzeptieren entweder einen Punkt oder ein Komma als Dezimaltrennzeichen, dies darf jedoch NICHT mit dem Feldtrenner kollidieren.
Felder können durch doppelte Anführungszeichen (") geschützt werden.
Gültige Beispiele:
5.7
5,7
"43.69520"
43,69520
9. Koordinaten
Breitengrad und Längengrad müssen numerisch sein.
Negative Koordinaten werden akzeptiert.
Beispiel:
DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000
Koordinaten werden vor dem Speichern auf fünf Dezimalstellen gerundet.
Beispiel:
43.6952347 -> 43.69523
7.2846128 -> 7.28461
10. Fehlende Werte
Pflichtfelder müssen gültige Werte enthalten.
Ungültig:
DATE;LAT;LON
2026-08-14 08:00:00;43.69520;
Optionale Felder dürfen leer sein:
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;;
Ein ungültiger optionaler numerischer Wert wird als null behandelt.
11. Unbekannte Spalten
Spalten, die keinem bekannten Feld oder Alias entsprechen, werden für den Import von Navigations-Data ignoriert.
Beispiel:
DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure
COMMENT ist ein unbekanntes Feld.
Unbekannte Header-Namen werden vom Importer protokolliert in:
fields_unknown.txt
Die Datei wird im selben Verzeichnis wie die importierte CSV gespeichert.
12. Dateivalidierung
Eine Datei wird nur akzeptiert, wenn alle folgenden Bedingungen erfüllt sind:
| Prüfung | Anforderung |
|---|---|
| Datei existiert | Erforderlich |
| Nicht leer | Erforderlich |
| Binär-Erkennung | Muss Text sein |
| Kodierung | Muss als UTF-8 lesbar sein |
| Trennzeichen | Komma (,), Semikolon (;), Pipe (|) oder TAB ohne Konflikt |
| Header | Mindestens 3 Spalten |
| Pflichtfelder | DATE, LAT, LON müssen über kanonische Namen oder Aliase auflösbar sein |
| Data | Mindestens ein Datensatz muss ein gültiges Datum, einen gültigen Breitengrad und einen gültigen Längengrad enthalten |
Eine Datei ohne gültigen GPS-Datensatz wird abgelehnt.
13. Datensatzvalidierung
Für jeden CSV-Datensatz:
| Bedingung | Ergebnis |
|---|---|
| Gültiges DATE + LAT + LON | Datensatz akzeptiert |
| Ungültiges DATE | Datensatz abgelehnt |
| Ungültiges LAT | Datensatz abgelehnt |
| Ungültiges LON | Datensatz abgelehnt |
| Ungültiges optionales Feld | Datensatz akzeptiert; Feld wird als null gespeichert |
| Leeres optionales Feld | Datensatz akzeptiert; Feld wird als null gespeichert |
14. Beispiel-Formate
14.1 Nur Position
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 GPS-Geschwindigkeit und Kurs
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 und scheinbarer Wind
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 Lange Header-Namen
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 Menschenlesbare Header-Varianten
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 Dezimalkommas
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 Unix Timestamps
timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85
14.8 Erweiterte Navigations-Data
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. Import-Batch
Wenn mindestens zwei Datensätze akzeptiert werden, erstellt der Importer einen Batch mit:
name = Uploaded from CSV
Die Batch-Startzeit ist der früheste Zeitstempel eines akzeptierten Datensatzes.
Die Batch-Stopzeit ist der späteste Zeitstempel eines akzeptierten Datensatzes.
Alle akzeptierten Datensätze aus einem CSV-Import teilen sich denselben Batch-Identifier.