STM32F4 Discovery mit OpenSource Toolchain programmieren und debuggen

ACHTUNG: Dieser Beitrag ist mittlerweile veraltet

[2015-12-07] Lieber Entwickelnde,

das Rad der Zeit dreht sich weiter. Mittlerweile ist es nicht mehr erforderlich, sich seine Toolchain "so umständlich" zusammenzubauen, wie hier beschrieben. "ac6" bietet auf http://www.openstm32.org/HomePage eine auch von ST empfohlene freie Toolchain an, die letztlich die gleichen Komponenten einsetzt. Die Dinge sich jedoch fertig vorkonfiguriert und der Start geht einfach und schnell, übrigens auch für die F1-Serie. Aktuell entwickele ich sehr gerne damit!

HTH und happy Coding!

Liebe Entwicklerin, lieber Entwickler,

im Folgenden möchte ich Dir die Installation und Grundkonfiguration einer freien Toolchain für die STM32F4-Prozessorfamilie beschreiben. Diese „Kette der Werkzeuge“ versetzt Dich kostenlos in die Lage, Software mit hohem Komfort zu schreiben, zu compilieren, zu linken, auf den Prozessor zu übertragen, dort zur Ausführung zu bringen und zu debuggen. Dieses Tutorial setzt einen Windows-PC (in meinem Fall Windows 7, 64bit) und natürlich zum Ausprobieren ein Entwicklungsboard mit einem STM32F4 voraus. Ich liebe und empfehle das STM32F4-Discovery für etwa 15Euro bei diversen Online-Händlern. Du brauchst etwa 1 Stunde, um die klassische blinkende Leuchtdiode zu bekommen. Die Toolchain funktioniert mit geringfügigen Änderungen auch mit anderen Mitgliedern der STM32-Familie.
Im Mikrocontroller.net-Forum gibt es unter http://www.mikrocontroller.net/topic/333056 einen Thread zu diesem Tutorial.
Tatsächlich passen alle Komponenten ziemlich gut zusammen und so sind glücklicherweise nur kleinere Konfigurationseinstellungen erforderlich. Störend ist an sich nur, dass die STM32CubeMX-Software keine Projekttemplates für Eclipse CDT erzeugen kann. Die manuelle Nacharbeit ist jedoch in wenigen Minuten erledigt und muss bei geschickter Nutzung von Systemvariablen nur einmalig durchgeführt werden. Ich selbst bin von der Lösung wirklich sehr angetan und freue mich über höchsten Komfort, der teilweise über die Unterstützung kommerzieller Lösungen weit hinausgeht.
Die weiteren Schritte teilen sich in die folgenden Bereiche auf:

1. Verzeichnisse erstellen
2. Basis-Softwarepakete herunterladen und installieren
3. Eclipse-Plugins installieren
4. Eclipse und Eclipse-Plugins konfigurieren
5. (wiederverwendbares) Template-Projekt erzeugen
6. Testprogramm erstellen, compilieren und zur Ausführung bringen

Nun aber Schritt für Schritt:

Nutzungsvereinbarung
Ich stelle an die Nutzung dieses Tutorials eine einzige Bitte: Sollte es beim Durcharbeiten irgendwelche Probleme geben, dass bitte ich Dich, mir dies zurückzumelden. Selbst wenn der Fehler bei Dir lag, ist der Hinweis wertvoll. So kann ich dieses Tutorial an entsprechender Stelle schärfen.

Verzeichnisse erstellen

Auch im Jahre 2014 ist es für bestimmte Software immer noch problematisch, wenn Installations- oder Datenverzeichnisse mehr als 8 Zeichen lang sind und/oder sich ein Leerzeichen darunter befindet. Ich lege Euch deshalb nahe, auf entsprechende Experimente zu verzichten. Ich installiere die Toolchain im Verzeichnis c:\stm32tc („ToolChain“) und habe die Projekte im Verzeichnis c:\stm32ws („WorkSpace“).

Basis-Softwarepakete herunterladen und installieren

Nun musst Du Deine DSL-Leitung zum Glühen bringen und mehrere Programme laden:

Java JDK in der aktuellen 1.8er-Version

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Funktion: Laufzeitbasis für Eclipse und das STM32CubeMX-Tool.

Installation: Gewöhnliche Installation in beliebiges Verzeichnis.

ACHTUNG: Benutzer melden kurz nach Schreiben dieses Beitrags Probleme im Zusammenhang zwischen dem STM32CubeMX und Java in der Version 1.8. Aus diesem Grund empfehle ich die Installation der neuesten 1.7er-Version. Die Probleme mit Java 1.8 scheinen aber nur in bestimmten Situationen zu bestehen. Bei mir (Win 8.1, 64 bit, CubeMX nicht als Eclipse-Plugin, sondern als separates Tool) gibt es keine Probleme...

Eclipse IDE for C/C++ Developers

http://www.eclipse.org/downloads/

Funktion: Integrierte Entwicklungsumgebung, funktionale Klammer über (fast) alle Tools

Installation: ZIP-Datei entpacken direkt im stm32tc-Verzeichnis. Die eclipse.exe befindet sich also direkt im c:\stm32tc

GNU Tools for ARM Embedded Processors

https://launchpad.net/gcc-arm-embedded/+download , bitte die neueste gcc-arm-none-eabi-xxxxxxxxx-win32.zip herunterladen

Funktion: Compiler, Assembler und Linker für ARM-Prozessoren.

Installation: ZIP-Datei entpacken in einem stm32tc-Unterverzeichnis, z.B. stm32tc\gcc48

Make

http://gnuwin32.sourceforge.net/packages/make.htm , Bitte „Complete package, except sources“ herunterladen.

Funktion: Hilfswerkzeug für die Softwareentwicklung; wird von Eclipse (und jedem guten C/C++-Programmierer) für die bedarfsgerechte Steuerung der GNU-Tools benötigt.

Installation: Installation in C:\stm32tc\GnuWin32. Ein Startmenüeintrag ist nicht erforderlich, auch ein Eintrag in die PATH-Systemvariable ist nicht erforderlich.

Coreutils

http://gnuwin32.sourceforge.net/packages/coreutils.htm , Bitte „Complete package, except sources“ herunterladen.

Funktion: Hilfswerkzeug für die Softwareentwicklung; wird von Eclipse (und jedem guten C/C++-Programmierer) für die bedarfsgerechte Steuerung der GNU-Tools benötigt.

Installation: Installation in C:\stm32tc\GnuWin32. Ein Startmenüeintrag ist nicht erforderlich, auch ein Eintrag in die PATH-Systemvariable ist nicht erforderlich.

STM32 ST-LINK utility

http://www.st.com/web/en/catalog/tools/PF258168 (Vorsicht: Links ändern sich auf der ST-Homepage häufig. Bei Problemen einfach Google nach „STM32 ST-LINK utility“ fragen.)

Funktion: Eine nützliche Software zum Flashen und Löschen des STM32. Und (fast noch wichtiger): Der USB-Treiber für den Programmer/Debugger auf dem Discovery-Board wird hiermit sehr komfortabel installiert.

Installation: Installation in c:\stm32tc\stlink.

STM32CubeMX for STM32 configuration and initialization C code

http://www.st.com/web/en/catalog/tools/PF257931 (Vorsicht: Links ändern sich auf der ST-Homepage häufig. Bei Problemen einfach Google fragen.

Funktion: Eine sehr aufwändige und vor allem fehleranfällige Tätigkeit bei der Entwicklung Mikrocontrollern ist die initiale Konfiguration aller Peripheriebausteiene. Das CubeMX-Plugin unterstützt Dich dabei, indem es eine grafische Konfiguration aller Peripherieelemente ermöglicht und ein Projektgrundgerüst erstellt. Es handelt sich hierbei um ein Eclipse-Plugin. Tatsächlich ist es mittlerweile m.E.fast sinnvoller, auf die Stand-Alone-Version zurück zu greifen. Diese vergeudet nicht so viel wertvollen Platz im Arbeitsbereich mit den zur Plugin-Benutzungszeit unnötigen Eclipse-Symbolleisten.

Installation: Es handelt sich hierbei um ein Eclipse-Plugin. Dieses wird innerhalb von Eclipse installiert.

OpenOCD

http://openocd.sourceforge.net/ und dort dem Link auf die compilierte Windows-Version auf http://www.freddiechopin.info/en/download/category/4-openocd folgen

Funktion: Software zum Flashen und Debuggen des STM32 (und vielen weiteren Prozessorfamilien)

Installation: 7Z-Datei (Entpacker unter http://www.7-zip.org/) entpacken in einem stm32tc-Unterverzeichnis, z.B. stm32tc\openocd8

(Partielle) Erfolgskontrolle

Nach der Installation sollte der c:\stm32tc-Ordner wie folgt aussehen:

Inhalte des Toolchain-Ordners

Nach der Installation kann auch das Discovery-Board in die USB-Buchse gesteckt werden und die Windows-Hardwareerkennung sollte automatisiert die Treiber finden und einrichten. Ich empfehle, dann direkt mit Hilfe des Tools den Flash-Speicher des STM32 auszulesen. So lässt sich einfach prüfen, ob die Kommunikation funktioniert.

Eclipse-Plugins installieren

• Eclipse starten
• Workspace-Verzeichnis angeben: c:\stm32ws (siehe Abbildung)
• „Welcome“Bildschirm schließen durch Klick auf Symbol -->Go to Workbench (siehe Abbildung)
• -->Help -->Install new software
• Zu unterscheiden ist nun zwischen dem bereits in Dateiform heruntergeladenen Plugin "STM32CubeMX" und jenen Plugins, die innerhalb von Eclipse herunter geladen werden (siehe Abbildungen). Zunächst gehe ich auf die Letzteren ein:
• Gnuarmeclipse: Plugin für die C/C++Entwicklung spezifisch für ARM-Prozessoren, schafft insbesondere die Verbindung zwischen dem Eclipse-Debugging-Framework und dem OpenOCD-Debugger.
• Work With = http://gnuarmeclipse.sourceforge.net/updates
• >>RETURN<<
• …warten…
• Häkchen setzen
• Durchbestätigen und akzeptieren
• Embsysview: Unerlässlich für Debugging; zeigt Inhalte von Prozessorregistern lesbar formatiert und mit Bezeichnungen an
• Work With= http://embsysregview.sourceforge.net/update
• >>RETURN<<
• …warten…
• Häkchen setzen
• Durchbestätigen und akzeptieren
• Nun zu dem bereits als Datei herunter geladenen STM32CubeMX
• -->Help -->Install new Software -->Add -->Archive -->Zip-Datei vom STM32CubeMX-Plugin auswählen.
• Durchbestätigen

Das GNUARMEclipse bietet eine Reihe weiterer Möglichkeiten. Insbesondere bietet es viele Projekttemplates basierend auf älteren CMSIS-Implementierungen. Zielsetzung meiner Anstrengungen war es jedoch, eine Toochain unter Nutzung des STM32CubeMX-Werkzeugs samt der eng damit verbundenen neuen CMSIS-Implementierung aufzubauen. Vom GNUARMEclipse werden wir Grund genommen nur die „Ansteuerfunktion“ für OpenOCD verwenden. Ein großer Teil der Funktionalität von Gnuarmeclipse liegt deshalb brach, aber das soll an dieser Stelle nicht weiter stören.

Workspace anlegen

Symbol anklicken, um den "Welcome"-Bildschirm zu schließen

Installation eines Plugins, das durch Eclipse heruntergeladen wird

Installation eines Plugins, das bereits in Dateiform auf der Festplatte vorliegt (hier: das STM32CubeMX-Plugin)

Eclipse und Eclipse-Plugins konfigurieren

• In Eclipse: -->Window -->Show View -->Other -->Other -->STM32CubeMX
• Die STM32CubeMX-Oberfläche wird unten angezeigt. Bitte die Ansicht möglichst vergrößern.
• In der STM32CubeMX-Oberfläche: -->Help -->Updater Settings --> Verzeichnis auf c:\stm32ws\CubeRepo (“Cube Repository”) einstellen -->ok
• Anmerkung: Natürlich kann das „Repository“ auch in das Standardverzeichnis installiert werden. Das Repository enthält jedoch interessanten Beispielcode und ich finde es nüztlich, den „in der Nähe“ zu haben.
• In der STM32CubeMX-Oberfläche: -->Help -->Install new Libraries --> Neuestes Firmware Package für F4 auswählen -->OK
• Dies lädt die wirklich äußerst nützliche CMSIS-Implementierung, wiederverwendbare Softwaremodule und jede Menge Beispiele in das zuvor konfigurierte Verzeichnis. Der Code ist die Basis für alle Projekte mit dem STM32F4.
• In Eclipse -->Windows -->Preferences -->Build -->Environment: Bitte der Variable >>PATH<< den Wert c:\stm32tc\GnuWin32 hinzufügen. So kann Eclipse das Tool „make“ und „make“ wiederum die Tools „rm“ und „echo“ finden.

Variable PATH innerhalb von Eclipse erweitern

Template-Projekt erzeugen [WiP]

CubeMX-Projekt erstellen

• In Eclipse: -->Window -->Show View -->Other -->Other -->STM32CubeMX
• In der STM32CubeMX-Oberfläche: -->New Project -->Board Selector -->STM32F4 Discovery

• Glücklicherweise sind damit schon alle notwendigen Einstellungen aller Pins und Peripheriekomponenten und insbesondere auch das Clock-System passend eingestellt. Sicherlich ist es interessant, sich durch die Einstellmöglichkeiten des Tools durchzuklicken. Bitte verändere aber bei diesem ersten Versuch nichts.
• -->Project -->Generate Code
• In diesem Fenster eingeben:
• Project Name: beliebig, aber bitte merken, den brauchen wir gleich nochmal (im Beispiel kl_tut_01)
• Project Location: c:\stm32ws (also genau das Eclipse-Workspace-Verzeichnis)
• Toolchain/IDE: TrueSTUDIO x.y.z auswählen.




• Zu der Auswahl der Toolchain muss ich noch eine Bemerkung loswerden: Das TrueSTUDIO ist unserer Toolchain relativ ähnlich. Zumindest ist die Ähnlichkeit so groß, dass das für TrueSTUDIO generierte Linkerscript von unserer Toolchain direkt übernommen werden könnte. "Könnte" deshalb, weil gemäß der Lizenzbedingung der Linker-Datei diese Datei nur zusammen mit dem TrueSTUDIO benutzt werden darf. Die folgenden Schritte führen deshalb möglicherweise zu Lizenzverletzungen. Seltsam ist das deshalb, weil die gesamte STM32Cube firmware (zu der auch das Linker-Script gehört) unter der sehr freien BSD-Lizenz steht. Tja...
• Nach einem Klick auf >>OK<< sollte der Vorgang einige Sekunden dauern und dann mit der folgenden Meldung abgeschlossen sein. Schließe diesen Dialog mit >>Close<<.



Code erfolgreich erzeugt






Eclipse-Projekt erstellen

Nun kommt der wesentliche Trick: Mit Eclipse musst Du genau in dem eben erstellten Projektverzeichnis ein Eclipse C-Projekt erstellen. Die Projektmetadaten des TrueSTUDIO interessieren Eclipse überhaupt nicht. Wir nutzen lediglich die generierten c- und h-Dateien sowie das Linker-Script.



• In Eclipse: -->File -->New -->C Project 
• Dialog „C Project“






• Project Name = der "gemerkte" Projektname des STM32CubeMX, also im Beispiel "kl_tut_01". 
• Anm: Eclipse blendet die Warnung ein, dass „Directory with specified name already exists“. Genau so soll es sein!
• Project Type= Executable --> Empty Project (bitte hier nicht der Verführung erliegen, direkt ein passender erscheinendes STM32F4-Projekt auszuwählen!)
• Toolchains = Cross ARM GCC
• -->NEXT
• Dialog “C Project, Select Configuration”
• Sowohl “Debug” als auch “Release” anhaken (Standardeinstellung)
• -->NEXT
• Dialog “C Project, Cross GNU ARM Toolchain”
• Toolchain name = GNU Tools for ARM Embedded Processors (arm-none-eabi-gcc)
• Toolchain Path: bin-Verzeichnis unterhalb des GCC-Installationsverzeichnisses, muss nur beim ersten Mal angegeben werden. Wenn Du Dich an meine Empfehlungen gehalten hast, ist das c:\stm32tc\gcc48\bin [TODO: Hier mit relativem Pfad zum Eclipse-Installationsverzeichnis arbeiten?]
• -->FINISH



Includes definieren

Nun kommt eine etwas leidige Frickelarbeit, die aber nur ein einziges Mal erforderlich ist
Der Eclipse-Indexer und insbesondere der Compiler müssen über den Speicherort alle relevanten Header-Files informiert werden.
Hierbei war mir es besonders wichtig, dass ein einmal eingerichtetes Template-Projekt beliebig in ein weiteres Verzeichnis im Workspace-Ordner kopiert werden kann und die Templates immer noch gefunden werden. Um zusätzlich eine wiederholte automatische Codeerzeugung von CubeMX zu ermöglichen und weder den Eclipse-Indexer zu verwirren, noch dem Compiler wichtige Header-Datei vorzuenthalten, hat sich die folgende Vorgehensweise bei mir bewährt.


• -->Properties im Projekt-Kontextmenü, -->C/C++ General, -->Path and Symbols -->Includes
• Füge  mit „ADD…“ die folgenden Verzeichnisse hinzu. Wähle dabei stets  „Add to all configurations“ und  „Add to all languages“ aus, um die Includes für Debug und Release und C-Code und Assembler-Code zu definieren. 
• Alle Include-Verzeichnisse, die STMCubeMX automatisch in den Projekt-Folder schreibt, werden mit Hilfe der Variable ${ProjDirPath} definiert. Dazu gehören im Beispielprojekt
• ${ProjDirPath}/Drivers/CMSIS/Device/ST/STM32F4xx/Include
• ${ProjDirPath}/Drivers/CMSIS/Include
• ${ProjDirPath}/Drivers/STM32F4xx_HAL_Driver/Inc
• ${ProjDirPath}/Inc
• Für das teilautomatisierte Einbinden dieser Includesgibt es im Microcontroller-Forum (Link s.o.) eine XML-Datei.

• Weitere eigene Quellcodebibliotheken, bei mir beispielsweise Code zur Ansteuerung von Sensoren, halte ich ich in einem “repository”-Verzeichnis im c:\stm32ws. Deren Include-Verzeichnisse referenziere ich mit Hilfe der Variable ${workspace_loc}, z.B. "${workspace_loc}/repository/enc28j60/Inc." Derartige eigene Bibliotheken nutzen wir in diesem Tutorial aber nicht.
• Alle unnötigen Header-Files im Verzeichnis Drivers\CMSIS\Device\ST\STM32F4xx\Include müssen vom Build ausgeschlossen werden, weil der Indexer sonst wegen der Mehrfachdefinitionen durcheinander kommt. Unnötig sind all jene Dateien, die sich nicht auf  "unseren" 407-Prozessor beziehen  (-->Properties aus Kontextmenü der Datei, -->C/C++ Build, Configuation = [All Configuration, „Exclude resource from build“ anhaken, >>OK<<).

Ausschluss unnötiger Header-Dateien

Nach dem Ausschluss (bitte nicht von den blauen Fragezeichen verwirren lassen, die blendet mein Versionskontrollsystem ein)

Symbole definieren

Gleich "nebenan" bei "Symbols" ( -->Properties im Projekt-Kontextmenü, -->C/C++ General, -->Path and Symbols -->Symbols musst Du nun zwei Symbole definieren. Symbole sind einfach nur Konstanten, die entweder einen konkreten Wert haben oder eben einfach nur als "vorhanden" definiert werden können
Füge also mit „ADD…“ die folgenden Symbole und Werte hinzu. Wähle dabei erneut stets  „Add to all configurations“ und  „Add to all languages“ aus, um die Werte für Debug und Release sowie Assembly und GNU C in allen vier Kombinationsmöglichkeiten hinzuzufügen.

• Name="USE_HAL_DRIVER", Value leer lassen
• Name= "STM32F407xx", Value leer lassen

Datei umbenennen

Ändere bitte den von Drivers/CMSIS/Device/ST/STM32F4xx/Source/Templates/gcc/startup_stm32f407xx.s in startup_stm32f407xx.asm. Damit wird diese als einzige der vielen Startup-Dateien vom Assembler auch tatsächlich berücksichtigt. „.s“-Dateien verarbeitet der GCC nämlich überhaupt nicht.

Toolchain konfigurieren

• -->Properties im Projekt-Kontextmenü, -->C/C++ Build, -->Settings -->Target Processor; bitte wie folgt anpassen

• ...und auch das weiter oben angesprochene Linker-File einbinden. Achtung: Dieses befindet sich in einem Unterverzeichnis, in dem der Projektname nochmals vorkommt. Um hier komplexe Pfadkonstruktionen mit Variablen zu vermeiden, füge ich dieses Linker-Script immer über seinen absoluten neu hinzu, wenn ich das Projekt umbennene oder kopiere. Das Hinzufügen eines Pfades funktioniert über das im Screenshot hervorgehobene "+"-Icon.

Linker-Scriptfile

Das Hello-World des STM32

Der große Moment rückt näher. Öffne nun die main.c-Datei und füge dort in der vorbereiteten "while(1)"-Endlosschleife den folgenden Code ein:

HAL_GPIO_TogglePin(GPIOD, GPIO_PIN_13); //GPIOD, und nicht B, wie im Screenshot!
HAL_Delay(400);

Dieser Fehler ist behoben (Stand 3.12.2014): Ein Fehler ist den CubeMX-Entwicklern bei der Definition wohl doch unterlaufen. Suche weiter unten diesen Codeabschnitt

/*Configure GPIO pins : PD12 PD13 PD14 PD15
PD4 */
GPIO_InitStruct.Pin = GPIO_PIN_12|GPIO_PIN_13|GPIO_PIN_14|GPIO_PIN_15
|GPIO_PIN_4;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_LOW;
HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);

...und füge vor der "Pull"-Zeile noch diese Zeile ein:

GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;

Klicke dann auf das "Hammer-Symbol" und nach einigen Sekunden sollte die Console ein erfolgreiches Build anzeigen.

Erfolgreicher Build-Vorgang

Stecke spätestens jetzt das STM32F4-Discovery in den USB-Port.

• -->Run -->Debug Configurations -->GDB OpenOCD Debugging -->New; in den Tab "Debugger" wechseln
• Im Textfeld "Executable" den OpenOCD-Programmdatei auswählen
• Im Textfeld „Other Options“ den Namen des Boards definieren, also „-f board/stm32f4discovery.cfg“.  Alle hier verfügbaren Scripte liegen übrigens im Unterverzeichnis „scripts“ des openocd-Installationsverzeichnisses.

• Auf >>Debug<< klicken; kurz warten, den "Confirm Perspective Switch" bejahen und sobald der Breakpoint am Anfang von Main steht, auf das "Weiter"-Symbol klicken.

Ich hoffe, Dir geht jetzt ein Licht auf, zumindest alle 800 Millisekunden für 400 Millisekunden:-)
Viel Spaß beim Nachahmen und Kommentieren!

FAQ

Probleme beim Compilieren können vielfältige Ursachen haben. Bitte prüfe das folgende:</

• Hast Du das richtige Linker-Script ausgewählt
• Hast Du die richtigen Dateien aus dem Projekt excludiert und die richtigen drin gelassen?
• Hast Du die beiden oben beschriebenen Symbole definiert
• Hast Du die include-Verzeichnisse richtig angegeben?