TECHNIKA WAGOWA · WŁASNY ROZWÓJ · WSPARCIE
+386 2 320 33 46info@preciz.si

NEUTRON APPENGINE · INSTRUKCJA DLA PROGRAMISTÓW

Neutron AppEngine — tworzenie aplikacji JavaScript

Tworzenie aplikacji JavaScript dla CloudScaleLink Neutron i CloudScale Neutron NS: środowisko wykonawcze, ważenie, cyfrowe I/O, ustawienia, pamięć, moduły komunikacyjne i zarządzanie aplikacjami. Instrukcja 1.0 · Neutron AppEngine 1.0.0 · API 1 · Data publikacji: 16 listopada 2026.

1. Cel i zakres

Neutron AppEngine jest dostępny dla modułu CloudScaleLink Neutron i modułów wagowych CloudScale Neutron NS z oprogramowaniem firmware w wersji 2.7 lub nowszej.

Neutron AppEngine umożliwia tworzenie własnych aplikacji JavaScript bezpośrednio w modułach wagowych CloudScaleLink Neutron i Neutron. Aplikacje mogą odczytywać pomiary, wykonywać operacje wagi, korzystać z timerów i łączyć się z systemami zewnętrznymi za pomocą obsługiwanych modułów komunikacyjnych (MQTT, TCP, WebSocket, REST, RS-232 i RS-485).
Ta instrukcja jest przeznaczona dla programistów, integratorów i systemów AI przygotowujących aplikacje do użytku z Neutron.
Ta instrukcja opisuje profil neutron-js-1, apiVersion: 1, według stanu na 16 listopada 2026. Wersja instrukcji to 1.0, a wersja interpretera Neutron AppEngine to 1.0.0. Wszystkie opisane tutaj zaimplementowane funkcje, zdarzenia, właściwości i operacje są dostępne od wersji 1.0.0. Sama wersja firmware nie potwierdza obsługi każdej funkcji: sprawdź app.capabilities() na urządzeniu i przetestuj aplikację.
Tabela 1

Obszar

Stan

Interfejs

Wykonywanie JavaScript

Zaimplementowano

Interpreter Neutron AppEngine; jedna trwale zapisana aplikacja użytkownika

Środowisko wykonawcze i diagnostyka

Zaimplementowano

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

Timery

Zaimplementowano

setTimeout, setInterval, anulowanie za pomocą identyfikatora

Waga

Zaimplementowano

Odczyt masy, tarowanie, zerowanie, ustawianie zadanej tary i wysyłanie poleceń CSCP za pomocą scale.cmd()

Klient / serwer TCP

Zaimplementowano

Przejęcie istniejącego interfejsu TCP, obsługa zdarzeń i wysyłanie danych

MQTT

Zaimplementowano

Niezależny broker użytkownika; mqtt, mqtts, ws i wss

RS-232 / RS-485

Zaimplementowano

serial.rs232 i serial.rs485; przejmowanie, konfiguracja SMD, zdarzenia i wysyłanie

Instalacja

Zaimplementowano

BLE, wewnętrzne HTTP/HTTPS i MQTT przez istniejący kanał APP

Wejścia/wyjścia cyfrowe

Zaimplementowano

io.input(1..6), io.output(1..6); konfiguracja, zdarzenia, przejmowanie wyjść i liczniki

Parametry i aplikacja zliczająca

Za pomocą obsługiwanych poleceń CSCP

scale.cmd() wykonuje polecenia obsługiwane przez urządzenie; osobne API JavaScript counting.* nie jest jeszcze dostępne.

Ustawienia modułu

Zaimplementowano

device.cmd dla RMD/SMD; device.settings.read/list/write

Pliki i lokalna baza danych

Zaimplementowano

storage; openRecords i indeksowane wyszukiwanie według klucza

REST/HTTP z JavaScript

Zaimplementowano

fetch dla HTTP/HTTPS; status, nagłówki, tekst, JSON i odpowiedzi binarne

Plik jest zwykłym skryptem .js w kodowaniu UTF-8. Jego rozmiar jest mierzony w bajtach, a nie w wierszach lub znakach, i wynosi maksymalnie 131 072 bajtów. Nie jest to moduł ES: import/export, await na najwyższym poziomie, Node.js, npm i DOM są niedostępne. Korzystaj z globalThis, standardowych obiektów JavaScript, Promise, async/await, Map, JSON i Uint8Array. Przeglądarkowe API TextEncoder/TextDecoder nie należą do tego profilu.

2. Pierwsza aplikacja

Zapisz poniższy kod jako first-application.js, prześlij go i wybierz Run. Co sekundę zwiększa on licznik i zapisuje jego wartość w skonfigurowanym kanale diagnostycznym. Konfiguracja wagi ani komunikacji nie jest wymagana.
let counter = 0;
setInterval(() => {
    counter += 1;
    console.log("Counter:", counter);
}, 1000);

W lokalnym interfejsie HTTP/HTTPS lub na stronie BLE otwórz JS application lub App, wybierz plik, podaj jego nazwę i wersję, a następnie wybierz Upload. Po walidacji wybierz Run. Aby zatrzymać aplikację, użyj Stop, a do sprawdzenia jej stanu i ostatniego błędu użyj Refresh. Włącz Auto run dopiero po przeprowadzeniu testów.

Aby przeprowadzić inicjalizację asynchroniczną, zdefiniuj funkcję i ją wywołaj. start to dowolna nazwa zdefiniowana przez użytkownika, bez specjalnego znaczenia dla środowiska wykonawczego.
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. Środowisko wykonawcze, zdarzenia i cykl życia

Unikaj blokowania: nie używaj while (true), aktywnego oczekiwania, głębokiej rekurencji ani nieskończonych łańcuchów Promise. Środowisko wykonawcze pozwala na około 1 s aktywnego wykonywania na krok przetwarzania; oczekiwanie na zdarzenie nie zużywa tego budżetu. Jego przekroczenie lub przepełnienie kolejki może zatrzymać aplikację; nie używaj tego jako normalnego mechanizmu sterowania.
Przygotowanie środowiska i kompilacja aplikacji mają osobne limity czasu wynoszące do 5 sekund na etap. Limit kompilacji jest taki sam podczas przesyłania i uruchamiania. Początkowe wykonanie kodu użytkownika otrzymuje następnie nowy limit jednej sekundy; ten sam limit dotyczy przetwarzania zdarzeń i timerów. Oczekiwanie na odpowiedzi sieciowe lub timery nie zużywa tego budżetu. TIMEOUT podaje etap i limit, na przykład TIMEOUT during application startup (limit 1000 ms). Przerwanie wykonywania nie powoduje automatycznego restartu modułu.
Tabela 2

Etap

Zachowanie

Instalacja

Kod źródłowy i atrybuty są zapisywane w pamięci urządzenia. Integralność i składnia są sprawdzane bez wykonywania kodu użytkownika.

Uruchomienie

Każde uruchomienie tworzy nowy kontekst JavaScript. Skrypt początkowy jest wykonywany raz; zmienne z poprzedniego uruchomienia nie są zachowywane.

Oczekiwanie

Po zakończeniu skryptu początkowego środowisko wykonawcze pozostaje aktywne, czekając na kolejny timer lub zdarzenie. Gdy nie ma pracy, Neutron AppEngine czeka bez wykonywania kodu użytkownika.

Zdarzenie

Zdarzenie z obsługiwanego modułu, upływ czasu timera lub wynik operacji wyzwala odpowiednie przetwarzanie w Neutron AppEngine. Oczekujący obiekt Promise zostaje spełniony lub odrzucony.

Zatrzymanie lub błąd

Timery i kontekst są usuwane. Stop nie cofa skutków już wykonanych operacji.

Ponowne uruchomienie

Najpierw zatrzymaj poprzednie uruchomienie i poczekaj na busy: false. Instalacja nowej wersji również wymaga zatrzymania aplikacji.
Neutron AppEngine wykonuje funkcje wywołania zwrotnego kolejno. Obsługuj zdarzenia szybko i unikaj nieograniczonej liczby oczekujących operacji. await oddaje sterowanie, umożliwiając wykonywanie innych funkcji wywołania zwrotnego podczas oczekiwania. Asynchroniczna funkcja wywołania zwrotnego nie jest więc transakcją blokującą inne zdarzenia.

4. API aplikacji

4.1 app.capabilities()

Dostępne od: Neutron AppEngine 1.0.0
const capabilities = app.capabilities();
Cel. Sprawdzenie obsługiwanych funkcji i limitów przed użyciem API.
Opis. Synchronicznie zwraca nowy obiekt z informacjami o obsłudze, wersjach i limitach. Nie inicjalizuje poszczególnych modułów ani nie gwarantuje ich bieżącej gotowości.

Parametry

Brak parametrów.

Wynik

Obiekt pokazany poniżej. Właściwości features wskazują obsługę modułu. Ustawienia i ograniczenia dla każdego modułu wyjaśniono w jego rozdziale.

Błędy i szczególne uwagi

Nie zwraca Promise. Nie wnioskuj o obsłudze funkcji na podstawie samej nazwy urządzenia lub wersji aplikacji.

Przykład

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
  }
}
Odczytaj wersję za pomocą app.capabilities().interpreterVersion, a nazwę za pomocą app.capabilities().interpreter. interpreterVersion oznacza wersję produktu Neutron AppEngine, apiVersion — kontrakt API, a runtime — profil. Są to wartości odrębne od wersji aplikacji użytkownika i firmware urządzenia. Aktualne wersje: Neutron AppEngine 1.0.0, API 1 i instrukcja 1.0.
console.info(app.capabilities().interpreter, app.capabilities().interpreterVersion);
Podczas uruchamiania urządzenia Neutron AppEngine interpreter v1.0.0 jest rejestrowane na poziomie INFO. Widoczność zależy od kanału diagnostycznego i ustawień poziomu. Do sprawdzenia z poziomu aplikacji użytkownika użyj capabilities.

4.2 app.stop()

Dostępne od: Neutron AppEngine 1.0.0
app.stop();
Cel. Normalne zatrzymanie aplikacji użytkownika.
Opis. Żąda zatrzymania wykonywania i uniemożliwia kolejne wywołania zwrotne. Nie resetuje modułu. Zwalnia zasoby przejęte przez aplikację; zachowanie poszczególnych zasobów opisano w rozdziałach dotyczących odpowiednich modułów.

Parametry

Brak parametrów.

Wynik

undefined. To jest żądanie, a nie Promise potwierdzające zamknięcie. Użyj statusu APP do potwierdzenia zewnętrznego.

Błędy i szczególne uwagi

Nie cofa już wykonanych operacji. Użyj return po wywołaniu, jeśli kolejne instrukcje bieżącej funkcji nie mogą być wykonane. Nie ma funkcji wywołania zwrotnego użytkownika przy zatrzymaniu.

Przykład

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

5. Diagnostyka i konsola

Konsola wysyła dane do systemu diagnostycznego Neutron, a nie do konsoli przeglądarki. Istniejące ustawienia diagnostyczne DI i DL wybierają wyjście i poziom. Wiadomości otrzymują prefiks [JS:application name]. Bieżąca konfiguracja transportu i połączenie określają, gdzie wiadomości są widoczne.

5.1 console.log(...)

Dostępne od: Neutron AppEngine 1.0.0
console.log(...values);
Cel. Rejestrowanie pomiarów lub stanu.
Opis. Łączy argumenty spacjami. Dla obiektów próbuje użyć JSON.stringify, a dla innych wartości konwersji na tekst. Zastępuje znaki sterujące spacjami. Wszystkie metody konsoli współdzielą ten sam limit rejestrowania.

Parametry

Tabela 3

Parametr

Typ / wymaganie

Opis

values

dowolne wartości JavaScript / opcjonalne

Zero lub więcej argumentów. Unikaj dużych obiektów i struktur cyklicznych.

Wynik

undefined; INFO dziennik, widoczny za pomocą DL ≥ 3 i odpowiedniego DI.

Błędy i szczególne uwagi

Rejestrowanie samo w sobie nie zatrzymuje aplikacji, także console.error(). Wspólny limit wynosi 10 wywołań/s i około 512 bajtów treści na wywołanie, bez prefiksu. Nadmiar danych wyjściowych jest odrzucany lub obcinany; może pojawić się dodatkowe ostrzeżenie o limicie częstotliwości. Błędy konwersji lub pamięci mogą zgłosić wyjątek JavaScript.

Przykład

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

5.2 console.info(...)

Dostępne od: Neutron AppEngine 1.0.0
console.info(...values);
Cel. Zgłaszanie informacji o uruchamianiu lub stanie.
Opis. Łączy argumenty spacjami. Dla obiektów próbuje użyć JSON.stringify, a dla innych wartości konwersji na tekst. Zastępuje znaki sterujące spacjami. Wszystkie metody konsoli współdzielą ten sam limit rejestrowania.

Parametry

Tabela 4

Parametr

Typ / wymaganie

Opis

values

dowolne wartości JavaScript / opcjonalne

Zero lub więcej argumentów. Unikaj dużych obiektów i struktur cyklicznych.

Wynik

undefined; INFO dziennik, widoczny za pomocą DL ≥ 3 i odpowiedniego DI.

Błędy i szczególne uwagi

Rejestrowanie samo w sobie nie zatrzymuje aplikacji, także console.error(). Wspólny limit wynosi 10 wywołań/s i około 512 bajtów treści na wywołanie, bez prefiksu. Nadmiar danych wyjściowych jest odrzucany lub obcinany; może pojawić się dodatkowe ostrzeżenie o limicie częstotliwości. Błędy konwersji lub pamięci mogą zgłosić wyjątek JavaScript.

Przykład

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

5.3 console.warn(...)

Dostępne od: Neutron AppEngine 1.0.0
console.warn(...values);
Cel. Rejestrowanie ostrzeżenia lub obsłużonego problemu.
Opis. Łączy argumenty spacjami. Dla obiektów próbuje użyć JSON.stringify, a dla innych wartości konwersji na tekst. Zastępuje znaki sterujące spacjami. Wszystkie metody konsoli współdzielą ten sam limit rejestrowania.

Parametry

Tabela 5

Parametr

Typ / wymaganie

Opis

values

dowolne wartości JavaScript / opcjonalne

Zero lub więcej argumentów. Unikaj dużych obiektów i struktur cyklicznych.

Wynik

undefined; WARN dziennik, widoczny za pomocą DL ≥ 2 i odpowiedniego DI.

Błędy i szczególne uwagi

Rejestrowanie samo w sobie nie zatrzymuje aplikacji, także console.error(). Wspólny limit wynosi 10 wywołań/s i około 512 bajtów treści na wywołanie, bez prefiksu. Nadmiar danych wyjściowych jest odrzucany lub obcinany; może pojawić się dodatkowe ostrzeżenie o limicie częstotliwości. Błędy konwersji lub pamięci mogą zgłosić wyjątek JavaScript.

Przykład

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

5.4 console.error(...)

Dostępne od: Neutron AppEngine 1.0.0
console.error(...values);
Cel. Opisanie błędu.
Opis. Łączy argumenty spacjami. Dla obiektów próbuje użyć JSON.stringify, a dla innych wartości konwersji na tekst. Zastępuje znaki sterujące spacjami. Wszystkie metody konsoli współdzielą ten sam limit rejestrowania.

Parametry

Tabela 6

Parametr

Typ / wymaganie

Opis

values

dowolne wartości JavaScript / opcjonalne

Zero lub więcej argumentów. Unikaj dużych obiektów i struktur cyklicznych.

Wynik

undefined; ERROR dziennik, widoczny za pomocą DL ≥ 1 i odpowiedniego DI.

Błędy i szczególne uwagi

Rejestrowanie samo w sobie nie zatrzymuje aplikacji, także console.error(). Wspólny limit wynosi 10 wywołań/s i około 512 bajtów treści na wywołanie, bez prefiksu. Nadmiar danych wyjściowych jest odrzucany lub obcinany; może pojawić się dodatkowe ostrzeżenie o limicie częstotliwości. Błędy konwersji lub pamięci mogą zgłosić wyjątek JavaScript.

Przykład

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

5.5 console.debug(...)

Dostępne od: Neutron AppEngine 1.0.0
console.debug(...values);
Cel. Rejestrowanie szczegółów podczas programowania.
Opis. Łączy argumenty spacjami. Dla obiektów próbuje użyć JSON.stringify, a dla innych wartości konwersji na tekst. Zastępuje znaki sterujące spacjami. Wszystkie metody konsoli współdzielą ten sam limit rejestrowania.

Parametry

Tabela 7

Parametr

Typ / wymaganie

Opis

values

dowolne wartości JavaScript / opcjonalne

Zero lub więcej argumentów. Unikaj dużych obiektów i struktur cyklicznych.

Wynik

undefined; DEBUG dziennik, widoczny za pomocą DL ≥ 4 i odpowiedniego DI.

Błędy i szczególne uwagi

Rejestrowanie samo w sobie nie zatrzymuje aplikacji, także console.error(). Wspólny limit wynosi 10 wywołań/s i około 512 bajtów treści na wywołanie, bez prefiksu. Nadmiar danych wyjściowych jest odrzucany lub obcinany; może pojawić się dodatkowe ostrzeżenie o limicie częstotliwości. Błędy konwersji lub pamięci mogą zgłosić wyjątek JavaScript.

Przykład

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

Poziom diagnostyczny może filtrować dane wyjściowe. Nie używaj konsoli jako niezawodnego transportu danych biznesowych. Do niezawodnej wymiany danych użyj odpowiedniego obsługiwanego modułu komunikacyjnego.

6. Timery

Timer określa najwcześniejszy planowany czas wykonania. Nie jest to środowisko JavaScript z twardymi gwarancjami czasu rzeczywistego: pomiar, komunikacja, poprzednie wywołania zwrotne i planowanie mogą opóźnić wykonanie. Pominięte interwały nie tworzą nieograniczonej kolejki wywołań do nadrobienia.

Okresowa funkcja wywołania zwrotnego async może nadal oczekiwać, gdy nadejdzie następny interwał. Użyj flagi zajętości lub zaplanuj następne setTimeout po zakończeniu operacji. To samo dotyczy zdarzeń z dowolnego modułu: jeśli przetwarzanie musi być sekwencyjne, zaimplementuj kolejkę o ograniczonej długości lub odrzucaj nową pracę do czasu zakończenia poprzedniej operacji.

6.1 setTimeout()

Dostępne od: Neutron AppEngine 1.0.0
const id = setTimeout(callback, delayMs = 0, ...args);
Cel. Jednorazowe wykonanie funkcji po opóźnieniu.
Opis. Zwraca natychmiast; wywołanie zwrotne zostanie uruchomione później. Zegar jest usuwany z aktywnego zestawu przed wywołaniem wywołania zwrotnego, więc wywołanie zwrotne może zaplanować kolejne wykonanie.

Parametry

Tabela 8

Parametr

Typ / wymaganie

Opis

callback

function / wymagane

Funkcja; kod przekazany jako ciąg znaków nie jest obsługiwany.

delayMs

number / opcjonalne, domyślnie 0

Konwertowane na liczbę i liczbę całkowitą. Nieprawidłowe, ujemne lub zerowe opóźnienia mają wartość co najmniej 1 ms. Maksymalnie: 2 147 483 647 ms.

... args

dowolne wartości / opcjonalne

Argumenty przekazywane funkcji wywołania zwrotnego przez środowisko wykonawcze.

Wynik

Numeryczny ID zaakceptowany przez clearTimeout. Obowiązuje tylko podczas bieżącego działania aplikacji.

Błędy i szczególne uwagi

Synchroniczny INVALID_ARGUMENT jeśli wywołanie zwrotne nie jest funkcją; QUOTA_EXCEEDED, jeśli timery 16 są już aktywne. Nieobsługiwany wyjątek lub odrzucenie wywołania zwrotnego może zatrzymać aplikację.

Przykład

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

6.2 setInterval()

Dostępne od: Neutron AppEngine 1.0.0
const id = setInterval(callback, delayMs = 0, ...args);
Cel. Okresowe odczytywanie lub wysyłanie danych.
Opis. Pierwsze wywołanie następuje po opóźnieniu. Kolejne funkcje wywołania zwrotnego są planowane okresowo; środowisko wykonawcze nie czeka na obietnice zwracane przez funkcje async. Opóźnienia nie powodują nieograniczonego nadrabiania pominiętych wywołań.

Parametry

Tabela 9

Parametr

Typ / wymaganie

Opis

callback

function / wymagane

Funkcja; kod przekazany jako ciąg znaków nie jest obsługiwany.

delayMs

number / opcjonalne, domyślnie 0

Konwertowane na liczbę i liczbę całkowitą. Nieprawidłowe, ujemne lub zerowe opóźnienia mają wartość co najmniej 1 ms. Maksymalnie: 2 147 483 647 ms.

... args

dowolne wartości / opcjonalne

Argumenty przekazywane funkcji wywołania zwrotnego przez środowisko wykonawcze.

Wynik

Liczbowy identyfikator akceptowany przez clearInterval. Interwał pozostaje aktywny do anulowania lub zatrzymania aplikacji.

Błędy i szczególne uwagi

Te same błędy synchroniczne co setTimeout. Chroń pracę asynchroniczną przed nakładaniem i przechwytuj odrzucenia wewnątrz funkcji async.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
clearTimeout(id);
Cel. Anulowanie przyszłych wykonań timera.
Opis. Obie funkcje korzystają z tego samego rejestru timerów i mogą anulować dowolny typ timera. Zalecane jest użycie odpowiedniej pary set/clear.

Parametry

Tabela 10

Parametr

Typ / wymaganie

Opis

id

number / wymagane

Identyfikator zwrócony przez setTimeout lub setInterval. Konwertowany za pomocą Number(id).

Wynik

undefined. Nieznany ID nie ma żadnego efektu.

Błędy i szczególne uwagi

Nie przerywa wywołania zwrotnego ani operacji asynchronicznej, która już się rozpoczęła. Konwersja niewłaściwej wartości JavaScript na liczbę może spowodować wygenerowanie standardowego wyjątku JavaScript.

Przykład

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

6.4 clearInterval()

Dostępne od: Neutron AppEngine 1.0.0
clearInterval(id);
Cel. Anulowanie przyszłych wykonań timera.
Opis. Obie funkcje korzystają z tego samego rejestru timerów i mogą anulować dowolny typ timera. Zalecane jest użycie odpowiedniej pary set/clear.

Parametry

Tabela 11

Parametr

Typ / wymaganie

Opis

id

number / wymagane

Identyfikator zwrócony przez setTimeout lub setInterval. Konwertowany za pomocą Number(id).

Wynik

undefined. Nieznany ID nie ma żadnego efektu.

Błędy i szczególne uwagi

Nie przerywa wywołania zwrotnego ani operacji asynchronicznej, która już się rozpoczęła. Konwersja niewłaściwej wartości JavaScript na liczbę może spowodować wygenerowanie standardowego wyjątku JavaScript.

Przykład

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

7. API wagi

7.1 scale.read()

Dostępne od: Neutron AppEngine 1.0.0
const measurement = scale.read();
Cel. Odczyt najnowszej dostępnej migawki wagi bez oczekiwania na stabilność.
Opis. Synchronicznie zwraca najnowszą dostępną migawkę danych wagi. Nie wyzwala nowego pomiaru. Odczytaj jeden obiekt i używaj jego pól razem, aby uzyskać spójne wartości netto/brutto/tary.

Parametry

Brak parametrów.

Wynik

Obiekt z poniższymi polami. Gdy pomiar jest niedostępny, net, gross i tare wynoszą NaN, a stable jest false. unit i status pozostają informacjami diagnostycznymi.

Błędy i szczególne uwagi

Niedostępna waga jest zgłaszana jako available=false zamiast wyjątku NO_MEASUREMENT. available=true nie oznacza stable=true. Wywołanie synchroniczne może zgłosić wyjątek po wyczerpaniu pamięci JavaScript.

Przykład

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);
}
Tabela 12

Pole

Typ

Znaczenie

available

boolean

Waga jest dostępna, interfejs ważenia jest włączony, a pomiar jest prawidłowy.

net

number

Masa netto obliczona z brutto i tary, zaokrąglona do skonfigurowanej liczby miejsc dziesiętnych.

gross

number

Masa brutto w skonfigurowanej jednostce.

tare

number

Bieżąca tara w skonfigurowanej jednostce.

stable

boolean

Prawidłowy pomiar jest stabilny według bieżącej konfiguracji wagi.

unit

string

Bieżąca jednostka wagi, taka jak kg lub g. Niekoniecznie jest to kg.

status

number

Bieżąca wartość stanu wagi. Profil JavaScript nie zapewnia oddzielnego nazwanego wyliczenia; nie wymyślaj mapowań kodu.

sequence

number

32-bitowy licznik opublikowanych pomiarów; zawija się przy przepełnieniu. Nie jest trwałym identyfikatorem rekordu ważenia.

timeMs

number

Czas ostatniej publikacji pomiaru w milisekundach od uruchomienia urządzenia. Nie jest czasem UTC; ten 32-bitowy licznik może się zawijać.

Skróty scale.net, scale.gross i scale.available to aktywne gettery odczytujące nową migawkę przy każdym dostępie. scale.tare jest funkcją; liczbową tarę odczytaj z scale.read().tare. Nie używaj dwóch oddzielnych getterów do pary brutto/netto, która musi pochodzić z tej samej migawki.

7.2 scale.tare()

Dostępne od: Neutron AppEngine 1.0.0
const measurement = await scale.tare();
Cel. Tarowanie przy użyciu bieżącego obciążenia.
Opis. Wykonuje odpowiednią funkcję wagi bez omijania wymagań stabilności, zakresu, ochrony, współbieżnych poleceń ani konfiguracji. Wykonuje polecenie ważenia T; nie jest to natychmiastowe tarowanie za pomocą TI.

Parametry

Brak parametrów.

Wynik

Promise<Measurement>: po udanej odpowiedzi odczytuje nową migawkę JavaScript ze strukturą scale.read(). Nie gwarantuje to nadejścia kolejnego pomiaru; obserwuj następne pomiary, aby potwierdzić efekt.

Błędy i szczególne uwagi

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED lub TIMEOUT. Obsługuj odrzucone obietnice za pomocą await/try/catch. Zatrzymanie niszczy kontekst; Promise kontynuacja nie jest gwarantowana.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const measurement = await scale.zero();
Cel. Wyzerowanie wagi.
Opis. Wykonuje odpowiednią funkcję wagi bez omijania wymagań stabilności, zakresu, ochrony, współbieżnych poleceń ani konfiguracji. Wykonuje Z, co różni się od tarowania. Sukces zależy od warunków pracy i dopuszczalnego zakresu zerowania.

Parametry

Brak parametrów.

Wynik

Promise<Measurement>: po udanej odpowiedzi odczytuje nową migawkę JavaScript ze strukturą scale.read(). Nie gwarantuje to nadejścia kolejnego pomiaru; obserwuj następne pomiary, aby potwierdzić efekt.

Błędy i szczególne uwagi

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED lub TIMEOUT. Obsługuj odrzucone obietnice za pomocą await/try/catch. Zatrzymanie niszczy kontekst; Promise kontynuacja nie jest gwarantowana.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const measurement = await scale.clearTare();
Cel. Usunięcie tary.
Opis. Wykonuje odpowiednią funkcję wagi bez omijania wymagań stabilności, zakresu, ochrony, współbieżnych poleceń ani konfiguracji. Wykonuje TAC, aby zażądać usunięcia bieżącej tary.

Parametry

Brak parametrów.

Wynik

Promise<Measurement>: po udanej odpowiedzi odczytuje nową migawkę JavaScript ze strukturą scale.read(). Nie gwarantuje to nadejścia kolejnego pomiaru; obserwuj następne pomiary, aby potwierdzić efekt.

Błędy i szczególne uwagi

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED lub TIMEOUT. Obsługuj odrzucone obietnice za pomocą await/try/catch. Zatrzymanie niszczy kontekst; Promise kontynuacja nie jest gwarantowana.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const measurement = await scale.setPresetTare(value);
Cel. Ustawienie zadanej tary.
Opis. Wykonuje odpowiednią funkcję wagi bez omijania wymagań stabilności, zakresu, ochrony, współbieżnych poleceń ani konfiguracji. Wykonuje TA z liczbową tarą w bieżącej jednostce wagi. Wartości nie są automatycznie przeliczane z innej jednostki.

Parametry

Tabela 13

Parametr

Typ / wymaganie

Opis

value

number / wymagane

Skończona liczba ≥ 0 w zakresie nośności wagi, w scale.read().unit. Ciągi znaków, NaN i Infinity są niedozwolone.

Wynik

Promise<Measurement>: po udanej odpowiedzi odczytuje nową migawkę JavaScript ze strukturą scale.read(). Nie gwarantuje to nadejścia kolejnego pomiaru; obserwuj następne pomiary, aby potwierdzić efekt.

Błędy i szczególne uwagi

Nieprawidłowy typ, wartość ujemna lub nieskończona powodują odrzucenie z INVALID_ARGUMENT; wartości powyżej nośności są odrzucane z OUT_OF_RANGE. Inne błędy: BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED lub TIMEOUT. Obsłuż odrzucenie za pomocą await/try/catch. Zatrzymanie niszczy kontekst; kontynuacja Promise nie jest gwarantowana.

Przykład

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();

Operacja ważenia czeka przez skonfigurowane okno czasowe polecenia wagi oraz około 2 sekundy na przetwarzanie. Dla tych operacji JavaScript nie ma osobnego parametru limitu czasu dla każdego wywołania. Waga przetwarzająca inne polecenie może zwrócić BUSY. Wykonuj zależne polecenia za pomocą kolejnych wywołań await zamiast nieograniczonego Promise.all.

7.6 scale.cmd()

Dostępne od: Neutron AppEngine 1.0.0
const response = await scale.cmd(command, { timeoutMs });
Cel. Wykonanie jednego polecenia CSCP i odczyt jego oryginalnej odpowiedzi.
Opis. Dostęp do poleceń wagi, konfiguracji i innych funkcji obsługiwanych przez urządzenie za pomocą CSCP. Obowiązują istniejące zasady walidacji parametrów i ochrony danych. RSD i zapytania o konfigurację nie wymagają prawidłowego pomiaru. S i SX czekają na stabilny pomiar; SI i SXI odpytują natychmiast.

Parametry

Tabela 14

Parametr

Typ / wymaganie

Opis

command

string / wymagane

Jedno polecenie CSCP, najwyżej 2048 bajtów UTF-8 po usunięciu otaczających białych znaków i opcjonalnego końcowego CRLF. Puste polecenia, NUL, osadzone CR/LF i inne znaki sterujące są zabronione. Składnia i wielkość liter są zgodne z CSCP.

options

object / opcjonalne, domyślnie {}

Opcje oczekiwania. Jednostkę, stabilność i uprawnienia określa polecenie oraz ustawienia wagi.

options.timeoutMs

liczba całkowita / opcjonalne

1–60000 ms. Domyślnie skonfigurowane okno oczekiwania wagi oraz 2 sekundy na przetwarzanie. Nie wydłuża wewnętrznego oczekiwania polecenia na stabilność.

Wynik

Promise<string> zawierająca oryginalną odpowiedź CSCP, najwyżej 4096 bajtów UTF-8. Jeden końcowy CRLF jest usuwany; wewnętrzne zakończenia wielowierszowe pozostają. Ciąg znaków nie jest obiektem Measurement i nie jest automatycznie parsowany. S I, ES, FT L i ERRAUTH są prawidłowymi wynikami CSCP i nie odrzucają Promise. Określ sukces polecenia na podstawie dokumentacji CSCP.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowym użyciu; MESSAGE_TOO_LARGE przy zbyt dużym poleceniu; UNSUPPORTED_COMMAND dla poleceń wieloodpowiedziowych/bez odpowiedzi lub resetu; BUSY przy zajętej wadze lub limicie operacji współbieżnych; TIMEOUT przy zbyt długim oczekiwaniu; NO_RESPONSE, gdy polecenie kończy się bez odpowiedzi; RESPONSE_TOO_LARGE przy zbyt dużej odpowiedzi; OUT_OF_MEMORY przy niewystarczającej pamięci. Odpowiedzi nigdy nie są cicho obcinane. Stop przerywa oczekujące wykonywanie; jego Promise nie jest kontynuowana w zniszczonym kontekście.

Przykład

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();

W danej chwili może oczekiwać tylko jedno polecenie wagi. Do wykonywania sekwencyjnego użyj await. Nowe żądanie otrzymuje BUSY, gdy inne polecenie oczekuje; nie ma ukrytej kolejki poleceń. Dotyczy to również łączenia scale.cmd() z tare/zero/clearTare/setPresetTare. Anulowanie ani przekroczenie limitu czasu nie cofa już zmienionych ustawień. Spóźniona odpowiedź nie jest przypisywana do następnego żądania.

Funkcja zwraca jedną odpowiedź. SIR, SR, SXIR, RAS, RASI, CAL, RST, CWRESULTA i CWDEBUG to odrzucone przed wykonaniem, łącznie z poleceniami zawierającymi pole uwierzytelniające P=. Dozwolona jest treść wielowierszowa w jednej odpowiedzi, np. I0. Użyj timera i scale.read() do powtarzania pomiarów; scale.cmd() nie otwiera strumienia odpowiedzi.

Polecenie może zawierać obsługiwane parametry i dane uwierzytelniające CSCP; funkcja nie omija zabezpieczenia wagi. Postępuj zgodnie ze składnią CSCP, gdy chronione polecenie wymaga poświadczeń. Obsługuj ERRAUTH i ERRLOCK w zwróconym tekście. Polecenia instalacji aplikacji i inne kanały zarządzania nie należą do scale.cmd().

Sprawdź obsługę za pomocą app.capabilities().scaleOperations.includes("cmd"). Limity są publikowane jako limits.maxScaleCommandBytes, limits.maxScaleResponseBytes i limits.maxScaleCommandTimeoutMs. Dostępne od Neutron AppEngine 1.0.0; flagi features opisują dedykowane moduły. io.* opisano w osobnym rozdziale I/O. Ustawienia modułu i przechowywanie danych mają własne rozdziały oraz oddzielne API device i storage.

Tabela 15

Wywołanie

Wynik / zachowanie

scale.cmd("S")

Następny stabilny pomiar lub odpowiedź błędu CSCP, taka jak S I.

scale.cmd("SI")

Natychmiastowa odpowiedź z bieżącą masą.

scale.cmd("RSD")

Dane i konfiguracja wagi jako ciąg znaków; działa bez dostępnego pomiaru masy.

scale.cmd("FT=?")

Bieżące ustawienie filtra, na przykład FT A 512.

scale.cmd("FT=512")

Zmienia i zapisuje filtr zgodnie z CSCP; sprawdź zwróconą odpowiedź.

scale.cmd("UNKNOWN")

Zwykle ES jako wynik spełnionego obiektu Promise, a nie odrzucenie JavaScript.

scale.cmd("SIR")

Odrzucenie UNSUPPORTED_COMMAND; nie rozpoczyna się ciągły strumień.

7.7 Błędy modułu wagi

Tabela 16

Kod

Znaczenie dla wagi

NO_MEASUREMENT

Operacja wagi bez prawidłowego pomiaru lub dostępnej wagi.

OUT_OF_RANGE

Zadana tara przekracza nośność.

PERMISSION_DENIED

Polecenie wagi odrzucone przez ochronę lub autoryzację.

SCALE_REJECTED

Waga odrzuciła operację; sprawdź komunikat i warunki pracy wagi.

7.8 Okresowe rejestrowanie masy

Samodzielny plik . js niewymagający TCP. Rejestruje prawidłowy pomiar raz na sekundę. Aby go zatrzymać, użyj Stop w menedżerze aplikacji.

// 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. Wejścia i wyjścia cyfrowe

Moduł io monitoruje sześć wejść i sześć wyjść, konfiguruje ich funkcje, bezpośrednio steruje przejętymi wyjściami i odczytuje liczniki wejść. Indeksy zawsze wynoszą 1–6. Wszystkie funkcje, właściwości i zdarzenia w tym rozdziale są dostępne od Neutron AppEngine 1.0.0. Obsługa API: app.capabilities().features.io; dostępność fizycznego I/O: app.capabilities().io.available.

Odczyt stanu i obserwowanie zdarzeń nie wymagają przejęcia zasobu. Możesz obserwować wyjście sterowane przez funkcję systemową; przed bezpośrednim zapisem wyraźnie wyłącz jego funkcję i przejmij je. Moduł korzysta ze wspólnego przetwarzania I/O urządzenia, dlatego te same zasady prawa do sterowania obowiązują także w innych interfejsach.

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

Dostępne od: Neutron AppEngine 1.0.0
const input = io.input(1);
const output = io.output(1);
Cel. Uzyskanie obiektu fizycznego wejścia lub wyjścia.
Opis. Powtórne wywołania dla tego samego pinu zwracają ten sam obiekt. Nie zmienia konfiguracji, nie rejestruje zdarzeń ani nie przełącza wyjścia.

Parametry

Tabela 17

Parametr

Typ / wymaganie

Opis

index

liczba całkowita / wymagane

1..6. Ciągi znaków, zero, wartości ułamkowe i indeksy powyżej 6 są odrzucane.

Wynik

Obiekt wejścia lub wyjścia. Oba obsługują read, configure, on, once i off. Wyjścia dodają claim, write i release; wejścia dodają counter i resetCounter.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowym indeksie. Obiekt można uzyskać bez płytki I/O; sprawdź read(). available.

Przykład

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

input.read() / output.read()

Dostępne od: Neutron AppEngine 1.0.0
const inputState = io.input(1).read();
const outputState = io.output(1).read();
Cel. Synchroniczny odczyt najnowszej migawki stanu i konfiguracji.
Opis. Odczyt nie wymaga przejęcia i nie emituje zdarzenia change. Migawka jest odświeżana przez wspólne przetwarzanie urządzenia i przy zmianach; read nie wykonuje dodatkowego fizycznego próbkowania. Po pomyślnym await configure/write migawka zawiera wyniki odpowiedniej operacji.

Parametry

Brak parametrów.

Wynik

Wejście: {index, available, value, functionId, function, mode, debounceMs, glitchUs, pull, counter}. Dane wyjściowe: {index, available, value, functionId, function, claimed}. Rodzaje i znaczenia są wymienione poniżej.

Błędy i szczególne uwagi

value wynosi null dla niedostępnego I/O i wejść w trybie disabled lub counter. counter jest typu BigInt tylko dla dostępnego wejścia licznikowego; inaczej null. Wyjściowe value oznacza zadany stan; potwierdzenie rzeczywistego przełączenia zewnętrznego stycznika lub urządzenia wymaga sygnału zwrotnego na wejściu.

Przykład

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

Pole od wersji Neutron AppEngine 1.0.0

Typ

Znaczenie

index

number

Numer pinu 1..6.

available

boolean

Urządzenie ma I/O.

value

boolean | null

true oznacza logiczne 1, false oznacza logiczne 0. Wartości wejściowe mają eliminowane drgania styków; null oznacza brak dostępnej wartości cyfrowej.

functionId / function

number / string

Istniejący numer funkcji i jej nazwa w API JavaScript. unknown oznacza nieobsługiwany zapisany numer.

mode

string / tylko wejście

disabled, digital lub counter.

debounceMs

number / tylko wejście

Czas potwierdzenia zmiany cyfrowej w milisekundach.

glitchUs

number / tylko wejście

Filtr krótkich impulsów licznika w mikrosekundach. Używany w trybie counter.

pull

string / tylko wejście

none, up lub down.

counter

bigint | null / tylko wejście

Najnowsza wartość licznika bez utraty precyzji dużych liczb całkowitych.

claimed

boolean / tylko wyjście

Wyjście jest przejęte przez aplikację użytkownika. Nie oznacza to, że jest włączone.

input.configure(options)

Dostępne od: Neutron AppEngine 1.0.0
await io.input(1).configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });
Cel. Skonfigurowanie i zapisanie trybu, funkcji i przetwarzania wybranego wejścia.
Opis. Zmienia podane właściwości i zachowuje pozostałe, jeśli są zgodne z wybranym trybem. Zapisuje i stosuje konfigurację bez restartu za pomocą istniejącej wspólnej ścieżki konfiguracji wejść. Tryby disabled i counter wyłączają funkcję systemową wejścia. Inicjalizacja nowego trybu nie emituje change i nie liczy początkowo aktywnego poziomu jako nowego naciśnięcia.

Parametry

Tabela 19

Parametr

Typ / wymaganie

Opis

options.mode

string / opcjonalne

disabled, digital lub counter. Pominięcie zachowuje bieżący tryb.

options.function

string | liczba całkowita / opcjonalne

Nazwa lub identyfikator z tabeli funkcji wejścia. Aktywna funkcja jest dozwolona tylko w trybie digital.

options.debounceMs

liczba całkowita / opcjonalne

0..60000 ms, tylko tryb digital. Istniejące ustawienie początkowe wynosi 20 ms; przy przełączaniu z innego trybu wyraźnie podaj żądaną wartość.

options.pull

string / opcjonalne

none, up lub down; tylko tryb digital.

options.glitchUs

liczba całkowita / opcjonalne

0..12 µs, tylko tryb counter. 0 wyłącza filtrowanie. Przy przełączaniu na counter bez podania filtra używany jest poprzedni filtr o wartości niezerowej lub 5 µs.

Wynik

Promise<InputState> z read() struktura. Ustawienia nie ulegają zmianie po zatrzymaniu i ponownym uruchomieniu urządzenia.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowych typach lub niezgodnych właściwościach, NOT_AVAILABLE, RESOURCE_IN_USE podczas aktywnego dozowania lub ważenia kontrolnego, CONFIGURE_FAILED przy błędzie zastosowania lub zapisu i BUSY. Tryb counter może być odrzucony, jeśli wybrane wejście nie ma dostępnego zasobu zliczania. Nie konfiguruj w szybkiej pętli okresowej.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
await io.output(1).configure({ function: "disabled" });
Cel. Wybranie i zapisanie funkcji systemowej wyjścia lub jej wyłączenie.
Opis. Zmiana funkcji nie przełącza bezpośrednio wyjścia. Aktywna funkcja steruje jego stanem zgodnie z regułami urządzenia. disabled umożliwia sterowanie ręczne i przejęcie przez JavaScript; nie wyłącza automatycznie bieżącego poziomu wyjściowego.

Parametry

Tabela 20

Parametr

Typ / wymaganie

Opis

options.function

string | liczba całkowita / wymagane

Nazwa lub identyfikator z tabeli funkcji wyjściowych.

Wynik

Promise<OutputState>. Ustawienie jest trwałe i obowiązuje bez ponownego uruchamiania.

Błędy i szczególne uwagi

RESOURCE_IN_USE, jeśli wyjście jest przejęte lub dozowanie/ważenie kontrolne jest aktywne. Wywołaj release(), następnie configure(). Inne kanały również nie mogą zmieniać funkcji przejętego wyjścia. Inne błędy: INVALID_ARGUMENT, NOT_AVAILABLE, CONFIGURE_FAILED, BUSY.

Przykład

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));

Nazwy i identyfikatory funkcji

Tabela 21

Identyfikator wejścia

Nazwa w API JavaScript od wersji Neutron AppEngine 1.0.0

Znaczenie

0

disabled

Brak funkcji systemowej

1

zero

Zerowanie

2

tare

Tarowanie

3

clearTare

Usunięcie tary

4

dosingStart

Rozpoczęcie dozowania

5

dosingPause

Wstrzymanie dozowania

6

dosingStop

Zatrzymanie dozowania

7

checkweigherSensor

Czujnik produktu

8

checkweigherStart

Rozpoczęcie ważenia kontrolnego

9

checkweigherPause

Wstrzymanie ważenia kontrolnego

10

checkweigherStop

Zatrzymanie ważenia kontrolnego

11

checkweigherReset

Resetowanie ważenia kontrolnego

12

checkweigherEnable

Włączenie CONS

13

checkweigherTrigger

Uruchomienie odrzutu

Tabela 22

Identyfikator wyjścia

Nazwa w API JavaScript od wersji Neutron AppEngine 1.0.0

Znaczenie

0

disabled

Brak funkcji systemowej

1

inTolerance

W granicach tolerancji

2

underTolerance

Poniżej tolerancji

3

overTolerance

Powyżej tolerancji

4

dosingActive

Dozowanie aktywne

5

dosingFast

Dozowanie zgrubne

6

dosingMedium

Dozowanie średnie

7

dosingFine

Dozowanie dokładne

8

dosingFly

Oczekiwanie na spływ materiału

9

dosingUnloading

Opróżnianie

10

dosingInTolerance

Dozowanie w granicach tolerancji

11

dosingOutOfTolerance

Dozowanie poza tolerancją

12

dosingEnd

Dozowanie zakończone

13

dosingError

Błąd dozowania

14

checkweigherBelt

Przenośnik

15

checkweigherLow

Odrzut z powodu zbyt małej masy

16

checkweigherHigh

Odrzut z powodu zbyt dużej masy

17

checkweigherGood

Impuls przy akceptowalnej masie

18

checkweigherCommon

Wspólny odrzut / błąd

19

checkweigherActive

Ważenie kontrolne aktywne

20

checkweigherAlarm

Alarm

21

checkweigherBuffer

Ostrzeżenie zasobnika

Funkcjonalność urządzenia określa rzeczywiste zasady tych funkcji systemowych. Zarejestrowanie change nie wyłącza funkcji: wejście przypisane do tare może uruchomić zarówno systemowe tarowanie, jak i zdarzenie JavaScript. Jeśli operację ma wykonywać JavaScript, najpierw ustaw function="disabled", aby uniknąć wykonania jej dwukrotnie. Listy identyfikatorów/nazw są także dostępne w capabilities.io.inputFunctions i outputFunctions.

output.claim(options?)

Dostępne od: Neutron AppEngine 1.0.0
await io.output(1).claim({ safeState: false });
Cel. Przejęcie wyłącznego ręcznego sterowania wyjściem na czas bieżącego uruchomienia aplikacji.
Opis. Dozwolone tylko przy function=disabled. Nie wyłącza automatycznie przypisanej funkcji systemowej ani nie zmienia bieżącego poziomu. Ta sama aplikacja może ponownie przejąć to samo wyjście, aby zaktualizować safeState.

Parametry

Tabela 23

Parametr

Typ / wymaganie

Opis

options.safeState

boolean / false

Stan wyjścia przy release() lub zakończeniu aplikacji. Dotyczy bieżącego uruchomienia; nie jest zapisywany jako stan po uruchomieniu urządzenia.

Wynik

Promise<OutputState> z claimed=true.

Błędy i szczególne uwagi

RESOURCE_IN_USE dla aktywnej funkcji systemowej lub innego właściciela zasobu. NOT_AVAILABLE, INVALID_ARGUMENT, BUSY. Przejęte wyjścia odrzucają zewnętrzne zapisy i zmiany funkcji, także przez inne kanały. Obserwowanie change pozostaje dozwolone.

Przykład

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

output.write(value)

Dostępne od: Neutron AppEngine 1.0.0
await io.output(1).write(true);
Cel. Ustawienie przejętego wyjścia w żądanym stanie logicznym.
Opis. Zapisuje przez wspólne przetwarzanie I/O. Rzeczywista zmiana emituje change; ponowny zapis tej samej wartości nie emituje zdarzenia. Stan nie jest zapisywany przy każdym przełączeniu. Promise i zdarzenie change to oddzielne powiadomienia; nie polegaj na ich wzajemnej kolejności.

Parametry

Tabela 24

Parametr

Typ / wymaganie

Opis

value

boolean / wymagane

true włącza, false wyłącza; 0, 1 i ciągi znaków są niedozwolone.

Wynik

Promise<OutputState> po zapisaniu wyjścia sterującego.

Błędy i szczególne uwagi

NOT_OWNER przed claim lub po release. NOT_AVAILABLE, INVALID_ARGUMENT, RESOURCE_IN_USE, BUSY. Potwierdzenie nie dowodzi fizycznego działania urządzenia zewnętrznego.

Przykład

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

output.release()

Dostępne od: Neutron AppEngine 1.0.0
await io.output(1).release();
Cel. Ustawienie wyjścia na safeState i zwolnienie prawa do sterowania.
Opis. Automatyczne zwolnienie następuje również podczas przetwarzania usługowego po Stop, nieobsłużonym błędzie lub zastąpieniu aplikacji. Poprzednia funkcja systemowa nie jest automatycznie przywracana: configure jest jawną, trwałą zmianą. Zwolnienie wyjścia nieprzejętego w bieżącym uruchomieniu nie ma skutku.

Parametry

Brak parametrów.

Wynik

Promise<undefined>. Jeśli safeState zmienia poziom, change jest emitowane, gdy aplikacja nadal działa.

Błędy i szczególne uwagi

NOT_OWNER dla innego właściciela, NOT_AVAILABLE, BUSY. Dostarczenie wydarzenia końcowego nie jest gwarantowane w momencie zakończenia aplikacji. Po resecie sprzętowym obowiązuje normalny stan wyjścia uruchamiania urządzenia (wyłączony), a nie poprzedni safeState. Nie zastępuje to sprzętowego obwodu zabezpieczającego.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
pin.on("change", callback);
pin.once("change", callback);
pin.off("change", callback);
Cel. Obserwowanie zmian wybranego wejścia lub wyjścia.
Opis. on obserwuje kolejne zmiany. once usuwa rejestrację przed pierwszą kolejną zmianą, którą może być włączenie lub wyłączenie. off usuwa rejestracje tej samej funkcji. Sama rejestracja nie emituje zdarzenia początkowego. Obsługiwane zdarzenie to change, z maksymalnie 32 funkcjami nasłuchującymi na pin.

Parametry

Tabela 25

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

Tylko "change".

callback

function / wymagane

Otrzymuje {index, value, previousValue, timeMs}. off wymaga tej samej referencji do funkcji.

Wynik

Zwraca ten sam obiekt pin do łączenia. Zdarzenia są niezależne od źródła zmiany: JavaScript, CSCP, inne interfejsy zarządzania lub funkcja systemu.

Błędy i szczególne uwagi

INVALID_ARGUMENT, QUOTA_EXCEEDED. Wejścia emitują zdarzenia po eliminacji drgań styków. Zdarzenia cyfrowe są niedostępne w trybie counter lub disabled. Wyjścia emitują zdarzenia tylko przy rzeczywistej zmianie zadanego poziomu. Wyjątek lub nieobsłużona odrzucona Promise w funkcji wywołania zwrotnego mogą zatrzymać aplikację według zasad środowiska wykonawczego. Bez funkcji nasłuchujących żadne zdarzenia tego pinu nie są wysyłane do JavaScript.

Przykład

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);
Tabela 26

Pole zdarzenia od wersji Neutron AppEngine 1.0.0

Typ

Znaczenie

index

integer

1..6 dla pinu z funkcją nasłuchującą.

value

boolean

Nowy stan: true oznacza logiczne 1, false oznacza logiczne 0.

previousValue

boolean

Poprzedni potwierdzony stan.

timeMs

number

Monotoniczny czas zmiany w milisekundach od uruchomienia urządzenia; może być ułamkowy. Nie jest datą, czasem UTC ani czasem dostarczenia wywołania zwrotnego. Dla wejść jest to czas potwierdzenia po eliminacji drgań styków.

Przykład pomiaru czasu aktywacji nie wymaga odpytywania. timeMs zaczyna się od nowa po restarcie urządzenia. Zmiany konfiguracji i początkowe próbki w nowym trybie nie są fizycznymi zdarzeniami zmiany.

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()

Dostępne od: Neutron AppEngine 1.0.0
const count = io.input(1).counter();
Cel. Zwrócenie najnowszej sumy wykrytych dodatnich impulsów wejścia licznikowego.
Opis. Zliczanie wykorzystuje istniejący mechanizm urządzenia bez wywoływania JavaScript dla każdego impulsu. BigInt zachowuje precyzję powyżej 2^53. Maksymalnie: 9223372036854775807; wartość nasyca się na tym limicie. Normalna trwałość licznika urządzeń pozostaje aktywna; nagła utrata zasilania może spowodować utratę impulsów, które nie zostały jeszcze zapisane.

Parametry

Brak parametrów.

Wynik

bigint. Ta sama wartość pojawia się w input.read().counter. Dla JSON użyj count.toString(); JSON.stringify nie może bezpośrednio serializować BigInt.

Błędy i szczególne uwagi

INVALID_MODE, jeśli wejście nie jest w trybie counter; NOT_AVAILABLE, jeśli brak I/O. To migawka, a nie gwarancja, że podczas odczytu nie nadszedł nowy impuls.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
await io.input(1).resetCounter();
Cel. Zresetowanie wybranego licznika i zapisanie nowej wartości bazowej.
Opis. Asynchroniczne; dozwolone tylko w trybie counter. Nie emituje cyfrowego zdarzenia change. Impulsy mogą pojawić się podczas resetowania lub bezpośrednio po nim.

Parametry

Brak parametrów.

Wynik

Promise<bigint> zawierający najnowszy zrzut licznika po wykonaniu. Nowe impulsy oznaczają, że może już nie być 0n.

Błędy i szczególne uwagi

INVALID_MODE, NOT_AVAILABLE, WRITE_FAILED, BUSY. Po zresetowaniu licznika w pamięci może wystąpić błąd zapisu; błąd nie cofa tego efektu. Nie resetuj w szybkiej pętli.

Przykład

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

Kompletny przykład: wejście steruje wyjściem

Przykład jawnie zapisuje konfigurację wejścia 1 i wyłącza funkcję systemową wyjścia 1. Następnie przejmuje wyjście z safeState=false, monitoruje wejście 1 i osobno obserwuje wyjście 2. Ogranicza nakładające się zapisy asynchroniczne i stosuje najnowszy stan wejścia po zakończeniu zapisu.

// 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.
});

Testowanie aplikacji I/O

Tabela 27

Test

Oczekiwany wynik

Stan początkowy

read zwraca wartość; rejestracja on/once nie emituje zdarzenia.

Włączanie i wyłączanie wejścia 1

Dwa zdarzenia change po eliminacji drgań styków, z przeciwnymi previousValue/value i odpowiednimi timeMs.

Krótkie drgania styków

Brak zduplikowanych zdarzeń dla jednej potwierdzonej zmiany.

Zewnętrzne SOT dla nieprzejętego wyjścia 2

Zdarzenie change JavaScript przy każdej rzeczywistej zmianie; powtórzenie tej samej wartości nie emituje żadnego.

Wyjście 2 sterowane przez funkcję systemową

JavaScript może obserwować zmiany bez przejęcia zasobu.

Zewnętrzne SOT/SOF lub zmiana funkcji dla przejętego wyjścia 1

Odrzucone bez nadpisania wyjścia aplikacji.

Stop lub błąd aplikacji przy włączonym przejętym wyjściu

Przejście do safeState i zwolnienie podczas przetwarzania usługowego.

Licznik i duże wartości

BigInt bez utraty precyzji; brak cyfrowego zdarzenia change dla każdego impulsu.

Niedostępne I/O lub nieprawidłowy indeks

available=false lub INVALID_ARGUMENT; brak dostępu do innego pinu.

9. Ustawienia modułu: RMD i SMD

Moduł device zarządza ustawieniami Neutron. Jest oddzielony od scale, który steruje ważeniem, oraz od danych aplikacji w storage. Wszystkie funkcje i właściwości w tym rozdziale są dostępne od Neutron AppEngine 1.0.0. Obsługa: app.capabilities().features.settings.

Zmiany korzystają z istniejącej walidacji i zapisu SMD. Uwzględniają zajęte interfejsy i przejęte wyjścia. Ustawienia możliwe do zastosowania podczas pracy korzystają z istniejących mechanizmów stosowania zmian na bieżąco. Pozostałe zgłaszają konieczność ponownego uruchomienia. API nigdy automatycznie nie uruchamia urządzenia ponownie.

device.cmd(command)

Dostępne od: Neutron AppEngine 1.0.0
const raw = await device.cmd("RMD");
const result = await device.cmd("SMD;S0B=19200;S0P=0;");
Cel. Wykonanie obsługiwanego polecenia zarządzania RMD lub SMD.
Opis. RMD zwraca tekstową listę ustawień i podstawowych stanów w istniejącym formacie. SMD używa tego samego wyniku co settings.write(). Inne polecenia zarządzania, takie jak REB, nie są tutaj obsługiwane. Nie powtarzaj SMD pomiędzy poszczególnymi ustawieniami.

Parametry

Tabela 28

Parametr

Typ / wymaganie

Opis

command

string / wymagane

RMD lub SMD;KEY=value;... . Maksymalnie 2048 bajtów UTF-8; bez znaków sterujących. SMD przyjmuje do 16 różnych kluczy.

Wynik

RMD: Promise<string>. SMD: Promise<SettingsWriteResult>, opisane poniżej.

Błędy i szczególne uwagi

INVALID_ARGUMENT, UNSUPPORTED_COMMAND, BUSY, NO_RESPONSE, RESPONSE_TOO_LARGE. RMD może przekroczyć 4096 bajtów; użyj settings.read dla wybranych kluczy lub settings.list do stronicowania. API nie odczytuje haseł, PIN-ów ani prywatnych danych certyfikatów. Zarządzaj certyfikatami przez istniejący proces ich dostarczania.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const values = await device.settings.read(["S0B", "S0P"]);
Cel. Odczyt wybranych zapisanych ustawień bez dużej odpowiedzi RMD.
Opis. Zwraca wartości jako ciągi znaków, w tym liczby. Brakujący klucz ma wartość null. Odczyt nie zmienia stanu urządzenia ani ustawień i nie gwarantuje zakończenia oczekującego zastosowania ustawień sprzętu.

Parametry

Tabela 29

Parametr

Typ / wymaganie

Opis

keys

string[] / wymagane

Klucze 1..16. Nazwy zawierają znaki 1..15: A–Z, 0–9 lub _.

Wynik

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

Błędy i szczególne uwagi

INVALID_ARGUMENT, PERMISSION_DENIED dla danych chronionych, RESPONSE_TOO_LARGE, BUSY. Nie twórz interfejsów API przy użyciu nieznanych kluczy; obsługiwane ustawienia są określone przez urządzenie i jego dokumentację.

Przykład

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?)

Dostępne od: Neutron AppEngine 1.0.0
const page = await device.settings.list({ cursor: null, limit: 16 });
Cel. Odczyt publicznie dostępnych zapisanych ustawień strona po stronie.
Opis. Klucze są sortowane rosnąco. cursor to ostatni klucz poprzedniej strony, który sam jest wykluczany. Ze względu na limit rozmiaru odpowiedź może zawierać mniej niż limit kluczy. Strony nie stanowią jednej migawki: ustawienia mogą zmieniać się pomiędzy wywołaniami.

Parametry

Tabela 30

Parametr

Typ / wymaganie

Opis

options.cursor

string | null / pominięte

nextCursor z poprzedniej odpowiedzi; null lub pominięcie rozpoczyna od początku.

options.limit

liczba całkowita / 16

1..32 kluczy na stronę; limit odpowiedzi pozostaje 4096 bajtów.

Wynik

Promise<{values:object, nextCursor:string|null}>. null oznacza koniec.

Błędy i szczególne uwagi

INVALID_ARGUMENT, RESPONSE_TOO_LARGE dla pojedynczej wartości ponadwymiarowej, BUSY. Lista zawiera zapisane klucze; dynamiczne stany RMD niekoniecznie są zapisanymi ustawieniami. Dane poufne zostały pominięte.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const result = await device.settings.write({ S0B: "19200", S0P: "0" });
Cel. Zapisanie grupy ustawień za pomocą istniejącego przetwarzania SMD.
Opis. Przed rozpoczęciem sprawdza ogólny format. Następnie błędy walidacji poszczególnych ustawień i błędy sprzętu podlegają istniejącym zasadom SMD. Grupa nie jest transakcją: jeden błąd nie cofa innych zapisanych wartości. Sprawdzaj result.ok i result.errors nawet po pomyślnym await.

Parametry

Tabela 31

Parametr

Typ / wymaganie

Opis

values

object / wymagane

Klucze 1..16. Wartościami mogą być ciągi znaków, wartości logiczne (0/1) lub liczby całkowite w −2147483648..4294967295. Podaj miejsca dziesiętne jako ciągi znaków w formacie ustawienia. Maksymalnie 1024 UTF-8 bajtów na wartość; bez średników, znaków kontrolnych i wartości specjalnych?. Całe żądanie musi mieścić się w 4096 bajtach.

Wynik

Promise<{ok:boolean, applied:string[], errors:object, rebootRequired:boolean, applyPending:boolean}>. applied wymienia klucze bez natychmiastowego błędu zapisu; nie jest niezależnym potwierdzeniem gotowości fizycznego interfejsu. Końcowy błąd zastosowania może mieć osobny klucz w errors.

Błędy i szczególne uwagi

Nieprawidłowy format jest odrzucany z INVALID_ARGUMENT lub MESSAGE_TOO_LARGE. Błędy poszczególnych ustawień zwracają ok=false i errors, np. CHECKWEIGHER_BUSY lub INVALID_OR_WRITE_FAILED. applyPending oznacza oczekujące zastosowanie interfejsu szeregowego; monitoruj stan interfejsu lub urządzenia. rebootRequired nigdy nie wyzwala automatycznego restartu. Nie zapisuj trwałych ustawień w szybkiej pętli pomiarowej.

Przykład

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");

Przykład odczytu ustawień

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. Pamięć i pliki

Moduł storage zapewnia trwałe przechowywanie danych aplikacji. Wszystkie funkcje w tym rozdziale są dostępne od Neutron AppEngine 1.0.0. Obsługa: app.capabilities().features.files. Pliki aplikacji są oddzielone od plików systemowych, certyfikatów i zainstalowanego kodu aplikacji. API nie ma dostępu do niczego poza tą przestrzenią danych.

Nazwy plików zawierają 1..64 znaków. Pierwszy musi być literą A–Z/a–z lub cyfrą; kolejne mogą także zawierać _, - lub kropkę. Kolejne kropki, ukośniki, podkatalogi i ścieżki bezwzględne są zabronione. Wielkość liter w nazwach ma znaczenie. Dane pozostają po Stop, restarcie i zwykłym zastąpieniu aplikacji. Zainstalowana aplikacja korzysta z jednej przestrzeni danych; nowa wersja lub inna aplikacja w urządzeniu może używać tych samych danych. Przywrócenie ustawień fabrycznych usuwa pliki użytkownika i lokalne bazy danych. Zwykłe usunięcie aplikacji poleceniem Delete ich nie usuwa.

Operacje są asynchroniczne i korzystają z kolejki usługowej o ograniczonej długości. Nie wczytuj całego dużego pliku do JavaScript, nie twórz nieograniczonych kolejek zapisu i nie wysyłaj wszystkich fragmentów bez await. Zatrzymanie nie cofa rozpoczętego zapisu; jego wynik może już nie dotrzeć do zatrzymanej aplikacji.

storage.info()

Dostępne od: Neutron AppEngine 1.0.0
const info = await storage.info();
Cel. Zgłoszenie wykorzystania, limitu i dostępnej przestrzeni.
Opis. Pliki i lokalne bazy danych współdzielą limit przestrzeni aplikacji. Rzeczywista dostępność zależy także od innych danych urządzenia i rezerwy systemowej. Kopie tymczasowe do atomowego zastępowania lub kompaktowania wymagają dodatkowego fizycznego miejsca.

Parametry

Brak parametrów.

Wynik

{quotaBytes, usedBytes, reserveBytes, freeBytes, availableBytes, maxFileBytes, databases:[{name,bytes}]}. usedBytes to łączny rozmiar logiczny zatwierdzonych plików i baz danych; freeBytes to całkowita ilość wolnego miejsca. availableBytes szacuje możliwy wzrost w ramach kwoty i rezerwy.

Błędy i szczególne uwagi

NOT_AVAILABLE lub błąd odczytu. Migawka, a nie rezerwacja do przyszłego zapisu. Dostępność jest sprawdzana ponownie podczas operacji.

Przykład

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

storage.write() / storage.writeText()

Dostępne od: Neutron AppEngine 1.0.0
await storage.write(name, data);
await storage.writeText(name, text);
Cel. Utworzenie pliku lub zastąpienie całej jego zawartości.
Opis. write przyjmuje string lub Uint8Array; writeText przyjmuje tylko string. Ciągi znaków są zapisywane jako UTF-8, a dane binarne jako dokładne bajty. Nie dodaje znaku nowego wiersza ani NUL. Pełne zastąpienie polega na zapisie tymczasowym, a następnie zastąpieniu zatwierdzonego pliku.

Parametry

Tabela 32

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Prawidłowa nazwa pliku.

data / text

string | Uint8Array / wymagane

0..4096 bajtów na wywołanie po kodowaniu UTF-8. writeText nie przyjmuje Uint8Array.

Wynik

Promise<undefined> po pomyślnym zapisaniu i potwierdzeniu zapisania. Pusty ładunek tworzy lub opróżnia plik.

Błędy i szczególne uwagi

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, NOT_AVAILABLE, BUSY. Nieudana wymiana powoduje zachowanie poprzedniego zatwierdzonego pliku. W przypadku większej zawartości napisz pierwszy fragment, a następnie dołącz go sekwencyjnie; ta wieloetapowa konstrukcja nie jest pojedynczą operacją atomową.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
await storage.append(name, data);
await storage.appendText(name, text);
Cel. Dopisanie danych do pliku, odpowiednie do dzienników.
Opis. Tworzy brakujący plik bez nadpisywania poprzedniej zawartości. Dopisywanie nie jest transakcją obejmującą wiele rekordów; błędy lub utrata zasilania mogą pozostawić ostatni dodatek niekompletny. Projektuj dzienniki tak, aby wykrywać takie niepełne rekordy końcowe.

Parametry

Tabela 33

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Prawidłowa nazwa pliku.

data / text

string | Uint8Array / wymagane

Najwyżej 4096 bajtów na wywołanie; appendText wymaga string. Maksymalny rozmiar pliku: 262144 bajtów.

Wynik

Promise<undefined>. Dostarczony sukces potwierdza zapis; brak odpowiedzi nie oznacza, że zapis się nie odbył.

Błędy i szczególne uwagi

MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, BUSY. Część dodatku może już istnieć po błędzie. Nie próbuj na ślepo ponawiać rekordów biznesowych bez unikalnego ID lub weryfikacji.

Przykład

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

storage.read() / storage.readText()

Dostępne od: Neutron AppEngine 1.0.0
const bytes = await storage.read(name, { offset: 0, length: 4096 });
const text = await storage.readText(name);
Cel. Odczyt bajtów binarnych lub tekstu UTF-8.
Opis. read zwraca Uint8Array; readText zwraca string. offset i length zawsze oznaczają bajty. Rozpoczęcie poza końcem pliku zwraca pusty wynik. Odczyt blisko końca może zwrócić mniej bajtów niż zażądano.

Parametry

Tabela 34

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Nazwa pliku.

options.offset

liczba całkowita / 0

0..262144 bajtów od początku.

options.length

liczba całkowita / opcjonalne

0..4096 bajtów. read domyślnie odczytuje do 4096 bajtów. Bez length readText wymaga, aby pozostały tekst zmieścił się w jednej odpowiedzi; w przeciwnym razie RESPONSE_TOO_LARGE.

Wynik

Promise<Uint8Array> lub Promise<string>. read zachowuje binarne NUL i wszystkie inne bajty.

Błędy i szczególne uwagi

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, RESPONSE_TOO_LARGE. Przestrzegaj granic znaków wielobajtowych podczas dzielenia tekstu UTF-8; niezależne dekodowanie dowolnych fragmentów może podzielić znak. readText nie jest parserem JSON ani JSONL; użyj JSON.parse w przypadku małych JSON dokumentów.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const page = await storage.list({ cursor: null, limit: 16 });
const info = await storage.stat("data.bin");
Cel. Wyświetlenie listy plików lub uzyskanie rozmiaru pliku.
Opis. list obejmuje tylko zwykłe pliki aplikacji, a nie wewnętrzne pliki baz danych. Nazwy są sortowane rosnąco; cursor wyklucza ostatnią już zwróconą nazwę. Bazy danych pojawiają się w storage.info().databases.

Parametry

Tabela 35

Parametr

Typ / wymaganie

Opis

options.cursor

string | null / pominięte

nextCursor z poprzedniej strony.

options.limit

liczba całkowita / 16

1..32 plików.

name dla stat

string / wymagane

Prawidłowa nazwa.

Wynik

list: {files:[{name,size}], nextCursor:string|null}. stat: {name,size}. Rozmiar jest w bajtach. null oznacza koniec listy.

Błędy i szczególne uwagi

NOT_FOUND dla stat, INVALID_ARGUMENT, READ_FAILED, OUT_OF_MEMORY. Strony nie są niezmienną migawką podczas współbieżnego dodawania lub usuwania.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const removed = await storage.remove("old.jsonl");
await storage.rename("measurements.jsonl", "archive.jsonl");
Cel. Usunięcie lub zmiana nazwy zwykłego pliku.
Opis. remove nie ma dostępu do wewnętrznych danych bazy. rename nie nadpisuje istniejącego celu; w razie potrzeby najpierw go jawnie usuń.

Parametry

Tabela 36

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Nazwa pliku źródłowego.

to dla rename

string / wymagane

Nowa prawidłowa nazwa bez istniejącego pliku.

Wynik

remove: Promise<boolean>, false przy braku pliku. rename: Promise<undefined>.

Błędy i szczególne uwagi

NOT_FOUND w przypadku brakującego źródła zmiany nazwy, ALREADY_EXISTS dla istniejącego miejsca docelowego, WRITE_FAILED, INVALID_ARGUMENT. Usunięcia nie można cofnąć.

Przykład

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

storage.findText(name, text, options?)

Dostępne od: Neutron AppEngine 1.0.0
const page = await storage.findText("measurements.jsonl", "ART-001", { offset: 0, limit: 16 });
Cel. Znalezienie dokładnego tekstu w zwykłym pliku bez wczytywania całej zawartości do JavaScript.
Opis. Sekwencyjne wyszukiwanie bajtów UTF-8 z rozróżnianiem wielkości liter, a nie wyrażenie regularne. Obsługuje nakładające się dopasowania. Każde wywołanie skanuje najwyżej 65536 bajtów lub zatrzymuje się przy limicie dopasowań. Do szybkiego wyszukiwania według klucza użyj lokalnej bazy danych zamiast wielokrotnie skanować pliki.

Parametry

Tabela 37

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Nazwa pliku.

text

string / wymagane

1..128 bajtów UTF-8, bez NUL.

options.offset

liczba całkowita / 0

Początkowe przesunięcie bajtowe, 0..262144.

options.limit

liczba całkowita / 16

1..64 dopasowań na stronę.

Wynik

{offsets:number[], nextOffset:number|null}. offsets oznaczają bezwzględne pozycje początkowe dopasowań w bajtach. Kontynuuj dokładnie od zwróconego nextOffset; zachowuje on możliwe częściowe dopasowania na granicach stron. null oznacza koniec pliku.

Błędy i szczególne uwagi

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, CANCELLED. Nie modyfikuj pliku podczas wyszukiwania wieloetapowego, jeśli potrzebujesz stabilnych wyników. Całkowity czas wyszukiwania sekwencyjnego jest proporcjonalny do rozmiaru pliku.

Przykład

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);

Dzienniki JSONL i rotacja

JSONL przechowuje jeden niezależny obiekt JSON w każdym wierszu, bez przecinków między wierszami i otaczających []. Umożliwia to dopisywanie pomiarów. Generuj każdy wiersz za pomocą JSON.stringify(record)+"\n". Po przerwaniu wykrywaj i osobno obsługuj niekompletny ostatni wiersz. JSONL nie zapewnia automatycznego indeksu ani automatycznego usuwania starych pomiarów.

// 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(); });

Wspólne limity pamięci

Tabela 38

Limit od wersji Neutron AppEngine 1.0.0

Wartość

Wspólny limit przestrzeni aplikacji

524288 bajtów łącznie dla plików i baz danych.

Rezerwa systemowa

131072 fizycznie wolne bajty przed dodatkowymi zapisami. Inne funkcje urządzenia mogą zmienić faktyczną dostępność.

Plik lub dziennik pojedynczej bazy danych

262144 bajtów.

Wywołanie odczytu / zapisu

4096 bajtów.

Zwykłe pliki

Najwyżej 64 nazw.

Kolejność

Żądania pamięci działają w jednej ograniczonej kolejce usługowej. Wiele wywołań nie stanowi transakcji.

Zakończenie aplikacji

Otwarte obiekty bazy danych są zwalniane; zatwierdzone dane pozostają.

Ustawienia fabryczne

Usuwa także pliki aplikacji i bazy danych.

11. Prosta lokalna baza rekordów

Lokalna baza danych przechowuje małe obiekty JSON z unikalnym kluczem, takim jak kod produktu, kod receptury lub identyfikator rekordu biznesowego. Wszystkie funkcje w tym rozdziale są dostępne od Neutron AppEngine 1.0.0. Obsługa: app.capabilities().features.records. Dane współdzielą przestrzeń i limit z plikami, ale wewnętrzne pliki bazy danych są oddzielone od zwykłego API plików.

Otwarcie weryfikuje dziennik rekordów i buduje posortowany indeks kluczy. get używa indeksu i bezpośredniego przesunięcia rekordu bez skanowania całej bazy. Otwieranie i kompaktowanie skanują dane i mogą trwać dłużej; otwórz raz przy uruchamianiu i ponownie używaj obiektu. Obsługiwany jest jeden indeksowany klucz na bazę danych. Nie ma SQL, relacji, automatycznego indeksowania dodatkowych pól ani transakcji obejmujących wiele rekordów.

storage.openRecords(name, options?)

Dostępne od: Neutron AppEngine 1.0.0
const articles = await storage.openRecords("articles", { key: "code" });
Cel. Utworzenie lub otwarcie bazy danych i przygotowanie jej indeksu.
Opis. Nazwa bazy danych i nazwa pola klucza są trwale wiązane podczas tworzenia. Przy ponownym otwieraniu użyj tej samej nazwy pola klucza. Otwarcie już otwartej nazwy jest odrzucane; ponownie użyj zwróconego obiektu. Obiekty są ważne tylko podczas bieżącego uruchomienia aplikacji.

Parametry

Tabela 39

Parametr

Typ / wymaganie

Opis

name

string / wymagane

1..32 znaków zgodnie z zasadami nazw plików.

options.key

string / "id"

Nazwa pola obiektu najwyższego poziomu. 1..32 ASCII znaki: najpierw litera lub _, potem także cyfry. Każdy rekord musi zawierać to pole w postaci niepustego ciągu znaków.

Wynik

Promise<RecordStore> z właściwościami name i key oraz metodami put/get/delete/list/stat/compact/close.

Błędy i szczególne uwagi

SCHEMA_MISMATCH dla innego kluczowego pola w istniejąca baza danych; ALREADY_OPEN; QUOTA_EXCEEDED; NO_SPACE; CORRUPT; CANCELLED; OUT_OF_MEMORY. Co najwyżej 8 trwałe bazy danych i 2 są otwarte jednocześnie. Niekompletny zapis końcowy jest usuwany po otwarciu; błąd integralności całego rekordu uniemożliwia otwarcie zamiast cichego usunięcia danych.

Przykład

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

records.put(record)

Dostępne od: Neutron AppEngine 1.0.0
await articles.put({ code: "ART-001", name: "Flour", target: 25 });
Cel. Wstawienie obiektu lub pełne zastąpienie rekordu z tym samym kluczem.
Opis. put zastępuje cały obiekt, a nie poszczególne pola. Dane są dopisywane do dziennika, a zatwierdzony rekord aktualizuje indeks. Wielkość liter w kluczach ma znaczenie. Wiele kolejnych wywołań put nie stanowi jednej transakcji.

Parametry

Tabela 40

Parametr

Typ / wymaganie

Opis

record

object / wymagane

JSON-obiekt nadający się do serializacji, co najwyżej 2048 UTF-8 bajtów po JSON.stringify i co najwyżej 16 zagnieżdżonych poziomów obiektów/tablicy. Pole klucza musi być ciągiem bajtów 1..64 UTF-8 bez znaków kontrolnych. Jawnie przekonwertuj identyfikatory numeryczne za pomocą String.

Wynik

Promise<object> zawierająca zapisany obiekt JSON.

Błędy i szczególne uwagi

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, CLOSED, CORRUPT. BigInt i odwołania cykliczne nie mogą być serializowane jako JSON. Błąd zatwierdzenia może pozostawić wynik zapisu niepewny; otwórz ponownie i sprawdź get przed ponowieniem. Nie rejestruj bez ograniczeń każdego impulsu.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const article = await articles.get("ART-001");
Cel. Szybkie pobranie najnowszego zatwierdzonego rekordu według unikalnego klucza.
Opis. Korzysta z posortowanego indeksu: wyszukanie klucza wymaga logarytmicznej liczby porównań i odczytania wybranego rekordu. Nie skanuje wszystkich obiektów. Zwraca nowy obiekt; jego zmiana w JavaScript sama w sobie nie zmienia bazy danych.

Parametry

Tabela 41

Parametr

Typ / wymaganie

Opis

key

string / wymagane

Dokładny klucz, 1..64 bajtów UTF-8, bez znaków sterujących.

Wynik

Promise<object|null>. null oznacza brak klucza.

Błędy i szczególne uwagi

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT. Pozostałe pola nie są indeksowane. Nie traktuj identyfikatorów ciągów jako liczb: "001" i "1" to odrębne klucze.

Przykład

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)

Dostępne od: Neutron AppEngine 1.0.0
const deleted = await articles.delete("ART-001");
Cel. Usunięcie rekordu z aktywnej listy bazy danych.
Opis. Zwykle dopisuje zatwierdzony rekord usunięcia; stare dane mogą pozostać do kompaktowania. Usunięcie nie oznacza bezpiecznego wymazania nośnika fizycznego. Usunięcie nieistniejącego klucza jest dozwolone.

Parametry

Tabela 42

Parametr

Typ / wymaganie

Opis

key

string / wymagane

Klucz zgodny z tymi samymi zasadami co get.

Wynik

Promise<boolean>: true, jeśli rekord istniał, w przeciwnym razie false.

Błędy i szczególne uwagi

INVALID_ARGUMENT, CLOSED, NO_SPACE, WRITE_FAILED, CORRUPT. Przy limicie dziennika usunięcie może wyzwolić kompaktowanie wymagające miejsca tymczasowego.

Przykład

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

records.list(options?)

Dostępne od: Neutron AppEngine 1.0.0
const page = await articles.list({ cursor: null, limit: 16 });
Cel. Odczyt aktywnych rekordów w kolejności kluczy, strona po stronie.
Opis. Rekordy są uporządkowane według kolejności bajtów kluczy. cursor wyklucza ostatni klucz poprzedniej strony. Limity rozmiaru odpowiedzi mogą skrócić stronę poniżej limit. Dla pól bez indeksu skanuj strony i filtruj w JavaScript; nie jest to szybkie wyszukiwanie indeksowane.

Parametry

Tabela 43

Parametr

Typ / wymaganie

Opis

options.cursor

string | null / pominięte

Zwrócone nextCursor z poprzedniej strony.

options.limit

liczba całkowita / 16

1..32 rekordów, ograniczonych również rozmiarami obiektów i odpowiedzi.

Wynik

{records:object[], nextCursor:string|null}. null oznacza koniec. Zmiana bazy danych między stronami oznacza, że wyniki nie są niezmienną migawką.

Błędy i szczególne uwagi

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT, OUT_OF_MEMORY. Unikaj gromadzenia każdej strony w jednej dużej tablicy, gdy potrzebny jest tylko jeden wynik.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const status = await articles.stat();
Cel. Odczyt liczby aktywnych rekordów, rozmiaru dziennika i pola klucza.
Opis. Rozmiar dziennika obejmuje zastąpione rekordy i usunięcia, a nie tylko aktualnie aktywne obiekty.

Parametry

Brak parametrów.

Wynik

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

Błędy i szczególne uwagi

CLOSED lub CORRUPT. Co najwyżej 2048 aktywne rekordy na bazę danych; limity rozmiaru i przydział współdzielony mogą zmniejszyć liczbę osiągalną.

Przykład

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

records.compact()

Dostępne od: Neutron AppEngine 1.0.0
await articles.compact();
Cel. Usunięcie starych wersji i zapisów usunięcia z dziennika w celu odzyskania miejsca.
Opis. Kopiuje tylko aktywne rekordy do pliku tymczasowego, weryfikuje go i zatwierdza, a następnie zastępuje starą bazę. Przerwanie zachowuje starą albo nową zatwierdzoną bazę danych. put lub delete mogą także uruchomić kompaktowanie, gdy dziennik osiągnie 262144 bajtów.

Parametry

Brak parametrów.

Wynik

Promise<undefined>. Aktywne klucze i wartości pozostają niezmienione.

Błędy i szczególne uwagi

NO_SPACE dla kopii tymczasowej, WRITE_FAILED, READ_FAILED, CANCELLED, CORRUPT, OUT_OF_MEMORY. Może trwać dłużej i zajmować kolejkę usługi pamięci; nie uruchamiaj po każdym pomiarze. Po QUOTA_EXCEEDED wspólnego limitu jawne kompaktowanie może usunąć nieaktualną zawartość przed ponowną próbą zapisu.

Przykład

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

records.close()

Dostępne od: Neutron AppEngine 1.0.0
await articles.close();
Cel. Zwolnienie otwartego obiektu i indeksu z zachowaniem danych.
Opis. Kolejne metody obiektu zwracają CLOSED. Powtórzenie close jest nieszkodliwe. W razie potrzeby otwórz ponownie przy użyciu tej samej nazwy bazy i pola klucza. Zakończenie aplikacji automatycznie zwalnia jej otwarte obiekty.

Parametry

Brak parametrów.

Wynik

Promise<undefined>.

Błędy i szczególne uwagi

BUSY, jeśli kolejka jest pełna. Operacje oczekujące w kolejce przed zamknięciem mogą zakończyć się jako pierwsze; używanie zamkniętego obiektu jest odrzucane.

Przykład

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

storage.removeRecords(name)

Dostępne od: Neutron AppEngine 1.0.0
const removed = await storage.removeRecords("articles");
Cel. Usunięcie całej lokalnej bazy danych i jej schematu.
Opis. Baza danych musi być zamknięta. Nazwy znajdziesz w storage.info().databases. Po usunięciu ta sama nazwa może zostać utworzona z innym polem klucza.

Parametry

Tabela 44

Parametr

Typ / wymaganie

Opis

name

string / wymagane

Nazwa bazy danych, 1..32 znaków.

Wynik

Promise<boolean>: true, jeśli istniał, w przeciwnym razie false.

Błędy i szczególne uwagi

RESOURCE_IN_USE dla otwartej bazy danych, INVALID_ARGUMENT, WRITE_FAILED. Nie można cofnąć usunięcia całej bazy danych.

Przykład

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

Kompletny przykład lokalnej bazy produktów

// 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();
});

Testowanie trwałości danych i odzyskiwania

Tabela 45

Test

Oczekiwany wynik

put dwa razy dla tego samego kodu

get zwraca najnowszą pełną wersję; count nie zwiększa się.

Stop, nowe Run lub zwykły restart

Ta sama nazwa i klucz otwierają zapisane dane; indeks jest odbudowywany.

Utrata zasilania podczas dopisywania

W pełni zatwierdzone rekordy pozostają; niekompletny ostatni rekord jest odrzucany przy otwieraniu. Wynik ostatniej niepotwierdzonej operacji może być niepewny.

Błąd integralności w kompletnym rekordzie

CORRUPT; cała baza danych nie jest automatycznie usuwana.

compact i ponowne otwarcie

Aktywne rekordy pozostają bez zmian; dziennik zmniejsza się, jeśli istniały stare wersje.

Osiągnięcie limitu przestrzeni

QUOTA_EXCEEDED lub NO_SPACE bez nieograniczonego przyrostu danych.

Ustawienia fabryczne

Pliki użytkownika i bazy danych są usuwane.

Dostęp do zamkniętego obiektu lub obiektu z poprzedniego uruchomienia

CLOSED lub odrzucenie nieaktualnego żądania.

12. Moduły komunikacyjne

Moduły komunikacyjne są oddzielone od modułu wykonawczego, modułu wagowego i zarządzania aplikacją. Każdy z nich ma swoje własne wymagania, funkcje, zdarzenia, błędy i ograniczenia. Aplikacje bez modułów komunikacyjnych mogą normalnie korzystać ze środowiska wykonawczego, diagnostyki, timerów i wagi.

Tabela 46

Moduł

Obsługa w Neutron AppEngine 1.0.0

Rozdział

TCP

Wdrożone; features.tcp=true

RS-232 / RS-485

Wdrożone; features.serial=true

MQTT

Wdrożone; features.mqtt=true

HTTP / REST

Wdrożone; features.http=true

WebSocket

Wdrożone; features.websocket=true

Przesyłanie aplikacji przez MQTT, HTTP lub BLE jest operacją zarządzania. Nie włącza tego protokołu w kodzie użytkownika. Procedury zarządzania opisano w rozdziałach Instalacja i Protokół APP.

13. Komunikacja TCP

configuredMode: 0 disabled, 1 server, 2 client, 3 both. Przykładowa wartość 1 służy ilustracji. maxLineBytes to maksymalny konfigurowalny limit; parser domyślnie używa 1024 bajtów.

Moduł TCP konfiguruje istniejący serwer i klienta, przejmuje ich strumienie dla własnego protokołu, wysyła dane i zgłasza zdarzenia połączenia. Tryby: disabled, server, client, both. W trybie both istnieje jeden serwer z jednym aktywnym urządzeniem partnerskim i jedno wychodzące połączenie klienta. API nie otwiera dowolnej liczby gniazd i nie obsługuje TLS ani nazw DNS; client.host musi być IPv4. Wszystkie funkcje i zdarzenia w tym rozdziale są dostępne od Neutron AppEngine 1.0.0.

Przed konfiguracją sieci lub przejęciem wyłącz systemowy protokół ważenia na I_TCP oraz mosty TCP–MQTT i TCP–RS-232/RS-485; w przeciwnym razie RESOURCE_IN_USE. Konfiguracja sieci i przejęcie są oddzielne: configure zapisuje i stosuje ustawienia; claim przekierowuje dane do aplikacji. Po pomyślnym configure użyj await tcp.claim().

13.1 tcp.configure()

Dostępne od: Neutron AppEngine 1.0.0
const status = await tcp.configure(options);
Cel. Konfiguracja ról TCP, parametrów sieci i wyznaczania granic wierszy tekstu.
Opis. Pominięte pola pozostają bez zmian. Ustawienia sieciowe są trwale zapisywane przez istniejące atrybuty modułu i stosowane bez restartu urządzenia. Zmieniona rola inicjalizuje się ponownie, podczas gdy druga zachowuje połączenie. Identyczne wartości nie przerywają prawidłowych połączeń. Zmiany exclusive wpływają na nowe połączenia bez rozłączania bieżącego partnera. Promise potwierdza zastosowanie ustawień, a nie połączenie z systemem zdalnym. Bez sieci ustawienia pozostają zapisane, a rola pozostaje w waitingNetwork. Monitoruj state/status pod kątem błędów połączenia. Lokalne ustawienia wierszy są stosowane po sukcesie i odrzucają niepełne wiersze. Podanie tylko delimiter/maxLineBytes stosuje je natychmiast dla zgodności, ale nadal zwraca Promise.

Parametry

Tabela 47

Parametr

Typ / wymaganie

Opis

options

object / wymagane

Obiekt z opcjonalnymi polami; nieznane pola są odrzucane.

options.mode

string / opcjonalne

disabled, server, client lub both. CTY: 0, 1, 2, 3. Disabled zatrzymuje obie role i zwalnia prawo do sterowania.

options.server

object / opcjonalnie

Konfiguracja serwera: port i exclusive.

options.server.port

liczba całkowita / opcjonalne

1–65535; istniejący atrybut S0C. S0P konfiguruje port szeregowy, a nie TCP.

options.server.exclusive

boolean / opcjonalnie

S0M: true=1, false=0. Wartość aktywna odrzuca nowe urządzenia partnerskie, gdy bieżące jest połączone; false pozwala zastąpić je nowym.

options.client

object / opcjonalnie

Konfiguracja połączenia wychodzącego: host i port.

options.client.host

string / opcjonalne

Adres IPv4 serwera zdalnego, na przykład 192.168.50.100. SIP atrybut; brak zer wiodących w oktetach. 0.0.0.0 i 255.255.255.255 są zabronione.

options.client.port

liczba całkowita / opcjonalne

1–65535; Atrybut SPO.

options.delimiter

string / domyślny CRLF

1–8 ASCII bajtów. Dotyczy tylko analizatora składni bieżącej aplikacji; nie zapisano w atrybutach.

options.maxLineBytes

integer / domyślny 1024

1–4096 bajty treści z wyłączeniem ogranicznika. Tylko bieżąca aplikacja.

Wynik

Promise<object> z migawką tcp.status(). Ustawienia aktywnej roli muszą być kompletne także przy zmianie tylko części obiektu. Aktualizacja częściowa wystarcza przy istniejącej prawidłowej konfiguracji. Zmiany SMD przez BLE, MQTT, HTTP lub device.settings.write korzystają z tego samego mechanizmu zastosowania.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowych lub niekompletnych aktywnych ustawieniach; walidacja argumentów JavaScript zgłasza wyjątek synchronicznie. Żądania sieciowe mogą zostać odrzucone z RESOURCE_IN_USE, BUSY, WRITE_FAILED, CONFIGURE_FAILED lub OUT_OF_MEMORY. Po błędzie zapisu niektóre ustawienia mogą już być zapisane; błędy startu serwera zachowują ustawienia i ponawiają start. Sprawdź status i usuń przyczynę. CONFIG_CHANGED przerywa oczekujące zapisy zmienionej roli. Zbyt długi wiersz powoduje MESSAGE_TOO_LARGE przed funkcją wywołania zwrotnego line i zatrzymuje aplikację; try/catch wewnątrz tej funkcji nie może tego przechwycić.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const result = await tcp.claim();
Cel. Przejęcie istniejącego kanału TCP dla własnego protokołu.
Opis. Żąda przekazania istniejących strumieni TCP aplikacji użytkownika. Zarejestruj funkcje wywołania zwrotnego przed przejęciem. Operacja nie gwarantuje, że zdalne urządzenie jest połączone.

Parametry

Brak parametrów.

Wynik

Promise<string>, "claimed" przy sukcesie. Zdarzenia danych i wysyłanie stają się dostępne po połączeniu. Diagnostyczne zdarzenia connection/state są dostępne bez przejęcia; rejestruj funkcje nasłuchujące przed configure/claim.

Błędy i szczególne uwagi

NOT_CONFIGURED przy wyłączonym/nieprawidłowym trybie TCP, RESOURCE_IN_USE przy konfliktach protokołu systemowego lub mostu; także BUSY i OUT_OF_MEMORY.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const result = await tcp.release();
Cel. Zwrócenie przejętego interfejsu TCP do firmware.
Opis. Zamyka przejęte połączenia serwera/klienta, zwalnia prawo do sterowania i odrzuca niepełne wiersze. Funkcje nasłuchujące JavaScript i timery pozostają. Skonfigurowana usługa nadal jest dostępna; klient systemowy może połączyć się ponownie.

Parametry

Brak parametrów.

Wynik

Promise<string>, "released" sukcesu. Aplikacja nadal działa.

Błędy i szczególne uwagi

Wspólne błędy BUSY i OUT_OF_MEMORY. Anuluj timery wysyłania i obsłuż oczekujące zapisy przed zwolnieniem.

Przykład

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

13.4 tcp.write()

Dostępne od: Neutron AppEngine 1.0.0
const bytesWritten = await tcp.write(data, { connectionId });
Cel. Wysyłanie tekstu lub danych binarnych przez przejęte połączenie.
Opis. Koduje ciągi znaków jako UTF-8 i wysyła Uint8Array jako bajty. Nie dodaje CRLF ani innego ogranicznika. Wysyłanie jest asynchroniczne; przesłane zapisy w jednym połączeniu zachowują kolejność, ale asynchroniczna logika użytkownika może zmienić kolejność przesyłania.

Parametry

Tabela 48

Parametr

Typ / wymaganie

Opis

data

string lub Uint8Array / wymagane

Najwyżej 4096 bajtów na wywołanie. Limity ciągów znaków obowiązują po kodowaniu UTF-8.

options

object / opcjonalne, domyślnie {}

Opcje wysyłania.

options.connectionId

liczba całkowita / opcjonalne

0 lub pominięte: wybierz jedyną połączoną rolę TCP. W przypadku wielu połączonych ról użyj ID z wydarzenia; zakres 0–4 294 967 295.

Wynik

Promise<number> z bajtami przyjętymi do transmisji TCP. Nie potwierdza zdalnego odbioru ani przetwarzania. W razie potrzeby zdefiniuj potwierdzenia w swoim protokole.

Błędy i szczególne uwagi

Odrzuca z INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, NOT_CONNECTED, CONFIG_CHANGED, BUSY, OUT_OF_MEMORY lub TIMEOUT. Limit oczekiwania na zapis wynosi około 3 s. Niektóre dane mogły zostać już przesłane po wystąpieniu błędu; nie ponawiaj na ślepo poleceń nieidempotentnych. Aktywny błąd zapisu/przekroczenie limitu czasu może spowodować zamknięcie połączenia. Nieprawidłowe użycie argumentu JavaScript może również spowodować wyrzucenie TypeError.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
tcp.on(eventName, callback);
Cel. Zarejestrowanie funkcji nasłuchującej zdarzeń TCP.
Opis. Wywołuje funkcję wywołania zwrotnego dla pasujących zdarzeń aż do off lub zakończenia aplikacji. Ta sama funkcja może rejestrować się wielokrotnie; każda rejestracja wlicza się do limitu.

Parametry

Tabela 49

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

Tylko "data", "line", "connection" lub "state".

callback

function / wymagane

Funkcja otrzymująca jeden obiekt zdarzenia. Zachowaj tę samą referencję dla off.

Wynik

Obiekt tcp, umożliwiający łączenie rejestracji w łańcuch.

Błędy i szczególne uwagi

Synchroniczne INVALID_ARGUMENT przy nieznanym zdarzeniu lub wartości niebędącej funkcją. Łącznie najwyżej 32 funkcje nasłuchujące on/once; nadmiar powoduje QUOTA_EXCEEDED. Nieobsłużony wyjątek funkcji wywołania zwrotnego lub odrzucenie Promise zatrzymuje aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

13.6 tcp.once()

Dostępne od: Neutron AppEngine 1.0.0
tcp.once(eventName, callback);
Cel. Zarejestrowanie jednorazowej funkcji nasłuchującej.
Opis. Usuwa detektor przed wywołaniem go dla pierwszego pasującego zdarzenia. Pozostaje zarejestrowany, jeśli nie nadejdzie żadne wydarzenie.

Parametry

Tabela 50

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

Tylko "data", "line", "connection" lub "state".

callback

function / wymagane

Funkcja otrzymująca jeden obiekt zdarzenia. Zachowaj tę samą referencję dla off.

Wynik

Obiekt tcp, umożliwiający łączenie rejestracji w łańcuch.

Błędy i szczególne uwagi

Synchroniczne INVALID_ARGUMENT przy nieznanym zdarzeniu lub wartości niebędącej funkcją. Łącznie najwyżej 32 funkcje nasłuchujące on/once; nadmiar powoduje QUOTA_EXCEEDED. Nieobsłużony wyjątek funkcji wywołania zwrotnego lub odrzucenie Promise zatrzymuje aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

13.7 tcp.off()

Dostępne od: Neutron AppEngine 1.0.0
tcp.off(eventName, callback);
Cel. Usunięcie funkcji nasłuchującej.
Opis. Usuwa wszystkie rejestracje tego samego odniesienia do wywołania zwrotnego dla wybranego zdarzenia. Nie przerywa już rozpoczętego wywołania zwrotnego async. Nie przekazuj nowej anonimowej funkcji, aby usunąć istniejącego słuchacza.

Parametry

Tabela 51

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

Tylko "data", "line", "connection" lub "state".

callback

function / wymagane

Funkcja otrzymująca jeden obiekt zdarzenia. Zachowaj tę samą referencję dla off.

Wynik

Obiekt tcp, umożliwiający łączenie rejestracji w łańcuch.

Błędy i szczególne uwagi

Synchroniczne INVALID_ARGUMENT przy nieznanym zdarzeniu lub wartości niebędącej funkcją. Łącznie najwyżej 32 funkcje nasłuchujące on/once; nadmiar powoduje QUOTA_EXCEEDED. Nieobsłużony wyjątek funkcji wywołania zwrotnego lub odrzucenie Promise zatrzymuje aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

13.8 Struktura zdarzeń TCP

Tabela 52

Zdarzenie

Pola

Znaczenie

data

{ connectionId, data: Uint8Array }

Surowy fragment strumienia TCP. Jedno zdarzenie niekoniecznie jest jednym poleceniem lub pakietem sieciowym.

line

{ connectionId, line: string }

Kompletna zdekodowana linia UTF-8 bez ograniczników. Puste linie są dozwolone; białe znaki nie są przycinane automatycznie.

connection

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

Połączenie nawiązane lub utracone podczas działania aplikacji, niezależnie dla każdej roli. connectionId identyfikuje sesję; po ponownym podłączeniu użyj nowego ID.

connection.reason: CONNECTED w przypadku powodzenia, CONFIG_CHANGED po zmianie adresu/portu/roli, REPLACED w przypadku wymiany równorzędnego serwera, NETWORK_DOWN w przypadku utraty usług sieciowych, CONNECTION_LOST w przypadku wykrytej utraty połączenia, DISCONNECTED w przypadku normalnego zamknięcia, APP_STOPPED w przypadku zwolnienia po zakończeniu aplikacji, RESOURCE_IN_USE w przypadku konfliktów. Zdarzenia po zakończeniu aplikacji nie są dostarczane. timeMs to monotoniczny czas urządzenia w milisekundach, a nie data lub czas trwania połączenia. Zdalny port równorzędnego serwera jest zwykle tymczasowy, a nie port nasłuchujący serwera.

state zawiera role, state, connected, connectionId, port, revision, error i timeMs oraz właściwości roli z tcp.status(). Stany serwera: disabled, waitingNetwork, listening, error. Stany klienta: disabled, waitingNetwork, connecting, reconnecting, connected, error. Zwolnienie z powodu konfliktu może emitować {role:"all", state:"released", reason:"RESOURCE_IN_USE"}. Próby połączenia klienta nie blokują aplikacji ani pomiarów; każda trwa do około 3 s, a kolejna rozpoczyna się około 5 s po niepowodzeniu lub wykryciu rozłączenia. Nieudany start serwera jest ponawiany mniej więcej co 5 s. Wykrycie fizycznego rozłączenia nie jest natychmiastowe; zależy od ruchu i monitorowania połączenia.

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);
});
Rejestracja nie odtwarza historii zdarzeń. Przejęcie może powiadomić o już nawiązanym połączeniu. Zawsze odpowiadaj za pomocą event.connectionId; nigdy nie zapisuj go trwale ani nie wymyślaj identyfikatorów.
TCP jest strumieniem. WEIGHT?\r\n może być dostarczone w kilku porcjach, a kilka poleceń w jednej porcji. Parser zachowuje częściowe linie na połączenie, składając częściowe znaki UTF-8 przed dekodowaniem zdarzeń liniowych. Ograniczniki i niekompletne linie są odrzucane po rozłączeniu.

Przy funkcji nasłuchującej line wiersze są najpierw przygotowywane z fragmentu strumienia, następnie wyzwalane jest data, a potem poszczególne wywołania zwrotne line. Rejestracja obu daje dwa widoki tych samych danych; nie przetwarzaj poleceń dwukrotnie. Bez funkcji nasłuchującej line dane binarne nie są zbierane w buforze wierszy. Protokoły binarne muszą implementować własne limity długości i składanie wiadomości.

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 Błędy modułu TCP

Tabela 53

Kod

Znaczenie dla TCP

NOT_CONFIGURED

TCP nie jest skonfigurowany do pracy klient/serwer.

RESOURCE_IN_USE

Systemowy protokół ważenia TCP lub most koliduje z przejęciem.

NOT_OWNER

Aplikacja nie przejęła TCP lub wystąpił konflikt routingu.

NOT_CONNECTED

Żądana sesja TCP nie jest już połączona.

MESSAGE_TOO_LARGE

Zapis przekracza 4096 bajtów lub odebrana linia jest za długa. Wewnętrzny błąd linii powoduje zatrzymanie aplikacji.

13.10 Limity modułu TCP

Tabela 54

Zasób

Limit

Wiadomość TCP

Maksymalnie 4096 bajtów na zapis; odbierane strumienie można podzielić na mniejsze części.

Wiersze

Domyślnie 1024; konfigurowalne 1–4096 bajtów z wyłączeniem ogranicznika; ASCII długość ogranicznika 1–8 bajtów.

Funkcje nasłuchujące

Łącznie najwyżej 32 rejestracje on/once dla data, line, connection i state.

13.11 Własny protokół TCP z CONT / CCONT

Samodzielny przykład skonfigurowanego serwera lub klienta TCP bez konfliktującego routingu systemowego. Każda linia kończy się rzeczywistymi bajtami CR LF. Narzędzia zewnętrzne muszą wysyłać te bajty, a nie cztery dosłowne ukośniki odwrotne-r-ukośniki odwrotne-n. W źródle JavaScript "\r\n" reprezentuje prawidłowe bajty terminatora.

Tabela 55

Odebrane polecenie + CRLF

Odpowiedź + CRLF

WEIGHT?

net,gross,unit lub ERR,NO_MEASUREMENT

CONT

OK; następnie jeden pomiar na sekundę dla tego samego połączenia. Powtórzenie nie tworzy dodatkowego interwału.

CCONT

OK; anuluje przyszłe okresowe wysyłki na tym połączeniu. Rozpoczęty już zapis może zostać zakończony.

TARE / ZERO / CLEAR_TARE

OK po potwierdzonej operacji lub ERR,&lt; code&gt;.

PRESET_TARE 2.5

Ustawia tarę w aktualnie skonfigurowanej jednostce; zwraca OK lub ERR,&lt; code&gt;.

Inne polecenie

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();
});

Nasłuchiwanie połączenia usuwa interwał po rozłączeniu; okresowy błąd zapisu również go zatrzymuje. Flaga wysyłania zapobiega nakładaniu się okresowych zapisów na połączenie. W przykładzie nie zaimplementowano żadnego trwałego dziennika, potwierdzenia zdalnego przetwarzania ani identyfikatorów żądań. W razie potrzeby dodaj ograniczone identyfikatory, odpowiedzi i reguły ponawiania prób.

13.12 Zamykanie TCP i współbieżność

app.stop() zamyka przejęte połączenia TCP i zwalnia prawo do sterowania. Skonfigurowany serwer nadal jest dostępny, a klient może połączyć się ponownie zgodnie z logiką systemową. Użyj tcp.release(), aby zwrócić TCP bez zatrzymywania aplikacji. Wiele odebranych poleceń może przetwarzać się asynchronicznie z nakładaniem; aby zachować ścisłą kolejność, klient powinien czekać na odpowiedź lub należy zaimplementować kolejkę o ograniczonej długości. clearInterval nie anuluje już rozpoczętego zapisu.

13.13 Testowanie aplikacji TCP

Tabela 56

Test

Oczekiwany wynik

Polecenie TCP rozdzielone na odbiory

Funkcja wywołania zwrotnego line uruchamia się dopiero po pełnym ograniczniku.

CONT dwukrotnie, następnie dwukrotnie CCONT

Jeden interwał na połączenie; wielokrotne anulowanie jest nieszkodliwe.

Rozłączenie / ponowne połączenie

Stare interwały i identyfikatory nie są ponownie wykorzystywane; nowa sesja jest niezależna.

Powolny / nieudany zapis TCP

Brak nakładających się prac okresowych i nieograniczonych kolejek.

13.14 tcp.status()

Dostępne od: Neutron AppEngine 1.0.0
const status = tcp.status();
Cel. Odczyt bieżącej konfiguracji i stanu obu ról TCP.
Opis. Synchroniczna migawka z ostatniego cyklu usługowego. Nie otwiera połączeń, nie przejmuje interfejsu ani nie odczytuje strumienia danych. pending oznacza, że zapisane ustawienia czekają na zastosowanie w następnym cyklu usługowym. Stan połączenia zmienia się dalej po configure; użyj zdarzeń connection/state, aby kontynuować po nawiązaniu połączenia.

Parametry

Brak parametrów.

Wynik

Obiekt: mode (disabled/server/client/both), configuredMode (0/1/2/3), claimed, pending, server i client. Obie role zawierają state, connected, connectionId (0 przy rozłączeniu), port, revision i error. Server zawiera dodatkowo listening, exclusive, remoteAddress i remotePort; client zawiera host, remoteAddress i remotePort. Puste error oznacza brak zarejestrowanego błędu. revision zmienia się przy zmianach punktu końcowego/roli; nie jest licznikiem odebranych danych. Ta migawka informacyjna może zmienić się natychmiast po odczycie.

Błędy i szczególne uwagi

Brak żądania sieciowego. Połączona migawka nie gwarantuje powodzenia późniejszego zapisu; zawsze obsługuj odrzucenie zapisu.

Przykład

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

Konfiguracja i podstawowy WEIGHT? przykład protokołu dla obu ról: wybierz żądany tryb w konfiguracji i dostosuj adres/port. Odpowiedzi korzystają z odebranego zdarzenia connectionId, więc działają w przypadku połączonych obu ról.

// 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

Port jest dostępny dla aplikacji tylko wtedy, gdy jej funkcja systemowa jest wyłączona: S0E=0 dla RS-232 lub S1E=0 dla RS-485. Nie można go przypisać do protokołu ważenia systemu, Modbus, wyjścia debugowania lub przesyłania. claim() nie wyłącza automatycznie tych funkcji.

Moduł szeregowy udostępnia dwa niezależne obiekty: serial.rs232 i serial.rs485, z tym samym API. Aplikacja może zająć jeden lub oba porty. Nie jest wymagany żaden inny moduł komunikacyjny. Wszystkie funkcje i zdarzenia w tym rozdziale są dostępne w Neutron AppEngine 1.0.0.

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

14.1 port.claim()

Dostępne od: Neutron AppEngine 1.0.0
const result = await port.claim();
Cel. Wyłączne przejęcie wybranego portu szeregowego.
Opis. Sprawdza, czy port jest Disabled i wolny, a następnie przygotowuje go z użyciem zapisanych ustawień fizycznych. Czeka na pomyślną inicjalizację. Powtórzenie udanego claim jest dozwolone bez ponownej inicjalizacji niezmienionych ustawień.

Parametry

Brak parametrów.

Wynik

Promise<string>, "claimed" przy sukcesie. W razie potrzeby zarejestruj funkcje nasłuchujące przed przejęciem. Obecność urządzenia zdalnego nie jest sprawdzana.

Błędy i szczególne uwagi

RESOURCE_IN_USE przy włączonej funkcji systemowej lub innym konflikcie; BUSY przy współbieżnych operacjach sterowania; RECONFIGURE_FAILED, TIMEOUT lub OUT_OF_MEMORY. Nieprawidłowo skonfigurowany port nie jest po cichu przejmowany.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const result = await port.configure(options);
Cel. Konfiguracja prędkości transmisji, formatu znaków i lokalnej analizy wiadomości.
Opis. Asynchroniczne, dozwolone po claim(). Mapuje parametry fizyczne na istniejące ustawienia SMD, weryfikuje je i trwale zapisuje. Ponownie inicjalizuje port raz dla całego żądania; Promise zostaje spełniona po zastosowaniu. Pominięte ustawienia pozostają bez zmian. Ponowne zastosowanie identycznych, pomyślnie zastosowanych wartości pozwala uniknąć zbędnej reinicjalizacji.

Parametry

Tabela 57

Parametr

Typ / wymaganie

Opis

options

object / wymagane

Obiekt z opcjonalnymi polami poniżej. Nieznane pola są odrzucane.

baudRate

liczba całkowita / opcjonalne

300–1 000 000 bit/s. Mapuje do S0B lub S1B.

dataBits

liczba całkowita / opcjonalne

7 lub 8. Mapowanie S0I/S1I: 0 oznacza 7 bitów, 1 oznacza 8 bitów.

stopBits

liczba całkowita / opcjonalne

1 lub 2. Mapuje do S0S/S1S.

parity

string / opcjonalne

"none", "even" lub "odd". Mapowanie S0P/S1P: 0, 1 lub 2.

delimiter

string / opcjonalnie, domyślnie CRLF

1–8 ASCII znaków, tylko w przypadku składania zdarzenia liniowego w bieżącej aplikacji.

maxLineBytes

integer / opcjonalnie, domyślnie 1024

1–4096 bajty zawierające zawartość wiersza, z wyłączeniem ogranicznika. Tylko bieżąca aplikacja.

Wynik

Promise<string>, "configured" przy sukcesie. Ustawienia fizyczne pozostają po release(), Stop i restarcie. delimiter i maxLineBytes nie są zapisywane w SMD; dotyczą bieżącego parsera JavaScript.

Błędy i szczególne uwagi

INVALID_ARGUMENT, NOT_OWNER, RESOURCE_IN_USE, BUSY, SETTINGS_FAILED, RECONFIGURE_FAILED, CONFIG_CHANGED, TIMEOUT lub OUT_OF_MEMORY. Błąd zapisu może pozostawić część ustawień fizycznych zapisaną; błąd zastosowania nie oznacza, że ustawienia nie zostały zapisane. Usuń przyczynę i ponów konfigurację/przejęcie. Konfiguracja lokalnego parsera zmienia się dopiero po sukcesie. Jeśli inny kanał zmieni żądane ustawienia fizyczne przed potwierdzeniem, wywołanie zostanie odrzucone z CONFIG_CHANGED.

Przykład

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 Zmiany ustawień bez ponownego uruchamiania

Ta sama ścieżka aplikacji obsługuje żądania SMD ze wszystkich kanałów zarządzania. Zmiana szybkości transmisji, bitów danych, bitów stopu, parzystości lub funkcji portu nie wymaga ponownego uruchomienia Neutron. Terminatory systemowe, ustawienia dołączania terminatorów, adresy RS-485 i powiązane przypisania portów są również odświeżane. Drugi port inicjuje się ponownie tylko wtedy, gdy ma to wpływ.

Podczas przejścia nowe zapisy są tymczasowo odrzucane lub wstrzymywane. Wcześniej przekazane bajty są transmitowane do końca w ograniczonym czasie; niepełne ramki odbiorcze są odrzucane. Kończą się stare żądania ważenia, ciągłe wyjście systemowe i sesje portu objętego zmianą. Zmiany szybkości transmisji lub formatu mogą powodować utratę danych, dlatego wykonuj je podczas uzgodnionej przerwy w komunikacji. Brak zakończenia transmisji lub otwarcia nowej konfiguracji zgłasza RECONFIGURE_FAILED.

Jeśli zewnętrzne SMD przypisze inną funkcję systemową lub spowoduje konflikt podczas przejęcia przez JavaScript, przejęcie zostaje cofnięte. Aplikacja otrzymuje state z reason="RESOURCE_IN_USE" i claimed=false; nowe zapisy zwracają NOT_OWNER. Dozwolone zmiany ustawień fizycznych zachowują prawo do sterowania i emitują RECONFIGURED. Niepełne wiersze JavaScript są odrzucane; skonfigurowany ogranicznik JavaScript pozostaje.

Tabela 58

Sprawdzanie za pomocą RMD

Znaczenie

S0APPLY / S1APPLY

PENDING: oczekiwanie na zastosowanie; OK: konfiguracja zastosowana; ERROR: zastosowanie nie powiodło się.

S0JS / S1JS

1 oznacza przejęcie przez aplikację; 0 oznacza brak przejęcia przez JavaScript.

S0REV / S1REV

Licznik zastosowanych zmian stanu portu; nie jest trwałym identyfikatorem sesji.

S0STATE / S1STATE

Ostatni stan: READY, DISABLED, CLAIMED, RECONFIGURED, RELEASED, RESOURCE_IN_USE lub RECONFIGURE_FAILED.

Zwykła odpowiedź SMD potwierdza zapis; fizyczne zastosowanie następuje w kolejnym cyklu przetwarzania urządzenia. Do zewnętrznego potwierdzenia użyj pól RMD APPLY lub dzienników diagnostycznych. port.configure() już czeka na zastosowanie. Te pola RMD służą diagnostyce i nie są zapisywalnymi ustawieniami SMD. Powtórzenie identycznego SMD po błędzie ponawia zastosowanie; po sukcesie identyczne wartości nie otwierają portu ponownie.

14.4 port.write()

Dostępne od: Neutron AppEngine 1.0.0
const bytes = await port.write(data, { timeoutMs });
Cel. Asynchroniczne wysyłanie tekstu lub bajtów binarnych.
Opis. Koduje ciągi znaków jako UTF-8; wysyła Uint8Array bez zmian. Nie dodaje terminatora, adresu RS-485 ani sumy kontrolnej. Zapisuje na jednym porcie zgodnie z kolejnością żądań; ich Obietnice nie potwierdzają przetwarzania zdalnego.

Parametry

Tabela 59

Parametr

Typ / wymaganie

Opis

data

string lub Uint8Array / wymagane

Co najwyżej 4096 bajtów po kodowaniu UTF-8; dozwolone są puste zapisy.

options

object / opcjonalne, domyślnie {}

Opcje czekania.

options.timeoutMs

liczba całkowita / opcjonalne

1–180000 ms. Wartość domyślna jest obliczana na podstawie długości i szybkości transmisji z marginesem i minimum 3 s.

Wynik

Promise<number> z bajtami przyjętymi do transmisji. Użyj drain(), aby poczekać na zakończenie fizycznej transmisji.

Błędy i szczególne uwagi

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT lub OUT_OF_MEMORY. Niektóre bajty mogą już zostać wysłane po przerwaniu lub przekroczeniu limitu czasu. CONFIG_CHANGED oznacza zmianę konfiguracji w trakcie oczekiwania; pozostałe bajty starego żądania nie są wysyłane w ramach nowych ustawień.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
await port.drain({ timeoutMs });
Cel. Oczekiwanie na zakończenie fizycznej transmisji.
Opis. Oczekuje wcześniejszych zapisów na tym samym porcie, a następnie sprawdza, czy przesłane zostały oczekujące bajty. Środowisko wykonawcze przetwarza inne zdarzenia w trakcie oczekiwania.

Parametry

Tabela 60

Parametr

Typ / wymaganie

Opis

options

object / opcjonalne, domyślnie {}

Opcje czekania.

options.timeoutMs

integer / opcjonalnie, domyślnie 6000

1–60000 ms.

Wynik

Promise<undefined>. Nie czeka na zdalną odpowiedź ani nie potwierdza, że magistrala RS-485 używana przez inne urządzenia jest wolna.

Błędy i szczególne uwagi

INVALID_ARGUMENT, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT lub OUT_OF_MEMORY. Ustaw odpowiedni limit czasu komunikacji; jego upływ nie cofa przesłanych bajtów.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const result = await port.release();
Cel. Zwolnienie przejęcia wybranego portu przez aplikację.
Opis. Zatrzymuje nowe zapisy aplikacji, kończy przejście i zwalnia prawo do sterowania. Port nadal ustawiony systemowo na Disabled i nieużywany w inny sposób zostaje zamknięty. Trwale zapisane ustawienia fizyczne pozostają. Nie wyłącza funkcji systemowej, która w międzyczasie przejęła port.

Parametry

Brak parametrów.

Wynik

Promise<string>, "released" przy sukcesie. Powtarzanie jest dozwolone. Niepełne lokalnie odebrane dane są odrzucane; zarejestrowane funkcje wywołania zwrotnego i timery pozostają.

Błędy i szczególne uwagi

BUSY, RECONFIGURE_FAILED, TIMEOUT lub OUT_OF_MEMORY. Anuluj wysyłanie timerów przed zwolnieniem. Nie można wycofać już przesłanych bajtów. Zatrzymanie aplikacji automatycznie zwalnia oba porty.

Przykład

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

14.7 port.on()

Dostępne od: Neutron AppEngine 1.0.0
port.on(eventName, callback);
Cel. Zarejestrowanie funkcji nasłuchującej zdarzeń portu szeregowego.
Opis. Zdarzenia należą do wybranego portu. once usuwa rejestrację przed wywołaniem funkcji wywołania zwrotnego. off wymaga tej samej referencji do funkcji i nie przerywa już rozpoczętej funkcji async.

Parametry

Tabela 61

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

"data", "line" lub "state".

callback

function / wymagane

Funkcja odbierająca jeden obiekt zdarzenia.

Wynik

Wybrany obiekt portu; rejestrację słuchacza można połączyć w łańcuch.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowym zdarzeniu lub funkcji wywołania zwrotnego; QUOTA_EXCEEDED powyżej 32 funkcji nasłuchujących na port. Nieobsłużone wyjątki lub odrzucenia w funkcjach wywołania zwrotnego zatrzymują aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

14.8 port.once()

Dostępne od: Neutron AppEngine 1.0.0
port.once(eventName, callback);
Cel. Nasłuchiwanie tylko pierwszego pasującego zdarzenia.
Opis. Zdarzenia należą do wybranego portu. once usuwa rejestrację przed wywołaniem funkcji wywołania zwrotnego. off wymaga tej samej referencji do funkcji i nie przerywa już rozpoczętej funkcji async.

Parametry

Tabela 62

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

"data", "line" lub "state".

callback

function / wymagane

Funkcja odbierająca jeden obiekt zdarzenia.

Wynik

Wybrany obiekt portu; rejestrację słuchacza można połączyć w łańcuch.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowym zdarzeniu lub funkcji wywołania zwrotnego; QUOTA_EXCEEDED powyżej 32 funkcji nasłuchujących na port. Nieobsłużone wyjątki lub odrzucenia w funkcjach wywołania zwrotnego zatrzymują aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

14.9 port.off()

Dostępne od: Neutron AppEngine 1.0.0
port.off(eventName, callback);
Cel. Usunięcie funkcji nasłuchującej.
Opis. Zdarzenia należą do wybranego portu. once usuwa rejestrację przed wywołaniem funkcji wywołania zwrotnego. off wymaga tej samej referencji do funkcji i nie przerywa już rozpoczętej funkcji async.

Parametry

Tabela 63

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

"data", "line" lub "state".

callback

function / wymagane

Funkcja odbierająca jeden obiekt zdarzenia.

Wynik

Wybrany obiekt portu; rejestrację słuchacza można połączyć w łańcuch.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowym zdarzeniu lub funkcji wywołania zwrotnego; QUOTA_EXCEEDED powyżej 32 funkcji nasłuchujących na port. Nieobsłużone wyjątki lub odrzucenia w funkcjach wywołania zwrotnego zatrzymują aplikację. off nie ma skutku przy brakującej rejestracji.

Przykład

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

14.10 Zdarzenia i wyznaczanie granic wiadomości

Tabela 64

Zdarzenie

Object

Opis

data

{ data: Uint8Array }

Surowy fragment strumienia; jedno zdarzenie niekoniecznie jest jednym pakietem protokołu. NUL i inne bajty binarne zostają zachowane.

line

{ line: string }

Zmontowana linia UTF-8 bez ogranicznika; podzielone fragmenty wiadomości są ponownie składane. Białe znaki nie są przycinane automatycznie.

state

{ port, claimed, reason, generation }

port to rs232 lub rs485. claimed jest typu boolean; reason określa przejście; generation zmienia się po zastosowaniu stanu portu.

Przy funkcji nasłuchującej line odebrane dane są składane aż do ogranicznika. Funkcja nasłuchująca data na tym samym porcie otrzymuje inny widok tego strumienia; nie przetwarzaj polecenia dwukrotnie. Zbyt długie wiersze powodują MESSAGE_TOO_LARGE przed funkcją wywołania zwrotnego line i mogą zatrzymać aplikację. Bez funkcji nasłuchujących line surowe dane binarne nie są zbierane w buforze wierszy. Zdarzenia sprzed reinicjalizacji nie są ponownie wykorzystywane jako dane przy nowej konfiguracji.

Porty szeregowe nie mają zdarzenia connection: odłączonych kabli lub wyłączonych urządzeń zwykle nie można wiarygodnie wykryć. state opisuje przejęcie i ustawienia Neutron AppEngine, a nie połączenie fizyczne. Sprawdzaj osiągalność za pomocą odpowiedzi i limitów czasu swojego protokołu. Aplikacje RS-485 implementują adresowanie, CRC i zasady dostępu do wspólnej magistrali; systemowy filtr R4A nie jest stosowany do surowych danych podczas przejęcia przez JavaScript.

14.11 Kompletna aplikacja RS-232 / RS-485

Ustaw funkcję wybranego portu na Disabled i usuń inne przypisania. Poniższa aplikacja przejmuje go, trwale konfiguruje 19200/8N1 i odpowiada na WEIGHT? za pomocą net,gross,unit. Dla drugiego portu zmień tylko wybrany obiekt. Skonfiguruj taki sam format znaków na urządzeniu zdalnym.

// 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 Testy integracyjne

Tabela 65

Test

Oczekiwany wynik

Przejęcie przy włączonej funkcji systemowej

RESOURCE_IN_USE; sposób użycia systemu pozostaje niezmieniony.

Skonfiguruj przez JavaScript i osobno przez SMD

Szybkość transmisji/parzystość/bity obowiązują bez ponownego uruchamiania urządzenia.

Zmiana jednego portu

Drugi port zachowuje dane i działanie, jeśli nie ma to na nie wpływu.

Przejęcie zewnętrzne podczas operacji JavaScript

state RESOURCE_IN_USE, claimed=false; nowe zapisy zwracają NOT_OWNER.

Bajty binarne i linia rozdzielona pomiędzy odbiory

Brak utraty NUL i podwójnych ograniczników; jedna prawidłowo zmontowana linia.

Skonfiguruj ponownie podczas częściowego odbioru lub zapisu

Stare linie częściowe są odrzucane; pozostałe stare zapisy nie są wysyłane przy nowych ustawieniach.

Zwolnienie / Stop i ponowne przejęcie

Brak stale zajętego portu; ustawienia fizyczne pozostają.

15. Moduł MQTT

Moduł ten nie wykonuje automatycznie poleceń CSCP. Aplikacja definiuje znaczenie tematów, format ładunku i dozwolone polecenia. mqtt.connect() łączy się z brokerem użytkownika, nie zmienia połączenia systemowego Scale Monitor i nie wymaga claim().
Moduł mqtt udostępnia aplikacji użytkownika jedno niezależne połączenie z brokerem, niezależne od połączenia systemowego Scale Monitor. Obydwa mogą działać jednocześnie z różnymi adresami, tożsamościami, danymi uwierzytelniającymi i subskrypcjami. Aplikacja nie zajmuje się tematami systemowymi. Wsparcie: app.capabilities().features.mqtt === true. Wszystkie funkcje, zdarzenia i właściwości w tym rozdziale są dostępne w Neutron AppEngine 1.0.0.
Tabela 66

URL

Połączenie

Przykład

mqtt://

MQTT przez TCP

mqtt://broker.example.com:1883

mqtts://

MQTT z uwierzytelnieniem serwera TLS

mqtts://broker.example.com:8883

ws://

MQTT przez WebSocket

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

wss://

MQTT przez bezpieczny protokół WebSocket

wss://broker.example.com/mqtt

Protokół: MQTT 3.1.1; API obsługuje QoS 0 i 1. WebSocket URL musi wskazywać na słuchacza MQTT brokera, a nie na dowolny serwer WebSocket. Warunkiem wstępnym jest dostęp do sieci, prawidłowe ustawienia DNS i osiągalny broker. Zegar urządzenia musi być prawidłowy, aby można było sprawdzić ważność certyfikatu.

Cykl życia połączenia

Najpierw zarejestruj funkcje nasłuchujące, następnie await mqtt.configure(...), await mqtt.connect() i await mqtt.subscribe(...). Konfiguracja obowiązuje podczas bieżącego uruchomienia aplikacji i jest odrzucana przy jego zakończeniu. Umieść ją w inicjalizacji, aby umożliwić automatyczny start aplikacji. Nie łącz się ponownie przy każdym cyklu timera.
Po udanym połączeniu rozłączenie domyślnie wyzwala automatyczne ponowne połączenie, z ograniczonym opóźnieniem podwajającym się do 60 sekund. Pomyślnie potwierdzone subskrypcje są przywracane automatycznie, asynchronicznie. connect i zakończenie connect() potwierdzają połączenie, a nie zakończenie wszystkich przywróconych subskrypcji. Błędy przywracania powodują emisję error. Przed pierwszym udanym połączeniem nieudana próba jest odrzucana; aplikacja decyduje, czy ponowić próbę.
Jawne disconnect(), błąd uwierzytelniania lub przepełnienie kolejki zdarzeń zatrzymują automatyczne ponowne łączenie. Zwykła utrata sieci po udanym połączeniu powoduje ponowne łączenie, jeśli jest ono włączone. Zatrzymanie lub zastąpienie aplikacji zamyka tylko jej własne połączenie MQTT. Asynchroniczne prawidłowe zamknięcie nie potwierdza dostarczenia ostatnich publikacji. Połączenie systemowe działa niezależnie.

mqtt.configure(options)

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.configure(options);
Cel. Konfiguracja brokera i tożsamości aplikacji.
Opis. Sprawdza i zastępuje ustawienia tylko wtedy, gdy klient użytkownika nie jest podłączony, nie łączy się ani nie oczekuje na ponowne połączenie. Poczekaj na disconnect() przed ich zmianą. Pomyślna nowa konfiguracja usuwa zapamiętane subskrypcje; awaria powoduje zachowanie poprzedniej konfiguracji.

Parametry

Tabela 67

Parametr

Typ / wymaganie

Opis

options

object / wymagane

Właściwości są wymienione poniżej. Nieznane właściwości są odrzucane; wartości muszą używać udokumentowanych typów.

Wynik

Promise<undefined>. Potwierdza konfigurację i załadowanie żądanych profili certyfikatów; nie łączy się.

Błędy i szczególne uwagi

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, BUSY, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, OUT_OF_MEMORY. Nieprawidłowa zawartość PEM może zakończyć się niepowodzeniem tylko podczas połączenia TLS.

Przykład

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
});
Tabela 68

Właściwość options

Typ / wartość domyślna

Znaczenie i limity

url

string / wymagane

Do 512 bajtów UTF-8. Jeden z czterech schematów. Nazwa użytkownika/hasło w URL, białe znaki i fragment # są niedozwolone. Uwzględnij prawidłową ścieżkę ws/wss, np. /mqtt.

clientId

string / automatyczny

Do 64 UTF-8 bajtów. Jeśli nie ma go lub jest pusty, urządzenie przypisuje stabilną tożsamość aplikacji użytkownika. Dwa jednoczesne połączenia z tym samym brokerem nie mogą dzielić clientId.

username, password

string / brak

Maksymalnie odpowiednio 256 i 512 UTF-8 bajtów. Nigdy nie loguj ich na konsolę; kod aplikacji nie jest tajnym skarbcem.

keepAlive

integer / 60

Sekundy, 5..3600.

cleanSession

boolean / true

false umożliwia trwałą sesję brokera dla tego samego clientId. Aplikacja API w dalszym ciągu przywraca potwierdzone subskrypcje; subskrypcje tylko dla brokerów nie są częścią jego listy lokalnej.

reconnect

boolean / true

Automatyczne ponowne połączenie po utracie nawiązanego połączenia. Nie powtarza nieudanego pierwszego logowania ani wyraźnego disconnect().

connectTimeoutMs

integer / 10000

1000..60000 ms. Termin podłączenia klienta i działania sieci.

reconnectDelayMs

integer / 1000

1000..60000 ms. Początkowe opóźnienie, podwajanie przy powtarzających się rozłączeniach aż do 60000 ms i resetowanie po pomyślnym zakończeniu.

will

object / brak

{topic, payload, qos?, retain?}. topic to temat publikacji; payload jest typu string. qos: 0 lub 1, domyślnie 0; retain: boolean, domyślnie false. Broker publikuje wiadomość will po nieoczekiwanym rozłączeniu zgodnie z zasadami MQTT; nie polegaj na niej po prawidłowym zamknięciu.

tls

object / brak

Tylko mqtts/wss. Właściwości: caProfile, clientCertificateProfile, clientKeyProfile. Zobacz TLS poniżej.

Kompletne opcje JSON muszą mieścić się w bajtach 4096 UTF-8, łącznie z nazwami właściwości i znakami ucieczki. Rzeczywista pojemność will.payload jest zatem mniejsza niż 4096 bajtów. Ciągi konfiguracyjne nie mogą zawierać NUL; użyj publish() dla danych binarnych. Ustawienia użytkownika-klienta są niezależne od ustawień brokera systemowego.

mqtt.connect(options?)

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.connect({ timeoutMs: 15000 });
Cel. Połączenie ze skonfigurowanym brokerem.
Opis. Promise zostaje spełniona po pomyślnym potwierdzeniu połączenia przez brokera. Wywołania przy już nawiązanym połączeniu kończą się sukcesem. Druga równoczesna próba połączenia jest odrzucana z BUSY.

Parametry

Tabela 69

Parametr

Typ / wymaganie

Opis

options.timeoutMs

liczba całkowita / opcjonalne

1..60000 ms; domyślnie skonfigurowany connectTimeoutMs. Dotyczy próby połączenia; oczekiwanie w kolejce na usługę i zamknięcie klienta mogą wydłużyć całkowity czas.

Wynik

Promise<undefined>. Informacje o połączeniu są dostępne także w connect i status().

Błędy i szczególne uwagi

NOT_CONFIGURED, BUSY, START_FAILED, AUTH_FAILED, CONNECTION_REFUSED, NOT_CONNECTED, TIMEOUT, CANCELLED. Dokładniejsze przyczyny sieciowe/TLS mogą pojawić się w error lub status(). lastError. Ogranicz ponawianie nieudanych prób początkowych.

Przykład

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

mqtt.disconnect()

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.disconnect();
Cel. Prawidłowe zamknięcie połączenia użytkownika i zatrzymanie ponownego łączenia.
Opis. Anuluje oczekujące operacje connect, publish, subscribe i unsubscribe; obsłuż ich obietnice. Konfiguracja i potwierdzone subskrypcje pozostają dla następnego connect w tym samym uruchomieniu; configure je zastępuje.

Parametry

Brak parametrów.

Wynik

Promise<undefined> po zamknięciu klienta. Wywołania przy już rozłączonym kliencie kończą się sukcesem.

Błędy i szczególne uwagi

NOT_CONFIGURED przed wstępną konfiguracją. Przerwane operacje otrzymują CANCELLED. Nie cofa publikacji zaakceptowanych już przez brokera. Nie wysyła automatycznej wiadomości biznesowej w trybie offline; opublikuj i potwierdź przed disconnect(), jeśli jest to wymagane.

Przykład

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

mqtt.status()

Dostępne od: Neutron AppEngine 1.0.0
const status = mqtt.status();
Cel. Zwrócenie bieżącego stanu połączenia użytkownika bez oczekiwania.
Opis. Zwraca kopię najnowszego stanu, a nie gwarancję powodzenia kolejnej operacji sieciowej. Nie ujawnia nazwy użytkownika, hasła ani certyfikatów.

Parametry

Brak parametrów.

Wynik

{configured:boolean, connected:boolean, state:string, reconnectAttempts:number, lastError:string}. state: unconfigured, disconnected, connecting, connected, reconnecting. reconnectAttempts zlicza rozpoczęcia automatycznego ponownego łączenia od ostatniego configure. lastError jest puste lub zawiera ostatni kod błędu; udane połączenie je czyści.

Błędy i szczególne uwagi

Synchroniczny; nie łączy się. Stan sieci może się zmieniać pomiędzy odczytem a następną operacją.

Przykład

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

mqtt.subscribe(topic, options?)

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.subscribe("factory/+/command", { qos: 1, timeoutMs: 10000 });
Cel. Subskrybowanie tematu lub filtra tematów.
Opis. Oczekuje na brokera SUBACK; odmowa brokera nie jest sukcesem. Potwierdzone subskrypcje są zapamiętywane do ponownego połączenia. Powtarzanie filtra nie powoduje wykorzystania dodatkowego miejsca; pomyślne potwierdzenie zastępuje żądany QoS. Broker może przyznać niższy QoS.

Parametry

Tabela 70

Parametr

Typ / wymaganie

Opis

topic

string / wymagane

1..192 bajtów UTF-8. + musi zajmować cały poziom, a # cały ostatni poziom; na przykład factory/+/command lub factory/#.

options.qos

liczba całkowita / 0

0 lub 1.

options.timeoutMs

integer / 10000

1..60000 ms dla potwierdzenia brokera.

Wynik

Promise<undefined> po udanym SUBACK. Przychodzące publikacje emitują message.

Błędy i szczególne uwagi

NOT_CONFIGURED, NOT_CONNECTED, SUBSCRIBE_FAILED, QUOTA_EXCEEDED, BUSY, TIMEOUT. Najwyżej 16 filtrów. Współbieżne subscribe/unsubscribe tego samego filtra otrzymuje BUSY. Żądania offline nie są kolejkowane na później.

Przykład

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

mqtt.unsubscribe(topic, options?)

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.unsubscribe("factory/scale-01/command");
Cel. Anulowanie subskrypcji dokładnego filtra i usunięcie go z listy ponownego łączenia.
Opis. Potwierdzono UNSUBACK. Subskrypcję nieznanych filtrów można anulować. Nie usuwa już otrzymanych wiadomości ani innych nakładających się subskrypcji.

Parametry

Tabela 71

Parametr

Typ / wymaganie

Opis

topic

string / wymagane

Dokładny filtr do rezygnacji z subskrypcji; do 192 UTF-8 bajtów.

options.timeoutMs

integer / 10000

1..60000 ms.

Wynik

Promise<undefined> po UNSUBACK.

Błędy i szczególne uwagi

NOT_CONFIGURED, NOT_CONNECTED, BUSY, TIMEOUT, CANCELLED. Aby zastąpić zapamiętane filtry przy rozłączonym kliencie, użyj configure; zastępuje całą lokalną listę, ale nie gwarantuje usunięcia starej sesji brokera.

Przykład

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

mqtt.publish(topic, payload, options?)

Dostępne od: Neutron AppEngine 1.0.0
await mqtt.publish(topic, payload, { qos: 1, retain: false });
Cel. Publikowanie tekstu lub danych binarnych.
Opis. Wysyła ciągi znaków jako UTF-8, a Uint8Array jako dokładne bajty; nie dodaje CR, LF ani NUL. Kopiuje dane wiadomości w chwili wywołania. Wysyłanie rozpoczyna się w osobnym zadaniu komunikacyjnym po przetworzeniu żądania. QoS 0 potwierdza udany zapis transportowy; QoS 1 czeka na PUBACK brokera. Żadne z nich nie potwierdza przetworzenia przez końcowego subskrybenta.

Parametry

Tabela 72

Parametr

Typ / wymaganie

Opis

topic

string / wymagane

1..192 UTF-8 bajtów, bez + i #.

payload

string | Uint8Array / wymagane

0..4096 bajtów po kodowaniu UTF-8; dane binarne mogą zawierać NUL.

options.qos

liczba całkowita / 0

0 lub 1; QoS 2 nie jest obsługiwane.

options.retain

boolean / false

Zachowaj wiadomość na brokerze. Pusty ładunek z retain=true usuwa zachowaną wartość tematu.

options.timeoutMs

integer / 10000

1..60000 ms. QoS 1 PUBACK ostateczny termin; QoS 0 nie czeka na brokera.

Wynik

Promise<undefined>; znaczenie potwierdzenia zależy od QoS.

Błędy i szczególne uwagi

NOT_CONNECTED offline; brak nieograniczonej kolejki offline. BUSY dla pełnej kolejki wychodzącej (32768 bajtów łącznie z narzutem protokołu) lub limitu operacji oczekujących. MESSAGE_TOO_LARGE, INVALID_ARGUMENT, NETWORK_ERROR, TIMEOUT, CANCELLED. Broker mógł już otrzymać wiadomość po przekroczeniu limitu czasu/rozłączeniu. QoS 1 może powielać dostawę; używaj identyfikatorów żądań i deduplikacji w operacjach biznesowych.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
mqtt.on(eventName, callback);
mqtt.once(eventName, callback);
mqtt.off(eventName, callback);
Cel. Zarejestrowanie lub usunięcie funkcji nasłuchującej zdarzeń brokera użytkownika.
Opis. Zdarzenia są wykonywane kolejno. Funkcja async oddaje sterowanie przy await; stosuj ochronę przed nakładaniem, gdy kolejność ma znaczenie. once usuwa rejestrację przed wywołaniem. off usuwa wszystkie rejestracje tej samej funkcji dla wybranego zdarzenia.

Parametry

Tabela 73

Parametr

Typ / wymaganie

Opis

eventName

string / wymagane

connect, disconnect, message lub error.

callback

function / wymagane

Otrzymuje jeden obiekt z polami wymienionymi poniżej. Zachowaj tę samą referencję do funkcji dla off.

Wynik

Zwraca mqtt dla łączenia. Co najwyżej 32 słuchaczy we wszystkich zdarzeniach MQTT.

Błędy i szczególne uwagi

INVALID_ARGUMENT, QUOTA_EXCEEDED. Samo error nie zatrzymuje aplikacji; nieobsłużony wyjątek funkcji nasłuchującej lub odrzucona Promise zatrzymują ją zgodnie z zasadami środowiska wykonawczego. Odrzucenie operacji i error są osobnymi powiadomieniami bez gwarantowanej wzajemnej kolejności.

Przykład

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));
Tabela 74

Zdarzenie

Pola od Neutron AppEngine 1.0.0

Znaczenie

connect

connected: true, reconnected: boolean, sessionPresent: boolean

CONNACK zaakceptowane. reconnected oznacza wcześniejsze pomyślne połączenie w ramach bieżącej konfiguracji. sessionPresent to flaga przywróconej sesji brokera, a nie lokalnie potwierdzona lista subskrypcji.

disconnect

connected: false, reason: string

Utrata nawiązanego połączenia lub wyraźne rozłączenie. Obsłuż Promise w przypadku nieudanego połączenia początkowego. Żadne zdarzenie nie jest gwarantowane w momencie zakończenia aplikacji.

message

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

Kompletna wiadomość MQTT, wcześniej złożona z fragmentów. text jest widokiem UTF-8; do dowolnych danych binarnych użyj data. qos to QoS odebranej wiadomości (API żąda najwyżej 1, ale broker może zachować starsze subskrypcje).

error

Błąd z polami code: string i message: string

Połączenie, TLS, przywrócenie subskrypcji, wiadomość o zbyt dużym rozmiarze lub błąd kolejki. Aplikacja decyduje, jak kontynuować; sprawdź status() i zaległe operacje.

TLS i profile certyfikatów

mqtts i wss sprawdzają nazwę serwera i zaufanie certyfikatu. Bez caProfile używane jest wbudowane zaufanie publiczne CA. Użyj profilu niestandardowego dla prywatnych urzędów certyfikacji. Wyłączenie weryfikacji certyfikatu nie jest częścią API. Ustawienia i certyfikaty brokera systemu nie mają zastosowania do połączeń użytkowników.

Tabela 75

Pole tls

Zapisany profil

Cel

caProfile: "company-ca"

JCA_company-ca

Zaufany łańcuch CA PEM lub CA.

clientCertificateProfile: "device-01"

JCC_device-01

Certyfikat klienta PEM dla wzajemnego TLS.

clientKeyProfile: "device-01"

JCK_device-01

Klucz prywatny klienta w formacie PEM; wymagany razem z certyfikatem. Klucze zaszyfrowane hasłem nie są obsługiwane w tej wersji.

Nazwy profili zawierają 1..48 znaków: A–Z, a–z, 0–9, _ lub -. Każdy znormalizowany PEM ma najwyżej 16384 bajtów. Autoryzowany integrator dostarcza profile przez istniejącą ścieżkę certyfikatów SMD, na przykład JCA_company-ca=<PEM>, z pełnym certyfikatem PEM jako wartością. Nie jest to ścieżka pliku, publiczny URL ani systemowy profil MCA. Pusta wartość usuwa profil według istniejących zasad certyfikatów. Aplikacje ładują profile podczas configure; zmiana zapisanych profili nie zastępuje certyfikatów aktywnego połączenia. Rozłącz, wykonaj configure, a następnie connect.
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();

Limity, błędy i odzyskiwanie

Tabela 76

Limit od wersji Neutron AppEngine 1.0.0

Wartość / obsługa

Połączenia

Jedno połączenie użytkownika, niezależne od połączenia systemowego Scale Monitor.

Dane wiadomości

4096 bajtów na wysłaną lub odebraną wiadomość: cała wiadomość, a nie każdy jej fragment.

Temat / subskrypcje / funkcje nasłuchujące

192 bajtów UTF-8 / 16 potwierdzonych filtrów / 32 funkcje nasłuchujące.

Oczekujące operacje

Najwyżej 8, współdzielonych z innymi asynchronicznymi operacjami środowiska wykonawczego. Kolejka wychodząca MQTT: 32768 bajtów.

Limit czasu

Maksymalnie 60000 ms w celu potwierdzenia połączenia lub brokera. Nie gwarantujemy dokładnego czasu reakcji urządzenia.

Zbyt duża wiadomość przychodząca

Cała wiadomość odrzucona; błąd MESSAGE_TOO_LARGE. Częściowe wiadomości nie są dostarczane.

Przepełnienie kolejki usługowej

EVENT_OVERFLOW zamyka połączenie użytkownika i przestaje łączyć się ponownie. Środowisko wykonawcze ma inną ograniczoną kolejkę; jego przepełnienie powoduje zatrzymanie aplikacji.

Przekroczenie czasu oczekiwania na potwierdzenie

Oczekująca operacja jest odrzucana i łączy się ponownie zgodnie ze skonfigurowanymi regułami. Inne operacje mogą otrzymać NOT_CONNECTED. Późne potwierdzenie ze starego połączenia nigdy nie potwierdza nowego żądania.

Rozłączenie podczas publikowania

Niepotwierdzone operacje odrzucone; aplikacja decyduje, czy ponowić próbę. Efekty już wykonane nie zostają cofnięte.

Główne kody: 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. Komunikaty błędów służą diagnostyce; decyzje programu opieraj na code. Przy błędach TLS sprawdź czas urządzenia, nazwę serwera, łańcuch zaufania i wymagany certyfikat klienta.

Kompletny przykład: publikowanie masy i odbieranie poleceń

Przed uruchomieniem dostosuj brokerUrl, baseTopic i dane uwierzytelniające. Każde urządzenie wymaga własnego clientId i tematów. Wysyłaj polecenia na /command bez retain. Przykład okresowo publikuje masę, automatycznie przywraca potwierdzone subskrypcje i nie powtarza tarowania dla zachowanych poleceń. Dla systemów ponawiających żądania QoS 1 dodaj identyfikatory żądań i rejestr wykonanych poleceń; samo retain nie zapobiega podwójnemu dostarczeniu.

// 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();
});

Testy integracyjne

Tabela 77

Test

Oczekiwany wynik

Połączenie systemowe i broker użytkownika jednocześnie

Scale Monitor kontynuuje; tematy użytkownika obsługiwane są wyłącznie przez aplikację.

Opublikuj WEIGHT? na wybranym /command

Pomiar w JSON pojawia się na /reply; /weight aktualizuje się mniej więcej co sekundę.

Utrata i przywrócenie sieci

status staje się reconnecting, następnie connect z reconnected=true i automatycznym przywróceniem subskrypcji.

Nieprawidłowe hasło / CA / nazwa serwera

connect jest odrzucane; error/status dostarczają diagnostykę. Nieudane uwierzytelnianie nie jest powtarzane bez ograniczeń.

Wyślij 4096 bajtów binarnych

Wszystkie bajty, łącznie z NUL, pozostają niezmienione. Temat nie jest wliczany do rozmiaru ładunku.

Odbierz wiadomość powyżej 4096 bajtów

MESSAGE_TOO_LARGE bez zdarzenia częściowego komunikatu.

Zatrzymanie aplikacji

Połączenie użytkownika zostaje zamknięte; połączenie systemowe pozostaje aktywne.

mqtt, mqtts, ws, wss

Przetestuj każdy URL na odpowiednim słuchaczu brokera; ws/wss wymagają poprawnej ścieżki.

16. Klient HTTP / REST

Globalny fetch() łączy aplikacje z zewnętrznymi interfejsami API REST poprzez HTTP lub HTTPS. Wsparcie: app.capabilities().features.http. Wszystkie funkcje, właściwości i opcje w tym rozdziale są dostępne w Neutron AppEngine 1.0.0. Jest to udokumentowany podzbiór fetch, a nie kompletne środowisko przeglądarki.

Urządzenie działa jako klient HTTP. Ten API nie dodaje niestandardowych tras REST do wewnętrznego serwera Neutron HTTP. Żądania nie zapewniają automatycznych ponownych prób, trwałej kolejki, automatycznej transmisji zdarzeń ani przechowywania odpowiedzi. Aplikacja definiuje czas połączeń, formaty danych i obsługę awarii.

fetch(url, options?)

Dostępne od: Neutron AppEngine 1.0.0
const response = await fetch(url, options);
Cel. Wysłanie żądania do zewnętrznego serwera HTTP/HTTPS i odebranie kompletnej odpowiedzi o ograniczonym rozmiarze.
Opis. Promise zostaje spełniona po odebraniu całej treści odpowiedzi, a nie tylko początkowych nagłówków. HTTP 400, 401, 404 i 500 są zwykłymi odpowiedziami i nie powodują odrzucenia. Błędy połączenia, TLS, limitu czasu i rozmiaru powodują odrzucenie. Przetwarzanie sieci odbywa się poza funkcją wywołania zwrotnego JavaScript, bez blokowania jej podczas oczekiwania.

Parametry

Tabela 78

Parametr

Typ / wymaganie

Opis

url

string / wymagane

Bezwzględny http:// lub https:// URL, maksymalnie 512 ASCII bajtów. Zakoduj Unicode i białe znaki w ścieżkach/wartościach zapytań; użyj encodeURIComponent dla poszczególnych wartości. # fragment został usunięty. Poświadczenia URL są zabronione.

options

object / opcjonalnie

method, headers, body, timeoutMs, tls i redirect. Nieznane opcje są odrzucane. Szczegóły podano poniżej.

Wynik

Promise<Response>, opisane poniżej. body i zakodowane opcje mają oddzielne limity; dane binarne nie są kodowane jako JSON ani Base64.

Błędy i szczególne uwagi

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. Po przerwie/przekroczeniu limitu czasu serwer mógł już przetworzyć żądanie; ponowna próba POST może zduplikować efekt biznesowy.

Przykład

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));
Tabela 79

Opcja od wersji Neutron AppEngine 1.0.0

Typ / wartość domyślna

Znaczenie

method

string / GET

GET, POST, PUT, PATCH, DELETE lub HEAD. Konwertowane na wielkie litery. Inne metody nie są obsługiwane w tej wersji.

headers

object / brak

Niestandardowe nazwy nagłówków i wartości tekstowe. Wielkość liter w nazwach nie ma znaczenia; zduplikowane nazwy różniące się tylko wielkością liter są odrzucane. Tylko wartości ASCII, bez CR/LF i znaków sterujących innych niż tabulator.

body

string | Uint8Array | null / brak

Najwyżej 4096 bajtów po kodowaniu UTF-8. null oznacza brak treści. GET i HEAD nie mogą mieć treści. Ciągi znaków bez jawnego Content-Type otrzymują text/plain; charset=UTF-8; dla JSON użyj JSON.stringify i application/json. Uint8Array nie otrzymuje automatycznego Content-Type.

timeoutMs

integer / 10000

1..60000 ms; udokumentowane rozszerzenie Neutron AppEngine, a nie standardowa opcja fetch przeglądarki. Zaczyna się przy wywołaniu i obejmuje oczekiwanie w kolejce oraz przesyłanie treści. Dostarczenie błędu nie ma gwarancji czasu rzeczywistego; podstawowe wywołania rozwiązywania nazw lub łączenia mogą zakończyć się później.

tls

object / brak

Tylko HTTPS. caProfile i opcjonalnie parę clientCertificateProfile/clientKeyProfile. Zobacz TLS.

redirect

string / manual

Obsługiwane jest tylko manual. Zwraca odpowiedzi 3xx, aby aplikacja mogła sprawdzić Location. Bez automatycznego podążania za przekierowaniem.

Najwyżej 32 podane nagłówki i łącznie 2048 bajtów (nazwy, wartości i separatory); nazwy do 64 znaków, wartości do 1024. Klient zarządza automatycznymi nagłówkami protokołu. Nie można ustawić Host, Content-Length, Connection, Transfer-Encoding, Accept-Encoding, Expect, Trailer, Upgrade, Proxy-Connection, TE ani Keep-Alive. Zakodowane opcje żądania mają dodatkowy łączny limit 4096 bajtów UTF-8.

Response: status i metadane

Dostępne od: Neutron AppEngine 1.0.0
const response = await fetch("https://api.example.com/articles/ART-001");
Cel. Sprawdzenie wyniku HTTP przed konwersją treści odpowiedzi.
Opis. Obiekt z właściwościami tylko do odczytu i metodami jednorazowego odczytania treści. Nie potwierdza biznesowego znaczenia statusu ani poprawności odebranego JSON.

Parametry

Brak parametrów.

Wynik

{status, statusText, ok, url, redirected, headers, bodyUsed, text(), json(), arrayBuffer()}. status to kod HTTP; ok oznacza 200..299. url to żądany URL bez fragmentu; redirected jest false; statusText w tej wersji jest pustym ciągiem znaków.

Błędy i szczególne uwagi

Obsługuj odrzucenie fetch oddzielnie od response.ok. Dla 204 lub HEAD oczekuj pustej treści; response.json() dla pustej treści zgłasza SyntaxError. Brak strumieniowego response.body, clone(), Blob, FormData, Request i globalnego konstruktora Response.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const text = await response.text();
Cel. Jednorazowa konwersja odebranej treści odpowiedzi na tekst UTF-8.
Opis. Usuwa początkowy BOM UTF-8. Nie wykonuje kolejnego żądania sieciowego; fetch już odebrał treść. bodyUsed staje się true przy pierwszym wywołaniu metody odczytującej treść.

Parametry

Brak parametrów.

Wynik

Promise<string>. Użyj arrayBuffer() dla dowolnych danych binarnych.

Błędy i szczególne uwagi

Ponowny odczyt zgłasza TypeError z code=BODY_USED. Dekoduje UTF-8; inne zestawy znaków nie są automatycznie obsługiwane.

Przykład

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

response.json()

Dostępne od: Neutron AppEngine 1.0.0
const value = await response.json();
Cel. Dekodowanie treści UTF-8 i jednorazowe wykonanie JSON.parse.
Opis. Zwraca obiekt, tablicę lub inną prawidłową wartość JSON. Content-Type nie zmienia reguł JSON.parse. Najpierw sprawdź status, jeśli API zwraca różne formaty treści błędów.

Parametry

Brak parametrów.

Wynik

Promise<JSON value>. bodyUsed staje się true nawet jeśli analiza JSON nie powiedzie się.

Błędy i szczególne uwagi

SyntaxError przy nieprawidłowym/pustym JSON; TypeError/BODY_USED przy ponownym odczycie. Zapisz wynik w zmiennej, aby użyć go ponownie.

Przykład

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()

Dostępne od: Neutron AppEngine 1.0.0
const buffer = await response.arrayBuffer();
Cel. Jednorazowe zwrócenie odebranych bajtów binarnych bez konwersji tekstowej.
Opis. Użyj Uint8Array, aby uzyskać dostęp do poszczególnych bajtów, w tym NUL. Zapisz je lub przekaż do innego obsługiwanego modułu.

Parametry

Brak parametrów.

Wynik

Promise<ArrayBuffer>, co najwyżej 4096 bajtów.

Błędy i szczególne uwagi

TypeError/BODY_USED podczas wielokrotnego czytania. Brak automatycznego gzipa lub innej dekompresji zawartości.

Przykład

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

Dostępne od: Neutron AppEngine 1.0.0
const contentType = response.headers.get("Content-Type");
Cel. Odczyt nagłówków odpowiedzi bez rozróżniania wielkości liter.
Opis. Obiekt tylko do odczytu obsługujący get, has, entries, keys, values, forEach i iterację. Powtarzające się nazwy nagłówków są łączone przecinkami; nie jest to automatyczny menedżer plików cookie.

Parametry

Tabela 80

Parametr

Typ / wymaganie

Opis

name dla get/has

string / wymagane

Prawidłowa nazwa nagłówka HTTP.

callback dla forEach

function / wymagane

Otrzymuje value, name i headers. Opcjonalny drugi argument ustawia thisArg.

Wynik

get zwraca string lub null; has zwraca boolean; entries/keys/values zwracają iteratory. forEach nie zwraca wyniku. Iteracja używa nazw nagłówków zapisanych małymi literami.

Błędy i szczególne uwagi

INVALID_ARGUMENT przy nieprawidłowych nazwach nagłówków lub funkcjach wywołania zwrotnego. Brak globalnego konstruktora Headers i metod odpowiedzi set/append/delete. Jeśli serwer przekroczy 32 nagłówki, łącznie 2048 bajtów lub obsługiwane długości nazw/wartości, fetch jest odrzucane zamiast cichego obcięcia.

Przykład

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);

Uwierzytelnianie

Przekaż w nagłówkach tokeny Bearer, klucze API lub wstępnie zakodowane wartości Basic. Nie umieszczaj danych uwierzytelniających w URL. Brak automatycznego logowania, odświeżania tokenów, uwierzytelniania HTTP Digest i wspólnej sesji z połączeniami systemowymi. Pliki cookie nie są automatycznie zapisywane ani wysyłane. Ten klient urządzenia nie podlega ograniczeniom CORS przeglądarki.

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 i profile certyfikatów

HTTPS zawsze weryfikuje nazwę serwera i zaufanie do certyfikatu. Bez caProfile używa wbudowanego zaufania publicznego CA. Użyj profilu niestandardowego dla prywatnych urzędów certyfikacji. Zegar urządzenia musi być prawidłowy, aby można było sprawdzić ważność certyfikatu. Żadnej niebezpiecznej opcji ani obejścia weryfikacji nazwy hosta.

Tabela 81

Opcja tls

Zapisany profil

Cel

caProfile: "company"

JHCA_company

Zaufany łańcuch CA PEM lub CA.

clientCertificateProfile: "scale01"

JHCC_scale01

Certyfikat klienta dla wzajemnego TLS.

clientKeyProfile: "scale01"

JHCK_scale01

klucz prywatny; wymagane wraz z certyfikatem klienta.

Nazwy profili: 1..48 znaków A–Z/a–z, 0–9, _ lub -. Każdy PEM ma najwyżej 16384 bajtów. Autoryzowani integratorzy dostarczają profile przez istniejącą ścieżkę certyfikatów SMD, na przykład JHCA_company=&lt; PEM&gt;. Nie jest to dowolna ścieżka pliku. Profile są oddzielone od systemowego MQTT i certyfikatów wewnętrznego serwera HTTP oraz ładowane dla każdego żądania. Klucze prywatne zaszyfrowane hasłem nie są obsługiwane.

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

Limity i wykonywanie

Tabela 82

Właściwość od wersji Neutron AppEngine 1.0.0

Obsługa

Wykonywanie

Jedno aktywne żądanie i maksymalnie cztery w kolejce. Obowiązuje również wspólny limit środowiska wykonawczego wynoszący osiem oczekujących operacji asynchronicznych.

Rozmiar

4096-bajtowa treść żądania i oddzielny limit 4096-bajtowej treści odpowiedzi. Zbyt duże odpowiedzi wywołują RESPONSE_TOO_LARGE; częściowe ciała nigdy nie są zwracane jako sukces.

Limit czasu

Domyślnie 10000 ms, maksymalnie 60000 ms, łącznie z oczekiwaniem w kolejce. Powolne napływanie danych nie resetuje terminu. Rzeczywisty czas dostawy błędu nie jest gwarantowany w czasie rzeczywistym.

Połączenia

Połączenia są zwalniane po każdym żądaniu. Brak trwałej sesji HTTP lub automatycznego ponawiania. Dlatego HTTPS ustanawia nowe bezpieczne połączenie przy każdym połączeniu.

Przekierowania

Zawsze manual. 3xx pozostaje odpowiedzią; można odczytać Location. Nagłówki uwierzytelniania nie są automatycznie przekazywane do innego serwera.

Kodowanie treści odpowiedzi

Żąda identity. gzip/br i inne kodowania nie są obsługiwane; niepusta zakodowana odpowiedź powoduje UNSUPPORTED_ENCODING.

Zatrzymanie aplikacji

Żądania umieszczone w kolejce z poprzedniego przebiegu są odrzucane; aktywny transfer zostaje przerwany w przypadku wykrycia zatrzymania lub zakończenia połączenia bazowego. Nie cofa to już wykonanych efektów serwera.

Podzbiór API

Brak konstruktorów AbortController/signal, body streaming, clone, Blob, FormData, URL/Request/Response/Headers lub automatycznego środowiska CORS/cookie.

Chroń połączenia okresowe przed nakładaniem się. Użyj identyfikatorów żądań i uzgodnionego protokołu serwera, aby zapewnić niezawodne ponowne próby biznesowe. Przekroczenie limitu czasu lub utrata odpowiedzi nie oznaczają, że serwer nie przetworzył POST/PUT/PATCH/DELETE.

Kompletny przykład: wysyłanie masy

// 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);
}

Testy integracyjne

Do testów lokalnych pakiet źródłowy zawiera tools/rest-test-server.py i tools/examples/rest-self-test.js dla urządzenia. Serwer domyślnie nasłuchuje lokalnie; jawnie użyj --host 0.0.0.0, aby udostępnić go Neutron, i ustaw adres IP komputera w aplikacji testowej. Opcjonalne --cert/--key włączają HTTPS; --ca włącza weryfikację certyfikatu klienta. Dostarczanie certyfikatów/profili pozostaje osobną procedurą zarządzania.

Tabela 83

Test

Oczekiwany wynik

GET/POST/PUT/PATCH/DELETE/HEAD

Prawidłowe żądanie i status; HEAD nie ma ciała.

404 lub 500

Promise spełnia; response.ok to false.

302

Status i Location bez automatycznego nowego żądania.

JSON / UTF-8 / chunked

Kompletna, prawidłowo zdekodowana treść; fragmenty nie są osobnymi zdarzeniami JavaScript.

Ciało binarne z NUL i 0xff

Dokładnie 4096 bajtów w każdym kierunku.

Przeczytaj treść jeszcze raz

TypeError z code=BODY_USED.

Powolna reakcja lub powolny strumień nagłówka

TIMEOUT; ważenie i środowisko wykonawcze nadal działają.

Zbyt duża odpowiedź/nagłówki

Wyraźne odrzucenie bez cichego obcięcia.

HTTPS z nieprawidłowym CA / nazwą / certyfikatem klienta

TLS_ERROR; weryfikacja pozostaje włączona.

Zatrzymaj się podczas transferu

Uwolnione zasoby; brak nieaktualnych odpowiedzi dostarczonych do nowego uruchomienia aplikacji.

17. Klient WebSocket

Dostępne od: Neutron AppEngine 1.0.0 / API 1.
WebSocket zapewnia trwałe dwukierunkowe połączenie z serwerem zewnętrznym. Aplikacje wysyłają wiadomości tekstowe lub binarne i odbierają zdarzenia. Każdy komunikat zachowuje swoją granicę; ograniczniki linii są niepotrzebne. Użyj fetch() dla REST i mqtt dla brokera MQTT.
Każda aplikacja posiada jedno niezależne połączenie, niezależne od ustawień modułu WebSocket, MQTT i Scale Monitor. Obsługuje nazwy ws://, wss://, DNS i IPv4. Sprawdź app.capabilities().features.websocket; limity znajdują się w app.capabilities().websocket.

new WebSocket(url, protocols?, options?)

Dostępne od: Neutron AppEngine 1.0.0
Tworzy klienta i rozpoczyna połączenie asynchroniczne. Zwraca obiekt WebSocket, a nie Promise. Sukces emituje open; awaria emituje error i close. Nieprawidłowe argumenty zgłaszane synchronicznie.
  • url: adres bezwzględny, maksymalnie 512 bajtów, np. wss://system.example.com/scales?device=01. Domyślne porty: 80 dla ws, 443 dla wss. Koduj ścieżki i parametry; Poświadczenia, fragmenty i protokół IPv6 URL nie są obsługiwane.
  • protocols: pominięta lub pusta tablica []. Negocjowanie podprotokołu jest niedostępne w tej wersji; inne wartości podnoszą UNSUPPORTED_PROTOCOL.
  • options: opcjonalny obiekt zawierający timeoutMs, headers i tls. Można również podać bezpośrednio jako drugi argument.
  • timeoutMs: całkowity limit czasu połączenia 1000–15000 ms, domyślnie 10000 ms. Szczegóły DNS/sieci mogą wpływać na rzeczywisty czas powrotu. Nie ogranicza całego czasu życia połączenia.
  • headers: nagłówki HTTP z wartościami tekstowymi, np. Authorization lub X-API-Key. Najwyżej 32 nagłówki i łącznie 512 bajtów. Nagłówki Connection i Sec-WebSocket-* są zarządzane przez klienta i nie można ich ustawiać. Pełne żądanie upgrade, wraz ze ścieżką, nazwą hosta i automatycznymi nagłówkami, musi być krótsze niż 1024 bajtów; zbyt duża kombinacja powoduje HEADERS_TOO_LARGE.
  • tls: tylko wss. caProfile, clientCertificateProfile i clientKeyProfile wykorzystują profile REST. Dostarcz razem certyfikat klienta i klucz. Nazwy profili: 1–48 znaki A–Z, a–z, 0–9, _ lub -. Bez caProfile używa domyślnego zaufania. Weryfikacja nazwy serwera i certyfikatu jest zawsze włączona.
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);

Kontrole certyfikatów wymagają prawidłowego czasu urządzenia. Wyślij dane uwierzytelniające przez wss. Przekierowania nie są realizowane automatycznie. Jeżeli miejsce połączenia jest zajęte, nowy obiekt otrzymuje BUSY i zamyka się; istniejące połączenie pozostaje aktywne.

Uwierzytelnianie Basic z nazwą użytkownika i hasłem

Dostępne od: Neutron AppEngine 1.0.0
Podaj nazwę użytkownika/hasło jako ciągi znaków i użyj poniższej funkcji pomocniczej do zbudowania Authorization. Basic nie haszuje danych uwierzytelniających: koduje username:password jako Base64. Kodowanie jest odwracalne; do przesyłania danych uwierzytelniających używaj wss://.
basicAuth(username, password) jest zdefiniowane w tym przykładzie, a nie wbudowane w Neutron AppEngine. Zwraca pełną wartość nagłówka Basic <Base64>. Obsługuje UTF-8, jeśli serwer go oczekuje, i nie wymaga btoa ani TextEncoder. Oba argumenty muszą być ciągami znaków, inaczej zgłaszany jest TypeError. Nazwy użytkowników nie mogą zawierać dwukropka; hasła mogą. Przykładowy adres i dane uwierzytelniające są fikcyjne.
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);
Zastąp /scale/auth rzeczywistym punktem końcowym serwera. Sama funkcja pomocnicza nie wymaga zmian przy zmianie danych uwierzytelniających. Nigdy nie rejestruj Authorization ani haseł. HTTP 401/403 podczas uwierzytelniania emituje error z AUTH_FAILED, a następnie close. basicAuth działa także w nagłówkach Authorization fetch przez HTTPS.

socket.send(data)

Dostępne od: Neutron AppEngine 1.0.0

W stanie OPEN dodaje jedną wiadomość do kolejki. Przyjmuje string, ArrayBuffer lub widok bufora, taki jak Uint8Array lub DataView. Ciągi znaków są wysyłane jako tekst UTF-8, a inne wartości jako wiadomości binarne. Dane binarne są kopiowane przy wywołaniu, co umożliwia późniejsze zmiany źródła. Puste wiadomości oraz bajty binarne 0 i 255 są dozwolone.

Zwraca undefined. Nie await tego jako potwierdzenia doręczenia: wysłanie nie potwierdza przetworzenia przez serwer. Dodaj identyfikatory żądań i odpowiedzi do swojego protokołu. bufferedAmount zlicza lokalne bajty w kolejce, a nie niepotwierdzone wiadomości serwera.

Najwyżej 4096 bajtów na wiadomość i 16384 bajtów w kolejce lokalnej; obowiązuje również wspólny limit operacji oczekujących. Zbyt duże wiadomości powodują MESSAGE_TOO_LARGE; pełna kolejka powoduje BUSY. CONNECTING powoduje INVALID_STATE; CLOSING/CLOSED ignorują send. Późniejsze błędy transmisji są dostarczane przez error i mogą zamknąć połączenie.

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

Zdarzenia i funkcje nasłuchujące

Dostępne od: Neutron AppEngine 1.0.0
Użyj onopen, onmessage, onerror, onclose lub addEventListener(type, callback, { once: true }). Usuń za pomocą removeEventListener(type, callback). Obsługiwane są tylko te cztery typy zdarzeń i wywołania zwrotne funkcji; maksymalnie 32 zarejestrowanych słuchaczy na obiekt. Zduplikowane pary typu/funkcji nie są dodawane. Brak zdarzeń DOM, przechwytywania lub sygnału AbortSignal.
  • open: aktualizacja połączenia i protokołu powiodła się; readyState to OPEN.
  • message: event.data jest typu string dla tekstu lub ArrayBuffer dla danych binarnych. Fragmenty są składane w jedną wiadomość, w tym znaki UTF-8 podzielone między fragmenty. Ping/pong nie jest dostarczany jako message.
  • error: event.code, event.message oraz Error w event.error. Błędy funkcji wywołania zwrotnego podlegają zasadom środowiska wykonawczego; przechwyć je wewnątrz funkcji, aby kontynuować.
  • close: event.code, event.reason, event.wasClean. 1006 oznacza przerwane zamykanie; 1005 oznacza, że odebrana ramka nie zawierała kodu. Obiekt pozostaje CLOSED. Wszystkie zdarzenia zawierają także type, target i 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?) i stan połączenia

Dostępne od: Neutron AppEngine 1.0.0
close() rozpoczyna asynchroniczne zamykanie i zwraca undefined. Domyślnie: code 1000, pusty reason. Kody użytkownika: 1000 lub 3000–4999; reason najwyżej 123 bajtów UTF-8. Nieprawidłowe argumenty powodują INVALID_ARGUMENT. Powtarzanie close w CLOSING/CLOSED nie ma skutku. Zamykanie podczas łączenia blokuje open; klient kończy bieżącą próbę, a następnie zamyka się. Brak odpowiedzi zamknięcia przez około 3 sekundy wymusza nieprawidłowe zamknięcie.
readyState: WebSocket.CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3. Stałe istnieją także na obiekcie. url zawiera adres; protocol i extensions są puste. binaryType zawsze wynosi arraybuffer; blob nie jest obsługiwane.
if (ws.readyState === WebSocket.OPEN) ws.send("PING");
ws.close(1000, "Application finished");

Limity, odzyskiwanie i błędy

Ta wersja obsługuje jedno połączenie klienta na aplikację, ws/wss, transfer binarny/tekstowy i weryfikację certyfikatu. Brak serwera WebSocket, podprotokołów, kompresji, obiektów Blob i automatycznego ponownego łączenia. Utwórz nowy obiekt po zamknięciu; w razie potrzeby użyj opóźnionego setTimeout. To gniazdo jest oddzielone od MQTT poprzez ws/wss.

Odbiór czeka na dostępne dane i nie wymaga odpytywania setInterval. Klient wysyła polecenie ping mniej więcej co 30 sekund i czeka do 10 sekund na pong. Operacje sieciowe po połączeniu mają oczekiwania ograniczone w przybliżeniu do 3 sekundy. Zbyt duże wiadomości przychodzące lub nieprawidłowe UTF-8 powodują błąd i zamknięcie. app.stop(), usunięcie aplikacji lub błędy działania powodują zamknięcie połączenia i zwolnienie zasobów; zakończenie aktywnej operacji sieciowej może zająć kilka sekund. JavaScript zdarzenia nie są już uruchamiane po zatrzymaniu.

Kody błędów: INVALID_ARGUMENT, INVALID_STATE, UNSUPPORTED_PROTOCOL, BUSY, QUOTA_EXCEEDED, MESSAGE_TOO_LARGE, HEADERS_TOO_LARGE, OUT_OF_MEMORY, AUTH_FAILED (HTTP 401/403 podczas połączenia), HANDSHAKE_FAILED, NETWORK_ERROR, TLS_OR_NETWORK_ERROR, TIMEOUT, PROTOCOL_ERROR, INVALID_UTF8. W przypadku TLS_OR_NETWORK_ERROR sprawdź łączność, godzinę, nazwę serwera i certyfikat. Awarie kolejki zdarzeń w czasie wykonywania podlegają ogólnym zasadom.

Testy integracyjne

Na komputerze uruchom python tools/websocket-test-server.py --host 0.0.0.0. Ustaw adres komputera w tools/examples/websocket-self-test.js i prześlij plik do Neutron. Testy obejmują UTF-8, fragmenty z pingiem między nimi, puste wiadomości, transmisje binarne do 4096 bajtów i prawidłowe zamknięcie. Przykład wysyłania masy: tools/examples/websocket-scale.js. Serwer obsługuje --cert/--key dla wss oraz --token do testowania Authorization. Użyj odpowiedniego profilu CA dla własnych certyfikatów.

Przetestuj również BIG (odpowiedź zbyt duża), nieprawidłowy certyfikat/token, utratę sieci i zatrzymanie/usunięcie podczas transferu. Testy JavaScript po stronie komputera API nie zastępują testów sieciowych i TLS na urządzeniu.

18. Błędy, try/catch i kontynuacja

Zewnętrzny try { setInterval(...) } catch (...) { ... } wychwytuje błędy rejestracji, a nie późniejsze błędy wywołania zwrotnego. Podobnie, try { asyncOperation() } bez await nie wychwytuje odrzucenia Promise. Złap wewnątrz wywołania zwrotnego lub na zwróconym Promise.
Rozróżniaj synchroniczne wyjątki JavaScript, asynchroniczne odrzucenia Promise i awarie całego środowiska wykonawczego. Standardowe TypeError, ReferenceError, SyntaxError i RangeError mają name/message, ale niekoniecznie code. Błędy operacji i walidacji argumentów zwykle zawierają error.code i error.message.
Tabela 84

Kod

Ogólne znaczenie

INVALID_ARGUMENT

Nieprawidłowy typ/wartość argumentu; szczegóły zależą od wywoływanej funkcji.

QUOTA_EXCEEDED

Przekroczono limit modułów; usuń nieużywane rejestracje.

BUSY

Zasób zajęty, zbyt wiele oczekujących operacji lub pełna kolejka. Poczekaj i ogranicz współbieżność oraz ponawianie prób.

OUT_OF_MEMORY

Niewystarczająca pamięć operacyjna. JavaScript awarie pamięci mogą zamiast tego używać standardowego wyjątku bez tego kodu.

TIMEOUT

Przerwana lub przekroczona limit czasu operacji asynchronicznej. Przed ponowną próbą sprawdź efekt poprzedniej operacji.

Wychwytuj oczekiwane awarie w funkcji, w której występują, aby kontynuować. Wybierz zamknięcie za pomocą app.stop() lub pozostaw błąd bez obsługi. Nie istnieje żadna globalna, konfigurowalna polityka dotycząca błędów API. Samo rejestrowanie błędów konsoli nie powoduje zatrzymania aplikacji.

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();

Nieobsłużone wyjątki/odrzucenia, wyczerpany czas aktywnego wykonywania, nadmierne zagnieżdżenie wywołań lub przepełnienie kolejki zdarzeń zatrzymują aplikację i ustawiają lastError. Wewnętrzne błędy kolejki/budżetu czasu nie muszą dostarczać obiektu z code; status może zawierać EVENT_OVERFLOW lub Active JS execution budget exceeded. Awarie systemowe urządzenia i utrata zasilania nie są wyjątkami JavaScript i nie można ich przechwycić za pomocą try/catch.

Błędy i reakcje specyficzne dla modułu są dokumentowane wraz z ich funkcjami. Ogólne zasady try/catch mają zastosowanie niezależnie od źródła operacji.

19. Limity i planowanie zasobów

Tabela 85

Zasób

Limit / zachowanie

Nazwa / wersja

Nazwa: 1–64 UTF-8 bajtów; wersja: 1–32 bajtów; żadnych znaków kontrolnych. Wersja to tekst, niekoniecznie wersja semantyczna.

Kod źródłowy

Jeden plik UTF-8, 1–131 072 bajtów.

Pamięć aplikacji

1 048 576 bajty dla Neutron AppEngine danych i obiektów; Rozmiar źródła jest sprawdzany osobno.

Zagnieżdżenie funkcji

Unikaj głębokiej rekurencji i długich łańcuchów wywołań. Nadmierne zagnieżdżanie może spowodować awarię aplikacji.

Czas aktywnego wykonywania

Około 1 s na krok przetwarzania środowiska wykonawczego; budżet 5 s podczas walidacji kodu. Nie jest to gwarantowany czas odpowiedzi wagi.

Timery

16 aktywnych timerów.

Operacje współbieżne

Najwyżej 8 oczekujących operacji. Przetwarzaj zdarzenia szybko; nadmierny zaległy ruch może zatrzymać aplikację z EVENT_OVERFLOW.

Konsola

Łącznie 10 wywołań/s, około 512 bajtów treści na wywołanie.

Przesyłanie

768 surowe bajty/fragment; istniejące BLE UI: 192 surowe bajty/fragment; sesja wygasa po 5 minutach braku aktywności.

Bez zdarzeń lub timerów Neutron AppEngine czeka, podczas gdy inne funkcje urządzenia działają normalnie. Oczekiwanie nie zużywa budżetu aktywnego wykonywania JavaScript. Oceniaj obciążenie CPU w rzeczywistej konfiguracji; nie ma tutaj gwarancji stałego procentowego obciążenia CPU.

Ograniczaj wzrost Map/Array, dane na polecenie i ponawianie prób. Timery do powolnej komunikacji zwykle wymagają flagi wysyłania. Nie zbieraj nowych żądań, gdy operacje nie mogą szybko się zakończyć. Pamięć zachowuje zainstalowane aplikacje po restarcie; zmienne JavaScript znikają przy Stop/reset. Do trwałych danych aplikacji używaj udokumentowanego API storage.

20. Instalacja, atrybuty i automatyczne uruchamianie

Tabela 86

Atrybut

Opis

name

Nazwa wyświetlana aplikacji i część przedrostka dziennika JavaScript.

version

Wersja aplikacji użytkownika; niezależnie od interpreterVersion, apiVersion i wersji oprogramowania sprzętowego urządzenia.

autorun

Wartość logiczna: uruchamia się automatycznie po uruchomieniu, chyba że ochrona odzyskiwania blokuje uruchomienie.

size / sha256

Długość i SHA-256 rzeczywistego pliku źródłowego UTF-8 bajtów. SHA-256 nie jest podpisem autora ani substytutem autoryzacji.

W wewnętrznym serwerze WWW lub na stronie BLE wybierz plik, ustaw atrybuty i użyj Upload. Save attributes aktualizuje istniejącą aplikację; Run rozpoczyna nowe wykonanie; Stop żąda zatrzymania; Refresh pokazuje stan; Abort upload anuluje transfer; Delete usuwa zainstalowaną aplikację. Podczas działania busy=true: zatrzymaj i poczekaj przed zmianą atrybutów lub instalacją. Delete podczas działania rozpoczyna zatrzymanie; pierwsza odpowiedź to state=stopping, a usuwanie kończy się później. Sprawdź status pod kątem empty. Status zawiera także runtimeActive, runtimeTaskAllocated i resourcesReleased; po zatrzymaniu wynoszą one false, false i true. Zwalnianie aktywnych żądań komunikacyjnych jest asynchroniczne; w tym czasie nowe Run może zwrócić BUSY. Interpreter nie wykonuje kodu bez działającej aplikacji.

Udane Upload potwierdza zweryfikowany zapisany kod, a nie pomyślnie wykonany program. Następnie użyj Run i sprawdź dzienniki/status. Auto run następuje po inicjalizacji firmware i co najmniej 10 s od uruchomienia urządzenia, a nie przy każdym ponownym połączeniu MQTT. Włączenie autorun w atrybutach nie uruchamia natychmiast ręcznego Run.

Początkowe dane wyjściowe konsoli mogą być niewidoczne, jeśli transport debugowania zostanie odłączony; sprawdź status APP/lastError. Program może pozostać uruchomiony po pojedynczym console.log, ponieważ środowisko wykonawcze czeka na przyszłe zdarzenia.

21. Protokół APP dla klientów i Scale Monitor

Przesyłanie nie wymaga nowego kanału komunikacji. Użyj istniejącej ścieżki uwierzytelnionych poleceń. Jest to protokół dla zewnętrznych klientów zarządzających, a nie funkcje, które aplikacja JavaScript może sama wywołać.

Tabela 87

Transport

Żądanie

Odpowiedź

Wewnętrzne HTTP/HTTPS

Uwierzytelnione POST /api/cmd, Content-Type: text/plain; treść APP <JSON>. Użyj istniejącej sesji logowania urządzenia.

JSON obiekt; sprawdź ok, nie tylko status HTTP.

BLE

Charakterystyka istniejącego polecenia i polecenie APP <JSON> z ramką poświadczeń. Użyj tej samej kolejki/fragmentacji wysyłania, co inne polecenia.
Istniejący kanał powiadomień, APP <JSON> z możliwymi przeplatanymi wynikami debugowania.

MQTT

Temat istniejącego urządzenia CMP/RX. DATA zawiera Base64 pełnego żądania UTF-8 JSON. Opublikuj za pomocą retain=false.

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

Zachowaj istniejące kontrole MID/poświadczeń i uwierzytelnianie MQTT. Zachowane polecenia APP są odrzucane. Przesyłanie MQTT różni się od używania MQTT wewnątrz JavaScript. Zdekodowane żądanie APP JSON ma maksymalnie 2048 bajtów.

21.1 Przesyłanie plików

Przed rozpoczęciem wyślij stop i sprawdź busy=false za pomocą status. Oblicz rozmiar i SHA-256 na podstawie oryginalnych bajtów pliku. Następnie wykonaj begin → sekwencję chunk → commit → status. Czekaj na każdą odpowiedź chunk; nie wysyłaj wszystkich fragmentów równocześnie.

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"}

To schemat wiadomości, a nie gotowy transfer: zastąp size, hash, uploadId i data rzeczywistymi wartościami. begin zwraca uploadId, offset=0 i chunkSize=768. Offset jest pozycją bajtową; podziel bajty przed kodowaniem Base64. Istniejący interfejs BLE używa 192 bajtów źródła na żądanie APP i dodatkowo dzieli wiadomości z ramką uwierzytelniającą na zapisy GATT.

Tabela 88

Operacja

Parametry oprócz op/rid

Wynik / warunki

begin

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

Tworzy sesję; zwraca uploadId, offset i chunkSize. Wymaga co najmniej size × 2 + 4096 wolnych bajtów pamięci. Najpierw przerwij każdą inną aktywną sesję.

chunk

uploadId, offset:integer, data:base64

1–768 zdekodowane bajty. Zwraca potwierdzone całkowite przesunięcie. Poprzedni fragment może zostać powtórzony tylko z identycznymi bajtami znajdującymi się całkowicie w potwierdzonym zakresie.

commit

uploadId

Dozwolone po otrzymaniu wszystkich bajtów. Rozpoczyna asynchroniczną walidację SHA/składni i aktywację; ok=true nie potwierdza zakończenia aktywacji. Odpytuj status do busy=false.

abort

uploadId

Usuwa plik etapowy i sesję. Dozwolone, gdy nie jest zajęty. Sesji należących do innych transportów nie można przejąć za pomocą samego uploadId.

configure

name, version, autorun:boolean

Zmienia wszystkie istniejące atrybuty aplikacji i rozpoczyna asynchroniczną weryfikację/aktywację. Wymaga zainstalowanej aplikacji, braku aktywnego przesyłania i busy=false.

run

—

Uruchamia zainstalowaną aplikację i zwraca stan. Przesyłanie musi zostać zakończone/przerwane i busy=false.

stop

—

Anuluje oczekujący automatyczny start i żąda zatrzymania. Potwierdzenie oznacza przyjęcie polecenia; odpytuj status do zakończenia.

status

—

Aktualny stan, zainstalowane atrybuty, błąd i odzyskiwanie. Dozwolone także podczas wykonywania.

delete

—

Usuwa aktywną aplikację, jej kopię zapasową, pliki pośrednie i zapis odzyskiwania. Najpierw zatrzymaj się i przerwij przesyłanie.

Sprawdź wartość logiczną ok w każdej odpowiedzi. Błąd zwraca ok=false i tekst błędu, inny niż JavaScript Promise error.code. Opcjonalnym rid jest korelacja tekstowa ID do 64 bajtów. Ponów próbę ID tylko z identycznym JSON; różne treści pod tym samym ID są odrzucane. Pamięć podręczna udanych mutacji przechowuje tylko sześć ostatnich żądań na proces, a nie trwałą gwarancję dokładnie raz. W przypadku fragmentów użyj uploadId/offset i potwierdzonych bajtów.

Sesja należy do pierwotnego transportu i uploadId oraz może wygasnąć po 5 minutach bezczynności. Po utracie odpowiedzi sprawdź status/received; nie zgaduj przesunięć. Błąd skrótu/składni nie jest udaną instalacją. Po commit sprawdź name/version/sha256 i lastError.

21.2 Stan i zakończenie operacji

{
  "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": ""
  }
}

Przykład służy ilustracji; odczytuj rzeczywiste wartości. state może być empty, ready, validating, running, stopped, error lub blocked. busy wynosi true także podczas zwykłego długotrwałego wykonywania. Aby sprawdzić zakończenie walidacji, poczekaj na busy=false i sprawdź lastError oraz tożsamość zainstalowanego kodu. Dla Run sprawdź running i monitoruj późniejsze błędy. Pola odzyskiwania lastState i lastResetReason są diagnostyką firmware, a nie stanem protokołu biznesowego.

Tabela 89

Przykładowy błąd APP

Znaczenie / reakcja klienta

BUSY

Wyślij stop i poczekaj na zakończenie; odpytuj status podczas walidacji.

Invalid APP JSON

Nieprawidłowy JSON lub żądanie przekracza 2048 bajtów.

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

Sprawdź długości UTF-8, wartość logiczną autorun, hash i size.

Invalid upload session

Nieprawidłowy uploadId, transport lub wygasła sesja.

Invalid offset / Overlapping chunk / Duplicate chunk differs

Dopasuj offset do potwierdzonego received; nie zmieniaj pliku podczas transferu.

Upload incomplete

Zatwierdź, zanim dotrą wszystkie bajty.

Insufficient filesystem space

Za mało miejsca na bezpieczny transfer i wymianę.

No application installed

run/configure bez zainstalowanej aplikacji.

Application storage not ready / Task allocation failed…

Pamięć lub RAM nie są gotowe; sprawdzaj status/dzienniki i diagnostykę urządzenia.

Lista błędów tekstowych nie jest kompletna. Zachowaj pełne error/lastError w diagnostyce klienta. Przekroczenie czasu klienta zewnętrznego nie dowodzi odrzucenia przez urządzenie.

22. Automatyczne uruchamianie i ochrona przed awariami

Przed uruchomieniem Neutron AppEngine przechowuje tożsamość aplikacji i monitoruje powodzenie uruchamiania. Nieoczekiwane ponowne uruchomienie urządzenia w tym okresie powoduje zarejestrowanie niestabilnej próby następnego uruchomienia. Po trzech kolejnych niestabilnych próbach uruchomienie automatyczne jest blokowane przed czwartą próbą automatyczną. Kod pozostaje przechowywany do kontroli lub wymiany.

Nieoczekiwane resetowanie spowodowane awarią systemu lub problemami z zasilaniem może zwiększyć licznik niestabilnych prób. Normalne włączenie i planowane ponowne uruchomienie są traktowane inaczej niż awarie aplikacji. Sama niestabilna próba nie dowodzi defektu kodu użytkownika; sprawdź także diagnostykę urządzenia.

Około 60 s potwierdzonej pracy zeruje sekwencję błędów, wliczając zwykłe oczekiwanie na zdarzenia, a nie wyłącznie czas CPU. Zwykłe Stop zamyka znacznik. Istniejąca blokada auto run pozostaje do udanej jawnej instalacji lub Save attributes/configure. Ręczne Run nadal jest możliwe i jest monitorowane. Błąd zapisu rekordu odzyskiwania może ze względów ochronnych uniemożliwić Run.

Zwykły nieobsługiwany błąd JavaScript zatrzymuje aplikację i ustawia lastError; różni się to od resetu modułu. Domyślne ustawienie fabryczne usuwa zainstalowany kod, jego kopię zapasową, pliki tymczasowe, stan odzyskiwania i pamięć aplikacji, w tym lokalne bazy danych. JavaScript try/catch nie może zapobiec resetowaniu sprzętu.

23. Zasady dla ScaleGuru AI i integratorów

Użyj tej sekcji jako umowy na generowanie aplikacji. ScaleGuru AI powinien zwrócić jeden kompletny plik UTF-8 . js i osobno wymienić wymaganą konfigurację systemu i kroki testowe. Dokumentacja nie upoważnia automatycznie AI do przesłania lub wykonania kodu na urządzeniu użytkownika.

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 Testy przed wydaniem aplikacji

Tabela 90

Test

Oczekiwany wynik

Urządzenie bez ważnego pomiaru

Brak niekontrolowanego wyjątku; aplikacja wyraźnie raportuje niedostępny pomiar.

Wiele poleceń w jednym odbiorze

Obsługuj każde polecenie; rozważ kolejność odpowiedzi dla poleceń asynchronicznych.

Waga zajęta / operacja odrzucona

Oczekiwane odrzucenie jest obsługiwane bez nieskończonych ponownych prób.

Zatrzymaj bez aktywnych liczników czasu

Bezczynne środowisko wykonawcze budzi się i kończy normalnie.

Uruchom ponownie z automatycznym uruchomieniem

Uruchamia się zweryfikowana zainstalowana wersja; sprawdzane są lastError i recovery.

24. Zmiany i powiązana dokumentacja

Tabela 91

Instrukcja

Data

Zmiany

1.0

15. 11. 2026

Pierwsze wydanie API: środowisko wykonawcze, waga, I/O, ustawienia modułu, pliki, lokalna baza danych, TCP, interfejsy szeregowe, MQTT, REST/HTTP, protokół APP i ochrona uruchamiania.

Powiązana dokumentacja: CSCP — protokół komunikacyjny Neutron. CSCP opisuje polecenia i konfigurację systemową; nie stają się one automatycznie funkcjami JavaScript. Ta dokumentacja ma układ: cel, składnia, parametry, wynik, błędy i przykład.

Przykłady są dołączone jako statyczny kod i pozostają czytelne bez JavaScript. Wyszukiwanie na stronie, kopiowanie kodu i drukowanie to narzędzia dokumentacji; nie wykonują aplikacji ani nie komunikują się z urządzeniem. Dokumentacja nie jest osadzona w firmware.

Często zadawane pytania

Czy mogę używać Node.js, npm lub API przeglądarki?

Nie. Prześlij jeden skrypt JavaScript w kodowaniu UTF-8 i korzystaj z udokumentowanych API neutron-js-1. Node.js, npm, DOM, import/export oraz await na najwyższym poziomie są niedostępne.

Jak sprawdzić dostępne funkcje?

Wywołaj app.capabilities() na urządzeniu. Przed użyciem funkcji sprawdź apiVersion, interpreterVersion, features oraz limity poszczególnych modułów.

Czy dane aplikacji pozostają po Stop i restarcie?

Zmienne JavaScript nie pozostają. Pliki i lokalne bazy rekordów w storage są zachowywane po Stop, restarcie i zwykłym zastąpieniu aplikacji. Przywrócenie ustawień fabrycznych usuwa te dane.

Kiedy należy włączyć Auto run?

Najpierw prześlij aplikację, uruchom ją ręcznie i przetestuj wymagane zachowanie, limity oraz przypadki błędów. Włącz Auto run dopiero po testach funkcjonalnych. Ochrona uruchamiania może zablokować powtarzające się niestabilne automatyczne uruchomienia.

Potrzebujesz pomocy?

Potrzebujesz pomocy z oprogramowaniem, łącznością lub obsługą rozwiązania? Opisz problem, abyśmy mogli pomóc w następnym kroku.

Przygotuj zgłoszenie →