From d252cd0b5e423f8de061be0175a654b48500a81c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franti=C5=A1ek=20Boh=C3=A1=C4=8Dek?= Date: Wed, 30 Jun 2021 09:39:17 +0200 Subject: [PATCH] docs: add manual to readme --- README.md | 254 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 240 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 8a3bd81bdb21867c6ba048cbc068e22c1ed1e86e..47c1fba80451fb8e611921357357c1c20dda0e4c 100644 --- a/README.md +++ b/README.md @@ -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