diff --git a/docs/da/errata/index.md b/docs/da/errata/index.md new file mode 100644 index 0000000..9abf031 --- /dev/null +++ b/docs/da/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Kendte fejl +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Kendte fejl + +Denne side viser alle kendte hardwarefejl i de forskellige HALMET-versioner. + +## Version 1.0.0 + +De digitale indgange 3 og 4 er byttet om i silketrykket på bagsiden. De korrekte benforbindelser er: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/da/getting-started/index.md b/docs/da/getting-started/index.md new file mode 100644 index 0000000..bc0915f --- /dev/null +++ b/docs/da/getting-started/index.md @@ -0,0 +1,73 @@ +--- +title: Kom godt i gang +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Kom godt i gang + +## Samling af hardwaren + +For at stikkene kan placeres mere frit i små kabinetter, leveres HALMET-kortene uden 1-Wire- og GPIO-stiklisterne monteret. Hvis du regner med at bruge en af disse grænseflader, skal du selv lodde stiklisten fast på kortet. + +Har du brug for en vejledning i at lodde stikben fast på kortet, kan du se SH-ESP32'ens [vejledning til samling af hardwaren](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards). + +## Strømforsyning af kortet + +HALMET forsynes gennem NMEA 2000-stikket. Hvis du skal slutte HALMET til et NMEA 2000-netværk, kan du forsyne kortet direkte fra netværket. Tilslut i så fald NMEA 2000-ledningerne til den 4-benede aftagelige klemrække som vist på figuren nedenfor. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Tilslut NMEA 2000-ledningerne til stikket som vist.
+
+ +Hvis du ikke skal slutte HALMET til et NMEA 2000-netværk, skal du bruge det samme stik, men kun tilslutte ledninger til `-` og `+`. Enhver strømforsyning på 5–32 V kan bruges. Kortets typiske strømforbrug med WiFi aktiveret er 0,07 A ved 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Tilslut forsyningsledningerne til stikket som vist.
+
+ +## Kabinetter + +Om bord på en båd bør HALMET altid placeres i et vandtæt kabinet. +Kortet er konstrueret, så det passer i [SH-ESP32-kabinettet](https://shop.hatlabs.fi/products/sh-esp32-enclosure). Nedenfor ses et eksempel på et HALMET-kort monteret i kabinettet. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET monteret i SH-ESP32-kabinettet.
+
+ +SH-ESP32-kabinettet har begrænset plads til stik. +Hver af langsiderne kan i praksis kun rumme 2–3 panelstik. +Hvis du regner med at tilslutte mere end nogle få indgange, anbefales et større kabinet. +For eksempel har Hat Labs' [kompakte SH-RPi-kabinet](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm), som ses nedenfor, rigelig plads til stik. + +
+![](medium_enclosure.jpg){ width="50%" } +
Det kompakte SH-RPi-kabinet giver mere plads til placering af panelstik.
+
+ + +Andre egnede vandtætte kabinetter er nemme at finde i enhver netbutik. Større samledåser til udendørs brug kan også bruges til formålet. + +### Boring af huller til panelstik + +Kabinetterne har normalt ingen forborede huller. Brug altid et konisk bor eller et trinbor (det, der ligner et lille juletræ af metal), når du borer huller. Almindelige metalbor bider let for hårdt og kan revne kabinetvæggen. + +Når du planlægger placeringen af huller og stik, skal du sørge for plads nok til at spænde stikkenes møtrikker og til selve stikhuset. Hvis du planlægger at vægmontere kabinettet, anbefales det at vende stikkene nedad, så risikoen for indtrængende vand bliver mindst mulig. + +Passende hulstørrelser til forskellige stik: + +- PG7-kabelforskruning og M12-panelstik (NMEA 2000): 12,5 mm eller 1/2" +- SP13-panelstik (de blåsorte plaststik): 13 mm +- PG9-kabelforskruning: 16 mm eller 5/8" + +Gennemføringstyller af gummi eller silikone giver plads til væsentligt flere kabler end panelstik eller kabelforskruninger. De er dog ikke lige så vandtætte som panelstik eller kabelforskruninger. Desuden kræver de, at kablet monteres permanent, hvilket kan gøre det vanskeligere at servicere systemet. + +TODO: Tilføj et billede af en gennemføringstyl. + +### Lodning af panelstikkene + +Brug altid krympeflex på de enkelte ledere, når du lodder de indvendige ledninger til panelstikkene. +Husk altid at trække krympeflexen ind på ledningen, _inden_ du lodder... +Som regel kan du først fylde loddetin i stikbenets hulrum og derefter smelte tinnet igen og føre lederen ind. diff --git a/docs/da/hardware/index.md b/docs/da/hardware/index.md new file mode 100644 index 0000000..c923ea8 --- /dev/null +++ b/docs/da/hardware/index.md @@ -0,0 +1,230 @@ +--- +title: Hardwarebeskrivelse +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hardware + +## Introduktion til ESP32 + +HALMET er baseret på det kraftfulde mikrocontrollermodul ESP32-WROOM-32E. ESP32 er en dobbeltkernet mikrocontroller med indbygget WiFi og Bluetooth. ESP32 er et populært valg til IoT-applikationer på grund af den lave pris, det gode udvalg af perifere enheder og den enkle anvendelse. + +## Kortets funktionsblokke + +Kortets forskellige funktionsblokke er beskrevet nedenfor. + +
+![](HALMET-func.jpg){ width="60%" } +
HALMETs funktionsblokke.
+
+ +1. NMEA 2000 samt strømindgang og beskyttelse. NMEA 2000-stikket har følgende + beskyttelseselementer: + - 500 mA selvgendannende sikring + - Diode til beskyttelse mod omvendt polaritet + - TVS-dioder til overspændings- og ESD-beskyttelse + - Totrins støjfiltrering + +2. Strømforsyning. En switchmode-strømforsyning med en maksimal udgangsstrøm på 2 A. + +3. CAN-transceiver til NMEA 2000. RX- og TX-LED'er giver en visuel indikation af + aktiviteten på CAN-bussen. + +4. I2C- og 1-Wire-grænseflader til tilslutning af yderligere sensorer. + +5. Brugergrænseflade. En reset-knap, en knap til boot-tilstand og generelle formål, + en rød strøm-LED og en blå brugerprogrammerbar LED. + +6. USB 2.0-grænseflade til programmering og fejlfinding. + +7. ESP32-WROOM-32E-modul med indbygget WiFi og Bluetooth. Modulet på HALMET-kortet + indeholder 16 MB flashhukommelse. + +8. Kredsløb til galvanisk adskillelse af de digitale og analoge indgange. + +9. Analoge indgange. Kortet har fire analoge indgange med 16-bits opløsning og en + maksimal indgangsspænding på 33 V. Hver indgang har beskyttelse mod under- og + overspænding samt lavpasfiltrering med en knækfrekvens på 160 Hz, som reducerer + målestøjen. + + De analoge indgange har en valgfri konstantstrømkilde på 10 mA til aktiv + modstandsmåling. Konstantstrømkilden kan aktiveres med CCS-jumperstiklisterne. + + I modstandsmåletilstand er den største modstand, der kan måles, 300 ohm. + +10. Digitale indgange. HALMET har fire digitale indgange med en maksimal + indgangsspænding på ±32 V. Indgangene har en Schmitt trigger, der forbedrer + støjimmuniteten. + + +## Galvanisk adskillelse + +Kortet har galvanisk adskillelse mellem de digitale og analoge indgange og +ESP32-mikrocontrolleren. Adskillelsen er opnået med digitale isolatorer til +henholdsvis I2C og de fire digitale indgange samt med en adskilt DC/DC-omformer, +der forsyner den adskilte del. + +Takket være adskillelsen kan kortet forsynes fra NMEA 2000-netværket uden risiko +for jordsløjfer. Adskillelsen beskytter også mod spændingsspidser og støj på +indgangene. + +
+![](HALMET-isolation.jpg){ width="60%" } +
HALMETs isolationsbarriere. Indgangsstikkene er adskilt fra resten af kortet, +hvilket betyder, at de ikke har fælles jordforbindelse med resten af kortet.
+
+ +## Stik + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
HALMETs stik, oversiden.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
HALMETs stik, undersiden.
+
+ +
+
+ +### Stik på oversiden + +1. NMEA 2000-stik. Stikket er en 4-benet aftagelig klemrække, der er kompatibel + med Phoenix MC 3.81. Stikket bruges til at forbinde kortet til et + NMEA 2000-netværk og til at forsyne kortet. + +2. 1-Wire-stikliste. 1-Wire-stiklisten kan bruges til at forbinde 1-Wire-sensorer + til kortet. Den er en 3-benet stikliste med 2,54 mm benafstand. Stiklisten er + ikke monteret på kortet fra fabrikken, fordi den kan komme i vejen for + placeringen af kabinettets panelstik. + +3. I2C-stikliste. I2C-stiklisten kan bruges til at forbinde I2C-sensorer til + kortet. Den er en 4-benet stikliste med 2,54 mm benafstand. + +4. Micro USB-stik. Stikket bruges til programmering og fejlfinding af kortet. + +5. Ubestykkede loddeflader til reset- (EN) og boot-signalerne (IO0). + +6. GPIO-stikliste. GPIO-stiklisten er en 2×10-benet stikliste med 2,54 mm + benafstand. Stiklisten fører ESP32'ens ledige GPIO-ben ud og kan også bruges + som JTAG-stikliste. + +7. Stikliste til forsyning af det adskilte område. Stiklisten kan bruges til at + forsyne eksterne enheder fra 3V3 og GND i den adskilte del. + +8. Jumperkontakter til konstantstrømkilden (CCS) til de analoge indgange. + Konstantstrømkilden kan aktiveres ved at kortslutte jumperkontakterne. + +9. Stik til analoge indgange. Stikkene er 2-benede aftagelige klemrækker, der er + kompatible med Phoenix MC 3.81. Stikkene bruges til at forbinde analoge + sensorer til kortet. + +10. Stik til digitale indgange. Stikkene er 2-benede aftagelige klemrækker, der er + kompatible med Phoenix MC 3.81. Stikkene bruges til at forbinde digitale + sensorer til kortet. + +### Stik på undersiden + +11. Loddejumper til CAN-terminering. Loddejumperen kan kortsluttes for at aktivere + termineringsmodstanden på 120 ohm til CAN-bussen. Brug ikke + termineringsmodstanden i NMEA 2000-netværk. + +12. Loddejumper til lavpasfilter. Loddejumperen kan kortsluttes for at aktivere et + lavpasfilter på den pågældende analoge indgang. Filteret har en knækfrekvens + på 2,3 kHz. Filteret kan for eksempel bruges til at reducere støj i signalet + fra en omdrejningstæller. + +13. Loddejumper til pull-down-modstand. Loddejumperen kan kortsluttes for at + aktivere en pull-down-modstand på 100 kohm på den pågældende digitale indgang. + Pull-down-modstanden kan bruges til at aflæse en normalt åben (NO) kontakt, + som trækkes høj, når den er sluttet. + +14. Loddejumper til pull-up-modstand. Loddejumperen kan kortsluttes for at aktivere + en pull-up-modstand på 100 kohm på den pågældende digitale indgang. + Pull-up-modstanden kan bruges til at aflæse en normalt sluttet (NC) kontakt, + som trækkes lav, når den er sluttet. + +15. Loddejumpere til valg af ADS1115'ens I2C-adresse. Loddejumperne kan kortsluttes + for at vælge I2C-adressen på analog-digital-omsætteren (ADC) ADS1115. + Loddejumperne bruges til at undgå adressekonflikter, når der er forbundet flere + ADS1115-AD-omsættere til den samme I2C-bus. Loddefladerne kan også bruges til + at forbinde yderligere I2C-enheder til kortets adskilte område. + +### GPIO-oversigt + +HALMET reserverer et antal GPIO-ben til de perifere indgangsenheder. Ledige GPIO-ben +er ført ud til den 2×10-benede GPIO-stikliste. Følgende tabel viser GPIO-benene og +deres funktioner. + +| GPIO | Funktion | Bemærkninger | +| ------: | :---------- | :------------------------------------------------- | +| 0 | Boot-knap | Går i bootloader, når benet trækkes lavt | +| 1 | TXD0 | Sender data til USB | +| 2 | LED | Rød LED på kortet | +| 3 | RXD0 | Modtager data fra USB | +| 4 | 1-Wire DQ | 1-Wire-datalinje | +| 5 | - | Ledig på GPIO-stiklisten | +| 12 | - / TDI | Ledig på GPIO-stiklisten. Alternativt: JTAG TDI | +| 13 | - / TCK | Ledig på GPIO-stiklisten. Alternativt: JTAG TCK | +| 14 | - / TMS | Ledig på GPIO-stiklisten. Alternativt: JTAG TMS | +| 15 | - / TDO | Ledig på GPIO-stiklisten. Alternativt: JTAG TDO | +| 16 | - | Ledig på GPIO-stiklisten | +| 17 | - | Ledig på GPIO-stiklisten | +| 18 | CAN RX | Modtager fra NMEA 2000 | +| 19 | CAN TX | Sender til NMEA 2000 | +| 21 | I2C SDA | I2C-datalinje. Bruges til analog indgang | +| 22 | I2C SCL | I2C-klokkelinje. Bruges til analoge indgange | +| 23 | DI1 | Digital indgang 1 | +| 25 | DI2 | Digital indgang 2 | +| 27 | DI3 | Digital indgang 3 | +| 26 | DI4 | Digital indgang 4 | +| 32 | - | Ledig på GPIO-stiklisten | +| 33 | - | Ledig på GPIO-stiklisten | +| 34 | - | Ledig på GPIO-stiklisten | +| 35 | - | Ledig på GPIO-stiklisten | +| 36 (VP) | Kun indgang | Ledig på GPIO-stiklisten | +| 39 (VN) | Kun indgang | Ledig på GPIO-stiklisten | + + +## Strømforsyning + +Det tilladte indgangsspændingsområde på kortet er 5–32 V. Det typiske strømforbrug er +90 mA ved 12 V med WiFi-modulet aktivt (svarer til 1,1 W). + +## NMEA 2000 + +NMEA 2000 er en udbredt kommunikationsstandard, der bruges til at forbinde sensorer, styreenheder og displayenheder på både og skibe. Den bygger på Controller Area Network (CAN-bussen), som er en køretøjsbusstandard, der er udviklet, så enheder kan kommunikere indbyrdes uden en værtscomputer. + +Kortet overholder NMEA 2000-standarden, så længe ingen af de ikke-adskilte stik er forbundet til andre enheder med fælles jordreference. En 1-Wire-temperatursensor med et langt kabel kan for eksempel bruges, fordi den ikke har fælles jordforbindelse med andre enheder. Derimod ville det bryde overensstemmelsen med NMEA 2000 at forbinde en I2C-AD-omsætter til det ikke-adskilte I2C-stik. + +TODO: NMEA 2000-benforbindelser til GPIO + +## Status-LED'er + +Der er to knapper og to LED'er på HALMET-kortet. De to knapper er mærket Reset og Boot. Reset-knappen genstarter kortet ved at trække ESP32'ens Enable-ben lavt. Boot-knappen er forbundet til GPIO0 og kan bruges under opstart af enheden til at tvinge modulet i download-tilstand. Ellers kan den bruges som en almindelig knapindgang. + +De to LED'er er ikke udtrykkeligt mærket. Den røde LED lyser, når der er 3,3 V forsyning på kortet. Den blå LED er forbundet til GPIO2 (det ben, der almindeligvis bruges til LED på ESP32-udviklingskort). Den kan styres af brugerprogrammer og vise enhedens tilstand. + +## 1-Wire + +1-Wire er et bussystem til kommunikation mellem enheder, udviklet af Dallas Semiconductor, som siden er blevet opkøbt af Maxim Integrated Products. Selvom 1-Wire er en langsom protokol, der kun understøtter hastigheder op til 16,3 kbit/s, er den meget enkel at implementere og kan bruges over lange afstande. Den bruges almindeligvis til temperatursensorer og lignende enkle måleenheder. + +HALMETs 1-Wire-implementering har ESD- og RF-støjfiltrering samt lavpasfiltrering, der forbedrer netværkets pålidelighed. + +Bemærk, at 1-Wire-databenet (mærket »DQ«) fysisk er forbundet til GPIO4, så brug GPIO4 til alle 1-Wire-data i dit program. + +## I2C + +I2C (Inter-Integrated Circuit) er en meget udbredt synkron seriel kommunikationsbus, der almindeligvis bruges til at forbinde en række forskellige IC'er. Den bruger to dataledninger ud over spænding og jordforbindelse. + +HALMET bruger I2C internt til AD-omsætteren ADS1115. I2C-bussen er også ført ud til en 4-benet stikliste, så der kan forbindes yderligere I2C-enheder. + +I2C-bussen er forbundet til GPIO21 (SDA) og GPIO22 (SCL) på ESP32'en. Disse ben er standardbenene til I2C i Arduinos ESP32-miljø, men de er forskellige fra standardbenene på SH-ESP32. diff --git a/docs/da/index.md b/docs/da/index.md new file mode 100644 index 0000000..a0c4c2e --- /dev/null +++ b/docs/da/index.md @@ -0,0 +1,35 @@ +--- +title: Introduktion +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Introduktion + +HALMET, Hat Labs Marine Engine & Tank interface, er et udviklingskort til tilslutning af motor- og tanksensorer på både og andre køretøjer. Det kan bruges til at aflæse digitale og analoge sensorer og til at kommunikere med andre enheder via NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire eller GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Billede af HALMET
+
+ +## Vigtigste funktioner + +- **Fire digitale indgange**: HALMET har fire digitale indgange til aflæsning af digitale alarmsignaler eller til brug som tællere. Indgangene tåler spændinger mellem −32 V og +32 V. De digitale indgange kan bruges både til at registrere signalniveauer og til tidsvarierende signaler som motorens omdrejningstal, brændstofflow eller pulser fra en kædetæller. + +- **Fire analoge indgange**: HALMET har fire analoge indgange til aflæsning af analoge sensorer. Indgangene tåler spændinger mellem −32 V og +32 V og har et måleområde fra 0 til 33 V. Indgangene er forbundet til en 16-bits analog-digital-omsætter (ADC) af typen ADS1115. De analoge indgange kan bruges både til passiv spændingsmåling og til aktiv modstandsmåling. + +- **NMEA 2000-kompatibel**: HALMET er fuldt kompatibel med NMEA 2000-standarden. Kortet kan sluttes til et NMEA 2000-netværk gennem den indbyggede NMEA 2000-grænseflade. + +- **I2C-, 1-Wire- og GPIO-grænseflader**: HALMET har en 4-benet I2C-grænseflade, en 3-benet 1-Wire-grænseflade og 13 tilgængelige almene ind- og udgange (GPIO). + +- **WiFi og Bluetooth**: HALMET har et indbygget ESP32-WROOM-32E-modul med WiFi og Bluetooth. De understøtter både tilslutning til eksisterende WiFi-netværk og oprettelse af et WiFi-adgangspunkt, så du kan forbinde dig direkte til kortet. + +- **ESP32-WROOM-32E med 16 MB flashhukommelse**: ESP32-WROOM-32E-modulet giver rigelig regnekraft og hukommelse til selv de mest krævende anvendelser. De 16 MB flashhukommelse gør det muligt at gemme store datamængder lokalt. + +- **Bredt indgangsspændingsområde**: HALMET kan uden videre forsynes fra de 12 V- eller 24 V-anlæg, der normalt findes i køretøjer og både. HALMET tåler indgangsspændinger mellem 5 V og 32 V. + +HALMET er åben hardware og udgives under licensen Creative Commons Attribution-ShareAlike 4.0 International. + +## Anskaffelse af hardwaren + +Du kan købe HALMET-kort hos [Hat Labs Oy](https://shop.hatlabs.fi). Alle designfiler er desuden tilgængelige i [GitHub-repositoriet med HALMET-hardwaren](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/da/revisions/index.md b/docs/da/revisions/index.md new file mode 100644 index 0000000..0126ba9 --- /dev/null +++ b/docs/da/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Hardwareversioner +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Hardwareversioner + +## Introduktion + +Denne side beskriver kortets forskellige versioner og indeholder links til kredsløbsdiagrammerne. Hele historikken for designfilerne findes i [GitHub-repositoriet HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Version 1.0.0 + +Første offentliggjorte version. + +Kredsløbsdiagram: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Version 1.0.1 + +Rettelser og forbedringer af silketrykket. 3V3- og GND-loddeflader er tilføjet på det adskilte område. + +Kredsløbsdiagram: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/da/software/index.md b/docs/da/software/index.md new file mode 100644 index 0000000..b6bfd25 --- /dev/null +++ b/docs/da/software/index.md @@ -0,0 +1,16 @@ +--- +title: Software +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Software + +## Introduktion + +HALMET er et udviklingskort og leveres uden forinstalleret software. Du skal selv installere den software, du vil bruge. Det er ikke svært, men det anbefales, at du har lidt erfaring med mikrocontrollerkort som Arduino eller ESP32 Devkit. + +Eksempelfirmware til HALMET findes i [GitHub-repositoriet HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Bemærk, at support til spørgsmål om softwareudvikling kun gives gennem [Hat Labs' diskussionsforum](https://github.com/hatlabs/discussions/discussions). + +Flere vejledninger følger snart. diff --git a/docs/da/tutorials/index.md b/docs/da/tutorials/index.md new file mode 100644 index 0000000..c6708a7 --- /dev/null +++ b/docs/da/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Vejledninger og eksempelprojekter +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +Vejledninger og eksempelprojekter til HALMET bliver vist på denne side. diff --git a/docs/da/usage/index.md b/docs/da/usage/index.md new file mode 100644 index 0000000..b6edb44 --- /dev/null +++ b/docs/da/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Brug +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Brug + +## Almindelige anvendelser + +Dette afsnit indeholder praktiske oplysninger om aflæsning af forskellige typer sensorer og om at forbinde HALMET til andre enheder. + +### Opsætning af software + +HALMET er et udviklingskort, og der er ingen software installeret på forhånd. +Du skal selv installere den software, du vil bruge. Det er ikke svært, men det anbefales, at du har lidt erfaring med mikrocontrollerkort som Arduino eller ESP32 Devkit. + +HALMET-dokumentationen forudsætter, at du bruger [HALMETs eksempelfirmware](https://github.com/hatlabs/HALMET-example-firmware). Denne firmware bygger på [SensESP](https://signalk.org/SensESP/)-frameworket og giver forholdsvis enkel adgang til kortets funktioner. + +[SensESPs introduktionsvejledning](https://signalk.org/SensESP/pages/getting_started/) indeholder detaljerede instruktioner til opsætning af det udviklingsmiljø, der skal bruges til at kompilere og installere firmwaren. Instruktionerne er skrevet til almindelige ESP32-enheder, men de gælder også for HALMET. Brug blot [HALMETs eksempelfirmware](https://github.com/hatlabs/HALMET-example-firmware) i stedet for SensESPs projektskabelon. + +Bemærk, at selvom SensESP-dokumentationen forudsætter brug af Signal K, kan HALMET også fint bruges som en selvstændig NMEA 2000-enhed. + +Hvis du helst vil undgå SensESP, kan du også skrive din egen firmware med Arduino IDE eller ESP-IDF. Til mange formål er ESPHome også et udmærket valg. + +**BEMÆRK:** Anvendelsen af GPIO-benene på HALMET afviger en smule fra benforbindelserne på både ESP32 Devkit og SH-ESP32. Hvis du tilpasser anden software end HALMETs eksempelfirmware, skal du kontrollere benforbindelserne en ekstra gang. Se [GPIO-oversigten](../hardware/index.md#gpio-oversigt) for flere oplysninger. + +### Brug af de digitale indgange + +HALMET har fire digitale indgange. Indgangene kan bruges til at læse digitale alarmsignaler eller som tællere. Dette afsnit beskriver, hvordan indgangene bruges i forskellige almindelige situationer. Vejledningen forudsætter, at du bruger HALMETs eksempelfirmware. + +De digitale indgange D1–D4 er forbundet til henholdsvis GPIO-ben 23, 25, 27 og 26. Indgangene tåler spændinger mellem −32 V og +32 V. Tærskelspændingen for at registrere et højt signal er cirka 1,55 V, med en hysterese på cirka 0,7 V. + +### Tilslutning til digitale alarmer + +Dette afsnit beskriver, hvordan HALMET tilsluttes forskellige til/fra-signaler som for eksempel motor- eller lænsealarmer. + +#### Opsætning af hardware + +Til/fra-signaler som motor- eller lænsealarmer kan normalt tilsluttes HALMETs digitale indgange direkte. Afhængigt af signaltypen kan en pull-up eller pull-down være nødvendig. + +På figuren nedenfor er der i eksempel (a) allerede en glødepære i kredsløbet. Når kontakten er åben, trækker pæren spændingen på D1 ned. Der er ikke brug for en ekstra pull-down.[^1] I eksempel (b) er der derimod ingen anden belastning i kredsløbet. Er kontakten åben, bliver spændingen på D2 flydende, og indgangen bliver tilfældigt enten høj eller lav. I det tilfælde skal den indbyggede pull-down-modstand aktiveres ved at kortslutte loddejumperen på bagsiden af kortet. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Digitale indgange i forskellige situationer. (a) Der er allerede en lampe i kredsløbet. (b) Ingen anden belastning i kredsløbet; kontakten trækker signalet højt, når den sluttes. (c) Kontakten trækker signalet lavt, når den sluttes.
+
+ +[^1]: Hvis panelets lamper er lavet med lysdioder, er spændingsfaldet over lysdioderne måske ikke stort nok til at trække spændingen tilstrækkeligt langt ned. I så fald skal pull-down-modstanden aktiveres. + +
+![](solder_jumpers.jpg){ width="60%" } +
Loddejumperne på bagsiden af kortet kan lukkes, så de indbyggede pull-up- eller pull-down-modstande aktiveres.
+
+ +På samme måde kan det være nødvendigt at aktivere den indbyggede pull-up, hvis kontakten trækker signalet lavt, når den sluttes, som i eksempel (c). + +Endelig gælder det modsatte, hvis alarmkontakterne er normalt sluttede. Når kontakten åbner, bliver indgangsspændingen trukket op eller ned afhængigt af kredsløbet. Også her kan det være nødvendigt at aktivere den indbyggede pull-up eller pull-down. + +#### Opsætning af software + +HALMETs eksempelfirmware indeholder hjælpemetoden `ConnectAlarmSender()` til at konfigurere og tilslutte digitale indgange. Se `main.cpp` fra linje 177 og frem. Både aktivt høje og aktivt lave signaler understøttes. + +### Digitale indgange som tællere + +HALMETs digitale indgange kan også bruges som tællere. Det er nyttigt til for eksempel at tælle motorens omdrejninger eller pulser fra en kædetæller. + +#### Opsætning af hardware + +Sådanne givere drives normalt aktivt i begge retninger, så der er ikke brug for pull-up eller pull-down. Hvis du forbinder HALMET til en udgang med lav impedans som for eksempel generatorens W-klemme, er det en god idé at montere en ledningssikring, så ledningen beskyttes mod kortslutninger som følge af skamfiling eller andre skader. Ellers kan giveren tilsluttes direkte til den digitale indgang. + +Hvis pulskilden støjer meget, så omdrejningstallet aflæses forkert, kan et lavpasfilter aktiveres ved at kortslutte LP-loddejumperen på bagsiden af kortet. Lavpasfilteret har en knækfrekvens på cirka 2,3 kHz, hvilket bør passe til anvendelser som indgange fra generatorens W-klemme. + +#### Opsætning af software + +HALMETs eksempelfirmware indeholder en pulstæller, der kan aktiveres på en enkelt eller på alle de digitale indgange. Se eksempelkonfigurationen i `main.cpp` fra linje 214 og frem. + +### Brug af de analoge indgange + +HALMET har fire analoge indgange, som kan bruges enten til passiv spændingsmåling eller til aktiv modstandsmåling. Dette afsnit beskriver, hvordan indgangene bruges i forskellige almindelige situationer. + +#### Opsætning af hardware + +De analoge indgange A1–A4 er forbundet til en analog-digital-omsætter (ADC) af typen ADS1115. ADS1115 har 16-bits opløsning og en maksimal samplingfrekvens på 860 målinger pr. sekund. HALMETs analoge indgange har dog et kraftigt lavpasfilter med en knækfrekvens på cirka 160 Hz. Det er stadig rigeligt til at måle udgangssignalet fra fysiske sensorer som tankniveausensorer eller trykgivere på motoren. + +På figuren nedenfor viser eksempel (a) et eksisterende instrument i motorpanelet forbundet til en modstandsgiver. Instrumenter i motorpaneler er som regel enten termostatiske eller magnetiske. I begge tilfælde virker instrumentet og giveren som en spændingsdeler, og spændingen over giveren er proportional med den målte størrelse. Denne spænding kan måles med HALMETs analoge indgange, uden at det forstyrrer det oprindelige instruments funktion. På grund af spændingsdeleren følger spændingen måske ikke lineært den målte størrelse, men det kan kompenseres i softwaren. + +
+![](analog_input.svg){ width="60%" } +
Tilslutning af analoge indgange med og uden et eksisterende instrument. (a) Er der allerede et instrument, skal HALMET bruges i tilstanden passiv spændingsmåling. (b) Er der ingen anden enhed, skal HALMET bruges i tilstanden aktiv modstandsmåling.
+
+ + +Eksempel (b) viser et tilfælde uden et eksisterende instrument. Giveren er forbundet direkte til HALMETs analoge indgang. Her skal HALMET selv levere excitationsspændingen (den spænding, der driver giveren). HALMET udfører modstandsmålingen med en konstantstrømkilde på 10 mA. De 10 mA giver en spændingsforskel på 1 volt over en modstand på 100 ohm, hvilket svarer til en største målbar modstand på cirka 300 ohm. Konstantstrømkilden aktiveres ved at sætte en jumper på benparret i CCS-jumperstiklisten (konstantstrømkilde). Se figuren nedenfor. + +
+![](ccs_jumpers.jpg){ width="60%" } +
Figuren viser konstantstrømkilden aktiveret for de analoge indgange A2 og A4.
+
diff --git a/docs/de/errata/index.md b/docs/de/errata/index.md new file mode 100644 index 0000000..ae9f147 --- /dev/null +++ b/docs/de/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Bekannte Fehler +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Bekannte Fehler + +Diese Seite listet alle bekannten Hardwarefehler der verschiedenen HALMET-Revisionen auf. + +## Version 1.0.0 + +Die Digitaleingänge 3 und 4 sind im Bestückungsdruck auf der Unterseite vertauscht. Die richtige Pinbelegung lautet: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/de/getting-started/index.md b/docs/de/getting-started/index.md new file mode 100644 index 0000000..ee4955f --- /dev/null +++ b/docs/de/getting-started/index.md @@ -0,0 +1,73 @@ +--- +title: Erste Schritte +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Erste Schritte + +## Hardware-Montage + +Damit sich die Anschlüsse in kleinen Gehäusen flexibler platzieren lassen, werden HALMET-Platinen ohne montierte 1-Wire- und GPIO-Stiftleisten ausgeliefert. Wenn Sie eine dieser Schnittstellen nutzen möchten, müssen Sie die Stiftleiste selbst auf die Platine löten. + +Eine Anleitung zum Auflöten von Stiftleisten finden Sie in der [Montageanleitung](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) des SH-ESP32. + +## Stromversorgung der Platine + +HALMET wird über den NMEA-2000-Anschluss mit Spannung versorgt. Wenn Sie HALMET an ein NMEA-2000-Netzwerk anschließen, können Sie die Platine direkt aus dem Netzwerk versorgen. Schließen Sie in diesem Fall die NMEA-2000-Adern wie in der folgenden Abbildung gezeigt an den 4-poligen steckbaren Klemmenblock an. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Schließen Sie die NMEA-2000-Adern wie gezeigt an den Klemmenblock an.
+
+ +Wenn Sie HALMET nicht an ein NMEA-2000-Netzwerk anschließen, verwenden Sie denselben Klemmenblock, belegen aber nur die Positionen `-` und `+`. Als Spannungsquelle eignet sich jede Quelle von 5–32 V. Die typische Stromaufnahme der Platine beträgt bei aktivem WLAN 0,07 A bei 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Schließen Sie die Versorgungsadern wie gezeigt an den Klemmenblock an.
+
+ +## Gehäuse + +Für den Einsatz an Bord sollte HALMET immer in ein wasserdichtes Gehäuse eingebaut werden. +Die Platine ist passend für das [SH-ESP32-Gehäuse](https://shop.hatlabs.fi/products/sh-esp32-enclosure) ausgelegt. Unten sehen Sie ein Beispiel für eine im Gehäuse montierte HALMET-Platine. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET im SH-ESP32-Gehäuse montiert.
+
+ +Das SH-ESP32-Gehäuse bietet nur begrenzt Platz für Anschlüsse. +Jede der Längsseiten nimmt praktisch nur 2–3 Einbausteckverbinder auf. +Wenn Sie mehr als einige wenige Eingänge anschließen möchten, empfiehlt sich ein größeres Gehäuse. +Das unten gezeigte [kompakte SH-RPi-Gehäuse](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) von Hat Labs bietet zum Beispiel bereits reichlich Raum für Anschlüsse. + +
+![](medium_enclosure.jpg){ width="50%" } +
Das kompakte SH-RPi-Gehäuse bietet mehr Platz für die Anordnung der Einbausteckverbinder.
+
+ + +Weitere geeignete wasserdichte Gehäuse finden sich problemlos auf jedem Online-Marktplatz. Auch größere Abzweigdosen für den Außenbereich eignen sich für diesen Zweck. + +### Bohrungen für Einbausteckverbinder + +Die Gehäuse sind in der Regel nicht vorgebohrt. Verwenden Sie zum Bohren immer einen Kegel- oder Stufenbohrer (den, der wie ein kleiner Weihnachtsbaum aus Metall aussieht). Normale Metallbohrer greifen leicht zu stark und können die Gehäusewand aufreißen. + +Lassen Sie bei der Planung der Bohrungen und Anschlusspositionen genügend Platz zum Festziehen der Überwurfmuttern und für den Körper des Steckverbinders. Wenn Sie das Gehäuse zur Wandmontage vorsehen, sollten die Anschlüsse nach unten zeigen, damit möglichst wenig Wasser eindringen kann. + +Geeignete Bohrungsdurchmesser für die verschiedenen Anschlüsse: + +- PG7-Kabelverschraubung und M12-Einbausteckverbinder (NMEA 2000): 12,5 mm oder 1/2 Zoll +- SP13-Einbausteckverbinder (blau-schwarze Kunststoffsteckverbinder): 13 mm +- PG9-Kabelverschraubung: 16 mm oder 5/8 Zoll + +Kabeltüllen aus Gummi oder Silikon erlauben deutlich höhere Kabeldichten als Einbausteckverbinder oder Kabelverschraubungen. Sie sind allerdings nicht so wasserdicht wie Einbausteckverbinder oder Kabelverschraubungen. Zudem erfordern sie eine dauerhafte Kabelbefestigung, was die Wartung des Systems erschweren kann. + +TODO: Bild einer Kabeltülle ergänzen. + +### Löten der Einbausteckverbinder + +Verwenden Sie beim Anlöten der internen Adern an die Einbausteckverbinder immer Schrumpfschlauch auf den einzelnen Adern. +Denken Sie daran, den Schrumpfschlauch _vor_ dem Löten auf die Ader zu schieben … +Meist können Sie zuerst Lot in den Lötbecher des Kontakts geben und dann das Lot erneut aufschmelzen und die Ader einführen. diff --git a/docs/de/hardware/index.md b/docs/de/hardware/index.md new file mode 100644 index 0000000..2597970 --- /dev/null +++ b/docs/de/hardware/index.md @@ -0,0 +1,240 @@ +--- +title: Hardware-Beschreibung +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hardware + +## ESP32 im Überblick + +HALMET basiert auf dem leistungsfähigen Mikrocontroller-Modul ESP32-WROOM-32E. Der ESP32 ist ein Dual-Core-Mikrocontroller mit integriertem WLAN und Bluetooth. Wegen seines niedrigen Preises, seiner guten Peripherieausstattung und seiner einfachen Handhabung ist der ESP32 eine beliebte Wahl für IoT-Anwendungen. + +## Funktionsblöcke der Platine + +Im Folgenden werden die verschiedenen Funktionsblöcke der Platine beschrieben. + +
+![](HALMET-func.jpg){ width="60%" } +
Funktionsblöcke des HALMET.
+
+ +1. NMEA 2000 sowie Spannungseingang und Schutzbeschaltung. Der NMEA-2000-Anschluss + verfügt über folgende Schutzelemente: + - Selbstrückstellende Sicherung mit 500 mA + - Verpolungsschutzdiode + - TVS-Dioden zum Überspannungs- und ESD-Schutz + - Zweistufige Störfilterung + +2. Stromversorgung. Ein Schaltnetzteil mit einem maximalen Ausgangsstrom von 2 A. + +3. CAN-Transceiver für NMEA 2000. RX- und TX-LEDs zeigen die CAN-Bus-Aktivität + optisch an. + +4. I2C- und 1-Wire-Schnittstellen zum Anschluss weiterer Sensoren. + +5. Bedienelemente. Ein Reset-Taster, ein Taster für den Boot-Modus, der auch + allgemein nutzbar ist, eine rote Betriebs-LED und eine blaue + benutzerprogrammierbare LED. + +6. USB-2.0-Schnittstelle zum Programmieren und Debuggen. + +7. ESP32-WROOM-32E-Modul mit integriertem WLAN und Bluetooth. Das Modul auf der + HALMET-Platine enthält 16 MB Flash-Speicher. + +8. Schaltung zur galvanischen Trennung der Digital- und Analogeingänge. + +9. Analogeingänge. Die Platine hat vier Analogeingänge mit 16-Bit-Auflösung und + einer maximalen Eingangsspannung von 33 V. Jeder Eingang verfügt über einen + Unter- und Überspannungsschutz sowie eine Tiefpassfilterung mit einer + Grenzfrequenz von 160 Hz, um Störungen bei der Messung zu verringern. + + Die Analogeingänge besitzen eine optionale Konstantstromquelle mit 10 mA für + die aktive Widerstandsmessung. Die Konstantstromquelle lässt sich über die + CCS-Jumper-Stiftleisten aktivieren. + + Im Widerstandsmessbetrieb beträgt der maximal messbare Widerstand 300 Ω. + +10. Digitaleingänge. HALMET hat vier Digitaleingänge mit einer maximalen + Eingangsspannung von ±32 V. Die Eingänge verfügen über einen Schmitt-Trigger, + der die Störfestigkeit verbessert. + + +## Galvanische Trennung + +Die Platine ist zwischen den Digital- und Analogeingängen und dem +ESP32-Mikrocontroller galvanisch getrennt. Die Trennung wird durch +Digitalisolatoren für I2C beziehungsweise die vier Digitaleingänge sowie durch +einen galvanisch getrennten DC/DC-Wandler zur Versorgung des getrennten Bereichs +erreicht. + +Dank dieser Trennung kann die Platine ohne die Gefahr von Masseschleifen aus dem +NMEA-2000-Netzwerk versorgt werden. Die Trennung schützt außerdem vor +Spannungsspitzen und Störungen an den Eingängen. + +
+![](HALMET-isolation.jpg){ width="60%" } +
Galvanische Trennstelle des HALMET. Die Eingangsanschlüsse sind vom Rest der Platine +getrennt, das heißt, sie haben keine gemeinsame Masse mit dem übrigen Teil der Platine.
+
+ +## Anschlüsse + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
Anschlüsse des HALMET, Oberseite.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
Anschlüsse des HALMET, Unterseite.
+
+ +
+
+ +### Anschlüsse auf der Oberseite + +1. NMEA-2000-Anschluss. Der Anschluss ist ein 4-poliger steckbarer Klemmenblock, + kompatibel zu Phoenix MC 3.81. Über ihn wird die Platine an ein + NMEA-2000-Netzwerk angeschlossen und mit Spannung versorgt. + +2. 1-Wire-Stiftleiste. An die 1-Wire-Stiftleiste lassen sich 1-Wire-Sensoren + anschließen. Es handelt sich um eine 3-polige Stiftleiste mit 2,54 mm + Rastermaß. Sie ist ab Werk nicht bestückt, weil sie die Platzierung der + Einbausteckverbinder im Gehäuse behindern kann. + +3. I2C-Stiftleiste. An die I2C-Stiftleiste lassen sich I2C-Sensoren anschließen. + Es handelt sich um eine 4-polige Stiftleiste mit 2,54 mm Rastermaß. + +4. Micro-USB-Anschluss. Der Anschluss dient zum Programmieren und Debuggen der + Platine. + +5. Unbestückte Lötpads für die Signale Reset (EN) und Boot (IO0). + +6. GPIO-Stiftleiste. Die GPIO-Stiftleiste ist zweireihig mit 2×10 Pins und + 2,54 mm Rastermaß. Sie führt die verfügbaren GPIO-Pins des ESP32 heraus und + lässt sich auch als JTAG-Stiftleiste nutzen. + +7. Stiftleiste für die Versorgung des getrennten Bereichs. Über sie können + externe Geräte aus 3V3 und GND des getrennten Bereichs versorgt werden. + +8. Kontakte der Jumper-Stiftleiste für die Konstantstromquelle (CCS) der + Analogeingänge. Die Konstantstromquelle wird aktiviert, indem die + Jumper-Kontakte gebrückt werden. + +9. Analogeingangs-Anschlüsse. Die Anschlüsse sind 2-polige steckbare + Klemmenblöcke, kompatibel zu Phoenix MC 3.81. Über sie werden analoge + Sensoren an die Platine angeschlossen. + +10. Digitaleingangs-Anschlüsse. Die Anschlüsse sind 2-polige steckbare + Klemmenblöcke, kompatibel zu Phoenix MC 3.81. Über sie werden digitale + Sensoren an die Platine angeschlossen. + +### Anschlüsse auf der Unterseite + +11. Lötbrücke für den CAN-Abschlusswiderstand. Durch Schließen der Lötbrücke wird + der Abschlusswiderstand von 120 Ω für den CAN-Bus aktiviert. Verwenden Sie + den Abschlusswiderstand nicht in NMEA-2000-Netzwerken. + +12. Lötbrücke für den Tiefpassfilter. Durch Schließen der Lötbrücke wird der + Tiefpassfilter am jeweiligen Analogeingang aktiviert. Der Filter hat eine + Grenzfrequenz von 2,3 kHz. Er lässt sich zum Beispiel nutzen, um Störungen + im Signal eines Drehzahlmessers zu verringern. + +13. Lötbrücke für den Pull-down-Widerstand. Durch Schließen der Lötbrücke wird am + jeweiligen Digitaleingang ein Pull-down-Widerstand von 100 kΩ aktiviert. Mit + dem Pull-down-Widerstand lässt sich ein Schließer (normally open) auslesen, + der den Eingang im geschlossenen Zustand auf High zieht. + +14. Lötbrücke für den Pull-up-Widerstand. Durch Schließen der Lötbrücke wird am + jeweiligen Digitaleingang ein Pull-up-Widerstand von 100 kΩ aktiviert. Mit + dem Pull-up-Widerstand lässt sich ein Öffner (normally closed) auslesen, der + den Eingang im geschlossenen Zustand auf Low zieht. + +15. Lötbrücken zur Auswahl der I2C-Adresse des ADS1115. Durch Schließen der + Lötbrücken wird die I2C-Adresse des ADS1115-ADC ausgewählt. Sie dienen dazu, + Adresskonflikte zu vermeiden, wenn mehrere ADS1115-ADCs am selben I2C-Bus + angeschlossen sind. Die Lötpads lassen sich außerdem nutzen, um weitere + I2C-Geräte an den getrennten Bereich der Platine anzuschließen. + +### GPIO-Referenz + +HALMET belegt einen Teil der GPIO-Pins für die Eingangsperipherie. Die +verfügbaren GPIO-Pins sind auf die zweireihige GPIO-Stiftleiste mit 2×10 Pins +herausgeführt. Die folgende Tabelle listet die GPIO-Pins und ihre Funktionen auf. + +| GPIO | Funktion | Anmerkungen | +| ------: | :---------- | :----------------------------------------------------- | +| 0 | Boot-Taster | Wechselt in den Bootloader, wenn auf Low gezogen | +| 1 | TXD0 | Datenübertragung zum USB | +| 2 | LED | Rote LED auf der Platine | +| 3 | RXD0 | Datenempfang vom USB | +| 4 | 1-Wire DQ | 1-Wire-Datenleitung | +| 5 | - | Auf der GPIO-Stiftleiste verfügbar | +| 12 | - / TDI | Auf der GPIO-Stiftleiste verfügbar. Optional: JTAG TDI | +| 13 | - / TCK | Auf der GPIO-Stiftleiste verfügbar. Optional: JTAG TCK | +| 14 | - / TMS | Auf der GPIO-Stiftleiste verfügbar. Optional: JTAG TMS | +| 15 | - / TDO | Auf der GPIO-Stiftleiste verfügbar. Optional: JTAG TDO | +| 16 | - | Auf der GPIO-Stiftleiste verfügbar | +| 17 | - | Auf der GPIO-Stiftleiste verfügbar | +| 18 | CAN RX | Empfang von NMEA 2000 | +| 19 | CAN TX | Senden an NMEA 2000 | +| 21 | I2C SDA | I2C-Datenleitung. Für die Analogeingänge genutzt | +| 22 | I2C SCL | I2C-Taktleitung. Für die Analogeingänge genutzt | +| 23 | DI1 | Digitaleingang 1 | +| 25 | DI2 | Digitaleingang 2 | +| 27 | DI3 | Digitaleingang 3 | +| 26 | DI4 | Digitaleingang 4 | +| 32 | - | Auf der GPIO-Stiftleiste verfügbar | +| 33 | - | Auf der GPIO-Stiftleiste verfügbar | +| 34 | - | Auf der GPIO-Stiftleiste verfügbar | +| 35 | - | Auf der GPIO-Stiftleiste verfügbar | +| 36 (VP) | Nur Eingang | Auf der GPIO-Stiftleiste verfügbar | +| 39 (VN) | Nur Eingang | Auf der GPIO-Stiftleiste verfügbar | + + +## Stromversorgung + +Der zulässige Eingangsspannungsbereich der Platine beträgt 5–32 V. Die typische +Stromaufnahme liegt bei 90 mA bei 12 V mit aktivem WLAN-Modul (entspricht 1,1 W). + +## NMEA 2000 + +NMEA 2000 ist ein weit verbreiteter Kommunikationsstandard, mit dem Sensoren, Bedien- und Anzeigegeräte auf Booten und Schiffen verbunden werden. Er basiert auf dem Controller Area Network (CAN-Bus), einem Fahrzeugbus-Standard, der Geräten die Kommunikation untereinander ohne Hostrechner ermöglicht. + +Die Platine erfüllt den NMEA-2000-Standard, solange keiner der nicht getrennten +Anschlüsse mit anderen massebezogenen Geräten verbunden ist. Ein +1-Wire-Temperatursensor mit langem Kabel lässt sich zum Beispiel verwenden, weil +er keine gemeinsame Masse mit anderen Geräten hat. Der Anschluss eines +I2C-Analog-Digital-Wandlers an den nicht getrennten I2C-Anschluss würde die +NMEA-2000-Konformität dagegen aufheben. + +TODO: NMEA-2000-GPIO-Pinbelegung + +## Status-LEDs + +Auf der HALMET-Platine befinden sich zwei Taster und zwei LEDs. Die beiden Taster sind mit Reset und Boot beschriftet. Der Reset-Taster startet die Platine neu, indem er den Enable-Pin des ESP32 auf Low zieht. Der Boot-Taster ist mit GPIO0 verbunden und lässt sich während des Gerätestarts nutzen, um das Modul in den Download-Modus zu zwingen. Ansonsten kann er als normaler Tastereingang verwendet werden. + +Die beiden LEDs sind nicht ausdrücklich beschriftet. Die rote LED leuchtet, sobald auf der Platine 3,3 V Versorgungsspannung anliegen. Die blaue LED ist mit GPIO2 verbunden (dem Pin, der auf ESP32-Entwicklungsboards üblicherweise für eine LED genutzt wird). Sie kann von Benutzerprogrammen angesteuert werden, um den Zustand des Geräts anzuzeigen. + +## 1-Wire + +1-Wire ist ein Bussystem für die Gerätekommunikation, das von Dallas Semiconductor entwickelt wurde; das Unternehmen wurde inzwischen von Maxim Integrated Products übernommen. Obwohl 1-Wire ein langsames Protokoll ist und nur Geschwindigkeiten bis 16,3 kbit/s unterstützt, lässt es sich sehr einfach umsetzen und funktioniert auch über große Entfernungen. Es wird häufig für Temperatursensoren und ähnliche einfache Sensorbausteine verwendet. + +Die 1-Wire-Umsetzung des HALMET verfügt über eine ESD- und HF-Störungsfilterung sowie über eine Tiefpassfilterung, um die Zuverlässigkeit des Netzwerks zu erhöhen. + +Beachten Sie, dass der 1-Wire-Datenpin (Beschriftung „DQ“) physisch auf GPIO4 gelegt ist; verwenden Sie in Ihrem Programm daher GPIO4 für alle 1-Wire-Daten. + +## I2C + +I2C (Inter-Integrated Circuit) ist ein sehr verbreiteter synchroner serieller Kommunikationsbus, der häufig zur Anbindung unterschiedlichster ICs verwendet wird. Er nutzt zusätzlich zu Versorgungsspannung und Masse zwei Datenleitungen. + +HALMET nutzt I2C intern für den Analog-Digital-Wandler ADS1115. Der I2C-Bus ist außerdem auf eine 4-polige Stiftleiste herausgeführt, um weitere I2C-Geräte anschließen zu können. + +Der I2C-Bus ist mit GPIO21 (SDA) und GPIO22 (SCL) des ESP32 verbunden. Diese Pins sind die Standard-I2C-Pins in der Arduino-ESP32-Umgebung, unterscheiden sich aber von den Standard-Pins des SH-ESP32. diff --git a/docs/de/index.md b/docs/de/index.md new file mode 100644 index 0000000..8603d59 --- /dev/null +++ b/docs/de/index.md @@ -0,0 +1,35 @@ +--- +title: Einführung +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Einführung + +HALMET, das Hat Labs Marine Engine & Tank interface, ist ein Entwicklungsboard zum Anschluss von Motor- und Tanksensoren auf Booten und in anderen Fahrzeugen. Damit lassen sich digitale und analoge Sensoren auslesen sowie Verbindungen zu anderen Geräten über NMEA 2000, WLAN, Bluetooth, I2C, 1-Wire oder GPIO herstellen. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Abbildung des HALMET
+
+ +## Wichtigste Merkmale + +- **Vier Digitaleingänge**: HALMET besitzt vier Digitaleingänge zum Lesen digitaler Alarmsignale oder zur Verwendung als Zähler. Die Eingänge vertragen Spannungen zwischen −32 V und +32 V. Mit den Digitaleingängen lassen sich sowohl Signalpegel als auch zeitlich veränderliche Signale wie Motordrehzahl, Kraftstoffdurchfluss oder Impulse eines Kettenzählers erfassen. + +- **Vier Analogeingänge**: HALMET besitzt vier Analogeingänge zum Auslesen analoger Sensoren. Die Eingänge vertragen Spannungen zwischen −32 V und +32 V bei einem Messbereich von 0 bis 33 V. Sie sind mit einem ADS1115-Analog-Digital-Wandler mit 16-Bit-Auflösung verbunden. Die Analogeingänge eignen sich sowohl für passive Spannungsmessungen als auch für aktive Widerstandsmessungen. + +- **NMEA-2000-kompatibel**: HALMET ist vollständig kompatibel mit dem NMEA-2000-Standard. Über die integrierte NMEA-2000-Schnittstelle lässt sich die Platine an ein NMEA-2000-Netzwerk anschließen. + +- **I2C-, 1-Wire- und GPIO-Schnittstellen**: HALMET verfügt über eine 4-polige I2C-Schnittstelle, eine 3-polige 1-Wire-Schnittstelle und 13 frei verfügbare Allzweck-Ein-/Ausgänge (GPIOs). + +- **WLAN- und Bluetooth-Konnektivität**: HALMET besitzt ein integriertes ESP32-WROOM-32E-Modul mit WLAN und Bluetooth. Damit lässt sich die Platine sowohl mit vorhandenen WLAN-Netzwerken verbinden als auch ein eigener WLAN-Access-Point für den direkten Zugriff auf die Platine aufspannen. + +- **ESP32-WROOM-32E mit 16 MB Flash**: Das ESP32-WROOM-32E-Modul bietet reichlich Rechenleistung und Speicher auch für anspruchsvollste Anwendungen. Der 16 MB große Flash-Speicher erlaubt es, große Datenmengen lokal zu speichern. + +- **Weiter Eingangsspannungsbereich**: HALMET kann sicher aus dem in Fahrzeugen und Booten üblichen 12-V- oder 24-V-Bordnetz versorgt werden. HALMET verträgt Eingangsspannungen zwischen 5 V und 32 V. + +HALMET ist Open Hardware (offene Hardware) und steht unter der Lizenz Creative Commons Attribution-ShareAlike 4.0 International. + +## Hardware beziehen + +HALMET-Platinen können Sie bei [Hat Labs Oy](https://shop.hatlabs.fi) kaufen. Alle Designdateien sind außerdem im [GitHub-Repository der HALMET-Hardware](https://github.com/hatlabs/halmet-hardware/) verfügbar. diff --git a/docs/de/revisions/index.md b/docs/de/revisions/index.md new file mode 100644 index 0000000..1494b59 --- /dev/null +++ b/docs/de/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Hardware-Revisionen +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Hardware-Revisionen + +## Einführung + +Diese Seite dokumentiert die verschiedenen Platinenrevisionen und verweist auf die zugehörigen Schaltpläne. Die vollständige Historie der Designdateien ist im [GitHub-Repository HALMET-hardware](https://github.com/hatlabs/HALMET-hardware) verfügbar. + + +## Version 1.0.0 + +Erste veröffentlichte Version. + +Schaltplan: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Version 1.0.1 + +Korrekturen und Verbesserungen am Bestückungsdruck. 3V3- und GND-Lötpads im galvanisch getrennten Bereich ergänzt. + +Schaltplan: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/de/software/index.md b/docs/de/software/index.md new file mode 100644 index 0000000..b80464c --- /dev/null +++ b/docs/de/software/index.md @@ -0,0 +1,16 @@ +--- +title: Software +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Software + +## Einführung + +Als Entwicklungsboard wird HALMET ohne vorinstallierte Software ausgeliefert. Passende Software müssen Sie selbst installieren. Das ist nicht schwierig, etwas Vorerfahrung mit Mikrocontroller-Boards wie Arduino oder ESP32 Devkits ist aber empfehlenswert. + +Eine Beispiel-Firmware für HALMET finden Sie im [GitHub-Repository HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Bitte beachten Sie, dass Unterstützung bei Fragen zur Softwareentwicklung ausschließlich über das [Hat-Labs-Diskussionsforum](https://github.com/hatlabs/discussions/discussions) angeboten wird. + +Weitere Anleitungen folgen in Kürze. diff --git a/docs/de/tutorials/index.md b/docs/de/tutorials/index.md new file mode 100644 index 0000000..5a38e31 --- /dev/null +++ b/docs/de/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Tutorials und Beispielprojekte +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +Auf dieser Seite werden Tutorials und Beispielprojekte für HALMET aufgeführt. diff --git a/docs/de/usage/index.md b/docs/de/usage/index.md new file mode 100644 index 0000000..2532c7f --- /dev/null +++ b/docs/de/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Verwendung +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Verwendung + +## Häufige Anwendungsfälle + +Dieser Abschnitt enthält praktische Hinweise zum Auslesen verschiedener Sensortypen und zum Anschluss von HALMET an andere Geräte. + +### Software-Einrichtung + +HALMET ist ein Entwicklungsboard und wird ohne vorinstallierte Software ausgeliefert. +Passende Software müssen Sie selbst installieren. Das ist nicht schwierig, etwas Vorerfahrung mit Mikrocontroller-Boards wie Arduino oder ESP32 Devkits ist aber empfehlenswert. + +Die HALMET-Dokumentation geht von der [HALMET-Beispiel-Firmware](https://github.com/hatlabs/HALMET-example-firmware) aus. Diese Firmware basiert auf dem Framework [SensESP](https://signalk.org/SensESP/) und bietet einen recht unkomplizierten Zugriff auf die Funktionen der Platine. + +Der [SensESP-Einstiegsleitfaden](https://signalk.org/SensESP/pages/getting_started/) enthält ausführliche Anweisungen zur Einrichtung der Entwicklungsumgebung, die zum Kompilieren und Installieren der Firmware nötig ist. Die Anleitung ist für allgemeine ESP32-Geräte geschrieben, gilt aber ebenso für HALMET. Verwenden Sie lediglich die [HALMET-Beispiel-Firmware](https://github.com/hatlabs/HALMET-example-firmware) anstelle der SensESP-Projektvorlage. + +Beachten Sie, dass die SensESP-Dokumentation zwar von der Verwendung von Signal K ausgeht, HALMET aber ebenso als eigenständiges NMEA-2000-Gerät nutzbar ist. + +Wenn Sie SensESP nicht verwenden möchten, können Sie auch eine eigene Firmware mit der Arduino IDE oder ESP-IDF erstellen. Für viele Anwendungsfälle ist auch ESPHome eine sehr gute Wahl. + +**HINWEIS:** Die Belegung der GPIO-Pins auf HALMET weicht leicht von der Belegung des ESP32 Devkit und des SH-ESP32 ab. Wenn Sie andere Software als die HALMET-Beispiel-Firmware anpassen, müssen Sie die Pin-Belegung genau prüfen. Weitere Informationen finden Sie in der [GPIO-Referenz](../hardware/index.md#gpio-referenz). + +### Digitaleingänge verwenden + +HALMET besitzt vier Digitaleingänge. Diese Eingänge lassen sich zum Lesen digitaler Alarmsignale oder als Zähler verwenden. Dieser Abschnitt beschreibt die Verwendung der Eingänge in verschiedenen häufigen Anwendungsfällen. Die Anleitung geht von der HALMET-Beispiel-Firmware aus. + +Die Digitaleingänge D1–D4 sind mit den GPIO-Pins 23, 25, 27 und 26 verbunden. Die Eingänge vertragen Spannungen zwischen −32 V und +32 V. Die Schwellenspannung für die Erkennung eines High-Signals liegt bei etwa 1,55 V, die Hysterese bei etwa 0,7 V. + +### Anschluss an digitale Alarme + +Dieser Abschnitt beschreibt, wie HALMET an verschiedene Ein/Aus-Signale wie Motor- oder Bilgenalarme angeschlossen wird. + +#### Hardware-Einrichtung + +In der Regel lassen sich Ein/Aus-Signale wie Motor- oder Bilgenalarme direkt an die Digitaleingänge von HALMET anschließen. Je nach Signaltyp kann ein Pull-up oder Pull-down erforderlich sein. + +In der Abbildung unten enthält der Stromkreis in Beispiel (a) bereits eine Glühlampe. Bei geöffnetem Schalter zieht die Glühlampe die Spannung an D1 nach unten. Ein zusätzlicher Pull-down ist nicht erforderlich.[^1] In Beispiel (b) befindet sich dagegen keine weitere Last im Stromkreis. Ist der Schalter geöffnet, liegt D2 auf undefiniertem Potenzial und der Eingang wird zufällig als High oder Low gelesen. In diesem Fall muss der interne Pull-down-Widerstand aktiviert werden, indem die Lötbrücke auf der Unterseite der Platine geschlossen wird. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Digitaleingänge in verschiedenen Anwendungsfällen. (a) Bereits vorhandene Lampe im Stromkreis. (b) Keine weitere Last im Stromkreis, der Schalter zieht das Signal beim Schließen nach High. (c) Der Schalter zieht das Signal beim Schließen nach Low.
+
+ +[^1]: Sind die Paneelleuchten mit LEDs ausgeführt, reicht der Spannungsabfall über den LEDs möglicherweise nicht aus, um die Spannung weit genug nach unten zu ziehen. In diesem Fall muss der Pull-down-Widerstand aktiviert werden. + +
+![](solder_jumpers.jpg){ width="60%" } +
Die Lötbrücken auf der Unterseite der Platine lassen sich schließen, um die eingebauten Pull-up- oder Pull-down-Widerstände zu aktivieren.
+
+ +Ebenso kann der interne Pull-up erforderlich sein, wenn der Schalter das Signal beim Schließen nach Low zieht wie in Beispiel (c). + +Handelt es sich bei den Alarmschaltern schließlich um Öffner (normally closed), kehrt sich die Betrachtung um. Beim Öffnen des Schalters wird die Eingangsspannung je nach Stromkreis nach oben oder nach unten gezogen. Auch in diesem Fall kann der interne Pull-up oder Pull-down erforderlich sein. + +#### Software-Einrichtung + +Die HALMET-Beispiel-Firmware stellt die Hilfsmethode `ConnectAlarmSender()` zum Konfigurieren und Anschließen der Digitaleingänge bereit. Siehe `main.cpp` ab Zeile 177. Sowohl aktiv-High- als auch aktiv-Low-Signale werden unterstützt. + +### Digitaleingänge als Zähler + +Die Digitaleingänge von HALMET lassen sich auch als Zähler verwenden. Das ist zum Beispiel nützlich, um Motorumdrehungen oder Impulse eines Kettenzählers zu zählen. + +#### Hardware-Einrichtung + +Solche Geber werden meist in beide Richtungen aktiv getrieben, sodass weder Pull-up noch Pull-down nötig ist. Wenn Sie HALMET an einen niederohmigen Ausgang wie die W-Klemme der Lichtmaschine anschließen, empfiehlt es sich, eine Leitungssicherung einzufügen, die die Leitung vor Kurzschlüssen durch Scheuern oder andere Beschädigungen schützt. Ansonsten können Sie den Geber direkt an den Digitaleingang anschließen. + +Ist die Impulsquelle stark gestört und liefert dadurch fehlerhafte Drehzahlwerte, lässt sich ein Tiefpassfilter aktivieren, indem die LP-Lötbrücke auf der Unterseite der Platine geschlossen wird. Der Tiefpassfilter hat eine Grenzfrequenz von etwa 2,3 kHz, was für Anwendungen wie den Anschluss an die W-Klemme der Lichtmaschine geeignet sein sollte. + +#### Software-Einrichtung + +Die HALMET-Beispiel-Firmware enthält einen Impulszähler, der sich auf einzelnen oder allen Digitaleingängen aktivieren lässt. Die Beispielkonfiguration finden Sie in `main.cpp` ab Zeile 214. + +### Analogeingänge verwenden + +HALMET besitzt vier Analogeingänge, die sich entweder für passive Spannungsmessungen oder für aktive Widerstandsmessungen nutzen lassen. Dieser Abschnitt beschreibt die Verwendung der Eingänge in verschiedenen häufigen Anwendungsfällen. + +#### Hardware-Einrichtung + +Die Analogeingänge A1–A4 sind mit einem ADS1115-Analog-Digital-Wandler verbunden. Der ADS1115 hat eine 16-Bit-Auflösung und eine maximale Abtastrate von 860 Messwerten pro Sekunde. Die Analogeingänge von HALMET enthalten allerdings einen kräftigen Tiefpassfilter mit einer Grenzfrequenz von etwa 160 Hz. Das reicht für die Messung physikalischer Sensorsignale wie Tankfüllstands- oder Motordrucksensoren immer noch mehr als aus. + +In der Abbildung unten zeigt Beispiel (a) ein vorhandenes Motorinstrument, das an einen Widerstandsgeber angeschlossen ist. Motorinstrumente sind meist entweder thermostatisch oder magnetisch aufgebaut. In beiden Fällen bilden Anzeigeinstrument und Geber einen Spannungsteiler, und die Spannung über dem Geber ist proportional zur gemessenen Größe. Diese Spannung lässt sich mit den Analogeingängen von HALMET messen, ohne die Funktion des ursprünglichen Anzeigeinstruments zu beeinträchtigen. Wegen des Spannungsteilers korreliert die Spannung möglicherweise nicht linear mit der gemessenen Größe; das lässt sich jedoch in der Software kompensieren. + +
+![](analog_input.svg){ width="60%" } +
Anschluss der Analogeingänge mit und ohne vorhandenes Anzeigeinstrument. (a) Bei einem vorhandenen Anzeigeinstrument verwenden Sie HALMET in der passiven Spannungsmessung. (b) Ist kein weiteres Gerät vorhanden, verwenden Sie HALMET in der aktiven Widerstandsmessung.
+
+ + +Beispiel (b) zeigt den Fall ohne vorhandenes Anzeigeinstrument. Der Geber ist direkt an den Analogeingang von HALMET angeschlossen. In diesem Fall muss HALMET die Speisespannung für den Geber bereitstellen. HALMET führt die Widerstandsmessung mit einer Konstantstromquelle von 10 mA durch. Der Strom von 10 mA erzeugt über einem Widerstand von 100 Ω eine Spannungsdifferenz von 1 V, woraus sich ein maximal messbarer Widerstand von etwa 300 Ω ergibt. Die Konstantstromquelle wird aktiviert, indem ein Jumper auf das Stiftpaar der CCS-Stiftleiste (Konstantstromquelle) gesteckt wird. Siehe die Abbildung unten. + +
+![](ccs_jumpers.jpg){ width="60%" } +
Die Abbildung zeigt die für die Analogeingänge A2 und A4 aktivierte Konstantstromquelle.
+
diff --git a/docs/en/hardware/index.md b/docs/en/hardware/index.md index 66f9306..96f96c3 100644 --- a/docs/en/hardware/index.md +++ b/docs/en/hardware/index.md @@ -47,14 +47,14 @@ Different functional blocks of the board are described below. measurement noise. The analog inputs have an optional 10 mA constant-current source for active - resistance measurement.The constant-current source can be enabled using the + resistance measurement. The constant-current source can be enabled using the CCS jumper headers. In resistance measurement mode, the maximum resistance that can be measured - is 320 ohms. + is 300 ohms. 10. Digital inputs. HALMET has four digital inputs with a maximum input voltage of - +/- 30 V. The inputs feature a Schmitt trigger to improve noise immunity. + +/- 32 V. The inputs feature a Schmitt trigger to improve noise immunity. ## Galvanic Isolation @@ -140,7 +140,7 @@ meaning that they do not share a common ground with the rest of the board. ![](analog_input.svg){ width="60%" } diff --git a/docs/es/errata/index.md b/docs/es/errata/index.md new file mode 100644 index 0000000..f08bcc7 --- /dev/null +++ b/docs/es/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Errores conocidos +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Errores conocidos + +En esta página se enumeran todos los defectos de hardware conocidos en las distintas versiones de HALMET. + +## Versión 1.0.0 + +Las entradas digitales 3 y 4 están intercambiadas en la serigrafía de la cara inferior. La asignación de pines correcta es: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/es/getting-started/index.md b/docs/es/getting-started/index.md new file mode 100644 index 0000000..32ad9e4 --- /dev/null +++ b/docs/es/getting-started/index.md @@ -0,0 +1,76 @@ +--- +title: Primeros pasos +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Primeros pasos + +## Montaje del hardware + +Para permitir una colocación más flexible de los conectores en carcasas pequeñas, las placas HALMET se entregan sin los conectores de pines 1-Wire ni GPIO montados. Si se va a utilizar alguna de estas interfaces, es necesario soldar los conectores de pines a la placa. + +Las [instrucciones de montaje del hardware](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) del SH-ESP32 explican cómo soldar los pines de un conector a la placa. + +## Alimentación de la placa + +HALMET se alimenta a través del conector NMEA 2000. Si HALMET se va a conectar a una red NMEA 2000, la placa se puede alimentar directamente desde la red. En ese +caso, conectar los cables NMEA 2000 al bloque de terminales enchufable de 4 pines como se muestra en la figura siguiente. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Conectar los cables NMEA 2000 al conector como se muestra.
+
+ +Si HALMET no se va a conectar a una red NMEA 2000, se utiliza el mismo conector pero se conectan cables solo a las posiciones `-` y `+`. Sirve cualquier fuente de alimentación de 5–32 V. El consumo de corriente típico de la placa con la WiFi activa es de 0,07 A a 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Conectar los cables de alimentación al conector como se muestra.
+
+ +## Carcasas + +Para el uso a bordo, HALMET debe alojarse siempre en una carcasa estanca. +La placa está diseñada para encajar en la [carcasa SH-ESP32](https://shop.hatlabs.fi/products/sh-esp32-enclosure). A continuación se muestra un ejemplo de una placa HALMET instalada en la carcasa. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET instalado en la carcasa SH-ESP32.
+
+ +La carcasa SH-ESP32 dispone de un espacio limitado para conectores. +En la práctica, cada uno de los lados largos solo admite 2–3 conectores de panel. +Si se van a conectar más de unas pocas entradas, se recomienda una carcasa mayor. +Por ejemplo, la [carcasa compacta para SH-RPi](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) de Hat Labs, mostrada abajo, ya ofrece espacio de sobra para conectores. + +
+![](medium_enclosure.jpg){ width="50%" } +
La carcasa compacta para SH-RPi ofrece más espacio para colocar los conectores de panel.
+
+ + +Otras carcasas estancas adecuadas se encuentran fácilmente en cualquier tienda en línea. Las cajas de conexiones de exterior de mayor tamaño también sirven para este fin. + +### Perforación de los agujeros para los conectores de panel + +Las carcasas no suelen traer orificios pretaladrados. Al taladrar, +utilizar siempre una broca cónica o escalonada (la que parece un pequeño árbol de Navidad metálico). Las brocas normales para metal pueden morder con demasiada fuerza y agrietar la pared de la carcasa. + +Al planificar la colocación de los agujeros y los conectores, dejar espacio suficiente para apretar las tuercas del conector y para el cuerpo del conector. Si la carcasa se va a montar en pared, se recomienda orientar los conectores hacia abajo para reducir al mínimo la entrada de agua. + +Tamaños de agujero adecuados para los distintos conectores: + +- Prensaestopas PG7 y conector de panel M12 (NMEA 2000): 12,5 mm o 1/2″ +- Conectores de panel SP13 (conectores de plástico azul y negro): 13 mm +- Prensaestopas PG9: 16 mm o 5/8″ + +Los pasacables de goma o silicona permiten densidades de cable mucho mayores que los conectores de panel o los prensaestopas. Sin embargo, no son tan estancos como los conectores de panel o los prensaestopas. Además, obligan a fijar el cable de forma permanente, lo que puede dificultar +el mantenimiento del sistema. + +TODO: añadir una imagen de un pasacables. + +### Soldadura de los conectores de panel + +Al soldar los cables internos a los conectores de panel, utilizar siempre tubo termorretráctil en cada uno de los cables. +Recordar siempre que el tubo termorretráctil se desliza sobre el cable _antes_ de soldar… +Normalmente conviene aplicar primero estaño en la cavidad del pin del conector y después volver a fundirlo e insertar el cable. diff --git a/docs/es/hardware/index.md b/docs/es/hardware/index.md new file mode 100644 index 0000000..c53a24e --- /dev/null +++ b/docs/es/hardware/index.md @@ -0,0 +1,241 @@ +--- +title: Descripción del hardware +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hardware + +## Introducción al ESP32 + +HALMET se basa en el potente módulo microcontrolador ESP32-WROOM-32E. El ESP32 es un microcontrolador de doble núcleo con conectividad WiFi y Bluetooth integrada. El ESP32 es una opción muy extendida en aplicaciones de IoT por su bajo precio, su buen conjunto de periféricos y su facilidad de uso. + +## Bloques funcionales de la placa + +A continuación se describen los distintos bloques funcionales de la placa. + +
+![](HALMET-func.jpg){ width="60%" } +
Bloques funcionales del HALMET.
+
+ +1. Entrada y protección de NMEA 2000 y de la alimentación. El conector NMEA 2000 + cuenta con los siguientes elementos de protección: + - Fusible rearmable de 500 mA + - Diodo de protección contra inversión de polaridad + - Diodos TVS de protección contra sobretensión y ESD + - Filtrado de ruido en dos etapas + +2. Fuente de alimentación. Fuente conmutada con una corriente de salida máxima de 2 A. + +3. Transceptor CAN para NMEA 2000. Incluye LED RX y TX que indican visualmente + la actividad del bus CAN. + +4. Interfaces I2C y 1-Wire para conectar sensores adicionales. + +5. Interfaz de usuario. Un botón de reinicio, un botón de modo de arranque y uso + general, un LED rojo de alimentación y un LED azul programable por el usuario. + +6. Interfaz USB 2.0 para programación y depuración. + +7. Módulo ESP32-WROOM-32E con WiFi y Bluetooth integrados. El módulo de la placa + HALMET incluye 16 MB de memoria flash. + +8. Circuitos de aislamiento galvánico para las entradas digitales y analógicas. + +9. Entradas analógicas. La placa tiene cuatro entradas analógicas con una + resolución de 16 bits y una tensión de entrada máxima de 33 V. Cada entrada + cuenta con protección contra subtensión y sobretensión y con filtrado de paso + bajo con una frecuencia de corte de 160 Hz para reducir el ruido de medición. + + Las entradas analógicas disponen de una fuente de corriente constante opcional + de 10 mA para la medición activa de resistencia. La fuente de corriente + constante se activa mediante los conectores de pines para puente CCS. + + En el modo de medición de resistencia, la resistencia máxima que se puede + medir es de 300 Ω. + +10. Entradas digitales. HALMET tiene cuatro entradas digitales con una tensión de + entrada máxima de ±32 V. Las entradas incorporan un Schmitt trigger para + mejorar la inmunidad al ruido. + + +## Aislamiento galvánico + +La placa incorpora aislamiento galvánico entre las entradas digitales y +analógicas y el microcontrolador ESP32. El aislamiento se consigue mediante +aisladores digitales para el I2C y para las cuatro entradas digitales, +respectivamente, y un convertidor DC/DC aislado que alimenta la sección aislada. + +Gracias a este aislamiento, la placa se puede alimentar desde la red NMEA 2000 +sin riesgo de bucles de masa. El aislamiento protege además frente a picos de +tensión y ruido en las entradas. + +
+![](HALMET-isolation.jpg){ width="60%" } +
Barrera de aislamiento del HALMET. Los conectores de entrada están aislados del resto +de la placa, es decir, no comparten masa común con el resto de la placa.
+
+ +## Conectores + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
Conectores del HALMET, cara superior.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
Conectores del HALMET, cara inferior.
+
+ +
+
+ +### Conectores de la cara superior + +1. Conector NMEA 2000. Es un bloque de terminales enchufable de 4 pines + compatible con Phoenix MC 3.81. Sirve para conectar la placa a una red + NMEA 2000 y para alimentarla. + +2. Conector de pines 1-Wire. Permite conectar sensores 1-Wire a la placa. Es un + conector de 3 pines con paso de 2,54 mm. No viene montado de fábrica porque + puede interferir con la colocación de los conectores de panel de la carcasa. + +3. Conector de pines I2C. Permite conectar sensores I2C a la placa. Es un + conector de 4 pines con paso de 2,54 mm. + +4. Conector Micro USB. Se utiliza para programar y depurar la placa. + +5. Islas de soldadura sin montar para las señales de reinicio (EN) y de arranque + (IO0). + +6. Conector de pines GPIO. Es un conector de 2×10 pines con paso de 2,54 mm. + Saca los pines GPIO disponibles del ESP32 y también se puede utilizar como + conector JTAG. + +7. Conector de pines de alimentación de la zona aislada. Permite alimentar + dispositivos externos desde las señales «3V3» y «GND» de la sección aislada. + +8. Contactos del conector para puente de la fuente de corriente constante (CCS) + de las entradas analógicas. La fuente de corriente constante se activa + puenteando los contactos. + +9. Conectores de entrada analógica. Son bloques de terminales enchufables de + 2 pines compatibles con Phoenix MC 3.81. Sirven para conectar sensores + analógicos a la placa. + +10. Conectores de entrada digital. Son bloques de terminales enchufables de + 2 pines compatibles con Phoenix MC 3.81. Sirven para conectar sensores + digitales a la placa. + +### Conectores de la cara inferior + +11. Puente de soldadura del terminador CAN. Al cerrar el puente de soldadura se + activa la resistencia de terminación de 120 Ω del bus CAN. No utilizar la + resistencia de terminación en redes NMEA 2000. + +12. Puente de soldadura del filtro de paso bajo. Al cerrar el puente de soldadura + se activa un filtro de paso bajo en la entrada analógica correspondiente. El + filtro tiene una frecuencia de corte de 2,3 kHz. Sirve, por ejemplo, para + reducir el ruido de una señal de tacómetro. + +13. Puente de soldadura de la resistencia de pull-down. Al cerrar el puente de + soldadura se activa una resistencia de pull-down (a masa) de 100 kΩ en la + entrada digital correspondiente. La resistencia de pull-down permite leer un + interruptor normalmente abierto (NA) que lleva la señal a nivel alto al + cerrarse. + +14. Puente de soldadura de la resistencia de pull-up. Al cerrar el puente de + soldadura se activa una resistencia de pull-up (a positivo) de 100 kΩ en la + entrada digital correspondiente. La resistencia de pull-up permite leer un + interruptor normalmente cerrado (NC) que lleva la señal a nivel bajo al + cerrarse. + +15. Puentes de soldadura de selección de la dirección I2C del ADS1115. Al cerrar + los puentes de soldadura se selecciona la dirección I2C del convertidor + analógico-digital (ADC) ADS1115. Sirven para evitar conflictos de direcciones + cuando hay varios convertidores ADS1115 conectados al mismo bus I2C. Las + islas de soldadura permiten también conectar dispositivos I2C adicionales a + la zona aislada de la placa. + +### Referencia de GPIO + +HALMET reserva varios pines GPIO para los periféricos de entrada. Los pines GPIO +disponibles se sacan al conector de pines GPIO de 2×10 pines. La tabla siguiente +enumera los pines GPIO y sus funciones. + +| GPIO | Función | Notas | +| ------: | :---------------- | :--------------------------------------------------------- | +| 0 | Botón de arranque | Entra en el gestor de arranque al llevarse a nivel bajo | +| 1 | TXD0 | Transmisión de datos al USB | +| 2 | LED | LED rojo de la placa | +| 3 | RXD0 | Recepción de datos del USB | +| 4 | 1-Wire DQ | Línea de datos 1-Wire | +| 5 | - | Disponible en el conector de pines GPIO | +| 12 | - / TDI | Disponible en el conector de pines GPIO. Opcional: JTAG TDI | +| 13 | - / TCK | Disponible en el conector de pines GPIO. Opcional: JTAG TCK | +| 14 | - / TMS | Disponible en el conector de pines GPIO. Opcional: JTAG TMS | +| 15 | - / TDO | Disponible en el conector de pines GPIO. Opcional: JTAG TDO | +| 16 | - | Disponible en el conector de pines GPIO | +| 17 | - | Disponible en el conector de pines GPIO | +| 18 | CAN RX | Recepción desde NMEA 2000 | +| 19 | CAN TX | Transmisión a NMEA 2000 | +| 21 | I2C SDA | Línea de datos I2C. Se usa para la entrada analógica | +| 22 | I2C SCL | Línea de reloj I2C. Se usa para las entradas analógicas | +| 23 | DI1 | Entrada digital 1 | +| 25 | DI2 | Entrada digital 2 | +| 27 | DI3 | Entrada digital 3 | +| 26 | DI4 | Entrada digital 4 | +| 32 | - | Disponible en el conector de pines GPIO | +| 33 | - | Disponible en el conector de pines GPIO | +| 34 | - | Disponible en el conector de pines GPIO | +| 35 | - | Disponible en el conector de pines GPIO | +| 36 (VP) | Solo entrada | Disponible en el conector de pines GPIO | +| 39 (VN) | Solo entrada | Disponible en el conector de pines GPIO | + + +## Alimentación + +El rango de tensión de entrada admitido en la placa es de 5–32 V. El consumo de +corriente típico es de 90 mA a 12 V con el módulo WiFi activo (equivale a 1,1 W). + +## NMEA 2000 + +NMEA 2000 es un estándar de comunicaciones omnipresente que se utiliza para conectar sensores y dispositivos de control y visualización en embarcaciones y buques. Se basa en el bus CAN (Controller Area Network), un estándar de bus para vehículos diseñado para que los dispositivos se comuniquen entre sí sin un ordenador anfitrión. + +La placa cumple el estándar NMEA 2000 siempre que ninguno de los conectores no +aislados esté conectado a otros dispositivos referidos a masa. Por ejemplo, se +puede utilizar un sensor de temperatura 1-Wire con un cable largo, ya que no +comparte masa común con otros dispositivos. En cambio, conectar un convertidor +analógico-digital I2C al conector I2C no aislado rompería la conformidad con +NMEA 2000. + +TODO: asignación de pines GPIO de NMEA 2000 + +## LED de estado + +La placa HALMET tiene dos botones y dos LED. Los botones llevan las etiquetas «Reset» y «Boot». El botón de reinicio «Reset» reinicia la placa llevando a nivel bajo el pin Enable del ESP32. El botón de arranque «Boot» está conectado a GPIO0 y se puede utilizar durante el encendido del dispositivo para forzar el módulo al modo de descarga. El resto del tiempo se puede utilizar como una entrada de botón normal. + +Los dos LED no llevan una etiqueta explícita. El LED rojo se enciende siempre que hay alimentación de 3,3 V en la placa. El LED azul está conectado a GPIO2 (el pin que se usa habitualmente para el LED en las placas de desarrollo ESP32). Los programas de usuario pueden controlarlo para indicar el estado del dispositivo. + +## 1-Wire + +1-Wire es un sistema de bus de comunicación entre dispositivos diseñado por Dallas Semiconductor, empresa adquirida posteriormente por Maxim Integrated Products. Aunque 1-Wire es un protocolo lento, que admite velocidades de solo hasta 16,3 kbps, resulta muy sencillo de implementar y se puede utilizar a largas distancias. Se emplea habitualmente en sensores de temperatura y otros dispositivos de medición sencillos. + +La implementación de 1-Wire de HALMET incorpora filtrado de ruido ESD y RF, además de filtrado de paso bajo, para mejorar la fiabilidad de la red. + +Conviene tener en cuenta que el pin de datos de 1-Wire (etiquetado «DQ») está asignado físicamente a GPIO4, por lo que en el programa se debe utilizar GPIO4 para todos los datos de 1-Wire. + +## I2C + +I2C (Inter-Integrated Circuit) es un bus de comunicación serie síncrono muy extendido que se utiliza habitualmente para conectar circuitos integrados de todo tipo. Emplea dos hilos de datos además de la alimentación y la masa. + +HALMET utiliza I2C internamente para el convertidor analógico-digital ADS1115. El bus I2C se saca también a un conector de 4 pines para conectar dispositivos I2C adicionales. + +El bus I2C está conectado a GPIO21 (SDA) y GPIO22 (SCL) del ESP32. Estos son los pines I2C predeterminados en el entorno Arduino para ESP32, pero difieren de los pines predeterminados del SH-ESP32. diff --git a/docs/es/index.md b/docs/es/index.md new file mode 100644 index 0000000..607e15c --- /dev/null +++ b/docs/es/index.md @@ -0,0 +1,35 @@ +--- +title: Introducción +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Introducción + +HALMET, la interfaz Hat Labs Marine Engine & Tank, es una placa de desarrollo para conectar sensores de motor y de tanque en embarcaciones y otros vehículos. Permite leer sensores digitales y analógicos, así como conectarse a otros dispositivos mediante las interfaces NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire o GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Imagen de HALMET
+
+ +## Características principales + +- **Cuatro entradas digitales**: HALMET tiene cuatro entradas digitales para leer señales de alarma digitales o para usarlas como contadores. Las entradas toleran tensiones de entre −32 V y +32 V. Las entradas digitales sirven tanto para detectar niveles de señal como señales variables en el tiempo, como las revoluciones del motor, el caudal de combustible o los impulsos del contador de cadena. + +- **Cuatro entradas analógicas**: HALMET tiene cuatro entradas analógicas para leer sensores analógicos. Las entradas toleran tensiones de entre −32 V y +32 V, con un rango de medición de 0 a 33 V. Las entradas están conectadas a un convertidor analógico-digital ADS1115 de 16 bits. Las entradas analógicas se pueden usar tanto para medición pasiva de tensión como para medición activa de resistencia. + +- **Compatible con NMEA 2000**: HALMET es totalmente compatible con el estándar NMEA 2000. La placa se puede conectar a una red NMEA 2000 mediante la interfaz NMEA 2000 integrada. + +- **Interfaces I2C, 1-Wire y GPIO**: HALMET tiene una interfaz I2C de 4 pines, una interfaz 1-Wire de 3 pines y 13 puertos de entrada/salida de propósito general (GPIO) disponibles. + +- **Conectividad WiFi y Bluetooth**: HALMET incorpora un módulo ESP32-WROOM-32E con conectividad WiFi y Bluetooth. Ambas permiten tanto conectarse a redes WiFi existentes como crear un punto de acceso WiFi para conectarse directamente a la placa. + +- **ESP32-WROOM-32E con 16 MB de memoria flash**: el módulo ESP32-WROOM-32E ofrece potencia de proceso y memoria de sobra incluso para las aplicaciones más exigentes. Los 16 MB de memoria flash permiten almacenar localmente grandes cantidades de datos. + +- **Amplio rango de tensión de entrada**: HALMET se puede alimentar con seguridad desde el sistema de 12 V o 24 V habitual en vehículos y embarcaciones. HALMET tolera tensiones de entrada de entre 5 V y 32 V. + +HALMET es hardware abierto, con licencia Creative Commons Atribución-CompartirIgual 4.0 Internacional. + +## Adquisición del hardware + +Las placas HALMET se pueden comprar en [Hat Labs Oy](https://shop.hatlabs.fi). Todos los archivos de diseño están disponibles además en el [repositorio de hardware de HALMET en GitHub](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/es/revisions/index.md b/docs/es/revisions/index.md new file mode 100644 index 0000000..f585e5c --- /dev/null +++ b/docs/es/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Versiones del hardware +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Versiones del hardware + +## Introducción + +En esta página se documentan las distintas versiones de la placa y se enlazan los esquemas. El historial completo de los archivos de diseño está disponible en el [repositorio HALMET-hardware en GitHub](https://github.com/hatlabs/HALMET-hardware). + + +## Versión 1.0.0 + +Primera versión publicada. + +Esquemas: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Versión 1.0.1 + +Correcciones y mejoras en la serigrafía. Se añaden islas de soldadura «3V3» y «GND» en la zona aislada. + +Esquemas: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/es/software/index.md b/docs/es/software/index.md new file mode 100644 index 0000000..0d92d32 --- /dev/null +++ b/docs/es/software/index.md @@ -0,0 +1,16 @@ +--- +title: Software +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Software + +## Introducción + +Al tratarse de una placa de desarrollo, HALMET se entrega sin software preinstalado. Es necesario instalar el software adecuado. Aunque no es difícil, se recomienda tener experiencia previa con placas de microcontrolador como Arduino o los ESP32 Devkit. + +Hay firmware de ejemplo para HALMET disponible en el [repositorio HALMET-example-firmware en GitHub](https://github.com/hatlabs/HALMET-example-firmware). + +Conviene tener en cuenta que el soporte para cuestiones de desarrollo de software se ofrece únicamente a través del [foro de discusión de Hat Labs](https://github.com/hatlabs/discussions/discussions). + +Próximamente se publicarán más instrucciones. diff --git a/docs/es/tutorials/index.md b/docs/es/tutorials/index.md new file mode 100644 index 0000000..01f652f --- /dev/null +++ b/docs/es/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Tutoriales y proyectos de ejemplo +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +En esta página se enumerarán los tutoriales y los proyectos de ejemplo de HALMET. diff --git a/docs/es/usage/index.md b/docs/es/usage/index.md new file mode 100644 index 0000000..22380db --- /dev/null +++ b/docs/es/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Uso +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Uso + +## Casos de uso habituales + +En esta sección se ofrece información práctica sobre la lectura de distintos tipos de sensores y sobre la conexión de HALMET a otros dispositivos. + +### Configuración del software + +HALMET es una placa de desarrollo y no incluye ningún software preinstalado. +Es necesario instalar el software adecuado. Aunque no es difícil, se recomienda tener experiencia previa con placas de microcontrolador como Arduino o los ESP32 Devkit. + +La documentación de HALMET da por supuesto el uso del [firmware de ejemplo de HALMET](https://github.com/hatlabs/HALMET-example-firmware). Este firmware se basa en el framework [SensESP](https://signalk.org/SensESP/) y ofrece un acceso relativamente sencillo a las funciones de la placa. + +La [guía de primeros pasos de SensESP](https://signalk.org/SensESP/pages/getting_started/) contiene instrucciones detalladas para instalar el entorno de desarrollo necesario para compilar e instalar el firmware. Las instrucciones están escritas para dispositivos ESP32 genéricos, pero también son aplicables a HALMET. Basta con usar el [firmware de ejemplo de HALMET](https://github.com/hatlabs/HALMET-example-firmware) en lugar de la plantilla de proyecto de SensESP. + +Conviene tener en cuenta que, aunque la documentación de SensESP da por supuesto el uso de Signal K, HALMET también se puede utilizar perfectamente como dispositivo NMEA 2000 autónomo. + +Si se prefiere no usar SensESP, también se puede crear un firmware propio con Arduino IDE o ESP-IDF. Para muchos casos de uso, ESPHome es asimismo una opción excelente. + +**NOTA:** la asignación de los pines GPIO de HALMET difiere ligeramente de la del ESP32 Devkit y de la del SH-ESP32. Si se adapta cualquier software distinto del firmware de ejemplo de HALMET, es necesario comprobar la asignación de pines. Más información en la [referencia de GPIO](../hardware/index.md#referencia-de-gpio). + +### Uso de las entradas digitales + +HALMET tiene cuatro entradas digitales. Estas entradas se pueden usar para leer señales de alarma digitales o como contadores. En esta sección se describe el uso de las entradas en distintos casos de uso habituales. Las instrucciones dan por supuesto el uso del firmware de ejemplo de HALMET. + +Las entradas digitales D1–D4 están conectadas a los pines GPIO 23, 25, 27 y 26, respectivamente. Las entradas toleran tensiones de entre −32 V y +32 V. La tensión de umbral para detectar una señal alta es de unos 1,55 V, con una histéresis de unos 0,7 V. + +### Conexión a alarmas digitales + +En esta sección se describe cómo conectar HALMET a distintas señales de todo o nada, como las alarmas de motor o de sentina. + +#### Configuración del hardware + +Normalmente, las distintas señales de todo o nada, como las alarmas de motor o de sentina, se pueden conectar directamente a las entradas digitales de HALMET. Según el tipo de señal, puede hacer falta una resistencia de pull-up (a positivo) o de pull-down (a masa). + +En la figura siguiente, en el ejemplo (a) el circuito ya incluye una bombilla. Cuando el interruptor está abierto, la bombilla lleva la tensión de D1 a nivel bajo. No hace falta ninguna resistencia de pull-down adicional.[^1] En cambio, en el ejemplo (b) no hay ninguna otra carga en el circuito. Si el interruptor está abierto, la tensión de D2 queda flotante y la entrada estará aleatoriamente a nivel alto o bajo. En ese caso hay que activar la resistencia interna de pull-down cerrando el puente de soldadura de la cara inferior de la placa. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Entradas digitales en distintos casos de uso. (a) El circuito ya incluye una luz. (b) No hay ninguna otra carga en el circuito; el interruptor lleva la señal a nivel alto al cerrarse. (c) El interruptor lleva la señal a nivel bajo al cerrarse.
+
+ +[^1]: Si las luces del panel están hechas con LED, la caída de tensión en los LED puede no bastar para llevar la tensión a un nivel suficientemente bajo. En ese caso hay que activar la resistencia de pull-down. + +
+![](solder_jumpers.jpg){ width="60%" } +
Los puentes de soldadura de la cara inferior de la placa se pueden cerrar para activar las resistencias integradas de pull-up o de pull-down.
+
+ +Del mismo modo, si el interruptor lleva la señal a nivel bajo al cerrarse, como en el ejemplo (c), puede ser necesario activar la resistencia interna de pull-up. + +Por último, si los interruptores de alarma son normalmente cerrados (NC), el tratamiento se invierte. Al abrirse el interruptor, la tensión de entrada se lleva a nivel alto o bajo según el circuito. En ese caso puede ser necesario activar la resistencia interna de pull-up o de pull-down. + +#### Configuración del software + +El firmware de ejemplo de HALMET ofrece el método auxiliar `ConnectAlarmSender()` para configurar y conectar las entradas digitales. Véase `main.cpp` a partir de la línea 177. Se admiten tanto las señales activas a nivel alto como las activas a nivel bajo. + +### Entradas digitales como contadores + +Las entradas digitales de HALMET también se pueden usar como contadores. Esto resulta útil, por ejemplo, para contar las revoluciones del motor o los impulsos del contador de cadena. + +#### Configuración del hardware + +Normalmente estos sensores se excitan activamente en ambos sentidos, por lo que no hace falta pull-up ni pull-down. Si HALMET se conecta a una salida de baja impedancia, como el borne W del alternador, conviene añadir un fusible en línea para proteger el conductor frente a cortocircuitos por rozadura u otros daños. Por lo demás, el sensor se puede conectar directamente a la entrada digital. + +Si la fuente de impulsos tiene mucho ruido y la lectura de revoluciones resulta errática, se puede activar un filtro de paso bajo cerrando el puente de soldadura «LP» de la cara inferior de la placa. El filtro de paso bajo tiene una frecuencia de corte de unos 2,3 kHz, adecuada para aplicaciones como las entradas conectadas al borne W del alternador. + +#### Configuración del software + +El firmware de ejemplo de HALMET implementa un contador de impulsos que se puede activar en cualquiera de las entradas digitales o en todas ellas. Véase la configuración de ejemplo en `main.cpp` a partir de la línea 214. + +### Uso de las entradas analógicas + +HALMET tiene cuatro entradas analógicas que se pueden usar para medición pasiva de tensión o para medición activa de resistencia. En esta sección se describe el uso de las entradas en distintos casos de uso habituales. + +#### Configuración del hardware + +Las entradas analógicas A1–A4 están conectadas a un convertidor analógico-digital ADS1115. El ADS1115 tiene una resolución de 16 bits y una frecuencia de muestreo máxima de 860 muestras por segundo. No obstante, las entradas analógicas de HALMET incorporan un filtro de paso bajo potente con una frecuencia de corte de unos 160 Hz. Aun así, es más que suficiente para medir las salidas de sensores físicos, como los sensores de nivel de tanque o los sensores de presión del motor. + +En la figura siguiente, el ejemplo (a) muestra un indicador del panel del motor ya existente conectado a un sensor resistivo. Los indicadores del panel del motor suelen ser de tipo termostático o magnético. En ambos casos, el indicador y el sensor forman un divisor de tensión, y la tensión en el sensor es proporcional a la magnitud medida. Esta tensión se puede medir con las entradas analógicas de HALMET sin interferir en el funcionamiento del indicador original. Debido al divisor de tensión, la tensión puede no guardar una relación lineal con la magnitud medida, pero esto se puede compensar por software. + +
+![](analog_input.svg){ width="60%" } +
Conexión de las entradas analógicas con un indicador existente y sin él. (a) Si ya hay un indicador, utilizar HALMET en modo de medición pasiva de tensión. (b) Si no hay ningún otro dispositivo, utilizar HALMET en modo de medición activa de resistencia.
+
+ + +El ejemplo (b) muestra un caso sin indicador. El sensor se conecta directamente a la entrada analógica de HALMET. En ese caso, HALMET debe proporcionar la tensión de excitación al sensor. HALMET realiza la medición de resistencia mediante una fuente de corriente constante de 10 mA. La corriente de 10 mA genera una diferencia de tensión de 1 voltio en una resistencia de 100 ohmios, lo que da una resistencia máxima de unos 300 ohmios. La fuente de corriente constante se activa colocando un puente (jumper) en el par de pines del conector de pines «CCS» (fuente de corriente constante). Véase la figura siguiente. + +
+![](ccs_jumpers.jpg){ width="60%" } +
En la figura, la fuente de corriente constante está activada para las entradas analógicas A2 y A4.
+
diff --git a/docs/fi/getting-started/index.md b/docs/fi/getting-started/index.md index a2b5f6f..46d4d56 100644 --- a/docs/fi/getting-started/index.md +++ b/docs/fi/getting-started/index.md @@ -7,7 +7,7 @@ translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 ## Kortin kokoaminen -Jotta liittimet voidaan sijoittaa joustavammin pieniin koteloihin, HALMET-kortit toimitetaan ilman 1-Wire- ja GPIO-liittimiä. Jos aiot käyttää kumpaakaan näistä liitännöistä, sinun on juotettava liitin kiinni korttiin. +Jotta liittimet voidaan sijoittaa joustavammin pieniin koteloihin, HALMET-kortit toimitetaan ilman 1-Wire- ja GPIO-liittimiä. Jos aiot käyttää kumpaakaan näistä liitännöistä, liitin on juotettava kiinni korttiin. Jos tarvitset ohjeita nastarimojen juottamiseen, katso SH-ESP32:n [kokoamisohjeet](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards). diff --git a/docs/fi/hardware/index.md b/docs/fi/hardware/index.md index 77fafac..95f7bf5 100644 --- a/docs/fi/hardware/index.md +++ b/docs/fi/hardware/index.md @@ -1,6 +1,6 @@ --- title: Laitteiston kuvaus -translated_from: 66f9306e0980490684ef1cb989b75a230f6600df +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 --- # Laitteisto @@ -51,10 +51,10 @@ Kortin eri toiminnalliset lohkot kuvataan alla. vastusmittausta varten. Vakiovirtalähteen voi ottaa käyttöön CCS-hyppyliittimillä. - Vastusmittaustilassa suurin mitattava vastus on 320 ohmia. + Vastusmittaustilassa suurin mitattava vastus on 300 ohmia. 10. Digitaalitulot. HALMETissa on neljä digitaalituloa, joiden suurin tulojännite - on +/- 30 V. Tuloissa on Schmitt-liipaisin parantamassa häiriönsietoa. + on ±32 V. Tuloissa on Schmitt trigger parantamassa häiriönsietoa. ## Galvaaninen erotus @@ -141,12 +141,12 @@ ei ole yhteistä maata kortin muun osan kanssa. 13. Alasvetovastuksen juotossilta. Sillan sulkeminen ottaa käyttöön 100 kohmin alasvetovastuksen kyseisellä digitaalitulolla. Alasvetovastusta voi käyttää - avautuvan kytkimen lukemiseen, kun kytkin vetää jännitteen korkeaksi + sulkeutuvan kytkimen lukemiseen, kun kytkin vetää jännitteen korkeaksi sulkeutuessaan. 14. Ylösvetovastuksen juotossilta. Sillan sulkeminen ottaa käyttöön 100 kohmin ylösvetovastuksen kyseisellä digitaalitulolla. Ylösvetovastusta voi käyttää - sulkeutuvan kytkimen lukemiseen, kun kytkin vetää jännitteen matalaksi + avautuvan kytkimen lukemiseen, kun kytkin vetää jännitteen matalaksi sulkeutuessaan. 15. ADS1115:n I2C-osoitteen valinnan juotossillat. Silloilla valitaan @@ -203,9 +203,9 @@ Kortti täyttää NMEA 2000 -standardin vaatimukset niin kauan kuin yhtäkään TODO: NMEA 2000:n GPIO-nastajärjestys -## Tilan LEDit +## Tila-LEDit -HALMET-kortilla on kaksi painiketta ja kaksi LEDiä. Painikkeet on merkitty tunnuksilla Reset ja Boot. Reset-painike käynnistää kortin uudelleen vetämällä ESP32:n Enable-nastan matalaksi. Boot-painike on kytketty GPIO0:aan, ja sillä voi pakottaa moduulin latausmoodiin laitteen käynnistyksen aikana. Muulloin sitä voi käyttää tavallisena painiketulona. +HALMET-kortilla on kaksi painiketta ja kaksi LEDiä. Painikkeet on merkitty tunnuksilla Reset ja Boot. Reset-painike käynnistää kortin uudelleen vetämällä ESP32:n Enable-nastan matalaksi. Boot-painike on kytketty GPIO0:aan, ja sillä voi pakottaa moduulin lataustilaan laitteen käynnistyksen aikana. Muulloin sitä voi käyttää tavallisena painiketulona. LEDejä ei ole erikseen merkitty. Punainen LED palaa aina, kun kortilla on 3,3 V:n käyttöjännite. Sininen LED on kytketty GPIO2:een (nasta, jota ESP32-kehityskorteissa yleisesti käytetään LEDille). Käyttäjän ohjelmat voivat ohjata sitä osoittamaan laitteen tilaa. diff --git a/docs/fi/index.md b/docs/fi/index.md index c1f4b24..b889b7e 100644 --- a/docs/fi/index.md +++ b/docs/fi/index.md @@ -1,11 +1,11 @@ --- title: Johdanto -translated_from: 2ad10049c9c3d0b5f6fb78356500eaa25670febd +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed --- # Johdanto -HALMET (Hat Labs Marine Engine & Tank interface) on kehityskortti moottori- ja tankkianturien liittämiseen veneissä ja muissa ajoneuvoissa. Sillä voi lukea digitaalisia ja analogisia antureita sekä liittyä muihin laitteisiin NMEA 2000-, WiFi-, Bluetooth-, I2C-, 1-Wire- tai GPIO-liitäntöjen kautta. +HALMET (Hat Labs Marine Engine & Tank interface) on kehityskortti moottori- ja tankkianturien liittämiseen veneissä ja muissa ajoneuvoissa. Sillä voi lukea digitaalisia ja analogisia antureita sekä liittyä muihin laitteisiin NMEA 2000 -väylän, WiFin, Bluetoothin, I2C:n, 1-Wiren tai GPIO-liitäntöjen kautta.
![](halmet_v1_top_photo.jpg){ width="60%" } @@ -14,9 +14,9 @@ HALMET (Hat Labs Marine Engine & Tank interface) on kehityskortti moottori- ja t ## Tärkeimmät ominaisuudet -- **Neljä digitaalituloa**: HALMETissa on neljä digitaalituloa digitaalisten hälytyssignaalien lukemiseen tai laskureiksi. Tulot kestävät jännitteitä -32 V:n ja +32 V:n välillä. Digitaalituloilla voi havaita sekä signaalitasoja että ajassa muuttuvia signaaleja, kuten moottorin kierroslukua, polttoaineen virtausta tai ketjulaskurin pulsseja. +- **Neljä digitaalituloa**: HALMETissa on neljä digitaalituloa digitaalisten hälytyssignaalien lukemiseen tai laskureiksi. Tulot kestävät jännitteitä −32 V:n ja +32 V:n välillä. Digitaalituloilla voi havaita sekä signaalitasoja että ajassa muuttuvia signaaleja, kuten moottorin kierroslukua, polttoaineen virtausta tai ketjulaskurin pulsseja. -- **Neljä analogiatuloa**: HALMETissa on neljä analogiatuloa analogisten antureiden lukemiseen. Tulot kestävät jännitteitä -32 V:n ja +32 V:n välillä, ja mittausalue on 0–32 V. Tulot on kytketty 16-bittiseen ADS1115-AD-muuntimeen. Analogiatuloja voi käyttää sekä passiiviseen jännitemittaukseen että aktiiviseen vastusmittaukseen. +- **Neljä analogiatuloa**: HALMETissa on neljä analogiatuloa analogisten antureiden lukemiseen. Tulot kestävät jännitteitä −32 V:n ja +32 V:n välillä, ja mittausalue on 0–33 V. Tulot on kytketty 16-bittiseen ADS1115-AD-muuntimeen. Analogiatuloja voi käyttää sekä passiiviseen jännitemittaukseen että aktiiviseen vastusmittaukseen. - **NMEA 2000 -yhteensopiva**: HALMET on täysin yhteensopiva NMEA 2000 -standardin kanssa. Kortin voi liittää NMEA 2000 -verkkoon sisäänrakennetun NMEA 2000 -liitännän kautta. diff --git a/docs/fi/usage/index.md b/docs/fi/usage/index.md index 77e9c17..4ce0f05 100644 --- a/docs/fi/usage/index.md +++ b/docs/fi/usage/index.md @@ -1,6 +1,6 @@ --- title: Käyttö -translated_from: 0d5855d63a22b19308b3b70c9481dfc441864197 +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 --- # Käyttö @@ -14,7 +14,7 @@ Tässä osiossa on käytännön tietoa erityyppisten antureiden lukemisesta ja H HALMET on kehityskortti, eikä siinä ole valmiiksi asennettua ohjelmistoa. Sopiva ohjelmisto pitää asentaa itse. Se ei ole vaikeaa, mutta aiempi kokemus mikro-ohjainkorteista, kuten Arduinosta tai ESP32 Devkitistä, on suositeltavaa. -HALMETin dokumentaatiossa oletetaan, että käytössä on [HALMETin esimerkkifirmware](https://github.com/hatlabs/HALMET-example-firmware). Se perustuu [SensESP](https://signalk.org/SensESP/) -kehykseen ja tarjoaa suhteellisen suoraviivaisen pääsyn kortin ominaisuuksiin. +HALMETin dokumentaatiossa oletetaan, että käytössä on [HALMETin esimerkkifirmware](https://github.com/hatlabs/HALMET-example-firmware). Se perustuu [SensESP](https://signalk.org/SensESP/)-kehykseen ja tarjoaa suhteellisen suoraviivaisen pääsyn kortin ominaisuuksiin. [SensESP:n aloitusopas](https://signalk.org/SensESP/pages/getting_started/) sisältää yksityiskohtaiset ohjeet firmwaren kääntämiseen ja asentamiseen tarvittavan kehitysympäristön asennukseen. Ohjeet on kirjoitettu yleisille ESP32-laitteille, mutta ne pätevät myös HALMETiin. Käytä vain [HALMETin esimerkkifirmwarea](https://github.com/hatlabs/HALMET-example-firmware) SensESP:n projektipohjan sijaan. @@ -22,13 +22,13 @@ Huomaa, että vaikka SensESP:n dokumentaatiossa oletetaan Signal K:n käyttö, H Jos et halua käyttää SensESP:tä, voit myös tehdä oman firmwaresi Arduino IDE:llä tai ESP-IDF:llä. Moniin käyttötapauksiin myös ESPHome on erinomainen vaihtoehto. -**HUOMAA:** HALMETin GPIO-nastojen käyttö poikkeaa hieman sekä ESP32 Devkitin että SH-ESP32:n nastajärjestyksestä. Jos otat käyttöön jotain muuta ohjelmistoa kuin HALMETin esimerkkifirmwaren, sinun on tarkistettava nastojen käyttö. Lisätietoja on [GPIO-taulukossa](../hardware/index.md#gpio-taulukko). +**HUOMAA:** HALMETin GPIO-nastojen käyttö poikkeaa hieman sekä ESP32 Devkitin että SH-ESP32:n nastajärjestyksestä. Jos otat käyttöön jotain muuta ohjelmistoa kuin HALMETin esimerkkifirmwaren, nastojen käyttö on tarkistettava. Lisätietoja on [GPIO-taulukossa](../hardware/index.md#gpio-taulukko). ### Digitaalitulojen käyttö HALMETissa on neljä digitaalituloa. Niitä voi käyttää digitaalisten hälytyssignaalien lukemiseen tai laskureina. Tässä osiossa kuvataan tulojen käyttö erilaisissa yleisissä käyttötapauksissa. Ohjeissa oletetaan, että käytössä on HALMETin esimerkkifirmware. -Digitaalitulot D1–D4 on kytketty GPIO-nastoihin 23, 25, 27 ja 26 tässä järjestyksessä. Tulot kestävät jännitteitä -32 V:n ja +32 V:n välillä. Korkean signaalin havaitsemisen kynnysjännite on noin 1,55 V ja hystereesi noin 0,7 V. +Digitaalitulot D1–D4 on kytketty GPIO-nastoihin 23, 25, 27 ja 26 tässä järjestyksessä. Tulot kestävät jännitteitä −32 V:n ja +32 V:n välillä. Korkean signaalin havaitsemisen kynnysjännite on noin 1,55 V ja hystereesi noin 0,7 V. ### Liittäminen digitaalisiin hälytyksiin @@ -54,7 +54,7 @@ Alla olevan kuvan esimerkissä (a) piirissä on jo hehkulamppu. Kun kytkin on au Vastaavasti jos kytkin vetää signaalin matalaksi sulkeutuessaan kuten esimerkissä (c), sisäinen ylösveto voi olla tarpeen ottaa käyttöön. -Jos hälytyskytkimet ovat sulkeutuvia, tilanne on päinvastainen. Kun kytkin avautuu, tulojännite vedetään ylös tai alas piiristä riippuen. Tällöin sisäinen ylös- tai alasveto voi olla tarpeen ottaa käyttöön. +Jos hälytyskytkimet ovat avautuvia, tilanne on päinvastainen. Kun kytkin avautuu, tulojännite vedetään ylös tai alas piiristä riippuen. Tällöin sisäinen ylös- tai alasveto voi olla tarpeen ottaa käyttöön. #### Ohjelmiston asennus @@ -66,7 +66,7 @@ HALMETin digitaalituloja voi käyttää myös laskureina. Tämä on hyödyllist #### Laitteiston asennus -Yleensä tällaisia antureita ohjataan aktiivisesti molempiin suuntiin, joten ylös- tai alasvetoa ei tarvita. Jos liität HALMETin matalaimpedanssiseen lähtöön, kuten laturin W-napaan, on suositeltavaa lisätä sarjaan sulake suojaamaan johdinta hankautumisesta tai muusta vauriosta johtuvilta oikosuluilta. Muuten anturin voi kytkeä suoraan digitaalituloon. +Yleensä tällaisia antureita ohjataan aktiivisesti molempiin suuntiin, joten ylös- tai alasvetoa ei tarvita. Jos liität HALMETin matalaimpedanssiseen lähtöön, kuten laturin W-napaan, on suositeltavaa lisätä linjasulake suojaamaan johdinta hankautumisesta tai muusta vauriosta johtuvilta oikosuluilta. Muuten anturin voi kytkeä suoraan digitaalituloon. Jos pulssilähde on hyvin häiriöinen ja kierroslukulukema heittelee, alipäästösuotimen voi ottaa käyttöön sulkemalla kortin takapuolen LP-juotossillan. Alipäästösuotimen rajataajuus on noin 2,3 kHz, mikä sopii esimerkiksi laturin W-navan kaltaisiin tuloihin. @@ -90,7 +90,7 @@ Alla olevan kuvan esimerkissä (a) on moottoripaneelin mittari kytkettynä vastu
-Esimerkissä (b) mittaria ei ole. Anturi on kytketty suoraan HALMETin analogiatuloon. Tällöin HALMETin on tuotettava anturille herätejännite. HALMET toteuttaa vastusmittauksen 10 mA:n vakiovirtalähteellä. 10 mA:n virta synnyttää 100 ohmin vastuksen yli 1 voltin jännite-eron, joten suurin mitattava vastus on noin 300 ohmia. Vakiovirtalähde otetaan käyttöön asettamalla hyppy CCS-hyppyliittimen (constant current source) nastapariin. Katso alla oleva kuva. +Esimerkissä (b) mittaria ei ole. Anturi on kytketty suoraan HALMETin analogiatuloon. Tällöin HALMETin on tuotettava anturille herätejännite. HALMET toteuttaa vastusmittauksen 10 mA:n vakiovirtalähteellä. 10 mA:n virta synnyttää 100 ohmin vastuksen yli 1 voltin jännite-eron, joten suurin mitattava vastus on noin 300 ohmia. Vakiovirtalähde otetaan käyttöön asettamalla hyppy CCS-hyppyliittimen (vakiovirtalähde) nastapariin. Katso alla oleva kuva.
![](ccs_jumpers.jpg){ width="60%" } diff --git a/docs/fr/errata/index.md b/docs/fr/errata/index.md new file mode 100644 index 0000000..ede7577 --- /dev/null +++ b/docs/fr/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Problèmes connus +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Problèmes connus + +Cette page recense toutes les anomalies matérielles connues des différentes versions de HALMET. + +## Version 1.0.0 + +Les entrées numériques 3 et 4 sont inversées sur la sérigraphie de la face arrière. Le brochage correct est le suivant : + + - DI3 : GPIO 27 + - DI4 : GPIO 26 diff --git a/docs/fr/getting-started/index.md b/docs/fr/getting-started/index.md new file mode 100644 index 0000000..6529fc2 --- /dev/null +++ b/docs/fr/getting-started/index.md @@ -0,0 +1,73 @@ +--- +title: Prise en main +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Prise en main + +## Assemblage du matériel + +Afin de permettre un placement plus souple des connecteurs dans les petits boîtiers, les cartes HALMET sont livrées sans les connecteurs 1-Wire ni GPIO. Si vous prévoyez d'utiliser l'une de ces interfaces, vous devrez souder le connecteur correspondant sur la carte. + +Si vous avez besoin d'instructions pour souder des barrettes de broches sur la carte, consultez les [instructions d'assemblage](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) de la SH-ESP32. + +## Alimentation de la carte + +HALMET est alimenté par le connecteur NMEA 2000. Si vous prévoyez de raccorder HALMET à un réseau NMEA 2000, vous pouvez alimenter la carte directement depuis le réseau. Dans ce cas, raccordez les fils NMEA 2000 au bornier débrochable à 4 broches comme le montre la figure suivante. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Raccordez les fils NMEA 2000 au connecteur comme indiqué.
+
+ +Si vous ne prévoyez pas de raccorder HALMET à un réseau NMEA 2000, utilisez le même connecteur mais ne câblez que les emplacements `-` et `+`. Toute source d'alimentation de 5–32 V convient. La consommation de courant typique de la carte, WiFi actif, est de 0,07 A sous 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Raccordez les fils d'alimentation au connecteur comme indiqué.
+
+ +## Boîtiers + +À bord d'un bateau, HALMET doit toujours être placé dans un boîtier étanche. +La carte est conçue pour s'adapter au [boîtier SH-ESP32](https://shop.hatlabs.fi/products/sh-esp32-enclosure). Voir ci-dessous un exemple de carte HALMET installée dans le boîtier. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET installé dans le boîtier SH-ESP32.
+
+ +Le boîtier SH-ESP32 offre peu de place pour les connecteurs. +Chacun des grands côtés ne peut accueillir en pratique que 2–3 connecteurs de panneau. +Si vous comptez raccorder plus de quelques entrées, un boîtier plus grand est recommandé. +Par exemple, le [boîtier compact SH-RPi](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) de Hat Labs, illustré ci-dessous, dispose déjà d'une place largement suffisante pour les connecteurs. + +
+![](medium_enclosure.jpg){ width="50%" } +
le boîtier compact SH-RPi offre plus de place pour l'implantation des connecteurs de panneau.
+
+ + +D'autres boîtiers étanches adaptés se trouvent facilement sur n'importe quelle place de marché en ligne. Les grandes boîtes de dérivation d'extérieur conviennent également. + +### Perçage des trous pour les connecteurs de panneau + +Les boîtiers n'ont généralement pas de trous prépercés. Pour percer, utilisez toujours un foret conique ou un foret étagé (celui qui ressemble à un petit sapin de Noël métallique). Les forets à métaux ordinaires mordent facilement trop fort et peuvent fissurer la paroi du boîtier. + +Lorsque vous planifiez l'emplacement des trous et des connecteurs, laissez suffisamment de place pour serrer les écrous des connecteurs et pour le corps du connecteur. Si vous prévoyez une fixation murale du boîtier, il est recommandé d'orienter les connecteurs vers le bas afin de limiter les risques d'infiltration d'eau. + +Tailles de trous adaptées aux différents connecteurs : + +- presse-étoupe PG7 et connecteur de panneau M12 (NMEA 2000) : 12,5 mm ou 1/2" +- connecteurs de panneau SP13 (connecteurs plastiques bleu-noir) : 13 mm +- presse-étoupe PG9 : 16 mm ou 5/8" + +Les passe-fils en caoutchouc ou en silicone permettent des densités de câbles nettement plus élevées que les connecteurs de panneau ou les presse-étoupes. Ils ne sont toutefois pas aussi étanches que les connecteurs de panneau ou les presse-étoupes. De plus, ils exigent une fixation permanente du câble, ce qui peut compliquer l'entretien du système. + +TODO : Ajouter une photo d'un passe-fil. + +### Soudure des connecteurs de panneau + +Lorsque vous soudez les fils internes aux connecteurs de panneau, utilisez toujours de la gaine thermorétractable sur chacun des fils. +Pensez toujours à enfiler la gaine thermorétractable sur les fils _avant_ de souder… +En général, vous pouvez d'abord déposer de la soudure dans la cavité de la broche du connecteur, puis refondre la soudure et y insérer le fil. diff --git a/docs/fr/hardware/index.md b/docs/fr/hardware/index.md new file mode 100644 index 0000000..2c82af5 --- /dev/null +++ b/docs/fr/hardware/index.md @@ -0,0 +1,234 @@ +--- +title: Description du matériel +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Matériel + +## Présentation de l'ESP32 + +HALMET repose sur le puissant module microcontrôleur ESP32-WROOM-32E. L'ESP32 est un microcontrôleur double cœur doté d'une connectivité WiFi et Bluetooth intégrée. L'ESP32 est un choix répandu pour les applications IoT grâce à son faible coût, à son bon ensemble de périphériques et à sa simplicité d'utilisation. + +## Blocs fonctionnels de la carte + +Les différents blocs fonctionnels de la carte sont décrits ci-dessous. + +
+![](HALMET-func.jpg){ width="60%" } +
Blocs fonctionnels de la carte HALMET.
+
+ +1. Entrée NMEA 2000 et alimentation, avec leurs protections. Le connecteur + NMEA 2000 comporte les éléments de protection suivants : + - Fusible réarmable de 500 mA + - Diode de protection contre l'inversion de polarité + - Diodes TVS de protection contre les surtensions et les décharges électrostatiques (ESD) + - Filtrage du bruit à deux étages + +2. Alimentation. Une alimentation à découpage dont le courant de sortie maximal est de 2 A. + +3. Émetteur-récepteur CAN pour NMEA 2000. Des LED RX et TX indiquent + visuellement l'activité du bus CAN. + +4. Interfaces I2C et 1-Wire pour raccorder des capteurs supplémentaires. + +5. Interface utilisateur. Un bouton Reset (réinitialisation), un bouton Boot + servant aussi de bouton à usage général, une LED d'alimentation rouge et une LED bleue programmable par l'utilisateur. + +6. Interface USB 2.0 pour la programmation et le débogage. + +7. Module ESP32-WROOM-32E avec WiFi et Bluetooth intégrés. Le module monté sur la carte + HALMET dispose de 16 Mo de mémoire flash. + +8. Circuits d'isolation galvanique des entrées numériques et analogiques. + +9. Entrées analogiques. La carte comporte quatre entrées analogiques d'une résolution de + 16 bits et d'une tension d'entrée maximale de 33 V. Chaque entrée dispose d'une protection + contre les sous-tensions et les surtensions, ainsi que d'un filtrage passe-bas dont la + fréquence de coupure est de 160 Hz, afin de réduire le bruit de mesure. + + Les entrées analogiques disposent en option d'une source de courant constant (CCS) de + 10 mA pour la mesure active de résistance. La source de courant constant s'active à + l'aide des connecteurs à cavalier CCS. + + En mode de mesure de résistance, la résistance maximale mesurable est de 300 Ω. + +10. Entrées numériques. HALMET comporte quatre entrées numériques dont la tension d'entrée + maximale est de ±32 V. Les entrées intègrent un Schmitt trigger pour améliorer l'immunité au bruit. + + +## Isolation galvanique + +La carte assure une isolation galvanique entre les entrées numériques et analogiques +d'une part et le microcontrôleur ESP32 d'autre part. L'isolation repose sur des +isolateurs numériques, respectivement pour l'I2C et pour les quatre entrées numériques, +ainsi que sur un convertisseur DC/DC isolé qui alimente la partie isolée. + +Grâce à cette isolation, la carte peut être alimentée par le réseau NMEA 2000 sans +risque de boucles de masse. L'isolation protège également des pics de tension et du +bruit sur les entrées. + +
+![](HALMET-isolation.jpg){ width="60%" } +
Barrière d'isolation de la carte HALMET. Les connecteurs d'entrée sont isolés du reste +de la carte : ils ne partagent donc pas de masse commune avec elle.
+
+ +## Connecteurs + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
Connecteurs de la carte HALMET, face supérieure.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
Connecteurs de la carte HALMET, face inférieure.
+
+ +
+
+ +### Connecteurs de la face supérieure + +1. Connecteur NMEA 2000. Il s'agit d'un bornier débrochable à 4 broches compatible + Phoenix MC 3.81. Il sert à raccorder la carte à un réseau NMEA 2000 et à + l'alimenter. + +2. Connecteur 1-Wire. Le connecteur 1-Wire permet de raccorder des capteurs 1-Wire à + la carte. Il s'agit d'un connecteur à 3 broches au pas de 2,54 mm. Il n'est pas + monté sur la carte par défaut, car il peut gêner l'emplacement des connecteurs de + panneau du boîtier. + +3. Connecteur I2C. Le connecteur I2C permet de raccorder des capteurs I2C à la carte. + Il s'agit d'un connecteur à 4 broches au pas de 2,54 mm. + +4. Connecteur Micro USB. Il sert à la programmation et au débogage de la carte. + +5. Pastilles non implantées pour les signaux Reset (EN) et Boot (IO0). + +6. Connecteur GPIO. Il s'agit d'un connecteur à 2×10 broches au pas de 2,54 mm. Il rend + accessibles les broches GPIO libres de l'ESP32 et peut aussi servir de connecteur JTAG. + +7. Connecteur d'alimentation de la zone isolée. Il permet d'alimenter des appareils + externes depuis les broches 3V3 et GND de la partie isolée. + +8. Contacts du connecteur à cavalier de la source de courant constant (CCS) des entrées + analogiques. La source de courant constant s'active en court-circuitant les contacts + du cavalier. + +9. Connecteurs des entrées analogiques. Ce sont des borniers débrochables à 2 broches + compatibles Phoenix MC 3.81. Ils servent à raccorder des capteurs analogiques à la + carte. + +10. Connecteurs des entrées numériques. Ce sont des borniers débrochables à 2 broches + compatibles Phoenix MC 3.81. Ils servent à raccorder des capteurs numériques à la + carte. + +### Connecteurs de la face inférieure + +11. Pont à souder de terminaison CAN. Le court-circuiter active la résistance de + terminaison de 120 Ω du bus CAN. N'utilisez pas cette résistance de terminaison + sur les réseaux NMEA 2000. + +12. Pont à souder du filtre passe-bas. Le court-circuiter active un filtre passe-bas + sur l'entrée analogique correspondante. La fréquence de coupure du filtre est de + 2,3 kHz. Ce filtre permet par exemple de réduire le bruit d'un signal de + compte-tours. + +13. Pont à souder de la résistance de tirage vers le bas (pull-down). Le court-circuiter + active une résistance de tirage vers le bas de 100 kΩ sur l'entrée numérique + correspondante. Cette résistance permet de lire un interrupteur normalement ouvert + qui met l'entrée à l'état haut lorsqu'il se ferme. + +14. Pont à souder de la résistance de tirage vers le haut (pull-up). Le court-circuiter + active une résistance de tirage vers le haut de 100 kΩ sur l'entrée numérique + correspondante. Cette résistance permet de lire un interrupteur normalement fermé + qui met l'entrée à l'état bas lorsqu'il se ferme. + +15. Ponts à souder de sélection de l'adresse I2C de l'ADS1115. Les court-circuiter permet + de choisir l'adresse I2C du convertisseur analogique-numérique ADS1115. Ils servent à + éviter les conflits d'adresses lorsque plusieurs convertisseurs ADS1115 sont raccordés + au même bus I2C. Ces pastilles peuvent aussi servir à raccorder d'autres appareils I2C + à la zone isolée de la carte. + +### Référence GPIO + +HALMET réserve un certain nombre de broches GPIO aux périphériques d'entrée. Les broches +GPIO libres sont rendues accessibles sur le connecteur GPIO à 2×10 broches. Le tableau +suivant récapitule les broches GPIO et leurs fonctions. + +| GPIO | Fonction | Remarques | +| ------: | :---------- | :------------------------------------------------- | +| 0 | Bouton Boot | Entre dans le bootloader à l'état bas | +| 1 | TXD0 | Émission de données vers l'USB | +| 2 | LED | LED rouge de la carte | +| 3 | RXD0 | Réception de données depuis l'USB | +| 4 | 1-Wire DQ | Ligne de données 1-Wire | +| 5 | - | Disponible sur le connecteur GPIO | +| 12 | - / TDI | Disponible sur le connecteur GPIO. En option : JTAG TDI | +| 13 | - / TCK | Disponible sur le connecteur GPIO. En option : JTAG TCK | +| 14 | - / TMS | Disponible sur le connecteur GPIO. En option : JTAG TMS | +| 15 | - / TDO | Disponible sur le connecteur GPIO. En option : JTAG TDO | +| 16 | - | Disponible sur le connecteur GPIO | +| 17 | - | Disponible sur le connecteur GPIO | +| 18 | CAN RX | Réception depuis NMEA 2000 | +| 19 | CAN TX | Émission vers NMEA 2000 | +| 21 | I2C SDA | Ligne de données I2C. Utilisée pour l'entrée analogique | +| 22 | I2C SCL | Ligne d'horloge I2C. Utilisée pour les entrées analogiques | +| 23 | DI1 | Entrée numérique 1 | +| 25 | DI2 | Entrée numérique 2 | +| 27 | DI3 | Entrée numérique 3 | +| 26 | DI4 | Entrée numérique 4 | +| 32 | - | Disponible sur le connecteur GPIO | +| 33 | - | Disponible sur le connecteur GPIO | +| 34 | - | Disponible sur le connecteur GPIO | +| 35 | - | Disponible sur le connecteur GPIO | +| 36 (VP) | Entrée seule | Disponible sur le connecteur GPIO | +| 39 (VN) | Entrée seule | Disponible sur le connecteur GPIO | + + +## Alimentation + +La plage de tension d'entrée admissible de la carte est de 5–32 V. La consommation de +courant typique est de 90 mA sous 12 V avec le module WiFi actif (soit 1,1 W). + +## NMEA 2000 + +NMEA 2000 est un standard de communication omniprésent, utilisé pour relier capteurs, organes de commande et afficheurs à bord des bateaux et des navires. Il repose sur le bus CAN (Controller Area Network), un standard de bus pour véhicules conçu pour permettre aux appareils de communiquer entre eux sans ordinateur hôte. + +La carte est conforme au standard NMEA 2000 tant qu'aucun des connecteurs non isolés +n'est raccordé à d'autres appareils référencés à la masse. Un capteur de température +1-Wire à câble long peut par exemple être utilisé, car il ne partage pas de masse commune +avec les autres appareils. En revanche, raccorder un convertisseur analogique-numérique +I2C au connecteur I2C non isolé romprait la conformité NMEA 2000. + +TODO : brochage GPIO NMEA 2000 + +## LED d'état + +La carte HALMET comporte deux boutons et deux LED. Les deux boutons portent les marquages Reset et Boot. Le bouton Reset redémarre la carte en mettant à l'état bas la broche Enable de l'ESP32. Le bouton Boot est relié à GPIO0 et permet, pendant le démarrage de l'appareil, de forcer le module en mode de téléchargement. Le reste du temps, il peut servir d'entrée bouton ordinaire. + +Les deux LED ne portent pas de marquage. La LED rouge est allumée dès que la carte est alimentée en 3,3 V. La LED bleue est reliée à GPIO2 (la broche habituellement utilisée pour la LED sur les cartes de développement ESP32). Les programmes de l'utilisateur peuvent la commander pour indiquer l'état de l'appareil. + +## 1-Wire + +1-Wire est un système de bus de communication entre appareils, conçu par Dallas Semiconductor, société depuis rachetée par Maxim Integrated Products. Bien que 1-Wire soit un protocole lent, limité à 16,3 kbit/s, il est très simple à mettre en œuvre et fonctionne sur de longues distances. Il est couramment utilisé pour les capteurs de température et d'autres dispositifs de mesure simples. + +L'implémentation 1-Wire de la carte HALMET comporte un filtrage des perturbations ESD et RF ainsi qu'un filtrage passe-bas, afin d'améliorer la fiabilité du réseau. + +Notez que la broche de données 1-Wire (marquée « DQ ») est physiquement reliée à GPIO4 : dans votre programme, utilisez donc GPIO4 pour toutes les données 1-Wire. + +## I2C + +I2C (Inter-Integrated Circuit) est un bus de communication série synchrone très répandu, couramment utilisé pour dialoguer avec toutes sortes de circuits intégrés. Il utilise deux fils de données, en plus de l'alimentation et de la masse. + +HALMET utilise l'I2C en interne pour le convertisseur analogique-numérique ADS1115. Le bus I2C est également rendu accessible sur un connecteur à 4 broches, pour raccorder d'autres appareils I2C. + +Le bus I2C est relié à GPIO21 (SDA) et GPIO22 (SCL) sur l'ESP32. Ce sont les broches I2C par défaut de l'environnement Arduino ESP32, mais elles diffèrent des broches par défaut du SH-ESP32. diff --git a/docs/fr/index.md b/docs/fr/index.md new file mode 100644 index 0000000..328a5d8 --- /dev/null +++ b/docs/fr/index.md @@ -0,0 +1,35 @@ +--- +title: Introduction +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Introduction + +HALMET, la Hat Labs Marine Engine & Tank interface, est une carte de développement destinée au raccordement des capteurs moteur et de réservoir sur les bateaux et autres véhicules. Elle permet de lire des capteurs numériques et analogiques, ainsi que de communiquer avec d'autres appareils via les interfaces NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire ou GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Photo de HALMET
+
+ +## Principales caractéristiques + +- **Quatre entrées numériques** : HALMET dispose de quatre entrées numériques pour lire des signaux d'alarme numériques ou pour servir de compteurs. Les entrées supportent des tensions comprises entre −32 V et +32 V. Les entrées numériques permettent aussi bien de détecter des niveaux de signal que des signaux variables dans le temps, comme le régime moteur, le débit de carburant ou les impulsions d'un compteur de chaîne. + +- **Quatre entrées analogiques** : HALMET dispose de quatre entrées analogiques pour lire des capteurs analogiques. Les entrées supportent des tensions comprises entre −32 V et +32 V, avec une plage de mesure de 0 à 33 V. Elles sont reliées à un convertisseur analogique-numérique ADS1115 de 16 bits. Les entrées analogiques permettent aussi bien la mesure passive de tension que la mesure active de résistance. + +- **Compatible NMEA 2000** : HALMET est entièrement compatible avec la norme NMEA 2000. La carte peut être raccordée à un réseau NMEA 2000 par l'interface NMEA 2000 intégrée. + +- **Interfaces I2C, 1-Wire et GPIO** : HALMET possède une interface I2C à 4 broches, une interface 1-Wire à 3 broches et 13 ports d'entrée/sortie à usage général (GPIO) disponibles. + +- **Connectivité WiFi et Bluetooth** : HALMET intègre un module ESP32-WROOM-32E doté de la connectivité WiFi et Bluetooth. Celle-ci permet aussi bien de se connecter à des réseaux WiFi existants que de créer un point d'accès WiFi pour se connecter directement à la carte. + +- **ESP32-WROOM-32E avec 16 Mo de flash** : le module ESP32-WROOM-32E offre une puissance de calcul et une mémoire largement suffisantes, même pour les applications les plus exigeantes. Les 16 Mo de flash permettent de stocker localement de grandes quantités de données. + +- **Large plage de tension d'entrée** : HALMET peut être alimenté en toute sécurité par le réseau 12 V ou 24 V couramment utilisé sur les véhicules et les bateaux. HALMET supporte des tensions d'entrée comprises entre 5 V et 32 V. + +HALMET est du matériel libre (open hardware), sous licence Creative Commons Attribution-ShareAlike 4.0 International. + +## Se procurer le matériel + +Vous pouvez acheter des cartes HALMET auprès de [Hat Labs Oy](https://shop.hatlabs.fi). Tous les fichiers de conception sont également disponibles dans le [dépôt GitHub du matériel HALMET](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/fr/revisions/index.md b/docs/fr/revisions/index.md new file mode 100644 index 0000000..168c892 --- /dev/null +++ b/docs/fr/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Versions de la carte +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Versions de la carte + +## Introduction + +Cette page documente les différentes versions de la carte et fournit des liens vers les schémas. L'historique complet des fichiers de conception est disponible dans le [dépôt GitHub HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Version 1.0.0 + +Première version publiée. + +Schémas : [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Version 1.0.1 + +Corrections et améliorations de la sérigraphie. Pastilles 3V3 et GND ajoutées sur la zone isolée. + +Schémas : [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/fr/software/index.md b/docs/fr/software/index.md new file mode 100644 index 0000000..4f69c0d --- /dev/null +++ b/docs/fr/software/index.md @@ -0,0 +1,16 @@ +--- +title: Logiciel +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Logiciel + +## Introduction + +En tant que carte de développement, HALMET est livré sans aucun logiciel préinstallé. Vous devrez installer vous-même un logiciel adapté. Ce n'est pas difficile, mais une certaine expérience préalable des cartes à microcontrôleur telles que les Arduino ou les ESP32 Devkit est recommandée. + +Un firmware d'exemple pour HALMET est disponible dans le [dépôt GitHub HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Veuillez noter que l'assistance sur les questions de développement logiciel est assurée uniquement via le [forum de discussion Hat Labs](https://github.com/hatlabs/discussions/discussions). + +D'autres instructions seront publiées prochainement. diff --git a/docs/fr/tutorials/index.md b/docs/fr/tutorials/index.md new file mode 100644 index 0000000..838a6dc --- /dev/null +++ b/docs/fr/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Tutoriels et projets d'exemple +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +Les tutoriels et projets d'exemple HALMET seront listés sur cette page. diff --git a/docs/fr/usage/index.md b/docs/fr/usage/index.md new file mode 100644 index 0000000..a0307e9 --- /dev/null +++ b/docs/fr/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Utilisation +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Utilisation + +## Cas d'usage courants + +Cette section rassemble des informations pratiques sur la lecture des différents types de capteurs et sur le raccordement de HALMET à d'autres appareils. + +### Configuration logicielle + +HALMET est une carte de développement et n'est livré avec aucun logiciel préinstallé. +Vous devrez installer vous-même un logiciel adapté. Ce n'est pas difficile, mais une certaine expérience préalable des cartes à microcontrôleur telles que les Arduino ou les ESP32 Devkit est recommandée. + +La documentation de HALMET suppose l'utilisation du [firmware d'exemple HALMET](https://github.com/hatlabs/HALMET-example-firmware). Ce firmware repose sur le framework [SensESP](https://signalk.org/SensESP/) et donne un accès relativement simple aux fonctions de la carte. + +Le [guide de démarrage SensESP](https://signalk.org/SensESP/pages/getting_started/) donne des instructions détaillées pour installer l'environnement de développement nécessaire à la compilation et à l'installation du firmware. Ces instructions sont écrites pour des appareils ESP32 génériques, mais elles s'appliquent aussi à HALMET. Utilisez simplement le [firmware d'exemple HALMET](https://github.com/hatlabs/HALMET-example-firmware) à la place du modèle de projet SensESP. + +Notez que, même si la documentation SensESP suppose l'utilisation de Signal K, HALMET est également parfaitement utilisable comme appareil NMEA 2000 autonome. + +Si vous préférez ne pas utiliser SensESP, vous pouvez aussi créer votre propre firmware avec l'Arduino IDE ou l'ESP-IDF. Pour de nombreux cas d'usage, ESPHome est également une excellente option. + +**REMARQUE :** l'affectation des broches GPIO de HALMET diffère légèrement de celle de l'ESP32 Devkit et de celle de la SH-ESP32. Si vous adaptez un logiciel autre que le firmware d'exemple HALMET, vous devrez vérifier attentivement l'affectation des broches. Voir la [référence GPIO](../hardware/index.md#reference-gpio) pour plus d'informations. + +### Utilisation des entrées numériques + +HALMET possède quatre entrées numériques. Ces entrées permettent de lire des signaux d'alarme numériques ou de servir de compteurs. Cette section décrit leur utilisation dans différents cas d'usage courants. Les instructions supposent l'utilisation du firmware d'exemple HALMET. + +Les entrées numériques D1–D4 sont reliées respectivement aux broches GPIO 23, 25, 27 et 26. Les entrées supportent des tensions comprises entre −32 V et +32 V. La tension de seuil de détection d'un niveau haut est d'environ 1,55 V, avec une hystérésis d'environ 0,7 V. + +### Raccordement aux alarmes numériques + +Cette section décrit comment raccorder HALMET à différents signaux de type tout ou rien, comme les alarmes moteur ou de cale. + +#### Configuration matérielle + +En général, les différents signaux de type tout ou rien, comme les alarmes moteur ou de cale, peuvent être raccordés directement aux entrées numériques de HALMET. Une résistance de tirage vers le haut (pull-up) ou vers le bas (pull-down) peut être nécessaire selon le type de signal. + +Sur la figure ci-dessous, dans l'exemple (a), une ampoule est déjà présente dans le circuit. Lorsque l'interrupteur est ouvert, l'ampoule tire la tension de D1 vers le bas. Aucune résistance de tirage vers le bas supplémentaire n'est nécessaire.[^1] En revanche, dans l'exemple (b), aucune autre charge n'est présente dans le circuit. Si l'interrupteur est ouvert, la tension de D2 reste flottante et l'entrée sera aléatoirement haute ou basse. Dans ce cas, il faut activer la résistance interne de tirage vers le bas en fermant le pont à souder situé au dos de la carte. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Entrées numériques dans différents cas d'usage. (a) Éclairage déjà présent dans le circuit. (b) Aucune autre charge dans le circuit, l'interrupteur tire le signal vers le haut lorsqu'il est fermé. (c) L'interrupteur tire le signal vers le bas lorsqu'il est fermé.
+
+ +[^1]: Si l'éclairage du tableau est réalisé avec des LED, la chute de tension aux bornes des LED peut ne pas suffire à faire descendre la tension à un niveau assez bas. Dans ce cas, il faut activer la résistance de tirage vers le bas. + +
+![](solder_jumpers.jpg){ width="60%" } +
Les ponts à souder situés au dos de la carte peuvent être fermés pour activer les résistances intégrées de tirage vers le haut ou vers le bas.
+
+ +De même, si l'interrupteur tire le signal vers le bas lorsqu'il est fermé, comme dans l'exemple (c), il peut être nécessaire d'activer la résistance interne de tirage vers le haut. + +Enfin, si les interrupteurs d'alarme sont normalement fermés, le traitement est inversé. À l'ouverture de l'interrupteur, la tension d'entrée sera tirée vers le haut ou vers le bas selon le circuit. Dans ce cas, il peut être nécessaire d'activer la résistance interne de tirage vers le haut ou vers le bas. + +#### Configuration logicielle + +Le firmware d'exemple HALMET fournit une méthode utilitaire `ConnectAlarmSender()` pour configurer et raccorder les entrées numériques. Voir `main.cpp` à partir de la ligne 177. Les signaux actifs à l'état haut comme à l'état bas sont pris en charge. + +### Entrées numériques utilisées comme compteurs + +Les entrées numériques de HALMET peuvent aussi servir de compteurs. C'est utile par exemple pour compter les tours du moteur ou les impulsions d'un compteur de chaîne. + +#### Configuration matérielle + +Ces capteurs sont généralement pilotés activement dans les deux sens, si bien qu'aucune résistance de tirage vers le haut ou vers le bas n'est nécessaire. Si vous raccordez HALMET à une sortie de faible impédance telle que la borne W de l'alternateur, il est conseillé d'ajouter un fusible en ligne pour protéger le fil des courts-circuits dus au ragage ou à d'autres dommages. À part cela, vous pouvez raccorder le capteur directement à l'entrée numérique. + +Si la source d'impulsions est très bruitée, ce qui fausse la lecture du régime moteur, un filtre passe-bas peut être activé en fermant le pont à souder LP situé au dos de la carte. Le filtre passe-bas a une fréquence de coupure d'environ 2,3 kHz, ce qui convient à des applications telles que les entrées reliées à la borne W d'un alternateur. + +#### Configuration logicielle + +Le firmware d'exemple HALMET met en œuvre un compteur d'impulsions activable sur une entrée numérique quelconque ou sur toutes. Voir l'exemple de configuration dans `main.cpp` à partir de la ligne 214. + +### Utilisation des entrées analogiques + +HALMET possède quatre entrées analogiques utilisables soit pour la mesure passive de tension, soit pour la mesure active de résistance. Cette section décrit leur utilisation dans différents cas d'usage courants. + +#### Configuration matérielle + +Les entrées analogiques A1–A4 sont reliées à un convertisseur analogique-numérique ADS1115. L'ADS1115 offre une résolution de 16 bits et une fréquence d'échantillonnage maximale de 860 échantillons par seconde. Les entrées analogiques de HALMET comportent toutefois un filtre passe-bas puissant dont la fréquence de coupure est d'environ 160 Hz. Cela reste largement suffisant pour mesurer la sortie de capteurs physiques tels que les capteurs de niveau de réservoir ou les capteurs de pression moteur. + +Sur la figure ci-dessous, l'exemple (a) montre un indicateur du tableau moteur existant raccordé à un capteur résistif. Les indicateurs de tableau moteur sont généralement soit thermostatiques, soit magnétiques. Dans les deux cas, l'indicateur et le capteur forment un diviseur de tension, et la tension aux bornes du capteur est proportionnelle à la grandeur mesurée. Cette tension peut être mesurée par les entrées analogiques de HALMET sans perturber le fonctionnement de l'indicateur d'origine. Du fait du diviseur de tension, la tension peut ne pas être corrélée linéairement à la grandeur mesurée, mais cela peut être compensé de manière logicielle. + +
+![](analog_input.svg){ width="60%" } +
Raccordement des entrées analogiques avec et sans indicateur existant. (a) Avec un indicateur existant, utilisez HALMET en mode de mesure passive de tension. (b) En l'absence de tout autre appareil, utilisez HALMET en mode de mesure active de résistance.
+
+ + +L'exemple (b) montre un cas sans indicateur existant. Le capteur est raccordé directement à l'entrée analogique de HALMET. Dans ce cas, HALMET doit fournir la tension d'excitation du capteur. HALMET réalise la mesure de résistance au moyen d'une source de courant constant (CCS) de 10 mA. Le courant de 10 mA crée une différence de tension de 1 volt aux bornes d'une résistance de 100 Ω, soit une résistance maximale d'environ 300 Ω. La source de courant constant s'active en plaçant un cavalier sur la paire de broches du connecteur à cavalier CCS. Voir la figure ci-dessous. + +
+![](ccs_jumpers.jpg){ width="60%" } +
La figure montre la source de courant constant activée pour les entrées analogiques A2 et A4.
+
diff --git a/docs/it/errata/index.md b/docs/it/errata/index.md new file mode 100644 index 0000000..b8e604f --- /dev/null +++ b/docs/it/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Problemi noti +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Problemi noti + +Questa pagina elenca tutti i difetti hardware noti delle diverse revisioni di HALMET. + +## Versione 1.0.0 + +Gli ingressi digitali 3 e 4 sono invertiti nella serigrafia sul retro della scheda. La piedinatura corretta è: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/it/getting-started/index.md b/docs/it/getting-started/index.md new file mode 100644 index 0000000..a5c2b86 --- /dev/null +++ b/docs/it/getting-started/index.md @@ -0,0 +1,75 @@ +--- +title: Primi passi +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Primi passi + +## Assemblaggio dell’hardware + +Per consentire una disposizione più flessibile dei connettori nelle custodie di piccole dimensioni, le schede HALMET vengono fornite senza i connettori a pettine 1-Wire e GPIO montati. Se si intende utilizzare una di queste due interfacce, occorre saldare alla scheda il relativo connettore a pettine. + +Per le istruzioni sulla saldatura dei connettori a pettine sulla scheda, consultare le [istruzioni di assemblaggio](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) di SH-ESP32. + +## Alimentazione della scheda + +HALMET viene alimentato attraverso il connettore NMEA 2000. Se si intende collegare HALMET a una rete NMEA 2000, la scheda può essere alimentata direttamente dalla rete. In tal caso, collegare i conduttori NMEA 2000 alla morsettiera estraibile a 4 pin come mostrato nella figura seguente. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Collegare i conduttori NMEA 2000 al connettore come mostrato.
+
+ +Se non si intende collegare HALMET a una rete NMEA 2000, utilizzare lo stesso connettore collegando i conduttori solo alle posizioni `-` e `+`. È possibile utilizzare qualsiasi sorgente di alimentazione da 5–32 V. L’assorbimento di corrente tipico della scheda con il WiFi attivo è di 0,07 A a 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Collegare i conduttori di alimentazione al connettore come mostrato.
+
+ +## Custodie + +Per l’uso su un’imbarcazione, HALMET va sempre collocato in una custodia impermeabile. +La scheda è progettata per adattarsi alla [custodia SH-ESP32](https://shop.hatlabs.fi/products/sh-esp32-enclosure). Di seguito un esempio di scheda HALMET installata nella custodia. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET installato nella custodia SH-ESP32.
+
+ +La custodia SH-ESP32 offre uno spazio limitato per i connettori. +Ciascuno dei lati lunghi può ospitare in pratica solo 2–3 connettori da pannello. +Se si intende collegare più di qualche ingresso, è consigliabile una custodia più grande. +Per esempio la [custodia compatta SH-RPi](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) di Hat Labs, mostrata di seguito, offre già ampio spazio per i connettori. + +
+![](medium_enclosure.jpg){ width="50%" } +
La custodia compatta SH-RPi offre più spazio per la disposizione dei connettori da pannello.
+
+ + +Altre custodie impermeabili adatte si trovano facilmente in qualsiasi negozio online. Anche le cassette di derivazione da esterno di dimensioni maggiori sono adatte allo scopo. + +### Foratura per i connettori da pannello + +Le custodie di solito non hanno fori predisposti. Per praticare i fori, +utilizzare sempre una punta conica o una punta a gradini (quella che sembra un piccolo albero di Natale metallico). Le normali punte per metallo tendono a mordere troppo e possono incrinare la parete della custodia. + +Nel pianificare la disposizione dei fori e dei connettori, lasciare spazio sufficiente per serrare i dadi dei connettori e per il corpo del connettore. Se si prevede il montaggio a parete della custodia, è consigliabile orientare i connettori verso il basso per ridurre al minimo la possibilità di infiltrazioni d’acqua. + +Diametri dei fori adatti ai vari connettori: + +- Pressacavo PG7 e connettore da pannello M12 (NMEA 2000): 12,5 mm o 1/2" +- Connettori da pannello SP13 (connettori di plastica blu e nera): 13 mm +- Pressacavo PG9: 16 mm o 5/8" + +I passacavi in gomma o in silicone consentono densità di cablaggio molto più elevate rispetto ai connettori da pannello o ai pressacavi. Non sono però impermeabili quanto i connettori da pannello o i pressacavi. Richiedono inoltre un fissaggio permanente del cavo, il che può rendere +più difficile la manutenzione dell’impianto. + +TODO: Aggiungere una foto di un passacavo in gomma. + +### Saldatura dei connettori da pannello + +Quando si saldano i conduttori interni ai connettori da pannello, utilizzare sempre la guaina termorestringente sui singoli conduttori. +Ricordare sempre di infilare la guaina sui conduttori _prima_ di saldare... +Di solito conviene depositare prima lo stagno nella cavità del pin del connettore, poi rifondere lo stagno e inserire il conduttore. diff --git a/docs/it/hardware/index.md b/docs/it/hardware/index.md new file mode 100644 index 0000000..5abd202 --- /dev/null +++ b/docs/it/hardware/index.md @@ -0,0 +1,240 @@ +--- +title: Descrizione dell’hardware +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hardware + +## Introduzione all’ESP32 + +HALMET è basato sul potente modulo microcontrollore ESP32-WROOM-32E. L’ESP32 è un microcontrollore dual-core con connettività WiFi e Bluetooth integrata. L’ESP32 è una scelta molto diffusa per le applicazioni IoT grazie al costo contenuto, al buon corredo di periferiche e alla facilità d’uso. + +## Blocchi funzionali della scheda + +Di seguito sono descritti i diversi blocchi funzionali della scheda. + +
+![](HALMET-func.jpg){ width="60%" } +
Blocchi funzionali dell’HALMET.
+
+ +1. Ingresso NMEA 2000 e di alimentazione con relative protezioni. Il connettore + NMEA 2000 dispone dei seguenti elementi di protezione: + - Fusibile autoripristinante da 500 mA + - Diodo di protezione contro l’inversione di polarità + - Diodi TVS di protezione contro le sovratensioni e le scariche elettrostatiche (ESD) + - Filtraggio dei disturbi a due stadi + +2. Alimentatore. Un alimentatore switching con corrente di uscita massima di 2 A. + +3. Transceiver CAN per NMEA 2000. I LED RX e TX forniscono un’indicazione visiva + dell’attività del bus CAN. + +4. Interfacce I2C e 1-Wire per il collegamento di sensori aggiuntivi. + +5. Interfaccia utente. Un pulsante Reset, un pulsante Boot / pulsante generico, un + LED rosso di alimentazione e un LED blu programmabile dall’utente. + +6. Interfaccia USB 2.0 per la programmazione e il debug. + +7. Modulo ESP32-WROOM-32E con WiFi e Bluetooth integrati. Il modulo montato sulla + scheda HALMET dispone di 16 MB di memoria flash. + +8. Circuiti di isolamento galvanico per gli ingressi digitali e analogici. + +9. Ingressi analogici. La scheda dispone di quattro ingressi analogici con + risoluzione a 16 bit e tensione di ingresso massima di 33 V. Ogni ingresso è + dotato di protezione contro le sottotensioni e le sovratensioni e di un + filtraggio passa-basso con frequenza di taglio a 160 Hz per ridurre i disturbi + di misura. + + Gli ingressi analogici dispongono di un generatore di corrente costante (CCS) + opzionale da 10 mA per la misura attiva di resistenza. Il generatore di corrente + costante si abilita tramite i connettori a pettine per jumper CCS. + + In modalità di misura di resistenza, la resistenza massima misurabile è 300 Ω. + +10. Ingressi digitali. HALMET dispone di quattro ingressi digitali con tensione di + ingresso massima di ±32 V. Gli ingressi sono dotati di uno Schmitt trigger per + migliorare l’immunità ai disturbi. + + +## Isolamento galvanico + +La scheda presenta un isolamento galvanico tra gli ingressi digitali e analogici e +il microcontrollore ESP32. L’isolamento è realizzato con isolatori digitali, +rispettivamente per il bus I2C e per i quattro ingressi digitali, e con un +convertitore DC/DC isolato che alimenta la sezione isolata. + +Grazie a questo isolamento, la scheda può essere alimentata dalla rete NMEA 2000 +senza rischio di anelli di massa. L’isolamento protegge inoltre dai picchi di +tensione e dai disturbi presenti sugli ingressi. + +
+![](HALMET-isolation.jpg){ width="60%" } +
Barriera di isolamento dell’HALMET. I connettori di ingresso sono isolati dal resto +della scheda, ovvero non condividono una massa comune con il resto della scheda.
+
+ +## Connettori + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
Connettori dell’HALMET, lato superiore.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
Connettori dell’HALMET, lato inferiore.
+
+ +
+
+ +### Connettori del lato superiore + +1. Connettore NMEA 2000. Si tratta di una morsettiera estraibile a 4 pin + compatibile Phoenix MC 3,81. Il connettore serve a collegare la scheda a una + rete NMEA 2000 e ad alimentarla. + +2. Connettore a pettine 1-Wire. Il pettine 1-Wire consente di collegare sensori + 1-Wire alla scheda. Il connettore è un pettine a 3 pin con passo 2,54 mm. Il + pettine non è montato sulla scheda di serie, perché può interferire con il + posizionamento dei connettori da pannello della custodia. + +3. Connettore a pettine I2C. Il pettine I2C consente di collegare sensori I2C alla + scheda. Il connettore è un pettine a 4 pin con passo 2,54 mm. + +4. Connettore Micro USB. Il connettore serve per la programmazione e il debug della + scheda. + +5. Piazzole libere per i segnali di reset (EN) e di boot (IO0). + +6. Connettore a pettine GPIO. Il pettine GPIO è un connettore a 2 × 10 pin con + passo 2,54 mm. Il pettine rende disponibili i pin GPIO liberi dell’ESP32 e può + essere usato anche come connettore JTAG. + +7. Connettore a pettine di alimentazione dell’area isolata. Il pettine consente di + alimentare dispositivi esterni dai contatti 3V3 e GND della sezione isolata. + +8. Contatti del pettine per jumper del generatore di corrente costante (CCS) degli + ingressi analogici. Il generatore di corrente costante si abilita + cortocircuitando i contatti del jumper. + +9. Connettori degli ingressi analogici. I connettori sono morsettiere estraibili a + 2 pin compatibili Phoenix MC 3,81. Servono a collegare sensori analogici alla + scheda. + +10. Connettori degli ingressi digitali. I connettori sono morsettiere estraibili a + 2 pin compatibili Phoenix MC 3,81. Servono a collegare sensori digitali alla + scheda. + +### Connettori del lato inferiore + +11. Jumper a saldare della terminazione CAN. Chiudendo il jumper a saldare si + abilita la resistenza di terminazione da 120 Ω del bus CAN. Non utilizzare la + resistenza di terminazione con le reti NMEA 2000. + +12. Jumper a saldare del filtro passa-basso. Chiudendo il jumper a saldare si + abilita un filtro passa-basso sul rispettivo ingresso analogico. Il filtro ha + una frequenza di taglio di 2,3 kHz e può essere usato ad esempio per ridurre i + disturbi in un segnale del contagiri. + +13. Jumper a saldare della resistenza di pull-down. Chiudendo il jumper a saldare si + abilita una resistenza di pull-down da 100 kΩ sul rispettivo ingresso digitale. + La resistenza di pull-down consente di leggere un interruttore normalmente + aperto (NA) che alla chiusura viene portato a livello alto. + +14. Jumper a saldare della resistenza di pull-up. Chiudendo il jumper a saldare si + abilita una resistenza di pull-up da 100 kΩ sul rispettivo ingresso digitale. + La resistenza di pull-up consente di leggere un interruttore normalmente chiuso + (NC) che alla chiusura viene portato a livello basso. + +15. Jumper a saldare per la selezione dell’indirizzo I2C dell’ADS1115. Chiudendo i + jumper a saldare si seleziona l’indirizzo I2C del convertitore + analogico-digitale (ADC) ADS1115. Servono a evitare conflitti di indirizzo + quando allo stesso bus I2C sono collegati più ADC ADS1115. Le piazzole possono + essere usate anche per collegare ulteriori dispositivi I2C all’area isolata + della scheda. + +### Riferimento GPIO + +HALMET riserva alcuni pin GPIO per le periferiche di ingresso. I pin GPIO liberi sono +portati sul pettine GPIO a 2 × 10 pin. La tabella seguente elenca i pin GPIO e le +rispettive funzioni. + +| GPIO | Funzione | Note | +| ------: | :----------- | :------------------------------------------------------ | +| 0 | Pulsante Boot | Entra nel bootloader quando è portato a livello basso | +| 1 | TXD0 | Trasmissione dati verso USB | +| 2 | LED | LED rosso sulla scheda | +| 3 | RXD0 | Ricezione dati da USB | +| 4 | 1-Wire DQ | Linea dati 1-Wire | +| 5 | - | Disponibile sul pettine GPIO | +| 12 | - / TDI | Disponibile sul pettine GPIO. In alternativa: JTAG TDI | +| 13 | - / TCK | Disponibile sul pettine GPIO. In alternativa: JTAG TCK | +| 14 | - / TMS | Disponibile sul pettine GPIO. In alternativa: JTAG TMS | +| 15 | - / TDO | Disponibile sul pettine GPIO. In alternativa: JTAG TDO | +| 16 | - | Disponibile sul pettine GPIO | +| 17 | - | Disponibile sul pettine GPIO | +| 18 | CAN RX | Ricezione da NMEA 2000 | +| 19 | CAN TX | Trasmissione verso NMEA 2000 | +| 21 | I2C SDA | Linea dati I2C. Usata per gli ingressi analogici | +| 22 | I2C SCL | Linea di clock I2C. Usata per gli ingressi analogici | +| 23 | DI1 | Ingresso digitale 1 | +| 25 | DI2 | Ingresso digitale 2 | +| 27 | DI3 | Ingresso digitale 3 | +| 26 | DI4 | Ingresso digitale 4 | +| 32 | - | Disponibile sul pettine GPIO | +| 33 | - | Disponibile sul pettine GPIO | +| 34 | - | Disponibile sul pettine GPIO | +| 35 | - | Disponibile sul pettine GPIO | +| 36 (VP) | Solo ingresso | Disponibile sul pettine GPIO | +| 39 (VN) | Solo ingresso | Disponibile sul pettine GPIO | + + +## Alimentazione + +L’intervallo di tensione di ingresso ammesso sulla scheda è 5–32 V. L’assorbimento +di corrente tipico è di 90 mA a 12 V con il modulo WiFi attivo (corrisponde a 1,1 W). + +## NMEA 2000 + +NMEA 2000 è uno standard di comunicazione diffusissimo, usato per collegare sensori, dispositivi di controllo e display su imbarcazioni e navi. Si basa sul Controller Area Network (bus CAN), uno standard di bus per veicoli progettato per consentire ai dispositivi di comunicare tra loro senza un computer host. + +La scheda è conforme allo standard NMEA 2000 finché nessuno dei connettori non +isolati è collegato ad altri dispositivi riferiti a massa. Ad esempio, è possibile +utilizzare un sensore di temperatura 1-Wire con un cavo lungo, poiché non condivide +una massa comune con altri dispositivi. Collegare invece un convertitore +analogico-digitale I2C al connettore I2C non isolato farebbe decadere la conformità +NMEA 2000. + +TODO: piedinatura GPIO di NMEA 2000 + +## LED di stato + +Sulla scheda HALMET sono presenti due pulsanti e due LED. I due pulsanti sono contrassegnati con “Reset” e “Boot”. Il pulsante Reset riavvia la scheda portando a livello basso il pin Enable dell’ESP32. Il pulsante Boot è collegato a GPIO0 e, durante l’accensione del dispositivo, consente di forzare il modulo in modalità download. Negli altri casi può essere usato come normale ingresso a pulsante. + +I due LED non sono contrassegnati esplicitamente. Il LED rosso è acceso ogni volta che sulla scheda è presente l’alimentazione a 3,3 V. Il LED blu è collegato a GPIO2 (il pin comunemente usato per il LED sulle schede di sviluppo ESP32). Può essere controllato dai programmi dell’utente per segnalare lo stato del dispositivo. + +## 1-Wire + +1-Wire è un sistema di bus per la comunicazione tra dispositivi progettato da Dallas Semiconductor, poi acquisita da Maxim Integrated Products. Sebbene 1-Wire sia un protocollo lento, che supporta velocità fino a soli 16,3 kbit/s, è molto semplice da implementare e può essere usato su lunghe distanze. È comunemente impiegato per sensori di temperatura e altri dispositivi di rilevamento altrettanto semplici. + +L’implementazione 1-Wire dell’HALMET dispone di filtraggio ESD e dei disturbi RF, oltre a un filtraggio passa-basso, per migliorare l’affidabilità della rete. + +Si noti che il pin dati 1-Wire (contrassegnato con “DQ”) è fisicamente mappato su GPIO4: nel proprio programma occorre quindi usare GPIO4 per tutti i dati 1-Wire. + +## I2C + +I2C (Inter-Integrated Circuit) è un bus di comunicazione seriale sincrono molto diffuso, comunemente usato per interfacciarsi con numerosi circuiti integrati diversi. Utilizza due conduttori dati oltre all’alimentazione e alla massa. + +HALMET utilizza il bus I2C internamente per il convertitore analogico-digitale ADS1115. Il bus I2C è portato anche su un pettine a 4 pin per il collegamento di ulteriori dispositivi I2C. + +Il bus I2C è collegato a GPIO21 (SDA) e GPIO22 (SCL) dell’ESP32. Questi sono i pin I2C predefiniti nell’ambiente Arduino ESP32, ma sono diversi dai pin predefiniti di SH-ESP32. diff --git a/docs/it/index.md b/docs/it/index.md new file mode 100644 index 0000000..7a49f8d --- /dev/null +++ b/docs/it/index.md @@ -0,0 +1,35 @@ +--- +title: Introduzione +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Introduzione + +HALMET, la Hat Labs Marine Engine & Tank interface, è una scheda di sviluppo per collegare sensori di motore e di serbatoio su imbarcazioni e altri veicoli. Può essere utilizzato per leggere sensori digitali e analogici e per collegarsi ad altri dispositivi tramite le interfacce NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire o GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Immagine di HALMET
+
+ +## Caratteristiche principali + +- **Quattro ingressi digitali**: HALMET ha quattro ingressi digitali per leggere segnali di allarme digitali o per l’impiego come contatori. Gli ingressi tollerano tensioni comprese tra −32 V e +32 V. Gli ingressi digitali permettono di rilevare sia i livelli del segnale sia segnali variabili nel tempo, come il regime del motore, la portata del carburante o gli impulsi del contacatena. + +- **Quattro ingressi analogici**: HALMET ha quattro ingressi analogici per la lettura di sensori analogici. Gli ingressi tollerano tensioni comprese tra −32 V e +32 V, con un intervallo di misura da 0 a 33 V. Gli ingressi sono collegati a un convertitore analogico-digitale (ADC) ADS1115 a 16 bit. Gli ingressi analogici possono essere utilizzati sia per misure passive di tensione sia per misure attive di resistenza. + +- **Compatibile con NMEA 2000**: HALMET è pienamente compatibile con lo standard NMEA 2000. La scheda può essere collegata a una rete NMEA 2000 attraverso l’interfaccia NMEA 2000 integrata. + +- **Interfacce I2C, 1-Wire e GPIO**: HALMET dispone di un’interfaccia I2C a 4 pin, di un’interfaccia 1-Wire a 3 pin e di 13 porte di ingresso/uscita generiche (GPIO) libere. + +- **Connettività WiFi e Bluetooth**: HALMET integra un modulo ESP32-WROOM-32E con connettività WiFi e Bluetooth. Queste permettono sia di collegarsi a reti WiFi esistenti sia di creare un access point WiFi per collegarsi direttamente alla scheda. + +- **ESP32-WROOM-32E con 16 MB di memoria flash**: il modulo ESP32-WROOM-32E offre potenza di calcolo e memoria in abbondanza anche per le applicazioni più esigenti. I 16 MB di memoria flash permettono di memorizzare localmente grandi quantità di dati. + +- **Ampio intervallo di tensione di ingresso**: HALMET può essere alimentato in sicurezza dall’impianto a 12 V o 24 V comunemente presente su veicoli e imbarcazioni. HALMET tollera tensioni di ingresso comprese tra 5 V e 32 V. + +HALMET è hardware aperto, distribuito con licenza Creative Commons Attribution-ShareAlike 4.0 International. + +## Come procurarsi l’hardware + +Le schede HALMET si possono acquistare da [Hat Labs Oy](https://shop.hatlabs.fi). Tutti i file di progetto sono disponibili anche nel [repository GitHub dell’hardware HALMET](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/it/revisions/index.md b/docs/it/revisions/index.md new file mode 100644 index 0000000..64f61ea --- /dev/null +++ b/docs/it/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Revisioni hardware +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Revisioni hardware + +## Introduzione + +Questa pagina documenta le diverse revisioni della scheda e fornisce i collegamenti agli schemi elettrici. La cronologia completa dei file di progetto è disponibile nel [repository GitHub HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Versione 1.0.0 + +Prima versione pubblicata. + +Schemi elettrici: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Versione 1.0.1 + +Correzioni e migliorie alla serigrafia. Aggiunte le piazzole 3V3 e GND nell’area isolata. + +Schemi elettrici: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/it/software/index.md b/docs/it/software/index.md new file mode 100644 index 0000000..32032ea --- /dev/null +++ b/docs/it/software/index.md @@ -0,0 +1,16 @@ +--- +title: Software +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Software + +## Introduzione + +Essendo una scheda di sviluppo, HALMET viene fornito senza alcun software preinstallato. Il software adatto va installato dall’utente. L’operazione non è difficile, ma è consigliabile una certa esperienza con schede a microcontrollore come Arduino o ESP32 Devkit. + +Il firmware di esempio per HALMET è disponibile nel [repository GitHub HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Si noti che l’assistenza per i problemi di sviluppo software viene fornita esclusivamente tramite il [forum di discussione di Hat Labs](https://github.com/hatlabs/discussions/discussions). + +Ulteriori istruzioni saranno pubblicate a breve. diff --git a/docs/it/tutorials/index.md b/docs/it/tutorials/index.md new file mode 100644 index 0000000..f809ba6 --- /dev/null +++ b/docs/it/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Tutorial e progetti di esempio +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +I tutorial e i progetti di esempio per HALMET saranno elencati in questa pagina. diff --git a/docs/it/usage/index.md b/docs/it/usage/index.md new file mode 100644 index 0000000..95fb03e --- /dev/null +++ b/docs/it/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Utilizzo +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Utilizzo + +## Casi d’uso comuni + +Questa sezione contiene informazioni pratiche sulla lettura di diversi tipi di sensori e sul collegamento di HALMET ad altri dispositivi. + +### Configurazione del software + +HALMET è una scheda di sviluppo e non viene fornito con alcun software preinstallato. +Il software adatto va installato dall’utente. L’operazione non è difficile, ma è consigliabile una certa esperienza con schede a microcontrollore come Arduino o ESP32 Devkit. + +La documentazione di HALMET presuppone l’utilizzo del [firmware di esempio per HALMET](https://github.com/hatlabs/HALMET-example-firmware). Questo firmware è basato sul framework [SensESP](https://signalk.org/SensESP/) e offre un accesso relativamente immediato alle funzioni della scheda. + +La [guida introduttiva di SensESP](https://signalk.org/SensESP/pages/getting_started/) contiene istruzioni dettagliate per installare l’ambiente di sviluppo necessario a compilare e installare il firmware. Le istruzioni sono scritte per dispositivi ESP32 generici, ma valgono anche per HALMET. È sufficiente utilizzare il [firmware di esempio per HALMET](https://github.com/hatlabs/HALMET-example-firmware) al posto del modello di progetto SensESP. + +Si noti che, sebbene la documentazione di SensESP presupponga l’uso di Signal K, HALMET è perfettamente utilizzabile anche come dispositivo NMEA 2000 autonomo. + +Se si preferisce non usare SensESP, è possibile realizzare un firmware personalizzato con Arduino IDE o ESP-IDF. Per molti casi d’uso anche ESPHome è un’ottima soluzione. + +**NOTA:** l’assegnazione dei pin GPIO su HALMET è leggermente diversa da quella dell’ESP32 Devkit e di SH-ESP32. Se si adatta un software diverso dal firmware di esempio per HALMET, occorre verificare con attenzione l’assegnazione dei pin. Per maggiori informazioni vedere il [riferimento GPIO](../hardware/index.md#riferimento-gpio). + +### Uso degli ingressi digitali + +HALMET ha quattro ingressi digitali. Questi ingressi possono essere utilizzati per leggere segnali di allarme digitali oppure come contatori. Questa sezione descrive l’uso degli ingressi nei diversi casi d’uso comuni. Le istruzioni presuppongono l’utilizzo del firmware di esempio per HALMET. + +Gli ingressi digitali D1–D4 sono collegati rispettivamente ai pin GPIO 23, 25, 27 e 26. Gli ingressi tollerano tensioni comprese tra −32 V e +32 V. La tensione di soglia per il rilevamento di un segnale alto è di circa 1,55 V, con un’isteresi di circa 0,7 V. + +### Collegamento ad allarmi digitali + +Questa sezione descrive come collegare HALMET a diversi segnali di tipo on/off, come gli allarmi del motore o di sentina. + +#### Configurazione dell’hardware + +Di norma i vari segnali di tipo on/off, come gli allarmi del motore o di sentina, possono essere collegati direttamente agli ingressi digitali di HALMET. A seconda del tipo di segnale può essere necessario un pull-up o un pull-down. + +Nella figura seguente, nell’esempio (a) è già presente una lampadina nel circuito. Quando l’interruttore è aperto, la lampadina porta a livello basso la tensione su D1. Non serve alcun pull-down aggiuntivo.[^1] Nell’esempio (b), invece, nel circuito non è presente nessun altro carico. Se l’interruttore è aperto, la tensione su D2 resta flottante e l’ingresso risulta casualmente alto o basso. In questo caso occorre abilitare la resistenza di pull-down interna chiudendo il jumper a saldare sul retro della scheda. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Ingressi digitali in diversi casi d’uso. (a) Lampada già presente nel circuito. (b) Nessun altro carico nel circuito, l’interruttore porta il segnale a livello alto quando si chiude. (c) L’interruttore porta il segnale a livello basso quando si chiude.
+
+ +[^1]: Se le luci del quadro sono realizzate con LED, la caduta di tensione ai capi dei LED può non bastare a portare la tensione a un livello sufficientemente basso. In questo caso occorre abilitare la resistenza di pull-down. + +
+![](solder_jumpers.jpg){ width="60%" } +
I jumper a saldare sul retro della scheda possono essere chiusi per abilitare le resistenze di pull-up o di pull-down integrate.
+
+ +Analogamente, se l’interruttore porta il segnale a livello basso quando si chiude, come nell’esempio (c), può essere necessario abilitare il pull-up interno. + +Infine, se gli interruttori di allarme sono normalmente chiusi (NC), il trattamento si inverte. Quando l’interruttore si apre, la tensione di ingresso viene portata a livello alto o basso a seconda del circuito. In questo caso può essere necessario abilitare il pull-up o il pull-down interno. + +#### Configurazione del software + +Il firmware di esempio per HALMET mette a disposizione il metodo di comodo `ConnectAlarmSender()` per configurare e collegare gli ingressi digitali. Vedere `main.cpp` a partire dalla riga 177. Sono supportati sia i segnali attivi alti sia quelli attivi bassi. + +### Ingressi digitali come contatori + +Gli ingressi digitali di HALMET possono essere utilizzati anche come contatori. Questo è utile, per esempio, per contare i giri del motore o gli impulsi del contacatena. + +#### Configurazione dell’hardware + +Di norma queste sonde sono pilotate attivamente in entrambe le direzioni, quindi non serve alcun pull-up o pull-down. Se si collega HALMET a un’uscita a bassa impedenza come il morsetto W dell’alternatore, è consigliabile aggiungere un fusibile in linea per proteggere il conduttore da cortocircuiti dovuti a sfregamento o ad altri danni. A parte questo, la sonda può essere collegata direttamente all’ingresso digitale. + +Se la sorgente di impulsi è molto disturbata e il numero di giri risulta instabile, è possibile abilitare un filtro passa-basso chiudendo il jumper a saldare LP sul retro della scheda. Il filtro passa-basso ha una frequenza di taglio di circa 2,3 kHz, adatta ad applicazioni come gli ingressi collegati al morsetto W dell’alternatore. + +#### Configurazione del software + +Il firmware di esempio per HALMET implementa un contatore di impulsi che può essere attivato su uno qualsiasi degli ingressi digitali o su tutti. Vedere la configurazione di esempio in `main.cpp` a partire dalla riga 214. + +### Uso degli ingressi analogici + +HALMET ha quattro ingressi analogici, utilizzabili sia per misure passive di tensione sia per misure attive di resistenza. Questa sezione descrive l’uso degli ingressi nei diversi casi d’uso comuni. + +#### Configurazione dell’hardware + +Gli ingressi analogici A1–A4 sono collegati a un convertitore analogico-digitale (ADC) ADS1115. L’ADS1115 ha una risoluzione a 16 bit e una frequenza di campionamento massima di 860 campioni al secondo. Gli ingressi analogici di HALMET integrano però un filtro passa-basso molto marcato, con una frequenza di taglio di circa 160 Hz. Questo resta comunque più che sufficiente per misurare le uscite di sensori fisici come i sensori di livello del serbatoio o i sensori di pressione del motore. + +Nella figura seguente, l’esempio (a) mostra un indicatore del quadro motore già presente, collegato a una sonda resistiva. Gli indicatori del quadro motore sono di solito di tipo termostatico o magnetico. In entrambi i casi l’indicatore e la sonda funzionano da partitore di tensione, e la tensione ai capi della sonda è proporzionale alla grandezza misurata. Questa tensione può essere misurata con gli ingressi analogici di HALMET senza interferire con il funzionamento dell’indicatore originale. A causa del partitore di tensione la tensione può non essere correlata linearmente alla grandezza misurata, ma è possibile compensare via software. + +
+![](analog_input.svg){ width="60%" } +
Collegamento degli ingressi analogici con e senza un indicatore già presente. (a) Con un indicatore già presente, utilizzare HALMET in modalità di misura passiva di tensione. (b) Se non è presente nessun altro dispositivo, utilizzare HALMET in modalità di misura attiva di resistenza.
+
+ + +L’esempio (b) mostra un caso in cui l’indicatore non è presente. La sonda è collegata direttamente all’ingresso analogico di HALMET. In questo caso HALMET deve fornire la tensione di eccitazione alla sonda. HALMET realizza la misura di resistenza con un generatore di corrente costante (CCS) da 10 mA. La corrente di 10 mA produce una differenza di tensione di 1 volt ai capi di una resistenza da 100 Ω, per una resistenza massima di circa 300 Ω. Il generatore di corrente costante si abilita inserendo un jumper sulla coppia di pin del connettore a pettine CCS (generatore di corrente costante). Vedere la figura seguente. + +
+![](ccs_jumpers.jpg){ width="60%" } +
La figura mostra il generatore di corrente costante abilitato per gli ingressi analogici A2 e A4.
+
diff --git a/docs/nb/errata/index.md b/docs/nb/errata/index.md new file mode 100644 index 0000000..1f65b73 --- /dev/null +++ b/docs/nb/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Kjente feil +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Kjente feil + +Denne siden lister opp alle kjente maskinvarefeil i de ulike HALMET-versjonene. + +## Versjon 1.0.0 + +Digitale innganger 3 og 4 er byttet om på silketrykket på undersiden. Riktig pinnebelegg er: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/nb/getting-started/index.md b/docs/nb/getting-started/index.md new file mode 100644 index 0000000..1a539d9 --- /dev/null +++ b/docs/nb/getting-started/index.md @@ -0,0 +1,73 @@ +--- +title: Kom i gang +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Kom i gang + +## Montering av maskinvaren + +For å gi mer fleksibel plassering av kontaktene i små kabinetter leveres HALMET-kortene uten 1-Wire- og GPIO-pinnelister montert. Hvis du planlegger å bruke ett av disse grensesnittene, må du lodde pinnelisten fast på kortet. + +Hvis du trenger veiledning i å lodde pinnelister på kortet, kan du se [monteringsanvisningen](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) for SH-ESP32. + +## Strømforsyning til kortet + +HALMET forsynes med strøm gjennom NMEA 2000-kontakten. Hvis du skal koble HALMET til et NMEA 2000-nettverk, kan du forsyne kortet direkte fra nettverket. Koble i så fall NMEA 2000-ledningene til den 4-pinners pluggbare koblingsklemmen som vist i figuren nedenfor. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Koble NMEA 2000-ledningene til kontakten som vist.
+
+ +Hvis du ikke skal koble HALMET til et NMEA 2000-nettverk, bruker du den samme kontakten, men kobler bare ledninger til `-` og `+`. Enhver strømkilde på 5–32 V kan brukes. Typisk strømforbruk for kortet med WiFi aktivt er 0,07 A ved 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Koble strømledningene til kontakten som vist.
+
+ +## Kabinetter + +Ved bruk i båt bør HALMET alltid plasseres i et vanntett kabinett. +Kortet er laget for å passe i [SH-ESP32-kabinettet](https://shop.hatlabs.fi/products/sh-esp32-enclosure). Nedenfor ser du et eksempel på et HALMET-kort montert i kabinettet. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET montert i SH-ESP32-kabinettet.
+
+ +SH-ESP32-kabinettet har begrenset plass til kontakter. +Hver av langsidene har i praksis bare plass til 2–3 panelkontakter. +Hvis du har tenkt å koble til mer enn noen få innganger, anbefales et større kabinett. +For eksempel har [det kompakte SH-RPi-kabinettet](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) fra Hat Labs, vist nedenfor, allerede rikelig med plass til kontakter. + +
+![](medium_enclosure.jpg){ width="50%" } +
Det kompakte SH-RPi-kabinettet gir mer plass til plassering av panelkontakter.
+
+ + +Andre egnede vanntette kabinetter er lette å finne i en hvilken som helst nettbutikk. Større koblingsbokser for utendørs bruk egner seg også til formålet. + +### Bore hull for panelkontakter + +Kabinettene har vanligvis ikke ferdigborede hull. Når du borer hull, bruker du alltid et konisk bor eller et trinnbor (det som ser ut som et lite juletre i metall). Vanlige metallbor kan lett bite for hardt og sprekke kabinettveggen. + +Når du planlegger plasseringen av hull og kontakter, må du la det være nok plass til å stramme kontaktmutrene og til selve kontakthuset. Hvis du planlegger å veggmontere kabinettet, anbefales det å plassere kontaktene vendt nedover for å redusere faren for vanninntrengning. + +Passende hullstørrelser for ulike kontakter: + +- PG7-kabelgjennomføring og M12-panelkontakt (NMEA 2000): 12,5 mm eller 1/2" +- SP13-panelkontakter (blåsvarte plastkontakter): 13 mm +- PG9-kabelgjennomføring: 16 mm eller 5/8" + +Gummigjennomføringer eller silikongjennomføringer gir vesentlig høyere kabeltetthet enn panelkontakter og kabelgjennomføringer. De er imidlertid ikke like vanntette som panelkontakter og kabelgjennomføringer. I tillegg krever de permanent kabelfeste, noe som kan gjøre service på systemet vanskeligere. + +TODO: Legg til et bilde av en gummigjennomføring. + +### Lodde panelkontaktene + +Når du lodder de innvendige ledningene til panelkontaktene, bruker du alltid krympestrømpe på hver enkelt ledning. +Husk alltid å tre krympestrømpen på ledningen _før_ du lodder... +Vanligvis kan du først fylle litt loddetinn i pinnehulrommet i kontakten og deretter smelte loddetinnet på nytt og føre ledningen inn. diff --git a/docs/nb/hardware/index.md b/docs/nb/hardware/index.md new file mode 100644 index 0000000..f4cbaff --- /dev/null +++ b/docs/nb/hardware/index.md @@ -0,0 +1,234 @@ +--- +title: Maskinvarebeskrivelse +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Maskinvare + +## Introduksjon til ESP32 + +HALMET bygger på den kraftige mikrokontrollermodulen ESP32-WROOM-32E. ESP32 er en tokjernet mikrokontroller med innebygd WiFi og Bluetooth. ESP32 er et populært valg for IoT-anvendelser på grunn av lav pris, et godt utvalg av periferienheter og enkel bruk. + +## Kortets funksjonsblokker + +De ulike funksjonsblokkene på kortet er beskrevet nedenfor. + +
+![](HALMET-func.jpg){ width="60%" } +
Funksjonsblokker på HALMET.
+
+ +1. NMEA 2000 og strøminngang med vern. NMEA 2000-kontakten har følgende + vernkomponenter: + - Selvtilbakestillende sikring på 500 mA + - Diode for polvendingsvern + - TVS-dioder for overspenningsvern og ESD-vern + - Totrinns filtrering av elektrisk støy + +2. Strømforsyning. En switchet strømforsyning med maksimal utgangsstrøm på 2 A. + +3. CAN-transceiver for NMEA 2000. RX- og TX-LED-er gir en visuell indikasjon på + aktiviteten på CAN-bussen. + +4. I2C- og 1-Wire-grensesnitt for tilkobling av flere sensorer. + +5. Brukergrensesnitt. En resetknapp, en boot-knapp som også kan brukes til + generelle formål, en rød strøm-LED og en blå brukerprogrammerbar LED. + +6. USB 2.0-grensesnitt for programmering og feilsøking. + +7. ESP32-WROOM-32E-modul med innebygd WiFi og Bluetooth. Modulen på + HALMET-kortet har 16 MB flashminne. + +8. Kretser for galvanisk isolasjon av de digitale og analoge inngangene. + +9. Analoge innganger. Kortet har fire analoge innganger med 16 bits oppløsning + og en maksimal inngangsspenning på 33 V. Hver inngang har underspennings- og + overspenningsvern samt lavpassfiltrering med en grensefrekvens på 160 Hz for + å redusere målestøy. + + De analoge inngangene har en valgfri konstantstrømkilde på 10 mA for aktiv + motstandsmåling. Konstantstrømkilden kan aktiveres med CCS-jumperpinnene. + + I motstandsmålingsmodus er den største motstanden som kan måles, 300 Ω. + +10. Digitale innganger. HALMET har fire digitale innganger med en maksimal + inngangsspenning på ±32 V. Inngangene har en Schmitt trigger som bedrer + støyimmuniteten. + + +## Galvanisk isolasjon + +Kortet har galvanisk isolasjon mellom de digitale og analoge inngangene og +ESP32-mikrokontrolleren. Isolasjonen er realisert med digitale isolatorer for +henholdsvis I2C og de fire digitale inngangene, og med en isolert DC/DC-omformer +som forsyner den isolerte seksjonen. + +Takket være isolasjonen kan kortet forsynes fra NMEA 2000-nettverket uten fare +for jordsløyfer. Isolasjonen gir også vern mot spenningsspisser og støy på +inngangene. + +
+![](HALMET-isolation.jpg){ width="60%" } +
HALMETs isolasjonsbarriere. Inngangsklemmene er isolert fra resten av kortet +og har dermed ikke felles jord med resten av kortet.
+
+ +## Kontakter + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
HALMETs kontakter, oversiden.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
HALMETs kontakter, undersiden.
+
+ +
+
+ +### Kontakter på oversiden + +1. NMEA 2000-kontakt. Kontakten er en 4-pinners pluggbar koblingsklemme som er + kompatibel med Phoenix MC 3,81. Den brukes til å koble kortet til et + NMEA 2000-nettverk og til å forsyne kortet med strøm. + +2. 1-Wire-pinneliste. 1-Wire-pinnelisten kan brukes til å koble 1-Wire-sensorer + til kortet. Den er en 3-pinners pinneliste med 2,54 mm senteravstand. + Pinnelisten er ikke montert på kortet fra fabrikk, fordi den kan komme i + veien for plasseringen av panelkontaktene i kabinettet. + +3. I2C-pinneliste. I2C-pinnelisten kan brukes til å koble I2C-sensorer til + kortet. Den er en 4-pinners pinneliste med 2,54 mm senteravstand. + +4. Micro USB-kontakt. Kontakten brukes til å programmere og feilsøke kortet. + +5. Ubestykkede loddeflater for reset- (EN) og boot-signalene (IO0). + +6. GPIO-pinneliste. GPIO-pinnelisten har 2×10 pinner og 2,54 mm senteravstand. + Den fører ut de tilgjengelige GPIO-pinnene på ESP32 og kan også brukes som + JTAG-pinneliste. + +7. Pinneliste for strøm i det isolerte området. Pinnelisten kan brukes til å + forsyne eksterne enheter fra 3V3 og GND i den isolerte seksjonen. + +8. Jumperpinner for konstantstrømkilden (CCS) til de analoge inngangene. + Konstantstrømkilden aktiveres ved å sette en jumper over pinnene. + +9. Koblingsklemmer for de analoge inngangene. Klemmene er 2-pinners pluggbare + koblingsklemmer som er kompatible med Phoenix MC 3,81. De brukes til å koble + analoge sensorer til kortet. + +10. Koblingsklemmer for de digitale inngangene. Klemmene er 2-pinners pluggbare + koblingsklemmer som er kompatible med Phoenix MC 3,81. De brukes til å koble + digitale sensorer til kortet. + +### Kontakter på undersiden + +11. Loddebro for CAN-terminering. Loddebroen kan loddes sammen for å aktivere + termineringsmotstanden på 120 Ω for CAN-bussen. Ikke bruk + termineringsmotstanden i NMEA 2000-nettverk. + +12. Loddebro for lavpassfilter. Loddebroen kan loddes sammen for å aktivere et + lavpassfilter på den aktuelle analoge inngangen. Filteret har en + grensefrekvens på 2,3 kHz. Filteret kan for eksempel brukes til å redusere + støy i et turtellersignal. + +13. Loddebro for pull-down-motstand. Loddebroen kan loddes sammen for å + aktivere en pull-down-motstand på 100 kΩ på den aktuelle digitale + inngangen. Pull-down-motstanden kan brukes til å lese av en normalt åpen + (NO) bryter som trekkes høy når den lukkes. + +14. Loddebro for pull-up-motstand. Loddebroen kan loddes sammen for å aktivere + en pull-up-motstand på 100 kΩ på den aktuelle digitale inngangen. + Pull-up-motstanden kan brukes til å lese av en normalt lukket (NC) bryter + som trekkes lav når den lukkes. + +15. Loddebroer for valg av I2C-adresse for ADS1115. Loddebroene loddes sammen + for å velge I2C-adressen til AD-omformeren ADS1115. De brukes til å unngå + adressekonflikter når flere ADS1115-omformere er koblet til samme I2C-buss. + Loddeflatene kan også brukes til å koble flere I2C-enheter til det isolerte + området på kortet. + +### GPIO-oversikt + +HALMET reserverer en del GPIO-pinner til periferienhetene for inngangene. De ledige +GPIO-pinnene er ført ut til GPIO-pinnelisten med 2×10 pinner. Tabellen nedenfor +viser GPIO-pinnene og funksjonene deres. + +| GPIO | Funksjon | Merknader | +| ------: | :---------- | :------------------------------------------------- | +| 0 | Boot-knapp | Går til bootloader når den trekkes lav | +| 1 | TXD0 | Sender data til USB | +| 2 | LED | Rød LED på kortet | +| 3 | RXD0 | Mottar data fra USB | +| 4 | 1-Wire DQ | Datalinje for 1-Wire | +| 5 | - | Ledig på GPIO-pinnelisten | +| 12 | - / TDI | Ledig på GPIO-pinnelisten. Eventuelt: JTAG TDI | +| 13 | - / TCK | Ledig på GPIO-pinnelisten. Eventuelt: JTAG TCK | +| 14 | - / TMS | Ledig på GPIO-pinnelisten. Eventuelt: JTAG TMS | +| 15 | - / TDO | Ledig på GPIO-pinnelisten. Eventuelt: JTAG TDO | +| 16 | - | Ledig på GPIO-pinnelisten | +| 17 | - | Ledig på GPIO-pinnelisten | +| 18 | CAN RX | Mottak fra NMEA 2000 | +| 19 | CAN TX | Sending til NMEA 2000 | +| 21 | I2C SDA | Datalinje for I2C. Brukes til analog inngang | +| 22 | I2C SCL | Klokkelinje for I2C. Brukes til analoge innganger | +| 23 | DI1 | Digital inngang DI1 | +| 25 | DI2 | Digital inngang DI2 | +| 27 | DI3 | Digital inngang DI3 | +| 26 | DI4 | Digital inngang DI4 | +| 32 | - | Ledig på GPIO-pinnelisten | +| 33 | - | Ledig på GPIO-pinnelisten | +| 34 | - | Ledig på GPIO-pinnelisten | +| 35 | - | Ledig på GPIO-pinnelisten | +| 36 (VP) | Bare inngang | Ledig på GPIO-pinnelisten | +| 39 (VN) | Bare inngang | Ledig på GPIO-pinnelisten | + + +## Strømforsyning + +Det tillatte inngangsspenningsområdet for kortet er 5–32 V. Typisk strømforbruk +er 90 mA ved 12 V når WiFi-modulen er aktiv (tilsvarer 1,1 W). + +## NMEA 2000 + +NMEA 2000 er en utbredt kommunikasjonsstandard som brukes til å koble sammen sensorer, styreenheter og skjermenheter på båter og skip. Den bygger på Controller Area Network (CAN-bussen), en standard for kjøretøybusser som lar enheter kommunisere med hverandre uten en vertsdatamaskin. + +Kortet er i samsvar med NMEA 2000-standarden så lenge ingen av de uisolerte +kontaktene er koblet til andre enheter med felles jordreferanse. En +1-Wire-temperatursensor med lang kabel kan for eksempel brukes, siden den ikke +har felles jord med andre enheter. Å koble en I2C-AD-omformer til den uisolerte +I2C-pinnelisten vil derimot bryte samsvaret med NMEA 2000. + +TODO: GPIO-pinnebelegg for NMEA 2000 + +## Status-LED-er + +Det er to knapper og to LED-er på HALMET-kortet. Knappene er merket `Reset` og `Boot`. `Reset`-knappen tilbakestiller kortet ved å trekke Enable-pinnen på ESP32 lav. `Boot`-knappen er koblet til GPIO0 og kan brukes under oppstart av enheten til å tvinge modulen i nedlastingsmodus (download mode). Ellers kan den brukes som en vanlig knappeinngang. + +De to LED-ene er ikke merket. Den røde LED-en lyser når det er 3,3 V spenning på kortet. Den blå LED-en er koblet til GPIO2 (pinnen som vanligvis brukes til LED på ESP32-utviklingskort). Den kan styres av brukerprogrammer for å vise tilstanden til enheten. + +## 1-Wire + +1-Wire er et bussystem for kommunikasjon mellom enheter, utviklet av Dallas Semiconductor, som senere er kjøpt opp av Maxim Integrated Products. Selv om 1-Wire er en langsom protokoll som bare støtter hastigheter opp til 16,3 kbps, er den svært enkel å implementere og kan brukes over lange avstander. Den brukes ofte til temperatursensorer og lignende enkle måleenheter. + +HALMETs 1-Wire-implementasjon har ESD- og RF-støyfiltrering samt lavpassfiltrering for å bedre påliteligheten i nettverket. + +Merk at datapinnen for 1-Wire (merket «DQ») fysisk er koblet til GPIO4, så bruk GPIO4 for alle 1-Wire-data i programmet ditt. + +## I2C + +I2C (Inter-Integrated Circuit) er en svært populær synkron seriell kommunikasjonsbuss som ofte brukes til å kommunisere med en rekke ulike integrerte kretser. Den bruker to datalinjer i tillegg til spenning og jord. + +HALMET bruker I2C internt til AD-omformeren ADS1115. I2C-bussen er også ført ut til en 4-pinners pinneliste for tilkobling av flere I2C-enheter. + +I2C-bussen er koblet til GPIO21 (SDA) og GPIO22 (SCL) på ESP32. Disse pinnene er standardpinnene for I2C i Arduino ESP32-miljøet, men de skiller seg fra standardpinnene på SH-ESP32. diff --git a/docs/nb/index.md b/docs/nb/index.md new file mode 100644 index 0000000..c33c152 --- /dev/null +++ b/docs/nb/index.md @@ -0,0 +1,35 @@ +--- +title: Innledning +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Innledning + +HALMET, Hat Labs Marine Engine & Tank interface, er et utviklingskort for tilkobling av motor- og tankgivere på båter og andre kjøretøy. Det kan brukes til å lese digitale og analoge sensorer, og til å koble til andre enheter via NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire eller GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Bilde av HALMET
+
+ +## Viktigste egenskaper + +- **Fire digitale innganger**: HALMET har fire digitale innganger for lesing av digitale alarmsignaler eller for bruk som tellere. Inngangene tåler spenninger mellom −32 V og +32 V. De digitale inngangene kan brukes både til å registrere signalnivåer og til signaler som varierer over tid, for eksempel motorens turtall, drivstoffstrøm eller pulser fra en kjettingteller. + +- **Fire analoge innganger**: HALMET har fire analoge innganger for lesing av analoge sensorer. Inngangene tåler spenninger mellom −32 V og +32 V, med et måleområde på 0–33 V. Inngangene er koblet til en 16 bits AD-omformer av typen ADS1115. De analoge inngangene kan brukes både til passiv spenningsmåling og til aktiv motstandsmåling. + +- **NMEA 2000-kompatibel**: HALMET er fullt kompatibel med NMEA 2000-standarden. Kortet kan kobles til et NMEA 2000-nettverk gjennom det innebygde NMEA 2000-grensesnittet. + +- **I2C-, 1-Wire- og GPIO-grensesnitt**: HALMET har et 4-pinners I2C-grensesnitt, et 3-pinners 1-Wire-grensesnitt og 13 tilgjengelige generelle inn- og utgangsporter (GPIO). + +- **WiFi og Bluetooth**: HALMET har en integrert ESP32-WROOM-32E-modul med WiFi og Bluetooth. Dette gjør det mulig både å koble seg til eksisterende WiFi-nettverk og å opprette et WiFi-aksesspunkt slik at du kan koble deg direkte til kortet. + +- **ESP32-WROOM-32E med 16 MB flashminne**: ESP32-WROOM-32E-modulen gir rikelig med regnekraft og minne selv til de mest krevende bruksområdene. Med 16 MB flashminne kan du lagre store datamengder lokalt. + +- **Bredt inngangsspenningsområde**: HALMET kan trygt forsynes fra det 12 V- eller 24 V-anlegget som er vanlig i kjøretøy og båter. HALMET tåler inngangsspenninger mellom 5 V og 32 V. + +HALMET er åpen maskinvare, lisensiert under Creative Commons Attribution-ShareAlike 4.0 International-lisensen. + +## Skaffe maskinvaren + +Du kan kjøpe HALMET-kort fra [Hat Labs Oy](https://shop.hatlabs.fi). Alle designfiler er også tilgjengelige i [GitHub-repositoriet for HALMET-maskinvaren](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/nb/revisions/index.md b/docs/nb/revisions/index.md new file mode 100644 index 0000000..b4640df --- /dev/null +++ b/docs/nb/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Maskinvareversjoner +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Maskinvareversjoner + +## Innledning + +Denne siden dokumenterer de ulike kortversjonene og lenker til kretsskjemaene. Hele historikken for designfilene finnes i [GitHub-repositoriet HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Versjon 1.0.0 + +Første publiserte versjon. + +Kretsskjema: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Versjon 1.0.1 + +Rettelser og forbedringer i silketrykket. 3V3- og GND-loddeflater lagt til på det isolerte området. + +Kretsskjema: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/nb/software/index.md b/docs/nb/software/index.md new file mode 100644 index 0000000..5760bdc --- /dev/null +++ b/docs/nb/software/index.md @@ -0,0 +1,16 @@ +--- +title: Programvare +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Programvare + +## Innledning + +Som utviklingskort leveres HALMET uten forhåndsinstallert programvare. Du må installere egnet programvare selv. Dette er ikke vanskelig, men noe erfaring med mikrokontrollerkort som Arduino eller ESP32 Devkit er anbefalt. + +Eksempelfirmware for HALMET finnes i [GitHub-repositoriet HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Vær oppmerksom på at vi bare gir støtte for spørsmål om programvareutvikling gjennom [diskusjonsforumet til Hat Labs](https://github.com/hatlabs/discussions/discussions). + +Flere instruksjoner kommer snart. diff --git a/docs/nb/tutorials/index.md b/docs/nb/tutorials/index.md new file mode 100644 index 0000000..d94231e --- /dev/null +++ b/docs/nb/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Veiledninger og eksempelprosjekter +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +Veiledninger og eksempelprosjekter for HALMET blir listet opp på denne siden. diff --git a/docs/nb/usage/index.md b/docs/nb/usage/index.md new file mode 100644 index 0000000..d0f3e9e --- /dev/null +++ b/docs/nb/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Bruk +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Bruk + +## Vanlige bruksområder + +Denne delen inneholder praktisk informasjon om hvordan du leser ulike typer sensorer og kobler HALMET til andre enheter. + +### Programvareoppsett + +HALMET er et utviklingskort, og det leveres uten forhåndsinstallert programvare. +Du må installere egnet programvare selv. Dette er ikke vanskelig, men noe erfaring med mikrokontrollerkort som Arduino eller ESP32 Devkit er anbefalt. + +HALMET-dokumentasjonen forutsetter at du bruker [eksempelfirmwaren for HALMET](https://github.com/hatlabs/HALMET-example-firmware). Denne firmwaren er basert på rammeverket [SensESP](https://signalk.org/SensESP/) og gir relativt enkel tilgang til funksjonene på kortet. + +[Kom i gang-veiledningen for SensESP](https://signalk.org/SensESP/pages/getting_started/) gir detaljerte instruksjoner for å sette opp utviklingsmiljøet som trengs for å kompilere og installere firmwaren. Instruksjonene er skrevet for generiske ESP32-enheter, men de gjelder også for HALMET. Bruk bare [eksempelfirmwaren for HALMET](https://github.com/hatlabs/HALMET-example-firmware) i stedet for prosjektmalen til SensESP. + +Merk at selv om SensESP-dokumentasjonen forutsetter at Signal K brukes, er HALMET også fullt brukbar som en frittstående NMEA 2000-enhet. + +Hvis du foretrekker å ikke bruke SensESP, kan du også lage din egen firmware med Arduino IDE eller ESP-IDF. For mange bruksområder er ESPHome også et utmerket alternativ. + +**MERK:** GPIO-pinnebelegget på HALMET skiller seg litt fra pinnebelegget på både ESP32 Devkit og SH-ESP32. Hvis du tilpasser annen programvare enn eksempelfirmwaren for HALMET, må du kontrollere pinnebelegget nøye. Se [GPIO-oversikten](../hardware/index.md#gpio-oversikt) for mer informasjon. + +### Bruke digitale innganger + +HALMET har fire digitale innganger. Disse inngangene kan brukes til å lese digitale alarmsignaler eller som tellere. Denne delen beskriver hvordan du bruker inngangene i ulike vanlige bruksområder. Instruksjonene forutsetter at du bruker eksempelfirmwaren for HALMET. + +De digitale inngangene D1–D4 er koblet til henholdsvis GPIO-pinne 23, 25, 27 og 26. Inngangene tåler spenninger mellom −32 V og +32 V. Terskelspenningen for å registrere et høyt signal er om lag 1,55 V, med en hysterese på omtrent 0,7 V. + +### Tilkobling til digitale alarmer + +Denne delen beskriver hvordan du kobler HALMET til ulike av/på-signaler, for eksempel motor- eller lensealarmer. + +#### Maskinvareoppsett + +Vanligvis kan ulike av/på-signaler som motor- eller lensealarmer kobles direkte til de digitale inngangene på HALMET. En pull-up eller pull-down kan være nødvendig, avhengig av signaltypen. + +I figuren nedenfor, i eksempel (a), finnes det allerede en lyspære i kretsen. Når bryteren er åpen, trekker lyspæra spenningen på D1 ned. Ingen ekstra pull-down er nødvendig.[^1] I eksempel (b) finnes det derimot ingen annen last i kretsen. Hvis bryteren er åpen, blir spenningen på D2 flytende, og inngangen blir tilfeldig enten høy eller lav. Da må den innebygde pull-down-motstanden aktiveres ved å lodde sammen loddebroen på undersiden av kortet. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Digitale innganger i ulike bruksområder. (a) Det finnes allerede et lys i kretsen. (b) Ingen annen last i kretsen, bryteren trekker signalet høyt når den lukkes. (c) Bryteren trekker signalet lavt når den lukkes.
+
+ +[^1]: Hvis panellysene er laget med LED-er, er spenningsfallet over LED-ene kanskje ikke stort nok til å trekke spenningen tilstrekkelig lavt. Da må pull-down-motstanden aktiveres. + +
+![](solder_jumpers.jpg){ width="60%" } +
Loddebroene på undersiden av kortet kan loddes sammen for å aktivere de innebygde pull-up- eller pull-down-motstandene.
+
+ +På samme måte kan det være nødvendig å aktivere den innebygde pull-up-motstanden hvis bryteren trekker signalet lavt når den lukkes, som i eksempel (c). + +Til slutt, hvis alarmbryteren er normalt lukket (NC), er behandlingen omvendt. Når bryteren åpner, blir inngangsspenningen trukket opp eller ned, avhengig av kretsen. Da kan det være nødvendig å aktivere den innebygde pull-up- eller pull-down-motstanden. + +#### Programvareoppsett + +Eksempelfirmwaren for HALMET har en praktisk metode `ConnectAlarmSender()` for å konfigurere og koble til digitale innganger. Se `main.cpp` fra linje 177 og utover. Både aktivt høye og aktivt lave signaler støttes. + +### Digitale innganger som tellere + +De digitale inngangene på HALMET kan også brukes som tellere. Det er nyttig for eksempel til å telle motorens omdreininger eller pulser fra en kjettingteller. + +#### Maskinvareoppsett + +Vanligvis drives slike givere aktivt i begge retninger, så verken pull-up eller pull-down er nødvendig. Hvis du kobler HALMET til en lavimpedansutgang som generatorens W-uttak, er det lurt å sette inn en linjesikring som beskytter lederen mot kortslutning på grunn av gnaging eller andre skader. Utover det kan du koble giveren direkte til den digitale inngangen. + +Hvis pulskilden har mye elektrisk støy slik at turtallet leses feil, kan du aktivere et lavpassfilter ved å lodde sammen LP-loddebroen på undersiden av kortet. Lavpassfilteret har en grensefrekvens på om lag 2,3 kHz, noe som bør passe til bruksområder som innganger fra generatorens W-uttak. + +#### Programvareoppsett + +Eksempelfirmwaren for HALMET har en pulsteller som kan aktiveres på én eller alle de digitale inngangene. Se eksempelkonfigurasjonen i `main.cpp` fra linje 214 og utover. + +### Bruke analoge innganger + +HALMET har fire analoge innganger som kan brukes enten til passiv spenningsmåling eller til aktiv motstandsmåling. Denne delen beskriver hvordan du bruker inngangene i ulike vanlige bruksområder. + +#### Maskinvareoppsett + +De analoge inngangene A1–A4 er koblet til en AD-omformer av typen ADS1115. ADS1115 har 16 bits oppløsning og en maksimal samplingsfrekvens på 860 samplinger per sekund. De analoge inngangene på HALMET har likevel et kraftig lavpassfilter med en grensefrekvens på om lag 160 Hz. Det er fortsatt mer enn nok til å måle utgangssignaler fra fysiske sensorer, for eksempel tankgivere eller trykkgivere på motoren. + +I figuren nedenfor viser eksempel (a) en eksisterende måler i motorpanelet koblet til en resistiv giver. Målere i motorpanelet er som regel enten termostatiske eller magnetiske. I begge tilfeller danner måleren og giveren en spenningsdeler, og spenningen over giveren er proporsjonal med den målte størrelsen. Denne spenningen kan måles med de analoge inngangene på HALMET uten å forstyrre funksjonen til den opprinnelige måleren. På grunn av spenningsdeleren korrelerer spenningen ikke nødvendigvis lineært med den målte størrelsen, men dette kan kompenseres i programvaren. + +
+![](analog_input.svg){ width="60%" } +
Tilkobling av analoge innganger med og uten en eksisterende måler. (a) Når det allerede finnes en måler, bruker du HALMET i modus for passiv spenningsmåling. (b) Når ingen annen enhet er til stede, bruker du HALMET i modus for aktiv motstandsmåling.
+
+ + +Eksempel (b) viser et tilfelle uten en eksisterende måler. Giveren kobles direkte til den analoge inngangen på HALMET. Da må HALMET levere matespenning til giveren. HALMET utfører motstandsmålingen med en konstantstrømkilde på 10 mA. Strømmen på 10 mA gir en spenningsforskjell på 1 volt over en motstand på 100 Ω, altså en maksimal motstand på omtrent 300 Ω. Konstantstrømkilden aktiveres ved å sette en jumper over pinneparet på CCS-pinnelisten (konstantstrømkilde). Se figuren nedenfor. + +
+![](ccs_jumpers.jpg){ width="60%" } +
Figuren viser konstantstrømkilden aktivert for de analoge inngangene A2 og A4.
+
diff --git a/docs/nl/errata/index.md b/docs/nl/errata/index.md new file mode 100644 index 0000000..dc9f367 --- /dev/null +++ b/docs/nl/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Bekende fouten +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Bekende fouten + +Op deze pagina staan alle bekende hardwarefouten in de verschillende versies van de HALMET. + +## Versie 1.0.0 + +De digitale ingangen 3 en 4 zijn in de opdruk aan de achterzijde verwisseld. De juiste pintoewijzing is: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/nl/getting-started/index.md b/docs/nl/getting-started/index.md new file mode 100644 index 0000000..b4fe029 --- /dev/null +++ b/docs/nl/getting-started/index.md @@ -0,0 +1,76 @@ +--- +title: Aan de slag +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Aan de slag + +## De hardware monteren + +Om connectoren in kleine behuizingen flexibeler te kunnen plaatsen, worden HALMET-printen geleverd zonder gemonteerde 1-Wire- of GPIO-pinheaders. Wilt u een van deze interfaces gebruiken, dan moet u de pinheaders zelf op de print solderen. + +Hebt u instructies nodig voor het solderen van pinheaders op de print, kijk dan bij de [montage-instructies](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards) van de SH-ESP32. + +## De print voeden + +De HALMET wordt gevoed via de NMEA 2000-connector. Sluit u de HALMET aan op een NMEA 2000-netwerk, dan kunt u de print rechtstreeks vanuit het netwerk voeden. Sluit in dat +geval de aders van de NMEA 2000-kabel aan op het 4-pins steekbare klemmenblok, zoals in de volgende afbeelding. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Sluit de aders van de NMEA 2000-kabel aan op het klemmenblok zoals weergegeven.
+
+ +Sluit u de HALMET niet aan op een NMEA 2000-netwerk, gebruik dan hetzelfde klemmenblok maar sluit alleen aders aan op de posities `-` en `+`. Elke voedingsbron van 5–32 V voldoet. Het typische stroomverbruik van de print met actieve wifi is 0,07 A bij 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Sluit de voedingsaders aan op het klemmenblok zoals weergegeven.
+
+ +## Behuizingen + +Voor gebruik aan boord hoort de HALMET altijd in een waterdichte behuizing te zitten. +De print is ontworpen om in de [SH-ESP32-behuizing](https://shop.hatlabs.fi/products/sh-esp32-enclosure) te passen. Hieronder ziet u een voorbeeld van een HALMET-print die in deze behuizing is gemonteerd. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
De HALMET gemonteerd in de SH-ESP32-behuizing.
+
+ +In de SH-ESP32-behuizing is maar beperkt ruimte voor connectoren. +Op elke lange zijde passen in de praktijk slechts 2–3 paneelconnectoren. +Wilt u meer dan een paar ingangen aansluiten, dan is een grotere behuizing aan te raden. +De [compacte SH-RPi-behuizing](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm) van Hat Labs, hieronder afgebeeld, biedt bijvoorbeeld al ruim voldoende plaats voor connectoren. + +
+![](medium_enclosure.jpg){ width="50%" } +
De compacte SH-RPi-behuizing biedt meer ruimte voor het plaatsen van paneelconnectoren.
+
+ + +Andere geschikte waterdichte behuizingen zijn eenvoudig te vinden op elke online marktplaats. Ook grotere lasdozen voor buitengebruik voldoen voor dit doel. + +### Gaten boren voor paneelconnectoren + +De behuizingen hebben meestal geen voorgeboorde gaten. Gebruik bij het boren +altijd een conische boor of een trapboor (die eruitziet als een klein metalen kerstboompje). Gewone metaalboren happen al snel te veel en kunnen de wand van de behuizing doen scheuren. + +Houd bij het bepalen van de plaats van de gaten en de connectoren voldoende vrije ruimte aan voor het aandraaien van de wartelmoeren en voor het huis van de connector. Wilt u de behuizing aan de wand monteren, plaats de connectoren dan bij voorkeur omlaag gericht, om de kans op binnendringend water zo klein mogelijk te maken. + +Geschikte gatmaten voor de verschillende connectoren: + +- PG7-kabelwartel en M12-paneelconnector (NMEA 2000): 12,5 mm of 1/2 inch +- SP13-paneelconnectoren (blauwzwarte kunststof connectoren): 13 mm +- PG9-kabelwartel: 16 mm of 5/8 inch + +Met doorvoertules van rubber of silicone kunt u aanzienlijk meer kabels op dezelfde ruimte kwijt dan met paneelconnectoren of kabelwartels. Ze zijn echter niet zo waterdicht als paneelconnectoren of kabelwartels. Bovendien moet de kabel er permanent in worden vastgezet, wat het onderhoud aan +het systeem lastiger kan maken. + +TODO: Een afbeelding van een doorvoertule toevoegen. + +### De paneelconnectoren solderen + +Gebruik bij het solderen van de interne aders aan de paneelconnectoren altijd krimpkous om de afzonderlijke aders. +Denk eraan de krimpkous _vóór_ het solderen over de ader te schuiven... +Meestal kunt u eerst soldeer in de pinholte van de connector aanbrengen, dat soldeer vervolgens opnieuw laten smelten en de ader erin steken. diff --git a/docs/nl/hardware/index.md b/docs/nl/hardware/index.md new file mode 100644 index 0000000..cd6844a --- /dev/null +++ b/docs/nl/hardware/index.md @@ -0,0 +1,242 @@ +--- +title: Hardwarebeschrijving +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hardware + +## De ESP32 in het kort + +De HALMET is gebaseerd op de krachtige microcontrollermodule ESP32-WROOM-32E. De ESP32 is een microcontroller met twee kernen en ingebouwde wifi- en Bluetooth-verbinding. De ESP32 is een populaire keuze voor IoT-toepassingen dankzij de lage prijs, het goede aanbod aan randapparatuur en het gebruiksgemak. + +## Functionele blokken van de print + +De verschillende functionele blokken van de print worden hieronder beschreven. + +
+![](HALMET-func.jpg){ width="60%" } +
De functionele blokken van de HALMET.
+
+ +1. NMEA 2000-aansluiting en voedingsingang met beveiliging. De NMEA 2000-connector + heeft de volgende beveiligingselementen: + + - Zelfherstellende zekering van 500 mA + - Ompoolbeveiligingsdiode + - TVS-diodes voor overspannings- en ESD-beveiliging + - Tweetraps storingsfiltering + +2. Voeding. Een schakelende voeding met een maximale uitgangsstroom van 2 A. + +3. CAN-transceiver voor NMEA 2000. RX- en TX-leds geven het verkeer op de + CAN-bus zichtbaar weer. + +4. I2C- en 1-Wire-aansluitingen voor het aansluiten van extra sensoren. + +5. Gebruikersinterface. Een resetknop, een knop voor de bootmodus die ook als + algemene knop dienstdoet, een rode voedings-led en een blauwe, door de + gebruiker programmeerbare led. + +6. USB 2.0-aansluiting voor programmeren en debuggen. + +7. ESP32-WROOM-32E-module met ingebouwde wifi en Bluetooth. De module op de + HALMET-print bevat 16 MB flashgeheugen. + +8. Schakeling voor de galvanische scheiding van de digitale en analoge ingangen. + +9. Analoge ingangen. De print heeft vier analoge ingangen met een 16-bits + resolutie en een maximale ingangsspanning van 33 V. Elke ingang heeft een + onderspannings- en overspanningsbeveiliging en een laagdoorlaatfilter met een + afsnijfrequentie van 160 Hz om de meetruis te beperken. + + De analoge ingangen hebben een optionele constantstroombron van 10 mA voor + actieve weerstandsmeting. De constantstroombron kan met de + CCS-jumperheaders worden ingeschakeld. + + In de weerstandsmeetmodus is de maximaal meetbare weerstand 300 Ω. + +10. Digitale ingangen. De HALMET heeft vier digitale ingangen met een maximale + ingangsspanning van ±32 V. De ingangen bevatten een Schmitt trigger die de + ruisongevoeligheid verbetert. + + +## Galvanische scheiding + +De print heeft een galvanische scheiding tussen de digitale en analoge ingangen +enerzijds en de ESP32-microcontroller anderzijds. De scheiding is gerealiseerd met +digitale isolatoren voor respectievelijk I2C en de vier digitale ingangen, en met +een gescheiden DC/DC-omzetter die het gescheiden deel voedt. + +Dankzij deze scheiding kan de print vanuit het NMEA 2000-netwerk worden gevoed +zonder risico op aardlussen. De scheiding beschermt de ingangen bovendien tegen +spanningspieken en ruis. + +
+![](HALMET-isolation.jpg){ width="60%" } +
De scheidingsbarrière van de HALMET. De ingangsconnectoren zijn gescheiden van +de rest van de print, wat betekent dat ze geen gemeenschappelijke massa met de rest van +de print delen.
+
+ +## Connectoren + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
De connectoren van de HALMET, bovenzijde.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
De connectoren van de HALMET, onderzijde.
+
+ +
+
+ +### Connectoren aan de bovenzijde + +1. NMEA 2000-connector. De connector is een 4-polig steekbaar klemmenblok dat + compatibel is met Phoenix MC 3.81. Via deze connector wordt de print op een + NMEA 2000-netwerk aangesloten en gevoed. + +2. 1-Wire-pinheader. Met de 1-Wire-pinheader kunt u 1-Wire-sensoren op de print + aansluiten. De connector is een 3-pins pinheader met 2,54 mm steek. De + pinheader is standaard niet op de print gemonteerd, omdat hij de plaatsing van + de paneelconnectoren van de behuizing kan hinderen. + +3. I2C-pinheader. Met de I2C-pinheader kunt u I2C-sensoren op de print + aansluiten. De connector is een 4-pins pinheader met 2,54 mm steek. + +4. Micro-USB-connector. Deze connector wordt gebruikt om de print te programmeren + en te debuggen. + +5. Niet-bestukte soldeereilanden voor de reset- (EN) en boot-signalen (IO0). + +6. GPIO-pinheader. De GPIO-pinheader is een 2×10-pins pinheader met 2,54 mm + steek. Hij brengt de beschikbare GPIO-pinnen van de ESP32 naar buiten en kan + ook als JTAG-pinheader worden gebruikt. + +7. Voedingspinheader van het gescheiden deel. Via deze pinheader kunt u externe + apparaten voeden vanaf 3V3 en GND van het gescheiden deel. + +8. Contacten van de jumperheader voor de constantstroombron (CCS) van de analoge + ingangen. De constantstroombron wordt ingeschakeld door de jumpercontacten + door te verbinden. + +9. Connectoren van de analoge ingangen. Het zijn 2-polige steekbare klemmenblokken + die compatibel zijn met Phoenix MC 3.81. Hiermee sluit u analoge sensoren op de + print aan. + +10. Connectoren van de digitale ingangen. Het zijn 2-polige steekbare klemmenblokken + die compatibel zijn met Phoenix MC 3.81. Hiermee sluit u digitale sensoren op de + print aan. + +### Connectoren aan de onderzijde + +11. Soldeerbrug voor de CAN-afsluitweerstand. Door de brug dicht te solderen + schakelt u de afsluitweerstand van 120 Ω voor de CAN-bus in. Gebruik de + afsluitweerstand niet in NMEA 2000-netwerken. + +12. Soldeerbrug voor het laagdoorlaatfilter. Door de brug dicht te solderen + schakelt u een laagdoorlaatfilter in op de bijbehorende analoge ingang. Het + filter heeft een afsnijfrequentie van 2,3 kHz. Het filter kan bijvoorbeeld + worden gebruikt om de ruis in een toerentellersignaal te verminderen. + +13. Soldeerbrug voor de pull-downweerstand. Door de brug dicht te solderen + schakelt u een pull-downweerstand van 100 kΩ in op de bijbehorende digitale + ingang. Met de pull-downweerstand kunt u een maakcontact (NO) uitlezen dat bij + sluiten hoog wordt getrokken. + +14. Soldeerbrug voor de pull-upweerstand. Door de brug dicht te solderen schakelt + u een pull-upweerstand van 100 kΩ in op de bijbehorende digitale ingang. Met + de pull-upweerstand kunt u een verbreekcontact (NC) uitlezen dat bij sluiten + laag wordt getrokken. + +15. Soldeerbruggen voor de keuze van het I2C-adres van de ADS1115. Door de bruggen + dicht te solderen kiest u het I2C-adres van de analoog-digitaalomzetter + (AD-omzetter) ADS1115. Zo voorkomt u adresconflicten wanneer er meerdere + ADS1115-omzetters op dezelfde I2C-bus zijn aangesloten. De soldeereilanden + kunnen ook worden gebruikt om extra I2C-apparaten op het gescheiden deel van + de print aan te sluiten. + +### GPIO-overzicht + +De HALMET reserveert een aantal GPIO-pinnen voor de ingangsperiferie. De beschikbare +GPIO-pinnen zijn naar de 2×10-pins GPIO-pinheader gebracht. De volgende tabel geeft +de GPIO-pinnen en hun functies. + +| GPIO | Functie | Opmerkingen | +| ------: | :---------- | :--------------------------------------------------- | +| 0 | Bootknop | Gaat naar de bootloader wanneer laag getrokken | +| 1 | TXD0 | Data verzenden naar USB | +| 2 | LED | Rode led op de print | +| 3 | RXD0 | Data ontvangen van USB | +| 4 | 1-Wire DQ | 1-Wire-datalijn | +| 5 | - | Beschikbaar op de GPIO-pinheader | +| 12 | - / TDI | Beschikbaar op de GPIO-pinheader. Optioneel: JTAG TDI | +| 13 | - / TCK | Beschikbaar op de GPIO-pinheader. Optioneel: JTAG TCK | +| 14 | - / TMS | Beschikbaar op de GPIO-pinheader. Optioneel: JTAG TMS | +| 15 | - / TDO | Beschikbaar op de GPIO-pinheader. Optioneel: JTAG TDO | +| 16 | - | Beschikbaar op de GPIO-pinheader | +| 17 | - | Beschikbaar op de GPIO-pinheader | +| 18 | CAN RX | Ontvangst van NMEA 2000 | +| 19 | CAN TX | Verzending naar NMEA 2000 | +| 21 | I2C SDA | I2C-datalijn. Gebruikt voor de analoge ingang | +| 22 | I2C SCL | I2C-kloklijn. Gebruikt voor de analoge ingangen | +| 23 | DI1 | Digitale ingang 1 | +| 25 | DI2 | Digitale ingang 2 | +| 27 | DI3 | Digitale ingang 3 | +| 26 | DI4 | Digitale ingang 4 | +| 32 | - | Beschikbaar op de GPIO-pinheader | +| 33 | - | Beschikbaar op de GPIO-pinheader | +| 34 | - | Beschikbaar op de GPIO-pinheader | +| 35 | - | Beschikbaar op de GPIO-pinheader | +| 36 (VP) | Alleen ingang | Beschikbaar op de GPIO-pinheader | +| 39 (VN) | Alleen ingang | Beschikbaar op de GPIO-pinheader | + + +## Voeding + +Het toegestane ingangsspanningsbereik van de print is 5–32 V. Het typische +stroomverbruik is 90 mA bij 12 V met de wifi-module actief (komt overeen met 1,1 W). + +## NMEA 2000 + +NMEA 2000 is een alomtegenwoordige communicatiestandaard waarmee sensoren, bedieningsapparatuur en displays op boten en schepen met elkaar worden verbonden. De standaard is gebaseerd op het Controller Area Network (CAN-bus), een voertuigbusstandaard die is ontworpen om apparaten zonder tussenkomst van een hostcomputer met elkaar te laten communiceren. + +De print voldoet aan de NMEA 2000-standaard zolang geen van de niet-gescheiden +connectoren is verbonden met andere apparaten die naar massa gerefereerd zijn. Zo +kan een 1-Wire-temperatuursensor met een lange kabel wel worden gebruikt, omdat die +geen gemeenschappelijke massa met andere apparaten deelt. Het aansluiten van een +AD-omzetter met I2C op de niet-gescheiden I2C-connector doorbreekt de conformiteit +met NMEA 2000 echter wel. + +TODO: NMEA 2000 GPIO-pinbezetting + +## Status-leds + +Op de HALMET-print zitten twee knoppen en twee leds. De twee knoppen zijn gemarkeerd met “Reset” en “Boot”. De Reset-knop start de print opnieuw op door de Enable-pin van de ESP32 laag te trekken. De Boot-knop is verbonden met GPIO0 en kan tijdens het opstarten van het apparaat worden gebruikt om de module in de downloadmodus te dwingen. Verder kan hij als gewone knopingang worden gebruikt. + +De twee leds zijn niet apart gemarkeerd. De rode led brandt zodra er 3,3 V op de print staat. De blauwe led is verbonden met GPIO2 (de pin die op ESP32-ontwikkelborden gewoonlijk voor een led wordt gebruikt). Gebruikersprogramma's kunnen hem aansturen om de toestand van het apparaat aan te geven. + +## 1-Wire + +1-Wire is een communicatiebussysteem voor apparaten, ontworpen door Dallas Semiconductor, dat inmiddels is overgenomen door Maxim Integrated Products. Hoewel 1-Wire een traag protocol is dat slechts snelheden tot 16,3 kbit/s ondersteunt, is het heel eenvoudig te implementeren en bruikbaar over grote afstanden. Het wordt veel gebruikt voor temperatuursensoren en vergelijkbare eenvoudige meetapparatuur. + +De 1-Wire-implementatie van de HALMET bevat ESD- en RF-storingsfiltering en daarnaast laagdoorlaatfiltering om de betrouwbaarheid van het netwerk te verbeteren. + +Let op: de datapin van 1-Wire (de opdruk “DQ”) is fysiek gekoppeld aan GPIO4; gebruik in uw programma dus GPIO4 voor alle 1-Wire-data. + +## I2C + +I2C (Inter-Integrated Circuit) is een zeer populaire synchrone seriële communicatiebus die veel wordt gebruikt om allerlei verschillende IC's aan te sturen. De bus gebruikt twee datadraden, naast voeding en massa. + +De HALMET gebruikt I2C intern voor de ADS1115-AD-omzetter. De I2C-bus is ook naar een 4-pins pinheader gebracht om extra I2C-apparaten aan te sluiten. + +De I2C-bus is verbonden met GPIO21 (SDA) en GPIO22 (SCL) van de ESP32. Dit zijn de standaard I2C-pinnen in de Arduino-ESP32-omgeving, maar ze wijken af van de standaardpinnen van de SH-ESP32. diff --git a/docs/nl/index.md b/docs/nl/index.md new file mode 100644 index 0000000..fa26400 --- /dev/null +++ b/docs/nl/index.md @@ -0,0 +1,35 @@ +--- +title: Inleiding +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Inleiding + +HALMET, de Hat Labs Marine Engine & Tank interface, is een ontwikkelbord voor het aansluiten van motor- en tanksensoren op boten en andere voertuigen. De print kan digitale en analoge sensoren uitlezen en verbinding maken met andere apparaten via NMEA 2000-, wifi-, Bluetooth-, I2C-, 1-Wire- of GPIO-interfaces. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Afbeelding van de HALMET
+
+ +## Belangrijkste kenmerken + +- **Vier digitale ingangen**: de HALMET heeft vier digitale ingangen voor het lezen van digitale alarmsignalen of voor gebruik als tellers. De ingangen verdragen spanningen tussen −32 V en +32 V. Met de digitale ingangen kunt u zowel signaalniveaus als in de tijd variërende signalen detecteren, zoals motortoerental, brandstofdebiet of pulsen van een kettingteller. + +- **Vier analoge ingangen**: de HALMET heeft vier analoge ingangen voor het uitlezen van analoge sensoren. De ingangen verdragen spanningen tussen −32 V en +32 V, met een meetbereik van 0 tot 33 V. De ingangen zijn aangesloten op een ADS1115-analoog-digitaalomzetter met een 16-bits resolutie. De analoge ingangen zijn geschikt voor zowel passieve spanningsmetingen als actieve weerstandsmetingen. + +- **NMEA 2000-compatibel**: de HALMET is volledig compatibel met de NMEA 2000-standaard. De print kan via de ingebouwde NMEA 2000-interface op een NMEA 2000-netwerk worden aangesloten. + +- **I2C-, 1-Wire- en GPIO-interfaces**: de HALMET heeft een 4-pins I2C-interface, een 3-pins 1-Wire-interface en 13 beschikbare universele in-/uitgangspoorten (GPIO's). + +- **Wifi- en Bluetooth-verbindingen**: de HALMET heeft een geïntegreerde ESP32-WROOM-32E-module met wifi en Bluetooth. Daarmee kan de print zowel verbinding maken met bestaande wifi-netwerken als zelf een wifi-accesspoint opzetten, zodat u rechtstreeks verbinding met de print kunt maken. + +- **ESP32-WROOM-32E met 16 MB flashgeheugen**: de ESP32-WROOM-32E-module biedt ruim voldoende rekenkracht en geheugen voor zelfs de meest veeleisende toepassingen. In het flashgeheugen van 16 MB kunnen grote hoeveelheden gegevens lokaal worden opgeslagen. + +- **Groot ingangsspanningsbereik**: de HALMET kan veilig worden gevoed uit het 12 V- of 24 V-systeem dat in voertuigen en boten gebruikelijk is. De HALMET verdraagt ingangsspanningen tussen 5 V en 32 V. + +HALMET is open hardware, uitgebracht onder de licentie Creative Commons Naamsvermelding-GelijkDelen 4.0 Internationaal. + +## De hardware aanschaffen + +HALMET-printen koopt u bij [Hat Labs Oy](https://shop.hatlabs.fi). Alle ontwerpbestanden zijn ook beschikbaar in de [GitHub-repository met HALMET-hardware](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/nl/revisions/index.md b/docs/nl/revisions/index.md new file mode 100644 index 0000000..53859e1 --- /dev/null +++ b/docs/nl/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Hardwareversies +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Hardwareversies + +## Inleiding + +Deze pagina documenteert de verschillende versies van de print en geeft links naar de schema's. De volledige geschiedenis van de ontwerpbestanden is te vinden in de [GitHub-repository HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Versie 1.0.0 + +Eerste gepubliceerde versie. + +Schema: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Versie 1.0.1 + +Correcties en verbeteringen in de opdruk. Soldeereilanden voor 3V3 en GND toegevoegd op het gescheiden deel. + +Schema: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/nl/software/index.md b/docs/nl/software/index.md new file mode 100644 index 0000000..1b61922 --- /dev/null +++ b/docs/nl/software/index.md @@ -0,0 +1,16 @@ +--- +title: Software +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Software + +## Inleiding + +Als ontwikkelbord wordt de HALMET geleverd zonder vooraf geïnstalleerde software. U installeert de geschikte software zelf. Dat is niet moeilijk, maar enige ervaring met microcontrollerborden zoals Arduino of ESP32 Devkit is wel aan te raden. + +Voorbeeldfirmware voor de HALMET is beschikbaar in de [GitHub-repository HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Let op: ondersteuning bij vragen over softwareontwikkeling wordt uitsluitend geboden via het [discussieforum van Hat Labs](https://github.com/hatlabs/discussions/discussions). + +Meer instructies volgen binnenkort. diff --git a/docs/nl/tutorials/index.md b/docs/nl/tutorials/index.md new file mode 100644 index 0000000..45881d8 --- /dev/null +++ b/docs/nl/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Tutorials en voorbeeldprojecten +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +Op deze pagina komen tutorials en voorbeeldprojecten voor de HALMET te staan. diff --git a/docs/nl/usage/index.md b/docs/nl/usage/index.md new file mode 100644 index 0000000..2c74abd --- /dev/null +++ b/docs/nl/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Gebruik +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Gebruik + +## Veelvoorkomende toepassingen + +Dit onderdeel bevat praktische informatie over het uitlezen van verschillende typen sensoren en over het aansluiten van de HALMET op andere apparaten. + +### Software installeren + +De HALMET is een ontwikkelbord en wordt zonder vooraf geïnstalleerde software geleverd. +U installeert de geschikte software zelf. Dat is niet moeilijk, maar enige ervaring met microcontrollerborden zoals Arduino of ESP32 Devkit is wel aan te raden. + +In de HALMET-documentatie wordt uitgegaan van de [HALMET-voorbeeldfirmware](https://github.com/hatlabs/HALMET-example-firmware). Deze firmware is gebaseerd op het framework [SensESP](https://signalk.org/SensESP/) en geeft betrekkelijk eenvoudig toegang tot de mogelijkheden van de print. + +De [SensESP Getting Started Guide](https://signalk.org/SensESP/pages/getting_started/) bevat uitgebreide instructies voor het installeren van de ontwikkelomgeving die u nodig hebt om de firmware te compileren en te installeren. Die instructies zijn geschreven voor gewone ESP32-apparaten, maar gelden ook voor de HALMET. Gebruik alleen de [HALMET-voorbeeldfirmware](https://github.com/hatlabs/HALMET-example-firmware) in plaats van het projectsjabloon van SensESP. + +Let op: hoewel in de SensESP-documentatie het gebruik van Signal K wordt verondersteld, is de HALMET ook volledig bruikbaar als zelfstandig NMEA 2000-apparaat. + +Wilt u SensESP liever niet gebruiken, dan kunt u ook eigen firmware maken met de Arduino IDE of ESP-IDF. Voor veel toepassingen is ESPHome eveneens een uitstekende keuze. + +**LET OP:** de GPIO-pintoewijzingen van de HALMET wijken licht af van de pintoewijzingen van zowel de ESP32 Devkit als de SH-ESP32. Past u andere software aan dan de HALMET-voorbeeldfirmware, dan moet u de pintoewijzingen zorgvuldig controleren. Zie het [GPIO-overzicht](../hardware/index.md#gpio-overzicht) voor meer informatie. + +### De digitale ingangen gebruiken + +De HALMET heeft vier digitale ingangen. Deze ingangen kunt u gebruiken voor het lezen van digitale alarmsignalen of als tellers. Dit onderdeel beschrijft het gebruik van de ingangen in verschillende veelvoorkomende situaties. In de instructies wordt uitgegaan van de HALMET-voorbeeldfirmware. + +De digitale ingangen D1–D4 zijn aangesloten op respectievelijk GPIO-pin 23, 25, 27 en 26. De ingangen verdragen spanningen tussen −32 V en +32 V. De drempelspanning voor het detecteren van een hoog signaal bedraagt ongeveer 1,55 V, met een hysterese van ongeveer 0,7 V. + +### Aansluiten op digitale alarmen + +Dit onderdeel beschrijft hoe u de HALMET aansluit op verschillende aan/uit-signalen, zoals motor- of bilgealarmen. + +#### De hardware aansluiten + +Aan/uit-signalen zoals motor- of bilgealarmen kunt u meestal rechtstreeks op de digitale ingangen van de HALMET aansluiten. Afhankelijk van het signaaltype kan een pull-up of pull-down nodig zijn. + +In de afbeelding hieronder zit in voorbeeld (a) al een controlelampje in het circuit. Als de schakelaar open is, trekt het controlelampje de spanning op D1 omlaag. Een extra pull-down is dan niet nodig.[^1] In voorbeeld (b) zit er echter geen andere belasting in het circuit. Als de schakelaar open is, blijft de spanning op D2 zweven en leest de ingang willekeurig hoog of laag. In dat geval moet u de interne pull-downweerstand inschakelen door de soldeerbrug aan de achterzijde van de print dicht te solderen. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Digitale ingangen in verschillende situaties. (a) Er zit al een lampje in het circuit. (b) Geen andere belasting in het circuit; de schakelaar trekt het signaal hoog wanneer hij sluit. (c) De schakelaar trekt het signaal laag wanneer hij sluit.
+
+ +[^1]: Is de paneelverlichting met leds uitgevoerd, dan is de spanningsval over de leds mogelijk niet groot genoeg om de spanning ver genoeg omlaag te trekken. In dat geval moet de pull-downweerstand worden ingeschakeld. + +
+![](solder_jumpers.jpg){ width="60%" } +
De soldeerbruggen aan de achterzijde van de print kunnen worden dichtgesoldeerd om de ingebouwde pull-up- of pull-downweerstanden in te schakelen.
+
+ +Trekt de schakelaar het signaal laag wanneer hij sluit, zoals in voorbeeld (c), dan kan het op dezelfde manier nodig zijn de interne pull-up in te schakelen. + +Zijn de alarmschakelaars ten slotte verbreekcontacten (NC), dan is de aanpak precies omgekeerd. Wanneer de schakelaar opent, wordt de ingangsspanning omhoog of omlaag getrokken, afhankelijk van het circuit. Ook dan kan het nodig zijn de interne pull-up of pull-down in te schakelen. + +#### De software instellen + +De HALMET-voorbeeldfirmware biedt de hulpmethode `ConnectAlarmSender()` voor het instellen en aansluiten van digitale ingangen. Zie `main.cpp` vanaf regel 177. Zowel actief hoge als actief lage signalen worden ondersteund. + +### Digitale ingangen als tellers + +De digitale ingangen van de HALMET kunt u ook als tellers gebruiken. Dat is bijvoorbeeld handig om motoromwentelingen of pulsen van een kettingteller te tellen. + +#### De hardware aansluiten + +Dergelijke gevers worden meestal in beide richtingen actief aangestuurd, zodat een pull-up of pull-down niet nodig is. Sluit u de HALMET aan op een uitgang met lage impedantie, zoals de W-klem van de dynamo, dan is het verstandig een kabelzekering op te nemen om de ader te beschermen tegen kortsluiting door schuren of andere beschadiging. Verder kunt u de gever rechtstreeks op de digitale ingang aansluiten. + +Is de pulsbron erg ruisig, waardoor het toerental onrustig wordt weergegeven, dan kunt u een laagdoorlaatfilter inschakelen door de LP-soldeerbrug aan de achterzijde van de print dicht te solderen. Het laagdoorlaatfilter heeft een afsnijfrequentie van ongeveer 2,3 kHz, wat geschikt zou moeten zijn voor toepassingen zoals ingangen op de W-klem van de dynamo. + +#### De software instellen + +De HALMET-voorbeeldfirmware bevat een pulsteller die u op één of op alle digitale ingangen kunt inschakelen. Zie de voorbeeldconfiguratie in `main.cpp` vanaf regel 214. + +### De analoge ingangen gebruiken + +De HALMET heeft vier analoge ingangen die u kunt gebruiken voor passieve spanningsmetingen of voor actieve weerstandsmetingen. Dit onderdeel beschrijft het gebruik van de ingangen in verschillende veelvoorkomende situaties. + +#### De hardware aansluiten + +De analoge ingangen A1–A4 zijn aangesloten op een ADS1115-analoog-digitaalomzetter. De ADS1115 heeft een 16-bits resolutie en een maximale bemonsteringsfrequentie van 860 samples per seconde. De analoge ingangen van de HALMET bevatten echter een sterk laagdoorlaatfilter met een afsnijfrequentie van ongeveer 160 Hz. Dat is nog steeds ruim voldoende om de uitgangssignalen van fysieke sensoren te meten, zoals tankniveausensoren of motordruksensoren. + +In de afbeelding hieronder toont voorbeeld (a) een bestaande meter op het motorpaneel die op een weerstandsgever is aangesloten. Meters op een motorpaneel zijn meestal thermostatisch of magnetisch uitgevoerd. In beide gevallen vormen de meter en de gever samen een spanningsdeler, en is de spanning over de gever evenredig met de gemeten grootheid. Die spanning kunt u met de analoge ingangen van de HALMET meten zonder de werking van de oorspronkelijke meter te verstoren. Door de spanningsdeler hoeft de spanning niet lineair samen te hangen met de gemeten grootheid, maar dat kunt u in de software compenseren. + +
+![](analog_input.svg){ width="60%" } +
Analoge ingangen aansluiten met en zonder bestaande meter. (a) Is er al een meter aanwezig, gebruik de HALMET dan in de modus passieve spanningsmeting. (b) Is er geen ander apparaat aanwezig, gebruik de HALMET dan in de modus actieve weerstandsmeting.
+
+ + +Voorbeeld (b) toont een situatie zonder bestaande meter. De gever is rechtstreeks op de analoge ingang van de HALMET aangesloten. In dat geval moet de HALMET zelf de excitatiespanning voor de gever leveren. De HALMET voert de weerstandsmeting uit met een constantstroombron van 10 mA. Die stroom van 10 mA levert over een weerstand van 100 Ω een spanningsverschil van 1 volt op, wat neerkomt op een maximale weerstand van ongeveer 300 Ω. U schakelt de constantstroombron in door een jumper op het pinpaar van de CCS-jumperheader (constantstroombron) te plaatsen. Zie de afbeelding hieronder. + +
+![](ccs_jumpers.jpg){ width="60%" } +
De afbeelding toont de constantstroombron ingeschakeld voor de analoge ingangen A2 en A4.
+
diff --git a/docs/sv/errata/index.md b/docs/sv/errata/index.md new file mode 100644 index 0000000..1c740e9 --- /dev/null +++ b/docs/sv/errata/index.md @@ -0,0 +1,15 @@ +--- +title: Kända fel +translated_from: 5ef927a8a1dd611d3215899a52dd6b3bfca86859 +--- + +# Kända fel + +Den här sidan listar alla kända hårdvarufel i HALMETs olika versioner. + +## Version 1.0.0 + +De digitala ingångarna 3 och 4 är förväxlade i monteringstrycket på undersidan. Rätt stiftindelning är: + + - DI3: GPIO 27 + - DI4: GPIO 26 diff --git a/docs/sv/getting-started/index.md b/docs/sv/getting-started/index.md new file mode 100644 index 0000000..d35eb1e --- /dev/null +++ b/docs/sv/getting-started/index.md @@ -0,0 +1,76 @@ +--- +title: Kom igång +translated_from: 75bcdba18bc044c04ce3e220067bf537e069ec82 +--- + +# Kom igång + +## Montering av hårdvaran + +För att kontakterna ska kunna placeras friare i små kapslingar levereras HALMET-korten utan monterade stiftlister för 1-Wire och GPIO. Om du tänker använda något av dessa gränssnitt måste du löda fast stiftlisten på kortet. + +Om du behöver anvisningar för att löda stiftlister på kortet kan du titta på SH-ESP32:s [monteringsanvisningar](https://docs.hatlabs.fi/sh-esp32/pages/getting-started/#revision-1-boards). + +## Strömförsörjning av kortet + +HALMET matas via NMEA 2000-kontakten. Om du ska ansluta HALMET till ett NMEA 2000-nätverk kan kortet matas direkt från nätverket. Anslut i så fall +NMEA 2000-ledarna till den 4-poliga löstagbara kopplingsplinten enligt figuren nedan. + +
+![](halmet_n2k_input.jpg){ width="50%" } +
Anslut NMEA 2000-ledarna till kontakten enligt figuren.
+
+ +Om du inte ska ansluta HALMET till ett NMEA 2000-nätverk använder du samma kontakt men ansluter bara ledare till `-` och `+`. Vilken strömkälla som helst på 5–32 V kan användas. Kortets typiska strömförbrukning med WiFi aktiverat är 0,07 A vid 12 V. + +
+![](power_connector.jpg){ width="50%" } +
Anslut matningsledarna till kontakten enligt figuren.
+
+ +## Kapslingar + +Vid användning i båt bör HALMET alltid placeras i en vattentät kapsling. +Kortet är konstruerat för att passa i [SH-ESP32-kapslingen](https://shop.hatlabs.fi/products/sh-esp32-enclosure). Nedan finns ett exempel på ett HALMET-kort monterat i kapslingen. + +
+![](halmet_small_enclosure.jpg){ width="50%" } +
HALMET monterat i SH-ESP32-kapslingen.
+
+ +SH-ESP32-kapslingen har begränsat med utrymme för kontakter. +Var och en av långsidorna rymmer i praktiken bara 2–3 panelkontakter. +Om du tänker ansluta fler än några få ingångar rekommenderas en större kapsling. +Till exempel Hat Labs [kompakta SH-RPi-kapsling](https://shop.hatlabs.fi/products/compact-weatherproof-enclosure-for-raspberry-pi-and-sh-rpi-158x90x60-mm), som visas nedan, har redan gott om plats för kontakter. + +
+![](medium_enclosure.jpg){ width="50%" } +
Den kompakta SH-RPi-kapslingen ger mer plats för placering av panelkontakter.
+
+ + +Andra lämpliga vattentäta kapslingar hittar du enkelt på vilken nätmarknadsplats som helst. Även större kopplingsdosor för utomhusbruk passar för ändamålet. + +### Borra hål för panelkontakter + +Kapslingarna har vanligtvis inga förborrade hål. När du borrar hål ska du +alltid använda ett koniskt borr eller en stegborr (den som ser ut som en liten julgran i metall). Vanliga metallborr biter lätt för hårt och kan spräcka kapslingens vägg. + +När du planerar placeringen av hål och kontakter ska du lämna tillräckligt med plats för att dra åt kontaktmuttrarna och för själva kontaktkroppen. Om du tänker väggmontera kapslingen rekommenderas att kontakterna placeras nedåt för att minimera risken för vattenintrång. + +Lämpliga hålstorlekar för olika kontakter: + +- PG7-kabelgenomföring och M12-panelkontakt (NMEA 2000): 12,5 mm eller 1/2" +- SP13-panelkontakter (blåsvarta plastkontakter): 13 mm +- PG9-kabelgenomföring: 16 mm eller 5/8" + +Gummi- eller silikongenomföringar ger betydligt högre kabeltäthet än panelkontakter eller kabelgenomföringar. De är dock inte lika vattentäta som panelkontakter eller kabelgenomföringar. Dessutom kräver de att kabeln fästs permanent, vilket kan göra det svårare att +serva systemet. + +TODO: Lägg till en bild på en gummigenomföring. + +### Löda panelkontakterna + +När du löder de inre ledarna till panelkontakterna ska du alltid använda krympslang på de enskilda ledarna. +Kom alltid ihåg att trä krympslangen på ledaren _innan_ du löder... +Vanligtvis kan du först tillsätta lod i kontaktstiftets hålighet och sedan smälta lodet på nytt och föra in ledaren. diff --git a/docs/sv/hardware/index.md b/docs/sv/hardware/index.md new file mode 100644 index 0000000..bdf56ff --- /dev/null +++ b/docs/sv/hardware/index.md @@ -0,0 +1,233 @@ +--- +title: Hårdvarubeskrivning +translated_from: 96f96c3aff8d2a33ab2f1b59c0dbb8747c8ed3e2 +--- + +# Hårdvara + +## Introduktion till ESP32 + +HALMET bygger på den kraftfulla mikrokontrollermodulen ESP32-WROOM-32E. ESP32 är en tvåkärnig mikrokontroller med inbyggd WiFi- och Bluetooth-anslutning. ESP32 är ett populärt val för IoT-tillämpningar tack vare sitt låga pris, sin goda uppsättning kringkretsar och att den är enkel att använda. + +## Kortets funktionsblock + +Kortets olika funktionsblock beskrivs nedan. + +
+![](HALMET-func.jpg){ width="60%" } +
HALMET-kortets funktionsblock.
+
+ +1. NMEA 2000-anslutning samt strömförsörjning och skydd. NMEA 2000-kontakten + har följande skyddskomponenter: + - Självåterställande säkring på 500 mA + - Diod för polvändningsskydd + - TVS-dioder för överspännings- och ESD-skydd + - Störningsfiltrering i två steg + +2. Strömförsörjning. Ett switchat nätaggregat med en maximal utström på 2 A. + +3. CAN-transceiver för NMEA 2000. RX- och TX-LED:er ger en visuell indikering + av trafiken på CAN-bussen. + +4. I2C- och 1-Wire-gränssnitt för anslutning av ytterligare givare. + +5. Användargränssnitt. En reset-knapp, en boot-knapp som även fungerar som + allmän knapp, en röd LED för spänningsindikering och en blå användarstyrd LED. + +6. USB 2.0-gränssnitt för programmering och felsökning. + +7. ESP32-WROOM-32E-modul med inbyggd WiFi och Bluetooth. Modulen på + HALMET-kortet har 16 MB flashminne. + +8. Kretsar för galvanisk isolation av de digitala och analoga ingångarna. + +9. Analoga ingångar. Kortet har fyra analoga ingångar med 16 bitars upplösning + och en maximal inspänning på 33 V. Varje ingång har skydd mot under- och + överspänning samt lågpassfiltrering med gränsfrekvensen 160 Hz för att + minska mätbruset. + + De analoga ingångarna har en valfri konstantströmkälla på 10 mA för aktiv + resistansmätning. Konstantströmkällan aktiveras med CCS-bygelstiften. + + I resistansmätningsläge är den högsta resistans som kan mätas 300 Ω. + +10. Digitala ingångar. HALMET har fyra digitala ingångar med en maximal + inspänning på ±32 V. Ingångarna har en Schmitt trigger som förbättrar + störningståligheten. + + +## Galvanisk isolation + +Kortet har galvanisk isolation mellan de digitala och analoga ingångarna och +ESP32-mikrokontrollern. Isolationen åstadkoms med digitala isolatorer för I2C +respektive de fyra digitala ingångarna, samt med en isolerad DC/DC-omvandlare +som matar den isolerade sektionen. + +Tack vare isolationen kan kortet strömförsörjas från NMEA 2000-nätverket utan +risk för jordslingor. Isolationen skyddar också mot spänningsspikar och +störningar på ingångarna. + +
+![](HALMET-isolation.jpg){ width="60%" } +
HALMET-kortets isolationsbarriär. Ingångsplintarna är isolerade från resten av +kortet, vilket innebär att de inte delar jord med kortets övriga delar.
+
+ +## Kontakter + +
+
+ +
+![](HALMET-conx-top.jpg){ width="100%" } +
HALMET-kortets kontakter, ovansidan.
+
+ +
+
+ +
+![](HALMET-conx-bottom.jpg){ width="100%" } +
HALMET-kortets kontakter, undersidan.
+
+ +
+
+ +### Kontakter på ovansidan + +1. NMEA 2000-kontakt. Kontakten är en 4-polig löstagbar kopplingsplint av + Phoenix MC 3.81-kompatibel typ. Den används för att ansluta kortet till ett + NMEA 2000-nätverk och för att strömförsörja kortet. + +2. 1-Wire-stiftlist. Med 1-Wire-stiftlisten kan du ansluta 1-Wire-givare till + kortet. Stiftlisten är 3-polig med 2,54 mm stiftavstånd. Den är inte + monterad på kortet som standard, eftersom den kan vara i vägen för + placeringen av panelkontakter i kapslingen. + +3. I2C-stiftlist. Med I2C-stiftlisten kan du ansluta I2C-givare till kortet. + Stiftlisten är 4-polig med 2,54 mm stiftavstånd. + +4. Micro USB-kontakt. Kontakten används för att programmera och felsöka kortet. + +5. Obestyckade lödytor för signalerna reset (EN) och boot (IO0). + +6. GPIO-stiftlist. GPIO-stiftlisten har 2×10 stift med 2,54 mm stiftavstånd. + Den för ut ESP32:s lediga GPIO-stift och kan även användas som JTAG-stiftlist. + +7. Stiftlist för det isolerade områdets strömförsörjning. Från stiftlisten kan + externa enheter matas från den isolerade sektionens 3V3 och GND. + +8. Bygelstift för de analoga ingångarnas konstantströmkälla (CCS). + Konstantströmkällan aktiveras genom att kortsluta bygelstiften med en bygel. + +9. Plintar för de analoga ingångarna. Plintarna är 2-poliga löstagbara + kopplingsplintar av Phoenix MC 3.81-kompatibel typ. De används för att + ansluta analoga givare till kortet. + +10. Plintar för de digitala ingångarna. Plintarna är 2-poliga löstagbara + kopplingsplintar av Phoenix MC 3.81-kompatibel typ. De används för att + ansluta digitala givare till kortet. + +### Kontakter på undersidan + +11. Lödbygel för CAN-terminering. Genom att löda ihop lödbygeln aktiveras + CAN-bussens termineringsmotstånd på 120 Ω. Använd inte termineringsmotståndet + i NMEA 2000-nätverk. + +12. Lödbygel för lågpassfilter. Genom att löda ihop lödbygeln aktiveras ett + lågpassfilter på motsvarande analoga ingång. Filtrets gränsfrekvens är + 2,3 kHz. Filtret kan till exempel användas för att minska bruset i en + varvräknarsignal. + +13. Lödbygel för pull-down-motstånd. Genom att löda ihop lödbygeln aktiveras ett + pull-down-motstånd på 100 kΩ på motsvarande digitala ingång. + Pull-down-motståndet kan användas för att läsa av en slutande kontakt (NO) + som dras hög när den sluts. + +14. Lödbygel för pull-up-motstånd. Genom att löda ihop lödbygeln aktiveras ett + pull-up-motstånd på 100 kΩ på motsvarande digitala ingång. + Pull-up-motståndet kan användas för att läsa av en brytande kontakt (NC) + som dras låg när den sluts. + +15. Lödbyglar för val av I2C-adress för ADS1115. Genom att löda ihop byglarna + väljer du I2C-adressen för AD-omvandlaren ADS1115. Byglarna används för att + undvika adresskonflikter när flera ADS1115-omvandlare är anslutna till + samma I2C-buss. Lödytorna kan också användas för att ansluta ytterligare + I2C-enheter till kortets isolerade område. + +### GPIO-referens + +HALMET reserverar ett antal GPIO-stift för ingångarnas kringkretsar. Lediga +GPIO-stift förs ut till GPIO-stiftlisten med 2×10 stift. Tabellen nedan listar +GPIO-stiften och deras funktioner. + +| GPIO | Funktion | Anmärkningar | +| ------: | :---------- | :------------------------------------------------- | +| 0 | Boot-knapp | Går till bootloader när stiftet dras lågt | +| 1 | TXD0 | Sänder data till USB | +| 2 | LED | Röd LED på kortet | +| 3 | RXD0 | Tar emot data från USB | +| 4 | 1-Wire DQ | 1-Wire-datalinje | +| 5 | - | Ledigt på GPIO-stiftlisten | +| 12 | - / TDI | Ledigt på GPIO-stiftlisten. Alternativt: JTAG TDI | +| 13 | - / TCK | Ledigt på GPIO-stiftlisten. Alternativt: JTAG TCK | +| 14 | - / TMS | Ledigt på GPIO-stiftlisten. Alternativt: JTAG TMS | +| 15 | - / TDO | Ledigt på GPIO-stiftlisten. Alternativt: JTAG TDO | +| 16 | - | Ledigt på GPIO-stiftlisten | +| 17 | - | Ledigt på GPIO-stiftlisten | +| 18 | CAN RX | Tar emot från NMEA 2000 | +| 19 | CAN TX | Sänder till NMEA 2000 | +| 21 | I2C SDA | I2C-datalinje. Används för analog ingång | +| 22 | I2C SCL | I2C-klocklinje. Används för analoga ingångar | +| 23 | DI1 | Digital ingång 1 | +| 25 | DI2 | Digital ingång 2 | +| 27 | DI3 | Digital ingång 3 | +| 26 | DI4 | Digital ingång 4 | +| 32 | - | Ledigt på GPIO-stiftlisten | +| 33 | - | Ledigt på GPIO-stiftlisten | +| 34 | - | Ledigt på GPIO-stiftlisten | +| 35 | - | Ledigt på GPIO-stiftlisten | +| 36 (VP) | Endast ingång | Ledigt på GPIO-stiftlisten | +| 39 (VN) | Endast ingång | Ledigt på GPIO-stiftlisten | + + +## Strömförsörjning + +Kortets tillåtna inspänningsområde är 5–32 V. Typisk strömförbrukning är 90 mA +vid 12 V med WiFi-modulen aktiv (motsvarar 1,1 W). + +## NMEA 2000 + +NMEA 2000 är en allmänt spridd kommunikationsstandard för att koppla samman givare, styrenheter och displayer på båtar och fartyg. Den bygger på Controller Area Network (CAN-bussen), en fordonsbusstandard som gör det möjligt för enheter att kommunicera med varandra utan en värddator. + +Kortet uppfyller NMEA 2000-standarden så länge ingen av de oisolerade kontakterna +är ansluten till andra enheter med jordreferens. Till exempel kan en +1-Wire-temperaturgivare med lång kabel användas, eftersom den inte delar jord med +andra enheter. Att däremot ansluta en I2C-AD-omvandlare till den oisolerade +I2C-kontakten skulle bryta överensstämmelsen med NMEA 2000. + +TODO: NMEA 2000 GPIO-stiftkonfiguration + +## Status-LED:er + +På HALMET-kortet finns två knappar och två LED:er. Knapparna är märkta Reset och Boot. Reset-knappen startar om kortet genom att dra ESP32:s Enable-stift lågt. Boot-knappen är ansluten till GPIO0 och kan under enhetens uppstart användas för att tvinga modulen till nedladdningsläge (download mode). I övrigt kan den användas som en vanlig knappingång. + +LED:erna är inte särskilt märkta. Den röda LED:en lyser så snart det finns 3,3 V spänning på kortet. Den blå LED:en är ansluten till GPIO2 (det stift som vanligen används för LED på ESP32-utvecklingskort). Den kan styras av användarens program för att visa enhetens tillstånd. + +## 1-Wire + +1-Wire är ett bussystem för kommunikation mellan enheter, utvecklat av Dallas Semiconductor som sedermera köpts upp av Maxim Integrated Products. Även om 1-Wire är ett långsamt protokoll och bara stöder hastigheter upp till 16,3 kbit/s är det mycket enkelt att implementera och fungerar över långa avstånd. Det används ofta för temperaturgivare och liknande enkla mätdon. + +HALMET-kortets 1-Wire-implementering har ESD- och RF-störningsfiltrering samt lågpassfiltrering för att förbättra nätverkets tillförlitlighet. + +Observera att 1-Wire-datastiftet (märkt ”DQ”) fysiskt är kopplat till GPIO4, så använd GPIO4 för all 1-Wire-data i ditt program. + +## I2C + +I2C (Inter-Integrated Circuit) är en mycket populär synkron seriell kommunikationsbuss som ofta används för att kommunicera med många olika kretsar. Den använder två dataledare utöver spänning och jord. + +HALMET använder I2C internt för AD-omvandlaren ADS1115. I2C-bussen förs också ut till en 4-polig stiftlist för anslutning av ytterligare I2C-enheter. + +I2C-bussen är ansluten till GPIO21 (SDA) och GPIO22 (SCL) på ESP32. Dessa stift är standardstiften för I2C i Arduinos ESP32-miljö, men skiljer sig från standardstiften på SH-ESP32. diff --git a/docs/sv/index.md b/docs/sv/index.md new file mode 100644 index 0000000..a83cf26 --- /dev/null +++ b/docs/sv/index.md @@ -0,0 +1,35 @@ +--- +title: Introduktion +translated_from: 864a9f606fb309bc3e706c3231d0ec7208b25eed +--- + +# Introduktion + +HALMET (Hat Labs Marine Engine & Tank interface) är ett utvecklingskort för att ansluta motor- och tankgivare på båtar och andra fordon. Det kan användas för att läsa digitala och analoga givare och för att ansluta till andra enheter via gränssnitten NMEA 2000, WiFi, Bluetooth, I2C, 1-Wire eller GPIO. + +
+![](halmet_v1_top_photo.jpg){ width="60%" } +
Bild på HALMET
+
+ +## Viktigaste egenskaper + +- **Fyra digitala ingångar**: HALMET har fyra digitala ingångar för att läsa digitala larmsignaler eller för att användas som räknare. Ingångarna tål spänningar mellan −32 V och +32 V. De digitala ingångarna kan användas både för att detektera signalnivåer och för tidsvarierande signaler som motorns varvtal, bränsleflöde eller pulser från en kättingräknare. + +- **Fyra analoga ingångar**: HALMET har fyra analoga ingångar för att läsa analoga givare. Ingångarna tål spänningar mellan −32 V och +32 V, med ett mätområde på 0–33 V. Ingångarna är anslutna till en 16-bitars ADS1115-AD-omvandlare. De analoga ingångarna kan användas både för passiv spänningsmätning och för aktiv resistansmätning. + +- **NMEA 2000-kompatibel**: HALMET är fullt kompatibel med standarden NMEA 2000. Kortet kan anslutas till ett NMEA 2000-nätverk via det inbyggda NMEA 2000-gränssnittet. + +- **I2C-, 1-Wire- och GPIO-gränssnitt**: HALMET har ett 4-poligt I2C-gränssnitt, ett 3-poligt 1-Wire-gränssnitt och 13 tillgängliga generella in- och utgångar (GPIO). + +- **WiFi- och Bluetooth-anslutning**: HALMET har en integrerad ESP32-WROOM-32E-modul med WiFi och Bluetooth. De gör det möjligt både att ansluta till befintliga WiFi-nätverk och att skapa en WiFi-accesspunkt för att ansluta direkt till kortet. + +- **ESP32-WROOM-32E med 16 MB flash**: ESP32-WROOM-32E-modulen ger gott om processorkraft och minne även för de mest krävande tillämpningarna. Med 16 MB flashminne kan stora datamängder lagras lokalt. + +- **Brett inspänningsområde**: HALMET kan matas säkert från det 12 V- eller 24 V-system som är vanligt i fordon och båtar. HALMET tål inspänningar mellan 5 V och 32 V. + +HALMET är öppen hårdvara och licensieras under Creative Commons Erkännande-DelaLika 4.0 Internationell. + +## Skaffa hårdvaran + +Du kan köpa HALMET-kort från [Hat Labs Oy](https://shop.hatlabs.fi). Alla konstruktionsfiler finns också i [GitHub-repositoriet för HALMET-hårdvaran](https://github.com/hatlabs/halmet-hardware/). diff --git a/docs/sv/revisions/index.md b/docs/sv/revisions/index.md new file mode 100644 index 0000000..5482dfb --- /dev/null +++ b/docs/sv/revisions/index.md @@ -0,0 +1,23 @@ +--- +title: Hårdvaruversioner +translated_from: b998495eda7b60a66b73cfc622807d9d9c4e8043 +--- + +# Hårdvaruversioner + +## Introduktion + +Den här sidan dokumenterar kortets olika versioner och länkar till kopplingsschemana. Hela historiken för konstruktionsfilerna finns i [GitHub-repositoriet HALMET-hardware](https://github.com/hatlabs/HALMET-hardware). + + +## Version 1.0.0 + +Första publicerade versionen. + +Kopplingsscheman: [HALMET-v1.0.0-schema.pdf](HALMET-v1.0.0-schema.pdf) + +## Version 1.0.1 + +Rättelser och förbättringar av monteringstrycket. Lödytor för 3V3 och GND på det isolerade området. + +Kopplingsscheman: [HALMET-v1.0.1-schema.pdf](HALMET-v1.0.1-schema.pdf) diff --git a/docs/sv/software/index.md b/docs/sv/software/index.md new file mode 100644 index 0000000..3e6216b --- /dev/null +++ b/docs/sv/software/index.md @@ -0,0 +1,16 @@ +--- +title: Programvara +translated_from: 4a66b76add4ab5ef880e7daff125e78b9d34e212 +--- + +# Programvara + +## Introduktion + +Som utvecklingskort levereras HALMET utan förinstallerad programvara. Du måste själv installera lämplig programvara. Det är inte svårt, men viss tidigare erfarenhet av mikrokontrollerkort som Arduino eller ESP32 Devkit rekommenderas. + +Exempelfirmware för HALMET finns i [GitHub-repositoriet HALMET-example-firmware](https://github.com/hatlabs/HALMET-example-firmware). + +Observera att stöd i frågor om programvaruutveckling endast ges via [Hat Labs diskussionsforum](https://github.com/hatlabs/discussions/discussions). + +Fler anvisningar kommer inom kort. diff --git a/docs/sv/tutorials/index.md b/docs/sv/tutorials/index.md new file mode 100644 index 0000000..8841a88 --- /dev/null +++ b/docs/sv/tutorials/index.md @@ -0,0 +1,6 @@ +--- +title: Guider och exempelprojekt +translated_from: 879db3c0579a621737332a0896bb66329d0f188c +--- + +HALMETs guider och exempelprojekt kommer att listas på den här sidan. diff --git a/docs/sv/usage/index.md b/docs/sv/usage/index.md new file mode 100644 index 0000000..bc95746 --- /dev/null +++ b/docs/sv/usage/index.md @@ -0,0 +1,98 @@ +--- +title: Användning +translated_from: 62b94ac6364a19f44074c56bd610d243063e9847 +--- + +# Användning + +## Vanliga användningsfall + +Det här avsnittet innehåller praktisk information om hur du läser olika typer av givare och ansluter HALMET till andra enheter. + +### Programvaruinstallation + +HALMET är ett utvecklingskort och levereras utan förinstallerad programvara. +Du måste själv installera lämplig programvara. Det är inte svårt, men viss tidigare erfarenhet av mikrokontrollerkort som Arduino eller ESP32 Devkit rekommenderas. + +HALMETs dokumentation utgår från att du använder [HALMETs exempelfirmware](https://github.com/hatlabs/HALMET-example-firmware). Den bygger på ramverket [SensESP](https://signalk.org/SensESP/) och ger relativt enkel tillgång till kortets funktioner. + +[SensESPs guide för att komma igång](https://signalk.org/SensESP/pages/getting_started/) innehåller detaljerade anvisningar för att installera den utvecklingsmiljö som behövs för att kompilera och installera firmware. Anvisningarna är skrivna för generiska ESP32-enheter, men de gäller även HALMET. Använd bara [HALMETs exempelfirmware](https://github.com/hatlabs/HALMET-example-firmware) i stället för SensESPs projektmall. + +Observera att även om SensESPs dokumentation utgår från Signal K är HALMET fullt användbar också som fristående NMEA 2000-enhet. + +Om du inte vill använda SensESP kan du också skapa en egen firmware med Arduino IDE eller ESP-IDF. För många användningsfall är även ESPHome ett utmärkt alternativ. + +**OBS:** GPIO-stiftens användning på HALMET skiljer sig något från stiftindelningen på både ESP32 Devkit och SH-ESP32. Om du anpassar någon annan programvara än HALMETs exempelfirmware måste du kontrollera stiftindelningen. Se [GPIO-referensen](../hardware/index.md#gpio-referens) för mer information. + +### Använda de digitala ingångarna + +HALMET har fyra digitala ingångar. De kan användas för att läsa digitala larmsignaler eller som räknare. Det här avsnittet beskriver hur ingångarna används i olika vanliga fall. Anvisningarna utgår från HALMETs exempelfirmware. + +De digitala ingångarna D1–D4 är anslutna till GPIO-stiften 23, 25, 27 respektive 26. Ingångarna tål spänningar mellan −32 V och +32 V. Tröskelspänningen för att detektera en hög signal är cirka 1,55 V, med en hysteres på cirka 0,7 V. + +### Ansluta digitala larm + +Det här avsnittet beskriver hur HALMET ansluts till olika på/av-signaler, till exempel motor- eller länslarm. + +#### Hårdvaruinstallation + +Vanligtvis kan olika på/av-signaler som motor- eller länslarm anslutas direkt till HALMETs digitala ingångar. En pull-up eller pull-down kan behövas beroende på signaltypen. + +I figuren nedan, i exempel (a), finns redan en glödlampa i kretsen. När strömbrytaren är öppen drar glödlampan ned spänningen på D1. Ingen extra pull-down behövs.[^1] I exempel (b) finns däremot ingen annan last i kretsen. Om strömbrytaren är öppen blir spänningen på D2 flytande och ingången blir slumpmässigt antingen hög eller låg. I det fallet måste det inbyggda pull-down-motståndet aktiveras genom att lödbygeln på kortets baksida löds ihop. + +
+![](digin_pullup_pulldown.svg){ width="60%" } +
Digitala ingångar i olika användningsfall. (a) Det finns redan en lampa i kretsen. (b) Ingen annan last i kretsen, strömbrytaren drar signalen hög när den sluts. (c) Strömbrytaren drar signalen låg när den sluts.
+
+ +[^1]: Om panelbelysningen är gjord med lysdioder räcker spänningsfallet över lysdioderna kanske inte till för att dra ned spänningen till en tillräckligt låg nivå. Då måste pull-down-motståndet aktiveras. + +
+![](solder_jumpers.jpg){ width="60%" } +
Lödbyglarna på kortets baksida kan lödas ihop för att aktivera de inbyggda pull-up- eller pull-down-motstånden.
+
+ +På samma sätt kan det inbyggda pull-up-motståndet behöva aktiveras om strömbrytaren drar signalen låg när den sluts, som i exempel (c). + +Slutligen, om larmkontakterna är brytande (NC), är hanteringen omvänd. När kontakten öppnar dras ingångsspänningen upp eller ned beroende på kretsen. Då kan det inbyggda pull-up- eller pull-down-motståndet behöva aktiveras. + +#### Programvaruinstallation + +HALMETs exempelfirmware har hjälpmetoden `ConnectAlarmSender()` för att konfigurera och ansluta digitala ingångar. Se `main.cpp` från rad 177 och framåt. Både aktivt höga och aktivt låga signaler stöds. + +### Digitala ingångar som räknare + +HALMETs digitala ingångar kan också användas som räknare. Det är användbart till exempel för att räkna motorns varv eller pulser från en kättingräknare. + +#### Hårdvaruinstallation + +Sådana givare drivs vanligtvis aktivt i båda riktningarna, så ingen pull-up eller pull-down behövs. Om du ansluter HALMET till en utgång med låg impedans, till exempel generatorns W-uttag, är det klokt att sätta en linjesäkring i serie för att skydda ledaren mot kortslutning på grund av skavning eller andra skador. I övrigt kan du ansluta givaren direkt till den digitala ingången. + +Om pulskällan är mycket brusig och varvtalsavläsningen hoppar kan ett lågpassfilter aktiveras genom att LP-lödbygeln på kortets baksida löds ihop. Lågpassfiltrets gränsfrekvens är cirka 2,3 kHz, vilket bör passa för tillämpningar som ingångar från generatorns W-uttag. + +#### Programvaruinstallation + +HALMETs exempelfirmware innehåller en pulsräknare som kan aktiveras på någon av eller alla de digitala ingångarna. Se exempelkonfigurationen i `main.cpp` från rad 214 och framåt. + +### Använda de analoga ingångarna + +HALMET har fyra analoga ingångar som kan användas antingen för passiv spänningsmätning eller för aktiv resistansmätning. Det här avsnittet beskriver hur ingångarna används i olika vanliga fall. + +#### Hårdvaruinstallation + +De analoga ingångarna A1–A4 är anslutna till en AD-omvandlare av typen ADS1115. ADS1115 har 16 bitars upplösning och en högsta samplingsfrekvens på 860 sampel per sekund. HALMETs analoga ingångar har dock ett kraftigt lågpassfilter med en gränsfrekvens på cirka 160 Hz. Det räcker ändå gott och väl för att mäta utsignaler från fysiska givare, till exempel tanknivågivare eller motorns tryckgivare. + +I figuren nedan visar exempel (a) en befintlig mätare i motorpanelen ansluten till en resistiv givare. Mätarna i motorpaneler är oftast antingen termostatiska eller magnetiska. I båda fallen fungerar mätaren och givaren som en spänningsdelare, och spänningen över givaren är proportionell mot den uppmätta storheten. Den spänningen kan mätas med HALMETs analoga ingångar utan att den ursprungliga mätarens funktion störs. På grund av spänningsdelaren korrelerar spänningen kanske inte linjärt med den uppmätta storheten, men det kan kompenseras i programvaran. + +
+![](analog_input.svg){ width="60%" } +
Anslutning av analoga ingångar med och utan en befintlig mätare. (a) Med en befintlig mätare, använd HALMET i läget för passiv spänningsmätning. (b) När ingen annan enhet finns, använd HALMET i läget för aktiv resistansmätning.
+
+ + +Exempel (b) visar ett fall utan befintlig mätare. Givaren ansluts direkt till HALMETs analoga ingång. Då måste HALMET ge matningsspänning till givaren. HALMET utför resistansmätningen med en konstantströmkälla på 10 mA. Strömmen på 10 mA ger en spänningsskillnad på 1 volt över en resistans på 100 Ω, vilket ger en största resistans på cirka 300 Ω. Konstantströmkällan aktiveras genom att en bygel sätts över stiftparet på CCS-bygelstiften (constant current source, konstantströmkälla). Se figuren nedan. + +
+![](ccs_jumpers.jpg){ width="60%" } +
Figuren visar konstantströmkällan aktiverad för de analoga ingångarna A2 och A4.
+
diff --git a/mkdocs.yml b/mkdocs.yml index 289751e..69f4867 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,7 +58,174 @@ plugins: Tutorials and Examples: Ohjeet ja esimerkit Hardware Revisions: Laitteistoversiot Errata: Tunnetut virheet - + - locale: fr + name: "Français" + build: true + site_name: "HALMET : interface moteur et réservoir de Hat Labs" + site_description: "Guide d'utilisation de HALMET — carte de mesure des capteurs moteur et réservoir à base d'ESP32, pour bateaux" + admonition_translations: + note: "Note" + warning: "Avertissement" + tip: "Astuce" + info: "Information" + danger: "Danger" + example: "Exemple" + nav_translations: + "Introduction": "Introduction" + "Getting Started": "Prise en main" + "Usage": "Utilisation" + "Hardware": "Matériel" + "Software": "Logiciel" + "Tutorials and Examples": "Tutoriels et exemples" + "Hardware Revisions": "Versions de la carte" + "Errata": "Problèmes connus" + - locale: de + name: "Deutsch" + build: true + site_name: "HALMET: Hat Labs Schnittstelle für Motor- und Tanksensoren" + site_description: "HALMET-Benutzerhandbuch — ESP32-basierte Messplatine für Motor- und Tanksensoren auf Booten" + admonition_translations: + note: "Hinweis" + warning: "Warnung" + tip: "Tipp" + info: "Info" + danger: "Gefahr" + example: "Beispiel" + nav_translations: + "Introduction": "Einführung" + "Getting Started": "Erste Schritte" + "Usage": "Verwendung" + "Hardware": "Hardware" + "Software": "Software" + "Tutorials and Examples": "Tutorials und Beispiele" + "Hardware Revisions": "Hardware-Revisionen" + "Errata": "Bekannte Fehler" + - locale: sv + name: "Svenska" + build: true + site_name: "HALMET: Hat Labs gränssnitt för motor- och tankgivare" + site_description: "Dokumentation för HALMET — ett ESP32-baserat gränssnittskort för motor- och tankgivare i båtar" + admonition_translations: + note: "Observera" + warning: "Varning" + tip: "Tips" + info: "Information" + danger: "Fara" + example: "Exempel" + nav_translations: + "Introduction": "Introduktion" + "Getting Started": "Kom igång" + "Usage": "Användning" + "Hardware": "Hårdvara" + "Software": "Programvara" + "Tutorials and Examples": "Guider och exempel" + "Hardware Revisions": "Hårdvaruversioner" + "Errata": "Kända fel" + - locale: es + name: "Español" + build: true + site_name: "HALMET: interfaz náutica de motor y tanques de Hat Labs" + site_description: "Documentación de HALMET, una placa de interfaz basada en ESP32 para sensores de motor y tanque en embarcaciones" + admonition_translations: + note: "Nota" + warning: "Advertencia" + tip: "Consejo" + info: "Información" + danger: "Peligro" + example: "Ejemplo" + nav_translations: + "Introduction": "Introducción" + "Getting Started": "Primeros pasos" + "Usage": "Uso" + "Hardware": "Hardware" + "Software": "Software" + "Tutorials and Examples": "Tutoriales y ejemplos" + "Hardware Revisions": "Versiones del hardware" + "Errata": "Errores conocidos" + - locale: it + name: "Italiano" + build: true + site_name: "HALMET: interfaccia nautica Hat Labs per sensori di motore e serbatoio" + site_description: "Documentazione di HALMET, scheda di interfaccia basata su ESP32 per il collegamento di sensori di motore e serbatoio a bordo di imbarcazioni e altri veicoli" + admonition_translations: + note: "Nota" + warning: "Avvertenza" + tip: "Suggerimento" + info: "Informazione" + danger: "Pericolo" + example: "Esempio" + nav_translations: + "Introduction": "Introduzione" + "Getting Started": "Primi passi" + "Usage": "Utilizzo" + "Hardware": "Hardware" + "Software": "Software" + "Tutorials and Examples": "Tutorial ed esempi" + "Hardware Revisions": "Revisioni hardware" + "Errata": "Problemi noti" + - locale: nl + name: "Nederlands" + build: true + site_name: "HALMET: motor- en tankinterface van Hat Labs" + site_description: "Documentatie voor HALMET — een ESP32-print voor het uitlezen van motor- en tanksensoren op boten en andere voertuigen" + admonition_translations: + note: "Opmerking" + warning: "Waarschuwing" + tip: "Tip" + info: "Info" + danger: "Gevaar" + example: "Voorbeeld" + nav_translations: + "Introduction": "Inleiding" + "Getting Started": "Aan de slag" + "Usage": "Gebruik" + "Hardware": "Hardware" + "Software": "Software" + "Tutorials and Examples": "Tutorials en voorbeelden" + "Hardware Revisions": "Hardwareversies" + "Errata": "Bekende fouten" + - locale: nb + name: "Norsk bokmål" + build: true + site_name: "HALMET: Hat Labs' grensesnitt for motor- og tankgivere" + site_description: "Brukerveiledning for HALMET — et ESP32-basert grensesnittkort for motor- og tankgivere i båt" + admonition_translations: + note: "Merk" + warning: "Advarsel" + tip: "Tips" + info: "Informasjon" + danger: "Fare" + example: "Eksempel" + nav_translations: + "Introduction": "Innledning" + "Getting Started": "Kom i gang" + "Usage": "Bruk" + "Hardware": "Maskinvare" + "Software": "Programvare" + "Tutorials and Examples": "Veiledninger og eksempler" + "Hardware Revisions": "Maskinvareversjoner" + "Errata": "Kjente feil" + - locale: da + name: "Dansk" + build: true + site_name: "HALMET: Hat Labs' maritime motor- og tankgrænseflade" + site_description: "Dokumentation til HALMET — et ESP32-baseret kort til aflæsning af motor- og tankgivere på både" + admonition_translations: + note: "Bemærk" + warning: "Advarsel" + tip: "Tip" + info: "Info" + danger: "Fare" + example: "Eksempel" + nav_translations: + "Introduction": "Introduktion" + "Getting Started": "Kom godt i gang" + "Usage": "Brug" + "Hardware": "Hardware" + "Software": "Software" + "Tutorials and Examples": "Vejledninger og eksempler" + "Hardware Revisions": "Hardwareversioner" + "Errata": "Kendte fejl" markdown_extensions: - admonition - pymdownx.details diff --git a/scripts/check_glossary.py b/scripts/check_glossary.py index aae0b56..f4831a0 100644 --- a/scripts/check_glossary.py +++ b/scripts/check_glossary.py @@ -28,6 +28,14 @@ GLOSSARIES = { "fi": "finnish-glossary.md", + "fr": "french-glossary.md", + "de": "german-glossary.md", + "sv": "swedish-glossary.md", + "es": "spanish-glossary.md", + "it": "italian-glossary.md", + "nl": "dutch-glossary.md", + "nb": "norwegian-glossary.md", + "da": "danish-glossary.md", } ROW = re.compile(r"^\| *`?([^|`]+?)`? *\| *`?([^|`]+?)`? *\|") @@ -89,9 +97,23 @@ def inflectable(term: str) -> re.Pattern[str]: obturateur`, so anchoring on the phrase as written finds neither. A verb phrase also takes its object in the middle — `aseta CM5 uudelleen paikalleen` — so a couple of words are allowed to intervene. + + The match must start at a word boundary, or a compounding language reports + a term as used when only a longer word containing it is present: Finnish + `virtalähde` (power supply) is a substring of `vakiovirtalähde` (constant + current source), two different components. Without the boundary this check + returns a false green, which is worse than a false alarm — a checker that + passes when it should not is no checker at all. + + The boundary only applies when the term starts with a word character. A row + like `−32 V and +32 V` opens with a minus sign, and `\\b` before a non-word + character asserts the opposite of what is meant — it would demand a letter + immediately before the minus and match nothing. """ words = [re.escape(w[: max(3, len(w) - 3)]) + r"\w*" for w in fold(term).split()] - return re.compile(r"(?:\W+\w+){0,2}\W+".join(words)) + body = r"(?:\W+\w+){0,2}\W+".join(words) + boundary = r"\b" if re.match(r"\w", fold(term)) else "" + return re.compile(boundary + body) def main() -> int: diff --git a/scripts/check_typography.py b/scripts/check_typography.py index 04628cc..15c0985 100644 --- a/scripts/check_typography.py +++ b/scripts/check_typography.py @@ -20,17 +20,22 @@ # Which mark opens a quotation, and which closes it, per language. QUOTES = { - "fi": ("”", "”"), # ”…” — the same character opens and closes + "fi": ("”", "”"), # ”…” — same character both sides + "fr": ("«", "»"), # «…» + "de": ("„", "“"), # „…“ + "sv": ("”", "”"), # ”…” + "es": ("«", "»"), # «…» + "it": ("“", "”"), # “…” + "nl": ("“", "”"), # “…” + "nb": ("«", "»"), # «…» + "da": ("»", "«"), # »…« — outward, the opposite of Norwegian } # French is the one language that *requires* a space before ; : ! ? — and # requires it to be unbreakable, so the line never breaks before the mark. # Everywhere else any space there is an error, which is why this cannot be one # rule for all: applying the French habit elsewhere is a known leak, and # applying the majority rule to French would flag every correct sentence. -# French is the one language that requires a space before ; : ! ? and requires -# it unbreakable. No language here does, but the exception is kept named so -# that adding French later is a one-line change rather than a rediscovery. -SPACE_REQUIRED: set[str] = set() +SPACE_REQUIRED = {"fr"} PLAIN_SPACE_BEFORE_PUNCT = re.compile(r"\u0020[;:!?]") # German compounds a multi-word proper name with hyphens throughout — # NMEA-2000-Netzwerk, Signal-K-Server — and its glossary calls a missing hyphen @@ -41,16 +46,12 @@ # ones. One rule cannot serve all three cases, so each is scoped to where its # glossary asks for it. HYPHEN_CHAINS = re.compile(r"NMEA-2000|Signal-K|Raspberry-Pi|Compute-Module") -# German compounds a proper name with hyphens throughout — NMEA-2000-Netzwerk — -# where every other language treats that chain as an error. -CHAINS_ALLOWED: set[str] = set() +CHAINS_ALLOWED = {"de"} JUNCTION_HYPHEN = re.compile( r"\b(?:HALPI2|HaLOS|NMEA 2000|Signal K|Raspberry Pi|E7T)-" r"[a-z\u00e1\u00e9\u00ed\u00f3\u00fa\u00f1\u00e0\u00e8\u00ec\u00f2\u00f9]" ) -# Romance languages take no hyphen between a product name and a common noun; -# Finnish and the other Germanic languages take one at the junction. -JUNCTION_FORBIDDEN: set[str] = set() +JUNCTION_FORBIDDEN = {"es", "it"} SPACE_BEFORE_PUNCT = re.compile(r"[   ][;:!?]") diff --git a/solutions/translation/danish-glossary.md b/solutions/translation/danish-glossary.md new file mode 100644 index 0000000..bd83428 --- /dev/null +++ b/solutions/translation/danish-glossary.md @@ -0,0 +1,628 @@ +--- +title: Danish translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Danish under docs/da/ + - Reviewing a Danish translation for consistency + - Adding a new term that has no established Danish equivalent +tags: + - translation + - i18n + - danish + - terminology + - mkdocs-static-i18n +--- + +# Danish translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Danish under `docs/da/`, using the `mkdocs-static-i18n` folder structure. +Each page is `docs/en/
/index.md`, and its translation lives at the +mirrored path: `docs/en/hardware/index.md` becomes `docs/da/hardware/index.md`. +Only markdown lives under `docs/da/`; images and other assets stay with the +English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with +two different Danish words. `carrier board` → `bærekort` is the HALPI2 call and +stands here too, even though HALMET is not a carrier board — see the note under +*Enclosure, mounting, and installation*. Terms below the `## HALMET terms` +heading are additions this product needed; everything above it is shared with +HALPI2, and **a change to a shared row must be made in both repositories or in +neither.** + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *drop cable* becomes `dropkabel` on one page and `nedstikskabel` +on the next — and the result reads as machine output even when each individual +sentence is correct. Extend this file when a page introduces a term it does not +cover, rather than inventing a one-off translation. + +`dutch-glossary.md`, `finnish-glossary.md`, `french-glossary.md`, +`german-glossary.md`, `italian-glossary.md`, `norwegian-glossary.md`, +`spanish-glossary.md` and `swedish-glossary.md` are the siblings of this file. +The general approach is the same in all of them; the section below is where it +must not be. + +## Five rules where the siblings are wrong for Danish + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary. Norwegian is the dangerous one: +it is close enough to Danish that a wrong form does not look wrong, and it is +being written at the same time as this language. + +Each rule ends with the count that proves it. Run the counts; do not reread the +prose. Every language branch so far shipped a typography rule that had been read +rather than measured, and it looked followed right up until a reviewer counted. + +1. **Quotation marks are `»…«`, pointing outward.** Opening `»` (U+00BB), + closing `«` (U+00AB). This is the exact reverse of Norwegian's `«…»`, and it + is neither German's `„…"` nor Swedish's `"…"` nor French's spaced `« … »`. + + *Count:* `grep -roE '«[^»]{0,120}»' docs/da | wc -l` must be **0** — every hit + is a Norwegian-order quote. `grep -roc '»' docs/da` and `grep -roc '«' docs/da` + must give the same total. + +2. **Address the reader as `du`.** Danish technical and consumer documentation + uses `du` throughout; the polite `De` is archaic and reads as parody in a + product manual. German's `Sie` and French's *vouvoiement* are both wrong here. + Instructions take the imperative: `Tilslut strømkablet.` / + `Kontrollér polariteten med multimeteret, før du tænder for spændingen.` + + *Count:* `grep -rnE '\b(De|Dem|Deres)\b' docs/da` must return **0** hits that + are not sentence-initial `De` meaning *they*. Every page with instructions + must have at least one `du`/`dig`/`din`/`dit`/`dine`. + +3. **No space before `; : ! ?`** — as in German, Swedish and Norwegian, and + unlike French, whose rule is the exact opposite and demands a no-break space. + + *Count:* with code fences stripped, `grep -rnE ' [;:!?]' docs/da` must return + **0**. + +4. **Compounding with a proper name takes one hyphen at the junction, not + throughout.** Danish writes `NMEA 2000-netværk`, `Signal K-server`, + `Raspberry Pi-antenne`, `Compute Module 5-stik`. German writes + `NMEA-2000-Netzwerk` — hyphens all the way through — and copying that pattern + into Danish is wrong. Ordinary compounds are written **solid**, no hyphen and + no space: `kabelforskruning`, `strømforsyning`, `strømafbrydelsestimer`, + `indgangsspændingsområde`. A space inside a compound is the most visible + marker of a machine-translated Danish page. + + *Count:* `grep -rnE 'NMEA-2000|Signal-K|Raspberry-Pi|Compute-Module' docs/da` + must return **0**. `grep -rnE 'NMEA 2000[a-zæøå]' docs/da` must return **0** + (a Danish head word glued on without the hyphen). + +5. **Danish is not Norwegian.** These are the forms that leak, in the order they + leak. Left is Danish and correct; right is Norwegian and must not appear. + + | Write | Never write | Where it shows up | + |:------|:------------|:------------------| + | `af` | `av` | everywhere — the highest-frequency tell | + | `-tion` (`installation`, `konfiguration`, `isolation`) | `-sjon` | every second page | + | `netværk` | `nettverk` | NMEA 2000, Ethernet | + | `spænding`, `spændingsfald` | `spenning`, `spenningsfall` | electrical sections | + | `vand`, `vandtæt`, `lænsevand` | `vann`, `vanntett` | mounting, enclosure | + | `kun` | `berre` | prerequisites, warnings | + | `ikke` | `ikkje` | warnings | + | `hvordan` | `korleis` | procedures | + | `nedlukning` | `nedstenging` | shutdown sections | + + *Count:* `grep -rniwE 'av|ikkje|berre|korleis|vann|nettverk|spenning' docs/da` + must return **0**, and `grep -rniE '[a-zæøå]sjon' docs/da` must return **0**. + +## Names that are never translated + +Identical in principle to the sibling glossaries; only the product list is +HALMET's. Product names, protocol names, hardware standards and software UI +strings stay in English. + +- **Products and software:** HALMET, HALPI2, SH-ESP32, SH-RPi, SensESP, + Signal K, Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, + I2C, 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, + Schmitt trigger, IoT +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `GPIO2`, `CCS`, `LP`, `VP`, `VN`, + `3V3`, `GND`. These are printed on the board, and a translated pin name sends + the reader looking for a label that does not exist. The same goes for the + button legends `Reset` and `Boot` and for the input names `DI1`–`DI4`. + +Command names, file paths, configuration keys, source filenames (`main.cpp`), +function names (`ConnectAlarmSender()`) and everything inside a code fence stay +exactly as the English source has them — including comments inside fences. +Command output is never touched. URLs and image filenames are never touched. + +Mode names stay English, the head noun is Danish: `boot-tilstand`, +`download-tilstand`. + +## Units and numbers + +Same handling as the other languages — the English source writes `12V` and +`0.9A`, and both are wrong in Danish. + +| English source | Danish | +|:---------------|:-------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | +| `250 kbps` | `250 kbit/s` | +| `2m`, `45mm` | `2 m`, `45 mm` | + +Decimal comma in every measured value. Version numbers, firmware versions and +file paths keep their dots: `v0.6.1`, `3.1.0`, `/dev/ttyAMA4`. + +*Count:* outside code fences, `grep -rnE '[0-9](V|A|W|Hz|Ω|mm|m |kg|°C)' docs/da` +must return **0** (missing space before the unit), and +`grep -rnE '[0-9]+-[0-9]+ *(V|A|°C|mA)' docs/da` must return **0** (hyphen +instead of en dash in a range). + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry a language segment; image captions and alt texts are +translated but filenames are not; screenshots stay English because the reader's +own screen is English; standard admonition titles are translated centrally in +`mkdocs.yml`, custom ones in the page. + +## Glossary + +### Enclosure, mounting, and installation + +| English | Danish | Note | +|:--------|:-------|:-----| +| carrier board | bærekort | The accurate term, as in French, German and Swedish | +| enclosure | kabinet | | +| enclosure lid | kabinetlåg | | +| gasket | pakning | | +| heat sink | køleplade | | +| ingress protection (IP rating) | kapslingsklasse | `kapslingsklasse IP65` | +| waterproof | vandtæt | Not the Norwegian `vanntett` | +| wall-mount | vægmontering | | +| mounting surface | monteringsflade | | +| mounting screw | monteringsskrue | | +| countersunk screw | undersænket skrue | | +| standoff | afstandsbolt | | +| pilot hole (you drill it) | styrehul | `Bor styrehuller til monteringsskruerne` | +| pre-drilled hole (already in the enclosure) | forboret hul | `Kabinettet har forborede huller til panelstik` | +| mounting template | boreskabelon | | +| bilge water | lænsevand | `Monter over det forventede lænsevandsniveau` | +| bulkhead | skot | | +| cable gland | kabelforskruning | | +| cable routing | kabelføring | | +| service loop | servicesløjfe | Slack left at both cable ends | +| cable tie | kabelbinder | Not the colloquial `strips` | +| blind plug | blindprop | | +| breather plug | trykudligningsprop | | +| thermal pad | termisk pude | | +| silk screen | silketryk | | + +**Two holes, two words.** `styrehul` is a hole *you* drill; `forboret hul` is a +hole the enclosure already ships with. Danish has one obvious root for both +(`forbore`), and using it for both produces the nonsense instruction *bor +forborede huller* — "drill pre-drilled holes" — which is exactly what happened +in Swedish. Keep the two words apart. + +**A note on `bærekort`.** Danish takes the accurate term, like French +(`carte porteuse`), German (`Trägerplatine`) and Swedish (`bärkort`), and unlike +Finnish (`emolevy`, literally *motherboard*, chosen there for reader +familiarity). The divergence between the languages is deliberate, decided per +language and per audience. Do not harmonise them. + +`bærekort` carries the CM5/board relationship on its own, so passages about +reseating the CM5 or troubleshooting a board that will not boot need no extra +explanation. Only the Finnish glossary needs that warning. + +**In HALMET the row is inherited, not used.** HALMET carries no compute module +and is never called a carrier board in the English source; it is a development +board, `udviklingskort` (see `## HALMET terms`). The row stays because the two +products share this file's decisions — not because `bærekort` describes HALMET. + +### Power and electrical + +| English | Danish | Note | +|:--------|:-------|:-----| +| power supply | strømforsyning | Both the function and the external unit | +| power rail | spændingsskinne | Later mentions: `3,3 V-skinnen` | +| input voltage range | indgangsspændingsområde | | +| polarity | polaritet | | +| reverse polarity protection | beskyttelse mod omvendt polaritet | | +| fuse | sikring | | +| inline fuse | ledningssikring | | +| circuit breaker | automatsikring | | +| current limiting | strømbegrænsning | | +| current limiter | strømbegrænser | | +| current limit switch | strømbegrænsningskontakt | | +| overcurrent | overstrøm | | +| voltage drop | spændingsfald | Not the Norwegian `spenningsfall` | +| grounding | jordforbindelse | | +| ground loop | jordsløjfe | | +| short circuit | kortslutning | | +| galvanic isolation | galvanisk adskillelse | | +| wire gauge | ledertværsnit | Danish uses mm², not AWG | +| marine-grade wire | marinegodkendt ledning | | +| wire strippers | afisoleringstang | | +| crimping | krimpning | | +| crimper | krimptang | | +| heat-shrink tubing | krympeflex | | +| heat gun | varmepistol | | +| multimeter | multimeter | | +| terminal block | klemrække | The pluggable Phoenix connector on the board | +| strain relief | trækaflastning | | +| super-capacitor | superkondensator | | +| real-time clock | realtidsur | | +| backup battery | backupbatteri | | + +### Connectors and interfaces + +| English | Danish | Note | +|:--------|:-------|:-----| +| connector | stik / tilslutning | `tilslutning` for a board-mounted socket | +| panel connector | panelstik | | +| barrel connector | DC-jackstik | First mention: `DC-jackstik (barrel)` | +| header | stikliste | `40-benet GPIO-stikliste` | +| pin | ben | `Kortslut benene` | +| pitch | benafstand | `3,81 mm benafstand` | +| jumper | jumper | | +| solder jumper | loddejumper | | +| switch (physical) | kontakt | | +| backbone | backbone | Established in Danish NMEA 2000 usage | +| drop cable | dropkabel | | +| T-connector | T-stik | | +| terminator | terminering | The function; the part is `termineringsmodstand` | +| termination resistor (120 Ω) | termineringsmodstand | | +| front panel | frontpanel | | +| flexible flat cable (FFC) | fladkabel (FFC) | | +| male / female | hanstik / hunstik | | +| port | port | | + +### Operation and system behaviour + +| English | Danish | Note | +|:--------|:-------|:-----| +| boat computer | bådcomputer | | +| to boot | starte | Booting: `opstart` | +| first boot | første opstart | | +| shutdown | nedlukning | Not the Norwegian `nedstenging` | +| to shut down | lukke ned | | +| graceful shutdown | kontrolleret nedlukning | | +| to power-cycle | slukke og tænde igen | Not a noun in Danish | +| reboot / restart | genstart | | +| power loss | strømsvigt | The loss of input power the controller detects | +| blackout | strømafbrydelse | Timer: `strømafbrydelsestimeren` — one solid compound | +| power management | strømstyring | | +| status LED | status-LED | | +| indicator | indikator | | +| monitoring | overvågning | | +| passive cooling | passiv køling | | +| filesystem | filsystem | | +| to unmount | afmontere | Both senses: a filesystem, and physically removing the CM5 or the carrier board | +| to reseat | genmontere | | +| watchdog | watchdog | | +| standby | standby | | +| mode | tilstand | `Solo-tilstand`, `Co-op-tilstand` | +| controller | controller | The RP2040 on the carrier board; also `mikrocontroller` | + +### Software and networking + +| English | Danish | Note | +|:--------|:-------|:-----| +| firmware | firmware | Not `fast programmel` — matches the sibling decision to keep the trade term | +| daemon | dæmon | First mention: `dæmon (baggrundstjeneste)` | +| to flash | flashe | | +| system image | systemimage | `et systemimage`, `systemimaget` — the trade says *image*, not *aftryk* | +| operating system image | styresystemimage | | +| container image | containerimage | | +| container app | containerapp | | +| headless | uden skærm | First mention: `uden skærm (headless)` | +| dashboard | dashboard | Kept: it is the name of the HaLOS page the reader opens | +| web interface | webgrænseflade | | +| browser | browser | | +| credentials | loginoplysninger | | +| username | brugernavn | | +| default password | standardadgangskode | | +| single sign-on (SSO) | single sign-on (SSO) | | +| Certificate Authority (CA) | certifikatmyndighed (CA) | | +| WiFi Access Point | WiFi-adgangspunkt | Keep `WiFi Access Point` where it names a UI string | +| wired / wireless | kablet / trådløs | | +| remote access | fjernadgang | | +| setting | indstilling | | +| update | opdatering | | +| package | pakke | | +| command line tool | kommandolinjeværktøj | | + +### Applications and use cases + +| English | Danish | Note | +|:--------|:-------|:-----| +| chart plotter | kortplotter | | +| data logging | datalogning | | +| vessel | fartøj | `båd` only where the source says *boat* | +| depth sounder | ekkolod | | +| wind instrument | vindmåler | | +| GPS receiver | GPS-modtager | | +| fleet management | flådestyring | | +| predictive maintenance | forudsigende vedligeholdelse | | +| remote monitoring | fjernovervågning | | +| compliance | overensstemmelse | | +| warranty | garanti | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. Rows above +this heading are shared with HALPI2 and must not be changed here alone. A few +rows below repeat a shared row unchanged, because the HALMET pages lean on it +constantly and a translator should not have to hunt for it; where that happens +the note says so, and the value is copied, never re-decided. + +Every Danish rule above still applies here. In particular: ordinary compounds +are solid (`udviklingskort`, `spændingsdeler`, `strømforbrug`), and the +`-tion`/`af` forms of rule 5 are as easy to get wrong in `isolation` and +`galvanisk adskillelse` as anywhere else. + +### Board and inputs + +| English | Danish | Note | +|:--------|:-------|:-----| +| development board | udviklingskort | HALMET is sold as one. Not `bærekort`, which is HALPI2's carrier board and stays reserved for it | +| digital input | digital indgang | The pins keep their printed names: `D1`–`D4`, `DI1`–`DI4` | +| analog input | analog indgang | `A1`–`A4` stay as printed | +| input | indgang | Not `input`; the Danish word is standard in electronics | +| output | udgang | | +| sender | giver | The marine sender a gauge reads. Not `sender`, which in Danish is a radio transmitter | +| tank sender | tankgiver | | +| resistive sender | modstandsgiver | | +| gauge (engine panel gauge) | instrument | `instrumentet i motorpanelet`. Distinct from `måler`, which is a measuring device you hold, and from `vindmåler` in the shared list | +| counter | tæller | The function; a single pulse count is `tælling` | +| chain counter | kædetæller | | +| alarm signal | alarmsignal | | +| engine RPM | motorens omdrejningstal | Not `RPM`; the unit is written `o/min` when a unit is needed | +| tachometer | omdrejningstæller | The instrument | +| alternator W terminal | generatorens W-klemme | Danish `generator` covers the alternator. `klemme` for a single screw terminal; `klemrække` in the shared list is the whole block | +| fuel flow | brændstofflow | Solid compound. `brændstofgennemstrømning` is correct but too heavy for a feature list | +| pulse source | pulskilde | | +| bilge alarm | lænsealarm | Built on the shared `lænsevand` | +| flash memory (16 MB) | flashhukommelse | Third sense of *flash* in this file, and the only one HALMET uses: the inherited rows are `to flash` → `flashe` (writing firmware) and `flash (casting residue)` → `grat`, neither of which applies to `16 MB flash` | + +### Measurement and circuits + +| English | Danish | Note | +|:--------|:-------|:-----| +| galvanic isolation | galvanisk adskillelse | Inherited unchanged from *Power and electrical*; repeated because it is the subject of a whole HALMET section | +| isolated (section, area) | adskilt | `det adskilte område`, `den adskilte del`. Not `isoleret`, which a Danish reader takes as thermal insulation | +| digital isolator | digital isolator | The component's own name — the one place `isolator` is right | +| isolation barrier | isolationsbarriere | The physical line across the board; the property it creates is `galvanisk adskillelse` | +| ground loop | jordsløjfe | Inherited unchanged from *Power and electrical* | +| analog-to-digital converter (ADC) | AD-omsætter | First mention: `analog-digital-omsætter (ADC)`. `ADS1115` and `ADC` stay as printed | +| resolution (16-bit) | opløsning | `16-bits opløsning` | +| sampling rate | samplingfrekvens | `860 målinger pr. sekund` for *samples per second* | +| low-pass filter | lavpasfilter | The `LP` solder-jumper label stays as printed | +| cutoff frequency | knækfrekvens | The −3 dB point. Not `afskæringsfrekvens`, which belongs to signal processing texts | +| noise (electrical) | støj | `elektrisk støj`, `målestøj`. Never `larm` | +| noise immunity | støjimmunitet | The shared glossary's `immunitet over for korte spændingsudfald` is HALPI2's *glitch immunity* — a different property, do not merge them | +| voltage divider | spændingsdeler | | +| constant current source (CCS) | konstantstrømkilde | The header label `CCS` stays as printed: `CCS-jumperstiklisten` | +| excitation voltage | excitationsspænding | The voltage HALMET applies to drive the sender. First mention may gloss it: `excitationsspænding (den spænding, der driver giveren)` | +| passive voltage measurement | passiv spændingsmåling | | +| active resistance measurement | aktiv modstandsmåling | | +| pull-up resistor | pull-up-modstand | Phrase compound: hyphens throughout, which rule 4 permits — rule 4 governs proper names, not English trade terms | +| pull-down resistor | pull-down-modstand | | +| threshold voltage | tærskelspænding | | +| hysteresis | hysterese | | +| floating (input) | flydende | `indgangen bliver flydende`, `flydende potentiale` | +| normally open (NO) | normalt åben (NO) | Matches the inherited `momentkontakt af typen normalt åben (NO)`. The component itself is a `sluttekontakt` | +| normally closed (NC) | normalt sluttet (NC) | The established Danish pair to `normalt åben`; the component is a `brydekontakt`. **Never** `normalt lukket`, which is a literal rendering of the English and is not what a Danish electrician says | +| self-resetting fuse | selvgendannende sikring | The PTC kind. Not `selvresettende`, an anglicism | +| reverse polarity protection | beskyttelse mod omvendt polaritet | Inherited unchanged from *Power and electrical* | +| overvoltage protection | overspændingsbeskyttelse | | +| switching power supply | switchmode-strømforsyning | Junction hyphen kept for legibility at the English/Danish seam; the shared `buckomformer` is short enough to be written solid and stays that way | +| current consumption | strømforbrug | Not `strømforbrugning` | +| short circuit | kortslutning | Inherited unchanged from *Power and electrical* | +| chafing | skamfiling | Inherited from *Terms added during translation*; the standard Danish marine word for cable wear | +| voltage spike | spændingsspids | | +| two-stage noise filtering | totrins støjfiltrering | | + +### Board features and assembly + +| English | Danish | Note | +|:--------|:-------|:-----| +| jumper | jumper | Inherited. The removable link you place on a pin pair — see `loddejumper` for the kind that is soldered | +| jumper header | jumperstikliste | The pin pair the jumper is placed on. Built on the shared `stikliste` | +| solder jumper | loddejumper | Inherited. Closed permanently with solder, never removed by hand | +| to short (a jumper) | kortslutte | `Kortslut loddejumperen`, matching the shared `Kortslut benene` | +| solder pad | loddeflade | `ubestykkede loddeflader`. Consistent with the inherited `kobberflade`; `pad` is heard in Danish workshops but is not written | +| unpopulated | ubestykket | Populating a board is `bestykning` | +| pitch | benafstand | Inherited: `2,54 mm benafstand`, `3,81 mm benafstand` | +| pluggable terminal block | aftagelig klemrække | Phoenix MC type. `klemrække` alone is the shared HALPI2 term and is enough after first mention | +| silkscreen | silketryk | Inherited as `silk screen`; the source spells it both ways and Danish does not care | +| to solder | lodde | | +| soldering iron | loddekolbe | | +| grommet | gennemføringstyl | Inherited from *Terms added during translation*. Rubber or silicone; distinct from `kabelforskruning`, the threaded gland | +| step drill bit | trinbor | The one that looks like a small metal Christmas tree | +| conical drill bit | konisk bor | | +| panel connector | panelstik | Inherited from *Connectors and interfaces* | +| reset button | reset-knappen | The board legend `Reset` stays English; `knap` for a push button, not the shared `kontakt`, which is a switch | +| boot button | boot-knappen | Legend `Boot` stays English | +| bootloader | bootloader | Kept English, like `firmware` and `watchdog`. `opstartsindlæser` is not used | +| download mode | download-tilstand | The ESP32 flashing mode. Head noun Danish, name English, as with `boot-tilstand` | +| user-programmable LED | brugerprogrammerbar LED | | +| open hardware | åben hardware | `HALMET er åben hardware` | + +### Two pairs that must not blur + +**`loddejumper` and `jumper`.** They are not two words for one thing. A +`loddejumper` is two pads on the PCB bridged with solder — the pull-up, +pull-down, `LP` and CAN-termination jumpers on the back of the board. A `jumper` +is a removable link pushed onto a `jumperstikliste`, which is how the `CCS` +constant-current source is enabled. Blur them and the reader either fetches a +soldering iron they do not need or tries to pull off something that is soldered +down. When the source says *shorting the jumper contacts*, look at which one it +means before choosing the word. + +**`normalt åben` and `normalt sluttet`.** These are the Danish terms, not a +description; the parts are called `sluttekontakt` and `brydekontakt`. The whole +pull-up/pull-down section of `usage/index.md` turns on the distinction, and the +literal `normalt lukket` reads as a translator guessing. + +### A note on `stik`, `tilslutning` and `stikliste` + +Danish already has three words where Finnish has one, so HALMET's *1-Wire header +connector* and *analog input connectors* do not need inventing anything: the +soldered pin strip is a `stikliste` (`1-Wire-stiklisten`, `GPIO-stiklisten`), the +pluggable Phoenix part is a `stik` or a `klemrække`, and a board-mounted socket +is a `tilslutning`. Do not render *header connector* with two words — +`stikliste` alone is the whole thing. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py da` passes. +5. `uv run python scripts/check_typography.py da` passes — it walks the `»…«` + marks in order rather than grepping for the pair, so it does not produce the + false positives the counts below can. +6. Structure matches the source — see `.claude/skills/translate-page/SKILL.md`. +7. Every number in the English text appears in the translation. A wrong voltage + or current in an installation guide is a safety problem, not a typo. On + HALMET this bites hardest in `hardware/index.md`: threshold voltages, GPIO + numbers and jumper resistances are all bare numbers a skimming translator + can drop. +8. **The five rules at the top are counted against the pages, not re-read.** + Every count below must come out at zero: + +```bash +# 1 — Norwegian-order quotes +grep -roE '«[^»]{0,120}»' docs/da | wc -l +# 1 — » and « must balance +grep -ro '»' docs/da | wc -l; grep -ro '«' docs/da | wc -l +# 2 — polite address +grep -rnE '\b(De|Dem|Deres)\b' docs/da +# 3 — French spacing +grep -rnE ' [;:!?]' docs/da +# 4 — German hyphen chains, and missing junction hyphen +grep -rnE 'NMEA-2000|Signal-K|Raspberry-Pi|Compute-Module|NMEA 2000[a-zæøå]' docs/da +# 5 — Norwegian forms +grep -rniwE 'av|ikkje|berre|korleis|vann|nettverk|spenning' docs/da +grep -rniE '[a-zæøå]sjon' docs/da +# units +grep -rnE '[0-9](V|A|W|Hz|Ω|mm|kg|°C)' docs/da +grep -rnE '[0-9]+-[0-9]+ *(V|A|mA|°C)' docs/da +# compounds that must be solid +grep -rniE 'kabel forskruning|strøm forsyning|udviklings kort|spændings deler' docs/da +# HALMET: the two pairs that must not blur +grep -rniE 'normalt lukket|selvresettende' docs/da +``` + +Strip code fences before running the spacing, unit and hyphen counts — commands, +paths and configuration keys legitimately contain all of them: + +```bash +python3 - <<'PY' +import re, pathlib +for p in sorted(pathlib.Path('docs/da').rglob('*.md')): + t = re.sub(r'^---\n.*?\n---\n', '', p.read_text(encoding='utf-8'), flags=re.S) + t = re.sub(r'```.*?```', ' ', t, flags=re.S) + t = re.sub(r'`[^`\n]*`', ' ', t) + print(p, len(re.findall(r' [;:!?]', t)), len(re.findall(r'[0-9](V|A|W|mm|°C)', t))) +PY +``` + +A non-zero count is the finding. A rule that was read looks followed. + +## Related + +- `dutch-glossary.md`, `finnish-glossary.md`, `french-glossary.md`, + `german-glossary.md`, `italian-glossary.md`, `norwegian-glossary.md`, + `spanish-glossary.md`, `swedish-glossary.md` — siblings +- `.claude/skills/translate-page/SKILL.md` — the procedure +- `scripts/check_glossary.py`, `scripts/check_typography.py` — the two checks + that measure this file against the pages instead of trusting a reread + +## Terms added during translation + +Inherited from the HALPI2 Danish translation, where page translators reported +them and they were consolidated here rather than written by each of them. The +page names in the notes are HALPI2's; the decisions still bind, and where a term +recurs in HALMET the row above under `## HALMET terms` points back to it. New +terms found while translating HALMET pages go at the bottom of this table, with +the HALMET page named. + +| English | Translation | Note | +|:--------|:------------|:-----| +| apt repository | apt-pakkearkiv | ubuntu-installation.md heading and body; glossary has 'package' but not 'repository'. 'pakkearkiv' is the standard Danish term for a Debian/apt repo; | +| schematic | kredsløbsdiagram | design-files.md title and body; mkdocs.yml nav_translations already fixes 'Design Files and Schematics' -> 'Designfiler og kredsløbsdiagrammer', so th | +| PCB layout | print-layout | design-files.md; 'print' is the established Danish word for a printed circuit board, and 'layout' is the trade term | +| component footprint | komponent-footprint | design-files.md 0.6.0 changelog; Danish PCB practice keeps 'footprint' untranslated — 'fodaftryk' would not be understood | +| buck converter | buckomformer | design-files.md 0.6.0 changelog; solid compound per rule 4, junction hyphen only against the number: '10 V-buckomformeren' | +| opamp / operational amplifier | operationsforstærker | design-files.md 0.6.0 changelog | +| solder nut | loddemøtrik | design-files.md 0.5.0 changelog | +| copper pour / copper fill | kobberflade / kobberudfyldning | design-files.md and errata.md; 'kobberflade' for the plural pours in the changelog, 'kobberudfyldning' for the errata heading | +| power plane | forsyningsplan | errata.md; later mention shortened to '3,3 V-planet' as the glossary does for spændingsskinne | +| mounting ledge | monteringsafsats | errata.md; the cast ledges inside the enclosure that the board rests on | +| solder mask | loddemaske | errata.md | +| inrush current | indkoblingsstrøm | errata.md; distinct from 'overstrøm' in the glossary | +| thermal throttling | termisk nedregulering | troubleshooting.md, CPU temperature section | +| stray voltage | vildfaren spænding | troubleshooting.md rainbow-LED section | +| rollback (firmware) | tilbagerulning / rulle tilbage | troubleshooting.md firmware section | +| single-board computer | enkeltkortcomputer | index.md; solid compound, distinct from 'bærekort' | +| glitch immunity | immunitet over for korte spændingsudfald | index.md hardware feature list; rendered descriptively since Danish has no single trade term | +| cross-compilation | krydskompilering | integration.md placeholder bullet | +| security hardening | sikkerhedshærdning | advanced-config.md placeholder bullet | +| brownout | underspænding | power-supply.md placeholder bullet; 'strømafbrydelse' in the glossary is the full blackout, so a separate word was needed | +| wall wart (plug-in mains power supply) | netadapter | "What You'll Need" list, DC barrel connector bullet. The glossary has 'power supply' -> 'strømforsyning' but nothing for the scare-quoted colloquial ' | +| peripherals | perifere enheder | Heading 'Step 1: Connect Essential Peripherals' and the 'high-current peripherals' sentence in the current-limiting section. Standard Danish IT term; | +| terminals (crimp-on ring/spade terminals) | kabelsko | 'Heat-shrink tubing and terminals' and 'Install terminals using proper crimping technique'. The glossary's 'terminal block' -> 'klemrække' is the boar | +| cable grommet | gennemføringstyl | 'Install cable glands or cable grommets if routing through bulkheads'. The glossary covers 'cable gland' -> 'kabelforskruning' but not the rubber grom | +| splash screen | startskærm | 'Raspberry Pi OS splash screen' in the First Boot section. | +| mounting hardware | monteringsbeslag | 'Use corrosion-resistant mounting hardware' under Marine Installations. Glossary has 'mounting screw' and 'standoff' but no collective term. | +| chafing | skamfiling | 'Protect cable from chafing and damage' in Cable Preparation; the standard Danish marine word for line/cable wear. | +| electrical code | elregler | 'Ensure compliance with local electrical codes' / 'Comply with local electrical codes'. Glossary has 'compliance' -> 'overensstemmelse' but not the co | +| flow control (hardware flow control) | flowkontrol (hardwarestyret flowkontrol) | technical-reference/interfaces.md, ctsrts paragraph. 'flowkontrol' is the established Danish trade term; 'strømningsstyring' would read as fluid mecha | +| chip select | chip select | technical-reference/interfaces.md CTS/RTS conflict table ('CAN FD chip-select'). Kept English, as Danish PCB/embedded practice does; rendered as 'Chip | +| transceiver (RS-485 transceiver) | transceiver | technical-reference/interfaces.md, rs485 parameter paragraph. Kept English; 'sendemodtager' exists but is not what Danish RS-485 documentation says. N | +| device node | enhedsnode | technical-reference/interfaces.md 'Verifying' section. Solid compound, standard Danish Linux usage. | +| block device | blokenhed | user-guide/software.md step 6 of the USB-boot procedure. Solid compound. | +| mass storage device / mass-storage gadget firmware | masselagerenhed / firmwaren til masselagerenheden | user-guide/software.md steps 4-6. 'masselager' is the standard Danish term; the English 'gadget' is dropped because Danish has no equivalent and it ad | +| port forwarding | portviderestilling | user-guide/software.md, VNC-over-internet paragraph. Solid compound; 'port forwarding' is also heard but the Danish form is unambiguous. | +| marine apps | marineapplikationer | user-guide/software.md image-variant table and Homarr dashboard bullet. Solid compound. Distinct from the glossary's 'containerapp', which names the C | +| login console | loginkonsol | technical-reference/interfaces.md UART intro. Solid compound, consistent with the glossary's 'loginoplysninger'. | +| setup wizard | opsætningsguide | user-guide/software.md, Raspberry Pi OS configuration section. | +| HAT (Raspberry Pi HAT) | HAT / HAT'er | hardware.md, whole 'Using HATs' section. The glossary lists no form for it; kept English as a hardware-standard name and inflected with apostrophe-s i | +| spudger | spudger (åbnerpind) | hardware.md, CM5 removal. No Danish trade word exists; first mention glosses it, following the glossary's own 'dæmon (baggrundstjeneste)' / 'uden skær | +| socket (the tool: 26mm socket, hex socket) | top / sekskanttop | hardware.md, connector removal. Must not collide with 'stik', which the glossary already assigns to the electrical connector sense — a reader meeting | +| board-to-board connector | kort-til-kort-stik | hardware.md, CM5 replacement. Phrase compound, so hyphens throughout are correct Danish here and do not conflict with rule 4, which governs proper-nam | +| threaded insert | gevindindsats | hardware.md, HAT installation ('pre-installed M2.5 threaded inserts'). Distinct from 'afstandsbolt' (standoff), which the glossary already has and whi | +| device tree overlay | device tree-overlay | hardware.md, interface sharing and software configuration. Kept English because it names the `dtoverlay` config key the reader types; junction hyphen | +| clearance (vertical clearance above the board) | frihøjde | hardware.md, physical constraints and standoff sizing. The standard Danish term for the free space above a component. | +| voltage bar (LED pattern) | spændingssøjle | operation.md, LED status quick-reference table — the LED row acting as a bar-graph readout of super-capacitor charge. Derived from the glossary's 'spæ | +| grace period | henstandsperiode | operation.md, automatic restart behaviour ('5-second grace period'). | +| wake-up event | opvækningshændelse | operation.md, standby mode feature-status admonition. | +| amber (LED colour) | ravgul | hardware.md, status LED table. Needed a distinct word from 'gul' (yellow), which the same table already uses for LED 3. | +| TVS clamping | TVS-begrænsning | technical-reference/hardware.md, input protection sentence. The glossary has no entry for clamping; 'begrænsning' matches 'strømbegrænsning' already i | +| thermal management | termisk styring | technical-reference/hardware.md H2. Chosen over the more literal 'varmeafledning' because docs/da/user-guide/hardware.md already renders the same Engl | +| load equivalency number (LEN) | Load Equivalency Number (LEN) | user-guide/interfaces.md, NMEA 2000 network loading. Kept in English as an NMEA 2000 standard designation, like the other protocol names; later mentio | +| transmit enable (RS-485) | sendetilladelse | user-guide/interfaces.md, RS-485 hardware configuration. No glossary entry; 'sendetilladelse' is the standard Danish description and avoids leaving an | +| multi-talker / single-talker network | multi-talker- / single-talker-anvendelser, netværk med flere talere / med én taler og flere lyttere | user-guide/interfaces.md. The adjectival compounds keep the NMEA 0183 trade terms; the descriptive form is used where the source spells out 'single-ta | +| form factor (M.2) | formfaktor | technical-reference/hardware.md, M.2 NVMe slot ('formfaktorerne 2230 til 2280'). | +| die-cast aluminium | trykstøbt aluminium | technical-reference/hardware.md, enclosure material rows. Note docs/da/user-guide/hardware.md paraphrases the same English as 'støbt aluminium' withou | +| ferrite bead filtering | filtrering med ferritperler | technical-reference/hardware.md, USB 3.0 ports. | +| normally-open (NO) momentary switch | momentkontakt af typen normalt åben (NO) | user-guide/interfaces.md, button header. The glossary has 'switch (physical) = kontakt' but nothing for the momentary/NO qualifiers. | +| pinout | benforbindelser | technical-reference/hardware.md H2 'Stikkenes benforbindelser' and user-guide/interfaces.md H3 'Benforbindelser på knapstiklisten'. Built on the gloss | +| fan (CM5 / PWM fan) | blæser | Consistency pass. 'ventilator' had appeared in user-guide/hardware.md while technical-reference/hardware.md used 'blæser'. 'blæser' is the Danish trade word for a CPU/PWM fan, and it keeps 'ventilation' free for the airflow-around-the-enclosure sense the getting-started page uses. | +| airflow / air circulation | luftcirkulation | Consistency pass. 'luftstrøm' had appeared once in getting-started.md. Treated as one concept: the same physical thing whether the source says 'airflow' or 'air circulation'. Distinct from 'ventilation', which renders the source's own 'ventilation'. | +| web-managed interface | webstyret grænseflade | Consistency pass. 'webadministreret grænseflade' had appeared in getting-started.md. 'webstyret' is the compact compound and avoids 'webadministreret grænseflade til systemadministration' in user-guide/software.md. Distinct from 'web interface' -> 'webgrænseflade' and 'web-based' -> 'webbaseret'. | +| baud rate | baudhastighed | Consistency pass. 'baudrate' had appeared once in troubleshooting.md. 'baudhastighed' matches the other rate compounds already in use ('opdateringshastighed', 'datahastigheder'). | +| repository (Git/GitHub) | repositorium (bestemt form: repositoriet) | Consistency pass. 'GitHub-arkivet' had appeared in design-files.md. 'arkiv' is reserved for the apt sense ('pakkearkiv'), so the source-code repository takes 'repositorium' — what Danish developers say. | +| diagnostics / diagnostic | diagnostik | Consistency pass. 'diagnose' had appeared once in index.md. In Danish 'diagnose' is the result, 'diagnostik' the activity — the latter is what the source means. | diff --git a/solutions/translation/dutch-glossary.md b/solutions/translation/dutch-glossary.md new file mode 100644 index 0000000..509c666 --- /dev/null +++ b/solutions/translation/dutch-glossary.md @@ -0,0 +1,667 @@ +--- +title: Dutch translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Dutch under docs/nl/ + - Reviewing a Dutch translation for consistency + - Adding a new term that has no established Dutch equivalent +tags: + - translation + - i18n + - dutch + - terminology + - mkdocs-static-i18n +--- + +# Dutch translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Dutch under `docs/nl/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/nl/hardware/index.md`. Only markdown lives under `docs/nl/` — images and +other assets stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with +two different Dutch words. A reader who has both a HALPI2 and a HALMET on the +bench should not have to learn that a *kabelwartel* on one page is something +else on the other. `carrier board` → `carrierboard` is the HALPI2 call and +stands here too, even though HALMET has no carrier board — the row is kept so +the two repositories stay comparable. Terms below the `## HALMET terms` heading +are additions this product needed; everything above it is shared with HALPI2, +and **a change to a shared row must be made in both repositories or in +neither.** + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `soldeerbrug` on one page and +`soldeerjumper` on the next — and the result reads as machine output even when +each individual sentence is correct. + +This file is the reference that prevents that drift. It is a living document: +extend it when a page introduces a term that is not listed here, rather than +inventing a one-off translation. + +`finnish-glossary.md`, `italian-glossary.md` and `spanish-glossary.md` are the +siblings of this file in this repository; the HALPI2 repository holds the French, +German and Swedish ones. The general approach is the same in all of them. + +Unlike the other files under `solutions/`, this one has no date in its filename +because it is meant to be edited in place, not superseded. + +## Seven rules where the siblings are wrong for Dutch + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary. Dutch sits closest to German and +Swedish — solid compounds, no space before punctuation — which is exactly why the +places where it diverges from them get carried across unnoticed. + +1. **Address the reader as `u` / `uw`, never `je`, `jij`, `jouw` or `jullie`.** + Dutch installation, safety and consumer manuals use `u`; Swedish uses `du`, + and copying that register produces a page that reads as a hobby blog next to + a warning about 32 V and short circuits. + + The trap is that the Dutch imperative is *identical* for both registers — + `Sluit de voedingskabel aan.` `Controleer de polariteit met de multimeter + voordat u de spanning inschakelt.` The register only surfaces in pronouns and + possessives, so a page can be 90 % correct and still leak `je` in three + places. That is why this is counted, not read. + + Write `u` and `uw` in lowercase. Capital `U` is an archaic reverential form + and is wrong here. + +2. **Quotation marks are `“…”` — U+201C opening, U+201D closing, two different + characters.** Not German's `„…“`, not Swedish's `”…”` (the *same* character + twice), not French's `« … »`, not straight `"…"`. A leaked Swedish habit is + visible as a `”` count higher than the `“` count. + +3. **Dutch does not capitalise common nouns.** German capitalises every noun; + Dutch capitalises only proper names and the first word of a sentence or + heading. Write `behuizing`, `voeding`, `carrierboard`, `afsluitweerstand`, + `soldeerbrug`, `ingang` mid-sentence — never `Behuizing`, `Voeding`, + `Soldeerbrug`. This is the single most likely German leak. + + The same rule flattens English title case in headings: `Drilling Holes for + Panel Connectors` becomes `Gaten boren voor paneelconnectoren`, not `Gaten + Boren voor Paneelconnectoren`. + +4. **Compounds are solid, but a compound with a proper name takes exactly one + hyphen, at the junction.** Dutch writes `NMEA 2000-netwerk`, `Signal + K-server`, `HALMET-print`, `ESP32-module`, `PG7-kabelwartel`, `M12-connector`, + `Phoenix MC-klemmenblok`, `ADS1115-omzetter`. German writes + `NMEA-2000-Netzwerk` — hyphens all the way through — and that pattern is + wrong in Dutch. + + Ordinary Dutch compounds carry no hyphen and no space: `voedingskabel`, + `kabelwartel`, `afsluitweerstand`, `soldeerbrug`, `spanningsdeler`, + `drempelspanning`. English two-word terms adopted whole become one Dutch + word: `carrier board` → `carrierboard`, `access point` → `accesspoint`, + `jumper header` → `jumperheader`. + +5. **No space before `; : ! ?`** — as in German and Swedish, and unlike French, + whose rule is the exact opposite and demands a no-break space. + +6. **`led` is an ordinary lowercase Dutch word, not an abbreviation.** German + writes `Status-LED` and Swedish `status-LED`; Dutch writes `status-led`, + `rgb-led` → `RGB-led`, plural `leds`. Uppercase `LED` belongs only inside + code, file paths, table cells that quote the GPIO reference, and quoted + silkscreen labels. Same for `wifi` (lowercase in prose; `WiFi (wlan0)` stays + as written when it names the on-screen menu item). + +7. **HALMET and HALPI2 are `de`-words, the carrierboard is a `het`-word.** + Grammatical gender drifts between pages faster than terminology does, because + nothing flags it. Fix it here: + + | Article | Nouns | + |:--------|:------| + | `de` | HALMET, HALPI2, behuizing, voeding, zekering, connector, kabelwartel, aardlekbeveiliging, supercondensator, afsluitweerstand, daemon, controller | + | `het` | carrierboard, frontpaneel, bestandssysteem, schot, klemmenblok, systeemimage, dashboard, energiebeheer | + + The HALMET-specific nouns are listed under `## HALMET terms`. + + English possessives do not survive the crossing: `HALMET's digital inputs` + becomes `de digitale ingangen van de HALMET`, never `HALMET's digitale + ingangen`. The apostrophe-`s` in Dutch marks the plural of a vowel-final word + or an abbreviation (`schema's`, `led's` — but write `leds`, see rule 6), + nothing else. + +## Names that are never translated + +Product names, protocol names, hardware standards and software UI strings stay +in English. The board's own labels and its development tools are in English, so +translating one would send the reader looking for something that does not exist. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, + I2C, 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, + Schmitt trigger, IoT +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`, and the GPIO numbers. These are printed on the board; a translated pin + name sends the reader looking for a label that does not exist. The same + applies to the button legends `Reset` and `Boot` and to the `DI1`–`DI4` rows + of the GPIO table. +- **UI strings, commands, hostnames, file paths and identifiers:** + `main.cpp`, `ConnectAlarmSender()`, `raspi-config`, `passwd`, `shutdown`, + `halos.local`, `can0` + +Code fences and their contents, command output, URLs and image filenames are +never touched. + +## Units and numbers + +The English source writes `12V` and `0.9A`. Both are wrong in Dutch and need an +active conversion on nearly every technical page. + +| English source | Dutch | +|:---------------|:------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω`, `100 kohm` | `120 Ω`, `100 kΩ` | +| `1.5mm²`, `2m` | `1,5 mm²`, `2 m` | +| `5-32 V`, `3-5A` | `5–32 V`, `3–5 A` (en dash for ranges) | +| `+/- 30 V` | `±30 V` | +| `250 kbps` | `250 kbit/s` | +| `2x10 pin` | `2×10 pins` | + +- **Decimal comma**, always: `0,9 A`, `5,5 mm`, `3,3 V-rail`, `2,54 mm`, + `2,3 kHz`, `1,55 V`. +- **A space between the number and its unit**, preferably a no-break space + (U+00A0), including before `°C` and `Ω`. +- **Write `ohm` as `Ω`**: the source writes `320 ohms`, `100 kohm`, `120 ohm`; + Dutch writes `320 Ω`, `100 kΩ`, `120 Ω`. +- **No thousands separator** in technical values: `115200 bps`, not `115.200`. +- **Dimensions given as a single product spec keep the tight form:** + `200 × 130 × 60 mm`, with `×` (U+00D7), not the letter `x`. +- **Version numbers, part numbers and addresses are identifiers, not numbers**: + `v1.0.1`, `M.2`, `0x48`, `GPIO21` keep their points and digits exactly as + written, while `2.54 mm` pitch takes the decimal comma → `2,54 mm`. +- **`16-bit` is attributive in Dutch and takes an `s`**: `een 16-bits + resolutie`, `een 16-bits AD-omzetter`. + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry an `en/` or `nl/` segment; image captions and alt +texts are translated but filenames are not; screenshots stay English because the +reader's own screen is English; standard admonition titles are translated +centrally in `mkdocs.yml`, custom ones — `!!! note "Shop Link"` → +`!!! note "Link naar de webshop"` — in the page. + +Navigation titles live in `mkdocs.yml` under the i18n plugin's +`nav_translations` and are not restated here. Two entries are judgement calls +worth recording: + +- `Errata` → **Bekende fouten**. The Latin term is opaque to a general + reader, and in Dutch *errata* additionally suggests corrections still to be + made rather than defects the reader has to live with. The page lists known + hardware defects, so plain Dutch is clearer. +- `Hardware Revisions` → **Hardwareversies**. Board versions, not revisions to + the documentation. `Revisies` alone would read as document revisions. + +When a new page is added to the nav in English, add its Dutch title to +`nav_translations` in the same change — an untranslated entry silently falls +back to English and is easy to miss. + +## Glossary + +### Enclosure, mounting, and installation + +| English | Dutch | Note | +|:--------|:------|:-----| +| carrier board | carrierboard | One word, lowercase, `het`-woord — see the note below | +| enclosure | behuizing | | +| lid | deksel | | +| gasket | afdichtingsrubber | Lid gasket | +| heat sink | koellichaam | Not *koelblok*, which is a cooling block on a chip | +| waterproof | waterdicht | | +| rugged | robuust | | +| wall-mount | wandmontage | | +| mounting surface | montageondergrond | What you drill into | +| pilot hole (to drill) | voorboren (verb) | `Boor de bevestigingsgaten voor.` Never `voorgeboorde gaten boren` | +| pre-drilled hole (already there) | voorgeboord gat | The holes the enclosure ships with | +| mounting template | boormal | | +| clearance | vrije ruimte | | +| bilge water | bilgewater | Also seen as *lenswater*; use `bilgewater` on every page | +| bulkhead | schot | `het schot`, plural `schotten` | +| cable gland | kabelwartel | `PG7-kabelwartel` | +| cable routing | kabelroute | The verb is *leggen* / *leiden* | +| service loop | servicelus | Slack left at both cable ends | +| chafing | schuren | | +| cable tie | kabelbinder | | +| blind plug | blindplug | | +| breather plug | ontluchtingsplug | For *pressure equalization* → *drukvereffening* | +| standoff | afstandsbus | | +| threaded insert | draadinzetstuk | | + +**A note on `carrierboard`, and why it differs from the siblings.** French, +German and Swedish each coined an accurate native term (`carte porteuse`, +`Trägerplatine`, `bärkort`); Finnish took the familiar-but-inaccurate `emolevy` +(*motherboard*). Dutch takes neither route: the Dutch marine and Raspberry Pi +trade already says *carrier board*, and Dutch spelling turns an adopted English +two-word term into one word — `carrierboard`. + +Do not "harmonise" the five. They differ on purpose, decided per language and +per audience. + +Two consequences worth stating: + +- **Never write `moederbord`.** That is the Finnish trade-off, and it inverts + the CM5/board relationship: it would make the board the computer and the CM5 + an add-on, which is the reverse of how HALPI2 is built. `carrierboard` carries + the relationship correctly on its own. +- **Never write `carrier board` with a space,** and never capitalise it + mid-sentence. Those are the English and German habits respectively, and both + are countable. + +On HALMET the row is inherited, not used: HALMET is not a carrier board and +nothing on it should be called one. See `ontwikkelbord` under +`## HALMET terms`. + +### Electrical + +| English | Dutch | Note | +|:--------|:------|:-----| +| power supply | voeding | The unit itself: *voedingsadapter* | +| power source | voedingsbron | | +| input voltage range | ingangsspanningsbereik | | +| polarity | polariteit | | +| positive (+) / negative (−) | plus (+) / min (−) | The `+` and `-` markings on the terminal block stay as printed | +| fuse | zekering | | +| inline fuse | kabelzekering | A fuse holder fitted in the positive lead | +| circuit breaker | installatieautomaat | The panel breaker; on a boat panel often just *automaat* | +| current limiting | stroombegrenzing | The switch is the *stroombegrenzer* | +| overcurrent | overstroom | | +| inrush current | inschakelstroom | | +| voltage drop | spanningsval | | +| grounding | aarding | | +| ground loop | aardlus | | +| short circuit | kortsluiting | | +| wire gauge | aderdoorsnede | Dutch uses mm², not AWG | +| marine-grade wire | kabel van maritieme kwaliteit | | +| to strip (a wire) | strippen | | +| wire strippers | striptang | | +| crimping | krimpen | Noun: *krimpverbinding* | +| crimper | krimptang | | +| crimp terminal | kabelschoen | | +| heat-shrink tubing | krimpkous | | +| heat gun | heteluchtpistool | | +| multimeter | multimeter | | +| continuity test | doorbelmeting | | +| terminal block | klemmenblok | The pluggable Phoenix MC connector | +| strain relief | trekontlasting | | +| super-capacitor | supercondensator | One word, lowercase | +| real-time clock | realtimeklok | Abbreviate as RTC after first mention | +| backup battery | backupbatterij | The cell itself is a `CR2032-knoopcel` | + +### Connectors and interfaces + +| English | Dutch | Note | +|:--------|:------|:-----| +| connector | connector / aansluiting | *aansluiting* for a board-mounted socket | +| barrel connector | DC-plug | Add *(barrel connector)* on first mention | +| header | pinheader | `2×10-pins GPIO-pinheader` | +| pin | pin | | +| pitch | steek | `2,54 mm steek` | +| backbone | backbone | Established in Dutch NMEA 2000 usage | +| drop cable | aftakkabel | | +| T-connector | T-stuk | Also renders *T-adapter* | +| terminator / termination (120 Ω) | afsluitweerstand | The component; the act is *afsluiten* | +| front panel | frontpaneel | | +| jumper | jumper | The removable link; see *soldeerbrug* under `## HALMET terms` | +| male / female | male / female | Trade usage; use *stekker / bus* when the plug-socket pair is meant | +| antenna | antenne | | +| extension cable | verlengkabel | | +| flexible flat cable (FFC) | platte flexkabel (FFC) | Keep the abbreviation after first mention | + +### Operation, system behaviour and status + +| English | Dutch | Note | +|:--------|:------|:-----| +| boat computer | boordcomputer | | +| to boot | opstarten | | +| first boot | eerste start | | +| shutdown | afsluiten | The noun is *het afsluiten* | +| graceful shutdown | gecontroleerd afsluiten | | +| to power down | uitschakelen | Cutting power, as opposed to *afsluiten* | +| power loss | spanningsuitval | The input goes away | +| blackout | stroomuitval | The boat's supply goes away; the firmware timer stays `blackouttimer` | +| glitch immunity | storingsongevoeligheid | | +| power management | energiebeheer | | +| status LED | status-led | Lowercase *led*, plural *leds* | +| LED bar | ledbalk | | +| monitoring | bewaking | | +| passive cooling | passieve koeling | | +| thermal pad | thermisch pad | | +| filesystem | bestandssysteem | | +| to unmount (a filesystem) | ontkoppelen | `het bestandssysteem wordt veilig ontkoppeld` | +| to unmount (a board or module) | demonteren | The English source uses one word for both — this one is mechanical: `het carrierboard demonteren` | +| to reseat (a module) | opnieuw plaatsen | | +| watchdog | watchdog | | +| standby | standby | `standbymodus`, one word | +| solo mode / co-op mode | solomodus / co-opmodus | Named firmware states; keep them recognisable | + +### Software and networking + +| English | Dutch | Note | +|:--------|:------|:-----| +| firmware | firmware | Not *bedrijfsprogrammatuur* — the trade term, as in every sibling | +| daemon | daemon | Not *achtergronddienst* | +| to flash | flashen | Past participle *geflasht* | +| system image / operating system image | systeemimage | | +| container image | containerimage | Not *systeemimage* — that is a disk image | +| container app | containerapp | | +| headless | zonder beeldscherm | First mention: `zonder beeldscherm (headless)` | +| deployment | ingebruikname | | +| dashboard | dashboard | `het dashboard` | +| WiFi Access Point | wifi-accesspoint | `wifi` lowercase in prose; `WiFi (wlan0)` stays as written when naming the menu item | +| wired / wireless | bekabeld / draadloos | | +| credentials | inloggegevens | | +| username / password | gebruikersnaam / wachtwoord | | +| default password | standaardwachtwoord | | +| single sign-on (SSO) | single sign-on (SSO) | Kept in English | +| Certificate Authority (CA) | certificaatautoriteit (CA) | | +| to trust (a certificate) | vertrouwen | | +| web interface | webinterface | | +| browser | browser | | +| system administration | systeembeheer | | +| package | pakket | Debian package → `Debian-pakket` | + +### Applications and use cases + +| English | Dutch | Note | +|:--------|:------|:-----| +| chart plotter | kaartplotter | | +| data logging | dataregistratie | | +| vessel | vaartuig | | +| engine parameters | motorgegevens | | +| fleet management | wagenparkbeheer | For ships it would be *vlootbeheer* | +| process monitoring | procesbewaking | | +| remote monitoring | bewaking op afstand | | +| predictive maintenance | voorspellend onderhoud | | +| electromagnetic interference (EMI/RFI) | elektromagnetische storing (EMI/RFI) | | +| compliance | conformiteit | | +| warranty | garantie | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. **Rows above +this heading are shared with HALPI2 and must not be changed here alone.** + +A handful of rows below repeat a shared row verbatim and are marked +`= shared row above` in the Note column. They are repeated because HALMET puts +them in a context HALPI2 never did — a *jumper* next to a *soldeerbrug*, a +*ground loop* as the reason for galvanic isolation — not because a second +decision was made. If one of those has to change, change it in the shared table +in both repositories. + +### Grammatical gender of the new nouns + +| Article | Nouns | +|:--------|:------| +| `de` | ingang, uitgang, gever, meter, teller, weerstand, spanningsdeler, drempelspanning, soldeerbrug, jumperheader, trapboor, dynamo, resolutie, ruis, scheiding, hysterese | +| `het` | ontwikkelbord, soldeereiland, laagdoorlaatfilter, alarmsignaal, motortoerental, stroomverbruik, klemmenblok, gescheiden deel | + +`het filter` and `de filter` both exist in Dutch; the technical sense is +`het filter`, so write `het laagdoorlaatfilter`. + +### Board and inputs + +| English | Dutch | Note | +|:--------|:------|:-----| +| development board | ontwikkelbord | HALMET is sold as one. Never *carrierboard*, which is HALPI2's board, and never *moederbord* | +| digital input | digitale ingang | `D1`–`D4` stay as printed; the GPIO table's `DI1`–`DI4` too | +| analog input | analoge ingang | `A1`–`A4` stay as printed | +| input | ingang | Not *invoer*, which is data being typed in | +| output | uitgang | Not *uitvoer* | +| sender | gever | The marine sender a gauge reads. **Never *zender***, which is a radio transmitter; *sensor* is acceptable where the source says *sensor* | +| tank sender | tankgever | Established in the Dutch chandlery trade | +| resistive sender | weerstandsgever | The kind measured with the constant current source | +| tank level sensor | tankniveausensor | The source says *sensor* here, so does the translation | +| gauge (engine panel) | meter | `de meter op het motorpaneel`. Not *meterklok*; *multimeter* keeps its own name | +| counter | teller | | +| pulse counter | pulsteller | The firmware feature on a digital input | +| chain counter | kettingteller | Anchor chain; *ankerkettingteller* on first mention if the context is not obvious | +| alarm signal | alarmsignaal | | +| alarm switch | alarmschakelaar | The contact that produces the signal | +| engine RPM | motortoerental | Not *RPM*; Dutch prose says *toerental*, the unit is `omw/min` | +| engine revolutions | motoromwentelingen | What the pulse counter counts | +| tachometer | toerenteller | The instrument; *toerenteller* also names the signal source in `toerentellersignaal` | +| alternator W terminal | W-klem van de dynamo | Dutch automotive and marine trade says *dynamo* for the alternator; *alternator* is understood but is not what the reader will find on a wiring diagram | +| fuel flow | brandstofdebiet | *Debiet* is flow rate; *brandstofverbruik* is consumption and is a different quantity | +| bilge alarm | bilgealarm | Built on the shared `bilgewater` | +| light bulb (panel lamp) | controlelampje | The existing lamp in the alarm circuit of figure (a); an ordinary bulb is *gloeilamp* | + +### Measurement, isolation and input circuits + +| English | Dutch | Note | +|:--------|:------|:-----| +| galvanic isolation | galvanische scheiding | The established Dutch term. Not *galvanische isolatie*, which reads as insulating material | +| isolated (section, area) | gescheiden | `het gescheiden deel van de print`, `de gescheiden ingangen`. Not *geïsoleerd*, which means thermally or electrically insulated | +| digital isolator | digitale isolator | The component keeps its trade name even though the property is *scheiding* | +| isolated DC/DC converter | gescheiden DC/DC-omzetter | Powers the isolated section | +| isolation barrier | scheidingsbarrière | The figure caption *HALMET isolation barrier* → `de scheidingsbarrière van de HALMET`. *Isolatiebarrière* also occurs in Dutch datasheets; keep one word across the pages | +| ground loop | aardlus | = shared row above. It is the reason the isolation exists, so it appears on hardware/index.md | +| analog-to-digital converter (ADC) | analoog-digitaalomzetter | `AD-omzetter` after first mention. The part number `ADS1115` and the abbreviation `ADC` stay | +| resolution | resolutie | `een 16-bits resolutie` — attributive `16-bits`, see the units section | +| sampling rate | bemonsteringsfrequentie | Names the property. The value keeps trade usage: `860 samples per seconde`, not *monsters* | +| low-pass filter | laagdoorlaatfilter | `het filter`. The solder jumper is the `LP`-soldeerbrug, label unchanged | +| cutoff frequency | afsnijfrequentie | *Grensfrequentie* also occurs; use *afsnijfrequentie* on every page | +| noise (electrical, in a measurement) | ruis | Never *lawaai* or *geluid*, which are sound. `meetruis`, `een ruisig pulssignaal` | +| noise filtering (on the power input) | storingsfiltering | The two-stage filter on the NMEA 2000 input is EMI suppression, so *storing* — matching the shared `elektromagnetische storing` — not *ruis* | +| noise immunity | ruisongevoeligheid | What the Schmitt trigger buys on the digital inputs. Kept apart from the shared `storingsongevoeligheid`, which renders *glitch immunity* — a power-supply and firmware property, not an input-circuit one | +| voltage divider | spanningsdeler | The gauge and the sender together form one | +| constant current source (CCS) | constantstroombron | Also written *constante stroombron*; use the solid form per rule 4. The header label `CCS` stays as printed | +| excitation voltage | excitatiespanning | The voltage HALMET supplies to a sender that has no gauge. Not *voedingsspanning*, which is the board's own supply | +| passive voltage measurement | passieve spanningsmeting | Mode (a): an existing gauge is present | +| active resistance measurement | actieve weerstandsmeting | Mode (b): HALMET drives the sender itself | +| resistance (the measured quantity) | weerstand | `een weerstand van 320 Ω`. The component is also *weerstand*; let the sentence carry it, as the shared glossary does for `afsluitweerstand` | +| pull-up resistor | pull-upweerstand | English term joined solid to the Dutch noun, keeping the internal hyphen of the English term (rule 4) | +| pull-down resistor | pull-downweerstand | | +| threshold voltage | drempelspanning | `de drempelspanning voor een hoog signaal` | +| hysteresis | hysterese | Dutch drops the `-is`: *hysterese*, not *hysteresis* | +| floating (input) | zwevend | `de ingang blijft zweven en leest willekeurig hoog of laag` | +| normally open (NO) | maakcontact (NO) | Dutch electrical trade term. **Never *normaal open*.** The abbreviation `NO` is kept because it is printed on the switch packaging | +| normally closed (NC) | verbreekcontact (NC) | **Never *normaal gesloten*.** Matches the HALPI2 page, which already writes `drukknop met maakcontact` | +| self-resetting fuse | zelfherstellende zekering | The 500 mA PTC on the NMEA 2000 input | +| reverse polarity protection | ompoolbeveiliging | The trade term; *omgekeerde-polariteitsbeveiliging* is the literal rendering and is not used | +| overvoltage protection | overspanningsbeveiliging | Under-voltage is *onderspanningsbeveiliging* | +| ESD protection | ESD-beveiliging | Junction hyphen after the abbreviation (rule 4) | +| switching power supply | schakelende voeding | Not *schakelvoeding* | +| current consumption | stroomverbruik | `typisch stroomverbruik 90 mA bij 12 V` | +| short circuit | kortsluiting | = shared row above. On usage/index.md it is the fault an inline fuse protects against | +| chafing | schuren | = shared row above. `schuren van de kabel` | +| CAN transceiver | CAN-transceiver | | +| flash memory | flashgeheugen | Never *flitsgeheugen* | + +### Board features and assembly + +| English | Dutch | Note | +|:--------|:------|:-----| +| jumper | jumper | = shared row above. The **removable** link placed on a pin pair — the CCS jumpers. Repeated here only because HALMET sets it beside *soldeerbrug* | +| jumper header | jumperheader | The pin pair a jumper is placed on. Adopted English term, one word (rule 4); `pinheader` stays the general term | +| solder jumper | soldeerbrug | Closed **permanently with solder**, not with a removable jumper: the LP, pull-up, pull-down, CAN terminator and ADS1115 address jumpers. Getting this wrong sends the reader for a soldering iron they do not need, or has them trying to pull off something that is soldered down | +| to short (a jumper) | doorverbinden | `verbind de jumpercontacten door`. Avoid *kortsluiten*: in Dutch prose that reads as the fault, and `kortsluiting` is already the shared word for it | +| to close a solder jumper | dichtsolderen | The specific act for a `soldeerbrug`: `soldeer de brug dicht` | +| solder pad | soldeereiland | The established Dutch PCB term; *soldeervlak* is the material, *pad* alone is ambiguous next to *thermisch pad* | +| unpopulated | niet-bestukt | `niet-bestukte soldeereilanden voor EN en IO0`. *Bestukking* is the Dutch word for component placement | +| pitch | steek | = shared row above. `2,54 mm steek`, `3,81 mm steek` | +| pluggable terminal block | steekbaar klemmenblok | The shared `klemmenblok` already means the Phoenix MC part; add *steekbaar* only where the source contrasts it with a fixed one | +| silkscreen | opdruk | Inherited from the HALPI2 page vocabulary. `de opdruk op de achterzijde`; a quoted label stays verbatim: `de opdruk “DQ”` | +| to solder | solderen | | +| soldering iron | soldeerbout | | +| grommet | doorvoertule | Inherited from the HALPI2 page vocabulary. Rubber or silicone; distinct from `kabelwartel`, the threaded gland | +| step drill bit | trapboor | The one that looks like a small metal Christmas tree | +| conical drill bit | conische boor | Named alongside the step drill bit | +| panel connector | paneelconnector | The connector mounted through the enclosure wall | +| reset button | resetknop | The legend `Reset` on the board stays English and quoted | +| boot button | bootknop | The legend `Boot` stays English and quoted | +| bootloader | bootloader | Not *opstartlader* | +| download mode | downloadmodus | The ESP32 flashing state. Solid compound, matching `standbymodus` | +| user-programmable LED | door de gebruiker programmeerbare led | Lowercase `led` per rule 6 | +| open hardware | open hardware | Kept in English and lowercase, like `firmware`: `HALMET is open hardware` | + +### A note on `connector` and `pinheader` + +The shared glossary splits `connector` into *connector* and *aansluiting*, and +renders `header` as *pinheader*. That split is kept. HALMET puts the two side by +side far more often than HALPI2 does — *1-Wire header connector*, *analog input +connectors*, *jumper header contacts* — so let the qualifier carry the +distinction (`1-Wire-pinheader`, `de connectoren van de analoge ingangen`, +`de contacten van de jumperheader`) rather than inventing a second word. Where a +sentence would otherwise be ambiguous, say what the thing is: `pinstrip` for a +bare strip of pins, `kabelconnector` for the plug that goes onto it. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes — the same command CI runs. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/check_typography.py nl` reports `ok`. +4. `uv run python scripts/check_glossary.py nl` passes. +5. `uv run python scripts/translation_status.py` shows the page as current. +6. Lists render as lists — see + `../best-practices/markdown-lists-need-blank-line-2026-05-16.md`. +7. **The seven rules at the top are counted against the pages, not re-read.** + +That last one is the point of this section. A half-applied typography rule looks +followed when you read it, because rereading your own text confirms whatever it +already says. The French and German branches each shipped one to review for +exactly that reason. + +`check_typography.py` counts rules 2, 4 and 5 for you. The rest are not covered +by any script, so run this: + +```bash +python3 - <<'PY' +import pathlib, re +def prose(p): + t = re.sub(r'^---\n.*?\n---\n', '', p.read_text(encoding='utf-8'), flags=re.S) + t = re.sub(r'```.*?```', ' ', t, flags=re.S) # code fences + return re.sub(r'`[^`\n]*`', ' ', t) # inline code +text = '\n'.join(prose(p) for p in sorted(pathlib.Path('docs/nl').rglob('*.md'))) +n = lambda pat: len(re.findall(pat, text)) +report = [ + ('rule 1 informal address je/jij/jouw/jullie', n(r'\b[Jj](?:e|ij|ouw|ullie)\b')), + ('rule 1 reverential capital U', n(r'\bU\b')), + ('rule 3 spaced "carrier board"', n(r'(?i)carrier board')), + ('rule 3 capitalised common nouns', n(r'(?4} {label}') +print('\nevery count must be 0; inspect each hit, do not adjust the pattern') +PY +``` + +Three of these need judgement rather than a blind zero: version numbers such as +`v1.0.1` are identifiers and legitimately contain points, a heading may +legitimately start with a capitalised common noun, and `GPIO21`/`ADS1115` are +identifiers that the unit pattern does not match but a careless variant would. +Read the hits. Everything else is a defect. + +Also confirm, as the skill requires, that every number in the English page +appears in the Dutch page. A wrong threshold voltage or a wrong fuse rating in an +installation guide is a safety problem, not a typo. + +## Related + +- `finnish-glossary.md`, `italian-glossary.md`, `spanish-glossary.md` — the + siblings in this repository +- `../../../halpi2/solutions/translation/dutch-glossary.md` — the HALPI2 + original this file was copied from; shared rows must stay identical in both +- `solutions/best-practices/markdown-lists-need-blank-line-2026-05-16.md` +- mkdocs-static-i18n documentation: https://ultrabug.github.io/mkdocs-static-i18n/ + +## Terms added during translation + +Reported by the page translators, consolidated here rather than written by each +of them, because several agents share this file. Inherited from HALPI2 unless a +note says otherwise; a row that HALMET has no use for is kept so the two +repositories stay comparable. + +| English | Translation | Note | +|:--------|:------------|:-----| +| desktop setup | opstelling op het bureau | The pre-installation bench test. Avoided *desktopopstelling*, which collides with the graphical desktop meaning | +| graphical desktop / desktop interface | grafische werkomgeving | Kept distinct from *opstelling op het bureau* so the two English senses of "desktop" do not merge in Dutch | +| splash screen | opstartscherm | Boot logo screen | +| cable management | kabelbeheer | The wider planning/tidiness sense; *kabelroute* is the physical route | +| cable grommet | doorvoertule | Appears alongside *cable gland* (kabelwartel), so it needs its own word | +| mounting hardware | bevestigingsmateriaal | Corrosion-resistant screws and brackets | +| mounting screws | montageschroeven | | +| transportation damage | transportschade | | +| ambient (temperature) | omgevingstemperatuur | Renders "-20°C to +60°C ambient" as a single Dutch noun | +| cable tester | kabeltester | | +| circuit / dedicated circuit | groep | Dutch electrical-panel usage for a breaker circuit; *circuit* alone would read as an electronic circuit — which on HALMET pages it usually is, so check the sense before applying this row | +| wire (conductor in a multi-core cable) | ader | Cores inside one cable, so *ader*, not *draad* or *kabel* | +| positive / negative terminal | plusklem / minklem | Extends plus (+) / min (−) to the terminal at the power source | +| community forums | communityforums | Hat Labs support channel; solid compound per rule 4 | +| rainbow pattern (LED) | regenboogpatroon | HALPI2 LED fault pattern | +| boot mode switch | bootmodusschakelaar | HALPI2 only; on HALMET the equivalent is the `bootknop` | +| amber LED | amberkleurige led | | +| mass storage device | massaopslagapparaat | | +| command line tool | opdrachtregelgereedschap | "opdrachtregel" is the Dutch term for command line | +| block device | blockdevice | Adopted English two-word term becomes one Dutch word (rule 4) | +| device node | apparaatknooppunt | | +| hardware flow control | hardwarematige flowcontrol | "stromingsregeling" would read as fluid dynamics | +| chip select | chipselect | One word, adopted whole | +| Unix domain socket | Unix-domainsocket | Proper name takes exactly one hyphen at the junction (rule 4) | +| setup wizard | installatiewizard | | +| update manager | updatebeheer | Matches the *beheer* pattern (systeembeheer, energiebeheer) | +| port forwarding | port forwarding | Dutch network documentation uses the English term | +| login console | inlogconsole | | +| silk screen (board legend) | opdruk | Also a HALMET term; see `## HALMET terms` | +| computer mainboard | hoofdprint van de computer | HALPI2 only. *moederbord* is forbidden, so this is the alternative | +| device tree overlay | device tree overlay | Kept in English; the reader meets it verbatim in `config.txt` | +| board-to-board connector | board-to-boardconnector | Adopted English term, one Dutch word, internal hyphens kept | +| expansion board | uitbreidingsprint | Distinct from *carrierboard* and from *ontwikkelbord* | +| spudger | spudger | No Dutch equivalent in trade usage | +| guitar pick | plectrum | | +| to pry / to rock (a connector loose) | wrikken | | +| socket (hex tool) | dop / dopsleutel | Kept apart from *aansluiting* | +| surface-mounted component | SMD-component | SMD is the established Dutch trade abbreviation | +| countersunk screw | verzonken schroef | | +| heat spreading area | warmteafvoervlak | | +| Blinkenlights | Blinkenlights | Heading left untranslated — it is a joke term, not a description | +| Load Equivalency Number (LEN) | belastingsgetal (LEN) | NMEA 2000 network loading; the abbreviation is kept | +| voltage bar (LED pattern) | spanningsbalk | HALPI2 LED pattern; *ledbalk* is the physical bar | +| power button | aan/uit-knop | | +| transmit enable (signal/mode) | zendvrijgave | RS-485; one of the few places *zend-* is correct, because it really is a transmitter | +| watchdog timeout | watchdog-time-out | "time-out" is the Dutch spelling | +| grace period | wachttijd | "Respijtperiode" is legal register and wrong here | +| normally-open (NO) momentary switch | drukknop met maakcontact (normally open, NO) | The HALPI2 row that fixes *maakcontact*; HALMET extends it with *verbreekcontact* | +| Battery-Backed RAM (BBR) | batterijgebufferd RAM (BBR) | | +| half-duplex mode | halfduplexmodus | Solid compound, no hyphen | +| multi-talker / single-talker network | multi-talkernetwerk / single-talkertoepassing | Kept in English as trade usage, joined solid to the Dutch noun | +| baud rate / update rate | baudrate / updatesnelheid | | +| progressive fill / solid / dim red (LED states) | oplopende vulling / continu / gedempt rood | HALPI2 LED patterns | +| wake-up event | wekgebeurtenis | | +| Data Browser (Signal K) | Data Browser | A UI string the reader sees in English on their own screen | +| bps / kbps / Mbps (bit rate) | bit/s / kbit/s / Mbit/s | `16.3 kbps` on the 1-Wire section becomes `16,3 kbit/s` | +| Bluetooth | Bluetooth | Capitalised, unlike `wifi`. In compounds it takes exactly one hyphen at the junction (rule 4): `Bluetooth-verbinding` | +| tool / utility | gereedschap | Never *hulpmiddel*, which reads as an aid rather than a program | +| command | opdracht | Never *commando*, which in Dutch reads as a military order | +| section (of this documentation) | onderdeel | Not *gedeelte* and not *sectie* — *sectie* is reserved for a section of a configuration file. A section of the board is `deel` (`het gescheiden deel`) | +| Ethernet port | ethernetaansluiting | Board-mounted socket, so the *aansluiting* branch applies. Other ports stay *poort* (`USB-poort`) | +| USB Boot connector | USB-bootconnector | HALPI2 only. On HALMET the equivalent is the `micro-USB-connector` | + + diff --git a/solutions/translation/finnish-glossary.md b/solutions/translation/finnish-glossary.md index e022a4d..4dcb52d 100644 --- a/solutions/translation/finnish-glossary.md +++ b/solutions/translation/finnish-glossary.md @@ -191,7 +191,6 @@ them. | English | Finnish | Note | |:--------|:--------|:-----| -| power supply | virtalähde | | | power source | virransyöttö | | | input voltage range | syöttöjännitealue | | | polarity | napaisuus | | @@ -353,11 +352,12 @@ this heading are shared with HALPI2 and should not be changed here alone. | threshold voltage | kynnysjännite | | | hysteresis | hystereesi | | | floating (input) | kelluva | `tulo jää kelluvaksi` | -| normally open / normally closed | avautuva / sulkeutuva | Standard Finnish switch terms | +| normally open / normally closed | sulkeutuva / avautuva | SFS/IEC contact terms, and easy to get backwards: a *sulkeutuva* contact is open at rest and **closes** when actuated, which is what *normally open* means. Swedish `slutande`/`brytande` and German `Schließer`/`Öffner` line up the same way. | | self-resetting fuse | itsestään palautuva sulake | | | reverse polarity protection | napaisuussuojaus | | | overvoltage protection | ylijännitesuojaus | | | switching power supply | hakkuriteholähde | | +| power supply | teholähde | **A deliberate divergence from HALPI2, which uses `virtalähde`. Do not harmonise.** On HALMET the two collide: `vakiovirtalähde` is the constant current source, an entirely different component described on the same page, and `virtalähde` is a substring of it — so a reader meets what looks like one component with a modifier. `teholähde` is also the base of `hakkuriteholähde`, which this glossary already prescribes. | | current consumption | virrankulutus | | | short circuit | oikosulku | | | chafing (of a wire) | hankautuminen | | @@ -384,7 +384,7 @@ this heading are shared with HALPI2 and should not be changed here alone. | reset button | reset-painike | The board's own labels `Reset` and `Boot` stay in English | | boot button | boot-painike | | | bootloader | käynnistyslataaja | | -| download mode | latauslataustila | ESP32 flashing mode | +| download mode | lataustila | ESP32 flashing mode | | user-programmable LED | käyttäjän ohjattava LED | | | open hardware | avoin laitteisto | | diff --git a/solutions/translation/french-glossary.md b/solutions/translation/french-glossary.md new file mode 100644 index 0000000..c4aac64 --- /dev/null +++ b/solutions/translation/french-glossary.md @@ -0,0 +1,409 @@ +--- +title: French translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into French under docs/fr/ + - Reviewing a French translation for consistency + - Adding a new term that has no established French equivalent +tags: + - translation + - i18n + - french + - terminology + - mkdocs-static-i18n +--- + +# French translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into French under `docs/fr/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/fr/hardware/index.md`. Only markdown lives under `docs/fr/` — images and +other assets stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with +two different French words. `carrier board` → `carte porteuse` is the HALPI2 +call and stands here too, including its deliberate divergence from the Finnish +`emolevy`. Terms below the HALMET heading are additions this product needed; +everything above it is shared with HALPI2, and a change to a shared row should +be made in both repositories or in neither. + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *drop cable* becomes `câble de dérivation` on one page and +`câble de descente` on the next — and the result reads as machine output even +when each individual sentence is correct. + +This file is the reference that prevents that drift. It is a living document: +extend it when a page introduces a term that is not listed here, rather than +inventing a one-off translation. + +The Finnish glossary (`finnish-glossary.md`) is the sibling of this file and the +place to look for the general approach. The rules below cover what is specific +to French. + +Unlike the other files under `solutions/`, this one has no date in its filename +because it is meant to be edited in place, not superseded. + +## Names that are never translated + +Product names, protocol names, hardware standards, and software UI strings stay +in English — the device's own interface is in English, so translating a menu +name would send the reader looking for something that does not exist on screen. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, + I2C, 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, + Schmitt trigger, IoT +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `GPIO2`, `CCS`, `LP`, `VP`, `VN`, + `3V3`, `GND`. These are printed on the board; a translated pin name sends the + reader looking for a label that does not exist. +- **UI paths, commands, hostnames, file paths:** `main.cpp`, + `ConnectAlarmSender()`, and every command, hostname and path in the same + position. + +Code fences, command output, URLs and image filenames are never touched. + +## Style rules + +### Address form + +Instructions use **the second person plural imperative** (*vouvoiement*): + +> Branchez le câble d'alimentation. Vérifiez la polarité au multimètre avant de +> mettre sous tension. + +Not the infinitive (*Brancher le câble*), which reads as a parts list rather +than guidance, and not *tu*. + +Descriptive passages use a plain statement or the passive: + +> L'appareil s'éteint automatiquement lorsque l'alimentation est coupée. + +### Typography + +French typography is stricter than English and this is the most common source of +sloppy-looking translated pages. The space before `; : ! ?` is not decoration: +an ordinary space lets the line break in front of the punctuation, which is the +first thing a French reader notices. + +U+00A0 rather than U+202F (narrow no-break): U+202F is the typographically +precise character but renders inconsistently across fonts, while U+00A0 is +universally supported and is what French technical documentation uses in +practice. + +- **No-break space (U+00A0) before** `;` `:` `!` `?` and inside `« »` +- **Guillemets** `« … »` for quotations, not `"…"` +- **Decimal comma**, as in Finnish: `0,9 A`, `5,5 × 2,1 mm` +- **Space before the unit**: `12 V`, `250 kbit/s`, `−20 °C` +- **En dash for ranges**: `3–5 A` + +`scripts/check_typography.py fr` enforces the quotation pairing and the +no-break space; it is the one check that is different for French than for every +sibling language, so do not assume a clean run in another language says +anything about this one. + +### Units and numbers + +Identical handling to Finnish — the English source writes `12V` and `0.9A`, and +both are wrong in French. Convert every one. + +| English source | French | +|:---------------|:-------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `5-32 V` | `5–32 V` (en dash for ranges) | +| `100 kohm` | `100 kΩ` | + +`+/- 30 V` in the source is written `±30 V`. + +### Links, images, admonitions, navigation + +Same rules as the Finnish glossary: paths are copied from the English source +unchanged and never carry an `en/` or `fr/` segment; image captions and alt +texts are translated but filenames are not; screenshots stay English because the +reader's own screen is English; standard admonition titles are translated +centrally in `mkdocs.yml`, custom ones in the page. + +Two navigation entries are judgement calls worth recording: + +- `Errata` → **Problèmes connus**. The page lists known hardware defects, not + corrections to be applied; *errata* in French reads as a printer's correction + list. +- `Hardware Revisions` → **Versions de la carte**. The page is about board + versions, and *révisions* alone would suggest servicing. + +## Glossary + +### Enclosure, mounting, and installation + +| English | French | Note | +|:--------|:-------|:-----| +| carrier board | carte porteuse | Deliberately *not* the Finnish approach — see the note below | +| enclosure | boîtier | | +| heat sink | dissipateur thermique | | +| waterproof | étanche | | +| wall-mount | fixation murale | | +| mounting surface | surface de fixation | | +| pilot hole | avant-trou | | +| mounting template | gabarit de perçage | | +| bilge | cale | | +| bulkhead | cloison | | +| cable gland | presse-étoupe | | +| cable routing | cheminement des câbles | | +| service loop | boucle de service | | +| cable tie | collier de serrage | | +| blind plug | bouchon obturateur | | +| breather plug | bouchon d'équilibrage de pression | | + +**A note on `carte porteuse`, and why it differs from Finnish.** Finnish +translates `carrier board` as `emolevy` — literally *motherboard* — chosen for +reader familiarity over accuracy. French deliberately does **not** follow that: +`carte porteuse` says what the board actually is. + +Do not "harmonise" the two. They differ on purpose, decided per language and per +audience, and the divergence is the decision rather than an oversight in either +one. + +The practical consequence is that French needs *less* care than Finnish here. +`emolevy` inverts the CM5/board relationship and the Finnish glossary tells +translators to write the roles out explicitly in passages where that matters. +`carte porteuse` carries the relationship on its own, so the surrounding sentence +does not have to. + +### Electrical + +| English | French | Note | +|:--------|:-------|:-----| +| power supply | alimentation | | +| input voltage range | plage de tension d'entrée | | +| polarity | polarité | | +| fuse | fusible | | +| inline fuse | fusible en ligne | | +| circuit breaker | disjoncteur | | +| current limiting | limitation de courant | | +| overcurrent | surintensité | | +| voltage drop | chute de tension | | +| grounding | mise à la terre | | +| short circuit | court-circuit | | +| wire gauge | section du conducteur | French uses mm², not AWG | +| marine-grade wire | conducteur de qualité marine | | +| wire strippers | pince à dénuder | | +| crimping | sertissage | | +| crimper | pince à sertir | | +| heat-shrink tubing | gaine thermorétractable | | +| heat gun | pistolet à air chaud | | +| multimeter | multimètre | | +| terminal block | bornier | | +| strain relief | serre-câble | | +| super-capacitor | supercondensateur | | +| real-time clock | horloge temps réel | | +| backup battery | pile de sauvegarde | | + +### Connectors and interfaces + +| English | French | Note | +|:--------|:-------|:-----| +| connector | connecteur | | +| barrel connector | connecteur cylindrique | Add *(barrel)* on first mention | +| header | connecteur | `connecteur GPIO 40 broches` | +| pin | broche | | +| backbone | dorsale | NMEA 2000 backbone | +| drop cable | câble de dérivation | | +| T-connector | connecteur en T | | +| termination (120 Ω) | résistance de terminaison | | +| front panel | panneau avant | | +| jumper | cavalier | | +| male / female | mâle / femelle | | + +### System behaviour and status + +| English | French | Note | +|:--------|:-------|:-----| +| boat computer | ordinateur de bord | | +| to boot | démarrer | | +| first boot | premier démarrage | | +| shutdown | arrêt | | +| graceful shutdown | arrêt propre | | +| power loss | perte d'alimentation | | +| blackout | coupure de courant | | +| power management | gestion de l'alimentation | | +| status LED | LED d'état | | +| monitoring | surveillance | | +| passive cooling | refroidissement passif | | +| filesystem | système de fichiers | | +| to unmount | démonter | | +| watchdog | chien de garde (watchdog) | Keep the English in parentheses once | +| standby | veille | | + +### Software and networking + +| English | French | Note | +|:--------|:-------|:-----| +| firmware | firmware | Not *micrologiciel* — matches the Finnish decision to keep the term the trade uses | +| daemon | démon | Established in French Linux usage, unlike Finnish | +| to flash | flasher | | +| operating system image | image système | | +| headless | sans écran | First mention: `sans écran (headless)` | +| container app | application conteneurisée | | +| container image | image de conteneur | | +| dashboard | tableau de bord | | +| WiFi Access Point | point d'accès WiFi | | +| wired / wireless | filaire / sans fil | | +| credentials | identifiants | | +| default password | mot de passe par défaut | | +| single sign-on (SSO) | authentification unique (SSO) | | +| Certificate Authority (CA) | autorité de certification (CA) | | +| web interface | interface web | | +| browser | navigateur | | + +### Applications and use cases + +| English | French | Note | +|:--------|:-------|:-----| +| chart plotter | traceur de cartes | | +| data logging | enregistrement de données | | +| vessel | navire | | +| fleet management | gestion de flotte | | +| predictive maintenance | maintenance prédictive | | +| remote monitoring | surveillance à distance | | +| compliance | conformité | | +| warranty | garantie | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. Rows above +this heading are shared with HALPI2 and should not be changed here alone. + +### Board and inputs + +| English | French | Note | +|:--------|:-------|:-----| +| development board | carte de développement | HALMET is sold as one; not `carte porteuse`, which is HALPI2's carrier board and names a different relationship | +| digital input | entrée numérique | `D1`–`D4` stay as printed | +| analog input | entrée analogique | `A1`–`A4` stay as printed | +| input | entrée | | +| output | sortie | | +| sender | capteur | The marine sender a gauge reads; not *transmetteur*, which reads as a telemetry transmitter | +| tank sender | capteur de niveau de réservoir | `capteur de niveau` alone after first mention | +| resistive sender | capteur résistif | | +| gauge (engine panel gauge) | indicateur | `indicateur du tableau moteur`; not *jauge*, which names the level itself or the dipstick | +| counter | compteur | | +| chain counter | compteur de chaîne | Windlass chain counter | +| alarm signal | signal d'alarme | | +| engine RPM | régime moteur | Not *RPM*; the unit is written `tr/min` | +| tachometer | compte-tours | | +| alternator W terminal | borne W de l'alternateur | `W` is printed on the alternator and stays | +| fuel flow | débit de carburant | | + +### Measurement and circuits + +| English | French | Note | +|:--------|:-------|:-----| +| galvanic isolation | isolation galvanique | Not *isolement*, which names the property rather than the arrangement; one word throughout | +| isolated (section, area) | isolé | `partie isolée`, `zone isolée` | +| digital isolator | isolateur numérique | | +| isolation barrier | barrière d'isolation | | +| ground loop | boucle de masse | Not *boucle de terre*: the shared conductor in a boat's DC system is the masse. `grounding` stays `mise à la terre` in the shared table — the two are different senses, not a contradiction | +| analog-to-digital converter | convertisseur analogique-numérique | **Never abbreviate to `CAN`** — see the note below. `ADC` and `ADS1115` stay as printed | +| resolution (16-bit) | résolution | `résolution de 16 bits` | +| sampling rate | fréquence d'échantillonnage | | +| low-pass filter | filtre passe-bas | The solder jumper is labelled `LP` and stays | +| cutoff frequency | fréquence de coupure | | +| noise (electrical) | bruit | `bruit électrique` where a reader could hear sound; unlike Finnish, French uses one word for both | +| noise immunity | immunité au bruit | | +| voltage divider | diviseur de tension | | +| constant current source | source de courant constant | The header label `CCS` stays as printed; write `source de courant constant (CCS)` on first mention | +| excitation voltage | tension d'excitation | | +| passive voltage measurement | mesure passive de tension | | +| active resistance measurement | mesure active de résistance | | +| pull-up resistor | résistance de tirage vers le haut | Add `(pull-up)` on first mention on a page — datasheets print the English | +| pull-down resistor | résistance de tirage vers le bas | Add `(pull-down)` on first mention | +| threshold voltage | tension de seuil | | +| hysteresis | hystérésis | | +| floating (input) | flottant | `l'entrée reste flottante` | +| normally open / normally closed | normalement ouvert / normalement fermé | The established switch terms, abbreviated `NO` / `NF`. Not a literal rendering | +| self-resetting fuse | fusible réarmable | The PTC kind; *auto-réarmable* is the same thing, pick one | +| reverse polarity protection | protection contre l'inversion de polarité | | +| overvoltage protection | protection contre les surtensions | | +| switching power supply | alimentation à découpage | | +| current consumption | consommation de courant | | +| short circuit | court-circuit | Already in the shared Electrical table with the same sense; repeated here only because HALMET's wiring advice turns on it. Change it there, not here | +| chafing (of a wire) | ragage | The nautical term for wear by rubbing; `usure par frottement` if the passage is not addressed to boaters | + +**A note on `CAN`, and why the ADC is never abbreviated.** The standard French +abbreviation for *convertisseur analogique-numérique* is `CAN` — the same three +letters as the CAN bus, which appears on nearly every HALMET page. A sentence +about the CAN transceiver and one about the CAN of the ADS1115 would be +indistinguishable. Write the converter out in full, keep `CAN` for the bus, and +keep `ADC` where the English source uses it as a label. + +### Board features and assembly + +| English | French | Note | +|:--------|:-------|:-----| +| jumper | cavalier | The shared term, kept: a removable link placed on a pin pair. See *solder jumper* for the PCB kind | +| jumper header | connecteur à cavalier | The pin pair a cavalier is placed on; `header` is `connecteur` in the shared table and that is kept | +| solder jumper | pont à souder | Closed permanently with a soldering iron. **Never `cavalier`** — the distinction decides whether the reader reaches for a soldering iron or tries to pull off something soldered down. Avoid *pont de soudure*, which also names an accidental bridge, i.e. a defect | +| to short (a jumper) | court-circuiter | `court-circuitez les deux broches` | +| pad (solder pad) | pastille | `pastilles de soudure` where the sentence needs it spelled out | +| unpopulated | non implanté | `pastilles non implantées`, `connecteur non implanté` — the component was never fitted | +| pitch (2.54 mm) | pas | `pas de 2,54 mm` | +| pluggable terminal block | bornier débrochable | Phoenix MC type; `bornier` alone is the shared HALPI2 term | +| silkscreen | sérigraphie | | +| to solder | souder | | +| soldering iron | fer à souder | | +| grommet | passe-fil | Rubber or silicone; distinct from `presse-étoupe`, the threaded gland | +| step drill bit | foret étagé | The one that looks like a small metal Christmas tree | +| conical drill bit | foret conique | | +| panel connector | connecteur de panneau | Mounted through the enclosure wall | +| reset button | bouton Reset | The board's own labels `Reset` and `Boot` stay in English; `bouton Reset (réinitialisation)` on first mention | +| boot button | bouton Boot | | +| bootloader | bootloader | Kept English, like `firmware`; *chargeur d'amorçage* is correct but not what the ESP32 tooling or the trade says | +| download mode | mode de téléchargement | The ESP32 flashing mode entered with the Boot button | +| user-programmable LED | LED programmable par l'utilisateur | | +| open hardware | matériel libre | Parallel to *logiciel libre*; add `(open hardware)` on first mention | + +### A note on `connecteur` + +The shared glossary renders both `connector` and `header` as `connecteur`, and +that is kept. HALMET puts the two side by side more often than HALPI2 does — +*1-Wire header connector*, *analog input connectors* — so let the qualifier +carry the distinction (`connecteur 1-Wire`, `connecteurs des entrées +analogiques`) rather than inventing a second word. Where a sentence would +otherwise be ambiguous, say what the thing is: `barrette de broches` for a bare +pin strip, `connecteur de câble` for the plug. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes — the same command CI runs. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py fr` reports every prescribed term in + use. +5. `uv run python scripts/check_typography.py fr` passes — the French rules are + the ones no sibling language shares. +6. Structure matches the source — see `.claude/skills/translate-page/SKILL.md`. +7. Every term used on the page that appears in this glossary matches it. + +## Related + +- `finnish-glossary.md` — the sibling glossary and the general approach +- `.claude/skills/translate-page/SKILL.md` — the procedure +- mkdocs-static-i18n documentation: https://ultrabug.github.io/mkdocs-static-i18n/ diff --git a/solutions/translation/german-glossary.md b/solutions/translation/german-glossary.md new file mode 100644 index 0000000..1088b84 --- /dev/null +++ b/solutions/translation/german-glossary.md @@ -0,0 +1,459 @@ +--- +title: German translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into German under docs/de/ + - Reviewing a German translation for consistency + - Adding a new term that has no established German equivalent +tags: + - translation + - i18n + - german + - terminology + - mkdocs-static-i18n +--- + +# German translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into German under `docs/de/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/de/hardware/index.md`. Only markdown lives under `docs/de/` — images and +other assets stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with +two different German words. `carrier board` → `Trägerplatine` is the HALPI2 +call and stands here too, as does every typography rule below. Terms below the +`## HALMET terms` heading are additions this product needed; everything above it +is shared with HALPI2, and a change to a shared row should be made in both +repositories or in neither. + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `Lötbrücke` on one page and +`Lötjumper` on the next — and the result reads as machine output even when each +individual sentence is correct. + +This file is the reference that prevents that drift. It is a living document: +extend it when a page introduces a term that is not listed here, rather than +inventing a one-off translation. + +`finnish-glossary.md` was adapted from HALPI2 first and is the model this file +followed; the other glossaries in this directory are its siblings. The general +approach is the same in all of them; the rules below cover what is specific to +German. + +Unlike the other files under `solutions/`, this one has no date in its filename +because it is meant to be edited in place, not superseded. + +## Names that are never translated + +Product names, protocol names, hardware standards, and software UI strings stay +in English. The device's own interface and toolchain are in English, so +translating a menu name or a build target would send the reader looking for +something that does not exist on screen. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, + I2C, 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, + Schmitt trigger +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`. These are printed on the board; a translated pin name sends the reader + looking for a label that does not exist. +- **UI paths, commands, hostnames, file paths:** `main.cpp`, `ConnectAlarmSender()`, + `can0`, and every command line quoted from the source. + +Code fences, command output, URLs and image filenames are never touched. + +**`CAN bus` in German prose.** The standard stays as written where it names the +standard (`CAN bus`), but German compounds it as `CAN-Bus` when it becomes part +of a sentence: `der CAN-Bus`, `CAN-Bus-Aktivität`. Both are correct; do not +write `CAN Bus` without the hyphen. + +## Style rules + +### No space before punctuation + +**German does not put a space before `;` `:` `!` `?`** — write `Symptome:`, not +`Symptome :`. + +This is stated explicitly because the French glossary requires the opposite, and +that rule cost a 334-site correction on its own branch. Do not carry the French +habit across. German's non-breaking spaces belong elsewhere: between a number +and its unit, and inside abbreviations like `z. B.`. + +### Quotation marks + +German uses `„…“` — low opening, high closing. Not `"…"`, and not the French +`« … »`. + +### Address form + +Instructions use the **Sie form imperative**, the standard register for German +consumer and installation manuals: + +> Schließen Sie das Stromkabel an. Prüfen Sie die Polarität mit dem Multimeter, +> bevor Sie die Spannung einschalten. + +Not the infinitive (*Kabel anschließen*), which reads as a parts list, and not +*du*. + +Descriptive passages use a plain statement or the passive: + +> Das Gerät schaltet sich automatisch ab, wenn die Stromversorgung getrennt wird. + +### Compound nouns + +German compounds a multi-word proper name with hyphens throughout, which the +English source does not: + +- `NMEA-2000-Netzwerk`, `NMEA-2000-Bus`, `Signal-K-Server`, + `Raspberry-Pi-Antenne`, `Compute-Module-5-Anschluss` +- `HALPI2-Gehäuse`, `E7T-Stecker`, `HaLOS-Image`, `USB-Tastatur` + +On HALMET pages the same rule produces `HALMET-Platine`, `ESP32-WROOM-32E-Modul`, +`Phoenix-MC-Klemmenblock`, `1-Wire-Stiftleiste`, `I2C-Adresse`, +`Schmitt-Trigger-Eingang`, `CCS-Stiftleiste`. + +A missing hyphen inside such a compound is the most visible marker of a +machine-translated German page. + +### Units and numbers + +Same handling as the other languages — the English source writes `12V` and +`0.9A`, and both are wrong in German. + +| English source | German | +|:---------------|:-------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | + +HALMET's pages add three recurring forms: `320 ohms` → `320 Ω`, +`2.54 mm pitch` → `2,54 mm Rastermaß`, and `+/- 30 V` → `±30 V`. + +### Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry an `en/`, `de/` or other language segment; image +captions and alt texts are translated but filenames are not; screenshots stay +English because the reader's own screen is English; standard admonition titles +are translated centrally in `mkdocs.yml`, custom ones in the page. + +Two navigation entries are judgement calls worth recording: + +- `Errata` → **Bekannte Fehler**. The Latin term is opaque to a general reader, + and the page lists hardware defects that exist, not corrections to be applied. +- `Hardware Revisions` → **Hardware-Revisionen**. Board versions, not document + revisions. + +## Glossary + +### Enclosure, mounting, and installation + +| English | German | Note | +|:--------|:-------|:-----| +| carrier board | Trägerplatine | The accurate term, as in French — see the note below | +| enclosure | Gehäuse | | +| heat sink | Kühlkörper | | +| waterproof | wasserdicht | | +| wall-mount | Wandmontage | | +| mounting surface | Montagefläche | | +| pilot hole | Vorbohrung | | +| mounting template | Bohrschablone | | +| bilge | Bilge | | +| bulkhead | Schott | | +| cable gland | Kabelverschraubung | `PG7-Kabelverschraubung` | +| cable routing | Kabelführung | | +| service loop | Serviceschlaufe | | +| cable tie | Kabelbinder | | +| blind plug | Blindstopfen | | +| breather plug | Druckausgleichsstopfen | | + +**A note on `Trägerplatine`.** German takes the accurate term, like French +(`carte porteuse`) and unlike Finnish (`emolevy`, literally *motherboard*, chosen +there for reader familiarity). The divergence between the three is deliberate, +decided per language and per audience. Do not harmonise them. + +The practical consequence matches French: `Trägerplatine` carries the CM5/board +relationship on its own, so passages about reseating the CM5 or troubleshooting +a board that will not boot need no extra explanation. The Finnish glossary does +need that warning. + +On HALMET the term does not apply at all — HALMET carries no module and is a +`Entwicklungsboard`, see the HALMET section. The row stays because it is shared, +not because these pages use it. + +### Electrical + +| English | German | Note | +|:--------|:-------|:-----| +| power supply | Stromversorgung | The unit itself: *Netzteil* | +| input voltage range | Eingangsspannungsbereich | | +| polarity | Polarität | | +| fuse | Sicherung | | +| inline fuse | Leitungssicherung | | +| circuit breaker | Leitungsschutzschalter | | +| current limiting | Strombegrenzung | | +| overcurrent | Überstrom | | +| voltage drop | Spannungsabfall | | +| grounding | Erdung | | +| short circuit | Kurzschluss | | +| wire gauge | Leiterquerschnitt | German uses mm², not AWG | +| marine-grade wire | seewasserfeste Leitung | | +| wire strippers | Abisolierzange | | +| crimping | Crimpen | | +| crimper | Crimpzange | | +| heat-shrink tubing | Schrumpfschlauch | | +| heat gun | Heißluftpistole | | +| multimeter | Multimeter | | +| terminal block | Klemmenblock | | +| strain relief | Zugentlastung | | +| super-capacitor | Superkondensator | | +| real-time clock | Echtzeituhr | | +| backup battery | Pufferbatterie | | + +### Connectors and interfaces + +| English | German | Note | +|:--------|:-------|:-----| +| connector | Stecker / Anschluss | *Anschluss* for a board-mounted socket | +| barrel connector | Hohlstecker | | +| header | Stiftleiste | `40-polige GPIO-Stiftleiste` | +| pin | Pin | | +| backbone | Backbone | Established in German NMEA 2000 usage | +| drop cable | Stichleitung | | +| T-connector | T-Stück | | +| termination (120 Ω) | Abschlusswiderstand | | +| front panel | Frontplatte | | +| jumper | Jumper | The removable link; see *solder jumper* in the HALMET section for the soldered kind | +| male / female | Stecker / Buchse | | + +### System behaviour and status + +| English | German | Note | +|:--------|:-------|:-----| +| boat computer | Bordcomputer | | +| to boot | starten | | +| first boot | erster Start | | +| shutdown | Herunterfahren | | +| graceful shutdown | geordnetes Herunterfahren | | +| power loss | Spannungsausfall | | +| blackout | Stromausfall | | +| power management | Energieverwaltung | | +| status LED | Status-LED | | +| monitoring | Überwachung | | +| passive cooling | passive Kühlung | | +| filesystem | Dateisystem | | +| to unmount | aushängen | | +| watchdog | Watchdog | | +| standby | Standby | | + +### Software and networking + +| English | German | Note | +|:--------|:-------|:-----| +| firmware | Firmware | | +| daemon | Daemon | | +| to flash | flashen | | +| operating system image | Systemabbild | | +| headless | ohne Bildschirm | First mention: `ohne Bildschirm (headless)` | +| container app | Container-Anwendung | | +| container image | Container-Image | | +| dashboard | Dashboard | | +| WiFi Access Point | WLAN-Access-Point | German prose says *WLAN*; keep *WiFi* only where it names a UI string or a physical label | +| wired / wireless | kabelgebunden / drahtlos | | +| credentials | Zugangsdaten | | +| default password | Standardpasswort | | +| single sign-on (SSO) | Single Sign-on (SSO) | | +| Certificate Authority (CA) | Zertifizierungsstelle (CA) | | +| web interface | Weboberfläche | | +| browser | Browser | | + +### Applications and use cases + +| English | German | Note | +|:--------|:-------|:-----| +| chart plotter | Kartenplotter | | +| data logging | Datenaufzeichnung | | +| vessel | Schiff | | +| fleet management | Flottenmanagement | | +| predictive maintenance | vorausschauende Wartung | | +| remote monitoring | Fernüberwachung | | +| compliance | Konformität | | +| warranty | Garantie | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. Rows above +this heading are shared with HALPI2 and should not be changed here alone. + +### Board and inputs + +| English | German | Note | +|:--------|:-------|:-----| +| development board | Entwicklungsboard | HALMET is sold as one; not *Trägerplatine*, which is HALPI2's carrier board | +| digital input | Digitaleingang | `D1`–`D4` stay as printed | +| analog input | Analogeingang | `A1`–`A4` stay as printed | +| input | Eingang | | +| output | Ausgang | | +| sender | Geber | The marine sender a gauge reads. Never *Sender*, which in German means a radio transmitter or broadcast station | +| tank sender | Tankgeber | | +| resistive sender | Widerstandsgeber | | +| gauge (engine panel gauge) | Anzeigeinstrument | `Motorinstrument` where the engine panel is meant; never *Messgerät*, which is a test instrument | +| counter | Zähler | | +| chain counter | Kettenzähler | | +| alarm signal | Alarmsignal | | +| engine RPM | Motordrehzahl | Not *RPM*; German prose uses `1/min` or `U/min` for the unit | +| tachometer | Drehzahlmesser | | +| alternator W terminal | W-Klemme der Lichtmaschine | `W-Klemme` alone after first mention | +| fuel flow | Kraftstoffdurchfluss | | +| bilge alarm | Bilgenalarm | | +| pulse | Impuls | `Impulszähler` for the firmware's pulse counter | + +### Measurement and circuits + +| English | German | Note | +|:--------|:-------|:-----| +| galvanic isolation | galvanische Trennung | Not *Isolierung*, which is insulating material | +| isolated (section, area) | galvanisch getrennt | `galvanisch getrennter Bereich`; shortened to `getrennter Bereich` after first mention | +| digital isolator | Digitalisolator | | +| isolation barrier | Trennstelle | `galvanische Trennstelle` on first mention | +| ground loop | Masseschleife | Boat DC grounds; not *Erdschleife*, which belongs to mains earthing | +| analog-to-digital converter (ADC) | Analog-Digital-Wandler (ADC) | The part number `ADS1115` stays | +| resolution (16-bit) | Auflösung | `16-Bit-Auflösung` | +| sampling rate | Abtastrate | | +| low-pass filter | Tiefpassfilter | | +| cutoff frequency | Grenzfrequenz | | +| noise (electrical) | Störungen | Not *Rauschen*, which is broadband noise specifically, and never *Lärm* or *Geräusch*, which are sound | +| noise immunity | Störfestigkeit | | +| voltage divider | Spannungsteiler | | +| constant current source (CCS) | Konstantstromquelle | The header label `CCS` stays as printed | +| excitation voltage | Speisespannung | *Erregerspannung* is the literal bridge-measurement term; `Speisespannung` is what a boat electrician reads | +| passive voltage measurement | passive Spannungsmessung | | +| active resistance measurement | aktive Widerstandsmessung | | +| pull-up resistor | Pull-up-Widerstand | Hyphenated both sides; not *Pullup-Widerstand* | +| pull-down resistor | Pull-down-Widerstand | | +| threshold voltage | Schwellenspannung | | +| hysteresis | Hysterese | | +| floating (input) | undefiniertes Potenzial | `der Eingang liegt auf undefiniertem Potenzial`. **Never *potentialfrei*** — see the note below | +| normally open / normally closed | Schließer / Öffner | The established German switch terms; see the note below | +| self-resetting fuse | selbstrückstellende Sicherung | The PTC type; *rückstellbare Sicherung* is also read | +| reverse polarity protection | Verpolungsschutz | | +| overvoltage protection | Überspannungsschutz | | +| switching power supply | Schaltnetzteil | | +| current consumption | Stromaufnahme | Not *Stromverbrauch*, which is energy over time | +| short circuit | Kurzschluss | Inherited row; the sense is the same here | +| chafing (of a wire) | Scheuern | `Scheuerstellen` for the damaged spots | +| voltage spike | Spannungsspitze | | + +**A note on `normally open` / `normally closed`.** German has established +single-word terms: a normally open contact is a **Schließer** (it closes on +actuation), a normally closed contact an **Öffner** (it opens on actuation). +Use them. A literal *normalerweise offen / normalerweise geschlossen* is +readable but marks the page as translated, and worse, it inverts easily under +editing — `Schließer` and `Öffner` cannot be got backwards by accident because +each names what the switch *does*. Write `Schließer (normally open)` on first +mention if the reader is likely to be matching against an English datasheet. + +**A note on `floating`.** German `potentialfrei` is a false friend here. It +means galvanically isolated — a volt-free contact, a *good* property, and the +one HALMET's isolation barrier actually provides. The English source's +*floating* means the opposite kind of thing: an input left undriven, sitting at +an undefined level and reading high or low at random. Rendering that as +`potentialfrei` tells the reader the circuit is fine when the page is telling +them to enable a pull-down resistor. Write `undefiniertes Potenzial` or +`unbeschalteter Eingang`. + +### Board features and assembly + +| English | German | Note | +|:--------|:-------|:-----| +| jumper | Jumper | Inherited row. The removable link placed on a pin pair — see the note below | +| jumper header | Jumper-Stiftleiste | The pin pair a jumper is placed on; `CCS-Stiftleiste` | +| solder jumper | Lötbrücke | Closed permanently with solder, not with a removable jumper — see the note below | +| to short (a jumper) | schließen | `die Lötbrücke schließen`, `die Kontakte brücken` | +| solder pad | Lötpad | *Lötfläche* is equally correct; pick one per page | +| unpopulated | unbestückt | `unbestückte Lötpads` | +| pitch (2.54 mm) | Rastermaß | `2,54 mm Rastermaß` | +| pluggable terminal block | steckbarer Klemmenblock | Phoenix MC type; `Klemmenblock` alone is the shared HALPI2 term | +| silkscreen | Bestückungsdruck | Not *Siebdruck*, which names the printing process, not the layer | +| to solder | löten | | +| soldering iron | Lötkolben | | +| grommet | Kabeltülle | Rubber or silicone; distinct from `Kabelverschraubung`, the threaded gland | +| step drill bit | Stufenbohrer | The one that looks like a metal Christmas tree | +| conical drill bit | Kegelbohrer | | +| panel connector | Einbausteckverbinder | `Einbaustecker` / `Einbaubuchse` when the gender matters | +| reset button | Reset-Taster | The board's own labels `Reset` and `Boot` stay in English | +| boot button | Boot-Taster | | +| bootloader | Bootloader | | +| download mode | Download-Modus | The ESP32 flashing mode | +| user-programmable LED | benutzerprogrammierbare LED | | +| open hardware | Open Hardware | The movement and licence family; add `offene Hardware` in parentheses on first mention | + +**A note on `Lötbrücke` and `Jumper`.** These are two different things and the +page tells the reader to do two different things with them: + +- A **Lötbrücke** (solder jumper) is a pair of pads on the PCB, closed + permanently with a soldering iron. HALMET's CAN terminator, low-pass filter, + pull-up, pull-down and ADS1115 address selections are all Lötbrücken, all on + the underside of the board. +- A **Jumper** is a removable plastic link pushed onto a pin pair. HALMET's + constant-current source is enabled this way, with a Jumper on the `CCS` + header. + +Rendering both as *Jumper*, or both as *Brücke*, sends the reader either +reaching for a soldering iron they do not need or trying to pull off something +that is soldered down. Keep `Lötbrücke` for the pads and `Jumper` for the link, +and never write *Lötjumper* or *Jumperbrücke*. + +### A note on `Stecker`, `Anschluss` and `Stiftleiste` + +The shared glossary splits `connector` into `Stecker` (the plug) and `Anschluss` +(the board-mounted socket), and renders `header` as `Stiftleiste`. That split is +kept, and HALMET needs it more than HALPI2 did, because the source puts the two +words side by side — *1-Wire header connector*, *analog input connectors*, +*panel connector*. Resolve each by what the thing is rather than by the English +wording: `1-Wire-Stiftleiste` (a pin strip on the board), +`Analogeingangs-Anschlüsse` (sockets on the board), +`Einbausteckverbinder` (the connector through the enclosure wall). Do not +translate *header connector* as two words. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes — the same command CI runs. +2. `uv run python scripts/check_typography.py de` reports no faults — this is + what catches a French space before a colon or a `"…"` pair that should be + `„…“`. +3. `uv run python scripts/check_glossary.py de` reports no unused prescribed + term. +4. `uv run python scripts/translation_status.py` shows the page as current. +5. `uv run mkdocs serve` shows the page rendering correctly in the browser, with + lists as lists (see + `../best-practices/markdown-lists-need-blank-line-2026-05-16.md` — the + blank-line rule applies identically to German pages). +6. Every term used on the page that appears in this glossary matches it. + +## Related + +- `finnish-glossary.md` and the other glossaries in this directory — the siblings +- `/Users/helmi/projects/halpi2/solutions/translation/german-glossary.md` — the + source this file was copied from; shared rows must change in both or neither +- `solutions/best-practices/markdown-lists-need-blank-line-2026-05-16.md` +- mkdocs-static-i18n documentation: https://ultrabug.github.io/mkdocs-static-i18n/ diff --git a/solutions/translation/italian-glossary.md b/solutions/translation/italian-glossary.md new file mode 100644 index 0000000..788dca1 --- /dev/null +++ b/solutions/translation/italian-glossary.md @@ -0,0 +1,776 @@ +--- +title: Italian translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Italian under docs/it/ + - Reviewing an Italian translation for consistency + - Adding a new term that has no established Italian equivalent +tags: + - translation + - i18n + - italian + - terminology + - mkdocs-static-i18n +--- + +# Italian translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Italian under `docs/it/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/it/hardware/index.md`. There are eight pages, each an `index.md` inside its +section directory. Only markdown lives under `docs/it/` — images and other assets +stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with two +different Italian words. A reader who has both boards on the same bulkhead should +meet `pressacavo`, `morsettiera`, `fusibile` and `scheda portante` with the same +meaning in both manuals. Terms below the `## HALMET terms` heading are additions +this product needed; everything above it is shared with HALPI2, and **a change to +a shared row must be made in both repositories or in neither.** The same applies +to the six typography rules — they were decided for Italian as a language, not +for one product, and a rule relaxed here would immediately disagree with the +HALPI2 pages. + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `jumper a saldare` on one page and +`ponticello` on the next — and the result reads as machine output even when each +individual sentence is correct. + +`finnish-glossary.md` is the sibling of this file in this repository, and it was +adapted from HALPI2 first; the sibling French, German and Swedish glossaries live +in the HALPI2 repository. The general approach is the same in all of them. + +The locale code is `it`. mkdocs-material ships built-in UI translations for it, +so nothing in the theme chrome needs a manual string. `it` is already registered +in `scripts/check_glossary.py` and `scripts/check_typography.py` in this +repository, so both checks run without further setup. + +Unlike the other files under `solutions/`, this one has no date in its filename +because it is meant to be edited in place, not superseded. + +## Six rules where the siblings are wrong for Italian + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary. The recorded failure mode in this +repository is exactly that — a rule from a neighbouring language carried across, +or a rule written here and then applied to the first three pages only. Both were +caught by *counting* the finished pages, never by rereading them. Each rule below +is therefore written so it can be counted; the commands are in +[Verification](#verification). + +1. **Address the reader impersonally.** Instructions use the **infinitive**, which + is the standard register of Italian installation and user manuals: + + > Collegare i conduttori NMEA 2000 alla morsettiera. Verificare la polarità + > con il multimetro prima di dare tensione. + + Descriptive passages use the impersonal *si*, the passive, or a plain + statement: + + > Il generatore di corrente costante si abilita cortocircuitando i contatti + > del connettore CCS. È possibile accedere alle piazzole di saldatura dopo + > aver estratto la scheda dalla custodia. + + **Never `tu`** (Swedish uses `du`), **never `Lei`** (German uses `Sie`), + **never the second person plural** (French uses *vouvoiement*). Italian + differs from all four siblings here, which makes this the rule most likely to + drift. No `puoi`, `devi`, `il tuo`, `la Sua`, `potete` anywhere in `docs/it/`. + + The English source is written in the second person and uses it heavily — + *you will need to solder the headers*, *if you're planning to wall-mount the + enclosure*, *in your program, use GPIO4*. Recast every one of them; do not + carry the pronoun over. *your program* becomes `il proprio programma`, + *your HALMET* becomes `il proprio HALMET` or simply `HALMET`. + +2. **Quotation marks are `"…"`** — U+201C opening, U+201D closing. **Not** the + caporali `« … »`: those belong to French here, and choosing them would drag in + the French no-break-space-inside habit with them. Not the German `„…"`, not + straight `"…"`. + + Almost everything quoted in this corpus is a physical label printed on the + board — `"DQ"`, `"Reset"`, `"Boot"`, `"CCS"`, `"LP"`, `"3V3"`, `"GND"` — and + doppi apici are the Italian convention for exactly that. The label text itself + stays in English; only the marks around it are Italian. + +3. **No space before `; : ! ?`** — as in German and Swedish, and unlike French, + whose rule is the exact opposite and demands a no-break space. Write + `Sintomi:`, never `Sintomi :`. The French rule cost a 334-site correction on + its own branch; it must not cross into Italian. + + Italian's only no-break space (U+00A0) is between a number and its unit: + `12 V`, `0,9 A`. + +4. **Never hyphenate a product name into a compound.** German writes + `NMEA-2000-Netzwerk` and Swedish writes `NMEA 2000-nätverk`. Italian does + neither: the name follows the noun as a plain apposition. + + - `rete NMEA 2000`, `bus NMEA 2000`, `server Signal K`, `framework SensESP` + - `bus I2C`, `sensore 1-Wire`, `connettore 1-Wire`, `connettore M12` + - `custodia di HALMET`, `ingressi digitali di HALMET`, `connettore USB` + - `modulo ESP32-WROOM-32E`, `convertitore ADS1115`, `morsettiera Phoenix MC` + + A hyphen between an English product name and an Italian noun is the single + most visible marker that a rule was copied from the German or Swedish page. + Hyphens inside a name that already has one (`1-Wire`, `ESP32-WROOM-32E`, + `RS-485`, `T-connector` as a source term) are untouched — the rule is about + *joining* a name to an Italian word. + +5. **Typographic apostrophe U+2019, and no apostrophe on `qual è`.** Italian + elides constantly — `l'alimentazione`, `dell'involucro`, `un'antenna`, + `all'interno` — and the character is always `'` (U+2019), never the straight + `'` (U+0027). No sibling glossary states this because no sibling needs it. + + `qual è` is written **without** an apostrophe. `qual'è` is the classic Italian + spelling error and it is trivially countable. + + Accents are not optional: `perché`, `poiché`, `affinché`, `né`, `sé`, `più`, + `così`, `è`. The grave-for-acute mistakes (`perchè`, `poichè`) are the second + trivially countable error. + +6. **No English plural `-s` on a loanword.** Italian borrows the singular and + leaves it invariable: `i jumper`, `i LED`, `i firmware`, `i pin`, + `i bootloader`, `i transceiver`, `i container`. Writing `i jumpers` or + `i LEDs` is the clearest tell of an unedited machine translation, and the + English source is full of the plural forms that invite it — *four digital + inputs*, *solder jumpers*, *pull-up resistors*, *panel connectors*. The + Italian nouns behind those (`ingressi`, `resistenze`, `connettori`) inflect + normally; only the borrowed English word stays fixed. + +## Names that are never translated + +Product names, protocol names, hardware standards and software UI strings stay +in English — the device's own interface is in English, so translating a menu +name would send the reader looking for something that does not exist on screen. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, Hat Labs. +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, I2C, + 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, Schmitt + trigger. +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`, and the `DI1`–`DI4` / `TDI`, `TCK`, `TMS`, `TDO` entries of the GPIO + table. These are printed on the board; **a translated pin name sends the reader + looking for a label that does not exist.** The surrounding prose is translated + as usual — `la linea dati DQ`, `il pin di reset EN`, `l'ingresso digitale D1`. + +Also never translated: + +- **Commands, file paths, repository names and identifiers** — `main.cpp`, + `ConnectAlarmSender()`, `HALMET-example-firmware`, `platformio.ini`. +- **Code fences and their contents**, including comments inside them, and all + command output. +- **Silkscreen and button labels** — `"Reset"`, `"Boot"`, `"DQ"`, `"CCS"`, + `"LP"`, `"3V3"`, `"GND"`. The board carries them in English; only the marks + around them are Italian, per rule 2. +- **URLs and image filenames.** + +Gender and article, fixed once so pages do not disagree with each other: + +- **HALMET** takes the elided article, because the `h` is silent: `l'HALMET`, + `dell'HALMET`, `all'HALMET`. Never `il HALMET`. (Same rule as `l'HALPI2` in the + sibling manual.) +- **ESP32, ESP32-WROOM-32E, ADS1115** are masculine: `l'ESP32`, `il modulo + ESP32-WROOM-32E`, `l'ADS1115`. +- **jumper, container, firmware, pin, LED, bootloader, transceiver, browser** + are masculine and invariable: `il jumper` / `i jumper`, `il LED` / `i LED`. +- **scheda portante**, **scheda di sviluppo**, **morsettiera**, **sonda** and + **piazzola** are feminine. +- **ingresso**, **connettore**, **sensore**, **partitore**, **contagiri** are + masculine. + +For bare acronyms, prefer putting an Italian noun in front rather than guessing +an article: `la porta USB`, `il bus I2C`, `il connettore M12`, +`il convertitore ADC`, `il generatore CCS`. + +## Glossary + +### Enclosure, mounting, and installation + +| English | Italian | Note | +|:--------|:--------|:-----| +| carrier board | scheda portante | The accurate term, as in French, German and Swedish — see the note below | +| enclosure | custodia | Not *involucro*, the normative IEC word, which reads as a standards document | +| lid | coperchio | | +| gasket | guarnizione | | +| heat sink | dissipatore di calore | | +| waterproof | impermeabile | One word for the whole corpus; do not alternate with *stagno* | +| wall-mount | montaggio a parete | | +| mounting surface | superficie di montaggio | | +| pilot hole | foro pilota | A hole **the reader drills**: `Praticare i fori pilota per le viti` | +| pre-drilled hole | foro predisposto | A hole **the enclosure ships with** — see the warning below | +| mounting template | dima di foratura | | +| bilge water | acqua di sentina | | +| bulkhead | paratia | | +| cable gland | pressacavo | | +| cable routing | posa dei cavi | | +| service loop | riserva di cavo | Slack left at both cable ends; gloss `(service loop)` on first mention | +| cable tie | fascetta | | +| blind plug | tappo cieco | | +| breather plug | tappo di compensazione | Pressure equalisation; must not be removed | +| thermal pad | pad termico | | +| standoff | distanziale | | +| countersunk screw | vite svasata | | +| socket (tool) | chiave a bussola | `chiave a bussola da 26 mm` | + +**`foro pilota` and `foro predisposto` are two different things.** The English +source uses *pilot hole* for a hole the installer drills into the bulkhead, and +*pre-drilled* for the connector openings the enclosure already has. Conflating +them produced a nonsense instruction on the Swedish branch — *drill the +pre-drilled holes*. Keep them apart: `Praticare i fori pilota` for the reader's +drilling step, `posizioni predisposte` / `fori predisposti` for the factory +openings on the front panel. + +**A note on `scheda portante`.** Italian takes the accurate term, like French +(`carte porteuse`), German (`Trägerplatine`) and Swedish (`bärkort`), and unlike +Finnish (`emolevy`, literally *motherboard*, chosen there for reader +familiarity). The divergence is deliberate, decided per language and per +audience. Do not harmonise them, and do not reach for `scheda madre`: it names +the wrong board and inverts the CM5 relationship. + +`scheda portante` carries the CM5/board relationship on its own, so passages +about reinserting the CM5 or troubleshooting a board that will not boot need no +extra explanation. Only the Finnish glossary needs that warning. Gloss +`(carrier board)` in parentheses on the first mention of each page, because the +English term is what is printed in the schematics the reader may open next. + +### Power and electrical + +| English | Italian | Note | +|:--------|:--------|:-----| +| power supply | alimentazione | The unit itself: *alimentatore* | +| input voltage range | intervallo di tensione di ingresso | | +| polarity | polarità | | +| rail (3.3V rail) | linea | `la linea da 3,3 V`, `la linea da 5 V` | +| fuse | fusibile | | +| inline fuse | fusibile in linea | | +| circuit breaker | interruttore automatico | | +| current limiting | limitazione di corrente | The switch itself: *limitatore di corrente* | +| overcurrent | sovracorrente | | +| voltage drop | caduta di tensione | | +| grounding | messa a terra | | +| short circuit | cortocircuito | | +| wire gauge | sezione del conduttore | Italian uses mm², not AWG | +| marine-grade wire | cavo per uso nautico | | +| wire strippers | pinza spelafili | | +| crimping | crimpatura | | +| crimper | pinza crimpatrice | | +| heat-shrink tubing | guaina termorestringente | | +| heat gun | pistola termica | | +| multimeter | multimetro | | +| terminal block | morsettiera | | +| strain relief | scarico della trazione | | +| super-capacitor | supercondensatore | Also renders *supercapacitor*, written as one word in the English source | +| real-time clock | orologio in tempo reale | Keep `(RTC)` on first mention | +| backup battery | batteria tampone | | +| power loss | mancanza di alimentazione | | +| blackout | interruzione di corrente | `blackout timer` becomes `timer di interruzione di corrente` | + +### Connectors and interfaces + +| English | Italian | Note | +|:--------|:--------|:-----| +| connector | connettore | | +| barrel connector | connettore cilindrico | Gloss `(barrel)` on first mention | +| header | connettore a pettine | GPIO: `connettore GPIO a 40 pin` | +| pin | pin | Invariable: `i pin`, never `i pins` | +| pinout | piedinatura | | +| pitch | passo | `passo 3,81 mm` | +| jumper | jumper | Invariable; the word is on the silkscreen | +| backbone | dorsale | `dorsale NMEA 2000` | +| drop cable | cavo di derivazione | | +| T-connector | connettore a T | The source also says *T-adapter*; both become `connettore a T` | +| terminator | resistenza di terminazione | The jumper: `jumper di terminazione` | +| termination | terminazione | The act, or the state of the network | +| front panel | pannello frontale | | +| male / female | maschio / femmina | | +| receptacle | presa | | +| flexible flat cable | cavo piatto flessibile | Keep `(FFC)`; the acronym is used alone afterwards | +| board-to-board connector | connettore scheda-scheda | | + +### Operation and system behaviour + +| English | Italian | Note | +|:--------|:--------|:-----| +| boat computer | computer di bordo | | +| boot | avvio | The verb: *avviare* / *avviarsi* | +| first boot | primo avvio | | +| shutdown | spegnimento | The verb: *spegnere* | +| graceful shutdown | spegnimento controllato | | +| power management | gestione dell'alimentazione | | +| status LED | LED di stato | `i LED`, never `i LEDs` | +| monitoring | monitoraggio | | +| passive cooling | raffreddamento passivo | | +| filesystem | file system | Two words, masculine, invariable | +| unmount (filesystem) | smontare | `smontare il file system` | +| unmount (module or board) | rimuovere | Physical removal — `rimuovere la scheda portante dalla custodia` | +| reseat | reinserire | `reinserire il CM5 nel connettore` | +| watchdog | watchdog | Invariable | +| standby | standby | `modalità standby`; not *attesa* — it names a firmware state | +| power cycle | spegnere e riaccendere | Verb phrase; there is no good Italian noun | +| chart plotter | plotter cartografico | Gloss `(chartplotter)` on first mention | +| vessel | imbarcazione | Exception: *research vessels* is `navi da ricerca` | +| data logging | registrazione dei dati | | +| fleet management | gestione della flotta | | +| predictive maintenance | manutenzione predittiva | | +| remote monitoring | monitoraggio remoto | | +| compliance | conformità | | +| warranty | garanzia | | + +### Software and networking + +| English | Italian | Note | +|:--------|:--------|:-----| +| firmware | firmware | Invariable, masculine — matches the sibling decision to keep the trade term | +| daemon | demone | Established in Italian Linux usage | +| flash (firmware) | flashare | `flashare il firmware dell'RP2040` | +| system image | immagine di sistema | Also `immagine del sistema operativo` where the source spells it out | +| headless | senza monitor | First mention: `senza monitor (headless)` | +| container app | applicazione in container | The Cockpit menu is `Container Apps` and stays English | +| container image | immagine del container | | +| dashboard | dashboard | Feminine: `la dashboard`. Homarr's view; not *cruscotto* | +| WiFi Access Point | access point WiFi | Standard Italian usage keeps *access point* | +| wired / wireless | via cavo / wireless | | +| credentials | credenziali | | +| default password | password predefinita | | +| single sign-on | autenticazione unica | Keep `(SSO)` on first mention, then `SSO` | +| Certificate Authority | autorità di certificazione | Keep `(CA)` on first mention, then `CA` | +| web interface | interfaccia web | | +| browser | browser | Invariable | +| remote access | accesso remoto | | +| update | aggiornamento | The verb: *aggiornare* | +| roll back | ripristinare | `ripristinare la versione precedente del firmware` | + +## Units and numbers + +The English source writes `12V` and `0.9A`, and both are wrong in Italian. +Convert every one. Numbers inside code fences and inline code are never touched. + +| English source | Italian | +|:---------------|:--------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | +| `9–36 VDC` | `9–36 V CC` | +| `200×130×60 mm` | `200 × 130 × 60 mm` | + +- **Decimal comma** everywhere in prose and tables: `0,9 A`, `3,81 mm`, `10,8 V`. +- **No-break space (U+00A0) between number and unit**, so the line never breaks + between them. +- **Multiplication sign** `×` (U+00D7) for dimensions and quantities — `4× 25 F`, + `2× USB 3.0` — never the letter `x`. +- **Minus sign** `−` (U+2212) for negative temperatures, not a hyphen. +- **En dash** `–` (U+2013) for ranges. In running prose `da −20 °C a +60 °C` + reads better than the dash and is allowed; in tables use the dash form. +- **No thousands separator** in technical figures: `250 kbit/s`, not `250.000`. +- Every numeral in the English page must appear in the Italian page. A wrong + voltage in an installation guide is a safety defect, not a typo. + +The conversions HALMET's own pages actually need, worked out once so the eight +pages cannot disagree. The rules above are shared with HALPI2; only these +examples are HALMET's: + +| English source | Italian | +|:---------------|:--------| +| `5-32 V`, `9-36 V` | `5–32 V`, `9–36 V` | +| `-32 V and +32 V` | `−32 V e +32 V` | +| `+/- 30 V` | `±30 V` | +| `120 ohm`, `320 ohms` | `120 Ω`, `320 Ω` | +| `100 kohm` | `100 kΩ` | +| `2.3 kHz`, `160 Hz` | `2,3 kHz`, `160 Hz` | +| `1.55 V`, `0.7 V`, `0.07 A` | `1,55 V`, `0,7 V`, `0,07 A` | +| `2.54 mm pitch`, `3.81` | `passo 2,54 mm`, `3,81` | +| `12.5 mm or 1/2"` | `12,5 mm o 1/2"` | +| `16.3 kbps` | `16,3 kbit/s` | +| `860 samples per second` | `860 campioni al secondo` | +| `2x10 pin` | `2 × 10 pin` | + +`1/2"` and `5/8"` are inch sizes for drill bits and stay as written — the +double-prime is part of the measurement, not a quotation mark, so rule 2 does not +touch it and neither does `check_typography.py`, which only counts `“` and `”`. + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: + +- Paths are copied from the English source unchanged and **never** carry an + `en/` or `it/` segment. The language comes from the directory the file is in. +- Image captions and alt texts are translated; filenames are not. +- Screenshots stay English, because the reader's own screen is English. +- Standard admonition titles (`note`, `warning`, `tip`, `info`, `danger`, + `example`) are translated centrally in `mkdocs.yml`, under the `it` language's + `admonition_translations`: `Nota`, `Avvertenza`, `Suggerimento`, + `Informazione`, `Pericolo`, `Esempio`. A **custom** title is translated in the + page: `!!! warning "Importante"`, `!!! danger "Attenzione"`, + `!!! quote "Informazioni correlate"`. The English source also writes a bare + `**NOTE:**` in `usage/index.md`; that is prose, not an admonition, and becomes + `**NOTA:**`. +- Navigation titles live in `mkdocs.yml` under `nav_translations`, not in any + markdown file. Three are judgement calls worth recording: + `Errata` → **Problemi noti**, matching HALPI2. These page names follow HALPI2 rather than the reading this glossary first recorded, because the same person reads both sites and a page cannot carry two names across two Hat Labs products. `Errata corrige` and `Guida introduttiva` are both defensible Italian; they simply lose to consistency here. If they are ever preferred, the change belongs in both repositories. + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. **Rows above +this heading are shared with HALPI2 and must not be changed here alone.** A few +rows below repeat a shared term deliberately — because HALMET uses it constantly +and a translator must not have to guess whether the shared row still applies. +Where a repeated row appears, its Italian is identical to the shared one; where +the shared row means something else, the note says so instead of contradicting +it. + +### Board and inputs + +| English | Italian | Note | +|:--------|:--------|:-----| +| development board | scheda di sviluppo | What HALMET is sold as. **Not** `scheda portante`: that shared row names HALPI2's role (a board that carries a CM5) and HALMET carries nothing. The shared row stays for the sibling manual; it simply never fires on a HALMET page | +| digital input | ingresso digitale | `D1`–`D4` stay as printed. Consistent with the shared `input voltage range → intervallo di tensione di ingresso` | +| analog input | ingresso analogico | `A1`–`A4` stay as printed | +| input | ingresso | Never *entrata*, and never *input* left in English | +| output | uscita | | +| sensor | sensore | The generic device (`sensori 1-Wire`, `sensori di temperatura`) | +| sender | sonda | The marine/automotive resistive device a gauge reads. Kept apart from `sensore` because the source uses both, sometimes in one sentence. *Trasmettitore* is the literal automotive calque but suggests something that transmits a signal over a link | +| tank sender | sonda di livello del serbatoio | Short form `sonda di livello` after first mention | +| resistive sender | sonda resistiva | | +| gauge (engine panel gauge) | indicatore | `indicatore del quadro motore`. Not *misuratore*, not *manometro* — that is a pressure gauge only | +| engine panel | quadro motore | | +| counter | contatore | | +| pulse counter | contatore di impulsi | The firmware feature in `main.cpp` | +| chain counter | contacatena | Windlass chain counter. `contametri` also circulates; one form only | +| alarm signal | segnale di allarme | | +| engine RPM | regime del motore | The reading itself: `numero di giri`. The unit is written `giri/min`, never `RPM`, which is not used in Italian prose | +| tachometer | contagiri | Masculine and invariable: `il contagiri`, `i contagiri` | +| alternator W terminal | morsetto W dell'alternatore | `morsetto`, not *terminale* — the shared glossary reserves *morsettiera* for the block and this is the single post | +| fuel flow | portata del carburante | | + +### Measurement and input circuits + +| English | Italian | Note | +|:--------|:--------|:-----| +| galvanic isolation | isolamento galvanico | Matches the inherited `galvanically isolated → isolato galvanicamente` | +| isolated section / isolated area | sezione isolata / area isolata | *Isolated area power header* is `connettore a pettine di alimentazione dell'area isolata` | +| digital isolator | isolatore digitale | The component; `isolamento` is the property | +| isolation barrier | barriera di isolamento | Figure caption on `hardware/index.md` | +| ground loop | anello di massa | **The shared row `grounding → messa a terra` is the protective-earth sense and is wrong here.** These inputs share no earth; the reference is `massa`. Never *messa a terra* for GND | +| analog-to-digital converter (ADC) | convertitore analogico-digitale | Keep `(ADC)` on first mention, then `ADC`. `ADS1115` is a part number and stays | +| resolution (16-bit) | risoluzione | `risoluzione a 16 bit`. No clash with `Risoluzione dei problemi` as a heading — different collocation, both correct Italian | +| sampling rate | frequenza di campionamento | `860 campioni al secondo` for *samples per second* | +| low-pass filter | filtro passa-basso | Invariable in the plural: `filtri passa-basso` | +| cutoff frequency | frequenza di taglio | | +| noise (electrical) | disturbi | Masculine plural, as Italian normally puts it: `ridurre i disturbi di misura`, `filtraggio dei disturbi RF`. *Rumore* is correct only in `rapporto segnale/rumore`, which does not occur here, and reads as acoustic noise everywhere else | +| noisy (signal source) | disturbato | `una sorgente di impulsi molto disturbata` | +| noise immunity | immunità ai disturbi | Keeps the `disturbi` choice above; the Schmitt trigger sentence | +| voltage divider | partitore di tensione | Not *divisore*, which is arithmetic | +| constant current source (CCS) | generatore di corrente costante | Keep `(CCS)` on first mention; the silkscreen label `CCS` stays as printed. *Sorgente di corrente* is a calque; Italian circuit theory says `generatore` | +| excitation voltage | tensione di eccitazione | | +| passive voltage measurement | misura passiva di tensione | The mode used when a gauge is already in the circuit | +| active resistance measurement | misura attiva di resistenza | The mode that needs the CCS jumper | +| pull-up resistor | resistenza di pull-up | `pull-up` stays English and invariable, per rule 6. Never *resistenza di richiamo* | +| pull-down resistor | resistenza di pull-down | | +| to pull high / to pull low | portare a livello alto / portare a livello basso | The verb behind the two rows above. *Tirare* is wrong in this sense | +| threshold voltage | tensione di soglia | | +| hysteresis | isteresi | Feminine: `un'isteresi di circa 0,7 V` | +| floating (input) | flottante | `l'ingresso resta flottante`. Not *fluttuante*, which means oscillating | +| normally open / normally closed | normalmente aperto / normalmente chiuso | The established Italian switch terms, abbreviated `NA` / `NC` in schematics. Never a literal *aperto di norma*. Gloss `(NA)` / `(NC)` on first mention, because that is what the reader will find printed on the switch | +| self-resetting fuse | fusibile autoripristinante | The 500 mA PTC on the NMEA 2000 input | +| reverse polarity protection | protezione contro l'inversione di polarità | | +| overvoltage protection | protezione contro le sovratensioni | Builds on the shared `overcurrent → sovracorrente` | +| switching power supply | alimentatore switching | The **unit** — so `alimentatore`, per the shared row's note, not `alimentazione`. *Switching* stays English and invariable | +| current consumption | assorbimento di corrente | `assorbimento tipico di 90 mA a 12 V`. One form only; *consumo di corrente* is understandable but not what Italian datasheets write | +| short circuit | cortocircuito | Identical to the shared row. Repeated because HALMET's use is a chafed wire shorting an input, not a fault inside the power supply | +| chafing (of a wire) | sfregamento | `cortocircuiti dovuti a sfregamento`. Not *abrasione*, which describes the surface damage rather than the cause | +| flash (memory) | memoria flash | **Homonym trap.** The shared rows give `flash (firmware) → flashare`; *16 MB flash* is storage and must never become a verb. `16 MB di memoria flash` | + +### Board features and assembly + +| English | Italian | Note | +|:--------|:--------|:-----| +| jumper | jumper | Identical to the shared row: masculine, invariable, `il jumper` / `i jumper`. The **removable** link placed on a pin pair — see the note below | +| jumper header | connettore a pettine per jumper | Built from the shared `header → connettore a pettine`. Short form after first mention: `pettine CCS`, `contatti del jumper`. The source's *placing a jumper header on the pin pair* is loose English: what is placed is the jumper, and the Italian says so | +| solder jumper | jumper a saldare | **Inherited from the HALPI2 page translations** (see the table at the end of this file). Closed permanently with solder, not with a removable jumper — see the note below | +| to short (a jumper) | cortocircuitare | `cortocircuitare i contatti`. For the solder kind the natural verb is `chiudere`: `chiudere il jumper a saldare con una goccia di stagno`. *Ponticellare* is not used here, so that `ponticello` cannot creep in as a rival for `jumper` | +| solder pad | piazzola di saldatura | Short form `piazzola`, feminine. Distinct from `impronta` (component footprint), inherited from HALPI2 | +| unpopulated | non montato | `connettore non montato`, `piazzole libere` for *unpopulated pads* — pads with nothing soldered to them, not empty holes | +| pitch (2.54 mm) | passo | Identical to the shared row: `passo 2,54 mm`, `passo 3,81 mm` | +| pluggable terminal block | morsettiera estraibile | The Phoenix MC 3.81 type. The shared `terminal block → morsettiera` still holds for the block in general | +| silkscreen | serigrafia | Inherited from the HALPI2 page translations. The *labels* printed in it stay English | +| to solder | saldare | The metal is `stagno`, the joint `saldatura` | +| soldering iron | saldatore | Not *ferro da saldatura* | +| grommet (rubber, silicone) | passacavo in gomma | `passacavo` is inherited from HALPI2 precisely so it does not collide with `pressacavo` (cable gland). The two differ by one letter and appear in the same paragraph here — check every occurrence against the English | +| step drill bit | punta a gradini | The one that looks like a small metal Christmas tree | +| conical drill bit | punta conica | | +| panel connector | connettore da pannello | Not *connettore a pannello* | +| reset button | pulsante Reset | The board's own labels `Reset` and `Boot` stay English and capitalised, as printed | +| boot button | pulsante Boot | Also *boot-mode/general-purpose button*: `pulsante Boot / pulsante generico` | +| bootloader | bootloader | Masculine, invariable. The shared `boot → avvio` covers the act; the loader keeps its English name | +| download mode | modalità download | ESP32 flashing mode. `download` stays English; *modalità di scaricamento* names a browser action | +| user-programmable LED | LED programmabile dall'utente | `i LED`, never `i LEDs` | +| open hardware | hardware aperto | `HALMET è hardware aperto, distribuito con licenza Creative Commons…`. The licence name is never translated | + +### `jumper` and `jumper a saldare` are two different things + +This is the pair most likely to send the reader after the wrong tool, so it is +worth stating flatly: + +- **`jumper`** — the removable plastic-bodied link placed across a pin pair. On + HALMET this is the CCS jumper. It is fitted and pulled off by hand: + `inserire il jumper sui contatti CCS`. +- **`jumper a saldare`** — two pads on the bottom of the PCB, closed with a + soldering iron. On HALMET these are the CAN terminator, LP, pull-up, pull-down + and ADS1115 address jumpers: `chiudere il jumper a saldare LP`. + +Never write `jumper` alone for the soldered kind, and never say `inserire` or +`rimuovere` about one. A reader who confuses them either reaches for a soldering +iron they do not need, or waits to pull off something that is soldered down. +Count them against the English before calling a page done — the check is in +[Verification](#verification). + +### `normalmente aperto` / `normalmente chiuso` + +Established terms, not descriptions. Italian technical writing and Italian switch +datasheets use `normalmente aperto (NA)` and `normalmente chiuso (NC)`; the +abbreviations are what the reader will find on the component. Do not invent +`aperto a riposo`, `di norma aperto` or a relative clause. The `usage/index.md` +passage where the treatment reverses for normally closed switches is the one +place a loose rendering would actually mislead — the reader has to know which of +the two resistors to enable. + +### A note on `connettore` + +The shared glossary renders `connector` as `connettore` and `header` as +`connettore a pettine`, and that is kept. HALMET puts the two side by side more +often than HALPI2 does — *1-Wire header connector*, *analog input connectors* — +so let the qualifier carry the distinction (`connettore 1-Wire`, `connettori +degli ingressi analogici`) rather than inventing a second word. Where a sentence +would otherwise be ambiguous, say what the thing is: `pettine di contatti` for a +bare pin strip, `morsettiera estraibile` for the pluggable block. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py it` passes. `it` is already in the + `GLOSSARIES` dict in this repository and maps to `italian-glossary.md`, so + this needs no setup — unlike on the HALPI2 branch, where registering it was a + prerequisite. +5. `uv run python scripts/check_typography.py it` passes. It enforces rules 2, + 3 and 4 mechanically: the `“…”` pair, no space before `; : ! ?`, and no + junction hyphen between a product name and an Italian word (`it` is in + `JUNCTION_FORBIDDEN`). The remaining rules are counted by hand, below. +6. Structure matches the source — see `.claude/skills/translate-page/SKILL.md`. +7. Every term used on the page that appears in this glossary matches it. + +8. **The six rules at the top are counted against the pages, not re-read.** A + half-applied typography rule looks followed when you read it, because + rereading your own text confirms whatever it already says. Both the French and + German branches shipped one to review for that reason. Run these; every one + must print `0`, and the two quote counts must be equal. + + ```bash + # Rule 1 — address form: no tu, no Lei, no second person plural + grep -rEoi '\b(tu|tuo|tuoi|tua|tue|puoi|devi|potrai|dovrai|potete|dovete|vostro|vostra|vostri|vostre)\b' docs/it | wc -l + grep -rEo '\b(Lei|Suo|Sua|Suoi|Sue)\b' docs/it | wc -l + + # Rule 2 — quotation marks: these two must be EQUAL and non-zero + grep -rFo '“' docs/it | wc -l + grep -rFo '”' docs/it | wc -l + # and these must be 0 + grep -rEo '[«»]' docs/it | wc -l + grep -rEo '(„|‟)' docs/it | wc -l + + # Rule 3 — no space (ordinary or no-break) before ; : ! ? + grep -rEn '( |\xc2\xa0)[;:!?]' docs/it | wc -l + + # Rule 4 — no product name hyphenated into an Italian compound + grep -rEn 'NMEA-2000|Signal K-|SensESP-[a-zàèéìòù]|HALMET-[a-zàèéìòù]|ESP32-[a-zàèéìòù]|I2C-[a-zàèéìòù]|1-Wire-[a-zàèéìòù]|Phoenix-' docs/it | wc -l + # ESP32-WROOM-32E, 1-Wire and Phoenix MC 3.81 are names with their own + # hyphens; the pattern above only fires on a lower-case word after the + # hyphen, which is what rule 4 forbids. Two known false positives are the + # repository names HALMET-example-firmware and HALMET-hardware inside link + # targets — check the line, do not blindly demand 0. + + # Rule 5 — apostrophes and accents + grep -rFo "'" docs/it | wc -l # straight U+0027: must be 0 + grep -rEon "qual'è" docs/it | wc -l + grep -rEoni '\b(perchè|poichè|benchè|affinchè|nè|sè)\b' docs/it | wc -l + + # Rule 6 — no English plural -s on a loanword + grep -rEoi '\b(jumpers|LEDs|pins|firmwares|bootloaders|transceivers|containers|headers|senders|drivers)\b' docs/it | wc -l + ``` + + Exclude code fences before counting rules 2, 3 and 5, since inline code and + command output legitimately contain straight quotes, apostrophes and colons: + + ```bash + python3 - <<'PY' + import re, pathlib + text = "\n".join( + re.sub(r'`[^`\n]*`', ' ', re.sub(r'```.*?```', ' ', p.read_text(encoding='utf-8'), flags=re.S)) + for p in sorted(pathlib.Path('docs/it').rglob('*.md')) + ) + checks = { + 'straight apostrophe': text.count("'"), + 'straight quote': text.count('"'), + 'guillemets': len(re.findall(r'[«»]', text)), + 'space before ;:!?': len(re.findall(r'[  ][;:!?]', text)), + 'open quotes': text.count('“'), + 'close quotes': text.count('”'), + 'tu/Lei forms': len(re.findall(r'\b(tu|tuo|tuoi|tua|tue|puoi|devi|Lei|Suo|Sua|potete|dovete|vostr\w+)\b', text)), + } + for k, v in checks.items(): + print(f'{v:6} {k}') + print('quotes pair' if checks['open quotes'] == checks['close quotes'] else 'QUOTES DO NOT PAIR') + PY + ``` + +9. **The two-sense terms are counted separately.** On HALMET the dangerous pairs + are different from HALPI2's, because the corpus is different. Compare the + counts page by page against the English source; a mismatch is a defect, not a + style question. + + - `jumper` (removable) versus `jumper a saldare` (soldered). Every English + *solder jumper* must have `a saldare` after it in the Italian, and the bare + `jumper` count must equal the English bare *jumper* count. + - `pressacavo` (cable gland) versus `passacavo` (grommet). One letter apart, + and `getting-started/index.md` uses both in the same paragraph. + - `sonda` (sender) versus `sensore` (sensor). + - `memoria flash` (storage) versus `flashare` (writing firmware). The Italian + pages must contain **no** `flashare` unless the English says *flash the + firmware*, which as of this writing it never does. + - `normalmente aperto` / `normalmente chiuso` must appear exactly as often as + the English *normally open* / *normally closed*, and never swapped — the + `usage/index.md` passage reverses the pull-up/pull-down advice between them. + + ```bash + for t in 'solder jumper' jumper 'cable gland' grommet sender sensor flash \ + 'normally open' 'normally closed'; do + printf '%-18s en=%s\n' "$t" "$(grep -rio "$t" docs/en | wc -l)"; done + for t in 'jumper a saldare' jumper pressacavo passacavo sonda sensor \ + 'memoria flash' flashar 'normalmente apert' 'normalmente chius'; do + printf '%-18s it=%s\n' "$t" "$(grep -rio "$t" docs/it | wc -l)"; done + ``` + +10. **Every numeral in the English page appears in the Italian page**, allowing + for the decimal comma. Diff the extracted number lists rather than skimming. + HALMET's pages are dense with them — `-32 V`, `+32 V`, `1,55 V`, `0,7 V`, + `160 Hz`, `2,3 kHz`, `10 mA`, `100 kΩ`, `320 Ω`, `860`, `500 mA`, `16 MB` — + and a wrong threshold voltage sends the reader to the wrong resistor. + +## Related + +- `finnish-glossary.md` — the sibling in this repository, adapted from HALPI2 + the same way and the model this file follows +- the HALPI2 repository's `solutions/translation/` — the French, German, + Swedish and Spanish siblings, and the original of this file +- `.claude/skills/translate-page/SKILL.md` — the procedure +- `../best-practices/` — the markdown traps that survive `--strict` + +## Terms added during translation + +**Inherited from the HALPI2 page translations.** Consolidated there rather than +written by each translator, because several agents shared the file. Rows are kept +here unchanged: most of them (`serigrafia`, `jumper a saldare`, `passacavo`, +`transceiver`, `punto di test`, `impronta`, `corrente di spunto`) describe parts +HALMET has too, and a term that recurs must not get a second Italian word in the +second manual. Rows about HALPI2-only things — CM5, HaLOS, Cockpit, the RP2040 +controller, the SSD — simply never fire on a HALMET page. **New terms found while +translating HALMET pages go in the `## HALMET terms` section above, not here.** + +| English | Translation | Note | +|:--------|:------------|:-----| +| Getting Started (page/guide title) | Primi passi | H1 of the page and the link text to the HaLOS equivalent guide. Standard Italian documentation title; 'Per iniziare' is the alternative but reads less | +| Step (numbered procedure heading) | Passaggio | Used in 5 headings (Step 0-3). Needed a fixed choice so headings do not alternate between 'Passaggio', 'Fase' and 'Punto'. 'Fase' is reserved here for | +| wire (individual conductor: red wire / black wire) | conduttore | The glossary covers 'wire gauge' and 'marine-grade wire' but not the countable conductor. 'Conduttore' distinguishes the individual red/black lead fro | +| terminals (crimp-on ring/spade terminals) | capicorda | Distinct from 'morsettiera' (terminal block), which the glossary already fixes. 'Capicorda' is the standard Italian term for crimped cable-end termina | +| cable grommet | passacavo | Appears alongside 'cable gland' (pressacavo, in glossary) in the same sentence; needed a different word so the pair does not collapse into one term. | +| mounting hardware (corrosion-resistant) | minuteria di fissaggio | Standard Italian for screws/washers/brackets as a class; a literal 'hardware di montaggio' would clash with 'hardware' used for electronics elsewhere | +| mounting clips | clip di fissaggio | Listed with cable ties in the materials list; kept parallel to 'minuteria di fissaggio'. | +| splash screen | schermata iniziale | Raspberry Pi OS boot screen. Established Italian rendering; the English term is not used in Italian consumer documentation. | +| controller (the RP2040 the HALPI daemon connects to) | controller | SUPERSEDED: this row first said 'controllore'. Resolved to 'controller' — see the 'controller (any controller IC)' row below. | +| rainbow pattern (LED) | sequenza arcobaleno | LED fault indication. Matched to 'sequenze dei LED di stato' used for 'status LED patterns' so the two references agree. | +| known-good device | dispositivo sicuramente funzionante | No idiomatic Italian noun phrase exists; a descriptive rendering is the usual solution in Italian technical manuals. | +| electrical codes | normative elettriche | Used three times (local electrical codes / comply with local electrical codes). 'Normative' rather than 'codici' — 'codice elettrico' is a calque that | +| Automotive Installations | Installazioni su veicoli | Heading parallel to 'Installazioni nautiche' and 'Installazioni industriali'; 'automobilistiche' would wrongly exclude commercial vehicles. | +| service loop (verb phrase 'allow/provide service loops') | prevedere una riserva di cavo | Glossary gives the noun 'riserva di cavo' and requires glossing '(service loop)' on first mention; recorded here as the verb collocation actually used | +| UART | UART (feminine: la UART, le UART) | The glossary lists no gender for UART and warns against guessing articles for bare acronyms. Feminine is the prevailing Italian usage (implicitly 'por | +| device tree overlay | overlay | Kept in English, masculine and invariable, matching the glossary's treatment of jumper/HAT/container. It is the literal name of the config.txt mechani | +| transceiver (RS-485) | transceiver | Kept in English, masculine. 'ricetrasmettitore' exists but is not what Italian electronics documentation calls an RS-485 line driver IC. Invariable pe | +| chip select | chip select | A signal name on the CAN FD controller, not prose. Left in English like the silkscreen labels; used in the conflicts table as 'Chip select del CAN FD' | +| SPI bus / I2C bus | bus SPI / bus I2C | Follows rule 4 (name as plain apposition after the noun), consistent with the glossary's 'bus NMEA 2000'. No hyphen. | +| mass-storage gadget | gadget di archiviazione di massa | Linux USB gadget terminology; 'gadget' has no Italian equivalent in this sense and is kept, with the rest translated. 'mass storage device' likewise b | +| block device | dispositivo a blocchi | Standard Italian Linux usage; not in the glossary. | +| boot mode switch | selettore della modalità di avvio | Built from the glossary's 'boot -> avvio'. The switch positions themselves stay English and quoted: “Normal”, “Abnormal”. | +| login console | console di accesso | The dedicated debug UART in interfaces.md. 'console' is feminine and invariable in Italian. | +| REST API | API REST | Italian inverts the order and treats API as feminine (l'API REST, un'interfaccia API REST). Appears in the heading 'Accesso all'API REST'. | +| port forwarding | port forwarding | Kept in English; the Italian calque 'inoltro delle porte' is not what router UIs or Italian network documentation use. | +| Hardware Guide (page title) | Guida all'hardware | Cross-reference target in software.md. Matches the pattern already established in docs/it: 'Guida introduttiva', 'Guida al software', 'Guida utente'. | +| hardware flow control | controllo di flusso hardware | Standard Italian term; not in the glossary. | +| device node | nodo di dispositivo | Used in the interfaces.md verification section for the /dev/ttyAMA* entry. | +| header pins (table column) | Pin del connettore | Derived from the glossary's 'header -> connettore a pettine' and 'pin -> pin' (invariable). Shortened for the table column head. | +| taskbar | barra delle applicazioni | Standard Italian desktop terminology, used in the Graphical Updates section. | +| update manager | gestore degli aggiornamenti | Descriptive, not a UI string the reader will see in English on this screen (the source does not capitalise it). | +| pre-built images | immagini precompilate | Distinct from the glossary's 'system image -> immagine di sistema'; describes how Hat Labs ships them. | +| solder jumper | jumper a saldare | The glossary fixes "jumper" as invariable but has no entry for the solder-bridge variant (GPIO6-CAN.CS). "Jumper a saldare" keeps the glossary's loanw | +| backup power | alimentazione di riserva | The glossary has "backup battery = batteria tampone" but nothing for the super-capacitor-fed supply. "Batteria tampone" is wrong here (there is no bat | +| mainboard | scheda principale del computer | Appears once, describing what the carrier board is. The glossary forbids "scheda madre" because it names the wrong board and inverts the CM5 relations | +| voltage bar (LED pattern) | barra di tensione | LED pattern name in the status table, used five times. No glossary entry; "barra" is the usual Italian word for a bar-graph indicator and keeps the ta | +| power-loss detection | rilevamento della mancanza di alimentazione | Built from the glossary's "power loss = mancanza di alimentazione"; recorded so the compound is spelled the same way on other pages rather than drifti | +| silk screen | serigrafia | Used for the printed markings on the board (Contacts arrows, module outline). The glossary covers silkscreen *labels* staying English but not the surf | +| die-cast, powder-coated (enclosure) | pressofuso, verniciato a polvere | Enclosure manufacturing terms in the opening paragraph; both are the standard Italian industrial terms and neither is in the enclosure section of the | +| spudger | spudger | Tool name in the CM5 removal procedure with no Italian equivalent in common use; kept as in the source alongside the translated alternatives (plettro | +| single-sided / double-sided (SSD) | a singola faccia / a doppia faccia | M.2 form-factor description in the SSD compatibility section; the standard Italian phrasing, recorded so the two halves of the contrast stay parallel. | +| grace period (before automatic restart) | periodo di attesa | "5-second grace period" in the automatic-restart section. "Periodo di grazia" is a calque; "periodo di attesa" is what Italian technical prose uses fo | +| carrier board controller | controller della scheda portante | The glossary fixes 'carrier board' but never says how 'controller' itself is handled. Kept in English, masculine and invariable (il controller / i con | +| supercapacitor backup | riserva a supercondensatori | The glossary gives 'super-capacitor -> supercondensatore' and 'backup battery -> batteria tampone', but not the compound used as a section heading and | +| kbps / Mbps / bps | kbit/s / Mbit/s / bit/s | The units section prescribes '250 kbit/s' in the no-thousands-separator example but never states the rule generally. Applied uniformly (250 kbit/s, 8 | +| transceiver | transceiver | SUPERSEDED: this row first said 'ricetrasmettitore', contradicting the 'transceiver (RS-485)' row above. Resolved to 'transceiver' — see the 'transceiver (RS-485 line driver)' row below. | +| isolated ground / galvanically isolated | massa isolata / isolato galvanicamente | The glossary gives 'grounding -> messa a terra', which is the protective-earth sense and wrong for GND_CAN and GND_RS485, a floating reference. 'Massa | +| ferrite bead | perlina di ferrite | Component name in the USB section, not in the glossary. 'Perlina di ferrite' is the usual Italian catalogue term. | +| threaded insert / solder nut | inserto filettato / dado da saldare | Mounting section fasteners; the glossary covers standoff and countersunk screw but not these two. | +| powder-coated die-cast aluminium | alluminio pressofuso verniciato a polvere | Enclosure material, appears twice (summary table and mechanical table). Fixed once here so the two tables cannot disagree. | +| depth sounder / wind instrument | ecoscandaglio / strumento del vento | Marine instrument names in the RS-485 'Common Applications' section. 'Ecoscandaglio' is the standard Italian term; 'strumento del vento' matches the u | +| use case | caso d'uso | Page title of use-cases.md; standard Italian software-engineering rendering, written with the typographic apostrophe (caso d’uso). | +| buck converter / overvoltage disconnect | convertitore buck / disconnessione per sovratensione | Power-supply table entries. 'Buck' is kept as the trade term (as the glossary does for jumper/watchdog); the glossary has 'overcurrent -> sovracorrent | +| controller (the RP2040 board controller) | controller | Not in the glossary. I first wrote 'controllore', then aligned to 'controller' because the parallel Italian page docs/it/technical-reference/hardware. | +| mounting ledge | sporgenza di appoggio | errata.md. The cast ledge inside the enclosure that the PCB rests on. Distinct from 'punto di fissaggio' (mounting point) used in design-files.md for | +| flash (casting defect) | bava | errata.md. Homonym trap: this is the casting sense of 'flash', nothing to do with 'flashare il firmware'. Quoted in the source as "flashes", so it app | +| inrush current | corrente di spunto | errata.md. Standard Italian electrotechnical term; 'corrente di avviamento' would read as motor jargon. | +| copper fill / copper pour | riempimento di rame | errata.md and design-files.md. The source uses both 'copper fill' and 'copper pours' for the same thing; both rendered identically. | +| solder nut | dado da saldare | design-files.md changelog. | +| test point | punto di test | design-files.md changelog. | +| buck converter | convertitore buck | design-files.md. 'convertitore step-down' also exists but 'buck' is what Italian datasheets use. | +| opamp | amplificatore operazionale | design-files.md. Spelled out; 'opamp' is not used in Italian running prose. | +| footprint (component) | impronta | design-files.md. PCB land pattern sense. | +| silkscreen | serigrafia | design-files.md. Distinct from the silkscreen *labels* themselves, which stay English per the glossary. | +| brownout | abbassamento di tensione | power-supply.md. Kept distinct from 'caduta di tensione' (voltage drop, already in the glossary) and from 'interruzione di corrente' (blackout). | +| cross-compilation | compilazione incrociata | integration.md. | +| thermal throttling | limitazione termica delle prestazioni | troubleshooting.md. Kept clear of 'limitazione di corrente' (current limiting) which is the glossary term for a different mechanism. | +| stray voltage | tensione parassita | troubleshooting.md. | +| gigabit ethernet | ethernet gigabit | index.md. Noun-first Italian order; no hyphen, per rule 4. | +| errata | errata corrige | errata.md page title. The standard Italian term. Note this changes the slug to 'errata-corrige'. | +| security hardening | rafforzamento della sicurezza | advanced-config.md. | +| cable plug (E7T cable plug) | spina volante | index.md. The free-hanging mating plug supplied loose, as opposed to the panel receptacle ('presa' in the glossary). | +| goodie bag | busta accessori | index.md image alt text. | +| controller (any controller IC: board controller, CAN FD controller, RP1 I/O controller, system controller) | controller | Rival-term resolution. Three earlier rows disagreed ('controllore' vs 'controller'). One rendering for all of them: `controller`, masculine and invariable (il controller / i controller), like jumper and watchdog. Italian electronics documentation says `controller CAN`, not `controllore`; `controllore` reads as a human inspector. `microcontrollore` is a different English word (*microcontroller*) and keeps its Italian form. | +| transceiver (RS-485 line driver) | transceiver | Rival-term resolution. Two earlier rows disagreed. `transceiver`, masculine and invariable. `ricetrasmettitore` is the Italian for a *radio* transceiver, which on a boat means the VHF set — actively misleading in this corpus. | +| LED pattern (table column and prose) | sequenza dei LED | Rival-term resolution. `Schema dei LED` appeared once as a table header against `Sequenza dei LED` elsewhere. `sequenza` is already fixed by the 'rainbow pattern' row; it now covers every use of *LED pattern*. | +| current limit switch | limitatore di corrente | Rival-term resolution. The main glossary already says the switch itself is `limitatore di corrente`, but the pages also called it `interruttore` and `selettore del limite di corrente`. One name only; refer back to it with a pronoun rather than a second noun. `interruttore` is reserved for circuit breakers and panel switches, `selettore` for the boot mode switch. | +| community | comunità | Rival-term resolution. The pages had both `community` and `comunità`. `comunità` matches the impersonal manual register of rule 1, and the sibling list labels around it are translated (`**Assistenza:**`), so `**Community:**` could not stay English. | +| support (help from Hat Labs or the community) | assistenza | Rival-term resolution. Distinct from `supporto`, which stays for the capability sense — *external antenna support* is `supporto per antenne esterne`, *HALPI2 support* is `supporto per HALPI2`. | diff --git a/solutions/translation/norwegian-glossary.md b/solutions/translation/norwegian-glossary.md new file mode 100644 index 0000000..a5d4bed --- /dev/null +++ b/solutions/translation/norwegian-glossary.md @@ -0,0 +1,681 @@ +--- +title: Norwegian Bokmål translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Norwegian Bokmål under docs/nb/ + - Reviewing a Norwegian Bokmål translation for consistency + - Adding a new term that has no established Norwegian Bokmål equivalent +tags: + - translation + - i18n + - norwegian + - bokmal + - terminology + - mkdocs-static-i18n +--- + +# Norwegian Bokmål translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Norwegian Bokmål under `docs/nb/`, using the `mkdocs-static-i18n` folder +structure. Each language directory mirrors the same tree, so a translation keeps +its source's path and filename: `docs/en/hardware/index.md` becomes +`docs/nb/hardware/index.md`. Only markdown lives under `docs/nb/`; images and +other assets stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with two +different Norwegian Bokmål words. `carrier board` → `bærekort` is the HALPI2 call +and stands here too, even though HALMET is not a carrier board and the term will +mostly appear in comparisons. Terms below the `## HALMET terms` heading are +additions this product needed; everything above it is shared with HALPI2, and a +change to a shared row must be made in both repositories or in neither. + +`finnish-glossary.md`, `french-glossary.md`, `german-glossary.md`, +`swedish-glossary.md`, `spanish-glossary.md` and `italian-glossary.md` are the +siblings of this file in this repository; `check_glossary.py` also reserves +`da` and `nl`, so a Danish and a Dutch sibling may appear. The general approach +is the same in all of them, and Danish is the one to watch — see the next +section. + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `loddebro` on one page and `loddejumper` +on the next — and the result reads as machine output even when each individual +sentence is correct. This file is the reference that prevents that drift. It is +a living document: extend it when a page introduces a term that is not listed +here, rather than inventing a one-off translation. + +Unlike the other files under `solutions/`, this one has no date in its filename +because it is meant to be edited in place, not superseded. + +## Six rules where the siblings are wrong for Norwegian Bokmål + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary. Danish is the dangerous +neighbour: it is close enough to read as correct and is being written against +the same English source, so a Danish habit that slips in will not look wrong to +anyone who is not counting. + +1. **Quotation marks are `«…»`, pointing inward.** Norwegian opens with `«` and + closes with `»`. **Danish is the exact opposite** — Danish opens with `»` and + closes with `«`. Not Swedish's `”…”`, not German's `„…“`, not straight + `"…"`. And unlike French, **no space inside the guillemets**: write + `«Abnormal»`, never `« Abnormal »`. + +2. **Address the reader as `du`.** Norwegian technical and consumer + documentation uses `du`. French uses *vouvoiement* and German uses *Sie* — + both wrong here. `Koble til strømkabelen.` / `Kontroller polariteten med + multimeteret før du slår på spenningen.` The formal `De`/`Dem`/`Deres` must + not appear at all. + +3. **No space before `; : ! ?`** — as in German and Swedish, and unlike French, + whose rule is the exact opposite and demands a no-break space. + +4. **Compounds are written solid, as one word.** `strømforsyning`, + `kabelgjennomføring`, `bærekort`, `spenningsfall`, `nedstenging`. Splitting a + compound in two (*særskriving*, `strøm forsyning`) is the single most visible + error in written Norwegian and is what English word order invites. English + `power supply` is two words; Norwegian is one. + +5. **Compounding with a proper name takes one hyphen at the junction, not + throughout.** Norwegian writes `NMEA 2000-nettverk`, `Signal K-server`, + `HALMET-kabinett`, `ESP32-modulen`. German writes + `NMEA-2000-Netzwerk` — hyphens all the way through. Copying the German + pattern is wrong, and copying English spacing (`NMEA 2000 nettverk`) is also + wrong. + +6. **Norwegian spelling, not Danish.** The pairs below are the ones this corpus + actually produces. Left is Norwegian and required; right is Danish and must + not appear. + + | Norwegian Bokmål | Danish — never write this | + |:-----------------|:--------------------------| + | konfigurasjon, installasjon, informasjon, funksjon, terminering | konfiguration, installation, information, funktion | + | å koble til (infinitive marker `å`) | at tilslutte (infinitive marker `at`) | + | bare | kun | + | nå | nu | + | noen | nogen | + | mye | meget | + | enn | end | + | etter | efter | + | sette, hjelp, endre | sætte, hjælp, ændre | + | sjekk | tjek | + | forbindelsene, kablene (definite plural `-ene`) | forbindelserne, kablerne (`-erne`) | + | bærekort | bæreprint | + + `kun` is not ungrammatical in Bokmål, but it is the Danish default. Banning + it here costs nothing and makes a leak from the Danish branch visible in one + `grep`. + +## Names that are never translated + +Product names, protocol names, hardware standards and software UI strings stay +in English — the device's own interface is in English, so translating a menu +name would send the reader looking for something that does not exist on screen. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs. HALPI2 and HaLOS keep + their names too, on the pages that mention them. +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, + I2C, 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, + Schmitt trigger. +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`. These are printed on the board; a translated pin name sends the reader + looking for a label that does not exist. The same holds for `DI1`–`DI4`, + `GPIO4`, `GPIO21`, `Reset` and `Boot` as printed labels — the buttons are + `Reset`-knappen and `Boot`-knappen when the label itself is meant. + +**Commands, file paths, configuration keys and code stay in English**, verbatim: +`main.cpp`, `ConnectAlarmSender()`, `can0`, `halos.local`, +`HALMET-example-firmware`. Code fences, command output, URLs and image +filenames are never touched. + +`CAN bus` is a name here, but Norwegian compounds it like any other: the bus +itself is `CAN-bussen`, and `NMEA 2000-nettverket` follows rule 5. + +## Units and numbers + +Same handling as the other languages — the English source writes `12V` and +`0.9A`, and both are wrong in Norwegian. + +| English source | Norwegian Bokmål | +|:---------------|:-----------------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | +| `200×130×60 mm` | `200 × 130 × 60 mm` | +| `2m`, `45mm`, `2kg` | `2 m`, `45 mm`, `2 kg` | + +**Do not insert a thousands separator.** `115200 bps` and `9600` stay exactly as +in the source. Norwegian typography would allow a no-break space, but the +verification step compares every number in the English text against the +translation, and `115 200` no longer matches `115200`. Digits are copied, not +reformatted — only the decimal separator and the unit spacing change. + +Decimal comma everywhere in prose, decimal point never — except inside inline +code and version numbers, which are copied verbatim (`v0.5.0`, `M4x10`, `PH2`). + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry an `en/`, `nb/` or other language segment; image +captions and alt texts are translated but filenames are not; screenshots stay +English because the reader's own screen is English; standard admonition titles +are translated centrally in `mkdocs.yml`, custom ones in the page. + +Admonition titles used centrally: `note` → Merk, `warning` → Advarsel, `tip` → +Tips, `info` → Informasjon, `danger` → Fare, `example` → Eksempel. + +Navigation titles live in `mkdocs.yml` under the i18n plugin's +`nav_translations`, which is their single source of truth; the list is not +restated here. Two entries are judgement calls worth recording: + +- `Errata` → **Kjente feil**, carried unchanged from HALPI2. The Latin word is + opaque to a general reader, and the page lists known hardware defects, not + corrections to be made. +- `Hardware Revisions` → **Maskinvareversjoner**, not *revisjoner*. Norwegian + *revisjon* reads as an audit; the page is about board versions. + +When a page is added to the nav in English, add its Norwegian title in the same +change — an untranslated entry falls back to English silently. + +## Glossary + +### Enclosure, mounting, and installation + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| carrier board | bærekort | The accurate term, as in Swedish, French and German — see the note below | +| enclosure | kabinett | Not *hus*; *kabinett* is what an electronics box is called | +| lid | lokk | | +| gasket | pakning | | +| heat sink | kjøleribbe | | +| waterproof | vanntett | | +| wall-mount | veggmontering | | +| mounting surface | monteringsflate | | +| pilot hole (to drill) | forbore (verb) | `Forbor hullene for monteringsskruene` — an action the reader performs | +| pre-drilled hole (already there) | ferdigboret hull | The holes the enclosure ships with. Never write `forbor de ferdigborede hullene` — that is the nonsense the Swedish branch shipped | +| mounting template | boremal | | +| bilge water | lensevann | As in *lensepumpe*; not *bunnvann* | +| bulkhead | skott | | +| cable gland | kabelgjennomføring | The PG7 parts specifically may be called `kabelnippel` when the physical part is meant | +| cable routing | kabelføring | | +| service loop | servicesløyfe | Slack left at both cable ends | +| cable tie | kabelstrips | | +| blind plug | blindplugg | | +| breather plug | trykkutjevningsplugg | | +| standoff | avstandsbolt | | +| threaded insert | gjengeinnsats | | +| thermal pad | varmeledende pute | | +| spudger | plastspade | Non-conductive prying tool | + +**A note on `bærekort`.** Norwegian takes the accurate term, like Swedish +(`bärkort`), French (`carte porteuse`) and German (`Trägerplatine`), and unlike +Finnish (`emolevy`, literally *motherboard*, chosen there for reader +familiarity). The divergence between the languages is deliberate, decided per +language and per audience. Do not harmonise them. + +`bærekort` carries the CM5/board relationship on its own, so passages about +reseating the CM5 or troubleshooting a board that will not boot need no extra +explanation. Only the Finnish glossary needs that warning. + +Danish would form this as `bæreprint` (Danish uses *print* for a circuit board). +Norwegian does not: the Norwegian word for a circuit board is `kretskort`, so +the compound is `bærekort`. + +### Power and electrical + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| power supply | strømforsyning | The external unit itself: *strømadapter* | +| input voltage range | inngangsspenningsområde | | +| polarity | polaritet | | +| fuse | sikring | | +| inline fuse | linjesikring | | +| circuit breaker | automatsikring | The panel breaker on the boat's electrical panel | +| current limiting | strømbegrensning | `strømbegrensningsbryter` for the switch | +| overcurrent | overstrøm | | +| voltage drop | spenningsfall | | +| grounding | jording | | +| short circuit | kortslutning | | +| wire gauge | ledertverrsnitt | Norwegian uses mm², not AWG | +| marine-grade wire | kabel av marin kvalitet | | +| wire strippers | avisoleringstang | | +| crimping | krimping | See the note below — *not* `krymping` | +| crimper | krimptang | | +| heat-shrink tubing | krympestrømpe | | +| heat gun | varmepistol | | +| multimeter | multimeter | | +| terminal block | koblingsklemme | In this documentation always the pluggable screw terminal on the carrier board, not a DIN-rail *rekkeklemme* | +| strain relief | strekkavlastning | | +| super-capacitor | superkondensator | | +| real-time clock | sanntidsklokke | | +| backup battery | reservebatteri | The CR2032 for the RTC | +| backup power | reservestrøm | What the super-capacitors deliver | +| voltage rail | spenningsskinne | `3,3 V-skinnen`, `5 V-skinnen` | + +**A note on `krimping` versus `krymping`.** Norwegian trade usage says both, and +that is exactly the problem: `krympe` also means *to shrink*, and this +documentation talks about heat-shrink tubing (`krympestrømpe`) two lines from +where it talks about crimping terminals. `krimping`/`krimptang` for the crimp +and `krymping`/`krympestrømpe` for the heat-shrink keeps the two apart on the +page. Do not "correct" one into the other. + +### Connectors and interfaces + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| connector | kontakt / tilkobling | *kontakt* for the physical part, *tilkobling* for the act of connecting | +| barrel connector | DC-plugg | First mention: `DC-plugg (barrel)` | +| header | pinneliste | `40-pinners GPIO-pinneliste` | +| pin | pinne | | +| pitch | senteravstand | `3,81 mm senteravstand` | +| backbone | backbone | Established in Norwegian NMEA 2000 usage | +| drop cable | stikkledning | Dealer catalogues also say *dropkabel*; this documentation uses *stikkledning* throughout | +| T-connector | T-kobling | The source also writes *T-adapter*; translate both as `T-kobling` | +| terminator (the component) | termineringsmotstand | The 120 Ω resistor and its jumper | +| termination (the state) | terminering | `Kontroller at nettverket er riktig terminert` | +| front panel | frontpanel | | +| jumper | jumper | The physical shunt; `loddebro` for a solder jumper | +| male / female | hann / hun | `hannkontakt`, `hunkontakt` | +| flexible flat cable (FFC) | flatkabel | Keep `(FFC)` on first mention | +| silk screen | silketrykk | | + +### Operation and system behaviour + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| boat computer | båtdatamaskin | | +| to boot | starte opp | | +| first boot | første oppstart | | +| shutdown | nedstenging | | +| graceful shutdown | kontrollert nedstenging | | +| to shut down | slå av / stenge ned | | +| power loss | strømbortfall | The event: input power disappears | +| blackout | strømbrudd | The interval the blackout timer measures: `strømbruddstimer` | +| power management | strømstyring | | +| status LED | status-LED | | +| monitoring | overvåking | Not the Swedish *övervakning* | +| passive cooling | passiv kjøling | | +| filesystem | filsystem | | +| to unmount (a filesystem) | avmontere | `filsystemene avmonteres trygt` | +| to unmount (hardware, remove a module) | demontere | Removing the CM5 or the carrier board is *demontering*, never *avmontering* | +| watchdog | watchdog | `watchdog-tidsavbrudd` | +| standby | ventemodus | The CM5 is off while the controller stays awake — not *hvilemodus*, which is sleep | +| power button | strømknapp | | +| reset button | resetknapp | | +| solo mode / co-op mode | solomodus / samspillsmodus | Keep the English in parentheses on first mention | + +### Software and networking + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| firmware | firmware | Not *fastvare* — matches the sibling decision to keep the trade term, and the package is named `halpi2-firmware` | +| daemon | daemon | `HALPI-daemonen`; not *tjeneste*, which is a systemd service | +| to flash | flashe | `flashe systembildet til SSD-en` | +| system image | systembilde | Also for *operating system image* | +| container image | containerbilde | | +| container app | containerapp | | +| headless | uten skjerm | First mention: `uten skjerm (headless)` | +| dashboard | dashbord | Homarr's dashboard view. The UI itself says *Dashboard* in English — keep that when naming the on-screen label | +| WiFi Access Point | WiFi-aksesspunkt | | +| wired / wireless | kablet / trådløs | | +| credentials | påloggingsinformasjon | | +| default password | standardpassord | | +| single sign-on (SSO) | enkel pålogging (SSO) | | +| Certificate Authority (CA) | sertifikatutsteder (CA) | | +| web interface | webgrensesnitt | | +| browser | nettleser | | +| to log in | logge på | | +| update | oppdatering | | +| device tree overlay | device tree-overlay | Keep the English term; it names a file the reader edits | + +### Applications and use cases + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| chart plotter | kartplotter | | +| data logging | datalogging | | +| vessel | fartøy | | +| fleet management | flåtestyring | | +| predictive maintenance | prediktivt vedlikehold | | +| remote monitoring | fjernovervåking | | +| compliance | samsvar | As in *samsvarserklæring* | +| warranty | garanti | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. Rows above +this heading are shared with HALPI2 and must not be changed here alone. + +### Board and inputs + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| development board | utviklingskort | HALMET is sold as one; not `bærekort`, which is HALPI2's carrier board | +| digital input | digital inngang | `D1`–`D4` stay as printed | +| analog input | analog inngang | `A1`–`A4` stay as printed | +| input | inngang | The terminal on the board; the signal arriving there is `inngangssignal`. Never *innmating* | +| output | utgang | | +| sender | giver | The marine sender a gauge reads: `nivågiver`, `temperaturgiver`. *sender* means a radio transmitter and is wrong here | +| tank sender | tankgiver | | +| resistive sender | resistiv giver | What it varies is `motstand` — see *active resistance measurement* | +| gauge (engine panel gauge) | måler | `måleren i motorpanelet`; the panel as a whole is `motorinstrumentene` | +| counter | teller | | +| chain counter | kjettingteller | Anchor chain is `ankerkjetting`, never *kjede* in this sense | +| alarm signal | alarmsignal | | +| engine RPM | motorens turtall | Not *RPM* in prose; the unit is `o/min` (omdreininger per minutt) | +| tachometer | turteller | The instrument. `turtall` is the quantity it shows | +| alternator W terminal | generatorens W-uttak | The alternator is `generatoren`, in full `vekselstrømsgeneratoren`. *dynamo* is widespread in Norwegian trade usage for the same part but names a DC machine — do not use it | +| fuel flow | drivstoffstrøm | `drivstoff`, never the Danish *brændstof* | +| engine panel | motorpanel | | +| bilge alarm | lensealarm | Formed on the shared `lensevann`, not *bunnvannsalarm* | +| microcontroller | mikrokontroller | The ESP32-WROOM-32E is a `modul`; the chip inside it is the `mikrokontrolleren` | + +### Measurement and circuits + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| galvanic isolation | galvanisk isolasjon | Not *galvanisk skille* — see the note below. Adjective: `galvanisk isolert` | +| isolated (section, area) | isolert | `isolert seksjon`, `isolert område`, `den isolerte siden` | +| digital isolator | digital isolator | The component that carries I2C and the four digital inputs across the barrier | +| isolation barrier | isolasjonsbarriere | Names the figure in `hardware/index.md` | +| ground loop | jordsløyfe | `uten fare for jordsløyfer` | +| analog-to-digital converter (ADC) | AD-omformer | Spelled out: `analog-digital-omformer`. The part name `ADS1115` stays. *konverter* is not used | +| resolution (16-bit) | oppløsning | `16 bits oppløsning` | +| sampling rate | samplingsfrekvens | `860 samplinger per sekund` | +| low-pass filter | lavpassfilter | The `LP` solder jumper keeps its printed label | +| cutoff frequency | grensefrekvens | *knekkfrekvens* also occurs in Norwegian; use `grensefrekvens` throughout | +| noise (electrical) | støy | `elektrisk støy` on first mention, because `støy` alone is also the ordinary word for sound. Interference coupled in from outside is `forstyrrelser` | +| noise immunity | støyimmunitet | What the Schmitt trigger improves. *støytoleranse* also occurs; pick one and keep it | +| voltage divider | spenningsdeler | The gauge and the sender together form one | +| constant current source (CCS) | konstantstrømkilde | One word. The header label `CCS` stays as printed | +| excitation voltage | matespenning | Write `matespenning til giveren`, so it is not read as the board's own `strømforsyning`. *eksitasjonsspenning* belongs to machines with field windings | +| passive voltage measurement | passiv spenningsmåling | | +| active resistance measurement | aktiv motstandsmåling | The measured quantity is `motstand` (`320 Ω`); `resistans` only where a sentence would otherwise confuse the quantity with the component | +| pull-up resistor | pull-up-motstand | The loan is kept and compounded — see the note below. Already fixed in the HALPI2 glossary's added-terms list; unchanged here | +| pull-down resistor | pull-down-motstand | | +| threshold voltage | terskelspenning | `terskelspenningen er om lag 1,55 V` | +| hysteresis | hysterese | Norwegian drops the `-is`: `en hysterese på omtrent 0,7 V` | +| floating (input) | flytende | `inngangen blir flytende` | +| normally open (NO) / normally closed (NC) | normalt åpen (NO) / normalt lukket (NC) | The established Norwegian pair — see the note below. Carried from the HALPI2 added-terms list, which already fixed `normalt åpen (NO)` | +| self-resetting fuse | selvtilbakestillende sikring | The 500 mA PTC on the NMEA 2000 input. Not *selvresettende* | +| reverse polarity protection | polvendingsvern | *polvendingsbeskyttelse* also occurs; `-vern` is chosen so it reads as a pair with `overspenningsvern` | +| overvoltage protection | overspenningsvern | | +| ESD protection | ESD-vern | Same `-vern` pattern; `ESD` is never translated | +| switching power supply | switchet strømforsyning | Trade spelling. Bokmål permits `svitsjet`, but no Norwegian datasheet writes it | +| current consumption | strømforbruk | Not *strømtrekk*, which is a momentary draw | +| short circuit | kortslutning | Already in the shared Power table with the same sense — repeated here only because HALMET's chafing warning turns on it | +| chafing (of a wire) | gnaging | `skade på grunn av gnaging`. *skuring* is about hulls, not cables | + +### Board features and assembly + +| English | Norwegian Bokmål | Note | +|:--------|:-----------------|:-----| +| jumper | jumper | Already in the shared Connectors table, same sense: the removable shunt pushed onto a pin pair. See *solder jumper* for the PCB kind | +| jumper header | jumperpinner | The pin pair a jumper is pushed onto. `pinneliste` is the shared word for a header in general; a single pair may be called `pinneparet` | +| solder jumper | loddebro | Inherited from the shared Connectors row. Closed permanently with a soldering iron — see the note below | +| to short (a jumper) | kortslutte | But prefer the verb that says which kind: `lodd sammen loddebroen` for the soldered ones, `sett en jumper over pinnene` for the removable ones | +| solder pad | loddeflate | The bare copper. `loddepunkt` is the finished joint and is not the same thing | +| unpopulated | ubestykket | `ubestykkede loddeflater`. A header the factory left off is `ikke montert` | +| pitch (2.54 mm) | senteravstand | Already in the shared Connectors table, same sense; repeated because nearly every HALMET connector is specified by it: `2,54 mm senteravstand`, `Phoenix MC 3,81` | +| pluggable terminal block | pluggbar koblingsklemme | Phoenix MC type; `koblingsklemme` alone is the shared HALPI2 term | +| silkscreen | silketrykk | Already in the shared Connectors table. The errata page's *back side silk screen* → `silketrykket på undersiden` | +| to solder | lodde | | +| soldering iron | loddebolt | The Norwegian tool word. Danish *loddekolbe* must not appear | +| grommet | gummigjennomføring | Carried from the HALPI2 added-terms list (*cable grommet*). Rubber or silicone; distinct from `kabelgjennomføring`, the threaded gland in the shared table | +| step drill bit | trinnbor | The one that looks like a small metal Christmas tree | +| conical drill bit | konisk bor | | +| panel connector | panelkontakt | The one mounted through the enclosure wall | +| reset button | resetknapp | Already in the shared Operation table. The printed label `Reset` stays English | +| boot button | boot-knapp | Hyphenated while `resetknapp` is solid — see the note below; do not "fix" either into the other | +| bootloader | bootloader | Kept in English, like `firmware`, `daemon` and `watchdog` in the shared tables. *oppstartslaster* is not established | +| download mode | nedlastingsmodus | The ESP32 flashing mode; first mention `nedlastingsmodus (download mode)`. Distinct from the HALPI2 added-terms `oppstartsmodus` (*boot mode*), which is about which medium the machine boots from | +| user-programmable LED | brukerprogrammerbar LED | The blue one on `GPIO2` | +| flash memory | flashminne | `16 MB flashminne`. The verb is `flashe`, already in the shared Software table | +| open hardware | åpen maskinvare | HALMET's licence statement. Source code is `åpen kildekode`; the two are not interchangeable | + +### A note on `galvanisk isolasjon`, and why not `galvanisk skille` + +`galvanisk skille` is the more frequent phrase in general Norwegian electrical +writing, and it is the wrong choice in a marine document: to a Norwegian boat +owner, *et galvanisk skille* is a specific product — the galvanic isolator +fitted in the shore-power earth conductor to stop stray-current corrosion. +HALMET has no such device, and the isolation being described is a property of +the board. `galvanisk isolasjon` for the property, `galvanisk isolert` for the +adjective, and `isolert seksjon` / `isolert område` for the parts on the far +side of the barrier. This is the same kind of near-collision the shared table +solves for `krimping` versus `krymping`. + +### A note on `normalt åpen` and `normalt lukket` + +Norwegian relay catalogues also say `sluttekontakt` (NO) and `brytekontakt` +(NC), and those are good words — but they name contacts, not switches, and the +HALPI2 glossary already fixed `normalt åpen (NO)` when it described the external +Power/Reset buttons. That decision is kept and `normalt lukket (NC)` completes +the pair. `normalt åpen`/`normalt lukket` is standard Norwegian technical usage +and not a literal calque; keep the English abbreviation in parentheses on first +mention, because the reader will meet `NO`/`NC` in the sender's own datasheet. + +Swedish diverges here (`slutande` / `brytande`). The divergence is deliberate, +decided per language, exactly as with `bærekort` / `emolevy`. Do not harmonise. + +Getting this pair wrong inverts the instructions: a normally open switch needs +the pull-down resistor, a normally closed one needs the pull-up, and the +`usage/index.md` passage says so in a single sentence. + +### A note on `jumper` and `loddebro` + +These are two different objects and the reader acts differently on each. + +A **`jumper`** is a removable shunt pushed onto a pin pair. On HALMET that is +only the `CCS` constant-current-source headers, which are enabled by placing +one and disabled by pulling it off. + +A **`loddebro`** is a pad pair on the PCB closed permanently with a soldering +iron: the `LP` low-pass filters, the pull-up and pull-down resistors, the CAN +terminator and the `ADS1115` address selection, all on the bottom side. +Confusing the two sends the reader either for a `loddebolt` they do not need or +trying to pull off something that is soldered down. Where the English says only +*jumper*, decide from the context which one it is — everything on the bottom +side is a `loddebro`. + +`loddebro` is the inherited term and is kept, but it is also what Norwegian +calls an accidental solder bridge. When the accidental kind is meant — the +errata page's short-circuit description is the place this will come up — write +`utilsiktet loddebro` and never leave it bare. + +### A note on `pull-up-motstand` + +Norwegian electronics keeps the English *pull-up* and *pull-down* and compounds +them with a hyphen: `pull-up-motstand`, `pull-down-motstanden`, +`pull-down-loddebroen`. Translated forms such as *oppdragningsmotstand* are not +established and would break the link to the schematic and to the board labels +the reader has in front of them. This is the same treatment the shared table +gives `device tree-overlay`. Finnish translates these (`ylösvetovastus`); that +divergence is deliberate and per language. + +### A note on `boot-knapp` next to `resetknapp` + +`reset` has been naturalised in Norwegian and compounds solid, which is why the +shared table already has `resetknapp`. `boot` has not, and `bootknapp` reads as +a typo, so it takes a junction hyphen — the same treatment the shared table +gives `status-LED`. The asymmetry is intentional. When the printed label itself +is meant rather than the button's function, write `Reset`-knappen and +`Boot`-knappen with the label in code style. + +### A note on `kontakt`, `pinneliste` and `klemme` + +HALMET puts *connector* and *header* side by side far more often than HALPI2 +does — *1-Wire header connector*, *I2C header connector*, *analog input +connectors*. The shared split is kept: `kontakt` for a connector as a physical +part, `tilkobling` for the act of connecting, `pinneliste` for a pin header. +Where the English doubles the words (*header connector*), use `pinneliste` +alone — Norwegian does not need both. The pluggable input connectors are +`koblingsklemmer` (`pluggbare koblingsklemmer`), and the one mounted through the +enclosure wall is a `panelkontakt`. + +### Numbers on HALMET pages + +The shared units table applies unchanged. Four forms occur only in this +repository: + +| English source | Norwegian Bokmål | +|:---------------|:-----------------| +| `320 ohms`, `100 kohm`, `120 ohm` | `320 Ω`, `100 kΩ`, `120 Ω` | +| `+/- 30 V`, `-32V and +32V` | `±30 V`, `−32 V og +32 V` | +| `2x10 pin`, `4-pin`, `3-pin` | `2×10 pinner`, `4-pinners`, `3-pinners` | +| `5-32 V`, `2-3 panel connectors` | `5–32 V`, `2–3 panelkontakter` (en dash) | + +Drill sizes keep the inch fraction as the source writes it: `12,5 mm eller +1/2"`, `16 mm eller 5/8"`. The fraction is a bit designation, not a measurement +to convert, and rewriting it would trip the numeric-drift check. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes — the same command CI runs. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py nb` passes. +5. `uv run python scripts/check_typography.py nb` passes. +6. Lists render as lists — see + `../best-practices/markdown-lists-need-blank-line-2026-05-16.md`. The rule + applies identically to Norwegian pages. +7. Every term used on the page that appears in this glossary matches it. + +`scripts/check_glossary.py` already carries `"nb": "norwegian-glossary.md"` in +its `GLOSSARIES` dict, and `check_typography.py` already knows that Norwegian +quotes are `«…»` and Danish `»…«`, so steps 4 and 5 run as they stand. + +One gap to know about: `check_typography.py` measures the junction hyphen only +for the names it lists, and `HALMET` is not among them. `HALMET-kabinett` and +`HALMET-kortet` are therefore not machine-checked — use the grep in the table +below. + +### The six rules are measured, not reread + +**A rule that was read looks followed.** Rereading your own page confirms +whatever it already says. Both the French and German branches shipped a +half-applied typography rule to review for exactly this reason, and Danish is +close enough to Norwegian that a leak from the parallel branch will read as +fine. Run these against `docs/nb/` and act on any non-zero count. Strip code +fences first — every count below is about prose, and inline code is exempt. + +| Rule | Command | Expected | +|:-----|:--------|:---------| +| Guillemets pair and point inward | `grep -o '«' -r docs/nb \| wc -l` and the same for `»` | equal counts | +| No Danish outward quotes | `grep -rnE '»[^«»]*«' docs/nb` | no output | +| No space inside guillemets | `grep -rnE '« \| »' docs/nb` | no output | +| Reader is `du` | `grep -rowiE '\b(du\|deg\|din\|ditt\|dine)\b' docs/nb \| wc -l` | well above zero | +| No formal address | `grep -rnE '\b(De\|Dem\|Deres)\b' docs/nb` | no output outside sentence-initial `De` | +| No space before `;:!?` | `grep -rnE ' [;:!?]' docs/nb` | no output | +| No `-tion` (Danish/English) | `grep -rniE '[a-zæøå]{3,}tion(en\|er\|ene\|s)?\b' docs/nb` | no output | +| Infinitive marker is `å` | `grep -rnE '\bat [a-zæøå]+e\b' docs/nb` | no output | +| No Danish function words | `grep -rniwE '(kun\|nu\|nogen\|meget\|end\|efter\|sætte\|hjælp\|ændre\|tjek)' docs/nb` | no output | +| No `-erne` plurals | `grep -rniE '[a-zæøå]{3,}erne\b' docs/nb` | no output | +| No split compounds | `grep -rniE '(strøm forsyning\|kabel gjennomføring\|lodde bro\|lavpass filter\|spennings deler\|konstant strømkilde\|status LED-\|spennings fall)' docs/nb` | no output | +| German hyphen chain | `grep -rn 'NMEA-2000\|Signal-K\|Raspberry-Pi' docs/nb` | no output | +| Junction hyphen present | `grep -rn 'NMEA 2000-\|Signal K-\|HALMET-' docs/nb` | matches wherever the name is compounded | +| Pin labels not translated | `grep -rniE '\b(inngang ?[1-4]\|utgang ?[1-4])\b' docs/nb` | no output — `D1`–`D4` and `A1`–`A4` are copied | +| Sender is `giver`, not `sender` | `grep -rniwE '(senderen\|sendere\|senderne)' docs/nb` | no output | +| Unit spacing | `grep -rnE '[0-9](V\|A\|W\|Ω\|mm\|kg\|m)\b' docs/nb` | no output | +| Decimal comma | `grep -rnE '[0-9]\.[0-9]' docs/nb` | no output outside version numbers | +| En dash in ranges | `grep -rnE '[0-9]-[0-9] ?(V\|A)' docs/nb` | no output | +| Numbers did not drift | every number in the English page appears in the Norwegian page | all present | + +A wrong voltage or current in an installation guide is a safety problem, not a +typo. The last row is not optional. + +## Related + +- `finnish-glossary.md`, `french-glossary.md`, `german-glossary.md`, + `swedish-glossary.md`, `spanish-glossary.md`, `italian-glossary.md`, + `danish-glossary.md` — siblings +- `.claude/skills/translate-page/SKILL.md` — the procedure +- `../best-practices/` — the markdown traps that survive `--strict` +- mkdocs-static-i18n documentation: + + +## Terms added during translation + +Reported by the page translators, consolidated here rather than written by each +of them, because several agents share this file. + +**The rows below were added while translating the HALPI2 pages.** They are kept +because they are Norwegian terminology decisions, not HALPI2 facts: where the +same English term occurs in a HALMET page — *transceiver*, *pull-up*, *boot +mode*, *cable grommet*, *normally-open* — the rendering here is binding, and the +HALMET tables above cite them where they overlap. The notes still describe the +HALPI2 page each term came from; that context is history, not scope. New terms +found while translating HALMET pages are appended to the same table. + +| English | Translation | Note | +|:--------|:------------|:-----| +| guitar pick | gitarplekter | Named as an alternative non-conductive prying tool next to the spudger in the CM5 removal procedure. The glossary lists spudger -> plastspade but not | +| board-to-board connector | kort-til-kort-kontakt | The two high-density connectors joining the CM5 to the carrier board. Central to the CM5 replacement section and its warranty warning, so it needs one | +| amber (LED colour) | ravgul | LED colour column in the status-LED table. Norwegian trade usage also says gul, which would collide with the yellow Ethernet-speed LED two rows above; | +| voltage bar (LED pattern) | spenningssøyle | The LED pattern name in the operation.md quick-reference table, where the five LEDs form a bar-graph charge indicator. | +| hex socket / socket size (tool) | pipe / pipestørrelse | The connector-removal step lists 26 mm, 10 mm, 8 mm and 17 mm sockets. pipe (pipenøkkel) is the Norwegian tool word; nøkkel alone would read as a span | +| countersunk screw | senkeskrue | The four M4x10 lid screws. Appears in the very first procedure on the page. | +| boot mode | oppstartsmodus | USB boot mode / Abnormal boot mode, in the connector table, the LED table and the SSD section. The glossary has to boot -> starte opp but not this com | +| single-sided / double-sided (SSD) | ensidig / tosidig | The M.2 2230-2280 compatibility rule turns on this distinction, so it is load-bearing rather than decorative. | +| chip select | chip select | Kept in English in the GPIO conflict table and prose, like the other SPI signal names (MISO, MOSI, SCK) which are already never-translate. | +| transceiver | transceiver | RS-485 transceiver, in the interface-disabling section. The Norwegian trade term is the English one, consistent with the glossary keeping firmware and | +| grace period | venteperiode | The 5-second window before HALPI2 restarts itself after a manual shutdown. naadeperiode is a legal term and wrong here. | +| feeding the watchdog | mating av watchdogen | The source sets it in quotes as jargon; kept as jargon inside Norwegian guillemets so it still reads as a quoted idiom. | +| heat spreading area | varmespredende flate | The areas on the enclosure bottom the CM5 thermal pads must meet, in the CM5 final-assembly step. | +| solid (LED state) | lyser fast | Opposed to blinker (flashing) throughout the operation.md LED table; needed one fixed rendering to keep the table columns parallel. | +| pressure equalization | trykkutjevning | The stated purpose of the breather plug. The glossary gives the part (trykkutjevningsplugg) but not the function, which the panel-connector list state | +| terminals (crimp-on cable terminals) | kabelsko | Appears twice in the permanent-installation materials list and in "Install terminals using proper crimping technique". The glossary covers terminal bl | +| cable grommet | gummigjennomføring | "Install cable glands or cable grommets if routing through bulkheads" lists it alongside cable gland (kabelgjennomføring). Needed a distinct word so t | +| "wall wart" (power supply type) | «wall wart» (kept English in guillemets) | Jargon in the optional-items list. No idiomatic Norwegian equivalent; kept as a quoted English idiom inside «…», the same treatment the glossary gives | +| mounting clips | monteringsklips | Last item of the materials list, next to cable ties (kabelstrips). Recording it so the next page that mentions clips does not invent klemmer or festek | +| known-good device | en enhet du vet fungerer | NMEA 2000 troubleshooting bullet. Rendered as a relative clause rather than a compound; noting it so the phrase stays the same if it recurs. | +| Load Equivalency Number (LEN) | Load Equivalency Number (LEN) | NMEA 2000 standard term for how much bus power a device draws. Norwegian marine dealers and the standard itself use the English name and the LEN abbre | +| multi-talker / single-talker-multiple-listener | multi-talker / single-talker-multiple-listener | NMEA 0183 / RS-485 topology terms. Kept English but glossed once on first use: 'nettverk med flere sendere (multi-talker)' and 'nettverk med én sender | +| half-duplex | halv dupleks | The RS-485 mode that lets one wire pair both transmit and receive. Two words in Norwegian (halv dupleks) rather than a solid compound, matching establ | +| normally-open (NO) momentary switch | normalt åpen (NO) momentbryter | The switch type required for the external Power/Reset/User buttons. Load-bearing: the wrong switch type makes the button behave inverted. 'momentbryte | +| Battery-Backed RAM (BBR) | batteribackup-RAM (BBR) | Where the u-blox GNSS receiver stores its settings. Explains why the configuration is re-run on every boot, so it needs a stable rendering. Abbreviati | +| PLC (programmable logic controller) | PLS | Industrial RS-485 device listed under common applications. PLS is the standard Norwegian abbreviation (programmerbar logisk styring); writing PLC woul | +| buck converter | buck-omformer | Names the SiC463ED regulating the 10 V intermediate rail in the power-supply table. Norwegian trade usage keeps 'buck' and compounds it with a junctio | +| ferrite bead | ferrittperle | USB 3.0 port filtering in technical-reference/hardware.md. Standard Norwegian component name. | +| pull-up (resistor) | pull-up-motstand | The 2,2 kΩ pull-ups on the controller I2C bus. Norwegian keeps the English 'pull-up' and compounds it, as with the glossary's device tree-overlay. | +| ingress protection | inntrengningsbeskyttelse | The IP65 row in the specifications summary. The separate 'IP rating' row in the enclosure table is rendered 'IP-klasse' — the two English phrasings ar | +| solder nut | loddemutter | The 4× M2.5 fasteners holding the CM5, in the mounting list. Distinct from the glossary's gjengeinnsats (threaded insert), which is the HAT mounting m | +| current limit (the value) | strømgrense | Column header in the USB 3.0 port table, where each cell is a number (0,93 A). The glossary has current limiting -> strømbegrensning for the function | +| depth sounder / wind instrument | ekkolodd / vindmåler | NMEA 0183 instrument types listed under common applications for RS-485. Both are the ordinary Norwegian boating words. | +| recessive state | resessiv tilstand | The bus state an RS-485 multi-talker interface must hold when not transmitting. Direct loan, as in the CAN literature. | +| power-on / power-off threshold | innkoblingsterskel / utkoblingsterskel | The 8,0 V and 5,5 V supercapacitor thresholds. Chosen as a matched pair so the two table rows read parallel; UVLO is kept as the English abbreviation | +| user space | brukerrommet (user space) | ubuntu-installation.md describes halpid as a user space daemon that talks to the power-management hardware over I2C. The glossary fixes daemon -> daem | +| thermal throttling | termisk struping | troubleshooting.md, the 'System runs slowly or freezes' step about CPU temperature above 80 °C. The glossary covers passiv kjøling but not the throttl | +| rollback (of a firmware update) | tilbakerulling / rulle tilbake | The whole 'Firmware Update Failed or Rolled Back' section turns on this word, and the LED/firmware sections of software.md already describe the same 3 | +| login prompt | påloggingsledetekst | troubleshooting.md tells the reader to attach HDMI and look for boot errors or a login prompt. The glossary has to log in -> logge på but not the on-s | +| bus contention | konflikt på bussen | The CAN error-counter step in troubleshooting.md lists it alongside wiring problems and wrong baud rate. No single-word Norwegian equivalent is in use | +| 3rd party (operating systems) | tredjeparter | The warning admonition at the top of ubuntu-installation.md. Spelled out as a word rather than kept as a digit, so the numeric-drift check will report | +| errata / known hardware issues | kjente feil | Page title of appendices/errata.md. Taken from the nb nav_translations block in mkdocs.yml ("Errata": "Kjente feil") so the H1 and the sidebar agree, | +| mounting ledge | monteringsknast | The cast aluminium ledges inside the enclosure that the PCB rests on. Central to the second errata item (heading plus three prose mentions); knast is | +| solder mask | loddemaske | The PCB coating a casting flash can penetrate, in the errata short-circuit description. | +| copper pour / power plane | kobberflate / spenningsplan | Both appear: copper pours in the v0.5.0 changelog and a 3,3 V power plane in errata. Kept apart because the errata text names the plane as a net, not | +| inrush current / initial current spike | startstrom | The errata compliance item turns on this quantity (1,1 A against the NMEA 2000 limit of 1 A), so it needed one fixed rendering rather than an ad-hoc p | +| through-hole (THT) | gjennomhullsmontering (THT) | The v0.5.0 jumper-header changelog entry. Abbreviation kept in parentheses as the source has it. | +| footprint (component) | komponentfotavtrykk | Last v0.6.0 changelog entry. Fotavtrykk alone would read as a carbon/disk footprint in a marine document. | +| signal integrity | signalintegritet | Appears twice in design-files (v0.6.1 summary and the v0.6.0 re-routing entry). | +| security hardening | sikkerhetsherding | Bullet in software-development/advanced-config.md. Sikring would collide with the glossary entry fuse -> sikring, which is the reason for choosing her | +| cross-compilation | krysskompilering | Bullet in software-development/integration.md. | +| kernel module | kjernemodul | Bullet in software-development/integration.md; kernel is otherwise never translated in the glossary, but the compound reads badly in English here. | +| goodie bag | tilbehørspose | The bag of extras shipped in the box. Appears only as the index.md image alt text, so nothing else in the corpus pins it down; recorded here so the next page that mentions it does not invent godtepose or tilbehørspakke. | +| layout | oppsett / oppbygning / plassering / kretskortlayout | Four senses the English word covers and Norwegian splits; they are not rivals and must not be harmonised. A set of items chosen from options is oppsett (standardoppsettet, tastaturoppsett, standardoppsettet med 40 pinner). How something is built up internally is oppbygning (the Intern oppbygning heading, and the carrier-board alt text Bærekortets oppbygning, oversiden). Where parts sit on a face is plassering (Kontaktplassering på HALPI2, the index.md alt text). PCB design files are kretskortlayout, the trade loan. | diff --git a/solutions/translation/spanish-glossary.md b/solutions/translation/spanish-glossary.md new file mode 100644 index 0000000..88e1e50 --- /dev/null +++ b/solutions/translation/spanish-glossary.md @@ -0,0 +1,684 @@ +--- +title: Spanish translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Spanish under docs/es/ + - Reviewing a Spanish translation for consistency + - Adding a new term that has no established Spanish equivalent +tags: + - translation + - i18n + - spanish + - terminology + - mkdocs-static-i18n +--- + +# Spanish translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Spanish under `docs/es/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/es/hardware/index.md`. Only markdown lives under `docs/es/`; images and +other assets stay with the English source and are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with +two different Spanish words. `carrier board` → `placa portadora` was decided +there and stands here too, as does every typography rule below. Terms under the +`## HALMET terms` heading are additions this product needed; everything above it +is shared with HALPI2, and **a change to a shared row must be made in both +repositories or in neither.** + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `puente de soldadura` on one page and +`puente soldado` on the next — and the result reads as machine output even when +each individual sentence is correct. This file is the reference that prevents +that drift, and it is a living document: extend it when a page introduces a term +that is not listed, rather than inventing a one-off translation. + +`finnish-glossary.md` is the sibling of this file in this repository, and it was +adapted from HALPI2 the same way. The general approach is the same in both. + +The locale is a single generic `es`. There is no `es-ES` and no `es-419` build, +so every regional choice below is made once, for both audiences, and recorded +here. + +## Six rules where the siblings are wrong for Spanish + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary — the Finnish, French, German and +Swedish files, which live beside this one in the HALPI2 repository and, for +Finnish, in this one too. Each rule is written so it can be counted in the +finished page rather than nodded at. + +1. **The reader is never addressed.** French uses *vouvoiement*, German uses + *Sie*, Finnish and Swedish use the second person singular. All four are wrong + here. Spanish technical documentation is impersonal: + + > La unidad se apaga automáticamente cuando se interrumpe la alimentación. + + Procedure steps take the **infinitive**, not an imperative: + + > Conectar el cable de alimentación. Comprobar la polaridad con el multímetro + > antes de aplicar tensión. + + This is also the only register that survives a generic `es` build: `usted` + sounds commercial in Spain, `tú` sounds wrong in an installation manual + anywhere, and `vosotros` does not exist in Latin America. The impersonal has + no regional split at all. + + *Count:* `usted`, `ustedes`, `tú`, `ti`, `vosotros`, `vosotras` appear **zero** + times. Every numbered and bulleted procedure step begins with an infinitive — + count the steps, count the infinitives, the two numbers are equal. + +2. **Inverted opening marks are mandatory.** `¿` and `¡` do not exist in the + English source, so a missing one is never a copy error — it is always an + omission, and it is the defect a Spanish reader sees first. Headings that are + questions carry both marks: `## ¿Qué es HALMET?` + + *Count:* the number of `¿` equals the number of `?` outside code. Exclamations + in prose are rare here; when one is used it opens with `¡`. Do not count the + `!` in `!!! warning` or in `![image]` — those are markdown syntax. + +3. **Quotation marks are `«…»`** — angular marks, the RAE first level. Not + German's `„…"`, not Swedish's `”…”`, not straight `"…"`. Use them for quoted + hardware labels and UI strings that stay in English: `el botón «Reset»`, + `el botón «Boot»`, `el puente «CCS»`. + + **Unlike French, there is no space inside the marks.** `«Abnormal»`, never + `« Abnormal »`. A French translator's muscle memory puts a no-break space + there and it is invisible in review. + + *Count:* `«` and `»` occur the same number of times. `"`, `”`, `„` and `“` + occur zero times outside code. The sequences `« ` and ` »` occur zero times, + including with U+00A0. + +4. **No space before `; : ! ?`** — as in German and Swedish, and the exact + opposite of French, whose rule demands a no-break space there. + + *Count:* zero occurrences of a space (U+0020 **or** U+00A0) immediately before + `;`, `:`, `!` or `?` outside code. Check U+00A0 explicitly: it is invisible, + and it is what arrives when a French sentence pattern is carried across. + +5. **A proper name never takes a hyphen in a compound.** German writes + `NMEA-2000-Netzwerk`, Swedish `NMEA 2000-nätverk`, Finnish `NMEA 2000 -verkko`. + Spanish uses a plain noun phrase or a preposition: + + - `red NMEA 2000`, `bus NMEA 2000`, `servidor Signal K`, `módulo ESP32` + - `carcasa del HALMET`, `conector M12`, `entradas del ADS1115`, `bus I2C` + + *Count:* `NMEA-2000`, `Signal-K`, `HALMET-`, `SH-ESP32-`, `ESP32-` (as a + compound with a Spanish noun, not the module name `ESP32-WROOM-32E`) and + `ADS1115-` occur zero times outside code and outside repository names such as + `HALMET-example-firmware`. + +6. **One Spanish, no mixing.** No sibling language has a regional split, so no + sibling glossary warns about this. Three decisions, made once: + + | Use | Never | Why | + |:----|:------|:----| + | ordenador | computadora, computador | One form must win; `ordenador` is chosen for the whole site | + | supercondensador | supercapacitor | `capacitor` is an Americanism; `condensador` is the general term | + | supervisión | monitoreo, monitorización | Both alternatives are regionally marked; `supervisión` is not | + + *Count:* each banned word appears zero times. + +## Names that are never translated + +Product names, protocol names, hardware standards and software UI strings stay +in English — the device's own interface is in English, so translating a menu +name sends the reader looking for something that is not on the screen. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, I2C, + 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, Schmitt + trigger +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`. These are printed on the board; a translated pin name sends the reader + looking for a label that does not exist. The same holds for `DI1`–`DI4`, + `GPIO0`, `GPIO2`, `GPIO4`, `TDI`, `TCK`, `TMS`, `TDO`, `CAN RX` and `CAN TX` + in the GPIO table. +- **Repository, file and command names:** `HALMET-example-firmware`, `main.cpp`, + `halmet-hardware` +- **UI strings and silkscreen labels the reader will see in English:** + `«Reset»`, `«Boot»`, `«CCS»`, `«LP»`, `«3V3»`, `«GND»` + +`bus CAN` is the one exception worth stating: `CAN bus` is a compound of a +standard's name with a common noun, so Spanish word order applies — `el bus CAN`, +never `el CAN bus`. The name `CAN` itself is untouched. + +Code fences, command output, URLs and image filenames are never touched. + +## Units and numbers + +The English source writes `12V` and `0.9A`. Both are wrong in Spanish: SI +spacing and a decimal comma are required, and this needs an active conversion on +nearly every technical page. + +| English source | Spanish | +|:---------------|:--------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | +| `1.5mm²`, `2m` | `1,5 mm²`, `2 m` | + +Dimensions written as a single product spec keep the tight form: +`200×130×60 mm`. + +**No thousands separator anywhere on this site.** Spanish forbids the English +comma (`115,200` reads as a decimal), and the alternatives — a period or a thin +space — buy nothing at the magnitudes used here. Baud rates, port numbers and +firmware versions are identifiers, not measurements: `115200 bps`, `9600`, +`puerto 2947`, `3.1.0` are copied unchanged. + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry an `en/`, `es/` or other language segment; image +captions and alt texts are translated but filenames are not; screenshots stay +English because the reader's own screen is English; standard admonition titles +are translated centrally in `mkdocs.yml`, custom ones in the page. + +Translated headings change their anchors, and `¿` and the accents are stripped +by the slugifier — `## ¿Qué es HALMET?` does **not** become `#¿que-es-halmet`. +Do not guess: build the site and read the real ids out of the generated HTML. +This matters on HALMET's `usage/index.md`, which links to +`../hardware/index.md#gpio-reference`: that anchor changes as soon as the +heading is translated, and `check_anchors.py` is what catches it. + +Section and page titles in the navigation are not part of any markdown file — +they live in `mkdocs.yml` under the i18n plugin's `nav_translations`, which is +the single source of truth. Two entries are judgement calls worth recording: + +- `Errata` → **Errores conocidos**. The page lists known hardware defects; + Spanish `erratas` means printing errors or corrections, which is the wrong + thing entirely. +- `Hardware Revisions` → **Versiones del hardware**. Board versions, not + document revisions, so not `revisiones`. + +## Glossary + +### Enclosure and mounting + +| English | Spanish | Note | +|:--------|:--------|:-----| +| carrier board | placa portadora | The accurate term, as in French, German and Swedish | +| enclosure | carcasa | | +| heat sink | disipador térmico | The enclosure doubles as one | +| waterproof | estanco | `carcasa estanca (IP65)` | +| rugged | robusto | | +| wall-mount | montaje en pared | | +| mounting surface | superficie de montaje | | +| pilot hole (to be drilled) | agujero guía | `Taladrar los agujeros guía para los tornillos` | +| pre-drilled hole (already there) | orificio pretaladrado | The holes the enclosure ships with | +| mounting template | plantilla de taladrado | | +| clearance | espacio libre | | +| bilge water | agua de sentina | The compartment alone: *sentina* | +| bulkhead | mamparo | | +| cable gland | prensaestopas | `prensaestopas PG7` | +| cable routing | tendido de cables | | +| service loop | bucle de servicio | Slack left at both cable ends | +| cable tie | brida | | +| blind plug | tapón ciego | | +| breather plug | tapón compensador de presión | Must never be removed | + +**Two rows, not one, for the holes.** `pilot hole` is a hole that does not exist +yet and has to be drilled; `pre-drilled hole` is one the enclosure arrives with. +The English source uses both, three sections apart. Collapsing them produced a +nonsense instruction in Swedish — *drill the pre-drilled holes* — so never write +`taladrar los orificios pretaladrados`. + +**A note on `placa portadora`.** Spanish takes the accurate term, like French +(`carte porteuse`), German (`Trägerplatine`) and Swedish (`bärkort`), and unlike +Finnish (`emolevy`, literally *motherboard*, chosen there for reader +familiarity). The divergence between the five is deliberate, decided per +language and per audience. Do not harmonise them. + +`placa portadora` carries the CM5/board relationship on its own, so passages +about reseating the CM5 or troubleshooting a board that will not boot need no +extra explanation. Only the Finnish glossary needs that warning. + +### Power and electrical + +| English | Spanish | Note | +|:--------|:--------|:-----| +| power supply | alimentación | The unit itself: *fuente de alimentación* | +| power source | fuente de alimentación | | +| input voltage range | rango de tensión de entrada | | +| polarity | polaridad | | +| positive (+) / negative (−) | positivo (+) / negativo (−) | | +| fuse | fusible | | +| inline fuse | fusible en línea | | +| circuit breaker | interruptor automático | Neutral; not *magnetotérmico* or *disyuntor* | +| electrical panel | cuadro eléctrico | | +| current limiting | limitación de corriente | | +| current limiter | limitador de corriente | The circuit | +| current limit | límite de corriente | The `0,9 A` / `2,5 A` setting | +| overcurrent | sobrecorriente | | +| voltage drop | caída de tensión | | +| grounding | puesta a tierra | | +| short circuit | cortocircuito | | +| wire gauge | sección del conductor | Spanish uses mm², not AWG | +| marine-grade wire | cable de calidad náutica | | +| to strip (a wire) | pelar | | +| wire strippers | pelacables | | +| crimping | crimpado | Verb: *crimpar*. Established trade usage, like `firmware` | +| crimper | tenaza de crimpar | | +| heat-shrink tubing | tubo termorretráctil | Two r's | +| heat gun | pistola de aire caliente | | +| multimeter | multímetro | Not *polímetro* | +| continuity test | prueba de continuidad | | +| terminal | terminal | | +| terminal block | bloque de terminales | Not *bornera* or *regleta* | +| strain relief | descarga de tracción | Its absence is why the screw-terminal barrel plug is temporary only | +| super-capacitor | supercondensador | | +| real-time clock | reloj de tiempo real | | +| backup battery | pila de respaldo | The CR2032 for the RTC | + +### Connectors and interfaces + +| English | Spanish | Note | +|:--------|:--------|:-----| +| connector | conector | | +| barrel connector | conector cilíndrico | Add *(barrel)* on first mention | +| header | conector de pines | `conector GPIO de 40 pines` | +| pin | pin | | +| jumper | puente | Add *(jumper)* on first mention | +| backbone | cable troncal | The NMEA 2000 trunk; the network as a whole: *red troncal* | +| drop cable | cable de derivación | | +| T-connector | conector en T | Also for the source's *T-adapter* | +| terminator | terminador | The bus terminator enabled by the jumper | +| termination resistor | resistencia de terminación | The 120 Ω component | +| termination | terminación | The act, and the network property | +| front panel | panel frontal | | +| antenna | antena | | +| extension cable | cable alargador | | +| male / female | macho / hembra | | + +### Operation and system behaviour + +| English | Spanish | Note | +|:--------|:--------|:-----| +| boat computer | ordenador de a bordo | See rule 6 on `ordenador` | +| to boot | arrancar | Noun: *arranque* | +| first boot | primer arranque | | +| shutdown | apagado | | +| graceful shutdown | apagado controlado | | +| power loss | pérdida de alimentación | | +| blackout | corte de corriente | `temporizador de corte de corriente` | +| glitch immunity | inmunidad a microcortes | | +| power management | gestión de la alimentación | | +| status LED | LED de estado | | +| LED bar | barra de LED | | +| monitoring | supervisión | Never *monitoreo* or *monitorización* | +| passive cooling | refrigeración pasiva | | +| watchdog | watchdog | Gloss once as *(temporizador de vigilancia)*, then keep the term | +| standby | modo de reposo | The planned state where the CM5 is off and the controller waits | +| filesystem | sistema de archivos | | +| to unmount (a filesystem) | desmontar | `el sistema de archivos se desmonta de forma segura` | +| to unmount (a board or module) | retirar | The source says *unmount* for the carrier board and the CM5 too; `desmontar` there reads as *dismantle* | +| to reseat (a module) | volver a asentar | | + +### Software and networking + +| English | Spanish | Note | +|:--------|:--------|:-----| +| firmware | firmware | Not *microprogramación* — matches the sibling decision to keep the trade term | +| daemon | demonio | Established in Spanish Linux usage, as in French | +| to flash (firmware or an image) | grabar | Noun: *grabación*. Never *flashear* | +| to flash (an LED) | parpadear | A machine translator renders both English senses the same way; these are different words in Spanish | +| system image | imagen del sistema | | +| operating system image | imagen del sistema operativo | | +| headless | sin pantalla | First mention: `sin pantalla (headless)` | +| deployment | puesta en marcha | | +| container app | aplicación en contenedor | | +| container image | imagen de contenedor | Not *imagen del sistema* | +| dashboard | panel de control | Homarr's *dashboard* view | +| WiFi Access Point | punto de acceso WiFi | | +| wired / wireless | por cable / inalámbrico | | +| credentials | credenciales | | +| username / password | nombre de usuario / contraseña | | +| default password | contraseña predeterminada | | +| single sign-on (SSO) | inicio de sesión único (SSO) | | +| Certificate Authority (CA) | autoridad de certificación (CA) | | +| to trust (a certificate) | confiar en | | +| web interface | interfaz web | Feminine: *la interfaz* | +| browser | navegador | | +| system administration | administración del sistema | | + +### Applications and use cases + +| English | Spanish | Note | +|:--------|:--------|:-----| +| chart plotter | plóter cartográfico | | +| data logging | registro de datos | | +| vessel | embarcación | Not *buque*, which implies a ship | +| engine parameters | parámetros del motor | | +| fleet management | gestión de flotas | | +| predictive maintenance | mantenimiento predictivo | | +| process monitoring | supervisión de procesos | | +| remote monitoring | supervisión remota | | +| electromagnetic interference (EMI/RFI) | interferencias electromagnéticas (EMI/RFI) | | +| compliance | conformidad | | +| warranty | garantía | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. **Rows above +this heading are shared with HALPI2 and must not be changed here alone.** Rows +below it are HALMET's own. + +### Board and inputs + +| English | Spanish | Note | +|:--------|:--------|:-----| +| development board | placa de desarrollo | What HALMET is sold as. Never `placa portadora` — that is HALPI2's carrier board and implies a module plugged into it | +| board (the HALMET board itself) | placa | `la placa`, `la cara inferior de la placa`. Not *tarjeta*, which is a plug-in card | +| microcontroller | microcontrolador | | +| flash memory | memoria flash | `16 MB de memoria flash`; the unit spacing rule applies | +| digital input | entrada digital | `D1`–`D4` stay as printed | +| analog input | entrada analógica | `A1`–`A4` stay as printed | +| input | entrada | | +| output | salida | | +| sender | sensor | The sending unit a gauge reads. Not *emisor* or *transmisor*, which suggest a radio transmitter. Spanish does not keep the English *sender*/*sensor* distinction; where a sentence pairs them, let the role carry it: `el indicador y el sensor forman un divisor de tensión` | +| tank sender | sensor de tanque | | +| tank | tanque | Regional decision per rule 6: `depósito` is Spain-marked, `tanque` is the neutral marine word | +| resistive sender | sensor resistivo | | +| gauge (engine panel gauge) | indicador | `indicador del panel del motor`. Never *calibre* — that is a machine translation of the other English *gauge*, the one the shared glossary renders as `sección del conductor` | +| counter | contador | | +| chain counter | contador de cadena | The anchor-chain counter. `cuentacadenas` is the trade name for the finished instrument; the function is `contador de cadena` | +| pulse | impulso | `contador de impulsos`, `impulsos del contador de cadena` | +| alarm signal | señal de alarma | | +| on/off signal | señal de todo o nada | The source's *on/off type signals*. A literal `señal de encendido/apagado` describes a power state, not a contact | +| engine RPM | revoluciones del motor | Spelled out in prose; `rpm` only as a unit after a number, lowercase and spaced: `3000 rpm` | +| tachometer | tacómetro | Regional decision per rule 6: `cuentarrevoluciones` is Spain-marked | +| alternator W terminal | borne W del alternador | A stud on the alternator, so `borne`. The shared glossary's `terminal` → `terminal` is unchanged and still applies to wiring terminals | +| fuel flow | caudal de combustible | Not *flujo*, which is the phenomenon rather than the measured rate | +| low-impedance output | salida de baja impedancia | | + +### Measurement and circuits + +| English | Spanish | Note | +|:--------|:--------|:-----| +| galvanic isolation | aislamiento galvánico | | +| isolated (section, area) | aislado | `sección aislada`, `zona aislada` | +| digital isolator | aislador digital | | +| isolation barrier | barrera de aislamiento | | +| ground loop | bucle de masa | `masa`, not `tierra`: this is the shared signal reference, not the protective earth the shared glossary calls `puesta a tierra`. A board with no common ground has `sin masa común` | +| analog-to-digital converter (ADC) | convertidor analógico-digital (ADC) | The acronym and the part number `ADS1115` stay English | +| resolution | resolución | `resolución de 16 bits` — Spanish spells the bit count out, no hyphen | +| sampling rate | frecuencia de muestreo | `860 muestras por segundo` | +| low-pass filter | filtro de paso bajo | One form for the whole site per rule 6: `pasa bajos`, `pasabajo` and `paso bajo` all circulate regionally. The solder-jumper label `LP` stays as printed | +| cutoff frequency | frecuencia de corte | | +| noise (electrical) | ruido | Electrical interference, not sound. Distinct from the shared `interferencias electromagnéticas (EMI/RFI)`, which is the radiated kind | +| noise immunity | inmunidad al ruido | Distinct from the shared `glitch immunity` → `inmunidad a microcortes`, which is about supply interruptions | +| voltage spike | pico de tensión | | +| voltage divider | divisor de tensión | `tensión`, never `voltaje`, throughout — the shared glossary already fixes this in `caída de tensión` and `rango de tensión de entrada` | +| constant current source (CCS) | fuente de corriente constante | A current source, not the shared `power source` → `fuente de alimentación`. The header label `CCS` stays as printed | +| excitation voltage | tensión de excitación | The voltage HALMET supplies to a sender that has no gauge | +| passive voltage measurement | medición pasiva de tensión | `medición`, not `medida`, for the act, consistently | +| active resistance measurement | medición activa de resistencia | | +| pull-up resistor | resistencia de pull-up | Trade term kept in English inside a Spanish noun phrase, like the shared `firmware` and `watchdog`. Gloss once on first mention: `resistencia de pull-up (a positivo)`. Not *resistencia de polarización*, which is a different circuit | +| pull-down resistor | resistencia de pull-down | Gloss once as `(a masa)` | +| to pull high / to pull low | llevar a nivel alto / llevar a nivel bajo | `el interruptor lleva la señal a nivel alto al cerrarse` | +| threshold voltage | tensión de umbral | | +| hysteresis | histéresis | | +| floating (input) | flotante | `la entrada queda flotante` | +| normally open (NO) / normally closed (NC) | normalmente abierto (NA) / normalmente cerrado (NC) | Established Spanish electrical terms; the abbreviation NO becomes **NA**. See the note below | +| self-resetting fuse | fusible rearmable | The 500 mA PTC. Not *autorreiniciable* | +| reverse polarity protection | protección contra inversión de polaridad | | +| overvoltage protection | protección contra sobretensión | Under-voltage: `subtensión`. Built on the shared `overcurrent` → `sobrecorriente` | +| switching power supply | fuente de alimentación conmutada | | +| current consumption | consumo de corriente | | +| short circuit | cortocircuito | Unchanged from the shared row above; repeated only because it is the reason HALMET asks for an in-line fuse on an alternator W terminal | +| chafing | rozadura | `cortocircuitos por rozadura`. New here: HALPI2's Spanish glossary has no row for it | + +### Board features and assembly + +| English | Spanish | Note | +|:--------|:--------|:-----| +| jumper | puente | Shared row, unchanged. The removable link placed on a pin pair — the CCS one. Add *(jumper)* on first mention | +| jumper header | conector de pines para puente | The pin pair a jumper is placed on. Built on the shared `header` → `conector de pines`; `contactos del conector` for the source's *jumper header contacts* | +| solder jumper | puente de soldadura | Same Spanish term as HALPI2 but the **opposite action** — see the note below | +| to short (a jumper) | puentear | `puentear los contactos`, `puentear el puente de soldadura para activar la resistencia`. Covers both kinds | +| solder pad | isla de soldadura | KiCad's Spanish term, consistent with the shared glossary's `footprint` → `huella`. Not *almohadilla*, which the shared list assigns to `thermal pad` | +| unpopulated | sin montar | `islas sin montar`. Of a header absent from the board as delivered, the verbal form reads better: `no viene montado de fábrica` | +| pitch | paso | Already fixed for HALPI2 (`paso de 3,81 mm`, `paso de 2,54 mm`); repeated because it occurs on nearly every HALMET connector | +| pluggable terminal block | bloque de terminales enchufable | Phoenix MC 3.81 type. Built on the shared `terminal block` → `bloque de terminales`; still never *bornera* or *regleta* | +| silkscreen | serigrafía | Already fixed for HALPI2. `la serigrafía de la cara inferior` | +| to solder | soldar | The tool: `soldador`. The material: `estaño` | +| grommet | pasacables | Rubber or silicone. Distinct from the shared `cable gland` → `prensaestopas`, the threaded one, exactly as in the HALPI2 list | +| step drill bit | broca escalonada | The one that looks like a small metal Christmas tree | +| conical drill bit | broca cónica | | +| panel connector | conector de panel | The connectors mounted through the enclosure wall; `tuercas del conector` for the nuts that hold them | +| reset button | botón de reinicio | The silkscreen label stays English: `el botón de reinicio «Reset»`. Not *reseteo* | +| boot button | botón de arranque | Label stays English: `el botón de arranque «Boot»`. It selects the boot mode; it does not switch the board on, so say what it does on first mention | +| bootloader | gestor de arranque | | +| download mode | modo de descarga | The ESP32's own flashing mode. Not *modo de grabación*: the shared glossary assigns `grabar` to the act of flashing, and reusing it here would blur the two | +| user-programmable LED | LED programable por el usuario | | +| open hardware | hardware abierto | The licence statement in `index.md`. `hardware` stays English, as in the shared `herrajes de montaje` note | + +### A note on `puente` and `puente de soldadura` + +Two different things, one word apart, and confusing them makes the reader do the +wrong physical action. + +- **`puente` (jumper)** is a removable link that is *placed on* a pin pair. On + HALMET this is the `CCS` header: `colocar el puente en el par de pines CCS`. + It comes off again with fingers. +- **`puente de soldadura` (solder jumper)** is a pair of pads on the PCB that is + *closed with solder*: `cerrar el puente de soldadura`. It needs a soldering + iron, and a reader who expects to pull it off will look for something that is + not there. + +The verb has to carry the difference, because the nouns are so close. Use +`colocar`/`retirar` for the jumper and `cerrar`/`soldar` for the solder jumper. + +**The HALPI2 sense is the opposite one.** There, `puente de soldadura` is a +factory-closed trace that has to be *cut* to open it, and the note in the +inherited term list says so. On HALMET the solder jumpers ship open and are +closed by the user. The Spanish term is the same in both products and stays the +same; only the verb changes. Never write `cortar el puente de soldadura` on a +HALMET page. + +### A note on `normalmente abierto` / `normalmente cerrado` + +Spanish has established terms for these and they must be used rather than a +literal rendering of the English words. A switch is `normalmente abierto (NA)` or +`normalmente cerrado (NC)`. The abbreviation changes: English `NO` becomes `NA`, +while `NC` happens to be the same in both languages. This matches the decision +already recorded for HALPI2 (`pulsador momentáneo normalmente abierto (NA)`). + +The pull-up/pull-down instructions in `usage/index.md` depend on getting this +right: with a normally closed switch the treatment is reversed, and a reader who +reads `abierto` where the source says *closed* enables the wrong resistor. + +### A note on `conector` + +The shared glossary renders both `connector` and `header` as connectors — +`conector` and `conector de pines` — and that is kept. HALMET puts the two side +by side more often than HALPI2 does (*1-Wire header connector*, *analog input +connectors*), so let the qualifier carry the distinction: `conector de pines +1-Wire`, `conectores de entrada analógica`. Where a sentence would still be +ambiguous, say what the thing is: `regleta de pines` for a bare pin strip, +`conector enchufable` for the plug that comes off. + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py es` passes. +5. `uv run python scripts/check_typography.py es` passes — it knows this + language's quotation marks and its space-before-punctuation rule. +6. Structure matches the source — see `.claude/skills/translate-page/SKILL.md`. +7. Every term used on the page that appears in this glossary matches it. +8. **The six rules at the top are measured against the pages, not re-read.** A + half-applied typography rule looks followed when you read it, because + rereading your own text confirms whatever it already says. The French and + German branches each shipped one to review for exactly this reason. Every + rule above carries a *Count:* line; run the counts. + +The four that catch the most on a Spanish page, as one command from the repo +root: + +```bash +python3 - <<'PY' +import re, pathlib +text = "\n".join( + re.sub(r"`[^`\n]*`", " ", re.sub(r"```.*?```", " ", p.read_text(encoding="utf-8"), flags=re.S)) + for p in sorted(pathlib.Path("docs/es").rglob("*.md")) +) +print("¿ vs ? ", text.count("¿"), text.count("?")) +print("« vs » ", text.count("«"), text.count("»")) +print("stray quotes ", sum(text.count(c) for c in '"”„“')) +print("space before ;:!?", len(re.findall(r"[  ][;:!?]", text))) +print("reader addressed", len(re.findall(r"\b(usted|ustedes|tú|ti|vosotr[oa]s)\b", text, re.I))) +print("regional mixing ", len(re.findall(r"\b(computador[a]?|supercapacitor|monitoreo|monitorizaci[óo]n)\b", text, re.I))) +PY +``` + +Every number on the right must be zero except the first two pairs, which must be +equal within each pair. + +## Related + +- `finnish-glossary.md` — the sibling in this repository, adapted from HALPI2 + the same way +- `../../../halpi2/solutions/translation/spanish-glossary.md` — the original. + Read-only from here: a shared row changes in both repositories or in neither +- `.claude/skills/translate-page/SKILL.md` — the procedure +- mkdocs-static-i18n documentation: https://ultrabug.github.io/mkdocs-static-i18n/ + +## Terms added during translation + +Inherited from the HALPI2 pages, where these were reported by the page +translators and consolidated into one list. They are kept because the Spanish +decisions in them are binding for HALMET too — `paso`, `serigrafía`, `puente de +soldadura`, `pasacables`, `normalmente abierto (NA)` and `V CC` are all reused +above. Rows naming HALPI2-only parts (CM5, HaLOS, the E7T connector) simply +never come up on a HALMET page; `check_glossary.py` only tests a term whose +English appears in the source, so they cost nothing. + +Extend this list the same way when a HALMET page introduces a term that is not +in the glossary tables. + +| English | Translation | Note | +|:--------|:------------|:-----| +| Getting Started (page/section title) | Primeros pasos | Page H1 and the HaLOS guide link text. Standard Spanish docs heading; avoids turning a noun phrase into a question that would need ¿…? | +| desktop setup (on a desk/bench, as opposed to permanent installation) | configuración de sobremesa | Recurs six times on this page as the counterpart of `instalación permanente`. Not the GUI desktop — `escritorio` would be wrong here. | +| wall wart (power supply) | «wall wart» (transformador de enchufe) | Quoted colloquial English in the source. Kept in guillemets per rule 3 with a short gloss on first and only mention; there is no established Spanish t | +| splash screen | pantalla de inicio | Raspberry Pi OS boot screen; needed a fixed rendering so it does not drift to `pantalla de bienvenida` on other pages. | +| cable grommet | pasacables | Appears alongside `cable gland` (prensaestopas) in the same sentence; the two must stay distinct, as with the pilot-hole / pre-drilled-hole pair. | +| mounting hardware (screws, brackets) | herrajes de montaje | "Corrosion-resistant mounting hardware" — `hardware` alone would read as electronics in a hardware manual. | +| cable tie / mounting clip | brida / clip de sujeción | `brida` is already in the glossary; `mounting clip` is not and is paired with it in the materials list. | +| rainbow pattern (LED fault indication) | patrón de arcoíris | Diagnostic LED pattern for an unseated CM5; a fixed wording matters because it is the symptom a reader searches for. | +| cable tester | comprobador de cables | Troubleshooting tool, distinct from `multímetro` which the glossary already fixes. | +| over-torque (verb) | excederse en el par (de apriete) | Mounting-screw instruction; `sobrepar` is not idiomatic Spanish. | +| Container Apps store (Cockpit) | tienda de aplicaciones en contenedor | Built on the glossary's `aplicación en contenedor`. Cockpit's own label is English, but the source uses it descriptively rather than as a quoted butto | +| known-good device | dispositivo que se sepa que funciona | Troubleshooting idiom with no compact Spanish equivalent; a literal `dispositivo bueno conocido` is meaningless. | +| device tree overlay | overlay | interfaces.md, 3 occurrences. Kept as the trade term, consistent with the glossary's decision to keep `firmware`. `superposicion de arbol de dispositi | +| chip-select | chip-select | interfaces.md table, `CAN FD chip-select`. A signal name on the board, not prose; `seleccion de chip` would not match anything the reader can look up. | +| transceiver | transceptor | interfaces.md, `an RS-485 transceiver's enable line`. Standard Spanish electronics term. | +| hardware flow control | control de flujo por hardware | interfaces.md, introduces the `ctsrts` parameter. | +| mass storage device | dispositivo de almacenamiento masivo | software.md, USB-boot procedure, 3 occurrences. The state the HALPI2 presents itself in during `rpiboot` flashing. | +| block device | dispositivo de bloques | software.md step 6, `any other tool that can write to a block device`. | +| boot mode switch | interruptor de modo de arranque | software.md, 3 occurrences in the USB-boot steps. Built on the glossary's `arranque`; the associated silkscreen labels stay English as `«Normal»` / `« | +| power cycle (noun) / to power-cycle | ciclo de alimentacion / realizar un ciclo de alimentacion | software.md, 3 occurrences including the admonition title. Distinct from `apagado` and from `reinicio`, and the firmware-update section depends on the | +| marine apps | aplicaciones náuticas | software.md image-variant table and Homarr description, 4 occurrences. The glossary has `vessel -> embarcacion` but no adjective for the application c | +| firewall | cortafuegos | software.md, VNC and Raspberry Pi Connect sections. | +| port forwarding | redireccion de puertos | software.md VNC section, alongside VPN. | +| taskbar | barra de tareas | software.md, Graphical Updates section. | +| update manager | gestor de actualizaciones | software.md, Graphical Updates section. | +| hostname | nombre de host | software.md, Raspberry Pi Imager customisations. Kept close to the English because the Imager field itself reads `hostname`. | +| to roll back (firmware) | volver a la version anterior | software.md Firmware Safety Features. Verbal phrase rather than a noun, so it composes with the impersonal register required by rule 1. | +| login console | consola de inicio de sesion | interfaces.md, the dedicated debug UART. Reuses the glossary's `inicio de sesion` from `single sign-on`. | +| power rail (3.3V rail, 5V rail) | línea (línea de 3,3 V, línea de 5 V) | Not in the glossary and it occurs eight times across both pages. Chose «línea» over the calque «raíl»/«riel» because it is regionally neutral (rule 6) | +| flange (wide flange required on inside) | reborde | The obvious equivalent «brida» is already assigned to *cable tie* in the glossary, so using it here would collide. «Reborde» names the wide collar of | +| standoff | separador | HAT mounting hardware; appears five times in the HAT installation section and had no glossary entry. | +| spudger | espátula (spudger) | No Spanish equivalent in common trade use; glossed on first mention and the English kept in parentheses, following the glossary's `sin pantalla (headl | +| solder jumper | puente de soldadura | Distinct from the removable `jumper` already in the glossary (`puente`); this one is a PCB trace that has to be cut. | +| Solo Mode / Co-op Mode | modo solo / modo cooperativo (co-op) | Firmware operating modes, not UI strings the reader sees on screen, so translated. «co-op» kept in parentheses on first mention because `halpi status` | +| VDC (11-32 VDC, 100 VDC) | V CC (11–32 V CC, 100 V CC) | SI/Spanish convention for direct-current voltage; the glossary sets unit spacing but does not cover the DC suffix. | +| chip select | selección de chip (chip select) | SPI signal name; translated with the English glossed once because the table row abbreviates it as `SPI CS`. | +| watchdog timeout | tiempo de espera del watchdog agotado | The glossary fixes `watchdog` itself but not `timeout`; «tiempo de espera» is used consistently for all four timeout occurrences across both pages. | +| blinkenlights | Blinkenlights | Left untranslated. It is a jargon in-joke, not a technical term, and any Spanish rendering loses the joke while gaining nothing; flagged here so a rev | +| rail (power rail: 5V rail, 3.3V rail) | línea (línea de 5 V, línea de 3,3 V) | Not in the glossary but already used in docs/es/user-guide/operation.md:121 ("La línea de 5 V se desactiva") and hardware.md:92. Adopted for consisten | +| pitch (connector pitch) | paso | Appears constantly in hardware.md (3.81 mm, 2.54 mm, 0.5 mm). Already established in docs/es/user-guide/hardware.md ("tipo Phoenix MC, paso de 3,81 mm | +| hub (USB hub) | concentrador | Already established in docs/es/user-guide/hardware.md:114-116 and appendices/design-files.md ("concentrador USB3"). | +| pinout | asignación de pines | Heading term in both pages. Already established in docs/es/user-guide/hardware.md:185,247. Chosen over "patillaje", which is Spain-marked. | +| VDC | V CC | Unit form, not a protocol name, so it is translated. Already established in docs/es/index.md:30, operation.md:43 and troubleshooting.md:11. | +| Load Equivalency Number (LEN) | número de equivalencia de carga (LEN) | NMEA 2000 term. Acronym kept in English because it is what the reader sees on cabling datasheets; the expansion is glossed once on first mention. | +| multi-talker / single-talker / single-talker-multiple-listener | multiemisor / de un solo emisor / de un emisor y varios receptores | RS-485 and NMEA 0183 topology terms used three times in interfaces.md. "Talker" has no established Spanish loan here; "emisor"/"receptor" is the stand | +| normally-open (NO) momentary switch | pulsador momentáneo normalmente abierto (NA) | Switch specification, not a UI string, so the abbreviation is translated (NO → NA) per Spanish electrical convention. | +| thermal pad | almohadilla térmica | Thermal management table in hardware.md. Distinct from "disipador térmico" (heat sink), which the glossary already covers. | +| half-duplex | semidúplex | RAE-accepted form; used once in the RS-485 section. | +| flexible flat cable (FFC) | cable plano flexible (FFC) | Used for the HDMI and MIPI connectors; the acronym stays English because it is the part-ordering term. | +| buck converter | convertidor reductor | Power supply table. "Convertidor buck" is also common but the Spanish form is unambiguous and needs no gloss. | +| receptacle (USB receptacle) / socket (M.2 Socket M) | conector hembra / zócalo | Two different English words for connector openings in hardware.md; kept distinct because the M.2 one is a card slot and the USB one is a cable port. | +| pigtail (panel connector) | latiguillo | Product name in the shop link in the RS-485 wiring section. | +| threaded insert / countersunk / gasket | inserto roscado / avellanado / junta | Mechanical specifications table; none appear in the glossary's enclosure section. | +| VDC (unit suffix, e.g. 32 VDC) | V CC | The glossary's units table covers V, A, Ω, °C, mm² but not the DC suffix. Spanish writes corriente continua, so the SI-spaced form is `32 V CC`. Appea | +| mounting ledge | resalte de montaje | errata.md, twice. Distinct from `punto de montaje` (mounting point, design-files.md) and from `superficie de montaje` (mounting surface, already in th | +| inrush current | corriente de irrupción | errata.md. The glossary has `overcurrent` → sobrecorriente and `current limiting` → limitación de corriente, but not the power-up surge. `corriente de | +| copper pour / copper fill | vertido de cobre | design-files.md and errata.md. PCB-layout term; `relleno de cobre` used for the errata heading where the source says "Copper Fill", `vertidos de cobre | +| power plane / rail | plano de alimentación / línea | errata.md (`3.3V power plane` → plano de alimentación de 3,3 V) and design-files.md (`3.3V rail` → la línea de 3,3 V). Kept distinct because the sourc | +| solder nut | tuerca soldable | design-files.md, twice. | +| footprint (PCB component) | huella | design-files.md. Established KiCad terminology in Spanish. | +| opamp (operational amplifier) | amplificador operacional | design-files.md. | +| test point | punto de prueba | design-files.md. | +| silkscreen | serigrafía | design-files.md. The glossary already refers to "the board's own silkscreen labels" in the what-stays-English section but does not give the Spanish no | +| PCB layout | trazado del PCB | design-files.md. Verb form for `to re-route`: volver a trazar. | +| signal integrity | integridad de señal | design-files.md, twice. | +| cable plug (the loose connector supplied for custom wiring) | clavija de cable | index.md (`E7T cable plug` → Clavija de cable E7T). Distinct from `conector` (the mating connector on the enclosure) and from `conector cilíndrico (ba | +| cutout (in the enclosure, for an extra connector) | troquel | index.md (`cutouts for 2 extra SMA connectors`). Not the same as `orificio pretaladrado`, which the glossary reserves for holes the enclosure already | +| thermal throttling | limitación térmica | troubleshooting.md. | +| runaway process | proceso desbocado | troubleshooting.md. | +| stray voltage | tensión parásita | troubleshooting.md, twice. The source says "stray voltages" injected by a connected device. | +| bus contention | contención en el bus | troubleshooting.md. | +| baud rate / bit rate (prose) | velocidad de transmisión | troubleshooting.md (`incorrect baud rate`). The glossary's number rules cover how to write `115200 bps` but not the prose noun. | +| differential signaling | señalización diferencial | troubleshooting.md (RS-485 A/B lines). | +| differential pair | par diferencial | design-files.md (`USB3 hub RX differential pairs`). | +| USB hub | concentrador | design-files.md. | +| clock oscillator | oscilador de reloj | design-files.md. | +| balancing circuit (super-capacitor) | circuito de equilibrado | design-files.md, twice. Verb/noun: equilibrado, not balanceo. | +| 3rd party | de terceros | ubuntu-installation.md (3rd party operating systems) and resources.md (third-party software compatibility). Used consistently across both. | +| user space | espacio de usuario | ubuntu-installation.md (`the user space halpid daemon`). | +| prebuilt package | paquete precompilado | ubuntu-installation.md. | +| command line tool | herramienta de línea de comandos | ubuntu-installation.md. The glossary keeps command names in English but does not give the phrase. | +| cross-compilation | compilación cruzada | integration.md. | +| custom image building | creación de imágenes personalizadas | integration.md. Built on the glossary's `imagen del sistema`. | +| security hardening | refuerzo de la seguridad | advanced-config.md. | +| backup and recovery (data, not power) | copia de seguridad y recuperación | advanced-config.md. Deliberately not `respaldo`, which the glossary assigns to the super-capacitor and RTC battery senses (`pila de respaldo`, `respal | +| performance tuning | ajuste del rendimiento | advanced-config.md. | +| power-on/off sequencing | secuenciación de encendido y apagado | power-supply.md. | +| brownout | caída de tensión | power-supply.md. Reuses the glossary's `voltage drop` → caída de tensión; kept distinct from `corte de corriente` (blackout), which the glossary alrea | +| load management | gestión de la carga | power-supply.md. | +| status reporting | notificación del estado | controller.md. Paired with the glossary's `monitoring` → supervisión in the same bullet. | +| CE marking | marcado CE | compliance.md. Official EU term. | +| environmental rating | clasificación ambiental | compliance.md. | +| chart plotter (plural) | plóteres cartográficos | index.md. Confirms the plural of the glossary's `plóter cartográfico`; plóteres, not plóters. | +| single-board computer | ordenador de placa única | index.md. Follows rule 6 on ordenador. | +| in-vehicle infotainment | infoentretenimiento a bordo | index.md. | +| telematics | telemática | index.md. | +| environmental sensing | detección ambiental | index.md. | +| quick start guide | guía de inicio rápido | index.md. Note this is the printed leaflet in the box, distinct from the nav section `Getting Started` → `Primeros pasos`, which mkdocs.yml already fi | +| goodie bag | bolsa de accesorios | index.md, image alt text only. | +| clean shutdown | apagado controlado | troubleshooting.md. The source varies its wording (`clean shutdown` here, `graceful shutdown` elsewhere) for one concept; Spanish keeps the single rendering the glossary already assigns to `graceful shutdown`. Not `apagado limpio`. | +| power connector / power socket | conector de alimentación | The English source alternates the two words for the same E7T port; Spanish uses one. `toma` is reserved for nothing here — see `receptacle / socket` above for the connector-opening senses. | diff --git a/solutions/translation/swedish-glossary.md b/solutions/translation/swedish-glossary.md new file mode 100644 index 0000000..daec2ed --- /dev/null +++ b/solutions/translation/swedish-glossary.md @@ -0,0 +1,428 @@ +--- +title: Swedish translation glossary and style rules (HALMET) +date: 2026-08-05 +category: translation +module: documentation +problem_type: reference +component: documentation +severity: medium +applies_when: + - Translating any page from docs/en/ into Swedish under docs/sv/ + - Reviewing a Swedish translation for consistency + - Adding a new term that has no established Swedish equivalent +tags: + - translation + - i18n + - swedish + - terminology + - mkdocs-static-i18n +--- + +# Swedish translation glossary and style rules + +## Context + +The HALMET documentation is written in English under `docs/en/` and translated +into Swedish under `docs/sv/`, using the `mkdocs-static-i18n` folder structure. +Each language directory mirrors the same tree, so a translation keeps its +source's path and filename: `docs/en/hardware/index.md` becomes +`docs/sv/hardware/index.md`. Every page in this repository is an +`
/index.md`, so the eight sections are the eight files. Only markdown +lives under `docs/sv/`; images and other assets stay with the English source and +are shared. + +**This file began as a copy of the HALPI2 glossary and deliberately keeps its +decisions**, so that two Hat Labs products do not describe the same part with two +different Swedish words. `carrier board` → `bärkort` stands here too, as do the +four typography rules and every row above the HALMET heading. Terms below the +HALMET heading are additions this product needed; everything above it is shared +with HALPI2, and **a change to a shared row must be made in both repositories or +in neither**. + +`finnish-glossary.md` is the sibling that was adapted for HALMET first, and the +French and German files carry the same shared core. The general approach is the +same in all of them. + +Translations are produced page by page, at different times, potentially by +different people. Without a fixed terminology list the same English term drifts +across pages — *solder jumper* becomes `lödbygel` on one page and `lödbrygga` on +the next — and the result reads as machine output even when each individual +sentence is correct. + +This file is the reference that prevents that drift. It is a living document: +extend it when a page introduces a term that is not listed here, rather than +inventing a one-off translation. Like the other glossaries it has no date in its +filename, because it is meant to be edited in place, not superseded. + +## Four rules where the siblings are wrong for Swedish + +Read this section before anything else. Every one of these is stated the +opposite way in at least one sibling glossary, and carrying the wrong habit +across has already cost two correction rounds on earlier branches. + +1. **Address the reader as `du`, not formally.** Swedish technical and consumer + documentation uses `du`. French uses *vouvoiement* and German uses *Sie* — + both wrong here. `Anslut strömkabeln.` / `Kontrollera polariteten med + multimetern innan du slår på spänningen.` + +2. **Quotation marks are `”…”`** — the *same* character (U+201D) on both sides. + Not German's `„…“`, not French's `« … »`, not straight `"…"`. + +3. **No space before `; : ! ?`** — as in German, and unlike French, whose rule is + the exact opposite and demands a no-break space. + +4. **Compounding with a proper name takes one hyphen at the junction, not + throughout.** Swedish writes `NMEA 2000-nätverk`, `Signal K-server`, + `Raspberry Pi-antenn`. German writes `NMEA-2000-Netzwerk` — hyphens all the + way through. Copying the German pattern into Swedish is wrong, and it is the + single most likely way this glossary gets violated. + +## Names that are never translated + +Identical in principle to the sibling glossaries; only the product list is +HALMET's. Product names, protocol names, hardware standards and software UI +strings stay in English. + +- **Products and software:** HALMET, SH-ESP32, SH-RPi, SensESP, Signal K, + Arduino IDE, ESP-IDF, ESPHome, PlatformIO, Hat Labs +- **Hardware and standards:** ESP32-WROOM-32E, ADS1115, NMEA 2000, CAN bus, I2C, + 1-Wire, GPIO, JTAG, USB, ADC, TVS, PG7, PG9, SP13, M12, Phoenix MC, Schmitt + trigger +- **Pin and signal names are copied exactly:** `D1`–`D4`, `A1`–`A4`, `SDA`, + `SCL`, `DQ`, `TXD0`, `RXD0`, `EN`, `IO0`, `CCS`, `LP`, `VP`, `VN`, `3V3`, + `GND`. These are printed on the board; a translated pin name sends the reader + looking for a label that does not exist. +- **UI paths, commands, file names:** `main.cpp`, `ConnectAlarmSender()`, and + every command, hostname and file path + +Compounds follow rule 4 above — one hyphen at the junction, none inside the +name: `HALMET-kortet`, `ESP32-modulen`, `1-Wire-givare`, `I2C-buss`, +`NMEA 2000-nätverk`, `Phoenix MC-plint`, `ADS1115-omvandlaren`. + +Code fences, command output, URLs and image filenames are never touched. + +## Units and numbers + +Same handling as the other languages — the English source writes `12V` and +`0.9A`, and both are wrong in Swedish. + +| English source | Swedish | +|:---------------|:--------| +| `12V`, `0.9A` | `12 V`, `0,9 A` | +| `5.5 x 2.1 mm` | `5,5 × 2,1 mm` | +| `-20°C to +60°C` | `−20 °C … +60 °C` | +| `120Ω` | `120 Ω` | +| `3-5A` | `3–5 A` (en dash for ranges) | + +## Links, images, admonitions, navigation + +Same as the sibling glossaries: paths are copied from the English source +unchanged and never carry a language segment; image captions and alt texts are +translated but filenames are not; screenshots stay English because the reader's +own screen is English; standard admonition titles are translated centrally in +`mkdocs.yml`, custom ones in the page. + +Navigation titles live in `mkdocs.yml` under the i18n plugin's +`nav_translations`, which is their single source of truth; the list is not +restated here. Three entries are judgement calls worth recording: + +- `Errata` → **Kända fel**. The page lists known hardware defects, not + corrections to be made, and the Latin term is opaque to a general reader. +- `Hardware` → **Hårdvara**, not *maskinvara*. Datatermgruppen prefers + *maskinvara* for computing in general, but this is a physical board, the trade + writes `hårdvara`, and `öppen hårdvara` is the established rendering of *open + hardware*. Use `hårdvara` throughout, including `Hardware Revisions` → + **Hårdvaruversioner**. +- `Tutorials and Examples` → **Guider och exempel**. *Handledningar* reads + academic; `guider` is what Swedish technical sites call these. + +When a page is added to the nav in English, add its Swedish title in the same +change — an untranslated entry silently falls back to English. + +## Glossary + +### Enclosure, mounting, and installation + +| English | Swedish | Note | +|:--------|:--------|:-----| +| carrier board | bärkort | The accurate term, as in French and German | +| enclosure | kapsling | | +| heat sink | kylfläns | | +| waterproof | vattentät | | +| wall-mount | väggmontage | | +| mounting surface | monteringsyta | | +| pilot hole (to drill) | förborra (verb) | `Förborra hålen` — never `borra förborrade hål` | +| pre-drilled hole (already there) | förborrat hål | The holes the enclosure ships with | +| mounting template | borrmall | | +| bilge water | slagvatten | | +| bulkhead | skott | | +| cable gland | kabelgenomföring | | +| cable routing | kabeldragning | | +| service loop | servicelänga | Slack left at both cable ends | +| cable tie | buntband | | +| blind plug | blindplugg | | +| breather plug | tryckutjämningsplugg | | + +**A note on `bärkort`.** Swedish takes the accurate term, like French +(`carte porteuse`) and German (`Trägerplatine`), and unlike Finnish (`emolevy`, +literally *motherboard*, chosen there for reader familiarity). The divergence +between the four is deliberate, decided per language and per audience. Do not +harmonise them. + +`bärkort` carries the CM5/board relationship on its own, so passages about +reseating the CM5 or troubleshooting a board that will not boot need no extra +explanation. Only the Finnish glossary needs that warning. + +### Electrical + +| English | Swedish | Note | +|:--------|:--------|:-----| +| power supply | strömförsörjning | The unit itself: *nätaggregat* | +| input voltage range | inspänningsområde | | +| polarity | polaritet | | +| fuse | säkring | | +| inline fuse | linjesäkring | | +| circuit breaker | automatsäkring | | +| current limiting | strömbegränsning | | +| overcurrent | överström | | +| voltage drop | spänningsfall | | +| grounding | jordning | | +| short circuit | kortslutning | | +| wire gauge | ledararea | Swedish uses mm², not AWG | +| marine-grade wire | sjövattenbeständig ledare | | +| wire strippers | avisoleringstång | | +| crimping | krimpning | | +| crimper | krimptång | | +| heat-shrink tubing | krympslang | | +| heat gun | varmluftspistol | | +| multimeter | multimeter | | +| terminal block | kopplingsplint | | +| strain relief | dragavlastning | | +| super-capacitor | superkondensator | | +| real-time clock | realtidsklocka | | +| backup battery | backupbatteri | | + +### Connectors and interfaces + +| English | Swedish | Note | +|:--------|:--------|:-----| +| connector | kontakt / anslutning | *anslutning* for a board-mounted socket | +| barrel connector | hålkontakt | | +| header | stiftlist | `40-polig GPIO-stiftlist` | +| pin | stift | | +| backbone | backbone | Established in Swedish NMEA 2000 usage | +| drop cable | stickledning | | +| T-connector | T-koppling | | +| termination (120 Ω) | termineringsmotstånd | | +| front panel | frontpanel | | +| jumper | bygel | | +| male / female | hane / hona | | + +### System behaviour and status + +| English | Swedish | Note | +|:--------|:--------|:-----| +| boat computer | båtdator | | +| to boot | starta | | +| first boot | första start | | +| shutdown | avstängning | | +| graceful shutdown | kontrollerad avstängning | | +| power loss | spänningsbortfall | | +| blackout | strömavbrott | | +| power management | strömhantering | | +| status LED | status-LED | | +| monitoring | övervakning | | +| passive cooling | passiv kylning | | +| filesystem | filsystem | | +| to unmount | avmontera | | +| watchdog | watchdog | | +| standby | vänteläge | | + +### Software and networking + +| English | Swedish | Note | +|:--------|:--------|:-----| +| firmware | firmware | Not *fast programvara* — matches the sibling decision to keep the trade term | +| daemon | daemon | | +| to flash | flasha | | +| operating system image | systemavbild | | +| headless | utan skärm | First mention: `utan skärm (headless)` | +| container app | containerapp | | +| container image | containeravbild | | +| dashboard | instrumentpanel | Homarr's *dashboard* view | +| WiFi Access Point | WiFi-accesspunkt | | +| wired / wireless | trådbunden / trådlös | | +| credentials | inloggningsuppgifter | | +| default password | standardlösenord | | +| single sign-on (SSO) | enkel inloggning (SSO) | | +| Certificate Authority (CA) | certifikatutfärdare (CA) | | +| web interface | webbgränssnitt | | +| browser | webbläsare | | + +### Applications and use cases + +| English | Swedish | Note | +|:--------|:--------|:-----| +| chart plotter | kartplotter | | +| data logging | datalagring | | +| vessel | fartyg | | +| fleet management | flotthantering | | +| predictive maintenance | förebyggande underhåll | | +| remote monitoring | fjärrövervakning | | +| compliance | överensstämmelse | | +| warranty | garanti | | + +## HALMET terms + +HALMET is a sensor interface board, so it needs vocabulary HALPI2 never used: +input circuits, measurement, and the things printed on a small PCB. Rows above +this heading are shared with HALPI2 and must not be changed here alone. + +### Board and inputs + +| English | Swedish | Note | +|:--------|:--------|:-----| +| development board | utvecklingskort | HALMET is sold as one; not `bärkort`, which is HALPI2's carrier board | +| digital input | digital ingång | `D1`–`D4` stay as printed | +| analog input | analog ingång | `A1`–`A4` stay as printed | +| input | ingång | The terminal on the board; an incoming signal is `insignal` | +| output | utgång | | +| sender | givare | The marine sender a gauge reads; *sändare* would mean a radio transmitter | +| tank sender | tankgivare | | +| resistive sender | resistiv givare | | +| gauge (engine panel gauge) | mätare | `mätaren i motorpanelen`; the panel as a whole is `motorinstrumenten` | +| counter | räknare | | +| chain counter | kättingräknare | Anchor chain is `ankarkätting`, never *kedja* in this sense | +| alarm signal | larmsignal | | +| engine RPM | motorns varvtal | Not *RPM* in prose; specifications write `varv/min` | +| tachometer | varvräknare | | +| alternator W terminal | generatorns W-uttag | *alternator* is `generator` in Swedish; spelled out, `växelströmsgenerator` | +| fuel flow | bränsleflöde | | + +### Measurement and circuits + +| English | Swedish | Note | +|:--------|:--------|:-----| +| galvanic isolation | galvanisk isolation | Adjective: `galvaniskt isolerad` | +| isolated (section, area) | isolerad | `isolerad sektion`, `isolerat område` | +| digital isolator | digital isolator | | +| isolation barrier | isolationsbarriär | | +| ground loop | jordslinga | | +| analog-to-digital converter (ADC) | AD-omvandlare | Spelled out: `analog-digital-omvandlare`. The part name `ADS1115` stays | +| resolution (16-bit) | upplösning | `16 bitars upplösning` | +| sampling rate | samplingsfrekvens | `860 sampel per sekund` | +| low-pass filter | lågpassfilter | The `LP` solder jumper keeps its printed label | +| cutoff frequency | gränsfrekvens | *brytfrekvens* also occurs in Swedish; pick `gränsfrekvens` throughout | +| noise (electrical) | brus | Not *buller*, which is sound. Interference coupled in from outside is `störning` | +| noise immunity | störningstålighet | What the Schmitt trigger improves | +| voltage divider | spänningsdelare | | +| constant current source (CCS) | konstantströmkälla | The header label `CCS` stays as printed | +| excitation voltage | matningsspänning | Write `matningsspänning till givaren` so it is not read as the board's own `strömförsörjning`. *excitationsspänning* is correct but rare outside datasheets | +| passive voltage measurement | passiv spänningsmätning | | +| active resistance measurement | aktiv resistansmätning | The quantity is `resistans`; `motstånd` is the component | +| pull-up resistor | pull-up-motstånd | Loan kept — see the note below | +| pull-down resistor | pull-down-motstånd | | +| threshold voltage | tröskelspänning | | +| hysteresis | hysteres | | +| floating (input) | flytande | `ingången blir flytande` | +| normally open / normally closed | slutande / brytande | The established Swedish switch terms: `slutande kontakt` = NO, `brytande kontakt` = NC. Not the literal *normalt öppen / normalt sluten*. Add `(NO)` / `(NC)` on first mention | +| self-resetting fuse | självåterställande säkring | | +| reverse polarity protection | polvändningsskydd | One word; no literal *omvänd polaritet*-construction | +| overvoltage protection | överspänningsskydd | | +| switching power supply | switchat nätaggregat | The shared table renders *power supply* as `strömförsörjning` and the unit itself as `nätaggregat`; this is the unit | +| current consumption | strömförbrukning | | +| short circuit | kortslutning | Already in the shared Electrical table with the same sense — repeated here only because HALMET's chafing warning uses it | +| chafing (of a wire) | skavning | `skador på grund av skavning` | + +### Board features and assembly + +| English | Swedish | Note | +|:--------|:--------|:-----| +| jumper | bygel | Already in the shared Connectors table, same sense: a removable link on a pin pair. See *solder jumper* for the PCB kind | +| jumper header | bygelstift | The pin pair a `bygel` is placed on; `stiftlist` is the shared word for a header in general | +| solder jumper | lödbygel | Closed permanently with solder, not with a removable `bygel` — the reader needs a soldering iron for one and not the other. Never `lödbrygga`, which is an accidental solder bridge | +| to short (a jumper) | kortsluta | `löd ihop lödbygeln` for the soldered kind, `sätt en bygel över stiften` for the removable kind | +| pad (solder pad) | lödyta | | +| unpopulated | obestyckad | `obestyckade lödytor`; a header not fitted at the factory is `inte monterad` | +| pitch (2.54 mm) | stiftavstånd | `2,54 mm stiftavstånd` | +| pluggable terminal block | löstagbar kopplingsplint | Phoenix MC type; `kopplingsplint` alone is the shared HALPI2 term | +| silkscreen | monteringstryck | The printed text and outlines on the PCB. The errata page's *back side silk screen* → `monteringstrycket på undersidan` | +| to solder | löda | | +| soldering iron | lödkolv | | +| grommet | gummigenomföring | Rubber or silicone; distinct from `kabelgenomföring`, the threaded gland in the shared table | +| step drill bit | stegborr | The one that looks like a metal Christmas tree | +| conical drill bit | koniskt borr | | +| panel connector | panelkontakt | The one mounted in the enclosure wall | +| reset button | reset-knapp | The board's own labels `Reset` and `Boot` stay in English | +| boot button | boot-knapp | | +| bootloader | bootloader | Kept in English, like `firmware` and `daemon` in the shared table | +| download mode | nedladdningsläge | The ESP32 flashing mode; first mention `nedladdningsläge (download mode)` | +| user-programmable LED | användarstyrd LED | | +| open hardware | öppen hårdvara | HALMET's licence statement | + +### A note on `pull-up-motstånd` + +Swedish electronics keeps the English *pull-up* and *pull-down* and compounds +them with a hyphen: `pull-up-motstånd`, `pull-down-motstånd`, `pull-down-bygeln`. +Translated forms such as *uppdragningsmotstånd* are not established, and they +would also break the link to the schematics and the board labels the reader has +in front of them. Finnish translates these (`ylösvetovastus`) — the divergence is +deliberate and decided per language, exactly as with `bärkort` / `emolevy`. Do +not harmonise them. + +### A note on `bygel` and `lödbygel` + +These are two different objects and the reader acts differently on each. A +`bygel` is a removable link pushed onto a pin pair — the `CCS` jumper headers, +which are enabled by placing one. A `lödbygel` is a pad pair on the PCB that is +closed permanently with a soldering iron — the `LP`, pull-up, pull-down, CAN +terminator and ADS1115 address jumpers on the bottom side. Confusing them sends +the reader either for a soldering iron they do not need, or trying to pull off +something that is soldered down. When the English says only *jumper*, decide from +the context which one it is; the bottom-side ones are always `lödbyglar`. + +### A note on `kontakt`, `stiftlist` and `plint` + +HALMET puts *connector* and *header* side by side far more often than HALPI2 does +— *1-Wire header connector*, *I2C header connector*, *analog input connectors*. +The shared split is kept: `kontakt` / `anslutning` for a connector, `stiftlist` +for a pin header. Where the English doubles the words (*header connector*), use +`stiftlist` alone — Swedish does not need both. The pluggable input connectors +are `plintar` (`löstagbar kopplingsplint`), and the one in the enclosure wall is +a `panelkontakt`. + +### Numbers on HALMET pages + +The shared units table applies unchanged. Three forms occur only in this +repository: + +| English source | Swedish | +|:---------------|:--------| +| `320 ohms`, `100 kohm` | `320 Ω`, `100 kΩ` | +| `+/- 30 V`, `-32V and +32V` | `±30 V`, `−32 V och +32 V` | +| `2x10 pin`, `4-pin` | `2×10 stift`, `4-poligt` | + +## Verification + +A translated page is not done until: + +1. `uv run mkdocs build --strict` passes. +2. `uv run python scripts/check_anchors.py site` passes. +3. `uv run python scripts/translation_status.py` shows the page as current. +4. `uv run python scripts/check_glossary.py sv` passes — it catches a prescribed + term the pages never actually use. +5. `uv run python scripts/check_typography.py sv` passes. +6. Structure matches the source — see `.claude/skills/translate-page/SKILL.md`. +7. Every term used on the page that appears in this glossary matches it. +8. **The four rules at the top are tested against the pages, not re-read.** A + half-applied typography rule looks followed when you read it. Both the French + and German branches shipped one to review because it was read rather than + measured. + +## Related + +- `finnish-glossary.md` — the sibling adapted for HALMET first +- `.claude/skills/translate-page/SKILL.md` — the procedure +- The HALPI2 repository's `solutions/translation/swedish-glossary.md` — the + source of every row above the HALMET heading; a shared row changes in both + files or in neither