Variabili di telemetria

Le variabili di telemetria (nella UI: tab Telemetria) definiscono quali dati un asset del template espone: chiave, tipo, unità, storico, visualizzazione in lista, scrivibilità e mappature.

Sono separate dalla Connettività IoT e dai Metadati: la connettività dice come arrivano i messaggi; i metadati sono informazioni statiche; le variabili di telemetria dicono quali campi live leggere (e scrivere) da quei messaggi.

Restano "vuote" finché un asset non è collegato a un device fisico (vedi Collegare un device).

Se la connettività è MQTT, il profilo (Generico, Seneca, Siemens Logo, Teltonika RutOS) cambia quali opzioni vedi su ogni campo, come Spaces propone le chiavi dal payload e come viene costruito il messaggio di scrittura. Vedi Profili MQTT e campi di telemetria.

Opzioni di una variabile

Per ogni campo in Telemetria puoi configurare:

Opzione	Effetto
Chiave	Identificativo del campo nel datastore e, di default, nel payload. Puoi cambiarla in conferma del rilevamento: sul filo resta la posizione nel messaggio.
Etichetta	Nome visualizzato in UI
Tipo	Boolean, Number o String
Unità	Es. °C, %, bar
Min / Max / Step	Vincoli per valori numerici (e per widget Slider)
Salva storico	Conserva i punti nel tempo (Trend, grafici, retention del piano)
Mostra in lista	Colonna nella lista asset; regole di formattazione (operatore, etichetta, icona, colore)
Scrivibile	Consente scrittura dal dettaglio asset e da widget Button/Slider/Switch
Template payload di scrittura	Solo MQTT Generico e Teltonika, e solo se il campo è scrivibile. JSON pubblicato su MQTT per questo campo. Vedi sotto.
Mappatura valori	Valore grezzo → etichetta (e, in lista/widget, icona/colore)
Posizione nel messaggio (path)	Percorso nel payload JSON. Identifica il campo sul filo anche se rinomini la chiave.

Puoi dichiarare i campi a mano in fase di creazione/modifica del template, oppure lasciarli emergere dalla scoperta telemetria.

Scoperta telemetria

Se il device invia chiavi non ancora dichiarate nel template, Spaces le propone nel pannello Rilevamento telemetria (aggiornato periodicamente), sul dettaglio asset o dal template.

Per ogni campo in attesa puoi:

1. Vedere un valore di esempio e dove si trova nel messaggio (percorso nel JSON).
2. Impostare chiave (puoi rinominarla rispetto a quella proposta), etichetta, tipo, unità, storico, show-in-list, scrivibile.
3. Usare Suggest AI metadata per una proposta automatica (una volta per set).
4. Confermare (aggiunge il campo al template, quindi a tutti gli asset di quel tipo), Ignorare o Ignora tutti.

La chiave confermata è il nome che userai in dashboard, allarmi e scritture. La posizione nel messaggio resta quella scoperta: Spaces continua a leggere (e, se serve, a scrivere) lo stesso punto del JSON anche se hai scelto una chiave più leggibile.

Sul template, in Telemetria, puoi abilitare/disabilitare il rilevamento automatico dei campi. Se è spento, le chiavi sconosciute vengono ignorate. Solo gli Admin gestiscono la discovery.

suggerimento

Con payload JSON annidati o a formato libero, abilita il rilevamento automatico: Spaces propone i path dei campi e tu li confermi come variabili di telemetria.

Variabili scrivibili

Se una variabile è scrivibile, dal tab Parametri (o da widget dedicati) puoi inviare un nuovo valore al device tramite la Connettività IoT configurata sul template.

Per MQTT, il messaggio pubblicato dipende dal profilo e, se presente, dal template di scrittura del campo. L'ordine è:

1. Template payload di scrittura del campo, se compilato (Generico e Teltonika).
2. Altrimenti, per il profilo Generico, il template payload del template.
3. Altrimenti il payload definito dal profilo (Seneca, Siemens Logo).
4. Se non c'è nessun template, viene pubblicato solo il valore grezzo (la chiave è già nel topic).

Placeholder accettati nei template:

Placeholder	Sostituzione
{{key}}	Chiave della variabile (quella confermata, non necessariamente il nome sul filo)
{{value}}	Valore come testo semplice
{{json_value}}	Valore codificato JSON (22.5, "auto", true)
{{random}}	Un intero casuale, uguale per tutte le occorrenze nello stesso messaggio (utile come cookie/id di correlazione)

Profili MQTT e campi di telemetria

Il profilo si sceglie in Connettività IoT. Qui sotto cosa cambia sui campi.

Profilo Generico

• In Telemetria, ogni campo scrivibile mostra Template payload di scrittura.
• Se lo lasci vuoto, vale il template (o il valore grezzo) configurato sul template.
• Se lo compili, quel campo pubblica il suo JSON e ignora il template di template.
• Il rilevamento propone le chiavi così come arrivano nel JSON (oggetti, array, tabelle chiave/valore).

Esempio di template sul campo:

{"cmd": "{{key}}", "val": {{json_value}}}

Profilo Seneca

• Il campo Template payload di scrittura non compare: ogni write usa { "value": <valore> }.
• I comandi remoti (reboot, VPN, …) non sono campi: stanno sullo scambio dati dell'asset.
• Il rilevamento usa i nomi che il device pubblica (di solito il campo name del payload Seneca).

Profilo Siemens Logo

• Il campo Template payload di scrittura non compare: Spaces pubblica già nel formato atteso dal LOGO, ad esempio:

{"state": { "Nome_Tag": {"value": [1]}}}

Nome_Tag è la chiave della variabile ({{key}}); il valore scritto va in value[0].

• In rilevamento Spaces:
  • ignora i wrapper desc e name (non diventano campi da confermare);
  • propone come chiave il nome del tag (primo segmento del percorso), anche se il valore sta in value[0].

Esempio. Il LOGO pubblica:

{
  "Nome_Tag": {
    "desc": "Temperatura serbatoio",
    "value": [22.5]
  }
}

Spaces propone un campo in attesa: chiave Nome_Tag, posizione ["Nome_Tag"]["value"][0], valore 22.5. Non propone desc. Puoi confermare la chiave così com'è o rinominarla (es. temperatura): in lettura Spaces continua a usare il path; in scrittura usa la chiave confermata dentro state.

Profilo Teltonika RutOS

• In Telemetria, ogni campo scrivibile mostra Template payload di scrittura (JSON Modbus/MQTT di Teltonika).
• Non esiste un template di scrittura a livello di template: o lo compili sul campo, o Spaces lo precompila dal rilevamento.
• Payload a record nominati (array di oggetti con name / key e una lettura scalare data / value / v / state): ogni riga diventa un campo. Se la riga ha anche ip, server_id e full_addr, Spaces riempie il JSON di scrittura, ad esempio:

{"cookie":{{random}},"type":0,"host":"192.168.1.127","port":502,"server_id":1,"timeout":5,"function":6,"register_number":3,"value":{{value}}}

full_addr in notazione Modbus 400003 diventa il registro 3. {{random}} è il cookie della richiesta; {{value}} è il valore che invii dal tab Parametri.

• Oggetti I/O singoli (formato libero, senza riga di collection): il rilevamento crea comunque il campo, ma non precompila il template. Lo inserisci a mano sul campo, dopo averlo reso scrivibile.
• Una volta confermata la variabile, i messaggi successivi non sovrascrivono il template di scrittura. Se cambia l'indirizzo Modbus, aggiorna il JSON sul campo.

:::note Pannello rilevamento Nel pannello dei campi in attesa il template di scrittura non è editabile. Per Teltonika viene comunque salvato in background e copiato sulla variabile quando confermi. Lo rivedi e lo modifichi in Telemetria, dopo la conferma, se il campo è scrivibile. :::

Prossimi passi

• Connettività IoT
• Metadati
• Creare asset
• Collegare un device
• Pagina di dettaglio asset