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.
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.
The following contents will be presented:
ipor from a development PC using
This section aims to introduce you to the basic Linux commands
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:
pwd (present working directory) command output tells you the full path to the directory you are inside:
# <a id="pwd" name="pwd" href="#pwd"> pwd</a>/home/root
touch command creates an empty file:
By using the
pwd command, you already know the present directory is
/home/root. Let's create two directories named
dir2 inside it:
mkdir dir1 dir2
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:
There are some notations for describing a directory path:
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:
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:
Change to the recently created
# <a id="relative_path" name="relative_path" href="#relative_path">relative path</a>cd dir1# <a id="absolute_path" name="absolute_path" href="#absolute_path">absolute path</a>cd /home/root/dir1
Go back to the parent directory:
# <a id="relative_path-2" name="relative_path-2" href="#relative_path-2">relative path</a>cd ..# <a id="from_anywhere_three_possibilities" name="from_anywhere_three_possibilities" href="#from_anywhere_three_possibilities">from anywhere (three possibilities)</a>cdcd ~cd /home/root
Go to the root directory:
Please go back to the home directory before proceeding to the next step.
cp command to copy files. Let's copy the
# <a id="copy_with_the_same_name_to_dir1" name="copy_with_the_same_name_to_dir1" href="#copy_with_the_same_name_to_dir1">copy with the same name to dir1</a>cp sample_file.txt dir1# <a id="copy_to_dir2_and_rename_file_to_copy_dir2_filetxt" name="copy_to_dir2_and_rename_file_to_copy_dir2_filetxt" href="#copy_to_dir2_and_rename_file_to_copy_dir2_filetxt">copy to dir2 and rename file to copydir2file.txt</a>cp sample_file.txt ./dir1/copy_dir2_file.txt# <a id="make_a_copy_to_the_same_directory_using_the_name_copy_filetxt" name="make_a_copy_to_the_same_directory_using_the_name_copy_filetxt" href="#make_a_copy_to_the_same_directory_using_the_name_copy_filetxt">make a copy to the same directory using the name copyfile.txt</a>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_contentscp -a dir1/. dir1_contents
Note: Use the
ls command in the next step to verify the directory's content.
ls command to see the directory contents:
lsls /homels /bin
You can see detailed information about the files and directories inside the one being inspected:
ls -l /binls -lh /bin
mv command can be used to rename or move a file/directory:
touch sample_file.txtmv sample_file.txt renamed.txtmv dir2 directory2
rm command to delete a file or directory.
Warning: The process is not reversible, so be careful to not delete something important!
# <a id="Delete_file" name="Delete_file" href="#Delete_file">Delete file</a>rm renamed.txt# <a id="Delete_directory" name="Delete_directory" href="#Delete_directory">Delete directory</a>rm -r dir1_copy# <a id="Ask_before_deleting" name="Ask_before_deleting" href="#Ask_before_deleting">Ask before deleting</a>rm -ri dir1_contents
This section explains how to read and write to a file directly from the command-line and also using a text editor.
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.
# <a id="create_or_overwrite_file" name="create_or_overwrite_file" href="#create_or_overwrite_file">create or overwrite file</a>echo "Hello World" > readwrite.txt# <a id="create_or_append_to_file" name="create_or_append_to_file" href="#create_or_append_to_file">create or append to file</a>echo "Hello Again" >> readwrite.txt
cat command to read a file from the command-line.
cat readwrite.txt# <a id="print_line_numbers_ignoring_or_not_the_empty_lines" name="print_line_numbers_ignoring_or_not_the_empty_lines" href="#print_line_numbers_ignoring_or_not_the_empty_lines">print line numbers, ignoring or not the empty lines</a>cat -b readwrite.txtcat -n readwrite.txt
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:
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.
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:
This is the command for write -> quit.
To go to a specific line:
# <a id="line_for_instance" name="line_for_instance" href="#line_for_instance"> :<line>, for instance:</a>:4
To search for a specific text:
# <a id="text_for_instance" name="text_for_instance" href="#text_for_instance"> /<text>, for instance</a>/world
Press the "n" key to browse through the
Play the browser-based game VIM Adventures to learn more about Vim in a funny way.
This section describes how to search for a specific file and how to search a directory for specific file text contents.
To search for a specific file, use the
find command. The search is made inside a specific directory and all of its children directories:
# <a id="find_path_name_filename" name="find_path_name_filename" href="#find_path_name_filename">find <path> -name "<filename>"</a># <a id="search_for_a_specific_file_name" name="search_for_a_specific_file_name" href="#search_for_a_specific_file_name">search for a specific file name</a>find . -name "readwrite.txt"# <a id="search_all_files_with_a_specific_extension" name="search_all_files_with_a_specific_extension" href="#search_all_files_with_a_specific_extension">search all files with a specific extension</a>find / -name "*.txt"# <a id="search_all_files_containing_read_in_the_name_for_the_current_directory" name="search_all_files_containing_read_in_the_name_for_the_current_directory" href="#search_all_files_containing_read_in_the_name_for_the_current_directory">search all files containing "read" in the name, for the current directory</a>find . -name "*read*"# <a id="search_all_files_containing_read_in_the_name_for_the_user_directory" name="search_all_files_containing_read_in_the_name_for_the_user_directory" href="#search_all_files_containing_read_in_the_name_for_the_user_directory">search all files containing "read" in the name, for the user directory</a>find /home/root/ -name "*read*"
To search for a file that has a specific text as content, you can use the
grep is useful not only for file contents search but also as a filter to the output of other commands, for instance.
# <a id="search_for_files_containing_the_hello_world_string_in_the_current_directory" name="search_for_files_containing_the_hello_world_string_in_the_current_directory" href="#search_for_files_containing_the_hello_world_string_in_the_current_directory">search for files containing the "hello world" string in the current directory</a>grep -nre "hello world" ./*# <a id="case_insensitive_search_with_absolute_path" name="case_insensitive_search_with_absolute_path" href="#case_insensitive_search_with_absolute_path">case insensitive search with absolute path</a>grep -nrie "hello world" /home/root/*
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
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.
enpand 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
You can refer to the Scan your local network to find the board IP and MAC address article to learn more about this topic.
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 email@example.com: # copy a file to /home/some-directory scp dir1/hello.sh firstname.lastname@example.org:/home/some-directory # copy a directory recursively to root's home scp -r dir1 email@example.com:
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 firstname.lastname@example.org:hello.sh . # copy a file from /home/some-directory into the current directory scp email@example.com:/home/some-directory/hello.sh . # copy a directory recursively from root's home into your home PC scp -r firstname.lastname@example.org:some-directory ~
If you have a more advanced use case in mind, consider searching on the internet how to use the
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.
# <a id="compress_folder_and_contents" name="compress_folder_and_contents" href="#compress_folder_and_contents">compress folder and contents</a>tar -cjvf compressed.tar.bz2 dir1tar -cvf compressed.tar.gz dir1# <a id="compress_only_the_folder_contents_notice_that_there_is_a_dot_after_the_directory" name="compress_only_the_folder_contents_notice_that_there_is_a_dot_after_the_directory" href="#compress_only_the_folder_contents_notice_that_there_is_a_dot_after_the_directory">compress only the folder contents (notice that there is a dot after the directory)</a>tar -cjvf compressed.tar.bz2 -C ./dir1 .tar -cvf compressed.tar.gz -C ./dir1 .
# <a id="decompress_to_current_directory" name="decompress_to_current_directory" href="#decompress_to_current_directory">decompress to current directory</a>tar -xjvf compressed.tar.bz2tar -xvf compressed.tar.gz# <a id="decompress_to_specific_directory" name="decompress_to_specific_directory" href="#decompress_to_specific_directory">decompress to specific directory</a>tar -cjvf compressed.tar.bz2 -C ./dir1tar -cvf compressed.tar.gz -C ./dir1
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.
hwclock command is commonly used in systems that don't have a program such as
timedatectl to synchronize the system and hardware clocks.
Get the clock times and system configuration:
# <a id="timedatectl" name="timedatectl" href="#timedatectl"> timedatectl</a>Local time: Thu 2017-01-12 13:34:00 BRSTUniversal time: Thu 2017-01-12 15:34:00 UTCRTC time: Thu 2017-01-12 13:34:01Time zone: America/Sao_Paulo (BRST, -0200)Network time on: yesNTP synchronized: noRTC in local TZ: yes
Set the system clock and synchronize changes with the hardware clock:
timedatectl set-ntp falsetimedatectl set-time "2017-01-12 13:40:11"
Change the time zone:
# <a id="list_available_time_zones" name="list_available_time_zones" href="#list_available_time_zones">list available time zones</a>timedatectl list-timezones# <a id="change_time_zone" name="change_time_zone" href="#change_time_zone">change time zone</a>timedatectl set-timezone America/Sao_Paulo
Get the system date/time:
# <a id="date" name="date" href="#date"> date</a>Thu Jan 12 13:56:43 BRST 2017
Note: Hwclock usage will not be presented. For
hwclock and also more
timedatectl usage, please use the option
--help, as in
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 a file named
print.sh using the vi editor, with the following contents:
# <a id="binsh" name="binsh" href="#binsh">!/bin/sh</a> 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.
Before running it, you have to make the file executable:
chmod +x print.sh
Run the script in the foreground:
./print.sh# <a id="or" name="or" href="#or">or</a>/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.
To run the script in the background, just add the "&" character to the end of the line:
./print.sh &# <a id="Notice_that_you_can_use_the_terminal_but_CTRLC_wont_stop_the_script_from_running" name="Notice_that_you_can_use_the_terminal_but_CTRLC_wont_stop_the_script_from_running" href="#Notice_that_you_can_use_the_terminal_but_CTRLC_wont_stop_the_script_from_running">Notice that you can use the terminal, but CTRL+C won't stop the script from running:</a>datels -lpwd
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:
# <a id="list_all_processes" name="list_all_processes" href="#list_all_processes">list all processes</a>ps aux# <a id="find_only_the_processes_containing_print_in_the_name" name="find_only_the_processes_containing_print_in_the_name" href="#find_only_the_processes_containing_print_in_the_name">find only the processes containing "print" in the name</a>ps aux | grep print
The second output column will print the process ID (PID).
Use kill to stop the script
See the figure below for reference regarding the previous steps:
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.
Note: Behind the kill command, there is the concept of Unix/Linux signals. You may want to search in the web for more information.
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.
To run htop:
You should see a screen similar to the one presented in the figure below:
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.
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
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:
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.
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 file
/etc/systemd/system/print.service with the following contents. You can use the vi text editor, previously presented:
[Unit] Description=Start the print.sh script After=multi-user.target [Service] Type=simple ExecStart=/home/root/print.sh [Install] WantedBy=multi-user.target
Reload the configurations and enable the service at startup:
systemctl daemon-reloadsystemctl enable print.service
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.servicesystemctl status print.service
Reboot the system and verify that the script started:
rebootps aux | grep print.sh
This section describes how to change the login password.
Use the command
passwd to change the system password:
# <a id="passwd" name="passwd" href="#passwd"> passwd</a>Enter new UNIX password:Retype new UNIX password:passwd: password updated successfully
This section shows how to download files from the web using
Warning: Your embedded system must have internet access.
wget command to download a file from the web:
wget -c https://docs.toradex.com/102075-colibri-imx6-datasheet.pdf
The file will be downloaded in the present directory.
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.
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.
First of all, update the packages list:
List the available packages and filter your search using
opkg listopkg 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
To install a package:
opkg install libpython2.7-1.0