grasmaaier

2026-10-29 15:51:23 +01:00
parent 40640247db
commit 7f2d2b64c3
8 changed files with 240 additions and 3 deletions
@@ -0,0 +1,18 @@
+# Cluster Repository & GitOps Guidelines
+
+## GitOps & CI/CD Pipeline
+- **`k8s-infra-vmserver` is een pure GitOps target-repository:**
+  - Breng **nooit** direct handmatige wijzigingen of commits aan in `k8s-infra-vmserver/workloads/cluster-infra/` (of andere componenten die via CI/CD beheerd worden).
+  - Dit voorkomt configuratie-drift en mergeconflicten met de geautomatiseerde deployment bots (`Gitea Actions Bot`).
+- **Single Source of Truth is `cluster-infra/`:**
+  - Wijzigingen aan Kubernetes manifests voor infrastructuurdiensten (zoals Mosquitto, InfluxDB, PostgreSQL, DNSmasq, RabbitMQ, Telegraf, etc.) horen **uitsluitend** in `cluster-infra/<dienst>/k8s/`.
+  - Na een `git push` naar `cluster-infra` draait de Gitea Actions workflow (`.gitea/workflows/build-and-deploy.yaml`).
+  - Deze workflow synct gewijzigde manifests automatisch naar `k8s-infra-vmserver/workloads/cluster-infra/<dienst>` met het commitbericht `ci(cluster-infra): sync manifests (...)`.
+  - ArgoCD detecteert de commit in `k8s-infra-vmserver` en synct de workloads naar het live Kubernetes cluster.
+- **Overige submodules (`HERMS`, `htpc`, `smart-home`):**
+  - Pas ook voor deze componenten altijd de configuratie aan in de respectievelijke bronrepository en laat de build/sync-workflows of migratiescripts het werk doen.
+
+## Topologie & Omgeving
+- Host `vmserver`: IP `10.2.0.4` (K3s/Kubernetes node).
+- Kubelet health probes (`readinessProbe` / `livenessProbe`) verbinden vanaf node-IP `10.2.0.4`.
+- Edge reverse proxy (Apache) draait native op `vmserver` (`10.2.0.4`) vóór Envoy Gateway / hostdiensten.
@@ -117,4 +117,5 @@ Alle gedetailleerde platformdocumentatie bevindt zich in de map **[`docs/`](file
 * 📊 **[Live Cluster Status](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele hardware-specs, namespaces, pods, PVCs en routes op `10.2.0.4`.
 * 🛡️ **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: VHosts configuraties, SSL terminatie en OIDC authenticatie.
 * 📦 **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Mappenstructuur, protocollen (MQTT/NATS) en microservices.
+* 🚜 **[Grasmaaier Automatisering (OpenMower / Mowgli)](file:///home/bart/git/cluster/docs/grasmaaier.md)**: Yardforce 500 robotmaaier met Mowgli, ROS Noetic, RTK GPS, Docker stack en MQTT-koppeling.
 * 💡 **[Developer & Agent Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Handige commando's, git conventies en valkuilen.
@@ -26,4 +26,5 @@ De werkmap `/home/bart/git/cluster` is een centrale **Git meta-repository** (sup
 * **[Live Cluster Status (10.2.0.4)](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele status, node-specificaties, namespaces, pods, PVCs en HTTPRoutes van het actieve cluster.
 * **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: Details over Apache op `10.2.0.4`, `/sites/vhosts`, TLS/OIDC terminatie en koppeling naar Envoy Gateway (NodePort 32608).
 * **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Gedetailleerde beschrijving van alle componenten, mappen, protocollen (MQTT, NATS) en functies.
+* **[Grasmaaier Automatisering (OpenMower / Mowgli)](file:///home/bart/git/cluster/docs/grasmaaier.md)**: Yardforce 500 robotmaaier met Mowgli, ROS Noetic, RTK GPS, Docker stack, MQTT bridge en netwerkconfiguratie.
 * **[AI Cheatsheet & Developer Richtlijnen](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Snelle referentie voor commando's, submodule workflows, conventies en valkuilen.
@@ -0,0 +1,216 @@
+# Grasmaaier Automatisering (OpenMower / Mowgli)
+
+Documentatie van de autonome robotmaaier (**`mowerv2`**) binnen het homelab netwerk en de integratie met het centrale Kubernetes cluster en Home Assistant.
+
+---
+
+## 🧭 Inhoudsopgave
+
+- [Overzicht](#-overzicht)
+- [Hardware & Componenten](#-hardware--componenten)
+- [Netwerk & Verbinding](#-netwerk--verbinding)
+- [Software Architectuur (Docker & ROS)](#-software-architectuur-docker--ros)
+- [Cluster & Smart Home Integratie](#-cluster--smart-home-integratie)
+- [Onderhoud & Troubleshooting](#-onderhoud--troubleshooting)
+
+---
+
+## 📌 Overzicht
+
+| Eigenschap | Waarde |
+| :--- | :--- |
+| **Hostname** | `mowerv2` / `mowerv2.lan` |
+| **IP-adres** | `10.2.1.10` (statisch IPv4 /16, gateway: `10.2.0.1`) |
+| **Basis Robot** | Yardforce 500 |
+| **Controller Mainboard** | Mowgli (OpenMower drop-in STM32 PCB) |
+| **Boordcomputer** | Raspberry Pi 4 Model B Rev 1.5 (4GB RAM) |
+| **Besturingssysteem** | Ubuntu 24.04 LTS (Noble Numbat) aarch64 (Kernel 6.8.0-raspi) |
+| **MAC-adressen** | Wi-Fi (`wlan0`): `2C:CF:67:64:8E:9F`<br>Ethernet (`eth0`): `2C:CF:67:64:8E:9A` |
+| **SSID** | `brupjelan` (vastgezet op 2.4 GHz) |
+| **Web UI & App** | `http://10.2.1.10:3000` (OpenMower App) / Poort 4005 (Nginx) |
+
+---
+
+## 🛠️ Hardware & Componenten
+
+```mermaid
+flowchart TD
+    subgraph MowerChassis ["Yardforce 500 Chassis"]
+        Motors["Wiel- & Maaimotoren (BLDC + ESCs)"]
+        Sensors["Bumpers, Lift- & Noodstopsensoren"]
+        Mowgli["Mowgli Mainboard (STM32 MCU)"]
+        STLink["STM32 STLink Programmer (SWD)"]
+        GPS["RTK GPS Ontvanger (CH341 UART)"]
+        Pi["Raspberry Pi 4B (4GB)"]
+    end
+
+    Motors <--> Mowgli
+    Sensors --> Mowgli
+    STLink -.->|SWD Flashen| Mowgli
+    STLink <-->|USB /dev/bus/usb/001/00x| Pi
+    Mowgli <-->|USB CDC ACM /dev/mowgli| Pi
+    GPS <-->|USB Serial /dev/serial/by-id/usb-1a86_USB_Serial...| Pi
+    Pi <-->|Wi-Fi 2.4 GHz| LAN["Thuisnetwerk (10.2.0.0/16)"]
+```
+
+1. **Yardforce 500 Chassis**:
+   * Wielmotoren en maaimotoren aangedreven via borstelloze ESCs.
+   * Veiligheidssensoren (kantelsensor, optilsensor, bumper microswitches).
+2. **Mowgli Mainboard**:
+   * Open-source PCB ontworpen voor het OpenMower project ter vervanging van het originele Yardforce moederbord.
+   * Bevat een STM32-microcontroller die real-time motorbesturing en sensor-uitlezing uitvoert.
+   * Communiceert met de Raspberry Pi via USB CDC ACM (`/dev/mowgli` -> `/dev/ttyACM0`).
+3. **STM32 STLink Programmer**:
+   * Vaste onboard STLink-debugger aangesloten via USB.
+   * Maakt het mogelijk om de STM32 firmware direct vanaf de Pi te flashen met OpenOCD.
+4. **RTK GPS Ontvanger**:
+   * Biedt centimeter-nauwkeurige RTK-positionering voor de maaier.
+   * Aangesloten via CH341 USB-naar-serieel adapter (`ttyUSB0` op baudrate 460800).
+
+---
+
+## 📶 Netwerk & Verbinding
+
+### 1. Statische Netplan Configuratie
+De netwerkconfiguratie bevindt zich in `/etc/netplan/50-cloud-init.yaml`:
+```yaml
+network:
+  version: 2
+  wifis:
+    wlan0:
+      optional: true
+      dhcp4: false
+      dhcp6: false
+      link-local: [ ipv4 ]
+      addresses:
+        - 10.2.1.10/16
+      routes:
+        - to: default
+          via: 10.2.0.1
+      nameservers:
+        addresses:
+          - 192.168.2.11
+          - 1.1.1.1
+          - 8.8.8.8
+      access-points:
+        "brupjelan":
+          password: "..."
+          band: "2.4GHz"
+```
+
+### 2. 2.4 GHz Band Pinnen
+Om verbindingsdrops door band-steering (switchen tussen 2.4 GHz en 5 GHz) tijdens het rijden in de tuin te voorkomen, is `band: "2.4GHz"` ingesteld. Hierdoor genereert Netplan een strikte frequentielijst in `wpa_supplicant` (`freq_list` 2412 t/m 2484 MHz).
+
+### 3. Wi-Fi Power Management Permanente Fix
+Standaard schakelt de `brcmfmac` Wi-Fi-driver van de Raspberry Pi energiebeheer in, wat leidt tot gemiste frames en deauthentications. Dit is permanent uitgeschakeld via de systemd-service:
+* **Unit**: `/etc/systemd/system/wifi-powersave-off.service`
+* **Commando**: `/sbin/iwconfig wlan0 power off`
+
+---
+
+## 🐳 Software Architectuur (Docker & ROS)
+
+De volledige OpenMower runtime draait in Docker Compose onder `/root/mowgli-docker/docker-compose.yaml` (repository `github.com/brupje/mowgli-docker`).
+
+```mermaid
+flowchart LR
+    subgraph DockerMower ["mowerv2 Docker Stack"]
+        RosCore["mowgli-roscore (ROS Noetic)"]
+        RosSerial["mowgli-rosserial (/dev/mowgli)"]
+        OpenMower["mowgli-openmower (open_mower.launch)"]
+        GUI["openmower-gui (v2)"]
+        App["app (Web UI :3000)"]
+        MQTT["mowgli-mqtt (Mosquitto :1883)"]
+    end
+
+    RosSerial <-->|Topic I/O| RosCore
+    OpenMower <-->|Navigation & Planner| RosCore
+    GUI <-->|Status & Map DB| RosCore
+    App <-->|REST / WS| GUI
+    OpenMower -->|Telemetry| MQTT
+    MQTT <-->|Bridge| K8sMosquitto["Centrale Mosquitto (K8s: 10.2.0.4)"]
+```
+
+### Belangrijkste Containers
+
+| Container | Image | Poorten / Netwerk | Functie |
+| :--- | :--- | :--- | :--- |
+| **`mowgli-roscore`** | `ghcr.io/brupje/mowgli-docker:upstream` | `host` (:11311) | Centrale ROS Noetic Master broker |
+| **`mowgli-rosserial`** | `ghcr.io/brupje/mowgli-docker:upstream` | `host` | `rosserial_server` gekoppeld aan `/dev/mowgli` (115200 baud) |
+| **`mowgli-openmower`** | `ghcr.io/brupje/mowgli-docker:upstream` | `host` | Hoofdproces voor navigatie, padplanning en RTK GPS integratie |
+| **`openmower-gui`** | `ghcr.io/brupje/openmower-gui:v2` | `host` | Backend service voor kaart- en taakbeheer |
+| **`app`** | `ghcr.io/xtech/openmower-app:edge` | `3000:3000` | Moderne webinterface voor status en live kaart |
+| **`mowgli-web`** | `nginx` | `4005:80` | Webserver voor statische data en web assets |
+| **`mowgli-mqtt`** | `eclipse-mosquitto:latest` | `1883:1883`, `9001:9001` | Lokale MQTT broker voor status-uitwisseling |
+| **`watchtower`** | `containrrr/watchtower` | Geïsoleerd | Automatische updates voor OpenMower GUI images |
+
+---
+
+## 🔗 Cluster & Smart Home Integratie
+
+### 1. DNS (Dnsmasq)
+In `cluster-infra/dnsmasq/dns-records` op `vmserver` is de maaier geregistreerd:
+```text
+10.2.1.10 mowerv2.lan mowerv2
+fd00:2::1:10 mowerv2.lan mowerv2
+```
+
+### 2. MQTT Bridge (K8s Mosquitto -> Grasmaaier)
+In de centrale Mosquitto broker in het Kubernetes cluster (`cluster-infra/mosquitto/k8s/configmap.yaml`) is een actieve bridge geconfigureerd:
+```text
+connection mower
+address grasmaaier.lan:1883
+cleansession true
+local_cleansession true
+notifications true
+try_private true
+topic # both 0 grasmaaier/ ""
+```
+Alle telemetrie en commando's van de maaier worden gesynchroniseerd onder het MQTT-prefix `grasmaaier/#` (de maaier publiceert root-topics zoals `robot_state/json`, welke lokaal gemapt worden naar `grasmaaier/robot_state/json`).
+
+### 3. Home Assistant
+Binnen de `smart-home` submodule koppelt Home Assistant via de centrale MQTT-broker aan de `grasmaaier/#` topics om de actuele status (batterij, maaimodus, foutmeldingen, laadstatus) in te zien en automatiseringen te triggeren.
+
+---
+
+## 🔧 Onderhoud & Troubleshooting
+
+### 1. Inloggen via SSH
+Vanaf het werkstation of de `vmserver`:
+```bash
+ssh bart@10.2.1.10
+# of
+ssh bart@mowerv2.lan
+```
+
+### 2. STM32 Firmware Flashen
+Wanneer er een nieuwe firmware gebouwd is (`firmware.elf`), kan deze direct geflashed worden naar het Mowgli board via de onboard STLink:
+```bash
+cd /home/bart
+./upload.sh
+```
+*Dit script stopt tijdelijk de communicatie, gebruikt OpenOCD om de STM32 te wissen en te herprogrammeren, en reset de USB-bus (`1-1`).*
+
+### 3. Docker Containers Beheren
+```bash
+cd /root/mowgli-docker
+
+# Status controleren
+sudo docker compose ps
+
+# Herstarten van de stack
+sudo docker compose restart
+
+# Live logs van de maaier en planner bekijken
+sudo docker logs -f mowgli-openmower
+sudo docker logs -f mowgli-rosserial
+```
+
+### 4. Wi-Fi & Verbinding Controleren
+```bash
+# Linkkwaliteit en frequentie controleren (moet 2.4xx GHz zijn en Power Management: off)
+iwconfig wlan0
+
+# Controleren of powersave-off service actief is
+sudo systemctl status wifi-powersave-off.service
+```
@@ -57,6 +57,7 @@ Dit document bevat specifieke details over de vier repositories in deze workspac
 * **`dnsmasq/`**: Lokale DNS caching, DHCP en NTP-optie uitgifte.
 * **`ntp/`**: Lokale Chrony NTP tijdserver (UDP 123) voor LAN en IoT apparaten.
 * **`email-service/`**: Interne mailrelay / notificatiedienst.
+* **`label-service/`**: gLabels template rendering naar PDF, ZPL II en PNG via JSON API.
 * **`infra-web/`**: Dashboard/webinterface voor infrastructuurbeheer.
 * **`vhosts/`**: Apache/Nginx SSL en non-SSL reverse proxy configuraties voor bnhmeijer.nl domeinen.
 * **`argocd/`**: ApplicationSet configuratie voor automatische ontdekking van workloads.