Externe Sensor-API

Überblick

Über die Weather-API kannst du externe Sensoren wie Wetterstationen, SQM-Meter oder andere Messgeräte an deine Kamera ankoppeln. Die Messwerte werden in der zentralen InfluxDB gespeichert und können in Grafana, auf der Kameraseite oder in eigenen Auswertungen verwendet werden.

Die API ist bewusst schlank gehalten: Du sendest einen Zeitstempel, einen Namen für den Sensor und ein freies Feld-Objekt mit Messwerten.

Zugang & API-Key

Die API ist nur für Kameras im AllskyKamera Netzwerk gedacht. Der API-Key entspricht dem Secret-Key der jeweiligen Kamera und verknüpft die Messdaten eindeutig mit der Kamera.

Endpoint & Authentifizierung

Der API-Key wird ausschließlich über den HTTP-Header übertragen und sollte niemals in öffentlichen Repositories oder Clients veröffentlicht werden.

Request-Struktur

Der Request erfolgt als JSON-Body per POST. Der Aufbau ist generisch gehalten, damit du beliebige numerische Messwerte senden kannst.

Beispiel-Request (JSON)

{
  "timestamp": "2025-01-01T23:15:00Z",
  "ext_sensor": "Test_Sensor",
  "fields": {
    "temp_c": 22.9,
    "hum_pct": 48.5,
    "pressure_hpa": 1002.8
  }
}

Felder im Request

• timestamp – Zeitstempel im ISO8601-Format in UTC (z. B. 2025-01-01T23:15:00Z).
• ext_sensor – Name deiner Sensorstation (frei wählbar, z. B. „Dachstation“, „Schulgarten“).
• fields – Objekt mit Messwerten als Schlüssel/Wert-Paare (nur Zahlenwerte).

Typische Feldnamen sind z. B. temp_c (°C), hum_pct (% relative Luftfeuchte) oder pressure_hpa (Luftdruck in hPa). Du kannst aber auch eigene Namen verwenden, z. B. mit Sensorkürzel wie BME280_temp_c oder DS18B20_temp_c, solange sie technisch zulässig sind.

Mehrere Sensoren in einer Station

Wenn deine Station aus mehreren Sensoren besteht (z. B. BME280, DS18B20, TSL2591), kannst du den Sensornamen in den Feldnamen verwenden. So bleiben die Werte später eindeutig zuordenbar – etwa BME280_temp_c, BME280_hum_pct oder DS18B20_temp_c.

Beispiel mit mehreren Sensoren

{
  "timestamp": "2025-01-01T23:20:00Z",
  "ext_sensor": "Dachstation",
  "fields": {
    "BME280_temp_c": 22.9,
    "BME280_hum_pct": 48.5,
    "DS18B20_temp_c": 21.3
  }
}

Antwort & Fehlercodes

Erfolgreiche Antwort (Beispiel)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok"
}

Fehlerhafte Anfrage (Beispiel)

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Missing fields (timestamp, fields)"
}

• 400 – Ungültiger Request (z. B. fehlende Felder wie timestamp oder fields).
• 401 – Fehlender oder ungültiger API-Key.
• 405 – Falsche HTTP-Methode (nur POST wird unterstützt).
• 500 – Interner Fehler auf Serverseite.

Limits & Nutzungskontingente

Um die Infrastruktur stabil zu halten, gibt es pro Kamera bestimmte Tages- und Monatslimits für API-Aufrufe. Diese Limits gelten automatisch für alle Kameras im Netzwerk.

Die Limits gelten pro Kamera. Wenn du dauerhaft höhere Messfrequenzen nutzen möchtest, kontaktiere bitte die Administration.

Beispiele

Achte darauf, dass du physikalisch sinnvolle Einheiten verwendest (z. B. °C, hPa, % rF). Die genaue Interpretation erfolgt später bei der Auswertung.

#!/usr/bin/env python3
import requests
from datetime import datetime, timezone

API_URL = "https://allskykamera.space/api/v1/weather.php"
API_KEY = "DEIN_GEHEIMER_KAMERA_KEY"

def main():
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

    payload = {
        "timestamp": timestamp,
        "ext_sensor": "Test_Sensor",
        "fields": {
            "temp_c": 22.9,
            "hum_pct": 48.5,
            "pressure_hpa": 1002.8
        }
    }

    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
    }

    resp = requests.post(API_URL, headers=headers, json=payload, timeout=10)
    print(resp.status_code, resp.text)

if __name__ == "__main__":
    main()

curl -X POST "https://allskykamera.space/api/v1/weather.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DEIN_GEHEIMER_KAMERA_KEY" \
  -d '{
    "timestamp": "2025-01-01T23:15:00Z",
    "ext_sensor": "Test_Sensor",
    "fields": {
      "temp_c": 22.9,
      "hum_pct": 48.5,
      "pressure_hpa": 1002.8
    }
  }'

#include <WiFi.h>
#include <HTTPClient.h>

const char* ssid     = "DEIN_WLAN";
const char* password = "DEIN_PASSWORT";

const char* apiUrl   = "https://allskykamera.space/api/v1/weather.php";
const char* apiKey   = "DEIN_GEHEIMER_KAMERA_KEY";

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("WLAN verbunden");
}

void loop() {
  if (WiFi.status() == WL_CONNECTED) {
    HTTPClient http;
    http.begin(apiUrl);
    http.addHeader("Content-Type", "application/json");
    http.addHeader("X-API-Key", apiKey);

    String payload = R"({
      "timestamp": "2025-01-01T23:15:00Z",
      "ext_sensor": "ESP32_Weather",
      "fields": {
        "temp_c": 23.4,
        "hum_pct": 51.2
      }
    })";

    int httpCode = http.POST(payload);
    String response = http.getString();

    Serial.printf("HTTP: %d\n", httpCode);
    Serial.println(response);

    http.end();
  }

  delay(60000); // alle 60 Sekunden
}

Verwendung auf der Kameraseite

Die über die API gesendeten Messwerte landen zunächst nur in der InfluxDB. Im User-Bereich kannst du festlegen, welche Sensoren auf deiner Kameraseite angezeigt werden, wie sie heißen und in welchen Gruppen sie dargestellt werden.

1. Melde dich in deinem User-Bereich an und öffne den Bereich „Externe Sensoren“. Dort findest du eine Kachel mit dem Button „Sensor-Konfiguration öffnen“.
2. In der Sensor-Konfiguration siehst du alle Felder, die deine Station per API gesendet hat. Für jedes Feld kannst du einen Anzeigenamen, eine Gruppe und eine Einheit vergeben sowie festlegen, ob der Sensor aktiv ist und auf der Webseite angezeigt werden soll.
3. Nach dem Speichern erscheint auf deiner Kameraseite ein Bereich „Eigene Sensoren“. Die Diagramme werden nach Gruppe sortiert angezeigt (z. B. „Wetter“, „GY-21“). Nur Sensoren mit gesetztem Häkchen bei „Sensor anzeigen“ werden dort dargestellt.

1. Externe Sensoren im User-Bereich

Im User-Profil kannst du die Konfiguration für externe Sensoren öffnen.

2. Sensor-Konfiguration

In der Sensor-Konfiguration vergibst du Anzeigenamen, Gruppen, Einheiten und Sichtbarkeit.

3. Anzeige auf der Kameraseite

Auf der Kameraseite werden die ausgewählten Sensoren gruppiert als Diagramme angezeigt.

Tipp: Nutze sinnvolle Gruppen und klare Anzeigenamen (z. B. „Wetter“, „GY-21“, „Innenraum“), damit Zuschauer deine Messwerte auf einen Blick verstehen.