TKK CSV Injector — Referentie voor bestandsformaat

1. Toepassingsgebied

Deze specificatie definieert het CSV-formaat dat wordt geaccepteerd door de Trakkit CSV track-importer.

Dit document is bedoeld voor ontwikkelaars en bevat technische informatie en specificaties. Het is niet bedoeld als primaire bron van documentatie. Voor een introductie en algemene gebruiksrichtlijnen, raadpleeg de TKK – Trakkit General Documentation.

Een CSV-bestand vertegenwoordigt een reeks GPS-posities die gekoppeld zijn aan een bestaande boat. Elk record moet een tijdstempel, latitude en longitude bevatten. Navigatiegegevens zoals snelheid, koers, wind, heading, diepte, temperatuur, druk, motortoerental (RPM) en elevatie kunnen optioneel worden meegegeven.


2. Bestandsvereisten

Eigenschap Vereiste
Bestandstype Tekst CSV
Encoding UTF-8 of UTF-8 met BOM
Veldscheidingsteken komma (,), puntkomma (;), pipe (|), of TAB
Header Vereist
Minimum aantal kolommen 3
Verplichte velden DATE, LAT, LON
Decimaalscheidingsteken . of ,

Het bestand MOET minstens één record bevatten met een geldige datum, latitude en longitude.


3. Minimaal geldig bestand

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-matching

Headernamen zijn niet hoofdlettergevoelig.

Vóór het matchen van een header doet de importer het volgende:

  1. verwijdert leidende en afsluitende witruimte;
  2. zet de naam om naar lowercase;
  3. verwijdert spaties;
  4. verwijdert underscores (_);
  5. verwijdert koppeltekens (-).

De volgende headernamen zijn daarom equivalent:

SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND

Elke canonieke veldnaam is op zichzelf ook een geldige header.


5. Verplichte velden

DATE

Tijdstempel van de GPS-positie (UTC impliciet als er geen tijdzone is)

Geaccepteerde headernamen:

DATE
date
ts
timestamp
datetime
time
horaire
utc

LAT

Latitude.

Geaccepteerde headernamen:

LAT
lat
latitude

LON

Longitude.

Geaccepteerde headernamen:

LON
lon
long
longitude
lng

Een record wordt afgewezen als DATE, LAT, of LON niet kan worden geparsed.


6. Optionele navigatievelden

Veld Beschrijving Geaccepteerde aliassen
AWS Schijnbare windsnelheid aws, apparentwindspeed, windspeedapparent
AWA Schijnbare windhoek awa, apparentwindangle, windangleapparent
COG Course Over Ground cog, courseoverground
SOG Speed Over Ground sog, speedoverground
TWA Ware windhoek twa, truewindangle
TWS Ware windsnelheid tws, truewindspeed
MTW Watertemperatuur mtw, watertemperature, tempwater, seatemperature
MTA Luchttemperatuur mta, airtemperature, tempair
HDG Heading hdg, heading
AWSMIN Minimale schijnbare windsnelheid awsmin, minaws, apparentwindspeedmin
AWSMAX Maximale schijnbare windsnelheid awsmax, maxaws, apparentwindspeedmax
TWD Ware windrichting twd, truewinddirection
CTW Course Through Water ctw, coursethroughwater
MBP Barometrische druk mbp, baropressure, pressure, pressurebaro, barometer
STW Speed Through Water stw, speedthroughwater
DEPTH Waterdiepte depth, profondeur, waterdepth, sonde
RPM Motortoerental (RPM) rpm, enginerpm, motorrpm
ELEV Elevatie / altitude elev, elevation, alt, altitude

Alle hierboven vermelde velden worden geaccepteerd voor database-import.

Een lege of niet-numerieke optionele waarde wordt opgeslagen als een null-waarde en zorgt er niet voor dat het record wordt afgewezen.


7. Datum- en tijdformaten

DATE accepteert Unix-tijdstempels, ISO 8601-tijdstempels en verschillende conventionele datumformaten.

7.1 Unix-tijdstempel

Unix epoch in seconden:

1786694400

Unix epoch in milliseconden:

1786694400000

Numerieke tijdstempelstrings met 10 tot 17 cijfers worden herkend.

Waarden groter dan 10^12 worden behandeld als milliseconden.

7.2 ISO 8601

Voorbeelden:

2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00

Waarden met tijdzone worden omgezet naar UTC.

ISO-tijdstempels zonder tijdzone-informatie worden geïnterpreteerd als UTC.

7.3 Conventionele formaten

De volgende formaten worden geaccepteerd:

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

Voorbeelden:

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

Conventionele datums zonder tijdzone-informatie worden geïnterpreteerd als UTC.


8. Numerieke waarden

Numerieke velden accepteren een punt of een komma als decimaalscheidingsteken, maar dit MAG NIET conflicteren met het veldscheidingsteken.

Velden kunnen worden beschermd met dubbele aanhalingstekens (").

Geldige voorbeelden:

5.7
5,7
"43.69520"
43,69520

9. Coördinaten

Latitude en longitude moeten numeriek zijn.

Negatieve coördinaten worden geaccepteerd.

Voorbeeld:

DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000

Coördinaten worden vóór opslag afgerond op vijf decimalen.

Voorbeeld:

43.6952347 -> 43.69523
7.2846128  -> 7.28461

10. Ontbrekende waarden

Verplichte velden moeten geldige waarden bevatten.

Ongeldig:

DATE;LAT;LON
2026-08-14 08:00:00;43.69520;

Optionele velden mogen leeg zijn:

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;;

Een ongeldige optionele numerieke waarde wordt behandeld als null.


11. Onbekende kolommen

Kolommen die niet matchen met een herkend veld of alias worden genegeerd voor import van navigatiegegevens.

Voorbeeld:

DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure

COMMENT is een onbekend veld.

Onbekende headernamen worden door de importer vastgelegd in:

fields_unknown.txt

Het bestand wordt onderhouden in dezelfde directory als de geïmporteerde CSV.


12. Bestandsvalidatie

Een bestand wordt alleen geaccepteerd als aan alle volgende voorwaarden is voldaan:

Controle Vereiste
Bestand bestaat Vereist
Niet leeg Vereist
Binaire detectie Moet tekst zijn
Encoding Moet leesbaar zijn als UTF-8
Delimiter komma (,), puntkomma (;), pipe (|), of TAB zonder conflict
Header Minstens 3 kolommen
Verplichte velden DATE, LAT, LON moeten resolven via canonieke namen of aliassen
Data Minstens één record moet een geldige datum, latitude en longitude bevatten

Een bestand dat geen enkel geldig GPS-record bevat, wordt afgewezen.


13. Recordvalidatie

Voor elk CSV-record:

Voorwaarde Resultaat
Geldige DATE + LAT + LON Record geaccepteerd
Ongeldige DATE Record afgewezen
Ongeldige LAT Record afgewezen
Ongeldige LON Record afgewezen
Ongeldig optioneel veld Record geaccepteerd; veld opgeslagen als null
Leeg optioneel veld Record geaccepteerd; veld opgeslagen als null

14. Voorbeeldformaten

14.1 Alleen positie

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-snelheid en koers

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 en schijnbare 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 headernamen

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 Mensleesbare 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 Decimale komma's

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-tijdstempels

timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85

14.8 Uitgebreide navigatiegegevens

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. Importbatch

Als minstens twee records worden geaccepteerd, maakt de importer een batch met:

name = Uploaded from CSV

De starttijd van de batch is de vroegste geaccepteerde recordtijdstempel.

De stoptijd van de batch is de laatste geaccepteerde recordtijdstempel.

Alle geaccepteerde records van één CSV-import delen dezelfde batch identifier.