Installationsanleitung für ES2

Hochschule Augsburg, Prof. Högl, Wintersemester 23/24,

2023-10-24

Änderungen:

Dieser Text beschreibt die Installation der ES2 Arbeitsumgebung unter Linux. Der erste Abschnitt richtet sich an Leute die Windows 10 oder 11 auf ihrem Rechner installiert haben. Mit dem Windows Subsystem für Linux in der Version 2 kann man Linux innerhalb von Windows betreiben. Alle weiteren Abschnitte sind unabhängig davon, ob man auf einem “realen” Linux oder in WSL2 arbeitet.

URL: https://gitlab.informatik.hs-augsburg.de/es2/doc

1 WSL2 installieren (nur bei Windows 10/11)

Bei dieser Anleitung habe ich mich an https://goneuland.de/windows-10-subsystem-fuer-linux-wsl-2-installieren gehalten.

WSL aktivieren

In Powershell (Administrator) eingeben

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Update auf WSL2

Kommandos

Version und Status ausgeben

wsl.exe -l -v

Welche Distributionen gibt es?

wsl.exe --list --online

Distribution installieren

wsl.exe --install -d Debian

Distribution für Benutzer ausführen

wsl.exe --distribution <Distribution Name> --user <User Name>

WSL Version ausgeben

wsl.exe --version

Shutdown

wsl.exe --shutdown Debian

Beenden und neu starten (das WSL wird neu gestartet, auf der Kommandozeile in WSL sieht man das aber nicht)

wsl.exe --terminate debian

Mountpunkte

USBIPD installieren unter Windows

Dieser Schritt ist nötig, da sich Windows alle angeschlossenen USB Geräte schnappt. Mit USBIPD gibt man bestimmte USB Geräte an die Linux Distribution weiter.

Auf der Homepage des Projekts unter

https://github.com/dorssel/usbipd-win

findet man einen msi Installer:

https://github.com/dorssel/usbipd-win/releases/

Mit

usbipd.exe wsl list

bekommt man eine Liste der angeschlossenen USB Geräte (das STM32L476 Nucleo ist über USB angeschlossen):

BUSID  VID:PID    DEVICE
STATE
3-1    046d:c534  USB-Eingabegerät                                              Not attached
3-6    04f2:b221  Integrated Camera                                             Not attached
4-2    0483:374b  ST-Link Debug, USB-Massenspeichergerät, Serielles USB-Ger...  Not attached

Danach “attached” man das gewünschte Gerät, in unserem Fall ist das der ST-Link Debugger auf dem Nucleo Board:

usbipd.exe wsl attach --busid 4-2

Mit usbipd.exe wsl list sieht man, dass das Gerät nun im Zustand “attached” ist.

Im Debian (in WSL2) installiert man die Pakete “usbip” und “usbutils” (darin ist lsusb).

sudo apt install usbip usbutils

Danach erkennt das lsusb Kommando in Debian das USB Gerät (sudo ist dazu nötig). Die Ausgabe sollte so ähnlich sein:

$ sudo lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 0483:374b STMicroelectronics ST-LINK/V2.1
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Quelle: https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/

Damit man ohne sudo auf die USB Geräte zugreifen kann müssen udev Regeln angelegt werden. Prinzipiell funktioniert das unter dem virtuellen Debian genauso wie im richtigen Debian - ist also weiter unten im Text beschrieben. Allerdings muss man bei WSL2 zunächst noch den udev Service aktivieren. Den aktuellen Status findet man mit sudo service udev status heraus.

Falls /etc/wsl.conf noch nicht existiert, legt man sie an mit den folgenden drei Zeilen:

[boot]
command="service udev start"
systemd=true

Die dritte Zeile ist optional, wenn sie vorhanden ist wird der systemd aktiviert.

Um das Zusammenspiel mit Windows zu verbessern kann man auch die folgenden zwei Zeilen einfügen (Danke für den Tipp):

[interop]
appendWindowsPath=true

Nun beendet man Debian und startet es sofort neu mit dem Kommando

wsl.exe --terminate debian

Dieser Vorgang dauert einige Sekunden, danach sollte der Zugriff auf die USB Geräte auch ohne sudo möglich sein, sofern die USB Regeln installiert sind.

Falls systemd aktiviert wurde, kann man die laufenden Dienste wie folgt ausgeben:

systemctl list-units --type=service

WSL Konfiguration

Es gibt zwei Konfigurationsdateien, die am Anfang noch nicht existieren:

Quelle: https://learn.microsoft.com/en-us/windows/wsl/wsl-config

Pakete in Linux installieren

Windows Terminal

Komfortables Terminal, bei dem man Powershell und Linux in verschiedenen Tabs öffnen kann. Man kann das Terminal auch teilen wie bei einem Terminal Multiplexer.

https://learn.microsoft.com/en-us/windows/terminal/install

APT Repository

Wer häufig Pakete installiert sollte den Server in /etc/apt/sources.list auf einen Server in der Region ändern.

Literatur

2 ARM-GCC

Es gibt zwei Möglichkeiten, 1. Installation der Linux Pakete, oder 2. Download und Installation einer ARM Toolchain.

  1. Linux Pakete installieren

    $ sudo apt install binutils-arm-none-eabi gcc-arm-none-eabi
$ sudo apt install gdb-multiarch

    Hinweis: Das ausführbare Programm des Debuggers heisst wie das Paket gdb-multiarch. Die Beispielprogramme haben jedoch den Namen arm-none-eabi-gdb konfiguriert. Als Lösung bietet sich ein symbolischer Link an:

    cd /usr/bin
sudo ln -s gdb-multiarch arm-none-eabi-gdb

  2. Die aktuellen Toolchains von ARM findet man unter

    https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

    im Bereich “x86_64 Linux hosted cross toolchains” / AArch32 bare-metal target (arm-none-eabi).

    Zur Zeit (10/2023) ist das arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi.tar.xz. Eine Kopie ist in https://hhoegl.informatik.hs-augsburg.de/es2/tools/.

    $ cd /opt
$ sudo tar Jxvf ~/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi.tar.xz

    In ~/.bashrc die PATH Variable erweitern:

    export PATH=$PATH:/opt/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi/bin

    Das Installationsverzeichnis /opt/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi ist knapp 1 GByte gross.

    Unter den ausführbaren Dateien ist auch der GNU Debugger arm-none-eabi-gdb. Allerdings gibt es hier ein Problem, da dieser GDB so gebaut wurde, dass er einen Python 3.8 Interpreter zum Starten braucht. Diese Python Version ist schon etwas älter und muss daher durch folgenden Umweg installiert werden:

    sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.8

    Hinweis: Alternativ kann man den Python Interpreter im Quelltext holen und selber kompilieren. Eine Anleitung ist unter https://tecadmin.net/install-python-3-8-ubuntu.

    Danach sollte man den GDB testweise starten:

    $ arm-none-eabi-gdb
GNU gdb (Arm GNU Toolchain 12.3.Rel1 (Build arm-12.35)) 13.2.90.20230627-git
Copyright (C) 2023 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
...
(gdb)

    Man beendet ihn mit dem quit Kommando.

Es ist auch möglich, den GDB als Paket zu installieren (sudo apt install gdb-multiarch) und den GCC als Download-Archiv zu beziehen.

3 OpenOCD

Auch hier gibt es wieder zwei Möglichkeiten: 1. Installation des Pakets, oder 2. Sourcen holen, kompilieren und installieren.

  1. Paket installieren

    $ sudo apt install openocd

    Die ausführbare Datei ist nachher in /usr/bin/openocd. Die Konfigurationsdateien liegen unter /usr/share/openocd.

  2. Selber kompilieren

    $ sudo apt install libusb-1.0-0-dev libtool pkg-config libusb-1.0-0-dev automake autoconf
$ wget https://hhoegl.informatik.hs-augsburg.de/es2/tools/openocd-0.12.0.tar.bz2
$ tar jtf openocd-0.12.0.tar.bz2
$ cd openocd-0.12.0
$ ./bootstrap 
$ ./configure --enable-stlink --prefix=/opt/openocd-0.12.0
$ make
$ sudo make install
# PATH um /opt/openocd-0.12.0/bin erweitern

    Optional lässt sich noch die Dokumentation im PDF Format erzeugen. Es sollte vorher schon LaTeX installiert sein:

    sudo apt install texinfo
make pdf

    Danach ist die Doku in doc/openocd.pdf zu finden.

    Auch hier findet man die PDF Datei: https://hhoegl.informatik.hs-augsburg.de/es2/openocd/openocd-0.12.0.pdf

    Die aktuellen OpenOCD Sourcen findet man unter https://github.com/openocd-org/openocd.

4 Udev Regeln

Damit man als gewöhnlicher User auf die USB Schnittstelle des STLINK Adapters zugreifen kann, müssen sogenannte udev Regeln in das Verzeichnis /etc/udev/rules.d/ kopiert werden. Es genügt, eine einzelne Datei 60-openocd.rules zu kopieren:

$ sudo cp /lib/udev/rules.d/60-openocd.rules /etc/udev/rules.d/

Die Datei /lib/udev/rules.d/60-openocd.rules ist nur vorhanden, wenn man das Linux Paket openocd installiert hat. Wenn man OpenOCD manuell installiert, dann muss man den Pfad ändern, ähnlich wie in folgendem Beispiel: /opt/openocd-0.12.0/share/openocd/contrib/60-openocd.rules.

Damit die Regeln aktiviert werden, gibt man abschliessend die Kommandos ein:

$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

5 Estool installieren

Das estool Program ist ein Hilfsprogramm, um die Arbeit mit dem STM32 etwas zu erleichtern. Der Python Quelltext liegt auf gitlab (VPN nötig):

https://gitlab.informatik.hs-augsburg.de/hhoegl/estool

  1. Python Installation testen

    Mit which kann man den Pfad ausgeben, an dem das Programm gefunden wird.

    $ which python
/usr/bin/python

    Es kann auch vorkommen, dass der Interpreter python3 heisst.

    Man sollte auch mal den Interpreter starten, damit man die Version sieht:

    $ python
Python 3.10.9 | packaged by conda-forge | (main, Feb  2 2023, 20:20:04) [GCC 11.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

    Mit Strg-D beendet man den >>> Eingabeprompt.

    Wer mit einer eigenen, von der systemweiten Python Installation unabhängig arbeiten will, der installiert Miniforge:

    https://github.com/conda-forge/miniforge/releases/

    Die aktuelle Release (10/2023) für Linux ist Miniforge3-23.3.1-1-Linux-x86_64.sh. Die Installation erfolgt mit

    $ cd ~
$ bash Miniforge3-23.3.1-1-Linux-x86_64.sh

    Wenn die Installation beendet ist, gibt es im Home Verzeichnis den Ordner miniforge3, der aktive Python Interpreter ist dann

    $ which python
$ /home/<user>/miniforge3/bin/python

  2. Virtuelle Python Umgebung erzeugen

    cd ~
python -m venv es2_pyvenv
source es2_pyvenv/bin/activate

    Das Kommando which python sollte den Pfad /home/<user>/es2_pyvenv/bin/python ausgeben.

    Mit deactivate kann man die virtuelle Python Umgebung wieder deaktivieren.

  3. Estool in die virtuelle Umgebung installieren (venv muss voher aktiviert werden). Damit man mit dem angegebenen ssh URL klonen kann, muss ein öffentlicher ssh Schlüssel auf gitlab übertragen werden. Wie das geht steht unter “Allgemeine Tipps” weiter unten.

    $ git clone ssh://git@gitlab.informatik.hs-augsburg.de:2222/hhoegl/estool.git
$ cd estool
$ python -m pip install .      # Alternativ: python -m pip install --upgrade .

    Mit der --check Option kann man prüfen, ob alle Werkzeuge richtig installiert wurden:

    $ estool --check

    Hinweis: Damit --check klappt muss man in einem Projektordner sein, also wie im nächsten Kapitel beschrieben z.B. “starter” holen und in das Verzeichnis gehen.

    Estool erhält seine Einstellungen in jedem Projektordner durch eine Konfigurationsdatei .estool/estool.ini, also z.B. starter/.estool/estool.ini.

6 Beispiel “starter” für STM32 Nucleo holen, kompilieren und flashen

Es gibt zwei Varianten, eine für Nucleo-F446 und eine für Nucleo-L476:

Im weiteren ist die Variante Nucleo-F446 gezeigt:

$ git clone ssh://git@gitlab.informatik.hs-augsburg.de:2222/es2/es2-nucf446/starter.git
$ cd starter 
$ ls -a
.  ..  .estool  .git  .gitignore  img  Makefile  README.md  src STM32F446RETx_FLASH.ld

Im Beispielverzeichnis starter ist nun die Konfigurationsdatei vom OpenOCD Server im Verzeichnis .estool enthalten. Das Verzeichnis beginnt mit einem Punkt (“.”), deshalb sieht man es nicht in der Ausgabe des ls Programms. Damit man es sieht, muss man ls -a angeben. Wir starten den OpenOCD Server probeweise mit

$ openocd -f .estool/openocd.cfg 
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
debug_level: 1
adapter speed: 500 kHz
adapter_nsrst_delay: 100
none separate
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
<hier hängt das Programm; abbrechen mit Strg-c>

Man bricht den im Vordergrund laufenden OpenOCD mit Strg-c (Steuerung-C, auf englisch control-c) ab. Damit OpenOCD erfolgreich starten kann, muss er mit dem Debug-Adapter STLINK Verbindung aufnehmen können. Als gewöhnlicher User kann man das nur mit der installierten udev Datei (siehe oben).

Nun kompilieren und flashen:

$ cd starter
$ make          
$ make flash

Bei make wird der Quelltext mit dem zuvor installierten ARM GCC Compiler kompiliert. Mit make flash wird der STM32 mit dem Programm geflasht. Das make flash Kommando startet in Hintergrund das estool, das wiederum den OpenOCD zum Flashen des STM32 startet und danach wieder beendet.

Danach sollte das über USB angesteckte Nucleo Board geflasht worden sein und die LED auf dem Board blinken. Über den UART, der auch über den STLINK Adapter verfügbar ist, werden die Schleifendurchläufe in ASCII mit 9600 Baud an den PC übertragen. Die Details stehen in der README.md Datei im starter Verzeichnis, und natürlich im Quelltext starter/src/.

Man kann ausserdem mit make gdb den GNU Debugger starten. Dazu muss allerdings der OpenOCD Server bereits im Hintergrund laufen. Diese Arbeit nimmt einem das estool ab mit estool --start-oocd. Nach getaner Debug Arbeit kann man OpenOCD wieder beenden mit estool --stop-oocd. Mit --ask-oocd kann man nachschauen, ob der OpenOCD Server läuft.

7 Allgemeine Tipps