diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..784bc2d --- /dev/null +++ b/AGENTS.md @@ -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//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/` 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. diff --git a/HERMS b/HERMS index 8c78b80..3f6e233 160000 --- a/HERMS +++ b/HERMS @@ -1 +1 @@ -Subproject commit 8c78b80131377bdb74e2f263bc00ee2c3fbc6abb +Subproject commit 3f6e2338199592e6bac385e6e2c338b48ce19707 diff --git a/README.md b/README.md index f3f932d..2fc3727 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/cluster-infra b/cluster-infra index ed9368f..8361b26 160000 --- a/cluster-infra +++ b/cluster-infra @@ -1 +1 @@ -Subproject commit ed9368f67677d8e1b3bfca15b2c430c76e520994 +Subproject commit 8361b26997831098bcdffd2574b8498c5988373b diff --git a/docs/README.md b/docs/README.md index e014469..6e1fc96 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/grasmaaier.md b/docs/grasmaaier.md new file mode 100644 index 0000000..14dcdbc --- /dev/null +++ b/docs/grasmaaier.md @@ -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`
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 +``` diff --git a/docs/repositories.md b/docs/repositories.md index ab82726..25e7d9b 100644 --- a/docs/repositories.md +++ b/docs/repositories.md @@ -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. diff --git a/k8s-infra-vmserver b/k8s-infra-vmserver index 2562dd2..5bdc869 160000 --- a/k8s-infra-vmserver +++ b/k8s-infra-vmserver @@ -1 +1 @@ -Subproject commit 2562dd23d165025f7a7fe4de30efc5a7d4d046dd +Subproject commit 5bdc86934756ee8fc720ca1bae38b9df1e4921a3