Spannung

Spannung ist ein Steuerungs- und Monitorprogramm für einen Raspberry Pi. Die Anwendung liest Spannungen über ADS1115-Bausteine am I²C-Bus und stellt die Messwerte sowie die Relaissteuerung über eine HTTPS-Weboberfläche bereit.

Die Anwendung ist für den Betrieb auf dem Raspberry Pi vorgesehen. Die Entwicklung und die lokalen Builds erfolgen auf einem Ubuntu-PC.

Aktueller Stand

Aktuelle Release-Version:

v0.2.8

Die Version wird nicht mehr über eine version.json verwaltet, sondern über Git-Tags. Der Build übernimmt die Versions- und Buildinformationen über Go-Linker-Flags.

Voraussetzungen

Entwicklung / lokaler Build

Für die lokale Entwicklung und den lokalen Build werden benötigt:

• Ubuntu/Linux
• Go
• Git
• die benötigten ARM-Cross-Compiler
• lokale Raspberry-Pi-Sysroots:
  • sysroot-arm64
  • sysroot-arm32

Die Sysroots enthalten die für Spannung benötigten projektspezifischen Bibliotheken, insbesondere libusb und libudev.

Raspberry Pi

Unterstützt werden:

• Linux ARM64
• Linux ARMv7

Die Anwendung benötigt den I²C-Bus und die angeschlossenen ADS1115-Bausteine.

Vor dem Start prüft der systemd-Dienst, ob die ADS1115 unter den erwarteten I²C-Adressen 0x48 und 0x49 erreichbar sind.

Projektstruktur

Spannung/
├── main.go
├── web/
│   ├── server.go
│   └── static/
│       └── index.html
├── configs/
│   └── config.json
├── systemd/
│   └── Spannung.service.in
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   ├── install.sh
│   └── uninstall.sh
├── get_lib_ARM.sh
├── sysroot-arm32/
├── sysroot-arm64/
└── build/

build/ und app/ sind erzeugte Verzeichnisse und werden nicht versioniert.

Das Skript get_lib_ARM.sh dient zum lokalen Herunterladen bzw. Aktualisieren der benötigten ARM-Bibliotheken für die Cross-Kompilierung.

Konfiguration

Die Konfiguration befindet sich im Repository unter:

configs/config.json

Bei der Installation wird sie nach:

/opt/Spannung/config.json

installiert.

Die Konfiguration enthält unter anderem:

• HTTPS-Adresse und Port
• Zertifikats- und Schlüsseldateien
• Relaiskonfiguration
• ADS1115-Konfiguration
• System-/Simulationsoptionen
• die optionale Anbindung an raspi-agent

Zertifikate

Spannung stellt die Weboberfläche über HTTPS bereit.

Die Release-Pakete enthalten keine Zertifikate und keine privaten Schlüssel. Das Zertifikat wird auf dem jeweiligen Raspberry Pi selbst erzeugt oder dort anderweitig bereitgestellt. Dies ist insbesondere für Server im Tailscale-VPN vorgesehen, die keinen Zugriff auf Let's Encrypt benötigen.

Nach der Installation werden die Zertifikate unter

/opt/Spannung/certs/

erwartet:

/opt/Spannung/certs/cert.pem
/opt/Spannung/certs/key.pem

Selbst signiertes Zertifikat erzeugen

Das Zertifikatsverzeichnis anlegen:

sudo mkdir -p /opt/Spannung/certs

Anschließend ein selbst signiertes Zertifikat erzeugen:

sudo openssl req -x509 -newkey rsa:4096 \
    -keyout /opt/Spannung/certs/key.pem \
    -out /opt/Spannung/certs/cert.pem \
    -sha256 \
    -days 3650 \
    -nodes

Als Common Name (CN) sollte der Hostname verwendet werden, unter dem der Raspberry Pi im VPN erreichbar ist, beispielsweise:

raspi51

oder der entsprechende DNS-/Tailscale-Hostname.

Danach die Zugriffsrechte setzen:

sudo chmod 644 /opt/Spannung/certs/cert.pem
sudo chmod 600 /opt/Spannung/certs/key.pem

Der private Schlüssel darf nicht allgemein lesbar sein.

Wichtig: Die Zertifikate gehören zum jeweiligen Server und werden nicht in das Git-Repository übernommen. Bei einer Aktualisierung von Spannung bleiben vorhandene Zertifikate erhalten.

Build

Der lokale Build erfolgt mit:

./scripts/build.sh

Erzeugt werden:

build/linux-arm64/Spannung
build/linux-arm64/Spannung.sha256

build/linux-arm-v7/Spannung
build/linux-arm-v7/Spannung.sha256

Der Build führt vorher unter anderem gofmt, go test ./... und go mod tidy aus.

Deployment

scripts/deploy.sh ist für den lokalen bzw. manuellen Deployment-Ablauf vorgesehen.

Der Forgejo-CI-Job verwendet deploy.sh nicht direkt. Die CI enthält stattdessen ihre eigene Release-Paketierung und veröffentlicht das fertige Release auf dem Forgejo-Server.

Release

Die Release-Pakete enthalten beide Raspberry-Pi-Versionen. Die passende Binary wird erst auf dem Zielsystem durch install.sh anhand der Systemarchitektur ausgewählt.

Ein Release enthält unter anderem:

Spannung-vX.Y.Z/
├── bin/
│   ├── Spannung-arm64
│   ├── Spannung-arm64.sha256
│   ├── Spannung-arm-v7
│   └── Spannung-arm-v7.sha256
├── config/
│   └── config.json
├── systemd/
│   └── Spannung.service.in
├── web/
│   └── static/
│       └── index.html
├── install.sh
└── uninstall.sh

Zertifikate und private Schlüssel sind nicht Bestandteil des Release-Pakets.

Die Release-ZIP-Datei und ihre SHA256-Prüfsumme werden automatisch erzeugt.

Installation

Nach dem Herunterladen und Entpacken eines Releases:

cd Spannung-vX.Y.Z
sudo ./install.sh

Das Installationsverzeichnis ist:

/opt/Spannung/

Wichtige Dateien:

/opt/Spannung/bin/Spannung
/opt/Spannung/config.json
/opt/Spannung/certs/cert.pem
/opt/Spannung/certs/key.pem
/opt/Spannung/web/static/index.html
/opt/Spannung/log/Spannung.log

Das Installationsskript wählt automatisch die für den Raspberry Pi passende Binary.

Vorhandene Zertifikate werden bei einer Aktualisierung nicht überschrieben.

Der Dienst heißt:

Spannung.service

Status prüfen:

sudo systemctl status Spannung.service

Logs anzeigen:

sudo journalctl -u Spannung.service

Deinstallation

Auf dem Raspberry Pi kann die Anwendung mit dem mitgelieferten Skript deinstalliert werden:

sudo ./uninstall.sh

Die serverbezogenen HTTPS-Zertifikate werden dabei gemäß der vorgesehenen Installationsstruktur erhalten.

Versionsverwaltung

Releases werden über Git-Tags gekennzeichnet.

Beispiel:

git tag -a v0.2.8 -m "Version 0.2.8"
git push origin main
git push origin v0.2.8

Bei einem exakt getaggten Commit verwendet scripts/build.sh den Tag als Version:

v0.2.8

Bei einem Entwicklungsstand ohne Tag wird die Version als

dev-<commit>

angezeigt, beispielsweise:

dev-d7ce6e5

Die Version und das Build-Datum werden beim Kompilieren per Go-Linker-Flags in die Anwendung eingebaut.

CI/CD

Die automatisierte Build- und Release-Erstellung erfolgt über Forgejo Actions.

Die CI verwendet die zentral gepflegte Docker-Buildumgebung go-fyne:1.25. Diese enthält die allgemeine Go-/Fyne-Buildumgebung, fyne-cross sowie die Cross-Compiler für die unterstützten Zielplattformen.

Der Container ist als zentrale, projektübergreifend nutzbare Kompilierungsumgebung vorgesehen. Die enthaltenen Werkzeuge sind nicht auf Spannung beschränkt und können auch von anderen Projekten genutzt werden.

Projektbezogene Abhängigkeiten

Für Spannung werden wegen des USB-Zugriffs über gousb zusätzlich die Bibliotheken libusb und libudev benötigt.

Die dafür erforderlichen Header, Bibliotheken und pkg-config-Dateien liegen in den versionierten Projektsysroots:

sysroot-arm64/
sysroot-arm32/

Diese projektspezifischen Abhängigkeiten werden nicht in den zentralen Build-Container installiert.

Damit gilt:

Zentrale Build-Umgebung
    ├── Go
    ├── Fyne / fyne-cross
    ├── ARM64-Crosscompiler
    └── ARMv7-Crosscompiler

Projekt Spannung
    ├── sysroot-arm64
    │   └── libusb / libudev
    └── sysroot-arm32
        └── libusb / libudev

Automatischer CI-Ablauf

Die CI führt die notwendigen Prüfungen und Builds selbstständig aus:

1. Repository auschecken
2. Go-Code prüfen
3. Go-Tests ausführen
4. Go-Module bereinigen
5. Linux ARM64 bauen
6. Linux ARMv7 bauen
7. SHA256-Prüfsummen erzeugen
8. Release-Paket zusammenstellen
9. Release-ZIP und SHA256-Prüfsumme erzeugen

Bei einem normalen Push wird der komplette Build- und Paketierungsablauf ausgeführt.

Bei einem Git-Tag der Form

vX.Y.Z

wird zusätzlich automatisch ein Forgejo Release erstellt und die erzeugte Release-ZIP-Datei sowie deren SHA256-Prüfsumme als Release-Artefakte hochgeladen.

Die CI installiert die Anwendung nicht automatisch auf einem Raspberry Pi.

Die Installation bzw. Deinstallation bleibt eine bewusste manuelle Aktion des Anwenders:

sudo ./install.sh

bzw.:

sudo ./uninstall.sh

Lizenz

GPL-3.0-or-later