~ $ man lokale-api

Lokale API

Steuere deinen ORCA Controller oder ORCAlight Controller der ersten Generation direkt im Heimnetz: aus eigenen Skripten, aus Home Assistant, Node-RED oder einer eigenen App. Ohne Internet und ohne reefhub-Konto.

Überblick

Wozu?

Jeder Controller bringt eine kleine Web-Schnittstelle mit. Das ist dieselbe, die auch die lokale Einstellungsseite benutzt (siehe „Notfall Konfiguration“ in der Anleitung des ORCA Controllers bzw. des ORCAlight Controllers). Über sie kannst du Kanäle starten und stoppen, kalibrieren und Drehwinkel sowie Geschwindigkeit einstellen. Damit lassen sich zum Beispiel die Pumpen zur Fütterung anhalten oder abends langsamer schwenken.

Voraussetzungen

Der Controller ist mit deinem WLAN verbunden (Status-LED pulsiert grün), siehe „WiFi Einrichtung“ in der Anleitung.
Dein Rechner, Server oder Smart-Home-System ist im selben Heimnetz.
Die Adresse des Controllers: http://myorca-SERIENNUMMER.local, zum Beispiel http://myorca-3k1z5jm174.local. Die Seriennummer steht auf der Rückseite des Controllers.
Funktioniert der .local-Name in deinem Netz nicht, nimm die IP-Adresse. Die Web-App zeigt sie unter Meine ORCAs beim Gerät unter „Lokale IP“ an. Am besten gibst du dem Controller in deinem Router eine feste IP-Adresse.
Firmware: ORCA Controller 7.0.x, ORCAlight Controller 1.2.x. Welche Version dein Gerät hat, siehst du in der Web-App.

Sicherheit

Achtung Die Schnittstelle hat kein Passwort und läuft unverschlüsselt über HTTP. Jeder, der in deinem Heimnetz ist, kann den Controller damit steuern. Gib sie deshalb niemals per Portweiterleitung ins Internet frei. Für den Zugriff von unterwegs gibt es die Web-App.

Schnittstelle

Endpunkte

N ist die Nummer des Kanals: 1 bis 4 beim ORCA Controller, beim ORCAlight Controller immer 1.

Methode	Pfad	Wirkung
GET	/start?channel=N	Kanal starten
GET	/stop?channel=N	Kanal stoppen
GET	/selftest?channel=N	Kanal kalibrieren: Die Dreheinheit fährt ihre Endpunkte an.
POST	/save/channelN	Drehwinkel und Geschwindigkeit setzen und dauerhaft speichern. Formularfelder `channelN_min`, `channelN_max`, `channelN_speed`, einzeln oder zusammen.
GET	/restart	Controller neu starten
GET	/	Statusseite (HTML) mit Firmware-Version, Zustand und Einstellungen jedes Kanals

Werte und Antworten

Drehwinkel (channelN_min, channelN_max): ganze Zahlen von −90 bis 90. Wenn du von vorne auf die Dreheinheit siehst, ist rechts −90° und links 90°.
Geschwindigkeit (channelN_speed): ganze Zahl von 10 bis 200, wie in der Web-App.
Werte außerhalb dieser Bereiche ignoriert der Controller ohne Fehlermeldung.
Der Controller antwortet mit einer Weiterleitung (HTTP 302) auf die Statusseite, nach einer Kalibrierung auf eine kurze Warteseite. Eine Antwort im JSON-Format gibt es nicht. Den Zustand liest du aus der Statusseite.
Gespeicherte Werte gelten sofort und bleiben nach einem Neustart erhalten. Die Web-App liest die Einstellungen direkt vom Gerät und zeigt deshalb auch lokal geänderte Werte an.

Beispiele

Kommandozeile (curl)

# Kanal 1 stoppen und wieder starten
curl "http://myorca-3k1z5jm174.local/stop?channel=1"
curl "http://myorca-3k1z5jm174.local/start?channel=1"

# Kanal 2: von −60° bis 45° schwenken, Geschwindigkeit 40
curl -X POST "http://myorca-3k1z5jm174.local/save/channel2" \
     -d channel2_min=-60 -d channel2_max=45 -d channel2_speed=40

Home Assistant

Mit rest_command in der configuration.yaml werden daraus Aktionen, die du in Automationen und Skripten benutzen kannst, zum Beispiel „Fütterung: Pumpen 10 Minuten anhalten“:

rest_command:
  orca_stop:
    url: "http://myorca-3k1z5jm174.local/stop?channel={{ channel }}"
  orca_start:
    url: "http://myorca-3k1z5jm174.local/start?channel={{ channel }}"
  orca_set:
    url: "http://myorca-3k1z5jm174.local/save/channel{{ channel }}"
    method: post
    content_type: "application/x-www-form-urlencoded"
    payload: "channel{{ channel }}_min={{ min }}&channel{{ channel }}_max={{ max }}&channel{{ channel }}_speed={{ speed }}"

Aufruf in einer Automation: Aktion rest_command.orca_stop mit den Daten channel: 1.

Python

import requests

ORCA = "http://myorca-3k1z5jm174.local"

requests.get(f"{ORCA}/stop", params={"channel": 1}, timeout=5)
requests.post(f"{ORCA}/save/channel1",
              data={"channel1_min": -45, "channel1_max": 45, "channel1_speed": 60},
              timeout=5)
requests.get(f"{ORCA}/start", params={"channel": 1}, timeout=5)

Weiteres

Was nur die Web-App kann

Pausen, Sektoren, BOOST Mode, SmartCalibration, Firmware-Updates und das Zurücksetzen auf Werkseinstellungen sind über die lokale Schnittstelle nicht verfügbar. Dafür gibt es die Web-App.

Kontakt

Fragen oder ein schönes Projekt mit deiner ORCA gebaut? Schreib uns an info@reefhub.de.