Sviluppo dispositivi di controllo

Per registrarsi come sviluppatore di dispositivi di controllo:

1. Accedi al tuo account Realer.
2. Clicca in alto a destra in qualsiasi pagina di Realer e seleziona Account.
3. Clicca su Registrati come sviluppatore dispositivi di controllo.
   Se sei già registrato come sviluppatore, vedrai Account sviluppatore dispositivi di controllo.
4. Fornisci i dettagli del tuo account sviluppatore es. nome aziendale, logo e sito web.
5. Clicca su Registrati come sviluppatore.

Per procurarti le chiavi API di un dispositivo di controllo:

1. Vai alla pagina del tuo account sviluppatore su Realer.
   È necessario essere registrato come sviluppatore di dispositivi di controllo.
2. Dalla pagina del tuo account sviluppatore, clicca Nuova licenza sviluppatore.
3. Scegli il piano di abbonamento per il dispositivo di controllo che vuoi sviluppare e clicca sul pulsante corrispondente con il prezzo.
4. Segui le istruzioni a schermo per effettuare il pagamento.

Dopo il checkout, Realer ti reindirizza alla pagina del dispositivo di controllo contenente le chiavi API generate. Conserva client_id e client_secret in modo sicuro; il firmware le usa all'endpoint token OAuth per ottenere token di accesso per le chiamate API del dispositivo.

Pianifica prima l'integrazione, poi sviluppa il firmware usando la documentazione API di Realer. La documentazione API definisce i contratti esatti di autenticazione OAuth con credenziali client, bootstrap runtime, catalogo, desired-state, feed-data, payload MQTT, campi e codici di risposta.

Usa la guida di pianificazione dell'integrazione per confermare il percorso runtime: polling HTTPS o messaggistica broker MQTT su TLS. Poi usa la pagina introduttiva della documentazione API quando sei pronto per implementare.

Prima di scrivere il firmware, decidi cosa controlla o osserva fisicamente il dispositivo, come si connette a Internet, a quale record dispositivo di controllo Realer appartiene e quale capacità runtime userà.

• Crea o seleziona il record dispositivo di controllo e ottieni le chiavi API per il provisioning del firmware.
• Conferma il percorso runtime assegnato al dispositivo. Un dispositivo usa un solo percorso runtime: polling HTTPS o messaggistica broker MQTT su TLS. Usa la pagina runtime della documentazione API per la suddivisione esatta.
• Pianifica subito la gestione dei token OAuth. Il firmware si autentica come dispositivo tramite credenziali client OAuth, poi legge il descrittore di bootstrap runtime prima del lavoro API protetto.

La guida di pianificazione dell'integrazione copre il percorso decisionale. Usa la pagina introduttiva della documentazione API quando ti servono i riferimenti esatti per implementare.

L'intento di utilizzo indica a Realer come un dispositivo di controllo dovrebbe essere usato prima di avviare aggiunte, aggiornamenti o ritiri del setup.

Usa questa checklist se hai dubbi:

• Se il dispositivo e' pensato per spostarsi tra risorse o clienti, scegli standalone riutilizzabile.
• Se rimuovere il dispositivo cambierebbe l'asset o prodotto fisso a cui appartiene, scegli integrato fisso.
• Se l'uso reale cambia in seguito, Realer puo' richiedere revisione o riclassificazione invece di cambiare silenziosamente la classificazione.

L'intento di utilizzo e' solo classificazione. Non concede controllo della risorsa, supporto tecnico, supporto operativo, accesso firmware, credenziali, segreti, diagnostica, billing, dashboard o approvazione marketplace.

Dopo aver scelto l'intento, torna alle modifiche setup. Prima di collegare apparecchiature reali, rivedi i test sicuri del firmware.

Progetta il contratto del dispositivo prima di codificare il ciclo firmware. Decidi quali uscite sono comandi, quali ingressi sono sensori, come applicare le richieste desired-state di Realer e quali valori il dispositivo deve riportare.

• Usa il bootstrap runtime all'avvio e la documentazione API del catalogo dispositivo per capire come Realer rappresenta il setup attivo di comandi e sensori.
• Usa la documentazione API dei feed-data per distinguere report di stato comando e letture sensore.
• Scegli unità di misura e contesti di quantità significativi per i valori numerici.
• Tieni separato il testo dell'interfaccia dagli identificatori firmware: le righe di risorse e dashboard usano etichette di riga, mentre la descrizione di un sensore è un dettaglio UI aggiuntivo. Il firmware dovrebbe usare campi tecnici del catalogo come tipo, contesto della grandezza, unità di misura e pin o porta.

Mantieni la progettazione di comandi, sensori, desired-state e feed-data al livello della guida. Usa semantica dei campi per regole di retry, ordinamento, correlazione, scadenza e gestione dei risultati.

Usa le modifiche setup quando un dispositivo di controllo deve aggiungere, aggiornare o ritirare setup di attuatori o sensori. Una modifica setup viene revisionata prima di diventare setup attivo.

• Un proprietario o amministratore del dispositivo parte dalla pagina del dispositivo di controllo, apre Modifiche setup del dispositivo di controllo, sceglie l'azione disponibile, spiega il motivo e invia il pacchetto di modifica setup.
• Uno sviluppatore può proporre solo le modifiche setup consentite dal suo ruolo corrente o dall'accesso al supporto tecnico. Un proprietario/admin del dispositivo di controllo, oppure una revisione limitata dello staff Realer quando richiesta, accetta le modifiche setup prima che vengano applicate. La storia della chat di supporto è evidenza utile, ma non è autorità da sola.
• Realer ricontrolla il dispositivo di controllo corrente, il setup selezionato, il tipo dispositivo, i limiti del piano e l'accesso al supporto tecnico prima che un pacchetto inviato possa essere accettato da un proprietario/admin o reviewer staff autorizzato.
• Un'aggiunta accettata crea solo setup del dispositivo di controllo. Un aggiornamento modifica solo i campi setup supportati, mentre Ritira setup rimuove il setup selezionato dal setup attivo senza cancellarne la storia.

Le modifiche setup non concedono controllo della risorsa, scritture di comando, accesso alla telemetria, segreti API, accesso billing, appartenenza dashboard, aggiornamenti firmware, supporto marketplace o eliminazione definitiva. Usare nuovo setup su una risorsa richiede approvazione separata da un amministratore della risorsa.

Se Realer chiede prima l'intento di utilizzo, usa la guida sull'intento di utilizzo per scegliere tra standalone riutilizzabile e integrato fisso.

Prima di proporre setup, progetta i comandi, le misurazioni e i feed-data che il dispositivo deve esporre.

Usa una correzione assistita del setup quando l'ultimo aggiornamento setup esatto accettato contiene un valore supportato da correggere. Realer deriva un nuovo pacchetto di modifica setup dall'evidenza accettata e dal setup corrente; non modifica la storia già accettata.

Per preparare la correzione:

1. Apri le modifiche setup e la storia dei pacchetti del dispositivo di controllo. Trova l'ultimo aggiornamento accettato per l'esatto setup attuatore o sensore, poi scegli Valuta correzione assistita.
2. Controlla i valori correnti e quelli corretti proposti. Un aggiornamento singolo produce un solo target esatto. Un aggiornamento multi-elemento accettato produce il suo intero set esatto originale; non puoi selezionarne un sottoinsieme.
3. Spiega perché l'aggiornamento deve essere corretto e prepara il nuovo pacchetto. La preparazione registra una proposta; non modifica il setup attivo.
4. Un revisore autorizzato accetta il pacchetto dopo che Realer ha ricontrollato ogni target e campo. Una correzione multi-elemento è atomica: se un elemento non supera la verifica, non viene applicato alcun elemento.

Chi può preparare e accettare il pacchetto:

• Per un dispositivo standalone riutilizzabile, un proprietario del dispositivo di controllo o un amministratore del dispositivo di controllo può prepararlo e accettarlo dalla pagina pubblica delle modifiche setup. Se la stessa persona è anche sviluppatore, l'accettazione usa comunque l'autorità di amministratore del dispositivo di controllo.
• Per un dispositivo standalone riutilizzabile, un utente che è solo sviluppatore deve avere una delega Technical Support corrente per l'aggiornamento di quello specifico setup (setup_update) per preparare la proposta. La delega non permette di accettarla; deve farlo un proprietario o un amministratore del dispositivo di controllo.
• Per un dispositivo integrato fisso, l'accettazione usa la pagina di revisione Realer riservata allo staff. La revisione staff non è un sostituto generale dell'amministratore del dispositivo di controllo nel percorso pubblico.

Realer blocca la correzione assistita quando non può più provarne la sicurezza in modo esatto, incluso quando:

• la sorgente non è più l'ultimo aggiornamento accettato per ogni target esatto, oppure un target non è più attivo;
• i valori correnti non corrispondono più ai valori successivi all'aggiornamento accettato, oppure è cambiata la struttura del target, come identità, tipo, pin o porta, stato del ciclo di vita o semantica del valore non correggibile;
• un altro pacchetto aperto su cui è ancora possibile intervenire copre già un target esatto, oppure l'autorità corrente, l'accesso Technical Support o la classificazione di utilizzo non consentono più la correzione.

La correzione assistita modifica solo i campi di aggiornamento supportati. Non è un ripristino da snapshot né un rollback strutturale, non inverte aggiunte o ritiri del setup e non modifica firmware, hardware, autorità o stato della risorsa, telemetria live, né invia una richiesta di comando. Snapshot e storia restano solo evidenza.

Usa la guida alle modifiche setup per il normale flusso dei pacchetti. Prima di applicare setup vicino ad apparecchiature reali, rivedi i test sicuri del firmware.

Testa il firmware in un ambiente controllato prima di collegarlo ad apparecchiature reali o esporlo ad altri utenti. Un dispositivo di controllo Realer può influenzare attuatori, sensori e sistemi critici per la sicurezza.

• Tieni le chiavi API fuori da repository pubblici, log, codice lato client e screenshot condivisi.
• Usa hardware isolato, carichi simulati o uscite disabilitate quando validi gestione dei comandi e reporting dei feed-data.
• Verifica il fallback locale per perdita di Internet, credenziali scadute, risposte API rifiutate e disconnessioni broker prima dell'uso in produzione.

Per la base di sicurezza, leggi la responsabilità dello sviluppatore prima dei test live.

Il firmware dovrebbe trattare Realer come un piano di controllo cloud che può essere temporaneamente non disponibile, rifiutare dati non validi o smettere di accettare operazioni cloud quando abbonamento o credenziali non sono più attivi.

• Per risultati HTTPS rifiutati, usa codici di risposta e semantica dei campi per decidere se ritentare, ignorare, riconciliare o entrare in comportamento locale sicuro.
• Per errori di autenticazione, bootstrap e runtime MQTT, rinnova token OAuth e credenziali MQTT a breve durata tramite i flussi documentati in autenticazione e flusso MQTT.
• Per perdita di abbonamento o entitlement, aspettati l'interruzione dell'accesso API cloud e segui la guida sulla fine dell'abbonamento.

La guida sulla gestione degli errori API copre il comportamento del firmware. Usa la documentazione API per contratti esatti di richiesta, payload e risposta.

Il riferimento sulle unità di misura aiuta quando un valore numerico di comando o sensore necessita dell'unità di misura corretta.

Il riferimento sui contesti di quantità aiuta quando un valore numerico necessita del significato fisico o di dominio corretto.