IronFlock SDK

Das IronFlock SDK ermöglicht Ihren Edge-Anwendungen die Interaktion mit der IronFlock-Plattform. Es übernimmt die Authentifizierung automatisch, wenn es auf einem registrierten Gerät ausgeführt wird, und bietet Funktionen zum Veröffentlichen von Daten, Abfragen von Verlaufsdaten, Aufrufen von Remote-Prozeduren über Geräte hinweg sowie zum Aktualisieren von Gerätemetadaten.

Installation

pip install ironflock

npm install ironflock

Schnellstart

import asyncio
from ironflock import IronFlock
 
async def main():
    while True:
        await ironflock.publish_to_table("sensordata", {
            "temperature": 22.5,
            "humidity": 60
        })
        await asyncio.sleep(5)
 
ironflock = IronFlock(mainFunc=main)
ironflock.run()

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock();
await ironflock.start();
 
setInterval(async () => {
    await ironflock.publishToTable("sensordata", [{
        temperature: 22.5,
        humidity: 60
    }]);
}, 5000);

Bei Verwendung innerhalb eines IronFlock-App-Containers liest das SDK die Verbindungsdaten automatisch aus der Umgebung — keine manuelle Konfiguration erforderlich.

Konstruktor-Optionen

ironflock = IronFlock(
    mainFunc=main,           # async function to run after connecting
    serial_number="abc123"   # override device serial (optional)
)

const ironflock = new IronFlock({
    serialNumber: "abc123",    // device serial (env: DEVICE_SERIAL_NUMBER)
    deviceKey: "dev-key-1",    // device key (env: DEVICE_KEY)
    appName: "MyApp",          // app name (env: APP_NAME)
    swarmKey: 10,              // project key (env: SWARM_KEY)
    appKey: 20,                // app key (env: APP_KEY)
    env: "PROD",               // "DEV" or "PROD" (env: ENV)
});

Daten veröffentlichen

publishToTable / publish_to_table

Veröffentlicht einen Datensatz in einer Fleet-Tabelle. Der Tabellenname muss einer in der data-template.yml Ihrer App definierten Tabelle entsprechen. Das SDK leitet die Daten automatisch an die richtige Projektdatenbank weiter.

await ironflock.publish_to_table("sensordata", {
    "temperature": 22.5,
    "humidity": 60,
    "device_id": "sensor-001"
})

await ironflock.publishToTable("sensordata", [{
    temperature: 22.5,
    humidity: 60,
    device_id: "sensor-001"
}]);

appendToTable / append_to_table

Fügt Daten über einen Remote Procedure Call anstelle von Pub/Sub an eine Fleet-Tabelle an. Verwenden Sie dies, wenn Sie eine Bestätigung benötigen, dass die Daten gespeichert wurden.

result = await ironflock.append_to_table("sensordata", {
    "temperature": 22.5,
    "humidity": 60
})

const result = await ironflock.appendToTable("sensordata", [{
    temperature: 22.5,
    humidity: 60
}]);

publishRowsToTable / publish_rows_to_table

Veröffentlicht mehrere Zeilen in einer einzigen Nachricht (Bulk-Insert) in einer Fleet-Tabelle. Die Plattform fügt den gesamten Stapel atomar (Alles-oder-nichts) in einem einzigen Vorgang ein. Verwenden Sie dies für hochfrequente Daten, bei denen ein Roundtrip pro Zeile zu kostspielig wäre. Wie publishToTable erfolgt dies nach dem Fire-and-Forget-Prinzip — die Bestätigung bestätigt die Zustellung an den Router, nicht den Datenbank-Insert.

await ironflock.publish_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])

await ironflock.publishRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);

Das zweite Argument ist eine nicht leere Liste von einzufügenden Zeilenobjekten.

appendRowsToTable / append_rows_to_table

Hängt mehrere Zeilen in einem einzigen Remote Procedure Call (Bulk-Insert) an eine Fleet-Tabelle an. Die Plattform fügt den gesamten Stapel atomar (Alles-oder-nichts) ein: Ist eine Zeile ungültig, wird der gesamte Stapel abgelehnt und nichts wird gespeichert. Bevorzugen Sie dies gegenüber publishRowsToTable / publish_rows_to_table, wenn Sie das Ergebnis des Inserts benötigen.

result = await ironflock.append_rows_to_table("sensordata", [
    {"tsp": "2024-01-15T10:30:00.000Z", "temperature": 22.5},
    {"tsp": "2024-01-15T10:30:01.000Z", "temperature": 22.7},
])
# result -> {"success": True, "count": 2}

const result = await ironflock.appendRowsToTable("sensordata", [
    { tsp: "2024-01-15T10:30:00.000Z", temperature: 22.5 },
    { tsp: "2024-01-15T10:30:01.000Z", temperature: 22.7 },
]);
// result -> { success: true, count: 2 }

reportError / report_error

Meldet einen Anwendungsfehler in die error-logs-Tabelle Ihrer Fleet. Dies ist ein komfortabler Wrapper über publishToTable / appendToTable: Er versieht die Zeile mit source: "app", einem Schweregrad level und einem Zeitstempel und schreibt sie anschließend wie jede normale Tabellenzeile. Der Fehler landet in derselben error-logs-Tabelle, die auch fleetdb-Systemfehler verwenden (gekennzeichnet mit source: "system"), und ist somit mit getHistory abfragbar, mit subscribeToTable / subscribe_to_table streambar, in Board-Templates nutzbar und wird in Echtzeit auf transformed.error-logs zugestellt — ohne den System-Fehler-Toast der Plattform auszulösen.

# Fire-and-forget (default): publishes to the error-logs table
await ironflock.report_error("Sensor read timed out", level="warn")
 
# Pass an exception to capture its traceback (falls back to the message)
try:
    risky_operation()
except Exception as err:
    await ironflock.report_error(err)
 
# Use the append RPC when you want to await the insert outcome
await ironflock.report_error("Calibration failed", level="error", append=True)

// Fire-and-forget (default): publishes to the error-logs table
await ironflock.reportError("Sensor read timed out", { level: "warn" });
 
// Pass an Error to capture its stack (falls back to the message)
try {
    riskyOperation();
} catch (err) {
    await ironflock.reportError(err);
}
 
// Use the append RPC when you want to await the insert outcome
await ironflock.reportError("Calibration failed", { level: "error", append: true });

Parameter:

In Python werden die Optionen als Keyword-Argumente übergeben (report_error(error, level=..., append=..., tsp=...)); in JavaScript werden sie über ein Optionsobjekt übergeben (reportError(error, { level, append, tsp })).

publish

Veröffentlicht eine Nachricht an ein beliebiges WAMP-Topic. Verwenden Sie dies für benutzerdefinierte Nachrichten oder Ereignisse, die keiner Datenbanktabelle zugeordnet sind.

await ironflock.publish("com.myapp.alerts", {
    "level": "warning",
    "message": "Temperature threshold exceeded"
})

await ironflock.publish("com.myapp.alerts", [{
    level: "warning",
    message: "Temperature threshold exceeded"
}]);

Historische Daten abfragen

getHistory

Ruft historische Daten aus einer Fleet-Tabelle ab. Unterstützt Filterung, Zeitbereiche und Paginierung.

# Simple query
data = await ironflock.getHistory("sensordata", {"limit": 100})
 
# Query with time range and filters
data = await ironflock.getHistory("sensordata", {
    "limit": 500,
    "offset": 0,
    "timeRange": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-03-01T00:00:00Z"
    },
    "filterAnd": [
        {"column": "temperature", "operator": ">", "value": 20},
        {"column": "humidity", "operator": "<=", "value": 80}
    ]
})
 
# Current value(s) only: the "latest" marker returns the newest row per entity
current = await ironflock.getHistory("sensordata", {
    "limit": 100,
    "filterAnd": [{"latest": True}]
})

// Simple query
const data = await ironflock.getHistory("sensordata", { limit: 100 });
 
// Query with time range and filters
const data = await ironflock.getHistory("sensordata", {
    limit: 500,
    offset: 0,
    timeRange: {
        start: "2026-01-01T00:00:00Z",
        end: "2026-03-01T00:00:00Z",
    },
    filterAnd: [
        { column: "temperature", operator: ">", value: 20 },
        { column: "humidity", operator: "<=", value: 80 },
    ],
});
 
// Current value(s) only: the `latest` marker returns the newest row per entity
const current = await ironflock.getHistory("sensordata", {
    limit: 100,
    filterAnd: [{ latest: true }],
});

Abfrageparameter:

Filteroperatoren: =, !=, >, <, >=, <=, LIKE, ILIKE, IN, NOT IN, IS, IS NOT

Jeder Filter ist ein Objekt mit den Schlüsseln column, operator und value.

Aktuelle Werte lesen. Ein Eintrag {"latest": true} in filterAnd ist keine Filterbedingung, sondern ein Modusschalter: Das Daten-Backend gibt nur die neueste Zeile pro Entität zurück, in SQL abgeleitet aus dem Entitätsschlüssel, den die Tabelle mit maintainLatestFlagFor deklariert. Eine Tabelle ohne Entitätsschlüssel gibt ihre einzelne aktuellste Zeile zurück.

Andere Bedingungen lassen sich wie erwartet mit dem Marker kombinieren: Bedingungen auf Spalten des Entitätsschlüssels schränken ein, welche Entitäten zurückgegeben werden, während alle übrigen Bedingungen und timeRange auf die resultierenden neuesten Zeilen angewendet werden. Die Kombination von {"latest": true} mit einem deleted-Filter blendet gelöschte Entitäten also aus, statt deren vorherige Zeile wieder auftauchen zu lassen.

Frühere Versionen von IronFlock speicherten eine physische Spalte latest_flag. Diese existiert nicht mehr — ein alter Filter latest_flag = true wird weiterhin akzeptiert und als Marker behandelt, neuer Code sollte aber {"latest": true} verwenden. Der latest-Marker steht in getSeriesHistory nicht zur Verfügung.

getSeriesHistory / get_series_history

Ruft heruntergerechnete Zeitreihendaten aus einer Fleet-Tabelle ab: numerische Spalten, die in Zeitfenster aggregiert werden (z. B. stündliche Durchschnittswerte). Ideal für Diagramme über lange Zeiträume. Für Tabellen verfügbar (nicht für Transforms).

series = await ironflock.get_series_history("sensordata", {
    "metrics": ["temperature", "humidity"],
    "method": "AVG",
    "limit": 500,
    "timeRange": ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    "groupBy": ["device_id"]
})

const series = await ironflock.getSeriesHistory("sensordata", {
    metrics: ["temperature", "humidity"],
    method: "AVG",
    limit: 500,
    timeRange: ["2026-01-01T00:00:00Z", "2026-03-01T00:00:00Z"],
    groupBy: ["device_id"],
});

Abfrageparameter:

Daten abonnieren

subscribeToTable / subscribe_to_table

Abonniert Echtzeit-Updates einer Fleet-Tabelle. Der Handler wird aufgerufen, wenn neue Daten in der Tabelle veröffentlicht werden. Zeilen, die über den Bulk-Insert-Pfad (publishRowsToTable / appendRowsToTable) geschrieben werden, werden Ihrem Handler einzeln zugestellt, sodass der Handler-Code unabhängig davon, wie die Daten geschrieben wurden, gleich bleibt.

def on_sensor_data(*args, **kwargs):
    print("New reading:", args, kwargs)
 
await ironflock.subscribe_to_table("sensordata", on_sensor_data)

function onSensorData(...args) {
    console.log("New reading:", args);
}
 
await ironflock.subscribeToTable("sensordata", onSensorData);

subscribe

Abonniert ein beliebiges WAMP-Topic für benutzerdefinierte Echtzeit-Kommunikation.

def on_alert(*args, **kwargs):
    print("Alert received:", args, kwargs)
 
await ironflock.subscribe("com.myapp.alerts", on_alert)

function onAlert(...args) {
    console.log("Alert received:", args);
}
 
await ironflock.subscribe("com.myapp.alerts", onAlert);

App-übergreifender Datenzugriff

Lesen Sie die Fleet-Daten einer anderen App aus Ihrer eigenen App heraus – innerhalb desselben Projekts. Die bereitstellende App muss Ihre App in ihrer data-template.yml im Abschnitt consumes: aufführen, und der Projektbenutzer muss den Zugriff gewähren. Der Zugriff ist schreibgeschützt: Sie können den Verlauf abfragen und Zeilen der vom Anbieter freigegebenen Tabellen und Transforms in Echtzeit abonnieren, aber nicht in sie schreiben. Verbindungen zu konsumierten Apps werden pro App zwischengespeichert und automatisch geschlossen, wenn Ihre Instanz stoppt.

Wenn Ihre App die Wildcard-Berechtigung besitzt (consumes: [{ app: "*" }]), können Sie Anbieter dynamisch mit listConsumableApps / list_consumable_apps und connectToAllApps / connect_to_all_apps (siehe unten) auffinden und öffnen.

connectToApp / connect_to_app

Öffnet eine schreibgeschützte Verbindung zum Data Backend einer anderen App und gibt ein Handle zurück. Das Handle stellt getHistory / get_history, subscribeToTable / subscribe_to_table und getSeriesHistory / get_series_history (nur Tabellen) bereit – dasselbe Abfragen und Abonnieren wie bei Ihren eigenen Tabellen – sowie close und die freigegebenen Kataloge tables / transforms.

# Open a read-only handle on another app's data backend
weather = await ironflock.connect_to_app("weather-app")
 
# Inspect what the provider shares
print([t["tablename"] for t in weather.tables])
 
# Query history and subscribe, just like your own tables
rows = await weather.get_history("forecasts", {"limit": 100})
 
def on_forecast(*args, **kwargs):
    print("New forecast:", args)
 
await weather.subscribe_to_table("forecasts", on_forecast)

// Open a read-only handle on another app's data backend
const weather = await ironflock.connectToApp("weather-app");
 
// Inspect what the provider shares
console.log(weather.tables.map((t) => t.tablename));
 
// Query history and subscribe, just like your own tables
const rows = await weather.getHistory("forecasts", { limit: 100 });
 
await weather.subscribeToTable("forecasts", (...args) => {
    console.log("New forecast:", args);
});

Parameter:

Bei verweigertem oder falsch verwendetem Zugriff wird ein CrossAppAccessError ausgelöst (Python) bzw. geworfen (JavaScript) mit einem code-Feld: NO_GRANT, PROVIDER_NOT_INSTALLED, UNKNOWN_APP, PRIVATE_TABLE oder NOT_AUTHORIZED.

In Python sind stage und on_error Keyword-Argumente; in JavaScript werden sie über ein Optionsobjekt übergeben (connectToApp(appName, { stage, onError })).

listConsumableApps / list_consumable_apps

Listet jeden nicht privaten Anbieter im Projekt auf – das Discovery-Primitiv für Apps, die die Wildcard-Consume-Berechtigung besitzen (consumes: [{ app: "*" }] in Ihrer data-template.yml, gewährt durch den Projektbenutzer). Sie führt einen einzigen Aufruf aus und öffnet keine Verbindungen: Stellen Sie die zurückgegebenen Kataloge in einem Auswahlmenü dar und rufen Sie dann connectToApp / connect_to_app für die gewünschten auf – oder connectToAllApps / connect_to_all_apps, um alle auf einmal zu öffnen.

Hinweis: Deklarieren Sie die Berechtigung in der data-template.yml Ihrer App und setzen Sie das * in Anführungszeichen – ein bloßes * ist ein YAML-Alias und kann nicht geparst werden:

consumes:
  - app: "*"

providers = await ironflock.list_consumable_apps()
 
for p in providers:
    print(p["app"], list(p["stages"].keys()))  # e.g. "weather-app" ["dev", "prod"]

const providers = await ironflock.listConsumableApps();
 
for (const p of providers) {
    console.log(p.app, Object.keys(p.stages)); // e.g. "weather-app" ["dev", "prod"]
}

Jeder Eintrag beschreibt einen Anbieter:

Es wird ein CrossAppAccessError mit code: NO_GRANT ausgelöst (Python) bzw. geworfen (JavaScript), wenn Ihre App keine Wildcard-Berechtigung besitzt.

connectToAllApps / connect_to_all_apps

Öffnet in einem einzigen Aufruf schreibgeschützte Handles zu jedem nicht privaten Anbieter im Projekt (nur für Wildcard-Consumer). Zählt die Anbieter über listConsumableApps / list_consumable_apps auf und öffnet jeden einzelnen, wobei alle ohne Data Backend für die angeforderte Stage übersprungen werden. Jedes Handle wird unter demselben Schlüssel wie bei connectToApp / connect_to_app zwischengespeichert, sodass ein späteres connectToApp(name) das bereits vorgewärmte Handle zurückgibt. Die zurückgegebenen Handles werden gemeinsam geschlossen, wenn Ihre Instanz stoppt.

apps = await ironflock.connect_to_all_apps(
    on_error=lambda err: print("Provider skipped:", err)
)
 
for app in apps:
    rows = await app.get_history(app.tables[0]["tablename"], {"limit": 10})
    print(app.app, rows)

const apps = await ironflock.connectToAllApps({
    onError: (err) => console.warn("Provider skipped:", err),
});
 
for (const app of apps) {
    const rows = await app.getHistory(app.tables[0]?.tablename, { limit: 10 });
    console.log(app.app, rows);
}

Parameter:

Gibt die erfolgreich geöffneten Anbieter-Handles zurück (derselbe Handle-Typ wie bei connectToApp / connect_to_app). Es wird ein CrossAppAccessError mit code: NO_GRANT ausgelöst (Python) bzw. geworfen (JavaScript), wenn Ihre App keine Wildcard-Berechtigung besitzt.

In Python sind stage, on_error und continue_on_error Keyword-Argumente; in JavaScript werden sie über ein Optionsobjekt übergeben (connectToAllApps({ stage, onError, continueOnError })).

Verwalteter Dateispeicher

Jedes App-Data-Backend erhält neben seinen Tabellen einen privaten Objektspeicher, erreichbar über die Eigenschaft files. Verwenden Sie ihn für Bilder, PDFs, Kamerabilder, Firmware-Blobs — alles, was nicht in eine Tabellenzeile gehört. Es ist keine Einrichtung nötig: Auch eine App ohne files:-Abschnitt in ihrer data-template.yml erhält einen Namespace mit dem Namen default.

Der zentrale Gedanke: Das Ablegen eines Objekts liefert Ihnen eine permanente URL zurück, die Sie direkt in eine Tabellenspalte schreiben können, sodass ein Dashboard-Widget sie ohne weiteres Zutun darstellen kann:

# Store an object and get a permanent URL back in the same call
info = await ironflock.files.put("part-1.jpg", jpeg_bytes, content_type="image/jpeg")
 
# The URL is safe to store in a table column — a dashboard widget can then
# render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publish_to_table("inspections", part_id="1", photo_url=info.url)
 
# Read it back
data = await ironflock.files.get("part-1.jpg")
 
# Walk every object under a prefix (pages are fetched for you)
async for obj in ironflock.files.iter(prefix="2026/"):
    print(obj.key, obj.size)

// Store an object and get a permanent URL back in the same call
const info = await ironflock.files.put("part-1.jpg", jpegBytes, {
    contentType: "image/jpeg",
});
 
// The URL is safe to store in a table column — a dashboard widget can then
// render <img src="{{photo_url}}"> without any extra round trip
await ironflock.publishToTable("inspections", [{ part_id: "1", photo_url: info.url }]);
 
// Read it back
const data = await ironflock.files.get("part-1.jpg");
 
// Walk every object under a prefix (pages are fetched for you)
for await (const obj of ironflock.files.iterate({ prefix: "2026/" })) {
    console.log(obj.key, obj.size);
}

Diese URL läuft nie ab, ist aber kein öffentlicher Link: Sie bleibt nur für einen authentifizierten Anfragenden lesbar, der READ-Zugriff auf dieses Data Backend besitzt, und ein Auth-Proxy prüft das bei jeder Anfrage erneut. Sie kann daher gefahrlos in der Datenbank gespeichert werden.

Namespaces

Ein Namespace ist ein Schlüsselpräfix, das Richtlinien mitführt — Aufbewahrung, Freigaberegeln, erlaubte Content-Types. Er ist kein separater Bucket; jeder Namespace einer App liegt innerhalb des einen Speicherbereichs dieser App. Deklarieren Sie einen eigenen Namespace nur, wenn eine Menge von Objekten andere Regeln benötigt; bleiben Sie andernfalls in default und organisieren Sie Ihre Objekte über Schlüsselpfade wie 2026/03/part-1.jpg.

Zusätzliche Namespaces deklarieren Sie in der data-template.yml:

files:
  # Storage budget the app suggests for itself. The project user can change it,
  # and their setting is the one that gets enforced.
  quotaBytes: 5368709120
  namespaces:
    - name: frames
      description: Raw camera frames, one JPEG per inspected part.
      contentTypes: ["image/jpeg"]
      maxObjectBytes: 20971520
      retention: { deleteAfter: 30 days }

Beachten Sie, dass das Budget einmal für die gesamte App deklariert wird, nicht pro Namespace. Ein Namespace ist lediglich ein Schlüsselpräfix innerhalb des einen Speicherbereichs der App, sodass es nichts gibt, wogegen sich ein Budget pro Präfix durchsetzen ließe. maxObjectBytes gilt dagegen pro Namespace — es begrenzt ein einzelnes Objekt, keine Summe.

Jede der folgenden Methoden nimmt den Namespace als optionales Argument entgegen und verwendet standardmäßig default.

Objekte ablegen und lesen

# Bytes in, bytes out
info = await ironflock.files.put("reports/march.pdf", pdf_bytes, content_type="application/pdf")
data = await ironflock.files.get("reports/march.pdf")
 
# Or straight from/to a local file — these stream on the large-object path,
# so a multi-gigabyte file never has to fit in memory
await ironflock.files.put_file("firmware/v2.bin", "/data/build/v2.bin")
await ironflock.files.get_to_file("firmware/v2.bin", "/tmp/v2.bin")

// Bytes in, bytes out — put/get work on Uint8Array in both Node and the browser
const info = await ironflock.files.put("reports/march.pdf", pdfBytes, {
    contentType: "application/pdf",
});
const data = await ironflock.files.get("reports/march.pdf");

JavaScript besitzt keine Helfer für Dateipfade, weil das Paket einen einzigen Build für Node und den Browser ausliefert — lesen und schreiben Sie lokale Dateien selbst mit fs.

put akzeptiert: content_type / contentType (den MIME-Typ; der Namespace kann einschränken, welche erlaubt sind) und namespace. In Python sind dies Keyword-Argumente; in JavaScript stehen sie in einem Optionsobjekt.

Auflisten und inspizieren

Objekte werden in beiden SDKs durch dieselben Felder beschrieben, jeweils in der Namenskonvention der Sprache: namespace, key, size, etag, content_type / contentType, last_modified / lastModified, checksum_sha256 / checksumSha256 und url.

Speicherbelegung und Kontingent

usage beantwortet die Frage in einem einzigen Aufruf direkt aus dem Objektspeicher, sodass die Summen exakt sind und nicht vom SDK zusammengezählt werden:

u = await ironflock.files.usage()
print(u.size_bytes, u.object_count, u.quota_bytes, u.free_bytes)
 
# Break the total down per namespace (costs one listing per namespace)
detailed = await ironflock.files.usage(detail=True)
print(detailed.per_namespace)   # {"default": 1048576, "frames": 73400320}

const u = await ironflock.files.usage();
console.log(u.sizeBytes, u.objectCount, u.quotaBytes, u.freeBytes);
 
// Break the total down per namespace (costs one listing per namespace)
const detailed = await ironflock.files.usage({ detail: true });
console.log(detailed.perNamespace);   // { default: 1048576, frames: 73400320 }

Die Aufschlüsselung pro Namespace ist standardmäßig abgeschaltet, weil der Speicher sie nicht direkt beantworten kann: Er rechnet pro Speicherbereich ab, und ein Namespace ist nur ein Präfix, sodass das SDK jeden Namespace auflisten muss, um die Größen aufzusummieren. Fordern Sie sie an, wenn Sie sie brauchen, aber nicht auf einem heißen Pfad.

Es tauchen zwei verschiedene Kontingente auf, und es lohnt sich, sie auseinanderzuhalten. catalog() meldet beide:

Sie unterscheiden sich immer dann, wenn ein Nutzer das Budget der App erhöht oder gesenkt hat. Genau deshalb wird der durchgesetzte Wert aus dem Speicher gelesen und nicht aus dem Template — ein erneutes Deployment der App darf die Entscheidung eines Nutzers nicht stillschweigend zurücksetzen. Eine Oberfläche kann beide anzeigen („die App schlägt X vor, Sie haben Y eingestellt“). Durchgesetzt wird immer der erste Wert.

Objekte freigeben

Es gibt zwei Arten von Links, und der Unterschied ist wesentlich:

share_url / shareUrl ist eine Bearer-Berechtigung: Geben Sie den Link an eine Person weiter, die vorübergehend Zugriff benötigt, und speichern Sie ihn nicht in der Datenbank. Verwenden Sie url für alles, was ein Dashboard darstellt.

url gibt None / undefined zurück, wenn das Deployment keinen HTTP-Edge besitzt (zum Beispiel eine Appliance mit reinem HTTP) — das ist das Signal, auf get zurückzufallen. Wird der etag eines Objekts als version-Argument übergeben, können Browser die Antwort unveränderlich zwischenspeichern.

upload_url / uploadUrl erzeugt eine ablaufende URL, die einen direkten Upload entgegennimmt, und gibt url, method, headers sowie expires_in / expiresIn zurück. Senden Sie genau die Header, die sie zurückgibt, sonst lässt sich die Signatur nicht verifizieren.

Große Objekte

Das SDK wählt den Transportweg automatisch anhand der Größe — es gibt nichts zu konfigurieren:

Das genaue Limit meldet der Server zur Laufzeit als inline_max_bytes / inlineMaxBytes in catalog(), sodass es ohne ein SDK-Release angehoben werden kann.

Zwei Obergrenzen bleiben bestehen, und beide melden TOO_LARGE mit einem Grund, der benennt, welche davon Sie erreicht haben:

• 5 GiB — das Limit des Objektspeichers für einen einzelnen Upload. Multipart-Upload ist noch nicht implementiert.
• Das Inline-Limit, wo es keinen direkten Endpunkt gibt — eine Air-Gap-Appliance kann ein großes Objekt überhaupt nicht übertragen. Kein Retry und keine kleinere Chunk-Größe hilft, und die Meldung sagt das auch.

Der direkte Pfad setzt voraus, dass das Gerät den Host des Objektspeichers erreicht, nicht nur den Router. Zwei im Feld häufige Fehler erhalten eigene Codes, statt wie Autorisierungsprobleme auszusehen: PRESIGN_UNREACHABLE (ein Proxy, der nur den Router zulässt) und CLOCK_SKEW (der Objektspeicher weist Anfragen zurück, die mehr als 15 Minuten abweichen — prüfen Sie NTP auf dem Gerät).

Fehler beim Dateispeicher

Jede Dateioperation löst einen FileStoreError aus (Python) bzw. wirft ihn (JavaScript), der einen stabilen code und einen menschenlesbaren reason trägt. Verzweigen Sie über code, niemals über reason.

from ironflock.filestore import FileStoreError
 
try:
    await ironflock.files.put("huge.bin", payload)
except FileStoreError as e:
    if e.code == "QUOTA_EXCEEDED":
        print("Filestore is full:", e.reason)
    else:
        raise

import { FileStoreError } from "ironflock";
 
try {
    await ironflock.files.put("huge.bin", payload);
} catch (e) {
    if (e instanceof FileStoreError && e.code === "QUOTA_EXCEEDED") {
        console.error("Filestore is full:", e.reason);
    } else {
        throw e;
    }
}

Ein neuerer Server kann Codes einführen, die dieses SDK-Release noch nicht kennt. Sie werden unverändert als code durchgereicht statt zusammengefasst zu werden; behandeln Sie einen unbekannten Wert daher als generischen Fehler.

In Python wird FileStoreError aus ironflock.filestore importiert; in JavaScript wird er aus dem Paket-Root exportiert (import { FileStoreError } from "ironflock").

Geräteübergreifende Kommunikation

registerDeviceFunction / register_device_function

Registriert eine Prozedur, die andere Geräte im selben Projekt aufrufen können. Das SDK versieht die Prozedur automatisch mit einem Namespace für das aktuelle Gerät.

def add(a, b):
    return a + b
 
await ironflock.register_device_function("com.myapp.add", add)

function add(args) {
    return args[0] + args[1];
}
 
await ironflock.registerDeviceFunction("com.myapp.add", add);

callDeviceFunction / call_device_function

Ruft eine von einem anderen Gerät registrierte Prozedur auf. Das SDK erstellt das vollständige WAMP-Topic automatisch anhand des Schlüssels des Zielgeräts.

result = await ironflock.call_device_function(
    42,                        # target device key
    "com.myapp.add",           # procedure name
    args=[3, 5]                # arguments
)
print(result)  # 8

const result = await ironflock.callDeviceFunction(
    42,                        // target device key
    "com.myapp.add",           // procedure name
    [3, 5]                     // arguments
);
console.log(result);  // 8

call

Ruft eine Remote-Prozedur über eine vollständige WAMP-URI auf. Verwenden Sie dies für direkte Aufrufe, wenn Sie das genaue Topic kennen.

result = await ironflock.call("some.full.wamp.topic", args=[42])

const result = await ironflock.call("some.full.wamp.topic", [42]);

Gerätemetadaten

setDeviceLocation / set_device_location

Aktualisiert den GPS-Standort des Geräts in der Plattform. Änderungen werden in Echtzeit auf IronFlock-Karten angezeigt.

await ironflock.set_device_location(long=8.6821, lat=50.1109)

await ironflock.setDeviceLocation(8.6821, 50.1109);

Der Standortverlauf wird nicht gespeichert. Um den Standort über die Zeit zu verfolgen, erstellen Sie eine eigene Tabelle und verwenden Sie publish_to_table / publishToTable.

getRemoteAccessUrlForPort

Gibt die öffentliche Remote-Zugriffs-URL für einen bestimmten Port auf dem Gerät zurück.

url = ironflock.getRemoteAccessUrlForPort(8080)
# "https://<device_key>-<app_name>-8080.app.ironflock.com"

const url = ironflock.getRemoteAccessUrlForPort(8080);
// "https://<device_key>-<app_name>-8080.app.ironflock.com"

Verbindungseigenschaften & Lebenszyklus

Fehlerbehandlung

Jede SDK-Methode schlägt lautstark fehl: Bei ungültigen Argumenten, einer abgerissenen Verbindung oder einer Ablehnung durch die Plattform löst sie eine Exception aus (Python) bzw. wird das Promise abgelehnt (JavaScript) — mit einer Meldung, die die Operation, das Topic und den Grund nennt. Nichts wird stillschweigend verschluckt; verpacken Sie Aufrufe, die überleben sollen, daher in einen try-Block.

try:
    rows = await ironflock.getHistory("sensordata", {"limit": 100})
except ValueError as e:
    # Invalid parameters — e.g. limit out of range, or a malformed filter
    print(f"Bad query: {e}")
except RuntimeError as e:
    # Not connected, table not in the data-template, or the platform rejected the call
    print(f"Query failed: {e}")

import { WampError } from "ironflock";
 
try {
    const rows = await ironflock.getHistory("sensordata", { limit: 100 });
} catch (e) {
    if (e instanceof WampError) {
        // Rejected by the platform — e.error holds the WAMP error URI
        console.error(`Query rejected: ${e.error}`, e.args);
    } else {
        // Invalid parameters, or no connection
        console.error(`Query failed: ${e.message}`);
    }
}

In JavaScript sind Fehler, die von der Plattform stammen, WampError-Instanzen — eine gewöhnliche Unterklasse von Error, die zusätzlich die WAMP-Fehler-URI in error und die Fehlerdaten in args / kwargs transportiert. Alles andere (fehlerhafte Parameter, keine Verbindung) ist ein einfacher Error.

Migration: Ältere SDK-Versionen protokollierten eine Meldung und gaben None / null zurück, wenn ein Aufruf fehlschlug. Sie lösen jetzt stattdessen einen Fehler aus, sodass Code der Form if result is None: Fehlschläge nicht mehr erkennt — verwenden Sie try / except (bzw. try / catch).

Browser-Nutzung (nur JavaScript)

Das JavaScript SDK funktioniert in modernen Browsern. Da Browser keine Umgebungsvariablen haben, übergeben Sie alle Konfigurationsoptionen über den Konstruktor:

import { IronFlock } from "ironflock";
 
const ironflock = new IronFlock({
    serialNumber: "device-serial-from-server",
    deviceKey: "my-device-key",
    appName: "MyWebApp",
    swarmKey: 10,
    appKey: 20,
    env: "PROD",
});
 
await ironflock.start();
await ironflock.publishToTable("sensordata", [{ temperature: 22 }]);

Verwenden Sie IronFlock.fromServer(), um die Konfiguration von Ihrem Backend abzurufen, anstatt Zugangsdaten fest einzuprogrammieren:

const ironflock = await IronFlock.fromServer("/api/ironflock-config");
await ironflock.start();

Ihr Backend-Endpunkt sollte ein JSON-Objekt mit den Verbindungsoptionen (serialNumber, deviceKey, appName, swarmKey, appKey, env) zurückgeben.

AI-Agent-Funktionen registrieren

Das SDK kann Funktionen registrieren, die von AI-Agents aufgerufen werden können. Registrieren Sie eine Prozedur und referenzieren Sie deren Topic in Ihrer ai-template.yml:

def get_sensor_reading(sensor_id):
    """Returns the latest reading from a sensor."""
    reading = read_from_hardware(sensor_id)
    return {
        "sensor_id": sensor_id,
        "temperature": reading.temp,
        "humidity": reading.hum,
        "timestamp": reading.ts
    }
 
await ironflock.register_device_function("sensors.get_latest", get_sensor_reading)

function getSensorReading(args, kwargs) {
    const sensorId = kwargs.sensor_id;
    const reading = readFromHardware(sensorId);
    return {
        sensor_id: sensorId,
        temperature: reading.temp,
        humidity: reading.hum,
        timestamp: reading.ts,
    };
}
 
await ironflock.registerDeviceFunction("sensors.get_latest", getSensorReading);

Der AI-Agent kann diese Funktion dann aufrufen, wenn ein Benutzer eine Frage stellt, die aktuelle Sensordaten erfordert.

Um das registrierte WAMP-Topic mit einem AI-Agenten zu verbinden, referenzieren Sie es in der .ironflock/ai-template.yml Ihrer App:

sensor_agent:
    tool_description: |
        Delegiere an diesen Agenten, wenn der Benutzer nach Sensormesswerten,
        Live-Gerätedaten oder aktuellen Umgebungsbedingungen fragt.
 
    system_prompt: |
        Du bist ein Sensordaten-Spezialist. Verwende get_current, um den
        aktuellen Messwert eines beliebigen Sensors abzurufen. Gib in
        deiner Antwort immer die Einheit an.
 
    main: true
    max_context_tokens: 30000
    max_iterations: 5
 
    tools:
        get_current:
            description: Gibt den aktuellen Messwert eines Sensors zurück.
            topic: sensors.get_latest
            parameters:
                sensor_id:
                    type: string
                    description: Der abzufragende Sensor-Bezeichner.
                    required: true

Der Wert von topic (sensors.get_latest) muss mit dem Namen übereinstimmen, der bei register_device_function / registerDeviceFunction im Edge-Code angegeben wurde. IronFlock leitet den Aufruf automatisch an das Gerät weiter, auf dem die Funktion registriert ist.

Die vollständige Referenz für ai-template.yml finden Sie unter Agents & Tools definieren.

Umgebungsvariablen

Diese Variablen werden von der IronFlock-Laufzeitumgebung automatisch innerhalb von App-Containern gesetzt:

import os
 
device_name = os.environ.get("DEVICE_NAME")
serial = os.environ.get("DEVICE_SERIAL_NUMBER")
project_key = os.environ.get("SWARM_KEY")

const deviceName = process.env.DEVICE_NAME;
const serial = process.env.DEVICE_SERIAL_NUMBER;
const projectKey = process.env.SWARM_KEY;