This page contains instructions how to work with education kit. For a description of hardware and peripherals, see the Education Kit MicroZed APO.

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 SSH for access. If you have only Microsoft Windows only computer available, you can use PuTTY program to access serial port and connect to the board through SSH. You will need FTDI USB to serial converter driver for serial port connection.

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

ssh-add /opt/zynq/ssh-connect/mzapo-root-key

ssh-add-mzapo-key

ssh root@192.168.202.xxx

The camera name, two kits below and connected DC motor number attached in the brackets.

192.168.223.201 (mzapoa)
192.168.223.202 (mzapob)

The laboratory access is realized as virtual room in the 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/.

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 ~/.ssh
chmod go-rwx ~/.ssh/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 ~/.ssh/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 ~/.ssh/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 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.

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 (see page about FEE GitLab version control system).

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

The template provides next files

• Makefile - rules to build application and its remote execution
• change_me.c - source code example with main function - file template which shuld be renamed
• font_prop14x16.c - font using proportional widths of glipths with maximal width 14 and height 16 pixels
• font_rom8x16.c - fixed width font
• font_types.h - font description structure type definition
• mzapo_parlcd.h - low level LCD display control and data write functions declaration
• mzapo_parlcd.c - low level LCD display control and data write functions implementation
• mzapo_phys.h - prototype declaration of the function which allows map physical address range into virtual/user/application address space
• mzapo_phys.c - implementation of the function which allows map physical address range into virtual/user/application address space
• 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 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 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).

Use of lightweight Geany editor and development environment is suggested for student without previous exerience.

Guide how to setup Eclipse development environment for development environment.

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 ~/.ssh/
chmod go-rwx ~/.ssh/mzapo-root-key
ssh-add ~/.ssh/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 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).

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

The KN:E-2 laboratory is connected behind 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

ssh -R 2222:localhost:22 restricted_user@147.32.xxx.xxx

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

scp login@postel.felk.cvut.cz:/opt/apo/zynq/ssh-connect/mzapo-root-key ~/.ssh/
chmod 600 ~/.ssh/mzapo-root-key
ssh-add ~/.ssh/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