CSCP — CloudScale Communication Protocol
Polecenia CSCP dla Neutron: struktura komunikatów, ważenie, konfiguracja, liczenie, ważenie kontrolne oraz cyfrowe I/O.
NEUTRON APPENGINE · INSTRUKCJA DLA PROGRAMISTÓW
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.
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-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ę.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 |
.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.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.
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();
});Unikaj blokowania: nie używajwhile (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.
TIMEOUT during application startup (limit 1000 ms). Przerwanie wykonywania nie powoduje automatycznego restartu modułu.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. |
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.const capabilities = app.capabilities();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
}
}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);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.app.stop();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();
}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.console.log(...values);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 });console.info(...values);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 });console.warn(...values);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 });console.error(...values);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 });console.debug(...values);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.
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.
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.const id = setTimeout(callback, delayMs = 0, ...args);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");const id = setInterval(callback, delayMs = 0, ...args);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);clearTimeout(id);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);clearInterval(id);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);const measurement = scale.read();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);
}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ć. |
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.const measurement = await scale.tare();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();const measurement = await scale.zero();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();const measurement = await scale.clearTare();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();const measurement = await scale.setPresetTare(value);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.
const response = await scale.cmd(command, { timeoutMs });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.
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ń. |
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. |
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);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.
const input = io.input(1);
const output = io.output(1);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);const inputState = io.input(1).read();
const outputState = io.output(1).read();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());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. |
await io.input(1).configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });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" });await io.output(1).configure({ function: "disabled" });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));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 |
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.
await io.output(1).claim({ safeState: false });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);await io.output(1).write(true);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);await io.output(1).release();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("change", callback);
pin.once("change", callback);
pin.off("change", callback);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);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;
}
});const count = io.input(1).counter();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() }));await io.input(1).resetCounter();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());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.
});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. |
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.
const raw = await device.cmd("RMD");
const result = await device.cmd("SMD;S0B=19200;S0P=0;");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");
}const values = await device.settings.read(["S0B", "S0P"]);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);const page = await device.settings.list({ cursor: null, limit: 16 });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);const result = await device.settings.write({ S0B: "19200", S0P: "0" });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");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(); });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.
const info = await storage.info();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);await storage.write(name, data);
await storage.writeText(name, text);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]));await storage.append(name, data);
await storage.appendText(name, text);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");const bytes = await storage.read(name, { offset: 0, length: 4096 });
const text = await storage.readText(name);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;
}const page = await storage.list({ cursor: null, limit: 16 });
const info = await storage.stat("data.bin");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);const removed = await storage.remove("old.jsonl");
await storage.rename("measurements.jsonl", "archive.jsonl");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");const page = await storage.findText("measurements.jsonl", "ART-001", { offset: 0, limit: 16 });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);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(); });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. |
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.
const articles = await storage.openRecords("articles", { key: "code" });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());await articles.put({ code: "ART-001", name: "Flour", target: 25 });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.const article = await articles.get("ART-001");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);const deleted = await articles.delete("ART-001");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);const page = await articles.list({ cursor: null, limit: 16 });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);const status = await articles.stat();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());await articles.compact();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());await articles.close();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();
}const removed = await storage.removeRecords("articles");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");// 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();
});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. |
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.
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 |
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().
const status = await tcp.configure(options);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.const result = await tcp.claim();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(); });const result = await tcp.release();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();const bytesWritten = await tcp.write(data, { connectionId });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);
}
});tcp.on(eventName, callback);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.once(eventName, callback);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);
});tcp.off(eventName, callback);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);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);
});event.connectionId; nigdy nie zapisuj go trwale ani nie wymyślaj identyfikatorów.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); }
});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. |
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. |
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.
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,< code>. |
PRESET_TARE 2.5 | Ustawia tarę w aktualnie skonfigurowanej jednostce; zwraca OK lub ERR,< code>. |
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.
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.
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. |
const status = tcp.status();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();
});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.rs485const result = await port.claim();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));const result = await port.configure(options);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));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.
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.
const bytes = await port.write(data, { timeoutMs });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));await port.drain({ timeoutMs });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));const result = await port.release();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));port.on(eventName, callback);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);port.once(eventName, callback);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);port.off(eventName, callback);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);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.
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();
});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ą. |
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 wymagaclaim().
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.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.
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.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ę.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.await mqtt.configure(options);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
});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.
await mqtt.connect({ timeoutMs: 15000 });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();
}await mqtt.disconnect();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();const status = mqtt.status();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);await mqtt.subscribe("factory/+/command", { qos: 1, timeoutMs: 10000 });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 });await mqtt.unsubscribe("factory/scale-01/command");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 });await mqtt.publish(topic, payload, { qos: 1, retain: false });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(eventName, callback);
mqtt.once(eventName, callback);
mqtt.off(eventName, callback);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));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. |
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.
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. |
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();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.
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();
});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. |
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.
const response = await fetch(url, options);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));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.
const response = await fetch("https://api.example.com/articles/ART-001");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());const text = await response.text();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);const value = await response.json();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.const buffer = await response.arrayBuffer();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);const contentType = response.headers.get("Content-Type");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);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 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.
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=< PEM>. 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);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.
// 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);
}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.
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. |
fetch() dla REST i mqtt dla brokera MQTT.ws://, wss://, DNS i IPv4. Sprawdź app.capabilities().features.websocket; limity znajdują się w app.capabilities().websocket.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.
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);/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.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.
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]));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);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");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.
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.
Zewnętrznytry { 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.
error.code i error.message.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.
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.
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.
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ć.
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.
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.
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.
{
"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.
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.
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.
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.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. |
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. |
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.
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.
Wywołaj app.capabilities() na urządzeniu. Przed użyciem funkcji sprawdź apiVersion, interpreterVersion, features oraz limity poszczególnych modułów.
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.
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.
Polecenia CSCP dla Neutron: struktura komunikatów, ważenie, konfiguracja, liczenie, ważenie kontrolne oraz cyfrowe I/O.
Dokumentacja Neutron Modbus RTU/TCP do integracji z PLC, SCADA i HMI: połączenie, adresowanie, rejestry, kalibracja i sterowanie automatyczną wagą kontrolną.
Integracja OPC UA z Neutron: bezpieczne połączenia, dane ważenia na żywo, przechwytywanie stabilnego pomiaru i integracja z PLC/SCADA.
Potrzebujesz pomocy z oprogramowaniem, łącznością lub obsługą rozwiązania? Opisz problem, abyśmy mogli pomóc w następnym kroku.