====== Documentation How to Work with MicroZed APO ======
This page contains instructions how to work with education kit. For a description of hardware and peripherals, see the [[..:mz_apo:start|Education Kit MicroZed APO]].
====== Work with a Kit in Lab Locally or at Home when Lent ======
Serial connection, parameters:
* Device: /dev/ttyUSB0
* Baudrate: 115200
* No partity and single stopbit
* Login: root
* The password for local serial port login will be provided by lab tutor
There are many utilities providing access to serial port communication, for example ''gtkterm'' or even direct commandline unitilty ''tio -b 115200 /dev/ttyUSB0'' from terminal.
After you obtain IP address of the board it is much more comfortable to use [[https://www.openssh.com/manual.html|SSH]] for access. If you have only Microsoft Windows only computer available, you can use [[https://en.wikipedia.org/wiki/PuTTY|PuTTY]] program to access serial port and connect to the board through SSH. You will need [[https://ftdichip.com/|FTDI]] USB to serial converter driver for serial port connection.
A kit IP address can be obtained from the graphic which appears on the LCD at end of boot sequence. Address is represented in binary form, each byte/number from most significant bit (7 .. MSB) on the left to least significant bit (0 .. LSB) on the right.
SSH private key is required for login onto the board. It is available in lab systems in ''/opt/zynq/ssh-connect''
ssh -i /opt/zynq/ssh-connect/mzapo-root-key root@192.168.202.xxx
The program SCP can be used to transfer files between host PC system and a target kit or it is possible to mount complete target kit filesystem tree into host system ''/tmp'' directory
/opt/zynq/sshfs-mount-target 192.168.202.xxx
The private SSH key used for a target kit access can be loaded into ssh agent for subsequent accesses till the end of session on the host system:
ssh-add /opt/zynq/ssh-connect/mzapo-root-key
There is shortcut for easy SSH key load n the lab systems
ssh-add-mzapo-key
Subsequent SSH connections to root account do not require explicit key parameter nor password then:
ssh root@192.168.202.xxx
===== Actual (22.5.2022) List of IP Addresses of Kits Avalilable Online =====
The camera name, two kits below and connected DC motor number attached in the brackets.
192.168.223.115 (2)\\
192.168.223.102 (1)
===== Remote Access to the Laboratory with Kits =====
The laboratory access is realized as virtual room in the [[https://bigbluebutton.org/|BigBluButton]] lerning platform.
This B35APO instance of the system is run on personal/desktop computer, please report problems to t Pavel Píša. The access gateway implemented Ing. Daniel Večerka. The gateway to access virtual laboratory is at the address [[https://cw.felk.cvut.cz/courses/apo/|https://cw.felk.cvut.cz/courses/apo/]].
The access to the ''root'' account on the kits is granted on base of check of private key ''mzapo-root-key'' ownership on the host side. After initial connection to the kit requesting login to the user/system administrator ''root'' account target requests to sign sent data by private key which public fingerprint is found in ''authorized_keys'' list for the account. Private key is available in directory ''/opt/zynq/ssh-connect'' on the server ''postel'' to all logged in CTU users. It can be copied to own computer by command
scp cvut_login@postel.felk.cvut.cz:/opt/zynq/ssh-connect/mzapo-root-key .
chmod go-rwx mzapo-root-key
The permission change is necessary, because in other case SSH warns and refuses connection stating that key can be easily stolen by some other use on the computer.
Connection to the selected kit is then available trough tunnel into the laboratory KN:E-2 local network realized by ''postel'' server.
ssh -i mzapo-root-key -o 'ProxyJump=cvut_login@postel.felk.cvut.cz' root@192.168.202.xxx
Key can be stored for time of actual host system user session into SSH agent
ssh-add mzapo-root-key
and then key parameter can be omitted in subsequent connections.
Another option to access kits in the lab is to login into ''postel'' postel server or connect SSH or even start remote graphics session on [[..:remote:start|KN:E-23]] laboratory computers, then it is possible to work and communicate with target systems same way as when accessed locally in the laboratory.
===== Template to Start work on Application for Target System =====
The template is located on the diskless system in the laboratory or on ''postel'' server in directory
/opt/apo/mzapo_template
The better choice is to obtain template from a version control system and then setup own repository ([[..:..:documentation:githowto:start|see page about FEE GitLab version control system]]).
git clone https://gitlab.fel.cvut.cz/b35apo/mzapo_template.git
The template provides next files
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/Makefile|Makefile]] - rules to build application and its remote execution
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/change_me.c|change_me.c]] - source code example with main function - file template which shuld be renamed
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_prop14x16.c|font_prop14x16.c]] - font using proportional widths of glipths with maximal width 14 and height 16 pixels
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_rom8x16.c|font_rom8x16.c]] - fixed width font
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/font_types.h|font_types.h]] - font description structure type definition
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_parlcd.h|mzapo_parlcd.h]] - low level LCD display control and data write functions declaration
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_parlcd.c|mzapo_parlcd.c]] - low level LCD display control and data write functions implementation
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_phys.h|mzapo_phys.h]] - prototype declaration of the function which allows map physical address range into virtual/user/application address space
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_phys.c|mzapo_phys.c]] - implementation of the function which allows map physical address range into virtual/user/application address space
* [[https://gitlab.fel.cvut.cz/b35apo/mzapo_template/blob/master/mzapo_regs.h|mzapo_regs.h]] - definition of base addresses and registers fields of the peripherals provided by education design for MZ_APO kits
More detailed description of the registers can be found in [[..:..:documentation:mz_apo:start|documentation of MZ_APO kits and design]].
The rules, source files list and target executable name in the ''Makefile'' rules for ''make'' utility should be adjusted for own application.
Application will be build from one or more source files, for the C language files use suffix ''*.c'', for C++ language ''*.cpp''.
The templete file ''change_me.c'' provides example with ''main'' function, this file should be renamed to the application specific name, abbreviation which makes sense.
The variable ''SOURCES'' is filled by the list of the source files, see corresponding lines in ''Makefile''
SOURCES = change_me.c mzapo_phys.c mzapo_parlcd.c
#SOURCES += font_prop14x16.c font_rom8x16.c
The name of the main application should be adjusted on the first line. If the font files are used then enable (remove ''#'' character) the second line.
The list of files on above lines can be extended or the line with plus-equal can be repeated.
Header files (''*.h'') should not be inserted into the list.
The filename of the target executable is defined by ''TARGET_EXE'' variable value.
Build/compile of the application is realized by invocation of make utility
make
When called without explicit target, the first one found is inwoked, ''all'' in the above case.
Target ''clean'' is used to remove generated, compiled files (object files, binary target and automatically generated dependency files. The targets can be combined
make clean all
The make check source changes/dependecny to taget build time relations, if you invoke ''run'' target a some file is changed, the rebuild of dependent files is realized
make TARGET_IP=192.168.202.xx run
Above command updates builds if needed, transfer files to the target system with provided IP address over SSH but it requires already available/activated SSH key in SSH agent for the given user session
ssh-add /opt/apo/zynq/ssh-connect/mzapo-root-key
The application is transferred to the ''/tmp'' tree subdirectory created according to the user login name. Application is then run on the target system. Its standard input, output and error output are connected over SSH session into involing terminal on the host system side.
The application can be debugged remotely in the [[https://www.gnu.org/software/ddd/|Data Display Debugger]] installed on the host system
make TARGET_IP=192.168.202.xx debug
The ''ddd'' and ''gdb-multiarch'' packages on the host system has to be installed (if ''Makefile'' is ajusted even arm-linux-gnueabihf-gdb ARM only version can be used).
===== Development Environments for Applications Development =====
Use of lightweight [[https://geany.org/|Geany]] editor and development environment is suggested for student without previous exerience.
Guide how to [[courses:b35apo:documentation:eclipse:start|setup Eclipse development environment]] for development environment.
===== Connection to the Kits from Own Computer from Public Internet) =====
To build target applications on Ubuntu/Debian systems, install cross-compiler
sudo apt install crossbuild-essential-armhf
Copy private key for SSH connection to the MZ_APO kits from laboratory local installation
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
Test that you can connect to the target system over SSH
ssh -o 'ProxyJump=ctu_login@postel.felk.cvut.cz' root@192.168.202.xxx
If connection works execute ''exit''.
Edit ''Makefile'', set variable ''TARGET_IP'' to chosen target kit IP address on internal laboratory network. Enable (remove ''#'' comment character) on start of the line with SSH parameters for connection with use of proxy and change ''ctu_login'' placeholder with your assigned CTU network login name .
TARGET_IP ?= 192.168.202.xxx
SSH_OPTIONS=-o 'ProxyJump=ctu_login@postel.felk.cvut.cz'
Run application on the target system
make run
To speedup and simplify login process to the ''postel.felk.cvut.cz'' server, private key authentication can be used instead of password repeated typing. If you do not have generated private key for your account on your computer, you can generate the one by command
ssh-keygen
The correct practice is to protect key on you computer by password. More about this topic on the page [[..:githowto:start|How to Use GIT with SSH Key]]. If the key is password protected, then it should be activated for given session by command
ssh-add
Then register your key as authorized to access your account on the ''postel.felk.cvut.cz'' server. Next command copies public part of your key to the account ''authorised_keys''
ssh-copy-id ctu_login@postel.felk.cvut.cz
Sbsequent ''make run'' invocation of build utility should start compiled application without need of user interaction (password typing).
===== Use of SSH Tunnel to the Laboratory Local Network Connected to Public Internet via NAT =====
An alternative to ''ProxyJump'' option from the previous chapter is to use a permanent SSH connection to the ''postel.felk.cvut.cz'' server to tunnel access to SSH port 22 on the selected development kit. Logging into the server with a public address happens once, so there is less risk that server protection will evaluate fast connecting as an attack. Reconnecting is significantly faster this way as well.
A tunnel to the port of the selected kit is created in a separate shell command window by
ssh -nNT ctu_login@postel.felk.cvut.cz -L 2222:192.168.202.xxx:22
The current Makefile is ready for this use, you need to enable
TARGET_IP = 127.0.0.1
SSH_OPTIONS=-o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -o "Port=2222"
SSH_GDB_TUNNEL_REQUIRED=y
===== Alternative Connection to the Laboratory from Public Network or EDUROAM =====
The KN:E-2 laboratory is connected behind [[https://en.wikipedia.org/wiki/Network_address_translation|NAT]]. Direct connection from own desktop computer connected to public EDUROAM IP address is not possible to the systems and target kits in the laboratory. If you the SSH server is running on your computer with public IP then you can create reverse tunnel.
Find public IP address of your computer
ip addr show
Crete auxiliary/temporal account on your computer with minimal level of permission to access files and system capabilities.
adduser restricted_user
and select password. Then SSH reverse tunnel can be build from the kit
ssh -R 2222:localhost:22 restricted_user@147.32.xxx.xxx
The tunnel listens on the 2222 port on your computer and each attempt to connect it is passed/translated as attempt to open local destionation localhost:22, where SSH server on the kits answers
The further connections to the kit are then possible through redirecting/teleport 2222.
ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" -p 2222 root@localhost
The kit private key for access kits ''root'' account is required. It can be downloaded and activated in the SSH agent by
scp login@postel.felk.cvut.cz:/opt/apo/zynq/ssh-connect/mzapo-root-key .
chmod 600 mzapo-root-key
ssh-add mzapo-root-key
The ''make'' program invocation has to specify ''SSH_OPTIONS''
make SSH_OPTIONS="-o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o Port=2222" TARGET_IP=localhost run
The option can be filled in rules ''Makefile'' for subsequent uses. The server ''postel'' can be used to build tunnel as well.