NAVMATE Testopstelling

Testopstelling — DAC/ADC scheepsnavigatie-testinstrument

Firmware (NXP LPC1752, C) + PC-gereedschap (Python) voor een maritiem navigatie-testinstrument. De MCU leest scheepssensoren via een 24-bit ADC, stuurt drie analoge uitgangen aan via DAC's en streamt op commando van de PC testsignalen voor analyse — SH = Stuurhendel, RS = Roerstand, BAW = Bochtaanwijzer.

Dit is een getting-started. Voor hoe het systeem werkt (protocol, conversie, ontwerp) zie Meer documentatie onderaan.

Wat heb je nodig

• Python 3.12+ (voor de PC-tooling).
• De testopstelling-hardware verbonden via USB-serieel (alleen nodig om écht te meten — zonder hardware kun je de tests en de mock draaien).
• Alleen voor firmware bouwen/flashen: MCUXpresso IDE + een J-Link (SWD).

1. Project ophalen

git clone https://github.com/MITCHEL-Development/NAVMATE-Testopstelling.git
cd NAVMATE-Testopstelling

2. Python-omgeving opzetten

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Controleren dat alles werkt (geen hardware nodig)

Alle tests draaien op de host tegen een in-memory MCU-mock:

.venv/bin/python -m pytest

Groen? Dan is de PC-laag correct opgezet.

4. Seriële poort instellen

De verbinding én de testparameters staan samen in config.py. Pas het CONNECTION-blok aan op jouw poort:

CONNECTION = {
    "port":    "/dev/tty.usbserial-FTHKZ02P",   # bv. "COM5" op Windows
    "baud":    230400,                          # moet matchen met de firmware
    "timeout": 0.25,
    "retries": 3,
}

Vind je poort: macOS/Linux ls /dev/tty.* of ls /dev/ttyUSB*; Windows via Apparaatbeheer (COM-poorten). Flags --port / --baud overschrijven config.py.

5. Verbinding testen

python CLI.py ping

Krijg je een OK terug, dan praat de PC met de testopstelling.

6. Een eerste test draaien

config.py bevat al voorbeeld-PARAMS (duur, rate, signaal per kanaal). Sinds kort worden die automatisch naar de firmware gestuurd bij start/run — een losse load of ping vooraf is niet meer nodig. Draai dus direct een meting van 10 s @ 100 Hz naar een CSV:

python CLI.py run 10 test.csv 100     # past config.py toe → output/test.csv (+ auto-plot)

Wil je de parameters expliciet (zonder te meten) naar de MCU sturen, dan kan dat nog steeds met python CLI.py load config.py.

Of stel zelf snel een signaal in zonder config.py te bewerken:

python CLI.py duration 10
python CLI.py rate 100
python CLI.py sh step 0V 5V 1000      # SH: stap 0→5 V na 1000 ms
python CLI.py rs ramp -2V 2V 500 3000 # RS: ramp
python CLI.py baw sine 0V 1V 1000 0   # BAW: sinus
python CLI.py run 10 test.csv 100

Interactieve modus (zonder argumenten) geeft een prompt met dezelfde commando's:

python CLI.py

Typ daar help voor het volledige overzicht.

7. Resultaat bekijken

• Na een run/start opent automatisch een plot van de CSV.
• Opgenomen CSV's staan in output/.
• Voor diepere analyse/vergelijking: dashboard.ipynb en testview.ipynb.

Handleiding (dagelijks gebruik)

Naast de getting-started hierboven: een praktische gids voor het werken met het instrument. Alles loopt via CLI.py (one-shot of interactief) en config.py.

• A. De CLI gebruiken
• B. Commando-overzicht
• C. Een meting configureren en draaien
• D. ADC kalibreren
• E. Oversampling & ruis (favg)
• F. Resultaten plotten

A. De CLI gebruiken

Twee manieren, met dezelfde commando's:

python CLI.py <commando> [args]   # one-shot: één commando, dan klaar
python CLI.py                     # interactief: prompt; typ 'help' of 'exit'

--port / --baud / --timeout / --retries overschrijven config.py per aanroep.

B. Commando-overzicht

Spanningen accepteren mV of V (bv. 5000, 5000mV, 5V, -2.5V). Kanalen heten sh/rs/baw (DAC) en ch0..ch3 (ADC). Het volledige overzicht: help op de prompt.

C. Een meting configureren en draaien

De nette werkwijze loopt via config.py → PARAMS:

PARAMS = {
    "duration": 60,                              # seconden
    "rate":     200,                             # Hz (100, 200, 300, 400 of 500)
    "favg":     16,                              # frame-middeling (zie §E)
    "sh":  ["step", "0V", "5V", "1000"],         # SH: stap 0→5 V na 1000 ms
    "rs":  ["ramp", "-5V", "5V", "500", "2000"], # RS: ramp
    "baw": ["sine", "0V", "3V", "2000"],         # BAW: sinus
    # PC-zijdige CSV-analyse (zie §F):
    "ema_alpha": 0.2, "sigma_k": 3.0, "rms_window": 25,
}

Daarna draaien — start/run sturen config.py automatisch eerst naar de MCU:

python CLI.py run 30 meting.csv      # 30 s, config.py-rate, → output/meting.csv
python CLI.py run 30 meting.csv 100  # idem, maar forceer 100 Hz
python CLI.py start meting.csv       # gebruik duur+rate uit config.py

Een lopende meting stop je met python CLI.py stop (of Ctrl-C in interactieve modus); de tot dan opgenomen CSV blijft behouden en wordt netjes afgerond.

Wil je los, zonder config.py te bewerken, snel iets instellen:

python CLI.py duration 10
python CLI.py rate 100
python CLI.py sh step 0V 5V 1000
python CLI.py run 10 test.csv

D. ADC kalibreren

Tweepunts (offset + gain) per kanaal is de standaard. Aanbevolen volgorde (laat het bord eerst ~5 min warmdraaien en gebruik een geijkte referentiespanning):

python CLI.py adc avg 64             # veel middelen tijdens het ijken
python CLI.py adc hwcal              # ADC-kern offset (geen signaal nodig)
# Per kanaal: 0 V aanleggen → offset; daarna een bekende spanning → gain:
python CLI.py adc cal ch0 offset
python CLI.py adc cal ch0 gain 9000  # 'gain <gemeten_mV>' = de echt aangelegde spanning
#   … herhaal voor ch1, ch2, ch3 …
python CLI.py adc cal show           # controleer de offset/gain-waarden
python CLI.py config save            # borg in flash
python CLI.py adc avg 16             # werkinstelling terug

adc syscal zero|gain doet een hardware-systeemkalibratie (op CH0, geldt voor alle kanalen). Volledige uitleg en de professionele werkwijze: features/adc-kalibreren.md.

E. Oversampling & ruis (favg)

favg middelt meerdere ADC-samples per frame → minder ruis (~√favg). Instelbaar via config.py (favg) of live met python CLI.py adc favg <n> (1..64).

• Het effect zie je in de CSV-kolom CHn rms_mV (daalt met meer middeling), niet in adc read … rms_uV (dat is een apart knopje, adc avg).
• Grote favg past alleen bij een lage framerate; bij 500 Hz is er weinig tijdbudget. Achtergrond en grenzen: features/protocol.md §8.2.

F. Resultaten plotten

• Na run/start opent automatisch een plot (te sturen met plot on|off); plot now toont de nieuwste CSV opnieuw.
• Los: python python/plotly.py (nieuwste CSV, alles gegroepeerd) of python python/plotly.py output/meting.csv "CH0 mV" "CH2 mV" voor losse kolommen.
• Opgenomen CSV's staan in output/; de plot wordt als .html ernaast geschreven.

De grafiek toont per eenheid een eigen subplot: DAC-uitgang, ADC-spanning (mV), ruwe code, en de PC-afgeleide statistiek rms/ema/clip, plus de optocouplers en event-flags. Wat elke reeks betekent en hoe hij berekend wordt staat in features/_software.md §10.

Firmware bouwen & flashen (optioneel)

Alleen nodig als je de C-firmware zelf wilt aanpassen. Het is een MCUXpresso IDE (Eclipse CDT) project voor de LPC1752. Part-support voor deze MCU zit ingebakken in de IDE — er hoeft geen SDK gedownload te worden. Het project hangt af van twee CMSIS-projecten die als voorbeeld-archief met elke MCUXpresso-installatie meekomen.

Importeren in MCUXpresso IDE

1. Clone de repo (zie 1. Project ophalen).

2. Importeer de twee CMSIS-projecten (eenmalig per workspace) via File → Import… → General → Existing Projects into Workspace → Select archive file:

   Archief (in de MCUXpresso-installatiemap)	Selecteer alleen
   ide/Examples/Legacy/CMSIS_CORE/CMSIS_CORE_Latest.zip	CMSIS_CORE_LPC17xx
   ide/Examples/CMSIS_DSPLIB/CMSIS_DSPLIB_Latest.zip	CMSIS_DSPLIB_CM3

   macOS: /Applications/MCUXpressoIDE_<versie>/ide/Examples/… — Windows: C:\nxp\MCUXpressoIDE_<versie>\ide\Examples\…

3. Importeer dit project: File → Import… → General → Existing Projects into Workspace → kies als root de gecloonde map → laat "Copy projects into workspace" uitgevinkt (anders werk je in een losse kopie en volgt git je wijzigingen niet). Het project verschijnt als navmate-testopstelling.

4. Build de Debug-configuratie (hamer-icoon). De Debug/-map en het linker-script worden automatisch gegenereerd, en de CMSIS-projecten worden als referenced projects vanzelf meegebouwd.

5. Flash/debug via J-Link: gebruik de meegeleverde launch-config navmate-testopstelling JLink Debug.launch (rechtsklik → Debug As). Hiervoor moeten de SEGGER J-Link drivers geïnstalleerd zijn.

Daarna kan het ook vanaf de commandoregel (toolchain in het pad), nadat de IDE de Debug/-map eenmaal heeft gegenereerd: make -C Debug all.

Repository-indeling

NAVMATE-Testopstelling/
├── src/  inc/          Firmware (C) + headers (inc/protocol.h = PC↔MCU-contract)
├── CLI.py              Hoofd-CLI vanaf de PC (one-shot + interactief)
├── config.py           Verbinding + testparameters (bewerk dit)
├── python/             PC-Python-pakket (protocol, commands, analyse, mock)
├── requirements.txt    Python-afhankelijkheden
├── tests/              Pytest-suites (PC-laag + C-firmware via ctypes)
├── output/             Opgenomen test-CSV's (niet in git)
├── notebooks/  *.ipynb Visualisatie & simulaties

cppcheck --enable=all \
  --inconclusive \
  --check-level=exhaustive \
  --std=c99 --platform=unix32 \
  --suppress=missingIncludeSystem \
  --suppress=missingInclude \
  --suppress=unusedFunction \
  --suppress=checkersReport \
  -I inc \
  -i src/lpc1752 -i src/cr_startup_lpc175x_6x.c \
  src/ 2> cppcheck_rapport.txt