====== Nápověda k práci s přípravkem MicroZed APO ======

Tato stránka obsahuje návody k práci s přípravkem. Popis hardware a periferií naleznete na stránce [[..:mz_apo:start|Přípravek MicroZed APO]].

====== Připojení k přípravku ======

Přístup přes sériový port, parametry:
  * Zařízení: /dev/ttyUSB0
  * Přenosová rychlost: 115200
  * Žádná parita a jeden stopbit
  * Login: root
  * Heslo bude sděleno na cvičení
Použít lze například program ''gtkterm''.

Po zjištění adresy připojené desky je výhodnější použít přístup přes [[https://www.openssh.com/manual.html|SSH]]

<note>
Adresu desky je možné zjistit i z výpisu na obrazovce. Adresa je zobrazená binárně v každé řádce vždy od nejvýznamnějšího bitu (MSB) k bitu nejméně významnému (LSB).
</note>

<code>
ssh -i /opt/zynq/ssh-connect/mzapo-root-key root@192.168.202.xxx
</code>

Pro přenos souborů mezi cílovým systémem a hostitelským PC
lze použít program SCP nebo si lze připojit kompletní souborový
systém cílové desky do podadresáře ''/tmp'' příkazem

<code>
/opt/zynq/sshfs-mount-target 192.168.202.xxx
</code>

<note>
Případně lze privátní klíč přidat do ssh agenta:
<code>
ssh-add /opt/zynq/ssh-connect/mzapo-root-key
</code>

Připravený příkaz pro rychlé zavedení klíče
<code>
ssh-add-mzapo-key
</code>

A potom se k systému připojit přes ssh s uživatelem root již bez zadávání klíče nebo hesla:
<code>
ssh root@192.168.202.xxx
</code>
</note>

===== Počáteční šablona pro tvorbu aplikace =====

Šablonu aplikace najdete na počítačích v laboratoři v adresáři

<code>
/opt/apo/mzapo_template
</code>

Výhodnější je však šablonu nahrát z verzovacího systému a založit si poté pro projekt vlastní repozitář ([[..:..:documentation:githowto:start|viz stránka z dokumentace]])

<code>
git clone https://gitlab.fel.cvut.cz/b35apo/mzapo_template.git
</code>

Součástí šablony jsou následující soubory

  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/Makefile|Makefile]] - pravidla pro sestavení a vzdálené spouštění aplikace
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/change_me.c|change_me.c]] - zdrojový kód s hlavní funkcí main - šablona určená k přejmenování
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_prop14x16.c|font_prop14x16.c]] - proporcionální font s maximální šířkou 14 a výškou 16 bodu
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_rom8x16.c|font_rom8x16.c]] - font s fixní šířkou
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_types.h|font_types.h]] - definice typu použitého pro popis fontu
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_parlcd.h|mzapo_parlcd.h]] - deklarace funkcí pro nízkoúrovňový přístup k LCD display
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_parlcd.c|mzapo_parlcd.c]] - implementace funkcí pro nízkoúrovňový přístup k LCD display
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_phys.h|mzapo_phys.h]] - deklarace funkce pro mapování fyzického rozsahu adres do aplikačního procesu
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_phys.c|mzapo_phys.c]] - implementace funkce pro mapování fyzického rozsahu adres do aplikačního procesu
  * [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_regs.h|mzapo_regs.h]] - definice bázových adres a registrů výukového návrhu MZ_APO

Podrobnější popis registrů návrhu lze nalézt v [[..:..:documentation:mz_apo:start|dokumentaci desky MZ_APO]].

Pravidla ''Makefile'' pro sestavovací program je potřeba upravit pro vlastní aplikaci.
Aplikace se bude skládat z jednoho nebo více zdrojových souborů v jazyce
C (soubory s příponou ''*.c'') a nebo v jazyce C++ (soubory s příponou ''*.cpp'').
Příkladem s hlavní funkci ''main'' je vzorový soubor ''change_me.c'', který by měl
být nahrazen, přejmenován za soubor specifický pro danou aplikaci.

Do proměnné ''SOURCES'' je nastaven seznam zdrojových souborů, viz následující
část souboru ''Makefile''

<code>
SOURCES = change_me.c mzapo_phys.c mzapo_parlcd.c
#SOURCES += font_prop14x16.c font_rom8x16.c
</code>

V první řádce je potřeba upravit jméno hlavního souboru aplikace.
Pokud jsou využité fonty, je potřeba druhou řádku odkomentovat.
Do seznamu je možné na těchto dvou řádkách nebo opakováním
řádku s plus-rovná-se přidat i další potřebné soubory.
Hlavičkové soubory (''*.h'') se do seznamu neuvádí.

Jméno žádaného binárního spustitelného souboru je nastavené
v do proměnné ''TARGET_EXE''.

Překlad je proveden prostým zavoláním sestavovacího programu

<code>
make
</code>

kdy je vyvoláno první nalezené pravidlo ''all''.

Pro smazání generovaných souborů (objektové soubory, binární kód aplikace a automaticky
generované závislosti) slouží cíl ''clean''. Cíle lze i kombinovat

<code>
make clean all
</code>

Případná kompilace při změně a spuštění aplikace na vzdálené jednotce je provedeno
při vyvolání cíle ''run''

<code>
make TARGET_IP=192.168.202.xx run
</code>

Automatické přihlášení, přenos dat a spuštění aplikace na cílovém zařízení
s danou IP adresou vyžaduje již zavedený privátní klíč v SSH agentovi pro dané sezení
<code>
ssh-add /opt/apo/zynq/ssh-connect/mzapo-root-key
</code>

Aplikace je nejdříve překopírovaná do podadresáře ''/tmp'' vytvořeného podle
přihlašovacího jména uživatele a poté je aplikace spuštěné s tím, že standardní
vstup i výstup je k dispozici na straně vývojářského počítače přes SSH spojení.

Aplikaci je možné na cílové platformě i ladit s využitím grafického ladícího programu [[https://www.gnu.org/software/ddd/|Data Display Debugger]]

<code>
make TARGET_IP=192.168.202.xx debug
</code>

===== Vývojová prostředí pro tvorbu programů =====

Stránka s návodem jak [[courses:b35apo:documentation:eclipse:start|nastavit vývojové prostředí Eclipse]] pro práci s přípravkem.

===== Připojení k přípravku v laboratoři ze sítě EDUROAM =====

Síť laboratoře K2 je za [[https://en.wikipedia.org/wiki/Network_address_translation|NAT]]em. Proto není možné přímé spojení z vlastního počítače na desku.
Pokud nám však na počítači běží SSH server, tak je možné vytvořit reverzní tunel.

Nejdříve zjistíme adresu našeho počítače v síti EDUROAM

<code>
ip addr show
</code>

Ideálně si na svém počítači vytvoříme pomocný uživatelský účet s nízkou úrovní oprávnění a přístupů k souborům.
<code>
adduser restricted_user
</code>
a zvolíme heslo. Z přípravku se připojíme k svému počítači přes SSH a vytvoříme reverzní tunel.

<code>
ssh -R 2222:localhost:22 restricted_user@147.32.xxx.xxx
</code>
Vytvořený tunel naslouchá na portu 2222 na našem počítači a každý pokus o připojení na port 2222
přenese na přípravek a zde provede pokus o otevření portu localhost:22, kde naslouchá
SSH server na přípravku.

K přípravku se pak připojujeme přes tunel tak, že se připojíme k lokálnímu teleportovanému portu 2222.
<code>
ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -p 2222 root@localhost
</code>
K úspěšnému přihlášení budeme ještě potřebovat privátní klíč, který otvírá vstup
k přípravku. Ten si lze stáhnout ze serveru postel a poté zavést například následujícími příkazy
<code>
scp login@postel.felk.cvut.cz:/opt/apo/zynq/ssh-connect/mzapo-root-key .
chmod 600 mzapo-root-key
ssh-add mzapo-root-key
</code>

Při volání ''make'' z adresáře se šablonou aplikace pak bude nutné přidat parametr ''SSH_OPTIONS''
<code>
make SSH_OPTIONS="-o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o Port=2222" TARGET_IP=localhost run
</code>
Pro opakované použití lze provést nastavení parametrů přímo v souboru ''Makefile''.