Skip to main content
Per abilitare l’apertura remota tramite SwitchBot, hai bisogno del token owner e del Device ID dall’account SwitchBot dello studente, segui questi passaggi nell’ordine esatto. Un errore nell’ordine o l’uso dell’account sbagliato causa il fallimento silenzioso dei comandi, spesso senza un messaggio di errore chiaro.

​
Prerequisiti

Prima di iniziare, verifica che siano tutti attivi:
  • Hub Mini online: LED frontale BLU fisso (non giallo, non rosso)
  • Serratura entro ~5 metri dall’Hub Mini: verifica la posizione fisica
  • Cloud Service attivo sulla serratura nell’app SwitchBot (Smart Lock → Cloud Service → attivo)

​
Collegamento

1

Abilita la modalità sviluppatore in SwitchBot

Lo studente apre l’app SwitchBot, va su Profilo → Preferenze → Informazioni app e tocca il logo SwitchBot 5 volte consecutive per abilitare le Developer Options. Poi va su Profilo → Developer Options e attiva la modalità sviluppatore.
2

Copia il Token e il Client Secret

In Developer Options, copia il Token (stringa lunga) e il Client Secret. In parole semplici: il Token identifica l’account (dice “sono io”); il Client Secret firma ogni richiesta in modo sicuro (dimostra che è davvero autorizzata). Servono entrambi per comandare la serratura.
3

Individua il Device ID della serratura

Nell’app SwitchBot, vai su Dispositivi, seleziona la Smart Lock e annota il Device ID visibile nelle impostazioni del dispositivo (di solito una stringa alfanumerica maiuscola).
4

Verifica Hub Mini e Cloud Service

Controlla che il LED dell’Hub Mini sia BLU fisso e che il Cloud Service sulla serratura sia attivo. Questi due controlli devono passare prima di procedere, altrimenti il test fallirà con errore 161.
5

Invia le credenziali in modo sicuro al team Mattone

Lo studente invia Token + Client Secret + Device ID al team Mattone tramite il canale sicuro concordato. Mai via email ordinaria, chat non cifrata o documenti condivisi.
6

Salva le credenziali nel Vault

Il team Mattone salva le credenziali cifrate nel Vault, associate alla proprietà dello studente. Nessun membro del team deve conservarle in locale o in strumenti non approvati.
7

Aggiungi il device in piattaforma

Nella piattaforma Mattone, vai su Devices → Aggiungi SwitchBot. Inserisci il Token, il Client Secret e il Device ID, quindi salva la configurazione.
8

Test di apertura e lettura dei log

Esegui un’apertura di test dalla piattaforma. Leggi i log immediatamente dopo, un errore 161 indica Hub Mini offline, non un problema di credenziali. Il log deve mostrare una risposta di successo senza codici di errore.
Usa SEMPRE l’account OWNER della Home SwitchBot, l’account member non ha i permessi necessari per il controllo remoto tramite API. Un token generato da un account member non produrrà un errore esplicito in fase di configurazione, ma il comando di apertura fallirà silenziosamente.
Se il LED dell’Hub Mini non è BLU, il comando non raggiunge la serratura, qualunque test effettuato restituirà errore 161 (device offline). Verifica il LED e la connessione WiFi 2.4GHz prima di eseguire qualsiasi test.

​
Verifica

Dopo il collegamento, controlla che tutto funzioni:
  • Il device appare come online nel pannello Devices della piattaforma
  • Il test di apertura sblocca fisicamente la serratura
  • I log mostrano una risposta di successo, nessun errore 161, nessun 401
▷ Prompt Claude Code: Collega una serratura SwitchBot · incolla in Claude Code:

SwitchBot API (docs)

Token/Secret + comandi

Troubleshooting 161

Owner vs member, codici