📗 ESPuino in Platformio anlegen und mit git aktuell halten

[biologist]

Du hast Visual Studio Code zusammen mit Platformio als Plugin gemäß dieser Anleitung installiert und fragst dich nun, wie du ESPuino als Projekt dort reinbekommst? Und du fragst dich auch, wie du es mit wenig Aufwand aktuell hältst? Dann bist du hier richtig!

So in der Art sollte es am Ende aussehen:

Code runterladen

Grundsätzlich ist ESPuino bereits ein Platformio-Projekt, was für dich den Vorteil hat, dass du es nur runterladen musst und als Projekt öffnen. Dafür gibt es zwei unterschiedliche Wege:

Variante 1: git

1. Ggf. musst du zuerst Git runterladen.
2. Lade dir in Visual Studio Code auch gleich „Gitlens“ als Plugin herunter. Dafür musst du links auf das Symbol mit den vier Quadraten wechseln und in die Suche „Gitlens“ eingeben + das Plugin installieren.

3. Drücke STRG + SHIFT + P. Es öffnet sich oben in der Mitte ein Fenster. Hier wählst du „Git: Clone“ aus. Es öffnet sich ein neues Fenster, in dem du gebeten wirst, die URL einzutragen. Hier fügst du https://github.com/biologist79/ESPuino ein.
4. Nun öffnet sich ein Fenster, in dem du gebeten wirst, einen Ort anzugeben/auszuwählen, wohin das ESPuino-Projekt gespeichert werden soll. Wenn das erledigt ist, so wirst du gefragt, ob du das frisch runtergeladene Repository öffnen willst. Das bestätigst du. Du befindest dich nun im frisch geclonten ESPuino-Projekt:

Hier wird nun einiges runtergeladen und konfiguriert. Das kann mitunter ein paar Minuten dauern!

Variante 2: Zip-File

1. Besuche mein GitHub-Respository (https://github.com/biologist79/ESPuino) und lade ESPuino herunter:

2. Entpacke es in deinem Dateisystem und merke dir den Ort.
3. Über das Pulldown-Menü „Datei“ von Visual Studio Code öffnest du jetzt den Ordner.
   Klicke nun auf „Open“ in der Spalte daneben.

Konfigurationen vornehmen

Nachdem das Projekt nun geöffnet ist, wirst du nun deine Konfiguration vornehmen wollen.

1. Wähle zuerst das passende Environment aus. Welches auszuwählen ist, hängt von deinem verwendeten Develboard ab. Auswählen kannst du es, indem du am unteren Bildschirmrand „env:…“ suchst und das passende Profil auswählst. Im nachfolgenden Bildbeispiel ist „env:lolin_d32_pro_sdmmc_pe“ ausgewählt:
   

   

2. Passe nun deine Konfiguration an. Im Normalfall ist dies settings.h und die Konfigurationsdatei, die zu deinem gewählten Environment passt. Im Falle von „env:lolin_d32_pro_sdmmc_pe“ wäre dies settings-lolin_d32_pro_sdmmc_pe.h, welches sich im Unterordner „src“ befindet. Du erreichst diese links über den Dateibrowser. Speichere die Änderungen mit STRG+S ab.

3. Wenn du mit der Konfiguration fertig bist, kann die Firmware kompiliert und auf dem ESP32 hochgeladen werden. Dafür klickst du links auf den Alienkopf und im Anschluss auf „Upload and Monitor“.

Die Firmware wird nun kompiliert; dies kann mehrere Minuten in Anspruch nehmen. Im Anschluss wird sie, wenn alles klappt, auf den ESP32 geflasht. Das alles kannst du unten im großen Fenster beobachten.

4. In der seriellen Konsole (ebenfalls unten), kannst du nun schauen, wie der ESP32 reagiert. Du kannst diese, wenn der ESP32 angeschlossen ist, auch jederzeit über „Monitor“ wieder aufrufen.

ESPuino aktuell halten

Der größte Vorteil der oben beschriebenen Git-Variante ist, dass man den Quellcode aktualisieren kann, ohne jedes Mal das ganze Repository runterladen zu müssen. Du musst dafür lediglich unten links in Visual Studio Code auf die Pfeile klicken, die im Kreis angeordnet sind:

Du wirst dann gefragt, ob du die Aktualisierung wirklich durchführen willst. Das bestätigst du. Und schon wird der Code mit meinem GitHub-Repository synchronisiert. Hinweis: Klickst du auf master, so kannst du auch in einen anderen Branch wechseln:

Mögliche Probleme durch Arbeiten mit git

Mögliche Probleme beim Aktualisieren kann es zahlreiche geben; ich picke mir hier ein paar wenige heraus. Solltest du dich unsicher fühlen: Es gibt im Internet zahlreiche Tutorials zu git, die du dir durchlesen/anschauen kannst.
Problem 1) Du hast z.B. Settings-Dateien angepasst und nicht per Commit im Repository gepeichert. Git verweigert das Aktualisieren (pull), weil es lokale die Änderungen überschreiben würde. Hier musst du vor dem pull deine Änderungen entweder rückgängig machen oder mit Stash arbeiten. Bei einem Stash würdest du deine Änderungen ohne Commit zwischenspeichern und nach dem Aktualisieren wieder zurückspielen. Möchtest du einen solchen Stash durchführen (lies den Absatz besser zu Ende, bevor du dies tust), dann klickst du unter Changes auf das linke Symbol mit dem Pfeil zurück + Plus „Stash all Changes“.

Es öffnet sich dann am oberen Bildschirmrand ein Fenster, in dem du aufgefordert wirst, dem Stash einen Namen zu geben:

Ich nenne ihn hier einfach exemplarisch „meine Config“. Das bestätige ich dann. Im Anschluss ist die Änderungsliste leer, dafür taucht dann links unten unter Stashes dieser Stash auf:

Klickst du in diesem Stash auf das Symbol mit dem Pfeil nach oben (Apply Stash),

so öffnet sich oben ein Fenster, in dem du gefragt wirst, was genau du tun willst:

Mit Apply Stash kannst du den Zustand herstellen, den du zuvor hattest. Mit „Pop Stash“ wird zusätzlich ein Commit durchgeführt.

Das Stashen kann sehr praktisch sein, jedoch auch ggf. zu „Problemen“ führen, wenn sich bei der Aktualisierung ausgerechnet in solchen Dateien Änderungen finden, die du auch geändert hast. Denn in diesem Falle müssen die Änderungen zusammengeführt werden.
Für die meisten Leute wird’s daher vermutlich einfacher sein, die Änderungen rückgängig zu machen und im Anschluss, nach dem Aktualisieren, neu zu setzen. Änderungen rückgängig machen ist relativ einfach: Zuerst mal siehst du auf der linken Seite, dass du z.B. zwei Dateien editiert hast:

Nun willst du vielleicht wissen, welche Änderungen zu eigentlich gemacht hast. Nichts leichter als das: Du klickst die Dateien einfach nacheinander an und siehst dann eine Anzeige, in der die Unterschiede dargestellt werden:

Nun gehst du mit dem Mauspfeil über das Zurücksymbol, welches direkt links neben dem Plus bei Changes zu finden ist. Dort sollte etwas angezeigt werden wie „Discard All Changes“. Das führst du aus.

Im Anschluss ist die Liste dann wieder leer:

Nun kannst du das Repository aktualisieren:

Und dann deine zuvor gelöschten Änderungen

Problem 2) Du hast zwar deine Änderungen im Repository per Commit abgespeichert (unter Punkt 1 hatte ich Änderungen beschrieben, bei denen kein Commit erfolgt war), jedoch treffen deine Änderungen einen Bereich, in dem durch die Aktualisierung auch weitere Änderungen reinkommen. Git ist bestrebt, das Ganze möglichst automatisch zusammenzuführen „mergen“, wird dir jedoch ggf. sagen, dass ein automatisches Merge nicht möglich war und du (punktuell) selbst entscheiden musst, was jetzt übernommen werden soll. Das finale Ergebnis wird man, nachdem man es getestet hat, dann üblicherweise per Commit ins lokale Repository überführen wollen.

Ein paar Sätze zum Arbeiten mit git:
Wichtig zu verstehen ist: Wenn du Änderungen gemacht hast und diese in deinem lokalen Repository nicht gespeichert hast (commit), dann gelten diese als temporär und ein git checkout würde diese normalerweise überschreiben. Tut es jedoch nicht, sondern wirft dir einen Fehler, dass du deine Änderungen zuerst comitten (oder stashen) sollst, bevor du den Befehl ausführen darfst.

Klingt total kompliziert und ist es vielleicht auch, aber du kannst in Visual Studio Code auch schön sehen, welche Dateien du verändert hast:

Im Bild siehst du die Zahl 13, welche besagt, dass ich in verschiedenen Projekten, an insgesamt 13 Dateien Änderungen gemacht habe. Unter Änderungen sieht man nun welche Dateien ich im Projekt ESPuino verändert habe (M steht für modified; auch neue Dateien etc pp werden hier aufgeführt). Man kann so eine Datei einfach anklicken und kriegt dann eine sehr schöne Gegenüberstellung angezeigt:

Im Bild sieht man, dass ich die main.cpp markiert habe. Klicke ich auf diesen gebogenen Pfeil zurück, so mache ich alle Änderungen an der Datei sofort rückgängig. Es ist dann wieder die Version aktiv, die im Repository als letzter Stand gespeichert wurde. Klicke ich auf +, so überführe ich diese Datei ins „Staging“. Was ist das nun wieder? Beispiel: Ich (@biologist) habe lokal ein Feature programmiert, das Änderungen an 11 Dateien mit sich bringt. Ich musste für meine lokalen Tests aber auch die settings.h anpassen, weil das für meine Testhardware notwendig war. Die Änderungen der settings.h sollen jedoch nicht ins Repository, da dies gewisse Voreinstellungen überschreiben würde. Daher überführe ich nur solche Dateien ins Staging, die auch im Repository landen sollen.

Hier sieht man nun, dass ich drei Dateien ins Staging überführt habe. Hinweis: Änderst du an einer gestageten Datei nachträglich nochmal was, so landen diese Änderungen nicht mehr im Staging. Du musst die Dateien durch Klicken auf „-“ wieder aus dem Staging rausholen und wieder neu reinnehmen, damit die Änderungen aktiv werden.

Ist man nun soweit, dass man alle Änderungen beisammen hat, alle zugehörigen Dateien im Staging sind und nun in einem Commit landen sollen, so trägt man eine Commit-Nachricht ein, was ich im Bild mal exemplarisch getan habe. Man drückt dann „Shift+Enter“ und deine Änderungen sind im Repository abgelegt. Keine Angst: Sie landen dadurch nicht automatisch bei GitHub oder sonstwo. Sie sind wirklich nur bei dir lokal.

Fazit: Mit git lässt sich komfortabel arbeiten, aber zugegebenermaßen bedarf es einiges an Wissen, damit das möglich ist. Aber auch wenn man sagt, dass man seine lokalen Änderungen (im Endeffekt reden wir bei den meisten Leuten ja eh nur von den Settings-Dateien) halt vor dem Aktualisieren rückgängig macht, weil man Angst hat, etwas kaputt zu machen, ist es immer noch komfortabler, als es per ZIP runterzuladen.

Das Ganze reißt das Thema git nur ganz oberflächlich an. Aber ich hoffe mal, dass es für den ein oder anderen User hilfreich ist. Schreibt gerne in weiteren Kommentaren, wenn ihr Tipps / Meinungen / Anregungen habt.

[JHB]

Hier mal mein Vorgehen, was sich vor allem anbietet wenn man mehr als ein Gerät zu pflegen hat.

Voraussetzung:
Schritte von oben sind gemacht, git pull holt den neusten Stand.

(optional)
git checkout dev für den Dev Branch

Dann wird ein neuer Branch erzeugt git branch Kind1 und dahin gewechselt git checkout Kind1 jetzt können beliebige Änderungen an diesem Branch gemacht werden, alle für das Gerät von „Kind1“.
(inkl. Commits und so weiter)

Aktuell halten

Auf den dev wechseln und diesen pullen

git checkout dev
git pull

Jetzt wieder auf den eigenen Branch wechseln und diesen dann „rebasen“

git checkout Kind1
git rebase dev

Durch das „rebasen“ fließen alle Änderungen in den eigenen Branch ein, die eigenen Änderungen bleiben erhalten!

[StadiC]

@JHB

Hier mal mein Vorgehen, was sich vor allem anbietet wenn man mehr als ein Gerät zu pflegen hat.

Ich habe selber keinen git-Account und das beschriebene Vorgehen hat bei mir nicht geklappt. Das Updaten unter Beibehaltung der Einstellungen ist für mich aber auch wichtig und ich habe folgenden Workaround gefunden:

git checkout master
git pull
git checkout "meinRep"
git stash
git rebase master
git stash pop

Da ich mich mit git aber wenig auskenne und die Befehle in einem anderen Forum gefunden habe, bin ich mir nicht ganz sicher, ob das Ergebnis das Gleiche ist.

Kann mir das hier jemand bestätigen oder die Unterschiede aufzeigen?

[JHB]

@StadiC

selber keinen git-Account

baucht man auch nicht, wenn git installiert ist reicht das.
Welche Fehlermeldung kommt denn?

[StadiC]

@JHB

Welche Fehlermeldung kommt denn?

Wenn ich es in PlatformIO in der Quellcodeverwaltung versuche kommt folgende Meldung:

git pull --tags origin master
Von GitHub - biologist79/ESPuino: RFID-controlled musicplayer powered by ESP32
branch master → FETCH_HEAD
Fehler: Ihre lokalen Änderungen in den folgenden Dateien würden durch den Merge
überschrieben werden:
src/AudioPlayer.cpp
src/Cmd.cpp
Bitte committen oder stashen Sie Ihre Änderungen, bevor Sie mergen.
Abbruch

Wenn ich committen will, kommt

Stellen Sie sicher, dass Sie Ihre „user.name“ und „user.email“ in Git konfigurieren

Wenn ich es übers Terminal versuche kommt (, welch Überraschung , ) dieselbe Fehlermeldung.

[biologist]

How to Configure Git Username and Email Address

[JHB]

du hast Änderungen im dev/main gemacht die will er irgendwohin gespeichert haben…

Du machst „nie“ commits auf den main/dev, der wird immer nur gepullt.

Erstmal das von @biologist machen dann gehts es weiter bei dir mit einen git pull --force, das sollte deinen lokalen Änderungen überschreiben
(vorher gucken was man geändert hat und merken/aufschreiben)

oder was auch gehen müsste, das mit dem branch machen (erstellen und wechsel dahon) da dann deine Änderungen als commit anlegen, dann wieder zurück wechseln

[biologist]

Wie @JHB schon sagte: Direkt im master/dev machst du keine Änderungen, da das zu Kuddelmuddel führen wird. Wenn du Änderungen am Code machst, musst du dich für eine der zweiVarianten entscheiden:

a) Wenn du commiten machen willst, dann erstellst du vorher einen Branch, den du von master oder dev ableitest (je nachdem, mit was du arbeiten willst). Der Branch lebt nur bei dir lokal.
Um das dauerhaft aktuell zu halten, synchronisierst du weiterhin master bzw. dev, jedoch musst du deren Aktualisierungen in deinen lokalen Branch per merge oder rebase integrieren. Es kann dabei zu Konflikten kommen, wenn zB an Stellen, wo du Änderungen gemacht hast, über master / dev Änderungen reinkommen. Diese musst du dann auflösen.

b) Du machst keinen commit (brauchst also auch keinen eigenen Branch) sondern stattdessen einen stash. Damit werden deine Änderungen quasi nur „lose“ im Repository aufbewahrt. Es kann jedoch auch hier zu Konflikten kommen.

Ich persönlich (bin jetzt auch nicht der riesen git-Held) mache es so, dass ich größere Code-Anpassungen (aktuell habe ich keine) über Variante a mache. Per Variante b bilde ich meine Änderungen an den Settings-Files ab. Es sind nicht viele, aber irgendwann ist es mir zu nervig geworden, die immer wieder von Hand neu zu machen.

[StadiC]

Das hat es für mich verständlicher gemacht, danke. Ich habe quasi eine Mischung aus a) und b) gemacht, weil ich Bedenken hatte, im Master irgend etwas rumzupfuschen.

Nur als Zusammenfassung für mich und evt. andere git-Unerfahrene:
Für a) muss also user name und email angegeben werden (wie von @JHB beschrieben auch ohne Anmeldung möglich), dann kann nach der ersten Antwort verfahren werden und für b) wären die Befehle

git stash
git pull
git stash pop #oder apply

Das geht auch ohne eigenen Branch, natürlich aber am eigenen Branch.