7 files changed, 355 insertions(+), 22 deletions(-)

M Makefile
M README.md
A docs/README.md
A docs/diagrams/file-browser.png
A docs/diagrams/image-viewer.png
A docs/diagrams/text-viewer.png
M docs/user-manual.org

@@ 84,7 84,7 @@ run-image-viewer: copy-executable
 run-text-viewer: copy-executable
 	ssh $(SSH_OPTIONS) -t $(TARGET_USER)@$(TARGET_IP) $(TARGET_DIR)/text-viewer $(ARG)
 
-docs:
+docs: FORCE
 	doxygen DOXYGEN
 
 clean:

@@ 1,22 1,248 @@
-* CTU FEE APO Semestral Project
+# Zadání
+Semestrální práce bude rozdělena do 3 jednotlivých programů vypracovaných pro MZAPO. Hlavní z nich
+bude průzkumník souborů, ve kterém bude možné procházet celý kořenový souborový systém ~~a také externí zařízení~~.
+~~Průzkumník bude umět základní operace jako kopírování, přesouvání a mazání souborů~~. Dále spouštět spustitelné soubory
+a pro obrázky, resp. pro textové soubory otevřít prohlížeč obrázků, resp. textových souborů.
 
-This project consists of 3 programs for MZ_APO.
+Prohlížeč obrázků je druhý program, který bude umět otevřít formáty jpeg, png a ppm. Přes rotační enkodery
+bude zařízen pohyb kurzoru po obrázku a následně se půjde na jednotlivé části obrázku přibližovat,
+aby obrázek nebyl moc malý.
 
-** Documentation
-Documentation may be built using make docs
-and then found in docs/ folder
+Prohlížeč textových souborů je poslední program, ten bude umět otevírat kterékoliv soubory, ale korektně
+bude zobrazovat jen ty textové. Půjde se v něm pohybovat za pomoci rotačních enkoderů.
 
-** File browser
-For viewing local filesystem, browsing folders and opening files
+Vstup bude zařízen standardním vstupem pro ovládání na dálku a rotačními enkodery pro ovládání přímo.
+Standardní výstup bude použit k logování hlášek o tom, co program právě dělá nebo v jakém chybovém stavu se nachází.
 
-More can be found in manual
+Pro rychlejší ladění bude možnost programy spouštět na osobním počítači, kde se jako displej využije SDL okno.
 
-** Image viewer
-For viewing images you can zoom to at cursor location
+## Zhodnocení splnění zadání
+U průzkumníku souborů jsem bohužel nestihl implementovat základní operace jako přesouvání, mazání nebo kopírování souborů.
+Stejně tak průzkumník souborů neumí sám namountovat externí zařízení jak bylo v plánu. Průzkumník tak umí pouze procházet složky,
+otevírat soubory v příslušném programu (podle mime typu).
+Na druhou stranu z prohlížeče textových souborů i obrázků se mi podařilo implementovat vše ze zadání
+jak pro ovládání přes rotační enkodery nebo přes standardní vstup.
 
-More can be found in manual
+Program na rychlejší lazení se mi povedlo vytvořit tak, že z většiny simuluje reálnou nízkou úroveň periferií. V kódu je tak potřeba
+minimum změn, aby místo na MZAPO běžel na osobních počítačích, je potřeba pouze změnit inicializaci programu, mapovací funkci nahradit
+vlastní mapovací funkcí a změnit posílání dat a příkazů displeji. Ovládání RGB LEDek i LED pásku zůstává stejné, není potřeba žádný zásah
+do kódu. Šlo by i jednoduše implementovat rotační enkodery po odchycení SDL eventů.
 
-** Text viewer
-For viewing text files (it will not work correctly with non text files)
+# Manuál
+## Průzkumník souborů
+### Funkce
+Program slouží na procházení kořenového systému souborů.
+Dokáže spouštět soubory a otevírat obrázky nebo textové soubory.
+Lze vyvolat kontextové menu, ve kterém lze otevřít kterýkoliv
+soubor v prohlížeči textu.
 
-More can be found in manual
+Program obsahuje jednoduchý návod k obsluze,
+ke kterému se jde dostat v hlavním menu.
+
+### (Virtuální) okna
+Program se skládá z oken, mezi kterými se přepíná.
+
+#### Výchozí menu
+
+Ve výchozím menu lze otevřít průzkumník souborů
+nebo si přečíst, jak se program ovládá.
+
+#### Průzkumník souborů
+
+Průzkumník souborů zobrazuje, v jaké složce
+se zrovna člověk nachází a soubory v ní.
+Lze se navigovat mezi složkami, zobrazit kontextové
+menu nebo spouštět soubory.
+
+#### Kontextové menu
+
+V kontextovém menu lze soubor spustit nebo ho
+zobrazit v prohlížeči textu.
+
+#### Dialog
+
+Dialogové okno se typicky ukáže při chybě.
+Je v něm zachycená chyba, která nastala.
+
+### Spouštění
+Program nepřijímá žádné argumenty, ty jsou ignorovány.
+
+Použití:
+`
+./file-browser
+`
+
+### LED pásek
+Na LED pásku se ukazuje vertikální pozice v průzkumníku souborů,
+aby bylo poznat, kolik souborů je ještě potřeba projít do konce
+složky.
+
+### Chybové stavy
+Chyby se hlásí přes dialogové okno.
+
+### Ovládání
+
+#### Standardní vstup
+- `h`, `j`, `k`, `l` - pohyb pohledu po souboru (doleva, dolů, nahoru, doprava)
+- `y`, `i`, `o`, `p` - pohyb o celou obrazovku pro rychlejší navigaci (doleva, dolů, nahoru, doprava)
+- `z`, `x` - přiblížení a oddálení textu
+- `n` - vrácení pohledu na začátek seznamu souborů
+- `m` - pohled na konec seznamu souborů
+- `e` - ukončení programu
+- `c` - kontextové menu souboru
+- `v` - potvrzení výběru (spuštění souboru / přepnutí složky)
+
+#### Rotační enkodery
+- První (červený) - horizontální posun pohledu
+- Druhý (zelený) - vertikální posun pohledu
+- Třetí (modrý) - přiblížení nebo oddálení textu
+- Tlačítko prvního enkoderu - ukončení programu / pohyb zpět
+- Tlačítko druhého enkoderu - kontextové menu souboru
+- Tlačítko třetího enkoderu - potvrzení výběru (spuštění souboru / přepnutí složky)
+## Prohlížeč textových souborů
+### Funkce
+Program zobrazí na LCD displeji text z textového souboru, lze se po něm pohybovat rotačními enkodery.
+Pokud program nedostane textový soubor, je možné, že ho nezobrazí korektně.
+
+### Spouštění
+Program nelze bez argumentů spustit, je vždy potřeba spustit s cestou k souboru s textem.
+Jinak program skončí s chybovým stavem vyobrazeným na RGB LEDkách.
+
+`
+./text-viewer [cesta-k-souboru]
+`
+
+### LED pásek
+Na LED pásku se ve fázi načítání ukazuje kolik dat je již načtených.
+Po načtení se zobrazuje vertikální pozice v souboru podle toho, jak moc je soubor posunutý.
+
+### Chybové stavy
+Pokud se program nespustí správně, jedna z RGB LEDek se rozsvítí červeně.
+
+Levá RGB LED znamená, že nebyl předán žádný argument. Pravá RGB LED znamená, že soubor se nepodařilo načíst,
+neexistuje nebo k němu nejsou přístupová práva. Konkrétní chybová hláška se objeví na standardním výstupu.
+
+### Ovládání
+
+#### Standardní vstup
+- `h`, `j`, `k`, `l` - pohyb pohledu po souboru (doleva, dolů, nahoru, doprava)
+- `y`, `i`, `o`, `p` - pohyb o celou obrazovku pro rychlejší navigaci (doleva, dolů, nahoru, doprava)
+- `z`, `x` - přiblížení a oddálení textu
+- `n` - vrácení pohledu na začátek souboru
+- `m` - pohled na konec souboru
+- `e` - ukončení programu
+
+#### Rotační enkodery
+- První (červený) - horizontální posun pohledu
+- Druhý (zelený) - vertikální posun pohledu
+- Třetí (modrý) - přiblížení nebo oddálení textu
+- Tlačítko prvního enkoderu - ukončení programu
+- Tlačítko druhého enkoderu - vrácení pohledu na začátek souboru
+- Tlačítko třetího enkoderu - pohled na konec souboru
+## Prohlížeč obrázků
+### Funkce
+Program zobrazí na LCD displeji přeškálovaný obrázek, který se dá přibližovat pomocí rotačních enkoderů nebo standardního vstupu.
+Při spuštění programu je obrázek oddálený tak, aby se vešel celý na obrazovku.
+
+### Spouštění
+Program nelze bez argumentů spustit, je vždy potřeba spustit s cestou k souboru s obrázkem.
+Jinak program skončí s chybovým stavem vyobrazeným na RGB LEDkách.
+
+Použití:
+`
+./image-viewer [cesta-k-souboru]
+`
+
+### Podporované formáty
+- jpg
+- png
+- ppm
+
+Formáty se rozlišují podle jejich hlaviček, koncovky se nerozlišují
+
+### LED pásek
+Na LED pásku se ve fázi načítání ukazuje kolik dat je již načtených.
+Po načtení se zobrazuje horizontální pozice kurzoru na obrázku
+pro snazší orientaci při větším zvětšení.
+
+### Chybové stavy
+Pokud se program nespustí správně, jedna z RGB LEDek se rozsvítí červeně.
+
+Levá RGB LED znamená, že nebyl předán žádný argument. Pravá RGB LED znamená, že soubor se nepodařilo načíst,
+neexistuje, není správný formát nebo k němu nejsou přístupová práva. Konkrétní chybová hláška se objeví na standardním výstupu.
+
+### Ovládání
+Program má kurzor, podle kterého se určuje, kam se přibližuje. Kurzor se zobrazí, když se s ním hýbe a chvilku potom. 
+
+#### Standardní vstup
+- `h`, `j`, `k`, `l` - ovládání kurzoru nebo posunu po celém obrázku v závislosti na módu, viz klávesa m (doleva, dolů, nahoru, doprava)
+- `z`, `x` - přiblížení a oddálení obrázku (do místa, kde je kurzor)
+- `r` - vrácení do původního stavu (oddálí obrázek a nastaví kurzor doprostřed obrázku)
+- `m` - přepnutí mezi módy pohybu po obrázku nebo pohybu kurzorem (při módu pohybu po obrázku svítí RGB LEDky zeleně)
+- `e` - ukončení programu
+
+#### Rotační enkodery
+- První (červený) - posun kurzoru horizontálně nebo posun horizontálně celého obrázku (viz tlačítko druhého enkoderu)
+- Druhý (zelený) - posun kurzoru vertikálně nebo posun vertikálně celého obrázku (viz tlačítko druhého enkoderu)
+- Třetí (modrý) - přiblížení a oddálení
+- Tlačítko prvního enkoderu - ukončení programu
+- Tlačítko druhého enkoderu - přepnutí mezi módy pohybu po obrázku nebo pohybu kurzorem
+- Tlačítko třetího enkoderu - vrácení do původního stavu přiblížení
+
+# Kompilace, instalace, spouštění
+Na kompilaci je použit `Makefile`.
+
+## Křížová kompilace pro MZAPO
+Pro křížovou kompilaci je zapotřebí `arm-gnueabihf-gcc` a dynamické knihovny
+`libjpeg` verze 62, `libpng` verze 16 a `libmagic` verze 1 pro MZAPO.
+
+Soubory se po kompilaci uloží do složky `bin`, pro spuštění je potřeba
+je překopírovat na MZAPO.
+
+Překopírování jde realizovat pomocí ssh, lze použít `make`, konkrétně
+`
+TARGET_IP=[ip-addr] make copy-executable
+`
+kde za `ip-addr` je potřeba dosadit ip adresu MZAPO.
+V základním režimu se počítá s tím, že je použit SSH tunel
+a `mzapo-root-key` (SSH klíč pro mzapo) se nachází
+na cestě ``/.ssh/mzapo-root-key`. Pro změnu základního nastavení
+stačí změnit konfiguraci v `Makefile` v kořenu projektu.
+Možné konfigurace jsou zakomentované na řádcích začínajících
+`SSHOPTIONS`
+
+Pro spuštění lze využít sériového portu nebo ssh. Případně pomocí `make`,
+na spuštění průzkumníku souborů:
+`
+TARGET_IP=[ip-addr] make run
+`
+případně pro spuštění prohlížeče obrázků `run-image-viewer`
+a pro spuštění prohlížeče textových souborů `run-text-viewer`.
+Pro předání argumentu slouží environment proměnná ARG
+
+Například lze použít
+`
+TARGET_IP=[ip-addr] ARG=/path/to/image make run-image-viewer
+`
+nebo
+`
+TARGET_IP=[ip-addr] ARG=/path/to/image make run-text-viewer
+`
+
+Program je třeba spouštět s cwd ve složce, kde se nachází binární soubory.
+## Kompilace na osobní počítač
+Pro lepší ladění je možnost program zkompilovat
+pro osobní počítač, kde je displej simulován
+pomocí SDL okna.
+
+Pro kompilaci pro počítač lze využít environment proměnné `COMPUTER`.
+Lze pak využít
+`
+COMPUTER=1 make
+`
+
+Po kompilaci jsou soubory ve složce `bin` v kořenu projektu.
+Lze je spustit napřímo s potřebnými parametry viz Manuál.
+
+Je potřeba překopírovat soubory ze složky `copy/` do složky `bin/` a program spouštět
+s cwd ve složce, kde se nachází všechny binární soubory

@@ 0,0 1,12 @@
+* Dokumentace semestrální práce
+
+** Manuál (česky)
+Manuál společně s návodem, jak program zkompilovat a spustit lze najít v souboru user-manual.pdf.
+
+** Kód (anglicky)
+Dokumentace kódu byla vygenerována přes Doxygen a její vstupní html index
+se nachází v `doxy/html/index.html`
+
+** Blokové schéma (anglicky)
+Diagramy s blokovým schématem programů se nachází ve složce diagrams/,
+nachází se zde 3 diagramy, pro každý program zvlášť.

@@ 1,12 1,12 @@
 #+TITLE: APO - Semestrální práce
 #+SUBTITLE: Průzkumník souborů, prohlížeč obrázků, textových souborů
 #+AUTHOR: František Boháček
-#+DATE: červen 2020
+#+DATE: červen 2021
 
 * Zadání
 Semestrální práce bude rozdělena do 3 jednotlivých programů vypracovaných pro MZAPO. Hlavní z nich
-bude průzkumník souborů, ve kterém bude možné procházet celý kořenový souborový systém a také externí zařízení.
-Průzkumník bude umět základní operace jako kopírování, přesouvání a mazání souborů. Dále spouštět spustitelné soubory
+bude průzkumník souborů, ve kterém bude možné procházet celý kořenový souborový systém +a také externí zařízení+.
++Průzkumník bude umět základní operace jako kopírování, přesouvání a mazání souborů+. Dále spouštět spustitelné soubory
 a pro obrázky, resp. pro textové soubory otevřít prohlížeč obrázků, resp. textových souborů.
 
 Prohlížeč obrázků je druhý program, který bude umět otevřít formáty jpeg, png a ppm. Přes rotační enkodery


@@ 21,8 21,89 @@ Standardní výstup bude použit k logování hlášek o tom, co program právě
 
 Pro rychlejší ladění bude možnost programy spouštět na osobním počítači, kde se jako displej využije SDL okno.
 
+** Zhodnocení splnění zadání
+U průzkumníku souborů jsem bohužel nestihl implementovat základní operace jako přesouvání, mazání nebo kopírování souborů.
+Stejně tak průzkumník souborů neumí sám namountovat externí zařízení jak bylo v plánu. Průzkumník tak umí pouze procházet složky,
+otevírat soubory v příslušném programu (podle mime typu).
+Na druhou stranu z prohlížeče textových souborů i obrázků se mi podařilo implementovat vše ze zadání
+jak pro ovládání přes rotační enkodery nebo přes standardní vstup.
+
+Program na rychlejší lazení se mi povedlo vytvořit tak, že z většiny simuluje reálnou nízkou úroveň periferií. V kódu je tak potřeba
+minimum změn, aby místo na MZAPO běžel na osobních počítačích, je potřeba pouze změnit inicializaci programu, mapovací funkci nahradit
+vlastní mapovací funkcí a změnit posílání dat a příkazů displeji. Ovládání RGB LEDek i LED pásku zůstává stejné, není potřeba žádný zásah
+do kódu. Šlo by i jednoduše implementovat rotační enkodery po odchycení SDL eventů.
+
 * Manuál
 ** Průzkumník souborů
+*** Funkce
+Program slouží na procházení kořenového systému souborů.
+Dokáže spouštět soubory a otevírat obrázky nebo textové soubory.
+Lze vyvolat kontextové menu, ve kterém lze otevřít kterýkoliv
+soubor v prohlížeči textu.
+
+Program obsahuje jednoduchý návod k obsluze,
+ke kterému se jde dostat v hlavním menu.
+
+*** (Virtuální) okna
+Program se skládá z oken, mezi kterými se přepíná.
+
+**** Výchozí menu
+
+Ve výchozím menu lze otevřít průzkumník souborů
+nebo si přečíst, jak se program ovládá.
+
+**** Průzkumník souborů
+
+Průzkumník souborů zobrazuje, v jaké složce
+se zrovna člověk nachází a soubory v ní.
+Lze se navigovat mezi složkami, zobrazit kontextové
+menu nebo spouštět soubory.
+
+**** Kontextové menu
+
+V kontextovém menu lze soubor spustit nebo ho
+zobrazit v prohlížeči textu.
+
+**** Dialog
+
+Dialogové okno se typicky ukáže při chybě.
+Je v něm zachycená chyba, která nastala.
+
+*** Spouštění
+Program nepřijímá žádné argumenty, ty jsou ignorovány.
+
+Použití:
+#+begin_src
+./file-browser
+#+end_src
+
+*** LED pásek
+Na LED pásku se ukazuje vertikální pozice v průzkumníku souborů,
+aby bylo poznat, kolik souborů je ještě potřeba projít do konce
+složky.
+
+*** Chybové stavy
+Chyby se hlásí přes dialogové okno.
+
+*** Ovládání
+
+**** Standardní vstup
+- ~h~, ~j~, ~k~, ~l~ - pohyb pohledu po souboru (doleva, dolů, nahoru, doprava)
+- ~y~, ~i~, ~o~, ~p~ - pohyb o celou obrazovku pro rychlejší navigaci (doleva, dolů, nahoru, doprava)
+- ~z~, ~x~ - přiblížení a oddálení textu
+- ~n~ - vrácení pohledu na začátek seznamu souborů
+- ~m~ - pohled na konec seznamu souborů
+- ~e~ - ukončení programu
+- ~c~ - kontextové menu souboru
+- ~v~ - potvrzení výběru (spuštění souboru / přepnutí složky)
+
+**** Rotační enkodery
+- První (červený) - horizontální posun pohledu
+- Druhý (zelený) - vertikální posun pohledu
+- Třetí (modrý) - přiblížení nebo oddálení textu
+- Tlačítko prvního enkoderu - ukončení programu / pohyb zpět
+- Tlačítko druhého enkoderu - kontextové menu souboru
+- Tlačítko třetího enkoderu - potvrzení výběru (spuštění souboru / přepnutí složky)
 ** Prohlížeč textových souborů
 *** Funkce
 Program zobrazí na LCD displeji text z textového souboru, lze se po něm pohybovat rotačními enkodery.


@@ 51,13 132,16 @@ neexistuje nebo k němu nejsou přístupová práva. Konkrétní chybová hláš
 
 **** Standardní vstup
 - ~h~, ~j~, ~k~, ~l~ - pohyb pohledu po souboru (doleva, dolů, nahoru, doprava)
-- ~r~ - vrácení pohledu na začátek souboru
-- ~t~ - pohled na konec souboru
+- ~y~, ~i~, ~o~, ~p~ - pohyb o celou obrazovku pro rychlejší navigaci (doleva, dolů, nahoru, doprava)
+- ~z~, ~x~ - přiblížení a oddálení textu
+- ~n~ - vrácení pohledu na začátek souboru
+- ~m~ - pohled na konec souboru
 - ~e~ - ukončení programu
 
 **** Rotační enkodery
 - První (červený) - horizontální posun pohledu
 - Druhý (zelený) - vertikální posun pohledu
+- Třetí (modrý) - přiblížení nebo oddálení textu
 - Tlačítko prvního enkoderu - ukončení programu
 - Tlačítko druhého enkoderu - vrácení pohledu na začátek souboru
 - Tlačítko třetího enkoderu - pohled na konec souboru


@@ 100,7 184,7 @@ Program má kurzor, podle kterého se určuje, kam se přibližuje. Kurzor se zo
 - ~h~, ~j~, ~k~, ~l~ - ovládání kurzoru nebo posunu po celém obrázku v závislosti na módu, viz klávesa m (doleva, dolů, nahoru, doprava)
 - ~z~, ~x~ - přiblížení a oddálení obrázku (do místa, kde je kurzor)
 - ~r~ - vrácení do původního stavu (oddálí obrázek a nastaví kurzor doprostřed obrázku)
-- ~m~ - přepnutí mezi módy pohybu po obrázku nebo pohybu kurzorem
+- ~m~ - přepnutí mezi módy pohybu po obrázku nebo pohybu kurzorem (při módu pohybu po obrázku svítí RGB LEDky zeleně)
 - ~e~ - ukončení programu
 
 **** Rotační enkodery


@@ 112,7 196,7 @@ Program má kurzor, podle kterého se určuje, kam se přibližuje. Kurzor se zo
 - Tlačítko třetího enkoderu - vrácení do původního stavu přiblížení
 
 * Kompilace, instalace, spouštění
-Na kompilaci je použit Makefile.
+Na kompilaci je použit ~Makefile~.
 
 ** Křížová kompilace pro MZAPO
 Pro křížovou kompilaci je zapotřebí ~arm-gnueabihf-gcc~ a dynamické knihovny


@@ 126,6 210,12 @@ Překopírování jde realizovat pomocí ssh, lze použít ~make~, konkrétně
 TARGET_IP=[ip-addr] make copy-executable
 #+end_src
 kde za ~ip-addr~ je potřeba dosadit ip adresu MZAPO.
+V základním režimu se počítá s tím, že je použit SSH tunel
+a ~mzapo-root-key~ (SSH klíč pro mzapo) se nachází
+na cestě ~~/.ssh/mzapo-root-key~. Pro změnu základního nastavení
+stačí změnit konfiguraci v ~Makefile~ v kořenu projektu.
+Možné konfigurace jsou zakomentované na řádcích začínajících
+~SSHOPTIONS~
 
 Pro spuštění lze využít sériového portu nebo ssh. Případně pomocí ~make~,
 na spuštění průzkumníku souborů:


@@ 144,6 234,8 @@ nebo
 #+begin_src
 TARGET_IP=[ip-addr] ARG=/path/to/image make run-text-viewer
 #+end_src
+
+Program je třeba spouštět s cwd ve složce, kde se nachází binární soubory.
 ** Kompilace na osobní počítač
 Pro lepší ladění je možnost program zkompilovat
 pro osobní počítač, kde je displej simulován


@@ 157,3 249,6 @@ COMPUTER=1 make
 
 Po kompilaci jsou soubory ve složce ~bin~ v kořenu projektu.
 Lze je spustit napřímo s potřebnými parametry viz Manuál.
+
+Je potřeba překopírovat soubory ze složky ~copy/~ do složky ~bin/~ a program spouštět
+s cwd ve složce, kde se nachází všechny binární soubory