Use the terminal

Why the terminal, and not just the desktop

• Over SSH there is no desktop, only a terminal. That is how you will work on the Pi from the lab PC and from home.
• The MQTT broker, the Flask web server and your control program will run as services without a screen. You will start, stop and inspect them from the command line.
• A command can be written down, copied, repeated and checked. A sequence of clicks cannot. Your project documentation on GitHub will be full of commands.

Read the prompt

Commands follow one pattern: command -options arguments. Options start with - (short) or -- (long) and change how the command behaves; arguments are what it acts on. ls -la /home is the command ls, the options l (long listing) and a (show hidden files), and the argument /home.

Where am I: moving around the file system

Linux has one tree of folders (directories) starting at /, the root. There are no drive letters. Your files live in your home folder, /home/username (with your own username), which the shell abbreviates to ~.

$ pwd                 # print working directory: where am I?
$ ls                  # list what is here
$ ls -la              # long listing, including hidden files (names starting with .)
$ cd Documents        # go into a folder (relative to here)
$ cd /boot/firmware   # go to an absolute path
$ cd ..               # up one level
$ cd                  # back to your home folder
$ cd -                # back to the previous folder

Make, copy, move, delete

$ mkdir iot                    # make a folder
$ mkdir -p iot/week2/evidence  # make the whole path at once
$ touch notes.txt              # create an empty file (or update its timestamp)
$ cp notes.txt backup.txt      # copy
$ cp -r iot iot-copy           # copy a folder and its contents
$ mv backup.txt iot/           # move (or rename when the target is a new name)
$ rm iot/backup.txt            # delete a file: no recycle bin, no undo
$ rm -r iot-copy               # delete a folder and everything in it

Look inside files

$ cat /etc/os-release           # print the whole file
$ less /var/log/syslog          # scroll a long file: space = page, / = search, q = quit
$ head -n 5 /etc/os-release     # first 5 lines
$ tail -n 20 /var/log/syslog    # last 20 lines
$ tail -f /var/log/syslog       # follow a log as it grows; Ctrl+C to stop
$ grep -i wlan /var/log/syslog  # only lines containing "wlan" (case-insensitive)
$ lsblk > evidence/lsblk.txt    # > sends output to a file instead of the screen
$ hostname -I >> evidence/net.txt   # >> appends instead of replacing

Edit with nano

nano is a small editor that runs inside the terminal, which makes it usable over SSH. The two-letter hints at the bottom of its screen are Ctrl combinations.

$ nano notes.txt

Editing a system file needs root: sudo nano /boot/firmware/config.txt. For Python you will use the Thonny editor on the desktop from Week 4; over SSH, nano remains the fallback.

Who is allowed: users, sudo, permissions

Your account owns your home folder and nothing else. System files belong to root. sudo runs one command as root after asking for your password; it is the reason you never log in as root.

$ whoami                 # your username
$ sudo apt update        # run this one command as root
$ ls -l notes.txt
-rw-r--r-- 1 username username 0 Aug 31 15:02 notes.txt

Read the permission string in threes: owner rw-, group r--, others r--. r read, w write, x execute (run as a program, or enter a folder). A Python script you want to run directly needs x:

$ chmod +x blink.py      # make it executable
$ sudo chown username:username file.txt   # take ownership of a file created by root

Install software with apt

Raspberry Pi OS is Debian. Software comes as packages from Raspberry Pi's repositories, and apt fetches and installs them with their dependencies. Two steps, always in this order:

$ sudo apt update                 # 1. refresh the catalogue of available packages
$ sudo apt full-upgrade           # 2. upgrade everything already installed
$ sudo apt install htop tree      # install packages (several at once is fine)
$ apt search mosquitto            # find a package by keyword
$ apt show mosquitto              # describe it before installing
$ sudo apt remove tree            # uninstall
$ sudo apt autoremove             # drop dependencies nobody needs any more

Python libraries are a separate world (pip inside a virtual environment). That is Week 4. Do not pip install system-wide on Raspberry Pi OS; it refuses, and for good reason.

Run and stop programs

$ python3 hello.py        # run a Python script
$ python3                 # interactive Python; exit() or Ctrl+D to leave
$ ps aux | grep python    # which python processes are running? (| pipes output into grep)
$ top                     # live view of CPU and memory; q to quit (htop is nicer)
$ kill 1234               # stop the process with that PID politely
$ kill -9 1234            # stop it forcefully

• Ctrl+C stops the program running in the foreground.
• Ctrl+D sends "end of input": closes a Python shell or an SSH session.
• Ctrl+Z pauses a program (fg resumes it). If a terminal seems stuck, you probably pressed this.

Network commands

$ hostname                     # the Pi's name
$ hostname -I                  # its IP address(es)
$ ip -brief address            # interfaces and their addresses
$ ping -c 3 192.168.4.1        # can I reach this address? (-c 3 = three tries)
$ ssh username@lastname-pi.local    # open a terminal on another machine
$ scp evidence.txt username@lastname-pi.local:~/    # copy a file to the Pi over SSH
$ scp username@lastname-pi.local:~/lsblk.txt .      # copy a file from the Pi to here (. = current folder)
$ ss -tlnp                     # which programs are listening on which ports (Week 3 and later)

Get help and go faster

$ ls --help             # short usage summary
$ man ls                # the full manual page; q to quit
$ history               # everything you typed; !42 re-runs line 42
$ clear                 # or Ctrl+L: clean the screen

Practice: ten minutes that produce your hand-in

Do this on the Pi (or over SSH to it). It creates the evidence folder you will submit at the end of the lab.

1. Make a home for the course

   $ cd
   $ mkdir -p iot/week2/evidence
   $ cd iot/week2/evidence
   $ pwd

2. Capture the proof

   $ findmnt -no SOURCE / > root-device.txt
   $ lsblk -o NAME,SIZE,TYPE,MOUNTPOINTS,MODEL > lsblk.txt
   $ hostnamectl > hostname.txt
   $ head -n 3 /etc/os-release > os.txt
   $ hostname -I > ip.txt
   $ vcgencmd get_throttled > throttled.txt

3. Write one line by hand

   Open nano station.txt, type your station number, Pi model and boot-drive label on one line, save with Ctrl+O, Enter, leave with Ctrl+X.

4. Check and read it back

   $ ls -l
   $ cat *.txt      # * matches every file ending in .txt

5. Bring it to the lab PC

   From the lab PC: scp -r username@lastname-pi.local:~/iot/week2/evidence . copies the whole folder next to you, ready for upload to Omnivox. (From Week 3 on, this folder goes into your GitHub repository instead.)

Cheat card

Print this section (the print stylesheet hides the navigation) or keep it open in a second tab.

Check yourself