From 70ca9b52c3c636d70ad7dda1c1cc1f39f973268b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franti=C5=A1ek=20Boh=C3=A1=C4=8Dek?= Date: Fri, 16 Jun 2023 09:04:18 +0200 Subject: [PATCH] chore: translate readme to english --- README.md | 371 +++++++++++++++++++++++++++--------------------------- 1 file changed, 186 insertions(+), 185 deletions(-) diff --git a/README.md b/README.md index 47c1fba..5997a74 100644 --- a/README.md +++ b/README.md @@ -1,248 +1,249 @@ -# 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ů. - -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ý. - -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ů. - -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í. - -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. +This is code from a semestral project for computer architecture. +It works on a MicroZed evaluation kit. +This kit contains: +- XilinX Zynq-7000 +- Dual ARM Cortex-A9 +- a display, knobs, buttons, LEDs +- and more + +![MicroZed evaluation kit](mzapo-sdl/mzapo.png "MicroZed evaluation kit") + +It is running Linux operating system. + +# Assignment (the crossed out parts were not finished) +The semestral project will be separated to 3 individual programs. +The main program will be a file browser. It will be possible to browse +through the whole root file system ~~as well as an external device~~. +The browser will be able to ~~perform simple operations such as copying, +moving or removing files.~~ It will be able to execute arbitrary files +and support opening some file formats in specified programs. + +The second part of the project will be an image viewer. The file browser +will be able to open image files using this program. +It will support jpeg, png and ppm formats. +It will be possible to use the rotation encoders to move a cursor +over the image. It will be possible to zoom to the cursor. + +The last part of the project will be a text file viewer. This file viewer +may open any file, but is intended mainly for plain text formats. +Again, it will be possible to zoom in on the text and move through the file. + +For faster debugging, a simple program that may be executed on personal computer +will be made. SDL window will be used. + +## Evaluation ofthe completion of the assignment +The file browser unfortunately does not support operations such as moving, removing or copying files. +It cannot mount external devices as planned. Only the root file system may be browsed through. +However it may open files using mime types as planned. +On the other hand, the text as well as image browsers support all features that +were in the assignment. + +# Manual +## File browser +### Function +The program may browse through the root file system. +It may execute files and open images or plain text files. +A context menu may be used to open any file in the plain text viewer. + +The program contains instructions accessible from the main menu. + +### Virtual windows +The program consists of windows that may be switched. + +### Default menu +It's possible to either enter the file browser +or read the instructions in the main menu. + +#### File browser +The file explorer displays what folder you are currently in and the files in it. +One can navigate between folders, view context menus or launch files. + +#### Context menu +You can run the file in the context menu or view it in the text viewer. #### Dialog +A dialog box will typically be shown when an error occurs. +It contains the error that occurred. -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. +### File browser entry +The file browser does not have any arguments. -Použití: +Usage: ` ./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. +### LED strip +The LED strip shows the vertical position in the file explorer, +to show how many files still need to be gone through before the end +folder. -### Chybové stavy -Chyby se hlásí přes dialogové okno. +### Error conditions +Errors are reported via a dialog box. -### Ovládání +### Controls -#### 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) +#### Standard input +- `h`, `j`, `k`, `l` - move the view around the file (left, down, up, right) +- `y`, `i`, `o`, `p` - move full screen for faster navigation (left, down, up, right) +- `z`, `x` - zoom in and out of text +- `n` - return the view to the top of the file list +- `m` - view to the end of the file list +- `e` - exit the program +- `c` - file context menu +- `v` - confirm selection (launch file / switch folder) -#### 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ě. +#### Rotary encoders +- First (red) - horizontal view shift +- Second (green) - vertical view shift +- Third (blue) - zoom in or out of text +- First encoder button - end program / move back +- Second encoder button - file context menu +- Third encoder button - confirm selection (start file / switch folder) +## Text file viewer +### Functions +The program displays the text from a text file on the LCD display, it can be moved around with the rotary encoders. +If the program does not receive the text file, it is possible that it will not display it correctly. -### 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. +### Running +The program cannot be run without arguments, it always needs to be run with the path to the text file. +Otherwise the program will end up with the error condition shown on the RGB LEDs. ` -./text-viewer [cesta-k-souboru] +./text-viewer [path-to-file] ` -### 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ý. +### LED strip +The LED strip shows how much data is already loaded during the loading phase. +After loading, it shows the vertical position in the file according to how much the file is shifted. -### Chybové stavy -Pokud se program nespustí správně, jedna z RGB LEDek se rozsvítí červeně. +### Error conditions +If the program does not start correctly, one of the RGB LEDs will light up red. -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. +The left RGB LED indicates that no argument has been passed. The right RGB LED means that the file failed to load, +does not exist or has no access rights. A specific error message appears on the standard output. -### Ovládání +### Control -#### 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 +#### Standard input +- `h`, `j`, `k`, `l` - move the view around the file (left, down, up, right) +- `y`, `i`, `o`, `p` - move full screen for faster navigation (left, down, up, right) +- `z`, `x` - zoom in and out of text +- `n` - return the view to the beginning of the file +- `m` - view to the end of the file +- `e` - exit the program -#### 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. +#### Rotary encoders +- First (red) - horizontal view shift +- Second (green) - vertical view shift +- Third (blue) - zoom in or out of text +- First encoder button - exit program +- Second encoder button - return the view to the beginning of the file +- Third encoder button - view to the end of the file +## Image viewer +### Functions +The program displays a rescaled image on the LCD that can be zoomed in using the rotary encoders or standard input. +When the program starts, the image is zoomed out to fit entirely on the screen. -### 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. +### Starting up +The program cannot be run without arguments, it always needs to be run with the path to the image file. +Otherwise the program will end with the error condition shown on the RGB LEDs. -Použití: +Usage: ` -./image-viewer [cesta-k-souboru] +./image-viewer [path-to-file] ` -### Podporované formáty +### Supported formats - jpg - png - ppm -Formáty se rozlišují podle jejich hlaviček, koncovky se nerozlišují +Formats are differentiated by their headers, endings are not differentiated -### 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í. +### LED strip +The LED strip shows how much data is already loaded during the loading phase. +After loading, the horizontal position of the cursor in the image is displayed +for easier orientation at higher magnification. -### Chybové stavy -Pokud se program nespustí správně, jedna z RGB LEDek se rozsvítí červeně. +### Error conditions +If the program does not start correctly, one of the RGB LEDs will light up red. -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. +The left RGB LED indicates that no argument has been passed. The right RGB LED means that the file failed to load, +it does not exist, the format is not correct or there are no access rights to it. A specific error message appears on the standard output. -### 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. +### Control +The program has a cursor that determines where to zoom in. The cursor appears when it is moved and a moment afterwards. -#### 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 +#### Standard input +- `h`, `j`, `k`, `l` - control the cursor or scroll across the image depending on the mode, see the m key (left, down, up, right) +- `z`, `x` - zoom in and out of the image (to where the cursor is) +- `r` - return to the original state (zooms out the image and sets the cursor in the middle of the image) +- `m` - switch between image or cursor movement modes (RGB LEDs light up green in image movement mode) +- `e` - exit the program -#### 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í +#### Rotary encoders +- First (red) - move the cursor horizontally or move the whole image horizontally (see button of the second encoder) +- Second (green) - move the cursor vertically or move the entire image vertically (see second encoder button) +- Third (blue) - zoom in and out +- First encoder button - exit the program +- Second encoder button - switch between image or cursor movement modes +- Third encoder button - return to the original zoom state -# Kompilace, instalace, spouštění -Na kompilaci je použit `Makefile`. +# Compilation, installation, startup +`Makefile` is used for compilation. -## 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. +## Cross compilation for MZAPO +For cross compilation, `arm-gnueabihf-gcc` and dynamic libraries are needed +`libjpeg` version 62, `libpng` version 16 and `libmagic` version 1 for MZAPO. -Soubory se po kompilaci uloží do složky `bin`, pro spuštění je potřeba -je překopírovat na MZAPO. +After compilation, the files are saved in the `bin` folder, to run +copy them to MZAPO. -Překopírování jde realizovat pomocí ssh, lze použít `make`, konkrétně +The copying can be done via ssh, you can use `make`, specifically ` 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 +where after `ip-addr` the ip address of MZAPO needs to be inserted. +In basic mode, it is assumed that the SSH tunnel is used +and the `mzapo-root-key` (SSH key for mzapo) is located +on the path ``/.ssh/mzapo-root-key`. To change the basic settings +just change the configuration in the `Makefile` in the project root. +The possible configurations are commented out on the lines starting `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ů: +You can use the serial port or ssh to boot. Alternatively, use `make`, +to launch the file explorer: ` 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 +or to launch the `run-image-viewer` image viewer +and to launch the text file viewer `run-text-viewer`. +The ARG environment variable is used to pass the argument -Například lze použít +For example, you can use ` TARGET_IP=[ip-addr] ARG=/path/to/image make run-image-viewer ` -nebo +or ` 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. +The program should be run with cwd in the folder where the binaries are located. +## Compiling for a personal computer +For better debugging it is possible to compile the program +for a personal computer where the display is simulated +using the SDL window. -Pro kompilaci pro počítač lze využít environment proměnné `COMPUTER`. -Lze pak využít +To compile for a PC, the environment variable `COMPUTER` can be used. +It is then possible to use ` 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. +After compilation, the files are in the `bin` folder in the root of the project. +They can be run directly with the necessary parameters, see the manual. -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 +You need to copy the files from the `copy/` folder to the `bin/` folder and run the program +with cwd in the folder where all the binary files are located -- 2.48.1