Module 0 · Lesson 2 of 12

Your developer toolkit and lab board: terminal, VS Code, Git, compilers, QEMU, Raspberry Pi, SSH and serial console

Set up the whole toolchain: terminal, VS Code remote, Git, gcc and clang, QEMU, then bring up a headless Raspberry Pi over SSH and serial.

  • Beginner to advanced
  • 26 min read
  • 45 min lab
What you will need

Ubuntu 24.04 (WSL2, VM or container); a Raspberry Pi 4 or 5, a microSD card, and a USB-TTL serial adapter for the lab-board sections

By the end you can 7 objectives
  • Describe the role of each tool in the edit-build-run-debug loop and explain why an embedded engineer needs a lab board.
  • Navigate the shell, set PATH and aliases, and redirect or pipe command output.
  • Trace the four stages of compilation and name the sub-programs gcc runs, as shown by gcc -v.
  • Create a Git repository, stage and commit changes, and push them over SSH to a remote.
  • Bring up a Raspberry Pi headless, log in over SSH, and locate it on the network.
  • Wire a USB-TTL adapter to the Pi UART and capture the boot log at 115200 8N1.
  • Compare RS-232 and 3.3 V TTL levels and explain why 5 V must never reach a GPIO pin.
Read the lesson below; the video will appear here when published.
01

Why a toolkit, and why a lab board

2 min read

Every line of C you will write in this program travels the same path: you type it in an editor, a compiler turns it into a program, you run the program and watch it misbehave, a debugger shows you why, and a version-control system saves the working version before you break it again. The tools in this lesson exist so that path is fast and safe.

You will need, on your Linux machine: a good terminal, a shell you can drive, a text editor, a compiler and debugger, Git, QEMU for emulation, and Python for the tooling scripts later in the program. Install the essentials in one command on Ubuntu, WSL2 or a Debian container:

bash
sudo apt update
sudo apt install build-essential gdb git qemu-system-x86 qemu-system-arm python3 python3-venv

build-essential pulls in gcc, the make build tool and the C library headers. gdb is the debugger. python3 -m venv is how you later create isolated Python environments for the automation modules. On Windows you will want Windows Terminal (install it from the Microsoft Store) and WSL2 from the previous lesson, because the whole program assumes a Unix shell.

One loop, everywhere

The edit-build-run-debug loop is identical on a laptop and on a board. On the board only the last two steps move: you build on the host or the board, then run on the board and debug over SSH or serial.

Why a lab board at all, when the next section hands you a QEMU virtual machine? Because emulation never catches a loose ground wire, a wrong baud rate, a brownout when a motor starts, or a driver that only misbehaves on the real silicon. The Raspberry Pi is this program's lab bench: cheap, widely available, and it runs the same Linux kernel as a production device.

The edit-build-run-debug loopEditVS CodeBuildgcc / clangRunhost orboardDebuggdb↻ Repeat from step 1EditVS CodeBuildgcc / clangRunhost orboardDebuggdb↻ Repeat from step 1
The edit, build, run and debug loop, with the tool that owns each stage.
02

The terminal and the shell

5 min read

Learn a handful of navigation commands first: pwd prints the current directory, ls lists it, cd moves elsewhere, and mkdir, rm, cp and mv manage files. cd .. goes up one level and cd ~ returns home.

When you type a command, the shell does not search the whole disk. It reads the in order and runs the first match. echo $PATH shows it, and which gcc or type gcc reveals which file the shell will run. PATH is an , one of many such as HOME and SHELL.

bash
echo $PATH
which gcc
export PATH="$HOME/bin:$PATH"

The last line prepends your own bin directory so your scripts are found first. Put it in ~/.bashrc to make it stick, alongside an :

bash
alias ll='ls -l'
alias ..='cd ..'

Command history saves retyping: the up arrow replays earlier lines, history lists them, and Ctrl-R searches backwards as you type.

Two commands connect programs together, and you will use both constantly. Redirection sends output to a file instead of the screen: > overwrites, >> appends, and 2>&1 sends the error stream to the same place as normal output. A pipe | feeds one program's output into the next as input.

bash
gcc -v 2>&1 | tee build.log
sudo dmesg | grep -i uart

The first line captures both the normal and error output of gcc into a file while still showing it; the second filters kernel messages (Ubuntu restricts the kernel log to administrators, hence sudo). In both, one program's output becomes another's input, and that idea of small tools joined by pipes is the heart of working with Linux.

Try it below:

cat passes the log line through unchanged; grep keeps it because it contains 'uart', dropping the rest of the kernel log, and uniq leaves it as-is.

Two editors, two jobs

Use nano for quick edits: type, then Ctrl+O to save and Ctrl+X to exit. For vim learn only the minimum now: press i to insert, Esc to leave insert mode, x to delete a character, and :wq to write and quit (or :q! to abandon changes).

From typed command to running programParse lineAlias?expandBuiltin?run inshellPATH lookupfirst matchExit from step 4: not foundcommand not foundfork + execParse lineAlias?expandBuiltin?run inshellPATH lookupfirst matchExit from step 4: not foundcommand not foundfork + exec
How the shell turns a typed command into a running program, from alias to PATH lookup.
Navigate the shell and inspect PATH
learner@embeddex:~/lab/work$ touch notes.txt
learner@embeddex:~/lab/work$ # list it
learner@embeddex:~/lab/work$ ls -l
total 0
-rw-r--r-- 1 learner learner 0 Nov 15 05:53 notes.txt
learner@embeddex:~/lab/work$ # up one level
learner@embeddex:~/lab/work$ cd ..
learner@embeddex:~/lab$ # PATH is a colon-separated list of directories
learner@embeddex:~/lab$ echo $PATH | tr ':' '\n' | head -5
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
learner@embeddex:~/lab$ # which file runs when you type gcc
learner@embeddex:~/lab$ which gcc
/usr/bin/gcc
learner@embeddex:~/lab$ # cd is a shell builtin, not a file on disk
learner@embeddex:~/lab$ type cd
cd is a shell builtin
learner@embeddex:~/lab$ # type gcc shows the path too, and that it is external
learner@embeddex:~/lab$ type gcc
gcc is /usr/bin/gcc
Redirect and pipe output
learner@embeddex:~/lab$ # > overwrites: write the first line
learner@embeddex:~/lab$ echo boot > log.txt
learner@embeddex:~/lab$ # >> appends the second line
learner@embeddex:~/lab$ echo panic >> log.txt
learner@embeddex:~/lab$ # and a third
learner@embeddex:~/lab$ echo boot >> log.txt
learner@embeddex:~/lab$ # redirection > wrote them
learner@embeddex:~/lab$ cat log.txt
boot
panic
boot
learner@embeddex:~/lab$ # < feeds the file in as input
learner@embeddex:~/lab$ wc -l < log.txt
3
learner@embeddex:~/lab$ # a pipe keeps only the matching lines
learner@embeddex:~/lab$ cat log.txt | grep boot
boot
boot
learner@embeddex:~/lab$ # pipes chain, each program doing one job
learner@embeddex:~/lab$ sort log.txt | uniq -c
      2 boot
      1 panic
Why a local script is 'command not found'
learner@embeddex:~/lab$ # the script exists, but note its permissions
learner@embeddex:~/lab$ ls -l hi
-rw-r--r-- 1 learner learner 35 Nov 15 05:53 hi
learner@embeddex:~/lab$ # run it by path: permission denied
learner@embeddex:~/lab$ ./hi
bash: ./hi: Permission denied
learner@embeddex:~/lab$ # add the execute bit
learner@embeddex:~/lab$ chmod +x hi
learner@embeddex:~/lab$ # now the path form runs
learner@embeddex:~/lab$ ./hi
hi from the sandbox
learner@embeddex:~/lab$ # the bare name still fails: . is not on PATH
learner@embeddex:~/lab$ hi
bash: hi: command not found
03

VS Code and the remote extensions

2 min read

Install VS Code from code.visualstudio.com or, on Ubuntu, from the official apt repository. The code command opens it from the shell. Then install three extensions: WSL (formerly called Remote - WSL), Remote - SSH, and the C/C++ extension (its extension id is ms-vscode.cpptools).

The remote extensions change where your files and commands live. With the WSL extension, the editor opens a window whose shell, compilers and filesystem are inside WSL2, while the window itself runs on Windows. With Remote - SSH, the same trick reaches a machine over the network: you open ssh user@host, and everything you type and build happens on that machine. For this program the payoff is that you can edit on the board directly through VS Code, or edit on the host and copy files across.

The C/C++ extension adds three things. IntelliSense gives you code completion, hover information and parameter hints as you type. Inline errors underline mistakes with red squiggles before you compile, because the extension runs the compiler's front end over your file. Integrated debugging lets you set breakpoints, step, and inspect variables without leaving the editor; under the hood it drives gdb or lldb.

The last two features read their settings from two JSON files in a hidden .vscode folder. tasks.json describes build tasks, such as running gcc -g -o hello hello.c with one keypress. launch.json describes how to start a program under the debugger and which binary to load. You do not need to write these from scratch: the extension can generate both, and you will customise them in the C toolchain lesson.

json
{
  "version": "2.0.0",
  "tasks": [
    { "label": "build", "type": "shell",
      "command": "gcc", "args": ["-g", "-o", "hello", "hello.c"] }
  ]
}

The short form above is all a build task is: a label, a shell command and its arguments. A launch configuration adds the debugger side, naming the program to run and the debugger to use.

VS Code remote architectureVS Code windowhost (Windows)Remote extensionRemote-SSH or WSLRemote Linuxboard or WSL2Toolchaingcc, gdbedits and commands go down, diagnostics come upVS Code windowhost (Windows)Remote extensionRemote-SSH or WSLRemote Linuxboard or WSL2Toolchaingcc, gdbedits and commands go down,diagnostics come up
VS Code's window on the host, the remote extension, and where the compiler and debugger actually run.
04

Git: snapshots and sharing

4 min read

A repository, a directory whose entire history Git records in a hidden .git folder, starts either from scratch or from a copy. git init creates an empty one; git clone URL downloads a complete copy of someone else's, including all history. The program's course repository is distributed this way, so your first real command will be a clone.

Step by stepHow a change becomes a commit
  1. Edit: you modify files in the working tree, the ordinary directory you see.

  2. Stage: git add file.c copies the change into the staging area, the next snapshot in waiting.

  3. Commit: git commit -m 'message' freezes the staged changes into the repository as a permanent snapshot.

  4. Push: git push sends new commits to a remote such as GitHub or GitLab.

  5. Pull: git pull brings other people's new commits back to your machine.

The staging area is the part people forget. Until you git add, a change is not part of any commit; git status shows what is staged, what is modified, and what is untracked. git diff shows unstaged changes, and git diff --staged shows what will be committed. git log lists history.

Before your first commit, tell Git who you are:

bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

A .gitignore file lists files Git should never track, such as build outputs and editor noise:

shell
build/
*.o
*.swp

Branching lets you work on a copy of the history without disturbing the main line. git branch feature creates a branch, git switch feature (or the older git checkout feature) moves onto it, and git switch -c name creates and moves in one step. You merge branches back later; for now the point is that a branch is a movable label on a commit, not a copy of your files.

To share over SSH, you need a key on the host. Generate one with ssh-keygen -t ed25519 -C "you@example.com", then paste the public half (~/.ssh/id_ed25519.pub) into the SSH keys page of GitHub or GitLab. Test with ssh -T git@github.com. The next section covers what that key actually is.

Git's three areas plus the remoteWorking treeyour filesStaging areanext snapshotLocal repository.git historyRemoteGitHub / GitLabTransitionsgit addWorking treeyour filesStaging areanext snapshotgit commitStaging areanext snapshotLocal repository.git historygit pushLocal repository.git historyRemoteGitHub / GitLabgit pullRemoteGitHub / GitLabWorking treeyour filesWorking treeyour filesStaging areanext snapshotLocal repository.git historyRemoteGitHub / GitLabTransitionsgit addWorkingtreeyour filesStagingareanextsnapshotgit commitStagingareanextsnapshotLocalrepository.githistorygit pushLocalrepository.githistoryRemoteGitHub /GitLabgit pullRemoteGitHub /GitLabWorkingtreeyour files
The three Git areas plus the remote, and which command moves a change between each.
Git: staging is what a commit snapshots
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   README.md

learner@embeddex:~/lab/demo$ # freeze the snapshot
learner@embeddex:~/lab/demo$ git commit -m 'first commit'
[main (root-commit) 3d51c17] first commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md
learner@embeddex:~/lab/demo$ # one commit in history
learner@embeddex:~/lab/demo$ git log --oneline
3d51c17 first commit
learner@embeddex:~/lab/demo$ # branch off to experiment
learner@embeddex:~/lab/demo$ git switch -c feature
Switched to a new branch 'feature'
learner@embeddex:~/lab/demo$ # two branches, feature checked out
learner@embeddex:~/lab/demo$ git branch
* feature
  main
05

Compilers: gcc and clang

4 min read

Both compilers turn C source into machine code. gcc is the GNU compiler, the default on Linux; clang is the LLVM-based compiler, often faster to compile and with clearer error messages. They accept the same C language, so clang can replace gcc in almost every command you will see. Compile a first program and run it:

bash
gcc -o hello hello.c
./hello

-o hello names the output; without it the result is a file called a.out. Useful flags you will use constantly: -g embeds debug information, -Wall -Wextra turn on warnings, and -O2 enables optimisation (which, as a beginner, you should usually leave off so the debugger lines up with your source).

Behind that one command is a pipeline of four stages, each a separate program the driver runs for you.

1preprocess

The preprocessor expands #include and #define directives, producing a pure C translation unit.

2compile

The real compiler, the cc1 program, turns that C into assembly language for the target CPU.

3assemble

The as assembler converts the assembly into an object file of machine code plus symbols.

4link

The linker (ld, reached through a wrapper called collect2) joins your object file with the C library into one executable.

You can stop at any stage. -E stops after preprocessing, -S after compiling to assembly, and -c after assembling to an object file. Each output is worth opening once, because it makes the whole rest of the program concrete.

bash
gcc -E hello.c -o hello.i   # preprocessed C
gcc -S hello.c -o hello.s   # assembly
gcc -c hello.c -o hello.o   # object file

Run gcc -v to watch the driver confess its sub-commands. Typical output (yours will differ):

shell
$ gcc -v -o hello hello.c
Using built-in specs.
Target: x86_64-linux-gnu
 ...
 /usr/lib/gcc/x86_64-linux-gnu/<version>/cc1 hello.c ... -o /tmp/ccXXXX.s
 as --64 -o /tmp/ccYYYY.o /tmp/ccXXXX.s
 /usr/lib/gcc/x86_64-linux-gnu/<version>/collect2 ... -o hello /tmp/ccYYYY.o ...

The Target line names the . This matters enormously for embedded work: a compiler whose triple begins x86_64 builds programs for your laptop, while aarch64-linux-gnu-gcc builds for a 64-bit ARM board like the Pi. Building for a different CPU than the one you are running on is called cross-compilation, and it returns throughout the program.

Going deeperWhere the compiler lives and what it really runs

The cc1 binary sits under /usr/lib/gcc/<triple>/<version>/, not on your PATH, which is why you never run it by hand. collect2 is a wrapper that knows how to find startup objects such as crt1.o (which contains _start, the real entry point that calls main) and the C library before handing off to ld. The preprocessor is not a separate binary in modern gcc: cc1 performs preprocessing internally, although a standalone cpp still exists. clang follows the same four stages but replaces cc1 with its own front end and may use the LLVM lld linker instead of GNU ld. When a build fails with a message about ld or collect2, the linker cannot find a symbol: a missing library, a misspelt function name, or a source file you forgot to list.

The four compilation stageshello.csourcePreprocessexpandincludesCompilecc1 toassemblyAssembleas toobjectLinkld toexecutablehello.csourcePreprocessexpandincludesCompilecc1 toassemblyAssembleas toobjectLinkld toexecutable
The four compilation stages and the file each produces, from hello.c to the executable.
gcc: four stages and the target triple
r /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=47566eaefd3e2283aa9dde1719520798f7119954, for GNU/L
inux 3.2.0, not stripped
learner@embeddex:~/lab$ # the driver confesses its sub-commands
learner@embeddex:~/lab$ gcc -v -o hello hello.c 2>&1 | grep -E 'Target:|cc1|--64|collect2'
Target: x86_64-linux-gnu
 /usr/libexec/gcc/x86_64-linux-gnu/13/cc1 -quiet -v -imultiarch x86_64-linux-gnu hello.c -quiet
-dumpbase hello.c -dumpbase-ext .c -mtune=generic -march=x86-64 -version -fasynchronous-unwind-t
ables -fstack-protector-strong -Wformat -Wformat-security -fstack-clash-protection -fcf-protecti
on -o /tmp/cccs0FIi.s
 as -v --64 -o /tmp/ccuDORxu.o /tmp/cccs0FIi.s
 /usr/libexec/gcc/x86_64-linux-gnu/13/collect2 -plugin /usr/libexec/gcc/x86_64-linux-gnu/13/libl
to_plugin.so -plugin-opt=/usr/libexec/gcc/x86_64-linux-gnu/13/lto-wrapper -plugin-opt=-fresoluti
on=/tmp/ccidhsrG.res -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s -plugin-o
pt=-pass-through=-lc -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s --build-i
d --eh-frame-hdr -m elf_x86_64 --hash-style=gnu --as-needed -dynamic-linker /lib64/ld-linux-x86-
64.so.2 -pie -z now -z relro -o hello /usr/lib/gcc/x86_64-linux-gnu/13/../../../x86_64-linux-gnu
/Scrt1.o /usr/lib/gcc/x86_64-linux-gnu/13/../../../x86_64-linux-gnu/crti.o /usr/lib/gcc/x86_64-l
inux-gnu/13/crtbeginS.o -L/usr/lib/gcc/x86_64-linux-gnu/13 -L/usr/lib/gcc/x86_64-linux-gnu/13/..
/../../x86_64-linux-gnu -L/usr/lib/gcc/x86_64-linux-gnu/13/../../../../lib -L/lib/x86_64-linux-g
nu -L/lib/../lib -L/usr/lib/x86_64-linux-gnu -L/usr/lib/../lib -L/usr/lib/gcc/x86_64-linux-gnu/1
3/../../.. /tmp/ccuDORxu.o -lgcc --push-state --as-needed -lgcc_s --pop-state -lc -lgcc --push-s
tate --as-needed -lgcc_s --pop-state /usr/lib/gcc/x86_64-linux-gnu/13/crtendS.o /usr/lib/gcc/x86
_64-linux-gnu/13/../../../x86_64-linux-gnu/crtn.o
06

QEMU: a machine in software

2 min read

When you run QEMU, it reads the guest's machine-code instructions one block at a time and translates them into instructions your real CPU can run, a technique called dynamic binary translation. It also emulates the hardware around the CPU: RAM, a disk controller, a network card, a serial port and a display. To the guest operating system, it looks like real hardware.

The qemu-system-* family provides one binary per target. qemu-system-x86_64 emulates a 64-bit PC, while qemu-system-arm and qemu-system-aarch64 emulate 32-bit and 64-bit ARM machines. Boot a small disk image with:

bash
qemu-system-x86_64 -m 512 -hda disk.img

-m 512 gives the guest 512 MB of RAM and -hda disk.img attaches a virtual hard disk. To try an ARM machine without hardware, a command such as qemu-system-aarch64 -M virt -cpu cortex-a57 -m 1G -nographic -kernel Image boots a kernel for a generic virtual ARM board.

Why does this program make you install it now? Because the embedded modules that follow, M4 and M5, build entire Linux images for ARM boards. Testing every image on real hardware is slow and expensive, so build systems such as Yocto and Buildroot run their images in QEMU first, and only the final image goes to a board. You are learning the tool you will rely on when your real board is not plugged in, and the M11 virtualization module will open the hood and add a device of your own.

Going deeperTCG and KVM: why emulation is slower than the real thing

QEMU's software translator is called TCG, the Tiny Code Generator. Every guest instruction becomes several host instructions, and every emulated device access is handled in software, so a guest can run many times slower than native code. When the guest and host share the same architecture, QEMU can instead use KVM, a Linux kernel feature that lets the guest run directly on the CPU with hardware virtualization. KVM is fast but only works same-architecture; TCG works everywhere, which is exactly what you need to run ARM guests on an x86 laptop. The two are often combined, with QEMU providing the devices and KVM providing the CPU.

A guest running under QEMUGuest programyour applicationGuest kernelLinuxEmulated machineCPU, RAM, devicesHost OSLinuxHost CPUx86 or ARMguest instructions are translated down to thereal CPUGuest programyour applicationGuest kernelLinuxEmulated machineCPU, RAM, devicesHost OSLinuxHost CPUx86 or ARMguest instructions aretranslated down to the real CPU
The layers between your guest program and your real CPU when running under QEMU.
07

The Raspberry Pi as a lab board

3 min read

Pick a model for the course. The Pi 4 uses a quad-core Cortex-A72, the Pi 5 a quad-core Cortex-A76, and both are fine; the Pi Zero 2 W is the cheap, minimal option that runs the same software with less RAM. The Pi 5 is the comfortable default for the heavier modules. You need a microSD card (16 GB or more), a power supply, and for first boot an HDMI cable, keyboard and mouse, or none of them if you go headless.

The operating system image is Raspberry Pi OS, a Debian-based Linux. The official Raspberry Pi Imager writes it to the SD card and, crucially, lets you preconfigure everything so the board boots straight onto your network. In the Imager you can set the hostname, a username and password, enable SSH, and enter your Wi-Fi name and passphrase. The dd alternative copies a downloaded image byte for byte:

bash
sudo dd if=raspios.img of=/dev/sdX bs=4M status=progress

A board is the normal state for an embedded device, so this lesson makes it your default. Raspberry Pi OS reads a few optional files from the small FAT partition on the SD card at first boot. An empty file named ssh turns on the SSH server. A file named userconf.txt containing username:password-hash creates the first user, where the hash comes from openssl passwd -6. The Imager writes all of this for you, which is the modern path; the files are what it writes on Raspberry Pi OS Bookworm, and you can create them by hand if you image with dd. Newer releases are moving first-boot setup to cloud-init files, which is one more reason to let the Imager do it.

bash
openssl passwd -6
# paste the output after "yourname:" into userconf.txt

1image the card

Use the Imager: choose Raspberry Pi OS Lite (no desktop, smaller and faster), select the card, and fill in the OS customisation settings.

2first boot

Insert the card, apply power, and give it a minute. With no monitor, watch the green activity LED settle instead of a login screen.

3find it and log in

On most networks the board answers at yourhostname.local through mDNS; the next sections cover finding its IP address and logging in over SSH.

The UART serial console, enabled next, is the other door into a headless board, and the one that works even when the network does not.

The Pi FAT boot partitionboot (FAT)read at first bootconfig.txtfirmware optionscmdline.txtkernel argumentskernel*.imgthe Linux kernelsshempty file enables SSHuserconf.txtfirst userfirstrun.shfirst-boot scriptboot (FAT)read at first bootconfig.txtfirmware optionscmdline.txtkernel argumentskernel*.imgthe Linux kernelsshempty file enables SSHuserconf.txtfirst userfirstrun.shfirst-boot script
The files on the Pi's FAT boot partition that a first boot reads, including the ssh and userconf.txt files.
Top view of a Raspberry Pi 4 Model B locating USB-C power, two micro-HDMI sockets, Ethernet, USB ports, the underside microSD slot and the 40-pin header with pin 1 marked.
Raspberry Pi 4 Model B port guide. The microSD slot is underneath. Pin 1 is the square pad at the board-facing left end of the GPIO header. Pi 5 has a different Ethernet/USB layout.On a small screen, scroll the diagram sideways to read all labels.
08

SSH: logging in and keys

4 min read

The client is ssh. Log in with ssh user@host or ssh user@192.168.1.50; the first connection asks you to confirm the host's fingerprint, which you accept once. Files copy with scp, which uses the same connection:

bash
scp hello.c pi@raspberrypi.local:
scp pi@raspberrypi.local:/etc/os-release .

The first copies a file to the Pi's home directory, the second pulls a file back. (Current Raspberry Pi OS keeps its logs in the systemd journal, read with journalctl, so there is no /var/log/syslog to copy.) Replace pi with the username you created: Raspberry Pi OS has had no default pi user since 2022. A bare : means the home directory; a path follows otherwise.

Password login sends your password over the encrypted link and checks it against the account. Key login replaces that with a cryptographic proof. Generate a pair with ssh-keygen -t ed25519; it writes the private key to ~/.ssh/id_ed25519 and the public key to ~/.ssh/id_ed25519.pub. Copy the public key to the board with ssh-copy-id user@host, which appends it to the board's ~/.ssh/authorized_keys.

Step by stepHow key-based authentication works
  1. Offer: your client presents the public key it would like to use.

  2. Check: the server looks for that public key in the account's authorized_keys file.

  3. Sign: the client signs data unique to this session (the session identifier from the key exchange) with the private key.

  4. Verify: the server checks that signature with the public key from authorized_keys; only the holder of the private key could have produced it.

  5. Open: on success the server opens the session. The private key never leaves your machine.

Save typing with ~/.ssh/config aliases:

shell
Host pi
    HostName raspberrypi.local
    User pi
    IdentityFile ~/.ssh/id_ed25519

Now ssh pi does the whole thing. When a key login fails, the permissions on the remote files are the usual culprit: ~/.ssh must be 700 and authorized_keys must be 600, or the server ignores them.

Try it below:

600 = -rw-------: only the owner reads and writes the file, which sshd requires for authorized_keys; the ~/.ssh directory itself must be 700, and any wider permission makes the server ignore the key.

  • octal: 600
Going deeperssh-agent, key reuse and port forwarding

If your private key has a passphrase, ssh-agent remembers it for the session: start it with eval $(ssh-agent) and load keys with ssh-add. Your host can then reuse the key for every connection without typing the passphrase again. The same key also authenticates Git pushes, so one ssh-add covers the board and your repository. Port forwarding previews a trick the later modules use heavily: ssh -L 8080:localhost:80 pi makes the Pi's web service appear at your machine's port 8080, and -R does the reverse, exposing a port of yours on the Pi. Forwarding is how you reach a service that listens only on the board, without opening it to the whole network.

Confirm the key before you lock the door

Before disabling password login, log in with the key alone, ideally from a second terminal, and verify it works. Once passwords are off, a lost key means a serial-console rescue, so the serial setup in the next section comes first for a reason.

Key-based SSH authenticationClientServeroffer public keychallenge, encryptedsignature (private key)verified, session open1. Client → Serveroffer public key2. Server → Clientchallenge, encrypted3. Client → Serversignature (private key)4. Server → Clientverified, session open
The key-based authentication exchange between client and server.
09

Serial console and the UART

4 min read

When a board will not boot onto the network, the serial console is the line that still prints the kernel's messages. The Pi exposes one on its GPIO header: BCM GPIO 14 is TXD (board pin 8), GPIO 15 is RXD (board pin 10), and there are several ground pins. The logic is 3.3 V, and the data is crossed: your adapter's TX wire goes to the Pi's RX pin, and the adapter's RX wire to the Pi's TX pin. Ground connects to ground. TX-to-TX is the classic first mistake, and its symptom is silence.

The must match on both ends. The framing convention is 115200 8N1: 115200 baud, 8 data bits, no parity bit, 1 stop bit. Every byte is wrapped in a start bit and one or more stop bits so the receiver can find the byte boundaries, since there is no separate clock.

To connect, you need a USB-TTL adapter built around a chip such as the CP2102, FT232 or CH340. This plugs into your laptop's USB port and presents a serial device, usually /dev/ttyUSB0 on Linux. Open the console with one of three tools:

bash
picocom -b 115200 /dev/ttyUSB0
minicom -D /dev/ttyUSB0 -b 115200
screen /dev/ttyUSB0 115200

picocom is the friendliest: exit with Ctrl+A then Ctrl+X. screen exits with Ctrl+A then k. Before the serial port works, enable it on the Pi: run sudo raspi-config, open Interface Options, then Serial Port, and answer yes to the login shell question: that puts the kernel console and a login prompt on the port, which is what you need to capture boot messages (answer no only if you want a bare serial port for your own programs). On a Pi 4 the equivalent config.txt setting is enable_uart=1. The Pi 5 is different: its default console is a dedicated 3-pin debug UART connector, and to use GPIO 14 and 15 instead you add dtparam=uart0_console to config.txt.

Match the voltage, always

Buy a 3.3 V USB-TTL adapter, and if it has a voltage jumper, set it to 3.3 V. A 5 V signal on a GPIO pin can destroy the Pi's system on a chip, which is not repairable.

Never feed 5 V into a 3.3 V pin

The Pi's GPIO pins are not 5 V tolerant. A 5 V USB-TTL adapter, a 5 V Arduino, or a power line mistaken for a signal wire will damage the board. Check voltages before connecting anything.

Going deeperRS-232 versus 3.3 V TTL, and flow control

A USB-TTL adapter is not the same as the old DE-9 serial port on a PC. Real RS-232 swings between about -12 V and +12 V, with a mark (idle, or logic 1) as a negative voltage, and uses a DE-9 connector. TTL UART logic uses 0 V for logic low and 3.3 V for logic high, on header pins or a USB cable. The USB-TTL chip converts TTL levels to USB, not to RS-232, so it connects straight to the Pi; a genuine RS-232 port connected directly to a GPIO pin would damage it just like 5 V. Flow control is a handshake for when one side cannot keep up: RTS/CTS uses two extra wires so the receiver can say pause, and XON/XOFF sends control characters in the data stream instead. A console at 115200 8N1 needs neither, because interactive text is slow and buffered; flow control matters when you stream data continuously and cannot afford to drop a byte.

RS-232 versus 3.3 V TTLRS-2323.3 V TTLConnectorDE-9 portUSB cable /header pinsVoltage swingabout -12 Vto +12 V0 V to 3.3 VMark (idle)negativevoltage3.3 V (high)Direct to GPIOdamages thePisafe, 3.3 Vlogic
The electrical difference between RS-232 and 3.3 V TTL serial, and why only one is safe on the Pi.
Pi physical pin 6 GND connects to adapter GND, pin 8 GPIO14 TXD connects to adapter RX, and pin 10 GPIO15 RXD connects to adapter TX. VCC is disconnected. Use 3.3 V logic only, never 5 V.
Cross transmit and receive and share ground: pin 6 to GND, pin 8 to RX, pin 10 to TX. Leave adapter VCC disconnected and power the Pi separately. Use 3.3 V TTL logic only, never 5 V or RS-232 levels. Configure the UART/console first; Pi 5 defaults to its separate debug UART.On a small screen, scroll the diagram sideways to read all labels.
10

Finding the board and putting it all together

4 min read

Most home networks hand out addresses automatically. means the Pi's address can change between boots. A static address, set by hand in the Pi's network configuration, never changes, which is useful for a lab board you always reach the same way. On your host, ip addr lists your own interfaces and addresses; arp -a (or the modern ip neigh) shows which MAC addresses your machine has seen, and a router's web interface has a DHCP lease table listing every device and the address it was given.

The friendlier route is mDNS: with Avahi running on the Pi (it is by default), the name raspberrypi.local resolves to the board's address automatically, so you type ssh pi@raspberrypi.local and never learn the IP.

bash
ip addr
ip neigh
ping raspberrypi.local
WSL2 and .local names

Windows Subsystem for Linux runs behind its own network stack, and .local names often do not resolve from inside WSL2. If ping raspberrypi.local fails there, find the IP from your router or from Windows, and use the IP directly in ~/.ssh/config.

When the board does not appear at all, diagnose in a fixed order, because each step depends on the one before it. Symptom: no login and no ping. Cause: one of four layers is broken. Diagnosis and fix, in order: confirm the power LED is on and the supply is adequate; confirm the SD card is seated and was imaged correctly (a card that never blinks means no boot); capture the serial log at 115200 8N1, which shows exactly where boot stops; and only then chase the network, checking the cable, the DHCP lease table, and mDNS.

For a board you leave on your desk, harden it the way you would any server. Log in with the key, then edit /etc/ssh/sshd_config, set PasswordAuthentication no, and restart sshd. Keep ~/.ssh at 700 and authorized_keys at 600 on the board. Reuse keys across hosts with ssh-agent and ssh-add rather than copying the same private key everywhere, and reach a board-only service with ssh -L port forwarding instead of exposing it.

The end-to-end loop that proves everything works is short. Edit on the host in VS Code. Sync the change to the board with git push then git pull, or with scp. Build and run on the board:

bash
ssh pi@raspberrypi.local
gcc -g -o hello hello.c
./hello

If that one command runs a program on your board, then your editor, your compiler, your SSH setup and your lab board all work together, and the foundation for the C toolchain lesson is complete.

Headless bring-up checklistPower LEDlit?SD cardimaged,seated?Serial logbootcaptured?NetworkIP found?Exit from step 4: no IPcheck cable and DHCP leaseSSH loginsuccessPower LEDlit?SD cardimaged,seated?Serial logbootcaptured?NetworkIP found?Exit from step 4: no IPcheck cable and DHCP leaseSSH loginsuccess
The ordered bring-up checklist: power, SD card, serial log, then network.
Finding a host on the network with ip
learner@embeddex:~/lab$ # the name mDNS advertises on the local network
learner@embeddex:~/lab$ hostname
embeddex
learner@embeddex:~/lab$ # your own interfaces and IP addresses
learner@embeddex:~/lab$ ip -brief address
lo               UNKNOWN        127.0.0.1/8 ::1/128
eth0             UP             172.22.214.87/20 fe80::215:5dff:fe2a:155d/64
learner@embeddex:~/lab$ # the default gateway: the router that hands out DHCP leases
learner@embeddex:~/lab$ ip route
default via 172.22.208.1 dev eth0 proto kernel onlink
172.22.208.0/20 dev eth0 proto kernel scope link src 172.22.214.87
learner@embeddex:~/lab$ # neighbors this machine has exchanged packets with
learner@embeddex:~/lab$ ip neigh
172.22.208.1 dev eth0 lladdr 00:15:5d:35:51:e3 REACHABLE
11

Try it

1 min read

Open the lab for this session and make the whole toolkit real. Flash the SD card with Raspberry Pi Imager, enable SSH and a user, boot the Pi headless, and log in with ssh. Connect the USB-TTL adapter to GPIO 14 and 15 with the lines crossed, open picocom at 115200 8N1, and capture the kernel boot log. Then clone the course repository, make a small commit, and push it, and run gcc -v to record the target triple for your machine. The practice pack has the exact commands and the checklist from the last section to work through.

Key takeaways

  • The terminal, editor, compiler, debugger and version control form one loop: edit, build, run, debug.
  • The shell resolves a command through aliases, builtins and the PATH, then joins programs with pipes and redirection.
  • gcc is a driver that runs the preprocessor, cc1, the assembler and the linker; gcc -v shows the real sub-commands.
  • Git's staging area sits between the working tree and the repository: add stages, commit snapshots, push shares.
  • QEMU emulates a whole machine in software, which is slower than hardware but perfect for the M4 and M5 image labs.
  • A headless Pi boots without a monitor; SSH and the serial UART are the two reliable ways in.
  • The Pi's serial logic is 3.3 V; the UART is crossed TX to RX and runs at 115200 8N1.
  • When a board does not appear, check power, then the SD card, then the serial log, then the network, in that order.

Reflect

  1. Explain to a colleague, in two sentences: describe the role of each tool in the edit-build-run-debug loop and explain why an embedded engineer needs a lab board.
  2. Which objective are you least sure about? Re-read that section, then do its exercise in the practice pack.
  3. What surprised you when you ran the commands yourself?

On a real board

Repeat the key commands on your Raspberry Pi or lab board over SSH or the serial console. Note anything that behaves differently from your PC, such as missing tools, a BusyBox shell or a read-only filesystem.

Practise this lessonExercises, quiz, interview preparation and spaced review

References and further reading

Official documentation first. Links checked when the lesson was published.

Find your next step

↑ ↓ to move · Enter to open · Esc to close