Prerequisiti
Prima di iniziare, assicurati che siano tutti soddisfatti:- Device Shelly fisicamente installato sulla porta o citofono dell’immobile
- Account Shelly Cloud creato dallo studente e associato al device
- Device visibile come online nell’app o nel portale Shelly Cloud
Collegamento
1
Lo studente recupera Server e Auth Key
Su my.shelly.cloud → User settings → Authorization cloud key: lì ci sono sia la Auth Key sia il Server dell’account (tipo
shelly-99-eu.shelly.cloud). Un account Shelly = un Server + una Auth Key, per tutti i suoi dispositivi.2
Lo studente recupera l'ID di ogni dispositivo
In Shelly Cloud, per ogni dispositivo: Settings → Device Information → Device ID (lettere e numeri). Accanto a ogni ID, il nome dell’appartamento che apre: è il nome con cui l’assistente lo cercherà.
3
Lo studente crea il canale Slack per gli avvisi
Obbligatorio per tutti: quando una porta va offline, l’avviso arriva sul suo Slack. Come si crea il link: Avvisi offline.
4
Invio sicuro al team Mattone
Auth Key, Server, elenco dispositivi e link Slack arrivano al team dal canale sicuro concordato, mai in chat ordinaria, email non cifrata o documenti condivisi.
5
Il team collega Shelly in piattaforma
Nella sezione admin della piattaforma, card «🔐 Shelly (smart-lock / apertura porte)» → «+ Nuovo cliente Shelly»: studente, Auth Key, Server, dispositivi, link Slack. I dispositivi si scrivono così:La piattaforma rifiuta i dati che poi non funzionerebbero: nessun dispositivo, ID non valido, due appartamenti con lo stesso nome, un server che non è Shelly, un link Slack non valido.
6
La piattaforma verifica davvero
Al salvataggio la piattaforma legge la configurazione come la leggerà l’assistente e interroga il primo dispositivo con la chiave dello studente; poi manda un messaggio di prova sul canale Slack. «connected» vuol dire che l’assistente può usarla davvero. Se il dispositivo è offline risulta collegato, con la nota. Se esce un errore: Troubleshooting.
7
Test di apertura reale
Un’apertura vera, con qualcuno presente all’immobile, per confermare che si apre la porta giusta.
In parole semplici: il Server dice dove sta l’account Shelly e la Auth Key autorizza ad aprire il relè (l’interruttore che apre porta/citofono) di quell’account. Senza, l’apertura è negata.Come è fatto davvero. Shelly Cloud lavora per account: ogni account ha un Server (
shelly-<NN>-eu.shelly.cloud) + una Auth Key. Per gli studenti questi dati si salvano cifrati dalla piattaforma e il nostro ponte li usa quando l’assistente lavora; per Cosmica i device stanno nel registro codice SHELLY_DEVICES (src/lib/shelly.ts), 1 riga per device (slug, deviceId 12-hex, tipo citofono/porta, account). L’apertura è un impulso al relè: POST /device/relay/control con timer=3 (acceso 3 sec poi si spegne). Stato: POST /device/status. Limite: 1 richiesta/sec per account.Verifica
Dopo il collegamento, controlla che tutto funzioni correttamente:- La card Shelly in piattaforma mostra lo studente connected
- Nel canale Slack dello studente è arrivato il messaggio di prova «✅ Avvisi Shelly collegati»
- Il test di apertura attiva fisicamente il relay (la porta o il citofono risponde)
- I log mostrano una risposta di successo, senza codici di errore
Shelly Cloud
Device → Settings → Device Information (deviceId)
Troubleshooting Shelly
Relay offline / non apre