Merge pull request #7 from amusarra/fix/review-docs-and-other

Fix/review docs and other

Author: amusarra

.github/workflows/generate-pdf.yml

@@ -0,0 +1,35 @@
+name: Generate and Commit eBook PDF via Asciidoctor
+
+on:
+  push:
+    paths:
+      - '**.adoc'  # Trigger on changes to .adoc files
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  generate-pdf:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+
+      - name: Install asciidoctor-pdf
+        run: |
+          gem install asciidoctor-pdf
+
+      - name: Generate PDF
+        run: |
+          asciidoctor-pdf -o docs/asciidoc/ebook-smartcard-contactless-raspberry-pi.pdf docs/asciidoc/index.adoc
+
+      - name: Commit eBook PDF
+        run: |
+          git config --local user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git config --local user.name github-actions[bot]
+          git add docs/asciidoc/ebook-smartcard-contactless-raspberry-pi.pdf
+          git commit -m "Update eBook PDF" || echo "No changes to commit"
+          git push

CHANGELOG.md

@@ -13,7 +13,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 ### Security
 
-## [1.0.2.dev0] - 2024-07-04
+## [1.0.2.dev1] - 2024-07-15
+
+### Added
+- Added the GitHub Actions for the AsciiDoc to PDF conversion. The PDF will be available at the directory `docs/asciidoc/`
+
+## Changed
+- Updated the `README.md` with the new section for the AsciiDoc to PDF conversion
+
+## Fixed
+- Fixed the AsciiDoc for the eBook (layout and content)
+
+## [1.0.2.dev0] - 2024-07-14
 
 ### Added
 - Added the AsciiDoc for eBook

README.markdown

@@ -253,3 +253,31 @@ Animation 1 - Smart Card Init tool in action (on asciinema https://asciinema.org
 ![Run Smart Card Access Tool](docs/images/gif/access_control_mifare_classic_1k_smart_card_speed_x2.gif)
 
 Animation 2 - Smart Card Access tool in action (on asciiname https://asciinema.org/a/475797)
+
+## 5. Documentation
+The documentation of the project is available in the `docs` folder. The documentation is written in Markdown format
+and can be read directly on GitHub pages at the following link: [Smart Card Contactless Raspberry Pi GitHub Pages](https://amusarra.github.io/smartcard-contactless-raspberry-pi/)
+
+Also, the documentation is available in PDF format at the following link: [eBook - Smart Card Contactless Raspberry Pi](https://bit.ly/3LkpkOt).
+The source code of the documentation is available in the `docs/asciidoc` folder of the project.
+
+The GitHub Pages are generated using the [MkDocs](https://www.mkdocs.org/) tool and the 
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme using the GitHub Actions workflow
+defined in the `.github/workflows/publish_doc_to_gh_pages.yml` file.
+
+The eBook is generated using the [Asciidoctor](https://asciidoctor.org/) tool and in particular the Asciidoctor PDF.
+The requirement to generate the PDF is to have the Asciidoctor PDF; the instructions for installing this tool are
+available at the following link: [Asciidoctor PDF](https://docs.asciidoctor.org/pdf-converter/latest/install/).
+
+The command to generate the PDF is as follows:
+
+```bash
+# Generate the PDF. The command must be executed from the root of the project.
+# The output file is saved in the docs/asciidoc folder.
+# The <ebook-file-name.pdf> must be replaced with the desired name of the PDF file.
+asciidoctor-pdf -o docs/asciidoc/<ebook-file-name.pdf> docs/asciidoc/index.adoc
+```
+Console 6 - Generate the PDF of the documentation
+
+Also, exist the GitHub Actions workflow defined in the `.github/workflows/generate-pdf.yml` file that generates the PDF
+of the documentation and commits it to the repository in the `docs/asciidoc` folder.

docs/asciidoc/attributes/_attributes-common.adoc

@@ -1,6 +1,6 @@
 :author: Antonio Musarra
-:revnumber: 1.0.1
-:revdate: Luglio 11, 2024
+:revnumber: 1.0.2
+:revdate: Luglio 15, 2024
 :email: [email protected]
 :description: Le Smart Card fanno parte ormai da tempo del nostro \
 quotidiano: dalla SIM (Subscriber Identity Module) del cellulare, alla \

docs/asciidoc/attributes/_attributes-pdf.adoc

@@ -1,2 +1,3 @@
 :doctype: book
-:icons: font
+:icons: font
+:pdf-theme: docs/asciidoc/resources/themes/basic-theme.yml

docs/asciidoc/chapters/00_informazioni_articolo.adoc

@@ -5,7 +5,7 @@
 
 Copertina e impaginazione di Antonio Musarra
 
-Prima edizione digitale Luglio 2024
+Edizione digitale Luglio 2024 (v{revnumber})
 
 Serie: Elettronica&Informatica (#elettronica-informatica)
 

docs/asciidoc/chapters/02_descrizione_scenario.adoc

@@ -25,6 +25,7 @@ Il processo di figura 3 mostra invece cosa succede quando l'ospite chiede di ent
 
 image::room_access_process.jpg[title="Figura 3 - Processo di accesso alla stanza"]
 
+<<<
 Credo che tutti i processi illustrati (in figura 2 e figura 3) in notazione BPMN siano abbastanza esplicativi da non richiedere ulteriori approfondimenti. I Service Task sono gli elementi che saranno oggetto di nostro interesse per l'implementazione del software che fin da questo momento possiamo dividere in due macro componenti le cui responsabilità devono essere:
 
 1.  il setup della Smart Card (o chiave elettronica) in fase di registrazione dell'ospite presso la struttura alberghiera. All'interno della Smart Card sarà memorizzato l'identificativo di un documento di riconoscimento dell'ospite, sul database del sistema di gestione dell'albergo saranno invece memorizzati i dati anagrafici insieme ad altri dati necessari per associare la chiave elettronica all'ospite e alla stanza a lui assegnata;

docs/asciidoc/chapters/05_atr.adoc

@@ -1,11 +1,15 @@
 <<<
 == Cos’è l’Answer to reset o ATR
 
-La prima risposta di una Smart Card inserita in un lettore si chiama https://en.wikipedia.org/wiki/Answer_to_reset[ATR] (*Answer to reset*). Lo scopo dell'ATR è descrivere i parametri di comunicazione supportati, la natura e lo stato della carta. L'ottenimento di un ATR viene spesso utilizzato come prima indicazione che questa sia operativa, e il suo contenuto viene esaminato come prima prova che sia del tipo appropriato per un determinato utilizzo. Il lettore di Smart Card, il driver del lettore e il sistema operativo utilizzeranno questi parametri per stabilire una comunicazione con la scheda.
+La prima risposta di una Smart Card inserita in un lettore si chiama https://en.wikipedia.org/wiki/Answer_to_reset[ATR] (*Answer to reset*). Lo scopo dell'ATR è descrivere i parametri di comunicazione supportati, la natura e lo stato della carta.
+
+L'ottenimento di un ATR viene spesso utilizzato come prima indicazione che questa sia operativa, e il suo contenuto viene esaminato come prima prova che sia del tipo appropriato per un determinato utilizzo. Il lettore di Smart Card, il driver del lettore e il sistema operativo utilizzeranno questi parametri per stabilire una comunicazione con la scheda.
 
 L'ATR è descritto dallo standard https://it.wikipedia.org/wiki/ISO/IEC_7816[ISO/IEC 7816-3]. I primi byte dell'ATR descrivono i parametri elettrici, seguiti da byte che descrivono le interfacce di comunicazione disponibili e i rispettivi parametri. Questi byte di interfaccia sono quindi seguiti da byte storici che non sono standardizzati e sono utili per trasmettere informazioni proprietarie come il tipo di scheda, la versione del software integrato o lo stato della scheda. Infine questi byte storici sono eventualmente seguiti da un byte di checksum.
 
-Potremmo riassumere che l'**ATR contiene "un sacco di dati" che ci dicono vita morte e miracoli della Smart Card**. Per esempio, scopriamo di più sull'ATR `3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 00 01 00 00 00 00 6A` utilizzando il tool https://smartcard-atr.apdu.fr/parse?ATR=3B8F8001804F0CA000000306030001000000006A[Smart card ATR parsing] sviluppato da https://ludovicrousseau.blogspot.com[Ludovic Rousseau]. La figura a seguire mostra le informazioni estratte alcune delle quali:
+Potremmo riassumere che l'**ATR contiene "un sacco di dati" che ci dicono vita morte e miracoli della Smart Card**.
+
+Per esempio, scopriamo di più sull'ATR `3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 00 01 00 00 00 00 6A` utilizzando il tool https://smartcard-atr.apdu.fr/parse?ATR=3B8F8001804F0CA000000306030001000000006A[Smart card ATR parsing] sviluppato da https://ludovicrousseau.blogspot.com[Ludovic Rousseau]. La figura a seguire mostra le informazioni estratte alcune delle quali:
 
 - tipo di Smart Card e in questo caso si tratta della MIFARE Classic 1K;
 - produttore della Smart Card e in questo caso NXP;
@@ -14,6 +18,8 @@ Potremmo riassumere che l'**ATR contiene "un sacco di dati" che ci dicono vita m
 
 image::mifare_classic_1k_atr_parsing.png[title="*Figura 11* - Dettagli estratti sull&#39;ATR della Smart Card MIFARE Classic 1K"]
 
-Ludovic Rousseau ha fatto un ottimo lavoro tracciando dal 2002 un http://ludovic.rousseau.free.fr/softwares/pcsc-tools/smartcard_list.txt[gran numero di ATR] costruendo un vero e proprio database. Così facendo è possibile identificare una Smart Card dato il suo ATR. All'interno della lista sono presenti anche le "nostrane Smart Card" come la **TS-CNS** (https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi[Tessera Sanitaria - Carta Nazionale Servizi]) e **CIE** (https://developers.italia.it/it/cie[Carta d'Identità Elettronica]). È possibile utilizzare il comando `pcsc_scan` per ottenere informazioni di dettaglio sulla Smart Card, le stesse illustrate in figura 11. La figura 12 mostra l'output del comando menzionato da cui è possibile dedurre che la Smart Card analizzata è una CIE.
+Ludovic Rousseau ha fatto un ottimo lavoro tracciando dal 2002 un http://ludovic.rousseau.free.fr/softwares/pcsc-tools/smartcard_list.txt[gran numero di ATR] costruendo un vero e proprio database. Così facendo è possibile identificare una Smart Card dato il suo ATR. All'interno della lista sono presenti anche le "nostrane Smart Card" come la **TS-CNS** (https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi[Tessera Sanitaria - Carta Nazionale Servizi]) e **CIE** (https://developers.italia.it/it/cie[Carta d'Identità Elettronica]).
+
+È possibile utilizzare il comando `pcsc_scan` per ottenere informazioni di dettaglio sulla Smart Card, le stesse illustrate in figura 11. La figura 12 mostra l'output del comando menzionato da cui è possibile dedurre che la Smart Card analizzata è una CIE.
 
 image::output_of_pcsc_scan_smart_card_cie.png[title="Figura 12 - Esempio di output del comando pcsc_scan che mostra le informazioni estratte dalla Smart Card, in questo caso CIE"]

docs/asciidoc/chapters/07_requisiti_software.adoc

@@ -3,13 +3,12 @@
 Così come abbiamo bisogno dell'hardware, è necessario che siano soddisfatti una serie di requisiti software, quali:
 
 1.  https://www.raspberrypi.com/documentation/computers/os.html#introduction[Raspberry Pi OS (64bit)]
-2.  https://www.raspberrypi.com/documentation/computers/os.html#python[Python 3.9.x] (distribuito e installato di default
-con Raspberry Pi OS)
+2.  https://www.raspberrypi.com/documentation/computers/os.html#python[Python 3.9.x] (distribuito e installato di default con Raspberry Pi OS)
 3.  https://docs.docker.com/engine/install/debian/[Docker 20.10.12]
 4.  https://packages.debian.org/bullseye/build-essential[Development Tools (make, gcc) (install or update via `sudo apt install build-essential`)]
 
 Per questo genere di scenari non è assolutamente necessario provvedere all'installazione del sistema operativo in versione Desktop, consiglio pertanto di preparare e usare l'immagine di https://www.raspberrypi.com/software/operating-systems/[Raspberry Pi OS Lite (64bit)]. Per coloro che avessero bisogno di una guida su come installare questo sistema operativo, consiglio di seguire la guida ufficiale https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-the-operating-system[Installing the Operating System].
 
 L'installazione di Docker potrebbe essere anche opzionale; personalmente preferisco installare il database in forma di container. Più in avanti vedremo quale database ho scelto per questa soluzione.
 
-Per approfondimenti sul tema Docker, consiglio la lettura del libro https://amzn.to/3tiyO1W[Docker:Sviluppare e rilasciare software tramite container] di https://www.linkedin.com/in/serena-sensini/[Serena Sensini] e la visione delle https://www.youtube.com/watch?v=wAyUdtQF05w[Pillole di Docker] sul canale YouTube di https://www.linkedin.com/in/mauro-cicolella-0b107076/[Mauro Cicolella].
+Per approfondimenti sul tema Docker, consiglio la lettura del libro https://amzn.to/3tiyO1W[Docker: Sviluppare e rilasciare software tramite container] di https://www.linkedin.com/in/serena-sensini/[Serena Sensini] e la visione delle https://www.youtube.com/watch?v=wAyUdtQF05w[Pillole di Docker] sul canale YouTube di https://www.linkedin.com/in/mauro-cicolella-0b107076/[Mauro Cicolella].