TECNOLOGIA DI PESATURA · SVILUPPO INTERNO · ASSISTENZA
+386 2 320 33 46info@preciz.si

NEUTRON APPENGINE · MANUALE PER SVILUPPATORI

Neutron AppEngine — sviluppo di applicazioni JavaScript

Sviluppo di applicazioni JavaScript per CloudScaleLink Neutron e CloudScale Neutron NS: ambiente di esecuzione, pesatura, I/O digitali, impostazioni, archiviazione, moduli di comunicazione e gestione delle applicazioni. Manuale 1.0 · Neutron AppEngine 1.0.0 · API 1 · Data di pubblicazione: 16 novembre 2026.

1. Scopo e ambito

Neutron AppEngine è disponibile per il modulo CloudScaleLink Neutron e per i moduli di pesatura CloudScale Neutron NS con firmware versione 2.7 o successiva.

Neutron AppEngine consente di sviluppare applicazioni JavaScript personalizzate direttamente sui moduli di pesatura CloudScaleLink Neutron e Neutron. Le applicazioni possono leggere le misurazioni, eseguire operazioni di pesatura, utilizzare timer e collegarsi a sistemi esterni tramite i moduli di comunicazione supportati (MQTT, TCP, WebSocket, REST, RS-232 e RS-485).
Questo manuale è destinato a sviluppatori, integratori e sistemi di IA che preparano applicazioni da utilizzare con Neutron.
Questo manuale descrive il profilo neutron-js-1, apiVersion: 1, alla data del 16 novembre 2026. La versione del manuale è 1.0 e quella dell’interprete Neutron AppEngine è 1.0.0. Tutte le funzioni, gli eventi, le proprietà e le operazioni implementati e descritti qui sono disponibili dalla versione 1.0.0. La sola versione del firmware non conferma il supporto di ogni funzionalità: verificare app.capabilities() sul dispositivo e provare l’applicazione.
Tabella 1

Area

Stato

Interfaccia

Esecuzione JavaScript

Implementato

Interprete Neutron AppEngine; una sola applicazione utente memorizzata in modo persistente

Ambiente di esecuzione e diagnostica

Implementato

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

Timer

Implementato

setTimeout, setInterval, annullamento tramite ID

Bilancia

Implementato

Lettura del peso, tara, azzeramento, tara preimpostata e invio di comandi CSCP con scale.cmd()

Client / server TCP

Implementato

Riserva dell’interfaccia TCP esistente, gestione degli eventi e invio di dati

MQTT

Implementato

Broker utente indipendente; mqtt, mqtts, ws e wss

RS-232 / RS-485

Implementato

serial.rs232 e serial.rs485; riserva, configurazione SMD, eventi e invio

Installazione

Implementato

BLE, HTTP/HTTPS interno e MQTT tramite il canale APP esistente

Ingressi/uscite digitali

Implementato

io.input(1..6), io.output(1..6); configurazione, eventi, riserva delle uscite e contatori

Parametri e applicazione di conteggio

Tramite i comandi CSCP supportati

scale.cmd() esegue i comandi supportati dal dispositivo; un’API JavaScript counting.* separata non è ancora disponibile.

Impostazioni del modulo

Implementato

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

File e database locale

Implementato

storage; openRecords e ricerca indicizzata per chiave

REST/HTTP da JavaScript

Implementato

fetch per HTTP/HTTPS; stato, intestazioni, testo, JSON e risposte binarie

Il file è un normale script .js UTF-8. La dimensione è misurata in byte, non in righe o caratteri, con un massimo di 131 072 byte. Non è un modulo ES: import/export, await al livello principale, Node.js, npm e il DOM non sono disponibili. Utilizzare globalThis, gli oggetti JavaScript standard, Promise, async/await, Map, JSON e Uint8Array. Le API browser TextEncoder/TextDecoder non fanno parte di questo profilo.

2. La prima applicazione

Salvare il codice seguente come first-application.js, caricarlo e selezionare Run. Incrementa un contatore ogni secondo e lo scrive sul canale di debug configurato. Non è richiesta alcuna configurazione della bilancia o della comunicazione.
let counter = 0;
setInterval(() => {
    counter += 1;
    console.log("Counter:", counter);
}, 1000);

Nell’interfaccia HTTP/HTTPS locale o nella pagina BLE, aprire JS application o App, selezionare il file, inserirne nome e versione, quindi selezionare Upload. Dopo la convalida, selezionare Run. Utilizzare Stop per arrestare l’applicazione e Refresh per verificarne lo stato e l’ultimo errore. Attivare Auto run solo dopo i test.

Per l’inizializzazione asincrona, definire e chiamare una funzione. start è un nome arbitrario definito dall’utente, senza significato speciale per l’ambiente di esecuzione.
async function start() {
    const caps = app.capabilities();
    if (caps.apiVersion !== 1) {
        throw new Error("Unsupported API version");
    }
    console.info("Application ready", caps.runtime);
}
start().catch(error => {
    console.error(error.code || "START_FAILED", error.message);
    app.stop();
});

3. Ambiente di esecuzione, eventi e ciclo di vita

Evitare i blocchi: non utilizzare while (true), attesa attiva, ricorsione profonda o catene infinite di Promise. L’ambiente di esecuzione consente circa 1 s di tempo attivo per fase di elaborazione; l’attesa sospesa di un evento non consuma questo budget. Superarlo o causare l’overflow di una coda può arrestare l’applicazione; non utilizzare questo comportamento come normale meccanismo di controllo.
La preparazione dell’ambiente e la compilazione dell’applicazione hanno limiti di tempo separati, fino a 5 secondi per fase. Il limite di compilazione è lo stesso durante il caricamento e l’avvio. L’esecuzione iniziale del codice utente riceve quindi un nuovo limite di un secondo; lo stesso limite si applica all’elaborazione di eventi e timer. L’attesa di risposte di rete o timer non consuma questo budget. TIMEOUT indica la fase e il limite, ad esempio TIMEOUT during application startup (limit 1000 ms). L’interruzione dell’esecuzione non riavvia automaticamente il modulo.
Tabella 2

Passaggio

Comportamento

Installazione

Il codice sorgente e gli attributi sono salvati nella memoria del dispositivo. Integrità e sintassi vengono controllate senza eseguire il codice utente.

Run

Ogni esecuzione crea un nuovo contesto JavaScript. Lo script iniziale viene eseguito una sola volta; le variabili di un’esecuzione precedente non vengono conservate.

Attesa

Al termine dello script iniziale, l’ambiente di esecuzione rimane attivo, in attesa del timer o evento successivo. Quando non c’è lavoro, Neutron AppEngine attende senza eseguire codice utente.

Evento

Un evento di un modulo supportato, la scadenza di un timer o il risultato di un’operazione attiva l’elaborazione corrispondente in Neutron AppEngine. Una Promise in sospeso viene risolta o rifiutata.

Arresto o errore

I timer e il contesto vengono rimossi. Stop non annulla gli effetti delle operazioni già eseguite.

Nuova esecuzione

Arrestare prima l’esecuzione precedente e attendere busy: false. Anche l’installazione di una nuova versione richiede che l’applicazione sia arrestata.
Neutron AppEngine esegue le callback in sequenza. Gestire rapidamente gli eventi ed evitare un numero illimitato di operazioni in sospeso. await cede l’esecuzione, consentendo ad altre callback di essere eseguite durante l’attesa. Una callback asincrona non è quindi una transazione che blocca gli altri eventi.

4. API dell’applicazione

4.1 app.capabilities()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const capabilities = app.capabilities();
Scopo. Verificare le funzionalità e i limiti supportati prima di utilizzare un’API.
Descrizione. Restituisce in modo sincrono un nuovo oggetto che indica supporto, versioni e limiti. Non inizializza i singoli moduli e non ne garantisce la disponibilità corrente.

Parametri

Nessun parametro.

Risultato

L’oggetto mostrato di seguito. Le proprietà features indicano il supporto dei moduli. Le impostazioni e i limiti di ogni modulo sono spiegati nel relativo capitolo.

Errori e considerazioni particolari

Non restituisce una Promise. Non dedurre il supporto delle funzionalità dal solo nome del dispositivo o dalla versione dell’applicazione.

Esempio

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
  }
}
Leggere la versione con app.capabilities().interpreterVersion e il nome con app.capabilities().interpreter. interpreterVersion identifica la versione del prodotto Neutron AppEngine, apiVersion il contratto dell’API e runtime il profilo. Questi valori sono distinti dalla versione dell’applicazione utente e dalla versione del firmware del dispositivo. Versioni attuali: Neutron AppEngine 1.0.0, API 1 e manuale 1.0.
console.info(app.capabilities().interpreter, app.capabilities().interpreterVersion);
All’avvio del dispositivo, Neutron AppEngine interpreter v1.0.0 viene registrato al livello INFO. La visibilità dipende dalle impostazioni del canale e del livello di debug. Utilizzare capabilities per verificare dall’applicazione utente.

4.2 app.stop()

Disponibile dalla versione: Neutron AppEngine 1.0.0
app.stop();
Scopo. Arrestare normalmente l’applicazione utente.
Descrizione. Richiede l’arresto dell’esecuzione e impedisce ulteriori callback. Non reimposta il modulo. Rilascia le risorse riservate dall’applicazione; il comportamento specifico delle risorse è descritto nel capitolo del relativo modulo.

Parametri

Nessun parametro.

Risultato

undefined. È una richiesta, non una Promise che conferma l’arresto. Utilizzare lo stato APP per una conferma esterna.

Errori e considerazioni particolari

Non annulla le operazioni già eseguite. Utilizzare return dopo la chiamata se le istruzioni successive nella funzione corrente non devono essere eseguite. Non esiste una callback di arresto utente.

Esempio

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

5. Diagnostica e console

La console invia l’output al sistema di debug Neutron, non alla console del browser. Le impostazioni di debug esistenti DI e DL selezionano l’uscita e il livello. I messaggi ricevono il prefisso [JS:application name]. La configurazione e la connessione del trasporto correnti determinano dove sono visibili i messaggi.

5.1 console.log(...)

Disponibile dalla versione: Neutron AppEngine 1.0.0
console.log(...values);
Scopo. Registrare misurazioni o stato.
Descrizione. Unisce gli argomenti separandoli con spazi. Tenta JSON.stringify per gli oggetti e la conversione in testo per gli altri valori. Sostituisce i caratteri di controllo con spazi. Tutti i metodi console condividono lo stesso limite di registrazione.

Parametri

Tabella 3

Parametro

Tipo / requisito

Descrizione

values

qualsiasi valore JavaScript / facoltativo

Zero o più argomenti. Evitare oggetti di grandi dimensioni e strutture circolari.

Risultato

undefined; log INFO, visibile con DL ≥ 3 e un DI appropriato.

Errori e considerazioni particolari

La registrazione non arresta di per sé l’applicazione, nemmeno console.error(). Il limite condiviso è di 10 chiamate/s e circa 512 byte di contenuto per chiamata, escluso il prefisso. L’output in eccesso viene rifiutato o troncato; può apparire un ulteriore avviso sul limite di frequenza. Gli errori di conversione o memoria possono generare un’eccezione JavaScript.

Esempio

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

5.2 console.info(...)

Disponibile dalla versione: Neutron AppEngine 1.0.0
console.info(...values);
Scopo. Segnalare informazioni di avvio o di stato.
Descrizione. Unisce gli argomenti separandoli con spazi. Tenta JSON.stringify per gli oggetti e la conversione in testo per gli altri valori. Sostituisce i caratteri di controllo con spazi. Tutti i metodi console condividono lo stesso limite di registrazione.

Parametri

Tabella 4

Parametro

Tipo / requisito

Descrizione

values

qualsiasi valore JavaScript / facoltativo

Zero o più argomenti. Evitare oggetti di grandi dimensioni e strutture circolari.

Risultato

undefined; log INFO, visibile con DL ≥ 3 e un DI appropriato.

Errori e considerazioni particolari

La registrazione non arresta di per sé l’applicazione, nemmeno console.error(). Il limite condiviso è di 10 chiamate/s e circa 512 byte di contenuto per chiamata, escluso il prefisso. L’output in eccesso viene rifiutato o troncato; può apparire un ulteriore avviso sul limite di frequenza. Gli errori di conversione o memoria possono generare un’eccezione JavaScript.

Esempio

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

5.3 console.warn(...)

Disponibile dalla versione: Neutron AppEngine 1.0.0
console.warn(...values);
Scopo. Registrare un avviso o un problema gestito.
Descrizione. Unisce gli argomenti separandoli con spazi. Tenta JSON.stringify per gli oggetti e la conversione in testo per gli altri valori. Sostituisce i caratteri di controllo con spazi. Tutti i metodi console condividono lo stesso limite di registrazione.

Parametri

Tabella 5

Parametro

Tipo / requisito

Descrizione

values

qualsiasi valore JavaScript / facoltativo

Zero o più argomenti. Evitare oggetti di grandi dimensioni e strutture circolari.

Risultato

undefined; log WARN, visibile con DL ≥ 2 e un DI appropriato.

Errori e considerazioni particolari

La registrazione non arresta di per sé l’applicazione, nemmeno console.error(). Il limite condiviso è di 10 chiamate/s e circa 512 byte di contenuto per chiamata, escluso il prefisso. L’output in eccesso viene rifiutato o troncato; può apparire un ulteriore avviso sul limite di frequenza. Gli errori di conversione o memoria possono generare un’eccezione JavaScript.

Esempio

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

5.4 console.error(...)

Disponibile dalla versione: Neutron AppEngine 1.0.0
console.error(...values);
Scopo. Descrivere un errore.
Descrizione. Unisce gli argomenti separandoli con spazi. Tenta JSON.stringify per gli oggetti e la conversione in testo per gli altri valori. Sostituisce i caratteri di controllo con spazi. Tutti i metodi console condividono lo stesso limite di registrazione.

Parametri

Tabella 6

Parametro

Tipo / requisito

Descrizione

values

qualsiasi valore JavaScript / facoltativo

Zero o più argomenti. Evitare oggetti di grandi dimensioni e strutture circolari.

Risultato

undefined; log ERROR, visibile con DL ≥ 1 e un DI appropriato.

Errori e considerazioni particolari

La registrazione non arresta di per sé l’applicazione, nemmeno console.error(). Il limite condiviso è di 10 chiamate/s e circa 512 byte di contenuto per chiamata, escluso il prefisso. L’output in eccesso viene rifiutato o troncato; può apparire un ulteriore avviso sul limite di frequenza. Gli errori di conversione o memoria possono generare un’eccezione JavaScript.

Esempio

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

5.5 console.debug(...)

Disponibile dalla versione: Neutron AppEngine 1.0.0
console.debug(...values);
Scopo. Registrare dettagli durante lo sviluppo.
Descrizione. Unisce gli argomenti separandoli con spazi. Tenta JSON.stringify per gli oggetti e la conversione in testo per gli altri valori. Sostituisce i caratteri di controllo con spazi. Tutti i metodi console condividono lo stesso limite di registrazione.

Parametri

Tabella 7

Parametro

Tipo / requisito

Descrizione

values

qualsiasi valore JavaScript / facoltativo

Zero o più argomenti. Evitare oggetti di grandi dimensioni e strutture circolari.

Risultato

undefined; log DEBUG, visibile con DL ≥ 4 e un DI appropriato.

Errori e considerazioni particolari

La registrazione non arresta di per sé l’applicazione, nemmeno console.error(). Il limite condiviso è di 10 chiamate/s e circa 512 byte di contenuto per chiamata, escluso il prefisso. L’output in eccesso viene rifiutato o troncato; può apparire un ulteriore avviso sul limite di frequenza. Gli errori di conversione o memoria possono generare un’eccezione JavaScript.

Esempio

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

Il livello di debug può filtrare l’output. Non utilizzare la console come trasporto affidabile dei dati aziendali. Per uno scambio affidabile dei dati, utilizzare un modulo di comunicazione supportato adatto.

6. Timer

Un timer specifica il primo istante previsto per l’esecuzione. Questo non è un ambiente JavaScript con garanzie di tempo reale rigide: misurazione, comunicazione, callback precedenti e pianificazione possono ritardare l’esecuzione. Gli intervalli mancati non creano una coda illimitata di chiamate di recupero.

Una callback periodica async può essere ancora in attesa quando arriva l’intervallo successivo. Utilizzare un indicatore di occupato o pianificare il successivo setTimeout dopo il completamento dell’operazione. Lo stesso vale per gli eventi di qualsiasi modulo: se l’elaborazione deve essere sequenziale, implementare una coda limitata o rifiutare nuovo lavoro finché l’operazione precedente non termina.

6.1 setTimeout()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const id = setTimeout(callback, delayMs = 0, ...args);
Scopo. Eseguire una funzione una sola volta dopo un ritardo.
Descrizione. Restituisce immediatamente; la callback viene eseguita in seguito. Il timer viene rimosso dall’insieme attivo prima di chiamare la callback, che può quindi pianificare un’altra esecuzione.

Parametri

Tabella 8

Parametro

Tipo / requisito

Descrizione

callback

function / obbligatorio

Una funzione; il codice fornito come stringa non è supportato.

delayMs

number / facoltativo, valore predefinito 0

Convertito in un numero e in un intero. I ritardi non validi, negativi o pari a zero diventano almeno 1 ms. Massimo: 2 147 483 647 ms.

...args

qualsiasi valore / facoltativo

Argomenti passati alla callback dall’ambiente di esecuzione.

Risultato

ID numerico accettato da clearTimeout. Valido solo durante l’esecuzione corrente dell’applicazione.

Errori e considerazioni particolari

INVALID_ARGUMENT sincrono se la callback non è una funzione; QUOTA_EXCEEDED se sono già attivi 16 timer. Un’eccezione o un rifiuto della callback non gestiti possono arrestare l’applicazione.

Esempio

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

6.2 setInterval()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const id = setInterval(callback, delayMs = 0, ...args);
Scopo. Leggere o inviare dati periodicamente.
Descrizione. La prima chiamata avviene dopo il ritardo. Le callback successive sono pianificate periodicamente; l’ambiente di esecuzione non attende le Promise restituite dalle callback async. I ritardi non causano esecuzioni di recupero illimitate.

Parametri

Tabella 9

Parametro

Tipo / requisito

Descrizione

callback

function / obbligatorio

Una funzione; il codice fornito come stringa non è supportato.

delayMs

number / facoltativo, valore predefinito 0

Convertito in un numero e in un intero. I ritardi non validi, negativi o pari a zero diventano almeno 1 ms. Massimo: 2 147 483 647 ms.

...args

qualsiasi valore / facoltativo

Argomenti passati alla callback dall’ambiente di esecuzione.

Risultato

ID numerico accettato da clearInterval. L’intervallo rimane attivo finché non viene annullato o l’applicazione si arresta.

Errori e considerazioni particolari

Gli stessi errori sincroni di setTimeout. Proteggere il lavoro asincrono dalle sovrapposizioni e intercettare i rifiuti all’interno della funzione async.

Esempio

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

6.3 clearTimeout()

Disponibile dalla versione: Neutron AppEngine 1.0.0
clearTimeout(id);
Scopo. Annullare le future esecuzioni del timer.
Descrizione. Entrambe le funzioni utilizzano lo stesso registro dei timer e possono annullare entrambi i tipi. Si consiglia di utilizzare la coppia set/clear corrispondente.

Parametri

Tabella 10

Parametro

Tipo / requisito

Descrizione

id

number / obbligatorio

ID restituito da setTimeout o setInterval. Convertito con Number(id).

Risultato

undefined. Un ID sconosciuto non ha effetto.

Errori e considerazioni particolari

Non interrompe una callback o un’operazione asincrona già iniziata. Convertire in numero un valore JavaScript non adatto può generare un’eccezione JavaScript standard.

Esempio

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

6.4 clearInterval()

Disponibile dalla versione: Neutron AppEngine 1.0.0
clearInterval(id);
Scopo. Annullare le future esecuzioni del timer.
Descrizione. Entrambe le funzioni utilizzano lo stesso registro dei timer e possono annullare entrambi i tipi. Si consiglia di utilizzare la coppia set/clear corrispondente.

Parametri

Tabella 11

Parametro

Tipo / requisito

Descrizione

id

number / obbligatorio

ID restituito da setTimeout o setInterval. Convertito con Number(id).

Risultato

undefined. Un ID sconosciuto non ha effetto.

Errori e considerazioni particolari

Non interrompe una callback o un’operazione asincrona già iniziata. Convertire in numero un valore JavaScript non adatto può generare un’eccezione JavaScript standard.

Esempio

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

7. API della bilancia

7.1 scale.read()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const measurement = scale.read();
Scopo. Leggere l’ultima istantanea disponibile della bilancia senza attendere la stabilità.
Descrizione. Restituisce in modo sincrono l’ultima istantanea disponibile dei dati della bilancia. Non avvia una nuova misurazione. Leggere un solo oggetto e utilizzarne i campi insieme per ottenere valori coerenti di netto/lordo/tara.

Parametri

Nessun parametro.

Risultato

Un oggetto con i campi seguenti. Quando la misurazione non è disponibile, net, gross e tare sono NaN e stable è false. Unità e stato rimangono informazioni diagnostiche.

Errori e considerazioni particolari

Una bilancia non disponibile viene segnalata come available=false anziché con un’eccezione NO_MEASUREMENT. available=true non implica stable=true. Una chiamata sincrona può generare un’eccezione se la memoria JavaScript è esaurita.

Esempio

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

Campo

Tipo

Significato

available

boolean

La bilancia è disponibile, l’interfaccia di pesatura è abilitata e la misurazione è valida.

net

number

Peso netto calcolato da lordo e tara, arrotondato alle cifre decimali configurate.

gross

number

Peso lordo nell’unità configurata.

tare

number

Tara corrente nell’unità configurata.

stable

boolean

La misurazione valida è stabile secondo la configurazione corrente della bilancia.

unit

string

Unità corrente della bilancia, ad esempio kg o g. Non è necessariamente kg.

status

number

Valore di stato corrente della bilancia. Il profilo JavaScript non fornisce un’enumerazione con nomi separata; non inventare corrispondenze dei codici.

sequence

number

Contatore a 32 bit delle misurazioni pubblicate; riparte da zero in caso di overflow. Non è un ID persistente di un record di pesatura.

timeMs

number

Istante dell’ultima pubblicazione di una misurazione in millisecondi dall’avvio del dispositivo. Non è UTC; questo contatore a 32 bit può ripartire da zero.

Le scorciatoie scale.net, scale.gross e scale.available sono getter dinamici che leggono una nuova istantanea a ogni accesso. scale.tare è una funzione; ottenere la tara numerica da scale.read().tare. Non utilizzare due getter separati per una coppia lordo/netto che deve condividere la stessa istantanea.

7.2 scale.tare()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const measurement = await scale.tare();
Scopo. Eseguire la tara con il carico corrente.
Descrizione. Esegue la funzione corrispondente della bilancia senza aggirare stabilità, intervallo, protezione, comandi concorrenti o configurazione. Esegue il comando di pesatura T; non è una tara immediata con TI.

Parametri

Nessun parametro.

Risultato

Promise<Measurement>: dopo una risposta riuscita, legge una nuova istantanea JavaScript con la struttura di scale.read(). Non garantisce che sia arrivata la misurazione successiva; monitorare le misurazioni successive per confermare l’effetto.

Errori e considerazioni particolari

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED o TIMEOUT. Gestire le Promise rifiutate con await/try/catch. L’arresto distrugge il contesto; la continuazione della Promise non è garantita.

Esempio

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

7.3 scale.zero()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const measurement = await scale.zero();
Scopo. Azzerare la bilancia.
Descrizione. Esegue la funzione corrispondente della bilancia senza aggirare stabilità, intervallo, protezione, comandi concorrenti o configurazione. Esegue Z, che è diverso dalla tara. Il successo dipende dalle condizioni operative e dall’intervallo di azzeramento consentito.

Parametri

Nessun parametro.

Risultato

Promise<Measurement>: dopo una risposta riuscita, legge una nuova istantanea JavaScript con la struttura di scale.read(). Non garantisce che sia arrivata la misurazione successiva; monitorare le misurazioni successive per confermare l’effetto.

Errori e considerazioni particolari

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED o TIMEOUT. Gestire le Promise rifiutate con await/try/catch. L’arresto distrugge il contesto; la continuazione della Promise non è garantita.

Esempio

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

7.4 scale.clearTare()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const measurement = await scale.clearTare();
Scopo. Cancellare la tara.
Descrizione. Esegue la funzione corrispondente della bilancia senza aggirare stabilità, intervallo, protezione, comandi concorrenti o configurazione. Esegue TAC per richiedere la rimozione della tara corrente.

Parametri

Nessun parametro.

Risultato

Promise<Measurement>: dopo una risposta riuscita, legge una nuova istantanea JavaScript con la struttura di scale.read(). Non garantisce che sia arrivata la misurazione successiva; monitorare le misurazioni successive per confermare l’effetto.

Errori e considerazioni particolari

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED o TIMEOUT. Gestire le Promise rifiutate con await/try/catch. L’arresto distrugge il contesto; la continuazione della Promise non è garantita.

Esempio

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

7.5 scale.setPresetTare(value)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const measurement = await scale.setPresetTare(value);
Scopo. Impostare una tara predefinita.
Descrizione. Esegue la funzione corrispondente della bilancia senza aggirare stabilità, intervallo, protezione, comandi concorrenti o configurazione. Esegue TA con una tara numerica nell’unità corrente della bilancia. I valori non vengono convertiti automaticamente da un’altra unità.

Parametri

Tabella 13

Parametro

Tipo / requisito

Descrizione

value

number / obbligatorio

Numero finito ≥ 0 entro la portata della bilancia, in scale.read().unit. Stringhe, NaN e Infinity non sono consentiti.

Risultato

Promise<Measurement>: dopo una risposta riuscita, legge una nuova istantanea JavaScript con la struttura di scale.read(). Non garantisce che sia arrivata la misurazione successiva; monitorare le misurazioni successive per confermare l’effetto.

Errori e considerazioni particolari

Un tipo non valido o un valore negativo o non finito viene rifiutato con INVALID_ARGUMENT; i valori superiori alla portata vengono rifiutati con OUT_OF_RANGE. Altri errori: BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED o TIMEOUT. Gestire il rifiuto con await/try/catch. L’arresto distrugge il contesto; la continuazione della Promise non è garantita.

Esempio

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

Un’operazione di pesatura attende per la finestra dei comandi della bilancia configurata, più circa 2 secondi per l’elaborazione. Queste operazioni JavaScript non prevedono un parametro di timeout per chiamata. Una bilancia che sta elaborando un altro comando può restituire BUSY. Eseguire i comandi dipendenti con chiamate await sequenziali anziché con Promise.all senza limiti.

7.6 scale.cmd()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const response = await scale.cmd(command, { timeoutMs });
Scopo. Eseguire un comando CSCP e leggerne la risposta originale.
Descrizione. Accedere tramite CSCP ai comandi della bilancia, alla configurazione e alle altre funzioni supportate dal dispositivo. Si applicano le regole esistenti di convalida dei parametri e protezione dei dati. RSD e le richieste di configurazione non richiedono una misurazione valida. S e SX attendono una misurazione stabile; SI e SXI eseguono la richiesta immediatamente.

Parametri

Tabella 14

Parametro

Tipo / requisito

Descrizione

command

string / obbligatorio

Un comando CSCP, al massimo 2048 byte UTF-8 dopo la rimozione degli spazi iniziali e finali e di un eventuale CRLF finale. Sono vietati comandi vuoti, NUL, CR/LF interni e altri caratteri di controllo. Sintassi e maiuscole/minuscole seguono CSCP.

options

object / facoltativo, valore predefinito {}

Opzioni di attesa. Unità, stabilità e autorizzazioni dipendono dal comando e dalle impostazioni della bilancia.

options.timeoutMs

integer / facoltativo

1–60000 ms. Il valore predefinito è la finestra di attesa configurata della bilancia più 2 secondi per l’elaborazione. Non estende l’attesa interna di stabilità del comando.

Risultato

Promise<string> contenente la risposta CSCP originale, al massimo 4096 byte UTF-8. Viene rimosso un CRLF finale; le terminazioni interne su più righe restano. La stringa non è un oggetto Measurement e non viene analizzata automaticamente. S I, ES, FT L ed ERRAUTH sono risultati CSCP validi e non rifiutano la Promise. Determinare il successo del comando utilizzando la relativa documentazione CSCP.

Errori e considerazioni particolari

INVALID_ARGUMENT per utilizzo errato; MESSAGE_TOO_LARGE per un comando troppo grande; UNSUPPORTED_COMMAND per comandi con più risposte/silenziosi o reset; BUSY per bilancia occupata o limite di operazioni concorrenti; TIMEOUT per attesa eccessiva; NO_RESPONSE quando un comando termina senza risposta; RESPONSE_TOO_LARGE per una risposta troppo grande; OUT_OF_MEMORY per memoria insufficiente. Le risposte non vengono mai troncate silenziosamente. Stop interrompe l’esecuzione in sospeso; la relativa Promise non prosegue nel contesto distrutto.

Esempio

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

Può essere in sospeso un solo comando di pesatura alla volta. Utilizzare await per l’esecuzione sequenziale. Una nuova richiesta riceve BUSY mentre un altro comando è in sospeso; non esiste una coda di comandi nascosta. Ciò vale anche combinando scale.cmd() con tare/zero/clearTare/setPresetTare. L’annullamento o il timeout non annulla le impostazioni già modificate. Una risposta tardiva non viene assegnata alla richiesta successiva.

La funzione restituisce una sola risposta. SIR, SR, SXIR, RAS, RASI, CAL, RST, CWRESULTA e CWDEBUG vengono rifiutati prima dell’esecuzione, anche nei comandi contenenti un campo di credenziali P=. È consentito contenuto su più righe all’interno di una risposta, ad esempio I0. Utilizzare un timer e scale.read() per misurazioni ripetute; scale.cmd() non apre un flusso di risposte.

Un comando può includere parametri supportati e credenziali CSCP; la funzione non aggira la protezione della bilancia. Seguire la sintassi CSCP quando un comando protetto richiede credenziali. Gestire ERRAUTH e ERRLOCK nel testo restituito. I comandi di installazione dell’applicazione e gli altri canali di gestione non appartengono a scale.cmd().

Verificare il supporto con app.capabilities().scaleOperations.includes("cmd"). I limiti sono pubblicati come limits.maxScaleCommandBytes, limits.maxScaleResponseBytes e limits.maxScaleCommandTimeoutMs. Disponibile da Neutron AppEngine 1.0.0; gli indicatori features descrivono moduli dedicati. io.* è documentato nel capitolo I/O separato. Le impostazioni del modulo e l’archiviazione dei dati hanno capitoli propri e API device e storage separate.

Tabella 15

Chiamata

Risultato / comportamento

scale.cmd("S")

Misurazione stabile successiva o risposta di errore CSCP come S I.

scale.cmd("SI")

Risposta immediata con il peso corrente.

scale.cmd("RSD")

Dati e configurazione della bilancia come stringa; funziona anche senza un peso disponibile.

scale.cmd("FT=?")

Impostazione corrente del filtro, ad esempio FT A 512.

scale.cmd("FT=512")

Modifica e salva il filtro secondo CSCP; esaminare la risposta restituita.

scale.cmd("UNKNOWN")

Solitamente ES come risultato della Promise risolta, non come rifiuto JavaScript.

scale.cmd("SIR")

Rifiuto UNSUPPORTED_COMMAND; non viene avviato alcun flusso continuo.

7.7 Errori del modulo bilancia

Tabella 16

Codice

Significato per la bilancia

NO_MEASUREMENT

Operazione di pesatura senza una misurazione valida o una bilancia disponibile.

OUT_OF_RANGE

La tara predefinita supera la portata.

PERMISSION_DENIED

Comando della bilancia rifiutato per protezione/autorizzazione.

SCALE_REJECTED

La bilancia ha rifiutato l’operazione; esaminare message e le condizioni della bilancia.

7.8 Registrazione periodica del peso

File .js autonomo senza requisiti TCP. Registra una misurazione valida una volta al secondo. Utilizzare Stop nel gestore delle applicazioni per arrestarlo.

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

8. Ingressi e uscite digitali

Il modulo io monitora sei ingressi e sei uscite, ne configura le funzioni, controlla direttamente le uscite riservate e legge i contatori degli ingressi. Gli indici sono sempre 1–6. Tutte le funzioni, le proprietà e gli eventi di questo capitolo sono disponibili da Neutron AppEngine 1.0.0. Supporto API: app.capabilities().features.io; disponibilità fisica I/O: app.capabilities().io.available.

La lettura dello stato e l’osservazione degli eventi non richiedono una riserva. È possibile osservare un’uscita controllata da una funzione di sistema; prima di scrivere direttamente, disabilitarne esplicitamente la funzione e riservarla. Il modulo condivide l’elaborazione I/O del dispositivo, quindi le stesse regole di proprietà si applicano tramite le altre interfacce.

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

Disponibile dalla versione: Neutron AppEngine 1.0.0
const input = io.input(1);
const output = io.output(1);
Scopo. Ottenere l’oggetto di un ingresso o di un’uscita fisici.
Descrizione. Le chiamate ripetute per lo stesso pin restituiscono lo stesso oggetto. Non modifica la configurazione, non registra eventi e non commuta un’uscita.

Parametri

Tabella 17

Parametro

Tipo / requisito

Descrizione

index

integer / obbligatorio

1..6. Stringhe, zero, valori frazionari e indici superiori a 6 vengono rifiutati.

Risultato

Oggetto ingresso o uscita. Entrambi supportano read, configure, on, once e off. Le uscite aggiungono claim, write e release; gli ingressi aggiungono counter e resetCounter.

Errori e considerazioni particolari

INVALID_ARGUMENT per un indice non valido. L’oggetto può essere ottenuto senza una scheda I/O; verificare read().available.

Esempio

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

input.read() / output.read()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const inputState = io.input(1).read();
const outputState = io.output(1).read();
Scopo. Leggere in modo sincrono l’ultima istantanea di stato e configurazione.
Descrizione. La lettura non richiede una riserva e non emette un evento change. L’istantanea viene aggiornata dall’elaborazione condivisa del dispositivo e in caso di modifiche; read non esegue ulteriori campionamenti fisici. Dopo un await configure/write riuscito, l’istantanea include i risultati dell’operazione corrispondente.

Parametri

Nessun parametro.

Risultato

Ingresso: {index, available, value, functionId, function, mode, debounceMs, glitchUs, pull, counter}. Uscita: {index, available, value, functionId, function, claimed}. Tipi e significati sono elencati di seguito.

Errori e considerazioni particolari

value è null per I/O non disponibili e ingressi in modalità disabled o counter. counter è BigInt solo per un ingresso contatore disponibile; altrimenti null. Il value dell’uscita rappresenta lo stato comandato; per confermare la commutazione effettiva di un contattore o dispositivo esterno serve un riscontro su un ingresso.

Esempio

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

Campo dalla versione Neutron AppEngine 1.0.0

Tipo

Significato

index

number

Numero del pin 1..6.

available

boolean

I/O è presente sul dispositivo.

value

boolean | null

true è 1 logico, false è 0 logico. Ai valori degli ingressi viene applicato il filtro antirimbalzo; null significa che non è disponibile un valore digitale.

functionId / function

number / string

Numero della funzione esistente e relativo nome nell’API JavaScript. unknown indica un numero memorizzato non supportato.

mode

string / solo ingresso

disabled, digital o counter.

debounceMs

number / solo ingresso

Tempo di conferma di una variazione digitale in millisecondi.

glitchUs

number / solo ingresso

Filtro degli impulsi brevi del contatore in microsecondi. Utilizzato in modalità counter.

pull

string / solo ingresso

none, up o down.

counter

bigint | null / solo ingresso

Ultimo valore del contatore senza perdita di precisione degli interi grandi.

claimed

boolean / solo uscita

L’uscita è riservata dall’applicazione utente. Non significa che l’uscita sia attiva.

input.configure(options)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.input(1).configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });
Scopo. Configurare e salvare modalità, funzione ed elaborazione dell’ingresso selezionato.
Descrizione. Modifica le proprietà fornite e mantiene le altre se compatibili con la modalità selezionata. Salva e applica la configurazione senza riavvio tramite il percorso condiviso esistente di configurazione degli ingressi. Le modalità disabled e counter disabilitano la funzione di sistema dell’ingresso. L’inizializzazione di una nuova modalità non emette change e non conta un livello inizialmente attivo come una nuova pressione.

Parametri

Tabella 19

Parametro

Tipo / requisito

Descrizione

options.mode

string / facoltativo

disabled, digital o counter. Se omesso, mantiene la modalità corrente.

options.function

string | integer / facoltativo

Nome o ID dalla tabella delle funzioni degli ingressi. Una funzione attiva è consentita solo in modalità digital.

options.debounceMs

integer / facoltativo

0..60000 ms, solo modalità digital. L’impostazione iniziale esistente è 20 ms; specificare esplicitamente il valore desiderato quando si passa da un’altra modalità.

options.pull

string / facoltativo

none, up o down; solo modalità digital.

options.glitchUs

integer / facoltativo

0..12 µs, solo modalità counter. 0 disabilita il filtro. Passando a counter senza specificare un filtro, utilizza il precedente filtro diverso da zero oppure 5 µs.

Risultato

Promise<InputState> con la struttura di read(). Le impostazioni persistono dopo Stop e il riavvio del dispositivo.

Errori e considerazioni particolari

INVALID_ARGUMENT per tipi non validi o proprietà incompatibili, NOT_AVAILABLE, RESOURCE_IN_USE durante dosaggio o controllo peso attivi, CONFIGURE_FAILED se l’applicazione o il salvataggio falliscono, e BUSY. La modalità counter può essere rifiutata se l’ingresso selezionato non ha una risorsa di conteggio disponibile. Non configurare in un ciclo periodico rapido.

Esempio

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

output.configure(options)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.output(1).configure({ function: "disabled" });
Scopo. Selezionare e salvare la funzione di sistema di un’uscita oppure disabilitarla.
Descrizione. Modificare la funzione non commuta direttamente l’uscita. Una funzione attiva ne controlla lo stato secondo le regole del dispositivo. disabled consente il controllo manuale e la riserva tramite JavaScript; non disattiva automaticamente il livello corrente dell’uscita.

Parametri

Tabella 20

Parametro

Tipo / requisito

Descrizione

options.function

string | integer / obbligatorio

Nome o ID dalla tabella delle funzioni delle uscite.

Risultato

Promise<OutputState>. L’impostazione è persistente e si applica senza riavvio.

Errori e considerazioni particolari

RESOURCE_IN_USE se l’uscita è riservata o sono attivi dosaggio/controllo peso. Chiamare release(), poi configure(). Anche gli altri canali non possono modificare la funzione di un’uscita riservata. Altri errori: INVALID_ARGUMENT, NOT_AVAILABLE, CONFIGURE_FAILED, BUSY.

Esempio

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

Nomi e ID delle funzioni

Tabella 21

ID ingresso

Nome JavaScript dalla versione Neutron AppEngine 1.0.0

Significato

0

disabled

Nessuna funzione di sistema

1

zero

Azzeramento

2

tare

Tara

3

clearTare

Cancellazione tara

4

dosingStart

Avvio dosaggio

5

dosingPause

Pausa dosaggio

6

dosingStop

Arresto dosaggio

7

checkweigherSensor

Sensore prodotto

8

checkweigherStart

Avvio controllo peso

9

checkweigherPause

Pausa controllo peso

10

checkweigherStop

Arresto controllo peso

11

checkweigherReset

Reimpostazione controllo peso

12

checkweigherEnable

Abilitazione CONS

13

checkweigherTrigger

Attivazione scarto

Tabella 22

ID uscita

Nome JavaScript dalla versione Neutron AppEngine 1.0.0

Significato

0

disabled

Nessuna funzione di sistema

1

inTolerance

Entro tolleranza

2

underTolerance

Sotto tolleranza

3

overTolerance

Sopra tolleranza

4

dosingActive

Dosaggio attivo

5

dosingFast

Dosaggio grossolano

6

dosingMedium

Dosaggio medio

7

dosingFine

Dosaggio fine

8

dosingFly

Attesa dell’afflusso

9

dosingUnloading

Scarico

10

dosingInTolerance

Dosaggio entro tolleranza

11

dosingOutOfTolerance

Dosaggio fuori tolleranza

12

dosingEnd

Dosaggio completato

13

dosingError

Errore di dosaggio

14

checkweigherBelt

Trasportatore

15

checkweigherLow

Scarto sottopeso

16

checkweigherHigh

Scarto sovrappeso

17

checkweigherGood

Impulso peso accettabile

18

checkweigherCommon

Scarto comune / errore

19

checkweigherActive

Controllo peso attivo

20

checkweigherAlarm

Allarme

21

checkweigherBuffer

Avviso tramoggia

Le funzionalità del dispositivo determinano le regole effettive di queste funzioni di sistema. Registrare change non disabilita una funzione: un ingresso assegnato alla tara può attivare sia la tara di sistema sia un evento JavaScript. Se l’operazione sarà eseguita da JavaScript, impostare prima function="disabled" per evitare di eseguirla due volte. Gli elenchi di ID/nomi sono disponibili anche in capabilities.io.inputFunctions e outputFunctions.

output.claim(options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.output(1).claim({ safeState: false });
Scopo. Riservare il controllo manuale esclusivo dell’uscita per l’esecuzione corrente dell’applicazione.
Descrizione. Consentito solo con function=disabled. Non disabilita automaticamente una funzione di sistema assegnata e non modifica il livello corrente. La stessa applicazione può riservare nuovamente la stessa uscita per aggiornare safeState.

Parametri

Tabella 23

Parametro

Tipo / requisito

Descrizione

options.safeState

boolean / false

Stato dell’uscita al momento di release() o della terminazione dell’applicazione. Si applica all’esecuzione corrente; non viene salvato come stato di avvio del dispositivo.

Risultato

Promise<OutputState> con claimed=true.

Errori e considerazioni particolari

RESOURCE_IN_USE per una funzione di sistema attiva o un altro proprietario. NOT_AVAILABLE, INVALID_ARGUMENT, BUSY. Le uscite riservate rifiutano scritture esterne e modifiche di funzione, anche tramite altri canali. L’osservazione di change resta consentita.

Esempio

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

output.write(value)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.output(1).write(true);
Scopo. Impostare un’uscita riservata sullo stato logico richiesto.
Descrizione. Scrive tramite l’elaborazione I/O condivisa. Una modifica effettiva emette change; riscrivere lo stesso valore non emette eventi. Lo stato non viene salvato a ogni commutazione. La Promise e l’evento change sono notifiche separate; non fare affidamento sul loro ordine relativo.

Parametri

Tabella 24

Parametro

Tipo / requisito

Descrizione

value

boolean / obbligatorio

true attiva, false disattiva; 0, 1 e stringhe non sono consentiti.

Risultato

Promise<OutputState> dopo la scrittura dell’uscita di controllo.

Errori e considerazioni particolari

NOT_OWNER prima di claim o dopo release. NOT_AVAILABLE, INVALID_ARGUMENT, RESOURCE_IN_USE, BUSY. La conferma non prova il funzionamento fisico del dispositivo esterno.

Esempio

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

output.release()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.output(1).release();
Scopo. Impostare l’uscita su safeState e rilasciarne la proprietà.
Descrizione. Il rilascio automatico avviene anche nell’elaborazione del servizio dopo Stop, un errore non gestito o la sostituzione dell’applicazione. La funzione di sistema precedente non viene ripristinata automaticamente: configure è una modifica esplicita persistente. Rilasciare un’uscita non riservata nell’esecuzione corrente non ha effetto.

Parametri

Nessun parametro.

Risultato

Promise<undefined>. Se safeState modifica il livello, viene emesso change mentre l’applicazione è ancora in esecuzione.

Errori e considerazioni particolari

NOT_OWNER per un altro proprietario, NOT_AVAILABLE, BUSY. La consegna di un evento finale non è garantita alla terminazione dell’applicazione. Dopo un reset hardware si applica il normale stato di avvio dell’uscita del dispositivo (disattivato), non il precedente safeState. Questo non sostituisce un circuito di sicurezza hardware.

Esempio

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

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

Disponibile dalla versione: Neutron AppEngine 1.0.0
pin.on("change", callback);
pin.once("change", callback);
pin.off("change", callback);
Scopo. Osservare le variazioni dell’ingresso o dell’uscita selezionati.
Descrizione. on osserva le variazioni successive. once annulla la registrazione prima della prima variazione successiva, che può essere sia un’attivazione sia una disattivazione. off rimuove le registrazioni della stessa funzione. La sola registrazione non emette alcun evento iniziale. L’evento supportato è change, con un massimo di 32 listener per pin.

Parametri

Tabella 25

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

Solo "change".

callback

function / obbligatorio

Riceve {index, value, previousValue, timeMs}. off richiede lo stesso riferimento alla funzione.

Risultato

Restituisce lo stesso oggetto pin per concatenare le chiamate. Gli eventi sono indipendenti dall’origine della variazione: JavaScript, CSCP, altre interfacce di gestione o una funzione di sistema.

Errori e considerazioni particolari

INVALID_ARGUMENT, QUOTA_EXCEEDED. Gli ingressi emettono eventi dopo il filtro antirimbalzo. Gli eventi digitali non sono disponibili in modalità counter o disabled. Le uscite emettono eventi solo quando il livello comandato cambia effettivamente. Un’eccezione o una Promise rifiutata non gestita in una callback può arrestare l’applicazione secondo le regole dell’ambiente di esecuzione. Senza listener, nessun evento di quel pin viene inviato a JavaScript.

Esempio

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

Campo evento dalla versione Neutron AppEngine 1.0.0

Tipo

Significato

index

integer

1..6 per il pin con il listener.

value

boolean

Nuovo stato: true è 1 logico, false è 0 logico.

previousValue

boolean

Stato confermato precedente.

timeMs

number

Istante monotono della variazione in millisecondi dall’avvio del dispositivo; può essere frazionario. Non è una data, un’ora UTC o l’istante di consegna della callback. Per gli ingressi, è l’istante della conferma dopo il filtro antirimbalzo.

L’esempio sulla durata di attivazione non richiede polling. timeMs riparte quando il dispositivo si riavvia. Le modifiche alla configurazione e i campioni iniziali in una nuova modalità non sono eventi di variazione fisica.

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

input.counter()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const count = io.input(1).counter();
Scopo. Restituire l’ultimo totale degli impulsi positivi rilevati su un ingresso contatore.
Descrizione. Il conteggio utilizza il meccanismo esistente del dispositivo senza invocare JavaScript per ogni impulso. BigInt conserva la precisione oltre 2^53. Massimo: 9223372036854775807; il valore satura a questo limite. La normale persistenza del contatore del dispositivo resta attiva; una perdita improvvisa di alimentazione può far perdere gli impulsi non ancora salvati.

Parametri

Nessun parametro.

Risultato

bigint. Lo stesso valore compare in input.read().counter. Utilizzare count.toString() per JSON; JSON.stringify non può serializzare direttamente BigInt.

Errori e considerazioni particolari

INVALID_MODE se l’ingresso non è in modalità counter; NOT_AVAILABLE se I/O è assente. È un’istantanea, non una garanzia che non siano arrivati nuovi impulsi durante la lettura.

Esempio

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

input.resetCounter()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await io.input(1).resetCounter();
Scopo. Reimpostare il contatore selezionato e salvare il nuovo valore di riferimento.
Descrizione. Asincrono; consentito solo in modalità counter. Non emette eventi di variazione digitale. Possono arrivare impulsi durante o subito dopo il ripristino.

Parametri

Nessun parametro.

Risultato

Promise<bigint> contenente l’ultima istantanea del contatore dopo l’esecuzione. Nuovi impulsi fanno sì che possa non essere più 0n.

Errori e considerazioni particolari

INVALID_MODE, NOT_AVAILABLE, WRITE_FAILED, BUSY. Un errore di salvataggio può verificarsi dopo il ripristino del contatore in memoria; l’errore non annulla tale effetto. Non reimpostare in un ciclo rapido.

Esempio

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

Esempio completo: un ingresso controlla un’uscita

L’esempio salva esplicitamente la configurazione dell’ingresso 1 e disabilita la funzione di sistema dell’uscita 1. Quindi riserva l’uscita con safeState=false, monitora l’ingresso 1 e osserva separatamente l’uscita 2. Limita la sovrapposizione delle scritture asincrone e applica l’ultimo stato dell’ingresso al termine di una scrittura.

// 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 di un’applicazione I/O

Tabella 27

Test

Risultato previsto

Stato iniziale

read restituisce un valore; la registrazione di on/once non emette eventi.

Attivare e disattivare l’ingresso 1

Due eventi change dopo il filtro antirimbalzo, con previousValue/value opposti e i corrispondenti timeMs.

Breve rimbalzo del contatto

Nessun evento duplicato per una variazione confermata.

SOT esterno per l’uscita 2 non riservata

Un evento change JavaScript a ogni variazione effettiva; ripetere lo stesso valore non ne emette alcuno.

Uscita 2 controllata da una funzione di sistema

JavaScript può osservare le variazioni senza riserva.

SOT/SOF esterno o modifica di funzione per l’uscita 1 riservata

Rifiutato senza sovrascrivere l’uscita dell’applicazione.

Stop o errore dell’applicazione con un’uscita riservata attiva

Passaggio a safeState e rilascio durante l’elaborazione del servizio.

Contatore e valori grandi

BigInt senza perdita di precisione; nessun evento di variazione digitale per ogni impulso.

I/O non disponibile o indice non valido

available=false o INVALID_ARGUMENT; nessun accesso a un altro pin.

9. Impostazioni del modulo: RMD e SMD

Il modulo device gestisce le impostazioni Neutron. È separato da scale, che controlla la pesatura, e dai dati dell’applicazione in storage. Tutte le funzioni e le proprietà di questo capitolo sono disponibili da Neutron AppEngine 1.0.0. Supporto: app.capabilities().features.settings.

Le modifiche utilizzano la convalida e la memorizzazione SMD esistenti. Rispettano le interfacce occupate e le uscite riservate. Le impostazioni applicabili durante il funzionamento utilizzano i meccanismi esistenti di applicazione a dispositivo attivo. Le altre indicano che è necessario un riavvio. L’API non riavvia mai automaticamente il dispositivo.

device.cmd(command)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const raw = await device.cmd("RMD");
const result = await device.cmd("SMD;S0B=19200;S0P=0;");
Scopo. Eseguire un comando di gestione RMD o SMD supportato.
Descrizione. RMD restituisce un elenco testuale delle impostazioni e degli stati di base nel formato esistente. SMD utilizza lo stesso risultato di settings.write(). Gli altri comandi di gestione, come REB, non sono supportati qui. Non ripetere SMD tra le singole impostazioni.

Parametri

Tabella 28

Parametro

Tipo / requisito

Descrizione

command

string / obbligatorio

RMD oppure SMD;KEY=value;... . Massimo 2048 byte UTF-8; nessun carattere di controllo. SMD accetta fino a 16 chiavi distinte.

Risultato

RMD: Promise<string>. SMD: Promise<SettingsWriteResult>, descritto di seguito.

Errori e considerazioni particolari

INVALID_ARGUMENT, UNSUPPORTED_COMMAND, BUSY, NO_RESPONSE, RESPONSE_TOO_LARGE. RMD può superare 4096 byte; utilizzare settings.read per chiavi selezionate o settings.list per la paginazione. L’API non legge password, PIN o dati privati dei certificati. Gestire i certificati tramite il processo esistente di predisposizione dei certificati.

Esempio

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

device.settings.read(keys)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const values = await device.settings.read(["S0B", "S0P"]);
Scopo. Leggere impostazioni memorizzate selezionate senza una risposta RMD di grandi dimensioni.
Descrizione. Restituisce i valori come stringhe, inclusi i numeri. Una chiave assente ha valore null. La lettura non modifica lo stato o le impostazioni del dispositivo e non garantisce che l’applicazione in sospeso all’hardware sia terminata.

Parametri

Tabella 29

Parametro

Tipo / requisito

Descrizione

keys

string[] / obbligatorio

1..16 chiavi. I nomi contengono 1..15 caratteri: A–Z, 0–9 oppure _.

Risultato

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

Errori e considerazioni particolari

INVALID_ARGUMENT, PERMISSION_DENIED per dati protetti, RESPONSE_TOO_LARGE, BUSY. Non inventare API utilizzando chiavi sconosciute; le impostazioni supportate sono definite dal dispositivo e dalla relativa documentazione.

Esempio

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

device.settings.list(options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const page = await device.settings.list({ cursor: null, limit: 16 });
Scopo. Leggere per pagine le impostazioni memorizzate accessibili pubblicamente.
Descrizione. Le chiavi sono ordinate in modo crescente. cursor è l’ultima chiave della pagina precedente, esclusa dalla successiva. La risposta può contenere meno di limit chiavi a causa del limite di dimensione. Le pagine non costituiscono un’unica istantanea: le impostazioni possono cambiare tra le chiamate.

Parametri

Tabella 30

Parametro

Tipo / requisito

Descrizione

options.cursor

string | null / omesso

nextCursor della risposta precedente; null o l’omissione parte dall’inizio.

options.limit

integer / 16

1..32 chiavi per pagina; il limite della risposta resta 4096 byte.

Risultato

Promise<{values:object, nextCursor:string|null}>. null indica la fine.

Errori e considerazioni particolari

INVALID_ARGUMENT, RESPONSE_TOO_LARGE per un singolo valore troppo grande, BUSY. L’elenco contiene chiavi memorizzate; gli stati RMD dinamici non sono necessariamente impostazioni memorizzate. I dati riservati sono omessi.

Esempio

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

device.settings.write(values)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await device.settings.write({ S0B: "19200", S0P: "0" });
Scopo. Salvare un gruppo di impostazioni tramite l’elaborazione SMD esistente.
Descrizione. Convalida il formato complessivo prima di iniziare. Le singole convalide e gli errori hardware seguono poi le regole SMD esistenti. Il gruppo non è una transazione: un errore non annulla gli altri valori salvati. Verificare result.ok e result.errors anche dopo un await riuscito.

Parametri

Tabella 31

Parametro

Tipo / requisito

Descrizione

values

object / obbligatorio

1..16 chiavi. I valori possono essere stringhe, booleani (0/1) o interi in −2147483648..4294967295. Fornire i decimali come stringhe nel formato dell’impostazione. Al massimo 1024 byte UTF-8 per valore; nessun punto e virgola, carattere di controllo o valore speciale ?. L’intera richiesta deve rientrare in 4096 byte.

Risultato

Promise<{ok:boolean, applied:string[], errors:object, rebootRequired:boolean, applyPending:boolean}>. applied elenca le chiavi senza errore immediato di salvataggio; non è una conferma indipendente della disponibilità dell’interfaccia fisica. Un errore finale di applicazione può avere una chiave separata in errors.

Errori e considerazioni particolari

Un formato non valido viene rifiutato con INVALID_ARGUMENT o MESSAGE_TOO_LARGE. Gli errori delle singole impostazioni restituiscono ok=false ed errors, come CHECKWEIGHER_BUSY o INVALID_OR_WRITE_FAILED. applyPending indica che l’applicazione all’interfaccia seriale è in sospeso; monitorare lo stato dell’interfaccia o del dispositivo. rebootRequired non attiva mai un riavvio automatico. Non scrivere impostazioni persistenti in un ciclo rapido di misurazione.

Esempio

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

Esempio di lettura delle impostazioni

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

10. Archiviazione e file

Il modulo storage fornisce l’archiviazione persistente dei dati dell’applicazione. Tutte le funzioni di questo capitolo sono disponibili da Neutron AppEngine 1.0.0. Supporto: app.capabilities().features.files. I file dell’applicazione sono separati dai file di sistema, dai certificati e dal codice dell’applicazione installata. L’API non può accedere a nulla al di fuori di questo spazio dati.

I nomi dei file contengono 1..64 caratteri. Il primo deve essere A–Z/a–z o una cifra; i successivi possono includere anche _, - o un punto. Sono vietati punti consecutivi, barre, sottocartelle e percorsi assoluti. I nomi distinguono maiuscole e minuscole. I dati sopravvivono a Stop, al riavvio e alla normale sostituzione dell’applicazione. L’applicazione installata condivide un unico spazio dati; una nuova versione o un’applicazione diversa sul dispositivo può utilizzare gli stessi dati. Factory default elimina i file utente e i database locali. Il normale Delete dell’applicazione non li elimina.

Le operazioni sono asincrone e utilizzano una coda di servizio limitata. Non caricare un intero file grande in JavaScript, non creare code di scrittura illimitate e non inviare tutti i blocchi senza await. L’arresto non annulla una scrittura già iniziata; il risultato potrebbe non raggiungere più l’applicazione arrestata.

storage.info()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const info = await storage.info();
Scopo. Indicare utilizzo, quota e spazio disponibile.
Descrizione. File e database locali condividono la quota dell’applicazione. La disponibilità effettiva dipende anche dagli altri dati del dispositivo e dalla riserva di sistema. Le copie temporanee per sostituzione atomica o compattazione richiedono ulteriore spazio fisico.

Parametri

Nessun parametro.

Risultato

{quotaBytes, usedBytes, reserveBytes, freeBytes, availableBytes, maxFileBytes, databases:[{name,bytes}]}. usedBytes è la dimensione logica complessiva di file e database confermati; freeBytes è lo spazio totale libero. availableBytes stima la crescita possibile entro quota e riserva.

Errori e considerazioni particolari

NOT_AVAILABLE o un errore di lettura. Un'istantanea, non una prenotazione per una scrittura futura. La disponibilità viene nuovamente controllata durante l'operazione.

Esempio

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

storage.write() / storage.writeText()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await storage.write(name, data);
await storage.writeText(name, text);
Scopo. Creare un file o sostituirne l’intero contenuto.
Descrizione. write accetta string o Uint8Array; writeText accetta solo string. Le stringhe sono memorizzate come UTF-8; i dati binari come byte esatti. Non aggiunge newline o NUL. La sostituzione completa utilizza una scrittura temporanea seguita dalla sostituzione del file confermato.

Parametri

Tabella 32

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome di file valido.

data / text

string | Uint8Array / obbligatorio

0..4096 byte per chiamata dopo la codifica UTF-8. writeText non accetta Uint8Array.

Risultato

Promise<undefined> dopo la conferma di scrittura e memorizzazione avvenuta con successo. Un payload vuoto crea o svuota il file.

Errori e considerazioni particolari

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, NOT_AVAILABLE, BUSY. La sostituzione non riuscita conserva il file precedentemente salvato. Per contenuti più grandi, scrivi il primo pezzo, quindi aggiungi in sequenza; questa costruzione in più fasi non è un'operazione atomica.

Esempio

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

storage.append() / storage.appendText()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await storage.append(name, data);
await storage.appendText(name, text);
Scopo. Aggiungere dati a un file, adatto ai log.
Descrizione. Crea un file assente senza sovrascrivere il contenuto precedente. L’aggiunta non è una transazione su più record; errori o interruzioni di alimentazione possono lasciare incompleta l’ultima aggiunta. Progettare i log per rilevare questi record finali parziali.

Parametri

Tabella 33

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome di file valido.

data / text

string | Uint8Array / obbligatorio

Al massimo 4096 byte per chiamata; appendText richiede string. Dimensione massima del file: 262144 byte.

Risultato

Promise<undefined>. Un successo consegnato conferma la scrittura; una risposta mancante non significa che la scrittura non sia avvenuta.

Errori e considerazioni particolari

MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, BUSY. Parte dell'aggiunta potrebbe già esistere dopo un errore. Non riprovare ciecamente i record aziendali senza un ID univoco o una verifica.

Esempio

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

storage.read() / storage.readText()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const bytes = await storage.read(name, { offset: 0, length: 4096 });
const text = await storage.readText(name);
Scopo. Leggere byte binari o testo UTF-8.
Descrizione. read restituisce Uint8Array; readText restituisce string. offset e length utilizzano sempre byte. Iniziare oltre la fine restituisce un risultato vuoto. Una lettura vicina alla fine può restituire meno byte di quelli richiesti.

Parametri

Tabella 34

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome del file.

options.offset

integer / 0

0..262144 byte dall’inizio.

options.length

integer / facoltativo

0..4096 byte. read legge per impostazione predefinita fino a 4096 byte. Senza length, readText richiede che il testo rimanente entri in una sola risposta; altrimenti RESPONSE_TOO_LARGE.

Risultato

Promise<Uint8Array> oppure Promise<string>. read conserva NUL binario e tutti gli altri byte.

Errori e considerazioni particolari

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, RESPONSE_TOO_LARGE. Rispettare i limiti dei caratteri multibyte durante la divisione del testo UTF-8; decodificare blocchi arbitrari in modo indipendente può dividere un carattere. readText non è un parser JSON o JSONL; utilizzare JSON.parse per documenti JSON piccoli.

Esempio

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

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

Disponibile dalla versione: Neutron AppEngine 1.0.0
const page = await storage.list({ cursor: null, limit: 16 });
const info = await storage.stat("data.bin");
Scopo. Elencare i file oppure ottenere la dimensione di un file.
Descrizione. list include solo i file ordinari dell’applicazione, non i file interni dei database. I nomi sono ordinati in modo crescente; cursor esclude l’ultimo nome già restituito. I database compaiono in storage.info().databases.

Parametri

Tabella 35

Parametro

Tipo / requisito

Descrizione

options.cursor

string | null / omesso

nextCursor della pagina precedente.

options.limit

integer / 16

1..32 file.

name per stat

string / obbligatorio

Nome valido.

Risultato

list: {files:[{name,size}], nextCursor:string|null}. stat: {name,size}. La dimensione è in byte. null indica la fine dell’elenco.

Errori e considerazioni speciali

NOT_FOUND per stat, INVALID_ARGUMENT, READ_FAILED, OUT_OF_MEMORY. Le pagine non sono un'istantanea immutabile durante aggiunte o eliminazioni simultanee.

Esempio

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

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

Disponibile dalla versione: Neutron AppEngine 1.0.0
const removed = await storage.remove("old.jsonl");
await storage.rename("measurements.jsonl", "archive.jsonl");
Scopo. Eliminare o rinominare un file ordinario.
Descrizione. remove non può accedere ai dati interni dei database. rename non sovrascrive una destinazione esistente; se necessario, eliminarla prima esplicitamente.

Parametri

Tabella 36

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome del file di origine.

to per rename

string / obbligatorio

Nuovo nome valido senza un file esistente.

Risultato

remove: Promise<boolean>, false se assente. rename: Promise<undefined>.

Errori e considerazioni speciali

NOT_FOUND per una sorgente di ridenominazione mancante, ALREADY_EXISTS per una destinazione esistente, WRITE_FAILED, INVALID_ARGUMENT. La cancellazione non può essere annullata.

Esempio

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

storage.findText(name, text, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const page = await storage.findText("measurements.jsonl", "ART-001", { offset: 0, limit: 16 });
Scopo. Cercare testo esatto in un file ordinario senza caricarne tutto il contenuto in JavaScript.
Descrizione. Ricerca sequenziale di byte UTF-8 con distinzione tra maiuscole e minuscole, non un’espressione regolare. Supporta corrispondenze sovrapposte. Ogni chiamata esamina al massimo 65536 byte oppure si arresta al limite delle corrispondenze. Utilizzare un database locale per la ricerca rapida per chiave anziché esaminare ripetutamente i file.

Parametri

Tabella 37

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome del file.

text

string / obbligatorio

1..128 byte UTF-8, senza NUL.

options.offset

integer / 0

Offset iniziale in byte, 0..262144.

options.limit

integer / 16

1..64 corrispondenze per pagina.

Risultato

{offsets:number[], nextOffset:number|null}. offsets contiene le posizioni iniziali assolute delle corrispondenze in byte. Proseguire esattamente con nextOffset restituito; conserva le possibili corrispondenze parziali tra i confini delle pagine. null indica la fine del file.

Errori e considerazioni particolari

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, CANCELLED. Non modificare il file durante una ricerca in più passaggi se sono necessari risultati stabili. Il tempo totale di ricerca sequenziale è proporzionale alla dimensione del file.

Esempio

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

Log JSONL e rotazione

JSONL memorizza un oggetto JSON indipendente per riga, senza virgole tra le righe o [] esterne. Ciò consente di aggiungere misurazioni. Generare ogni riga con JSON.stringify(record)+"\n". Rilevare e gestire separatamente una riga finale incompleta dopo un’interruzione. JSONL non fornisce un indice automatico né l’eliminazione automatica delle vecchie misurazioni.

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

Limiti condivisi dell’archiviazione

Tabella 38

Limite dalla versione Neutron AppEngine 1.0.0

Valore

Quota condivisa dell’applicazione

524288 byte per file e database complessivamente.

Riserva di sistema

131072 byte fisicamente liberi prima di ulteriori scritture. Le altre funzioni del dispositivo possono modificare la disponibilità effettiva.

File o log di un singolo database

262144 byte.

Chiamata di lettura / scrittura

4096 byte.

File ordinari

Al massimo 64 nomi.

Ordine

Le richieste di archiviazione vengono eseguite in una sola coda di servizio limitata. Più chiamate non costituiscono una transazione.

Terminazione dell’applicazione

Gli oggetti database aperti vengono rilasciati; i dati confermati restano.

Factory default

Elimina anche i file e i database dell’applicazione.

11. Database locale semplice di record

Il database locale memorizza piccoli oggetti JSON con una chiave univoca, come un codice prodotto, un codice ricetta o un ID di record aziendale. Tutte le funzioni di questo capitolo sono disponibili da Neutron AppEngine 1.0.0. Supporto: app.capabilities().features.records. I dati condividono lo spazio e la quota di archiviazione dei file, ma i file interni del database sono separati dall’API dei file ordinari.

L’apertura convalida il log dei record e costruisce un indice ordinato delle chiavi. get utilizza l’indice e l’offset diretto del record senza esaminare l’intero database. L’apertura e la compattazione esaminano i dati e possono richiedere più tempo; aprire una sola volta all’avvio e riutilizzare l’oggetto. È supportata una chiave indicizzata per database. Non sono disponibili SQL, relazioni, indicizzazione secondaria automatica o transazioni su più record.

storage.openRecords(name, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const articles = await storage.openRecords("articles", { key: "code" });
Scopo. Creare o aprire un database e prepararne l’indice.
Descrizione. Il nome del database e quello del campo chiave vengono associati in modo permanente alla creazione. Utilizzare lo stesso nome del campo chiave alla riapertura. L’apertura di un nome già aperto viene rifiutata; riutilizzare l’oggetto restituito. Gli oggetti sono validi solo durante l’esecuzione corrente dell’applicazione.

Parametri

Tabella 39

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

1..32 caratteri secondo le regole dei nomi dei file.

options.key

string / "id"

Nome di un campo dell’oggetto al livello principale. 1..32 caratteri ASCII: prima una lettera o _, poi anche cifre. Ogni record deve contenere questo campo come stringa non vuota.

Risultato

Promise<RecordStore> con proprietà name e key e metodi put/get/delete/list/stat/compact/close.

Errori e considerazioni particolari

SCHEMA_MISMATCH per un campo chiave diverso in un database esistente; ALREADY_OPEN; QUOTA_EXCEEDED; NO_SPACE; CORRUPT; CANCELLED; OUT_OF_MEMORY. Al massimo 8 database persistenti e 2 aperti contemporaneamente. Un record finale incompleto viene rimosso all’apertura; un errore di integrità in un record completo rifiuta l’apertura anziché eliminare silenziosamente i dati.

Esempio

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

records.put(record)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await articles.put({ code: "ART-001", name: "Flour", target: 25 });
Scopo. Inserire un oggetto o sostituire completamente il record con la stessa chiave.
Descrizione. put sostituisce l’intero oggetto, non i singoli campi. I dati vengono aggiunti al log e il record confermato aggiorna l’indice. Le chiavi distinguono maiuscole e minuscole. Più chiamate put sequenziali non costituiscono un’unica transazione.

Parametri

Tabella 40

Parametro

Tipo / requisito

Descrizione

record

object / obbligatorio

Oggetto serializzabile in JSON, al massimo 2048 byte UTF-8 dopo JSON.stringify e al massimo 16 livelli annidati di oggetti/array. Il campo chiave deve essere una stringa di 1..64 byte UTF-8 senza caratteri di controllo. Convertire esplicitamente gli ID numerici con String.

Risultato

Promise<object> contenente l’oggetto JSON memorizzato.

Errori e considerazioni particolari

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, CLOSED, CORRUPT. BigInt e riferimenti circolari non possono essere serializzati come JSON. Un errore di commit può rendere incerto l’esito della scrittura; riaprire e verificare get prima di riprovare. Non registrare ogni impulso senza limiti.

Esempio

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

records.get(key)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const article = await articles.get("ART-001");
Scopo. Recuperare rapidamente l’ultimo record confermato tramite una chiave univoca.
Descrizione. Utilizza un indice ordinato: la ricerca per chiave richiede un numero logaritmico di confronti e la lettura del record selezionato. Non esamina tutti gli oggetti. Restituisce un nuovo oggetto; modificarlo in JavaScript non modifica di per sé il database.

Parametri

Tabella 41

Parametro

Tipo / requisito

Descrizione

key

string / obbligatorio

Chiave esatta, 1..64 byte UTF-8, senza caratteri di controllo.

Risultato

Promise<object|null>. null significa che la chiave è assente.

Errori e considerazioni particolari

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT. Gli altri campi non sono indicizzati. Non trattare gli ID di stringa come numeri: "001" e "1" sono chiavi distinte.

Esempio

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

records.delete(key)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const deleted = await articles.delete("ART-001");
Scopo. Rimuovere un record dall’elenco attivo del database.
Descrizione. Normalmente aggiunge un record di eliminazione confermato; i vecchi dati possono rimanere fino alla compattazione. L’eliminazione non è una cancellazione sicura del supporto fisico. È consentito eliminare una chiave assente.

Parametri

Tabella 42

Parametro

Tipo / requisito

Descrizione

key

string / obbligatorio

Chiave secondo le stesse regole di get.

Risultato

Promise<boolean>: true se il record esisteva, altrimenti false.

Errori e considerazioni particolari

INVALID_ARGUMENT, CLOSED, NO_SPACE, WRITE_FAILED, CORRUPT. Al limite del registro, l'eliminazione potrebbe attivare la compattazione che richiede spazio temporaneo.

Esempio

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

records.list(options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const page = await articles.list({ cursor: null, limit: 16 });
Scopo. Leggere i record attivi in ordine di chiave, pagina per pagina.
Descrizione. I record seguono l’ordine dei byte delle chiavi. cursor esclude l’ultima chiave della pagina precedente. I limiti della dimensione della risposta possono ridurre una pagina al di sotto di limit. Per i campi non indicizzati, esaminare le pagine e filtrare in JavaScript; non è una ricerca indicizzata rapida.

Parametri

Tabella 43

Parametro

Tipo / requisito

Descrizione

options.cursor

string | null / omesso

nextCursor restituito dalla pagina precedente.

options.limit

integer / 16

1..32 record, limitati anche dalle dimensioni degli oggetti e della risposta.

Risultato

{records:object[], nextCursor:string|null}. null segna la fine. Cambiare il database tra le pagine significa che i risultati non sono un'istantanea immutabile.

Errori e considerazioni particolari

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT, OUT_OF_MEMORY. Evita di accumulare ogni pagina in un unico grande array quando è necessario un solo risultato.

Esempio

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

records.stat()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const status = await articles.stat();
Scopo. Leggere il numero dei record attivi, la dimensione del log e il campo chiave.
Descrizione. La dimensione del log include i record sostituiti e le eliminazioni, non solo gli oggetti attualmente attivi.

Parametri

Nessun parametro.

Risultato

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

Errori e considerazioni particolari

CLOSED oppure CORRUPT. Al massimo 2048 record attivi per database; i limiti di dimensione e la quota condivisa possono ridurre il conteggio ottenibile.

Esempio

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

records.compact()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await articles.compact();
Scopo. Rimuovere dal log le vecchie versioni e le eliminazioni per recuperare spazio.
Descrizione. Copia solo i record attivi in un file temporaneo, lo convalida e lo conferma, quindi sostituisce il vecchio database. Un’interruzione conserva il vecchio o il nuovo database confermato. Anche put o delete possono avviare la compattazione quando il log raggiunge 262144 byte.

Parametri

Nessun parametro.

Risultato

Promise<undefined>. Le chiavi attive e i valori rimangono invariati.

Errori e considerazioni particolari

NO_SPACE per la copia temporanea, WRITE_FAILED, READ_FAILED, CANCELLED, CORRUPT, OUT_OF_MEMORY. Può richiedere più tempo e occupare la coda del servizio di archiviazione; non eseguire dopo ogni misurazione. Dopo QUOTA_EXCEEDED della quota condivisa, una compattazione esplicita può rimuovere contenuti obsoleti prima di ritentare una scrittura.

Esempio

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

records.close()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await articles.close();
Scopo. Rilasciare l’oggetto aperto e l’indice conservando i dati.
Descrizione. I metodi successivi dell’oggetto restituiscono CLOSED. Ripetere close è innocuo. Riaprire con lo stesso nome del database e campo chiave quando necessario. La terminazione dell’applicazione rilascia automaticamente gli oggetti aperti.

Parametri

Nessun parametro.

Risultato

Promise<undefined>.

Errori e considerazioni particolari

BUSY se la coda è piena. Le operazioni in coda prima della chiusura potrebbero essere completate per prime; l'utilizzo di un oggetto chiuso viene rifiutato.

Esempio

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

storage.removeRecords(name)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const removed = await storage.removeRecords("articles");
Scopo. Eliminare un intero database locale e il relativo schema.
Descrizione. Il database deve essere chiuso. Trovare i nomi in storage.info().databases. Dopo l’eliminazione, lo stesso nome può essere creato con un campo chiave diverso.

Parametri

Tabella 44

Parametro

Tipo / requisito

Descrizione

name

string / obbligatorio

Nome del database, 1..32 caratteri.

Risultato

Promise<boolean>: true se esisteva, altrimenti false.

Errori e considerazioni particolari

RESOURCE_IN_USE per un database aperto, INVALID_ARGUMENT, WRITE_FAILED. La cancellazione dell'intero database non può essere annullata.

Esempio

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

Esempio completo di database locale dei prodotti

// 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 di persistenza e ripristino

Tabella 45

Test

Risultato previsto

Eseguire put due volte con lo stesso codice

get restituisce l’ultima versione completa; il conteggio non aumenta.

Stop, nuovo Run o riavvio normale

Lo stesso nome e la stessa chiave aprono i dati memorizzati; l’indice viene ricostruito.

Perdita di alimentazione durante l’aggiunta

I record completamente confermati restano; un record finale incompleto viene scartato all’apertura. L’esito dell’ultima operazione non confermata può essere incerto.

Errore di integrità in un record completo

CORRUPT; l’intero database non viene eliminato automaticamente.

Eseguire compact e riaprire

I record attivi restano invariati; il log si riduce se esistevano vecchie versioni.

Quota raggiunta

QUOTA_EXCEEDED o NO_SPACE senza crescita illimitata dei dati.

Factory default

I file utente e i database vengono eliminati.

Accedere a un oggetto chiuso o di un’esecuzione precedente

CLOSED o rifiuto di una richiesta obsoleta.

12. Moduli di comunicazione

I moduli di comunicazione sono separati dall’ambiente di esecuzione, dal modulo di pesatura e dalla gestione dell’applicazione. Ognuno ha requisiti, funzioni, eventi, errori e limiti propri. Le applicazioni senza moduli di comunicazione possono utilizzare normalmente l’ambiente di esecuzione, la diagnostica, i timer e la bilancia.

Tabella 46

Modulo

Supporto in Neutron AppEngine 1.0.0

Capitolo

TCP

Implementato; features.tcp=true

RS-232 / RS-485

Implementato; features.serial=true

MQTT

Implementato; features.mqtt=true

HTTP / REST

Implementato; features.http=true

WebSocket

Implementato; features.websocket=true

Caricare un’applicazione tramite MQTT, HTTP o BLE è un’operazione di gestione. Non abilita quel protocollo nel codice utente. Consultare Installazione e Protocollo APP per le procedure di gestione.

13. Comunicazione TCP

configuredMode: 0 disabled, 1 server, 2 client, 3 both. Il valore d’esempio 1 è illustrativo. maxLineBytes è il limite massimo configurabile; il parser utilizza per impostazione predefinita 1024 byte.

Il modulo TCP configura il server e il client esistenti, ne riserva i flussi per un protocollo personalizzato, invia dati e segnala eventi di connessione. Modalità: disabled, server, client, both. In modalità both vi sono un server con un peer attivo e una connessione client in uscita. L’API non apre un numero arbitrario di socket e non supporta né TLS né nomi DNS; client.host deve essere IPv4. Tutte le funzioni e gli eventi di questo capitolo sono disponibili da Neutron AppEngine 1.0.0.

Prima della configurazione di rete o della riserva, disabilitare il protocollo di pesatura di sistema su I_TCP e i bridge TCP–MQTT e TCP–RS-232/RS-485; altrimenti RESOURCE_IN_USE. La configurazione di rete e la riserva sono separate: configure salva e applica le impostazioni; claim reindirizza i dati all’applicazione. Dopo il successo di configure, utilizzare await tcp.claim().

13.1 tcp.configure()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const status = await tcp.configure(options);
Scopo. Configurare ruoli TCP, parametri di rete e delimitazione delle righe di testo.
Descrizione. I campi omessi restano invariati. Le impostazioni di rete vengono salvate in modo persistente tramite gli attributi esistenti del modulo e si applicano senza riavviare il dispositivo. Un ruolo modificato viene reinizializzato mentre l’altro conserva la connessione. Valori identici non interrompono le connessioni funzionanti. Le modifiche a exclusive influiscono sulle nuove connessioni senza disconnettere il peer corrente. La Promise conferma l’applicazione delle impostazioni, non la connessione a un sistema remoto. In assenza di rete, le impostazioni restano salvate e il ruolo rimane in waitingNetwork. Monitorare state/status per gli errori di connessione. Le impostazioni locali delle righe si applicano dopo il successo e scartano le righe parziali. Fornire solo delimiter/maxLineBytes le applica immediatamente per compatibilità, ma restituisce comunque una Promise.

Parametri

Tabella 47

Parametro

Tipo / requisito

Descrizione

options

object / obbligatorio

Oggetto con campi facoltativi; i campi sconosciuti vengono rifiutati.

options.mode

string / facoltativo

disabled, server, client o both. CTY: 0, 1, 2, 3. Disabled arresta entrambi i ruoli e rilascia la proprietà.

options.server

object / facoltativo

Configurazione server: port ed exclusive.

options.server.port

integer / facoltativo

1–65535; attributo esistente S0C. S0P configura una porta seriale, non TCP.

options.server.exclusive

boolean / facoltativo

S0M: true=1, false=0. True rifiuta nuovi peer mentre il peer corrente è connesso; false consente la sostituzione con un nuovo peer.

options.client

object / facoltativo

Configurazione della connessione in uscita: host e port.

options.client.host

string / facoltativo

Indirizzo IPv4 del server remoto, ad esempio 192.168.50.100. Attributo SIP; nessuno zero iniziale negli ottetti. 0.0.0.0 e 255.255.255.255 sono vietati.

options.client.port

integer / facoltativo

1–65535; attributo SPO.

options.delimiter

string / valore predefinito CRLF

1–8 byte ASCII. Si applica solo al parser dell’applicazione corrente; non viene salvato negli attributi.

options.maxLineBytes

integer / valore predefinito 1024

1–4096 byte di contenuto escluso il delimitatore. Solo applicazione corrente.

Risultato

Promise< object> con un’istantanea di tcp.status(). Le impostazioni del ruolo attivo devono essere complete anche modificando solo parte dell’oggetto. Un aggiornamento parziale è sufficiente con una configurazione valida esistente. Le modifiche SMD tramite BLE, MQTT, HTTP o device.settings.write utilizzano lo stesso meccanismo di applicazione.

Errori e considerazioni particolari

INVALID_ARGUMENT per impostazioni attive non valide o incomplete; la convalida degli argomenti JavaScript genera un’eccezione sincrona. Le richieste di rete possono essere rifiutate con RESOURCE_IN_USE, BUSY, WRITE_FAILED, CONFIGURE_FAILED o OUT_OF_MEMORY. Alcune impostazioni possono già essere salvate dopo un errore di scrittura; gli errori di avvio del server conservano le impostazioni e ritentano l’avvio. Verificare status e correggere la causa. CONFIG_CHANGED interrompe le scritture in sospeso per il ruolo modificato. Una riga troppo grande genera MESSAGE_TOO_LARGE prima della callback line e arresta l’applicazione; try/catch dentro quella callback non può intercettarlo.

Esempio

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

13.2 tcp.claim()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await tcp.claim();
Scopo. Riservare il canale TCP esistente per un protocollo personalizzato.
Descrizione. Richiede il trasferimento dei flussi TCP esistenti all’applicazione utente. Registrare le callback prima della riserva. L’operazione non garantisce che un peer remoto sia connesso.

Parametri

Nessun parametro.

Risultato

Promise<string>, "claimed" in caso di successo. Gli eventi data e l’invio diventano disponibili dopo la connessione. Gli eventi diagnostici connection/state sono disponibili senza riserva; registrare i listener prima di configure/claim.

Errori e considerazioni particolari

NOT_CONFIGURED per modalità TCP disabilitata/non valida, RESOURCE_IN_USE per conflitti con protocollo di sistema o bridge; anche BUSY e OUT_OF_MEMORY.

Esempio

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

13.3 tcp.release()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await tcp.release();
Scopo. Restituire al firmware l’interfaccia TCP riservata.
Descrizione. Chiude le connessioni server/client riservate, rilascia la proprietà e scarta le righe parziali. I listener e i timer JavaScript restano. Il servizio configurato rimane disponibile; il client di sistema può riconnettersi.

Parametri

Nessun parametro.

Risultato

Promise<string>, "released" sul successo. L'applicazione continua a funzionare.

Errori e considerazioni particolari

Errori condivisi BUSY e OUT_OF_MEMORY. Annulla i timer di invio e gestisci le scritture in sospeso prima del rilascio.

Esempio

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

13.4 tcp.write()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const bytesWritten = await tcp.write(data, { connectionId });
Scopo. Inviare testo o dati binari tramite una connessione riservata.
Descrizione. Codifica le stringhe come UTF-8 e invia Uint8Array come byte. Non aggiunge CRLF o altri delimitatori. L’invio è asincrono; le scritture inviate su una connessione mantengono l’ordine, ma la logica utente asincrona può modificare l’ordine di invio.

Parametri

Tabella 48

Parametro

Tipo / requisito

Descrizione

data

string o Uint8Array / obbligatorio

Al massimo 4096 byte per chiamata. I limiti delle stringhe si applicano dopo la codifica UTF-8.

options

object / facoltativo, valore predefinito {}

Opzioni di invio.

options.connectionId

integer / facoltativo

0 o omesso: seleziona l’unico ruolo TCP connesso. Con più ruoli connessi, utilizzare l’ID dell’evento; intervallo 0–4 294 967 295.

Risultato

Promise<number> con i byte accettati per la trasmissione TCP. Non conferma ricezione o elaborazione remote. Definire conferme nel proprio protocollo se necessario.

Errori e considerazioni particolari

Rifiuta con INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, NOT_CONNECTED, CONFIG_CHANGED, BUSY, OUT_OF_MEMORY o TIMEOUT. Il limite di attesa di scrittura è di circa 3 s. Alcuni dati potrebbero essere già stati inviati dopo un errore; non riprovare ciecamente i comandi non idempotenti. Un errore/timeout di scrittura attivo potrebbe chiudere la connessione. L'uso errato dell'argomento JavaScript può anche generare TypeError.

Esempio

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

13.5 tcp.on()

Disponibile dalla versione: Neutron AppEngine 1.0.0
tcp.on(eventName, callback);
Scopo. Registrare un listener di eventi TCP.
Descrizione. Invoca la callback per gli eventi corrispondenti fino a off o alla terminazione dell’applicazione. La stessa funzione può registrarsi ripetutamente; ogni registrazione conta nel limite.

Parametri

Tabella 49

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

Solo "data", "line", "connection" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento. Conservare lo stesso riferimento per off.

Risultato

L’oggetto tcp, che consente di concatenare le registrazioni.

Errori e considerazioni particolari

INVALID_ARGUMENT sincrono per un evento sconosciuto o un valore non funzione. Al massimo 32 listener on/once complessivi; il superamento genera QUOTA_EXCEEDED. Un’eccezione della callback o un rifiuto di Promise non gestiti arrestano l’applicazione. off non ha effetto su una registrazione assente.

Esempio

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

13.6 tcp.once()

Disponibile dalla versione: Neutron AppEngine 1.0.0
tcp.once(eventName, callback);
Scopo. Registrare un listener eseguito una sola volta.
Descrizione. Rimuove il listener prima di invocarlo per il primo evento corrispondente. Rimane registrato se non arriva alcun evento.

Parametri

Tabella 50

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

Solo "data", "line", "connection" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento. Conservare lo stesso riferimento per off.

Risultato

L’oggetto tcp, che consente di concatenare le registrazioni.

Errori e considerazioni particolari

INVALID_ARGUMENT sincrono per un evento sconosciuto o un valore non funzione. Al massimo 32 listener on/once complessivi; il superamento genera QUOTA_EXCEEDED. Un’eccezione della callback o un rifiuto di Promise non gestiti arrestano l’applicazione. off non ha effetto su una registrazione assente.

Esempio

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

13.7 tcp.off()

Disponibile dalla versione: Neutron AppEngine 1.0.0
tcp.off(eventName, callback);
Scopo. Rimuovere un listener.
Descrizione. Rimuove tutte le registrazioni dello stesso riferimento alla callback per l’evento selezionato. Non interrompe una callback async già iniziata. Non passare una nuova funzione anonima per rimuovere un listener esistente.

Parametri

Tabella 51

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

Solo "data", "line", "connection" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento. Conservare lo stesso riferimento per off.

Risultato

L’oggetto tcp, che consente di concatenare le registrazioni.

Errori e considerazioni particolari

INVALID_ARGUMENT sincrono per un evento sconosciuto o un valore non funzione. Al massimo 32 listener on/once complessivi; il superamento genera QUOTA_EXCEEDED. Un’eccezione della callback o un rifiuto di Promise non gestiti arrestano l’applicazione. off non ha effetto su una registrazione assente.

Esempio

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

13.8 Struttura degli eventi TCP

Tabella 52

Evento

Campi

Significato

data

{ connectionId, data: Uint8Array }

Blocco del flusso TCP grezzo. Un evento non corrisponde necessariamente a un comando o a un pacchetto di rete.

line

{ connectionId, line: string }

Riga completa decodificata in UTF-8 senza delimitatore. Le righe vuote sono consentite; gli spazi non vengono rimossi automaticamente.

connection

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

Connessione stabilita o persa durante l’esecuzione dell’applicazione, indipendentemente per ogni ruolo. connectionId identifica la sessione; utilizzare un nuovo ID dopo la riconnessione.

connection.reason: CONNECTED in caso di successo, CONFIG_CHANGED dopo modifiche a indirizzo/porta/ruolo, REPLACED quando viene sostituito un peer del server, NETWORK_DOWN per perdita del servizio di rete, CONNECTION_LOST per perdita della connessione rilevata, DISCONNECTED per chiusura normale, APP_STOPPED per rilascio dopo la terminazione dell’applicazione, RESOURCE_IN_USE per conflitti. Gli eventi dopo la terminazione dell’applicazione non vengono consegnati. timeMs è il tempo monotono del dispositivo in millisecondi, non una data o la durata della connessione. La porta remota di un peer del server è solitamente effimera, non la porta di ascolto del server.

state contiene role, state, connected, connectionId, port, revision, error e timeMs, più le proprietà del ruolo da tcp.status(). Stati server: disabled, waitingNetwork, listening, error. Stati client: disabled, waitingNetwork, connecting, reconnecting, connected, error. Il rilascio dovuto a un conflitto può emettere {role:"all",state:"released",reason:"RESOURCE_IN_USE"}. I tentativi di connessione del client non bloccano l’applicazione o le misurazioni; ciascuno dura fino a circa 3 s, con un nuovo tentativo che inizia circa 5 s dopo un errore o una disconnessione rilevata. Un errore di avvio del server viene ritentato circa ogni 5 s. Il rilevamento della disconnessione fisica non è immediato; dipende dal traffico e dal monitoraggio della connessione.

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);
});
La registrazione non riproduce la cronologia degli eventi. La riserva può notificare una connessione già stabilita. Rispondere sempre utilizzando event.connectionId; non memorizzarlo in modo persistente e non inventare ID.
TCP è un flusso. WEIGHT?\r\n può arrivare in più blocchi e più comandi possono arrivare in un solo blocco. Il parser conserva righe parziali per connessione, assemblando i caratteri UTF-8 parziali prima di decodificare gli eventi line. I delimitatori e le righe incomplete vengono scartati alla disconnessione.

Con un listener line, le righe vengono prima preparate da un blocco del flusso, poi viene emesso data, seguito dalle singole callback line. Registrare entrambi offre due viste degli stessi dati; non elaborare i comandi due volte. Senza un listener line, i dati binari non vengono accumulati in un buffer di righe. I protocolli binari devono implementare propri limiti di lunghezza e assemblaggio dei messaggi.

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

13.9 Errori del modulo TCP

Tabella 53

Codice

Significato per TCP

NOT_CONFIGURED

TCP non è configurato per il funzionamento client/server.

RESOURCE_IN_USE

Il protocollo di pesatura TCP di sistema o un bridge è in conflitto con la riserva.

NOT_OWNER

L’applicazione non possiede TCP oppure è sorto un conflitto di instradamento.

NOT_CONNECTED

La sessione TCP richiesta non è più connessa.

MESSAGE_TOO_LARGE

La scrittura supera 4096 byte o la riga ricevuta è troppo lunga. Un errore interno di riga arresta l’applicazione.

13.10 Limiti del modulo TCP

Tabella 54

Risorsa

Limite

Messaggio TCP

Al massimo 4096 byte per scrittura; i flussi ricevuti possono essere divisi in blocchi più piccoli.

Righe

Valore predefinito 1024; configurabile 1–4096 byte escluso il delimitatore; lunghezza del delimitatore ASCII 1–8 byte.

Listener

Al massimo 32 registrazioni on/once complessive per data, line, connection e state.

13.11 Protocollo TCP personalizzato con CONT / CCONT

Esempio autonomo per un server o client TCP configurato senza instradamento di sistema in conflitto. Ogni riga termina con veri byte CR LF. Gli strumenti esterni devono inviare quei byte, non quattro caratteri letterali barra inversa-r-barra inversa-n. Nel sorgente JavaScript, "\r\n" rappresenta i byte terminatori corretti.

Tabella 55

Comando ricevuto + CRLF

Risposta + CRLF

WEIGHT?

net,gross,unit oppure ERR,NO_MEASUREMENT

CONT

OK; poi una misurazione al secondo per la stessa connessione. Ripetere non crea un intervallo aggiuntivo.

CCONT

OK; annulla gli invii periodici futuri su questa connessione. Una scrittura già iniziata può completarsi.

TARE / ZERO / CLEAR_TARE

OK dopo un’operazione confermata oppure ERR,&lt;code&gt;.

PRESET_TARE 2.5

Imposta la tara nell’unità attualmente configurata; restituisce OK oppure ERR,&lt;code&gt;.

Altro comando

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

Il listener della connessione rimuove l’intervallo alla disconnessione; anche un errore di scrittura periodica lo arresta. Un indicatore di invio impedisce scritture periodiche sovrapposte per connessione. L’esempio non implementa log persistente, conferma dell’elaborazione remota o ID di richiesta. Aggiungere ID, risposte e regole di ritentativo con limiti quando necessario.

13.12 Chiusura TCP e concorrenza

app.stop() chiude le connessioni TCP riservate e rilascia la proprietà. Il server configurato rimane disponibile e il client può riconnettersi secondo la logica di sistema. Utilizzare tcp.release() per restituire TCP senza arrestare l’applicazione. Più comandi ricevuti possono sovrapporre elaborazioni asincrone; per un ordine rigoroso, fare attendere al client una risposta oppure implementare una coda limitata. clearInterval non annulla una scrittura già iniziata.

13.13 Test di un’applicazione TCP

Tabella 56

Test

Risultato previsto

Comando TCP diviso tra più ricezioni

La callback line si attiva solo dopo il delimitatore completo.

CONT due volte, poi CCONT due volte

Un intervallo per connessione; l’annullamento ripetuto è innocuo.

Disconnessione/riconnessione

I vecchi intervalli e ID non vengono riutilizzati; la nuova sessione è indipendente.

Scrittura TCP lenta/non riuscita

Nessun lavoro periodico sovrapposto o coda illimitata.

13.14 tcp.status()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const status = tcp.status();
Scopo. Leggere configurazione e stato correnti di entrambi i ruoli TCP.
Descrizione. Istantanea sincrona dell’ultimo ciclo di servizio. Non apre connessioni, non riserva interfacce e non legge dati del flusso. pending significa che le impostazioni salvate attendono l’applicazione nel ciclo di servizio successivo. Lo stato della connessione continua a cambiare dopo configure; utilizzare gli eventi connection/state per proseguire dopo la connessione.

Parametri

Nessun parametro.

Risultato

Oggetto: mode (disabled/server/client/both), configuredMode (0/1/2/3), claimed, pending, server e client. Entrambi i ruoli contengono state, connected, connectionId (0 se disconnesso), port, revision ed error. server include anche listening, exclusive, remoteAddress e remotePort; client include host, remoteAddress e remotePort. error vuoto significa nessun errore registrato. revision cambia con le modifiche a endpoint/ruolo; non è un contatore dei dati ricevuti. Questa istantanea informativa può cambiare immediatamente dopo la lettura.

Errori e considerazioni particolari

Nessuna richiesta di rete. Un’istantanea connessa non garantisce il successo di una scrittura successiva; gestire sempre il rifiuto della scrittura.

Esempio

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

Esempio di configurazione e protocollo WEIGHT? di base per entrambi i ruoli: scegliere la modalità desiderata nella configurazione e adattare indirizzo/porta. Le risposte utilizzano il connectionId dell’evento ricevuto e quindi funzionano con entrambi i ruoli connessi.

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

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

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

14. RS-232 / RS-485

Una porta è disponibile per l’applicazione solo quando la sua funzione di sistema è Disabled: S0E=0 per RS-232 o S1E=0 per RS-485. Non deve essere assegnata a un protocollo di pesatura di sistema, Modbus, uscita di debug o inoltro. claim() non disabilita automaticamente queste funzioni.

Il modulo seriale fornisce due oggetti indipendenti: serial.rs232 e serial.rs485, con la stessa API. Un’applicazione può riservare una o entrambe le porte. Non è richiesto alcun altro modulo di comunicazione. Tutte le funzioni e gli eventi di questo capitolo sono disponibili da Neutron AppEngine 1.0.0.

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

14.1 port.claim()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await port.claim();
Scopo. Riservare in esclusiva la porta seriale selezionata.
Descrizione. Verifica che la porta sia Disabled e libera, quindi la prepara utilizzando le impostazioni fisiche memorizzate. Attende il successo dell’inizializzazione. È consentito ripetere una riserva riuscita senza reinizializzare impostazioni invariate.

Parametri

Nessun parametro.

Risultato

Promise< string>, "claimed" in caso di successo. Registrare i listener prima della riserva se necessario. La presenza del dispositivo remoto non viene verificata.

Errori e considerazioni particolari

RESOURCE_IN_USE per una funzione di sistema abilitata o altro conflitto; BUSY per operazioni di controllo concorrenti; RECONFIGURE_FAILED, TIMEOUT o OUT_OF_MEMORY. Una porta configurata in modo errato non viene riservata silenziosamente.

Esempio

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

14.2 port.configure()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await port.configure(options);
Scopo. Configurare velocità di trasmissione, formato dei caratteri e parsing locale dei messaggi.
Descrizione. Asincrono, consentito dopo claim(). Associa i parametri fisici alle impostazioni SMD esistenti, li convalida e li salva in modo persistente. Reinizializza la porta una sola volta per l’intera richiesta; la Promise viene risolta dopo l’applicazione. Le impostazioni omesse restano invariate. Riapplicare valori identici già applicati con successo evita reinizializzazioni inutili.

Parametri

Tabella 57

Parametro

Tipo / requisito

Descrizione

options

object / obbligatorio

Oggetto con i campi facoltativi seguenti. I campi sconosciuti vengono rifiutati.

baudRate

integer / facoltativo

300–1 000 000 bit/s. Corrisponde a S0B o S1B.

dataBits

integer / facoltativo

7 o 8. Corrispondenza S0I/S1I: 0 significa 7 bit, 1 significa 8 bit.

stopBits

integer / facoltativo

1 o 2. Corrisponde a S0S/S1S.

parity

string / facoltativo

"none", "even" o "odd". Corrispondenza S0P/S1P: 0, 1 o 2.

delimiter

string / facoltativo, valore predefinito CRLF

1–8 caratteri ASCII, solo per l’assemblaggio degli eventi line nell’applicazione corrente.

maxLineBytes

integer / facoltativo, valore predefinito 1024

1–4096 byte di contenuto della riga escluso il delimitatore. Solo applicazione corrente.

Risultato

Promise< string>, "configured" in caso di successo. Le impostazioni fisiche persistono dopo release(), Stop e riavvio. Delimiter e maxLineBytes non vengono salvati in SMD; si applicano al parser JavaScript corrente.

Errori e considerazioni particolari

INVALID_ARGUMENT, NOT_OWNER, RESOURCE_IN_USE, BUSY, SETTINGS_FAILED, RECONFIGURE_FAILED, CONFIG_CHANGED, TIMEOUT o OUT_OF_MEMORY. Un errore di salvataggio può lasciare alcune impostazioni fisiche salvate; un errore di applicazione non significa che le impostazioni non siano state salvate. Correggere la causa e ritentare configurazione/riserva. La configurazione del parser locale cambia solo dopo il successo. Se un altro canale modifica le impostazioni fisiche richieste prima della conferma, la chiamata viene rifiutata con CONFIG_CHANGED.

Esempio

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

14.3 Modifiche alle impostazioni senza riavvio

Lo stesso percorso di applicazione gestisce le richieste SMD di tutti i canali di gestione. Modificare velocità, bit dati, bit di stop, parità o funzione della porta non richiede un riavvio di Neutron. Vengono aggiornati anche i terminatori di sistema, le impostazioni di aggiunta del terminatore, l’indirizzo RS-485 e le relative assegnazioni delle porte. L’altra porta viene reinizializzata solo se interessata.

Durante la transizione, le nuove scritture vengono temporaneamente rifiutate o trattenute. I byte già inviati vengono trasmessi entro un termine limitato; i frame ricevuti incompleti vengono scartati. Terminano le vecchie richieste di pesatura, l’uscita continua di sistema e le sessioni della porta interessata. Le modifiche a velocità o formato possono causare perdita di dati, quindi eseguirle durante un’interruzione concordata della comunicazione. Il mancato completamento della trasmissione o l’impossibilità di aprire la nuova configurazione segnala RECONFIGURE_FAILED.

Se SMD esterno assegna un’altra funzione di sistema o causa un conflitto mentre JavaScript possiede la porta, la riserva viene revocata. L’applicazione riceve state con reason="RESOURCE_IN_USE" e claimed=false; le nuove scritture restituiscono NOT_OWNER. Le modifiche consentite alle impostazioni fisiche mantengono la proprietà ed emettono RECONFIGURED. Le righe JavaScript parziali vengono scartate; il delimitatore JavaScript configurato resta.

Tabella 58

Verifica tramite RMD

Significato

S0APPLY / S1APPLY

PENDING: in attesa dell’applicazione; OK: configurazione applicata; ERROR: applicazione non riuscita.

S0JS / S1JS

1 significa riservata dall’applicazione; 0 significa nessuna riserva JavaScript.

S0REV / S1REV

Contatore delle modifiche di stato della porta applicate; non è un ID di sessione persistente.

S0STATE / S1STATE

Ultimo stato: READY, DISABLED, CLAIMED, RECONFIGURED, RELEASED, RESOURCE_IN_USE o RECONFIGURE_FAILED.

Una normale risposta SMD conferma il salvataggio; l’applicazione fisica segue nel ciclo di elaborazione successivo del dispositivo. Per una conferma esterna, utilizzare i campi RMD APPLY o i log di debug. port.configure() attende già l’applicazione. Questi campi RMD sono diagnostici, non impostazioni SMD scrivibili. Ripetere SMD identico dopo un errore ritenta l’applicazione; dopo il successo, valori identici non riaprono la porta.

14.4 port.write()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const bytes = await port.write(data, { timeoutMs });
Scopo. Inviare in modo asincrono testo o byte binari.
Descrizione. Codifica le stringhe come UTF-8; invia Uint8Array invariato. Non aggiunge terminatore, indirizzo RS-485 o checksum. Le scritture su una porta seguono l’ordine delle richieste; le relative Promise non confermano l’elaborazione remota.

Parametri

Tabella 59

Parametro

Tipo / requisito

Descrizione

data

string o Uint8Array / obbligatorio

Al massimo 4096 byte dopo la codifica UTF-8; sono consentite scritture vuote.

options

object / facoltativo, valore predefinito {}

Opzioni di attesa.

options.timeoutMs

integer / facoltativo

1–180000 ms. Il valore predefinito viene calcolato da lunghezza e velocità con un margine e un minimo di 3 s.

Risultato

Promise< number> con i byte accettati per la trasmissione. Utilizzare drain() per attendere il completamento della trasmissione fisica.

Errori e considerazioni particolari

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT o OUT_OF_MEMORY. Alcuni byte potrebbero essere già stati inviati dopo l'interruzione o il timeout. CONFIG_CHANGED significa configurazione modificata durante l'attesa; i restanti byte della vecchia richiesta non vengono inviati con le nuove impostazioni.

Esempio

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

14.5 port.drain()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await port.drain({ timeoutMs });
Scopo. Attendere il completamento della trasmissione fisica.
Descrizione. Attende dopo le scritture precedenti sulla stessa porta, quindi verifica che i byte in sospeso siano stati trasmessi. L’ambiente di esecuzione elabora altri eventi durante l’attesa.

Parametri

Tabella 60

Parametro

Tipo / requisito

Descrizione

options

object / facoltativo, valore predefinito {}

Opzioni di attesa.

options.timeoutMs

integer / facoltativo, valore predefinito 6000

1–60000 ms.

Risultato

Promise< undefined>. Non attende una risposta remota né conferma che un bus RS-485 utilizzato da altri dispositivi sia libero.

Errori e considerazioni particolari

INVALID_ARGUMENT, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT o OUT_OF_MEMORY. Impostare un termine di comunicazione adatto; la scadenza non annulla i byte trasmessi.

Esempio

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

14.6 port.release()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const result = await port.release();
Scopo. Rilasciare la riserva dell’applicazione sulla porta selezionata.
Descrizione. Arresta le nuove scritture dell’applicazione, completa la transizione e rilascia la proprietà. Una porta ancora Disabled a livello di sistema e senza altri utilizzi viene chiusa. Le impostazioni fisiche memorizzate in modo persistente restano. Non disabilita una funzione di sistema che nel frattempo ha preso il controllo della porta.

Parametri

Nessun parametro.

Risultato

Promise< string>, "released" in caso di successo. È consentito ripetere la chiamata. La ricezione locale parziale viene scartata; callback registrate e timer restano.

Errori e considerazioni particolari

BUSY, RECONFIGURE_FAILED, TIMEOUT o OUT_OF_MEMORY. Annullare i timer di invio prima del rilascio. I byte già trasmessi non possono essere ritirati. Stop dell’applicazione rilascia automaticamente entrambe le sue porte.

Esempio

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

14.7 port.on()

Disponibile dalla versione: Neutron AppEngine 1.0.0
port.on(eventName, callback);
Scopo. Registrare un listener di eventi seriali.
Descrizione. Gli eventi appartengono alla porta selezionata. once rimuove la registrazione prima di invocare la callback. off richiede lo stesso riferimento alla funzione e non interrompe una callback async già iniziata.

Parametri

Tabella 61

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

"data", "line" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento.

Risultato

L'oggetto porta selezionato; la registrazione dell'ascoltatore può essere concatenata.

Errori e considerazioni speciali

INVALID_ARGUMENT per un evento o callback non valido; QUOTA_EXCEEDED sopra 32 ascoltatori per porta. Le eccezioni o i rifiuti di richiamata non gestiti interrompono l'applicazione. off non ha effetto in caso di registrazione assente.

Esempio

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

14.8 port.once()

Disponibile dalla versione: Neutron AppEngine 1.0.0
port.once(eventName, callback);
Scopo. Ascoltare solo il primo evento corrispondente.
Descrizione. Gli eventi appartengono alla porta selezionata. once rimuove la registrazione prima di invocare la callback. off richiede lo stesso riferimento alla funzione e non interrompe una callback async già iniziata.

Parametri

Tabella 62

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

"data", "line" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento.

Risultato

L'oggetto porta selezionato; la registrazione dell'ascoltatore può essere concatenata.

Errori e considerazioni speciali

INVALID_ARGUMENT per un evento o callback non valido; QUOTA_EXCEEDED sopra 32 ascoltatori per porta. Le eccezioni o i rifiuti di richiamata non gestiti interrompono l'applicazione. off non ha effetto in caso di registrazione assente.

Esempio

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

14.9 port.off()

Disponibile dalla versione: Neutron AppEngine 1.0.0
port.off(eventName, callback);
Scopo. Rimuovere un listener.
Descrizione. Gli eventi appartengono alla porta selezionata. once rimuove la registrazione prima di invocare la callback. off richiede lo stesso riferimento alla funzione e non interrompe una callback async già iniziata.

Parametri

Tabella 63

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

"data", "line" o "state".

callback

function / obbligatorio

Funzione che riceve un oggetto evento.

Risultato

L'oggetto porta selezionato; la registrazione dell'ascoltatore può essere concatenata.

Errori e considerazioni speciali

INVALID_ARGUMENT per un evento o callback non valido; QUOTA_EXCEEDED sopra 32 ascoltatori per porta. Le eccezioni o i rifiuti di richiamata non gestiti interrompono l'applicazione. off non ha effetto in caso di registrazione assente.

Esempio

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

14.10 Eventi e delimitazione dei messaggi

Tabella 64

Evento

Oggetto

Descrizione

data

{ data: Uint8Array }

Blocco del flusso grezzo; un evento non corrisponde necessariamente a un pacchetto di protocollo. NUL e gli altri byte binari vengono preservati.

line

{ line: string }

Riga UTF-8 assemblata senza delimitatore; i blocchi di messaggio divisi vengono riassemblati. Gli spazi non vengono rimossi automaticamente.

state

{ port, claimed, reason, generation }

port è rs232 o rs485. claimed è boolean; reason identifica la transizione; generation cambia quando viene applicato lo stato della porta.

Con un listener line, la ricezione viene assemblata fino al delimitatore. Un listener data sulla stessa porta riceve un’altra vista del flusso; non elaborare un comando due volte. Le righe troppo grandi causano MESSAGE_TOO_LARGE prima della callback line e possono arrestare l’applicazione. Senza listener line, i dati binari grezzi non vengono accumulati in un buffer di righe. Gli eventi precedenti alla reinizializzazione non vengono riutilizzati come dati nella nuova configurazione.

Le porte seriali non hanno un evento connection: cavi scollegati o dispositivi spenti generalmente non sono rilevabili in modo affidabile. state descrive proprietà e impostazioni di Neutron AppEngine, non la connettività fisica. Verificare la raggiungibilità tramite risposte e timeout del proprio protocollo. Le applicazioni RS-485 implementano indirizzamento, CRC e regole di accesso al bus condiviso; il filtro di sistema R4A non si applica ai dati grezzi mentre JavaScript possiede la porta.

14.11 Applicazione RS-232 / RS-485 completa

Impostare la funzione della porta scelta su Disabled e rimuovere le altre assegnazioni. L’applicazione seguente la riserva, configura in modo persistente 19200/8N1 e risponde a WEIGHT? con net,gross,unit. Per l’altra porta, modificare solo l’oggetto selezionato. Configurare lo stesso formato dei caratteri sul dispositivo remoto.

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

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

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

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

14.12 Test di integrazione

Tabella 65

Test

Risultato previsto

Riserva con una funzione di sistema abilitata

RESOURCE_IN_USE; l’utilizzo di sistema resta invariato.

Configurare tramite JavaScript e separatamente tramite SMD

Velocità/parità/bit si applicano senza riavviare il dispositivo.

Modificare una porta

L’altra porta conserva dati e funzionamento se non interessata.

Presa di controllo esterna durante il funzionamento JavaScript

state RESOURCE_IN_USE, claimed=false; le nuove scritture restituiscono NOT_OWNER.

Byte binari e una riga divisa tra più ricezioni

Nessuna perdita di NUL o delimitatore duplicato; una riga assemblata correttamente.

Riconfigurare durante una ricezione o scrittura parziale

Le vecchie righe parziali vengono scartate; le vecchie scritture residue non vengono inviate con le nuove impostazioni.

Rilasciare / Stop e riservare nuovamente

Nessuna porta occupata permanentemente; le impostazioni fisiche persistono.

15. Modulo MQTT

Questo modulo non esegue automaticamente i comandi CSCP. L’applicazione definisce significati dei topic, formato del payload e comandi consentiti. mqtt.connect() si collega al broker utente, non modifica la connessione di sistema Scale Monitor e non richiede claim().
Il modulo mqtt fornisce all’applicazione utente una connessione indipendente a un broker, separata dalla connessione di sistema Scale Monitor. Entrambe possono funzionare contemporaneamente con indirizzi, identità, credenziali e sottoscrizioni diversi. L’applicazione non riserva i topic di sistema. Supporto: app.capabilities().features.mqtt === true. Tutte le funzioni, gli eventi e le proprietà di questo capitolo sono disponibili da Neutron AppEngine 1.0.0.
Tabella 66

URL

Connessione

Esempio

mqtt://

MQTT su TCP

mqtt://broker.example.com:1883

mqtts://

MQTT con autenticazione del server TLS

mqtts://broker.example.com:8883

ws://

MQTT su WebSocket

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

wss://

MQTT su WebSocket sicuro

wss://broker.example.com/mqtt

Protocollo: MQTT 3.1.1; l’API supporta QoS 0 e 1. Un URL WebSocket deve puntare al listener MQTT del broker, non a un server WebSocket arbitrario. Sono necessari accesso alla rete, impostazioni DNS corrette e un broker raggiungibile. L’orologio del dispositivo deve essere corretto per verificare la validità dei certificati.

Ciclo di vita della connessione

Registrare prima i listener, quindi await mqtt.configure(...), await mqtt.connect() e await mqtt.subscribe(...). La configurazione dura per l’esecuzione corrente dell’applicazione e viene scartata alla terminazione. Includerla nell’avvio per l’avvio automatico dell’applicazione. Non riconnettersi a ogni iterazione del timer.
Dopo una connessione riuscita, la disconnessione attiva per impostazione predefinita la riconnessione automatica, con un ritardo limitato che raddoppia fino a 60 secondi. Le sottoscrizioni confermate con successo vengono ripristinate automaticamente, in modo asincrono. connect e il completamento di connect() confermano la connessione, non il completamento di tutte le sottoscrizioni ripristinate. Gli errori di ripristino emettono error. Prima della prima connessione riuscita, un tentativo fallito viene rifiutato; l’applicazione decide se riprovare.
Un disconnect() esplicito, un errore di autenticazione o l’overflow della coda degli eventi arresta la riconnessione automatica. Una normale perdita di rete dopo una connessione riuscita causa la riconnessione se abilitata. Arrestare o sostituire l’applicazione chiude solo la propria connessione MQTT. La chiusura ordinata asincrona non conferma la consegna delle pubblicazioni finali. La connessione di sistema continua in modo indipendente.

mqtt.configure(options)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.configure(options);
Scopo. Configurare il broker e l’identità dell’applicazione.
Descrizione. Convalida e sostituisce le impostazioni solo quando il client utente non è connesso, non si sta connettendo e non attende una riconnessione. Attendere disconnect() prima di modificarle. Una nuova configurazione riuscita cancella le sottoscrizioni memorizzate; un errore conserva la configurazione precedente.

Parametri

Tabella 67

Parametro

Tipo / requisito

Descrizione

options

object / obbligatorio

Le proprietà sono elencate di seguito. Le proprietà sconosciute vengono rifiutate; i valori devono utilizzare i tipi documentati.

Risultato

Promise<undefined>. Conferma la configurazione e il caricamento dei profili di certificato richiesti; non si connette.

Errori e considerazioni particolari

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, BUSY, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, OUT_OF_MEMORY. Un contenuto PEM non valido può causare un errore solo durante la connessione TLS.

Esempio

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

Proprietà di options

Tipo/predefinito

Significato e limiti

url

string / obbligatorio

Fino a 512 byte UTF-8. Uno dei quattro schemi. Nell’URL non sono consentiti nome utente/password, spazi o frammenti #. Includere il percorso ws/wss corretto, ad esempio /mqtt.

clientId

string / automatico

Fino a 64 UTF-8 byte. Se assente o vuoto, il dispositivo assegna un'identità utente-applicazione stabile. Due connessioni simultanee allo stesso broker non devono condividere un clientId.

username, password

string / nessuno

Al massimo 256 e 512 UTF-8 byte rispettivamente. Non registrarli mai sulla console; il codice dell'applicazione non è un deposito segreto.

keepAlive

integer / 60

Secondi, 5..3600.

cleanSession

boolean / true

false abilita una sessione persistente del broker per lo stesso clientId. L’API dell’applicazione ripristina comunque le sottoscrizioni confermate; le sottoscrizioni presenti solo sul broker non fanno parte dell’elenco locale.

reconnect

boolean / true

Riconnessione automatica dopo aver perso una connessione stabilita. Non ripete l'accesso iniziale non riuscito o l'esplicito disconnect().

connectTimeoutMs

integer / 10000

1000..60000 ms. Termine per la connessione del client e per le operazioni di rete.

reconnectDelayMs

integer / 1000

1000..60000 ms. Ritardo iniziale, raddoppio in caso di disconnessioni ripetute fino a 60000 ms e ripristino dopo il successo.

will

object / nessuno

{topic, payload, qos?, retain?}. topic è un topic di pubblicazione; payload è string. qos: 0 o 1, valore predefinito 0; retain: boolean, valore predefinito false. Il broker pubblica il will dopo una disconnessione imprevista secondo le regole MQTT; non farvi affidamento dopo una chiusura ordinata.

tls

object / nessuno

Solo mqtts/wss. Proprietà: caProfile, clientCertificateProfile, clientKeyProfile. Vedi TLS di seguito.

L’intero JSON delle opzioni deve rientrare in 4096 byte UTF-8, inclusi nomi delle proprietà ed escape. La capacità effettiva di will.payload è quindi inferiore a 4096 byte. Le stringhe di configurazione non possono contenere NUL; utilizzare publish() per i dati binari. Le impostazioni del client utente sono indipendenti da quelle del broker di sistema.

mqtt.connect(options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.connect({ timeoutMs: 15000 });
Scopo. Connettersi al broker configurato.
Descrizione. La Promise viene soddisfatta alla conferma della connessione riuscita al broker. Le chiamate quando già connesso riescono. Un secondo tentativo di connessione contemporaneo viene rifiutato con BUSY.

Parametri

Tabella 69

Parametro

Tipo / requisito

Descrizione

options.timeoutMs

integer / facoltativo

1..60000 ms; il valore predefinito è il connectTimeoutMs configurato. Si applica al tentativo di connessione; l’attesa nella coda di servizio e l’arresto del client possono prolungare il tempo totale.

Risultato

Promise<undefined>. Le informazioni sulla connessione sono disponibili anche in connect e status().

Errori e considerazioni particolari

NOT_CONFIGURED, BUSY, START_FAILED, AUTH_FAILED, CONNECTION_REFUSED, NOT_CONNECTED, TIMEOUT, CANCELLED. Cause di rete/TLS più dettagliate possono comparire in error o status().lastError. Limitare i ritentativi dei tentativi iniziali falliti.

Esempio

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

mqtt.disconnect()

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.disconnect();
Scopo. Chiudere la connessione utente in modo pulito e interrompere la riconnessione.
Descrizione. Annulla le operazioni connect, publish, subscribe e unsubscribe in sospeso; gestirne le Promise. La configurazione e le sottoscrizioni confermate restano per il successivo connect nella stessa esecuzione; configure le sostituisce.

Parametri

Nessun parametro.

Risultato

Promise<undefined> dopo la chiusura del client. Le chiamate quando già disconnesso riescono.

Errori e considerazioni particolari

NOT_CONFIGURED prima della configurazione iniziale. Le operazioni interrotte ricevono CANCELLED. Non annulla le pubblicazioni già accettate dal broker. Non invia messaggi aziendali offline automatici; pubblicane e confermane uno prima disconnect() se richiesto.

Esempio

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

mqtt.status()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const status = mqtt.status();
Scopo. Restituisce lo stato corrente della connessione dell'utente senza attendere.
Descrizione. Restituisce una copia dell'ultimo stato, non una garanzia del successo della successiva operazione di rete. Non rivela nome utente, password o certificati.

Parametri

Nessun parametro.

Risultato

{configured:boolean, connected:boolean, state:string, reconnectAttempts:number, lastError:string}. state: unconfigured, disconnected, connecting, connected, reconnecting. reconnectAttempts conta gli avvii di riconnessione automatica dall’ultimo configure. lastError è vuoto o contiene l’ultimo codice di errore; una connessione riuscita lo cancella.

Errori e considerazioni particolari

Sincrono; non si connette. Lo stato della rete può cambiare tra la lettura e l'operazione successiva.

Esempio

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

mqtt.subscribe(topic, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.subscribe("factory/+/command", { qos: 1, timeoutMs: 10000 });
Scopo. Sottoscrivere un topic o un filtro di topic.
Descrizione. Attende SUBACK del broker; il rifiuto del broker non è un successo. Le sottoscrizioni confermate vengono memorizzate per la riconnessione. Ripetere un filtro non occupa un altro slot; una conferma riuscita sostituisce il QoS richiesto. Il broker può concedere un QoS inferiore.

Parametri

Tabella 70

Parametro

Tipo / requisito

Descrizione

topic

string / obbligatorio

1..192 UTF-8 byte.+ deve occupare un intero livello, # tutto il livello finale; ad esempio factory/+/command o factory/#.

options.qos

integer / 0

0 o 1.

options.timeoutMs

integer / 10000

1..60000 ms per la conferma del broker.

Risultato

Promise<undefined> dopo SUBACK riuscito. Le pubblicazioni in arrivo emettono message.

Errori e considerazioni particolari

NOT_CONFIGURED, NOT_CONNECTED, SUBSCRIBE_FAILED, QUOTA_EXCEEDED, BUSY, TIMEOUT. Al massimo 16 filtri. subscribe/unsubscribe concorrenti per lo stesso filtro ricevono BUSY. Le richieste offline non vengono accodate per un secondo momento.

Esempio

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

mqtt.unsubscribe(topic, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.unsubscribe("factory/scale-01/command");
Scopo. Annullare la sottoscrizione del filtro esatto e rimuoverlo dall’elenco di riconnessione.
Descrizione. Confermato da UNSUBACK. È possibile annullare la sottoscrizione di filtri sconosciuti. Non rimuove i messaggi già ricevuti né altre sottoscrizioni sovrapposte.

Parametri

Tabella 71

Parametro

Tipo / requisito

Descrizione

topic

string / obbligatorio

Filtro esatto di cui annullare la sottoscrizione; fino a 192 byte UTF-8.

options.timeoutMs

integer / 10000

1..60000 ms.

Risultato

Promise<undefined> dopo UNSUBACK.

Errori e considerazioni particolari

NOT_CONFIGURED, NOT_CONNECTED, BUSY, TIMEOUT, CANCELLED. Per sostituire i filtri ricordati mentre sei disconnesso, usa configure; sostituisce la lista locale completa ma non garantisce la rimozione della vecchia sessione del broker.

Esempio

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

mqtt.publish(topic, payload, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
await mqtt.publish(topic, payload, { qos: 1, retain: false });
Scopo. Pubblica testo o dati binari.
Descrizione. Invia le stringhe come UTF-8 e Uint8Array come byte esatti; non aggiunge CR, LF o NUL. Copia payload al momento della chiamata. L’invio parte da un’attività di comunicazione separata dopo l’elaborazione della richiesta. QoS 0 conferma una scrittura riuscita sul trasporto; QoS 1 attende PUBACK del broker. Nessuno dei due conferma l’elaborazione da parte del sottoscrittore finale.

Parametri

Tabella 72

Parametro

Tipo / requisito

Descrizione

topic

string / obbligatorio

1..192 UTF-8 byte, senza + o #.

payload

string | Uint8Array / obbligatorio

0..4096 byte dopo la codifica UTF-8; i dati binari possono contenere NUL.

options.qos

integer / 0

0 o 1; QoS 2 non è supportato.

options.retain

boolean / false

Conservare il messaggio sul broker. Un payload vuoto con retain=true rimuove il valore conservato del topic.

options.timeoutMs

integer / 10000

1..60000 ms. Termine per PUBACK con QoS 1; QoS 0 non attende il broker.

Risultato

Promise<undefined>; il significato della conferma dipende dal QoS.

Errori e considerazioni particolari

NOT_CONNECTED offline; nessuna coda offline illimitata. BUSY per una coda in uscita completa (32768 byte incluso l'overhead del protocollo) o limite di operazioni in sospeso. MESSAGE_TOO_LARGE, INVALID_ARGUMENT, NETWORK_ERROR, TIMEOUT, CANCELLED. Il broker potrebbe aver già ricevuto un messaggio dopo il timeout/disconnessione. QoS 1 potrebbe duplicare la consegna; utilizzare gli ID di richiesta e la deduplicazione per le operazioni aziendali.

Esempio

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

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

Disponibile dalla versione: Neutron AppEngine 1.0.0
mqtt.on(eventName, callback);
mqtt.once(eventName, callback);
mqtt.off(eventName, callback);
Scopo. Registrare o rimuovere un listener di eventi del broker utente.
Descrizione. Gli eventi vengono eseguiti in sequenza. Una callback async cede l’esecuzione in await; utilizzare una protezione contro le sovrapposizioni quando l’ordine è importante. once rimuove la registrazione prima dell’invocazione. off rimuove tutte le registrazioni della stessa funzione per l’evento selezionato.

Parametri

Tabella 73

Parametro

Tipo / requisito

Descrizione

eventName

string / obbligatorio

connect, disconnect, message o error.

callback

function / obbligatorio

Riceve un oggetto con i campi elencati di seguito. Mantenere lo stesso riferimento alla funzione per off.

Risultato

Restituisce mqtt per il concatenamento. Al massimo 32 ascoltatori in tutti gli eventi MQTT.

Errori e considerazioni particolari

INVALID_ARGUMENT, QUOTA_EXCEEDED. error da solo non arresta l’applicazione; un’eccezione del listener o una Promise rifiutata non gestite la arrestano secondo le regole dell’ambiente di esecuzione. Il rifiuto dell’operazione ed error sono notifiche separate senza un ordine relativo garantito.

Esempio

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

Evento

Campi dalla versione Neutron AppEngine 1.0.0

Significato

connect

connected: true, reconnected: boolean, sessionPresent: boolean

CONNACK accettato. reconnected indica una precedente connessione riuscita con la configurazione corrente. sessionPresent è l’indicatore della sessione ripristinata del broker, non l’elenco delle sottoscrizioni confermate localmente.

disconnect

connected: false, reason: string

Perdita di una connessione stabilita o disconnessione esplicita. Gestire la Promise di un connect iniziale fallito. Non è garantito alcun evento alla terminazione dell’applicazione.

message

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

Messaggio MQTT completo, assemblato prima dai frammenti. text è una vista UTF-8; utilizzare data per payload binari arbitrari. qos è il QoS del messaggio ricevuto (l’API richiede al massimo 1, ma il broker può conservare sottoscrizioni più vecchie).

error

Errore con code: string e message: string

Errore di connessione, TLS, ripristino delle sottoscrizioni, messaggio troppo grande o coda. L’applicazione decide come proseguire; esaminare status() e le operazioni in sospeso.

TLS e profili di certificato

mqtts e wss verificano il nome del server e l’attendibilità del certificato. Senza caProfile, viene utilizzata l’attendibilità incorporata delle CA pubbliche. Utilizzare un profilo personalizzato per le CA private. La disattivazione della verifica dei certificati non fa parte dell’API. Le impostazioni e i certificati del broker di sistema non si applicano alle connessioni utente.

Tabella 75

campo tls

Profilo memorizzato

Scopo

caProfile: "company-ca"

JCA_company-ca

PEM di una CA attendibile o catena di CA.

clientCertificateProfile: "device-01"

JCC_device-01

Certificato cliente PEM per mutuo TLS.

clientKeyProfile: "device-01"

JCK_device-01

PEM della chiave privata del client; richiesto insieme al certificato. Le chiavi cifrate con password non sono supportate in questa versione.

I nomi dei profili contengono 1..48 caratteri: A–Z, a–z, 0–9, _ oppure -. Ogni PEM normalizzato è al massimo 16384 byte. Un integratore autorizzato predispone i profili tramite il percorso SMD dei certificati esistente, ad esempio JCA_company-ca=<PEM>, con il certificato PEM completo come valore. Non è un percorso di file, un URL pubblico o un profilo MCA di sistema. Un valore vuoto elimina un profilo secondo le regole esistenti dei certificati. Le applicazioni caricano i profili durante configure; modificare i profili memorizzati non sostituisce i certificati della connessione attiva. Eseguire disconnect, configure, quindi 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();

Limiti, errori e ripristino

Tabella 76

Limite dalla versione Neutron AppEngine 1.0.0

Valore / gestione

Connessioni

Una connessione utente, separata dalla connessione di sistema Scale Monitor.

Payload

4096 byte per messaggio inviato o ricevuto: l'intero messaggio, non ogni frammento.

Topic / sottoscrizioni / listener

192 byte UTF-8 / 16 filtri confermati / 32 listener.

Operazioni in sospeso

Al massimo 8, condivise con le altre operazioni asincrone dell’ambiente di esecuzione. Coda MQTT in uscita: 32768 byte.

Scadenza

Al massimo 60000 ms per la connessione o la conferma del broker. Non garantisce un tempo di risposta esatto del dispositivo.

Messaggio in arrivo di grandi dimensioni

Intero messaggio scartato; errore MESSAGE_TOO_LARGE. I messaggi parziali non vengono recapitati.

Overflow della coda del servizio

EVENT_OVERFLOW chiude la connessione utente e arresta la riconnessione. L’ambiente di esecuzione ha un’altra coda limitata; il suo overflow arresta l’applicazione.

Timeout della conferma

L’operazione in sospeso viene rifiutata e la riconnessione segue le regole configurate. Le altre operazioni possono ricevere NOT_CONNECTED. Una conferma tardiva di una vecchia connessione non conferma mai una nuova richiesta.

Disconnessione durante la pubblicazione

Le operazioni non confermate vengono rifiutate; l’applicazione decide se riprovare. Gli effetti già prodotti non vengono annullati.

Codici principali: 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. I messaggi di errore sono diagnostici; basare le decisioni del programma su code. Per gli errori TLS, verificare ora del dispositivo, nome del server, catena di attendibilità e certificato client richiesto.

Esempio completo: pubblica peso e ricevi comandi

Adattare brokerUrl, baseTopic e credenziali prima dell’esecuzione. Ogni dispositivo richiede clientId e topic propri. Inviare i comandi a /command senza retain. L’esempio pubblica periodicamente il peso, ripristina automaticamente le sottoscrizioni confermate e non ripete la tara per comandi conservati. Per i sistemi che ritentano richieste QoS 1, aggiungere ID di richiesta e un registro dei comandi eseguiti; retain da solo non impedisce la consegna duplicata.

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

Tabella 77

Test

Risultato previsto

Connessione al sistema e broker utente contemporaneamente

Scale Monitor continua; i topic utente sono gestiti solo dall’applicazione.

Pubblicare WEIGHT? sul /command selezionato

La misura JSON arriva su /reply;/weight si aggiorna circa ogni secondo.

Perdita e ripristino della rete

status diventa reconnecting, quindi arriva connect con reconnected=true e ripristino automatico delle sottoscrizioni.

Password/CA/nome server errato

Connect viene rifiutato; error/status forniscono informazioni diagnostiche. L’autenticazione non riuscita non si ripete senza limiti.

Invia 4096 byte binari

Tutti i byte, incluso NUL, rimangono invariati. Il topic non viene conteggiato nella dimensione del payload.

Ricevi un messaggio superiore a 4096 byte

MESSAGE_TOO_LARGE senza evento di messaggio parziale.

Arresto dell'applicazione

La connessione dell'utente si chiude; la connessione al sistema rimane attiva.

mqtt, mqtts, ws, wss

Testare ciascun URL rispetto al broker listener appropriato; ws/wss richiedono il percorso corretto.

16. Client HTTP / REST

La funzione globale fetch() collega le applicazioni ad API REST esterne tramite HTTP o HTTPS. Supporto: app.capabilities().features.http. Tutte le funzioni, proprietà e opzioni di questo capitolo sono disponibili da Neutron AppEngine 1.0.0. È un sottoinsieme documentato di fetch, non un ambiente browser completo.

Il dispositivo agisce come client HTTP. Questa API non aggiunge percorsi REST personalizzati al server HTTP interno di Neutron. Le richieste non forniscono ritentativi automatici, coda persistente, trasmissione automatica degli eventi o archiviazione delle risposte. L’applicazione definisce tempi delle chiamate, formati dei dati e gestione degli errori.

fetch(url, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
const response = await fetch(url, options);
Scopo. Invia una richiesta a un server HTTP/HTTPS esterno e ricevi una risposta completa e limitata.
Descrizione. La Promise viene soddisfatta dopo la ricezione dell’intero corpo, non solo delle intestazioni iniziali. HTTP 400, 401, 404 e 500 sono risposte normali e non causano un rifiuto. Gli errori di connessione, TLS, timeout e dimensione causano un rifiuto. L’elaborazione di rete avviene fuori dalla callback JavaScript senza bloccarla durante l’attesa.

Parametri

Tabella 78

Parametro

Tipo / requisito

Descrizione

url

string / obbligatorio

URL assoluto http:// o https://, al massimo 512 byte ASCII. Codificare Unicode e spazi nei percorsi/valori delle query; utilizzare encodeURIComponent per i singoli valori. Un frammento # viene rimosso. Le credenziali negli URL sono vietate.

options

object / facoltativo

method, headers, body, timeoutMs, tls e redirect. Le opzioni sconosciute vengono rifiutate. I dettagli seguono di seguito.

Risultato

Promise<Response>, descritto di seguito. body e opzioni codificate hanno limiti separati; i payload binari non sono codificati JSON o Base64.

Errori e considerazioni particolari

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. Dopo l'interruzione/timeout il server potrebbe già aver elaborato la richiesta; riprovare POST può duplicare il suo effetto commerciale.

Esempio

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

Opzione dalla versione Neutron AppEngine 1.0.0

Tipo/predefinito

Significato

method

string / GET

GET, POST, PUT, PATCH, DELETE o HEAD. Convertito in maiuscolo. Altri metodi non sono supportati in questa versione.

headers

object / nessuno

Nomi di intestazioni personalizzati e valori stringa. I nomi non distinguono maiuscole e minuscole; i nomi duplicati che differiscono solo per maiuscole/minuscole vengono rifiutati. Solo valori ASCII, senza CR/LF o caratteri di controllo diversi dalla tabulazione.

body

string | Uint8Array | null / nessuno

Al massimo 4096 byte dopo la codifica UTF-8. null significa nessun corpo. GET e HEAD non possono avere un corpo. Le stringhe senza Content-Type esplicito ricevono text/plain; charset=UTF-8; per JSON utilizzare JSON.stringify e application/json. Uint8Array non riceve alcun Content-Type automatico.

timeoutMs

integer / 10000

1..60000 ms; un'estensione Neutron AppEngine documentata, non un'opzione fetch del browser standard. Inizia al momento della chiamata e include l'attesa in coda e il trasferimento del corpo. La consegna degli errori non è una garanzia in tempo reale; la risoluzione dei nomi sottostante o le chiamate di connessione potrebbero terminare in un secondo momento.

tls

object / nessuno

Solo HTTPS. caProfile e opzionalmente la coppia clientCertificateProfile/clientKeyProfile. Vedi TLS.

redirect

string / manual

È supportato solo manual. Restituisce risposte 3xx affinché l’applicazione possa esaminare Location. Non segue automaticamente i reindirizzamenti.

Al massimo 32 intestazioni fornite e 2048 byte complessivi (nomi, valori e separatori); nomi fino a 64 caratteri, valori fino a 1024. Il client gestisce le intestazioni automatiche del protocollo. Non è possibile impostare Host, Content-Length, Connection, Transfer-Encoding, Accept-Encoding, Expect, Trailer, Upgrade, Proxy-Connection, TE e Keep-Alive. Le opzioni codificate della richiesta hanno un ulteriore limite complessivo di 4096 byte UTF-8.

Risposta: stato e metadati

Disponibile dalla versione: Neutron AppEngine 1.0.0
const response = await fetch("https://api.example.com/articles/ART-001");
Scopo. Controlla il risultato di HTTP prima di convertirne il corpo.
Descrizione. Un oggetto con proprietà di sola lettura e metodi per consumare il corpo una sola volta. Non conferma il significato applicativo dello stato né la validità del JSON ricevuto.

Parametri

Nessun parametro.

Risultato

{status, statusText, ok, url, redirected, headers, bodyUsed, text(), json(), arrayBuffer()}. status è il codice HTTP; ok significa 200..299. url è l’URL richiesto senza frammento; redirected è false; statusText è una stringa vuota in questa versione.

Errori e considerazioni particolari

Gestire il rifiuto di fetch separatamente da response.ok. Prevedere un corpo vuoto per 204 o HEAD; response.json() su un corpo vuoto genera SyntaxError. Non sono disponibili response.body in streaming, clone(), Blob, FormData, Request o costruttore globale Response.

Esempio

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

response.text()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const text = await response.text();
Scopo. Converte il corpo ricevuto in testo UTF-8 una volta.
Descrizione. Rimuove un BOM UTF-8 iniziale. Non esegue ulteriori richieste di rete; fetch ha già ricevuto il corpo. bodyUsed diventa true alla prima chiamata di un metodo di consumo del corpo.

Parametri

Nessun parametro.

Risultato

Promise<string>. Utilizzare arrayBuffer() per dati binari arbitrari.

Errori e considerazioni particolari

Una lettura ripetuta genera TypeError con code=BODY_USED. Decodifica UTF-8; gli altri set di caratteri non sono supportati automaticamente.

Esempio

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

response.json()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const value = await response.json();
Scopo. Decodificare il corpo UTF-8 ed eseguire JSON.parse una sola volta.
Descrizione. Restituisce un oggetto, un array o un altro valore JSON valido. Content-Type non cambia le regole di JSON.parse. Verificare prima lo stato se la propria API restituisce formati diversi per il corpo degli errori.

Parametri

Nessun parametro.

Risultato

Promise<JSON value>. bodyUsed diventa true anche se l'analisi di JSON fallisce.

Errori e considerazioni speciali

SyntaxError per non valido/vuoto JSON; TypeError/BODY_USED per lettura ripetuta. Memorizza il risultato in una variabile per riutilizzarlo.

Esempio

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

response.arrayBuffer()

Disponibile dalla versione: Neutron AppEngine 1.0.0
const buffer = await response.arrayBuffer();
Scopo. Restituire i byte binari ricevuti una sola volta, senza conversione in testo.
Descrizione. Utilizzare Uint8Array per accedere ai singoli byte, incluso NUL. Memorizzarli o inoltrarli a un altro modulo supportato.

Parametri

Nessun parametro.

Risultato

Promise<ArrayBuffer>, al massimo 4096 byte.

Errori e considerazioni particolari

TypeError/BODY_USED in caso di lettura ripetuta. Nessuna decompressione automatica gzip o di altri contenuti.

Esempio

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

response.headers

Disponibile dalla versione: Neutron AppEngine 1.0.0
const contentType = response.headers.get("Content-Type");
Scopo. Legge le intestazioni delle risposte senza distinzione tra maiuscole e minuscole.
Descrizione. Oggetto di sola lettura che supporta get, has, entries, keys, values, forEach e iterazione. I nomi di intestazione ripetuti sono uniti da virgole; non è un gestore automatico di cookie.

Parametri

Tabella 80

Parametro

Tipo / requisito

Descrizione

name per get/has

string / obbligatorio

Nome dell'intestazione HTTP valido.

callback per forEach

function / obbligatorio

Riceve value, name e headers. Un secondo argomento facoltativo imposta thisArg.

Risultato

get restituisce string o null; has restituisce boolean; entries/keys/values restituiscono iteratori. forEach non restituisce alcun risultato. L’iterazione utilizza nomi di intestazione minuscoli.

Errori e considerazioni particolari

INVALID_ARGUMENT per nomi di intestazione o callback non validi. Nessun costruttore globale Headers o metodi set/append/delete della risposta. Se il server supera 32 intestazioni, 2048 byte complessivi o le lunghezze di nome/valore supportate, fetch viene rifiutato anziché troncare silenziosamente.

Esempio

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

Autenticazione

Fornire token Bearer, chiavi API o valori Basic precodificati nelle intestazioni. Non inserire credenziali negli URL. Non sono disponibili accesso automatico, aggiornamento dei token, autenticazione HTTP Digest o sessione condivisa con le connessioni di sistema. I cookie non vengono salvati o inviati automaticamente. Questo client del dispositivo non è soggetto alle restrizioni CORS del browser.

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 e profili di certificato

HTTPS verifica sempre il nome del server e l’attendibilità del certificato. Senza caProfile utilizza l’attendibilità incorporata delle CA pubbliche. Utilizzare un profilo personalizzato per le CA private. L’orologio del dispositivo deve essere corretto per verificare la validità dei certificati. Non è disponibile un’opzione non sicura o un modo per aggirare la verifica del nome host.

Tabella 81

opzione tls

Profilo memorizzato

Scopo

caProfile: "company"

JHCA_company

PEM di una CA attendibile o catena di CA.

clientCertificateProfile: "scale01"

JHCC_scale01

Certificato cliente per mutuo TLS.

clientKeyProfile: "scale01"

JHCK_scale01

Chiave privata; richiesta insieme al certificato client.

Nomi dei profili: 1..48 caratteri A–Z/a–z, 0–9, _ o -. Ogni PEM è al massimo 16384 byte. Gli integratori autorizzati predispongono i profili tramite il percorso SMD esistente dei certificati, ad esempio JHCA_company=&lt; PEM&gt;. Non è un percorso di file arbitrario. I profili sono separati dai certificati MQTT di sistema e del server HTTP interno e vengono caricati per ogni richiesta. Le chiavi private cifrate con password non sono supportate.

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

Limiti ed esecuzione

Tabella 82

Proprietà dalla versione Neutron AppEngine 1.0.0

Gestione

Esecuzione

Una richiesta attiva e fino a quattro in coda. Si applica anche il limite condiviso dell’ambiente di esecuzione di otto operazioni asincrone in sospeso.

Dimensioni

Corpo della richiesta di 4096 byte e limite separato di 4096 byte per il corpo della risposta. Le risposte troppo grandi generano RESPONSE_TOO_LARGE; i corpi parziali non vengono mai restituiti come risultato riuscito.

Timeout

Predefinito 10000 ms, massimo 60000 ms, inclusa l'attesa in coda. I dati in arrivo lenti non ripristinano la scadenza. Il tempo effettivo di consegna dell'errore non è garantito in tempo reale.

Connessioni

Le connessioni vengono rilasciate dopo ogni richiesta. Nessuna sessione HTTP persistente o nuovo tentativo automatico. HTTPS stabilisce quindi una nuova connessione sicura ad ogni chiamata.

Reindirizzamenti

Sempre manual. 3xx resta una risposta; è possibile leggere Location. Le intestazioni di autenticazione non vengono inoltrate automaticamente a un altro server.

Codifica del corpo

Richiede identity. gzip/br e le altre codifiche non sono supportati; una risposta codificata non vuota causa UNSUPPORTED_ENCODING.

Arresto dell'applicazione

Le richieste in coda di un'esecuzione precedente vengono scartate; il trasferimento attivo viene interrotto quando viene rilevato un arresto o termina la chiamata di connessione sottostante. Ciò non annulla gli effetti del server già eseguiti.

Sottoinsieme dell’API

Non sono disponibili AbortController/signal, corpo in streaming, clone, Blob, FormData, costruttori URL/Request/Response/Headers o ambiente CORS/cookie automatico.

Proteggere le chiamate periodiche dalle sovrapposizioni. Utilizzare ID di richiesta e un protocollo concordato con il server per ritentativi affidabili delle operazioni applicative. Un timeout o una risposta persa non provano che il server non abbia elaborato POST/PUT/PATCH/DELETE.

Esempio completo: invia peso

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

Test di integrazione

Per i test locali, il pacchetto sorgente include tools/rest-test-server.py e tools/examples/rest-self-test.js per il dispositivo. Il server ascolta localmente per impostazione predefinita; utilizzare esplicitamente --host 0.0.0.0 per l'accesso Neutron e impostare IP del computer nell'applicazione di test. Opzionale --cert/--key abilita HTTPS;--ca abilita la convalida del certificato client. Il provisioning di certificati/profili rimane una procedura di gestione separata.

Tabella 83

Test

Risultato previsto

GET/POST/PUT/PATCH/DELETE/HEAD

Richiesta e stato corretti; HEAD non ha corpo.

404 o 500

La Promise viene soddisfatta; response.ok è false.

302

Stato e Location senza una nuova richiesta automatica.

JSON / UTF-8 / chunked

Corpo completo correttamente decodificato; i blocchi non sono eventi JavaScript separati.

Corpo binario con NUL e 0xff

Esattamente 4096 byte in ciascuna direzione.

Leggi di nuovo il corpo

TypeError con code=BODY_USED.

Risposta lenta o flusso di intestazione lento

TIMEOUT; la pesatura e l’ambiente di esecuzione continuano.

Risposta/intestazioni sovradimensionate

Rifiuto esplicito senza troncamento silenzioso.

HTTPS con CA /nome/certificato cliente errato

TLS_ERROR; la verifica rimane abilitata.

Stop durante il trasferimento

Risorse rilasciate; nessuna risposta obsoleta fornita in una nuova esecuzione dell'applicazione.

17. Client WebSocket

Disponibile dal: Neutron AppEngine 1.0.0 / API 1.
WebSocket fornisce una connessione bidirezionale persistente a un server esterno. Le applicazioni inviano messaggi di testo o binari e ricevono eventi. Ogni messaggio mantiene il suo confine; i delimitatori di linea non sono necessari. Utilizza fetch() per REST e mqtt per un broker MQTT.
Ogni applicazione ha una connessione indipendente, separata dalle impostazioni WebSocket del modulo, MQTT e Scale Monitor. Supporta nomi ws://, wss://, DNS e IPv4. Controlla app.capabilities().features.websocket; i limiti sono in app.capabilities().websocket.

new WebSocket(url, protocols?, options?)

Disponibile dalla versione: Neutron AppEngine 1.0.0
Crea un client e avvia la connessione asincrona. Restituisce un oggetto WebSocket, non una Promise. Il successo emette open; l’errore emette error e close. Gli argomenti non validi generano un’eccezione sincrona.
  • url: indirizzo assoluto, al massimo 512 byte, come wss://system.example.com/scales?device=01. Porte predefinite: 80 per ws, 443 per wss. Codificare percorsi e parametri; URL credenziali, frammenti e IPv6 non sono supportati.
  • protocols: omesso oppure array vuoto []. La negoziazione dei sottoprotocolli non è disponibile in questa versione; altri valori generano UNSUPPORTED_PROTOCOL.
  • options: oggetto opzionale contenente timeoutMs, headers e tls. Può anche essere fornito direttamente come secondo argomento.
  • timeoutMs: limite di connessione intero 1000–15000 ms, predefinito 10000 ms. DNS/i dettagli della rete possono influire sull'orario di restituzione effettivo. Non limita l'intera durata della connessione.
  • headers: intestazioni HTTP con valori stringa, ad esempio Authorization o X-API-Key. Al massimo 32 intestazioni e 512 byte complessivi. Le intestazioni Connection e Sec-WebSocket-* sono gestite dal client e non possono essere impostate. L’intera richiesta di upgrade, inclusi percorso, nome host e intestazioni automatiche, deve essere inferiore a 1024 byte; una combinazione troppo grande genera HEADERS_TOO_LARGE.
  • tls: solo wss. caProfile, clientCertificateProfile e clientKeyProfile utilizzano i profili REST. Fornire insieme il certificato client e la chiave. Nomi dei profili: 1–48 caratteri A–Z, a–z, 0–9, _ o -. Senza caProfile, utilizza l'attendibilità predefinita. Il nome del server e la verifica del certificato sono sempre abilitati.
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);

I controlli del certificato richiedono l'ora corretta del dispositivo. Invia credenziali tramite wss. I reindirizzamenti non vengono seguiti automaticamente. Se lo slot di connessione è occupato, il nuovo oggetto riceve BUSY e si chiude; la connessione esistente rimane attiva.

Autenticazione Basic con nome utente e password

Disponibile dalla versione: Neutron AppEngine 1.0.0
Inserisci nome utente/password come stringhe e utilizza l'helper di seguito per creare Authorization. Basic non esegue l'hashing delle credenziali: codifica Base64 username:password. La codifica è reversibile; utilizzare wss:// per le credenziali.
basicAuth(username, password) è definito in questo esempio, non integrato in Neutron AppEngine. Restituisce il valore completo dell'intestazione Basic <Base64>. Supporta UTF-8 se il server lo prevede e non ha bisogno né di btoa né di TextEncoder. Entrambi gli argomenti devono essere stringhe altrimenti viene generato TypeError. I nomi utente non possono contenere due punti; le password possono. L'indirizzo e le credenziali di esempio sono fittizi.
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);
Sostituire /scale/auth con l’endpoint effettivo del server. L’helper non richiede modifiche quando cambiano le credenziali. Non registrare mai Authorization o password. HTTP 401/403 durante l’autenticazione emette error con AUTH_FAILED, quindi close. basicAuth funziona anche nelle intestazioni Authorization di fetch tramite HTTPS.

socket.send(data)

Disponibile dalla versione: Neutron AppEngine 1.0.0

Nello stato OPEN, accoda un messaggio. Accetta string, ArrayBuffer o una vista di buffer come Uint8Array o DataView. Le stringhe sono inviate come testo UTF-8; gli altri valori come messaggi binari. I dati binari vengono copiati al momento della chiamata, consentendo successive modifiche alla sorgente. Sono consentiti messaggi vuoti e i byte binari 0 e 255.

Restituisce undefined. Non utilizzare await come conferma di consegna: l’invio non conferma l’elaborazione da parte del server. Aggiungere ID di richiesta e risposte al protocollo. bufferedAmount conta i byte locali in coda, non i messaggi non confermati dal server.

Al massimo 4096 byte per messaggio e 16384 byte nella coda locale; si applica anche il limite condiviso delle operazioni in sospeso. I messaggi troppo grandi generano MESSAGE_TOO_LARGE; una coda piena genera BUSY. CONNECTING genera INVALID_STATE; CLOSING/CLOSED ignorano send. Gli errori di trasferimento successivi arrivano tramite error e possono chiudere la connessione.

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

Eventi e listener

Disponibile dalla versione: Neutron AppEngine 1.0.0
Usa onopen, onmessage, onerror, onclose o addEventListener(type, callback, { once: true }). Rimuovere con removeEventListener(type, callback). Sono supportati solo questi quattro tipi di eventi e callback di funzioni; al massimo 32 ascoltatori registrati per oggetto. Le coppie tipo/funzione duplicate non vengono aggiunte. Nessun evento DOM, acquisizione o AbortSignal.
  • open: connessione e aggiornamento del protocollo riusciti; readyState è OPEN.
  • message: event.data è una stringa per testo o ArrayBuffer per dati binari. I frammenti si assemblano in un unico messaggio, inclusi i caratteri UTF-8 suddivisi in frammenti. Ping/pong non viene recapitato come messaggio.
  • error: event.code, event.message e un Error in event.error. Gli errori delle callback seguono le regole dell’ambiente di esecuzione; intercettarli nella callback per proseguire.
  • close: event.code, event.reason, event.wasClean. 1006 indica una chiusura interrotta; 1005 significa che il frame ricevuto non aveva un codice. L’oggetto rimane CLOSED. Tutti gli eventi contengono anche type, target e currentTarget.
ws.onmessage = event => {
  try {
    if (typeof event.data === "string") {
      if (event.data.trim() === "WEIGHT?") ws.send(JSON.stringify(scale.read()));
    } else {
      const bytes = new Uint8Array(event.data);
      console.info("Binarni bajti:", bytes.length);
    }
  } catch (error) { console.warn(error.code || error.name, error.message); }
};
ws.addEventListener("open", () => console.info("Povezava odprta"), { once: true });
ws.onclose = event => console.info(event.code, event.reason, event.wasClean);

socket.close(code?, reason?) e stato della connessione

Disponibile dalla versione: Neutron AppEngine 1.0.0
close() avvia la chiusura asincrona e restituisce undefined. Valori predefiniti: code 1000, reason vuoto. Codici utente: 1000 o 3000–4999; reason al massimo 123 byte UTF-8. Gli argomenti non validi generano INVALID_ARGUMENT. Ripetere close in CLOSING/CLOSED non ha effetto. La chiusura durante la connessione sopprime open; il client completa il tentativo corrente e poi chiude. L’assenza di una risposta di chiusura entro circa 3 secondi forza una chiusura non regolare.
readyState: WebSocket.CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3. Le costanti esistono anche sull’oggetto. url contiene l’indirizzo; protocol e extensions sono vuoti. binaryType è sempre arraybuffer; blob non è supportato.
if (ws.readyState === WebSocket.OPEN) ws.send("PING");
ws.close(1000, "Application finished");

Limiti, ripristino ed errori

Questa versione supporta una connessione client per applicazione, ws/wss, trasferimento binario/testo e verifica dei certificati. Non sono disponibili server WebSocket, sottoprotocolli, compressione, Blob o riconnessione automatica. Creare un nuovo oggetto dopo close; utilizzare setTimeout con ritardo se necessario. Questo socket è separato da MQTT tramite ws/wss.

La ricezione attende i dati disponibili e non richiede polling con setInterval. Il client invia ping circa ogni 30 secondi e attende pong fino a 10 secondi. Le operazioni di rete dopo la connessione hanno attese limitate a circa 3 secondi. I messaggi in arrivo troppo grandi o UTF-8 non valido causano error e chiusura. app.stop(), l’eliminazione dell’applicazione o gli errori dell’ambiente di esecuzione chiudono la connessione e rilasciano le risorse; un’operazione di rete attiva può richiedere secondi per terminare. Gli eventi JavaScript non vengono più eseguiti dopo l’arresto.

Codici di errore: INVALID_ARGUMENT, INVALID_STATE, UNSUPPORTED_PROTOCOL, BUSY, QUOTA_EXCEEDED, MESSAGE_TOO_LARGE, HEADERS_TOO_LARGE, OUT_OF_MEMORY, AUTH_FAILED (HTTP 401/403 durante la connessione), HANDSHAKE_FAILED, NETWORK_ERROR, TLS_OR_NETWORK_ERROR, TIMEOUT, PROTOCOL_ERROR, INVALID_UTF8. Per TLS_OR_NETWORK_ERROR verificare connettività, ora, nome del server e certificato. Gli errori della coda eventi dell’ambiente di esecuzione seguono le sue regole generali.

Test di integrazione

Su un computer, eseguire python tools/websocket-test-server.py --host 0.0.0.0. Impostare l’indirizzo del computer in tools/examples/websocket-self-test.js e caricarlo su Neutron. I test coprono UTF-8, frammenti con un ping intermedio, messaggi vuoti, trasferimenti binari fino a 4096 byte e chiusura ordinata. Esempio di invio del peso: tools/examples/websocket-scale.js. Il server supporta --cert/--key per wss e --token per verificare Authorization. Utilizzare il profilo CA appropriato per certificati personalizzati.

Provare anche BIG (risposta troppo grande), certificato/token errato, perdita della rete e Stop/Delete durante il trasferimento. I test dell’API JavaScript sul computer non sostituiscono i test di rete e TLS sul dispositivo.

18. Errori, try/catch e prosecuzione

Un try { setInterval(...) } catch (...) { ... } esterno intercetta gli errori di registrazione, non gli errori successivi della callback. Analogamente, try { asyncOperation() } senza await non intercetta il rifiuto della Promise. Intercettare gli errori nella callback o sulla Promise restituita.
Distinguere tra eccezioni JavaScript sincrone, rifiuti asincroni delle Promise ed errori dell’intero ambiente di esecuzione. TypeError, ReferenceError, SyntaxError e RangeError standard hanno name/message ma non necessariamente code. Gli errori di operazione e convalida degli argomenti includono generalmente error.code ed error.message.
Tabella 84

Codice

Significato generale

INVALID_ARGUMENT

Tipo/valore di argomento non valido; i dettagli dipendono dalla funzione chiamata.

QUOTA_EXCEEDED

Limite del modulo superato; rimuovere le registrazioni inutilizzate.

BUSY

Risorsa occupata, troppe operazioni in sospeso o coda piena. Attendere e limitare concorrenza/ritentativi.

OUT_OF_MEMORY

Memoria insufficiente per l’operazione. Gli errori di memoria JavaScript possono invece utilizzare un’eccezione standard senza questo codice.

TIMEOUT

Operazione asincrona interrotta o scaduta. Verificare l’effetto dell’operazione precedente prima di riprovare.

Per proseguire, intercettare gli errori previsti nella funzione in cui si verificano. Scegliere l’arresto con app.stop() oppure lasciare l’errore non gestito. Non esiste un’API globale configurabile per la gestione degli errori. Registrare soltanto l’errore in console non arresta l’applicazione.

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

Eccezioni/rifiuti non gestiti, tempo attivo esaurito, annidamento eccessivo delle chiamate o overflow della coda eventi arrestano l’applicazione e impostano lastError. Gli errori interni di coda/budget temporale non forniscono necessariamente un oggetto con code; lo stato può contenere EVENT_OVERFLOW o Active JS execution budget exceeded. I guasti del sistema del dispositivo e le interruzioni di alimentazione non sono eccezioni JavaScript e non possono essere intercettati con try/catch.

Gli errori e le risposte specifici dei moduli sono documentati con le relative funzioni. Le regole generali di try/catch si applicano indipendentemente dall’origine dell’operazione.

19. Limiti e pianificazione delle risorse

Tabella 85

Risorsa

Limite / comportamento

Nome / versione

Nome: 1–64 byte UTF-8; versione: 1–32 byte; nessun carattere di controllo. La versione è testo, non necessariamente una versione semantica.

Codice sorgente

Un file UTF-8, 1–131 072 byte.

Memoria dell’applicazione

1 048 576 byte per dati e oggetti di Neutron AppEngine; la dimensione del sorgente viene controllata separatamente.

Annidamento delle funzioni

Evitare la ricorsione profonda e le lunghe catene di chiamate. Un annidamento eccessivo può causare un errore dell’applicazione.

Tempo attivo

Circa 1 s per fase di elaborazione dell’ambiente di esecuzione; budget di 5 s durante la convalida del codice. Non è un tempo di risposta garantito della bilancia.

Timer

16 timer attivi.

Operazioni concorrenti

Al massimo 8 operazioni in sospeso. Elaborare rapidamente gli eventi; un accumulo eccessivo può arrestare l’applicazione con EVENT_OVERFLOW.

Console

10 chiamate/s complessive, circa 512 byte di contenuto per chiamata.

Upload

768 byte grezzi/blocco; interfaccia BLE esistente: 192 byte grezzi/blocco; la sessione scade dopo 5 minuti di inattività.

Senza eventi o timer, Neutron AppEngine attende mentre le altre funzioni del dispositivo continuano normalmente. L’attesa non consuma il budget JavaScript attivo. Valutare il carico CPU nella configurazione effettiva; qui non è garantita alcuna percentuale CPU fissa.

Limitare la crescita di Map/Array, i dati per comando e i ritentativi. I timer per comunicazioni lente richiedono generalmente un indicatore di invio. Non accumulare nuove richieste quando le operazioni non possono terminare rapidamente. L’archiviazione conserva le applicazioni installate dopo un riavvio; le variabili JavaScript scompaiono con Stop/reset. Utilizzare l’API di archiviazione documentata per i dati persistenti dell’applicazione.

20. Installazione, attributi e avvio automatico

Tabella 86

Attributo

Descrizione

name

Nome visualizzato dell’applicazione e parte del prefisso dei log JavaScript.

version

Versione dell’applicazione utente; distinta da interpreterVersion, apiVersion e versione del firmware del dispositivo.

autorun

Booleano: avvio automatico dopo l’accensione, salvo blocco da parte della protezione di ripristino.

size / sha256

Lunghezza e SHA-256 dei byte UTF-8 effettivi del file sorgente. SHA-256 non è una firma dell’autore né sostituisce l’autorizzazione.

Nel server web interno o nella pagina BLE, selezionare un file, impostare gli attributi e Upload. Save attributes aggiorna l’applicazione esistente; Run avvia una nuova esecuzione; Stop richiede l’arresto; Refresh mostra lo stato; Abort upload annulla il trasferimento; Delete rimuove l’applicazione installata. busy=true durante l’esecuzione: arrestare e attendere prima di modificare gli attributi o installare. Delete durante l’esecuzione avvia l’arresto; la risposta iniziale è state=stopping e l’eliminazione termina in seguito. Verificare che lo stato sia empty. Lo stato include anche runtimeActive, runtimeTaskAllocated e resourcesReleased; dopo l’arresto sono false, false e true. Il rilascio delle richieste di comunicazione attive è asincrono; nel frattempo un nuovo Run può restituire BUSY. L’interprete non viene eseguito senza un’applicazione in esecuzione.

Un Upload riuscito conferma codice memorizzato e convalidato, non un programma eseguito con successo. Eseguire poi Run e verificare log/stato. Auto run avviene dopo l’inizializzazione del firmware e almeno 10 s dall’avvio, non a ogni riconnessione MQTT. Abilitare autorun negli attributi non attiva immediatamente un Run manuale.

L’output iniziale della console può essere invisibile se il trasporto di debug è disconnesso; verificare stato APP/lastError. Un programma può rimanere in esecuzione dopo un solo console.log perché l’ambiente di esecuzione attende eventi futuri.

21. Protocollo APP per client e Scale Monitor

Il caricamento non richiede un nuovo canale di comunicazione. Utilizzare il percorso del comando autenticato esistente. Questo è un protocollo per client di gestione esterni, non funzioni che l'applicazione JavaScript può invocare da sola.

Tabella 87

Trasporto

Richiesta

Risposta

HTTP/HTTPS interno

POST /api/cmd autenticato, Content-Type: text/plain; corpo APP <JSON>. Utilizzare la sessione di accesso esistente del dispositivo.

oggetto JSON; controlla ok, non solo lo stato HTTP.

BLE

Caratteristica di comando esistente e comando APP <JSON> incapsulato con le credenziali. Utilizzare la stessa coda di invio/frammentazione degli altri comandi.
Canale di notifiche esistente, APP <JSON> con possibile output di debug interlacciato.

MQTT

Topic CMP/RX esistente del dispositivo. DATA contiene la codifica Base64 dell’intera richiesta JSON UTF-8. Pubblicare con retain=false.

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

Mantenere i controlli MID/credenziali esistenti e l’autenticazione MQTT. I comandi APP conservati tramite retain vengono rifiutati. Il caricamento MQTT è separato dall’utilizzo di MQTT dentro JavaScript. Il JSON decodificato della richiesta APP è al massimo 2048 byte.

21.1 Trasferimento file

Inviare stop e verificare busy=false con status prima di iniziare. Calcolare size e SHA-256 sui byte originali del file. Quindi eseguire begin → sequenza di chunk → commit → status. Attendere la risposta di ogni chunk; non inviare tutti i chunk contemporaneamente.

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

È uno schema di messaggio, non un trasferimento pronto per l’invio: sostituire size, hash, uploadId e data con valori effettivi. begin restituisce uploadId, offset=0 e chunkSize=768. Offset è una posizione in byte; suddividere i byte prima della codifica Base64. L’interfaccia BLE esistente utilizza 192 byte sorgente per richiesta APP e frammenta ulteriormente i messaggi incapsulati con credenziali in scritture GATT.

Tabella 88

Operazione

Parametri oltre a op/rid

Risultato/condizioni

begin

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

Crea una sessione; restituisce uploadId, offset e chunkSize. Richiede almeno size × 2 + 4096 byte liberi di archiviazione. Annullare prima qualsiasi altra sessione attiva.

chunk

uploadId, offset:integer, data:base64

1–768 byte decodificati. Restituisce l'offset totale confermato. Un pezzo precedente può essere ripetuto solo con byte identici interamente all'interno dell'intervallo confermato.

commit

uploadId

Consentito dopo l’arrivo di tutti i byte. Avvia la convalida SHA/sintassi e l’attivazione asincrone; ok=true non conferma il completamento dell’attivazione. Interrogare periodicamente status fino a busy=false.

abort

uploadId

Rimuove il file temporaneo e la sessione. Consentito quando non occupato. Non è possibile prendere il controllo di sessioni di altri trasporti utilizzando solo uploadId.

configure

name, version, autorun:boolean

Modifica tutti gli attributi dell'applicazione esistenti e avvia la convalida/attivazione asincrona. Richiede un'applicazione installata, nessun caricamento attivo e busy=false.

run

—

Avvia l’applicazione installata e restituisce state. Il caricamento deve essere completato/annullato e busy=false.

stop

—

Annulla l’avvio automatico in sospeso e richiede l’arresto. La conferma indica l’accettazione del comando; interrogare periodicamente status per verificarne il completamento.

status

—

Stato corrente, attributi installati, errore e ripristino. Consentito anche durante l'esecuzione.

delete

—

Elimina l'applicazione attiva, il relativo backup, i file intermedi e il record di ripristino. Prima fermati e interrompi qualsiasi caricamento.

Verificare il booleano ok in ogni risposta. Un errore restituisce ok=false e testo error, distinti da error.code delle Promise JavaScript. rid facoltativo è un ID testuale di correlazione fino a 64 byte. Ritentare un ID solo con JSON identico; contenuti diversi con lo stesso ID vengono rifiutati. La cache delle modifiche riuscite conserva solo le ultime sei richieste per processo, non garantisce in modo persistente un’esecuzione esattamente una volta. Per i chunk, utilizzare uploadId/offset e i byte confermati.

Una sessione appartiene al trasporto iniziale e a uploadId e può scadere dopo 5 minuti di inattività. Dopo una risposta persa, esaminare status/received; non indovinare gli offset. Un errore di hash/sintassi non è un’installazione riuscita. Dopo commit verificare name/version/sha256 e lastError.

21.2 Stato e completamento operazione

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

L’esempio è illustrativo; leggere i valori effettivi. State può essere empty, ready, validating, running, stopped, error o blocked. Busy è true anche durante la normale esecuzione prolungata. Per il completamento della convalida, attendere busy=false ed esaminare lastError e l’identità del codice installato. Per Run, verificare running e monitorare gli errori successivi. I dati di ripristino lastState e lastResetReason sono diagnostica del firmware, non stato del protocollo applicativo.

Tabella 89

Esempio errore APP

Significato / risposta del client

BUSY

Inviare stop e attendere il completamento; interrogare periodicamente status durante la convalida.

Invalid APP JSON

JSON non valido o la richiesta supera 2048 byte.

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

Verificare lunghezze UTF-8, booleano autorun, hash e size.

Invalid upload session

uploadId errato, trasporto o sessione scaduta.

Invalid offset / Overlapping chunk / Duplicate chunk differs

Allineare offset a received confermato; non modificare il file durante il trasferimento.

Upload incomplete

Commit inviato prima dell’arrivo di tutti i byte.

Insufficient filesystem space

Spazio insufficiente per un trasferimento e una sostituzione sicuri.

No application installed

Run/configure senza un’applicazione installata.

Application storage not ready / Task allocation failed…

Archiviazione o RAM non pronto; ispezionare lo stato/i registri e la diagnostica del dispositivo.

L’elenco degli errori testuali non è esaustivo. Conservare error/lastError completi nella diagnostica del client. Un timeout del client esterno non prova un rifiuto del dispositivo.

22. Avvio automatico e protezione dagli arresti anomali

Prima dell'avvio, Neutron AppEngine memorizza l'identità dell'applicazione e monitora il successo dell'avvio. Un riavvio imprevisto del dispositivo durante questo periodo registra un tentativo instabile all'avvio successivo. Dopo tre tentativi instabili consecutivi, l'esecuzione automatica viene bloccata prima di un quarto tentativo automatico. Il codice rimane memorizzato per ispezione o sostituzione.

Ripristini imprevisti dovuti a guasti del sistema o problemi di alimentazione possono aumentare il contatore dei tentativi instabili. L'accensione normale e i riavvii pianificati vengono trattati diversamente dagli arresti anomali dell'applicazione. Un tentativo instabile da solo non dimostra un difetto del codice utente; controllare anche la diagnostica del dispositivo.

Circa 60 s di funzionamento confermato azzerano la sequenza di errori, includendo la normale attesa degli eventi e non solo il tempo CPU. Uno Stop normale chiude il marcatore. Un blocco Auto run esistente rimane fino a un’installazione esplicita riuscita o a Save attributes/configure. Il Run manuale resta possibile ed è monitorato. Un errore di salvataggio del record di ripristino può impedire Run per protezione.

Un normale errore JavaScript non gestito arresta l’applicazione e imposta lastError; è diverso da un reset del modulo. Factory default elimina codice installato, relativo backup, file temporanei, stato di ripristino e archiviazione dell’applicazione, inclusi i database locali. try/catch JavaScript non può impedire un reset hardware.

23. Regole per ScaleGuru AI e integratori

Utilizzare questa sezione come contratto per la generazione dell'applicazione. ScaleGuru AI dovrebbe restituire un file UTF-8 .js completo ed elencare separatamente la configurazione di sistema richiesta e i passaggi del test. La documentazione non autorizza automaticamente AI a caricare o eseguire codice sul dispositivo di un utente.

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

23.1 Test prima del rilascio dell'applicazione

Tabella 90

Test

Risultato previsto

Dispositivo senza una misurazione valida

Nessuna eccezione incontrollata; l'applicazione segnala chiaramente la misura non disponibile.

Più comandi in una ricezione

Gestisci ogni comando; considerare l'ordinamento delle risposte per i comandi asincroni.

Bilancia occupata/operazione rifiutata

Il rifiuto previsto viene gestito senza tentativi infiniti.

Arresto senza timer attivi

L’ambiente di esecuzione inattivo si risveglia e termina normalmente.

Riavvia con l'esecuzione automatica

Si avvia la versione installata convalidata; vengono esaminati lastError e i dati di ripristino.

24. Revisioni e documentazione correlata

Tabella 91

Manuale

Data

Cambiamenti

1.0

15. 11. 2026

Prima versione dell’API: ambiente di esecuzione, bilancia, I/O, impostazioni del modulo, file, database locale, TCP, interfacce seriali, MQTT, REST/HTTP, protocollo APP e protezione all’avvio.

Documentazione correlata: CSCP — protocollo di comunicazione Neutron. CSCP descrive comandi e configurazione di sistema; questi non diventano automaticamente funzioni JavaScript. Questo riferimento segue scopo, sintassi, parametri, risultato, errori ed esempio.

Gli esempi sono inclusi come codice statico e rimangono leggibili senza JavaScript. La ricerca delle pagine, la copiatura e la stampa del codice sono strumenti di documentazione; non eseguono applicazioni né comunicano con un dispositivo. La documentazione non è incorporata nel firmware.

Domande frequenti

Posso utilizzare Node.js, npm o le API del browser?

No. Caricare un unico script JavaScript UTF-8 e utilizzare le API neutron-js-1 documentate. Node.js, npm, il DOM, import/export e await al livello principale non sono disponibili.

Come verifico le funzionalità disponibili?

Chiamare app.capabilities() sul dispositivo. Verificare apiVersion, interpreterVersion, features e i limiti specifici del modulo prima di utilizzare una funzione.

I dati dell’applicazione vengono conservati dopo Stop e il riavvio?

Le variabili JavaScript non vengono conservate. I file e i database locali di record in storage persistono dopo Stop, il riavvio e la normale sostituzione dell’applicazione. Factory default elimina questi dati.

Quando devo abilitare Auto run?

Prima caricare l’applicazione, eseguirla manualmente e verificare il comportamento richiesto, i limiti e i casi di errore. Abilitare Auto run solo dopo i test funzionali. La protezione all’avvio può bloccare avvii automatici instabili ripetuti.

Avete bisogno di aiuto?

Vi serve aiuto con il software, la connettività o l’utilizzo di una soluzione? Descrivete il problema, così potremo aiutarvi a individuare il passo successivo.

Prepara una richiesta →