====== 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ři práci v laboratoři =====
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'' nebo ještě jednodušeji ''tio -b 115200 /dev/ttyUSB0'' z terminálu.
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]]. Z počítače, kde je nainstalovaný pouze OS Windows, je možné na sériový port i přes SSH přistupovat k zařízení s využitím programu [[https://en.wikipedia.org/wiki/PuTTY|PuTTY]].
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).
ssh -i /opt/zynq/ssh-connect/mzapo-root-key root@192.168.202.xxx
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
/opt/zynq/sshfs-mount-target 192.168.202.xxx
Případně lze privátní klíč přidat do ssh agenta:
ssh-add /opt/zynq/ssh-connect/mzapo-root-key
Připravený příkaz pro rychlé zavedení klíče
ssh-add-mzapo-key
A potom se lze k systému připojit přes ssh s uživatelem root již bez zadávání klíče nebo hesla:
ssh root@192.168.202.xxx
Více o použití protokolu SSH, SSH klíčů a SSH agenta najdete v článku o [[courses:b35apo:documentation:remote:start|vzdáleném přístupu]].
===== Aktuální (22.5.2022) IP adresy přípravků pro online přístup =====
V závorce je uvedené číslo připojeného motoru.
192.168.223.115 (2)\\
192.168.223.102 (1)
===== Vzdálený přístup do laboratoře =====
Laboratoř je přístupná přes instalaci konferenčního systému [[https://bigbluebutton.org/|BigBluButton]].
Jedná se o lokální/experimentální instalaci na osobním/desktopovém počítači, s problémy se obracejte
na jeho majitele (Pavel Píša), přístupovou bránu zařídil Ing. Daniel Večerka. Brána pro vstup do virtuální laboratoře
je na adrese [[https://cw.felk.cvut.cz/courses/apo/|https://cw.felk.cvut.cz/courses/apo/]].
Připojení k přípravkům s oprávněními uživatele ''root'' je autentizované na základě vlastnictví privátního klíče ''mzapo-root-key''. Při navázání spojení s požadavkem na přístup na uživatelský/systémový účet ''root'' je vlastnictví privátního klíče ověřené veřejným klíčem uloženým v seznamu oprávnění k přístupu k účtu na přípravcích. Privátní klíč je k dispozici všem uživatelům v adresáři ''/opt/zynq/ssh-connect'' na serveru ''postel''. Zkopírovat ho lze na vlastní počítač příkazem
scp cvut_login@postel.felk.cvut.cz:/opt/zynq/ssh-connect/mzapo-root-key ~/.ssh/
chmod 600 ~/.ssh/mzapo-root-key
K vybranému přípravku se poté lze připojit protunelování do lokální sítě laboratoře KN:E-2 přes server ''postel''.
ssh -i ~/.ssh/mzapo-root-key -o 'ProxyJump=cvut_login@postel.felk.cvut.cz' root@192.168.202.xxx
Klíč je také možné si po dobu běhu sezení na vývojovém počítači uložit do SSH agenta
ssh-add ~/.ssh/mzapo-root-key
a poté již není nutné klíč v každém příkazu uvádět. Adresář ''~/.ssh/'' zde používáme, protože na windows subsystem for Linux vznikají potíže se změnou přístupových práv k souborům uloženým přímo v domovském (''~/'') adresáři.
Další možností vzdáleného přístupu k přípravkům je otevření sezení na serveru ''postel'' nebo na počítačích v laboratoři [[..:remote:start|KN:E-23]], kdy lze postupovat stejně jako při lokální práci v laboratoři.
===== Počáteční šablona pro tvorbu aplikace =====
Šablonu aplikace najdete na počítačích v laboratoři v adresáři
/opt/apo/mzapo_template
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]])
git clone https://gitlab.fel.cvut.cz/b35apo/mzapo_template.git
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''
SOURCES = change_me.c mzapo_phys.c mzapo_parlcd.c
#SOURCES += font_prop14x16.c font_rom8x16.c
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
make
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
make clean all
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''
make TARGET_IP=192.168.202.xx run
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í
ssh-add /opt/apo/zynq/ssh-connect/mzapo-root-key
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]]
make TARGET_IP=192.168.202.xx debug
Na počítači, ze kterého je cílový systém laděný, musí být nainstalované balíčky ''ddd'' a ''gdb-multiarch'' (případně s úpravou ''Makefile'' arm-linux-gnueabihf-gdb).
===== Vývojová prostředí pro tvorbu programů =====
Doporučení pro studenty bez předchozí preference je na našich systémech používat editor/prostředí [[https://geany.org/|Geany]].
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 z vlastního počítače mimo laboratoř (přes veřejný internet) =====
Pro kompilaci na Ubuntu/Debian systemu nainstalujde křížový kompilátor
sudo apt install crossbuild-essential-armhf
Zkopírujte privátní klíč pro SSH připojení k deskám MZ_APO z lokální sítě učebny
scp ctu_login@postel.felk.cvut.cz:/opt/zynq/ssh-connect/mzapo-root-key .
chmod go-rwx mzapo-root-key
ssh-add mzapo-root-key
Vyzkoušíme, že se na systém můžeme připojit přes SSH
ssh -o 'ProxyJump=ctu_login@postel.felk.cvut.cz' root@192.168.202.xxx
Když projde tak ''exit''.
Zeditujte ''Makefile'', v proměnné ''TARGET_IP'' nastavte konkrétní adresu cílové desky ve vnitřní síti.
Odkomentujte řádku s nastavením SSH pro spojení přes prostředníka s veřejnou adresou a nahraďte
přihlašovací jméno ''ctu_login'' svým přiděleným přihlašovacím jménem do sítě ČVUT.
TARGET_IP ?= 192.168.202.xxx
SSH_OPTIONS=-o 'ProxyJump=ctu_login@postel.felk.cvut.cz'
Spusťte aplikaci na vzdáleném systému
make run
Pro urychlení přihlašování na server ''postel.felk.cvut.cz'' bez nutnosti vypisovat heslo můžete také využít ověřování privátním klíčem. Pokud ještě privátní klíč na svém systému nemáte nagenerovaný, tak použijte
ssh-keygen
Správné je svůj klíč i na svém počítači chránit heslem. Více na o klíčích na stránce [[..:githowto:start|Jak používat GIT s SSH klíčem]]. Pokud je klíč chráněný heslem, tak je ho potřeba po přihlášení do sezení aktivovat příkazem
ssh-add
Dále informujeme server ''postel.felk.cvut.cz'' o naší důvěře, volbě, že ṕro ověření našeho předaného účtu stačí otisk daného klíče
ssh-copy-id ctu_login@postel.felk.cvut.cz
Dále by již ''make run'' mělo startovat aplikaci bez nutnosti jakékoliv interakce ze strany uživatele (žádné dotazy na hesla atd.).
===== Využití SSH tunelu do lokální sítě laboratoře připojené na veřejnou přes NAT =====
Alternativou, k ''ProxyJump'' z předchozí kapitoly je využít trvalé SSH spojení na server ''postel.felk.cvut.cz'' pro tunelování přístupu na SSH port 22 na vybraném přípravku. Přihlášení přes server s veřejnou adresou se provede jen jednou, je tedy menší riziko, že ochrana serveru vyhodnotí rychlé připojování jako útok. Opětovná připojování jsou takto i výrazně rychlejší.
Tunel na port požadovaného kitu se vytvoří v samostatném okně se shellem příkazem
ssh -nNT ctu_login@postel.felk.cvut.cz -L 2222:192.168.202.xxx:22
Aktuální Makefile na to je na toto použití připravené, je potřeba povolit
TARGET_IP = 127.0.0.1
SSH_OPTIONS=-o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -o "Port=2222"
SSH_GDB_TUNNEL_REQUIRED=y
===== 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
ip addr show
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.
adduser restricted_user
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.
ssh -R 2222:localhost:22 restricted_user@147.32.xxx.xxx
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.
ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -p 2222 root@localhost
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
scp login@postel.felk.cvut.cz:/opt/apo/zynq/ssh-connect/mzapo-root-key .
chmod 600 mzapo-root-key
ssh-add mzapo-root-key
Při volání ''make'' z adresáře se šablonou aplikace pak bude nutné přidat parametr ''SSH_OPTIONS''
make SSH_OPTIONS="-o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o Port=2222" TARGET_IP=localhost run
Pro opakované použití lze provést nastavení parametrů přímo v souboru ''Makefile''.
===== Připojení přípravku přímo k hostovskému PC (v případě zapůjčených desek) =====
V základní nastavení se přípravek chová jako DHCP klient a očekává přidělení IP adresy po připojení síťového kabelu. Pokud není možné zprostředkovat připojení k DHCP serveru, je možné nastavit statické IP adresy hostovského PC i přípravku a propojit tyto napřímo.
K nastavení statické IP adresy je možné využít příkaz ''ip'' ve formátu:
ip addr add [IP_ADDRESS] dev [DEVICE]
kde ''IP_ADDRESS'' je požadovaná IP adresa a ''DEVICE'' je název síťového rozhranní přes které je přípravek připojen. Seznam všech rozhranní je možné vypsat příkazem ''ip addr'' nebo ''ifconfig''.
Nastavit statickou IP adresu na přípravku lze pomocí sériového rozhraní (například přes ''gtkterm''), po přihlášení jménem a heslem, například pomocí příkazu, v doporučené sekvenci příkazů je před nastavení pevné IP adresy přidané vypnutí DHCP klienta a nakonec pak aktivace rozhraní:
ifdown eth0
ip addr add 192.168.135.14/24 dev eth0
ip link set dev eth0 up
V hostitelském PC je pak nutné s oprávněním správce systému (navýšení práv ''sudo -i'') nastavit jinou IP adresu ze stejné podsítě (192.168.135.xxx), například:
ip addr add 192.168.135.101/24 dev enx00e04c18681b
kde ''enx00e04c18681b'' je příklad názvu síťového rozhranní usb-to-ethernet donglu.
Následně je možné komunikovat s deskou již běžným způsobem přes nastavenou IP adresu.
V případě výpadku spojení zkontrolujte, že deska IP adresu nezapomněla. IP adresu
na hostitelském počítači lze nastavit také z grafického prostředí například
jako další profil pro drátové připojení s nastavenou pevnou adresou. V takovém
případě se nastavuje rozsah lokální sítě většinou maskou, pro uvedený případ 255.255.255.0.