Introduction

This article is a collection of basic Linux commands and procedures relevant to using your embedded system.

Note: This article is meant as an overview to get you started, thus you may find useful to search for more comprehensive tutorials, guides, and manuals over the internet.

Torizon and Reference Images for Yocto Project

Both Torizon and the Toradex Reference Images for Yocto Project are Linux-based. Several instructions presented in this article will apply seamlessly to both, others may require tweaks or simply not apply to one or the other.

Contents Overview

The following contents will be presented:

• Use the basic Linux commands touch, cp, cd, ls, mv, mkdir, rm and pwd
• Basic file read/write using echo, cat and the Vi text editor
• Search for a file or file contents using file and grep
• Get your board IP and MAC addresses either from the debug UART using ip or from a development PC using arp-scan or nmap
• Copy files between two Linux machines using scp
• Compress and decompress folders using tar
• Get the system date and time using the timedatectl, date and hwclock commands
• Create, run in the background and kill a shell script, using the chmod, ps and kill commands
• Monitor system performance using the system manager htop
• Run a script automatically at boot time, by creating a systemd service
• Change the system password using passwd
• Download files, using wget

Basic Linux commands

This section aims to introduce you to the basic Linux commands touch, cp, cd, ls, mv, mkdir, rm and pwd, as well as some concepts regarding directory structure.

Note: Whenever you want a quick help for a specific command, use the --help option, such as in the example below:

<command> --help

Find out in which directory you are

The pwd (present working directory) command output tells you the full path to the directory you are inside:

# pwd
/home/root

Create an empty file

The touch command creates an empty file:

touch sample_file.txt

Create a new directory

By using the pwd command, you already know the present directory is /home/root. Let's create two directories named dir1 and dir2 inside it:

mkdir dir1 dir2

Directory structure

Note: This step explains the directory structure for a Linux environment. You might skip it once this is a theoretical step. Click the button below to show.

In the Linux environment, there is the notion of absolute or full path and relative path. See the following directory structure:

• 

  Sample directory structure

There are some notations for describing a directory path:

• / is the root directory. All absolute paths start with /
• / is also the directory separator
• . denotes the current or present directory
• .. denotes the parent directory, relative to the current directory
• ~ is the home directory. For the Toradex modules, it is always the /home/root directory.

The full path points to a location in a file system without depending on the current directory. The picture below presents the absolute paths for the previously presented directory structure:

• 

  Absolute paths

The relative path points to a location in a file system relative to the current path. The picture below presents the relative paths for the previously presented directory structure, considering /home/root the present directory:

• 

  Relative paths

Change directory

Change to the recently created dir1:

#relative path
cd dir1
#absolute path
cd /home/root/dir1

Go back to the parent directory:

#relative path
cd ..
#from anywhere (three possibilities)
cd
cd ~
cd /home/root

Go to the root directory:

cd /

Please go back to the home directory before proceeding to the next step.

Copy file/directory

Use the cp command to copy files. Let's copy the sample_file.txt around:

#copy with the same name to dir1
cp sample_file.txt dir1
#copy to dir2 and rename file to copy_dir2_file.txt
cp sample_file.txt ./dir1/copy_dir2_file.txt
#make a copy to the same directory using the name copy_file.txt
cp sample_file.txt copy_file.txt

In order to copy a whole directory and its contents, preserving file attributes:

cp -a dir1 dir1_copy

If you want to copy the directory contents inside an already created directory:

mkdir dir1_contents
cp -a dir1/. dir1_contents

Note: Use the ls command in the next step to verify the directory's content.

Check directory contents

Use the ls command to see the directory contents:

ls
ls /home
ls /bin

You can see detailed information about the files and directories inside the one being inspected:

ls -l /bin
ls -lh /bin

Move or rename a file/directory

The mv command can be used to rename or move a file/directory:

touch sample_file.txt
mv sample_file.txt renamed.txt
mv dir2 directory2

Delete a file/directory

Use the rm command to delete a file or directory.

Warning: The process is not reversible, so be careful to not delete something important!

#Delete file
rm renamed.txt
#Delete directory
rm -r dir1_copy
#Ask before deleting
rm -ri dir1_contents

Basic file read/write

This section explains how to read and write to a file directly from the command-line and also using a text editor.

Write from command-line

Use the echo command to write to a file from the command-line.

Note: This command will be useful to set/configure hardware features from the command-line, although it is limited for text file editing.

#create or overwrite file
echo "Hello World" > readwrite.txt
#create or append to file
echo "Hello Again" >> readwrite.txt

Read from command-line

Use the cat command to read a file from the command-line.

cat readwrite.txt
#print line numbers, ignoring or not the empty lines
cat -b readwrite.txt
cat -n readwrite.txt

For getting used to the basic Linux commands, you may want to play the games bashcrawl and Terminus.

Use the Vi text editor

Note: Vi and also the Vim editor have many features and commands and are known as hard-to-use for beginners. Search the web if you want to dive deep into learning how to use them, or have a look at the nano text editor with may be slightly more user-friendly.

To create or edit a file using the Vi text editor:

vi readwrite

When you open the application, you are in the normal mode and cannot edit the text. Press the "i" key to enter the "insert" mode. Then you can edit the file as you will.

• 

  Vi text editor insert mode

After you make some changes, press the "ESC" key to return to the "normal" mode. In this mode, you can save changes and exit Vi. To do so, type the following:

:wq

This is the command for write -> quit.

• 

  Save changes and quit Vi

To go to a specific line:

# :<line>, for instance:
:4

To search for a specific text:

# /<text>, for instance
/world

Press the "n" key to browse through the <text> occurrences.

• 

  Vi text search

Play the browser-based game VIM Adventures to learn more about Vim in a funny way.

File search

This section describes how to search for a specific file and how to search a directory for specific file text contents.

Search for a specific file

To search for a specific file, use the find command. The search is made inside a specific directory and all of its children directories:

#find <path> -name "<filename>"
#search for a specific file name
find . -name "readwrite.txt"
#search all files with a specific extension
find / -name "*.txt"
#search all files containing "read" in the name, for the current directory
find . -name "*read*"
#search all files containing "read" in the name, for the user directory
find /home/root/ -name "*read*"

Search files containing some text

To search for a file that has a specific text as content, you can use the grep command. grep is useful not only for file contents search but also as a filter to the output of other commands, for instance.

#search for files containing the "hello world" string in the current directory
grep -nre "hello world" ./*
#case insensitive search with absolute path
grep -nrie "hello world" /home/root/*

Find your IP and MAC address

This section describes how to get your board IP and MAC address, either from the board itself using ip if you have a debug serial connection or from your development PC using arp-scan or nmap.

Find board IP and MAC from the debug serial

Make sure that you have a working serial connection by following the instructions from Configuring Serial Port Debug Console (Linux/U-Boot).

# ip address
or, as a shortcut
# ip a

A relatively big list might be displayed, depending on how many physical and virtual active interfaces the board has. Two interfaces will be printed for sure:

• lo, which is a loopback interface.
• A wired interface. It usually starts with eth or enp and might vary slightly depending on the distribution you are using (TorizonCore, Toradex Reference Images for Yocto, legacy images such as the Angstrom-based from BSP 2.8).

In the example below using TorizonCore, the Ethernet interface is ethernet0, the IP address is 192.168.10.44 and the MAC address is 00:14:2d:63:19:3f:

• 

  List of network interfaces on TorizonCore with IP and MAC address

Scan your local network to find the board IP and MAC address

You can refer to the Scan your local network to find the board IP and MAC address article to learn more about this topic.

Copy files between Linux PCs

This section describes how to copy files over the network using SSH with the scp command. First, create a directory structure and some files inside it:

mkdir -p dir1/dir2/dir3
touch dir1/hello.sh dir1/dir2/hello-again.sh dir1/dir2/dir3/hello-thrice.txt

Then, as described in the previous section, find the IP of your board. Let's assume the IP is 192.168.10.5, the user is root and there is no password for the sake of this example. To copy some files or directories to the board:

# copy a file to root's home
scp dir1/hello.sh root@192.168.10.5:
# copy a file to /home/some-directory
scp dir1/hello.sh root@192.168.10.5:/home/some-directory
# copy a directory recursively to root's home
scp -r dir1 root@192.168.10.5:

You can also transfer files and directories from the remote host into your PC:

# copy a file from root's home into the current directory
scp root@192.168.10.5:hello.sh .
# copy a file from /home/some-directory into the current directory
scp root@192.168.10.5:/home/some-directory/hello.sh .
# copy a directory recursively from root's home into your home PC
scp -r root@192.168.10.5:some-directory ~

If you have a more advanced use case in mind, consider searching on the internet how to use the rsync command.

Compress and decompress folders

This section describes how to compress and decompress folders using the tar command. It does not cover all the possibilities, only some of the most commonly used.

Compress

#compress folder and contents
tar -cjvf compressed.tar.bz2 dir1
tar -cvf compressed.tar.gz dir1
#compress only the folder contents (notice that there is a dot after the directory)
tar -cjvf compressed.tar.bz2 -C ./dir1 .
tar -cvf compressed.tar.gz -C ./dir1 .

Decompress

#decompress to current directory
tar -xjvf compressed.tar.bz2
tar -xvf compressed.tar.gz
#decompress to specific directory
tar -cjvf compressed.tar.bz2 -C ./dir1
tar -cvf compressed.tar.gz -C ./dir1

Date and time

There are two relevant date/time clocks in Linux: the hardware date/time, usually referred to as real-time clock (RTC), and the system date/time. While the command timedatectl takes care of synchronizing both of them, usually the date command is used to get the system time, due to its simpler output.

The hwclock command is commonly used in systems that don't have a program such as timedatectl to synchronize the system and hardware clocks.

Timedatectl get clocks

Get the clock times and system configuration:

# timedatectl
Local time: Thu 2017-01-12 13:34:00 BRST
Universal time: Thu 2017-01-12 15:34:00 UTC
RTC time: Thu 2017-01-12 13:34:01
Time zone: America/Sao_Paulo (BRST, -0200)
Network time on: yes
NTP synchronized: no
RTC in local TZ: yes

Timedatectl set clocks

Set the system clock and synchronize changes with the hardware clock:

timedatectl set-ntp false
timedatectl set-time "2017-01-12 13:40:11"

Timedatectl change system clock time zone

Change the time zone:

#list available time zones
timedatectl list-timezones
#change time zone
timedatectl set-timezone America/Sao_Paulo

Date get system clock

Get the system date/time:

# date
Thu Jan 12 13:56:43 BRST 2017

Note: Hwclock usage will not be presented. For hwclock and also more date and timedatectl usage, please use the option --help, as in hwclock --help.

Shell script

In this chapter, you will learn how to create a shell script, run it in the background, and kill it. A simple script that prints a string to the terminal every 5 seconds will be used as an example.

Create the script

Create a file named print.sh using the vi editor, with the following contents:

 print.sh
#!/bin/sh

while true
do
 echo "Hello world!"
 sleep 5
done

Warning: The line #!/bin/sh is not a commented line! It tells that the application used to execute the script is /bin/sh, therefore you must not erase this line. This line is known as shebang.

Make it executable

Before running it, you have to make the file executable:

chmod +x print.sh

Run the script

Run the script in the foreground:

./print.sh
#or
/home/root/print.sh

Note: Press CTRL+C to stop the script, or any command-line application, from running. Sometimes there are applications that don't exit on CTRL+C such as the vi text editor, but in general it works.

Run in the background

To run the script in the background, just add the "&" character to the end of the line:

./print.sh &
#Notice that you can use the terminal, but CTRL+C won't stop the script from running:
date
ls -l
pwd

Find the script PID

Use the command ps to get a snapshot of all the processes running. Combine it with the grep command to search for a specific task/application:

#list all processes
ps aux
#find only the processes containing "print" in the name
ps aux | grep print

The second output column will print the process ID (PID).

Kill the script

Use kill to stop the script

kill <PID>

See the figure below for reference regarding the previous steps:

• 

  Run in the background and kil

Note: For this specific case, you could use the fg command to bring the process to the foreground and then use CTRL+C to stop it.

./print.sh &
fg
<CTRL+C>

Note: Behind the kill command, there is the concept of Unix/Linux signals. You may want to search in the web for more information.

System resources monitoring

Htop is an interactive process viewer for Unix systems. It is not the only option available (there is also top) but it was chosen for this how-to because of its user-friendly interface.

Run htop

To run htop:

htop

You should see a screen similar to the one presented in the figure below:

• 

  Htop overview

It presents system status and statistics, such as: CPU and RAM usage (the pre-built images have swap disabled by default); system tasks; load average and; uptime. Below the overall status, all of the system tasks are listed, as well as their individual resources usage and other relevant information.

Note: To exit htop press F10.

kill the print.sh script

As an exampĺe of htop functionality, run the stress command in the background to see the CPU usage go up:

./print.sh &
stress -c 1 &
htop

• 

  CPU usage increased by the stress command

Use the arrow keys to browse through the processes until you find the stress task. You can also use the search functionality pressing F3 or use your mouse to click on the process line:

• 

  Using htop to kill process

Select SIGTERM and press ENTER to kill the process.

Note: When using the kill system call without parameters, as in the previous step, it sends a SIGTERM to the process.

Startup service - systemd

In this section, a service that runs a script at system startup will be created.

Note: For Torizon users: to run a container on startup, read the article Run and Manage Docker Container on Torizon.

Create the script file

Create the file /etc/systemd/system/print.service with the following contents. You can use the vi text editor, previously presented:

 /etc/systemd/system/print.service
[Unit]
Description=Start the print.sh script           
After=multi-user.target

[Service]
Type=simple
ExecStart=/home/root/print.sh     

[Install]
WantedBy=multi-user.target

Enable the service

Reload the configurations and enable the service at startup:

systemctl daemon-reload
systemctl enable print.service

Run and test

Start the script manually for the first time and see its status. Notice that the script doesn't print directly to the terminal, since a new shell session is created by the service.

systemctl start print.service
systemctl status print.service

• 

  Print script running

Reboot the system

Reboot the system and verify that the script started:

reboot
ps aux | grep print.sh

Change the system password

This section describes how to change the login password.

Single Step: Passwd

Use the command passwd to change the system password:

# passwd
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

Download files

This section shows how to download files from the web using wget.

Warning: Your embedded system must have internet access.

Single step: Download

Use the wget command to download a file from the web:

wget -c https://docs.toradex.cn/102075-colibri-imx6-datasheet.pdf

The file will be downloaded in the present directory.

Legacy

This section contains knowledge that is generally useful for embedded Linux but relates to technologies that are not used anymore by Toradex in its embedded Linux software offerings, thus the name legacy.

The content here is provided as-is and is not updated over time.

Package manager (OPKG)

Attention: until BSP 2.8, the Ångström feeds were available on Toradex pre-built images.

OPKG is the package manager for the Ångström distribution. This section shows how to list, install and remove packages.

Warning: Your embedded system must have internet access.

Update

First of all, update the packages list:

opkg update

List available packages

List the available packages and filter your search using grep:

opkg list
opkg list | grep libpython

Note: The Python programming language has many packages available. If you filter using python instead of libpython, there will be many results to browse through

Install package

To install a package:

opkg install libpython2.7-1.0