- Go 64.4%
- HTML 20.8%
- Shell 14.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| configs | ||
| scripts | ||
| systemd | ||
| web | ||
| .gitattributes | ||
| .gitignore | ||
| CHANGELOG.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| main.go | ||
| README.md | ||
Steckdose
Steckdose ist eine schlanke Go-Anwendung für den Raspberry Pi. Sie schaltet vier Relais unabhängig voneinander über vier GPIO-Ausgänge und eine HTTPS-Weboberfläche.
Funktionsumfang
- Vier unabhängig schaltbare GPIO-Ausgänge
- HTTPS-Weboberfläche mit Statusanzeige und automatischer Aktualisierung
- Konfigurierbare Relaisnamen und GPIO-Zuordnung
- Builds für Linux amd64, ARM64, ARMv7 und ARMv6
- systemd-Dienst mit Installations- und Deinstallationsskript
- Versions- und Buildinformationen aus Git
Es gibt keine Spannungsmessung, keine ADS1115-Anbindung und keine USB-Relaiskarte.
GPIO-Belegung
Die Standardkonfiguration verwendet folgende GPIO-Ausgänge:
| Relais | Bezeichnung | GPIO |
|---|---|---|
| 1 | Steckdose 1 | GPIO5 |
| 2 | Steckdose 2 | GPIO6 |
| 3 | Steckdose 3 | GPIO13 |
| 4 | Steckdose 4 | GPIO16 |
Die Zuordnung kann in configs/config.json geändert werden. Die Namen müssen von der verwendeten GPIO-Bibliothek als Raspberry-Pi-GPIO erkannt werden. Beim Start werden alle vier Ausgänge auf LOW gesetzt; beim regulären Beenden versucht die Anwendung ebenfalls, alle Ausgänge auf LOW zu setzen.
Hinweis zur elektrischen Sicherheit: Die GPIOs dürfen keine Relais-Spulen direkt treiben, sofern die Relaisplatine dafür keine geeignete Treiber- und Schutzschaltung besitzt. Netzspannung darf nur mit dafür geeigneten, sicher isolierten Relaismodulen und fachgerechter Verdrahtung geschaltet werden. Die Software ersetzt keine elektrische Schutzmaßnahme.
Voraussetzungen
Entwicklung und Build
- Ubuntu/Linux
- Go 1.25 oder neuer
- Git
- Für die Cross-Builds die vorhandenen ARM-Compiler
aarch64-linux-gnu-gccundarm-linux-gnueabihf-gccsind nicht erforderlich, da die Anwendung ohne CGO gebaut wird. - Keine projektspezifischen USB-Sysroots oder
libusb-Entwicklungsdateien erforderlich.
Die CI verwendet die Build-Umgebung go-fyne:1.25-ci. Fyne ist für dieses Projekt selbst nicht erforderlich.
Raspberry Pi
Unterstützt werden:
- Linux ARM64 (
aarch64) - Linux ARMv7 (
armv7l) - Linux ARMv6 (
armv6l), getestet auf einem Raspberry Pi Zero W
Der Dienst benötigt Zugriff auf die konfigurierten GPIO-Ausgänge. Die Anwendung soll nicht als root laufen; notwendige administrative Einrichtung erfolgt einmalig bei Installation bzw. Hardwareeinrichtung.
Projektstruktur
Steckdose/
├── .forgejo/workflows/ci.yml
├── main.go
├── go.mod
├── go.sum
├── configs/config.json
├── web/
│ ├── server.go
│ └── static/index.html
├── systemd/Steckdose.service.in
├── scripts/
│ ├── install.sh
│ └── uninstall.sh
├── build/ # generierte Einzel-Builds
└── dist/ # generierte Release-Pakete
build/ und dist/ enthalten generierte Artefakte und werden nicht versioniert. Build, Paketierung und Veröffentlichung werden durch .forgejo/workflows/ci.yml gesteuert.
Konfiguration
Die Entwicklungskonfiguration liegt unter configs/config.json. Bei der Installation wird sie nach /opt/Steckdose/config.json kopiert. Eine vorhandene Zielkonfiguration wird bei Updates nicht überschrieben.
{
"web_port": ":8080",
"ssl_cert": "/opt/Steckdose/certs/cert.pem",
"ssl_key": "/opt/Steckdose/certs/key.pem",
"relais_pins": [
{"id": 1, "name": "Steckdose 1", "gpio": "GPIO5"},
{"id": 2, "name": "Steckdose 2", "gpio": "GPIO6"},
{"id": 3, "name": "Steckdose 3", "gpio": "GPIO13"},
{"id": 4, "name": "Steckdose 4", "gpio": "GPIO16"}
]
}
Die Konfiguration muss genau vier Relais mit eindeutigen IDs von 1 bis 4 enthalten. Alle Einträge müssen auf GPIO-Ausgänge verweisen.
HTTPS-Zertifikate
Zertifikate und private Schlüssel gehören nicht ins Git-Repository und werden nicht in Release-Pakete aufgenommen.
Standardpfade:
/opt/Steckdose/certs/cert.pem
/opt/Steckdose/certs/key.pem
Wenn diese Dateien fehlen, erzeugt der Webserver ein temporäres selbstsigniertes Zertifikat unter /tmp/Steckdose. Für den regulären Betrieb sollte ein dauerhaftes Zertifikat bereitgestellt werden.
Automatisierter Build und Release
Der gesamte Build- und Release-Ablauf wird durch .forgejo/workflows/ci.yml auf dem Forgejo-Server gesteuert. Builds und Releases werden nicht über separate lokale Build- oder Deploy-Skripte gestartet.
Auslöser des Workflows
Der Workflow läuft bei:
- Pull Requests: Prüfung und Build; es wird kein Release veröffentlicht.
- Pushes auf
main: Prüfung, Builds, Paketierung und Aktualisierung des Entwicklungs-Releasesdevelop. - Pushes eines Git-Tags mit Präfix
v(zum Beispielv0.1.0): Prüfung, Builds, Paketierung und Erstellung eines versionierten Releases.
Prüfungen und Build-Umgebung
Der Workflow verwendet den Forgejo-Runner go-fyne und führt die Go-Prüfungen sowie Cross-Builds in der Build-Umgebung go-fyne:1.25-ci aus. Fyne wird von Steckdose selbst nicht benötigt.
Vor dem Build prüft die CI:
- die Go-Formatierung mit
gofmt - die Konsistenz der Moduldateien mit
go mod tidy -diff - die Tests mit
go test ./...
Build-Ziele
Die CI erstellt mit CGO_ENABLED=0 folgende Linux-Builds:
| Ziel | Go-Architektur | Paketname |
|---|---|---|
| Linux amd64 | amd64 |
Steckdose-amd64 |
| Linux ARM64 | arm64 |
Steckdose-arm64 |
| Linux ARMv7 | arm, GOARM=7 |
Steckdose-arm-v7 |
| Linux ARMv6 | arm, GOARM=6 |
Steckdose-arm-v6 |
Für diese Builds sind keine ARM-Cross-Compiler, CGO-Toolchains, projektspezifischen USB-Sysroots oder libusb-Entwicklungsdateien erforderlich.
Die Anwendung erhält Versions- und Buildinformationen automatisch aus Git und dem Buildzeitpunkt. Bei einem exakten Git-Tag wird dieser Tag als Version verwendet; andernfalls lautet die Version dev-<commit>. Das Build-Datum wird in UTC gesetzt.
Für jedes Binary erzeugt die CI eine SHA256-Prüfsumme und kontrolliert, ob alle erwarteten Artefakte vorhanden sind.
Release-Paket
Die CI erstellt ein ZIP-Archiv Steckdose-<VERSION>.zip und eine zugehörige Datei Steckdose-<VERSION>.zip.sha256. Das Paket enthält:
- die vier Linux-Binaries samt SHA256-Prüfsummen im Verzeichnis
bin/ config/config.json- die systemd-Vorlage
systemd/Steckdose.service.in - die Weboberfläche
web/static/index.html install.shunduninstall.sh
Bei einem Push auf main wird das vorhandene Entwicklungs-Release develop ersetzt und mit dem neuesten Paket sowie dessen Prüfsumme veröffentlicht. Bei einem Push eines Tags wie v0.1.0 erstellt die CI ein reguläres versioniertes Forgejo-Release mit dem entsprechenden ZIP-Archiv und der Prüfsumme.
Deployment und Installation
Installation eines Releases auf dem Raspberry Pi
Die folgenden Schritte zeigen die Installation eines versionierten Releases auf dem Raspberry Pi. Dafür werden eine Netzwerkverbindung und die Programme wget und unzip benötigt. Das Beispiel verwendet v0.1.0; ersetze Tag und Dateiname bei Bedarf durch die gewünschte Version.
-
Installationsverzeichnis anlegen und wechseln:
mkdir -p ~/Steckdose_Installation cd ~/Steckdose_Installation -
Das Release-Paket herunterladen:
Dabei natürlich die jeweils aktuelle Version verwenden.
VERSION="v0.1.0"
ARCHIVE="Steckdose-${VERSION}.zip"
wget "https://git.lang-dieter.de/dieter/Steckdose/releases/download/${VERSION}/${ARCHIVE}"
-
Archiv entpacken und in das entpackte Verzeichnis wechseln:
unzip "${ARCHIVE}" cd "Steckdose-${VERSION}"Das laufend aktualisierte Entwicklungs-Release hat den Tag
develop. Sein Paketname enthält die automatisch erzeugte Build-Versiondev-<commit>; verwende dafür den exakten Dateinamen, der im Forgejo-Releasedevelopangezeigt wird. -
Installer mit Administratorrechten starten:
sudo ./install.shDer Installer richtet Steckdose unter
/opt/Steckdose/ein und installiert den systemd-Dienst. Die Anwendung läuft anschließend als eigener Benutzer und nicht dauerhaft mit root-Rechten. -
Den Dienststatus prüfen:
systemctl status Steckdose.service --no-pagerDer Status sollte
active (running)anzeigen. Bei Problemen können die letzten Meldungen mit folgendem Befehl angezeigt werden:sudo journalctl -u Steckdose.service -n 50 --no-pager
Weboberfläche öffnen
Die Standardkonfiguration verwendet Port 8080 und HTTPS. Im Browser wird die Adresse des Raspberry Pi aufgerufen:
https://<IP-Adresse-des-Raspberry-Pi>:8080
Bei einem selbstsignierten Zertifikat zeigt der Browser möglicherweise eine Zertifikatswarnung. Prüfe, ob die Adresse tatsächlich zu deinem Raspberry Pi gehört, bevor du fortfährst.
Im lokalen Netzwerk wird die LAN-IP-Adresse des Raspberry Pi verwendet. Wenn der Raspberry Pi über Tailscale beziehungsweise den eigenen Headscale-Server erreichbar ist, kann auch seine Tailscale-IP-Adresse verwendet werden. So lässt sich die Weboberfläche beispielsweise auf dem Handy über eine mobile Datenverbindung aufrufen, sofern das Handy ebenfalls mit dem eigenen Tailnet verbunden ist.
Automatischen Start prüfen
Der Dienst wird über systemd gestartet. Nach einem Neustart kann der Status erneut geprüft werden:
sudo reboot
Nach dem Neustart wieder anmelden und ausführen:
systemctl status Steckdose.service --no-pager
Wenn der Dienst active (running) meldet, sollte die Weboberfläche wieder erreichbar sein.
Installation aus einem vorbereiteten Paket
Wenn bereits ein Installationspaket vorliegt, wird es entpackt. Im entpackten Verzeichnis wird der Installer mit Administratorrechten gestartet:
sudo ./install.sh
Installationspfad: /opt/Steckdose/
Dienststatus und Logs
sudo systemctl status Steckdose.service
sudo journalctl -u Steckdose.service
Deinstallation
Im Verzeichnis eines vorbereiteten Installationspakets:
sudo ./uninstall.sh
Versionsverwaltung
Versionen werden mit Git-Tags gekennzeichnet. Commit-Nachrichten sollen deutsch formuliert werden.
git tag -a v0.1.0 -m "Erste Version von Steckdose"
git push origin main
git push origin v0.1.0
Ein Push auf main aktualisiert das Entwicklungs-Release develop. Das Pushen eines Tags mit Präfix v startet die Erstellung eines regulären Releases. Die Version wird durch .forgejo/workflows/ci.yml aus einem exakten Git-Tag ermittelt oder andernfalls als dev-<commit> gesetzt.
Lizenz
GPL-3.0-or-later