Kamera verbinden: connect/v1
SharedSky › Für Entwickler
Mit dieser Schnittstelle kann jede Allsky-Kamera bei SharedSky mitmessen, egal mit welcher Software sie läuft: gekaufte Programme, eigene Skripte oder Bastelprojekte. Die Kamera schickt über HTTPS an den Hub. MQTT, FTP und Portfreigaben braucht es nicht. Den Vertrag dazu beschreibt SPEC §10.
Für indi-allsky reicht die Konfiguration, siehe unten. Allsky hat dafür ein Modul, siehe unten. Allsky und alle anderen Kameras, die ihr neuestes Bild unter einer festen Adresse zeigen, können sich auch ohne eigenen Code über diese Adresse verbinden („Allsky / Bild-Adresse“ bei Kamera verbinden).
Anmelden
Lege ein kostenloses Konto an und wähle Kamera verbinden. Danach zeigt dir der Hub einmal die Station-ID (26 Zeichen) und das Geheimnis (64 Hex-Zeichen). Ein neues Geheimnis kannst du jederzeit erzeugen, das alte gilt dann sofort nicht mehr. Jede Anfrage trägt den Header
Authorization: Bearer <Station-ID>:<Geheimnis>
Die Adresse ist https://allskyhub.org/api/connect/v1. Alle Zeiten sind ISO 8601 in UTC, zum Beispiel 2026-11-05T21:40:12Z.
1. Station melden: PUT /station
Beim Start und wenn sich etwas ändert:
{
"name": "Sternwarte Musterberg",
"latitude": 48.3, "longitude": 4.29, "elevation_m": 300,
"software": "MySky", "software_version": "1.2",
"lens": {"focal_mm": 1.55, "f_ratio": 2.0, "projection": "equidistant"},
"width": 3096, "height": 2080,
"clock_synced": true
}
width×heightist die Größe des vollen Bildes, so wie die Kamera es speichert, nach einem eventuellen Zuschnitt. Alle Pixelangaben beziehen sich auf dieses Bild; ändert sich die Größe, richtet der Hub die Kamera neu an den Sternen aus.clock_synced: Die Uhr läuft per NTP oder GPS. Der Hub prüft das zusätzlich an jedem Bild.
Antwort: {"orientation": null, "want_full_frame": false}
Die Ausrichtung. Sobald der Hub die Kamera an den Sternen ausgerichtet hat, steht in orientation: {north_deg, mirrored, solved_at, stars, rms_deg, lens: {cx, cy, a1, a3, tilt_east_deg, tilt_north_deg, width, height}}. north_deg ist die Bildrichtung von Norden am Horizont (0 = oben, im Uhrzeigersinn); mirrored heißt: Osten liegt gegen den Uhrzeigersinn von Norden, der übliche Blick einer Kamera nach oben. Eine Richtung (Höhe, Azimut) liegt bei t = (90° − Höhe) / 90°, r = a1·t + a3·t³, Winkel = north_deg − Azimut (gespiegelt) oder north_deg + Azimut, x = cx + r·sin(Winkel), y = cy − r·cos(Winkel), in Pixeln eines Bildes von width × height; bei einer geneigten Kamera wird die Richtung vorher um die Neigung gedreht (SPEC §4.8). Fertig in Python: sky_to_pixel() im Allsky-Modul, etwa für Sternbilder oder Himmelsrichtungen im eigenen Bild.
2. Bild schicken: POST /frames
Etwa einmal pro Minute, Multipart mit zwei Teilen:
metadata: JSON{"time", "exposure_s", "gain", "night", "clock_synced", "stars", "sky_brightness"};timeist die Mitte der Belichtung.image: JPEG, normalerweise ein Vorschaubild (höchstens 640 px an der langen Seite, 300 kB). Nur wenn die letzte Antwort"want_full_frame": trueenthielt, das volle Bild (höchstens 8 MB).
Antwort: {"want_full_frame": false}
3. Meteor melden: POST /events
Multipart: metadata als JSON und image, das volle Bild mit dem Meteor, genau width × height.
{
"kind": "meteor",
"start": "2026-11-05T21:40:00Z", "end": "2026-11-05T21:40:30Z",
"peak": 0.8,
"track": [[812, 431], [990, 502], [1140, 566]],
"clock_synced": true
}
track sind 2 bis 32 Punkte entlang der Spur, in Pixeln des vollen Bildes. peak (0 bis 1) ist optional; ohne ihn misst der Hub die Helligkeit selbst. Antwort: {"id": "meteor-20261105T214000Z"}
Testmodus
Unter /api/connect/v1/test/station, /test/frames und /test/events prüft der Hub jede Anfrage genauso, speichert aber nichts, und antwortet, was er verstanden hat: {"ok": true, "understood": {…}}. Damit lässt sich eine Anbindung gefahrlos ausprobieren.
Grenzen und Fehler
120 Anfragen pro Minute und Station. Der Hub sieht sich jedes Bild an und behält alle 5 Minuten ein Vorschaubild; pro Nacht höchstens 3000 Meteore, pro Station höchstens 500 MB (darüber fallen die ältesten vollen Bilder zuerst weg). Fehler kommen als {"error": "<code>"}:
| Status | error | Bedeutung |
|---|---|---|
| 400 | bad_request | ein Feld fehlt oder liegt außerhalb des Bereichs, dazu field |
| 400 | bad_image | kein lesbares JPEG |
| 400 | wrong_size | das volle Bild hat nicht width × height |
| 401 | unauthorized | unbekannte Station oder falsches Geheimnis |
| 413 | too_large | Bild zu groß |
| 429 | too_often / night_full | zu viele Anfragen oder Meteore in dieser Nacht, mit Retry-After |
Beispiel mit curl
AUTH="Authorization: Bearer $STATION_ID:$SECRET"
curl -X PUT https://allskyhub.org/api/connect/v1/station -H "$AUTH" \
-H 'Content-Type: application/json' -d @station.json
curl https://allskyhub.org/api/connect/v1/frames -H "$AUTH" \
-F 'metadata={"time":"2026-11-05T21:40:15Z","exposure_s":30,"night":true,"clock_synced":true};type=application/json' \
-F image=@thumb.jpg
Beispiel in Python
import json
import requests
BASE = "https://allskyhub.org/api/connect/v1"
AUTH = {"Authorization": f"Bearer {STATION_ID}:{SECRET}"}
requests.put(f"{BASE}/station", json=station, headers=AUTH, timeout=30).raise_for_status()
meta = {"time": "2026-11-05T21:40:15Z", "exposure_s": 30, "night": True, "clock_synced": True}
with open("thumb.jpg", "rb") as image:
r = requests.post(
f"{BASE}/frames",
headers=AUTH,
files={"metadata": (None, json.dumps(meta), "application/json"), "image": image},
timeout=30,
)
print(r.json()) # {"want_full_frame": false}
Allsky
Das SharedSky-Modul für das Modulsystem von Allsky schickt die Station, etwa einmal pro Minute ein kleines Bild, das volle Bild, wenn der Hub darum bittet, und jeden Meteor, den das Modul „Meteor Detection (temporal)“ gespeichert hat, mit seiner Spur. Kopiere allsky_sharedsky.py nach ~/allsky/config/myFiles/modules/, nimm es in den Tag- und Nacht-Ablauf auf (nachts nach der Meteorerkennung, vor dem Overlay), trage Station-ID und Geheimnis ein und drücke „Test“: Das Modul schickt dann an den Testmodus oben.
indi-allsky
indi-allsky braucht keine Installation. In der Konfiguration unter SyncAPI: einschalten, Base URL https://allskyhub.org/indi-allsky, Username die Station-ID, API Key das Geheimnis, Bilder synchronisieren: jedes Bild. indi-allsky schickt dann mit jedem Bild Standort, Objektiv, Belichtung, Sternzahl und die Zahl erkannter Meteorspuren.
Was mit den Daten passiert
- Bilder bleiben deine. Der Hub zeigt sie nur dort, wo du es erlaubst, und immer mit dem Namen der Station.
- Messwerte (Zeiten, Spuren, Bahnen, Raten, Himmelshelligkeit) teilt der Hub unter CC BY 4.0 mit dem Namen der Station; nur so kann er sie an wissenschaftliche Partner weitergeben.
- Standort: Der genaue Ort dient nur der Rechnung, öffentlich steht er immer gerundet.