To start up your DEBIX Model A, the following accessories are needed:

• A computer monitor or television(It’s suggested that you use a display with HDMI input, if your display uses an HDMI connection and has built-in speakers, you can use it to output sound).
• A display cable to connect your monitor to DEBIX Model A.
• A computer keyboard and mouse(All standard USB keyboards and mouses will work with your DEBIX Model A, wireless keyboards and mice will work if already paired).
• A good quality power supply(we recommend buying power supply from the following website https://www.okdo.com/p/okdo-usb-c-fixed-head-power-supply-uk-plug/). DEBIX Model A uses type C power supply.
• An Micro SD card(we recommend a minimum of 8GB micro SD card and use Etcher to install an operating system onto it).

1.1.1. Optional Items

• A network (Ethernet) cable to connect your DEBIX Model A to your local network and the Internet.

1.1.2.Troubleshooting

You can get help with setting up your DEBIX Model A in our discord.

DEBIX Model A recommend the use of Etcher to install an operating system on your SD card. You will need another computer with an SD card reader to install the image. We recommend a minimum of 8GB micro SD card.

1.2.1. Downloading an Image

We recommend using Etcher tool to flash images. Images for DEBIX Model A computers are available from website https://debix.io/.

It’s recommended to use Etcher to write images to SD cards, so it is a good place to start. If you’re looking for more advanced options on Linux, you can use the standard command line tools below(When using dd command, you should be very careful, because it may overwrite any partition of your machine.)

1.3.1 Discovering the SD Card mountpoint and unmounting it

• To check the devices connected to your machine, just run lsblk -p . The output should look like the following: 

• If your computer has a slot for SD cards, insert the card. If not, insert the card into an SD card reader, then connect the reader to your computer.

• Open the terminal, run lsblk -p again. The new device that has appeared is your SD card, you can also usually tell from the listed device size. The naming of the device will follow the format described in the next paragraph. 

• As shown in the picture above, the left column of the results from the lsblk -p command gives the device name of your SD card and the names of any partitions on it. It lists device name /dev/mmcblk1 (with partition name /dev/mmcblk1p1). The right column indicates where the partitions have been mounted.

• If any partitions on the SD card have been mounted, unmount them all with umount, for example umount /dev/mmcblk1p1 (replace mmcblk1 with your SD card’s device name, and change the number for any other partitions).

1.3.2 Copying the Image to the SD Card

Open a terminal, use the following command to write the image to the Micro SD card, do not forget to replace the input file if= argument with the path to your .img file, and the /dev/sdX in the output file of= argument with the correct device name. This is very important, as you will lose all the data on the hard drive if you provide the wrong device name. Make sure the device name is the name of the whole SD card as described above, not just a partition. For example: mmcblk1, not mmcblk1p1.

sudo dd if=debix-ubuntu-20211022.img of=/dev/sdX bs=4M conv=fsync

1.3.3 Copying a Zipped Image to the SD Card

It is possible to combine the unzip and SD copying process into one command. The following command unzips the zip file(replace debix-ubuntu-20211022.bz2 with the appropriate zip filename), and pipes the output directly to the dd command. This in turn copies it to the SD card, as described in the previous section.

bunzip2 -c debix-ubuntu-20211022.bz2 | sudo dd of=/dev/sdX bs=4M conv=fsync

1.3.4 Checking the Image Copy Progress

By default, the dd command does not give any information about its progress. To see the progress of the copy operation, you can run the dd command with the status option.

sudo dd if=debix-ubuntu-20211022.img of=/dev/sdX bs=4M conv=fsync status=progress

1.3.5 Optional: Checking Whether the Image was Correctly Written to the SD Card

After dd command is finished, you can check whether the writing process to the SD card has no problem by dd-ing from the card back to another image on your hard disk, truncating the new image to the same size as the original, and then running diff on those two images.

• If the image is much smaller than the SD card, it’s not needed to read back the whole SD card, since it will be mostly empty. So you need to check the number of blocks that were written to the card by the dd command. At the end of its run, dd will have displayed the number of blocks written as below：

xxx+0 records in
yyy+0 records out

sudo  dd if=/dev/sdX of=from-sd-card.img bs=4M count=xxx

sudo truncate --reference debix-ubuntu-20211022.img from-sd-card.img

diff -s from-sd-card.img debix-ubuntu-20211022.img

Sometimes, maybe you want to prepare your desired Linux system other than the Ubuntu20.04 we provided. Then, the u-boot file, kernel, u-boot flash method are as below:

• Download u-boot file: imx-boot-imx8mpevk-sd.bin-flash_evk
  

• Flash u-boot file through command: dd if=imx-boot-imx8mpevk-sd.bin-flash_evk of=/dev/mmcblk1 bs=1k seek=32 conv=fsync, substitute the device name(/dev/mmcblk1) with your corresponding one.
  

• kernel: https://github.com/debix-tech/linux
  

It’s recommended to use Etcher to write images to SD cards. However, if you do not want to use the Etcher you can still copy an operating system to the card from the command line.

1.5.1 Finding the SD Card

Insert the SD card in the slot, or connect the SD card reader with the SD card inside, and type diskutil list at the command line. You should see something like this:

Here the SD Card is /dev/disk2. However your disk and partition list may vary.

1.5.2 Copying the Image

Warning

diskutil unmountDisk /dev/diskN

You can then copy the image.

sudo dd bs=1m if=path_of_your_image.img of=/dev/rdiskN; sync

Remember to replace N with the disk number. Do not provide a compressed image(e.g. *.img.bz2) in the above command, or the image copied to the SD card will not boot.

Caution

sudo diskutil eject /dev/rdiskN

1.5.3 Troubleshooting

• If the following error occurs dd: /dev/rdiskN: Resource busy, you need to unmount the volume first sudo diskutil unmountDisk /dev/diskN.
• If the following error occurs dd: bs: illegal numeric value, change the block size bs=1m to bs=1M.
• If the following error occurs dd: /dev/rdiskN: Operation not permitted, go to System Preferences--> Security & Privacy --> Privacy --> Files and Folders --> Give Removable Volumes access to Terminal.
• If the following error occurs dd: /dev/rdiskN: Permission denied, the partition table of the SD card is being protected against being overwritten by mac OS.

You can use the following command to erase the SD card’s partition table:

sudo diskutil partitionDisk /dev/diskN 1 MBR "Free Space" "%noformat%" 100%

That command will also set the permissions on the device to allow writing, after running this command, you will get the output like this:

1.6.1 balenaEtcher

• Download the Windows installer from balena.io (https://www.balena.io/etcher/)
• Run balenaEtcher and select the corresponding unzipped OS image file
• Select the SD card drive
• Finally, click Flash to write the corresponding OS image to the SD card

• You’ll see a progress bar. Once complete, a notification “Flash Complete!” will show, the utility will automatically unmount the SD card so it’s safe to remove it from your computer.

1.6.2 Win32DiskImager

• Insert the SD card into your SD card reader. If you have an SD card slot or an SD adapter in a USB port, you can also use them. Please remember the drive letter assigned to the SD card. You can see the drive letter in the left hand column of Windows Explorer, for example E:.
• Download the Win32DiskImager utility and install it.
• Run the Win32DiskImager utility from your desktop or menu. In the interactive dialogue, select the image file you extracted earlier; In the device box, select the drive letter of the SD card. Be careful to select the correct drive: if wrong drive is chosen, you may destroy the data on your computer’s hard disk! If you are using an SD card slot in your computer, and can’t see the drive in the Win32DiskImager window, try using an external SD adapter.
• Click 'Write' and wait for the write to complete.
• Exit the imager and eject the SD card.

DEBIX Model A computers use a micro SD card.

1.7.1 Recommended Capacity

We recommend using an SD card of 8GB or greater capacity with DEBIX Model A OS.

1.7.2 Troubleshooting

We recommend buying an SD card from one of our official resellers. 

If you are having problems with your SD card:

• Check the SD card. The best way to avoid fake SD cards is to always buy from a reputable supplier.
• Check the power supply: we recommend using an official DEBIX Model A power supply.
• The power supply cable may also have problems.
• Make sure you shut down the operating system correctly before you power down the DEBIX Model A.

Generally speaking, you will need to connect the DEBIX Model A with a display(a computer monitor or a television). of course, you can also set your DEBIX Model A headless.

1.8.1. Connecting Using HDMI

The DEBIX Model A has an HDMI port which you can connect directly to a monitor or TV with an HDMI cable.

If a monitor with built-in speakers are connected to your DEBIX with HDMI cable, you can use it to output sound.

1.8.2. Connecting Using DVI

If your monitors only have a DVI port, you can use an HDMI-to-DVI cable, or an HDMI cable with a DVI adapter.

Caution

1.8.3. Connecting Using VGA

If your monitors only have a VGA port, you can use an HDMI-to-VGA adapter. Note that VGA does not support audio.

DEBIX OS is a free operating system based on Ubuntu20.04. We are continuously optimizing this OS to meet the needs of developers and users.

It's suggested that you update your DEBIX OS regularly to keep your software up to date. Every several days, the DEBIX OS will release a new version that may contain new features or have fixed several bugs. Right now, DEBIX only support upgrading the OS through re-burning the image to the Micro SD card.

2.2.1.Using APT

On Ubuntu(which DEBIX OS used), the easiest way to manage packages is using the apt command line tool from a Terminal window.

2.2.1.1 Keeping your Operating System up to Date

A list of software sources are kept by APT on DEBIX in the file /etc/apt/sources.list. Before installing software, It’s needed to run command apt update to update the package list:

sudo apt update

Then, run the following command to upgrade all your installed packages to the latest versions:

sudo apt full-upgrade

Note that full-upgrade is used in preference to a simple upgrade, as it also picks up any dependency changes that may have been made.

Generally speaking, doing this will keep your installation up to date for the particular major DEBIX OS release you are using. It will not update from one major release to another. This upgrade command only updates the already installed packages, it will not update the DEBIX system, it’s needed to re-burn the updated image to the SD card to upgrade to the latest DEBIX system.

2.2.1.2. Running Out of Space

You'd better run the command df -h to check the free disk space, the space needed by the command sudo apt full-upgrade will show once it's executed. If the remaining space of the disk is not enough for upgrading, use command sudo apt auto-clean to free up some space.

2.2.1.3. Searching for Software

Using a given keyword, you can search the archives for a package with command apt-cache search:

More information about a package can be gotten through command apt-cache show:

apt-cache show ssh 
Package: ssh 
Architecture: all 
Version: 1:8.2p1-4 
Multi-Arch: foreign 
Priority: optional 
Section: net 
Source: openssh 
Origin: Ubuntu 
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> 
Original-Maintainer: Debian OpenSSH Maintainers <debian-ssh@lists.debian.org> 
Bugs: https://bugs.launchpad.net/ubuntu/+filebug 
Installed-Size: 117 
Pre-Depends: dpkg (>= 1.17.5) 
Depends: openssh-client (>= 1:8.2p1-4), openssh-server (>= 1:8.2p1-4) 
Filename: pool/main/o/openssh/ssh_8.2p1-4_all.deb 
Size: 5072 
MD5sum: 8458a9ef29438a18bc9b5147b8c07c21 
SHA1: aaaadb79c9d54f3b74d0c5ad6248f364514384ef 
SHA256: 0b95e6a28e5d081c277ec84217c4662546e58b2ea9a498533bdbcea8f835fb67 
Homepage: http://www.openssh.com/ 
Description-en: secure shell client and server (metapackage) 
This metapackage is a convenient way to install both the OpenSSH client 
and the OpenSSH server. It provides nothing in and of itself, so you 
may remove it if nothing depends on it. 
Description-md5: b00e309365895c14a10af55945efb136

sudo apt install qtwayland5

After typing this command, the terminal may prompt you to enter Y to continue the installation. You can bypass the this interaction by adding the -y flag to the command:

sudo apt install qtwayland5 -y

2.2.1.5. Uninstalling a Package with APT

You can uninstall a package with apt remove:

sudo apt remove qtwayland5

After executing this command, you will be prompted to confirm the removal. If you provide -y option in the command line, the command will auto-confirm.

If you do not need this package any longer, you can completely remove the package with command  apt purge:

sudo apt purge qtwayland5

You can use a standard USB webcam to take pictures and videos on DEBIX.

Run the following command to install package fswebcam:

sudo apt install fswebcam

Run the following command to install v4l-utils:

sudo apt install v4l-utils

Run the following command to check the devices controlled by v4l2:

v4l2-ctl --list-devices

The output of the v4l2-ctl --list-device should be like this:

You can find the corresponding device node of the camera.

If you are not using the default DEBIX user account, you need to add your username to the video group, or the ‘permission denied’ error will occur(run the following command using DEBIX user account):

sudo usermod -a -G video <username>

2.4.1.fswebcam Basic Usage

The following examples are finished using the DEBIX user account.

Use the following command to take a picture and save it to the specified location:

fswebcam -d /dev/video2 -r 640x480 /home/debix/image.jpg

You should substitute the value ‘/dev/video2’ of option ‘-d’ to the corresponding one which is shown in the output of command v4l2-ctl --list-devices

If you do not want the banner with timestamp appear in your image, you can add ‘--no-banner’ option:

fswebcam -d /dev/video2 -r 640x480 --no-banner /home/debix/image.jpg

Note, the ‘--no-banner’ option should be located before ‘/home/debix/image.jgp’, otherwise, the banner with timestamp will still appear.

2.4.2.Using Cheese

2.4.3.Using mplayer to open USB cameras

sudo apt update 
sudo apt install mplayer 
mplayer tv:// -tv driver=v4l2:device=/dev/video2:width=640:height=480:fps=50 -vo x11

Note, the mplayer command cannot be executed remotely, you should run it from the desktop. Remember to substitute the ‘device=/dev/video2’ option with your corresponding one, which can be checked in the output of commandv4l2-ctl --list-devices.

For more usage of mplayer, you can find it on the internet.

2.4.4.Using python3-opencv to open USB cameras

Alternatively, you can write python scripts to open USB cameras.

sudo apt update 
sudo apt install python3-opencv

Create python script with the name of ‘camera_test.py’, of course, you can use your desired name. Put the following content into the script:

#!/usr/bin/python3 
import cv2 
# select /dev/video2 
cap = cv2.VideoCapture(2) 
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 800) 
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 600) 
cap.set(cv2.CAP_PROP_FPS, 20) 
winname="capture" 
while True: 
    ret, frame = cap.read() 
    cv2.imshow(winname, frame) 
    k = cv2.waitKey(1) 
    if cv2.getWindowProperty(winname, cv2.WND_PROP_AUTOSIZE) < 1: 
        break 
    elif k == 27: 
        break 
cap.release() 
cv2.destroyAllWindows() 

Note, sentence ‘cap = cv2.VideoCapture(2)’ corresponds to ‘/dev/video2’, you should substitute it with the correct value, which can be checked in the output of command v4l2-ctl --list-devices.

Finally, run the script through command python3 camera_test.py.

2.5.1.Basic Python usage

Hello world in Python:

print("Hello world")

2.5.1.1. Indentation

Python uses indentation for nesting. For example a function definition in Python:

def print_hello(): 
    print("Hello")

It's needed to add indentation here. The second indented line is a part of the loop. If another line is added without indentation, the newly added line does not belong to the loop. For example:

for i in range(2): 
    print("Hello, 1") 
    print("Hello, 2")

would print:

Hello, 1 
Hello, 2 
Hello, 1

However, if the following codes are used:

for i in range(2): 
    print("Hello, 1") 
print("Hello, 2")

would print:

Hello, 1 
Hello, 1 
Hello, 2

2.5.1.2. Variables

To define a variable and give the variable a value, you can do like this:

color = "blue" 
size = 20

Note that data types were not specified with these variables, as types are inferred, and can be changed later.

size = 20 
size += 1 # increment size by 1 
print(size) 

Note that there is a comment in the second line. In python, comments are started with sign #.

2.5.1.3. Comments

If you want to use single line comment, you can put a # sign at the beginning of the line. Whereas, if you want to use multi-line comments, you need to use triple quotes as below:

""" 
This program is used to print Hello. 
It’s very simple. 
""" 
print("Hello") 

2.5.1.4. Lists

Lists are collections of data of any type, python use lists to store data:

shapes = ["circle", "rectangle", "square"]

2.5.1.5. Iteration

If a data type is iterable, it means that you can loop over the values they contain. Take a list for example:

shapes = ["rectangle", "square", "circle"] 
for shape in shapes: 
    print(shape) 

This takes each item in the list shapes and prints out the item:

rectangle 
square 
circle 

In the above example, the word shape is used to denote each item in the list. You can also choose another word. It’s recommended that you choose descriptive words for variables, using singular form for each item, and plural form for lists, thus the readers can understand them easier.

Other data types are iterable, for example the string:

door_color = "orange" 
for char in door_color: 
    print(char) 

This loops over each character and prints them out:

o 
r 
a 
n 
g 
e

2.5.1.6. Range

The integer data type is not iterable and trying to iterate over it will produce an error. For example:

for i in 3: 
    print(i) 

The following error will occur:

TypeError: 'int' object is not iterable 

However you can make an iterable object using the range function:

for i in range(3): 
    print(i) 

Note that range(6) contains the numbers 0, 1, 2, 3, 4 and 5 (six numbers in total). To get the numbers 2 to 7 (inclusive) use range(2, 8).

2.5.1.7. Length

To find the length of a string or a list, you can use functions like len:

color = "purple" 
print(len(color)) # 6 
shapes = ["rectangle", "circle", "square", "triangle"] 
print(len(shapes)) # 4 

2.5.1.8. If statements

Just like the other programming languages , python also has if statements, you can use if statements for control flow:

color = "blue" 
if len(color) > 3: 
    print("The color is,") 
    print(color) 
else: 
    print("That color name is short,") print(name) 

2.5.2.Using the Command Line

Create a python file with certain contents, then you can execute it from the command line with command python3, e.g. python3 hello.py . An example is given in the following image.

2.5.3.Other Ways of Using Python

You can access the standard built-in python shell through command python3 in the terminal. This This shell does not have syntax highlighting or autocompletion. You can look back on the history of the commands you’ve entered by using the Up and Down keys. Use Ctrl + D or command exit() to exit.

2.5.3.1. IPython

IPython is an interactive python shell which supports auto-completion and auto-indentation. There are various useful built-in functions. You can install it through the following commands:

sudo apt install python3-pip 
sudo pip install ipython 

Run command  ipython from the command line, just use it the same as using python3. ipython has more features. Try typing range? and hitting Enter. You're shown information including the docstring for the range function.

You can try the following dictionary comprehension:

{color: color + "kind" for color in ["blue", "red", "green", "yellow"]}

This will pretty print the following:

{'blue': 'blue kind', 
'red': 'red kind', 
'green': 'green kind', 
'yellow': 'yellow kind'} 

In the standard Python shell, this would have printed on one line:

{'blue': 'blue kind', 'red': 'red kind', 'green': 'green kind', 'yellow': 'yellow kind'}

2.5.4.Installing Python Libraries

pip

You can use command pip to install packages from the Python Package Index (known as PyPI). You need to install pip first:

sudo apt install python3-pip

Then install Python packages (e.g. qtwayland5) with pip3:

sudo pip install qtwayland5

There are 40-pin headers along the edge of Debix boards. They are called the GPIO(general-purpose input/output) pins.

You can set the GPIO pins as input or output pins according to your needs. The numbering of the GPIO pins follows the default function numbering sequence of DEBIX, for example, UART/SPI/I2C/CAN/GPIO, i.e., the net aliases of J2 defined in DEBIX schematics, if changes to the default configuration are needed, software configuration is required.

2.6.1.Voltages

2.6.2.Outputs

2.6.3.Inputs

2.6.4.More

As well as simple input and output devices, the GPIO pins can be used with a variety of alternative functions, some are available on all pins, others on specific pins.

• lPWM (pulse-width modulation)
• Software PWM available on all pins
• Hardware PWM available on GPIO1_IO11, GPIO1_IO13
• SPI
• SPI1: ECSPI1_SS0, ECSPI1_MOSI, ECSPI1_MISO, ECSPI1_SCLK
• SPI2: ECSPI2_SS0, ECSPI2_MOSI, ECSPI2_MISO, ECSPI2_SCLK
• I2C
• I2C4_SCL, I2C4_SDA, I2C6_SCL, I2C6_SDA
• Serial
• UART2_RXD, UART2_TXD, system debug serial port as default
• UART3_RXD, UART3_TXD, UART4_RXD, UART4_TXD

2.6.5.GPIO debix-gpio

GPIO pins can be controlled through command debix-gpio in the command line. A handy reference can be accessed through command debix-gpio showGpioName.

There are two approaches to set wireless connections in DEBIX OS. One approach is through a GUI on DEBIX Desktop, The other approach is from the command line.

3.1.1.Configure the network from the desktop

By default, the wireless connections is enabled. In the upper right corner of DEBIX desktop, there are a group of icons together, including Ethernet icon, sound icon and power icon. Click the group of icons, unwrap the Wi-Fi Not Connected menu and click the Select Network sub-menu, the dialogue listing all available wireless networks will show as below:

The lock icons on the right side show whether a network is secured or not, and the icons on the right of the locks give an indication of the network signal strength. Click the network that you want to connect to, if the network you selected is secured, a dialogue box will prompt you to enter the network password:

Input the password and click Connect then wait for a while. If the network icon is flashing, it means that the wireless connection is being created. Once the network icon stops flashing and show the signal strength, it reveals that the network connection is OK and you can go to surf on the internet.

3.1.2.Configuring the network from the Command Line

3.1.2.1 Getting Wireless LAN Network Details

You need to run command sudo apt install wireless-tools to install iwlist to scan wireless networks. Run command sudo iwlist wlan0 scan, all available wireless networks, along with other useful information will occur, e.g., part of the output of command sudo iwlist wlan0 scan is as below:

In the above picture:

• 'ESSID:"polyhex_mi1"' is the name of the wireless network.
• 'IE: IEEE 802.11i/WPA2 Version 1' is the authentication used. To use this wireless network, you need to know the password of this network. The ESSID (ssid) for the examples below is polyhex_mi1 and the password (psk) is bohai2021.

3.1.2.2 Adding the Network Details to your DEBIX

• Create the wpa-supplicant configuration file:

sudo touch /etc/wpa_supplicant/wpa_supplicant.conf

• Add the following content to the configuration file, please remember to substitute the ssid value and psk value with your own values:

network={
    ssid="polyhex_mi1"
    psk="bohai2021"
}

The password can be given in plain text as the content provided above. The password can also be given as a pre-encrypted 32byte hexadecimal number, to get the corresponding pre-encrypted 32byte hexadecimal number, use utility wpa_passphrase. For example, you can generate the PSK with wpa_passphrase "polyhex_mi1", Then you will need to input the password of the wireless network "polyhex_mi1" (in this case bohai2021). The output is as follows:

network={ 
    ssid="polyhex_mi1" 
    #psk="bohai2021" psk=6c8ba976985110ccf61b592ad11889036ed9e5859c868144e447bfe248a058d9 
} 

To avoid revealing your wireless network password, you need to delete the plain text password line which is commented out. The wpa_passphrase tool requires a password with between 8 and 63 characters. If you want to use a more complex password, you can extract the content of a text file and use it as input for wpa_passphrase. Store the password in a text file and input it to wpa_passphrase by calling wpa_passphrase "polyhex_mi" < file_where_password_is_stored.

3.1.2.3 Connecting to the wireless network

• Insert the Ethernet cable to connect to the internet, run command sudo apt install isc-dhcp-client to get dhclient command, once finished installing isc-dhcp-client, unplug the Ethernet cable.
• Run command sudo wpa_supplicant -i wlan0 -B -c /etc/wpa_supplicant/wpa_supplicant.conf

Note

• Run command sudo dhcient wlan0 (Note, if there is no wlan0 in the output of command  ifconfig, you need to run sudo ifconfig wlan0 up beforehand)

network={ 
    ssid="polyhex_mi1" 
    key_mgmt=NONE 
} 

3.1.2.5 Hidden Networks

If you want to use a hidden network, you need to use scan_ssid in the wpa_supplicant file, for example, your wpa_supplicant.conf should be look like this:

network={ 
    ssid="yourHiddenSSID" 
    scan_ssid=1 
    psk="Your_wireless_network_password" 
} 

On DEBIX, you can set a routed wireless access point through the app “DEBIX Wifi AP” on the desktop. Just double click it, and input the AP name, AP password, and sudo password following the given wizard.

Alternatively, you can also set the routed wireless access point in the command line, use command debix_wifi_ap, input the sudo password, AP name and AP password, the access point will be created.

And you can check whether the access point is set up successfully through connecting to the created AP with your desktop computer or mobile phone.

Generally speaking, you can connect your HDMI-equipped monitor with DEBIX using a standard HDMI cable. DEBIX can drive one display, with a resolution up to 3840 x 2160.

As for external hard disk, SSD or USB stick, you can connect them to any of the USB ports on DEBIX, then mount the file system to access the data stored on it.

3.5.1.Mounting a Storage Device

The storage device can be mounted at a specific folder location. The /mnt folder is usually used to do this, e.g. /mnt/mydisk. Note that the folder must be empty.

• Insert the storage device into a USB port of DEBIX.
• Run command sudo lsblk -o UUID,NAME,FSTYPE,SIZE,MOUNTPOINT,LABEL,MODEL to list all the disk partitions.
• Use the SIZE, LABEL, and MODEL columns to identify the name of the disk partition that points to your storage device. For example, sda1.
• The FSTYPE column contains the filesystem type. If your storage device uses an exFAT file system, you need to install the exFAT driver, just run command sudo apt update, sudo apt install exfat-fuse , If your storage device uses an NTFS file system, you will have read-only access to it. If you want to write to the device, you can install the ntfs-3g driver: sudo apt update; sudo apt install ntfs-3g
• To get the location of the disk partition, run command sudo blkid

Take /dev/sda1 as an example.

• Run command sudo mkdir /mnt/mydisk to create a target folder to be the mount point of the storage device. The mount point here is named mydisk. You can specify your desired name:
• Run command sudo mount /dev/sda1 /mnt/mydisk to mount the storage device at the mount point you created.
• Run command ls /mnt/mydisk to verify that the storage device is mounted successfully by listing the contents.

3.5.2.Configure Automatic Mounting

The location where the storage device will be automatically mounted when DEBIX starts up can be defined in fstab file. In the fstab file, the disk partition is identified by the universally unique identifier (UUID).

• Run command sudo blkid to get the UUID of the disk partition:
• Find the disk partition from the list and note the UUID. For example, 68BA-C562.
• Run command sudo vim /etc/fstab to open the fstab file
• Add the content UUID=68BA-C562 /mnt/mydisk fstype defaults,auto,users,rw,nofail 0 0 to the fstab file, replace fstype with the type of your file system, which you found in the part of 'Mounting a storage device' above, for example: ntfs. If the filesystem type is FAT or NTFS, add, umask=000 immediately after nofail - this will allow all users full read/write access to every file on the storage device.

Now that you have set an entry in fstab, you can start up your DEBIX with or without the storage device attached. Before you unplug the device you must either shut down the DEBIX, or manually unmount it using the steps in 'Unmounting a storage device' below.

More information on each Linux command can be gotten through the specific manual page using the man command. e.g., man fstab.

3.5.3.Unmounting a Storage Device

When the DEBIX shuts down, the system takes care of unmounting the storage device so that it is safe to unplug it. If you want to manually unmount a device, run command sudo umount /mnt/mydisk, if the error 'target is busy' shows, this means that the storage device was not unmounted. If no error was displayed, you can safely unplug the device.

3.5.3.1 Dealing with 'target is busy'

The 'target is busy' message means there are files on the storage device that are in use by a program. To close the files, use the following procedure.

• Close any program which has open files on the storage device.
• If you have a terminal open, make sure that you are not in the folder where the storage device is mounted, or in a sub-folder of it.
• If you are still unable to unmount the storage device, you can use the lsof tool to check which program has files open on the device. If there is no lsof command in your DEBIX, run command sudo apt update and sudo apt install lsof. To use lsof, run command lsof /mnt/mydisk. For more information of lsof, you can refer to the man page of lsof.

3.6.1.Changing the Language

3.6.2.Configuring the Keyboard

3.6.3.Changing the Timezone

If the security of DEBIX is vulnerable, hackers will then be able to use it without your permission. So it’s recommended you ensure the security of DEBIX.

It depends on your aim of using DEBIX whether you need to set your DEBIX to a higher security level. For example, if you are simply using your DEBIX at home, behind a router with a firewall, then it is already quite secure by default.

However, if you wish to expose your DEBIX directly to the internet, you need to make some basic security changes.

Even if there is a firewall, you also need to take care of security seriously. In the following part, we will describe several ways to improve the security of your DEBIX, the following introduced methods may do not cover all aspects. For more security strategies, please refer to other related documents on the internet.

3.7.1.Change the Default Password

By default, each DEBIX running DEBIX OS will use the original username and password(debix:debix). So if these settings have not been changed, other users can have root access to the DEBIX and it’s dangerous. So it’s required to change the password. Run command passwd to change the password, it will prompt you to type in your new password and confirm it.

3.7.2.Improving SSH Security

It’s a widely-adopted way to use SSH to access a linux machine remotely. When using SSH, it requires to provide username and password to log in, and there are ways to make this more secure. An even more secure method is to use key based authentication.

3.7.2.1 Improving username/password security

If you have a complicated password, this sometimes helps to protect your DEBIX.

The sshd configuration file is /etc/ssh/sshd_config.

• To allow or deny specific users: Add, edit, or append to the end of the file /etc/ssh/sshd_config the following content AllowUsers alice bob, which contains the usernames you wish to allow to log in(substitute alice bob to your corresponding names).
• To stop some usernames from logging in, you can add, edit, or append to the end of the file /etc/ssh/sshd_config the following content DenyUsers jane john, which contains the usernames you wish to deny them from logging in(substitute jane john with your corresponding names).
• Once the modification of /etc/ssh/sshd_config is finished, run command sudo systemctl restart ssh or reboot so the changes take effect.

3.7.2.2 Using key-based authentication

Key pairs are two cryptographically secure keys. One is private, and one is public. They can be used to authenticate a client to an SSH server (for the current situation, the SSH server is DEBIX). As shown in the following image, there are two files in the directory .ssh, these two files are the key pairs. The file id_rsa.pub is the public key, the file id_rsa is the private key.

The client generates two keys, which are cryptographically linked to each other. The private key(id_rsa) should not be revealed, but the public key(id_rsa.pub) can be freely shared.

The SSH server maintains a copy of the public key, and, when a link is requested, uses this key to send the client a challenge message, which the client will encrypt using the private key. If the server can use the public key to decrypt this message back to the original challenge message, then the identity of the client can be confirmed.

On the client, run command ssh-keygen to generate a key pair. The keys are stored by default in the .ssh folder in the user’s home directory. The key will be 2048 bits long: it’s relatively difficult to break the encryption on a key of that length, so it is secure.

Note that you should only execute the command ssh-keygen once, if repeated, it will overwrite any previous generated keys. The things relying on those old keys will need to be updated to the new keys.

When executing ssh-keygen, you will be prompted to input a passphrase during key generation: this is for extra security. Currently, just leave it blank and press Enter key.

The public key now needs to be moved on to the server, you can use command scp to do it, e.g. run command scp id_rsa.pub debix@192.168.31.21:/home/debix/.ssh/id_rsa.pub1 (Remember to substitute the file path and IP address with your own), on the server, run command cd /home/debix/.ssh, then run command cat id_rsa.pub1 >> authorized_keys to add the public key to the tail of file authorized_keys.

Finally, we need to disable password logins, so that all authentication is done by the key pairs. Run command sudo vim /etc/ssh/sshd_config to edit the configure file, the following three items are needed to be set to no, if they have not been set that way:

ChallengeResponseAuthentication no 
PasswordAuthentication no 
UsePAM no 

Save the file and either restart the ssh system with sudo systemctl restart sshd or reboot to make the modifications take effect, then, only the clients which has put their public_key to the file authorized_keys of DEBIX Sever can access DEBIX server and users can no longer log in DEBIX server through username and password.

3.7.3.Installing Firewall ufw

As for Firewalls, iptables is widely used. iptables is installed by default on DEBIX OS, but is not set up. Setting iptables up can be a complicated task, whereas ufw provides a simpler interface than iptables, ufw(Uncomplicated Fire Wall) can be easily installed on DEBIX.

• Run command sudo apt install ufw to install ufw.

There are some GUIs available for ufw, we only introduce some basic command line options in this document. It’s needed to use sudo with ufw command.

• Run command sudo ufw enable to enable the firewall, it will also ensure ufw starts up on boot
• Run command sudo ufw disable to disable the firewall, and disable start up on boot
• Run command sudo ufw allow 22 to allow a particular port to have access(we used port 22 here)
• Run command sudo ufw deny 22 to deny access on a port(again, we have used port 22 as an example):
• Run command sudo ufw deny 22/tcp to deny tcp service on port 22. You can specify other services on a port.
• Run command sudo ufw allow ssh to allow ssh service. You can specify the service even if you do not know which port it uses.
• Run command sudo ufw status to list all current settings for the firewall

The rules can be quite complicated. For more information, please refer to the man page of ufw. The following are two relatively sophisticated examples.

• Run command sudo ufw limit ssh/tcp to limit login attempts on ssh port using tcp: this denies connection if an IP address has attempted to connect six or more times in the last 30 seconds.
• Run command sudo ufw deny from 192.168.31.21 port 30 to deny access to port 30 from IP address 192.168.31.21

3.7.4.Installing fail2ban

Fail2ban is written in Python, it is a scanner that examines the log files produced by DEBIX, and checks them for suspicious activity. It catches things like multiple brute-force attempts to log in, and can inform the installed firewall to stop further login attempts from suspicious IP addresses.

If you are using your DEBIX as some sort of server, for example an ssh or a webserver, your firewall will have deliberate 'holes' in it to let the server traffic through. In these cases, Fail2ban can be useful.

• Run command sudo apt install fail2ban to install fail2ban

On installation, Fail2ban creates a folder /etc/fail2ban in which there is a configuration file called jail.conf.

• Run command sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local, the file /etc/fail2ban/jail.conf needs to be copied to /etc/fail2ban/jail.local to enable fail2ban. Inside this configuration file are a set of default options, there are also some options for checking the abnormalities of specific services.
• Add the following section to the /etc/fail2ban/jail.local file. If this part is already there, update this pre-existing section.

[sshd]
# To use more aggressive sshd modes set filter parameter "mode" in jail.local:
# normal (default), ddos, extra or aggressive (combines all).
# See "tests/files/logs/sshd" or "filter.d/sshd.conf" for usage example and details.
#mode   = normal
enabled = true
port    = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
maxretry = 6

• Run command sudo apt install rsyslog, because the logpath is defined in /etc/fail2ban/paths-common.conf, it’s /var/log/auth.log, to achieve this file by default on DEBIX, we need to run sudo apt install rsyslog beforehand.

If you want to permanently ban an IP address after six failed attempts, you can change the maxretry value in the [ssh] section, and set the bantime to a negative number:

[sshd] 
# To use more aggressive sshd modes set filter parameter "mode" in jail.local: 
# normal (default), ddos, extra or aggressive (combines all). 
# See "tests/files/logs/sshd" or "filter.d/sshd.conf" for usage example and details. 
#mode = normal 
enabled = true 
port = ssh 
logpath = %(sshd_log)s 
backend = %(sshd_backend)s 
maxretry = 6 
bantime=-1 

Once we have modified the fail2ban configuration, it’s needed to run command sudo systemctl restart fail2ban to make the change take effect. For more information, you can refer to https://www.fail2ban.org/wiki/index.php/Main_Page.

3.8.1 Configuring Screen Blanking On Console

When running without a graphical desktop, DEBIX OS will blank the screen after 5 minutes without user input, e.g. mouse movement or key presses.

Run command gsettings set org.gnome.desktop.session idle-delay 60 to set the blank screen time to 1 minute, you can change the time as you want.

You can also use dconf-editor, to use dconf-editor, you need to install it by running sudo apt install dconf-editor, and then run command dconf-editor to launch the GUI, search idle-delay in the launched GUI, and set the time in custom value.

3.8.2. Configuring Screen Blanking On the Desktop

DEBIX OS will blank the graphical desktop after 5 minutes without user input. You can change the blank screen time in power which is a submenu of Settings.

There is also a graphical screensaver available, which is called xscreensaver.

• Run command sudo apt install xscreensaver to install xscreensaver. For there are many packages needed to be installed, this command may take a few minutes.

Once the installation finished, you can find the Screensaver application in Show Applications part on the desktop: it provides many options for setting up the screensaver, including disabling it completely.

DEBIX Kernel codes are hosted on GitHub：https://github.com/debix-tech/linux, We will update the kernel codes when needed.

The compilers and linkers that come with the operating system can generate executable code on this platform. Whereas when one platform generates executable code of another platform, it is defined as cross-compilation.

Cross-compilation of DEBIX kernel is useful for two reasons:

• it allows a 64-bit kernel to be built using a 32-bit OS, and vice versa, and
• A powerful enough laptop can cross-compile a DEBIX kernel faster than the DEBIX itself.

The instructions below are divided into native builds and cross-compilation. Choose the right tool for your situation, although there are many identical steps between the two, it is important to do nonetheless.

5.2.1.Building the Kernel Locally

On a DEBIX, first install the latest version of DEBIX OS. Then boot your DEBIX, plug in Ethernet to give you access to the sources, and log in.

Caution

sudo apt install git bc bison flex libssl-dev make

Next get the sources, which will take some time,depending on your ethernet bandwidth:

git clone --depth=1 https://github.com/debix-tech/linux

5.2.1.1. Choosing Sources

The git clone command above will download the current active branch (the one we are building DEBIX OS images from) without any history. Omitting the --depth=1 will download the entire repository, including the full history of all branches, but this takes much longer and occupies much more storage.

To download a different branch (again with no history), use the --branch option：

git clone --depth=1 --branch <branch> https://github.com/debix-tech/linux

In the above command, <branch> is the name of the branch that you wish to download.

5.2.1.2. Kernel Configuration

Configure the kernel; as well as the default configuration, you may wish to configure your kernel in more detail or apply patches from another source, to add or remove required functionality.

5.2.1.3. Apply the Default Configuration

First, prepare the default configuration by running the following commands (The default configuration of DEBIX is imx_v8_defconfig):

cd debix-kernel 
make imx_v8_defconfig

5.2.1.4 Building the Kernel

make -j4 
sudo make INSTALL_MOD_STRIP=1 modules_install 
sudo cp arch/arm64/boot/dts/freescale/*.dtb /boot/ 
sudo cp arch/arm64/boot/Image /boot/

Await completion and then restart the system.

5.2.2.Cross-Compiling the Kernel

First, you will need a suitable Linux cross-compilation host. We tend to use Ubuntu, since DEBIX OS is also a Debian distribution, it means many aspects are similar, such as the command lines. You can also use a virtual machine to install the Linux operating system on Windows to do this.

5.2.2.1. Install Required Dependencies and Toolchain

To build the sources for cross-compilation, make sure you have the dependencies needed on your machine by executing:

sudo apt install git bc bison flex libssl-dev make libc6-dev libncurses5-dev

If you find you need other things, please contact us to change the documentation.

Get cross compilation tool

sudo mkdir /opt/toolchain 
cd /opt/toolchain 
sudo wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz 
tar xpf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz 
export PATH=$PATH:/opt/toolchain/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin

Caution

You need to execute the following command before doing compilation.

5.2.2.2. Get the Kernel Sources

To download the minimal source tree for the current branch, run:

git clone --depth=1 https://github.com/debix-tech/linux

5.2.2.3. Build sources

Enter the following commands to build the sources and Device Tree files

export PATH=$PATH:/opt/toolchain/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin 
cd debix-kernel 
make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- imx_v8_defconfig 

5.2.2.4. Build with Configs
Caution

5.2.2.5. Compile kernel dts modules
Caution

export PATH=$PATH:/opt/toolchain/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin 
make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu-

5.2.2.6. Install Directly onto the SD Card

Having built the kernel, you need to copy it onto your DEBIX and install the modules; this is best done directly using an SD card reader. Prepare an SD card with DEBIX OS installed beforehand.

First, use lsblk before and after plugging in your SD card to identify it. You should end up with something a lot like this:

sdb 
  sdb1 
  sdb2

with sdb1 being the FAT (boot) partition, and sdb2 being the ext4 filesystem (root) partition.

Mount these first, adjusting the partition number as necessary:

mkdir mnt 
mkdir mnt/fat32 
mkdir mnt/ext4 
sudo mount /dev/sdb1 mnt/fat32 
sudo mount /dev/sdb2 mnt/ext4

Next, install the kernel modules onto the SD card:

export PATH=$PATH:/opt/toolchain/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin 
sudo env PATH=$PATH make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- INSTALL_MOD_PATH=mnt/ext4 INSTALL_MOD_STRIP=1 modules_install 
sudo umount /mnt/ext4

Finally, copy the kernel and Device Tree blobs onto the SD card, making sure to back up your old kernel:

sudo cp mnt/fat32/Image mnt/fat32/Image-backup.img 
sudo cp arch/arm64/boot/Image mnt/fat32/Image 
sudo cp arch/arm64/boot/dts/freescale/imx8mp-evk.dtb mnt/fat32/imx8mp-evk.dtb 
sudo umount /mnt/fa

Finally, plug the card into DEBIX and boot it

5.2.2.7. Install to eMMC

This method is only advisable for DEBIX Model A with eMMC storage

First install the produced kernel into the Micro SD card

If not sure how to operate, please refer to 5.2.2.6

Insert the Micro SD Card into DEBIX, switch the DIP switch to 10, and start DEBIX through eMMC:

Use the following commands to copy the kernel and device tree files in the Micro SD card to the boot partition of eMMC

mkdir mnt 
mkdir mnt/fat32 
mkdir mnt/ext4 
sudo mount /dev/sda1 mnt/fat32 
sudo mount /dev/mmcblk2p1 /boot 
cp mnt/fat32/* /boot/ 
sudo umount /dev/sda1

Take the .ko driver file in the Micro SD card to replace into the eMMC

mkdir mnt 
mkdir mnt/fat32 
mkdir mnt/ext4 
sudo mount /dev/sda1 mnt/fat32 
sudo mount /dev/mmcblk2p1 /boot 
cp mnt/fat32/* /boot/ 
sudo umount /dev/sda1

The Linux kernel is highly configurable, you may want to modify the default configuration to customize it to your needs, such as enabling a new or experimental network protocol, or enabling support for new hardware. Configuration is most commonly done through the make menuconfig interface. Alternatively, you can modify your .config file manually, but this can be more difficult for new users.

5.3.1.Preparing to Configure

The menuconfig tool requires the ncurses development headers to compile properly. These can be installed with the following command:

sudo apt install libncurses5-dev

You’ll also need to download and prepare your kernel sources, as described in the build guide. In particular, ensure you have installed the default configuration.

5.3.2.Using menuconfig

Once you’ve got everything set up and ready to go, you can compile and run the menuconfig utility as follows:

make menuconfig

Or, if you are cross-compiling a 64-bit kernel:

export PATH=$PATH:/opt/toolchain/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin 
make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- menuconfig

The menuconfig utility has simple keyboard navigation. After a brief compilation, you’ll be presented with a list of submenus containing all the options you can configure, there’s a lot, so take your time to read through them and get acquainted.

Use the arrow keys to navigate, the Enter key to enter a submenu ( ---> instruction). Escape twice to go up a level or exit, and the space bar to cycle the state of an option. Some options have multiple choices, in which case they’ll appear as a submenu and the Enter key will select an option. You can press h on most entries to get help about that particular option or menu.

Resist the temptation to enable or disable a lot of things on your first attempt; it’s relatively easy to break your configuration, so start small and get comfortable with the configuration and build process.

5.3.3.Saving your Changes

6.1.1. Terminal Window

In DEBIX, the default terminal application is called gnome-terminal. You can open a terminal through the application on the DEBIX desktop or the shortcut Ctrl+Alt+T, and when started will look something like this:

In the terminal window you will be able to see the following prompt ,it contains some system information.

debix@imx8mpevk~ $

In the above image, you can find the username and the hostname of the DEBIX. Here debix is your username and imx8mpevk is your hostname.

6.1.2. Start Enjoying Your DEBIX

Type in your first command ls -la, enter Enter to execute the command, and you can view all files / folders and properties in the current directory. The details are shown in the following figure:

The ls command lists the contents of the directory that you are currently in (your present working directory). If you want to know more about ls command, you can refer to section 6.3.1. The total block size of the file in the current directory, file permissions, modification time and other information are given.

You can use the cd command to change the working directory, you can choose to give a relative path or an absolute path. The detailed usage is described in section 6.3.1. You can use cd or cd ~ when you want to switch to the default working directory.

6.1.3. About sudo

6.1.4. Auto-complete and history

Terminal supports viewing historical commands through the up or down keys of the keyboard. When you enter some commands, files or file paths, you can enter a part, and then use the tab key to complete it automatically. For example, when you want to type in command mkdir, you only need to type in mk and then enter tab key, you can choose mkdir from the listed items.

6.1.5. Using apt to manage packages

• Run command sudo apt update to update the list of packages available on DEBIX.
• Run command sudo apt full-upgrade to update the old packages to the available new version.
• Run command sudo apt install <package name> to install a package.
• Run command sudo apt remove <package name>  to uninstall or remove a package.

6.1.6. Command manual

To learn more about a specific command, you can prefix your command with man (e.g. man cd). The man-page of the command will be displayed, including information about the program flag and its impact. Some man pages will give examples of usage. (For ubuntu20.04 used by DEBIX, we need to run sudo unnimize to get the man page).

6.1.7. Other Commonly-used Commands

Here are some commonly-used commands:

• cat lists the contents of files, e.g. cat test.py will display the contents of test.py.

debix@imx8mpevk:~$ cat test.py
#!/usr/bin/python
print("Hello world")

debix@imx8mpevk:~/tmp-lihong$ mkdir temp_dir
debix@imx8mpevk:~/tmp-lihong$ ls
temp_dir

debix@imx8mpevk:~/tmp-lihong$ cp test.txt /tmp/nancy/
debix@imx8mpevk:~/tmp-lihong$ ls /tmp/nancy/
test.txt

debix@imx8mpevk:~/tmp-lihong$ ls
test.txt  test1.txt
debix@imx8mpevk:~/tmp-lihong$ ls /tmp/nancy/
debix@imx8mpevk:~/tmp-lihong$ mv test.txt /tmp/nancy/
debix@imx8mpevk:~/tmp-lihong$ ls /tmp/nancy/
test.txt
debix@imx8mpevk:~/tmp-lihong$ ls
test1.txt
debix@imx8mpevk:~/tmp-lihong$ mv test1.txt test2.txt
debix@imx8mpevk:~/tmp-lihong$ ls
test2.txt
debix@imx8mpevk:~/tmp-lihong$

Warning

debix@imx8mpevk:~/tmp-lihong$ ls 
test.txt test_dir 
debix@imx8mpevk:~/tmp-lihong$ rm test.txt 
debix@imx8mpevk:~/tmp-lihong$ ls 
test_dir 
debix@imx8mpevk:~/tmp-lihong$ rm -r test_dir/ 
debix@imx8mpevk:~/tmp-lihong$ ls 
debix@imx8mpevk:~/tmp-lihong$

Other commonly-used commands can be found in the Section 6.3.

6.2.1. Home

If you are using user debix to login to DEBIX system, you will be located in the home folder of user debix(that is the directory /home/debix) when you open a terminal.

When you are not working in your home directory, you can navigate to your home folder on the command line, simply type cd and press Enter. This is the equivalent of typing cd /home/debix(assuming your current username is debix), where debix is your username. You can also use the tilde key (~), for example cd ~, which can be used to relatively link back to your home folder. For instance, cd ~/Pictures/ is the same as cd /home/debix/Pictures.

Run command cd /home to navigate to /home/ and run ls, and you’ll see the home folders of each of the users on the system(Note that if logged in as the root user, typing cd or cd ~ will take you to the root user’s home directory; unlike normal users, this is located at /root/ not /home/root/).

6.3.1 Filesystem

mkdir

The mkdir command can create a new folder, e.g. mkdir temp would create the directory temp in the present working directory.

Example command output as below:

debix@imx8mpevk:~$ mkdir temp 
debix@imx8mpevk:~$ ls 
Desktop Documents Linux Pictures Templates gstshark_2022-04-21_12:54:49 
Device Downloads Music Public Videos temp

cd

The cd command can change the current directory to the one specified. You can use relative (i.e. cd temp) or absolute (i.e. cd /home/debix/temp) paths.

Example command output is as below:

debix@imx8mpevk:~$ cd temp/ 
debix@imx8mpevk:~/temp$

ls

The ls command lists the content of the current directory (or one that is specified). It can be used with the -l flag to display additional information (permissions, owner, group, size, date and timestamp of last edit) about each file and directory in a list format. The -a flag allows you to view files beginning with . (i.e. dotfiles).

Example command output is as below:

debix@imx8mpevk:~$ ls 
Desktop Documents Linux Pictures Templates gstshark_2022-04-21_12:54:49 
Device Downloads Music Public Videos temp

rm

The rm command removes the specified file (or recursively from a directory when used with -r). Be careful with this command: files deleted in this way are mostly gone.

Example command output is as below:

debix@imx8mpevk:~/temp$ rm -f temp.txt debix@imx8mpevk:~/temp$ cd .. 
debix@imx8mpevk:~$ rm -rf temp 
debix@imx8mpevk:~$ ls 
Desktop Device Documents Downloads Linux Music Pictures Public Templates Videos gstshark_2022-04-21_12:54:49

pwd

The pwd command displays the name of the present working directory: on a DEBIX, entering pwd will output something like /home/debix.

Example command output is as below:

debix@imx8mpevk:~$ pwd 
/home/debix

rmdir

The rmdir command removes empty directories.

Example command output is as below, directory tmp_dir1 is empty, it can be removed by rmdir, directory tmp_dir2 is not empty, it cannot be removed by rmdir:

debix@imx8mpevk:~/mytemp$ ls 
debix.txt main.py tmp_dir1 tmp_dir2 
debix@imx8mpevk:~/mytemp$ ls tmp_dir1 
tmp_file1 
debix@imx8mpevk:~/mytemp$ ls tmp_dir2 
debix@imx8mpevk:~/mytemp$ rmdir tmp_dir1 
rmdir: failed to remove 'tmp_dir1': Directory not empty 
debix@imx8mpevk:~/mytemp$ rmdir tmp_dir2 
debix@imx8mpevk:~/mytemp$ ls 
debix.txt main.py tmp_dir1 
debix@imx8mpevk:~/mytemp$

cp

The cp command makes a copy of a file and places it at the specified location (this is similar to copying and pasting). For example, cp ~/file1 /home/otheruser/ would copy the file file1 from your home directory to that of the user otheruser (assuming you have permission to copy it there). This command can be used as below:

• cp FILE FILE (cp file1 file2), copy file1 to file2.
• cp FILE DIR (cp file1 /temp/) ,it copies file1 to the directory /temp/.
• cp -r DIR DIR (cp -r dir1 dir2), it recursively copies contents of dir1 to dir2.

Example command output as below:

debix@imx8mpevk:~$ ls 
Desktop Device Documents Downloads Linux Music Pictures Public Templates Videos file1 gstshark_2022-04-21_12:54:49 
debix@imx8mpevk:~$ sudo cp ~/file1 /home/otheruser/ 
debix@imx8mpevk:~$ cd /home/otheruser/ 
debix@imx8mpevk:/home/otheruser$ ls 
file1

mv

The mv command moves a file and places it at the specified location (so where cp performs a 'copy-paste', mv performs a 'cut-paste'). The usage is similar to cp. So mv ~/file1 /home/otheruser/ would move the file file1 from your home directory to that of the user otheruser(assuming you have the permission). This command can be used as below:

• mv FILE FILE (mv file1 file2), move file1 to file2.
• mv FILE DIR (mv file1 temp_dir1/), move file1 from the current location to directory temp_dir1/.
• mv DIR DIR (mv temp_dir1/  temp_dir2/)move directory temp_dir1 to directory temp_dir2.

Example command output is as below:

debix@imx8mpevk:~$ ls ~ 
Desktop Downloads Pictures Templates file1 
Documents Music Public Videos gstshark_2022-07-13_09:11:19 
debix@imx8mpevk:~$ sudo mv file1 /home/otheruser/ 
debix@imx8mpevk:~$ ls 
Desktop Downloads Pictures Templates gstshark_2022-07-13_09:11:19 
Documents Music Public Videos 
debix@imx8mpevk:~$ ls /home/otheruser 
file1 
debix@imx8mpevk:~$

cat

The cat command lists the contents of file(s), e.g. cat file1 will display the contents of file1. This command can also be used to list the contents of multiple files, i.e. cat *.txt will list the contents of all .txt files in the current directory.

Example command output is as below:

debix@imx8mpevk:~$ ls 
Desktop Device Documents Downloads Linux Music Pictures Public Templates Videos file1 gstshark_2022-04-21_12:54:49 
debix@imx8mpevk:~$ cat file1 
This is a test!

head

The head command displays the beginning of a file. Can be used with -n to specify the number of lines to show (by default ten), or with -c to specify the number of bytes.

Example command output is as below:

debix@imx8mpevk:~$ head -n 1 file1 
This is a test!

chmod

The chmod command can change the permissions for a file. The chmod command can use symbols u (user that owns the file), g (the files group), and o (other users) and the permissions r (read), w (write), and x (execute). Using chmod u+x filename will add execute permission for the owner of the file.

Example command output is as below:

debix@imx8mpevk:~$ ls -l test.sh 
-rw-rw-r-- 1 debix debix 32 Jul 22 02:35 test.sh 
debix@imx8mpevk:~$ chmod +x test.sh 
debix@imx8mpevk:~$ ls -l test.sh 
-rwxrwxr-x 1 debix debix 32 Jul 22 02:35 test.sh 
debix@imx8mpevk:~$

ssh

ssh connects to another computer using an encrypted network connection. For more information, you can check SSH (secure shell)

Example command output is as below:

debix@imx8mpevk:~$ sudo ssh debix@192.168.1.10 
ECDSA key fingerprint is SHA256:4wru1tGenheRduefLj00n6J+dqLJORbylnmWsAwxVmc. 
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes 
Warning: Permanently added '192.168.1.10' (ECDSA) to the list of known hosts. 
debix@192.168.1.10's password: 
Welcome to Ubuntu 20.04.4 LTS (GNU/Linux 5.10.72-lts-5.10.y+g3f536c684411 aarch64) 
* Documentation: https://help.ubuntu.com 
* Management: https://landscape.canonical.com 
* Support: https://ubuntu.com/advantage 
This system has been minimized by removing packages and content that are 
not required on a system that users do not log into. 
To restore this content, you can run the 'unminimize' command. 
Last login: Wed Jul 20 08:50:43 2022 from 192.168.1.8 
debix@imx8mpevk:~$

scp

The scp command copies a file from one computer to another using ssh. For more details see SCP (secure copy)

Example command output is as below:

debix@imx8mpevk:~/Documents$sudo scp debix@192.168.1.10: ~/file1 /home/debix/Documents/ 
[sudo] password for debix: 
debix@192.168.1.10's password:
file1                                           100%   16    33.1KB/s   00:00                                                                                                                                                                    
debix@imx8mpevk:~/Documents$ ls 
file1

dd

The dd command copies a file converting the file as specified. It is often used to copy an entire disk to a single file or back again. So, for example, dd if=/dev/sdd of=backup.img will create a backup image from an SD card or USB disk drive at /dev/sdd. Make sure to use the correct drive when copying an image to the SD card as it can overwrite the entire disk.

df

The df command can display the disk space available and used on the mounted filesystems. Use df -h to see the output in a human-readable format using M for MBs rather than showing number of bytes.

Example command output is as below:

debix@imx8mpevk:~$ df -h 
Filesystem Size Used Avail Use% Mounted on 
/dev/root 29G 5.6G 22G 21% / 
devtmpfs 494M 0 494M 0% /dev 
tmpfs 975M 0 975M 0% /dev/shm 
tmpfs 195M 3.4M 192M 2% /run 
tmpfs 5.0M 4.0K 5.0M 1% /run/lock 
tmpfs 975M 0 975M 0% /sys/fs/cgroup 
tmpfs 195M 1.3M 194M 1% /run/user/1000 
tmpfs 195M 36K 195M 1% /run/user/114

tar

The tar command stores or extracts files from a tape archive file. It can also reduce the space required by compressing the file similar to a zip file.

Example command output is as below:

debix@imx8mpevk:~$ tar -cvf test.tar test.sh 
test.sh 
debix@imx8mpevk:~$ ls 
Desktop Device Documents Downloads Linux Music Pictures Public Templates Videos backup.img file1 gstshark_2022-04-21_12:54:49 test.sh test.tar

When creating a compressed file, use command tar -cvzf filename.tar.gz directory/. To extract the contents of a file, use command tar -xvzf filename.tar.gz

unzip

The unzip command extracts the files from a compressed zip file.

pipes

The pipe symbol is a vertical line |. A pipe allows the output from one command to be used as the input for another command. For example, run command cat tmp.txt | grep "hello", the output of command cat tmp.txt will be provided as input for command grep -o "hello". Example command output is as below:

debix@imx8mpevk:~$ ls 
Desktop Downloads Pictures Templates gstshark_2022-07-13_09:11:19 
Documents Music Public Videos tmp.txt 
debix@imx8mpevk:~$ cat tmp.txt 
helloworld. 
debix@imx8mpevk:~$ cat tmp.txt | grep -o "hello" 
hello 
debix@imx8mpevk:~$

&

Run a command in the background with &, freeing up the shell for future commands.

tree

Use the tree command to show a directory and all subdirectories and files indented as a tree structure. You can install it with APT:

sudo apt install tree

curl

Use curl to download or upload a file to/from a server. By default, it will output the file contents of the file to the screen. You can install it with apt:

sudo apt install curl

wget

Download a file from the web directly to the computer with wget. So wget https://www.debix.io/public/uploads/files/20220127/68e3735204a9f7e09114e2ee677a7c9e.pdf will download the 68e3735204a9f7e09114e2ee677a7c9e.pdf datasheet and save it as 68e3735204a9f7e09114e2ee677a7c9e.pdf.

man

Show the manual page for a file with man. To find out more, run man man to view the manual page of the man command. Right now, on DEBIX, you need to run the following command to get manpages:

sudo unminimize

6.3.2. Search

find

The find command searches a directory and subdirectories for files matching certain patterns.

Example command output is as below:

debix@imx8mpevk:~$ ls 
Desktop Device Documents Downloads Linux Music Pictures Public Templates Videos backup.img file1 gstshark_2022-04-21_12:54:49 test.sh test.tar 
debix@imx8mpevk:~$ find . -name "test.sh" 
./test.sh

grep

Use grep to search inside files for certain search patterns. For example, grep "hello" file* will look in all the files in the current directory starting with file for the string hello. The grep command supports regular expressions which allows special letter combinations to be included in the search. There are various options can be used with command grep, you can refer to its man page.

Example command output is as below:

debix@imx8mpevk:~$ ls 
Desktop Downloads Pictures Templates gstshark_2022-07-13_09:11:19 
Documents Music Public Videos tmp.txt 
debix@imx8mpevk:~$ cat tmp.txt 
helloworld 
debix@imx8mpevk:~$ grep -o "h." tmp.txt 
he 
debix@imx8mpevk:~$

awk

awk is a programming language useful for searching and manipulating text files, it’s useful to get the content of a specific column in a file.

Example command output is as below:

debix@imx8mpevk:~$ cat tmp.txt 
color blue 
name nancy 
age 11 
debix@imx8mpevk:~$ awk '{print $1}' tmp.txt 
color 
name 
age 
debix@imx8mpevk:~$

whereis

Use whereis to find the location of a command. It looks through standard program locations until it finds the requested command.

The command output is as below:

debix@imx8mpevk:~$ whereis -b whereis 
whereis: /usr/bin/whereis

6.3.3. Networking

ping

The ping utility is usually used to check if communication can be made with another host. It can be used with default settings by just specifying a hostname (e.g. ping debix.io) or an IP address (e.g. ping 114.114.114.114). It can specify the number of packets to send with the -c flag.

Example command output is as below:

debix@imx8mpevk:~$ ping -c 5 debix.io 
PING debix.io (47.91.220.87) 56(84) bytes of data. 
64 bytes from 47.91.220.87 (47.91.220.87): icmp_seq=1 ttl=48 time=37.5 ms 
64 bytes from 47.91.220.87 (47.91.220.87): icmp_seq=2 ttl=48 time=37.6 ms 
64 bytes from 47.91.220.87 (47.91.220.87): icmp_seq=3 ttl=48 time=37.8 ms 
64 bytes from 47.91.220.87 (47.91.220.87): icmp_seq=4 ttl=48 time=37.6 ms 
64 bytes from 47.91.220.87 (47.91.220.87): icmp_seq=5 ttl=48 time=37.7 ms 
--- debix.io ping statistics --- 
5 packets transmitted, 5 received, 0% packet loss, time 4007ms 
rtt min/avg/max/mdev = 37.486/37.643/37.814/0.107 ms

nmap

nmap is a network exploration and scanning tool. It can return port and OS information about a host or a range of hosts. You can install it with apt:

sudo apt install nmap

ifconfig

Use ifconfig to display the network configuration details for the interfaces on the current system when run without any arguments (i.e. ifconfig). For more information, you can check the man page.

hostname

The hostname command displays the current hostname of the system. A privileged (super) user can set the hostname to a new one by supplying it as an argument (e.g. hostname new-host).

6.4.1. Text Editors in the Terminal

6.4.1.1 Vi

Vi command line editor, which is available on most UNIX systems and is installed by default on DEBIX OS. VIM (VI improvement) is inherited from vi, you need to run command sudo apt install vim to install vim.

Vi and Vim have various different modes, which other editors do not have.

• Run command vi file.txt, you start in command mode which doesn’t directly permit text entry.
• Edit the file :Type in i to switch to insert mode in order to edit the file, and edit away.
• Save the modification:to save the file you must return to command mode, so press the Escape key and enter :w (followed by Enter), which is the command to write the file to disk.
• To search for the word 'debix' in a file, make sure you’re in command mode (press Escape), then type /debix followed by n and N to flick forwards/backwards through the results.
• To save and exit, enter the command :wq. To exit without saving, enter the command :q!.

6.4.1.2 Vim

Vim is an extension of Vi and works in much the same way, with a number of improvements. If there isn’t a vim in your system, install it with apt:

sudo apt install vim

You can edit a file in Vim with vim file.txt.

6.4.1.3 Emacs

Emacs is a GNU command-line text editor; it’s powerful and extensible. You can install it with apt:

sudo apt install emacs

6.4.1.4 nano

GNU Nano is at the easy-to-use end of command-line editors, use nano file.txt to edit a file, and keyboard shortcuts like Ctrl + O to save and Ctrl + X to exit. You can install it with apt:

sudo apt install nano

6.5.1. Changing Password

After logging in as a DEBIX user, you can use the passwd command to change the default password to improve the security of DEBIX.

Enter passwd on the command line and press Enter. You’ll be prompted to enter your current password to authenticate, and then asked for a new password. Press Enter on completion and you’ll be asked to confirm it. Note that no characters will be displayed while entering your password. Once you’ve correctly confirmed your password, you’ll be shown a success message(passwd: password updated successfully), and the new password will apply immediately.

If your user has sudo permissions, you can change another user’s password with passwd followed by the user’s username. For example, sudo passwd otheruser will allow you to set the user otheruser's password, and then some additional optional values for the user such as their name. Just press Enter to skip each of these options.

6.5.1.1 Remove a User’s Password

You can remove the password for the user otheruser with sudo passwd otheruser -d. Without a password the user will not be able to login to a Terminal(This is useful for users that need to exist for system reasons, but you don’t want it to be possible to login to the account for security reasons).

6.5.2. Adding User

You can create additional users on your DEBIX OS installation with the adduser command. Enter sudo adduser otheruser and you’ll be prompted for a password for the new user otheruser. Leave this blank if you don’t want a password.

6.5.2.1 Home Folder

Once a new user is created, This new created user will have a home folder in /home/. The debix user’s home folder is at /home/debix/.

6.5.3. Deleting a User

The userdel command can delete users on the system, and -r can delete their home folders at the same time:

sudo userdel -r otheruser

Linux operating system allows multi-user login and operation to use it. In order to ensure computer security, the user's operation permission should be restricted.

Most users are allowed to run most programs, and to save and edit files stored in their own home folder. Normal users are not normally allowed to edit files in other users' folders or any of the system files. There’s a special user in Linux known as the superuser, which is usually given the username root. The superuser can operate and access computers without restrictions.

6.6.1. Sudo

When you are not logged in to the computer as root, you can use the sudo command to provide access as a superuser. For example, logging in as Debix is an ordinary user. You can use the sudo command to execute the command as root before the command you need to run.

For example, if you want to install additional software on DEBIX OS then you normally use the apt tool. To update the list of available software, you need to prefix the apt command with sudo:sudo apt update

You can also use sudo su to run the super user shell. When you run commands as a super user, your system will be very vulnerable to serious damage when you perform some improper operations. It is recommended that you only run commands as a superuser when needed and exit when the superuser shell is no longer needed.

6.6.2. The sudo’ers List

The default debix user on DEBIX Model A OS is a member of the sudo group. This gives the ability to run commands as root when preceded by sudo, and to switch to the root user with sudo su.

• To add a new user to the sudo group, use the adduser command:

sudo adduser otheruser sudo

Note that the user otheruser will be prompted to enter their password when they run sudo. If you wish to remove the password prompt from the new user, create a custom sudoers file and place it in the /etc/sudoers.d directory.

• Run command sudo visudo /etc/sudoers.d/010_otheruser-nopasswd.
• Insert the following contents on a single line: otheruser ALL=(ALL) NOPASSWD: ALL
• Save the file and exit.

After exiting the editor, if the file does not detect an error, the file is saved and the shell prompt is returned. If errors were detected, you will be asked 'what now?' Press the 'enter' key on your keyboard: this will bring up a list of options. You will probably want to use 'e' for '(e)dit sudoers file again', so you can edit the file and fix the problem(Note, Choosing option 'Q' will save the file with any syntax errors still in place, which makes it impossible for any user to use the sudo command.).

Note

There is a hidden file named .bashrc in your home folder, which contains some user configuration options. You can edit this file according to your needs. Changes made in this file will be actioned the next time a terminal is opened, since that is when the .bashrc file is read.

If you want your changes to take place in your current terminal, you can

• Run command source ~/.bashrc (it re-executes the .bashrc file, which may result in undesirable changes to things like the path)
• Run command exec bash.(it replaces the current shell with a new bash shell, which resets the shell back to the state at login, throwing away any shell variables you may have set)

For example, some ls aliases:

alias ls='ls --color=auto' 
alias grep='grep --color=auto'

Aliases like these are provided to help users of other systems like Microsoft Windows (dir is the ls of DOS/Windows). Others are to add colour to the output of commands like ls and grep by default.

6.7.1. The .bash_aliases File

.bashrc also contains a reference to a .bash_aliases file, which does not exist by default. You can add it to provide a handy way of keeping all your aliases in a separate file.

if [ -f ~/.bash_aliases ]; then 
    . ~/.bash_aliases 
fi

Then you just create the file .bash_aliases and add more aliases like so:

alias gs='git status'

You can add other things directly to this file, or to another and include that file like the .bash_aliases example above.

You can combine commands into one file and then grant executable permission to the file. For example, copy the following into a text editor:

• Run command touch script-temp to create a script file.
• Add the following content to this script-temp file.

#!/bin/bash
echo "Debix Model A!"

• Run command chmod +x script-temp to give it executable permission, the file script-temp will now be executable.
• Run command ./script-temp or command /bin/bash script-temp (assuming it’s in your current directory)

This script will print Debix Model A!

On UNIX systems, you can use the cron tool to configure scheduled tasks. It is used to schedule commands or scripts to run at the intervals you configured. Using cron, you can back up your files at midnight every day, you can also record specific program information every hour.

The command crontab (cron table) is used to edit the list of scheduled tasks in operation, and is done on a per-user basis; each user (including root) has their own crontab.

6.9.1. Editing the crontab File

• Run command sudo apt install cron to install cron package.
• Run command crontab -e to edit the cron table.

Note

6.9.2. Viewing Scheduled Tasks

• Run command crontab -l to view your currently saved scheduled tasks.

6.9.3. Adding Scheduled Task

The layout for a cron entry is made up of six components: minute, hour, day of month, month of year, day of week, and the command to be executed.

• m: min(0-59)
• h: hour(0-23)
• dom: day of month(1-31)
• mon: month(1-12)
• dow: day of week(0-7)(0 to 6 are Sunday to Saturday, or use names;7 is Sunday, the same as 0)
• command: command to execute

For example:

0 0 * * * /home/debix/backup.sh

This cron entry would run the backup.sh script every day at midnight.

6.9.4. Erase Scheduled Tasks

• Run command crontab -r to delete all currently scheduled tasks:

6.9.5. Running a Task on Reboot

You can substitute @reboot with the time and date to run the command every time the machine starts up. For example:

@reboot python /home/debix/myscript.py

@reboot python /home/debix/myscript.py &

6.10.1. Creating a Service

On your DEBIX, create a .service file for your service, for example: myscript.service

• Run command touch mytemp.service to create a service file, add the following content to it

[Unit]
Description=My service
After=network.target
[Service]
ExecStart=/usr/bin/python3 -u main.py
WorkingDirectory=/home/debix/myscript
StandardOutput=inherit
StandardError=inherit
Restart=always
User=debix
[Install]
WantedBy=multi-user.target

So in this instance, the service would run Python 3 from our working directory /home/debix/myscript which contains our python program to run main.py. But you are not limited to Python programs: simply change the ExecStart line to be the command to start any program or script that you want running from booting.

• Run command touch /home/debix/mytemp/main.py to create file main.py in directory /home/debix/mytemp, add the following content to it.

#!/usr/bin/python3
import os
os.system("touch %s" % "debix.txt")

• Run chmod +x /home/debix/mytemp/main.py to make file main.py executable.
• Run command sudo cp mytemp.service /etc/systemd/system/mytemp.service to copy this service file into /etc/systemd/system as root.
• Run command sudo systemctl daemon-reload to inform systemd that a new service has been added.
• Run command sudo systemctl start mytemp.service to start the service, in this example, after starting the service, you will find a new file debix.txt is created under the working directory /home/debix/mytemp.
• Run command sudo systemctl stop mytemp.service to stop the service.
• Run command sudo systemctl enable mytemp.service to start it automatically on reboot.

When using DEBIX, if you do not have a monitor or you want to access it from somewhere else, then you need to know remote access. You can connect to your DEBIX from another machine. But you need to know its IP Address beforehand.

Once a device is connected to a Local Area Network, the device will be assigned an IP address. It’s easy to know your DEBIX’s IP address if your DEBIX has a display, and there are also various other methods of finding DEBIX’s IP address remotely from another machine on the network. If you have gotten DEBIX’s IP address, you can connect to your DEBIX from another machine using tools such as SSH and VNC.

7.1.1.Finding DEBIX's IP address

• If your DEBIX have a display, run command hostname -I to find the IP address.

hostname -I

• If your DEBIX do not have a display, you can try following methods:
• Using router devices list, navigate to your router’s IP address e.g. http://192.168.31.1 in a web browser, which is usually printed on a label on your router; this will take you to a control panel. Then log in using your credentials, you will find your DEBIX’s IP address.
• Resolving imx8mpevk.local with mDNS. On DEBIX, multicast DNS is supported out-of-the-box by the Avahi service. If your device supports mDNS, you can reach your DEBIX by using its hostname with the .local suffix. The default hostname on a fresh Ubuntu20.04 OS install is imx8mpevk, so by default any DEBIX running Ubuntu20.04 responds to the following command:

ping imx8mpevk.local

If DEBIX is reachable, this will show DEBIX’s IP address like this:

If you change the system hostname of the DEBIX(e.g., by editing /etc/hostname), Avahi will also change the .local mDNS address.

• Use nmap command. The nmap command (Network Mapper) is a free and open-source tool for network discovery, available for Linux, macOS, and Windows. To install it on Linux, install the nmap package e.g. apt install nmap. To install nmap on macOS or Windows, see the nmap.org download page.

To use nmap to scan the devices on your network, you need to know the subnet you are connected to. First find your own IP address, in other words the one of the computer you’re using to find your DEBIX’s IP address(On Linux, type hostname -I into a terminal window; On macOS, go to System Preferences then Network and select your active network connection to view the IP address; On Windows, go to the Control Panel, then under Network and Sharing Center, click View network connections, select your active network connection and click View status of this connection to view the IP address).

After you have had the IP address of your computer, you will scan the whole subnet for other devices. For example, if your IP address is 192.168.31.97, other devices will be at addresses like 192.168.31.27, 192.168.31.37, 192.168.31.47, etc. The notation of this subnet range is 192.168.31.0/24 (it covers 192.168.31.0 to 192.168.31.255).

Now use the nmap command with the -sn flag on the whole subnet range. This may take a few seconds:

nmap -sn 192.168.31.0/24

The Secure Shell(SSH) protocol can be used to access the command line of DEBIX remotely from another computer. However, only the command line can be accessed, you can not access the full desktop environment, to access the full remote desktop, try VNC.

7.2.1.Set up your Local Network

7.2.2.Enabling the Server

On one DEBIX, one Mac book or a linux computer, run the following command to log in to the DEBIX you want to connect to. Here, you need to give the IP address of the DEBIX you want to connect to. As for how to get the IP address, you can refer to “Finding DEBIX’s IP address” part of this document(run command ifconfig or command hostname -I).

ssh debix@<IP>

During the connection, it will prompt you a security/authenticity warning. Type yes to continue. You will only see this warning the first time you connect. If you receive a connection time out error, you need to check the given IP address.

If no other errors occur, you will be prompted for the password for the debix login: the default password for DEBIX is debix, update it if you have changed it to another password(For security reasons, it is recommended to change the default password on DEBIX).

Once the correct password is provided, you should now be able to see the DEBIX prompt, which will be the same with the one found on the DEBIX itself, you should see something like this:

debix@imx8mpevk ~ $

If you have set up another user on the DEBIX, you can connect to it in the same way, replacing the username and IP address with your corresponding one, e.g. nancy@192.168.31.23

You are now connected to the DEBIX remotely, and can execute commands.

On Windows10, if you want to connect to your DEBIX, open the command window and input the following command, replace <IP> with the IP address of the DEBIX you’re trying to connect to.

ssh debix@<IP> 

When the connection works you will see a security/authenticity warning. Type yes to continue. You will only see this warning the first time you connect.

If the error connection timed out error occurs, you need to check the given IP address.

If no error occurs, you will be prompted for the password for the debix login: the default password for DEBIX is debix(for security reasons, it’s recommended to change the default password on DEBIX).

Once the password is provided, you should now be able to see the DEBIX prompt, which will be the same with the one found on the DEBIX itself.

debix@imx8mpevk:~ $ 

If you have set up another user on the DEBIX, you can connect to it in the same way, replacing the username and IP address with your corresponding ones, e.g. nancy@192.168.31.23

7.5.1.Checking for Existing SSH Keys

First, check whether there are already keys on the computer you are using to connect to the DEBIX:

ls ~/.ssh

If you see files named id_rsa.pub or id_dsa.pub then you have keys set up already, so you can skip the 'Generate new SSH keys' step below.

7.5.2.Generate new SSH Keys

Run the following command to generate SSH keys:

ssh-keygen

After executing this command, you will be asked where to save the key. It’s recommended to save it in the default location (~/.ssh/id_rsa) by pressing Enter. You will then be asked to enter a passphrase(The passphrase is used to encrypt the private SSH key, so that if someone else copied the key, they could not impersonate you to gain access). If you want to use a passphrase, type it here and press Enter, then type it again when prompted. Leave the field empty for no passphrase.

Then, your .ssh directory should look like this:

debix@imx8mpevk:~$ ls .ssh id_rsa id_rsa.pub

7.5.3.Copy your Key to your DEBIX

On the computer you are using to connect to the remote DEBIX, run the following command to append the public key to your authorized_keys file on the DEBIX by sending it over SSH, substitute the <USERNAME> with the username you used to log in to remote DEBIX, substitute the <IP-ADDRESS> with the IP address of the remote DEBIX.

ssh-copy-id <USERNAME>@<IP-ADDRESS>

If command ssh-copy-id is not available on your system, you can copy the file id_rsa.pub manually and then put its content to the corresponding authorized_keys file or you can run the following command:

cat ~/.ssh/id_rsa.pub | ssh <USERNAME>@<IP-ADDRESS> 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'

If you are using windows, download WinSCP to transfer the file ‘id_rsa.pub’ to DEBIX and add the context of file ‘id_rsa.pub’ to file ‘~/.ssh/authorized_keys’. If file ‘~/.ssh/authorized_keys’ does not exist, create directory ~/.ssh and file ~/.ssh/authorized_keys manually, then add the content of file ‘id_rsa.pub’ to ~/.ssh/authorized_keys.

Then, you can try ssh <USER>@<IP-ADDRESS> and you should connect without a password prompt.

The command Secure Copy (scp) send files over SSH. This means you can copy files between computers, say from your DEBIX to your desktop or laptop, or vice-versa. You’ll need to know your DEBIX’s IP address beforehand.

7.6.1.Copying Files to your DEBIX

Run the following command to copy the file myfile.txt from your computer to the debix user’s home folder of your DEBIX at the IP address 192.168.31.23:

scp myfile.txt debix@192.168.31.23:

Run the following command to copy the file myfile.txt to the /home/debix/project/ directory on your DEBIX (the project folder must already exist):

scp myfile.txt debix@192.168.31.23:project/

7.6.2.Copying Files from your DEBIX

Run the following command to copy the file myfile.txt from your DEBIX to the current directory on your other computer:

scp debix@192.168.31.23:myfile.txt .

7.6.3.Copying Multiple Files

Run the following command to copy multiple files by separating them with spaces:

scp myfile.txt myfile2.txt debix@192.168.31.23:

Run the following command to copy all the files that has a suffix “.txt” to the remote DEBIX:

scp *.txt debix@192.168.31.23:

7.6.4.Copying a Whole Directory

Run the following command to copy the directory project/ from your computer to the debix user’s home folder of your DEBIX at the IP address 192.168.31.23:

scp -r project/ debix@192.168.31.23:

The tool rsync can be used to synchronize folders between computers. You can use it to transfer some files from your desktop computer or laptop to your DEBIX. Using rsync over SSH allows you to transfer files to your computer automatically.

The following is an example of how to set up the sync of a folder named my_files on your DEBIX to your computer:

On your computer, run the following command to create a folder called my_files:

mkdir my_files

Look up the DEBIX’s IP address by logging in to it and running hostname -I. In this example, there are several file in the folder /home/debix/my_files, and there will be some new files added to this folder continuously.

Maybe you will need to install rsync, for example, if you are using Debian, run the following command to install it:

sudo apt install rsync

rsync -avz -e ssh debix@192.168.31.23:my_files/ my_files/

You can use Network File System(NFS) to share a directory located on one networked computer with other computers or devices on the same network. The computer maintains the directory to share is called the server, and computers connecting to that server are called clients.

Clients usually mount the shared directory to make it a part of their own directory structure. The shared directory is an example of a shared resource or network share.

To deploy an NFS, you should be familiar with linux file and directory permissions, and you should also be familiar with mounting and unmounting filesystems.

7.8.1.Setting up a Basic NFS Server

Run the following command to install the required packages:

sudo apt install nfs-kernel-server

In order to configure easily, we will isolate all NFS exports in single directory, and mount the real directories into this single directory with the --bind option.

The following is an example of exporting our users' home directories, which are in /home/users First we create the export file system:

sudo mkdir -p /export/users

Note that /export and /export/users will need 777 permissions, as we will be accessing the NFS share from the client without LDAP/NIS authentication. This will not apply if using authentication (see below). Now mount the real users directory with command:

sudo mount --bind /home/users /export/users

/home/users /export/users none bind 0 0

There are three configuration files that relate to an NFS server:

• /etc/default/nfs-kernel-server (The only important option in /etc/default/nfs-kernel-server for now is NEED_SVCGSSD. It is set to "no" by default, which is fine, because we are not activating NFSv4 security this time.)
• /etc/default/nfs-common
• /etc/exports

In order for the ID names to be automatically mapped, the file /etc/idmapd.conf must exist on both the client and the server with the same contents and with the correct domain names. Furthermore, this file should have the following lines in the Mapping section:

[Mapping] 
Nobody-User = nobody 
Nobody-Group = nogroup

cat /etc/passwd 
cat /etc/group

[Translation] 
Method = nsswitch

This will cause idmapd to know to look at nsswitch.conf to determine where it should look for credential information. 

To export our directories to a local network 192.168.31.0/24, we add the following two lines to /etc/exports:

/export 192.168.31.0/24(rw,fsid=0,insecure,no_subtree_check,async) 
/export/users 192.168.31.0/24(rw,nohide,insecure,no_subtree_check,async)

Finally, to make your changes take effect, restart the service:

sudo systemctl restart nfs-kernel-server

7.8.2.Configuring an NFS Client

After the nfs server is running, you need to set up the NFS client to be able to access the server. To start, install the required packages:

sudo apt install nfs-common

On the client, we can mount the complete export tree with one command:

sudo mount -t nfs -o proto=tcp,port=2049 :/ /mnt

:/ /mnt nfs auto 0 0

Samba is a free software, and is comprised of server and client. It is an implementation of the SMB/CIFS networking protocol that is used by Microsoft Windows devices to provide shared access to files, printers, and serial ports. On your DEBIX, you can use Samba to mount a folder shared from a Windows machine, and you can also share a folder from your DEBIX to your Windows machine.

7.9.1.Installing Samba related packages

By default, DEBIX OS does not include CIFS/Samba support, but this can be added. The following commands will install all the required components for using Samba as a server or a client.

sudo apt update 
sudo apt install samba samba-common-bin smbclient cifs-utils

7.9.2.Mount a Folder Shared from Windows

It is obvious that you need to share a folder on your Windows device.

7.9.2.1. Turn on sharing on Windows

• Right-click the system tray and select network connection
• Click network and sharing center, then enter it
• Click Change advanced sharing settings
• Select Turn on network discovery
• Select Turn on file and printer sharing
• Save changes

7.9.2.2. Share the folder

You can share any folder you want, but for this example, simply create a folder called share.

• On your desktop, create a folder share.
• Right-click the new folder, and select Properties.
• Click the Sharing tab -> Advanced Sharing button
• Select Share this folder; by default, the share name is the name of the folder
• Click the Permissions button
• For this example, select Everyone and Full Control (you can limit access to specific users if required); click OK when done, then OK again to leave the Advanced Sharing page
• Click the Security tab, as we now need to configure the same permissions
• Select the same settings as the Permissions tab, adding the chosen user if necessary
• Click OK

Once the above steps are finished, the folder should now be shared.

7.9.2.3. Windows 10 Sharing Wizard

On Windows 10 there is a Sharing Wizard that helps with some of these steps.

• Open the Computer Management application from the Start Bar
• Select Shared Folders, then Shares
• Right-click and select New Share, which will start up the Sharing Wizard; click Next
• Select the folder you wish to share, and click Next
• Type in share name and click Next to use all the sharing defaults
• Set the required permissions, and click Finish

7.9.2.4. Mount the folder on DEBIX

• Run the following command to create a directory to be mounted into
  

mkdir windowshare

• Run the following command to mount the remote folder to the created folder. The remote folder is the host name or IP address of the Windows PC, and the share name used when sharing it. The Windows username is also needed to be provided.

sudo mount.cifs ///share /home/debix/windowshare -o user=

cd windowshare 
ls

7.9.3.Sharing a Folder from your DEBIX to Windows10

7.9.3.1. DEBIX configurations

Firstly, create a folder to share. This example creates a folder called shared in the home folder of the current user, and assumes the current user is debix.

cd ~ 
mkdir shared 
chmod 0740 shared

Note, sometimes after sharing using samba from debix, on windows10, we cannot operate on the shared directory( it notifies that we do not have permission), we need to run chmod 777 shared (substitute shared to the directory you create in your computer) to operate on it.

Now we need to tell Samba that there is a debix user when accessing that folder. When asked, enter the password of the debix user - this can be the default password, but that is well known and should be changed for better security.

sudo smbpasswd -a debix

sudo vim /etc/samba/smb.conf

[share] 
    path = /home/debix/shared 
    read only = no 
    public = yes 
    writable = yes

workgroup = <your workgroup name here>

Right now, On your Window10, when you browse the network(type \\<your debix ip > in the search bar in the down left corner of your Win10 desktop), the folder should appear and you should be able to connect to it.

Apache is a popular web server application you can install on the DEBIX to allow it to serve web pages.

On its own, Apache can serve HTML files over HTTP, and with additional modules can serve dynamic web pages using scripting languages such as PHP.

7.10.1.Installing Apache

• Run the following command to update all the available packages:

sudo apt update

• Run the following command to install the package apache2:

sudo apt install apache2 -y

7.10.2.Test the Web Server

Apache puts a test HTML file in the web folder by default. You can access the default web page when you browse to http://localhost/ on the DEBIX itself, or http://192.168.31.23 (substitute the IP with your DEBIX’s IP address) from another computer on the network. To find the DEBIX’s IP address, run command hostname -I  or command  ifconfig in the command line, and there are also some other approaches.

Browse to the default web page either on the DEBIX or from another computer on the network and you should see the following:

When you see the above image, it means that you have Apache working.

7.10.2.1. Changing the Default Web Page

This default web page is just an HTML file on the filesystem. It is located at /var/www/html/index.html.

Navigate to this directory in a terminal window and have a look at what’s inside:

cd /var/www/html 
ls -al

total 20 
drwxr-xr-x 2 root root 4096 Jul 21 09:48 . 
drwxr-xr-x 3 root root 4096 Jul 21 09:48 .. 
-rw-r--r-- 1 root root 10918 Jul 21 09:48 index.html

From the above image, we can see that there is one file in/var/www/html/ called index.html and it is owned by the user root, the enclosing folder is also owned by the user root. In order to edit the file, you need to change its ownership to your own username. Change the owner of the file using command chown, so here the command should be sudo chown debix:debix index.html.

Now, you can try to edit this file and then refresh the browser to check the web page change. You can also do some research on HTML to make your own websites.

7.10.3.Installing PHP for Apache

Run the following command to install the latest version of PHP and PHP module for Apache, thus your Apache server can process PHP files.

sudo apt install php libapache2-mod-php -y

Now remove the file:index.html

sudo rm index.html

sudo vim index.php

<?php echo "Hello, This is Debix"; ?>

This instructions assume that you have an existing home network. A Ubuntu20.04 virtual machine is used for the server. You will need a DEBIX client to be booted. The DEBIX should be connected with peripherals and also with an Micro SD card(already flashed an image) inserted.

• Ubuntu20.04 virtual machine server Configuration

Assuming that the user account you are using is debix, run the following command to install the required packages.

sudo apt install nfs-kernel-server rpcbind

sudo mkdir -p /home/debix/nfs_new

Add the following line to file /etc/exports:

Put the DEBIX kernel image(Image), device tree file(imx8mp-evk.dtb), and the decompressed 

root filesystem under directory /home/debix/nfs_new

sudo chown -R root:root .

Run the following command to restart nfs-kernel-server:

sudo /etc/init.d/nfs-kernel-server restart

• DEBIX client uboot configuration

Instantly tap the Enter key after pressing the Reset button on the main board to enter the uboot command line of DEBIX

setenv ipaddr 192.168.31.111 
setenv ethaddr b8:ae:1d:01:00:00 
setenv gatewayip 192.168.31.1 
setenv netmask 255.255.255.0 
setenv serverip 192.168.31.197 
saveenv

Run the following command in uboot command line to set bootargs:

setenv bootargs 'console=ttymxc1,115200 root=/dev/nfs rw nfsroot=192.168.31.197:/home/debix/nfs_new,v3,proto=tcp 
ip=192.168.31.111:192.168.31.197:192.168.31.1:255.255.255.0::ens33:off'

Run the following command to in uboot command line set bootcmd:

setenv bootcmd 'nfs 40480000 192.168.31.197:/home/debix/nfs_new/Image; nfs 43000000 192.168.31.197:/home/debix/nfs_new/imx8mp-evk.dtb; booti 40480000 - 43000000'

Run the following command in uboot command line to boot:

saveenv 
boot

Schematics for Debix Model A:

8.1.1.DEBIX Model A

• DEBIX Model A Schematics.pdf
• DEBIX Model A Mechanical Drawings.pdf
• DEBIX Model A Mechanical Drawings.dxf

8.1.2.DEBIX Model A I/O Board

• DEBIX Model A I/O Board Schematics.pdf

• DEBIX Model A I/O Board Mechanical Drawings.pdf
• DEBIX Model A I/O Board Mechanical Drawings.dxf
  

8.1.3.DEBIX Model A LoRa Board

• DEBIX Model A LoRa Board Schematics.pdf

• DEBIX Model A LoRa Board Mechanical Drawings.pdf

• DEBIX Model A LoRa Board Mechanical Drawings.dxf

8.1.4. DEBIX Model A 4G Board

• DEBIX Model A 4G Board Schematics.pdf

• DEBIX Model A 4G Board Mechanical Drawings.dxf

9.1.1.DEBIX SOM A

The Compute Module of DEBIX is DEBIX SOM A.

• DEBIX SOM A Board-to-board Connector Schematics.pdf

• DEBIX SOM A Mechanical Drawings.dxf

9.1.2. DEBIX SOM A I/O Board

• DEBIX SOM A I/O Board Schematics.pdf

• DEBIX SOM A I/O Board Schematics Release Note.txt

• DEBIX SOM A I/O Board Schematics Source File.rar

• DEBIX SOM A I/O Board Mechanical Drawings.dxf

The NXP i.MX 8M Plus is the NXP chip used in DEBIX Model A. NXP i.MX 8M Plus, 4 x ARM Cortex-A53, comes with an integrated neural processing unit (NPU) that delivers up to 2.3 TOPS. Industrial grade CPU runs at 1.6GHz, and commercial grade CPU runs at up to 1.8GHz.

Other information regarding the processor can be found in the following link: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-8-processors:IMX8-SERIES  

11.1.1.eIQ ML Software Development Environment®

The NXP eIQ machine learning(ML) software development environment enables the use of ML algorithms on NXP EdgeVerse®®™ microcontrollers and microprocessors, including i.MX RT crossover MCUs, and i.MX family application processors. eIQ ML software includes a ML workflow tool called eIQ Toolkit, along with inference engines, neural network compilers and optimized libraries. This software leverages open-source and proprietary technologies and is fully integrated into our MCUXpresso SDK and Yocto development environments, allowing you to develop complete system-level applications with ease.

Source: NXP

When comparing NPU with CPU(quad-core Arm® Cortex®-A53 applications processor running at up to 1.8 GHz) performance on the i.MX 8M Plus, the perception is that inference time is much longer on the NPU. This is due to the fact that the ML accelerator spends more time performing overall initialization steps. This initialization phase is known as warmup and is necessary only once at the beginning of the application. After this step inference is executed in a truly accelerated manner as expected for a dedicated NPU. The purpose of this document is to clarify the impact of the warmup time on overall performance.

This document will touch upon the purpose of warmup time and how it on the overall performance of DEBIX Model A.

11.3.1.Software Environment

The primary APIs supported by the NPU are OpenVX 1.2. Figure 1 presents the software stack for the two inference engines, eIQ TF Lite and Arm NN, which currently support NPU acceleration for i.MX 8M Plus.

Source: NXP

Note:

Yocto BSP release: i.MX 8M Plus Beta 1 release L5.4.24_2.1.0_MX8MP

For details of eIQ support build image for imx-image-full, check i.MX Yocto Project User's Guide (document IMXLXYOCTOUG).

This Yocto BSP release includes TF Lite 2.1.0. It supports hardware acceleration using Neural Networks API (NNAPI) Delegates.

eIQ TF Lite applications (pre-installed for Yocto images containing eIQ)

TF Lite benchmarking application (/usr/bin/tensorflow-lite-2.1.0/examples/benchmark_model)

TF Lite image classification example (/usr/bin/tensorflow-lite-2.1.0/examples/label_image). This was used as a starting point and modified to demonstrate Warmup Time impact.

Note:

11.3.2.Hardware Overview

The following table lists the hardware features relevant for the use case described in this application note.

NPU

SRAM (256KB) available for the neural network engine. Some of its features are:

Provide Intelligent caching mechanism for kernel and input tensor.

Pre-determine the best caching allocation.

Guarantee no cache thrashing.

Multiple layers of kernel can be stored at the same time.

Store intermediate tensors.

Intermediate tensors are often broken down into smaller tile to reduce memory footprint.

For more details, refer to i.MX 8M PLUS APPLICATIONS PROCESSOR FAMILY (document IMX8MPLUSFS).

11.3.3.CPU versus NPU Performance

Image Classification:

cd /usr/bin/tensorflow-lite-2.6.0/examples

Run on CPU

./label_image -m mobilenet_v1_1.0_224_quant.tflite -i grace_hopper.bmp -l labels.txt

Results:

INFO: Loaded model mobilenet_v1_1.0_224_quant.tflite

INFO: resolved reporter

INFO: invoked

INFO: average time: 47.289 ms

INFO: 0.764706: 653 military uniform

INFO: 0.121569: 907 Windsor tie

INFO: 0.0156863: 458 bow tie

INFO: 0.0117647: 466 bulletproof vest

INFO: 0.00784314: 835 suit

Run on GPU/NPU acceleration

./label_image -m mobilenet_v1_1.0_224_quant.tflite -i grace_hopper.bmp -l labels.txt -a 1

Results:

INFO: Loaded model mobilenet_v1_1.0_224_quant.tflite

INFO: resolved reporter

INFO: Created TensorFlow Lite delegate for NNAPI.

NNAPI delegate created.

INFO: Applied NNAPI delegate.

INFO: invoked

INFO: average time: 2.807 ms

INFO: 0.768627: 653 military uniform

INFO: 0.105882: 907 Windsor tie

INFO: 0.0196078: 458 bow tie

INFO: 0.0117647: 466 bulletproof vest

INFO: 0.00784314: 835 suit

After this comparison, we can see the average CPU runtime is 47.3ms while with NPU acceleration, it only needs 2.8ms.

Benchmarks:

CPU single core

./benchmark_model --graph=mobilenet_v1_1.0_224_quant.tflite

Result:

STARTING!

Log parameter values verbosely: [0]

Graph: [mobilenet_v1_1.0_224_quant.tflite]

Loaded model mobilenet_v1_1.0_224_quant.tflite

Going to apply 0 delegates one after another.

The input model file size (MB): 4.27635

Initialized session in 2.282ms.

Running benchmark for at least 1 iterations and at least 0.5 seconds but terminate if exceeding 150 seconds.

count=3 first=184806 curr=179480 min=179480 max=184806 avg=181606 std=2303

Running benchmark for at least 50 iterations and at least 1 seconds but terminate if exceeding 150 seconds.

count=50 first=179468 curr=179393 min=179220 max=179672 avg=179464 std=108

Inference timings in us: Init: 2282, First inference: 184806, Warmup (avg): 181606, Inference (avg): 179464

Note: as the benchmark tool itself affects memory footprint, the following is only APPROXIMATE to the actual memory footprint of the model at runtime. Take the information at your discretion.

Peak memory footprint (MB): init=4.89062 overall=10.9961

CPU running on 4 cores

./benchmark_model --graph=mobilenet_v1_1.0_224_quant.tflite --num_threads=4

Result:

STARTING!

Log parameter values verbosely: [0]

Num threads: [4]

Graph: [mobilenet_v1_1.0_224_quant.tflite]

#threads used for CPU inference: [4]

#threads used for CPU inference: [4]

Loaded model mobilenet_v1_1.0_224_quant.tflite

Going to apply 0 delegates one after another.

The input model file size (MB): 4.27635

Initialized session in 2.228ms.

Running benchmark for at least 1 iterations and at least 0.5 seconds but terminate if exceeding 150 seconds.

count=11 first=53805 curr=47928 min=47808 max=53805 avg=48793.2 std=1631

Running benchmark for at least 50 iterations and at least 1 seconds but terminate if exceeding 150 seconds.

count=50 first=138408 curr=47839 min=47692 max=138408 avg=50667.9 std=14264

Inference timings in us: Init: 2228, First inference: 53805, Warmup (avg): 48793.2, Inference (avg): 50667.9

Note: as the benchmark tool itself affects memory footprint, the following is only APPROXIMATE to the actual memory footprint of the model at runtime. Take the information at your discretion.

Peak memory footprint (MB): init=4.84375 overall=10.6602

GPU/NPU Acceleration

./benchmark_model --graph=mobilenet_v1_1.0_224_quant.tflite --num_threads=4 --use_nnapi=true

Result:

STARTING!

Log parameter values verbosely: [0]

Num threads: [4]

Graph: [mobilenet_v1_1.0_224_quant.tflite]

#threads used for CPU inference: [4]

#threads used for CPU inference: [4]

Use NNAPI: [1]

NNAPI accelerators available: [vsi-npu]

Loaded model mobilenet_v1_1.0_224_quant.tflite

INFO: Created TensorFlow Lite delegate for NNAPI.

NNAPI delegate created.

Going to apply 1 delegates one after another.

Explicitly applied NNAPI delegate, and the model graph will be completely executed by the delegate.

The input model file size (MB): 4.27635

Initialized session in 5.111ms.

Running benchmark for at least 1 iterations and at least 0.5 seconds but terminate if exceeding 150 seconds.

count=1 curr=5146489

Running benchmark for at least 50 iterations and at least 1 seconds but terminate if exceeding 150 seconds.

count=359 first=2797 curr=2717 min=2683 max=2797 avg=2720.98 std=16

Inference timings in us: Init: 5111, First inference: 5146489, Warmup (avg): 5.14649e+06, Inference (avg): 2720.98

Note: as the benchmark tool itself affects memory footprint, the following is only APPROXIMATE to the actual memory footprint of the model at runtime. Take the information at your discretion.

Peak memory footprint (MB): init=2.625 overall=30.1836

11.4.1.Warm up time in the case of multiple models running sequentially

Let’s assume we created an application that runs inference on multiple models sequentially. We have Model A, Model B and Model C. The inference for each runs one step at a time, not necessarily in the same order.

Source: NXP

Assuming inference for all the models is executed from the same application. Each of the models has associated a TF Lite Interpreter instance. The Init and Warmup phases should be executed in the beginning. Then the appropriate TF Lite Interpreter will be used to run inference as needed on the corresponding model. To detail the previous sequence, the steps are shown in Figure 3.

Source: NXP

To exemplify the impact on performance, we will run a similar sequence on three TF Lite quantized models:

Mobilenet V1

Mobilenet V2

Inception V3

The time values are obtained when running on the NPU.

Table 1. Warmup time

Table 1 lists preliminary results, subject to change.

The average inference time remains the same no matter in what order the models are running.

If the models are loaded and used from the same application, the information will be kept, and warmup time only has an impact in the initialization phase. If the application exits and restarts, it will load the models again and go through the warmup phase.

Refer to C++ sample code for the C++ sample implementation.

Refer to Python sample code for the python sample implementation.

The python TF Lite API currently allows running inference only on the NPU (CPU not supported).

With the python API, the Init time is not output separately. Only the warm-up and inference time are shown.

The results obtained for the C++ and python applications are similar, there is no noticeable overhead in the python version.

The implementation is based on TF Lite for the purpose of providing a simplified example. The described behavior is the same when using eIQ Arm NN.

This application is focused on the i.MX 8M Plus NPU but note that the warmup time is specific to ML accelerators with hardware support for the OpenVX API. The warmup time will be significant also for i.MX8 platforms using the GPU as ML accelerator.

11.4.2.OVX Graph Caching

There is a way to improve warmup time for subsequent runs of the application by setting the following environment variables:

export VIV_VX_CACHE_BINARY_GRAPH_DIR=`pwd`

export VIV_VX_ENABLE_CACHE_GRAPH_BINARY="1"

By setting up these variables the result of the OpenVX graph compilation will be stored on disk, as the network binary graph files. For example, the files resulted after caching the models used as example in Warmup time in the case of multiple models running sequentially are:

The runtime will do a quick hash check on the network and if it matches the *.nb file hash it will load it into the NPU memory directly

Note:

Table 2 Warmup time

Note:

The decrease of the warm-up time is explained by the fact that the generated network binary graph requires no further compilation and the instructions will be issued to hardware with minimal preparation.

The main steps of the graph caching process are:

1.Load TF Lite file into CPU DDR, done by the TF Lite runtime.
2.The neural network runtime will build the network using the TF Lite model.
3.The neural network runtime will compile the network and store the NPU instructions in memory owned by the NPU.
4.The NPU instructions will be saved on disk in the format of a *.nb file.
5.Next time the same network is loaded in Step 2.
6.The neural network runtime will do a quick hash check on the network. If it matches the Hash, it will load the *.nb file into NPU memory directly.
7.Run inference on the NPU.

To analyze the impact on memory usage, the size of used CPU RAM, CPU Cache/Buffers and NPU memory was analyzed in different stages. For details, see Hardware overview part in this document. The peak value for memory usage is presented for reference. The same application is described in “Warmup time in the case of multiple models running sequentially" was used.

1.AT BOOT: Measurement was performed immediately after linux login, without executing anything else.

2.FIRST RUN [GRAPH NOT CACHED]: The first run of the application right after login.

3.FIRST RUN [GRAPH CACHED]: Graph caching was enabled. 

Set VIV_VX_CACHE_BINARY_GRAPH_DIR and VIV_VX_ENABLE_CACHE_GRAPH_BINARY. The variables were set persistently in order to remain set after a reboot. Then the application was run again.

4.SECOND RUN [GRAPH CACHED]: The second run of the application. The graph was previously cached.

5.AFTER APPLICATION EXIT

Figure 4 illustrates the memory usage at each stage.

Source: NXP

The memory impact should to be taken into consideration when designing the application, to improve the warm-up time might have a draw-back on overall system performance. The impact should be analyzed for each case in order to decide if it will benefit the overall solution.

Note:

When benchmarking an application, it is important to have a good understanding of the data in order to draw correct conclusions.

In the case of the i.MX 8M Plus NPU, the warmup time is considerably longer then the inference time. It has an impact only on the initialization phase of an application. The time should be measured separately for warmup and inference.

Warmup time will usually affect only the first inference run. However, depending on the ML model type it might be noticeable for the first few inference runs. Some preliminary tests must be done to take a decision on what to consider warmup time.

Once the warmup phase is well delimited, the subsequent inference runs can be considered as pure inference and used to compute an average for the inference phase.

Currently the warmup time can be decreased for subsequent application runs by using a graph caching mechanism. One should measure the impact of this feature on overall system performance, in order to decide is the application will benefit from using this mechanism.

There is work in progress to improve the initial warm-up time, speeding up the graph initialization without using the caching mechanism, so please check future releases for related updates.

• Windows 10 IoT Enterprise User Manual V2.2.pdf
• DEBIX Performance Test Results.xlsx
• i.MX Linux User Guide.pdf
• DEBIX Network Boot Instructions.pdf
• IMX8MPRM Rev. 1.06.pdf
• Deploy Deep-learning Model of CUDA on DEBIX and NPU Debugging.pdf