TECHNIQUE DE PESAGE · DÉVELOPPEMENT INTERNE · ASSISTANCE
+386 2 320 33 46info@preciz.si

NEUTRON APPENGINE · MANUEL POUR DÉVELOPPEURS

Neutron AppEngine — développement d’applications JavaScript

Développement d’applications JavaScript pour CloudScaleLink Neutron et CloudScale Neutron NS : environnement d’exécution, pesage, E/S numériques, paramètres, stockage, modules de communication et gestion des applications. Manuel 1.0 · Neutron AppEngine 1.0.0 · API 1 · Date de publication : 16 novembre 2026.

1. Objectif et périmètre

Neutron AppEngine est disponible pour le module CloudScaleLink Neutron et les modules de pesage CloudScale Neutron NS équipés d’un firmware version 2.7 ou ultérieure.

Neutron AppEngine permet de développer des applications JavaScript personnalisées directement sur les modules de pesage CloudScaleLink Neutron et Neutron. Les applications peuvent lire les mesures, effectuer des opérations de pesage, utiliser des temporisateurs et se connecter à des systèmes externes via les modules de communication pris en charge (MQTT, TCP, WebSocket, REST, RS-232 et RS-485).
Ce manuel s’adresse aux développeurs, aux intégrateurs et aux systèmes d’IA qui préparent des applications destinées à Neutron.
Ce manuel décrit le profil neutron-js-1, apiVersion: 1, au 16 novembre 2026. La version du manuel est 1.0 et celle de l’interpréteur Neutron AppEngine est 1.0.0. Toutes les fonctions, tous les événements, toutes les propriétés et toutes les opérations implémentés et décrits ici sont disponibles depuis la version 1.0.0. La seule version du firmware ne confirme pas la prise en charge de chaque fonctionnalité : vérifiez app.capabilities() sur l’appareil et testez votre application.
Tableau 1

Domaine

État

Interface

Exécution JavaScript

Implémenté

Interpréteur Neutron AppEngine ; une seule application utilisateur stockée de façon persistante

Environnement d’exécution et diagnostics

Implémenté

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

Temporisateurs

Implémenté

setTimeout, setInterval, annulation par ID

Balance

Implémenté

Lecture du poids, tarage, mise à zéro, tare prédéfinie et envoi de commandes CSCP avec scale.cmd()

Client / serveur TCP

Implémenté

Réservation de l’interface TCP existante, gestion des événements et envoi de données

MQTT

Implémenté

Broker utilisateur indépendant ; mqtt, mqtts, ws et wss

RS-232 / RS-485

Implémenté

serial.rs232 et serial.rs485 ; réservation, configuration SMD, événements et envoi

Installation

Implémenté

BLE, HTTP/HTTPS interne et MQTT via le canal APP existant

Entrées/sorties numériques

Implémenté

io.input(1..6), io.output(1..6) ; configuration, événements, réservation des sorties et compteurs

Paramètres et application de comptage

Via les commandes CSCP prises en charge

scale.cmd() exécute les commandes prises en charge par l’appareil ; une API JavaScript counting.* distincte n’est pas encore disponible.

Paramètres du module

Implémenté

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

Fichiers et base de données locale

Implémenté

storage ; openRecords et recherche indexée par clé

REST/HTTP depuis JavaScript

Implémenté

fetch pour HTTP/HTTPS ; état, en-têtes, texte, JSON et réponses binaires

Le fichier est un script .js UTF-8 ordinaire. Sa taille se mesure en octets, et non en lignes ou en caractères, avec un maximum de 131 072 octets. Ce n’est pas un module ES : import/export, await au niveau supérieur, Node.js, npm et le DOM ne sont pas disponibles. Utilisez globalThis, les objets JavaScript standard, Promise, async/await, Map, JSON et Uint8Array. Les API de navigateur TextEncoder/TextDecoder ne font pas partie de ce profil.

2. Votre première application

Enregistrez le code suivant sous first-application.js, téléversez-le et sélectionnez Run. Il incrémente un compteur chaque seconde et l’écrit sur le canal de débogage configuré. Aucune configuration de la balance ni de la communication n’est requise.
let counter = 0;
setInterval(() => {
    counter += 1;
    console.log("Counter:", counter);
}, 1000);

Dans l’interface HTTP/HTTPS locale ou la page BLE, ouvrez JS application ou App, sélectionnez le fichier, saisissez son nom et sa version, puis sélectionnez Upload. Après validation, sélectionnez Run. Utilisez Stop pour arrêter l’application et Refresh pour vérifier son état et la dernière erreur. Activez Auto run uniquement après les tests.

Pour une initialisation asynchrone, définissez et appelez une fonction. start est un nom arbitraire défini par l’utilisateur, sans signification particulière pour l’environnement d’exécution.
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. Environnement d’exécution, événements et cycle de vie

Éviter les blocages : n’utilisez pas while (true), d’attente active, de récursion profonde ni de chaînes infinies de Promise. L’environnement d’exécution autorise environ 1 s de temps actif par étape de traitement ; l’attente suspendue d’un événement ne consomme pas ce budget. Le dépasser ou faire déborder une file peut arrêter l’application ; n’utilisez pas cela comme mécanisme normal de contrôle.
La préparation de l’environnement et la compilation de l’application ont des limites de temps distinctes, allant jusqu’à 5 secondes par phase. La limite de compilation est identique lors du téléversement et du démarrage. L’exécution initiale du code utilisateur dispose ensuite d’un nouveau délai d’une seconde ; la même limite s’applique au traitement des événements et des temporisateurs. L’attente de réponses réseau ou de temporisateurs ne consomme pas ce budget. TIMEOUT indique la phase et la limite, par exemple TIMEOUT during application startup (limit 1000 ms). L’interruption de l’exécution ne redémarre pas automatiquement le module.
Tableau 2

Étape

Comportement

Installation

Le code source et les attributs sont enregistrés dans le stockage de l’appareil. L’intégrité et la syntaxe sont vérifiées sans exécuter le code utilisateur.

Run

Chaque exécution crée un nouveau contexte JavaScript. Le script initial s’exécute une seule fois ; les variables d’une exécution précédente ne sont pas conservées.

Attente

Une fois le script initial terminé, l’environnement d’exécution reste actif et attend le prochain temporisateur ou événement. Lorsqu’il n’y a rien à traiter, Neutron AppEngine attend sans exécuter de code utilisateur.

Événement

Un événement d’un module pris en charge, l’expiration d’un temporisateur ou le résultat d’une opération déclenche le traitement correspondant dans Neutron AppEngine. Une Promise en attente est résolue ou rejetée.

Arrêt ou erreur

Les temporisateurs et le contexte sont supprimés. Stop n’annule pas les effets des opérations déjà effectuées.

Nouvelle exécution

Arrêtez d’abord l’exécution précédente et attendez busy: false. L’installation d’une nouvelle version exige également que l’application soit arrêtée.
Neutron AppEngine exécute les callbacks séquentiellement. Traitez les événements rapidement et évitez un nombre illimité d’opérations en attente. await cède l’exécution, permettant à d’autres callbacks de s’exécuter pendant l’attente. Un callback asynchrone n’est donc pas une transaction qui bloque les autres événements.

4. API de l’application

4.1 app.capabilities()

Disponible depuis : Neutron AppEngine 1.0.0
const capabilities = app.capabilities();
Objectif. Vérifier les fonctionnalités et les limites prises en charge avant d’utiliser une API.
Description. Renvoie de manière synchrone un nouvel objet indiquant la prise en charge, les versions et les limites. N’initialise pas les modules individuels et ne garantit pas qu’ils soient actuellement prêts.

Paramètres

Aucun paramètre.

Résultat

L’objet présenté ci-dessous. Les propriétés features indiquent la prise en charge des modules. Les paramètres et limites de chaque module sont expliqués dans son chapitre.

Erreurs et considérations particulières

Ne renvoie pas de Promise. Ne déduisez pas la prise en charge des fonctionnalités du seul nom de l’appareil ou de la version de l’application.

Exemple

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
  }
}
Lisez la version avec app.capabilities().interpreterVersion et le nom avec app.capabilities().interpreter. interpreterVersion identifie la version du produit Neutron AppEngine, apiVersion le contrat de l’API et runtime le profil. Ces valeurs sont distinctes de la version de l’application utilisateur et de celle du firmware de l’appareil. Versions actuelles : Neutron AppEngine 1.0.0, API 1 et manuel 1.0.
console.info(app.capabilities().interpreter, app.capabilities().interpreterVersion);
Au démarrage de l’appareil, Neutron AppEngine interpreter v1.0.0 est consigné au niveau INFO. Sa visibilité dépend des paramètres du canal et du niveau de débogage. Utilisez capabilities pour effectuer la vérification depuis une application utilisateur.

4.2 app.stop()

Disponible depuis : Neutron AppEngine 1.0.0
app.stop();
Objectif. Arrêter normalement l’application utilisateur.
Description. Demande l’arrêt de l’exécution et empêche les callbacks suivants. Ne réinitialise pas le module. Libère les ressources réservées par l’application ; le comportement propre à chaque ressource est décrit dans le chapitre du module concerné.

Paramètres

Aucun paramètre.

Résultat

undefined. Il s’agit d’une demande, pas d’une Promise confirmant l’arrêt. Utilisez l’état APP pour une confirmation externe.

Erreurs et considérations particulières

N’annule pas les opérations déjà effectuées. Utilisez return après l’appel si les instructions suivantes de la fonction actuelle ne doivent pas s’exécuter. Il n’existe pas de callback d’arrêt utilisateur.

Exemple

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

5. Diagnostics et console

La console envoie la sortie au système de débogage Neutron, et non à la console du navigateur. Les paramètres de débogage existants DI et DL sélectionnent la sortie et le niveau. Les messages reçoivent le préfixe [JS:application name]. La configuration et la connexion actuelles du transport déterminent où les messages sont visibles.

5.1 console.log(...)

Disponible depuis : Neutron AppEngine 1.0.0
console.log(...values);
Objectif. Consigner des mesures ou un état.
Description. Joint les arguments en les séparant par des espaces. Tente JSON.stringify pour les objets et une conversion en texte pour les autres valeurs. Remplace les caractères de contrôle par des espaces. Toutes les méthodes console partagent la même limite de journalisation.

Paramètres

Tableau 3

Paramètre

Type / exigence

Description

values

toutes valeurs JavaScript / facultatif

Zéro ou plusieurs arguments. Évitez les objets volumineux et les structures circulaires.

Résultat

undefined ; journal INFO, visible avec DL ≥ 3 et un DI approprié.

Erreurs et considérations particulières

La journalisation n’arrête pas à elle seule l’application, y compris console.error(). La limite partagée est de 10 appels/s et d’environ 512 octets de contenu par appel, hors préfixe. La sortie excédentaire est rejetée ou tronquée ; un avertissement supplémentaire de limitation de débit peut apparaître. Les erreurs de conversion ou de mémoire peuvent lever une exception JavaScript.

Exemple

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

5.2 console.info(...)

Disponible depuis : Neutron AppEngine 1.0.0
console.info(...values);
Objectif. Signaler des informations de démarrage ou d’état.
Description. Joint les arguments en les séparant par des espaces. Tente JSON.stringify pour les objets et une conversion en texte pour les autres valeurs. Remplace les caractères de contrôle par des espaces. Toutes les méthodes console partagent la même limite de journalisation.

Paramètres

Tableau 4

Paramètre

Type / exigence

Description

values

toutes valeurs JavaScript / facultatif

Zéro ou plusieurs arguments. Évitez les objets volumineux et les structures circulaires.

Résultat

undefined ; journal INFO, visible avec DL ≥ 3 et un DI approprié.

Erreurs et considérations particulières

La journalisation n’arrête pas à elle seule l’application, y compris console.error(). La limite partagée est de 10 appels/s et d’environ 512 octets de contenu par appel, hors préfixe. La sortie excédentaire est rejetée ou tronquée ; un avertissement supplémentaire de limitation de débit peut apparaître. Les erreurs de conversion ou de mémoire peuvent lever une exception JavaScript.

Exemple

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

5.3 console.warn(...)

Disponible depuis : Neutron AppEngine 1.0.0
console.warn(...values);
Objectif. Consigner un avertissement ou un problème géré.
Description. Joint les arguments en les séparant par des espaces. Tente JSON.stringify pour les objets et une conversion en texte pour les autres valeurs. Remplace les caractères de contrôle par des espaces. Toutes les méthodes console partagent la même limite de journalisation.

Paramètres

Tableau 5

Paramètre

Type / exigence

Description

values

toutes valeurs JavaScript / facultatif

Zéro ou plusieurs arguments. Évitez les objets volumineux et les structures circulaires.

Résultat

undefined ; journal WARN, visible avec DL ≥ 2 et un DI approprié.

Erreurs et considérations particulières

La journalisation n’arrête pas à elle seule l’application, y compris console.error(). La limite partagée est de 10 appels/s et d’environ 512 octets de contenu par appel, hors préfixe. La sortie excédentaire est rejetée ou tronquée ; un avertissement supplémentaire de limitation de débit peut apparaître. Les erreurs de conversion ou de mémoire peuvent lever une exception JavaScript.

Exemple

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

5.4 console.error(...)

Disponible depuis : Neutron AppEngine 1.0.0
console.error(...values);
Objectif. Décrire une erreur.
Description. Joint les arguments en les séparant par des espaces. Tente JSON.stringify pour les objets et une conversion en texte pour les autres valeurs. Remplace les caractères de contrôle par des espaces. Toutes les méthodes console partagent la même limite de journalisation.

Paramètres

Tableau 6

Paramètre

Type / exigence

Description

values

toutes valeurs JavaScript / facultatif

Zéro ou plusieurs arguments. Évitez les objets volumineux et les structures circulaires.

Résultat

undefined ; journal ERROR, visible avec DL ≥ 1 et un DI approprié.

Erreurs et considérations particulières

La journalisation n’arrête pas à elle seule l’application, y compris console.error(). La limite partagée est de 10 appels/s et d’environ 512 octets de contenu par appel, hors préfixe. La sortie excédentaire est rejetée ou tronquée ; un avertissement supplémentaire de limitation de débit peut apparaître. Les erreurs de conversion ou de mémoire peuvent lever une exception JavaScript.

Exemple

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

5.5 console.debug(...)

Disponible depuis : Neutron AppEngine 1.0.0
console.debug(...values);
Objectif. Consigner des détails pendant le développement.
Description. Joint les arguments en les séparant par des espaces. Tente JSON.stringify pour les objets et une conversion en texte pour les autres valeurs. Remplace les caractères de contrôle par des espaces. Toutes les méthodes console partagent la même limite de journalisation.

Paramètres

Tableau 7

Paramètre

Type / exigence

Description

values

toutes valeurs JavaScript / facultatif

Zéro ou plusieurs arguments. Évitez les objets volumineux et les structures circulaires.

Résultat

undefined ; journal DEBUG, visible avec DL ≥ 4 et un DI approprié.

Erreurs et considérations particulières

La journalisation n’arrête pas à elle seule l’application, y compris console.error(). La limite partagée est de 10 appels/s et d’environ 512 octets de contenu par appel, hors préfixe. La sortie excédentaire est rejetée ou tronquée ; un avertissement supplémentaire de limitation de débit peut apparaître. Les erreurs de conversion ou de mémoire peuvent lever une exception JavaScript.

Exemple

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

Le niveau de débogage peut filtrer la sortie. N’utilisez pas la console comme transport fiable pour les données métier. Utilisez un module de communication pris en charge adapté pour un échange fiable de données.

6. Temporisateurs

Un temporisateur indique le premier instant d’exécution prévu. Cet environnement JavaScript ne garantit pas un temps réel strict : la mesure, la communication, les callbacks précédents et l’ordonnancement peuvent retarder l’exécution. Les intervalles manqués ne créent pas une file illimitée d’appels de rattrapage.

Un callback périodique async peut encore être en attente lorsque l’intervalle suivant arrive. Utilisez un indicateur d’occupation ou programmez le prochain setTimeout après la fin de l’opération. Il en va de même pour les événements de tout module : si le traitement doit être séquentiel, implémentez une file bornée ou refusez tout nouveau travail jusqu’à la fin de l’opération précédente.

6.1 setTimeout()

Disponible depuis : Neutron AppEngine 1.0.0
const id = setTimeout(callback, delayMs = 0, ...args);
Objectif. Exécuter une fonction une seule fois après un délai.
Description. Renvoie immédiatement ; le callback s’exécute plus tard. Le temporisateur est retiré de l’ensemble actif avant l’appel du callback, qui peut ainsi programmer une autre exécution.

Paramètres

Tableau 8

Paramètre

Type / exigence

Description

callback

function / requis

Une fonction ; le code fourni sous forme de chaîne n’est pas pris en charge.

delayMs

number / facultatif, valeur par défaut 0

Converti en nombre et en entier. Les délais invalides, négatifs ou nuls deviennent au minimum 1 ms. Maximum : 2 147 483 647 ms.

...args

toutes valeurs / facultatif

Arguments transmis au callback par l’environnement d’exécution.

Résultat

ID numérique accepté par clearTimeout. Valide uniquement pendant l’exécution actuelle de l’application.

Erreurs et considérations particulières

INVALID_ARGUMENT synchrone si le callback n’est pas une fonction ; QUOTA_EXCEEDED si 16 temporisateurs sont déjà actifs. Une exception ou un rejet de callback non gérés peuvent arrêter l’application.

Exemple

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

6.2 setInterval()

Disponible depuis : Neutron AppEngine 1.0.0
const id = setInterval(callback, delayMs = 0, ...args);
Objectif. Lire ou envoyer des données périodiquement.
Description. Le premier appel a lieu après le délai. Les callbacks suivants sont programmés périodiquement ; l’environnement d’exécution n’attend pas les Promise renvoyées par les callbacks async. Les retards ne provoquent pas une exécution de rattrapage illimitée.

Paramètres

Tableau 9

Paramètre

Type / exigence

Description

callback

function / requis

Une fonction ; le code fourni sous forme de chaîne n’est pas pris en charge.

delayMs

number / facultatif, valeur par défaut 0

Converti en nombre et en entier. Les délais invalides, négatifs ou nuls deviennent au minimum 1 ms. Maximum : 2 147 483 647 ms.

...args

toutes valeurs / facultatif

Arguments transmis au callback par l’environnement d’exécution.

Résultat

ID numérique accepté par clearInterval. L’intervalle reste actif jusqu’à son annulation ou l’arrêt de l’application.

Erreurs et considérations particulières

Les mêmes erreurs synchrones que setTimeout. Protégez le travail asynchrone des chevauchements et interceptez les rejets à l’intérieur de la fonction async.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
clearTimeout(id);
Objectif. Annuler les exécutions futures du temporisateur.
Description. Les deux fonctions utilisent le même registre de temporisateurs et peuvent annuler l’un ou l’autre type. Il est recommandé d’utiliser la paire set/clear correspondante.

Paramètres

Tableau 10

Paramètre

Type / exigence

Description

id

number / requis

ID renvoyé par setTimeout ou setInterval. Converti avec Number(id).

Résultat

undefined. Un ID inconnu n’a aucun effet.

Erreurs et considérations particulières

N’interrompt pas un callback ou une opération asynchrone déjà commencés. Convertir une valeur JavaScript inadaptée en nombre peut lever une exception JavaScript standard.

Exemple

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

6.4 clearInterval()

Disponible depuis : Neutron AppEngine 1.0.0
clearInterval(id);
Objectif. Annuler les exécutions futures du temporisateur.
Description. Les deux fonctions utilisent le même registre de temporisateurs et peuvent annuler l’un ou l’autre type. Il est recommandé d’utiliser la paire set/clear correspondante.

Paramètres

Tableau 11

Paramètre

Type / exigence

Description

id

number / requis

ID renvoyé par setTimeout ou setInterval. Converti avec Number(id).

Résultat

undefined. Un ID inconnu n’a aucun effet.

Erreurs et considérations particulières

N’interrompt pas un callback ou une opération asynchrone déjà commencés. Convertir une valeur JavaScript inadaptée en nombre peut lever une exception JavaScript standard.

Exemple

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

7. API de la balance

7.1 scale.read()

Disponible depuis : Neutron AppEngine 1.0.0
const measurement = scale.read();
Objectif. Lire le dernier instantané disponible de la balance sans attendre la stabilité.
Description. Renvoie de manière synchrone le dernier instantané disponible des données de la balance. Ne déclenche pas de nouvelle mesure. Lisez un seul objet et utilisez ses champs ensemble pour obtenir des valeurs net/brut/tare cohérentes.

Paramètres

Aucun paramètre.

Résultat

Un objet avec les champs ci-dessous. Lorsque la mesure est indisponible, net, gross et tare sont NaN et stable vaut false. L’unité et l’état restent des informations diagnostiques.

Erreurs et considérations particulières

Une balance indisponible est signalée par available=false plutôt que par une exception NO_MEASUREMENT. available=true n’implique pas stable=true. Un appel synchrone peut lever une exception si la mémoire JavaScript est épuisée.

Exemple

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

Champ

Type

Signification

available

boolean

La balance est disponible, l’interface de pesage est activée et la mesure est valide.

net

number

Poids net calculé à partir du poids brut et de la tare, arrondi au nombre de décimales configuré.

gross

number

Poids brut dans l’unité configurée.

tare

number

Tare actuelle dans l’unité configurée.

stable

boolean

La mesure valide est stable selon la configuration actuelle de la balance.

unit

string

Unité actuelle de la balance, par exemple kg ou g. Ce n’est pas nécessairement kg.

status

number

Valeur d’état actuelle de la balance. Le profil JavaScript ne fournit pas d’énumération nommée distincte ; n’inventez pas de correspondances entre codes.

sequence

number

Compteur sur 32 bits des mesures publiées ; revient au début en cas de dépassement. Ce n’est pas un ID persistant d’enregistrement de pesée.

timeMs

number

Instant de la dernière publication d’une mesure en millisecondes depuis le démarrage de l’appareil. Ce n’est pas l’heure UTC ; ce compteur sur 32 bits peut revenir au début.

Les raccourcis scale.net, scale.gross et scale.available sont des accesseurs dynamiques qui lisent un nouvel instantané à chaque accès. scale.tare est une fonction ; obtenez la tare numérique avec scale.read().tare. N’utilisez pas deux accesseurs distincts pour un couple brut/net devant partager le même instantané.

7.2 scale.tare()

Disponible depuis : Neutron AppEngine 1.0.0
const measurement = await scale.tare();
Objectif. Effectuer la tare avec la charge actuelle.
Description. Exécute la fonction correspondante de la balance sans contourner la stabilité, la plage, la protection, les commandes concurrentes ou la configuration. Exécute la commande de pesage T ; il ne s’agit pas d’un tarage immédiat avec TI.

Paramètres

Aucun paramètre.

Résultat

Promise<Measurement> : après une réponse réussie, lit un nouvel instantané JavaScript avec la structure de scale.read(). Cela ne garantit pas l’arrivée de la mesure suivante ; surveillez les mesures suivantes pour confirmer l’effet.

Erreurs et considérations particulières

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED ou TIMEOUT. Traitez les Promise rejetées avec await/try/catch. L’arrêt détruit le contexte ; la poursuite de la Promise n’est pas garantie.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const measurement = await scale.zero();
Objectif. Mettre la balance à zéro.
Description. Exécute la fonction correspondante de la balance sans contourner la stabilité, la plage, la protection, les commandes concurrentes ou la configuration. Exécute Z, ce qui diffère du tarage. La réussite dépend des conditions de fonctionnement et de la plage de mise à zéro autorisée.

Paramètres

Aucun paramètre.

Résultat

Promise<Measurement> : après une réponse réussie, lit un nouvel instantané JavaScript avec la structure de scale.read(). Cela ne garantit pas l’arrivée de la mesure suivante ; surveillez les mesures suivantes pour confirmer l’effet.

Erreurs et considérations particulières

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED ou TIMEOUT. Traitez les Promise rejetées avec await/try/catch. L’arrêt détruit le contexte ; la poursuite de la Promise n’est pas garantie.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const measurement = await scale.clearTare();
Objectif. Effacer la tare.
Description. Exécute la fonction correspondante de la balance sans contourner la stabilité, la plage, la protection, les commandes concurrentes ou la configuration. Exécute TAC pour demander la suppression de la tare actuelle.

Paramètres

Aucun paramètre.

Résultat

Promise<Measurement> : après une réponse réussie, lit un nouvel instantané JavaScript avec la structure de scale.read(). Cela ne garantit pas l’arrivée de la mesure suivante ; surveillez les mesures suivantes pour confirmer l’effet.

Erreurs et considérations particulières

BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED ou TIMEOUT. Traitez les Promise rejetées avec await/try/catch. L’arrêt détruit le contexte ; la poursuite de la Promise n’est pas garantie.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const measurement = await scale.setPresetTare(value);
Objectif. Définir une tare prédéfinie.
Description. Exécute la fonction correspondante de la balance sans contourner la stabilité, la plage, la protection, les commandes concurrentes ou la configuration. Exécute TA avec une tare numérique dans l’unité actuelle de la balance. Les valeurs ne sont pas automatiquement converties depuis une autre unité.

Paramètres

Tableau 13

Paramètre

Type / exigence

Description

value

number / requis

Nombre fini ≥ 0 dans la capacité de la balance, en scale.read().unit. Les chaînes, NaN et Infinity ne sont pas autorisés.

Résultat

Promise<Measurement> : après une réponse réussie, lit un nouvel instantané JavaScript avec la structure de scale.read(). Cela ne garantit pas l’arrivée de la mesure suivante ; surveillez les mesures suivantes pour confirmer l’effet.

Erreurs et considérations particulières

Un type invalide ou une valeur négative ou non finie est rejeté avec INVALID_ARGUMENT ; les valeurs au-delà de la capacité sont rejetées avec OUT_OF_RANGE. Autres erreurs : BUSY, OUT_OF_MEMORY, NO_MEASUREMENT, PERMISSION_DENIED, SCALE_REJECTED ou TIMEOUT. Traitez le rejet avec await/try/catch. L’arrêt détruit le contexte ; la poursuite de la Promise n’est pas garantie.

Exemple

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

Une opération de pesage attend pendant la fenêtre de commande configurée de la balance, plus environ 2 secondes de traitement. Ces opérations JavaScript ne disposent pas d’un paramètre de délai par appel. Une balance traitant une autre commande peut renvoyer BUSY. Exécutez les commandes dépendantes avec des appels await séquentiels plutôt qu’avec un Promise.all sans limite.

7.6 scale.cmd()

Disponible depuis : Neutron AppEngine 1.0.0
const response = await scale.cmd(command, { timeoutMs });
Objectif. Exécuter une commande CSCP et lire sa réponse d’origine.
Description. Accéder via CSCP aux commandes de la balance, à la configuration et aux autres fonctions prises en charge par l’appareil. Les règles existantes de validation des paramètres et de protection des données s’appliquent. RSD et les requêtes de configuration ne nécessitent pas de mesure valide. S et SX attendent une mesure stable ; SI et SXI interrogent immédiatement.

Paramètres

Tableau 14

Paramètre

Type / exigence

Description

command

string / requis

Une commande CSCP, au maximum 2048 octets UTF-8 après suppression des espaces autour et d’un éventuel CRLF final. Les commandes vides, NUL, les CR/LF internes et les autres caractères de contrôle sont interdits. La syntaxe et la casse suivent CSCP.

options

object / facultatif, valeur par défaut {}

Options d’attente. L’unité, la stabilité et les autorisations sont déterminées par la commande et les paramètres de la balance.

options.timeoutMs

integer / facultatif

1–60000 ms. Par défaut, la fenêtre d’attente configurée de la balance plus 2 secondes de traitement. Ne prolonge pas l’attente interne de stabilité de la commande.

Résultat

Promise<string> contenant la réponse CSCP d’origine, au maximum 4096 octets UTF-8. Un CRLF final est retiré ; les fins de ligne internes restent. La chaîne n’est pas un objet Measurement et n’est pas analysée automatiquement. S I, ES, FT L et ERRAUTH sont des résultats CSCP valides et ne rejettent pas la Promise. Déterminez la réussite de la commande à l’aide de sa référence CSCP.

Erreurs et considérations particulières

INVALID_ARGUMENT pour un usage incorrect ; MESSAGE_TOO_LARGE pour une commande trop volumineuse ; UNSUPPORTED_COMMAND pour les commandes à réponses multiples/silencieuses ou de réinitialisation ; BUSY pour une balance occupée ou la limite d’opérations concurrentes ; TIMEOUT pour une attente excessive ; NO_RESPONSE lorsqu’une commande se termine sans réponse ; RESPONSE_TOO_LARGE pour une réponse trop volumineuse ; OUT_OF_MEMORY pour une mémoire insuffisante. Les réponses ne sont jamais tronquées silencieusement. Stop interrompt l’exécution en attente ; sa Promise ne se poursuit pas dans le contexte détruit.

Exemple

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

Une seule commande de pesage peut être en attente à la fois. Utilisez await pour une exécution séquentielle. Une nouvelle requête reçoit BUSY lorsqu’une autre commande est en attente ; il n’existe pas de file de commandes cachée. Cela s’applique aussi à l’association de scale.cmd() avec tare/zero/clearTare/setPresetTare. Une annulation ou un délai dépassé n’annule pas les paramètres déjà modifiés. Une réponse tardive n’est pas attribuée à la requête suivante.

La fonction renvoie une seule réponse. SIR, SR, SXIR, RAS, RASI, CAL, RST, CWRESULTA et CWDEBUG sont rejetés avant exécution, y compris les commandes contenant un champ d’identifiants P=. Le contenu multiligne au sein d’une réponse, tel que I0, est autorisé. Utilisez un temporisateur et scale.read() pour des mesures répétées ; scale.cmd() n’ouvre pas de flux de réponses.

Une commande peut inclure des paramètres pris en charge et des identifiants CSCP ; la fonction ne contourne pas la protection de la balance. Respectez la syntaxe CSCP lorsqu’une commande protégée exige des identifiants. Traitez ERRAUTH et ERRLOCK dans le texte renvoyé. Les commandes d’installation d’application et les autres canaux de gestion n’ont pas leur place dans scale.cmd().

Vérifiez la prise en charge avec app.capabilities().scaleOperations.includes("cmd"). Les limites sont publiées sous limits.maxScaleCommandBytes, limits.maxScaleResponseBytes et limits.maxScaleCommandTimeoutMs. Disponible depuis Neutron AppEngine 1.0.0 ; les indicateurs features décrivent les modules dédiés. io.* est documenté dans le chapitre E/S distinct. Les paramètres du module et le stockage des données ont leurs propres chapitres et des API device et storage distinctes.

Tableau 15

Appel

Résultat / comportement

scale.cmd("S")

Prochaine mesure stable ou réponse d’échec CSCP telle que S I.

scale.cmd("SI")

Réponse immédiate avec le poids actuel.

scale.cmd("RSD")

Données et configuration de la balance sous forme de chaîne ; fonctionne sans poids disponible.

scale.cmd("FT=?")

Paramètre actuel du filtre, par exemple FT A 512.

scale.cmd("FT=512")

Modifie et enregistre le filtre selon CSCP ; examinez la réponse renvoyée.

scale.cmd("UNKNOWN")

Généralement ES comme résultat de la Promise résolue, et non comme rejet JavaScript.

scale.cmd("SIR")

Rejet UNSUPPORTED_COMMAND ; aucun flux continu n’est lancé.

7.7 Erreurs du module balance

Tableau 16

Code

Signification pour la balance

NO_MEASUREMENT

Opération de pesage sans mesure valide ou sans balance disponible.

OUT_OF_RANGE

La tare prédéfinie dépasse la capacité.

PERMISSION_DENIED

Commande de la balance rejetée par la protection/l’autorisation.

SCALE_REJECTED

La balance a rejeté l’opération ; examinez message et les conditions de la balance.

7.8 Journalisation périodique du poids

Fichier .js autonome ne nécessitant pas TCP. Consigne une mesure valide une fois par seconde. Utilisez Stop dans le gestionnaire d’applications pour l’arrêter.

// 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. Entrées et sorties numériques

Le module io surveille six entrées et six sorties, configure leurs fonctions, commande directement les sorties réservées et lit les compteurs des entrées. Les indices sont toujours 1–6. Toutes les fonctions, propriétés et tous les événements de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0. Prise en charge de l’API : app.capabilities().features.io ; disponibilité physique des E/S : app.capabilities().io.available.

La lecture de l’état et l’observation des événements ne nécessitent pas de réservation. Vous pouvez observer une sortie commandée par une fonction système ; avant d’écrire directement, désactivez explicitement sa fonction et réservez-la. Le module partage le traitement E/S de l’appareil ; les mêmes règles de propriété s’appliquent donc via les autres interfaces.

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

Disponible depuis : Neutron AppEngine 1.0.0
const input = io.input(1);
const output = io.output(1);
Objectif. Obtenir l’objet d’une entrée ou sortie physique.
Description. Des appels répétés pour la même broche renvoient le même objet. Ne modifie pas la configuration, n’enregistre pas d’événements et ne commute pas de sortie.

Paramètres

Tableau 17

Paramètre

Type / exigence

Description

index

integer / requis

1..6. Les chaînes, zéro, les valeurs fractionnaires et les indices supérieurs à 6 sont rejetés.

Résultat

Objet d’entrée ou de sortie. Les deux prennent en charge read, configure, on, once et off. Les sorties ajoutent claim, write et release ; les entrées ajoutent counter et resetCounter.

Erreurs et considérations particulières

INVALID_ARGUMENT pour un indice invalide. L’objet peut être obtenu sans carte E/S ; vérifiez read().available.

Exemple

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

input.read() / output.read()

Disponible depuis : Neutron AppEngine 1.0.0
const inputState = io.input(1).read();
const outputState = io.output(1).read();
Objectif. Lire de manière synchrone le dernier instantané de l’état et de la configuration.
Description. La lecture ne nécessite pas de réservation et n’émet aucun événement change. L’instantané est actualisé par le traitement partagé de l’appareil et lors des changements ; read n’effectue aucun échantillonnage physique supplémentaire. Après un await configure/write réussi, l’instantané inclut les résultats de l’opération correspondante.

Paramètres

Aucun paramètre.

Résultat

Entrée : {index, available, value, functionId, function, mode, debounceMs, glitchUs, pull, counter}. Sortie : {index, available, value, functionId, function, claimed}. Les types et significations figurent ci-dessous.

Erreurs et considérations particulières

value vaut null pour les E/S indisponibles et les entrées en mode disabled ou counter. counter est BigInt uniquement pour une entrée compteur disponible ; sinon null. Le value de sortie représente l’état commandé ; confirmer la commutation réelle d’un contacteur ou appareil externe nécessite un retour sur une entrée.

Exemple

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

Champ depuis Neutron AppEngine 1.0.0

Type

Signification

index

number

Numéro de broche 1..6.

available

boolean

Les E/S sont présentes sur l’appareil.

value

boolean | null

true correspond au 1 logique, false au 0 logique. Les valeurs d’entrée sont filtrées contre les rebonds ; null signifie qu’aucune valeur numérique n’est disponible.

functionId / function

number / string

Numéro de fonction existant et son nom dans l’API JavaScript. unknown indique un numéro stocké non pris en charge.

mode

string / entrée uniquement

disabled, digital ou counter.

debounceMs

number / entrée uniquement

Délai de confirmation d’un changement numérique en millisecondes.

glitchUs

number / entrée uniquement

Filtre des impulsions courtes du compteur en microsecondes. Utilisé en mode counter.

pull

string / entrée uniquement

none, up ou down.

counter

bigint | null / entrée uniquement

Dernière valeur du compteur sans perte de précision des grands entiers.

claimed

boolean / sortie uniquement

La sortie est réservée par l’application utilisateur. Cela ne signifie pas que la sortie est activée.

input.configure(options)

Disponible depuis : Neutron AppEngine 1.0.0
await io.input(1).configure({ mode: "digital", function: "disabled", debounceMs: 20, pull: "down" });
Objectif. Configurer et enregistrer le mode, la fonction et le traitement de l’entrée sélectionnée.
Description. Modifie les propriétés fournies et conserve les autres lorsqu’elles sont compatibles avec le mode sélectionné. Enregistre et applique la configuration sans redémarrage, via le chemin partagé existant de configuration des entrées. Les modes disabled et counter désactivent la fonction système de l’entrée. L’initialisation d’un nouveau mode n’émet pas change et ne compte pas un niveau initialement actif comme un nouvel appui.

Paramètres

Tableau 19

Paramètre

Type / exigence

Description

options.mode

string / facultatif

disabled, digital ou counter. En cas d’omission, conserve le mode actuel.

options.function

string | integer / facultatif

Nom ou ID provenant du tableau des fonctions d’entrée. Une fonction active n’est autorisée qu’en mode digital.

options.debounceMs

integer / facultatif

0..60000 ms, mode digital uniquement. Le réglage initial existant est de 20 ms ; indiquez explicitement la valeur souhaitée lors du passage depuis un autre mode.

options.pull

string / facultatif

none, up ou down ; mode digital uniquement.

options.glitchUs

integer / facultatif

0..12 µs, mode counter uniquement. 0 désactive le filtrage. Lors du passage à counter sans filtre spécifié, utilise le filtre non nul précédent ou 5 µs.

Résultat

Promise<InputState> avec la structure de read(). Les paramètres persistent après Stop et le redémarrage de l’appareil.

Erreurs et considérations particulières

INVALID_ARGUMENT pour des types invalides ou des propriétés incompatibles, NOT_AVAILABLE, RESOURCE_IN_USE pendant un dosage ou contrôle pondéral actif, CONFIGURE_FAILED si l’application ou l’enregistrement échoue, et BUSY. Le mode counter peut être rejeté si l’entrée sélectionnée n’a pas de ressource de comptage disponible. Ne configurez pas dans une boucle périodique rapide.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
await io.output(1).configure({ function: "disabled" });
Objectif. Sélectionner et enregistrer la fonction système d’une sortie ou la désactiver.
Description. Modifier la fonction ne commute pas directement la sortie. Une fonction active commande son état selon les règles de l’appareil. disabled permet la commande manuelle et la réservation par JavaScript ; cela ne désactive pas automatiquement le niveau actuel de la sortie.

Paramètres

Tableau 20

Paramètre

Type / exigence

Description

options.function

string | integer / requis

Nom ou ID provenant du tableau des fonctions de sortie.

Résultat

Promise<OutputState>. Le paramètre est persistant et s’applique sans redémarrage.

Erreurs et considérations particulières

RESOURCE_IN_USE si la sortie est réservée ou si le dosage/contrôle pondéral est actif. Appelez release(), puis configure(). Les autres canaux ne peuvent pas non plus changer la fonction d’une sortie réservée. Autres erreurs : INVALID_ARGUMENT, NOT_AVAILABLE, CONFIGURE_FAILED, BUSY.

Exemple

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

Noms et ID des fonctions

Tableau 21

ID d’entrée

Nom JavaScript depuis Neutron AppEngine 1.0.0

Signification

0

disabled

Aucune fonction système

1

zero

Mise à zéro

2

tare

Tarage

3

clearTare

Effacement de la tare

4

dosingStart

Démarrage du dosage

5

dosingPause

Pause du dosage

6

dosingStop

Arrêt du dosage

7

checkweigherSensor

Capteur de produit

8

checkweigherStart

Démarrage du contrôle pondéral

9

checkweigherPause

Pause du contrôle pondéral

10

checkweigherStop

Arrêt du contrôle pondéral

11

checkweigherReset

Réinitialisation du contrôle pondéral

12

checkweigherEnable

Activation de CONS

13

checkweigherTrigger

Déclenchement du rejet

Tableau 22

ID de sortie

Nom JavaScript depuis Neutron AppEngine 1.0.0

Signification

0

disabled

Aucune fonction système

1

inTolerance

Dans la tolérance

2

underTolerance

Sous la tolérance

3

overTolerance

Au-dessus de la tolérance

4

dosingActive

Dosage actif

5

dosingFast

Dosage grossier

6

dosingMedium

Dosage moyen

7

dosingFine

Dosage fin

8

dosingFly

Attente de l’afflux

9

dosingUnloading

Vidange

10

dosingInTolerance

Dosage dans la tolérance

11

dosingOutOfTolerance

Dosage hors tolérance

12

dosingEnd

Dosage terminé

13

dosingError

Erreur de dosage

14

checkweigherBelt

Convoyeur

15

checkweigherLow

Rejet pour poids insuffisant

16

checkweigherHigh

Rejet pour poids excessif

17

checkweigherGood

Impulsion de poids acceptable

18

checkweigherCommon

Rejet commun / erreur

19

checkweigherActive

Contrôle pondéral actif

20

checkweigherAlarm

Alarme

21

checkweigherBuffer

Avertissement de trémie

Les fonctionnalités de l’appareil déterminent les règles réelles de ces fonctions système. Enregistrer change ne désactive pas une fonction : une entrée affectée à la tare peut déclencher à la fois le tarage système et un événement JavaScript. Si JavaScript doit effectuer l’opération, définissez d’abord function="disabled" pour éviter une double exécution. Les listes d’ID/noms sont également disponibles dans capabilities.io.inputFunctions et outputFunctions.

output.claim(options?)

Disponible depuis : Neutron AppEngine 1.0.0
await io.output(1).claim({ safeState: false });
Objectif. Réserver la commande manuelle exclusive de la sortie pour l’exécution actuelle de l’application.
Description. Autorisé uniquement avec function=disabled. Ne désactive pas automatiquement une fonction système affectée et ne modifie pas le niveau actuel. La même application peut réserver à nouveau la même sortie pour actualiser safeState.

Paramètres

Tableau 23

Paramètre

Type / exigence

Description

options.safeState

boolean / false

État de la sortie lors de release() ou de l’arrêt de l’application. S’applique à l’exécution actuelle ; n’est pas enregistré comme état de démarrage de l’appareil.

Résultat

Promise<OutputState> avec claimed=true.

Erreurs et considérations particulières

RESOURCE_IN_USE pour une fonction système active ou un autre propriétaire. NOT_AVAILABLE, INVALID_ARGUMENT, BUSY. Les sorties réservées rejettent les écritures externes et les changements de fonction, y compris via les autres canaux. L’observation de change reste autorisée.

Exemple

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

output.write(value)

Disponible depuis : Neutron AppEngine 1.0.0
await io.output(1).write(true);
Objectif. Définir une sortie réservée sur l’état logique demandé.
Description. Écrit via le traitement E/S partagé. Un changement réel émet change ; réécrire la même valeur n’émet aucun événement. L’état n’est pas enregistré à chaque commutation. La Promise et l’événement change sont des notifications distinctes ; ne vous fiez pas à leur ordre relatif.

Paramètres

Tableau 24

Paramètre

Type / exigence

Description

value

boolean / requis

true active, false désactive ; 0, 1 et les chaînes ne sont pas autorisés.

Résultat

Promise<OutputState> après écriture de la sortie de commande.

Erreurs et considérations particulières

NOT_OWNER avant claim ou après release. NOT_AVAILABLE, INVALID_ARGUMENT, RESOURCE_IN_USE, BUSY. La confirmation ne prouve pas le fonctionnement physique de l’appareil externe.

Exemple

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

output.release()

Disponible depuis : Neutron AppEngine 1.0.0
await io.output(1).release();
Objectif. Définir la sortie sur safeState et libérer sa propriété.
Description. La libération automatique se produit aussi dans le traitement du service après Stop, une erreur non gérée ou le remplacement de l’application. La fonction système précédente n’est pas restaurée automatiquement : configure est une modification persistante explicite. Libérer une sortie non réservée dans l’exécution actuelle n’a aucun effet.

Paramètres

Aucun paramètre.

Résultat

Promise<undefined>. Si safeState modifie le niveau, change est émis pendant que l’application est encore en cours d’exécution.

Erreurs et considérations particulières

NOT_OWNER pour un autre propriétaire, NOT_AVAILABLE, BUSY. La transmission d’un événement final n’est pas garantie à l’arrêt de l’application. Après une réinitialisation matérielle, l’état normal de sortie au démarrage de l’appareil s’applique (désactivé), pas le safeState précédent. Cela ne remplace pas un circuit de sécurité matériel.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
pin.on("change", callback);
pin.once("change", callback);
pin.off("change", callback);
Objectif. Observer les changements sur l’entrée ou la sortie sélectionnée.
Description. on observe les changements suivants. once se désinscrit avant le premier changement suivant, qui peut être une activation ou une désactivation. off supprime les inscriptions de la même fonction. L’inscription seule n’émet aucun événement initial. L’événement pris en charge est change, avec au maximum 32 écouteurs par broche.

Paramètres

Tableau 25

Paramètre

Type / exigence

Description

eventName

string / requis

Uniquement "change".

callback

function / requis

Reçoit {index, value, previousValue, timeMs}. off nécessite la même référence de fonction.

Résultat

Renvoie le même objet broche pour chaîner les appels. Les événements sont indépendants de l’origine du changement : JavaScript, CSCP, autres interfaces de gestion ou fonction système.

Erreurs et considérations particulières

INVALID_ARGUMENT, QUOTA_EXCEEDED. Les entrées émettent des événements après filtrage antirebond. Les événements numériques sont indisponibles en mode counter ou disabled. Les sorties émettent des événements uniquement lorsque le niveau commandé change réellement. Une exception ou une Promise rejetée non gérée dans un callback peut arrêter l’application selon les règles de l’environnement d’exécution. Sans écouteurs, aucun événement de cette broche n’est envoyé à JavaScript.

Exemple

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

Champ d’événement depuis Neutron AppEngine 1.0.0

Type

Signification

index

integer

1..6 pour la broche possédant l’écouteur.

value

boolean

Nouvel état : true correspond au 1 logique, false au 0 logique.

previousValue

boolean

État confirmé précédent.

timeMs

number

Instant monotone du changement en millisecondes depuis le démarrage de l’appareil ; peut être fractionnaire. Ce n’est ni une date, ni une heure UTC, ni l’instant de transmission du callback. Pour les entrées, il s’agit de l’instant de confirmation après filtrage antirebond.

L’exemple de durée d’activation ne nécessite pas d’interrogation périodique. timeMs repart au redémarrage de l’appareil. Les changements de configuration et les échantillons initiaux dans un nouveau mode ne sont pas des événements de changement physique.

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

Disponible depuis : Neutron AppEngine 1.0.0
const count = io.input(1).counter();
Objectif. Renvoyer le dernier total des impulsions positives détectées sur une entrée compteur.
Description. Le comptage utilise le mécanisme existant de l’appareil sans appeler JavaScript à chaque impulsion. BigInt préserve la précision au-delà de 2^53. Maximum : 9223372036854775807 ; la valeur sature à cette limite. La persistance normale du compteur de l’appareil reste active ; une coupure soudaine d’alimentation peut entraîner la perte des impulsions non encore enregistrées.

Paramètres

Aucun paramètre.

Résultat

bigint. La même valeur apparaît dans input.read().counter. Utilisez count.toString() pour JSON ; JSON.stringify ne peut pas sérialiser directement BigInt.

Erreurs et considérations particulières

INVALID_MODE si l’entrée n’est pas en mode counter ; NOT_AVAILABLE si les E/S sont absentes. C’est un instantané, pas une garantie qu’aucune nouvelle impulsion ne soit arrivée pendant la lecture.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
await io.input(1).resetCounter();
Objectif. Réinitialiser le compteur sélectionné et enregistrer la nouvelle valeur de référence.
Description. Asynchrone ; autorisé uniquement en mode counter. N’émet aucun événement de changement numérique. Des impulsions peuvent arriver pendant ou immédiatement après la réinitialisation.

Paramètres

Aucun paramètre.

Résultat

Promise<bigint> contenant le dernier instantané du compteur après exécution. De nouvelles impulsions signifient qu’il peut ne plus valoir 0n.

Erreurs et considérations particulières

INVALID_MODE, NOT_AVAILABLE, WRITE_FAILED, BUSY. Un échec d’enregistrement peut se produire après la remise à zéro du compteur en mémoire ; l’erreur n’annule pas cet effet. Ne réinitialisez pas dans une boucle rapide.

Exemple

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

Exemple complet : une entrée commande une sortie

L’exemple enregistre explicitement la configuration de l’entrée 1 et désactive la fonction système de la sortie 1. Il réserve ensuite la sortie avec safeState=false, surveille l’entrée 1 et observe séparément la sortie 2. Il borne le chevauchement des écritures asynchrones et applique le dernier état de l’entrée après la fin d’une écriture.

// 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 d’une application E/S

Tableau 27

Test

Résultat attendu

État initial

read renvoie une valeur ; l’inscription de on/once n’émet aucun événement.

Activer puis désactiver l’entrée 1

Deux événements change après filtrage antirebond, avec previousValue/value opposés et les timeMs correspondants.

Bref rebond du contact

Aucun événement en double pour un changement confirmé.

SOT externe pour la sortie 2 non réservée

Un événement change JavaScript à chaque changement réel ; répéter la même valeur n’en émet aucun.

Sortie 2 commandée par une fonction système

JavaScript peut observer les changements sans réservation.

SOT/SOF externe ou changement de fonction pour la sortie 1 réservée

Rejeté sans écraser la sortie de l’application.

Stop ou erreur de l’application avec une sortie réservée activée

Passage à safeState et libération pendant le traitement du service.

Compteur et grandes valeurs

BigInt sans perte de précision ; aucun événement de changement numérique pour chaque impulsion.

E/S indisponibles ou indice invalide

available=false ou INVALID_ARGUMENT ; aucun accès à une autre broche.

9. Paramètres du module : RMD et SMD

Le module device gère les paramètres Neutron. Il est distinct de scale, qui commande le pesage, et des données de l’application dans storage. Toutes les fonctions et propriétés de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0. Prise en charge : app.capabilities().features.settings.

Les modifications utilisent la validation et le stockage SMD existants. Elles respectent les interfaces occupées et les sorties réservées. Les paramètres applicables en fonctionnement utilisent les mécanismes existants d’application à chaud. Les autres signalent qu’un redémarrage est nécessaire. L’API ne redémarre jamais automatiquement l’appareil.

device.cmd(command)

Disponible depuis : Neutron AppEngine 1.0.0
const raw = await device.cmd("RMD");
const result = await device.cmd("SMD;S0B=19200;S0P=0;");
Objectif. Exécuter une commande de gestion RMD ou SMD prise en charge.
Description. RMD renvoie une liste textuelle des paramètres et des états de base dans le format existant. SMD utilise le même résultat que settings.write(). Les autres commandes de gestion telles que REB ne sont pas prises en charge ici. Ne répétez pas SMD entre les paramètres individuels.

Paramètres

Tableau 28

Paramètre

Type / exigence

Description

command

string / requis

RMD ou SMD;KEY=value;... . Maximum 2048 octets UTF-8 ; aucun caractère de contrôle. SMD accepte jusqu’à 16 clés distinctes.

Résultat

RMD : Promise<string>. SMD : Promise<SettingsWriteResult>, décrit ci-dessous.

Erreurs et considérations particulières

INVALID_ARGUMENT, UNSUPPORTED_COMMAND, BUSY, NO_RESPONSE, RESPONSE_TOO_LARGE. RMD peut dépasser 4096 octets ; utilisez settings.read pour des clés sélectionnées ou settings.list pour paginer. L’API ne lit ni mots de passe, ni PIN, ni données privées de certificats. Gérez les certificats via le processus existant de provisionnement des certificats.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const values = await device.settings.read(["S0B", "S0P"]);
Objectif. Lire des paramètres stockés sélectionnés sans réponse RMD volumineuse.
Description. Renvoie les valeurs sous forme de chaînes, y compris les nombres. Une clé absente a la valeur null. La lecture ne modifie ni l’état ni les paramètres de l’appareil et ne garantit pas que l’application matérielle en attente soit terminée.

Paramètres

Tableau 29

Paramètre

Type / exigence

Description

keys

string[] / requis

1..16 clés. Les noms contiennent 1..15 caractères : A–Z, 0–9 ou _.

Résultat

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

Erreurs et considérations particulières

INVALID_ARGUMENT, PERMISSION_DENIED pour les données protégées, RESPONSE_TOO_LARGE, BUSY. N’inventez pas d’API avec des clés inconnues ; les paramètres pris en charge sont définis par l’appareil et sa documentation.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const page = await device.settings.list({ cursor: null, limit: 16 });
Objectif. Lire par pages les paramètres stockés accessibles publiquement.
Description. Les clés sont triées par ordre croissant. cursor est la dernière clé de la page précédente, exclue de la suivante. La réponse peut contenir moins de limit clés en raison de sa limite de taille. Les pages ne constituent pas un instantané unique : les paramètres peuvent changer entre les appels.

Paramètres

Tableau 30

Paramètre

Type / exigence

Description

options.cursor

string | null / omis

nextCursor de la réponse précédente ; null ou une omission commence au début.

options.limit

integer / 16

1..32 clés par page ; la limite de réponse reste de 4096 octets.

Résultat

Promise<{values:object, nextCursor:string|null}>. null indique la fin.

Erreurs et considérations particulières

INVALID_ARGUMENT, RESPONSE_TOO_LARGE pour une valeur unique trop volumineuse, BUSY. La liste contient des clés stockées ; les états RMD dynamiques ne sont pas nécessairement des paramètres stockés. Les données confidentielles sont omises.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const result = await device.settings.write({ S0B: "19200", S0P: "0" });
Objectif. Enregistrer un groupe de paramètres via le traitement SMD existant.
Description. Valide le format global avant de commencer. La validation individuelle et les défaillances matérielles suivent ensuite les règles SMD existantes. Le groupe n’est pas une transaction : un échec n’annule pas les autres valeurs enregistrées. Vérifiez result.ok et result.errors même après un await réussi.

Paramètres

Tableau 31

Paramètre

Type / exigence

Description

values

object / requis

1..16 clés. Les valeurs peuvent être des chaînes, des booléens (0/1) ou des entiers dans −2147483648..4294967295. Fournissez les décimaux sous forme de chaînes dans le format du paramètre. Au maximum 1024 octets UTF-8 par valeur ; aucun point-virgule, caractère de contrôle ou valeur spéciale ?. La requête entière doit tenir dans 4096 octets.

Résultat

Promise<{ok:boolean, applied:string[], errors:object, rebootRequired:boolean, applyPending:boolean}>. applied liste les clés sans erreur immédiate d’enregistrement ; ce n’est pas une confirmation indépendante de la disponibilité de l’interface physique. Une erreur finale d’application peut avoir une clé distincte dans errors.

Erreurs et considérations particulières

Un format invalide est rejeté avec INVALID_ARGUMENT ou MESSAGE_TOO_LARGE. Les échecs des paramètres individuels renvoient ok=false et errors, tels que CHECKWEIGHER_BUSY ou INVALID_OR_WRITE_FAILED. applyPending indique une application à l’interface série en attente ; surveillez l’état de l’interface ou de l’appareil. rebootRequired ne déclenche jamais de redémarrage automatique. N’écrivez pas de paramètres persistants dans une boucle rapide de mesure.

Exemple

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

Exemple de lecture des paramètres

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. Stockage et fichiers

Le module storage fournit un stockage persistant des données de l’application. Toutes les fonctions de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0. Prise en charge : app.capabilities().features.files. Les fichiers de l’application sont distincts des fichiers système, des certificats et du code de l’application installée. L’API ne peut accéder à rien en dehors de cet espace de données.

Les noms de fichiers contiennent 1..64 caractères. Le premier doit être A–Z/a–z ou un chiffre ; les suivants peuvent aussi inclure _, - ou un point. Les points consécutifs, les barres obliques, les sous-répertoires et les chemins absolus sont interdits. Les noms sont sensibles à la casse. Les données subsistent après Stop, un redémarrage et un remplacement normal de l’application. L’application installée partage un seul espace de données ; une nouvelle version ou une autre application sur l’appareil peut utiliser les mêmes données. Factory default supprime les fichiers utilisateur et les bases locales. Le Delete normal de l’application ne les supprime pas.

Les opérations sont asynchrones et utilisent une file de service bornée. Ne chargez pas un fichier volumineux entier dans JavaScript, ne créez pas de files d’écriture illimitées et n’envoyez pas tous les blocs sans await. L’arrêt n’annule pas une écriture déjà commencée ; son résultat peut ne plus parvenir à l’application arrêtée.

storage.info()

Disponible depuis : Neutron AppEngine 1.0.0
const info = await storage.info();
Objectif. Indiquer l’utilisation, le quota et l’espace disponible.
Description. Les fichiers et les bases locales partagent le quota de l’application. La disponibilité réelle dépend aussi des autres données de l’appareil et de la réserve système. Les copies temporaires pour un remplacement atomique ou une compaction nécessitent de l’espace physique supplémentaire.

Paramètres

Aucun paramètre.

Résultat

{quotaBytes, usedBytes, reserveBytes, freeBytes, availableBytes, maxFileBytes, databases:[{name,bytes}]}. usedBytes est la taille logique cumulée des fichiers et bases validés ; freeBytes est l’espace total libre. availableBytes estime la croissance possible dans les limites du quota et de la réserve.

Erreurs et considérations particulières

NOT_AVAILABLE ou une erreur de lecture. Un instantané, pas une réservation pour une future écriture. La disponibilité est à nouveau vérifiée pendant l'opération.

Exemple

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

storage.write() / storage.writeText()

Disponible depuis : Neutron AppEngine 1.0.0
await storage.write(name, data);
await storage.writeText(name, text);
Objectif. Créer un fichier ou remplacer tout son contenu.
Description. write accepte string ou Uint8Array ; writeText accepte uniquement string. Les chaînes sont stockées en UTF-8 ; les données binaires sous forme d’octets exacts. N’ajoute ni saut de ligne ni NUL. Le remplacement complet utilise une écriture temporaire, puis le remplacement du fichier validé.

Paramètres

Tableau 32

Paramètre

Type / exigence

Description

name

string / requis

Nom de fichier valide.

data / text

string | Uint8Array / requis

0..4096 octets par appel après encodage UTF-8. writeText n’accepte pas Uint8Array.

Résultat

Promise<undefined> après une confirmation d'écriture et de stockage réussie. Une charge utile vide crée ou vide le fichier.

Erreurs et considérations particulières

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, NOT_AVAILABLE, BUSY. L'échec du remplacement conserve le fichier validé précédent. Pour un contenu plus volumineux, écrivez le premier morceau, puis ajoutez-le séquentiellement ; cette construction en plusieurs étapes n'est pas une opération atomique.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
await storage.append(name, data);
await storage.appendText(name, text);
Objectif. Ajouter des données à un fichier, ce qui convient aux journaux.
Description. Crée un fichier absent sans écraser le contenu précédent. L’ajout n’est pas une transaction sur plusieurs enregistrements ; des erreurs ou une coupure d’alimentation peuvent laisser le dernier ajout incomplet. Concevez les journaux pour détecter ces enregistrements finaux partiels.

Paramètres

Tableau 33

Paramètre

Type / exigence

Description

name

string / requis

Nom de fichier valide.

data / text

string | Uint8Array / requis

Au maximum 4096 octets par appel ; appendText exige string. Taille maximale du fichier : 262144 octets.

Résultat

Promise<undefined>. Un succès livré confirme l'écriture ; une réponse manquante ne signifie pas que l'écriture n'a pas eu lieu.

Erreurs et considérations particulières

MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, BUSY. Une partie de l'ajout peut déjà exister après une erreur. Ne réessayez pas aveuglément les enregistrements commerciaux sans un ID unique ou une vérification.

Exemple

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

storage.read() / storage.readText()

Disponible depuis : Neutron AppEngine 1.0.0
const bytes = await storage.read(name, { offset: 0, length: 4096 });
const text = await storage.readText(name);
Objectif. Lire des octets binaires ou du texte UTF-8.
Description. read renvoie Uint8Array ; readText renvoie string. offset et length utilisent toujours des octets. Commencer au-delà de la fin renvoie un résultat vide. Une lecture près de la fin peut renvoyer moins d’octets que demandé.

Paramètres

Tableau 34

Paramètre

Type / exigence

Description

name

string / requis

Nom du fichier.

options.offset

integer / 0

0..262144 octets depuis le début.

options.length

integer / facultatif

0..4096 octets. read lit par défaut jusqu’à 4096 octets. Sans length, readText exige que le texte restant tienne dans une réponse ; sinon RESPONSE_TOO_LARGE.

Résultat

Promise<Uint8Array> ou Promise<string>. read préserve le binaire NUL et tous les autres octets.

Erreurs et considérations particulières

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, RESPONSE_TOO_LARGE. Respectez les limites des caractères multi-octets lors de la division du texte UTF-8 ; décoder indépendamment des morceaux arbitraires peut diviser un caractère. readText n'est pas un analyseur JSON ou JSONL ; utilisez JSON.parse pour les petits documents JSON.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const page = await storage.list({ cursor: null, limit: 16 });
const info = await storage.stat("data.bin");
Objectif. Lister les fichiers ou obtenir la taille d’un fichier.
Description. list inclut uniquement les fichiers ordinaires de l’application, pas les fichiers internes des bases de données. Les noms sont triés par ordre croissant ; cursor exclut le dernier nom déjà renvoyé. Les bases apparaissent dans storage.info().databases.

Paramètres

Tableau 35

Paramètre

Type / exigence

Description

options.cursor

string | null / omis

nextCursor de la page précédente.

options.limit

integer / 16

1..32 fichiers.

name pour stat

string / requis

Nom valide.

Résultat

list : {files:[{name,size}], nextCursor:string|null}. stat : {name,size}. La taille est en octets. null indique la fin de la liste.

Erreurs et considérations particulières

NOT_FOUND pour stat, INVALID_ARGUMENT, READ_FAILED, OUT_OF_MEMORY. Les pages ne sont pas un instantané immuable lors d'ajouts ou de suppressions simultanés.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const removed = await storage.remove("old.jsonl");
await storage.rename("measurements.jsonl", "archive.jsonl");
Objectif. Supprimer ou renommer un fichier ordinaire.
Description. remove ne peut pas accéder aux données internes des bases. rename n’écrase pas une destination existante ; supprimez-la d’abord explicitement si nécessaire.

Paramètres

Tableau 36

Paramètre

Type / exigence

Description

name

string / requis

Nom du fichier source.

to pour rename

string / requis

Nouveau nom valide sans fichier existant.

Résultat

remove : Promise<boolean>, false si absent. rename : Promise<undefined>.

Erreurs et considérations particulières

NOT_FOUND pour une source de renommage absente, ALREADY_EXISTS pour une destination existante, WRITE_FAILED, INVALID_ARGUMENT. La suppression ne peut pas être annulée.

Exemple

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

storage.findText(name, text, options?)

Disponible depuis : Neutron AppEngine 1.0.0
const page = await storage.findText("measurements.jsonl", "ART-001", { offset: 0, limit: 16 });
Objectif. Rechercher un texte exact dans un fichier ordinaire sans charger tout le contenu dans JavaScript.
Description. Recherche séquentielle d’octets UTF-8 sensible à la casse, et non une expression régulière. Accepte les correspondances qui se chevauchent. Chaque appel parcourt au maximum 65536 octets ou s’arrête à la limite de correspondances. Utilisez une base locale pour rechercher rapidement par clé plutôt que de parcourir les fichiers à répétition.

Paramètres

Tableau 37

Paramètre

Type / exigence

Description

name

string / requis

Nom du fichier.

text

string / requis

1..128 octets UTF-8, sans NUL.

options.offset

integer / 0

Position initiale en octets, 0..262144.

options.limit

integer / 16

1..64 correspondances par page.

Résultat

{offsets:number[], nextOffset:number|null}. offsets contient les positions initiales absolues des correspondances en octets. Continuez exactement avec le nextOffset renvoyé ; il préserve les correspondances partielles possibles entre pages. null indique la fin du fichier.

Erreurs et considérations particulières

NOT_FOUND, INVALID_ARGUMENT, READ_FAILED, CANCELLED. Ne modifiez pas le fichier lors d'une recherche en plusieurs étapes si vous avez besoin de résultats stables. Le temps total de recherche séquentielle est proportionnel à la taille du fichier.

Exemple

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

Journaux JSONL et rotation

JSONL stocke un objet JSON indépendant par ligne, sans virgules entre les lignes ni [] autour. Cela permet d’ajouter des mesures. Générez chaque ligne avec JSON.stringify(record)+"\n". Détectez et traitez séparément une dernière ligne incomplète après interruption. JSONL ne fournit ni index automatique ni suppression automatique des anciennes mesures.

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

Limites de stockage partagées

Tableau 38

Limite depuis Neutron AppEngine 1.0.0

Valeur

Quota partagé de l’application

524288 octets pour l’ensemble des fichiers et des bases de données.

Réserve système

131072 octets physiquement libres avant toute écriture supplémentaire. Les autres fonctions de l’appareil peuvent modifier la disponibilité réelle.

Fichier ou journal d’une seule base de données

262144 octets.

Appel de lecture / écriture

4096 octets.

Fichiers ordinaires

Au maximum 64 noms.

Ordre

Les requêtes de stockage s’exécutent dans une seule file de service bornée. Plusieurs appels ne constituent pas une transaction.

Arrêt de l’application

Les objets de base de données ouverts sont libérés ; les données validées subsistent.

Factory default

Supprime aussi les fichiers et les bases de données de l’application.

11. Base de données locale simple d’enregistrements

La base locale stocke de petits objets JSON avec une clé unique, par exemple un code produit, un code recette ou un ID d’enregistrement métier. Toutes les fonctions de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0. Prise en charge : app.capabilities().features.records. Les données partagent l’espace et le quota de stockage des fichiers, mais les fichiers internes de la base sont distincts de l’API des fichiers ordinaires.

L’ouverture valide le journal des enregistrements et construit un index trié des clés. get utilise l’index et la position directe de l’enregistrement sans parcourir toute la base. L’ouverture et la compaction parcourent les données et peuvent prendre plus de temps ; ouvrez une seule fois au démarrage et réutilisez l’objet. Une seule clé indexée par base est prise en charge. Il n’y a ni SQL, ni relations, ni indexation secondaire automatique, ni transaction sur plusieurs enregistrements.

storage.openRecords(name, options?)

Disponible depuis : Neutron AppEngine 1.0.0
const articles = await storage.openRecords("articles", { key: "code" });
Objectif. Créer ou ouvrir une base et préparer son index.
Description. Le nom de la base et celui du champ clé sont associés définitivement à la création. Utilisez le même nom de champ clé à la réouverture. L’ouverture d’un nom déjà ouvert est rejetée ; réutilisez l’objet renvoyé. Les objets sont valides uniquement pendant l’exécution actuelle de l’application.

Paramètres

Tableau 39

Paramètre

Type / exigence

Description

name

string / requis

1..32 caractères suivant les règles des noms de fichiers.

options.key

string / "id"

Nom d’un champ de premier niveau de l’objet. 1..32 caractères ASCII : d’abord une lettre ou _, puis également des chiffres. Chaque enregistrement doit contenir ce champ sous forme de chaîne non vide.

Résultat

Promise<RecordStore> avec les propriétés name et key et les méthodes put/get/delete/list/stat/compact/close.

Erreurs et considérations particulières

SCHEMA_MISMATCH pour un champ clé différent dans une base existante ; ALREADY_OPEN ; QUOTA_EXCEEDED ; NO_SPACE ; CORRUPT ; CANCELLED ; OUT_OF_MEMORY. Au maximum 8 bases persistantes et 2 ouvertes simultanément. Un dernier enregistrement incomplet est retiré à l’ouverture ; un défaut d’intégrité dans un enregistrement complet rejette l’ouverture au lieu de supprimer silencieusement les données.

Exemple

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

records.put(record)

Disponible depuis : Neutron AppEngine 1.0.0
await articles.put({ code: "ART-001", name: "Flour", target: 25 });
Objectif. Insérer un objet ou remplacer entièrement l’enregistrement possédant la même clé.
Description. put remplace l’objet entier, pas les champs individuels. Les données sont ajoutées au journal et l’enregistrement validé actualise l’index. Les clés sont sensibles à la casse. Plusieurs appels put séquentiels ne constituent pas une seule transaction.

Paramètres

Tableau 40

Paramètre

Type / exigence

Description

record

object / requis

Objet sérialisable en JSON, au maximum 2048 octets UTF-8 après JSON.stringify et au maximum 16 niveaux imbriqués d’objets/tableaux. Le champ clé doit être une chaîne de 1..64 octets UTF-8 sans caractères de contrôle. Convertissez explicitement les ID numériques avec String.

Résultat

Promise<object> contenant l’objet JSON stocké.

Erreurs et considérations particulières

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, QUOTA_EXCEEDED, NO_SPACE, WRITE_FAILED, CLOSED, CORRUPT. Les références BigInt et circulaires ne peuvent pas être sérialisées en tant que JSON. Un échec de validation peut laisser le résultat de l’écriture incertain ; rouvrez et vérifiez get avant de réessayer. N'enregistrez pas chaque impulsion sans limites.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const article = await articles.get("ART-001");
Objectif. Récupérer rapidement le dernier enregistrement validé par sa clé unique.
Description. Utilise un index trié : la recherche de clé nécessite un nombre logarithmique de comparaisons et la lecture de l’enregistrement sélectionné. Ne parcourt pas tous les objets. Renvoie un nouvel objet ; le modifier en JavaScript ne modifie pas à lui seul la base.

Paramètres

Tableau 41

Paramètre

Type / exigence

Description

key

string / requis

Clé exacte, 1..64 octets UTF-8, sans caractères de contrôle.

Résultat

Promise<object|null>. null signifie que la clé est absente.

Erreurs et considérations particulières

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT. Les autres champs ne sont pas indexés. Ne traitez pas les ID de chaîne comme des nombres : "001" et "1" sont des clés distinctes.

Exemple

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)

Disponible depuis : Neutron AppEngine 1.0.0
const deleted = await articles.delete("ART-001");
Objectif. Retirer un enregistrement de la liste active de la base.
Description. Ajoute normalement un enregistrement de suppression validé ; les anciennes données peuvent subsister jusqu’à la compaction. La suppression n’est pas un effacement sécurisé du support physique. La suppression d’une clé absente est autorisée.

Paramètres

Tableau 42

Paramètre

Type / exigence

Description

key

string / requis

Clé suivant les mêmes règles que get.

Résultat

Promise<boolean> : true si l’enregistrement existait, sinon false.

Erreurs et considérations particulières

INVALID_ARGUMENT, CLOSED, NO_SPACE, WRITE_FAILED, CORRUPT. À la limite du journal, la suppression peut déclencher un compactage nécessitant un espace temporaire.

Exemple

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

records.list(options?)

Disponible depuis : Neutron AppEngine 1.0.0
const page = await articles.list({ cursor: null, limit: 16 });
Objectif. Lire les enregistrements actifs dans l’ordre des clés, page par page.
Description. Les enregistrements suivent l’ordre des octets des clés. cursor exclut la dernière clé de la page précédente. Les limites de taille de réponse peuvent réduire une page sous limit. Pour les champs non indexés, parcourez les pages et filtrez en JavaScript ; ce n’est pas une recherche indexée rapide.

Paramètres

Tableau 43

Paramètre

Type / exigence

Description

options.cursor

string | null / omis

nextCursor renvoyé par la page précédente.

options.limit

integer / 16

1..32 enregistrements, également limités par les tailles des objets et de la réponse.

Résultat

{records:object[], nextCursor:string|null}. null marque la fin. Changer la base de données entre les pages signifie que les résultats ne sont pas un instantané immuable.

Erreurs et considérations particulières

INVALID_ARGUMENT, CLOSED, READ_FAILED, CORRUPT, OUT_OF_MEMORY. Évitez d'accumuler chaque page dans un grand tableau lorsqu'un seul résultat est nécessaire.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const status = await articles.stat();
Objectif. Lire le nombre d’enregistrements actifs, la taille du journal et le champ clé.
Description. La taille du journal inclut les enregistrements remplacés et les suppressions, pas seulement les objets actuellement actifs.

Paramètres

Aucun paramètre.

Résultat

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

Erreurs et considérations particulières

CLOSED ou CORRUPT. Au plus 2048 enregistrements actifs par base de données ; les limites de taille et les quotas partagés peuvent réduire le nombre réalisable.

Exemple

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

records.compact()

Disponible depuis : Neutron AppEngine 1.0.0
await articles.compact();
Objectif. Retirer du journal les anciennes versions et les suppressions pour récupérer de l’espace.
Description. Copie uniquement les enregistrements actifs dans un fichier temporaire, le valide et confirme son écriture, puis remplace l’ancienne base. Une interruption conserve soit l’ancienne base validée, soit la nouvelle. put ou delete peuvent aussi déclencher une compaction lorsque le journal atteint 262144 octets.

Paramètres

Aucun paramètre.

Résultat

Promise<undefined>. Les clés et valeurs actives restent inchangées.

Erreurs et considérations particulières

NO_SPACE pour la copie temporaire, WRITE_FAILED, READ_FAILED, CANCELLED, CORRUPT, OUT_OF_MEMORY. Peut prendre plus de temps et occuper la file du service de stockage ; ne l’exécutez pas après chaque mesure. Après QUOTA_EXCEEDED du quota partagé, une compaction explicite peut retirer les contenus obsolètes avant de réessayer une écriture.

Exemple

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

records.close()

Disponible depuis : Neutron AppEngine 1.0.0
await articles.close();
Objectif. Libérer l’objet ouvert et l’index tout en conservant les données.
Description. Les méthodes suivantes de l’objet renvoient CLOSED. Répéter close est sans effet nuisible. Rouvrez avec le même nom de base et le même champ clé si nécessaire. L’arrêt de l’application libère automatiquement ses objets ouverts.

Paramètres

Aucun paramètre.

Résultat

Promise<undefined>.

Erreurs et considérations particulières

BUSY si la file d'attente est pleine. Les opérations mises en file d'attente avant la fermeture peuvent se terminer en premier ; l'utilisation d'un objet fermé est rejetée.

Exemple

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

storage.removeRecords(name)

Disponible depuis : Neutron AppEngine 1.0.0
const removed = await storage.removeRecords("articles");
Objectif. Supprimer une base locale entière et son schéma.
Description. La base doit être fermée. Trouvez les noms dans storage.info().databases. Après suppression, le même nom peut être créé avec un autre champ clé.

Paramètres

Tableau 44

Paramètre

Type / exigence

Description

name

string / requis

Nom de la base, 1..32 caractères.

Résultat

Promise<boolean> : true s'il existait, sinon false.

Erreurs et considérations particulières

RESOURCE_IN_USE pour une base de données ouverte, INVALID_ARGUMENT, WRITE_FAILED. La suppression de l'intégralité de la base de données ne peut pas être annulée.

Exemple

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

Exemple complet de base locale de produits

// 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 de persistance et de récupération

Tableau 45

Test

Résultat attendu

Exécuter put deux fois avec le même code

get renvoie la dernière version complète ; le nombre d’enregistrements n’augmente pas.

Stop, nouveau Run ou redémarrage normal

Le même nom et la même clé ouvrent les données stockées ; l’index est reconstruit.

Coupure d’alimentation pendant l’ajout

Les enregistrements entièrement validés subsistent ; un dernier enregistrement incomplet est écarté à l’ouverture. Le résultat de la dernière opération non confirmée peut être incertain.

Défaut d’intégrité dans un enregistrement complet

CORRUPT ; la base entière n’est pas supprimée automatiquement.

Exécuter compact et rouvrir

Les enregistrements actifs restent inchangés ; le journal diminue si d’anciennes versions existaient.

Quota atteint

QUOTA_EXCEEDED ou NO_SPACE sans croissance illimitée des données.

Factory default

Les fichiers utilisateur et les bases sont supprimés.

Accéder à un objet fermé ou issu d’une exécution précédente

CLOSED ou rejet d’une requête périmée.

12. Modules de communication

Les modules de communication sont distincts de l’environnement d’exécution, du module de pesage et de la gestion de l’application. Chacun possède ses propres exigences, fonctions, événements, erreurs et limites. Les applications sans module de communication peuvent utiliser normalement l’environnement d’exécution, les diagnostics, les temporisateurs et la balance.

Tableau 46

Module

Prise en charge dans Neutron AppEngine 1.0.0

Chapitre

TCP

Implémenté ; features.tcp=true

RS-232 / RS-485

Implémenté ; features.serial=true

MQTT

Implémenté ; features.mqtt=true

HTTP / REST

Implémenté ; features.http=true

WebSocket

Implémenté ; features.websocket=true

Téléverser une application via MQTT, HTTP ou BLE est une opération de gestion. Cela n’active pas ce protocole dans le code utilisateur. Consultez Installation et Protocole APP pour les procédures de gestion.

13. Communication TCP

configuredMode : 0 disabled, 1 server, 2 client, 3 both. La valeur d’exemple 1 est illustrative. maxLineBytes est la limite maximale configurable ; le parseur utilise 1024 octets par défaut.

Le module TCP configure le serveur et le client existants, réserve leurs flux pour un protocole personnalisé, envoie des données et signale les événements de connexion. Modes : disabled, server, client, both. En mode both, il existe un serveur avec un pair actif et une connexion client sortante. L’API n’ouvre pas un nombre arbitraire de sockets et ne prend en charge ni TLS ni les noms DNS ; client.host doit être une adresse IPv4. Toutes les fonctions et tous les événements de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0.

Avant la configuration réseau ou la réservation, désactivez le protocole de pesage système sur I_TCP ainsi que les ponts TCP–MQTT et TCP–RS-232/RS-485 ; sinon RESOURCE_IN_USE. La configuration réseau et la réservation sont distinctes : configure enregistre et applique les paramètres ; claim redirige les données vers l’application. Après la réussite de configure, utilisez await tcp.claim().

13.1 tcp.configure()

Disponible depuis : Neutron AppEngine 1.0.0
const status = await tcp.configure(options);
Objectif. Configurer les rôles TCP, les paramètres réseau et la délimitation des lignes de texte.
Description. Les champs omis restent inchangés. Les paramètres réseau sont enregistrés de façon persistante via les attributs existants du module et s’appliquent sans redémarrer l’appareil. Un rôle modifié est réinitialisé tandis que l’autre conserve sa connexion. Des valeurs identiques n’interrompent pas les connexions saines. Les changements de exclusive affectent les nouvelles connexions sans déconnecter le pair actuel. La Promise confirme l’application des paramètres, pas la connexion à un système distant. Sans réseau, les paramètres restent enregistrés et le rôle reste en waitingNetwork. Surveillez state/status pour les échecs de connexion. Les paramètres locaux de lignes s’appliquent après réussite et abandonnent les lignes partielles. Fournir uniquement delimiter/maxLineBytes les applique immédiatement pour compatibilité, mais renvoie toujours une Promise.

Paramètres

Tableau 47

Paramètre

Type / exigence

Description

options

object / requis

Objet avec champs facultatifs ; les champs inconnus sont rejetés.

options.mode

string / facultatif

disabled, server, client ou both. CTY : 0, 1, 2, 3. Disabled arrête les deux rôles et libère la propriété.

options.server

object / facultatif

Configuration serveur : port et exclusive.

options.server.port

integer / facultatif

1–65535 ; attribut existant S0C. S0P configure un port série, pas TCP.

options.server.exclusive

boolean / facultatif

S0M : true=1, false=0. True rejette les nouveaux pairs tant que le pair actuel est connecté ; false autorise son remplacement par un nouveau pair.

options.client

object / facultatif

Configuration de la connexion sortante : host et port.

options.client.host

string / facultatif

Adresse IPv4 du serveur distant, par exemple 192.168.50.100. Attribut SIP ; aucun zéro initial dans les octets. 0.0.0.0 et 255.255.255.255 sont interdits.

options.client.port

integer / facultatif

1–65535 ; attribut SPO.

options.delimiter

string / valeur par défaut CRLF

1–8 octets ASCII. S’applique uniquement au parseur de l’application actuelle ; non enregistré dans les attributs.

options.maxLineBytes

integer / valeur par défaut 1024

1–4096 octets de contenu hors délimiteur. Application actuelle uniquement.

Résultat

Promise< object> avec un instantané de tcp.status(). Les paramètres du rôle actif doivent être complets même en ne changeant qu’une partie de l’objet. Une mise à jour partielle suffit avec une configuration valide existante. Les changements SMD via BLE, MQTT, HTTP ou device.settings.write utilisent le même mécanisme d’application.

Erreurs et considérations particulières

INVALID_ARGUMENT pour des paramètres actifs invalides ou incomplets ; la validation des arguments JavaScript lève une exception synchrone. Les requêtes réseau peuvent être rejetées avec RESOURCE_IN_USE, BUSY, WRITE_FAILED, CONFIGURE_FAILED ou OUT_OF_MEMORY. Certains paramètres peuvent déjà être enregistrés après un échec d’écriture ; les échecs de démarrage du serveur conservent les paramètres et réessaient le démarrage. Vérifiez status et corrigez la cause. CONFIG_CHANGED interrompt les écritures en attente du rôle modifié. Une ligne trop volumineuse génère MESSAGE_TOO_LARGE avant le callback line et arrête l’application ; try/catch dans ce callback ne peut pas l’intercepter.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const result = await tcp.claim();
Objectif. Réserver le canal TCP existant pour un protocole personnalisé.
Description. Demande le transfert des flux TCP existants vers l’application utilisateur. Enregistrez les callbacks avant la réservation. L’opération ne garantit pas qu’un pair distant soit connecté.

Paramètres

Aucun paramètre.

Résultat

Promise<string>, "claimed" en cas de réussite. Les événements data et l’envoi deviennent disponibles une fois connecté. Les événements diagnostiques connection/state sont disponibles sans réservation ; enregistrez les écouteurs avant configure/claim.

Erreurs et considérations particulières

NOT_CONFIGURED pour un mode TCP désactivé/invalide, RESOURCE_IN_USE pour les conflits de protocole système ou de pont ; également BUSY et OUT_OF_MEMORY.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const result = await tcp.release();
Objectif. Rendre au firmware l’interface TCP réservée.
Description. Ferme les connexions serveur/client réservées, libère la propriété et abandonne les lignes partielles. Les écouteurs et temporisateurs JavaScript restent. Le service configuré reste disponible ; le client système peut se reconnecter.

Paramètres

Aucun paramètre.

Résultat

Promise<string>, "released" en cas de réussite. L’application continue de fonctionner.

Erreurs et considérations particulières

Erreurs partagées BUSY et OUT_OF_MEMORY. Annulez les temporisateurs d’envoi et gérez les écritures en attente avant la libération.

Exemple

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

13.4 tcp.write()

Disponible depuis : Neutron AppEngine 1.0.0
const bytesWritten = await tcp.write(data, { connectionId });
Objectif. Envoyer du texte ou des données binaires sur une connexion réservée.
Description. Encode les chaînes en UTF-8 et envoie Uint8Array sous forme d’octets. N’ajoute ni CRLF ni autre délimiteur. L’envoi est asynchrone ; les écritures soumises sur une connexion conservent leur ordre, mais la logique utilisateur asynchrone peut changer l’ordre de soumission.

Paramètres

Tableau 48

Paramètre

Type / exigence

Description

data

string ou Uint8Array / requis

Au maximum 4096 octets par appel. Les limites des chaînes s’appliquent après encodage UTF-8.

options

object / facultatif, valeur par défaut {}

Options d’envoi.

options.connectionId

integer / facultatif

0 ou omis : sélectionne le seul rôle TCP connecté. Avec plusieurs rôles connectés, utilisez l’ID de l’événement ; plage 0–4 294 967 295.

Résultat

Promise<number> avec les octets acceptés pour la transmission TCP. Ne confirme ni la réception ni le traitement à distance. Définissez des accusés de réception dans votre protocole si nécessaire.

Erreurs et considérations particulières

Rejette avec INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, NOT_CONNECTED, CONFIG_CHANGED, BUSY, OUT_OF_MEMORY ou TIMEOUT. La limite d’attente d’écriture est d’environ 3 s. Des données peuvent déjà avoir été envoyées après une erreur ; ne réessayez pas aveuglément les commandes non idempotentes. Une erreur/un délai dépassé d’écriture active peut fermer la connexion. Un usage incorrect des arguments JavaScript peut aussi lever TypeError.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
tcp.on(eventName, callback);
Objectif. Enregistrer un écouteur d’événements TCP.
Description. Appelle le callback pour les événements correspondants jusqu’à off ou l’arrêt de l’application. La même fonction peut s’inscrire plusieurs fois ; chaque inscription compte dans la limite.

Paramètres

Tableau 49

Paramètre

Type / exigence

Description

eventName

string / requis

Uniquement "data", "line", "connection" ou "state".

callback

function / requis

Fonction recevant un objet événement. Conservez la même référence pour off.

Résultat

L’objet tcp, permettant de chaîner les inscriptions.

Erreurs et considérations particulières

INVALID_ARGUMENT synchrone pour un événement inconnu ou une valeur non fonction. Au maximum 32 écouteurs on/once cumulés ; le dépassement génère QUOTA_EXCEEDED. Une exception de callback ou un rejet de Promise non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

13.6 tcp.once()

Disponible depuis : Neutron AppEngine 1.0.0
tcp.once(eventName, callback);
Objectif. Enregistrer un écouteur à usage unique.
Description. Retire l’écouteur avant de l’appeler pour le premier événement correspondant. Reste inscrit si aucun événement n’arrive.

Paramètres

Tableau 50

Paramètre

Type / exigence

Description

eventName

string / requis

Uniquement "data", "line", "connection" ou "state".

callback

function / requis

Fonction recevant un objet événement. Conservez la même référence pour off.

Résultat

L’objet tcp, permettant de chaîner les inscriptions.

Erreurs et considérations particulières

INVALID_ARGUMENT synchrone pour un événement inconnu ou une valeur non fonction. Au maximum 32 écouteurs on/once cumulés ; le dépassement génère QUOTA_EXCEEDED. Une exception de callback ou un rejet de Promise non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

13.7 tcp.off()

Disponible depuis : Neutron AppEngine 1.0.0
tcp.off(eventName, callback);
Objectif. Retirer un écouteur.
Description. Supprime toutes les inscriptions de la même référence de callback pour l’événement sélectionné. N’interrompt pas un callback async déjà commencé. Ne transmettez pas une nouvelle fonction anonyme pour retirer un écouteur existant.

Paramètres

Tableau 51

Paramètre

Type / exigence

Description

eventName

string / requis

Uniquement "data", "line", "connection" ou "state".

callback

function / requis

Fonction recevant un objet événement. Conservez la même référence pour off.

Résultat

L’objet tcp, permettant de chaîner les inscriptions.

Erreurs et considérations particulières

INVALID_ARGUMENT synchrone pour un événement inconnu ou une valeur non fonction. Au maximum 32 écouteurs on/once cumulés ; le dépassement génère QUOTA_EXCEEDED. Une exception de callback ou un rejet de Promise non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

13.8 Structure des événements TCP

Tableau 52

Événement

Champs

Signification

data

{ connectionId, data: Uint8Array }

Bloc du flux TCP brut. Un événement ne correspond pas nécessairement à une commande ou à un paquet réseau.

line

{ connectionId, line: string }

Ligne complète décodée en UTF-8 sans délimiteur. Les lignes vides sont autorisées ; les espaces ne sont pas supprimés automatiquement.

connection

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

Connexion établie ou perdue pendant l’exécution de l’application, indépendamment pour chaque rôle. connectionId identifie la session ; utilisez un nouvel ID après reconnexion.

connection.reason : CONNECTED en cas de réussite, CONFIG_CHANGED après un changement d’adresse/port/rôle, REPLACED lorsqu’un pair du serveur est remplacé, NETWORK_DOWN en cas de perte du service réseau, CONNECTION_LOST en cas de perte de connexion détectée, DISCONNECTED pour une fermeture normale, APP_STOPPED pour une libération après l’arrêt de l’application, RESOURCE_IN_USE pour les conflits. Les événements après l’arrêt de l’application ne sont pas transmis. timeMs est le temps monotone de l’appareil en millisecondes, pas une date ni une durée de connexion. Le port distant d’un pair du serveur est généralement éphémère, et non le port d’écoute du serveur.

state contient role, state, connected, connectionId, port, revision, error et timeMs, ainsi que les propriétés de rôle de tcp.status(). États serveur : disabled, waitingNetwork, listening, error. États client : disabled, waitingNetwork, connecting, reconnecting, connected, error. Une libération due à un conflit peut émettre {role:"all",state:"released",reason:"RESOURCE_IN_USE"}. Les tentatives de connexion du client ne bloquent ni l’application ni les mesures ; chacune dure jusqu’à environ 3 s, la suivante commençant environ 5 s après un échec ou une déconnexion détectée. Un échec de démarrage du serveur est réessayé environ toutes les 5 s. La détection d’une déconnexion physique n’est pas immédiate ; elle dépend du trafic et de la surveillance de connexion.

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);
});
L’inscription ne rejoue pas l’historique des événements. La réservation peut notifier une connexion déjà établie. Répondez toujours avec event.connectionId ; ne le stockez jamais de façon persistante et n’inventez pas d’ID.
TCP est un flux. WEIGHT?\r\n peut arriver en plusieurs blocs, et plusieurs commandes dans un seul bloc. Le parseur conserve les lignes partielles par connexion, assemblant les caractères UTF-8 partiels avant de décoder les événements line. Les délimiteurs et les lignes incomplètes sont abandonnés à la déconnexion.

Avec un écouteur line, les lignes sont d’abord préparées depuis un bloc de flux, puis data est émis, suivi des callbacks line individuels. Enregistrer les deux donne deux vues des mêmes données ; ne traitez pas les commandes deux fois. Sans écouteur line, les données binaires ne sont pas accumulées dans un tampon de lignes. Les protocoles binaires doivent implémenter leurs propres limites de longueur et assemblage des messages.

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 Erreurs du module TCP

Tableau 53

Code

Signification pour TCP

NOT_CONFIGURED

TCP n’est pas configuré pour le fonctionnement client/serveur.

RESOURCE_IN_USE

Le protocole de pesage TCP système ou un pont entre en conflit avec la réservation.

NOT_OWNER

L’application ne possède pas TCP ou un conflit de routage est survenu.

NOT_CONNECTED

La session TCP demandée n’est plus connectée.

MESSAGE_TOO_LARGE

L’écriture dépasse 4096 octets ou la ligne reçue est trop longue. Une erreur interne de ligne arrête l’application.

13.10 Limites du module TCP

Tableau 54

Ressource

Limite

Message TCP

Au maximum 4096 octets par écriture ; les flux reçus peuvent être divisés en blocs plus petits.

Lignes

Valeur par défaut 1024 ; configurable de 1–4096 octets hors délimiteur ; longueur du délimiteur ASCII de 1–8 octets.

Écouteurs

Au maximum 32 inscriptions on/once cumulées pour data, line, connection et state.

13.11 Protocole TCP personnalisé avec CONT / CCONT

Exemple autonome pour un serveur ou client TCP configuré sans routage système en conflit. Chaque ligne se termine par de véritables octets CR LF. Les outils externes doivent envoyer ces octets, et non quatre caractères littéraux antislash-r-antislash-n. Dans le source JavaScript, "\r\n" représente les bons octets de terminaison.

Tableau 55

Commande reçue + CRLF

Réponse + CRLF

WEIGHT?

net,gross,unit ou ERR,NO_MEASUREMENT

CONT

OK ; puis une mesure par seconde pour la même connexion. Répéter ne crée pas d’intervalle supplémentaire.

CCONT

OK ; annule les futurs envois périodiques sur cette connexion. Une écriture déjà commencée peut se terminer.

TARE / ZERO / CLEAR_TARE

OK après une opération confirmée ou ERR,&lt;code&gt;.

PRESET_TARE 2.5

Définit la tare dans l’unité actuellement configurée ; renvoie OK ou ERR,&lt;code&gt;.

Autre commande

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

L’écouteur de connexion supprime l’intervalle à la déconnexion ; un échec d’écriture périodique l’arrête également. Un indicateur d’envoi empêche les écritures périodiques de se chevaucher par connexion. L’exemple n’implémente ni journal persistant, ni accusé de traitement distant, ni ID de requêtes. Ajoutez des ID, des réponses et des règles de nouvelle tentative bornés si nécessaire.

13.12 Fermeture TCP et concurrence

app.stop() ferme les connexions TCP réservées et libère la propriété. Le serveur configuré reste disponible et le client peut se reconnecter selon la logique système. Utilisez tcp.release() pour rendre TCP sans arrêter l’application. Plusieurs commandes reçues peuvent entraîner des traitements asynchrones simultanés ; pour un ordre strict, faites attendre une réponse au client ou implémentez une file bornée. clearInterval n’annule pas une écriture déjà commencée.

13.13 Test d’une application TCP

Tableau 56

Test

Résultat attendu

Commande TCP répartie sur plusieurs réceptions

Le callback line se déclenche uniquement après le délimiteur complet.

CONT deux fois, puis CCONT deux fois

Un intervalle par connexion ; une annulation répétée est sans effet nuisible.

Déconnexion/reconnexion

Les anciens intervalles et ID ne sont pas réutilisés ; la nouvelle session est indépendante.

Écriture TCP lente/échouée

Aucun travail périodique superposé ni file illimitée.

13.14 tcp.status()

Disponible depuis : Neutron AppEngine 1.0.0
const status = tcp.status();
Objectif. Lire la configuration et l’état actuels des deux rôles TCP.
Description. Instantané synchrone du dernier cycle de service. N’ouvre aucune connexion, ne réserve aucune interface et ne lit aucune donnée de flux. pending signifie que les paramètres enregistrés attendent d’être appliqués au prochain cycle de service. L’état de connexion continue de changer après configure ; utilisez les événements connection/state pour poursuivre une fois connecté.

Paramètres

Aucun paramètre.

Résultat

Objet : mode (disabled/server/client/both), configuredMode (0/1/2/3), claimed, pending, server et client. Les deux rôles contiennent state, connected, connectionId (0 si déconnecté), port, revision et error. server inclut aussi listening, exclusive, remoteAddress et remotePort ; client inclut host, remoteAddress et remotePort. error vide signifie aucune erreur enregistrée. revision change avec les changements de point de terminaison/rôle ; ce n’est pas un compteur de données reçues. Cet instantané informatif peut changer immédiatement après lecture.

Erreurs et considérations particulières

Aucune demande de réseau. Un instantané connecté ne garantit pas qu’une écriture ultérieure réussira ; gérez toujours le rejet d'écriture.

Exemple

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

Exemple de configuration et de protocole WEIGHT? de base pour les deux rôles : choisissez le mode souhaité dans la configuration et adaptez l’adresse/le port. Les réponses utilisent le connectionId de l’événement reçu ; elles fonctionnent donc avec les deux rôles connectés.

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

Un port est disponible pour l’application uniquement lorsque sa fonction système est Disabled : S0E=0 pour RS-232 ou S1E=0 pour RS-485. Il ne doit pas être affecté à un protocole de pesage système, Modbus, une sortie de débogage ou un transfert. claim() ne désactive pas automatiquement ces fonctions.

Le module série fournit deux objets indépendants : serial.rs232 et serial.rs485, avec la même API. Une application peut réserver l’un ou les deux ports. Aucun autre module de communication n’est requis. Toutes les fonctions et tous les événements de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0.

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

14.1 port.claim()

Disponible depuis : Neutron AppEngine 1.0.0
const result = await port.claim();
Objectif. Réserver exclusivement le port série sélectionné.
Description. Vérifie que le port est Disabled et libre, puis le prépare avec les paramètres physiques stockés. Attend une initialisation réussie. Répéter une réservation réussie est autorisé sans réinitialiser les paramètres inchangés.

Paramètres

Aucun paramètre.

Résultat

Promise< string>, "claimed" en cas de réussite. Enregistrez les écouteurs avant la réservation si nécessaire. La présence de l’appareil distant n’est pas vérifiée.

Erreurs et considérations particulières

RESOURCE_IN_USE pour une fonction système activée ou un autre conflit ; BUSY pour des opérations de contrôle concurrentes ; RECONFIGURE_FAILED, TIMEOUT ou OUT_OF_MEMORY. Un port mal configuré n’est pas réservé silencieusement.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const result = await port.configure(options);
Objectif. Configurer le débit, le format des caractères et l’analyse locale des messages.
Description. Asynchrone, autorisé après claim(). Associe les paramètres physiques aux paramètres SMD existants, les valide et les enregistre de façon persistante. Réinitialise le port une fois pour la requête entière ; la Promise est résolue après application. Les paramètres omis restent inchangés. Réappliquer des valeurs identiques déjà appliquées avec succès évite une réinitialisation inutile.

Paramètres

Tableau 57

Paramètre

Type / exigence

Description

options

object / requis

Objet avec les champs facultatifs ci-dessous. Les champs inconnus sont rejetés.

baudRate

integer / facultatif

300–1 000 000 bit/s. Correspond à S0B ou S1B.

dataBits

integer / facultatif

7 ou 8. Correspondance S0I/S1I : 0 signifie 7 bits, 1 signifie 8 bits.

stopBits

integer / facultatif

1 ou 2. Correspond à S0S/S1S.

parity

string / facultatif

"none", "even" ou "odd". Correspondance S0P/S1P : 0, 1 ou 2.

delimiter

string / facultatif, valeur par défaut CRLF

1–8 caractères ASCII, uniquement pour assembler les événements line dans l’application actuelle.

maxLineBytes

integer / facultatif, valeur par défaut 1024

1–4096 octets de contenu de ligne hors délimiteur. Application actuelle uniquement.

Résultat

Promise< string>, "configured" en cas de réussite. Les paramètres physiques persistent après release(), Stop et redémarrage. Delimiter et maxLineBytes ne sont pas enregistrés dans SMD ; ils s’appliquent au parseur JavaScript actuel.

Erreurs et considérations particulières

INVALID_ARGUMENT, NOT_OWNER, RESOURCE_IN_USE, BUSY, SETTINGS_FAILED, RECONFIGURE_FAILED, CONFIG_CHANGED, TIMEOUT ou OUT_OF_MEMORY. Un échec d’enregistrement peut laisser certains paramètres physiques enregistrés ; un échec d’application ne signifie pas que les paramètres n’ont pas été enregistrés. Corrigez la cause et réessayez la configuration/réservation. La configuration du parseur local ne change qu’après réussite. Si un autre canal change les paramètres physiques demandés avant confirmation, l’appel est rejeté avec CONFIG_CHANGED.

Exemple

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 Modifications des paramètres sans redémarrage

Le même chemin d’application traite les requêtes SMD de tous les canaux de gestion. Modifier le débit, les bits de données, les bits d’arrêt, la parité ou la fonction du port ne nécessite pas de redémarrage de Neutron. Les terminateurs système, les paramètres d’ajout de terminateur, l’adresse RS-485 et les affectations de ports associées sont également actualisés. L’autre port est réinitialisé uniquement s’il est affecté.

Pendant la transition, les nouvelles écritures sont temporairement rejetées ou retenues. Les octets précédemment soumis sont transmis dans un délai borné ; les trames reçues incomplètes sont abandonnées. Les anciennes requêtes de pesage, la sortie système continue et les sessions du port affecté se terminent. Un changement de débit ou de format peut perdre des données ; effectuez-le donc pendant une interruption de communication convenue. L’impossibilité de terminer la transmission ou d’ouvrir la nouvelle configuration signale RECONFIGURE_FAILED.

Si un SMD externe affecte une autre fonction système ou provoque un conflit pendant que JavaScript possède le port, la réservation est révoquée. L’application reçoit state avec reason="RESOURCE_IN_USE" et claimed=false ; les nouvelles écritures renvoient NOT_OWNER. Les changements de paramètres physiques autorisés conservent la propriété et émettent RECONFIGURED. Les lignes JavaScript partielles sont abandonnées ; le délimiteur JavaScript configuré reste.

Tableau 58

Vérification via RMD

Signification

S0APPLY / S1APPLY

PENDING : en attente d’application ; OK : configuration appliquée ; ERROR : échec de l’application.

S0JS / S1JS

1 signifie réservé par l’application ; 0 signifie aucune réservation JavaScript.

S0REV / S1REV

Compteur des changements d’état de port appliqués ; ce n’est pas un ID de session persistant.

S0STATE / S1STATE

Dernier état : READY, DISABLED, CLAIMED, RECONFIGURED, RELEASED, RESOURCE_IN_USE ou RECONFIGURE_FAILED.

Une réponse SMD normale confirme l’enregistrement ; l’application physique suit au prochain cycle de traitement de l’appareil. Pour une confirmation externe, utilisez les champs RMD APPLY ou les journaux de débogage. port.configure() attend déjà l’application. Ces champs RMD sont diagnostiques, et non des paramètres SMD modifiables. Répéter un SMD identique après un échec réessaie l’application ; après réussite, des valeurs identiques ne rouvrent pas le port.

14.4 port.write()

Disponible depuis : Neutron AppEngine 1.0.0
const bytes = await port.write(data, { timeoutMs });
Objectif. Envoyer de façon asynchrone du texte ou des octets binaires.
Description. Encode les chaînes en UTF-8 ; envoie Uint8Array sans modification. N’ajoute ni terminateur, ni adresse RS-485, ni somme de contrôle. Les écritures sur un port suivent l’ordre des requêtes ; leurs Promise ne confirment pas le traitement distant.

Paramètres

Tableau 59

Paramètre

Type / exigence

Description

data

string ou Uint8Array / requis

Au maximum 4096 octets après encodage UTF-8 ; les écritures vides sont autorisées.

options

object / facultatif, valeur par défaut {}

Options d’attente.

options.timeoutMs

integer / facultatif

1–180000 ms. La valeur par défaut est calculée à partir de la longueur et du débit, avec une marge et un minimum de 3 s.

Résultat

Promise< number> avec les octets acceptés pour la transmission. Utilisez drain() pour attendre la fin de la transmission physique.

Erreurs et considérations particulières

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT ou OUT_OF_MEMORY. Certains octets peuvent déjà être envoyés après une interruption ou un délai d'attente. CONFIG_CHANGED signifie que la configuration a été modifiée en attendant ; Les octets restants de l'ancienne demande ne sont pas envoyés sous les nouveaux paramètres.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
await port.drain({ timeoutMs });
Objectif. Attendre la fin de la transmission physique.
Description. Attend après les écritures précédentes sur le même port, puis vérifie que les octets en attente ont été transmis. L’environnement d’exécution traite d’autres événements pendant l’attente.

Paramètres

Tableau 60

Paramètre

Type / exigence

Description

options

object / facultatif, valeur par défaut {}

Options d’attente.

options.timeoutMs

integer / facultatif, valeur par défaut 6000

1–60000 ms.

Résultat

Promise< undefined>. N'attend pas de réponse à distance et ne confirme pas qu'un bus RS-485 utilisé par d'autres appareils est libre.

Erreurs et considérations particulières

INVALID_ARGUMENT, NOT_OWNER, BUSY, PORT_UNAVAILABLE, CONFIG_CHANGED, TIMEOUT ou OUT_OF_MEMORY. Définissez un délai de communication adapté ; son expiration n’annule pas les octets transmis.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const result = await port.release();
Objectif. Libérer la réservation du port sélectionné par l’application.
Description. Arrête les nouvelles écritures de l’application, termine la transition et libère la propriété. Un port toujours Disabled côté système et sans autre utilisation se ferme. Les paramètres physiques enregistrés de façon persistante restent. Ne désactive pas une fonction système ayant entre-temps pris le contrôle du port.

Paramètres

Aucun paramètre.

Résultat

Promise< string>, "released" en cas de réussite. La répétition est autorisée. La réception locale partielle est abandonnée ; les callbacks inscrits et les temporisateurs restent.

Erreurs et considérations particulières

BUSY, RECONFIGURE_FAILED, TIMEOUT ou OUT_OF_MEMORY. Annulez les temporisateurs d’envoi avant la libération. Les octets déjà transmis ne peuvent pas être retirés. Stop de l’application libère automatiquement ses deux ports.

Exemple

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

14.7 port.on()

Disponible depuis : Neutron AppEngine 1.0.0
port.on(eventName, callback);
Objectif. Enregistrer un écouteur d’événements série.
Description. Les événements appartiennent au port sélectionné. once retire l’inscription avant d’appeler le callback. off exige la même référence de fonction et n’interrompt pas un callback async déjà commencé.

Paramètres

Tableau 61

Paramètre

Type / exigence

Description

eventName

string / requis

"data", "line" ou "state".

callback

function / requis

Fonction recevant un objet événement.

Résultat

L’objet du port sélectionné ; l’inscription des écouteurs peut être chaînée.

Erreurs et considérations particulières

INVALID_ARGUMENT pour un événement ou callback invalide ; QUOTA_EXCEEDED au-delà de 32 écouteurs par port. Les exceptions ou rejets de callback non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

14.8 port.once()

Disponible depuis : Neutron AppEngine 1.0.0
port.once(eventName, callback);
Objectif. Écouter uniquement le premier événement correspondant.
Description. Les événements appartiennent au port sélectionné. once retire l’inscription avant d’appeler le callback. off exige la même référence de fonction et n’interrompt pas un callback async déjà commencé.

Paramètres

Tableau 62

Paramètre

Type / exigence

Description

eventName

string / requis

"data", "line" ou "state".

callback

function / requis

Fonction recevant un objet événement.

Résultat

L’objet du port sélectionné ; l’inscription des écouteurs peut être chaînée.

Erreurs et considérations particulières

INVALID_ARGUMENT pour un événement ou callback invalide ; QUOTA_EXCEEDED au-delà de 32 écouteurs par port. Les exceptions ou rejets de callback non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

14.9 port.off()

Disponible depuis : Neutron AppEngine 1.0.0
port.off(eventName, callback);
Objectif. Retirer un écouteur.
Description. Les événements appartiennent au port sélectionné. once retire l’inscription avant d’appeler le callback. off exige la même référence de fonction et n’interrompt pas un callback async déjà commencé.

Paramètres

Tableau 63

Paramètre

Type / exigence

Description

eventName

string / requis

"data", "line" ou "state".

callback

function / requis

Fonction recevant un objet événement.

Résultat

L’objet du port sélectionné ; l’inscription des écouteurs peut être chaînée.

Erreurs et considérations particulières

INVALID_ARGUMENT pour un événement ou callback invalide ; QUOTA_EXCEEDED au-delà de 32 écouteurs par port. Les exceptions ou rejets de callback non gérés arrêtent l’application. off n’a aucun effet sur une inscription absente.

Exemple

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

14.10 Événements et délimitation des messages

Tableau 64

Événement

Objet

Description

data

{ data: Uint8Array }

Bloc du flux brut ; un événement ne correspond pas nécessairement à un paquet de protocole. NUL et les autres octets binaires sont préservés.

line

{ line: string }

Ligne UTF-8 assemblée sans délimiteur ; les blocs de message séparés sont réassemblés. Les espaces ne sont pas supprimés automatiquement.

state

{ port, claimed, reason, generation }

port est rs232 ou rs485. claimed est boolean ; reason identifie la transition ; generation change lors de l’application de l’état du port.

Avec un écouteur line, la réception est assemblée jusqu’au délimiteur. Un écouteur data sur le même port reçoit une autre vue du flux ; ne traitez pas une commande deux fois. Les lignes trop longues provoquent MESSAGE_TOO_LARGE avant le callback line et peuvent arrêter l’application. Sans écouteur line, les données binaires brutes ne sont pas accumulées dans un tampon de lignes. Les événements antérieurs à la réinitialisation ne sont pas réutilisés comme données sous la nouvelle configuration.

Les ports série n’ont pas d’événement connection : les câbles débranchés ou les appareils éteints ne peuvent généralement pas être détectés de façon fiable. state décrit la propriété et les paramètres de Neutron AppEngine, pas la connectivité physique. Vérifiez l’accessibilité avec les réponses et les délais de votre protocole. Les applications RS-485 implémentent l’adressage, le CRC et les règles d’accès au bus partagé ; le filtre système R4A ne s’applique pas aux données brutes lorsque JavaScript possède le port.

14.11 Application RS-232 / RS-485 complète

Définissez la fonction du port choisi sur Disabled et supprimez les autres affectations. L’application ci-dessous le réserve, configure de façon persistante 19200/8N1 et répond à WEIGHT? par net,gross,unit. Pour l’autre port, changez uniquement l’objet sélectionné. Configurez le même format de caractères sur l’appareil distant.

// 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 Tests d’intégration

Tableau 65

Test

Résultat attendu

Réservation avec une fonction système activée

RESOURCE_IN_USE ; l’utilisation système reste inchangée.

Configurer via JavaScript et séparément via SMD

Le débit/la parité/les bits s’appliquent sans redémarrer l’appareil.

Modifier un port

L’autre port conserve ses données et son fonctionnement s’il n’est pas affecté.

Prise de contrôle externe pendant le fonctionnement JavaScript

state RESOURCE_IN_USE, claimed=false ; les nouvelles écritures renvoient NOT_OWNER.

Octets binaires et ligne répartie sur plusieurs réceptions

Aucune perte de NUL ni délimiteur dupliqué ; une ligne correctement assemblée.

Reconfigurer pendant une réception ou une écriture partielle

Les anciennes lignes partielles sont abandonnées ; les anciennes écritures restantes ne sont pas envoyées avec les nouveaux paramètres.

Libérer / Stop et réserver à nouveau

Aucun port occupé définitivement ; les paramètres physiques persistent.

15. Module MQTT

Ce module n’exécute pas automatiquement les commandes CSCP. L’application définit la signification des topics, le format du payload et les commandes autorisées. mqtt.connect() se connecte au broker utilisateur, ne change pas la connexion système Scale Monitor et ne nécessite pas de claim().
Le module mqtt fournit à l’application utilisateur une connexion indépendante à un broker, distincte de la connexion système Scale Monitor. Les deux peuvent fonctionner simultanément avec des adresses, identités, identifiants et abonnements différents. L’application ne réserve pas les topics système. Prise en charge : app.capabilities().features.mqtt === true. Toutes les fonctions, propriétés et tous les événements de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0.
Tableau 66

URL

Connexion

Exemple

mqtt://

MQTT sur TCP

mqtt://broker.example.com:1883

mqtts://

MQTT avec authentification du serveur TLS

mqtts://broker.example.com:8883

ws://

MQTT sur WebSocket

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

wss://

MQTT sur WebSocket sécurisé

wss://broker.example.com/mqtt

Protocole : MQTT 3.1.1 ; l’API prend en charge QoS 0 et 1. Une URL WebSocket doit pointer vers l’écouteur MQTT du broker, pas vers un serveur WebSocket quelconque. Un accès réseau, des paramètres DNS corrects et un broker accessible sont requis. L’horloge de l’appareil doit être correcte pour vérifier la validité des certificats.

Cycle de vie de la connexion

Enregistrez d’abord les écouteurs, puis await mqtt.configure(...), await mqtt.connect() et await mqtt.subscribe(...). La configuration dure pendant l’exécution actuelle de l’application et est abandonnée à son arrêt. Incluez-la dans le démarrage pour le démarrage automatique de l’application. Ne vous reconnectez pas à chaque itération du temporisateur.
Après une connexion réussie, la déconnexion déclenche par défaut une reconnexion automatique, avec un délai borné doublant jusqu’à 60 secondes. Les abonnements confirmés avec succès sont restaurés automatiquement, de façon asynchrone. connect et la fin de connect() confirment la connexion, pas la fin de la restauration de tous les abonnements. Les échecs de restauration émettent error. Avant la première connexion réussie, une tentative échouée est rejetée ; l’application décide s’il faut réessayer.
Un disconnect() explicite, un échec d’authentification ou un débordement de la file d’événements arrête la reconnexion automatique. Une perte réseau ordinaire après une connexion réussie entraîne une reconnexion si celle-ci est activée. L’arrêt ou le remplacement de l’application ferme uniquement sa propre connexion MQTT. Une fermeture ordonnée asynchrone ne confirme pas la livraison des dernières publications. La connexion système continue indépendamment.

mqtt.configure(options)

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.configure(options);
Objectif. Configurer le broker et l’identité de l’application.
Description. Valide et remplace les paramètres uniquement lorsque le client utilisateur n’est ni connecté, ni en cours de connexion, ni en attente de reconnexion. Attendez disconnect() avant de les modifier. Une nouvelle configuration réussie efface les abonnements mémorisés ; un échec conserve la configuration précédente.

Paramètres

Tableau 67

Paramètre

Type / exigence

Description

options

object / requis

Les propriétés sont répertoriées ci-dessous. Les propriétés inconnues sont rejetées ; les valeurs doivent utiliser les types documentés.

Résultat

Promise<undefined>. Confirme la configuration et le chargement des profils de certificat demandés ; ne se connecte pas.

Erreurs et considérations particulières

INVALID_ARGUMENT, MESSAGE_TOO_LARGE, BUSY, CERTIFICATE_NOT_FOUND, CERTIFICATE_TOO_LARGE, OUT_OF_MEMORY. Un contenu PEM invalide peut ne provoquer un échec qu’au moment de la connexion TLS.

Exemple

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

Propriété de options

Type / par défaut

Signification et limites

url

string / requis

Jusqu’à 512 octets UTF-8. L’un des quatre schémas. Aucun nom d’utilisateur/mot de passe, espace ou fragment # dans l’URL. Incluez le chemin ws/wss correct, tel que /mqtt.

clientId

string / automatique

Jusqu’à 64 octets UTF-8. S’il est absent ou vide, l’appareil attribue une identité stable à l’application utilisateur. Deux connexions simultanées au même broker ne doivent pas partager un clientId.

username, password

string / aucun

Au plus 256 et 512 UTF-8 octets respectivement. Ne les enregistrez jamais sur la console ; le code de l'application n'est pas un coffre-fort secret.

keepAlive

integer / 60

Secondes, 5..3600.

cleanSession

boolean / true

false active une session persistante sur le broker pour le même clientId. L’API de l’application restaure toujours ses abonnements confirmés ; les abonnements présents uniquement sur le broker ne font pas partie de sa liste locale.

reconnect

boolean / true

Reconnexion automatique après perte d'une connexion établie. Ne répète pas l'échec de la connexion initiale ou le disconnect() explicite.

connectTimeoutMs

integer / 10000

1000..60000 ms. Délai limite de connexion du client et d’opération réseau.

reconnectDelayMs

integer / 1000

1000..60000 ms. Délai initial, doublé en cas de déconnexions répétées jusqu'à 60000 ms et réinitialisation après succès.

will

object / aucun

{topic, payload, qos?, retain?}. topic est un topic de publication ; payload est string. qos : 0 ou 1, valeur par défaut 0 ; retain : boolean, valeur par défaut false. Le broker publie le will après une déconnexion inattendue selon les règles MQTT ; ne vous y fiez pas après une fermeture ordonnée.

tls

object / aucun

mqtts/wss uniquement. Propriétés : caProfile, clientCertificateProfile, clientKeyProfile. Voir TLS ci-dessous.

Le JSON complet des options doit tenir dans 4096 octets UTF-8, noms de propriétés et échappements compris. La capacité réelle de will.payload est donc inférieure à 4096 octets. Les chaînes de configuration ne peuvent pas contenir NUL ; utilisez publish() pour les données binaires. Les paramètres du client utilisateur sont indépendants de ceux du broker système.

mqtt.connect(options?)

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.connect({ timeoutMs: 15000 });
Objectif. Se connecter au broker configuré.
Description. La Promise est satisfaite après confirmation d’une connexion réussie au broker. Les appels déjà connectés réussissent. Une deuxième tentative de connexion simultanée est rejetée avec BUSY.

Paramètres

Tableau 69

Paramètre

Type / exigence

Description

options.timeoutMs

integer / facultatif

1..60000 ms ; utilise par défaut le connectTimeoutMs configuré. S’applique à la tentative de connexion ; l’attente dans la file de service et l’arrêt du client peuvent prolonger la durée totale.

Résultat

Promise<undefined>. Les informations de connexion sont aussi disponibles dans connect et status().

Erreurs et considérations particulières

NOT_CONFIGURED, BUSY, START_FAILED, AUTH_FAILED, CONNECTION_REFUSED, NOT_CONNECTED, TIMEOUT, CANCELLED. Des causes réseau/TLS plus détaillées peuvent apparaître dans error ou status().lastError. Bornez les nouvelles tentatives après les échecs initiaux.

Exemple

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

mqtt.disconnect()

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.disconnect();
Objectif. Fermez proprement la connexion utilisateur et arrêtez la reconnexion.
Description. Annule les opérations connect, publish, subscribe et unsubscribe en attente ; traitez leurs Promise. La configuration et les abonnements confirmés restent pour le prochain connect dans la même exécution ; configure les remplace.

Paramètres

Aucun paramètre.

Résultat

Promise<undefined> après la fermeture du client. Les appels déjà déconnectés réussissent.

Erreurs et considérations particulières

NOT_CONFIGURED avant la configuration initiale. Les opérations interrompues reçoivent CANCELLED. N’annule pas les publications déjà acceptées par le broker. N’envoie pas automatiquement de message métier de mise hors ligne ; publiez-en un et confirmez-le avant disconnect() si nécessaire.

Exemple

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

mqtt.status()

Disponible depuis : Neutron AppEngine 1.0.0
const status = mqtt.status();
Objectif. Renvoie l'état actuel de la connexion de l'utilisateur sans attendre.
Description. Renvoie une copie du dernier état, ce qui ne garantit pas le succès de la prochaine opération réseau. Ne révèle aucun nom d'utilisateur, mot de passe ou certificat.

Paramètres

Aucun paramètre.

Résultat

{configured:boolean, connected:boolean, state:string, reconnectAttempts:number, lastError:string}. state : unconfigured, disconnected, connecting, connected, reconnecting. reconnectAttempts compte les débuts de reconnexion automatique depuis le dernier configure. lastError est vide ou contient le dernier code d’erreur ; une connexion réussie l’efface.

Erreurs et considérations particulières

Synchrone ; ne se connecte pas. L'état du réseau peut changer entre la lecture et l'opération suivante.

Exemple

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

mqtt.subscribe(topic, options?)

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.subscribe("factory/+/command", { qos: 1, timeoutMs: 10000 });
Objectif. S’abonner à un topic ou à un filtre de topics.
Description. Attend le SUBACK du broker ; un refus du broker n’est pas une réussite. Les abonnements confirmés sont mémorisés pour la reconnexion. Répéter un filtre n’utilise aucun emplacement supplémentaire ; une confirmation réussie remplace le QoS demandé. Le broker peut accorder un QoS inférieur.

Paramètres

Tableau 70

Paramètre

Type / exigence

Description

topic

string / requis

1..192 octets UTF-8. + doit occuper un niveau entier, # le niveau final entier ; par exemple factory/+/command ou factory/#.

options.qos

integer / 0

0 ou 1.

options.timeoutMs

integer / 10000

1..60000 ms pour l’accusé de réception du broker.

Résultat

Promise<undefined> après SUBACK réussi. Les publications entrantes émettent message.

Erreurs et considérations particulières

NOT_CONFIGURED, NOT_CONNECTED, SUBSCRIBE_FAILED, QUOTA_EXCEEDED, BUSY, TIMEOUT. Au maximum 16 filtres. Des subscribe/unsubscribe concurrents pour le même filtre reçoivent BUSY. Les requêtes hors ligne ne sont pas mises en file pour plus tard.

Exemple

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

mqtt.unsubscribe(topic, options?)

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.unsubscribe("factory/scale-01/command");
Objectif. Désabonnez le filtre exact et supprimez-le de la liste de reconnexion.
Description. Confirmé par UNSUBACK. Les filtres inconnus peuvent être désabonnés. Ne supprime ni les messages déjà reçus ni les autres abonnements qui se chevauchent.

Paramètres

Tableau 71

Paramètre

Type / exigence

Description

topic

string / requis

Filtre exact à désabonner ; jusqu’à 192 octets UTF-8.

options.timeoutMs

integer / 10000

1..60000 ms.

Résultat

Promise<undefined> après UNSUBACK.

Erreurs et considérations particulières

NOT_CONFIGURED, NOT_CONNECTED, BUSY, TIMEOUT, CANCELLED. Pour remplacer les filtres mémorisés pendant la déconnexion, utilisez configure ; il remplace la liste locale complète mais ne garantit pas la suppression de l'ancienne session du broker.

Exemple

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

mqtt.publish(topic, payload, options?)

Disponible depuis : Neutron AppEngine 1.0.0
await mqtt.publish(topic, payload, { qos: 1, retain: false });
Objectif. Publier du texte ou des données binaires.
Description. Envoie les chaînes en UTF-8 et Uint8Array sous forme d’octets exacts ; n’ajoute ni CR, ni LF, ni NUL. Copie payload au moment de l’appel. L’envoi commence depuis une tâche de communication distincte après le traitement de la requête. QoS 0 confirme une écriture réussie sur le transport ; QoS 1 attend le PUBACK du broker. Aucun des deux ne confirme le traitement par l’abonné final.

Paramètres

Tableau 72

Paramètre

Type / exigence

Description

topic

string / requis

1..192 UTF-8 octets, sans + ou #.

payload

string | Uint8Array / requis

0..4096 octets après l'encodage UTF-8 ; les données binaires peuvent contenir NUL.

options.qos

integer / 0

0 ou 1 ; QoS 2 n'est pas pris en charge.

options.retain

boolean / false

Conserver le message sur le broker. Un payload vide avec retain=true supprime la valeur conservée du topic.

options.timeoutMs

integer / 10000

1..60000 ms. Délai limite de PUBACK avec QoS 1 ; QoS 0 n’attend pas le broker.

Résultat

Promise<undefined>; la signification de l'accusé de réception dépend de QoS.

Erreurs et considérations particulières

NOT_CONNECTED hors ligne ; pas de file d'attente hors ligne illimitée. BUSY pour une file d'attente sortante complète (32768 octets incluant la surcharge de protocole) ou une limite d'opérations en attente. MESSAGE_TOO_LARGE, INVALID_ARGUMENT, NETWORK_ERROR, TIMEOUT, CANCELLED. Le broker a peut-être déjà reçu un message après un délai d'attente/déconnexion. QoS 1 peut faire double emploi ; utilisez les ID de demande et la déduplication pour les opérations commerciales.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
mqtt.on(eventName, callback);
mqtt.once(eventName, callback);
mqtt.off(eventName, callback);
Objectif. Enregistrer ou retirer un écouteur d’événements du broker utilisateur.
Description. Les événements s’exécutent séquentiellement. Un callback async cède l’exécution à await ; protégez-vous des chevauchements lorsque l’ordre compte. once retire l’inscription avant l’appel. off retire toutes les inscriptions de la même fonction pour l’événement sélectionné.

Paramètres

Tableau 73

Paramètre

Type / exigence

Description

eventName

string / requis

connect, disconnect, message ou error.

callback

function / requis

Reçoit un objet avec les champs répertoriés ci-dessous. Conservez la même référence de fonction pour off.

Résultat

Renvoie mqtt pour chaîner les appels. Au maximum 32 écouteurs pour l’ensemble des événements MQTT.

Erreurs et considérations particulières

INVALID_ARGUMENT, QUOTA_EXCEEDED. error seul n’arrête pas l’application ; une exception d’écouteur ou une Promise rejetée non gérées l’arrêtent selon les règles de l’environnement d’exécution. Le rejet d’opération et error sont des notifications distinctes sans ordre relatif garanti.

Exemple

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

Événement

Champs depuis Neutron AppEngine 1.0.0

Signification

connect

connected: true, reconnected: boolean, sessionPresent: boolean

CONNACK accepté. reconnected indique une connexion antérieure réussie sous la configuration actuelle. sessionPresent est l’indicateur de session restaurée du broker, pas la liste des abonnements confirmés localement.

disconnect

connected: false, reason: string

Perte d’une connexion établie ou déconnexion explicite. Traitez la Promise d’un connect initial échoué. Aucun événement n’est garanti à l’arrêt de l’application.

message

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

Message MQTT complet, d’abord assemblé à partir des fragments. text est une vue UTF-8 ; utilisez data pour des payloads binaires quelconques. qos est le QoS du message reçu (l’API demande au maximum 1, mais le broker peut conserver d’anciens abonnements).

error

Erreur avec code: string et message: string

Connexion, TLS, restauration d'abonnement, message surdimensionné ou erreur de file d'attente. L'application décide comment continuer ; inspecter status() et les opérations en cours.

TLS et profils de certificat

mqtts et wss vérifient le nom du serveur et la confiance du certificat. Sans caProfile, la confiance intégrée des autorités de certification publiques est utilisée. Utilisez un profil personnalisé pour les autorités privées. La désactivation de la vérification des certificats ne fait pas partie de l’API. Les paramètres et certificats du broker système ne s’appliquent pas aux connexions utilisateur.

Tableau 75

champ tls

Profil stocké

Objectif

caProfile : "company-ca"

JCA_company-ca

PEM d’une autorité de certification de confiance ou chaîne d’autorités de certification.

clientCertificateProfile : "device-01"

JCC_device-01

Certificat client PEM pour TLS mutuel.

clientKeyProfile : "device-01"

JCK_device-01

PEM de la clé privée du client ; requis avec le certificat. Les clés chiffrées par mot de passe ne sont pas prises en charge dans cette version.

Les noms de profils contiennent 1..48 caractères : A–Z, a–z, 0–9, _ ou -. Chaque PEM normalisé mesure au maximum 16384 octets. Un intégrateur autorisé provisionne les profils via le chemin SMD existant des certificats, par exemple JCA_company-ca=<PEM>, avec le certificat PEM complet comme valeur. Ce n’est ni un chemin de fichier, ni une URL publique, ni un profil MCA système. Une valeur vide supprime un profil selon les règles existantes des certificats. Les applications chargent les profils pendant configure ; modifier les profils stockés ne remplace pas les certificats d’une connexion active. Effectuez disconnect, configure, puis 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();

Limites, erreurs et récupération

Tableau 76

Limite depuis Neutron AppEngine 1.0.0

Valeur / traitement

Connexions

Une connexion utilisateur, distincte de la connexion système Scale Monitor.

Payload

4096 octets par message envoyé ou reçu : le message entier, pas chaque fragment.

Topic / abonnements / écouteurs

192 octets UTF-8 / 16 filtres confirmés / 32 écouteurs.

Opérations en attente

Au maximum 8, partagées avec les autres opérations asynchrones de l’environnement d’exécution. File MQTT sortante : 32768 octets.

Délai

Au maximum 60000 ms pour la connexion ou l'accusé de réception du broker. Cela ne garantit pas un temps de réponse exact de l'appareil.

Message entrant surdimensionné

Message entier supprimé ; erreur MESSAGE_TOO_LARGE. Les messages partiels ne sont pas remis.

Débordement de file d'attente de service

EVENT_OVERFLOW ferme la connexion utilisateur et arrête la reconnexion. L’environnement d’exécution possède une autre file bornée ; son débordement arrête l’application.

Délai d'acquittement

L’opération en attente est rejetée et la reconnexion suit les règles configurées. Les autres opérations peuvent recevoir NOT_CONNECTED. Un accusé tardif d’une ancienne connexion ne confirme jamais une nouvelle requête.

Déconnexion pendant la publication

Les opérations non confirmées sont rejetées ; l’application décide s’il faut réessayer. Les effets déjà produits ne sont pas annulés.

Codes principaux : 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. Les messages d’erreur sont diagnostiques ; fondez les décisions du programme sur code. Pour les erreurs TLS, vérifiez l’heure de l’appareil, le nom du serveur, la chaîne de confiance et le certificat client requis.

Exemple complet : publier le poids et recevoir des commandes

Adaptez brokerUrl, baseTopic et les identifiants avant l’exécution. Chaque appareil nécessite ses propres clientId et topics. Envoyez les commandes à /command sans retain. L’exemple publie le poids périodiquement, restaure automatiquement les abonnements confirmés et ne répète pas le tarage pour les commandes conservées. Pour les systèmes qui réessaient des requêtes QoS 1, ajoutez des ID de requêtes et un registre des commandes exécutées ; retain seul n’empêche pas une livraison en double.

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

Tests d'intégration

Tableau 77

Test

Résultat attendu

Connexion système et broker utilisateur simultanément

Scale Monitor continue ; les topics utilisateur sont gérés uniquement par l’application.

Publier WEIGHT? sur le /command sélectionné

Le JSON de mesure arrive sur /reply ; /weight est actualisé environ chaque seconde.

Perte et restauration du réseau

status devient reconnecting, puis connect arrive avec reconnected=true et restauration automatique des abonnements.

Mot de passe incorrect / CA / nom du serveur

Connect est rejeté ; error/status fournissent des diagnostics. Une authentification échouée ne boucle pas indéfiniment.

Envoyer 4096 octets binaires

Tous les octets, y compris NUL, restent inchangés. Le topic ne compte pas dans la taille du payload.

Recevez un message au-dessus de 4096 octets

MESSAGE_TOO_LARGE sans événement de message partiel.

Arrêt de l'application

La connexion utilisateur se ferme ; la connexion système reste active.

mqtt, mqtts, ws, wss

Testez chaque URL par rapport à l'écouteur de broker approprié ; ws/wss nécessite le chemin correct.

16. Client HTTP / REST

La fonction globale fetch() connecte les applications aux API REST externes via HTTP ou HTTPS. Prise en charge : app.capabilities().features.http. Toutes les fonctions, propriétés et options de ce chapitre sont disponibles depuis Neutron AppEngine 1.0.0. Il s’agit d’un sous-ensemble documenté de fetch, pas d’un environnement de navigateur complet.

L’appareil agit comme client HTTP. Cette API n’ajoute aucune route REST personnalisée au serveur HTTP interne de Neutron. Les requêtes ne fournissent ni nouvelles tentatives automatiques, ni file persistante, ni transmission automatique d’événements, ni stockage des réponses. L’application définit le moment des appels, les formats de données et la gestion des échecs.

fetch(url, options?)

Disponible depuis : Neutron AppEngine 1.0.0
const response = await fetch(url, options);
Objectif. Envoyez une requête à un serveur HTTP/HTTPS externe et recevez une réponse complète limitée.
Description. La Promise est satisfaite après réception du corps entier, pas seulement des en-têtes initiaux. HTTP 400, 401, 404 et 500 sont des réponses normales et ne provoquent pas de rejet. Les échecs de connexion, TLS, délai et taille provoquent un rejet. Le traitement réseau s’exécute hors du callback JavaScript sans le bloquer pendant l’attente.

Paramètres

Tableau 78

Paramètre

Type / exigence

Description

url

string / requis

URL absolue http:// ou https://, au maximum 512 octets ASCII. Encodez Unicode et les espaces dans les chemins/valeurs de requête ; utilisez encodeURIComponent pour les valeurs individuelles. Un fragment # est retiré. Les identifiants dans les URL sont interdits.

options

object / facultatif

method, headers, body, timeoutMs, tls et redirect. Les options inconnues sont rejetées. Les détails suivent ci-dessous.

Résultat

Promise<Response>, décrit ci-dessous. body et les options encodées ont des limites distinctes ; les payloads binaires ne sont encodés ni en JSON ni en Base64.

Erreurs et considérations particulières

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. Après une interruption/un délai d'attente, le serveur a peut-être déjà traité la demande ; réessayer POST peut dupliquer son effet commercial.

Exemple

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

Option depuis Neutron AppEngine 1.0.0

Type / par défaut

Signification

method

string / GET

GET, POST, PUT, PATCH, DELETE ou HEAD. Converti en majuscules. Les autres méthodes ne sont pas prises en charge dans cette version.

headers

object / aucun

Noms d’en-tête personnalisés et valeurs de type chaîne. Les noms sont insensibles à la casse ; les noms en double ne différant que par la casse sont rejetés. Valeurs ASCII uniquement, sans CR/LF ni caractères de contrôle autres que la tabulation.

body

string | Uint8Array | null / aucun

Au maximum 4096 octets après encodage UTF-8. null signifie aucun corps. GET et HEAD ne peuvent pas avoir de corps. Les chaînes sans Content-Type explicite reçoivent text/plain; charset=UTF-8 ; pour JSON, utilisez JSON.stringify et application/json. Uint8Array ne reçoit aucun Content-Type automatique.

timeoutMs

integer / 10000

1..60000 ms; une extension Neutron AppEngine documentée, pas une option fetch de navigateur standard. Commence à l’heure de l’appel et comprend l’attente dans la file d’attente et le transfert du corps. La livraison des erreurs ne constitue pas une garantie en temps réel ; La résolution de nom sous-jacente ou les appels de connexion peuvent se terminer plus tard.

tls

object / aucun

HTTPS uniquement. caProfile et en option la paire clientCertificateProfile/clientKeyProfile. Voir TLS.

redirect

string / manual

Seul manual est pris en charge. Renvoie les réponses 3xx afin que l’application puisse examiner Location. Aucun suivi automatique des redirections.

Au maximum 32 en-têtes fournis et 2048 octets cumulés (noms, valeurs et séparateurs) ; noms jusqu’à 64 caractères, valeurs jusqu’à 1024. Le client gère les en-têtes automatiques du protocole. Host, Content-Length, Connection, Transfer-Encoding, Accept-Encoding, Expect, Trailer, Upgrade, Proxy-Connection, TE et Keep-Alive ne peuvent pas être définis. Les options encodées de requête ont une limite cumulée supplémentaire de 4096 octets UTF-8.

Réponse : statut et métadonnées

Disponible depuis : Neutron AppEngine 1.0.0
const response = await fetch("https://api.example.com/articles/ART-001");
Objectif. Inspectez le résultat HTTP avant de convertir son corps.
Description. Un objet avec des propriétés en lecture seule et des méthodes pour consommer le corps une seule fois. Ne confirme ni la signification métier de l’état ni la validité du JSON reçu.

Paramètres

Aucun paramètre.

Résultat

{status, statusText, ok, url, redirected, headers, bodyUsed, text(), json(), arrayBuffer()}. status est le code HTTP ; ok signifie 200..299. url est l’URL demandée sans fragment ; redirected vaut false ; statusText est une chaîne vide dans cette version.

Erreurs et considérations particulières

Traitez le rejet de fetch séparément de response.ok. Attendez-vous à un corps vide pour 204 ou HEAD ; response.json() sur un corps vide lève SyntaxError. Aucun response.body en streaming, clone(), Blob, FormData, Request ni constructeur global Response.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const text = await response.text();
Objectif. Convertissez une fois le corps reçu en texte UTF-8.
Description. Retire un BOM UTF-8 initial. N’effectue aucune autre requête réseau ; fetch a déjà reçu le corps. bodyUsed devient true au premier appel d’une méthode de consommation du corps.

Paramètres

Aucun paramètre.

Résultat

Promise<string>. Utilisez arrayBuffer() pour les données binaires arbitraires.

Erreurs et considérations particulières

Une lecture répétée lève TypeError avec code=BODY_USED. Décode UTF-8 ; les autres jeux de caractères ne sont pas automatiquement pris en charge.

Exemple

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

response.json()

Disponible depuis : Neutron AppEngine 1.0.0
const value = await response.json();
Objectif. Décodez le corps UTF-8 et exécutez JSON.parse une fois.
Description. Renvoie un objet, un tableau ou une autre valeur JSON valide. Content-Type ne modifie pas les règles JSON.parse. Vérifiez d'abord l'état si votre API renvoie différents formats de corps d'erreur.

Paramètres

Aucun paramètre.

Résultat

Promise<JSON value>. bodyUsed devient true même si l'analyse de JSON échoue.

Erreurs et considérations particulières

SyntaxError pour un JSON invalide/vide ; TypeError/BODY_USED pour une lecture répétée. Stockez le résultat dans une variable pour le réutiliser.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const buffer = await response.arrayBuffer();
Objectif. Renvoie une fois les octets binaires reçus, sans conversion de texte.
Description. Utilisez Uint8Array pour accéder aux octets individuels, y compris NUL. Stockez-les ou transférez-les vers un autre module pris en charge.

Paramètres

Aucun paramètre.

Résultat

Promise<ArrayBuffer>, au plus 4096 octets.

Erreurs et considérations particulières

TypeError/BODY_USED lors d’une lecture répétée. Aucune décompression automatique gzip ou d’autres contenus.

Exemple

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

Disponible depuis : Neutron AppEngine 1.0.0
const contentType = response.headers.get("Content-Type");
Objectif. Lire les en-têtes de réponse sans tenir compte de la casse.
Description. Objet en lecture seule prenant en charge get, has, entries, keys, values, forEach et l’itération. Les noms d’en-tête répétés sont joints par des virgules ; ce n’est pas un gestionnaire automatique de cookies.

Paramètres

Tableau 80

Paramètre

Type / exigence

Description

name pour get/has

string / requis

Nom d'en-tête HTTP valide.

callback pour forEach

function / requis

Reçoit value, name et headers. Un deuxième argument facultatif définit thisArg.

Résultat

get renvoie string ou null ; has renvoie boolean ; entries/keys/values renvoient des itérateurs. forEach ne renvoie aucun résultat. L’itération utilise des noms d’en-tête minuscules.

Erreurs et considérations particulières

INVALID_ARGUMENT pour des noms d’en-tête ou callbacks invalides. Aucun constructeur global Headers ni méthodes set/append/delete de réponse. Si le serveur dépasse 32 en-têtes, 2048 octets cumulés ou les longueurs de nom/valeur prises en charge, fetch rejette au lieu de tronquer silencieusement.

Exemple

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

Authentification

Fournissez des jetons Bearer, des clés API ou des valeurs Basic préencodées dans les en-têtes. Ne placez pas d’identifiants dans les URL. Il n’y a ni connexion automatique, ni actualisation des jetons, ni authentification HTTP Digest, ni session partagée avec les connexions système. Les cookies ne sont ni enregistrés ni envoyés automatiquement. Ce client de l’appareil n’est pas soumis aux restrictions CORS du navigateur.

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 et profils de certificat

HTTPS vérifie toujours le nom du serveur et la confiance du certificat. Sans caProfile, utilise la confiance intégrée des autorités de certification publiques. Utilisez un profil personnalisé pour les autorités privées. L’horloge de l’appareil doit être correcte pour vérifier la validité des certificats. Aucune option non sécurisée ni contournement de la vérification du nom d’hôte.

Tableau 81

option tls

Profil stocké

Objectif

caProfile : "company"

JHCA_company

PEM d’une autorité de certification de confiance ou chaîne d’autorités de certification.

clientCertificateProfile : "scale01"

JHCC_scale01

Certificat client pour TLS mutuel.

clientKeyProfile : "scale01"

JHCK_scale01

Clé privée ; requise avec le certificat client.

Noms de profils : 1..48 caractères A–Z/a–z, 0–9, _ ou -. Chaque PEM mesure au maximum 16384 octets. Les intégrateurs autorisés provisionnent les profils via le chemin SMD existant des certificats, par exemple JHCA_company=&lt; PEM&gt;. Ce n’est pas un chemin de fichier arbitraire. Les profils sont distincts des certificats MQTT système et du serveur HTTP interne et sont chargés à chaque requête. Les clés privées chiffrées par mot de passe ne sont pas prises en charge.

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

Limites et exécution

Tableau 82

Propriété depuis Neutron AppEngine 1.0.0

Traitement

Exécution

Une requête active et jusqu’à quatre en attente. La limite partagée de l’environnement d’exécution de huit opérations asynchrones en attente s’applique également.

Taille

Corps de requête limité à 4096 octets et limite distincte de 4096 octets pour le corps de réponse. Les réponses trop volumineuses génèrent RESPONSE_TOO_LARGE ; les corps partiels ne sont jamais renvoyés comme résultat réussi.

Délai d'attente

Par défaut 10000 ms, maximum 60000 ms, y compris la file d'attente. Les données entrantes lentes ne réinitialisent pas le délai. Le délai de livraison réel des erreurs n’est pas garanti en temps réel.

Connexions

Les connexions sont libérées après chaque demande. Pas de session HTTP persistante ni de nouvelle tentative automatique. HTTPS établit donc une nouvelle connexion sécurisée à chaque appel.

Redirections

Toujours manual. 3xx reste une réponse ; Location peut être lu. Les en-têtes d’authentification ne sont pas automatiquement transmis à un autre serveur.

Encodage du corps

Demande identity. gzip/br et les autres encodages ne sont pas pris en charge ; une réponse encodée non vide provoque UNSUPPORTED_ENCODING.

Arrêt de l'application

Les requêtes en file d'attente d'une exécution précédente sont ignorées ; le transfert actif est interrompu lorsque l'arrêt est détecté ou lorsque l'appel de connexion sous-jacent se termine. Cela n'annule pas les effets serveur déjà effectués.

Sous-ensemble de l’API

Aucun AbortController/signal, corps en streaming, clone, Blob, FormData, constructeur URL/Request/Response/Headers ni environnement CORS/cookie automatique.

Protégez les appels périodiques des chevauchements. Utilisez des ID de requêtes et un protocole convenu avec le serveur pour réessayer les opérations métier de façon fiable. Un délai dépassé ou une réponse perdue ne prouve pas que le serveur n’a pas traité POST/PUT/PATCH/DELETE.

Exemple complet : envoyer le poids

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

Tests d'intégration

Pour les tests locaux, le paquet source inclut tools/rest-test-server.py et tools/examples/rest-self-test.js pour l’appareil. Le serveur écoute localement par défaut ; utilisez explicitement --host 0.0.0.0 pour l’accès de Neutron et définissez l’adresse IP de l’ordinateur dans l’application de test. Les options --cert/--key activent HTTPS ; --ca active la validation du certificat client. Le provisionnement des certificats/profils reste une procédure de gestion distincte.

Tableau 83

Test

Résultat attendu

GET/POST/PUT/PATCH/DELETE/HEAD

Demande et statut corrects ; HEAD n'a pas de corps.

404 ou 500

La Promise est satisfaite ; response.ok vaut false.

302

État et Location sans nouvelle requête automatique.

JSON / UTF-8 / chunked

Corps complet correctement décodé ; les morceaux ne sont pas des événements JavaScript séparés.

Corps binaire avec NUL et 0xff

Exactement 4096 octets dans chaque direction.

Relisez le corps

TypeError avec code=BODY_USED.

Réponse lente ou flux d'en-tête lent

TIMEOUT ; le pesage et l’environnement d’exécution continuent.

Réponse/en-têtes surdimensionnés

Rejet explicite sans troncature silencieuse.

HTTPS avec un CA/nom/certificat client incorrect

TLS_ERROR ; la vérification reste activée.

Arrêt pendant le transfert

Ressources libérées ; aucune réponse obsolète n'est fournie lors d'une nouvelle exécution d'application.

17. Client WebSocket

Disponible depuis : Neutron AppEngine 1.0.0 / API 1.
WebSocket fournit une connexion bidirectionnelle persistante à un serveur externe. Les applications envoient des messages texte ou binaires et reçoivent des événements. Chaque message conserve sa limite ; les délimiteurs de lignes sont inutiles. Utilisez fetch() pour REST et mqtt pour un broker MQTT.
Chaque application dispose d’une connexion indépendante, distincte des paramètres WebSocket du module, de MQTT et de Scale Monitor. Prend en charge ws://, wss://, les noms DNS et IPv4. Vérifiez app.capabilities().features.websocket ; les limites figurent dans app.capabilities().websocket.

new WebSocket(url, protocols?, options?)

Disponible depuis : Neutron AppEngine 1.0.0
Crée un client et lance une connexion asynchrone. Renvoie un objet WebSocket, pas une Promise. La réussite émet open ; l’échec émet error et close. Les arguments invalides lèvent une exception synchrone.
  • url : adresse absolue, au plus 512 octets, comme wss://system.example.com/scales?device=01. Ports par défaut : 80 pour ws, 443 pour wss. Encoder les chemins et les paramètres ; Les informations d'identification URL, les fragments et IPv6 ne sont pas pris en charge.
  • protocols : omis ou tableau vide []. La négociation de sous-protocole n’est pas disponible dans cette version ; les autres valeurs génèrent UNSUPPORTED_PROTOCOL.
  • options : objet optionnel contenant timeoutMs, headers et tls. Peut également être fourni directement comme deuxième argument.
  • timeoutMs : limite entière de connexion 1000–15000 ms, valeur par défaut 10000 ms. Les détails DNS/réseau peuvent affecter le temps de retour réel. Ne limite pas la durée de vie totale de la connexion.
  • headers : en-têtes HTTP à valeur de chaîne, tels que Authorization ou X-API-Key. Au plus 32 en-têtes et 512 octets combinés. Les en-têtes Connection et Sec-WebSocket-* sont gérés par le client et ne peuvent pas être définis. La demande de mise à niveau complète, y compris le chemin, le nom d'hôte et les en-têtes automatiques, doit être plus courte que 1024 octets ; une combinaison surdimensionnée soulève HEADERS_TOO_LARGE.
  • tls : wss uniquement. caProfile, clientCertificateProfile et clientKeyProfile utilisent les profils REST. Fournissez le certificat client et la clé ensemble. Noms de profil : 1–48 caractères A–Z, a–z, 0–9, _ ou -. Sans caProfile, utilise la confiance par défaut. La vérification du nom du serveur et du certificat est toujours activée.
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);

Les vérifications de certificat nécessitent l'heure correcte de l'appareil. Envoyez les informations d'identification via wss. Les redirections ne sont pas suivies automatiquement. Si l'emplacement de connexion est occupé, le nouvel objet reçoit BUSY et se ferme ; la connexion existante reste active.

Authentification Basic avec nom d’utilisateur et mot de passe

Disponible depuis : Neutron AppEngine 1.0.0
Entrez le nom d'utilisateur/mot de passe sous forme de chaînes et utilisez l'assistant ci-dessous pour créer Authorization. Basic ne hache pas les informations d'identification : il encode en Base64 username:password. L'encodage est réversible ; utilisez wss:// pour les informations d'identification.
basicAuth(username, password) est défini dans cet exemple, non intégré à Neutron AppEngine. Renvoie la valeur complète de l'en-tête Basic <Base64>. Prend en charge UTF-8 si le serveur l'attend et n'a besoin ni de btoa ni de TextEncoder. Les deux arguments doivent être des chaînes, sinon TypeError est lancé. Les noms d'utilisateur ne peuvent pas contenir de deux-points ; les mots de passe le peuvent. L'exemple d'adresse et d'informations d'identification est fictif.
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);
Remplacez /scale/auth par le point de terminaison réel du serveur. La fonction auxiliaire ne nécessite aucune modification lorsque les identifiants changent. Ne journalisez jamais Authorization ni les mots de passe. HTTP 401/403 pendant l’authentification émet error avec AUTH_FAILED, puis close. basicAuth fonctionne aussi dans les en-têtes Authorization de fetch via HTTPS.

socket.send(data)

Disponible depuis : Neutron AppEngine 1.0.0

À l’état OPEN, met un message en file. Accepte string, ArrayBuffer ou une vue de tampon telle que Uint8Array ou DataView. Les chaînes sont envoyées comme texte UTF-8 ; les autres valeurs comme messages binaires. Les données binaires sont copiées au moment de l’appel, permettant des modifications ultérieures de la source. Les messages vides et les octets binaires 0 et 255 sont autorisés.

Renvoie undefined. N’utilisez pas await comme confirmation de livraison : l’envoi ne confirme pas le traitement par le serveur. Ajoutez des ID de requêtes et des réponses à votre protocole. bufferedAmount compte les octets locaux en file, pas les messages non acquittés par le serveur.

Au maximum 4096 octets par message et 16384 octets dans la file locale ; la limite partagée d’opérations en attente s’applique également. Les messages trop volumineux génèrent MESSAGE_TOO_LARGE ; une file pleine génère BUSY. CONNECTING génère INVALID_STATE ; CLOSING/CLOSED ignorent send. Les erreurs de transfert ultérieures arrivent via error et peuvent fermer la connexion.

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

Événements et écouteurs

Disponible depuis : Neutron AppEngine 1.0.0
Utilisez onopen, onmessage, onerror, onclose ou addEventListener(type, callback, { once: true }). Supprimez avec removeEventListener(type, callback). Seuls ces quatre types d’événements et rappels de fonctions sont pris en charge ; au plus 32 écouteurs enregistrés par objet. Les paires type/fonction en double ne sont pas ajoutées. Aucun événement DOM, capture ou AbortSignal.
  • open : la mise à niveau de la connexion et du protocole a réussi ; readyState est OPEN.
  • message : event.data est une chaîne pour le texte ou ArrayBuffer pour les données binaires. Les fragments s'assemblent en un seul message, comprenant les caractères UTF-8 répartis en fragments. Le ping/pong n'est pas délivré sous forme de message.
  • error : event.code, event.message et un Error dans event.error. Les erreurs de callback suivent les règles de l’environnement d’exécution ; interceptez-les dans le callback pour continuer.
  • close : event.code, event.reason, event.wasClean. 1006 indique une fermeture interrompue ; 1005 signifie que la trame reçue n’avait pas de code. L’objet reste CLOSED. Tous les événements contiennent aussi type, target et 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?) et état de connexion

Disponible depuis : Neutron AppEngine 1.0.0
close() lance la fermeture asynchrone et renvoie undefined. Valeurs par défaut : code 1000, reason vide. Codes utilisateur : 1000 ou 3000–4999 ; reason au maximum 123 octets UTF-8. Les arguments invalides génèrent INVALID_ARGUMENT. Répéter close en CLOSING/CLOSED n’a aucun effet. Fermer pendant la connexion supprime open ; le client termine la tentative actuelle puis ferme. L’absence de réponse de fermeture dans un délai d’environ 3 secondes force une fermeture non propre.
readyState : WebSocket.CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3. Des constantes existent également sur l'objet. url contient l'adresse ; protocol et extensions sont vides. binaryType est toujours arraybuffer ; le blob n’est pas pris en charge.
if (ws.readyState === WebSocket.OPEN) ws.send("PING");
ws.close(1000, "Application finished");

Limites, récupération et erreurs

Cette version prend en charge une connexion client par application, ws/wss, le transfert binaire/texte et la vérification des certificats. Aucun serveur WebSocket, sous-protocole, compression, Blob ni reconnexion automatique. Créez un nouvel objet après close ; utilisez un setTimeout différé si nécessaire. Ce socket est distinct de MQTT via ws/wss.

La réception attend les données disponibles et ne nécessite pas d’interrogation périodique avec setInterval. Le client envoie ping environ toutes les 30 secondes et attend pong jusqu’à 10 secondes. Les opérations réseau après connexion ont des attentes bornées d’environ 3 secondes. Les messages entrants trop volumineux ou UTF-8 invalide provoquent error et fermeture. app.stop(), la suppression de l’application ou les erreurs de l’environnement d’exécution ferment la connexion et libèrent les ressources ; une opération réseau active peut prendre quelques secondes à se terminer. Les événements JavaScript ne s’exécutent plus après l’arrêt.

Codes d’erreur : INVALID_ARGUMENT, INVALID_STATE, UNSUPPORTED_PROTOCOL, BUSY, QUOTA_EXCEEDED, MESSAGE_TOO_LARGE, HEADERS_TOO_LARGE, OUT_OF_MEMORY, AUTH_FAILED (HTTP 401/403 pendant la connexion), HANDSHAKE_FAILED, NETWORK_ERROR, TLS_OR_NETWORK_ERROR, TIMEOUT, PROTOCOL_ERROR, INVALID_UTF8. Pour TLS_OR_NETWORK_ERROR, vérifiez la connectivité, l’heure, le nom du serveur et le certificat. Les erreurs de la file d’événements de l’environnement d’exécution suivent ses règles générales.

Tests d'intégration

Sur un ordinateur, exécutez python tools/websocket-test-server.py --host 0.0.0.0. Définissez l’adresse de l’ordinateur dans tools/examples/websocket-self-test.js et téléversez le fichier sur Neutron. Les tests couvrent UTF-8, les fragments avec un ping intermédiaire, les messages vides, les transferts binaires jusqu’à 4096 octets et la fermeture ordonnée. Exemple d’envoi du poids : tools/examples/websocket-scale.js. Le serveur prend en charge --cert/--key pour wss et --token pour tester Authorization. Utilisez le profil CA approprié pour les certificats personnalisés.

Testez aussi BIG (réponse trop volumineuse), un certificat/jeton incorrect, la perte réseau et Stop/Delete pendant le transfert. Les tests de l’API JavaScript sur ordinateur ne remplacent pas les tests réseau et TLS sur l’appareil.

18. Erreurs, try/catch et poursuite de l’exécution

Un try { setInterval(...) } catch (...) { ... } externe intercepte les erreurs d’inscription, pas les échecs ultérieurs du callback. De même, try { asyncOperation() } sans await n’intercepte pas le rejet de Promise. Interceptez dans le callback ou sur la Promise renvoyée.
Distinguez les exceptions JavaScript synchrones, les rejets asynchrones de Promise et les défaillances de l’ensemble de l’environnement d’exécution. Les TypeError, ReferenceError, SyntaxError et RangeError standard ont name/message, mais pas nécessairement code. Les erreurs d’opération et de validation des arguments incluent généralement error.code et error.message.
Tableau 84

Code

Signification générale

INVALID_ARGUMENT

Type/valeur d’argument invalide ; les détails dépendent de la fonction appelée.

QUOTA_EXCEEDED

Limite du module dépassée ; retirez les inscriptions inutilisées.

BUSY

Ressource occupée, trop d’opérations en attente ou file pleine. Attendez et bornez la concurrence/les nouvelles tentatives.

OUT_OF_MEMORY

Mémoire insuffisante pour l’opération. Les défaillances mémoire JavaScript peuvent utiliser à la place une exception standard sans ce code.

TIMEOUT

Opération asynchrone interrompue ou expirée. Vérifiez l’effet de l’opération précédente avant de réessayer.

Pour continuer, interceptez les échecs attendus dans la fonction où ils se produisent. Choisissez l’arrêt avec app.stop() ou laissez l’erreur non gérée. Il n’existe pas d’API globale configurable de politique d’erreurs. Consigner une erreur dans la console ne suffit pas à arrêter l’application.

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

Les exceptions/rejets non gérés, l’épuisement du temps actif, l’imbrication excessive des appels ou le débordement de la file d’événements arrêtent l’application et définissent lastError. Les erreurs internes de file/budget temporel ne fournissent pas nécessairement un objet avec code ; l’état peut contenir EVENT_OVERFLOW ou Active JS execution budget exceeded. Les défaillances système de l’appareil et les coupures d’alimentation ne sont pas des exceptions JavaScript et ne peuvent pas être interceptées avec try/catch.

Les erreurs et réponses propres aux modules sont documentées avec leurs fonctions. Les règles générales de try/catch s’appliquent quelle que soit l’origine de l’opération.

19. Limites et planification des ressources

Tableau 85

Ressource

Limite / comportement

Nom / version

Nom : 1–64 octets UTF-8 ; version : 1–32 octets ; aucun caractère de contrôle. La version est du texte, pas nécessairement une version sémantique.

Code source

Un fichier UTF-8, 1–131 072 octets.

Mémoire de l’application

1 048 576 octets pour les données et objets de Neutron AppEngine ; la taille du source est vérifiée séparément.

Imbrication des fonctions

Évitez la récursion profonde et les longues chaînes d’appels. Une imbrication excessive peut provoquer une défaillance de l’application.

Temps actif

Environ 1 s par étape de traitement de l’environnement d’exécution ; budget de 5 s pendant la validation du code. Ce n’est pas un temps de réponse garanti de la balance.

Temporisateurs

16 temporisateurs actifs.

Opérations concurrentes

Au maximum 8 opérations en attente. Traitez les événements rapidement ; un arriéré excessif peut arrêter l’application avec EVENT_OVERFLOW.

Console

10 appels/s au total, environ 512 octets de contenu par appel.

Upload

768 octets bruts/bloc ; interface BLE existante : 192 octets bruts/bloc ; la session expire après 5 minutes d’inactivité.

Sans événements ni temporisateurs, Neutron AppEngine attend tandis que les autres fonctions de l’appareil continuent normalement. L’attente ne consomme pas le budget JavaScript actif. Évaluez la charge CPU dans la configuration réelle ; aucun pourcentage CPU fixe n’est garanti ici.

Bornez la croissance des Map/Array, les données par commande et les nouvelles tentatives. Les temporisateurs pour une communication lente nécessitent généralement un indicateur d’envoi. N’accumulez pas de nouvelles requêtes lorsque les opérations ne peuvent pas se terminer rapidement. Le stockage conserve les applications installées après redémarrage ; les variables JavaScript disparaissent avec Stop/reset. Utilisez l’API de stockage documentée pour les données persistantes de l’application.

20. Installation, attributs et démarrage automatique

Tableau 86

Attribut

Description

name

Nom d’affichage de l’application et partie du préfixe de journal JavaScript.

version

Version de l’application utilisateur ; distincte de interpreterVersion, apiVersion et de la version du firmware de l’appareil.

autorun

Booléen : démarrage automatique après amorçage, sauf si la protection de récupération bloque le démarrage.

size / sha256

Longueur et SHA-256 des octets UTF-8 réels du fichier source. SHA-256 n’est ni une signature d’auteur ni un substitut à une autorisation.

Dans le serveur web interne ou la page BLE, sélectionnez un fichier, définissez les attributs et Upload. Save attributes actualise l’application existante ; Run démarre une nouvelle exécution ; Stop demande l’arrêt ; Refresh affiche l’état ; Abort upload annule le transfert ; Delete supprime l’application installée. busy=true pendant l’exécution : arrêtez et attendez avant de modifier les attributs ou d’installer. Delete pendant l’exécution lance l’arrêt ; la réponse initiale est state=stopping et la suppression se termine ensuite. Vérifiez que l’état est empty. L’état inclut aussi runtimeActive, runtimeTaskAllocated et resourcesReleased ; après l’arrêt, ils valent false, false et true. La libération des requêtes de communication actives est asynchrone ; un nouveau Run peut renvoyer BUSY entre-temps. L’interpréteur ne s’exécute pas sans application en cours d’exécution.

Un Upload réussi confirme du code stocké et validé, pas un programme exécuté avec succès. Lancez ensuite Run et vérifiez les journaux/l’état. Auto run intervient après l’initialisation du firmware et au moins 10 s après l’amorçage, pas à chaque reconnexion MQTT. Activer autorun dans les attributs ne déclenche pas immédiatement un Run manuel.

La sortie initiale de la console peut être invisible si le transport de débogage est déconnecté ; vérifiez l’état APP/lastError. Un programme peut rester en cours après un seul console.log, car l’environnement d’exécution attend les événements futurs.

21. Protocole APP pour les clients et Scale Monitor

Le téléversement ne nécessite aucun nouveau canal de communication. Utilisez le chemin de commande authentifié existant. Il s’agit d’un protocole pour les clients de gestion externes, pas de fonctions que l’application JavaScript peut appeler elle-même.

Tableau 87

Transport

Requête

Réponse

HTTP/HTTPS interne

Authentifié POST /api/cmd, Content-Type : text/plain ; corps APP <JSON>. Utilisez la session de connexion existante de l'appareil.

Objet JSON ; vérifiez ok, pas seulement le statut HTTP.

BLE

Caractéristique de commande existante et commande APP <JSON> encadrée avec les identifiants. Utilisez la même file d’envoi/fragmentation que les autres commandes.
Canal de notifications existant, APP <JSON> avec sortie de débogage entrelacée possible.

MQTT

Topic CMP/RX existant de l’appareil. DATA contient le Base64 de la requête JSON UTF-8 complète. Publiez avec retain=false.

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

Conservez les contrôles MID/identifiants existants et l’authentification MQTT. Les commandes APP conservées via retain sont rejetées. Le téléversement MQTT est distinct de l’utilisation de MQTT dans JavaScript. Le JSON décodé de la requête APP mesure au maximum 2048 octets.

21.1 Transfert de fichiers

Envoyez stop et vérifiez busy=false avec status avant de commencer. Calculez size et SHA-256 sur les octets d’origine du fichier. Effectuez ensuite begin → séquence de chunk → commit → status. Attendez chaque réponse de chunk ; n’envoyez pas tous les chunks simultanément.

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

Il s’agit d’un schéma de message, pas d’un transfert prêt à envoyer : remplacez size, hash, uploadId et data par les valeurs réelles. begin renvoie uploadId, offset=0 et chunkSize=768. Offset est une position en octets ; découpez les octets avant l’encodage Base64. L’interface BLE existante utilise 192 octets source par requête APP et fragmente ensuite les messages encadrés avec identifiants en écritures GATT.

Tableau 88

Opération

Paramètres en plus de op/rid

Résultat / conditions

begin

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

Crée une session ; renvoie uploadId, offset et chunkSize. Nécessite au moins size × 2 + 4096 octets libres de stockage. Abandonnez d’abord toute autre session active.

chunk

uploadId, offset:integer, data:base64

1–768 octets décodés. Renvoie le décalage total confirmé. Un morceau précédent ne peut être répété qu'avec des octets identiques entièrement compris dans la plage confirmée.

commit

uploadId

Autorisé après l’arrivée de tous les octets. Lance la validation SHA/syntaxe et l’activation asynchrones ; ok=true ne confirme pas la fin de l’activation. Interrogez périodiquement status jusqu’à busy=false.

abort

uploadId

Supprime le fichier et la session intermédiaires. Autorisé lorsqu'il n'est pas occupé. Les sessions appartenant à d'autres transports ne peuvent pas être reprises en utilisant uniquement uploadId.

configure

name, version, autorun:boolean

Modifie tous les attributs existants de l’application et lance la validation/activation asynchrone. Nécessite une application installée, aucun téléversement actif et busy=false.

run

—

Démarre l’application installée et renvoie state. Le téléversement doit être terminé/abandonné et busy=false.

stop

—

Annule le démarrage automatique en attente et demande l’arrêt. L’accusé confirme l’acceptation de la commande ; interrogez périodiquement status pour vérifier la fin.

status

—

État actuel, attributs installés, erreur et récupération. Également autorisé pendant l'exécution.

delete

—

Supprime l’application active, sa sauvegarde, les fichiers intermédiaires et l’enregistrement de récupération. Arrêtez d’abord l’application et abandonnez tout téléversement.

Vérifiez le booléen ok dans chaque réponse. Un échec renvoie ok=false et le texte error, distincts de error.code des Promise JavaScript. rid facultatif est un ID textuel de corrélation jusqu’à 64 octets. Réessayez un ID uniquement avec un JSON identique ; des contenus différents sous le même ID sont rejetés. Le cache des modifications réussies ne conserve que les six dernières requêtes par processus, sans garantie persistante d’une exécution exactement une fois. Pour les chunks, utilisez uploadId/offset et les octets confirmés.

Une session appartient à son transport initial et à uploadId et peut expirer après 5 minutes d’inactivité. Après une réponse perdue, examinez status/received ; ne devinez pas les positions. Un échec de hachage/syntaxe n’est pas une installation réussie. Après commit, vérifiez name/version/sha256 et lastError.

21.2 État et fin de l'opération

{
  "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’exemple est illustratif ; lisez les valeurs réelles. State peut être empty, ready, validating, running, stopped, error ou blocked. Busy vaut aussi true pendant une exécution normale prolongée. Pour la fin de la validation, attendez busy=false et examinez lastError et l’identité du code installé. Pour Run, vérifiez running et surveillez les échecs ultérieurs. Les données de récupération lastState et lastResetReason sont des diagnostics du firmware, pas l’état du protocole métier.

Tableau 89

Exemple d'erreur APP

Signification / réponse du client

BUSY

Envoyez stop et attendez la fin ; interrogez périodiquement status pendant la validation.

Invalid APP JSON

JSON invalide ou la demande dépasse 2048 octets.

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

Vérifiez les longueurs UTF-8, le booléen autorun, hash et size.

Invalid upload session

uploadId incorrect, transport ou session expirée.

Invalid offset / Overlapping chunk / Duplicate chunk differs

Alignez offset sur received confirmé ; ne modifiez pas le fichier pendant le transfert.

Upload incomplete

Commit envoyé avant l’arrivée de tous les octets.

Insufficient filesystem space

Espace insuffisant pour un transfert et un remplacement en toute sécurité.

No application installed

Run/configure sans application installée.

Application storage not ready / Task allocation failed…

Stockage ou RAM pas prêt ; inspecter l’état/les journaux et les diagnostics de l’appareil.

La liste des erreurs textuelles n’est pas exhaustive. Conservez error/lastError complets dans les diagnostics client. Un délai dépassé côté client externe ne prouve pas un rejet de l’appareil.

22. Démarrage automatique et protection contre les plantages

Avant le démarrage, Neutron AppEngine stocke l'identité de l'application et surveille le succès du démarrage. Un redémarrage inattendu de l'appareil pendant cette période enregistre une tentative instable au prochain démarrage. Après trois tentatives instables consécutives, l'exécution automatique est bloquée avant une quatrième tentative automatique. Le code reste stocké pour inspection ou remplacement.

Des réinitialisations inattendues dues à des pannes du système ou à des problèmes d'alimentation peuvent augmenter le compteur de tentatives instables. La mise sous tension normale et les redémarrages planifiés sont traités différemment des pannes d'application. Une tentative instable ne prouve pas à elle seule un défaut du code utilisateur ; inspectez également les diagnostics de l’appareil.

Environ 60 s de fonctionnement confirmé effacent la séquence d’échecs, en incluant l’attente normale d’événements plutôt que le seul temps CPU. Un Stop normal ferme le marqueur. Un blocage Auto run existant reste jusqu’à une installation explicite réussie ou Save attributes/configure. Le Run manuel reste possible et est surveillé. Un échec d’enregistrement de la récupération peut empêcher Run par protection.

Une erreur JavaScript ordinaire non gérée arrête l’application et définit lastError ; elle diffère d’une réinitialisation du module. Factory default supprime le code installé, sa sauvegarde, les fichiers temporaires, l’état de récupération et le stockage de l’application, y compris les bases locales. try/catch JavaScript ne peut pas empêcher une réinitialisation matérielle.

23. Règles pour ScaleGuru AI et les intégrateurs

Utilisez cette section comme contrat de génération d’applications. ScaleGuru AI doit renvoyer un fichier .js UTF-8 complet et lister séparément la configuration système et les étapes de test nécessaires. La documentation n’autorise pas automatiquement l’IA à téléverser ou exécuter du code sur l’appareil d’un utilisateur.

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

23.1 Tests avant la sortie de l'application

Tableau 90

Test

Résultat attendu

Appareil sans mesure valide

Aucune exception incontrôlée ; l'application signale clairement une mesure indisponible.

Plusieurs commandes en une seule réception

Gérez chaque commande ; envisagez l’ordre des réponses pour les commandes asynchrones.

Balance occupée / opération rejetée

Le rejet attendu est traité sans tentatives infinies.

Stop sans temporisateurs actifs

L’environnement d’exécution inactif se réveille et se termine normalement.

Redémarrer avec exécution automatique

La version installée validée démarre ; lastError et les données de récupération sont examinés.

24. Révisions et documentation associée

Tableau 91

Manuel

Date

Changements

1.0

15. 11. 2026

Première version de l’API : environnement d’exécution, balance, E/S, paramètres du module, fichiers, base locale, TCP, interfaces série, MQTT, REST/HTTP, protocole APP et protection au démarrage.

Documentation associée : CSCP — protocole de communication Neutron. CSCP décrit les commandes et la configuration système ; celles-ci ne deviennent pas automatiquement des fonctions JavaScript. Cette référence suit l’objectif, la syntaxe, les paramètres, le résultat, les erreurs et l’exemple.

Les exemples sont inclus sous forme de code statique et restent lisibles sans JavaScript. La recherche de pages, la copie de code et l'impression sont des outils de documentation ; ils n'exécutent pas d'applications et ne communiquent pas avec un appareil. La documentation n'est pas intégrée au firmware.

Questions fréquentes

Puis-je utiliser Node.js, npm ou les API du navigateur ?

Non. Téléversez un seul script JavaScript UTF-8 et utilisez les API neutron-js-1 documentées. Node.js, npm, le DOM, import/export et await au niveau supérieur ne sont pas disponibles.

Comment vérifier les fonctionnalités disponibles ?

Appelez app.capabilities() sur l’appareil. Vérifiez apiVersion, interpreterVersion, features et les limites propres au module avant d’utiliser une fonction.

Les données de l’application sont-elles conservées après Stop et un redémarrage ?

Les variables JavaScript ne sont pas conservées. Les fichiers et les bases locales d’enregistrements dans storage persistent après Stop, un redémarrage et un remplacement normal de l’application. Factory default supprime ces données.

Quand dois-je activer Auto run ?

Téléversez d’abord l’application, exécutez-la manuellement et testez le comportement requis, les limites et les cas d’échec. Activez Auto run uniquement après les tests fonctionnels. La protection au démarrage peut bloquer des démarrages automatiques instables répétés.

Besoin d’aide ?

Besoin d’aide pour logiciel, connectivité ou utilisation ? Décrivez le problème pour que nous aidions à la prochaine étape.

Préparer une demande →