# Guida all'installazione di KoboOPDS

## Introduzione

KoboOPDS è uno strumento leggero pensato per i possessori di Kobo che desiderano accedere a cataloghi OPDS senza abbandonare l'ambiente di lettura standard del Kobo. OPDS, acronimo di **Open Publication Distribution System**, è un sistema comunemente utilizzato per sfogliare, cercare e scaricare libri da un catalogo online.

Con KoboOPDS puoi collegare il tuo Kobo a:

- cataloghi OPDS pubblici disponibili su Internet;
- raccolte di libri gratuiti, come Project Gutenberg;
- un tuo server OPDS privato o self-hosted;
- una biblioteca personale condivisa tramite Calibre Content Server o un'altra applicazione compatibile con OPDS.

KoboOPDS utilizza il browser integrato del Kobo come interfaccia. I libri scaricati possono quindi essere importati nella normale biblioteca del Kobo e aperti con il lettore standard Kobo. È pensato per chi desidera accedere comodamente via Wi-Fi a raccolte di libri remote continuando a utilizzare la familiare interfaccia Kobo.

Questa guida spiega come installare **prima NickelMenu** e **successivamente KoboOPDS**. Non sono necessari riga di comando, modalità sviluppatore o modifiche al database.

> **Importante:** NickelMenu e KoboOPDS vengono distribuiti come due file distinti che hanno entrambi lo stesso nome: `KoboRoot.tgz`. Installali **uno alla volta**. Non unirli, non rinominarne il contenuto e non estrarli.

## Prima di iniziare

Occorrono:

- un eReader Kobo con firmware Kobo 4.x;
- un PC Windows, Mac o computer Linux;
- il cavo USB del Kobo;
- una rete Wi-Fi attiva per consultare i cataloghi OPDS.

NickelMenu attualmente non supporta il firmware Kobo 5.x. Puoi controllare la versione del firmware del Kobo in **Altro → Impostazioni → Informazioni sul dispositivo → Versione software**.

Carica il Kobo almeno al 30% prima dell'installazione. Se il dispositivo contiene libri o annotazioni importanti, esegui un normale backup prima di modificarlo.

## Comprendere le cartelle del Kobo

Quando il Kobo viene collegato tramite USB, sul computer appare come unità rimovibile, normalmente denominata `KOBOeReader`.

La cartella di installazione è:

```text
KOBOeReader/.kobo
```

Il punto iniziale fa parte del nome. `.kobo` è una cartella nascosta.

Per visualizzare i file nascosti:

- **Windows:** apri Esplora file e seleziona **Visualizza → Mostra → Elementi nascosti**.
- **macOS:** apri il Kobo nel Finder e premi **Command + Shift + .**
- **Linux:** nella maggior parte dei file manager premi **Ctrl + H**.

## Parte 1 — Installare NickelMenu

### 1. Scaricare NickelMenu

1. Apri la [pagina ufficiale delle release di NickelMenu](https://github.com/pgaskin/NickelMenu/releases).
2. Apri l'ultima versione stabile.
3. Se necessario, espandi la sezione **Assets**.
4. Scarica il pacchetto di installazione `KoboRoot.tgz`.

**Non** decomprimere né aprire `KoboRoot.tgz`.

### 2. Copiare NickelMenu sul Kobo

1. Collega il Kobo al computer tramite il cavo USB.
2. Sullo schermo del Kobo, tocca **Connetti**.
3. Sul computer, apri l'unità `KOBOeReader`.
4. Apri la cartella nascosta `.kobo`.
5. Copia il file `KoboRoot.tgz` di NickelMenu direttamente dentro `.kobo`.

Il risultato deve essere:

```text
KOBOeReader/.kobo/KoboRoot.tgz
```

Non inserirlo all'interno di un'altra cartella.

### 3. Espellere in sicurezza e attendere

1. Espelli in sicurezza `KOBOeReader` dal sistema operativo.
2. Scollega il cavo USB solo dopo che il computer indica che è possibile farlo in sicurezza.
3. Attendi mentre il Kobo mostra la schermata di aggiornamento e si riavvia.

L'aggiornamento può richiedere alcuni minuti. Non spegnere il Kobo durante questa fase. Dopo l'installazione, normalmente il file `KoboRoot.tgz` scompare: è del tutto normale.

### 4. Verificare NickelMenu

Dopo che il Kobo è tornato alla schermata Home:

1. Apri **Altro**.
2. Cerca **NickelMenu**.

Non installare KoboOPDS finché NickelMenu non compare. Se non è presente, consulta la sezione [Risoluzione dei problemi](#risoluzione-dei-problemi) più avanti.

## Parte 2 — Installare KoboOPDS

### 1. Scaricare KoboOPDS

Scarica il pacchetto KoboOPDS corrente:

[Scarica KoboOPDS 0.7.22](download)

Anche questo file si chiama `KoboRoot.tgz`, ma **non** è il pacchetto NickelMenu. Prima di continuare, assicurati che NickelMenu sia già installato.

**Non** decomprimere né aprire il pacchetto KoboOPDS.

### 2. Copiare KoboOPDS sul Kobo

1. Collega nuovamente il Kobo al computer.
2. Tocca **Connetti** sullo schermo del Kobo.
3. Apri l'unità `KOBOeReader`.
4. Apri `.kobo`.
5. Copia il file `KoboRoot.tgz` di KoboOPDS direttamente dentro `.kobo`.
6. Se il computer chiede se sostituire un vecchio `KoboRoot.tgz`, conferma soltanto se sei certo che si tratti di un file di installazione rimasto dalla procedura precedente. Normalmente il pacchetto precedente è già stato eliminato automaticamente.

### 3. Espellere in sicurezza e attendere nuovamente

1. Espelli in sicurezza `KOBOeReader`.
2. Scollega il cavo.
3. Lascia che il Kobo installi il pacchetto e completi il riavvio.

KoboOPDS include NickelDBus per l'importazione automatica nella biblioteca. Il riavvio è necessario anche se KoboOPDS era già stato installato in precedenza.

### 4. Avviare KoboOPDS

1. Apri **Altro → NickelMenu**.
2. Tocca **Kobo OPDS**.
3. KoboOPDS attiva il Wi-Fi e si apre in una finestra del browser Kobo.
4. Se richiesto, seleziona la tua rete Wi-Fi e inserisci la password.

Le nuove installazioni includono due sorgenti già pronte all'uso:

- **Project Gutenberg**, selezionato per impostazione predefinita;
- **Feedbooks OPDS Test Catalog**, utile per verificare la connessione e il parser.

Project Gutenberg può occasionalmente restituire un errore temporaneo del server. In questo caso, usa il pulsante quadrato per riprovare oppure seleziona il catalogo di test Feedbooks dalle Impostazioni.

## Comandi di KoboOPDS

Le icone nell'intestazione nera vengono sempre visualizzate, quando pertinenti, nel seguente ordine:

1. **Cuore:** mostra la pagina locale di supporto e il codice QR per le donazioni.
2. **Libro aperto:** torna al catalogo OPDS attivo.
3. **Info:** mostra versione, stato della connessione e informazioni diagnostiche.
4. **Ingranaggio:** apre le impostazioni delle sorgenti e della lingua.

L'icona corrispondente alla pagina attualmente visualizzata viene intenzionalmente omessa.

Nelle impostazioni delle sorgenti:

- tocca **+** per creare una sorgente OPDS vuota;
- tocca il **segno di spunta** per selezionare una sorgente;
- tocca la **matita** per modificarla;
- tocca **X** per eliminarla dopo aver confermato.

Nome utente e password sono facoltativi e sono destinati all'autenticazione HTTP Basic. Rimangono memorizzati localmente sul Kobo.

## Download e importazione nella biblioteca

1. Sfoglia o cerca nel catalogo OPDS selezionato.
2. Apri la scheda di un libro.
3. Seleziona uno dei formati disponibili.
4. Attendi il risultato del download, poi continua a sfogliare oppure chiudi il browser.

Poco dopo il completamento di un download, KoboOPDS chiede automaticamente a Nickel di eseguire la scansione della biblioteca: non è più necessario attendere la chiusura del browser. I download ravvicinati o multipli vengono riuniti in un'unica scansione e le richieste non riuscite vengono ritentate. Il libro scaricato dovrebbe comparire nella schermata Home del Kobo oppure in **I miei libri**.

Se non compare, apri NickelMenu e seleziona **Import downloaded books**.

All'avvio di KoboOPDS, Nickel prova a collegarsi alla rete Wi-Fi preferita e può mostrare le reti disponibili quando è necessario l'intervento dell'utente. Se il Wi-Fi era disattivato prima dell'avvio, viene disattivato nuovamente dopo la chiusura del browser KoboOPDS. Se era già attivo, viene lasciato invariato.

## Aggiornare KoboOPDS

Installa una versione più recente del file `KoboRoot.tgz` di KoboOPDS seguendo esattamente la procedura descritta nella Parte 2. Non è necessario reinstallare NickelMenu prima di ogni aggiornamento di KoboOPDS.

Gli aggiornamenti mantengono:

- le sorgenti OPDS salvate;
- nomi utente e password;
- la sorgente attiva;
- la lingua dell'interfaccia selezionata.

Il programma di installazione non sostituisce intenzionalmente questi file di configurazione personali.

## Risoluzione dei problemi

### NickelMenu non compare

- Verifica che il Kobo utilizzi il firmware 4.x e non il 5.x.
- Reinstalla l'ultima versione stabile di NickelMenu.
- Assicurati che `KoboRoot.tgz` sia stato copiato dentro `.kobo`, non nella cartella principale del Kobo e non in una seconda cartella `.kobo` annidata.
- Assicurati che l'archivio non sia stato estratto o rinominato dal browser.

NickelMenu segnala molti errori di configurazione tramite una voce all'interno del proprio menu. Il progetto ufficiale consiglia inoltre, per una diagnostica avanzata, di controllare `logread` tramite SSH o Telnet.

### Toccando Kobo OPDS parte un download invece di aprirsi il catalogo

Riavvia nuovamente il Kobo e riprova. Il servizio locale potrebbe non aver completato il primo avvio. Se il problema persiste, apri **Info** e controlla l'errore registrato.

### Non è possibile raggiungere un catalogo

- Verifica che il Wi-Fi sia connesso.
- Controlla l'indirizzo OPDS completo, incluso `http://` oppure `https://`.
- Verifica nome utente e password.
- Prova il **Feedbooks OPDS Test Catalog** incluso.
- Usa **Info** per distinguere tra errori di autenticazione, DNS, TLS, timeout ed errori temporanei del server.

### Log diagnostico

Gli utenti avanzati possono controllare tramite USB, SSH o Telnet il seguente file:

```text
.adds/kobo-opds/run/httpd.log
```

Non pubblicare file di configurazione o log senza prima verificare che non contengano indirizzi di server privati o altre informazioni personali.

## Rimuovere KoboOPDS

Collega il Kobo tramite USB ed elimina:

```text
.adds/kobo-opds
.adds/nm/kobo-opds
```

Successivamente riavvia il Kobo. Questa procedura rimuove KoboOPDS ma lascia NickelMenu installato.

## Riferimenti ufficiali di NickelMenu

- [Progetto NickelMenu e note di installazione](https://github.com/pgaskin/NickelMenu)
- [Release stabili di NickelMenu](https://github.com/pgaskin/NickelMenu/releases)
- [Documentazione di configurazione di NickelMenu](https://github.com/pgaskin/NickelMenu/blob/master/res/doc)