WÄGETECHNIK · EIGENENTWICKLUNG · SUPPORT
+386 2 320 33 46info@preciz.si

NEUTRON APPENGINE · ENTWICKLERHANDBUCH

Neutron AppEngine — Entwicklung von JavaScript-Anwendungen

Entwicklung von JavaScript-Anwendungen für CloudScaleLink Neutron und CloudScale Neutron NS: Laufzeitumgebung, Wägen, digitale I/O, Einstellungen, Speicher, Kommunikationsmodule und Anwendungsverwaltung. Handbuch 1.0 · Neutron AppEngine 1.0.0 · API 1 · Veröffentlichungsdatum: 16. November 2026.

1. Zweck und Geltungsbereich

Neutron AppEngine ist für das Modul CloudScaleLink Neutron und die Wägemodule CloudScale Neutron NS mit Firmware-Version 2.7 oder höher verfügbar.

Mit Neutron AppEngine können Sie eigene JavaScript-Anwendungen direkt auf den Wägemodulen CloudScaleLink Neutron und Neutron entwickeln. Anwendungen können Messwerte lesen, Waagenfunktionen ausführen, Timer verwenden und über unterstützte Kommunikationsmodule (MQTT, TCP, WebSocket, REST, RS-232 und RS-485) eine Verbindung zu externen Systemen herstellen.
Dieses Handbuch richtet sich an Entwickler, Integratoren und KI-Systeme, die Anwendungen für Neutron erstellen.
Dieses Handbuch beschreibt das Profil neutron-js-1, apiVersion: 1, mit Stand vom 16. November 2026. Die Handbuchversion ist 1.0 und die Version des Neutron AppEngine-Interpreters ist 1.0.0. Alle hier beschriebenen implementierten Funktionen, Ereignisse, Eigenschaften und Vorgänge sind ab 1.0.0 verfügbar. Die Firmware-Version allein bestätigt nicht die Unterstützung jeder Funktion: Prüfen Sie app.capabilities() auf dem Gerät und testen Sie Ihre Anwendung.
Tabelle 1

Bereich

Status

Schnittstelle

JavaScript-Ausführung

Implementiert

Neutron AppEngine-Interpreter; eine dauerhaft gespeicherte Benutzeranwendung

Laufzeitumgebung und Diagnose

Implementiert

app.capabilities(), app.stop(), console

Timer

Implementiert

setTimeout, setInterval, Abbrechen über die ID

Waage

Implementiert

Gewicht lesen, tarieren, nullstellen, Tara vorgeben und CSCP-Befehle mit scale.cmd() senden

TCP-Client / -Server

Implementiert

Die vorhandene TCP-Schnittstelle übernehmen, Ereignisse verarbeiten und Daten senden

MQTT

Implementiert

Unabhängiger Benutzer-Broker; mqtt, mqtts, ws und wss

RS-232 / RS-485

Implementiert

serial.rs232 und serial.rs485; Übernahme, SMD-Konfiguration, Ereignisse und Senden

Installation

Implementiert

BLE, internes HTTP/HTTPS und MQTT über den vorhandenen APP-Kanal

Digitale Ein-/Ausgänge

Implementiert

io.input(1..6), io.output(1..6); Konfiguration, Ereignisse, Übernahme von Ausgängen und Zähler

Parameter und Zählanwendung

Über unterstützte CSCP-Befehle

scale.cmd() führt die vom Gerät unterstützten Befehle aus; eine separate JavaScript-API counting.* ist noch nicht verfügbar.

Moduleinstellungen

Implementiert

device.cmd für RMD/SMD; device.settings.read/list/write

Dateien und lokale Datenbank

Implementiert

storage; openRecords und indizierte Schlüsselsuche

REST/HTTP aus JavaScript

Implementiert

fetch für HTTP/HTTPS; Status, Header, Text, JSON und binäre Antworten

Die Datei ist ein reguläres UTF-8-Skript mit der Endung .js. Ihre Größe wird in Byte gemessen, nicht in Zeilen oder Zeichen; sie darf höchstens 131 072 Byte betragen. Es ist kein ES-Modul: import/export, await auf oberster Ebene, Node.js, npm und das DOM sind nicht verfügbar. Verwenden Sie globalThis, Standard-JavaScript-Objekte, Promise, async/await, Map, JSON und Uint8Array. Die Browser-APIs TextEncoder/TextDecoder sind nicht Bestandteil dieses Profils.

2. Ihre erste Anwendung

Speichern Sie den folgenden Code als first-application.js, laden Sie ihn hoch und wählen Sie Run. Er erhöht jede Sekunde einen Zähler und gibt ihn über den konfigurierten Debug-Kanal aus. Eine Konfiguration der Waage oder Kommunikation ist nicht erforderlich.
let counter = 0;
setInterval(() => {
    counter += 1;
    console.log("Counter:", counter);
}, 1000);

Öffnen Sie in der lokalen HTTP-/HTTPS-Oberfläche oder auf der BLE-Seite JS application oder App, wählen Sie die Datei aus, geben Sie Namen und Version ein und wählen Sie Upload. Wählen Sie nach der Validierung Run. Mit Stop halten Sie die Anwendung an; mit Refresh prüfen Sie ihren Zustand und den letzten Fehler. Aktivieren Sie Auto run erst nach dem Testen.

Definieren Sie für die asynchrone Initialisierung eine Funktion und rufen Sie sie auf. start ist ein frei gewählter benutzerdefinierter Name ohne besondere Bedeutung für die Laufzeitumgebung.
async function start() {
    const caps = app.capabilities();
    if (caps.apiVersion !== 1) {
        throw new Error("Unsupported API version");
    }
    console.info("Application ready", caps.runtime);
}
start().catch(error => {
    console.error(error.code || "START_FAILED", error.message);
    app.stop();
});

3. Laufzeitumgebung, Ereignisse und Lebenszyklus

Blockieren vermeiden: Verwenden Sie weder while (true) noch aktives Warten, tiefe Rekursion oder endlose Promise-Ketten. Die Laufzeitumgebung erlaubt etwa 1 s aktive Zeit pro Verarbeitungsschritt; das Warten bis zu einem Ereignis verbraucht dieses Budget nicht. Eine Überschreitung oder ein Warteschlangenüberlauf kann die Anwendung beenden; verwenden Sie dies nicht als normalen Steuerungsmechanismus.
Für die Vorbereitung der Umgebung und die Kompilierung der Anwendung gelten getrennte Zeitlimits von bis zu 5 Sekunden pro Phase. Das Kompilierungslimit ist beim Hochladen und Starten gleich. Die anfängliche Ausführung des Benutzercodes erhält anschließend ein neues Zeitlimit von einer Sekunde; dasselbe Limit gilt für die Verarbeitung von Ereignissen und Timern. Das Warten auf Netzwerkantworten oder Timer verbraucht dieses Budget nicht. TIMEOUT meldet Phase und Limit, beispielsweise TIMEOUT during application startup (limit 1000 ms). Eine Unterbrechung der Ausführung startet das Modul nicht automatisch neu.
Tabelle 2

Schritt

Verhalten

Installation

Quellcode und Attribute werden im Gerätespeicher gespeichert. Integrität und Syntax werden geprüft, ohne Benutzercode auszuführen.

Ausführen

Jeder Start erzeugt einen neuen JavaScript-Kontext. Das anfängliche Skript wird einmal ausgeführt; Variablen aus einem vorherigen Lauf bleiben nicht erhalten.

Warten

Nach der Rückkehr des anfänglichen Skripts bleibt die Laufzeitumgebung aktiv und wartet auf den nächsten Timer oder das nächste Ereignis. Wenn keine Arbeit ansteht, wartet Neutron AppEngine, ohne Benutzercode auszuführen.

Ereignis

Ein Ereignis eines unterstützten Moduls, der Ablauf eines Timers oder das Ergebnis eines Vorgangs löst die entsprechende Verarbeitung in Neutron AppEngine aus. Ein ausstehendes Promise wird erfüllt oder abgelehnt.

Stopp oder Fehler

Timer und Kontext werden entfernt. Stop macht die Auswirkungen bereits ausgeführter Vorgänge nicht rückgängig.

Erneut ausführen

Beenden Sie zuerst den vorherigen Lauf und warten Sie auf busy: false. Auch für die Installation einer neuen Version muss die Anwendung angehalten sein.
Neutron AppEngine führt Callbacks nacheinander aus. Verarbeiten Sie Ereignisse zügig und vermeiden Sie eine unbegrenzte Anzahl ausstehender Vorgänge. await gibt die Ausführung frei, sodass während des Wartens andere Callbacks laufen können. Ein asynchroner Callback ist daher keine Transaktion, die andere Ereignisse blockiert.

4. Anwendungs-API

4.1 app.capabilities()

Verfügbar seit: Neutron AppEngine 1.0.0
const capabilities = app.capabilities();
Zweck. Unterstützte Funktionen und Grenzen vor der Verwendung einer API prüfen.
Beschreibung. Gibt synchron ein neues Objekt mit Angaben zu Unterstützung, Versionen und Grenzen zurück. Initialisiert keine einzelnen Module und garantiert nicht deren aktuelle Bereitschaft.

Parameter

Keine Parameter.

Ergebnis

Das unten gezeigte Objekt.features Eigenschaften zeigen Modulunterstützung an. Einstellungen und Grenzen für jedes Modul werden in seinem Kapitel erläutert.

Fehler und besondere Hinweise

Gibt kein Promise zurück. Schließen Sie die Funktionsunterstützung nicht allein aus dem Gerätenamen oder der Anwendungsversion ab.

Beispiel

const c = app.capabilities();
if (c.apiVersion !== 1) throw new Error("Neustrezen API");
console.info(c.interpreter, c.interpreterVersion, c.apiVersion);
const capabilities = {
  apiVersion: 1,
  runtime: "neutron-js-1",
  interpreter: "Neutron AppEngine",
  interpreterVersion: "1.0.0",
  features: {
    timers: true, scale: true, tcp: true,
    io: true, mqtt: true, serial: true, files: true, records: true, settings: true, http: true, websocket: true
  },
  scaleOperations: ["tare", "zero", "clearTare", "setPresetTare", "cmd"],
  tcp: { configuredMode: 1, requiresClaim: true },
  http: {
    protocols: ["http", "https"], methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"],
    maxActiveRequests: 1, maxQueuedRequests: 4, maxRequestBytes: 4096, maxResponseBytes: 4096,
    maxHeaderBytes: 2048, maxHeaders: 32, maxUrlBytes: 512, maxOptionsBytes: 4096,
    maxTimeoutMs: 60000, redirect: "manual", certificateProfiles: true, compression: false
  },
  settings: { maxKeysPerRequest: 16, maxPageKeys: 32, maxCommandBytes: 2048, maxValueBytes: 1024, automaticReboot: false },
  storage: {
    quotaBytes: 524288, reserveBytes: 131072, maxFileBytes: 262144,
    maxChunkBytes: 4096, maxFiles: 64, maxFindScanBytes: 65536,
    maxFindNeedleBytes: 128, maxDatabases: 8, maxOpenDatabases: 2,
    maxRecords: 2048, maxRecordBytes: 2048, maxRecordDepth: 16, maxKeyBytes: 64, indexedFields: 1
  },
  io: {
    available: true, inputCount: 6, outputCount: 6, indexBase: 1,
    inputFunctions: [{ id: 0, name: "disabled" } /* celoten seznam na napravi */],
    outputFunctions: [{ id: 0, name: "disabled" } /* celoten seznam na napravi */],
    maxListenersPerPin: 32, maxDebounceMs: 60000, maxGlitchUs: 12,
    counterType: "bigint", maxCounterValue: "9223372036854775807",
    requiresOutputClaim: true, defaultSafeState: false
  },
  mqtt: {
    transports: ["mqtt", "mqtts", "ws", "wss"], protocolVersion: "3.1.1",
    maxConnections: 1, qos: [0, 1], maxMessageBytes: 4096,
    maxTopicBytes: 192, maxSubscriptions: 16, maxListeners: 32,
    maxConfigurationBytes: 4096, maxPendingOperations: 8,
    maxOperationTimeoutMs: 60000, certificateProfiles: true
  },
  serial: {
    ports: ["rs232", "rs485"], requiresClaim: true, requiresDisabled: true,
    dataBits: [7, 8], stopBits: [1, 2], parity: ["none", "even", "odd"],
    minBaudRate: 300, maxBaudRate: 1000000, maxMessageBytes: 4096,
    maxLineBytes: 4096, maxListenersPerPort: 32,
    maxWriteTimeoutMs: 180000, maxDrainTimeoutMs: 60000
  },
  limits: {
    maxTimers: 16, maxPendingOperations: 8,
    maxTcpMessageBytes: 4096, maxLineBytes: 4096,
    maxHeapBytes: 1048576, callbackTimeoutMs: 1000,
    maxScaleCommandBytes: 2048, maxScaleResponseBytes: 4096, maxScaleCommandTimeoutMs: 60000
  }
}
Lesen Sie die Version mit app.capabilities().interpreterVersion und den Namen mit app.capabilities().interpreter. interpreterVersion bezeichnet die Produktversion von Neutron AppEngine, apiVersion den API-Vertrag und runtime das Profil. Diese Angaben unterscheiden sich von der Version der Benutzeranwendung und der Gerätefirmware. Aktuelle Versionen: Neutron AppEngine 1.0.0, API 1 und Handbuch 1.0.
console.info(app.capabilities().interpreter, app.capabilities().interpreterVersion);
Beim Gerätestart wird Neutron AppEngine interpreter v1.0.0 auf INFO-Ebene protokolliert. Die Sichtbarkeit hängt vom Debug-Kanal und den Pegeleinstellungen ab. Verwenden Sie capabilities für die Prüfung aus einer Benutzeranwendung.

4.2 app.stop()

Verfügbar seit: Neutron AppEngine 1.0.0
app.stop();
Zweck. Die Benutzeranwendung regulär beenden.
Beschreibung. Fordert das Beenden der Ausführung an und verhindert weitere Callbacks. Setzt das Modul nicht zurück. Gibt die von der Anwendung übernommenen Ressourcen frei; das ressourcenspezifische Verhalten wird im jeweiligen Modulkapitel beschrieben.

Parameter

Keine Parameter.

Ergebnis

undefined. Dies ist eine Anfrage, kein Promise zur Bestätigung des Herunterfahrens. Verwenden Sie den Status APP für die externe Bestätigung.

Fehler und besondere Hinweise

Macht bereits ausgeführte Vorgänge nicht rückgängig. Verwenden Sie return nach dem Aufruf, wenn nachfolgende Anweisungen in der aktuellen Funktion nicht ausgeführt werden dürfen. Es gibt keinen benutzerdefinierten Callback beim Beenden.

Beispiel

if (app.capabilities().apiVersion !== 1) {
    console.error("API version is not supported");
    app.stop();
}

5. Diagnose und Konsole

Die Konsole sendet Ausgaben an das Neutron-Debug-System, nicht an die Browserkonsole. Die vorhandenen Debug-Einstellungen DI und DL wählen Ausgabe und Pegel. Meldungen erhalten das Präfix [JS:application name]. Die aktuelle Transportkonfiguration und Verbindung bestimmen, wo Meldungen sichtbar sind.

5.1 console.log(...)

Verfügbar seit: Neutron AppEngine 1.0.0
console.log(...values);
Zweck. Messwerte oder Status protokollieren.
Beschreibung. Verbindet Argumente mit Leerzeichen. Versucht bei Objekten JSON.stringify und bei anderen Werten eine Textumwandlung. Ersetzt Steuerzeichen durch Leerzeichen. Alle Konsolenmethoden teilen sich dasselbe Protokollierungslimit.

Parameter

Tabelle 3

Parameter

Typ / Anforderung

Beschreibung

values

beliebige JavaScript-Werte / optional

Null oder mehr Argumente. Vermeiden Sie große Objekte und zyklische Strukturen.

Ergebnis

undefined; INFO Protokoll, sichtbar mit DL ≥ 3 und einem entsprechenden DI.

Fehler und besondere Hinweise

Die Protokollierung selbst stoppt die Anwendung nicht, einschließlich console.error(). Das gemeinsame Limit beträgt 10 Aufrufe/s und ungefähr 512 Inhaltsbytes pro Aufruf, ohne Präfix. Überschüssige Ausgaben werden abgelehnt oder abgeschnitten. Möglicherweise wird eine zusätzliche Ratenbegrenzungswarnung angezeigt. Konvertierungs- oder Speicherfehler können eine JavaScript-Ausnahme auslösen.

Beispiel

console.log("Stanje aplikacije", { ready: true, counter: 5 });

5.2 console.info(...)

Verfügbar seit: Neutron AppEngine 1.0.0
console.info(...values);
Zweck. Start- oder Statusinformationen melden.
Beschreibung. Verbindet Argumente mit Leerzeichen. Versucht bei Objekten JSON.stringify und bei anderen Werten eine Textumwandlung. Ersetzt Steuerzeichen durch Leerzeichen. Alle Konsolenmethoden teilen sich dasselbe Protokollierungslimit.

Parameter

Tabelle 4

Parameter

Typ / Anforderung

Beschreibung

values

beliebige JavaScript-Werte / optional

Null oder mehr Argumente. Vermeiden Sie große Objekte und zyklische Strukturen.

Ergebnis

undefined; INFO Protokoll, sichtbar mit DL ≥ 3 und einem entsprechenden DI.

Fehler und besondere Hinweise

Die Protokollierung selbst stoppt die Anwendung nicht, einschließlich console.error(). Das gemeinsame Limit beträgt 10 Aufrufe/s und ungefähr 512 Inhaltsbytes pro Aufruf, ohne Präfix. Überschüssige Ausgaben werden abgelehnt oder abgeschnitten. Möglicherweise wird eine zusätzliche Ratenbegrenzungswarnung angezeigt. Konvertierungs- oder Speicherfehler können eine JavaScript-Ausnahme auslösen.

Beispiel

console.info("Stanje aplikacije", { ready: true, counter: 5 });

5.3 console.warn(...)

Verfügbar seit: Neutron AppEngine 1.0.0
console.warn(...values);
Zweck. Eine Warnung oder ein behandeltes Problem protokollieren.
Beschreibung. Verbindet Argumente mit Leerzeichen. Versucht bei Objekten JSON.stringify und bei anderen Werten eine Textumwandlung. Ersetzt Steuerzeichen durch Leerzeichen. Alle Konsolenmethoden teilen sich dasselbe Protokollierungslimit.

Parameter

Tabelle 5

Parameter

Typ / Anforderung

Beschreibung

values

beliebige JavaScript-Werte / optional

Null oder mehr Argumente. Vermeiden Sie große Objekte und zyklische Strukturen.

Ergebnis

undefined; WARN Protokoll, sichtbar mit DL ≥ 2 und einem entsprechenden DI.

Fehler und besondere Hinweise

Die Protokollierung selbst stoppt die Anwendung nicht, einschließlich console.error(). Das gemeinsame Limit beträgt 10 Aufrufe/s und ungefähr 512 Inhaltsbytes pro Aufruf, ohne Präfix. Überschüssige Ausgaben werden abgelehnt oder abgeschnitten. Möglicherweise wird eine zusätzliche Ratenbegrenzungswarnung angezeigt. Konvertierungs- oder Speicherfehler können eine JavaScript-Ausnahme auslösen.

Beispiel

console.warn("Stanje aplikacije", { ready: true, counter: 5 });

5.4 console.error(...)

Verfügbar seit: Neutron AppEngine 1.0.0
console.error(...values);
Zweck. Einen Fehler beschreiben.
Beschreibung. Verbindet Argumente mit Leerzeichen. Versucht bei Objekten JSON.stringify und bei anderen Werten eine Textumwandlung. Ersetzt Steuerzeichen durch Leerzeichen. Alle Konsolenmethoden teilen sich dasselbe Protokollierungslimit.

Parameter

Tabelle 6

Parameter

Typ / Anforderung

Beschreibung

values

beliebige JavaScript-Werte / optional

Null oder mehr Argumente. Vermeiden Sie große Objekte und zyklische Strukturen.

Ergebnis

undefined; ERROR Protokoll, sichtbar mit DL ≥ 1 und einem entsprechenden DI.

Fehler und besondere Hinweise

Die Protokollierung selbst stoppt die Anwendung nicht, einschließlich console.error(). Das gemeinsame Limit beträgt 10 Aufrufe/s und ungefähr 512 Inhaltsbytes pro Aufruf, ohne Präfix. Überschüssige Ausgaben werden abgelehnt oder abgeschnitten. Möglicherweise wird eine zusätzliche Ratenbegrenzungswarnung angezeigt. Konvertierungs- oder Speicherfehler können eine JavaScript-Ausnahme auslösen.

Beispiel

console.error("Stanje aplikacije", { ready: true, counter: 5 });

5.5 console.debug(...)

Verfügbar seit: Neutron AppEngine 1.0.0
console.debug(...values);
Zweck. Details während der Entwicklung protokollieren.
Beschreibung. Verbindet Argumente mit Leerzeichen. Versucht bei Objekten JSON.stringify und bei anderen Werten eine Textumwandlung. Ersetzt Steuerzeichen durch Leerzeichen. Alle Konsolenmethoden teilen sich dasselbe Protokollierungslimit.

Parameter

Tabelle 7

Parameter

Typ / Anforderung

Beschreibung

values

beliebige JavaScript-Werte / optional

Null oder mehr Argumente. Vermeiden Sie große Objekte und zyklische Strukturen.

Ergebnis

undefined; DEBUG Protokoll, sichtbar mit DL ≥ 4 und einem entsprechenden DI.

Fehler und besondere Hinweise

Die Protokollierung selbst stoppt die Anwendung nicht, einschließlich console.error(). Das gemeinsame Limit beträgt 10 Aufrufe/s und ungefähr 512 Inhaltsbytes pro Aufruf, ohne Präfix. Überschüssige Ausgaben werden abgelehnt oder abgeschnitten. Möglicherweise wird eine zusätzliche Ratenbegrenzungswarnung angezeigt. Konvertierungs- oder Speicherfehler können eine JavaScript-Ausnahme auslösen.

Beispiel

console.debug("Stanje aplikacije", { ready: true, counter: 5 });

Der Debug-Pegel kann Ausgaben filtern. Verwenden Sie die Konsole nicht als zuverlässigen Transport für Geschäftsdaten. Nutzen Sie für einen zuverlässigen Datenaustausch ein geeignetes unterstütztes Kommunikationsmodul.

6. Timer

Ein Timer legt den frühesten vorgesehenen Ausführungszeitpunkt fest. Dies ist keine JavaScript-Umgebung mit harten Echtzeitgarantien: Messung, Kommunikation, vorherige Callbacks und Ablaufplanung können die Ausführung verzögern. Ausgelassene Intervalle erzeugen keine unbegrenzte Warteschlange nachzuholender Aufrufe.

Ein periodischer async-Callback kann noch warten, wenn das nächste Intervall eintritt. Verwenden Sie ein Beschäftigt-Flag oder planen Sie den nächsten setTimeout nach Abschluss des Vorgangs. Dasselbe gilt für Ereignisse jedes Moduls: Wenn die Verarbeitung nacheinander erfolgen muss, implementieren Sie eine begrenzte Warteschlange oder lehnen Sie neue Arbeit ab, bis der vorherige Vorgang abgeschlossen ist.

6.1 setTimeout()

Verfügbar seit: Neutron AppEngine 1.0.0
const id = setTimeout(callback, delayMs = 0, ...args);
Zweck. Eine Funktion einmal nach einer Verzögerung ausführen.
Beschreibung. Kehrt sofort zurück; der Callback läuft später. Der Timer wird vor dem Aufruf des Callbacks aus der aktiven Menge entfernt, sodass der Callback eine weitere Ausführung planen kann.

Parameter

Tabelle 8

Parameter

Typ / Anforderung

Beschreibung

callback

function / erforderlich

Eine Funktion; als Zeichenkette übergebener Code wird nicht unterstützt.

delayMs

number / optional, Standardwert 0

Umwandlung in eine Zahl und eine Ganzzahl. Ungültige, negative oder Null-Verzögerungen ergeben mindestens 1 ms. Maximum: 2 147 483 647 ms.

... args

beliebige Werte / optional

Von der Laufzeitumgebung an den Callback übergebene Argumente.

Ergebnis

Numerische ID, die von clearTimeout akzeptiert wird. Nur während des aktuellen Anwendungslaufs gültig.

Fehler und besondere Hinweise

Synchrones INVALID_ARGUMENT, wenn der Callback keine Funktion ist; QUOTA_EXCEEDED, wenn bereits 16 Timer aktiv sind. Eine unbehandelte Ausnahme oder Ablehnung im Callback kann die Anwendung beenden.

Beispiel

const id = setTimeout(message => {
    console.info(message);
}, 2000, "Two seconds after scheduling");

6.2 setInterval()

Verfügbar seit: Neutron AppEngine 1.0.0
const id = setInterval(callback, delayMs = 0, ...args);
Zweck. Daten regelmäßig lesen oder senden.
Beschreibung. Der erste Aufruf erfolgt nach der Verzögerung. Weitere Callbacks werden periodisch geplant; die Laufzeitumgebung wartet nicht auf Promises, die von async-Callbacks zurückgegeben werden. Verzögerungen verursachen keine unbegrenzte Nachholausführung.

Parameter

Tabelle 9

Parameter

Typ / Anforderung

Beschreibung

callback

function / erforderlich

Eine Funktion; als Zeichenkette übergebener Code wird nicht unterstützt.

delayMs

number / optional, Standardwert 0

Umwandlung in eine Zahl und eine Ganzzahl. Ungültige, negative oder Null-Verzögerungen ergeben mindestens 1 ms. Maximum: 2 147 483 647 ms.

... args

beliebige Werte / optional

Von der Laufzeitumgebung an den Callback übergebene Argumente.

Ergebnis

Numerische ID, die von clearInterval akzeptiert wird. Das Intervall bleibt aktiv, bis es abgebrochen wird oder die Anwendung endet.

Fehler und besondere Hinweise

Dieselben synchronen Fehler wie bei setTimeout. Schützen Sie asynchrone Arbeit vor Überlappung und fangen Sie Ablehnungen innerhalb der async-Funktion ab.

Beispiel

let working = false;
let counter = 0;
const id = setInterval(async () => {
    if (working) return;
    working = true;
    try {
        // Example asynchronous step; Promise yields execution.
        const next = await Promise.resolve(counter + 1);
        counter = next;
        console.info("Completed step:", counter);
    } catch (error) {
        console.warn(error.code || error.name, error.message);
    } finally {
        working = false;
    }
}, 1000);

6.3 clearTimeout()

Verfügbar seit: Neutron AppEngine 1.0.0
clearTimeout(id);
Zweck. Zukünftige Timer-Ausführung abbrechen.
Beschreibung. Beide Funktionen verwenden dasselbe Timer-Verzeichnis und können jeden der beiden Timer-Typen abbrechen. Die Verwendung des jeweils passenden set/clear-Paars wird empfohlen.

Parameter

Tabelle 10

Parameter

Typ / Anforderung

Beschreibung

id

number / erforderlich

Von setTimeout oder setInterval zurückgegebene ID. Umgewandelt mit Number(id).

Ergebnis

undefined. Ein unbekannter ID hat keine Auswirkung.

Fehler und besondere Hinweise

Unterbricht keinen Callback oder asynchronen Vorgang, der bereits gestartet wurde. Das Konvertieren eines ungeeigneten JavaScript-Werts in eine Zahl kann eine Standardausnahme JavaScript auslösen.

Beispiel

const id = setTimeout(() => console.info("Pozneje"), 1000);
clearTimeout(id);

6.4 clearInterval()

Verfügbar seit: Neutron AppEngine 1.0.0
clearInterval(id);
Zweck. Zukünftige Timer-Ausführung abbrechen.
Beschreibung. Beide Funktionen verwenden dasselbe Timer-Verzeichnis und können jeden der beiden Timer-Typen abbrechen. Die Verwendung des jeweils passenden set/clear-Paars wird empfohlen.

Parameter

Tabelle 11

Parameter

Typ / Anforderung

Beschreibung

id

number / erforderlich

Von setTimeout oder setInterval zurückgegebene ID. Umgewandelt mit Number(id).

Ergebnis

undefined. Ein unbekannter ID hat keine Auswirkung.

Fehler und besondere Hinweise

Unterbricht keinen Callback oder asynchronen Vorgang, der bereits gestartet wurde. Das Konvertieren eines ungeeigneten JavaScript-Werts in eine Zahl kann eine Standardausnahme JavaScript auslösen.

Beispiel

const id = setInterval(() => console.info("Interval"), 1000);
clearInterval(id);

7. Waagen-API

7.1 scale.read()

Verfügbar seit: Neutron AppEngine 1.0.0
const measurement = scale.read();
Zweck. Die letzte verfügbare Momentaufnahme der Waage lesen, ohne auf Stabilität zu warten.
Beschreibung. Gibt synchron die letzte verfügbare Momentaufnahme der Waagendaten zurück. Löst keine neue Messung aus. Lesen Sie ein Objekt und verwenden Sie dessen Felder gemeinsam für konsistente Netto-/Brutto-/Tara-Werte.

Parameter

Keine Parameter.

Ergebnis

Ein Objekt mit den folgenden Feldern. Wenn kein Messwert verfügbar ist, sind net, gross und tare NaN und stable ist false. unit und status bleiben Diagnoseinformationen.

Fehler und besondere Hinweise

Eine nicht verfügbare Waage wird als available=false gemeldet und nicht als NO_MEASUREMENT-Ausnahme. available=true bedeutet nicht stable=true. Ein synchroner Aufruf kann eine Ausnahme werfen, wenn der JavaScript-Speicher erschöpft ist.

Beispiel

const m = scale.read();
if (m.available && Number.isFinite(m.net)) {
    console.log(m.net, m.gross, m.tare, m.unit, m.stable);
} else {
    console.warn("Ni veljavne meritve", m.status);
}
Tabelle 12

Feld

Typ

Bedeutung

available

boolean

Die Waage ist verfügbar, die Wägeschnittstelle ist aktiviert und der Messwert ist gültig.

net

number

Aus Brutto und Tara berechnetes Nettogewicht, auf die konfigurierten Dezimalstellen gerundet.

gross

number

Bruttogewicht in der konfigurierten Einheit.

tare

number

Aktuelle Tara in der konfigurierten Einheit.

stable

boolean

Der gültige Messwert ist gemäß der aktuellen Waagenkonfiguration stabil.

unit

string

Aktuelle Waageneinheit, etwa kg oder g. Es ist nicht unbedingt kg.

status

number

Aktueller Statuswert der Waage. Das JavaScript-Profil stellt keine separate benannte Aufzählung bereit; erfinden Sie keine Codezuordnungen.

sequence

number

32-Bit-Zähler veröffentlichter Messungen; läuft bei Überlauf um. Keine dauerhafte ID eines Wägedatensatzes.

timeMs

number

Zeitpunkt der letzten Messwertveröffentlichung in Millisekunden seit Gerätestart. Keine UTC-Zeit; dieser 32-Bit-Zähler kann überlaufen.

Die Kurzformen scale.net, scale.gross und scale.available sind Live-Getter, die bei jedem Zugriff eine neue Momentaufnahme lesen. scale.tare ist eine Funktion; den numerischen Tarawert erhalten Sie über scale.read().tare. Verwenden Sie keine zwei getrennten Getter für ein Brutto-/Netto-Paar, das aus derselben Momentaufnahme stammen muss.

7.2 scale.tare()

Verfügbar seit: Neutron AppEngine 1.0.0
const measurement = await scale.tare();
Zweck. Mit der aktuellen Last tarieren.
Beschreibung. Führt die entsprechende Waagenfunktion aus, ohne Stabilität, Bereich, Schutz, gleichzeitige Befehle oder Konfiguration zu umgehen. Führt den Wägebefehl T aus; dies ist kein sofortiges Tarieren mit TI.

Parameter

Keine Parameter.

Ergebnis

Promise<Measurement>: Liest nach einer erfolgreichen Antwort eine neue JavaScript-Momentaufnahme mit der Struktur von scale.read(). Dies garantiert nicht, dass die nächste Messung eingetroffen ist; beobachten Sie nachfolgende Messungen, um die Wirkung zu bestätigen.

Fehler und besondere Hinweise

BUSY,OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED oder TIMEOUT. Behandeln Sie abgelehnte Promises mit await/try/catch. Anhalten zerstört den Kontext; Promise Fortsetzung ist nicht garantiert.

Beispiel

async function apply() {
    try {
        const m = await scale.tare();
        console.info("Operation successful", m.net, m.tare, m.unit);
    } catch (error) {
        console.warn(error.code || "SCALE_FAILED", error.message);
    }
}
apply();

7.3 scale.zero()

Verfügbar seit: Neutron AppEngine 1.0.0
const measurement = await scale.zero();
Zweck. Die Waage nullstellen.
Beschreibung. Führt die entsprechende Waagenfunktion aus, ohne Stabilität, Bereich, Schutz, gleichzeitige Befehle oder Konfiguration zu umgehen. Führt Z aus; dies unterscheidet sich vom Tarieren. Der Erfolg hängt von den Betriebsbedingungen und dem zulässigen Nullstellbereich ab.

Parameter

Keine Parameter.

Ergebnis

Promise<Measurement>: Liest nach einer erfolgreichen Antwort eine neue JavaScript-Momentaufnahme mit der Struktur von scale.read(). Dies garantiert nicht, dass die nächste Messung eingetroffen ist; beobachten Sie nachfolgende Messungen, um die Wirkung zu bestätigen.

Fehler und besondere Hinweise

BUSY,OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED oder TIMEOUT. Behandeln Sie abgelehnte Promises mit await/try/catch. Anhalten zerstört den Kontext; Promise Fortsetzung ist nicht garantiert.

Beispiel

async function apply() {
    try {
        const m = await scale.zero();
        console.info("Operation successful", m.net, m.tare, m.unit);
    } catch (error) {
        console.warn(error.code || "SCALE_FAILED", error.message);
    }
}
apply();

7.4 scale.clearTare()

Verfügbar seit: Neutron AppEngine 1.0.0
const measurement = await scale.clearTare();
Zweck. Tara löschen.
Beschreibung. Führt die entsprechende Waagenfunktion aus, ohne Stabilität, Bereich, Schutz, gleichzeitige Befehle oder Konfiguration zu umgehen. Führt TAC aus, um das Entfernen der aktuellen Tara anzufordern.

Parameter

Keine Parameter.

Ergebnis

Promise<Measurement>: Liest nach einer erfolgreichen Antwort eine neue JavaScript-Momentaufnahme mit der Struktur von scale.read(). Dies garantiert nicht, dass die nächste Messung eingetroffen ist; beobachten Sie nachfolgende Messungen, um die Wirkung zu bestätigen.

Fehler und besondere Hinweise

BUSY,OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED oder TIMEOUT. Behandeln Sie abgelehnte Promises mit await/try/catch. Anhalten zerstört den Kontext; Promise Fortsetzung ist nicht garantiert.

Beispiel

async function apply() {
    try {
        const m = await scale.clearTare();
        console.info("Operation successful", m.net, m.tare, m.unit);
    } catch (error) {
        console.warn(error.code || "SCALE_FAILED", error.message);
    }
}
apply();

7.5 scale.setPresetTare(value)

Verfügbar seit: Neutron AppEngine 1.0.0
const measurement = await scale.setPresetTare(value);
Zweck. Eine Tara-Vorgabe einstellen.
Beschreibung. Führt die entsprechende Waagenfunktion aus, ohne Stabilität, Bereich, Schutz, gleichzeitige Befehle oder Konfiguration zu umgehen. Führt TA mit einer numerischen Tara in der aktuellen Waageneinheit aus. Werte werden nicht automatisch aus einer anderen Einheit umgerechnet.

Parameter

Tabelle 13

Parameter

Typ / Anforderung

Beschreibung

value

number / erforderlich

Endliche Zahl ≥ 0 innerhalb der Waagenkapazität, in scale.read().unit. Zeichenketten, NaN und Infinity sind nicht zulässig.

Ergebnis

Promise<Measurement>: Liest nach einer erfolgreichen Antwort eine neue JavaScript-Momentaufnahme mit der Struktur von scale.read(). Dies garantiert nicht, dass die nächste Messung eingetroffen ist; beobachten Sie nachfolgende Messungen, um die Wirkung zu bestätigen.

Fehler und besondere Hinweise

Ein ungültiger Typ, negativer oder nicht endlicher Wert lehnt mit ab INVALID_ARGUMENT; Werte über der Kapazität werden mit OUT_OF_RANGE abgelehnt. Andere Fehler: BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED oder TIMEOUT. Behandeln Sie die Ablehnung mit await/try/catch. Anhalten zerstört den Kontext; Promise Fortsetzung ist nicht garantiert.

Beispiel

async function apply() {
    try {
        const m = await scale.setPresetTare(2.5);
        console.info("Operation successful", m.net, m.tare, m.unit);
    } catch (error) {
        console.warn(error.code || "SCALE_FAILED", error.message);
    }
}
apply();

Ein Wägevorgang wartet für das konfigurierte Zeitfenster des Waagenbefehls zuzüglich etwa 2 Sekunden Verarbeitung. Für diese JavaScript-Vorgänge gibt es keinen Timeout-Parameter pro Aufruf. Eine Waage, die einen anderen Befehl verarbeitet, kann BUSY zurückgeben. Führen Sie voneinander abhängige Befehle mit aufeinanderfolgenden await-Aufrufen aus, statt mit unbegrenztem Promise.all.

7.6 scale.cmd()

Verfügbar seit: Neutron AppEngine 1.0.0
const response = await scale.cmd(command, { timeoutMs });
Zweck. Einen CSCP-Befehl ausführen und seine ursprüngliche Antwort lesen.
Beschreibung. Zugriff auf Waagenbefehle, Konfiguration und andere vom Gerät unterstützte Funktionen über CSCP. Die vorhandene Parametervalidierung und die Regeln zum Datenschutz gelten. RSD und Konfigurationsabfragen erfordern keinen gültigen Messwert. S und SX warten auf einen stabilen Messwert; SI und SXI fragen sofort ab.

Parameter

Tabelle 14

Parameter

Typ / Anforderung

Beschreibung

command

string / erforderlich

Ein CSCP-Befehl, höchstens 2048 UTF-8-Byte nach dem Entfernen umgebender Leerzeichen und eines optionalen abschließenden CRLF. Leere Befehle, NUL, eingebettete CR/LF und andere Steuerzeichen sind unzulässig. Syntax und Groß-/Kleinschreibung folgen CSCP.

options

object / optional, Standardwert {}

Warteoptionen. Einheit, Stabilität und Berechtigungen werden durch den Befehl und die Waageneinstellungen bestimmt.

options.timeoutMs

Ganzzahl / optional

1–60000 ms. Standardmäßig das konfigurierte Wartefenster der Waage zuzüglich 2 Sekunden Verarbeitung. Verlängert nicht die interne Stabilitätswartezeit des Befehls.

Ergebnis

Promise<string> mit der ursprünglichen CSCP-Antwort, höchstens 4096 UTF-8-Byte. Ein abschließendes CRLF wird entfernt; interne mehrzeilige Zeilenenden bleiben erhalten. Die Zeichenkette ist kein Measurement-Objekt und wird nicht automatisch geparst. S I, ES, FT L und ERRAUTH sind gültige CSCP-Ergebnisse und führen nicht zur Ablehnung des Promise. Bestimmen Sie den Befehlserfolg anhand der CSCP-Referenz.

Fehler und besondere Hinweise

INVALID_ARGUMENT bei falscher Verwendung; MESSAGE_TOO_LARGE bei einem zu großen Befehl; UNSUPPORTED_COMMAND bei Befehlen mit mehreren/keinen Antworten oder Zurücksetzen; BUSY bei belegter Waage oder erreichtem Limit gleichzeitiger Vorgänge; TIMEOUT bei zu langem Warten; NO_RESPONSE, wenn ein Befehl ohne Antwort endet; RESPONSE_TOO_LARGE bei zu großer Antwort; OUT_OF_MEMORY bei unzureichendem Speicher. Antworten werden niemals stillschweigend gekürzt. Stop unterbricht die ausstehende Ausführung; ihr Promise wird im zerstörten Kontext nicht fortgesetzt.

Beispiel

async function start() {
    try {
        const stable = await scale.cmd("S", { timeoutMs: 10000 });
        console.info("CSCP weight:", stable);
        const settings = await scale.cmd("RSD");
        console.info("Configuration length:", settings.length);
        const result = await scale.cmd("FT=512");
        console.info("CSCP filter:", result);
    } catch (error) {
        console.warn(error.code || error.name, error.message);
    }
}
start();

Es darf jeweils nur ein Waagenbefehl ausstehen. Verwenden Sie await für die sequenzielle Ausführung. Eine neue Anfrage erhält BUSY, solange ein anderer Befehl aussteht; es gibt keine versteckte Befehlswarteschlange. Dies gilt auch beim Kombinieren von scale.cmd() mit tare/zero/clearTare/setPresetTare. Abbruch oder Zeitüberschreitung machen bereits geänderte Einstellungen nicht rückgängig. Eine verspätete Antwort wird nicht der nächsten Anfrage zugeordnet.

Die Funktion gibt eine Antwort zurück. SIR, SR, SXIR, RAS, RASI, CAL, RST, CWRESULTA und CWDEBUG werden vor der Ausführung abgelehnt, einschließlich Befehlen mit einem Zugangsdatenfeld P=. Mehrzeiliger Inhalt innerhalb einer Antwort, etwa I0, ist zulässig. Verwenden Sie einen Timer und scale.read() für wiederholte Messungen; scale.cmd() öffnet keinen Antwortdatenstrom.

Ein Befehl kann unterstützte Parameter und eine CSCP-Anmeldeinformation enthalten; Die Funktion umgeht den Waagenschutz nicht. Befolgen Sie die Syntax CSCP, wenn für einen geschützten Befehl Anmeldeinformationen erforderlich sind. Behandeln Sie ERRAUTH und ERRLOCK im zurückgegebenen Text. Anwendungsinstallationsbefehle und andere Verwaltungskanäle gehören nicht in scale.cmd().

Prüfen Sie die Unterstützung mit app.capabilities().scaleOperations.includes("cmd"). Grenzen werden als limits.maxScaleCommandBytes, limits.maxScaleResponseBytes und limits.maxScaleCommandTimeoutMs veröffentlicht. Verfügbar ab Neutron AppEngine 1.0.0; features-Flags beschreiben dedizierte Module. io.* ist im separaten I/O-Kapitel dokumentiert. Moduleinstellungen und Datenspeicherung haben eigene Kapitel sowie getrennte device- und storage-APIs.

Tabelle 15

Aufruf

Ergebnis / Verhalten

scale.cmd("S")

Nächster stabiler Messwert oder eine CSCP-Fehlerantwort wie S I.

scale.cmd("SI")

Sofortige Antwort mit dem aktuellen Gewicht.

scale.cmd("RSD")

Waagendaten und Konfiguration als Zeichenkette; funktioniert ohne verfügbaren Gewichtswert.

scale.cmd("FT=?")

Aktuelle Filtereinstellung, beispielsweise FT A 512.

scale.cmd("FT=512")

Ändert und speichert den Filter gemäß CSCP; prüfen Sie die zurückgegebene Antwort.

scale.cmd("UNKNOWN")

Üblicherweise ES als Ergebnis des erfüllten Promise, keine JavaScript-Ablehnung.

scale.cmd("SIR")

Ablehnung mit UNSUPPORTED_COMMAND; es wird kein kontinuierlicher Datenstrom gestartet.

7.7 Fehler des Waagenmoduls

Tabelle 16

Code

Bedeutung für die Waage

NO_MEASUREMENT

Waagenvorgang ohne gültigen Messwert oder verfügbare Waage.

OUT_OF_RANGE

Tara-Vorgabe überschreitet die Kapazität.

PERMISSION_DENIED

Waagenbefehl durch Schutz oder Autorisierung abgelehnt.

SCALE_REJECTED

Die Waage hat den Vorgang abgelehnt; prüfen Sie Meldung und Waagenbedingungen.

7.8 Regelmäßige Protokollierung des Gewichts

Eigenständige . js-Datei ohne TCP-Anforderung. Protokolliert einmal pro Sekunde eine gültige Messung. Verwenden Sie Stop im Anwendungsmanager, um es zu stoppen.

// Runtime stays active until Stop. No overlap: this callback is synchronous.
console.info(app.capabilities());
setInterval(() => {
    const measurement = scale.read();
    if (measurement.available) {
        console.log("Neto:", measurement.net, "Bruto:", measurement.gross, measurement.unit);
    }
}, 1000);

8. Digitale Ein- und Ausgänge

Das Modul io überwacht sechs Eingänge und sechs Ausgänge, konfiguriert deren Funktionen, steuert übernommene Ausgänge direkt und liest Eingangszähler. Indizes sind immer 1–6. Alle Funktionen, Eigenschaften und Ereignisse dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar. API-Unterstützung: app.capabilities().features.io; physische I/O-Verfügbarkeit: app.capabilities().io.available.

Das Lesen des Zustands und Beobachten von Ereignissen erfordert keine Übernahme. Sie können einen durch eine Systemfunktion gesteuerten Ausgang beobachten; bevor Sie direkt schreiben, deaktivieren Sie seine Funktion ausdrücklich und übernehmen Sie ihn. Das Modul nutzt die gemeinsame I/O-Verarbeitung des Geräts, daher gelten dieselben Zugriffsregeln auch über andere Schnittstellen.

io.input(index) / io.output(index)

Verfügbar seit: Neutron AppEngine 1.0.0
const input = io.input(1);
const output = io.output(1);
Zweck. Das Objekt für einen physischen Eingang oder Ausgang abrufen.
Beschreibung. Wiederholte Aufrufe für denselben Pin geben dasselbe Objekt zurück. Ändert keine Konfiguration, registriert keine Ereignisse und schaltet keinen Ausgang.

Parameter

Tabelle 17

Parameter

Typ / Anforderung

Beschreibung

index

Ganzzahl / erforderlich

1..6. Zeichenketten, Null, Bruchwerte und Indizes über 6 werden abgelehnt.

Ergebnis

Eingangs- oder Ausgangsobjekt. Beide unterstützen read, configure, on, once und off. Ausgänge ergänzen claim, write und release; Eingänge ergänzen counter und resetCounter.

Fehler und besondere Hinweise

INVALID_ARGUMENT bei ungültigem Index. Das Objekt kann ohne I/O-Platine abgerufen werden; prüfen Sie read(). available.

Beispiel

const input = io.input(1);
const output = io.output(2);
console.info(input.read().available, output.read().value);

input.read() / output.read()

Verfügbar seit: Neutron AppEngine 1.0.0
const inputState = io.input(1).read();
const outputState = io.output(1).read();
Zweck. Die letzte Momentaufnahme von Zustand und Konfiguration synchron lesen.
Beschreibung. Das Lesen erfordert keine Übernahme und löst kein change-Ereignis aus. Die Momentaufnahme wird durch die gemeinsame Geräteverarbeitung und bei Änderungen aktualisiert; read führt keine zusätzliche physische Abtastung durch. Nach erfolgreichem await configure/write enthält die Momentaufnahme die Ergebnisse des entsprechenden Vorgangs.

Parameter

Keine Parameter.

Ergebnis

Eingabe: {index, available, value, functionId, function, mode, debounceMs, glitchUs, pull, counter}. Ausgabe: {index, available, value, functionId, function, claimed}. Typen und Bedeutungen sind unten aufgeführt.

Fehler und besondere Hinweise

value ist null bei nicht verfügbarem I/O und Eingängen im Modus disabled oder counter. counter ist nur bei einem verfügbaren Zählereingang BigInt; andernfalls null. Der Ausgangswert value stellt den angeforderten Zustand dar; die Bestätigung des tatsächlichen Schaltens eines externen Schützes oder Geräts erfordert eine Rückmeldung an einem Eingang.

Beispiel

const s = io.input(1).read();
console.info(s.mode, s.value, s.function);
if (s.counter !== null) console.info(s.counter.toString());
Tabelle 18

Feld seit Neutron AppEngine 1.0.0

Typ

Bedeutung

index

number

Pin-Nummer 1..6.

available

boolean

I/O ist auf dem Gerät vorhanden.

value

boolean | null

true entspricht logisch 1, false entspricht logisch 0. Eingangswerte sind entprellt; null bedeutet, dass kein digitaler Wert verfügbar ist.

functionId / function

number / string

Vorhandene Funktionsnummer und ihr Name in der JavaScript-API. unknown kennzeichnet eine nicht unterstützte gespeicherte Nummer.

mode

string / nur Eingang

disabled, digital oder counter.

debounceMs

number / nur Eingang

Bestätigungszeit digitaler Änderungen in Millisekunden.

glitchUs

number / nur Eingang

Kurzimpulsfilter des Zählers in Mikrosekunden. Wird im Modus counter verwendet.

pull

string / nur Eingang

none, up oder down.

counter

bigint | null / nur Eingang

Letzter Zählerwert ohne Genauigkeitsverlust bei großen Ganzzahlen.

claimed

boolean / nur Ausgang

Der Ausgang wurde von der Benutzeranwendung übernommen. Dies bedeutet nicht, dass der Ausgang eingeschaltet ist.

input.configure(options)

Verfügbar seit: Neutron AppEngine 1.0.0
await io.input(1).configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });
Zweck. Modus, Funktion und Verarbeitung des ausgewählten Eingangs konfigurieren und speichern.
Beschreibung. Ändert angegebene Eigenschaften und behält andere bei, soweit sie mit dem ausgewählten Modus kompatibel sind. Speichert und übernimmt die Konfiguration ohne Neustart über den vorhandenen gemeinsamen Pfad zur Eingangskonfiguration. Die Modi disabled und counter deaktivieren die Systemfunktion des Eingangs. Das Initialisieren eines neuen Modus löst kein change aus und zählt einen anfänglich aktiven Pegel nicht als neuen Tastendruck.

Parameter

Tabelle 19

Parameter

Typ / Anforderung

Beschreibung

options.mode

string / optional

disabled, digital oder counter. Bei Weglassen bleibt der aktuelle Modus erhalten.

options.function

string | Ganzzahl / optional

Name oder ID aus der Eingangsfunktionstabelle. Eine aktive Funktion ist nur im Modus digital zulässig.

options.debounceMs

Ganzzahl / optional

0..60000 ms, nur im Modus digital. Die vorhandene Grundeinstellung ist 20 ms; geben Sie beim Wechsel aus einem anderen Modus ausdrücklich den gewünschten Wert an.

options.pull

string / optional

none, up oder down; nur im Modus digital.

options.glitchUs

Ganzzahl / optional

0..12 µs, nur im Modus counter. 0 deaktiviert die Filterung. Beim Wechsel zu counter ohne Filterangabe wird der vorherige Filter mit einem Wert ungleich Null oder 5 µs verwendet.

Ergebnis

Promise<InputState> mit demread() Struktur. Die Einstellungen bleiben nach Stopp und Neustart des Geräts bestehen.

Fehler und besondere Hinweise

INVALID_ARGUMENT bei ungültigen Typen oder inkompatiblen Eigenschaften, NOT_AVAILABLE, RESOURCE_IN_USE beim aktiven Dosieren oder Kontrollwägen, CONFIGURE_FAILED bei fehlgeschlagener Übernahme oder Speicherung und BUSY. Der Modus counter kann abgelehnt werden, wenn der ausgewählte Eingang keine verfügbare Zählressource hat. Konfigurieren Sie nicht in einer schnellen periodischen Schleife.

Beispiel

await io.input(1).configure({ mode: "digital", function: "tare", debounceMs: 30, pull: "down" });
// For independent JavaScript handling of the same input:
await io.input(1).configure({ function: "disabled" });

output.configure(options)

Verfügbar seit: Neutron AppEngine 1.0.0
await io.output(1).configure({ function: "disabled" });
Zweck. Die Systemfunktion eines Ausgangs auswählen und speichern oder deaktivieren.
Beschreibung. Das Ändern der Funktion schaltet den Ausgang nicht direkt um. Eine aktive Funktion steuert seinen Zustand gemäß den Geräteregeln. disabled ermöglicht manuelle Steuerung und Übernahme durch JavaScript; der aktuelle Ausgangspegel wird dadurch nicht automatisch ausgeschaltet.

Parameter

Tabelle 20

Parameter

Typ / Anforderung

Beschreibung

options.function

string | Ganzzahl / erforderlich

Name oder ID aus der Tabelle der Ausgangsfunktionen.

Ergebnis

Promise<OutputState>. Die Einstellung ist dauerhaft und gilt ohne Neustart.

Fehler und besondere Hinweise

RESOURCE_IN_USE, wenn der Ausgang übernommen ist oder Dosieren/Kontrollwägen aktiv ist. Rufen Sie release() und dann configure() auf. Andere Kanäle können die Funktion eines übernommenen Ausgangs ebenfalls nicht ändern. Weitere Fehler: INVALID_ARGUMENT, NOT_AVAILABLE, CONFIGURE_FAILED, BUSY.

Beispiel

await io.output(2).configure({ function: "inTolerance" });
// Monitoring is allowed even when the system controls the output.
io.output(2).on("change", e => console.info(e.value));

Funktionsnamen und IDs

Tabelle 21

Eingangs-ID

JavaScript-Name seit Neutron AppEngine 1.0.0

Bedeutung

0

disabled

Keine Systemfunktion

1

zero

Nullstellen

2

tare

Tarieren

3

clearTare

Tara löschen

4

dosingStart

Dosierung starten

5

dosingPause

Dosierung pausieren

6

dosingStop

Dosierung stoppen

7

checkweigherSensor

Produktsensor

8

checkweigherStart

Kontrollwägen starten

9

checkweigherPause

Kontrollwägen pausieren

10

checkweigherStop

Kontrollwägen stoppen

11

checkweigherReset

Kontrollwägen zurücksetzen

12

checkweigherEnable

CONS aktivieren

13

checkweigherTrigger

Ausschleusung auslösen

Tabelle 22

Ausgangs-ID

JavaScript-Name seit Neutron AppEngine 1.0.0

Bedeutung

0

disabled

Keine Systemfunktion

1

inTolerance

Innerhalb der Toleranz

2

underTolerance

Unterhalb der Toleranz

3

overTolerance

Oberhalb der Toleranz

4

dosingActive

Dosierung aktiv

5

dosingFast

Grobdosierung

6

dosingMedium

Mittlere Dosierung

7

dosingFine

Feindosierung

8

dosingFly

Warten auf Nachlauf

9

dosingUnloading

Entleeren

10

dosingInTolerance

Dosierung innerhalb der Toleranz

11

dosingOutOfTolerance

Dosierung außerhalb der Toleranz

12

dosingEnd

Dosierung abgeschlossen

13

dosingError

Dosierfehler

14

checkweigherBelt

Förderband

15

checkweigherLow

Untergewicht ausschleusen

16

checkweigherHigh

Übergewicht ausschleusen

17

checkweigherGood

Impuls bei akzeptablem Gewicht

18

checkweigherCommon

Gemeinsame Ausschleusung / Fehler

19

checkweigherActive

Kontrollwägen aktiv

20

checkweigherAlarm

Alarm

21

checkweigherBuffer

Behälterwarnung

Die Gerätefunktionalität bestimmt die tatsächlichen Regeln dieser Systemfunktionen. Die Registrierung von change deaktiviert keine Funktion: Ein mit tare belegter Eingang kann sowohl die systemseitige Tarierung als auch ein JavaScript-Ereignis auslösen. Wenn JavaScript den Vorgang ausführen soll, setzen Sie zuerst function="disabled", um eine doppelte Ausführung zu vermeiden. ID-/Namenslisten sind auch in capabilities.io.inputFunctions und outputFunctions verfügbar.

output.claim(options?)

Verfügbar seit: Neutron AppEngine 1.0.0
await io.output(1).claim({ safeState: false });
Zweck. Die ausschließliche manuelle Kontrolle über den Ausgang für den aktuellen Anwendungslauf übernehmen.
Beschreibung. Nur mit function=disabled zulässig. Deaktiviert weder automatisch eine zugewiesene Systemfunktion noch ändert es den aktuellen Pegel. Dieselbe Anwendung darf denselben Ausgang erneut übernehmen, um safeState zu aktualisieren.

Parameter

Tabelle 23

Parameter

Typ / Anforderung

Beschreibung

options.safeState

boolean / false

Ausgangszustand bei release() oder Beendigung der Anwendung. Gilt für den aktuellen Lauf; wird nicht als Gerätestartzustand gespeichert.

Ergebnis

Promise<OutputState> mit claimed=true.

Fehler und besondere Hinweise

RESOURCE_IN_USE bei aktiver Systemfunktion oder einem anderen Zugriffsberechtigten. NOT_AVAILABLE, INVALID_ARGUMENT, BUSY. Übernommene Ausgänge lehnen externe Schreibvorgänge und Funktionsänderungen auch über andere Kanäle ab. Das Beobachten von change bleibt zulässig.

Beispiel

const out = io.output(1);
await out.configure({ function: "disabled" });
await out.claim({ safeState: false });
await out.write(true);

output.write(value)

Verfügbar seit: Neutron AppEngine 1.0.0
await io.output(1).write(true);
Zweck. Einen übernommenen Ausgang auf den angeforderten logischen Zustand setzen.
Beschreibung. Schreibt über die gemeinsame I/O-Verarbeitung. Eine tatsächliche Änderung löst change aus; erneutes Schreiben desselben Werts löst kein Ereignis aus. Der Zustand wird nicht bei jedem Schalten gespeichert. Das Promise und das change-Ereignis sind getrennte Benachrichtigungen; verlassen Sie sich nicht auf deren relative Reihenfolge.

Parameter

Tabelle 24

Parameter

Typ / Anforderung

Beschreibung

value

boolean / erforderlich

true schaltet ein, false schaltet aus; 0, 1 und Zeichenketten sind nicht zulässig.

Ergebnis

Promise<OutputState> nach dem Schreiben des Steuerausgangs.

Fehler und besondere Hinweise

NOT_OWNER vor claim oder nach release. NOT_AVAILABLE, INVALID_ARGUMENT, RESOURCE_IN_USE, BUSY. Die Bestätigung beweist nicht die physische Funktion des externen Geräts.

Beispiel

const out = io.output(1);
await out.claim();
await out.write(true);
await out.write(false);

output.release()

Verfügbar seit: Neutron AppEngine 1.0.0
await io.output(1).release();
Zweck. Den Ausgang auf safeState setzen und die Kontrolle freigeben.
Beschreibung. Die automatische Freigabe erfolgt auch in der Dienstverarbeitung nach Stop, einem unbehandelten Fehler oder dem Ersetzen der Anwendung. Die vorherige Systemfunktion wird nicht automatisch wiederhergestellt: configure ist eine ausdrückliche dauerhafte Änderung. Die Freigabe eines im aktuellen Lauf nicht übernommenen Ausgangs hat keine Wirkung.

Parameter

Keine Parameter.

Ergebnis

Promise<undefined>. Wenn safeState den Pegel ändert, wird change ausgelöst, während die Anwendung noch läuft.

Fehler und besondere Hinweise

NOT_OWNER bei einem anderen Zugriffsberechtigten, NOT_AVAILABLE, BUSY. Die Zustellung eines abschließenden Ereignisses beim Beenden der Anwendung ist nicht garantiert. Nach einem Hardware-Reset gilt der normale Ausgangszustand beim Gerätestart (aus), nicht der vorherige safeState. Dies ersetzt keine Hardware-Sicherheitsschaltung.

Beispiel

await io.output(1).release();
// A system function can now be assigned again:
await io.output(1).configure({ function: "inTolerance" });

pin.on() / pin.once() / pin.off()

Verfügbar seit: Neutron AppEngine 1.0.0
pin.on("change", callback);
pin.once("change", callback);
pin.off("change", callback);
Zweck. Änderungen am ausgewählten Eingang oder Ausgang beobachten.
Beschreibung. on beobachtet nachfolgende Änderungen. once entfernt die Registrierung vor der ersten nachfolgenden Änderung, die sowohl Ein- als auch Ausschalten sein kann. off entfernt Registrierungen derselben Funktion. Die Registrierung allein löst kein anfängliches Ereignis aus. Das unterstützte Ereignis ist change, mit bis zu 32 Listenern pro Pin.

Parameter

Tabelle 25

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

Nur "change".

callback

function / erforderlich

Empfängt {index, value, previousValue, timeMs}. off erfordert dieselbe Funktionsreferenz.

Ergebnis

Gibt das gleiche Pin-Objekt zur Verkettung zurück. Ereignisse sind unabhängig von der Quelle der Änderung: JavaScript, CSCP, anderen Verwaltungsschnittstellen oder einer Systemfunktion.

Fehler und besondere Hinweise

INVALID_ARGUMENT, QUOTA_EXCEEDED. Eingänge geben nach der Entprellung Ereignisse aus. Digitale Ereignisse sind im Modus counter oder disabled nicht verfügbar. Ausgänge geben Ereignisse nur dann aus, wenn sich der befohlene Pegel tatsächlich ändert. Eine Ausnahme oder ein nicht behandelter abgelehnter Promise in einem Callback kann die Anwendung gemäß Laufzeitregeln stoppen. Ohne Listener werden keine Ereignisse für diesen Pin an JavaScript gesendet.

Beispiel

const onInput = event => {
    console.info(event.index, event.previousValue, "->", event.value, event.timeMs);
    if (event.value) console.info("Input activated");
};
io.input(1).on("change", onInput);
io.output(2).once("change", e => console.info("First output change:", e.value));
// Later: io.input(1).off("change", onInput);
Tabelle 26

Ereignisfeld seit Neutron AppEngine 1.0.0

Typ

Bedeutung

index

integer

1..6 für den Pin mit dem Listener.

value

boolean

Neuer Zustand: true entspricht logisch 1, false entspricht logisch 0.

previousValue

boolean

Vorheriger bestätigter Zustand.

timeMs

number

Monotoner Änderungszeitpunkt in Millisekunden seit Gerätestart; kann einen Bruchteil enthalten. Kein Datum, keine UTC-Zeit und kein Zeitpunkt der Callback-Zustellung. Bei Eingängen ist dies der Bestätigungszeitpunkt nach der Entprellung.

Das Beispiel zur Aktivierungsdauer benötigt kein Polling. timeMs beginnt bei einem Gerätestart neu. Konfigurationsänderungen und anfängliche Abtastungen in einem neuen Modus sind keine physischen change-Ereignisse.

let activatedAt;
io.input(1).on("change", event => {
    if (event.value) activatedAt = event.timeMs;
    else if (activatedAt !== undefined) {
        console.info("Active duration:", event.timeMs - activatedAt, "ms");
        activatedAt = undefined;
    }
});

input.counter()

Verfügbar seit: Neutron AppEngine 1.0.0
const count = io.input(1).counter();
Zweck. Den letzten Gesamtwert der erkannten positiven Impulse eines Zählereingangs zurückgeben.
Beschreibung. Die Zählung verwendet den vorhandenen Gerätemechanismus, ohne JavaScript für jeden Impuls aufzurufen. BigInt erhält die Genauigkeit oberhalb von 2^53. Maximum: 9223372036854775807; an dieser Grenze bleibt der Wert stehen. Die normale dauerhafte Speicherung des Gerätezählers bleibt aktiv; bei plötzlichem Stromausfall können noch nicht gespeicherte Impulse verloren gehen.

Parameter

Keine Parameter.

Ergebnis

bigint. Der gleiche Wert erscheint im input.read().counter. Verwenden Sie count.toString() für JSON;JSON.stringify kann BigInt nicht direkt serialisieren.

Fehler und besondere Hinweise

INVALID_MODE, wenn der Eingang nicht im Modus counter ist; NOT_AVAILABLE, wenn I/O fehlt. Dies ist eine Momentaufnahme und keine Garantie, dass während des Lesens kein neuer Impuls eingetroffen ist.

Beispiel

await io.input(1).configure({ mode: "counter", glitchUs: 5 });
const count = io.input(1).counter();
console.info(count.toString());
console.info(JSON.stringify({ count: count.toString() }));

input.resetCounter()

Verfügbar seit: Neutron AppEngine 1.0.0
await io.input(1).resetCounter();
Zweck. Den ausgewählten Zähler zurücksetzen und den neuen Ausgangswert speichern.
Beschreibung. Asynchron; nur im Modus counter zulässig. Löst kein digitales change-Ereignis aus. Impulse können während oder unmittelbar nach dem Zurücksetzen eintreffen.

Parameter

Keine Parameter.

Ergebnis

Promise<bigint> enthält den neuesten Zähler-Snapshot nach der Ausführung. Neue Impulse bedeuten, dass es möglicherweise nicht mehr 0n ist.

Fehler und besondere Hinweise

INVALID_MODE, NOT_AVAILABLE, WRITE_FAILED, BUSY. Nach dem Zurücksetzen des In-Memory-Zählers kann ein Speicherfehler auftreten. Der Fehler macht diesen Effekt nicht rückgängig. Nicht in einer schnellen Schleife zurücksetzen.

Beispiel

await io.input(1).resetCounter();
console.info(io.input(1).counter().toString());

Vollständiges Beispiel: Eingang steuert Ausgang

Das Beispiel speichert die Konfiguration von Eingang 1 ausdrücklich und deaktiviert die Systemfunktion von Ausgang 1. Danach übernimmt es den Ausgang mit safeState=false, überwacht Eingang 1 und beobachtet Ausgang 2 getrennt. Es begrenzt sich überlappende asynchrone Schreibvorgänge und übernimmt den letzten Eingangszustand, nachdem ein Schreibvorgang abgeschlossen ist.

// Input 1 controls output 1; output 2 is only monitored.
// configure() settings persist. The active system function on output 1
// is explicitly disabled; during dosing/checkweighing the call is rejected.
const input = io.input(1);
const output = io.output(1);
let ready = false;
let updating = false;
let dirty = false;

// Bounded change coalescing: apply the latest state after a slow write.
async function updateOutput() {
    if (!ready) return;
    dirty = true;
    if (updating) return;
    updating = true;
    try {
        while (dirty) {
            dirty = false;
            await output.write(input.read().value);
        }
    } catch (error) {
        console.error(error.code || error.name, error.message);
        app.stop();
    } finally {
        updating = false;
    }
}

input.on("change", event => {
    console.info("Input", event.index, event.value, "timeMs:", event.timeMs);
    updateOutput(); // The function handles its own errors.
});

io.output(2).on("change", event => {
    // Also works when a CSCP command or system function switches output 2.
    console.info("Output", event.index, event.previousValue, "->", event.value);
});

async function start() {
    const caps = app.capabilities();
    if (!caps.features.io || !caps.io.available) throw new Error("I/O unavailable");
    await input.configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });
    await output.configure({ function: "disabled" });
    await output.claim({ safeState: false });
    ready = true;
    await updateOutput(); // Initial state emits no change event.
    console.info("I/O application ready");
}

start().catch(error => {
    console.error(error.code || error.name, error.message);
    app.stop(); // Stopping sets the claimed output to safeState.
});

Prüfen einer I/O-Anwendung

Tabelle 27

Test

Erwartetes Ergebnis

Anfangszustand

read gibt einen Wert zurück; die Registrierung von on/once löst kein Ereignis aus.

Eingang 1 ein- und ausschalten

Zwei change-Ereignisse nach der Entprellung, mit entgegengesetztem previousValue/value und entsprechendem timeMs.

Kurzes Kontaktprellen

Keine doppelten Ereignisse für eine bestätigte Änderung.

Externes SOT für nicht übernommenen Ausgang 2

Ein JavaScript-change-Ereignis bei jeder tatsächlichen Änderung; die Wiederholung desselben Werts löst keines aus.

Ausgang 2 durch eine Systemfunktion gesteuert

JavaScript kann Änderungen ohne Übernahme beobachten.

Externes SOT/SOF oder Funktionsänderung für übernommenen Ausgang 1

Abgelehnt, ohne den Ausgang der Anwendung zu überschreiben.

Stop oder Anwendungsfehler bei eingeschaltetem übernommenem Ausgang

Übergang zu safeState und Freigabe während der Dienstverarbeitung.

Zähler und große Werte

BigInt ohne Genauigkeitsverlust; kein digitales change-Ereignis für jeden Impuls.

Nicht verfügbares I/O oder ungültiger Index

available=false oder INVALID_ARGUMENT; kein Zugriff auf einen anderen Pin.

9. Moduleinstellungen: RMD und SMD

Das Modul device verwaltet Neutron-Einstellungen. Es ist getrennt von scale, das das Wägen steuert, sowie von Anwendungsdaten in storage. Alle Funktionen und Eigenschaften dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar. Unterstützung: app.capabilities().features.settings.

Änderungen verwenden die vorhandene SMD-Validierung und Speicherung. Sie berücksichtigen belegte Schnittstellen und übernommene Ausgänge. Einstellungen, die während des Betriebs angewendet werden können, nutzen die vorhandenen Mechanismen zur laufenden Übernahme. Andere melden, dass ein Neustart erforderlich ist. Die API startet das Gerät niemals automatisch neu.

device.cmd(command)

Verfügbar seit: Neutron AppEngine 1.0.0
const raw = await device.cmd("RMD");
const result = await device.cmd("SMD;S0B=19200;S0P=0;");
Zweck. Einen unterstützten RMD- oder SMD-Verwaltungsbefehl ausführen.
Beschreibung. RMD gibt eine Textliste von Einstellungen und Grundzuständen im vorhandenen Format zurück. SMD verwendet dasselbe Ergebnis wie settings.write(). Andere Verwaltungsbefehle wie REB werden hier nicht unterstützt. Wiederholen Sie SMD nicht zwischen einzelnen Einstellungen.

Parameter

Tabelle 28

Parameter

Typ / Anforderung

Beschreibung

command

string / erforderlich

RMD oder SMD;KEY=value;... . Höchstens 2048 UTF-8-Byte; keine Steuerzeichen. SMD akzeptiert bis zu 16 unterschiedliche Schlüssel.

Ergebnis

RMD:Promise<string>. SMD: Promise<SettingsWriteResult>, unten beschrieben.

Fehler und besondere Hinweise

INVALID_ARGUMENT, UNSUPPORTED_COMMAND, BUSY, NO_RESPONSE, RESPONSE_TOO_LARGE. RMD kann 4096 Bytes überschreiten; Verwenden Sie settings.read für ausgewählte Schlüssel oder settings.list für die Paginierung. Der API liest keine Passwörter, PINs oder privaten Zertifikatsdaten. Verwalten Sie Zertifikate über den vorhandenen Zertifikatsbereitstellungsprozess.

Beispiel

try {
    const raw = await device.cmd("RMD");
    console.info(raw);
} catch (error) {
    if (error.code !== "RESPONSE_TOO_LARGE") throw error;
    console.info("Use device.settings.list() for paged settings");
}

device.settings.read(keys)

Verfügbar seit: Neutron AppEngine 1.0.0
const values = await device.settings.read(["S0B", "S0P"]);
Zweck. Ausgewählte gespeicherte Einstellungen ohne große RMD-Antwort lesen.
Beschreibung. Gibt Werte als Zeichenketten zurück, auch Zahlen. Ein fehlender Schlüssel hat den Wert null. Das Lesen ändert weder Gerätezustand noch Einstellungen und garantiert nicht, dass eine ausstehende Hardwareübernahme abgeschlossen ist.

Parameter

Tabelle 29

Parameter

Typ / Anforderung

Beschreibung

keys

string[] / erforderlich

1..16 Schlüssel. Namen enthalten 1..15 Zeichen: A–Z, 0–9 oder _.

Ergebnis

Promise<object>, zum Beispiel {S0B:"19200", S0P:"0", UNKNOWN:null}.

Fehler und besondere Hinweise

INVALID_ARGUMENT, PERMISSION_DENIED bei geschützten Daten, RESPONSE_TOO_LARGE, BUSY. Erfinden Sie keine APIs mit unbekannten Schlüsseln; unterstützte Einstellungen werden durch das Gerät und seine Dokumentation festgelegt.

Beispiel

const values = await device.settings.read(["S0B", "S0I", "S0P", "S0S"]);
const baudRate = values.S0B === null ? null : Number(values.S0B);
console.info(baudRate);

device.settings.list(options?)

Verfügbar seit: Neutron AppEngine 1.0.0
const page = await device.settings.list({ cursor: null, limit: 16 });
Zweck. Öffentlich zugängliche gespeicherte Einstellungen seitenweise lesen.
Beschreibung. Schlüssel sind aufsteigend sortiert. cursor ist der letzte Schlüssel der vorherigen Seite, der selbst ausgeschlossen wird. Aufgrund des Größenlimits kann die Antwort weniger als limit Schlüssel enthalten. Seiten bilden keine gemeinsame Momentaufnahme: Einstellungen können sich zwischen Aufrufen ändern.

Parameter

Tabelle 30

Parameter

Typ / Anforderung

Beschreibung

options.cursor

string | null / weggelassen

nextCursor aus der vorherigen Antwort; null oder Weglassen beginnt am Anfang.

options.limit

Ganzzahl / 16

1..32 Schlüssel pro Seite; das Antwortlimit bleibt 4096 Byte.

Ergebnis

Promise<{values:object, nextCursor:string|null}>. null zeigt das Ende an.

Fehler und besondere Hinweise

INVALID_ARGUMENT, RESPONSE_TOO_LARGE bei einem einzelnen zu großen Wert, BUSY. Die Liste enthält gespeicherte Schlüssel; dynamische RMD-Zustände sind nicht unbedingt gespeicherte Einstellungen. Vertrauliche Daten werden ausgelassen.

Beispiel

let cursor = null;
do {
    const page = await device.settings.list({ cursor, limit: 16 });
    console.info(page.values);
    cursor = page.nextCursor;
} while (cursor !== null);

device.settings.write(values)

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await device.settings.write({ S0B: "19200", S0P: "0" });
Zweck. Eine Gruppe von Einstellungen über die vorhandene SMD-Verarbeitung speichern.
Beschreibung. Prüft vor dem Start das Gesamtformat. Anschließende Einzelfehler bei Validierung und Hardware folgen den vorhandenen SMD-Regeln. Die Gruppe ist keine Transaktion: Ein Fehler macht andere gespeicherte Werte nicht rückgängig. Prüfen Sie result.ok und result.errors auch nach erfolgreichem await.

Parameter

Tabelle 31

Parameter

Typ / Anforderung

Beschreibung

values

object / erforderlich

1..16 Schlüssel. Werte dürfen Zeichenketten, boolesche Werte (0/1) oder Ganzzahlen in −2147483648..4294967295 sein. Geben Sie Dezimalwerte als Zeichenketten im Format der Einstellung an. Höchstens 1024 UTF-8-Byte pro Wert; keine Semikolons, Steuerzeichen oder der Sonderwert ?. Die gesamte Anfrage muss in 4096 Byte passen.

Ergebnis

Promise<{ok:boolean, applied:string[], errors:object, rebootRequired:boolean, applyPending:boolean}>. applied listet Schlüssel ohne unmittelbaren Speicherfehler auf; dies bestätigt nicht unabhängig die physische Bereitschaft der Schnittstelle. Ein abschließender Fehler bei der Übernahme kann einen eigenen Schlüssel in errors haben.

Fehler und besondere Hinweise

Ungültiges Format wird mit INVALID_ARGUMENT oder MESSAGE_TOO_LARGE abgelehnt. Fehler einzelner Einstellungen geben ok=false und errors zurück, etwa CHECKWEIGHER_BUSY oder INVALID_OR_WRITE_FAILED. applyPending kennzeichnet die ausstehende Übernahme der seriellen Schnittstelle; überwachen Sie Schnittstellenzustand oder Gerätestatus. rebootRequired löst niemals einen automatischen Neustart aus. Schreiben Sie keine dauerhaften Einstellungen in einer schnellen Messschleife.

Beispiel

const result = await device.settings.write({ S0B: "19200", S0I: "1", S0P: "0", S0S: "1" });
if (!result.ok) console.warn("Some settings failed:", result.errors);
if (result.rebootRequired) console.info("A device restart is required");
if (result.applyPending) console.info("Serial configuration is still being applied");

Beispiel zum Lesen von Einstellungen

async function start() {
    if (!app.capabilities().features.settings) throw new Error("Settings API is unavailable");
    console.info("Selected settings:", await device.settings.read(["S0B", "S0I", "S0P", "S0S"]));
    // Changes persist. Uncomment only the desired keys before use.
    // const result = await device.settings.write({ S0B: "19200", S0I: "1", S0P: "0", S0S: "1" });
    // console.info(result.ok, result.errors, result.rebootRequired, result.applyPending);
    // Equivalent: await device.cmd("SMD;S0B=19200;S0I=1;S0P=0;S0S=1;");
    // Use pagination for more settings; complete RMD may exceed 4096 bytes.
    const page = await device.settings.list({ limit: 8 });
    console.info("First settings page:", page.values);
}
start().catch(error => { console.error(error.code || error.name, error.message); app.stop(); });

10. Speicher und Dateien

Das Modul storage stellt dauerhaften Speicher für Anwendungsdaten bereit. Alle Funktionen dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar. Unterstützung: app.capabilities().features.files. Anwendungsdateien sind von Systemdateien, Zertifikaten und installiertem Anwendungscode getrennt. Die API kann auf nichts außerhalb dieses Datenbereichs zugreifen.

Dateinamen enthalten 1..64 Zeichen. Das erste muss A–Z/a–z oder eine Ziffer sein; weitere Zeichen dürfen auch _, - oder ein Punkt sein. Aufeinanderfolgende Punkte, Schrägstriche, Unterverzeichnisse und absolute Pfade sind unzulässig. Namen unterscheiden Groß- und Kleinschreibung. Daten bleiben nach Stop, Neustart und regulärem Ersetzen der Anwendung erhalten. Die installierte Anwendung teilt sich einen Datenbereich; eine neue Version oder eine andere Anwendung auf dem Gerät kann dieselben Daten verwenden. Das Zurücksetzen auf Werkseinstellungen löscht Benutzerdateien und lokale Datenbanken. Das normale Löschen der Anwendung mit Delete löscht diese nicht.

Vorgänge sind asynchron und verwenden eine begrenzte Dienstwarteschlange. Laden Sie keine gesamte große Datei in JavaScript, erstellen Sie keine unbegrenzten Schreibwarteschlangen und senden Sie nicht alle Blöcke ohne await. Das Beenden macht einen bereits begonnenen Schreibvorgang nicht rückgängig; sein Ergebnis erreicht die beendete Anwendung möglicherweise nicht mehr.

storage.info()

Verfügbar seit: Neutron AppEngine 1.0.0
const info = await storage.info();
Zweck. Nutzung, Kontingent und verfügbaren Speicherplatz melden.
Beschreibung. Dateien und lokale Datenbanken teilen sich das Anwendungskontingent. Die tatsächliche Verfügbarkeit hängt außerdem von anderen Gerätedaten und der Systemreserve ab. Temporäre Kopien zum atomaren Ersetzen oder Komprimieren erfordern zusätzlichen physischen Speicherplatz.

Parameter

Keine Parameter.

Ergebnis

{quotaBytes, usedBytes, reserveBytes, freeBytes, availableBytes, maxFileBytes, databases:[{name,bytes}]}. usedBytes ist die gemeinsame logische Größe festgeschriebener Dateien und Datenbanken; freeBytes ist der insgesamt freie Speicherplatz. availableBytes schätzt das mögliche Wachstum innerhalb von Kontingent und Reserve.

Fehler und besondere Hinweise

NOT_AVAILABLE oder ein Lesefehler. Eine Momentaufnahme, keine Reservierung für einen zukünftigen Schreibvorgang. Die Verfügbarkeit wird während des Vorgangs erneut geprüft.

Beispiel

const info = await storage.info();
console.info(info.usedBytes, info.availableBytes, info.databases);

storage.write() / storage.writeText()

Verfügbar seit: Neutron AppEngine 1.0.0
await storage.write(name, data);
await storage.writeText(name, text);
Zweck. Eine Datei erstellen oder ihren gesamten Inhalt ersetzen.
Beschreibung. write akzeptiert string oder Uint8Array; writeText akzeptiert nur string. Zeichenketten werden als UTF-8 gespeichert, Binärdaten als exakte Bytefolge. Fügt weder Zeilenumbruch noch NUL hinzu. Das vollständige Ersetzen schreibt zunächst eine temporäre Datei und ersetzt danach die festgeschriebene Datei.

Parameter

Tabelle 32

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Gültiger Dateiname.

data / text

string | Uint8Array / erforderlich

0..4096 Byte pro Aufruf nach UTF-8-Kodierung. writeText akzeptiert kein Uint8Array.

Ergebnis

Promise<undefined> nach erfolgreichem Schreiben und Speicherbestätigung. Eine leere Nutzlast erstellt oder leert die Datei.

Fehler und besondere Hinweise

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, NOT_AVAILABLE, BUSY. Bei einer fehlgeschlagenen Ersetzung bleibt die zuvor festgeschriebene Datei erhalten. Schreiben Sie für größere Inhalte den ersten Block und hängen Sie ihn dann nacheinander an. Diese mehrstufige Konstruktion ist keine einzelne atomare Operation.

Beispiel

await storage.writeText("config.json", JSON.stringify({ target: 25, tolerance: 0.1 }));
await storage.write("data.bin", new Uint8Array([0, 255, 10, 13]));

storage.append() / storage.appendText()

Verfügbar seit: Neutron AppEngine 1.0.0
await storage.append(name, data);
await storage.appendText(name, text);
Zweck. Daten an eine Datei anhängen, geeignet für Protokolle.
Beschreibung. Erstellt eine fehlende Datei, ohne vorhandenen Inhalt zu überschreiben. Das Anhängen ist keine Transaktion über mehrere Datensätze; Fehler oder Stromausfall können den letzten Zusatz unvollständig lassen. Gestalten Sie Protokolle so, dass solche unvollständigen letzten Datensätze erkannt werden.

Parameter

Tabelle 33

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Gültiger Dateiname.

data / text

string | Uint8Array / erforderlich

Höchstens 4096 Byte pro Aufruf; appendText erfordert string. Maximale Dateigröße: 262144 Byte.

Ergebnis

Promise<undefined>. Ein gelieferter Erfolg bestätigt den Schreibvorgang; Eine fehlende Antwort bedeutet nicht, dass der Schreibvorgang nicht stattgefunden hat.

Fehler und besondere Hinweise

MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, BUSY. Ein Teil des Zusatzes kann nach einem Fehler bereits vorhanden sein. Versuchen Sie es nicht blind mit Geschäftsdaten, ohne ein eindeutiges ID oder eine Bestätigung.

Beispiel

await storage.appendText("measurements.jsonl", JSON.stringify({ id: 1, net: scale.net }) + "\n");

storage.read() / storage.readText()

Verfügbar seit: Neutron AppEngine 1.0.0
const bytes = await storage.read(name, { offset: 0, length: 4096 });
const text = await storage.readText(name);
Zweck. Binäre Bytefolgen oder UTF-8-Text lesen.
Beschreibung. read gibt Uint8Array zurück; readText gibt string zurück. offset und length beziehen sich immer auf Byte. Ein Start hinter dem Dateiende gibt ein leeres Ergebnis zurück. Ein Lesevorgang nahe dem Ende kann weniger Byte als angefordert liefern.

Parameter

Tabelle 34

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Dateiname.

options.offset

Ganzzahl / 0

0..262144 Byte ab dem Anfang.

options.length

Ganzzahl / optional

0..4096 Byte. read liest standardmäßig bis zu 4096 Byte. Ohne length muss bei readText der verbleibende Text in eine Antwort passen; andernfalls RESPONSE_TOO_LARGE.

Ergebnis

Promise<Uint8Array> oder Promise<string>. read erhält binäres NUL und alle anderen Bytewerte.

Fehler und besondere Hinweise

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, RESPONSE_TOO_LARGE. Beachten Sie die Grenzen von Multibyte-Zeichen, wenn Sie den Text UTF-8 aufteilen. Durch die unabhängige Dekodierung beliebiger Blöcke kann ein Zeichen geteilt werden. readText ist kein JSON- oder JSONL-Parser; Verwenden Sie JSON.parse für kleine JSON Dokumente.

Beispiel

const config = JSON.parse(await storage.readText("config.json"));
let offset = 0;
for (;;) {
    const part = await storage.read("data.bin", { offset, length: 4096 });
    if (!part.length) break;
    console.info("Read bytes:", part.length);
    offset += part.length;
}

storage.list(options?) / storage.stat(name)

Verfügbar seit: Neutron AppEngine 1.0.0
const page = await storage.list({ cursor: null, limit: 16 });
const info = await storage.stat("data.bin");
Zweck. Dateien auflisten oder die Größe einer Datei abrufen.
Beschreibung. list umfasst nur reguläre Anwendungsdateien, keine internen Datenbankdateien. Namen sind aufsteigend sortiert; cursor schließt den zuletzt zurückgegebenen Namen aus. Datenbanken erscheinen in storage.info().databases.

Parameter

Tabelle 35

Parameter

Typ / Anforderung

Beschreibung

options.cursor

string | null / weggelassen

nextCursor aus der vorherigen Seite.

options.limit

Ganzzahl / 16

1..32 Dateien.

name für stat

string / erforderlich

Gültiger Name.

Ergebnis

list: {files:[{name,size}], nextCursor:string|null}. stat: {name,size}. Die Größe ist in Byte angegeben. null markiert das Listenende.

Fehler und besondere Hinweise

NOT_FOUND bei stat, INVALID_ARGUMENT, READ_FAILED, OUT_OF_MEMORY. Seiten sind bei gleichzeitigen Ergänzungen oder Löschungen keine unveränderliche Momentaufnahme.

Beispiel

let cursor = null;
do {
    const page = await storage.list({ cursor, limit: 16 });
    for (const file of page.files) console.info(file.name, file.size);
    cursor = page.nextCursor;
} while (cursor !== null);

storage.remove(name) / storage.rename(name, to)

Verfügbar seit: Neutron AppEngine 1.0.0
const removed = await storage.remove("old.jsonl");
await storage.rename("measurements.jsonl", "archive.jsonl");
Zweck. Eine reguläre Datei löschen oder umbenennen.
Beschreibung. remove kann nicht auf interne Datenbankdaten zugreifen. rename überschreibt kein vorhandenes Ziel; entfernen Sie dieses bei Bedarf zuerst ausdrücklich.

Parameter

Tabelle 36

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Name der Quelldatei.

to für rename

string / erforderlich

Neuer gültiger Name ohne vorhandene Datei.

Ergebnis

remove: Promise<boolean>, false, wenn nicht vorhanden. rename: Promise<undefined>.

Fehler und besondere Hinweise

NOT_FOUND für eine fehlende Umbenennungsquelle, ALREADY_EXISTS für ein bestehendes Ziel, WRITE_FAILED, INVALID_ARGUMENT. Der Löschvorgang kann nicht rückgängig gemacht werden.

Beispiel

await storage.remove("measurements-old.jsonl");
await storage.rename("measurements.jsonl", "measurements-old.jsonl");

storage.findText(name, text, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
const page = await storage.findText("measurements.jsonl", "ART-001", { offset: 0, limit: 16 });
Zweck. Exakten Text in einer regulären Datei finden, ohne den gesamten Inhalt in JavaScript zu laden.
Beschreibung. Sequenzielle UTF-8-Bytesuche unter Beachtung der Groß- und Kleinschreibung, kein regulärer Ausdruck. Unterstützt überlappende Treffer. Jeder Aufruf durchsucht höchstens 65536 Byte oder endet am Trefferlimit. Verwenden Sie für schnelle Schlüsselsuchen eine lokale Datenbank, statt wiederholt Dateien zu durchsuchen.

Parameter

Tabelle 37

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Dateiname.

text

string / erforderlich

1..128 UTF-8-Byte, ohne NUL.

options.offset

Ganzzahl / 0

Startoffset in Byte, 0..262144.

options.limit

Ganzzahl / 16

1..64 Treffer pro Seite.

Ergebnis

{offsets:number[], nextOffset:number|null}. offsets sind absolute Anfangspositionen der Treffer in Byte. Fahren Sie mit exakt dem zurückgegebenen nextOffset fort; so bleiben mögliche Teiltreffer über Seitengrenzen hinweg erhalten. null markiert das Dateiende.

Fehler und besondere Hinweise

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, CANCELLED. Ändern Sie die Datei nicht während einer mehrstufigen Suche, wenn Sie stabile Ergebnisse benötigen. Die gesamte sequentielle Suchzeit ist proportional zur Dateigröße.

Beispiel

let offset = 0;
do {
    const page = await storage.findText("measurements.jsonl", "ART-001", { offset, limit: 16 });
    console.info(page.offsets);
    offset = page.nextOffset;
} while (offset !== null);

JSONL-Protokolle und Rotation

JSONL speichert pro Zeile ein unabhängiges JSON-Objekt, ohne Kommas zwischen Zeilen oder umgebende []. Dies unterstützt das Anhängen von Messwerten. Erzeugen Sie jede Zeile mit JSON.stringify(record)+"\n". Erkennen und behandeln Sie eine nach einer Unterbrechung unvollständige letzte Zeile gesondert. JSONL bietet weder einen automatischen Index noch das automatische Löschen alter Messungen.

// Size-limited JSONL log with one archive file.
let writing = false;
async function start() {
    if (!app.capabilities().features.files) throw new Error("Storage API is unavailable");
    console.info("Storage:", await storage.info());
    setInterval(async () => {
        if (writing) return;
        writing = true;
        try {
            const m = scale.read();
            if (!m.available) return;
            let size = 0;
            try { size = (await storage.stat("measurements.jsonl")).size; }
            catch (error) { if (error.code !== "NOT_FOUND") throw error; }
            if (size >= 32768) {
                await storage.remove("measurements-old.jsonl");
                await storage.rename("measurements.jsonl", "measurements-old.jsonl");
            }
            await storage.appendText("measurements.jsonl", JSON.stringify({ timeMs: m.timeMs, net: m.net, gross: m.gross, unit: m.unit }) + "\n");
        } catch (error) {
            console.warn(error.code || error.name, error.message);
        } finally {
            writing = false;
        }
    }, 10000);
}
start().catch(error => { console.error(error.code || error.name, error.message); app.stop(); });

Gemeinsame Speichergrenzen

Tabelle 38

Grenzwert seit Neutron AppEngine 1.0.0

Wert

Gemeinsames Anwendungskontingent

524288 Byte für Dateien und Datenbanken zusammen.

Systemreserve

131072 physisch freie Bytes vor zusätzlichen Schreibvorgängen. Andere Gerätefunktionen können die tatsächliche Verfügbarkeit verändern.

Datei oder einzelnes Datenbankprotokoll

262144 Byte.

Lese-/Schreibaufruf

4096 Byte.

Reguläre Dateien

Höchstens 64 Namen.

Reihenfolge

Speicheranfragen laufen in einer begrenzten Dienstwarteschlange. Mehrere Aufrufe sind keine Transaktion.

Beenden der Anwendung

Offene Datenbankobjekte werden freigegeben; festgeschriebene Daten bleiben erhalten.

Werkseinstellungen

Löscht auch Anwendungsdateien und Datenbanken.

11. Einfache lokale Datensatzdatenbank

Die lokale Datenbank speichert kleine JSON-Objekte mit eindeutigem Schlüssel, etwa einem Produktcode, Rezeptcode oder einer Geschäftsdatensatz-ID. Alle Funktionen dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar. Unterstützung: app.capabilities().features.records. Daten teilen sich Speicherplatz und Kontingent mit Dateien, die internen Datenbankdateien sind jedoch von der regulären Datei-API getrennt.

Das Öffnen prüft das Datensatzprotokoll und erstellt einen sortierten Schlüsselindex. get verwendet den Index und den direkten Datensatzoffset, ohne die gesamte Datenbank zu durchsuchen. Öffnen und Komprimieren durchsuchen Daten und können länger dauern; öffnen Sie einmal beim Start und verwenden Sie das Objekt erneut. Pro Datenbank wird ein indizierter Schlüssel unterstützt. Es gibt weder SQL noch Beziehungen, automatische Sekundärindizes oder Transaktionen über mehrere Datensätze.

storage.openRecords(name, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
const articles = await storage.openRecords("articles", { key: "code" });
Zweck. Eine Datenbank erstellen oder öffnen und ihren Index vorbereiten.
Beschreibung. Datenbankname und Schlüsselfeldname werden bei der Erstellung dauerhaft verknüpft. Verwenden Sie beim erneuten Öffnen denselben Schlüsselfeldnamen. Das Öffnen eines bereits geöffneten Namens wird abgelehnt; verwenden Sie das zurückgegebene Objekt erneut. Objekte sind nur während des aktuellen Anwendungslaufs gültig.

Parameter

Tabelle 39

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

1..32 Zeichen gemäß den Dateinamenregeln.

options.key

string / "id"

Name des Objektfelds der obersten Ebene.1..32 ASCII Zeichen: zuerst ein Buchstabe oder _, dann auch Ziffern. Jeder Datensatz muss dieses Feld als nicht leere Zeichenfolge enthalten.

Ergebnis

Promise<RecordStore> mit den Eigenschaften name und key sowie den Methoden put/get/delete/list/stat/compact/close.

Fehler und besondere Hinweise

SCHEMA_MISMATCH für ein anderes Schlüsselfeld in einer vorhandenen Datenbank; ALREADY_OPEN; QUOTA_EXCEEDED; NO_SPACE; CORRUPT; CANCELLED; OUT_OF_MEMORY. Höchstens 8 persistente Datenbanken und 2 gleichzeitig geöffnet. Ein unvollständiger Enddatensatz wird beim Öffnen entfernt; Ein Integritätsfehler in einem vollständigen Datensatz lehnt das Öffnen ab, anstatt Daten stillschweigend zu löschen.

Beispiel

const articles = await storage.openRecords("articles", { key: "code" });
// Reuse articles in application events and timers.
console.info(await articles.stat());

records.put(record)

Verfügbar seit: Neutron AppEngine 1.0.0
await articles.put({ code: "ART-001", name: "Flour", target: 25 });
Zweck. Ein Objekt einfügen oder den Datensatz mit demselben Schlüssel vollständig ersetzen.
Beschreibung. put ersetzt das gesamte Objekt, nicht einzelne Felder. Daten werden an das Protokoll angehängt und der festgeschriebene Datensatz aktualisiert den Index. Schlüssel unterscheiden Groß- und Kleinschreibung. Mehrere aufeinanderfolgende put-Aufrufe bilden keine gemeinsame Transaktion.

Parameter

Tabelle 40

Parameter

Typ / Anforderung

Beschreibung

record

object / erforderlich

JSON-serialisierbares Objekt, höchstens 2048 UTF-8 Bytes nach JSON.stringify und höchstens 16 verschachtelte Objekt-/Array-Ebenen. Das Schlüsselfeld muss eine Zeichenfolge von 1..64 UTF-8 Bytes ohne Steuerzeichen sein. Konvertieren Sie numerische IDs explizit mit String.

Ergebnis

Promise<object> mit dem gespeicherten JSON-Objekt.

Fehler und besondere Hinweise

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, CLOSED, CORRUPT. BigInt- und Zirkelverweise können nicht als JSON serialisiert werden. Ein Commit-Fehler kann dazu führen, dass das Schreibergebnis ungewiss ist. Öffnen Sie es erneut und überprüfen Sie „get“, bevor Sie es erneut versuchen. Zeichnen Sie nicht jeden Puls grenzenlos auf.

Beispiel

await articles.put({ code: "ART-001", name: "Flour", target: 25 });
await articles.put({ code: "ART-001", name: "Flour", target: 30 });
// The second call replaces the complete first record with that code.

records.get(key)

Verfügbar seit: Neutron AppEngine 1.0.0
const article = await articles.get("ART-001");
Zweck. Den letzten festgeschriebenen Datensatz schnell über den eindeutigen Schlüssel abrufen.
Beschreibung. Verwendet einen sortierten Index: Die Schlüsselsuche erfordert eine logarithmische Anzahl von Vergleichen und das Lesen des ausgewählten Datensatzes. Durchsucht nicht alle Objekte. Gibt ein neues Objekt zurück; dessen Änderung in JavaScript ändert die Datenbank nicht von selbst.

Parameter

Tabelle 41

Parameter

Typ / Anforderung

Beschreibung

key

string / erforderlich

Exakter Schlüssel, 1..64 UTF-8-Byte, ohne Steuerzeichen.

Ergebnis

Promise<object|null>. null bedeutet, dass der Schlüssel fehlt.

Fehler und besondere Hinweise

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT. Andere Felder werden nicht indiziert. Behandeln Sie Zeichenfolgen-IDs nicht als Zahlen: "001" und "1" sind unterschiedliche Schlüssel.

Beispiel

const article = await articles.get("ART-001");
if (article === null) console.warn("Article not found");
else console.info(article.name, article.target);

records.delete(key)

Verfügbar seit: Neutron AppEngine 1.0.0
const deleted = await articles.delete("ART-001");
Zweck. Einen Datensatz aus der aktiven Liste der Datenbank entfernen.
Beschreibung. Hängt normalerweise einen festgeschriebenen Löschdatensatz an; alte Daten können bis zur Komprimierung erhalten bleiben. Das Löschen ist kein sicheres Löschen physischer Medien. Das Löschen eines nicht vorhandenen Schlüssels ist zulässig.

Parameter

Tabelle 42

Parameter

Typ / Anforderung

Beschreibung

key

string / erforderlich

Schlüssel gemäß denselben Regeln wie bei get.

Ergebnis

Promise<boolean>:true, wenn der Datensatz existierte, andernfalls false.

Fehler und besondere Hinweise

INVALID_ARGUMENT, CLOSED, NO_SPACE, WRITE_FAILED, CORRUPT. Bei Erreichen des Protokolllimits kann das Löschen eine Komprimierung auslösen, die temporären Speicherplatz erfordert.

Beispiel

const deleted = await articles.delete("ART-002");
console.info("Deleted:", deleted);

records.list(options?)

Verfügbar seit: Neutron AppEngine 1.0.0
const page = await articles.list({ cursor: null, limit: 16 });
Zweck. Aktive Datensätze Seite für Seite in Schlüsselreihenfolge lesen.
Beschreibung. Datensätze folgen der Byte-Reihenfolge der Schlüssel. cursor schließt den letzten Schlüssel der vorherigen Seite aus. Antwortgrößenlimits können eine Seite auf weniger als limit verkürzen. Durchlaufen Sie für nicht indizierte Felder die Seiten und filtern Sie in JavaScript; dies ist keine schnelle indizierte Suche.

Parameter

Tabelle 43

Parameter

Typ / Anforderung

Beschreibung

options.cursor

string | null / weggelassen

Zurückgegebenes nextCursor aus der vorherigen Seite.

options.limit

Ganzzahl / 16

1..32 Datensätze, zusätzlich begrenzt durch Objekt- und Antwortgrößen.

Ergebnis

{records:object[], nextCursor:string|null}. null markiert das Ende. Das Ändern der Datenbank zwischen Seiten bedeutet, dass die Ergebnisse keine unveränderliche Momentaufnahme sind.

Fehler und besondere Hinweise

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT, OUT_OF_MEMORY. Vermeiden Sie es, jede Seite in einem großen Array anzusammeln, wenn nur ein Ergebnis benötigt wird.

Beispiel

let cursor = null;
do {
    const page = await articles.list({ cursor, limit: 8 });
    for (const record of page.records) {
        if (record.target >= 25) console.info(record.code, record.target);
    }
    cursor = page.nextCursor;
} while (cursor !== null);

records.stat()

Verfügbar seit: Neutron AppEngine 1.0.0
const status = await articles.stat();
Zweck. Anzahl aktiver Datensätze, Protokollgröße und Schlüsselfeld lesen.
Beschreibung. Die Protokollgröße umfasst ersetzte Datensätze und Löschungen, nicht nur aktuell aktive Objekte.

Parameter

Keine Parameter.

Ergebnis

{count:number, bytes:number, key:string}.

Fehler und besondere Hinweise

CLOSED oder CORRUPT. Höchstens 2048 aktive Datensätze pro Datenbank; Größenlimits und gemeinsames Kontingent können die erreichbare Anzahl reduzieren.

Beispiel

console.info(await articles.stat());

records.compact()

Verfügbar seit: Neutron AppEngine 1.0.0
await articles.compact();
Zweck. Alte Versionen und Löschungen aus dem Protokoll entfernen, um Speicherplatz freizugeben.
Beschreibung. Kopiert nur aktive Datensätze in eine temporäre Datei, prüft sie und schreibt sie fest; anschließend wird die alte Datenbank ersetzt. Bei Unterbrechung bleibt entweder die alte oder die neue festgeschriebene Datenbank erhalten. put oder delete können die Komprimierung auch auslösen, wenn das Protokoll 262144 Byte erreicht.

Parameter

Keine Parameter.

Ergebnis

Promise<undefined>. Aktive Schlüssel und Werte bleiben unverändert.

Fehler und besondere Hinweise

NO_SPACE für die temporäre Kopie, WRITE_FAILED, READ_FAILED, CANCELLED, CORRUPT, OUT_OF_MEMORY. Kann länger dauern und die Speicherdienstwarteschlange belegen; führen Sie dies nicht nach jeder Messung aus. Nach QUOTA_EXCEEDED des gemeinsamen Kontingents kann ausdrückliches Komprimieren veraltete Inhalte entfernen, bevor ein Schreibvorgang erneut versucht wird.

Beispiel

await articles.compact();
console.info("After compaction:", await articles.stat());

records.close()

Verfügbar seit: Neutron AppEngine 1.0.0
await articles.close();
Zweck. Das offene Objekt und den Index freigeben, während die Daten erhalten bleiben.
Beschreibung. Nachfolgende Objektmethoden geben CLOSED zurück. Wiederholtes close ist unproblematisch. Öffnen Sie bei Bedarf erneut mit demselben Datenbanknamen und Schlüsselfeld. Beim Beenden gibt die Anwendung ihre offenen Objekte automatisch frei.

Parameter

Keine Parameter.

Ergebnis

Promise<undefined>.

Fehler und besondere Hinweise

BUSY, wenn die Warteschlange voll ist. Vor dem Schließen in die Warteschlange gestellte Vorgänge werden möglicherweise zuerst abgeschlossen. Die Verwendung eines geschlossenen Objekts wird abgelehnt.

Beispiel

try {
    console.info(await articles.get("ART-001"));
} finally {
    await articles.close();
}

storage.removeRecords(name)

Verfügbar seit: Neutron AppEngine 1.0.0
const removed = await storage.removeRecords("articles");
Zweck. Eine gesamte lokale Datenbank und ihr Schema löschen.
Beschreibung. Die Datenbank muss geschlossen sein. Namen finden Sie in storage.info().databases. Nach dem Löschen kann derselbe Name mit einem anderen Schlüsselfeld erstellt werden.

Parameter

Tabelle 44

Parameter

Typ / Anforderung

Beschreibung

name

string / erforderlich

Datenbankname, 1..32 Zeichen.

Ergebnis

Promise<boolean>:true, wenn es existierte, andernfalls false.

Fehler und besondere Hinweise

RESOURCE_IN_USE für eine offene Datenbank, INVALID_ARGUMENT, WRITE_FAILED. Das Löschen der gesamten Datenbank kann nicht rückgängig gemacht werden.

Beispiel

await articles.close();
// Execute only if you want to remove all products:
// await storage.removeRecords("articles");

Vollständiges Beispiel einer lokalen Produktdatenbank

// Simple local product database. Data survives Stop and restart.
async function start() {
    if (!app.capabilities().features.records) throw new Error("Local records API is unavailable");
    const articles = await storage.openRecords("articles", { key: "code" });
    try {
        // put inserts or fully replaces the record with the same code.
        await articles.put({ code: "ART-001", name: "Flour", target: 25, tolerance: 0.1 });
        await articles.put({ code: "ART-002", name: "Sugar", target: 10, tolerance: 0.05 });
        const article = await articles.get("ART-001");
        console.info("Article:", article);
        let cursor = null;
        do {
            const page = await articles.list({ cursor, limit: 8 });
            for (const record of page.records) console.info(record.code, record.name);
            cursor = page.nextCursor;
        } while (cursor !== null);
        console.info("Database:", await articles.stat());
        // await articles.delete("ART-002");
        // await articles.compact(); // Reclaim obsolete records after many updates.
    } finally {
        await articles.close();
    }
}
start().catch(error => {
    console.error(error.code || error.name, error.message);
    app.stop();
});

Prüfen von Persistenz und Wiederherstellung

Tabelle 45

Test

Erwartetes Ergebnis

put zweimal mit demselben Code

get gibt die letzte vollständige Version zurück; count erhöht sich nicht.

Stop, neuer Run oder normaler Neustart

Derselbe Name und Schlüssel öffnen gespeicherte Daten; der Index wird neu aufgebaut.

Stromausfall beim Anhängen

Es bleiben vollständig festgeschriebene Datensätze erhalten. Ein unvollständiger Enddatensatz wird beim Öffnen verworfen. Der Ausgang der letzten unbestätigten Operation ist möglicherweise ungewiss.

Integritätsfehler in einem vollständigen Datensatz

CORRUPT; die gesamte Datenbank wird nicht automatisch gelöscht.

compact und erneut öffnen

Aktive Datensätze bleiben unverändert; das Protokoll schrumpft, wenn alte Versionen vorhanden waren.

Kontingent erreicht

QUOTA_EXCEEDED oder NO_SPACE ohne unbegrenztes Datenwachstum.

Werkseinstellungen

Benutzerdateien und Datenbanken werden gelöscht.

Zugriff auf ein geschlossenes Objekt oder eines aus einem vorherigen Lauf

CLOSED oder Ablehnung einer veralteten Anfrage.

12. Kommunikationsmodule

Kommunikationsmodule sind von Laufzeitumgebung, Wägemodul und Anwendungsverwaltung getrennt. Jedes hat eigene Anforderungen, Funktionen, Ereignisse, Fehler und Grenzen. Anwendungen ohne Kommunikationsmodule können Laufzeitumgebung, Diagnose, Timer und Waage normal verwenden.

Tabelle 46

Modul

Unterstützung in Neutron AppEngine 1.0.0

Kapitel

TCP

Implementiert; features.tcp=true

RS-232 / RS-485

Implementiert; features.serial=true

MQTT

Implementiert; features.mqtt=true

HTTP / REST

Implementiert; features.http=true

WebSocket

Implementiert; features.websocket=true

Das Hochladen einer Anwendung über MQTT, HTTP oder BLE ist ein Verwaltungsvorgang. Dieses Protokoll wird im Benutzercode nicht aktiviert. Siehe Installation und APP Protokoll für Verwaltungsverfahren.

13. TCP-Kommunikation

configuredMode: 0 disabled, 1 server, 2 client, 3 both. Der Beispielwert 1 dient der Veranschaulichung. maxLineBytes ist die maximal konfigurierbare Grenze; der Parser verwendet standardmäßig 1024 Byte.

Das TCP-Modul konfiguriert den vorhandenen Server und Client, übernimmt ihre Datenströme für ein eigenes Protokoll, sendet Daten und meldet Verbindungsereignisse. Modi: disabled, server, client, both. Im Modus both gibt es einen Server mit einer aktiven Gegenstelle und eine ausgehende Clientverbindung. Die API öffnet keine beliebige Anzahl von Sockets und unterstützt weder TLS noch DNS-Namen; client.host muss IPv4 sein. Alle Funktionen und Ereignisse dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar.

Deaktivieren Sie vor Netzwerkkonfiguration oder Übernahme das systemseitige Wägeprotokoll auf I_TCP sowie die TCP–MQTT- und TCP–RS-232/RS-485-Brücken; andernfalls RESOURCE_IN_USE. Netzwerkkonfiguration und Übernahme sind getrennt: configure speichert und übernimmt Einstellungen; claim leitet Daten an die Anwendung weiter. Verwenden Sie nach erfolgreichem configure await tcp.claim().

13.1 tcp.configure()

Verfügbar seit: Neutron AppEngine 1.0.0
const status = await tcp.configure(options);
Zweck. TCP-Rollen, Netzwerkparameter und die Abgrenzung von Textzeilen konfigurieren.
Beschreibung. Weggelassene Felder bleiben unverändert. Netzwerkeinstellungen werden über vorhandene Modulattribute dauerhaft gespeichert und ohne Gerätestart übernommen. Eine geänderte Rolle wird neu initialisiert, während die andere ihre Verbindung behält. Identische Werte unterbrechen intakte Verbindungen nicht. Änderungen an exclusive betreffen neue Verbindungen, ohne die aktuelle Gegenstelle zu trennen. Das Promise bestätigt die Übernahme der Einstellungen, nicht die Verbindung zu einem entfernten System. Ohne Netzwerk bleiben Einstellungen gespeichert und die Rolle in waitingNetwork. Überwachen Sie state/status auf Verbindungsfehler. Lokale Zeileneinstellungen gelten nach Erfolg und verwerfen unvollständige Zeilen. Werden nur delimiter/maxLineBytes angegeben, gelten diese aus Kompatibilitätsgründen sofort; dennoch wird ein Promise zurückgegeben.

Parameter

Tabelle 47

Parameter

Typ / Anforderung

Beschreibung

options

object / erforderlich

Objekt mit optionalen Feldern; Unbekannte Felder werden abgelehnt.

options.mode

string / optional

disabled, server, client oder both. CTY: 0, 1, 2, 3. Disabled beendet beide Rollen und gibt die Kontrolle frei.

options.server

object / optional

Serverkonfiguration: port und exclusive.

options.server.port

Ganzzahl / optional

1–65535; vorhandenes Attribut S0C. S0P konfiguriert einen seriellen Port, nicht TCP.

options.server.exclusive

boolean / optional

S0M: true=1, false=0. Ein aktivierter Wert lehnt neue Gegenstellen ab, solange die aktuelle Gegenstelle verbunden ist; false erlaubt deren Ersetzung durch eine neue Gegenstelle.

options.client

object / optional

Konfiguration der ausgehenden Verbindung: host und port.

options.client.host

string / optional

IPv4-Adresse des Remote-Servers, zum Beispiel 192.168.50.100. SIP-Attribut; keine führenden Nullen in Oktetten.0.0.0.0 und 255.255.255.255 sind verboten.

options.client.port

Ganzzahl / optional

1–65535; SPO-Attribut.

options.delimiter

string / Standard CRLF

1–8 ASCII Bytes. Gilt nur für den Parser der aktuellen Anwendung; nicht in Attributen gespeichert.

options.maxLineBytes

Ganzzahl / Standard 1024

1–4096 Inhaltsbyte ohne Trennzeichen. Nur für die aktuelle Anwendung.

Ergebnis

Promise<object> mit einer Momentaufnahme von tcp.status(). Einstellungen aktiver Rollen müssen auch dann vollständig sein, wenn nur ein Teil des Objekts geändert wird. Bei vorhandener gültiger Konfiguration reicht eine Teilaktualisierung. SMD-Änderungen über BLE, MQTT, HTTP oder device.settings.write verwenden denselben Übernahmemechanismus.

Fehler und besondere Hinweise

INVALID_ARGUMENT bei ungültigen oder unvollständigen aktiven Einstellungen; die JavaScript-Argumentvalidierung wirft synchron eine Ausnahme. Netzwerkanfragen können mit RESOURCE_IN_USE, BUSY, WRITE_FAILED, CONFIGURE_FAILED oder OUT_OF_MEMORY abgelehnt werden. Nach einem Schreibfehler können einige Einstellungen bereits gespeichert sein; Fehler beim Serverstart behalten Einstellungen bei und wiederholen den Start. Prüfen Sie status und beheben Sie die Ursache. CONFIG_CHANGED unterbricht ausstehende Schreibvorgänge für die geänderte Rolle. Eine zu lange Zeile löst MESSAGE_TOO_LARGE vor dem line-Callback aus und beendet die Anwendung; try/catch innerhalb dieses Callbacks kann dies nicht abfangen.

Beispiel

async function start() {
    await tcp.configure({
        mode: "server", server: { port: 5000, exclusive: true },
        delimiter: "\r\n", maxLineBytes: 512
    });
    await tcp.claim();
    console.info(JSON.stringify(tcp.status()));
}
start().catch(error => { console.error(error.code, error.message); app.stop(); });
// Alternative: outbound connection or both roles.
async function configureClient() {
    await tcp.configure({mode: "client", client: {host: "192.168.50.100", port: 5000}});
    await tcp.claim();
}
// For both roles use mode: "both" and supply server and client.
// The example does not call configureClient() to avoid automatic configuration changes.

13.2 tcp.claim()

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await tcp.claim();
Zweck. Den vorhandenen TCP-Kanal für ein eigenes Protokoll übernehmen.
Beschreibung. Fordert die Übergabe vorhandener TCP-Datenströme an die Benutzeranwendung an. Registrieren Sie Callbacks vor der Übernahme. Der Vorgang garantiert nicht, dass eine entfernte Gegenstelle verbunden ist.

Parameter

Keine Parameter.

Ergebnis

Promise<string>, bei Erfolg "claimed". Datenereignisse und Senden werden bei bestehender Verbindung verfügbar. Diagnostische connection/state-Ereignisse sind ohne Übernahme verfügbar; registrieren Sie Listener vor configure/claim.

Fehler und besondere Hinweise

NOT_CONFIGURED bei deaktiviertem/ungültigem TCP-Modus, RESOURCE_IN_USE bei Konflikten mit Systemprotokoll oder Brücken; außerdem BUSY und OUT_OF_MEMORY.

Beispiel

async function start() {
    tcp.configure({ delimiter: "\r\n", maxLineBytes: 512 });
    tcp.on("line", event => console.log(event.connectionId, event.line));
    await tcp.claim();
    console.info("TCP protocol ready; waiting for connection");
}
start().catch(error => { console.error(error.code, error.message); app.stop(); });

13.3 tcp.release()

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await tcp.release();
Zweck. Die übernommene TCP-Schnittstelle an die Firmware zurückgeben.
Beschreibung. Schließt übernommene Server-/Client-Verbindungen, gibt die Kontrolle frei und verwirft unvollständige Zeilen. JavaScript-Listener und Timer bleiben erhalten. Der konfigurierte Dienst bleibt verfügbar; der Systemclient kann sich erneut verbinden.

Parameter

Keine Parameter.

Ergebnis

Promise<string>,"released" auf Erfolg. Die Anwendung läuft weiter.

Fehler und besondere Hinweise

Gemeinsame Fehler BUSY und OUT_OF_MEMORY. Brechen Sie Sendetimer ab und behandeln Sie ausstehende Schreibvorgänge vor der Freigabe.

Beispiel

async function releaseTcp() {
    try { console.info(await tcp.release()); }
    catch (error) { console.warn(error.code, error.message); }
}
releaseTcp();

13.4 tcp.write()

Verfügbar seit: Neutron AppEngine 1.0.0
const bytesWritten = await tcp.write(data, { connectionId });
Zweck. Text oder Binärdaten über eine übernommene Verbindung senden.
Beschreibung. Codiert Zeichenfolgen als UTF-8 und sendet Uint8Array als Bytes. Fügt kein CRLF oder anderes Trennzeichen hinzu. Der Versand erfolgt asynchron; Übermittelte Schreibvorgänge auf einer Verbindung behalten die Reihenfolge bei, aber die asynchrone Benutzerlogik kann die Übermittlungsreihenfolge ändern.

Parameter

Tabelle 48

Parameter

Typ / Anforderung

Beschreibung

data

string oder Uint8Array / erforderlich

Höchstens 4096 Bytes pro Aufruf. Nach der Kodierung UTF-8 gelten Zeichenfolgenbeschränkungen.

options

object / optional, Standardwert {}

Sendeoptionen.

options.connectionId

Ganzzahl / optional

0 oder weggelassen: Wählen Sie die einzige verbundene TCP-Rolle aus. Verwenden Sie bei mehreren verbundenen Rollen das ID aus dem Ereignis; Bereich 0–4 294 967 295.

Ergebnis

Promise<number> mit den zur TCP-Übertragung angenommenen Byte. Bestätigt weder Empfang noch Verarbeitung auf der Gegenstelle. Definieren Sie bei Bedarf Bestätigungen in Ihrem Protokoll.

Fehler und besondere Hinweise

Abgelehnt mit INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, NOT_CONNECTED, CONFIG_CHANGED, BUSY, OUT_OF_MEMORY oder TIMEOUT. Das Schreibwartelimit beträgt ungefähr 3 s. Möglicherweise wurden nach einem Fehler bereits einige Daten gesendet; Versuchen Sie nicht blind, nicht-idempotente Befehle erneut auszuführen. Ein aktiver Schreibfehler/Timeout kann die Verbindung schließen. Falsche Verwendung des Arguments JavaScript kann auch TypeError auslösen.

Beispiel

tcp.on("line", async event => {
    try {
        const n = await tcp.write("OK\r\n", { connectionId: event.connectionId });
        console.debug("Bytes sent:", n);
    } catch (error) {
        console.warn("Sending:", error.code, error.message);
    }
});

13.5 tcp.on()

Verfügbar seit: Neutron AppEngine 1.0.0
tcp.on(eventName, callback);
Zweck. Einen TCP-Ereignislistener registrieren.
Beschreibung. Ruft den Callback für passende Ereignisse bis zu off oder zur Beendigung der Anwendung auf. Dieselbe Funktion kann mehrfach registriert werden; jede Registrierung zählt zum Limit.

Parameter

Tabelle 49

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

Nur "data", "line", "connection" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt. Behalten Sie dieselbe Referenz für off bei.

Ergebnis

Das tcp-Objekt; ermöglicht verkettete Registrierungen.

Fehler und besondere Hinweise

Synchrones INVALID_ARGUMENT bei unbekanntem Ereignis oder einem Wert, der keine Funktion ist. Höchstens 32 on/once-Listener zusammen; Überschreitung löst QUOTA_EXCEEDED aus. Eine unbehandelte Callback-Ausnahme oder Promise-Ablehnung beendet die Anwendung. off hat bei fehlender Registrierung keine Wirkung.

Beispiel

function receive(event) { console.log(event.line); }
tcp.on("line", receive);

13.6 tcp.once()

Verfügbar seit: Neutron AppEngine 1.0.0
tcp.once(eventName, callback);
Zweck. Einen einmaligen Listener registrieren.
Beschreibung. Entfernt den Listener, bevor er für das erste passende Ereignis aufgerufen wird. Bleibt registriert, wenn kein Ereignis eintrifft.

Parameter

Tabelle 50

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

Nur "data", "line", "connection" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt. Behalten Sie dieselbe Referenz für off bei.

Ergebnis

Das tcp-Objekt; ermöglicht verkettete Registrierungen.

Fehler und besondere Hinweise

Synchrones INVALID_ARGUMENT bei unbekanntem Ereignis oder einem Wert, der keine Funktion ist. Höchstens 32 on/once-Listener zusammen; Überschreitung löst QUOTA_EXCEEDED aus. Eine unbehandelte Callback-Ausnahme oder Promise-Ablehnung beendet die Anwendung. off hat bei fehlender Registrierung keine Wirkung.

Beispiel

tcp.once("connection", event => {
    console.info("Prva sprememba povezave", event.connectionId, event.connected);
});

13.7 tcp.off()

Verfügbar seit: Neutron AppEngine 1.0.0
tcp.off(eventName, callback);
Zweck. Einen Listener entfernen.
Beschreibung. Entfernt alle Registrierungen derselben Callbackreferenz für das ausgewählte Ereignis. Unterbricht einen bereits gestarteten async-Callback nicht. Übergeben Sie keine neue anonyme Funktion, um einen vorhandenen Listener zu entfernen.

Parameter

Tabelle 51

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

Nur "data", "line", "connection" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt. Behalten Sie dieselbe Referenz für off bei.

Ergebnis

Das tcp-Objekt; ermöglicht verkettete Registrierungen.

Fehler und besondere Hinweise

Synchrones INVALID_ARGUMENT bei unbekanntem Ereignis oder einem Wert, der keine Funktion ist. Höchstens 32 on/once-Listener zusammen; Überschreitung löst QUOTA_EXCEEDED aus. Eine unbehandelte Callback-Ausnahme oder Promise-Ablehnung beendet die Anwendung. off hat bei fehlender Registrierung keine Wirkung.

Beispiel

function receive(event) { console.log(event.line); }
tcp.on("line", receive);
tcp.off("line", receive);

13.8 Struktur der TCP-Ereignisse

Tabelle 52

Ereignis

Felder

Bedeutung

data

{ connectionId, data: Uint8Array }

Roher TCP-Stream-Block. Ein Ereignis ist nicht unbedingt ein Befehl oder ein Netzwerkpaket.

line

{ connectionId, line: string }

Vollständige UTF-8 dekodierte Zeile ohne Trennzeichen. Leerzeilen sind erlaubt; Leerzeichen werden nicht automatisch entfernt.

connection

{ connectionId, connected: boolean, role: "server" | "client", remoteAddress, remotePort, reason, timeMs }

Verbindung während des Anwendungslaufs hergestellt oder getrennt, unabhängig für jede Rolle. connectionId identifiziert die Sitzung; verwenden Sie nach dem erneuten Verbinden eine neue ID.

connection.reason: CONNECTED bei Erfolg, CONFIG_CHANGED nach Adress-/Port-/Rollenänderungen, REPLACED beim Ersetzen einer Servergegenstelle, NETWORK_DOWN bei Verlust des Netzwerkdienstes, CONNECTION_LOST bei erkanntem Verbindungsverlust, DISCONNECTED bei regulärem Schließen, APP_STOPPED bei Freigabe nach Beendigung der Anwendung, RESOURCE_IN_USE bei Konflikten. Ereignisse nach Beendigung der Anwendung werden nicht zugestellt. timeMs ist die monotone Gerätezeit in Millisekunden, kein Datum und keine Verbindungsdauer. Der entfernte Port einer Servergegenstelle ist normalerweise ein kurzlebiger Port und nicht der Empfangsport des Servers.

state enthält role, state, connected, connectionId, port, revision, error und timeMs sowie rollenspezifische Eigenschaften aus tcp.status(). Serverzustände: disabled, waitingNetwork, listening, error. Clientzustände: disabled, waitingNetwork, connecting, reconnecting, connected, error. Eine konfliktbedingte Freigabe kann {role:"all", state:"released", reason:"RESOURCE_IN_USE"} auslösen. Client-Verbindungsversuche blockieren weder Anwendung noch Messungen; jeder dauert bis zu etwa 3 s, ein weiterer beginnt etwa 5 s nach einem Fehler oder einer erkannten Trennung. Bei fehlgeschlagenem Serverstart wird der Versuch etwa alle 5 s wiederholt. Die Erkennung einer physischen Trennung erfolgt nicht sofort; sie hängt vom Datenverkehr und der Verbindungsüberwachung ab.

tcp.on("state", event => console.info("TCP state", JSON.stringify(event)));
tcp.on("connection", event => {
    console.info(event.role, event.connected, event.connectionId,
        event.remoteAddress, event.remotePort, event.reason, event.timeMs);
});
Die Registrierung spielt keine Ereignishistorie erneut ab. Bei der Übernahme kann eine bereits bestehende Verbindung gemeldet werden. Antworten Sie immer über event.connectionId; speichern Sie diesen Wert niemals dauerhaft und erfinden Sie keine IDs.
TCP ist ein Stream.WEIGHT?\r\n kann in mehreren Blöcken und mehrere Befehle in einem Block ankommen. Der Parser behält Teilzeilen pro Verbindung bei und setzt Teilzeichen UTF–8 zusammen, bevor er Zeilenereignisse dekodiert. Trennzeichen und unvollständige Zeilen werden beim Trennen der Verbindung verworfen.

Mit einem line-Listener werden zuerst Zeilen aus einem Datenstromblock vorbereitet, dann wird data ausgelöst, gefolgt von den einzelnen line-Callbacks. Die Registrierung beider liefert zwei Ansichten derselben Daten; verarbeiten Sie Befehle nicht doppelt. Ohne line-Listener werden Binärdaten nicht in einem Zeilenpuffer gesammelt. Binärprotokolle müssen eigene Längenlimits und das Zusammensetzen von Nachrichten implementieren.

tcp.on("data", async event => {
    // Binary echo example; adds no terminators.
    try { await tcp.write(event.data, { connectionId: event.connectionId }); }
    catch (error) { console.warn(error.code, error.message); }
});

13.9 Fehler des TCP-Moduls

Tabelle 53

Code

Bedeutung für TCP

NOT_CONFIGURED

TCP ist nicht für den Client/Server-Betrieb konfiguriert.

RESOURCE_IN_USE

Das systemseitige TCP-Wägeprotokoll oder eine Brücke steht im Konflikt mit der Übernahme.

NOT_OWNER

Die Anwendung hat TCP nicht übernommen oder ein Routing-Konflikt ist aufgetreten.

NOT_CONNECTED

Die angeforderte TCP-Sitzung ist nicht mehr verbunden.

MESSAGE_TOO_LARGE

Der Schreibvorgang überschreitet 4096 Byte oder die empfangene Zeile ist zu lang. Ein interner Zeilenfehler beendet die Anwendung.

13.10 Grenzen des TCP-Moduls

Tabelle 54

Ressource

Grenzwert

TCP-Nachricht

Höchstens 4096 Bytes pro Schreibvorgang; Empfangene Streams können in kleinere Teile aufgeteilt werden.

Zeilen

Standard 1024; konfigurierbare 1–4096 Bytes ohne Trennzeichen; ASCII Trennzeichenlänge 1–8 Bytes.

Listener

Höchstens 32 on/once-Registrierungen zusammen über data, line, connection und state.

13.11 Eigenes TCP-Protokoll mit CONT / CCONT

Standalone-Beispiel für einen konfigurierten TCP-Server oder -Client ohne widersprüchliches Systemrouting. Jede Zeile endet mit den tatsächlichen CR LF Bytes. Externe Tools müssen diese Bytes senden, nicht vier Literal-Backslash-R-Backslash-N-Zeichen. In der JavaScript-Quelle stellt "\r\n" die korrekten Abschlussbytes dar.

Tabelle 55

Empfangener Befehl + CRLF

Antwort + CRLF

WEIGHT?

net,gross,unit oder ERR,NO_MEASUREMENT

CONT

OK; dann eine Messung pro Sekunde für die gleiche Verbindung. Durch das Wiederholen entsteht kein zusätzliches Intervall.

CCONT

OK; bricht zukünftige regelmäßige Sendungen über diese Verbindung ab. Ein bereits begonnener Schreibvorgang kann abgeschlossen werden.

TARE / ZERO / CLEAR_TARE

OK nach einem bestätigten Vorgang oder ERR,&lt; code&gt;.

PRESET_TARE 2.5

Setzt die Tara in der aktuell konfigurierten Einheit; gibt OK oder ERR,&lt; code&gt; zurück.

Anderer Befehl

ERR,UNKNOWN_COMMAND

// Disable system TCP protocol and RS-232/RS-485/MQTT bridges.
// On startup this example configures and saves a TCP server on port 5000.
// CONT starts sending each second; CCONT stops it for the same connection.
const streams = new Map();

function weightReply() {
    const m = scale.read();
    return m.available ? m.net + "," + m.gross + "," + m.unit : "ERR,NO_MEASUREMENT";
}

function stopStream(connectionId) {
    const stream = streams.get(connectionId);
    if (!stream) return;
    clearInterval(stream.intervalId);
    streams.delete(connectionId);
}

function startStream(connectionId) {
    if (streams.has(connectionId)) return;
    const stream = { intervalId: 0, sending: false };
    stream.intervalId = setInterval(async () => {
        if (stream.sending) return;
        stream.sending = true;
        try {
            await tcp.write(weightReply() + "\r\n", { connectionId });
        } catch (error) {
            stopStream(connectionId);
            console.warn("Continuous send stopped:", error.code, error.message);
        } finally {
            stream.sending = false;
        }
    }, 1000);
    streams.set(connectionId, stream);
}

tcp.configure({ delimiter: "\r\n", maxLineBytes: 512 });

tcp.on("connection", event => {
    if (!event.connected) stopStream(event.connectionId);
    console.info("TCP", event.connectionId, event.connected ? "connected" : "disconnected");
});

tcp.on("line", async event => {
    let reply;
    try {
        switch (event.line.trim()) {
        case "WEIGHT?": {
            reply = weightReply();
            break;
        }
        case "TARE":
            await scale.tare(); reply = "OK"; break;
        case "ZERO":
            await scale.zero(); reply = "OK"; break;
        case "CLEAR_TARE":
            await scale.clearTare(); reply = "OK"; break;
        case "CONT":
            startStream(event.connectionId);
            reply = "OK";
            break;
        case "CCONT":
            stopStream(event.connectionId);
            reply = "OK";
            break;
        default:
            if (event.line.startsWith("PRESET_TARE ")) {
                await scale.setPresetTare(Number(event.line.substring(12)));
                reply = "OK";
            } else {
                reply = await scale.cmd(event.line.trim());
            }
        }
    } catch (error) {
        reply = "ERR," + (error.code || "FAILED");
    }
    try {
        await tcp.write(reply + "\r\n", { connectionId: event.connectionId });
    } catch (error) {
        console.warn("Reply failed:", error.code, error.message);
    }
});

async function start() {
    await tcp.configure({mode: "server", server: {port: 5000, exclusive: true}});
    await tcp.claim();
    console.info("Custom TCP scale protocol ready");


}

start().catch(error => {
    console.error(error.code || error.name, error.message);
    app.stop();
});

Der connection-Listener entfernt das Intervall bei Trennung; auch ein fehlgeschlagener periodischer Schreibvorgang beendet es. Ein Sende-Flag verhindert sich überlappende periodische Schreibvorgänge pro Verbindung. Das Beispiel implementiert kein dauerhaftes Protokoll, keine Bestätigung der entfernten Verarbeitung und keine Anfrage-IDs. Ergänzen Sie bei Bedarf begrenzte IDs, Antworten und Wiederholungsregeln.

13.12 TCP-Beendigung und Nebenläufigkeit

app.stop() schließt übernommene TCP-Verbindungen und gibt die Kontrolle frei. Der konfigurierte Server bleibt verfügbar und der Client kann sich gemäß Systemlogik erneut verbinden. Verwenden Sie tcp.release(), um TCP zurückzugeben, ohne die Anwendung zu beenden. Mehrere empfangene Befehle können sich in der asynchronen Verarbeitung überlappen; lassen Sie den Client für eine strikte Reihenfolge auf eine Antwort warten oder implementieren Sie eine begrenzte Warteschlange. clearInterval bricht keinen bereits begonnenen Schreibvorgang ab.

13.13 Prüfen einer TCP-Anwendung

Tabelle 56

Test

Erwartetes Ergebnis

TCP Befehlsaufteilung auf mehrere Empfänge

Der line-Callback wird erst nach dem vollständigen Trennzeichen ausgelöst.

CONT zweimal, dann CCONT zweimal

Ein Intervall pro Verbindung; wiederholtes Abbrechen ist unproblematisch.

Trennen / erneut verbinden

Alte Intervalle und IDs werden nicht wiederverwendet; Die neue Sitzung ist unabhängig.

Langsamer / fehlgeschlagener TCP-Schreibvorgang

Keine überlappenden periodischen Arbeiten oder unbegrenzte Warteschlange.

13.14 tcp.status()

Verfügbar seit: Neutron AppEngine 1.0.0
const status = tcp.status();
Zweck. Aktuelle Konfiguration und Zustand beider TCP-Rollen lesen.
Beschreibung. Synchrone Momentaufnahme aus dem letzten Dienstzyklus. Öffnet keine Verbindungen, übernimmt keine Schnittstelle und liest keine Datenströme. pending bedeutet, dass gespeicherte Einstellungen im nächsten Dienstzyklus übernommen werden. Der Verbindungszustand ändert sich nach configure weiter; verwenden Sie connection/state-Ereignisse, um nach dem Verbindungsaufbau fortzufahren.

Parameter

Keine Parameter.

Ergebnis

Objekt: mode (disabled/server/client/both), configuredMode (0/1/2/3), claimed, pending, server und client. Beide Rollen enthalten state, connected, connectionId (0 bei getrennter Verbindung), port, revision und error. Server enthält zusätzlich listening, exclusive, remoteAddress und remotePort; client enthält host, remoteAddress und remotePort. Ein leeres error bedeutet, dass kein Fehler verzeichnet ist. revision ändert sich bei Änderungen an Endpunkt/Rolle; es ist kein Zähler empfangener Daten. Diese informative Momentaufnahme kann sich unmittelbar nach dem Lesen ändern.

Fehler und besondere Hinweise

Keine Netzwerkanfrage. Ein verbundener Snapshot garantiert nicht, dass ein späterer Schreibvorgang erfolgreich ist; Schreibablehnung immer behandeln.

Beispiel

const status = tcp.status();
console.info(status.mode, status.claimed, status.server.state, status.client.state);
console.info(JSON.stringify(status));

Beispiel für Konfiguration und einfaches WEIGHT?-Protokoll für beide Rollen: Wählen Sie den gewünschten Modus in configuration und passen Sie Adresse/Port an. Antworten verwenden die connectionId des empfangenen Ereignisses, sodass sie auch funktionieren, wenn beide Rollen verbunden sind.

// Neutron AppEngine 1.0.0. Disable system TCP protocol and TCP/MQTT/serial bridges.
// Settings persist. Adjust the object below for client/both.
const configuration = {
    mode: "server",
    server: { port: 5000, exclusive: true },
    // mode: "client", client: { host: "192.168.50.100", port: 5000 },
    delimiter: "\r\n",
    maxLineBytes: 512
};

tcp.on("state", event => console.info("TCP state", JSON.stringify(event)));
tcp.on("connection", event => {
    console.info("TCP", event.role, event.connected ? "connected" : "disconnected",
        event.remoteAddress, event.remotePort, event.connectionId, event.reason);
});
tcp.on("line", async event => {
    try {
        const m = scale.read();
        const reply = event.line.trim() === "WEIGHT?"
            ? (m.available ? m.net + "," + m.gross + "," + m.unit : "ERR,NO_MEASUREMENT")
            : "ERR,UNKNOWN_COMMAND";
        await tcp.write(reply + "\r\n", { connectionId: event.connectionId });
    } catch (error) {
        console.warn("TCP reply", error.code, error.message);
    }
});

async function start() {
    console.info("TCP configured", JSON.stringify(await tcp.configure(configuration)));
    await tcp.claim();
    console.info("TCP ready", JSON.stringify(tcp.status()));
}
start().catch(error => {
    console.error(error.code, error.message);
    app.stop();
});

14. RS-232 / RS-485

Ein Port ist für die Anwendung nur verfügbar, wenn seine Systemfunktion deaktiviert ist: S0E=0 für RS-232 oder S1E=0 für RS-485. Es darf keinem Systemwägeprotokoll, Modbus, Debug-Ausgabe oder Weiterleitung zugeordnet werden. claim() deaktiviert diese Funktionen nicht automatisch.

Das serielle Modul stellt zwei unabhängige Objekte mit derselben API bereit: serial.rs232 und serial.rs485. Eine Anwendung kann einen oder beide Ports übernehmen. Es ist kein weiteres Kommunikationsmodul erforderlich. Alle Funktionen und Ereignisse dieses Kapitels sind ab Neutron AppEngine 1.0.0 verfügbar.

const port = serial.rs232; // or serial.rs485

14.1 port.claim()

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await port.claim();
Zweck. Den ausgewählten seriellen Port exklusiv übernehmen.
Beschreibung. Prüft, ob der Port Disabled und frei ist, und bereitet ihn dann mit den gespeicherten physischen Einstellungen vor. Wartet auf die erfolgreiche Initialisierung. Ein erfolgreiches claim darf wiederholt werden, ohne unveränderte Einstellungen neu zu initialisieren.

Parameter

Keine Parameter.

Ergebnis

Promise<string>, bei Erfolg "claimed". Registrieren Sie Listener bei Bedarf vor der Übernahme. Das Vorhandensein einer Gegenstelle wird nicht geprüft.

Fehler und besondere Hinweise

RESOURCE_IN_USE für eine aktivierte Systemfunktion oder einen anderen Konflikt; BUSY für gleichzeitige Steuervorgänge; RECONFIGURE_FAILED, TIMEOUT oder OUT_OF_MEMORY. Ein falsch konfigurierter Port wird nicht stillschweigend beansprucht.

Beispiel

async function start() {
    await serial.rs232.claim();
    console.info("RS-232 prevzet");
}
start().catch(error => console.error(error.code, error.message));

14.2 port.configure()

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await port.configure(options);
Zweck. Baudrate, Zeichenformat und lokale Nachrichtenverarbeitung konfigurieren.
Beschreibung. Asynchron, nach claim() zulässig. Ordnet physische Parameter vorhandenen SMD-Einstellungen zu, prüft und speichert sie dauerhaft. Initialisiert den Port einmal für die gesamte Anfrage neu; das Promise wird nach der Übernahme erfüllt. Weggelassene Einstellungen bleiben unverändert. Das erneute Anwenden identischer, erfolgreich übernommener Werte vermeidet unnötige Neuinitialisierungen.

Parameter

Tabelle 57

Parameter

Typ / Anforderung

Beschreibung

options

object / erforderlich

Objekt mit den optionalen Feldern unten. Unbekannte Felder werden abgelehnt.

baudRate

Ganzzahl / optional

300–1 000 000 Bit/s. Zuordnung zu S0B oder S1B.

dataBits

Ganzzahl / optional

7 oder 8. S0I/S1I Zuordnung: 0 bedeutet 7 Bits, 1 bedeutet 8 Bits.

stopBits

Ganzzahl / optional

1 oder 2. Zuordnung zu S0S/S1S.

parity

string / optional

"none", "even" oder "odd". S0P-/S1P-Zuordnung: 0, 1 oder 2.

delimiter

string / optional, Standard CRLF

1–8 ASCII Zeichen, nur für Zeilenereignisassembly in der aktuellen Anwendung.

maxLineBytes

Ganzzahl / optional, Standard 1024

1–4096 Inhaltsbyte pro Zeile ohne Trennzeichen. Nur für die aktuelle Anwendung.

Ergebnis

Promise<string>, bei Erfolg "configured". Physische Einstellungen bleiben nach release(), Stop und Neustart erhalten. delimiter und maxLineBytes werden nicht in SMD gespeichert; sie gelten für den aktuellen JavaScript-Parser.

Fehler und besondere Hinweise

INVALID_ARGUMENT, NOT_OWNER, RESOURCE_IN_USE, BUSY, SETTINGS_FAILED, RECONFIGURE_FAILED, CONFIG_CHANGED, TIMEOUT oder OUT_OF_MEMORY. Ein Speicherfehler kann dazu führen, dass einige physische Einstellungen gespeichert bleiben. Ein Anwendungsfehler bedeutet nicht, dass die Einstellungen nicht gespeichert wurden. Beheben Sie die Ursache und versuchen Sie es erneut mit der Konfiguration/Beanspruchung. Die Konfiguration des lokalen Parsers ändert sich erst nach Erfolg. Wenn ein anderer Kanal die angeforderten physikalischen Einstellungen vor der Bestätigung ändert, wird der Aufruf mit CONFIG_CHANGED abgewiesen.

Beispiel

async function configurePort() {
    const port = serial.rs485;
    await port.claim();
    await port.configure({
        baudRate: 19200, dataBits: 8, parity: "even", stopBits: 1,
        delimiter: "\r\n", maxLineBytes: 512
    });
    console.info("Nastavitve uveljavljene");
}
configurePort().catch(error => console.warn(error.code, error.message));

14.3 Einstellungen ohne Neustart ändern

Derselbe Anwendungspfad verarbeitet SMD-Anfragen von allen Verwaltungskanälen. Das Ändern von Baudrate, Datenbits, Stoppbits, Parität oder Portfunktion erfordert keinen Neutron Neustart. Systemabschlusszeichen, Einstellungen zum Anhängen von Abschlusszeichen, RS-485-Adresse und zugehörige Portzuweisungen werden ebenfalls aktualisiert. Der andere Port wird nur dann neu initialisiert, wenn er betroffen ist.

Während des Übergangs werden neue Schreibvorgänge vorübergehend abgelehnt oder zurückgehalten. Bereits übergebene Bytefolgen werden innerhalb eines begrenzten Zeitlimits fertig übertragen; unvollständige Empfangsframes werden verworfen. Alte Wägeanfragen, kontinuierliche Systemausgabe und Sitzungen des betroffenen Ports enden. Änderungen von Baudrate oder Format können Datenverlust verursachen; führen Sie sie deshalb während einer vereinbarten Kommunikationspause durch. Kann die Übertragung nicht abgeschlossen oder die neue Konfiguration nicht geöffnet werden, wird RECONFIGURE_FAILED gemeldet.

Wenn externes SMD während der Übernahme durch JavaScript eine andere Systemfunktion zuweist oder einen Konflikt verursacht, wird die Übernahme widerrufen. Die Anwendung erhält state mit reason="RESOURCE_IN_USE" und claimed=false; neue Schreibvorgänge geben NOT_OWNER zurück. Zulässige Änderungen physischer Einstellungen behalten die Kontrolle bei und lösen RECONFIGURED aus. Unvollständige JavaScript-Zeilen werden verworfen; das konfigurierte JavaScript-Trennzeichen bleibt erhalten.

Tabelle 58

Prüfen über RMD

Bedeutung

S0APPLY / S1APPLY

PENDING: wartet auf Übernahme; OK: Konfiguration übernommen; ERROR: Übernahme fehlgeschlagen.

S0JS / S1JS

1 bedeutet von der Anwendung übernommen; 0 bedeutet keine JavaScript-Übernahme.

S0REV / S1REV

Zähler übernommener Portzustandsänderungen; keine dauerhafte Sitzungs-ID.

S0STATE / S1STATE

Letzter Zustand: READY, DISABLED, CLAIMED, RECONFIGURED, RELEASED, RESOURCE_IN_USE oder RECONFIGURE_FAILED.

Eine normale SMD-Antwort bestätigt das Speichern; die physische Übernahme folgt im nächsten Verarbeitungszyklus des Geräts. Verwenden Sie für eine externe Bestätigung RMD-APPLY-Felder oder Debug-Protokolle. port.configure() wartet bereits auf die Übernahme. Diese RMD-Felder dienen der Diagnose und sind keine beschreibbaren SMD-Einstellungen. Identisches SMD nach einem Fehler versucht die Übernahme erneut; nach Erfolg öffnen identische Werte den Port nicht erneut.

14.4 port.write()

Verfügbar seit: Neutron AppEngine 1.0.0
const bytes = await port.write(data, { timeoutMs });
Zweck. Text oder binäre Bytefolgen asynchron senden.
Beschreibung. Kodiert Zeichenketten als UTF-8; sendet Uint8Array unverändert. Fügt weder Abschlusszeichen noch RS-485-Adresse oder Prüfsumme hinzu. Schreibvorgänge auf einem Port folgen der Anfragereihenfolge; ihre Promises bestätigen keine entfernte Verarbeitung.

Parameter

Tabelle 59

Parameter

Typ / Anforderung

Beschreibung

data

string oder Uint8Array / erforderlich

Höchstens 4096 Bytes nach UTF-8 Kodierung; Leere Schreibvorgänge sind zulässig.

options

object / optional, Standardwert {}

Warteoptionen.

options.timeoutMs

Ganzzahl / optional

1–180000 ms. Der Standardwert wird aus Länge und Baudrate mit einer Marge und einem Mindestwert 3 s berechnet.

Ergebnis

Promise<number> mit den zur Übertragung angenommenen Byte. Verwenden Sie drain(), um auf den Abschluss der physischen Übertragung zu warten.

Fehler und besondere Hinweise

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT oder OUT_OF_MEMORY. Einige Bytes können nach einer Unterbrechung oder einem Timeout bereits gesendet werden. CONFIG_CHANGED bedeutet, dass die Konfiguration während des Wartens geändert wurde; verbleibende alte Anforderungsbytes werden unter neuen Einstellungen nicht gesendet.

Beispiel

async function send() {
    await serial.rs232.write("WEIGHT?\r\n");
    await serial.rs232.write(new Uint8Array([0, 1, 255]));
}
send().catch(error => console.warn(error.code, error.message));

14.5 port.drain()

Verfügbar seit: Neutron AppEngine 1.0.0
await port.drain({ timeoutMs });
Zweck. Auf den Abschluss der physischen Übertragung warten.
Beschreibung. Wartet auf frühere Schreibvorgänge am selben Port und prüft dann, ob ausstehende Bytes übertragen wurden. Die Laufzeit verarbeitet während des Wartens andere Ereignisse.

Parameter

Tabelle 60

Parameter

Typ / Anforderung

Beschreibung

options

object / optional, Standardwert {}

Warteoptionen.

options.timeoutMs

Ganzzahl / optional, Standard 6000

1–60000 ms.

Ergebnis

Promise<undefined>. Wartet nicht auf eine Remote-Antwort oder bestätigt nicht, dass ein von anderen Geräten verwendeter RS-485-Bus frei ist.

Fehler und besondere Hinweise

INVALID_ARGUMENT, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT oder OUT_OF_MEMORY. Set eine geeignete Kommunikationsfrist; Ablauf macht übertragene Bytes nicht rückgängig.

Beispiel

async function sendAndWait() {
    await serial.rs485.write("READ\r\n");
    await serial.rs485.drain({ timeoutMs: 5000 });
}
sendAndWait().catch(error => console.warn(error.code, error.message));

14.6 port.release()

Verfügbar seit: Neutron AppEngine 1.0.0
const result = await port.release();
Zweck. Die Übernahme des ausgewählten Ports durch die Anwendung freigeben.
Beschreibung. Verhindert neue Schreibvorgänge der Anwendung, schließt den Übergang ab und gibt die Kontrolle frei. Ein weiterhin systemseitig auf Disabled gesetzter Port ohne andere Nutzung wird geschlossen. Dauerhaft gespeicherte physische Einstellungen bleiben erhalten. Deaktiviert keine Systemfunktion, die den Port inzwischen übernommen hat.

Parameter

Keine Parameter.

Ergebnis

Promise<string>, bei Erfolg "released". Wiederholen ist zulässig. Unvollständige lokale Empfangsdaten werden verworfen; registrierte Callbacks und Timer bleiben erhalten.

Fehler und besondere Hinweise

BUSY, RECONFIGURE_FAILED, TIMEOUT oder OUT_OF_MEMORY. Brechen Sie Sendetimer vor der Freigabe ab. Bereits übertragene Byte können nicht zurückgenommen werden. Stop der Anwendung gibt automatisch beide Ports frei.

Beispiel

async function releasePort() {
    console.info(await serial.rs232.release());
}
releasePort().catch(error => console.warn(error.code, error.message));

14.7 port.on()

Verfügbar seit: Neutron AppEngine 1.0.0
port.on(eventName, callback);
Zweck. Einen seriellen Ereignislistener registrieren.
Beschreibung. Ereignisse gehören zum ausgewählten Port. once entfernt die Registrierung vor dem Aufruf des Callbacks. off erfordert dieselbe Funktionsreferenz und unterbricht keinen bereits gestarteten async-Callback.

Parameter

Tabelle 61

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

"data", "line" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt.

Ergebnis

Das ausgewählte Portobjekt; Die Registrierung des Hörers kann verkettet werden.

Fehler und besondere Hinweise

INVALID_ARGUMENT für ein ungültiges Ereignis oder einen Callback; QUOTA_EXCEEDED oben 32 Listener pro Port. Nicht behandelte Callbackausnahmen oder Ablehnungen stoppen die Anwendung. off hat keine Auswirkung auf eine abwesende Registrierung.

Beispiel

function receive(event) { console.info(event.line); }
serial.rs232.on("line", receive);

14.8 port.once()

Verfügbar seit: Neutron AppEngine 1.0.0
port.once(eventName, callback);
Zweck. Nur auf das erste passende Ereignis warten.
Beschreibung. Ereignisse gehören zum ausgewählten Port. once entfernt die Registrierung vor dem Aufruf des Callbacks. off erfordert dieselbe Funktionsreferenz und unterbricht keinen bereits gestarteten async-Callback.

Parameter

Tabelle 62

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

"data", "line" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt.

Ergebnis

Das ausgewählte Portobjekt; Die Registrierung des Hörers kann verkettet werden.

Fehler und besondere Hinweise

INVALID_ARGUMENT für ein ungültiges Ereignis oder einen Callback; QUOTA_EXCEEDED oben 32 Listener pro Port. Nicht behandelte Callbackausnahmen oder Ablehnungen stoppen die Anwendung. off hat keine Auswirkung auf eine abwesende Registrierung.

Beispiel

function receive(event) { console.info(event.line); }
serial.rs232.once("line", receive);

14.9 port.off()

Verfügbar seit: Neutron AppEngine 1.0.0
port.off(eventName, callback);
Zweck. Einen Listener entfernen.
Beschreibung. Ereignisse gehören zum ausgewählten Port. once entfernt die Registrierung vor dem Aufruf des Callbacks. off erfordert dieselbe Funktionsreferenz und unterbricht keinen bereits gestarteten async-Callback.

Parameter

Tabelle 63

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

"data", "line" oder "state".

callback

function / erforderlich

Funktion, die ein Ereignisobjekt empfängt.

Ergebnis

Das ausgewählte Portobjekt; Die Registrierung des Hörers kann verkettet werden.

Fehler und besondere Hinweise

INVALID_ARGUMENT für ein ungültiges Ereignis oder einen Callback; QUOTA_EXCEEDED oben 32 Listener pro Port. Nicht behandelte Callbackausnahmen oder Ablehnungen stoppen die Anwendung. off hat keine Auswirkung auf eine abwesende Registrierung.

Beispiel

function receive(event) { console.info(event.line); }
serial.rs232.off("line", receive);

14.10 Ereignisse und Nachrichtenabgrenzung

Tabelle 64

Ereignis

Object

Beschreibung

data

{ data: Uint8Array }

Roher Stream-Block; Ein Ereignis ist nicht unbedingt ein Protokollpaket. NUL und andere Binärbytes bleiben erhalten.

line

{ line: string }

Zusammengesetzte Zeile UTF-8 ohne Trennzeichen; Geteilte Nachrichtenblöcke werden wieder zusammengesetzt. Leerzeichen werden nicht automatisch entfernt.

state

{ port, claimed, reason, generation }

port ist rs232 oder rs485. claimed ist boolean; reason bezeichnet den Übergang; generation ändert sich bei Übernahme des Portzustands.

Mit einem line-Listener werden Empfangsdaten bis zum Trennzeichen zusammengesetzt. Ein data-Listener am selben Port erhält eine andere Ansicht desselben Datenstroms; verarbeiten Sie einen Befehl nicht doppelt. Zu lange Zeilen verursachen MESSAGE_TOO_LARGE vor dem line-Callback und können die Anwendung beenden. Ohne line-Listener werden rohe Binärdaten nicht in einem Zeilenpuffer gesammelt. Ereignisse von vor der Neuinitialisierung werden nicht als Daten unter der neuen Konfiguration wiederverwendet.

Serielle Ports haben kein connection-Ereignis: Abgezogene Kabel oder ausgeschaltete Geräte lassen sich im Allgemeinen nicht zuverlässig erkennen. state beschreibt die Übernahme und Einstellungen von Neutron AppEngine, nicht die physische Verbindung. Prüfen Sie die Erreichbarkeit über Antworten und Zeitlimits Ihres Protokolls. RS-485-Anwendungen implementieren Adressierung, CRC und Zugriffsregeln für den gemeinsamen Bus; der systemseitige R4A-Filter gilt während der Übernahme durch JavaScript nicht für Rohdaten.

14.11 Vollständige RS-232-/RS-485-Anwendung

Setzen Sie die Funktion des ausgewählten Ports auf Disabled und entfernen Sie andere Zuweisungen. Die folgende Anwendung übernimmt ihn, konfiguriert dauerhaft 19200/8N1 und antwortet auf WEIGHT? mit net,gross,unit. Ändern Sie für den anderen Port nur das ausgewählte Objekt. Konfigurieren Sie dasselbe Zeichenformat auf der Gegenstelle.

// Neutron AppEngine 1.0.0. Port must be Disabled, with no system protocol,
// Modbus, debug output or BLE forwarding.
async function start() {
    if (!app.capabilities().features.serial) throw new Error("Serial API is unsupported");
    const port = serial.rs232; // For RS-485 use serial.rs485.

    port.on("state", event => {
        console.info(event.port, event.reason, "claimed:", event.claimed);
        if (event.reason === "RESOURCE_IN_USE" || event.reason === "RECONFIGURE_FAILED") {
            app.stop();
        }
    });

    port.on("line", async event => {
        try {
            if (event.line.trim() === "WEIGHT?") {
                const m = scale.read();
                const reply = m.available ? m.net + "," + m.gross + "," + m.unit : "ERR,NO_MEASUREMENT";
                await port.write(reply + "\r\n");
            } else {
                await port.write("ERR,UNKNOWN_COMMAND\r\n");
            }
        } catch (error) {
            console.warn(error.code || error.name, error.message);
        }
    });

    await port.claim();
    // Physical settings persist through the same path as SMD.
    await port.configure({
        baudRate: 19200, dataBits: 8, parity: "none", stopBits: 1,
        delimiter: "\r\n", maxLineBytes: 512
    });
    console.info("Serial protocol ready");
}
start().catch(error => {
    console.error(error.code || error.name, error.message);
    app.stop();
});

14.12 Integrationstests

Tabelle 65

Test

Erwartetes Ergebnis

Übernahme bei aktivierter Systemfunktion

RESOURCE_IN_USE; Die Systemnutzung bleibt unverändert.

Konfigurieren Sie über JavaScript und separat über SMD

Baudrate/Parität/Bits gelten ohne Neustart des Geräts.

Einen Port ändern

Der andere Port behält Daten und Betrieb bei, sofern er nicht betroffen ist.

Externe Übernahme während des JavaScript Betriebs

state RESOURCE_IN_USE, claimed=false; neue Schreibvorgänge geben NOT_OWNER zurück.

Binäre Bytefolgen und eine auf mehrere Empfangsvorgänge verteilte Zeile

Kein NUL-Verlust und keine doppelten Trennzeichen; eine korrekt zusammengesetzte Zeile.

Neukonfiguration während teilweisem Empfang oder Schreiben

Alte Teilzeilen werden verworfen; verbleibende alte Schreibvorgänge werden unter den neuen Einstellungen nicht gesendet.

Freigeben / Stop und erneut übernehmen

Kein dauerhaft belegter Port; physische Einstellungen bleiben erhalten.

15. MQTT-Modul

Dieses Modul führt CSCP-Befehle nicht automatisch aus. Die Anwendung definiert Themenbedeutungen, Nutzlastformat und zulässige Befehle.mqtt.connect() stellt eine Verbindung zum Benutzerbroker her, verändert die Systemverbindung Scale Monitor nicht und erfordert keine claim().
Das Modul mqtt stellt einer Benutzeranwendung eine unabhängige Brokerverbindung zur Verfügung, die von der Systemverbindung Scale Monitor getrennt ist. Beide können gleichzeitig mit unterschiedlichen Adressen, Identitäten, Anmeldeinformationen und Abonnements arbeiten. Die Anwendung beansprucht keine Systemthemen. Unterstützung: app.capabilities().features.mqtt === true. Alle Funktionen, Ereignisse und Eigenschaften in diesem Kapitel sind verfügbar ab Neutron AppEngine 1.0.0.
Tabelle 66

URL

Verbindung

Beispiel

mqtt://

MQTT über TCP

mqtt://broker.example.com:1883

mqtts://

MQTT mit TLS Serverauthentifizierung

mqtts://broker.example.com:8883

ws://

MQTT über WebSocket

ws://broker.example.com:8080/mqtt

wss://

MQTT über sicheren WebSocket

wss://broker.example.com/mqtt

Protokoll: MQTT 3.1.1; API unterstützt QoS 0 und 1. Ein WebSocket URL muss auf den MQTT-Listener des Brokers verweisen, nicht auf einen beliebigen WebSocket-Server. Voraussetzung sind Netzwerkzugriff, korrekte DNS-Einstellungen und ein erreichbarer Broker. Für die Gültigkeitsprüfung des Zertifikats muss die Geräteuhr korrekt sein.

Verbindungslebenszyklus

Registrieren Sie zuerst Listener, dann await mqtt.configure(...), await mqtt.connect() und await mqtt.subscribe(...). Die Konfiguration gilt für den aktuellen Anwendungslauf und wird bei dessen Beendigung verworfen. Nehmen Sie sie für einen automatischen Anwendungsstart in die Startinitialisierung auf. Verbinden Sie sich nicht bei jedem Timer-Durchlauf erneut.
Nach einer erfolgreichen Verbindung löst die Trennung standardmäßig eine automatische Wiederherstellung der Verbindung aus, mit einer begrenzten Verzögerung, die sich auf bis zu 60 Sekunden verdoppelt. Erfolgreich bestätigte Abonnements werden automatisch und asynchron wiederhergestellt.connect und Abschluss von connect() bestätigen die Verbindung, nicht den Abschluss aller wiederhergestellten Abonnements. Wiederherstellungsfehler geben error aus. Vor der ersten erfolgreichen Verbindung wird ein fehlgeschlagener Versuch abgelehnt; Die Anwendung entscheidet, ob es erneut versucht wird.
Ein ausdrückliches disconnect(), Authentifizierungsfehler oder Überlauf der Ereigniswarteschlange beendet die automatische Wiederverbindung. Nach einer erfolgreichen Verbindung wird bei gewöhnlichem Netzwerkverlust erneut verbunden, sofern dies aktiviert ist. Beenden oder Ersetzen der Anwendung schließt nur ihre eigene MQTT-Verbindung. Das asynchrone geordnete Schließen bestätigt nicht die Zustellung letzter Veröffentlichungen. Die Systemverbindung läuft unabhängig weiter.

mqtt.configure(options)

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.configure(options);
Zweck. Broker und Anwendungsidentität konfigurieren.
Beschreibung. Überprüft und ersetzt Einstellungen nur, wenn der Benutzer-Client weder verbunden ist, eine Verbindung herstellt noch auf eine erneute Verbindung wartet. Warten Sie disconnect(), bevor Sie sie ändern. Eine erfolgreiche neue Konfiguration löscht gespeicherte Abonnements; Bei einem Fehler bleibt die vorherige Konfiguration erhalten.

Parameter

Tabelle 67

Parameter

Typ / Anforderung

Beschreibung

options

object / erforderlich

Die Eigenschaften sind unten aufgeführt. Unbekannte Eigenschaften werden abgelehnt; Werte müssen die dokumentierten Typen verwenden.

Ergebnis

Promise<undefined>. Bestätigt die Konfiguration und das Laden der angeforderten Zertifikatsprofile; stellt keine Verbindung her.

Fehler und besondere Hinweise

INVALID_ARGUMENT,MESSAGE_TOO_LARGE, BUSY, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, OUT_OF_MEMORY. Ungültiger PEM-Inhalt schlägt möglicherweise nur während der TLS-Verbindung fehl.

Beispiel

await mqtt.configure({
    url: "mqtts://broker.example.com:8883",
    clientId: "scale-01-app",
    username: "integrator", password: "replace-me",
    keepAlive: 60, cleanSession: true, reconnect: true,
    connectTimeoutMs: 10000, reconnectDelayMs: 1000
});
Tabelle 68

Eigenschaft von options

Typ / Standardwert

Bedeutung und Grenzen

url

string / erforderlich

Bis zu 512 UTF-8 Bytes. Eines der vier Schemata. Kein Benutzername/Passwort im URL, Leerzeichen oder #-Fragment. Geben Sie den richtigen ws/wss-Pfad an, z. B. /mqtt.

clientId

string / automatisch

Bis zu 64 UTF-8 Bytes. Wenn es nicht vorhanden oder leer ist, weist das Gerät eine stabile Benutzeranwendungsidentität zu. Zwei gleichzeitige Verbindungen zum gleichen Broker dürfen sich kein clientId teilen.

username, password

string / keine

Höchstens 256 beziehungsweise 512 UTF-8-Byte. Geben Sie diese niemals in der Konsole aus; Anwendungscode ist kein Geheimnisspeicher.

keepAlive

Ganzzahl / 60

Sekunden, 5..3600.

cleanSession

boolean / true

false ermöglicht eine dauerhafte Brokersitzung für dasselbe clientId. Die Anwendung API stellt weiterhin ihre bestätigten Abonnements wieder her; Nur-Broker-Abonnements sind nicht Teil der lokalen Liste.

reconnect

boolean / true

Automatische Wiederverbindung nach Verlust einer bestehenden Verbindung. Wiederholt keine fehlgeschlagene Erstanmeldung oder explizites disconnect().

connectTimeoutMs

Ganzzahl / 10000

1000..60000 ms. Frist für Client-Verbindung und Netzwerkbetrieb.

reconnectDelayMs

Ganzzahl / 1000

1000..60000 ms. Anfängliche Verzögerung, Verdoppelung bei wiederholten Verbindungsabbrüchen bis 60000 ms und Zurücksetzen nach Erfolg.

will

object / keine

{topic, payload, qos?, retain?}. topic ist ein Veröffentlichungsthema; payload ist string. qos: 0 oder 1, Standardwert 0; retain: boolean, Standardwert false. Der Broker veröffentlicht die Will-Nachricht nach einer unerwarteten Trennung gemäß MQTT-Regeln; verlassen Sie sich nach einem geordneten Schließen nicht darauf.

tls

object / keine

Nur mqtts/wss. Eigenschaften: caProfile, clientCertificateProfile, clientKeyProfile. Siehe TLS unten.

Das vollständige options-JSON muss einschließlich Eigenschaftsnamen und Escape-Sequenzen in 4096 UTF-8-Byte passen. Die tatsächliche Kapazität von will.payload liegt daher unter 4096 Byte. Konfigurationszeichenketten dürfen kein NUL enthalten; verwenden Sie publish() für Binärdaten. Benutzer-Client-Einstellungen sind unabhängig von den Einstellungen des System-Brokers.

mqtt.connect(options?)

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.connect({ timeoutMs: 15000 });
Zweck. Eine Verbindung zum konfigurierten Broker herstellen.
Beschreibung. Das Promise wird bei erfolgreicher Bestätigung der Brokerverbindung erfüllt. Aufrufe bei bereits bestehender Verbindung sind erfolgreich. Ein zweiter gleichzeitiger Verbindungsversuch wird mit BUSY abgelehnt.

Parameter

Tabelle 69

Parameter

Typ / Anforderung

Beschreibung

options.timeoutMs

Ganzzahl / optional

1..60000 ms; standardmäßig der konfigurierte Wert connectTimeoutMs. Gilt für den Verbindungsversuch; Warten in der Dienstwarteschlange und das Beenden des Clients können die Gesamtdauer verlängern.

Ergebnis

Promise<undefined>. Verbindungsinformationen sind auch in connect und status() verfügbar.

Fehler und besondere Hinweise

NOT_CONFIGURED, BUSY, START_FAILED, AUTH_FAILED, CONNECTION_REFUSED, NOT_CONNECTED, TIMEOUT, CANCELLED. Genauere Netzwerk-/TLS-Ursachen können in error oder status(). lastError erscheinen. Begrenzen Sie Wiederholungen fehlgeschlagener Erstversuche.

Beispiel

try {
    await mqtt.connect({ timeoutMs: 20000 });
    console.info("Broker connected");
} catch (error) {
    console.error(error.code, error.message);
    app.stop();
}

mqtt.disconnect()

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.disconnect();
Zweck. Die Benutzerverbindung geordnet schließen und die Wiederverbindung beenden.
Beschreibung. Bricht ausstehende connect-, publish-, subscribe- und unsubscribe-Vorgänge ab; behandeln Sie deren Promises. Konfiguration und bestätigte Abonnements bleiben für das nächste connect im selben Lauf erhalten; configure ersetzt sie.

Parameter

Keine Parameter.

Ergebnis

Promise<undefined> nach dem Schließen des Clients. Aufrufe bei bereits getrennter Verbindung sind erfolgreich.

Fehler und besondere Hinweise

NOT_CONFIGURED vor der Erstkonfiguration. Unterbrochene Vorgänge erhalten CANCELLED. Macht vom Broker bereits akzeptierte Veröffentlichungen nicht rückgängig. Sendet keine automatische Geschäfts-Offline-Nachricht; Veröffentlichen und bestätigen Sie eines vor disconnect(), falls erforderlich.

Beispiel

if (mqtt.status().connected) {
    await mqtt.publish("scale/status", "offline", { qos: 1, retain: true });
}
await mqtt.disconnect();

mqtt.status()

Verfügbar seit: Neutron AppEngine 1.0.0
const status = mqtt.status();
Zweck. Den aktuellen Zustand der Benutzerverbindung ohne Warten zurückgeben.
Beschreibung. Gibt eine Kopie des neuesten Status zurück, keine Garantie für den Erfolg des nächsten Netzwerkvorgangs. Gibt keinen Benutzernamen, kein Passwort oder keine Zertifikate preis.

Parameter

Keine Parameter.

Ergebnis

{configured:boolean, connected:boolean, state:string, reconnectAttempts:number, lastError:string}. state: unconfigured, disconnected, connecting, connected, reconnecting. reconnectAttempts zählt die Starts automatischer Wiederverbindungen seit dem letzten configure. lastError ist leer oder enthält den letzten Fehlercode; eine erfolgreiche Verbindung löscht ihn.

Fehler und besondere Hinweise

Synchron; verbindet sich nicht. Der Netzwerkstatus kann sich zwischen dem Lesen und dem nächsten Vorgang ändern.

Beispiel

const status = mqtt.status();
console.info(status.state, status.connected, status.lastError);

mqtt.subscribe(topic, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.subscribe("factory/+/command", { qos: 1, timeoutMs: 10000 });
Zweck. Ein Thema oder einen Themenfilter abonnieren.
Beschreibung. Wartet auf SUBACK des Brokers; eine Ablehnung durch den Broker ist kein Erfolg. Bestätigte Abonnements werden für die Wiederverbindung gespeichert. Die Wiederholung eines Filters belegt keinen zusätzlichen Platz; eine erfolgreiche Bestätigung ersetzt die angeforderte QoS. Der Broker darf eine niedrigere QoS gewähren.

Parameter

Tabelle 70

Parameter

Typ / Anforderung

Beschreibung

topic

string / erforderlich

1..192 UTF-8 Bytes.+ muss ein ganzes Level belegen, # das gesamte letzte Level; zum Beispiel „factory/+/command“ oder „factory/#“.

options.qos

Ganzzahl / 0

0 oder 1.

options.timeoutMs

Ganzzahl / 10000

1..60000 ms für die Bestätigung des Brokers.

Ergebnis

Promise<undefined> nach erfolgreichem SUBACK. Eingehende Veröffentlichungen lösen message aus.

Fehler und besondere Hinweise

NOT_CONFIGURED,NOT_CONNECTED, SUBSCRIBE_FAILED, QUOTA_EXCEEDED, BUSY, TIMEOUT. Höchstens 16 Filter. Das gleichzeitige Abonnieren/Abmelden für denselben Filter erhält BUSY. Offline-Anfragen werden nicht für später in die Warteschlange gestellt.

Beispiel

await mqtt.subscribe("factory/scale-01/command", { qos: 1 });

mqtt.unsubscribe(topic, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.unsubscribe("factory/scale-01/command");
Zweck. Das Abonnement des exakten Filters beenden und ihn aus der Wiederverbindungsliste entfernen.
Beschreibung. Bestätigt am UNSUBACK. Unbekannte Filter können abgemeldet werden. Entfernt keine bereits empfangenen Nachrichten oder andere sich überschneidende Abonnements.

Parameter

Tabelle 71

Parameter

Typ / Anforderung

Beschreibung

topic

string / erforderlich

Genauer Filter zum Abbestellen; bis zu 192 UTF-8 Bytes.

options.timeoutMs

Ganzzahl / 10000

1..60000 ms.

Ergebnis

Promise<undefined> nach UNSUBACK.

Fehler und besondere Hinweise

NOT_CONFIGURED,NOT_CONNECTED, BUSY, TIMEOUT, CANCELLED. Um gespeicherte Filter bei getrennter Verbindung zu ersetzen, verwenden Sie configure; Es ersetzt die vollständige lokale Liste, garantiert jedoch nicht die Entfernung der alten Broker-Sitzung.

Beispiel

await mqtt.unsubscribe("factory/+/command", { timeoutMs: 5000 });

mqtt.publish(topic, payload, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
await mqtt.publish(topic, payload, { qos: 1, retain: false });
Zweck. Text oder Binärdaten veröffentlichen.
Beschreibung. Sendet Zeichenfolgen als UTF-8 und Uint8Array als exakte Bytes; fügt kein CR, LF oder NUL hinzu. Kopiert die Nutzlast zum Zeitpunkt des Aufrufs. Der Versand beginnt mit einer separaten Kommunikationsaufgabe nach der Bearbeitung der Anfrage. QoS 0 bestätigt einen erfolgreichen Transportschreibvorgang; QoS 1 wartet auf Broker PUBACK. Beides bestätigt die Verarbeitung durch den Endabonnenten nicht.

Parameter

Tabelle 72

Parameter

Typ / Anforderung

Beschreibung

topic

string / erforderlich

1..192 UTF-8 Bytes, ohne + oder #.

payload

string | Uint8Array / erforderlich

0..4096 Bytes nach UTF-8 Kodierung; Binärdaten können NUL enthalten.

options.qos

Ganzzahl / 0

0 oder 1; QoS 2 wird nicht unterstützt.

options.retain

boolean / false

Behalten Sie die Nachricht beim Broker bei. Leere Nutzlast mit retain=true entfernt den beibehaltenen Wert des Themas.

options.timeoutMs

Ganzzahl / 10000

1..60000 ms. QoS 1 PUBACK Frist; QoS 0 wartet nicht auf den Broker.

Ergebnis

Promise<undefined>; Die Bedeutung der Bestätigung hängt von QoS ab.

Fehler und besondere Hinweise

NOT_CONNECTED offline; Keine unbegrenzte Offline-Warteschlange.BUSY für eine volle Ausgangswarteschlange (32768 Bytes einschließlich Protokoll-Overhead) oder Grenzwert für ausstehende Vorgänge.MESSAGE_TOO_LARGE, INVALID_ARGUMENT, NETWORK_ERROR, TIMEOUT, CANCELLED. Möglicherweise hat der Broker nach Zeitüberschreitung/Verbindungsabbruch bereits eine Nachricht erhalten. QoS 1 kann zu einer doppelten Zustellung führen; Verwenden Sie Anforderungs-IDs und Deduplizierung für den Geschäftsbetrieb.

Beispiel

const m = scale.read();
if (m.available && mqtt.status().connected) {
    await mqtt.publish("factory/scale-01/weight", JSON.stringify({
        net: m.net, gross: m.gross, unit: m.unit
    }), { qos: 1 });
}
await mqtt.publish("factory/scale-01/binary", new Uint8Array([0, 10, 255]));

mqtt.on() / mqtt.once() / mqtt.off()

Verfügbar seit: Neutron AppEngine 1.0.0
mqtt.on(eventName, callback);
mqtt.once(eventName, callback);
mqtt.off(eventName, callback);
Zweck. Einen Ereignislistener des Benutzer-Brokers registrieren oder entfernen.
Beschreibung. Ereignisse werden nacheinander ausgeführt. Ein async-Callback gibt bei await die Ausführung frei; verwenden Sie einen Schutz vor Überlappung, wenn die Reihenfolge wichtig ist. once entfernt die Registrierung vor dem Aufruf. off entfernt alle Registrierungen derselben Funktion für das ausgewählte Ereignis.

Parameter

Tabelle 73

Parameter

Typ / Anforderung

Beschreibung

eventName

string / erforderlich

connect, disconnect, message oder error.

callback

function / erforderlich

Empfängt ein Objekt mit den unten aufgeführten Feldern. Behalten Sie die gleiche Funktionsreferenz für „off“ bei.

Ergebnis

Gibt mqtt zur Verkettung zurück. Höchstens 32 Listener über alle MQTT Ereignisse hinweg.

Fehler und besondere Hinweise

INVALID_ARGUMENT, QUOTA_EXCEEDED. error allein beendet die Anwendung nicht; eine unbehandelte Listener-Ausnahme oder ein abgelehntes Promise dagegen schon, gemäß den Laufzeitregeln. Vorgangsablehnung und error sind getrennte Benachrichtigungen ohne garantierte relative Reihenfolge.

Beispiel

mqtt.on("message", async event => {
    try {
        if (event.topic !== "factory/scale-01/request" || event.retain) return;
        const request = JSON.parse(event.text);
        console.info(request.id, request.command);
    } catch (error) {
        console.warn(error.code || error.name, error.message);
    }
});
mqtt.on("error", error => console.warn(error.code, error.message));
Tabelle 74

Ereignis

Felder seit Neutron AppEngine 1.0.0

Bedeutung

connect

connected: true, reconnected: boolean, sessionPresent: boolean

CONNACK akzeptiert. reconnected zeigt eine frühere erfolgreiche Verbindung unter der aktuellen Konfiguration an. sessionPresent ist das Flag des Brokers für eine wiederhergestellte Sitzung und nicht die lokal bestätigte Abonnementliste.

disconnect

connected: false, reason: string

Verlust einer bestehenden Verbindung oder explizite Trennung. Behandeln Sie den Promise für eine fehlgeschlagene Erstverbindung. Bei Beendigung der Anwendung wird kein Ereignis garantiert.

message

topic: string, data: Uint8Array, text: string, qos: number, retain: boolean

Vollständige MQTT-Nachricht, zunächst aus Fragmenten zusammengesetzt. text ist eine UTF-8-Ansicht; verwenden Sie data für beliebige binäre Nutzdaten. qos ist die QoS der empfangenen Nachricht (die API fordert höchstens 1 an, aber der Broker kann ältere Abonnements beibehalten).

error

Fehler mit code: string und message: string

Verbindungs-, TLS-, Abonnementwiederherstellungs-, Nachrichtengrößen- oder Warteschlangenfehler. Die Anwendung entscheidet über das weitere Vorgehen; prüfen Sie status() und ausstehende Vorgänge.

TLS und Zertifikatsprofile

mqtts und wss überprüfen den Servernamen und die Vertrauenswürdigkeit des Zertifikats. Ohne caProfile wird die integrierte öffentliche CA-Vertrauensstellung verwendet. Verwenden Sie ein benutzerdefiniertes Profil für private Zertifizierungsstellen. Das Deaktivieren der Zertifikatsüberprüfung ist nicht Teil des API. Einstellungen und Zertifikate des Systembrokers gelten nicht für Benutzerverbindungen.

Tabelle 75

Feld von tls

Gespeichertes Profil

Zweck

caProfile: "company-ca"

JCA_company-ca

Vertrauenswürdige CA PEM oder CA Kette.

clientCertificateProfile: "device-01"

JCC_device-01

Client-Zertifikat PEM für gegenseitiges TLS.

clientKeyProfile: "device-01"

JCK_device-01

Privater Client-Schlüssel im PEM-Format; zusammen mit dem Zertifikat erforderlich. Passwortverschlüsselte Schlüssel werden in dieser Version nicht unterstützt.

Profilnamen enthalten 1..48 Zeichen: A–Z, a–z, 0–9, _ oder -. Jedes normalisierte PEM ist höchstens 16384 Byte groß. Ein autorisierter Integrator stellt Profile über den vorhandenen SMD-Zertifikatspfad bereit, beispielsweise JCA_company-ca=<PEM>, mit dem vollständigen PEM-Zertifikat als Wert. Dies ist weder ein Dateipfad noch eine öffentliche URL oder ein systemseitiges MCA-Profil. Ein leerer Wert löscht ein Profil gemäß den vorhandenen Zertifikatsregeln. Anwendungen laden Profile während configure; das Ändern gespeicherter Profile ersetzt keine Zertifikate aktiver Verbindungen. Trennen Sie die Verbindung, führen Sie configure aus und verbinden Sie erneut.
await mqtt.configure({
    url: "mqtts://mqtt.company.example:8883",
    clientId: "scale-01-app",
    tls: {
        caProfile: "company-ca",
        clientCertificateProfile: "device-01",
        clientKeyProfile: "device-01"
    }
});
await mqtt.connect();

Grenzen, Fehler und Wiederherstellung

Tabelle 76

Grenzwert seit Neutron AppEngine 1.0.0

Wert / Behandlung

Verbindungen

Eine Benutzerverbindung, getrennt von der Systemverbindung Scale Monitor.

Nutzdaten

4096 Bytes pro gesendeter oder empfangener Nachricht: die gesamte Nachricht, nicht jedes Fragment.

Thema / Abonnements / Listener

192 UTF-8 Bytes / 16 bestätigte Filter / 32 Listener.

Ausstehende Vorgänge

Höchstens 8 gemeinsam mit anderen asynchronen Laufzeitoperationen. MQTT Ausgangswarteschlange: 32768 Bytes.

Zeitlimit

Höchstens 60000 ms für Verbindungs- oder Brokerbestätigung. Keine Garantie für eine genaue Reaktionszeit des Geräts.

Zu große eingehende Nachricht

Gesamte Nachricht verworfen; Fehler MESSAGE_TOO_LARGE. Teilnachrichten werden nicht zugestellt.

Überlauf der Dienstwarteschlange

EVENT_OVERFLOW schließt die Benutzerverbindung und stoppt die erneute Verbindung. Die Laufzeit verfügt über eine weitere begrenzte Warteschlange. sein Überlauf stoppt die Anwendung.

Zeitüberschreitung der Bestätigung

Der ausstehende Vorgang wird abgelehnt und die erneute Verbindung folgt den konfigurierten Regeln. Andere Vorgänge erhalten möglicherweise NOT_CONNECTED. Eine verspätete Bestätigung einer alten Verbindung bestätigt niemals eine neue Anfrage.

Verbindungsabbruch beim Veröffentlichen

Unbestätigte Vorgänge werden abgelehnt; Die Anwendung entscheidet, ob es erneut versucht wird. Bereits ausgeführte Effekte werden nicht rückgängig gemacht.

Wichtige Codes: INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_CONFIGURED, NOT_CONNECTED, BUSY, QUOTA_EXCEEDED, OUT_OF_MEMORY, START_FAILED, AUTH_FAILED, CONNECTION_REFUSED, NETWORK_ERROR, TLS_ERROR, SUBSCRIBE_FAILED, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, TIMEOUT, CANCELLED, EVENT_OVERFLOW, INVALID_MESSAGE. Fehlermeldungen dienen der Diagnose; stützen Sie Programmentscheidungen auf code. Prüfen Sie bei TLS-Fehlern Gerätezeit, Servername, Vertrauenskette und erforderliches Client-Zertifikat.

Vollständiges Beispiel: Gewicht veröffentlichen und Befehle empfangen

Passen Sie brokerUrl, baseTopic und Zugangsdaten vor dem Start an. Jedes Gerät benötigt eine eigene clientId und eigene Themen. Senden Sie Befehle ohne retain an /command. Das Beispiel veröffentlicht regelmäßig das Gewicht, stellt bestätigte Abonnements automatisch wieder her und wiederholt keine Tarierung für gespeicherte Befehle. Ergänzen Sie bei Systemen, die QoS-1-Anfragen wiederholen, Anfrage-IDs und eine Aufzeichnung ausgeführter Befehle; retain allein verhindert keine doppelte Zustellung.

// Set your broker address and a unique base topic for this device.
// Supports mqtt://, mqtts://, ws:// and wss://.
const brokerUrl = "mqtt://192.168.1.10:1883";
const baseTopic = "factory/scale-01";
let sending = false;
let commandBusy = false;

mqtt.on("error", error => console.warn(error.code, error.message));
mqtt.on("connect", event => console.info("MQTT connected; reconnected:", event.reconnected));
mqtt.on("disconnect", event => console.warn("MQTT disconnected:", event.reason));

mqtt.on("message", async event => {
    if (event.topic !== baseTopic + "/command") return;
    // Do not execute retained commands on every resubscription.
    if (event.retain || commandBusy) return;
    commandBusy = true;
    try {
        let reply;
        switch (event.text.trim()) {
        case "WEIGHT?": reply = JSON.stringify(scale.read()); break;
        case "TARE": await scale.tare(); reply = "OK"; break;
        case "ZERO": await scale.zero(); reply = "OK"; break;
        case "CLEAR_TARE": await scale.clearTare(); reply = "OK"; break;
        default: reply = "ERR,UNKNOWN_COMMAND";
        }
        await mqtt.publish(baseTopic + "/reply", reply, { qos: 1 });
    } catch (error) {
        console.warn("Command failed:", error.code || error.name, error.message);
    } finally {
        commandBusy = false;
    }
});

async function start() {
    if (!app.capabilities().features.mqtt) throw new Error("MQTT API unsupported");
    await mqtt.configure({
        url: brokerUrl,
        clientId: "scale-01-user-app", // Each device needs its own clientId.
        // username: "user", password: "password",
        keepAlive: 60, reconnect: true, reconnectDelayMs: 1000,
        will: { topic: baseTopic + "/status", payload: "offline", qos: 1, retain: true }
        // For a private CA: mqtts/wss in tls: { caProfile: "company-ca" }.
    });
    await mqtt.connect();
    await mqtt.subscribe(baseTopic + "/command", { qos: 1 });
    // The subscription restores automatically after disconnection.
    await mqtt.publish(baseTopic + "/status", "online", { qos: 1, retain: true });
    mqtt.on("connect", async () => {
        try { await mqtt.publish(baseTopic + "/status", "online", { qos: 1, retain: true }); }
        catch (error) { console.warn(error.code, error.message); }
    });
    setInterval(async () => {
        if (sending || !mqtt.status().connected) return;
        sending = true;
        try {
            const m = scale.read();
            if (m.available) await mqtt.publish(baseTopic + "/weight", JSON.stringify({ net: m.net, gross: m.gross, unit: m.unit }), { qos: 1 });
        } catch (error) {
            console.warn("Publish failed:", error.code, error.message);
        } finally {
            sending = false;
        }
    }, 1000);
}

start().catch(error => {
    console.error(error.code || error.name, error.message);
    app.stop();
});

Integrationstests

Tabelle 77

Test

Erwartetes Ergebnis

Systemanbindung und Benutzerbroker gleichzeitig

Scale Monitor geht weiter; Benutzerthemen werden nur von der Anwendung behandelt.

WEIGHT? auf dem ausgewählten /command veröffentlichen

Messung JSON kommt bei /reply an;/weight wird ungefähr jede Sekunde aktualisiert.

Netzwerkausfall und Wiederherstellung

status wird reconnecting, danach connect mit reconnected=true und automatischer Wiederherstellung der Abonnements.

Falsches Passwort / CA / Servername

connect wird abgelehnt; error/status liefern Diagnosen. Fehlgeschlagene Authentifizierung wird nicht unbegrenzt wiederholt.

Senden Sie 4096 Binärbytes

Alle Bytes, einschließlich NUL, bleiben unverändert. Das Thema zählt nicht zur Nutzlastgröße.

Erhalten Sie eine Nachricht über 4096 Bytes

MESSAGE_TOO_LARGE ohne Teilmeldungsereignis.

Anwendungsstopp

Die Benutzerverbindung wird geschlossen; Die Systemverbindung bleibt aktiv.

mqtt, mqtts, ws, wss

Testen Sie jeden URL mit dem entsprechenden Broker-Listener. ws/wss erfordern den richtigen Pfad.

16. HTTP-/REST-Client

Global fetch() verbindet Anwendungen mit externen REST APIs über HTTP oder HTTPS. Unterstützung: app.capabilities().features.http. Alle Funktionen, Eigenschaften und Optionen in diesem Kapitel sind verfügbar ab Neutron AppEngine 1.0.0. Dies ist eine dokumentierte Teilmenge von fetch, keine vollständige Browserumgebung.

Das Gerät fungiert als HTTP-Client. Dieser API fügt keine benutzerdefinierten REST-Routen zum internen HTTP-Server von Neutron hinzu. Anfragen bieten keine automatischen Wiederholungsversuche, keine dauerhafte Warteschlange, keine automatische Ereignisübertragung oder Antwortspeicherung. Die Anwendung definiert Aufrufzeitpunkt, Datenformate und Fehlerbehandlung.

fetch(url, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
const response = await fetch(url, options);
Zweck. Eine Anfrage an einen externen HTTP-/HTTPS-Server senden und eine vollständige Antwort mit begrenzter Größe empfangen.
Beschreibung. Das Promise wird erfüllt, nachdem der gesamte Nachrichtenkörper empfangen wurde, nicht nur die ersten Header. HTTP 400, 401, 404 und 500 sind normale Antworten und werden nicht abgelehnt. Verbindungs-, TLS-, Timeout- und Größenfehler werden abgelehnt. Die Netzwerkverarbeitung läuft außerhalb des JavaScript-Callbacks, ohne ihn während des Wartens zu blockieren.

Parameter

Tabelle 78

Parameter

Typ / Anforderung

Beschreibung

url

string / erforderlich

Absolutes http:// oder https:// URL, höchstens 512 ASCII Bytes. Unicode und Leerzeichen in Pfaden/Abfragewerten kodieren; Verwenden Sie encodeURIComponent für einzelne Werte. Ein #-Fragment wird entfernt. URL-Anmeldeinformationen sind verboten.

options

object / optional

method, headers, body, timeoutMs, tls und redirect. Unbekannte Optionen werden abgelehnt. Einzelheiten folgen unten.

Ergebnis

Promise<Response>, unten beschrieben. body und kodierte Optionen haben getrennte Grenzen; binäre Nutzdaten werden weder als JSON noch als Base64 kodiert.

Fehler und besondere Hinweise

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, HEADERS_TOO_LARGE, RESPONSE_TOO_LARGE, NETWORK_ERROR, TLS_ERROR, TIMEOUT, CANCELLED, INVALID_RESPONSE, INCOMPLETE_RESPONSE, UNSUPPORTED_ENCODING, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, OUT_OF_MEMORY, BUSY. Nach einer Unterbrechung/Zeitüberschreitung hat der Server die Anfrage möglicherweise bereits verarbeitet; Ein erneuter Versuch von POST kann seine geschäftlichen Auswirkungen duplizieren.

Beispiel

async function sendWeight() {
    const m = scale.read();
    const response = await fetch("https://api.example.com/measurements", {
        method: "POST",
        headers: { "Content-Type": "application/json", "Authorization": "Bearer replace-me" },
        body: JSON.stringify({ net: m.net, gross: m.gross, unit: m.unit }),
        timeoutMs: 10000
    });
    if (!response.ok) {
        console.warn("HTTP", response.status, await response.text());
        return;
    }
    if (response.status !== 204) console.info(await response.json());
}
sendWeight().catch(error => console.warn(error.code || error.name, error.message));
Tabelle 79

Option seit Neutron AppEngine 1.0.0

Typ / Standardwert

Bedeutung

method

string / GET

GET, POST, PUT, PATCH, DELETE oder HEAD. In Großbuchstaben umgewandelt. Andere Methoden werden in dieser Version nicht unterstützt.

headers

object / keine

Benutzerdefinierte Header-Namen und Zeichenfolgenwerte. Bei Namen wird die Groß-/Kleinschreibung nicht beachtet. Doppelte Namen, die sich nur in der Schreibweise unterscheiden, werden abgelehnt. Nur ASCII-Werte, ohne CR/LF oder andere Steuerzeichen als Tabulatorzeichen.

body

string | Uint8Array | null / keine

Höchstens 4096 Bytes nach UTF-8 Kodierung. null bedeutet kein Nachrichtenkörper. GET und HEAD können keinen Nachrichtenkörper haben. Strings ohne expliziten Content-Type erhalten text/plain; charset=UTF-8; Verwenden Sie für JSON JSON.stringify und application/json. Uint8Array erhält keinen automatischen Content-Type.

timeoutMs

Ganzzahl / 10000

1..60000 ms; eine dokumentierte Neutron AppEngine-Erweiterung, keine standardmäßige fetch-Option eines Browsers. Beginnt beim Aufruf und umfasst Wartezeit in der Warteschlange sowie die Übertragung des Nachrichtenkörpers. Die Fehlerzustellung hat keine Echtzeitgarantie; zugrunde liegende Namensauflösungs- oder Verbindungsaufrufe können später enden.

tls

object / keine

Nur HTTPS. caProfile und optional das Paar clientCertificateProfile/clientKeyProfile. Siehe TLS.

redirect

string / manual

Nur manual wird unterstützt. Gibt 3xx-Antworten zurück, damit die Anwendung Location prüfen kann. Keine automatische Weiterleitung.

Höchstens 32 bereitgestellte Header und 2048 Bytes zusammen (Namen, Werte und Trennzeichen); Namen bis zu 64 Zeichen, Werte bis zu 1024. Der Client verwaltet automatische Protokollheader. Host, Content-Length, Connection, Transfer-Encoding, Accept-Encoding, Expect, Trailer, Upgrade, Proxy-Connection, TE und Keep-Alive können nicht eingestellt werden. Für codierte Anforderungsoptionen gilt ein zusätzliches kombiniertes Byte-Limit 4096 UTF-8.

Response: Status und Metadaten

Verfügbar seit: Neutron AppEngine 1.0.0
const response = await fetch("https://api.example.com/articles/ART-001");
Zweck. Das HTTP-Ergebnis vor der Umwandlung des Antwortkörpers prüfen.
Beschreibung. Ein Objekt mit schreibgeschützten Eigenschaften und Methoden zum einmaligen Lesen des Antwortkörpers. Bestätigt weder die geschäftliche Bedeutung des Status noch die Gültigkeit empfangenen JSON.

Parameter

Keine Parameter.

Ergebnis

{status, statusText, ok, url, redirected, headers, bodyUsed, text(), json(), arrayBuffer()}. status ist der HTTP-Code; ok bedeutet 200..299. url ist die angeforderte URL ohne Fragment; redirected ist false; statusText ist in dieser Version eine leere Zeichenkette.

Fehler und besondere Hinweise

Behandeln Sie eine fetch-Ablehnung getrennt von response.ok. Erwarten Sie für 204 oder HEAD einen leeren Antwortkörper; response.json() wirft bei leerem Nachrichtenkörper SyntaxError. Kein Streaming von response.body, kein clone(), Blob, FormData, Request oder globaler Response-Konstruktor.

Beispiel

const response = await fetch("https://api.example.com/articles/ART-001");
if (response.status === 404) console.info("Article not found");
else if (!response.ok) console.warn("HTTP status:", response.status);
else console.info(await response.json());

response.text()

Verfügbar seit: Neutron AppEngine 1.0.0
const text = await response.text();
Zweck. Den empfangenen Antwortkörper einmal in UTF-8-Text umwandeln.
Beschreibung. Entfernt ein anfängliches UTF-8 BOM. Führt keine weitere Netzwerkanfrage durch; fetch hat den Nachrichtenkörper bereits erhalten. bodyUsed wird beim ersten Aufruf der Nachrichtenkörperverbrauchsmethode zu true.

Parameter

Keine Parameter.

Ergebnis

Promise<string>. Verwenden Sie arrayBuffer() für beliebige Binärdaten.

Fehler und besondere Hinweise

Wiederholtes Lesen wirft TypeError mit code=BODY_USED. Dekodiert UTF-8; andere Zeichensätze werden nicht automatisch unterstützt.

Beispiel

const response = await fetch("https://api.example.com/status");
const text = await response.text();
console.info(response.status, text);

response.json()

Verfügbar seit: Neutron AppEngine 1.0.0
const value = await response.json();
Zweck. Den UTF-8-Antwortkörper dekodieren und JSON.parse einmal ausführen.
Beschreibung. Gibt ein Objekt, Array oder einen anderen gültigen JSON-Wert zurück. Content-Type ändert die JSON.parse-Regeln nicht. Überprüfen Sie zunächst den Status, wenn Ihr API unterschiedliche Fehlerkörperformate zurückgibt.

Parameter

Keine Parameter.

Ergebnis

Promise<JSON value>. bodyUsed wird zu true, auch wenn das Parsen von JSON fehlschlägt.

Fehler und besondere Hinweise

SyntaxError bei ungültigem/leerem JSON; TypeError/BODY_USED bei wiederholtem Lesen. Speichern Sie das Ergebnis zur Wiederverwendung in einer Variablen.

Beispiel

const response = await fetch("https://api.example.com/settings");
const settings = await response.json();
console.info(settings);
// Do not also call response.text() on the same response.

response.arrayBuffer()

Verfügbar seit: Neutron AppEngine 1.0.0
const buffer = await response.arrayBuffer();
Zweck. Empfangene binäre Bytefolgen einmal ohne Textumwandlung zurückgeben.
Beschreibung. Mit Uint8Array können Sie auf einzelne Bytes zugreifen, einschließlich NUL. Speichern Sie sie oder leiten Sie sie an ein anderes unterstütztes Modul weiter.

Parameter

Keine Parameter.

Ergebnis

Promise<ArrayBuffer>, höchstens4096 Bytes.

Fehler und besondere Hinweise

TypeError/BODY_USED bei wiederholtem Lesen. Keine automatische gzip- oder andere Inhaltsdekomprimierung.

Beispiel

const response = await fetch("https://api.example.com/data.bin");
if (!response.ok) throw new Error("HTTP " + response.status);
const data = new Uint8Array(await response.arrayBuffer());
await storage.write("download.bin", data);

response.headers

Verfügbar seit: Neutron AppEngine 1.0.0
const contentType = response.headers.get("Content-Type");
Zweck. Antwortheader ohne Unterscheidung von Groß- und Kleinschreibung lesen.
Beschreibung. Schreibgeschütztes Objekt mit Unterstützung für get, has, entries, keys, values, forEach und Iteration. Wiederholte Headernamen werden durch Kommas verbunden; dies ist keine automatische Cookie-Verwaltung.

Parameter

Tabelle 80

Parameter

Typ / Anforderung

Beschreibung

name für get/has

string / erforderlich

Gültiger HTTP-Headername.

callback für forEach

function / erforderlich

Empfängt value, name und headers. Ein optionales zweites Argument setzt thisArg.

Ergebnis

get gibt string oder null zurück; has gibt boolean zurück; entries/keys/values geben Iteratoren zurück. forEach gibt kein Ergebnis zurück. Die Iteration verwendet kleingeschriebene Headernamen.

Fehler und besondere Hinweise

INVALID_ARGUMENT bei ungültigen Headernamen oder Callbacks. Kein globaler Headers-Konstruktor und keine set/append/delete-Methoden für Antworten. Überschreitet der Server 32 Header, insgesamt 2048 Byte oder unterstützte Namens-/Wertlängen, wird fetch abgelehnt, statt stillschweigend zu kürzen.

Beispiel

const response = await fetch("https://api.example.com/status");
console.info(response.headers.get("Content-Type"));
for (const [name, value] of response.headers) console.info(name, value);

Authentifizierung

Übergeben Sie Bearer-Token, API-Schlüssel oder bereits kodierte Basic-Werte in Headern. Setzen Sie keine Zugangsdaten in URLs. Keine automatische Anmeldung, Token-Erneuerung, HTTP-Digest-Authentifizierung oder gemeinsame Sitzung mit Systemverbindungen. Cookies werden weder automatisch gespeichert noch gesendet. Dieser Geräteclient unterliegt keinen CORS-Beschränkungen eines Browsers.

const response = await fetch("https://api.example.com/status", {
    headers: { "Authorization": "Bearer replace-me" }
});
// For example, Basic user:pass uses header "Authorization": "Basic dXNlcjpwYXNz".
// Basic/Base64 is not encryption: use HTTPS for credentials.

HTTPS und Zertifikatsprofile

HTTPS überprüft immer den Servernamen und die Zertifikatsvertrauenswürdigkeit. Ohne caProfile wird die integrierte öffentliche CA-Vertrauensstellung verwendet. Verwenden Sie ein benutzerdefiniertes Profil für private Zertifizierungsstellen. Für die Gültigkeitsprüfung des Zertifikats muss die Geräteuhr korrekt sein. Keine unsichere Option oder Umgehung der Hostnamen-Überprüfung.

Tabelle 81

Option tls

Gespeichertes Profil

Zweck

caProfile: "company"

JHCA_company

Vertrauenswürdige CA PEM oder CA Kette.

clientCertificateProfile: "scale01"

JHCC_scale01

Client-Zertifikat für gegenseitiges TLS.

clientKeyProfile: "scale01"

JHCK_scale01

Privater Schlüssel; zusammen mit dem Client-Zertifikat erforderlich.

Profilnamen: 1..48 Zeichen A–Z/a–z, 0–9, _ oder -. Jedes PEM ist höchstens 16384 Byte groß. Autorisierte Integratoren stellen Profile über den vorhandenen SMD-Zertifikatspfad bereit, beispielsweise JHCA_company=&lt; PEM&gt;. Dies ist kein beliebiger Dateipfad. Profile sind getrennt von System-MQTT- und internen HTTP-Serverzertifikaten und werden pro Anfrage geladen. Passwortverschlüsselte private Schlüssel werden nicht unterstützt.

const response = await fetch("https://api.company.example/status", {
    tls: {
        caProfile: "company",
        clientCertificateProfile: "scale01",
        clientKeyProfile: "scale01"
    },
    timeoutMs: 15000
});
console.info(response.status);

Grenzen und Ausführung

Tabelle 82

Eigenschaft seit Neutron AppEngine 1.0.0

Behandlung

Ausführung

Eine aktive Anfrage und bis zu vier in der Warteschlange. Es gilt auch die gemeinsame Laufzeitbeschränkung von acht ausstehenden asynchronen Vorgängen.

Größe

4096-Byte-Anforderungstext und eine separate 4096-Byte-Antworttextbegrenzung. Übergroße Antworten lösen RESPONSE_TOO_LARGE aus; Teilkörper werden niemals als Erfolg zurückgegeben.

Zeitlimit

Standardwert 10000 ms, maximal 60000 ms, einschließlich Warteschlangenwartezeit. Bei langsam eingehenden Daten wird die Frist nicht zurückgesetzt. Die tatsächliche Fehlerlieferzeit wird nicht in Echtzeit garantiert.

Verbindungen

Verbindungen werden nach jeder Anfrage freigegeben. Keine dauerhafte HTTP-Sitzung oder automatische Wiederholung. HTTPS baut daher bei jedem Aufruf eine neue sichere Verbindung auf.

Weiterleitungen

Immer manual. 3xx bleibt eine Antwort; Location kann gelesen werden. Authentifizierungsheader werden nicht automatisch an einen anderen Server weitergegeben.

Kodierung des Antwortkörpers

Fordert identity an. gzip/br und andere Kodierungen werden nicht unterstützt; eine nicht leere kodierte Antwort verursacht UNSUPPORTED_ENCODING.

Anwendungsstopp

In der Warteschlange befindliche Anforderungen aus einem vorherigen Lauf werden verworfen; Die aktive Übertragung wird unterbrochen, wenn ein Stopp erkannt wird oder der zugrunde liegende Verbindungsanruf beendet wird. Bereits durchgeführte Servereffekte werden dadurch nicht rückgängig gemacht.

API-Teilmenge

Kein AbortController/signal, kein Streaming des Nachrichtenkörpers, kein clone, Blob, FormData, keine URL/Request/Response/Headers-Konstruktoren und keine automatische CORS-/Cookie-Umgebung.

Schützen Sie regelmäßige Aufrufe vor Überschneidungen. Verwenden Sie Anforderungs-IDs und ein vereinbartes Serverprotokoll für zuverlässige Geschäftswiederholungen. Timeout oder Antwortverlust beweisen nicht, dass der Server POST/PUT/PATCH/DELETE nicht verarbeitet hat.

Vollständiges Beispiel: Gewicht senden

// Adjust the URL and, if required, Authorization for your REST server.
const endpoint = "https://api.example.com/measurements";
let sending = false;

async function sendWeight() {
    if (sending) return;
    const m = scale.read();
    if (!m.available) return;
    sending = true;
    try {
        const response = await fetch(endpoint, {
            method: "POST",
            headers: {
                "Content-Type": "application/json"
                // "Authorization": "Bearer replace-me"
            },
            body: JSON.stringify({ device: "scale-01", timeMs: m.timeMs, net: m.net, gross: m.gross, unit: m.unit }),
            timeoutMs: 10000
        });
        if (!response.ok) {
            console.warn("REST status:", response.status, await response.text());
            return;
        }
        console.info("REST status:", response.status);
        // If the API returns JSON: const result = await response.json();
        // 204 has no body. A body can be consumed only once.
    } catch (error) {
        console.warn(error.code || error.name, error.message);
    } finally {
        sending = false;
    }
}

if (!app.capabilities().features.http) {
    console.error("REST API is unavailable");
    app.stop();
} else {
    sendWeight();
    setInterval(sendWeight, 10000);
}

Integrationstests

Für lokale Tests enthält das Quellpaket tools/rest-test-server.py und tools/examples/rest-self-test.js für das Gerät. Der Server lauscht standardmäßig lokal; verwenden Sie für Neutron-Zugriff ausdrücklich --host 0.0.0.0 und setzen Sie die IP-Adresse des Computers in der Testanwendung. Die optionalen --cert/--key aktivieren HTTPS; --ca aktiviert die Client-Zertifikatsprüfung. Die Bereitstellung von Zertifikaten/Profilen bleibt ein separater Verwaltungsvorgang.

Tabelle 83

Test

Erwartetes Ergebnis

GET/POST/PUT/PATCH/DELETE/HEAD

Korrekte Anfrage und Status; HEAD hat keinen Nachrichtenkörper.

404 oder 500

Das Promise erfüllt;response.ok ist false.

302

Status und Location ohne automatische neue Anfrage.

JSON / UTF-8 / gestückelt

Vollständiger, korrekt dekodierter Nachrichtenkörper; Chunks sind keine separaten JavaScript Ereignisse.

Binärkörper mit NUL und 0xff

Genau 4096 Bytes in jede Richtung.

Lesen Sie den Nachrichtenkörper noch einmal

TypeError mit code=BODY_USED.

Langsame Antwort oder langsamer Header-Stream

TIMEOUT; Wiegen und Laufzeit laufen weiter.

Übergroße Antwort/Header

Explizite Ablehnung ohne stillschweigende Kürzung.

HTTPS mit falschem CA / Name / Client-Zertifikat

TLS_ERROR; Die Verifizierung bleibt aktiviert.

Stoppen Sie während der Übertragung

Freigegebene Ressourcen; Es wird keine veraltete Antwort in einen neuen Anwendungslauf geliefert.

17. WebSocket-Client

Verfügbar seit: Neutron AppEngine 1.0.0 / API 1.
WebSocket bietet eine dauerhafte bidirektionale Verbindung zu einem externen Server. Anwendungen senden Text- oder Binärnachrichten und empfangen Ereignisse. Jede Nachricht behält ihre Grenzen; Zeilentrennzeichen sind nicht erforderlich. Verwenden Sie fetch() für REST und mqtt für einen MQTT-Broker.
Jede Anwendung hat eine unabhängige Verbindung, getrennt von den WebSocket-Einstellungen des Moduls, MQTT und Scale Monitor. Unterstützt ws://, wss://, DNS-Namen und IPv4. Prüfen Sie app.capabilities().features.websocket; Grenzen stehen in app.capabilities().websocket.

new WebSocket(url, protocols?, options?)

Verfügbar seit: Neutron AppEngine 1.0.0
Erstellt einen Client und startet den asynchronen Verbindungsaufbau. Gibt ein WebSocket-Objekt zurück, kein Promise. Erfolg löst open aus; ein Fehler löst error und close aus. Ungültige Argumente werfen synchron eine Ausnahme.
  • url: absolute Adresse, höchstens 512 Bytes, wie zum Beispiel wss://system.example.com/scales?device=01. Standardports: 80 für ws, 443 für wss. Pfade und Parameter kodieren; URL-Anmeldeinformationen, Fragmente und IPv6 werden nicht unterstützt.
  • protocols: weggelassen oder leeres Array []. Die Aushandlung von Unterprotokollen ist in dieser Version nicht verfügbar; andere Werte lösen UNSUPPORTED_PROTOCOL aus.
  • options: optionales Objekt, das timeoutMs, headers und tls enthält. Kann auch direkt als zweites Argument angegeben werden.
  • timeoutMs: Ganzzahliges Verbindungslimit 1000–15000 ms, Standard 10000 ms. DNS/Netzwerkdetails können sich auf die tatsächliche Rückgabezeit auswirken. Begrenzt nicht die gesamte Lebensdauer der Verbindung.
  • headers: HTTP-Header mit Zeichenkettenwerten, etwa Authorization oder X-API-Key. Höchstens 32 Header und insgesamt 512 Byte. Connection- und Sec-WebSocket-*-Header werden vom Client verwaltet und können nicht gesetzt werden. Die vollständige Upgrade-Anfrage einschließlich Pfad, Hostname und automatischer Header muss kürzer als 1024 Byte sein; eine zu große Kombination löst HEADERS_TOO_LARGE aus.
  • tls: nur wss.caProfile, clientCertificateProfile und clientKeyProfile verwenden die Profile REST. Geben Sie Client-Zertifikat und Schlüssel zusammen an. Profilnamen: 1–48 Zeichen A–Z, a–z, 0–9, _ oder -. Ohne caProfile wird die Standardvertrauensstellung verwendet. Die Überprüfung des Servernamens und des Zertifikats ist immer aktiviert.
const ws = new WebSocket("wss://system.example.com/scales", [], {
  headers: { Authorization: "Bearer demo-token" },
  timeoutMs: 10000,
  tls: { caProfile: "company" }
});
ws.onopen = () => ws.send(JSON.stringify(scale.read()));
ws.onerror = event => console.warn(event.code, event.message);

Zertifikatsprüfungen erfordern die korrekte Gerätezeit. Anmeldeinformationen über wss senden. Weiterleitungen werden nicht automatisch verfolgt. Wenn der Verbindungssteckplatz belegt ist, erhält das neue Objekt BUSY und schließt; die bestehende Verbindung bleibt aktiv.

Basic-Authentifizierung mit Benutzername und Passwort

Verfügbar seit: Neutron AppEngine 1.0.0
Geben Sie Benutzername/Passwort als Zeichenfolgen ein und verwenden Sie den Hilfsassistenten unten, um Authorization zu erstellen. Basic führt kein Hashing der Anmeldeinformationen durch: Es kodiert Base64 username:password. Die Kodierung ist umkehrbar; Verwenden Sie wss:// für Anmeldeinformationen.
basicAuth(username, password) wird in diesem Beispiel definiert und ist nicht in Neutron AppEngine eingebaut. Gibt den vollständigen Headerwert Basic <Base64> zurück. Unterstützt UTF-8, wenn der Server es erwartet, und benötigt weder btoa noch TextEncoder. Beide Argumente müssen Zeichenketten sein, andernfalls wird TypeError geworfen. Benutzernamen dürfen keinen Doppelpunkt enthalten; Passwörter dürfen ihn enthalten. Die Beispieladresse und Zugangsdaten sind fiktiv.
function basicAuth(username, password) {
    if (typeof username !== "string" || typeof password !== "string")
        throw new TypeError("Username and password must be strings");
    if (username.includes(":"))
        throw new Error("Username must not contain ':'");

    // Encode username:password as UTF-8 bytes, then Base64.
    const text = encodeURIComponent(username + ":" + password)
        .replace(/%([0-9A-F]{2})/g,
            (_, hex) => String.fromCharCode(parseInt(hex, 16)));
    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    let encoded = "";

    for (let i = 0; i < text.length; i += 3) {
        const n = (text.charCodeAt(i) << 16)
            | ((text.charCodeAt(i + 1) || 0) << 8)
            | (text.charCodeAt(i + 2) || 0);
        encoded += alphabet[(n >>> 18) & 63];
        encoded += alphabet[(n >>> 12) & 63];
        encoded += i + 1 < text.length ? alphabet[(n >>> 6) & 63] : "=";
        encoded += i + 2 < text.length ? alphabet[n & 63] : "=";
    }
    return "Basic " + encoded;
}

// Fictional address and credentials; replace with your server settings.
const username = "demo_operator";
const password = "DemoOnly-42!";
const socket = new WebSocket("wss://gateway.example.com:9443/scale/auth", {
    headers: { Authorization: basicAuth(username, password) }
});
socket.onopen = () => socket.send(JSON.stringify(scale.read()));
socket.onerror = event => console.warn(event.code, event.message);
socket.onclose = event => console.info("WebSocket closed", event.code, event.wasClean);
Ersetzen Sie /scale/auth durch den tatsächlichen Serverendpunkt. Die Hilfsfunktion selbst muss bei geänderten Zugangsdaten nicht angepasst werden. Protokollieren Sie niemals Authorization oder Passwörter. HTTP 401/403 bei der Authentifizierung löst error mit AUTH_FAILED und anschließend close aus. basicAuth funktioniert auch in fetch-Authorization-Headern über HTTPS.

socket.send(data)

Verfügbar seit: Neutron AppEngine 1.0.0

Im Zustand OPEN wird eine Nachricht eingereiht. Akzeptiert string, ArrayBuffer oder eine Pufferansicht wie Uint8Array oder DataView. Zeichenketten werden als UTF-8-Text, andere Werte als Binärnachrichten gesendet. Binärdaten werden beim Aufruf kopiert, sodass die Quelle danach geändert werden kann. Leere Nachrichten und die binären Bytewerte 0 und 255 sind zulässig.

Gibt undefined zurück. Nicht als Zustellungsbestätigung await verwenden: Durch das Senden wird die Verarbeitung durch den Server nicht bestätigt. Fügen Sie Ihrem Protokoll Anforderungs-IDs und Antworten hinzu.bufferedAmount zählt lokale Bytes in der Warteschlange, nicht unbestätigte Servernachrichten.

Höchstens 4096 Byte pro Nachricht und 16384 Byte in der lokalen Warteschlange; das gemeinsame Limit ausstehender Vorgänge gilt ebenfalls. Zu große Nachrichten lösen MESSAGE_TOO_LARGE aus; eine volle Warteschlange löst BUSY aus. CONNECTING löst INVALID_STATE aus; CLOSING/CLOSED ignorieren send. Spätere Übertragungsfehler werden über error gemeldet und können die Verbindung schließen.

ws.send("WEIGHT?");
ws.send(JSON.stringify({ net: scale.net, gross: scale.gross }));
ws.send(new Uint8Array([0, 127, 255]));

Ereignisse und Listener

Verfügbar seit: Neutron AppEngine 1.0.0
Verwenden Sie onopen, onmessage, onerror, onclose oder addEventListener(type, callback, { once: true }). Mit removeEventListener(type, callback) entfernen. Nur diese vier Ereignistypen und Funktionsrückrufe werden unterstützt; höchstens 32 registrierte Listener pro Objekt. Doppelte Typ-/Funktionspaare werden nicht hinzugefügt. Keine DOM-Ereignisse, Erfassung oder AbortSignal.
  • open: Verbindungs- und Protokollaktualisierung erfolgreich; readyState ist OPEN.
  • message: event.data ist string für Text oder ArrayBuffer für Binärdaten. Fragmente werden zu einer Nachricht zusammengesetzt, einschließlich über Fragmente verteilter UTF-8-Zeichen. Ping/pong wird nicht als message zugestellt.
  • error: event.code, event.message und ein Error in event.error. Fehler in Callbacks folgen den Laufzeitregeln; fangen Sie sie im Callback ab, um fortzufahren.
  • close: event.code, event.reason, event.wasClean. 1006 kennzeichnet einen unterbrochenen Schließvorgang; 1005 bedeutet, dass der empfangene Frame keinen Code enthielt. Das Objekt bleibt CLOSED. Alle Ereignisse enthalten außerdem type, target und currentTarget.
ws.onmessage = event => {
  try {
    if (typeof event.data === "string") {
      if (event.data.trim() === "WEIGHT?") ws.send(JSON.stringify(scale.read()));
    } else {
      const bytes = new Uint8Array(event.data);
      console.info("Binarni bajti:", bytes.length);
    }
  } catch (error) { console.warn(error.code || error.name, error.message); }
};
ws.addEventListener("open", () => console.info("Povezava odprta"), { once: true });
ws.onclose = event => console.info(event.code, event.reason, event.wasClean);

socket.close(code?, reason?) und Verbindungszustand

Verfügbar seit: Neutron AppEngine 1.0.0
close() startet das asynchrone Schließen und gibt undefined zurück. Standardwerte: code 1000, leerer reason. Benutzercodes: 1000 oder 3000–4999; reason höchstens 123 UTF-8-Byte. Ungültige Argumente lösen INVALID_ARGUMENT aus. Wiederholtes close in CLOSING/CLOSED hat keine Wirkung. Schließen während des Verbindungsaufbaus unterdrückt open; der Client beendet den aktuellen Versuch und schließt dann. Bleibt eine Schließantwort etwa 3 Sekunden aus, wird ein ungeordnetes Schließen erzwungen.
readyState: WebSocket.CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3. Konstanten sind auch am Objekt vorhanden. url enthält die Adresse; protocol und extensions sind leer. binaryType ist immer arraybuffer; blob wird nicht unterstützt.
if (ws.readyState === WebSocket.OPEN) ws.send("PING");
ws.close(1000, "Application finished");

Grenzen, Wiederherstellung und Fehler

Diese Version unterstützt eine Clientverbindung pro Anwendung, ws/wss, binäre und Textübertragung sowie Zertifikatsprüfung. Kein WebSocket-Server, keine Unterprotokolle, Komprimierung, Blob oder automatische Wiederverbindung. Erstellen Sie nach close ein neues Objekt; verwenden Sie bei Bedarf ein verzögertes setTimeout. Dieser Socket ist von MQTT über ws/wss getrennt.

Der Empfang wartet auf verfügbare Daten und benötigt kein setInterval-Polling. Der Client sendet etwa alle 30 Sekunden ping und wartet bis zu 10 Sekunden auf pong. Netzwerkvorgänge nach dem Verbindungsaufbau haben begrenzte Wartezeiten von etwa 3 Sekunden. Zu große eingehende Nachrichten oder ungültiges UTF-8 verursachen error und das Schließen. app.stop(), das Löschen der Anwendung oder Laufzeitfehler schließen die Verbindung und geben Ressourcen frei; ein aktiver Netzwerkvorgang kann mehrere Sekunden bis zum Abschluss benötigen. Nach dem Beenden werden keine JavaScript-Ereignisse mehr ausgeführt.

Fehlercodes: INVALID_ARGUMENT, INVALID_STATE, UNSUPPORTED_PROTOCOL, BUSY, QUOTA_EXCEEDED, MESSAGE_TOO_LARGE, HEADERS_TOO_LARGE, OUT_OF_MEMORY, AUTH_FAILED (HTTP 401/403 während der Verbindung), HANDSHAKE_FAILED, NETWORK_ERROR, TLS_OR_NETWORK_ERROR, TIMEOUT, PROTOCOL_ERROR, INVALID_UTF8. Überprüfen Sie für TLS_OR_NETWORK_ERROR Konnektivität, Uhrzeit, Servernamen und Zertifikat. Fehler in der Laufzeit-Ereigniswarteschlange folgen den allgemeinen Regeln.

Integrationstests

Führen Sie auf einem Computer python tools/websocket-test-server.py --host 0.0.0.0 aus. Setzen Sie die Computeradresse in tools/examples/websocket-self-test.js und laden Sie die Datei auf Neutron hoch. Tests umfassen UTF-8, Fragmente mit einem dazwischenliegenden Ping, leere Nachrichten, binäre Übertragungen bis 4096 Byte und geordnetes Schließen. Beispiel zum Senden von Gewicht: tools/examples/websocket-scale.js. Der Server unterstützt --cert/--key für wss sowie --token zum Testen von Authorization. Verwenden Sie das passende CA-Profil für eigene Zertifikate.

Testen Sie außerdem BIG (übergroße Antwort), falsches Zertifikat/Token, Netzwerkverlust und Stopp/Löschen während der Übertragung. Computerseitige JavaScript API-Tests ersetzen nicht die Netzwerk- und TLS-Tests auf dem Gerät.

18. Fehler, try/catch und Fortsetzung

Ein äußerer try { setInterval(...) } catch (...) { ... } fängt Registrierungsfehler ab, nicht spätere Callbackfehler. Ebenso wird bei try { asyncOperation() } ohne await die Promise-Ablehnung nicht erkannt. Fangen Sie im Callback oder im zurückgegebenen Promise ab.
Unterscheiden Sie synchrone JavaScript-Ausnahmen, asynchrone Promise-Ablehnungen und Ausfälle der gesamten Laufzeitumgebung. Standardmäßige TypeError, ReferenceError, SyntaxError und RangeError haben name/message, aber nicht unbedingt code. Fehler bei Vorgängen und der Argumentvalidierung enthalten im Allgemeinen error.code und error.message.
Tabelle 84

Code

Allgemeine Bedeutung

INVALID_ARGUMENT

Ungültiger Argumenttyp/-wert; Details hängen von der aufgerufenen Funktion ab.

QUOTA_EXCEEDED

Modullimit überschritten; Entfernen Sie nicht verwendete Registrierungen.

BUSY

Ressource ausgelastet, zu viele ausstehende Vorgänge oder volle Warteschlange. Warten und begrenzte Parallelität/Wiederholungsversuche.

OUT_OF_MEMORY

Nicht genügend Betriebsspeicher. JavaScript Speicherfehler können stattdessen eine Standardausnahme ohne diesen Code verwenden.

TIMEOUT

Unterbrochener oder abgelaufener asynchroner Vorgang. Überprüfen Sie die Auswirkungen des vorherigen Vorgangs, bevor Sie es erneut versuchen.

Erwartete Fehler in der Funktion dort abfangen, wo sie auftreten, um fortzufahren. Wählen Sie das Herunterfahren mit app.stop() oder lassen Sie den Fehler unbehandelt. Es existiert keine globale konfigurierbare Fehlerrichtlinie API. Die Konsolenfehlerprotokollierung allein stoppt die Anwendung nicht.

async function readSettings() {
    return JSON.parse('{"enabled":true}');
}
async function start() {
    try {
        const settings = await readSettings();
        console.info("Enabled:", settings.enabled);
    } catch (error) {
        console.warn(error.code || error.name, error.message);
        // Handled error: application continues.
        // Use app.stop() to stop.
    }
}
start();

Unbehandelte Ausnahmen/Ablehnungen, ausgeschöpfte aktive Zeit, übermäßige Aufrufverschachtelung oder Überlauf der Ereigniswarteschlange beenden die Anwendung und setzen lastError. Interne Warteschlangen-/Zeitbudgetfehler liefern nicht unbedingt ein Objekt mit code; status kann EVENT_OVERFLOW oder Active JS execution budget exceeded enthalten. Systemfehler des Geräts und Stromausfall sind keine JavaScript-Ausnahmen und können nicht mit try/catch abgefangen werden.

Modulspezifische Fehler und Reaktionen werden mit ihren Funktionen dokumentiert. Die allgemeinen try/catch-Regeln gelten unabhängig von der Quelle des Vorgangs.

19. Grenzen und Ressourcenplanung

Tabelle 85

Ressource

Grenzwert / Verhalten

Name / Version

Name: 1–64 UTF-8 Bytes; Version: 1–32 Bytes; keine Steuerzeichen. Version ist Text, nicht unbedingt semantische Versionierung.

Quellcode

Eine UTF-8-Datei, 1–131 072 Bytes.

Anwendungsspeicher

1 048 576 Bytes für Neutron AppEngine Daten und Objekte; Die Quellgröße wird separat überprüft.

Funktionsverschachtelung

Vermeiden Sie tiefe Rekursionen und lange Aufrufketten. Übermäßige Verschachtelung kann zu Anwendungsfehlern führen.

Aktive Zeit

Ungefähr 1 s pro Laufzeitverarbeitungsschritt;5 s Budget während der Codevalidierung. Keine garantierte Reaktionszeit der Waage.

Timer

16 aktive Timer.

Gleichzeitige Vorgänge

Höchstens 8 ausstehende Vorgänge. Verarbeiten Sie Ereignisse zügig; ein zu großer Rückstau kann die Anwendung mit EVENT_OVERFLOW beenden.

Konsole

Insgesamt 10 Aufrufe/s, etwa 512 Inhaltsbyte pro Aufruf.

Hochladen

768 Rohbytes/Chunk; vorhanden BLE UI: 192 Rohbytes/Chunk; Die Sitzung läuft nach 5 Minuten Inaktivität ab.

Ohne Ereignisse oder Timer wartet Neutron AppEngine, während andere Gerätefunktionen normal weiterlaufen. Das Warten verbraucht kein aktives JavaScript-Budget. Bewerten Sie die CPU-Last auf die tatsächliche Konfiguration. Hier wird kein fester CPU-Prozentsatz garantiert.

Begrenzen Sie das Wachstum von Map/Array, Daten pro Befehl und Wiederholungsversuche. Timer für langsame Kommunikation benötigen im Allgemeinen ein Sende-Flag. Sammeln Sie keine neuen Anfragen an, wenn Vorgänge nicht zügig enden können. Der Speicher bewahrt installierte Anwendungen über einen Neustart hinweg; JavaScript-Variablen verschwinden bei Stop/Reset. Verwenden Sie die dokumentierte storage-API für dauerhafte Anwendungsdaten.

20. Installation, Attribute und automatischer Start

Tabelle 86

Attribut

Beschreibung

name

Anzeigename der Anwendung und Teil des Protokollpräfixes JavaScript.

version

Benutzeranwendungsversion; getrennt von interpreterVersion, apiVersion und Geräte-Firmware-Version.

autorun

Boolescher Wert: Nach dem Booten automatisch starten, es sei denn, der Wiederherstellungsschutz blockiert den Start.

size / sha256

Länge und SHA-256 der tatsächlichen Quelldatei UTF-8 Bytes. SHA-256 ist keine Autorensignatur oder ein Ersatz für eine Autorisierung.

Wählen Sie im internen Webserver oder auf der BLE-Seite eine Datei aus, setzen Sie Attribute und wählen Sie Upload. Save attributes aktualisiert die vorhandene Anwendung; Run startet einen neuen Lauf; Stop fordert das Beenden an; Refresh zeigt den Zustand; Abort upload bricht die Übertragung ab; Delete entfernt die installierte Anwendung. Während des Laufs gilt busy=true: Stoppen Sie und warten Sie, bevor Sie Attribute ändern oder installieren. Delete während des Laufs leitet das Beenden ein; die erste Antwort lautet state=stopping, und das Löschen wird danach abgeschlossen. Prüfen Sie status auf empty. Status enthält außerdem runtimeActive, runtimeTaskAllocated und resourcesReleased; nach dem Beenden sind diese false, false und true. Die Freigabe aktiver Kommunikationsanfragen ist asynchron; ein neuer Run kann währenddessen BUSY zurückgeben. Der Interpreter führt ohne laufende Anwendung keinen Code aus.

Ein erfolgreicher Upload bestätigt geprüften gespeicherten Code, kein erfolgreich ausgeführtes Programm. Wählen Sie danach Run und prüfen Sie Protokolle/status. Auto run erfolgt nach der Firmwareinitialisierung und frühestens 10 s nach dem Gerätestart, nicht bei jeder MQTT-Wiederverbindung. Das Aktivieren von autorun in den Attributen löst keinen sofortigen manuellen Run aus.

Die anfängliche Konsolenausgabe ist möglicherweise nicht sichtbar, wenn der Debug-Transport getrennt ist. Überprüfen Sie den APP-Status/lastError. Ein Programm kann nach einem einzigen console.log weiterlaufen, da die Laufzeit auf zukünftige Ereignisse wartet.

21. APP-Protokoll für Clients und Scale Monitor

Für das Hochladen ist kein neuer Kommunikationskanal erforderlich. Verwenden Sie den vorhandenen authentifizierten Befehlspfad. Dies ist ein Protokoll für externe Verwaltungsclients, keine Funktionen, die die Anwendung JavaScript selbst aufrufen kann.

Tabelle 87

Transport

Anfrage

Antwort

Internes HTTP/HTTPS

Authentifiziert POST /api/cmd, Content-Type: text/plain; Nachrichtenkörper APP <JSON>. Verwenden Sie die vorhandene Anmeldesitzung des Geräts.

JSON-Objekt; prüfen Sie ok, nicht nur den HTTP-Status.

BLE

Vorhandene Befehlscharakteristik und mit Anmeldeinformationen versehener APP <JSON>-Befehl. Verwenden Sie dieselbe Sendewarteschlange/Fragmentierung wie andere Befehle.
Vorhandener Benachrichtigungskanal, APP <JSON> mit möglicher verschachtelter Debug-Ausgabe.

MQTT

Bestehendes Gerät CMP/RX Thema. DATA enthält Base64 der vollständigen UTF-8 JSON-Anfrage. Veröffentlichen Sie mit retain=false.

CMP/TX, APP <JSON>.
APP;MID=<device MID>;P=<existing credential>;DATA=<base64 UTF-8 JSON>;

Behalten Sie vorhandene MID/Anmeldeinformationsprüfungen und MQTT-Authentifizierung bei. Zurückgehaltene APP-Befehle werden abgelehnt. Das Hochladen von MQTT erfolgt unabhängig von der Verwendung von MQTT in JavaScript. Die dekodierte APP-Anfrage JSON umfasst höchstens 2048 Bytes.

21.1 Dateiübertragung

Senden Sie vor Beginn stop und prüfen Sie mit status auf busy=false. Berechnen Sie Größe und SHA-256 über die ursprünglichen Dateibytes. Führen Sie dann begin → chunk-Sequenz → commit → status aus. Warten Sie jede chunk-Antwort ab; senden Sie nicht alle Blöcke gleichzeitig.

APP {"op":"begin","rid":"install-001","name":"TCP tehtnica","version":"1.0.0","autorun":false,"size":1234,"sha256":"<64 hex characters>"}
APP {"op":"chunk","rid":"chunk-001","uploadId":"<id from begin>","offset":0,"data":"<base64 source bytes>"}
APP {"op":"commit","rid":"commit-001","uploadId":"<id from begin>"}
APP {"op":"status","rid":"status-001"}

Dies ist ein Nachrichtenschema, keine fertige Übertragung: Ersetzen Sie size, hash, uploadId und data durch tatsächliche Werte. begin gibt uploadId, offset=0 und chunkSize=768 zurück. Offset ist eine Byteposition; teilen Sie Bytefolgen vor der Base64-Kodierung auf. Die vorhandene BLE-Oberfläche verwendet 192 Quellbyte pro APP-Anfrage und zerlegt Nachrichten mit Zugangsdatenrahmen weiter in GATT-Schreibvorgänge.

Tabelle 88

Vorgang

Parameter zusätzlich zu op/rid

Ergebnis / Bedingungen

begin

name, version, autorun:boolean, size:integer, sha256:string

Erstellt eine Sitzung; gibt uploadId, offset und chunkSize zurück. Erfordert mindestens size × 2 + 4096 freie Speicherbyte. Brechen Sie zuerst jede andere aktive Sitzung ab.

chunk

uploadId, offset:integer, data:base64

1–768 dekodierte Bytes. Gibt den bestätigten Gesamtoffset zurück. Ein vorheriger Block darf nur mit identischen Bytes wiederholt werden, die vollständig innerhalb des bestätigten Bereichs liegen.

commit

uploadId

Nach Eingang aller Byte zulässig. Startet die asynchrone SHA-/Syntaxprüfung und Aktivierung; ok=true bestätigt keine abgeschlossene Aktivierung. Fragen Sie status ab, bis busy=false gilt.

abort

uploadId

Entfernt bereitgestellte Dateien und Sitzungen. Zulässig, wenn nicht besetzt. Sitzungen, die zu anderen Transporten gehören, können nicht allein mit uploadId übernommen werden.

configure

name, version, autorun:boolean

Ändert alle vorhandenen Anwendungsattribute und startet die asynchrone Validierung/Aktivierung. Erfordert eine installierte Anwendung, keinen aktiven Upload und busy=false.

run

—

Startet die installierte Anwendung und gibt state zurück. Der Upload muss abgeschlossen oder abgebrochen sein und busy=false gelten.

stop

—

Bricht den ausstehenden automatischen Start ab und fordert das Beenden an. Die Bestätigung bestätigt die Annahme des Befehls; fragen Sie status bis zum Abschluss ab.

status

—

Aktueller Status, installierte Attribute, Fehler und Wiederherstellung. Auch während der Ausführung erlaubt.

delete

—

Löscht die aktive Anwendung, ihre Sicherung, Zwischendateien und Wiederherstellungsdatensätze. Stoppen Sie zuerst und brechen Sie jeden Upload ab.

Prüfen Sie den booleschen Wert ok in jeder Antwort. Ein Fehler liefert ok=false und Fehlertext, getrennt von JavaScript-Promise-error.code. Das optionale rid ist eine Text-Korrelations-ID bis 64 Byte. Wiederholen Sie eine ID nur mit identischem JSON; anderer Inhalt unter derselben ID wird abgelehnt. Der Cache erfolgreicher Änderungen enthält nur die letzten sechs Anfragen pro Prozess und garantiert keine dauerhafte genau einmalige Ausführung. Verwenden Sie für Blöcke uploadId/offset und bestätigte Bytefolgen.

Eine Sitzung gehört zu ihrem ursprünglichen Transport und uploadId und kann nach 5 Minuten Inaktivität ablaufen. Prüfen Sie nach verlorener Antwort status/received; raten Sie keine Offsets. Ein Hash-/Syntaxfehler ist keine erfolgreiche Installation. Prüfen Sie nach commit name/version/sha256 und lastError.

21.2 Status und Abschluss von Vorgängen

{
  "ok": true, "rid": "status-001",
  "state": "running", "busy": true,
  "name": "TCP tehtnica", "version": "1.0.0", "autorun": false,
  "size": 1234, "sha256": "<64 hex characters>", "lastError": "",
  "uploadId": "", "received": 0, "maxSize": 131072,
  "recovery": {
    "healthy": true, "crashes": 0, "limit": 3,
    "autoRunDisabled": false, "stableAfterMs": 60000,
    "lastState": "starting", "lastResetReason": 1, "error": ""
  }
}

Das Beispiel dient der Veranschaulichung; lesen Sie tatsächliche Werte. state kann empty, ready, validating, running, stopped, error oder blocked sein. busy ist auch während eines normalen langen Anwendungslaufs true. Warten Sie für den Abschluss der Validierung auf busy=false und prüfen Sie lastError sowie die Identität des installierten Codes. Prüfen Sie für Run running und überwachen Sie spätere Fehler. Die Wiederherstellungswerte lastState und lastResetReason sind Firmwarediagnosen und kein Geschäftsprotokollstatus.

Tabelle 89

Beispiel eines APP-Fehlers

Bedeutung / Client-Reaktion

BUSY

stop senden und den Abschluss abwarten; während der Validierung status abfragen.

Invalid APP JSON

Ungültiger JSON oder Anfrage überschreitet 2048 Bytes.

Invalid metadata / Invalid name, version, autorun, size or sha256

Prüfen Sie UTF-8-Längen, den booleschen Wert autorun, hash und size.

Invalid upload session

Falscher uploadId, Transport oder abgelaufene Sitzung.

Invalid offset / Overlapping chunk / Duplicate chunk differs

Passen Sie offset an das bestätigte received an; ändern Sie die Datei während der Übertragung nicht.

Upload incomplete

Festschreiben, bevor alle Bytes eintreffen.

Insufficient filesystem space

Nicht genügend Platz für sicheren Transfer und Austausch.

No application installed

run/configure ohne installierte Anwendung.

Application storage not ready / Task allocation failed…

Speicher oder RAM nicht bereit; prüfen Sie status/Protokolle und Gerätediagnosen.

Die Liste der Textfehler ist nicht vollständig. Bewahren Sie den vollständigen Wert error/lastError in der Clientdiagnose auf. Ein Timeout des externen Clients beweist keine Ablehnung durch das Gerät.

22. Automatischer Start und Absturzschutz

Vor dem Start speichert Neutron AppEngine die Anwendungsidentität und überwacht den Starterfolg. Ein unerwarteter Geräteneustart während dieses Zeitraums zeichnet einen instabilen Versuch beim nächsten Start auf. Nach drei aufeinanderfolgenden instabilen Versuchen wird der automatische Start vor einem vierten automatischen Versuch blockiert. Der Code bleibt zur Überprüfung oder zum Austausch gespeichert.

Unerwartete Resets aufgrund von Systemfehlern oder Stromproblemen können den Zähler für instabile Versuche erhöhen. Normales Einschalten und geplante Neustarts werden anders behandelt als Anwendungsabstürze. Ein instabiler Versuch allein beweist keinen Fehler im Benutzercode; Überprüfen Sie auch die Gerätediagnose.

Etwa 60 s bestätigter Betrieb löschen die Fehlerfolge; dazu zählt normales Warten auf Ereignisse und nicht nur CPU-Zeit. Ein regulärer Stop schließt die Markierung. Eine vorhandene Auto-run-Sperre bleibt bis zur erfolgreichen ausdrücklichen Installation oder Save attributes/configure bestehen. Manueller Run bleibt möglich und wird überwacht. Ein Fehler beim Speichern des Wiederherstellungsdatensatzes kann Run aus Schutzgründen verhindern.

Ein gewöhnlicher, nicht behandelter Fehler JavaScript stoppt die Anwendung und setzt lastError; es unterscheidet sich von einem Modul-Reset. Die Werkseinstellung löscht installierten Code, seine Sicherung, bereitgestellte Dateien, den Wiederherstellungsstatus und den Anwendungsspeicher, einschließlich lokaler Datenbanken. JavaScript try/catch kann einen Hardware-Reset nicht verhindern.

23. Regeln für ScaleGuru AI und Integratoren

Verwenden Sie diesen Abschnitt als Vertrag für die Anwendungserstellung. ScaleGuru AI sollte eine vollständige UTF-8 . js-Datei zurückgeben und die erforderlichen Systemkonfigurations- und Testschritte separat auflisten. Die Dokumentation berechtigt AI nicht automatisch zum Hochladen oder Ausführen von Code auf dem Gerät eines Benutzers.

Target: CS-NEUTRON application, Neutron AppEngine 1.0.0, API 1.
1. Identify required modules and verify support with app.capabilities().
2. Use only documented functions of supported modules. Never invent APIs.
3. Produce one UTF-8 file without top-level await, import/export or npm.
4. Define and call an async initialization function; handle its rejection.
5. Use standard timers; setInterval does not await async callbacks.
6. Handle rejected operations with await/try/catch or .catch().
7. Choose error handling: continue, bounded retry or app.stop().
8. Respect memory, active-time and module limits.
9. No busy waiting, deep recursion or unbounded queues and buffers.
10. Find configuration, events, errors and examples in the relevant module chapter.
11. The installation channel does not determine the application's communication module.
12. Test manual Run first; enable auto run only after functional testing.
13. If a required module is unsupported, explain the limit instead of generating fake calls.

23.1 Tests vor der Anwendungsfreigabe

Tabelle 90

Test

Erwartetes Ergebnis

Gerät ohne gültige Messung

Keine unkontrollierte Ausnahme; Die Anwendung meldet eindeutig eine nicht verfügbare Messung.

Mehrere Befehle in einem Empfang

Behandeln Sie jeden Befehl; Erwägen Sie die Reihenfolge der Antworten für asynchrone Befehle.

Besetzte Waage / abgelehnter Vorgang

Die erwartete Ablehnung wird ohne unendliche Wiederholungsversuche behandelt.

Stoppen Sie ohne aktive Timer

Die wartende Laufzeitumgebung wacht auf und beendet sich regulär.

Neustart mit Autorun

Die validierte installierte Version startet; lastError und recovery werden geprüft.

24. Revisionen und weiterführende Dokumentation

Tabelle 91

Handbuch

Datum

Änderungen

1.0

15. 11. 2026

Erste API-Veröffentlichung: Laufzeitumgebung, Waage, I/O, Moduleinstellungen, Dateien, lokale Datenbank, TCP, serielle Schnittstellen, MQTT, REST/HTTP, APP-Protokoll und Startschutz.

Weiterführende Dokumentation: CSCP — Neutron-Kommunikationsprotokoll. CSCP beschreibt Systembefehle und Konfiguration; diese werden nicht automatisch zu JavaScript-Funktionen. Diese Referenz folgt dem Aufbau Zweck, Syntax, Parameter, Ergebnis, Fehler und Beispiel.

Beispiele sind als statischer Code enthalten und bleiben ohne JavaScript lesbar. Seitensuche, Kopieren von Code und Drucken sind Dokumentationswerkzeuge; sie führen keine Anwendungen aus und kommunizieren nicht mit einem Gerät. Die Dokumentation ist nicht in die Firmware eingebettet.

Häufig gestellte Fragen

Kann ich Node.js, npm oder Browser-APIs verwenden?

Nein. Laden Sie ein einzelnes UTF-8-JavaScript-Skript hoch und verwenden Sie die dokumentierten neutron-js-1-APIs. Node.js, npm, das DOM, import/export und await auf oberster Ebene sind nicht verfügbar.

Wie prüfe ich die verfügbaren Funktionen?

Rufen Sie app.capabilities() auf dem Gerät auf. Prüfen Sie apiVersion, interpreterVersion, features und die modulspezifischen Grenzen, bevor Sie eine Funktion verwenden.

Bleiben Anwendungsdaten nach Stop und Neustart erhalten?

JavaScript-Variablen bleiben nicht erhalten. Dateien und lokale Datensatzdatenbanken in storage bleiben nach Stop, Neustart und regulärem Ersetzen der Anwendung erhalten. Das Zurücksetzen auf Werkseinstellungen löscht diese Daten.

Wann sollte ich Auto run aktivieren?

Laden Sie die Anwendung zuerst hoch, starten Sie sie manuell und testen Sie das erforderliche Verhalten, die Grenzen und Fehlerfälle. Aktivieren Sie Auto run erst nach Funktionstests. Der Startschutz kann wiederholte instabile automatische Starts blockieren.

Brauchen Sie Hilfe?

Benötigen Sie Hilfe bei Software, Konnektivität oder der Verwendung einer Lösung? Beschreiben Sie das Problem, damit wir beim nächsten Schritt helfen können.

Eine Anfrage vorbereiten →