COS'È?

walNUT non è niente di più che un’interfaccia fra voi e NUT (Network UPS Tools), usando upsc e upscmd di NUT. Fornisce un pratico menu del pannello e un'icona per monitorare i propri dispositivi ed eseguire i comandi istantanei di NUT.

Prima di cominciare, è necessario avere NUT già installato e funzionante: in pratica, se tutto va bene con upsc e upscmd, le probabilità sono alte che walNUT funzioni già fin da subito.

1. INSTALLAZIONE

È possibile installare questa estensione per il proprio utente eseguendo:

cd ~/.local/share/gnome-shell/extensions
git clone git://github.com/zykh/walNUT.git walnut@networkupstools
glib-compile-schemas walnut@networkupstools/schemas/

Dopo l’installazione è necessario riavviare Gnome Shell:

  • ALT+F2 per aprire il prompt dei comandi

  • Inserire r per riavviare Gnome Shell

Quindi è possibile attivare l’esensione attraverso Gnome Tweak Tool (Shell Extensions → walNUT → On) o tramite https://extensions.gnome.org/local/

Nota Oltre a NUT, è necessario anche timeout (vedi problemi conosciuti).

2. PRIMA ESECUZIONE

Una volta che si è installato walNUT, quando viene eseguito per la prima volta, od ogni volta che la sua lista dei dispositivi è vuota, proverà a cercare automaticamente nuovi dispositivi in localhost:3493.
Quindi, per la maggior parte delle installazioni, dovrebbe aver già trovato i dispositivi disponibili. In caso contrario, è necessario aggiungerli tramite il riquadro per trovare nuovi dispositivi.

È importante comprendere come walNUT comunica e come può essere personalizzato: si prega di leggere le sezioni icona/etichetta del pannello, menu del pannello e preferenze.
Non si dimentichi la sezione problemi conosciuti!

3. ICONA/ETICHETTA DEL PANNELLO

L’icona e l’etichetta di walNUT sono personalizzabili tramite le preferenze.
Qui è spiegato come si comportano.

Icona del pannello

L’icona del pannello normalmente mostra solo il livello di carica della batteria [A], ma può visualizzare anche il livello di carico del dispositivo [B], se disponibile.
In tal caso il ‘seme’ della noce sarà diviso in due parti: quella più a sinistra [1] mostrerà il livello di carica della batteria, quella più a destra [2] il livello di carico del dispositivo.

Attenzione Nal caso in cui si imposti anche Mostra il carico del dispositivo nell’icona del pannello nelle preferenze e il livello di carica della batteria non sia disponibile, l’icona sarà esattamente la stessa di quella per il solo livello di carica della batteria [A]: si prega di prestare attenzione.

Icona del pannello - in linea/a batteria + Carico/Caricando

L’icona del pannello visualizza anche lo stato della linea elettrica: se il dispositivo è connesso alla rete (l’elettricità non è assente, ups.status: OL) ci sarà un piccolo fulmine [C] alla destra della noce che non sarà visualizzato se il dispositivo è alimentato dalla batteria [D].
Questo fulmine mostrerà anche se il dispositivo è carico oppure no: se il livello di carica della batteria è del 100% o se il livello di carica della batteria non è disponibile e il dispositivo non ci sta dicendo che si sta caricando o scaricando (ups.status: CHRG/DISCHRG) supporremo che sia carico e il fulmine sarà trasparente [E], altrimenti sarà a piena opacità [F].

Icona del pannello - Attenzione

Per gli altri stati (ups.status: BYPASS, TRIM, ..) o se si verifica un allarme (ups.status: ALARM + ups.alarm) ci sarà un punto esclamativo nell’angolo in alto a destra della noce.

Icona del pannello - Fantasma

Se il livello di carica della batteria non è disponibile oppure se anche l’opzione Mostra il carico del dispositivo nell’icona del pannello è selezionata nelle preferenze e sia il livello di carico del dispositivo, sia il livello di carica della batteria non sono disponibili l’icona sarà una noce piena e trasparente.

Icona del pannello - Errore

Questa è l’icona visualizzata in caso di errori.

Etichette sul pannello

walNUT può anche mostrare un’etichetta, alla destra dell’icona sul pannello, con il livello di carica della batteria [G], il livello di carico del dispositivo [H] o entrambi [I], se disponibili.

Nota

L’icona mostra il livello di carica della batteria e il livello di carico del dispositivo attraverso tre barre:

Icona Barre Significato

3 barre per livello di carica della batteria/livello del carico

3 barre

Più del 75%

2 barre per livello di carica della batteria/livello del carico

2 barre

Tra il 50% e il 75%

1 barra per livello di carica della batteria/livello del carico

1 barra

Tra il 25% e il 50%

Nessuna barra per livello di carica della batteria/livello del carico

nessuna barra

Meno del 25%

4. MENU DEL PANNELLO

Ecco una rapida panoramica del menu del pannello.
Di base il menu ha questo aspetto:

Menu del pannello

Con tutte le opzioni disponibili impostate:

Menu del pannello - Completo

Il menu può essere suddiviso in varie sezioni:

In caso di errore, il menu appare in questo modo:

Menu del pannello - Errore

Dove la lista dei dispositivi [A] è visibile o meno, a seconda del tipo di errore [L].

4.1. LISTA DEI DISPOSITIVI

Lista dei dispositivi

I dispositivi sono elencati in ordine alfabetico di hostname:porta e quindi secondo l’ordine alfabetico dei loro nomi.

Nota Di ciascun dispositivo memorizzato nella lista di walNUT verrà controllata la disponibilità ogni volta che si cambia qualche opzione o quando Gnome Shell viene aggiornato (ad esempio, di ritorno dal blocco dello schermo ..e così via) o quando il menu viene aperto, a condizione che più di 15 minuti siano passati dall’ultimo aggiornamento.
Lista dei dispositivi aperta

I dispositivi non disponibili sono segnalati con (N/D) [A] alla loro destra. È possibile scegliere di visualizzare o meno i dispositivi non disponibili nelle preferenze.

4.2. MODELLO DEL DISPOSITIVO

Modello del dispositivo

Se disponibili, sia il produttore del dispositivo che il modello saranno mostrati qui.

Suggerimento Se il dispositivo non sta fornendo uno fra produttore o modello oppure entrambi, o se si desidera un’etichetta più accattivante, è possibile sovrascriverne uno o entrambi in ups.conf.

4.3. STATO DEL DISPOSITIVO

Stato del dispositivo

Lo stato del dispositivo mostrerà: lo stato della linea elettrica [A] (in linea/a batteria), e quindi, nella seconda riga, ogni stato segnalato dal dispositivo [B] (bypass, smorzamento, ..).

4.4. ALLARME DEL DISPOSITIVO

Allarme del dispositivo

Se viene riportato un allarme (ups.status: ALARM e ups.alarm) sarà mostrato qui.

Nota L’allarme viene segnalato anche attraverso un ‘punto esclamativo’ nell'icona del pannello.

4.5. TABELLA DEI DATI

Tabella dei dati

Se disponibili, [C] il livello di carica della batteria, [D] il tempo stimato di backup, [E] il livello di carico e [F] la temperatura del dispositivo saranno visualizzati qui.
L’icona della batteria [1] mostrerà l’effettivo livello di carica tramite il numero di barre orizzontali (come quelle dell'icona del pannello).

4.6. DATI GREZZI

Dati grezzi

Se si desidera visualizzare nel dettaglio tutte le variabili disponibili per un dispositivo è necessario selezionare l’opzione Mostra i dati grezzi nelle preferenze: i dati grezzi saranno visualizzati in un sotto-menu scorrevele.

4.7. COMANDI DEL DISPOSITIVO

Comandi del dispositivo - Menu a cascata

Se si desidera eseguire i comandi istantanei di NUT tramite walNUT è necessario selezionare l’opzione Mostra i comandi del dispositivo nelle preferenze.
È possibile scegliere di visualizzare i comandi istantanei del dispositivo sia in menu a cascata [A] che in un sotto-menu [B].

Comandi del dispositivo - Sotto-menu

Se si sceglie il menu a cascata [A], per prima cosa è necessario selezionare il comando, quindi si deve cliccare sul bottone [1] ‘esegui’ alla destra della descrizione del comando [2].

Comandi del dispositivo - Menu a cascata, selezionato

Se si sceglie il sotto-menu [B], quando si clicca su un comando, questo viene eseguito.

Suggerimento

Il sotto-menu di base visualizza anche una descrizione localizzata dei comandi [C], ma se si pensa che occupi troppo spazio è possibile scegliere di non mostrarla [D] nelle preferenze.

Comandi del dispositivo - Sotto-menu, con o senza descrizione

Una volta che un comando è stato eseguito, verrà segnalato se è stato inviato con successo al driver [E] oppure no [F].

Comandi del dispositivo - Notifica
Nota Il principale vantaggio del menu a cascata è che si tratta di un processo in due fasi, mentre il sotto-menu fornisce un’interfaccia scorrevole se si dispone di un limitato spazio in verticale.

4.8. PULSANTI DI CONTROLLO

Pulsanti di controllo

In fondo al menu del pannello si trova una manciata di pulsanti di controllo, alcuni dei quali apriranno il loro riquadro [A] appena prima della riga dei pulsanti di controllo [B].

Pulsanti di controllo + Riquadro di controllo

I pulsanti mostreranno:

4.9. RIQUADRO DELLE CREDENZIALI

Riquadro delle credenziali

Cliccando sul pulsante ‘credenziali’ [A] si aprirà il riquadro delle credenziali [B] che è usato per memorizzare il nome utente e la password per i dispositivi in modo che non vengano richiesti ogni volta che si esegue un comando.

Nota Se si desidera cancellare il nome utente, la password o entrambi (ad esempio in modo che da ora in avanti essi vengano richiesti), è necessario salvarli vuoti.

Se si clicca sul pulsante ‘annulla e chiudi’ [1] qualsiasi modifica effettuata al nome utente o alla password prima di cliccare sul pulsante ‘salva’ [2] verrà scartata.

Suggerimento Di base la password è nascosta, ma se lo si desidera, è possibile scegliere di non nasconderla nelle preferenze.

4.10. TROVARE NUOVI DISPOSITIVI/RIQUADRO PER CERCARE NUOVI DISPOSITIVI

Riquadro per trovare nuovi dispositivi

Al fine di cercare nuovi dispositivi, una volta che si è cliccato sul pulsante ‘trova’ [A], è necessario inserire l’hostname [1] e la porta [2] del dispositivo e quindi cliccare sul pulsante ‘inizia ricerca’ [B].

Nota Se l’hostname non viene fornito sarà localhost, mentre la porta, se non indicata, sarà 3493.

Si verrà avvisati sia che nuovi dispositivi siano trovati [C] o meno [D].

Trova nuovi dispositivi - Notifica

4.11. RIMUOVERE DISPOSITIVI/RIQUADRO PER RIMUOVERE UN DISPOSITIVO

Riquadro per rimuovere un dispositivo

Se si vuole rimuovere un dispositivo, per prima cosa è necessario selezionarlo dalla lista dei dispositivi, quindi è necessario cliccare sul pulsante ‘rimuovi’ [A].
Un nuovo riquadro [B] apparirà chiedendo se si vuole davvero rimuoverlo [1] oppure no [2].

Nota Se si vuole rimuovere un dispositivo che non è al momento disponibile, controllare prima di aver abilitato l’opzione Mostra i dispositivi non disponibili nelle preferenze.

5. CREDENZIALI DEL DISPOSITIVO

Se si desidera eseguire i comandi instantanei di un dispositivo, è necessario fornire un nome utente e una password validi (come impostati nel file di configurazione upsd.user). È possibile salvarli tramite il riquadro delle credenziali oppure si possono inserire nella finestra delle credenziali ogni volta che si esegue un comando.

Nota Se il nome utente e la password salvati si dimostrassero errati, verrebbero richiesti con la finestra delle credenziali, qualora si provasse ad eseguire un comando.

5.1. FINESTRA DELLE CREDENZIALI

Finestra delle credenziali

La finestra delle credenziali vi chiederà di inserire un nome utente e una password validi sia che non siano stati salvati tramite il riquadro delle credenziali sia che si siano dimostrati errati [A].

Finestra delle credenziali - errore
Nota Il pulsante ‘esegui’ [B] sarà selezionabile solo se sia il nome utente che la password non sono vuoti.
Attenzione Dopo aver inserito nome utente e password, quando si clicca sul pulsante ‘esegui’ [B] il comando sarà inviato al driver.

6. PREFERENZE

Per personalizzare walNUT in base alle proprie esigenze si può decidere di modificare alcune opzioni.

Pulsante delle preferenze

È possibile accedere alle preferenze dal pulsante delle preferenze [A] nel menu del pannello.

Si aprirà una nuova finestra in cui è possibile impostare le varie opzioni.

Preferenze
Opzioni disponibili
# Opzione Descrizione

1

Secondi prima del prossimo aggiornamento

I secondi dopo i quali walNUT aggiorna i dati del dispositivo. (default: 15)

2

Unità di misura della temperatura

L’unità di misura (Centigradi o Fahrenheit) in cui walNUT deve mostrare la temperatura. (default: Centigradi)

3

Mostra i dispositivi non disponibili

Visualizza anche i dispositivi non disponibili nel menu a cascata del menu del pannello (il dispositivo scelto sarà sempre mostrato, anche se non disponibile, a dispetto di questa opzione). (default: OFF)

4

Mostra i dati grezzi

Visualizza anche i dati grezzi in un sotto-menu. (default: OFF)

5

Mostra i comandi del disposivo

Visualizza i comandi del dispositivo disponibili. Sono necessari nome utente e password di upsd per eseguirli. (default: OFF)

6

Comandi del dispositivo in un menu a cascata

Se l’estensione deve mostrare i comandi del dispositivo in un menu a cascata oppure no (se no, i comandi sono visualizzati in un sotto-menu). (default: ON)

7

Mostra la descrizione dei comandi del dispositivo (sotto-menu)

Visualizza anche una descrizione localizzata dei comandi del dispositivo disponibili (sotto-menu). (default: ON)

8

Nascondi la password nel riquadro delle credenziali

Se la password nel riquadro delle credenziali deve essere nascosta oppure no. (default: ON)

9

Mostra il carico del dispositivo nell’icona del pannello

Se il livello di carico del dispositivo deve essere visualizzato nell’icona sul pannello oppure no. (default: OFF)

10

Mostra il carico del dispositivo nel pannello

Se il livello di carico del dispositivo deve essere visualizzato nell’etichetta sul pannello oppure no. (default: OFF)

11

Mostra la carica della batteria nel pannello

Se il livello di carica della batteria deve essere visualizzato nell’etichetta sul pannello oppure no. (default: OFF)

7. PROBLEMI CONOSCIUTI

Dal momento che walNUT si affida a upsc di NUT per cercare nuovi dispositivi e per stabilire se un dispositivo sia disponibile o meno, se un hostname:porta non è risolvibile, o se l’host non ha un NUT attivo e funzionante, upsc impiegherà del tempo per dircelo, così ogni volta che la lista dei dispositivi viene aggiornata o quando una ricerca per nuovi dispositivi è iniziata o, se il dispositivo ‘problematico’ è quello attualmente scelto, ogni volta che walNUT prova ad aggiornare le suo variabili, potrebbe potenzialmente congelare Gnome Shell per alcuni secondi (~3 per ogni dispositivo ‘problematico’).

Al fine di evitare questi blocchi, ogni invocazione di upsc/upscmd è effettuata attraverso un timeout di 150ms.
Nel caso in cui un dispositivo non venga trovato (ad esempio ha bisogno di più di 150ms per rispondere), è possibile cambiare questo timeout modificando l’opzione timeout (default: 0.150) sia tramite dconf-editor (org → gnome → shell → extensions → walnut) che eseguendo:

gsettings set org.gnome.shell.extensions.walnut timeout N.NNN

Dove N.NNN è il timeout in secondi.

Attenzione A prescindere da questo timeout, è meglio non giocare con il riquadro per trovare nuovi dispositivi e host ‘di fantasia’ ed è altamente raccomandabile rimuovere dalla lista quei dispositivi il cui hostname:porta stia per non essere più risolvibile.

8. AIUTO

Se questo manuale non risponde alle vostre domande o per qualsiasi problema che possiate incontrare, è possibile trovare dell’aiuto nella mailing list di NUT:

Se volete aiutare, sarete i benvenuti nella mailing list di NUT e nella mailing list degli sviluppatori di NUT:

8.1. TRADUTTORI

Una guida alla traduzione delle estensioni può essere trovata nelle FAQ sulle estensioni di Gnome Shell.

La documentazione di walNUT è scritta in AsciiDoc e quindi elaborata sia per la versione in html che per la versione in Mallard per Yelp.

I file di aiuto devono essere messi nella cartella help dell’estensione, creando una cartella con il nome del language code del locale desiderato (ad esempio en, it, ..) o, per i locale specifici di una nazione, con il nome del language code e il codice della nazione (ad esempio pt_BR, pt_PT).

La versione in html deve essere compilata con:

asciidoc --backend=xhtml11 \
         -a lang=XX \
         --out-file help.html \
         manual.txt

Dove help.html è il nome che il file di aiuto deve avere, manual.txt è il nome del file sorgente e XX è il proprio language code (ad esempio it, es, ..).

Mentre la versione in Mallard necessita di qualche ulteriore passaggio:

  1. Scaricare questo Mallard backend per AsciiDoc (documentazione qui)

  2. Installare il backend

    asciidoc --backend install mallard.zip
  3. Compilare il file sorgente (ad esempio manual.txt) con:

    asciidoc --backend=mallard \
             -a chunked=1 \
             -a toc \
             --out-file temp.page \
             manual.txt
  4. Scaricare lo script di bash chunkenizer (documentazione qui)

  5. Dare allo script di bash chunkenizer i permessi di esecuzione:

    chmod +x chunkenizer
  6. Elaborare il file temporaneo precedentemente creato temp.page con:

    ./chunkenizer --yelp temp.page outdir

    Dove outdir è la cartella di destinazione con il nome del proprio locale (ad esempio pt_BR).

Nota

Se si desidera utilizzare le immagini del manuale inglese è necessario creare un collegamento simbolico alla loro cartella nella cartella del proprio locale:

ln -s ../C/img img

9. AUTORE

Daniele Pezzini <hyouko@gmail.com>