Manuale minimo

L'uso di Shelly Scanner è piuttosto intuitivo; in questa pagina sono comunque raccolte le informazioni essenziali.
Di seguito l'elenco dei bottoni che compongono la toolbar con la premessa che alcune funzioni si applicano esclusivamente ad un singolo dispositivo, altre anche a più dispositivi contemporaneamente; le prime si distinguono in quanto le rispettive icone sono disabilitare nel caso in cui sono selezionati più dispositivi sulla tabella:

Riesegue la scansione della rete alla ricerca dei dispositivi connessi.
Aggiorna immediatamente lo stato di tutti i dispositivi.
Apre una finesta che riporta le informazioni complete del dispositivo selezionato in formato json.
Apre una finesta che mostra i grafici relativi ai dispositivi selezionati. Qui la descrizione dettagliata della funzione.
Apre una finesta che riporta i log del dispositivo selezionato. I dispositivi di prima generazione consentono soltanto la visione di uno o due file di log (i log devono essere stati preventivamente abilitati dall'interfaccia web del dispositivo); al contrario i dispositivi di seconda generazione rendono disponibili i log in streaming e dalla finestra è possibile abilitare/disabilitare i log, bloccare temporaneamente (fino alla chiusura della finestra) i refresh di Shelly Scanner per il dispositivo (per interrompere la generazione dei relativi messaggi di log), selezionare il livello di log.
Apre una finesta che riporta una checklist relativa alla configurazione dei dispositivi selezionati cercando di identificare eventuali errori. Qui la descrizione dettagliata del contenuto della finestra.
Apre l'interfaccia grafica del dispositivo selezionato sul browser di sistema.
Esegue il backup della configurazione di uno o più dispositivi. Se sono selezionati più dispositivi l'applicazione chiede di selezionare una cartella dove salvare tutti i file che, in questo caso, assumono il nome di default. Se doveste avere l'esigenza di modificare le informazioni prima del ripristino, sappiate che i file di backup, con estensione sbk, sono in realtà un insieme di file di testo in formato json zippati; i backaup dei dispositivi di seconda generazione contengono anche gli eventuali scipt che però non sono ripristinati automaticamente (si veda la sezione dedicata agli script).
Attenzione: può accadere che aggiornando il firmware di un dispositivo i suoi file di backup diventino inutilizzabili.
Esegue il restore della configurazione del dispositivo selezionato. Il restore può essere effettuato su un dispositivo diverso da quello che ha generato il file di backup purché dello stesso tipo; in questo caso verrà chiesta conferma prima di procedere. Durante il processo di restore l'applicazione può chiedere, se necessario per il ripristino, le password di: restricted login, wi-fi1, wi-fi2, server mqtt. Non tutti i paramenti vengono ripristinati ma ad ogni avanzamento di versione se ne aggiungono di nuovi.
Apre una finestra dalla quale è possibile gestire globalmente alcune caratteristiche dei dispositivi selezionati al momento dell'attivazione di questa funzione. Per agevolare la selezione di tutti i dispositivi sono disponibili due pulsanti in basso a destra sulla barra di stato; per ovvi motivi le modifiche non hanno effetto sui dispositivi fuori linea. Nello specifico si possono gestire:
- Firmware update all'ultima versione stabile o alla beta corrente (da notare che mantenendo il puntatore del mouse su un numero di versione compare l'identificatico completo della versione stessa);
- WI-FI primario (1) e di backup (2)
  Se ci sono più dispositivi selezionati è possibile configurare soltanto connessioni con hdcp;
- Restricted login
  Se ci sono dispositivi di seconda generazione tra quelli selezionati il nome utente deve essere necessariamente "admin";
- configurazione MQTT
  I campi lasciati vuoti in questa sezione non vengono alterati sul dispositivo.
Gestione degli script e del Key Value Store (Dispositivi di seconda generazione o successiva). Si apre una finestra, inizialmente sulla sezione scripts, che da accesso ad un sistema di gestione completo descritto in una apposita pagina. Riguardo le coppie chiave valore è possibile effettuare:
- Creazione;
- Cancellazione;
- Editazione dei valori.
Riavvia (previa conferma) i dispositivi selezionati.
Attiva un editor con il quale è possibile scrivere note di testo per ogni singolo dispositivo (è necessario che l'archivio sia attivo).
Attiva la "vista completa": vengono visualizzate tutte le colonne informative; la finestra si ingrandisce, o resta invariata, secondo uno dei criteri definiti nei settings applicativi. Quando questa modalità è attiva il bottone diventa e consente di tornare alla tabella in forma standard.
Esporta i valori della tabella in un file in formato CSV.
Stampa la tabella.
Configurazione dell'applicazione. Si apre una finestra con tre sezioni dalle quali si personalizzano nell'ordine l'interfaccia utente, i parametri di connessione verso i dispositivi, l'archivio - o gli archivi - dei dispositivi rilevati. Da qui è possibile, per esempio, scegliere quali colonne visualizzare (nella vista standard o nella vista completa a seconda della modalità corrente), specificare la frequenza di aggiornamento, selezionare la modalità di connessione e definire i valori di default (utente e PIN) per l'accesso ai dispositivi protetti (attenzione: la password è memorizzata in maniera non sicura sul disco).
Fornisce informazioni sull'applicazione (contiene anche il link per caricare questa pagina).

Le contenuto delle colonne della tabella ha un significato generalmente evidente tuttavia alcune precisazioni possono risultare utili:

I simboli che possono apparire nella colonna Stato hanno i seguenti significati:
- On line;
- On line - reboot necessario (solo dispositivi di seconda generazione);
- Informazioni in aggiornamento;
- Dispositivo protetto, occorre effettuare il login (si può fare dal menu contestuale - tasto destro del mouse);
- Dispositivo non raggiungibile; il tootip fornisce il timestamp dell'ultima connessione eseguita con successo;
- Il dispositivo è in errore (nella maggior parte dei casi la causa è da attribuire ad un malfunzionamento dell'applicazione probabilmente determinato da un firmware non aggiornato).
- Dispositivo archiviato non ancora rilevato (rilevato in una precedente esecuzione); il tootip fornisce il timestamp dell'ultimo rilevamento (dal menu contestuale - tasto destro del mouse - è possibile rimuovere permanentemente il dispositivo dall'archivio);
Cloud (En/com) contiene una informazione duplice: abilitazione del cloud / effettiva connessione al cloud;
MQTT (En/com) contiene una informazione duplice: abilitazione della connessione MQTT / effettiva connessione al server;
Uptime è il tempo trascorso dall'ultimo avvio del dispositivo (o dall'aggiornamento del firmware) espresso, per default, in secondi (dai settings applicativi è possibile modificare il formato); il tooltip, che compare mantenendo il puntatore per qualche istante sul riquadro dell’uptime, dà lo stesso valore espresso in giorni, ore, minuti e secondi e come istante dell'ultimo avvio (Up from);
Il contenuto della colonna Command varia significativamente a seconda dispositivo associato; nel caso di dispositivi con input di tipo "interruttore" la scritta on/off all'interno del bottone rappresentato può essere nera o arancione; il secondo caso indica che il contatto dell'input è chiuso indipendentemente dallo stato del relè;
Il tootip della colonna Command, se non è visibile la colonna Source, consente di verificare a quale evento è attribuibile l’ultimo cambiamento di stato.

Qui sono descritti alcuni dettagli che ad un primo sguardo possono sfuggire e che di seguito vengono brevemente elencati:

Se l'applicazione non trova all'avvio tutti i dispositivi (tenendo conto che alcuni Shelly alimentati a batteria: Button 1, Flood, D&W, ... diventano visibili soltanto nel momento in cui si attivano) è probabile che il computer su cui gira Shelly Scanner ed i dispositivi non si trovino esattamente sulla stessa rete. In questo caso occorre configurare alcuni parametri applicativi dall'apposita finestra (attenzione: le modifiche di questi parametri sono applicate solo al successivo avvio dell'applicazione).
Nel caso in cui il computer ha più di una interfaccia di rete fisica o virtuale (VPN) è necessario configurare l'applicazione in modo che effettui il "full scan"; in questo caso, rispetto al "local scan", la ricerca dei dispositivi sarà lievemente più lenta.
Se i dispositivi si trovano su una rete separata (è, per esempio, il caso di una sottorete dedicata ai dispositivi domotici) occorre impostare lo "scan by IP" che però non consente il rilevamento di alcuni Shelly alimentati a batteria come Button 1, Flood e D&W.
In alternativa è possibile avviare l'applicazione da terminale chiedendole di ignorare le impostazioni correnti di scansione con la seguente riga di comando: java -jar <path completo>\shellyscan-x.x.x.jar aggiungendo il parametro -fullscan per utilizzare il "full mDNS scan", -localscan per il "local mDNS scan" oppure -ipscan x.y.z.a-b dove x.y.z è il prefisso della rete, a e b sono rispettivamente il primo e l'ultimo indirizzo da verificare (esempio: -ipscan 192.168.1.1-254).
Doppio click su una riga della tabella (ma non sulla colonna "Command") mostra le informazioni dettagliate del dispositivo corrispondente (equivale al click sul bottone della toolbar o del menu contestuale) oppure apre la pagina web dello stesso dispositivo sul browser di sistema ; questo comportamento è definito dalle impostazioni dell'applicazione.
Alcuni comandi eseguibili dalla toolbar possono essere applicati ad un solo dispositivo alla volta, altri invece hanno effetto su tutti i dispositivi selezionati. I bottoni sulla toolbar che funzionano su dispositivi multipli restano attivi quando è selezionato più di un dispositivo. Questo vale anche per la funzione "settings".
Cliccando su una riga della tabella con il tasto destro del mouse viene selezionato il dispositivo corrispondente e si attiva un menu contestuale che ripropone parte dei comandi accessibili della toolbar più il login attivo su dispositivi protetti per i quali non sono già state fornite le credenziali o, in alternativa, Il reload che ricarica interamente tutte le informazioni relative al dispositivo (compreso l'elenco di altri dispositivi eventualmente connessi ad esso in modalità range extender).
Il filtro per righe può essere usato con dei comandi da tastiera: ctrl-S cicla tra i valori della combo che consente di scegliere su quale colonna è effettuata la ricerca; ctrl-F seleziona il campo di testo sul quale digitare i caratteri per la ricerca; ctrl-E seleziona il campo di testo e lo svuota.
In basso a destra si trovano alcuni strumenti che permettono di selezionare i dispositivi secondo criteri predefiniti; tenendo premuto il tasto ctrl mentre si effettua una nuova selezione la selezione corrente è mantenuta (la nuova selezione si somma alla precedente).
Dai settings applicativi è possibile scegliere quali colonne sono mostrate dall'applicazione nella tabella. L'ordine delle colonne può essere modificato semplicemente trascinando l'intestazione con il mouse. La posizione viene ricordata al successivo riavvio di Scelly Scanner. L'esportazione in CSV tiene conto delle visivilità e delle posizioni impostate.
Linea di comando ed esecuzione non interattiva: eseguendo Shelly Scanner da terminale con il comando java -jar <path completo>\shellyscan-x.x.x.jar è possibile specificare alcuni parametri; si è già visto come forzare all'avvio la modalità di ricerca dei dispositivi sulla rete ignorando la normale configurazione:
-fullscan (o -full) esegue la ricerca su mDNS considerando eventuali interfacce multiple di rete;
-localscan (o -local) esegue la ricerca su mDNS sull'interfaccia di rete principale;
-ipscan (o -ipscan0 o -ip o -ip0) seguito da un parametro con formato x.y.z.a-b dove x.y.z è il prefisso della rete, a e b sono rispettivamente il primo e l'ultimo indirizzo da verificare; esegue la ricerca per IP (rinunciando alla possibilità di rintracciare tutti i dispositivi alimentati a batteria che normalmente non sono attivi); -ipscan<n> o -ip<n> (con n numeri interi consecutivi) consentono di definire intervalli di IP multipli;
-noscan mostra il contenuto dell'archivio.
A questi parametri si uniscono ulteriori due opzioni che rendono Shelly Scanner non interattiva (non parte l'interfaccia grafica, viene eseguito il comando e l'applicazione termina):
-list esegue la ricerca ed elenca sul terminale i dispositivi trovati;
-backup seguito da un parametro che identifica una directory esistente; esegue il backup di tutti i dispositivi che trova mettendo i file prodotti nella directory specificata.
Usando questi ultimi parametri è anche possibile specificare uno dei parametri che modificano la modalità di ricerca.
Infine la funzione del parametro -graphs è descritta nella pagina dedicata ai grafici.
Se intendete segnalare un errore dell'applicazione (della qual cosa vi sarei grato) vi prego di attivare i log avviando l'applicazione da terminale con la seguente riga di comando: java -D"org.slf4j.simpleLogger.log.it.usna=debug" -jar <path completo>\shellyscan-x.x.x.jar, produrre l'errore ed allegare alla segnalazione tutto ciò che compare sul terminale.

Di seguito alcuni link utili per chi volesse approfondire:

Shelly Scanner è scaricabile gratuitamente e lo sarà sempre, tuttavia, se lo ritenete opportuno, potete supportare il suo sviluppo con una donazione.