feat(examples): rebuild the catalog along the course weeks

README.md

@@ -7,25 +7,52 @@ relative to this repository and its immutable release ref.
 ## Didactic structure
 
 The examples follow the weekly `ITxx` course documents used in the first
-semester. Each sketch focuses on one concept and contains four parts:
+semester; the week number in a file name matches the number of the course
+document. Each sketch focuses on one concept from that week and contains five
+parts:
 
 1. a learning objective,
-2. a directly observable result,
-3. small experiments that modify the sketch, and
-4. learning questions without included answers.
+2. a reference to the slides it illustrates (`Bezug zu den Unterlagen`),
+3. a directly observable result,
+4. small experiments that modify the sketch, and
+5. learning questions without included answers.
+
+The sketches use the conventions of the slides: constants in upper case,
+`const byte` for pin numbers, `struct Messung` with the `struct` keyword, and
+the voltage conversion `messwert / 1024.0 * 5.0`. Comments are German with
+umlauts; string literals stay ASCII. Every example compiles for the Arduino Uno
+without warnings.
 
 File names use the pattern `it<week>-<number>-<topic>.ino`, for example
-`it03-03-digitaler-ausgang.ino`. File names stay ASCII-only for reliable use in
+`it03-04-led-blinken.ino`. File names stay ASCII-only for reliable use in
 URLs and different file systems; German characters may be used in the titles
 inside `manifest.json`.
 
-The examples are intentionally small reference programs. Complete solutions
-for the larger Morse, LED dice, traffic-light, and workpiece-detection exercises
-are not part of the public catalog.
+Headers are plain `.h` files with definitions, as in the course, so beginners
+only ever handle one extra file. `examples/IT11/mat_func.h` is shared by the
+matrix examples IT11.2 to IT11.5.
+
+The weeks IT09 and IT10 are project weeks and have no examples. The examples
+are intentionally small reference programs. Complete solutions for the larger
+Morse, LED dice, traffic-light, and workpiece-detection exercises are not part
+of the public catalog.
+
+IT08.4 (`typedef` in function signatures) and the IT11 examples (array
+parameters sized by constants, default arguments) need an UnoSim version whose
+generated function prototypes follow the Arduino IDE, that is, placed before the
+first function definition and without default arguments. IT03.6 and IT04.4
+expect an open `INPUT_PULLUP` pin to read `HIGH`, which also needs that version.
+
+UnoSim does not run the sketch as Uno machine code, so a few observations
+differ from the hardware: `int` is 32 bits wide, `double` 64 bits, and a float
+printed without a precision shows `2.5` instead of `2.50`. The examples avoid
+these cases (overflow is shown with `byte`, floats are always printed with a
+precision). Keep it that way in new examples; the UnoSim user guide lists all
+differences in its section "Grenzen der Simulation".
 
 ## Releases
 
-Releases use immutable tags such as `v2.0.0`; production UnoSim deployments may
+Releases use immutable tags such as `v3.0.0`; production UnoSim deployments may
 pin the corresponding tag or commit SHA.
 
 ## Course Content and Tutor authoring

examples/IT01/it01-01-variable-definieren.ino

@@ -0,0 +1,82 @@
+/*
+ * IT01.1 – Eine Variable deklarieren, initialisieren und zuweisen
+ *
+ * Lernziel:
+ * Deklaration, Initialisierung und Zuweisung unterscheiden und erklären,
+ * was bei einer neuen Zuweisung mit dem alten Wert geschieht.
+ *
+ * Bezug zu den Unterlagen:
+ * IT01 Daten, Folien „Variable deklarieren“ und „Datentypen für ganze Zahlen“
+ * (Deklaration + Initialisierung = Definition).
+ *
+ * Beobachtung:
+ * Der serielle Monitor zeigt „Teile: 3“, dann „Teile: 5“ und „Fehler: 0“.
+ * Serial wird hier nur benutzt, um die Werte sichtbar zu machen.
+ */
+
+int anzahlTeile;        // Deklaration: Es gibt jetzt eine Variable vom Typ int
+int anzahlFehler = 0;   // Definition: Deklaration und Initialisierung in einem Schritt
+
+void setup() {
+  Serial.begin(115200);
+
+  anzahlTeile = 3;      // Zuweisung
+  Serial.print("Teile: ");
+  Serial.println(anzahlTeile);
+
+  anzahlTeile = 5;      // Die neue Zuweisung überschreibt den alten Wert
+  Serial.print("Teile: ");
+  Serial.println(anzahlTeile);
+
+  Serial.print("Fehler: ");
+  Serial.println(anzahlFehler);
+}
+
+void loop() {
+}
+
+/*
+ * Experimente:
+ * 1. Weise anzahlFehler in setup() den Wert 2 zu und gib ihn erneut aus.
+ * 2. Deklariere drei weitere Variablen in einer Zeile: int x, y, z;
+ * 3. Schreibe in einer der Ausgaben AnzahlTeile mit großem A und lies die
+ *    Fehlermeldung des Compilers.
+ *
+ * Lernfragen:
+ * 1. Welche Zeile ist nur eine Deklaration und welche eine Definition?
+ * 2. Was geschieht mit dem alten Wert, wenn anzahlTeile = 5 ausgeführt wird?
+ * 3. Warum erkennt der Compiler AnzahlTeile nicht als dieselbe Variable?
+ */
+
+/* @unosim-tutor
+schemaVersion: 2
+learningObjectives:
+  - "Die Studierenden sollen Deklaration, Initialisierung und Zuweisung einer Variablen unterscheiden können."
+  - "Sie sollen erklären können, dass eine Zuweisung den alten Wert überschreibt."
+afterFocus: free
+focus:
+  - id: begriffe
+    title: "Deklaration, Definition, Zuweisung"
+    objective: "Die drei Begriffe an den Zeilen des Sketches zeigen und unterscheiden."
+    questions:
+      - kind: recall
+        text: "Welche Zeile ist nur eine Deklaration, und welche Zeile ist eine Definition?"
+      - kind: concept
+        text: "Worin unterscheidet sich die Zeile mit `anzahlFehler` von der Zeile, in der `anzahlTeile` deklariert wird?"
+  - id: ueberschreiben
+    title: "Einen Wert überschreiben"
+    objective: "Vorhersagen, welchen Wert eine Variable nach mehreren Zuweisungen besitzt."
+    questions:
+      - kind: prediction
+        text: "Was geschieht mit dem alten Wert von `anzahlTeile`, wenn `anzahlTeile = 5` ausgeführt wird?"
+      - kind: application
+        text: "Wie viele Werte kann `anzahlTeile` zu einem Zeitpunkt gleichzeitig speichern?"
+  - id: namen
+    title: "Variablennamen"
+    objective: "Die Regeln für Variablennamen anwenden."
+    questions:
+      - kind: concept
+        text: "Warum meldet der Compiler einen Fehler, wenn `anzahlTeile` an einer Stelle mit großem A geschrieben wird?"
+      - kind: transfer
+        text: "Welche weitere Variable würdest du für ein Zählprogramm definieren, und mit welchem Startwert?"
+@end-unosim-tutor */

examples/IT01/it01-02-konstante.ino

@@ -1,34 +1,52 @@
 /*
- * IT01.2 - Einen unveraenderlichen Wert festlegen
+ * IT01.2 – Einen unveränderlichen Wert festlegen
  *
  * Lernziel:
- * Einen Wert mit const als Konstante deklarieren.
+ * Werte, die sich nie ändern sollen, mit const als Konstante definieren und
+ * die vordefinierten Arduino-Konstanten kennenlernen.
+ *
+ * Bezug zu den Unterlagen:
+ * IT01 Daten, Folien „Konstanten“ und „Festlegungen“ (Konstanten werden
+ * immer großgeschrieben).
  *
  * Beobachtung:
- * Der serielle Monitor zeigt den festgelegten Grenzwert.
- * Serial wird hier nur benutzt, um den Wert sichtbar zu machen.
+ * Der serielle Monitor zeigt die eigene Konstante, einen Umrechnungsfaktor
+ * und die Zahlenwerte der vordefinierten Konstanten HIGH und LOW.
  */
 
 const byte MAXIMALE_ANZAHL = 10;
+const float ZOLL_IN_CM = 2.54;
 
 void setup() {
   Serial.begin(115200);
+
   Serial.print("Maximale Anzahl: ");
   Serial.println(MAXIMALE_ANZAHL);
+
+  Serial.print("1 Zoll = ");
+  Serial.print(ZOLL_IN_CM, 2);
+  Serial.println(" cm");
+
+  Serial.print("HIGH hat den Wert ");
+  Serial.println(HIGH);
+  Serial.print("LOW hat den Wert ");
+  Serial.println(LOW);
 }
 
 void loop() {
 }
 
 /*
  * Experimente:
- * 1. Aendere den Wert der Konstante auf 20.
- * 2. Versuche nach der Deklaration MAXIMALE_ANZAHL = 5; zu ergaenzen.
+ * 1. Ändere den Wert von MAXIMALE_ANZAHL auf 20.
+ * 2. Ergänze in setup() die Zeile MAXIMALE_ANZAHL = 5; und lies die
+ *    Fehlermeldung des Compilers.
+ * 3. Gib zusätzlich die vordefinierte Konstante A0 aus.
  *
  * Lernfragen:
  * 1. Wodurch unterscheidet sich eine Konstante von einer Variablen?
  * 2. Warum meldet der Compiler beim zweiten Experiment einen Fehler?
- * 3. Warum werden Konstantennamen hier grossgeschrieben?
+ * 3. Warum werden Konstantennamen großgeschrieben?
  */
 
 /* @unosim-tutor
@@ -40,20 +58,20 @@ afterFocus: free
 focus:
   - id: konstante-oder-variable
     title: "Konstante oder Variable"
-    objective: "Den Unterschied zwischen einer Konstante und einer Variablen erklären und die Folge einer Änderung vorhersagen."
+    objective: "Den Unterschied zwischen Konstante und Variable erklären und die Folge einer Änderung vorhersagen."
     questions:
       - kind: concept
         text: "Wodurch unterscheidet sich `MAXIMALE_ANZAHL` von einer gewöhnlichen Variablen?"
       - kind: prediction
-        text: "Was würde der Compiler melden, wenn man später versucht, `MAXIMALE_ANZAHL` einen neuen Wert zuzuweisen, und warum?"
-  - id: const-und-namen
-    title: "const und Namenswahl"
-    objective: "Die Rolle von `const` und die Namenskonvention für Konstanten begründen."
+        text: "Was meldet der Compiler, wenn in `setup` versucht wird, `MAXIMALE_ANZAHL` einen neuen Wert zuzuweisen?"
+  - id: konventionen
+    title: "Namen und vordefinierte Konstanten"
+    objective: "Die Namenskonvention begründen und vordefinierte Konstanten einordnen."
     questions:
       - kind: concept
-        text: "Welche Aufgabe hat das Schlüsselwort `const` in der Deklaration?"
-      - kind: concept
-        text: "Warum ist der Name `MAXIMALE_ANZAHL` hier großgeschrieben?"
+        text: "Warum sind die Namen `MAXIMALE_ANZAHL` und `ZOLL_IN_CM` großgeschrieben?"
+      - kind: recall
+        text: "Welche Zahlenwerte stehen hinter den vordefinierten Konstanten `HIGH` und `LOW`?"
       - kind: transfer
-        text: "Für welchen weiteren Wert in einem Sketch wäre eine Konstante sinnvoll?"
+        text: "Für welchen weiteren Wert in einem Arduino-Programm wäre eine Konstante sinnvoll?"
 @end-unosim-tutor */

examples/IT01/it01-03-datentyp-waehlen.ino

@@ -0,0 +1,73 @@
+/*
+ * IT01.3 – Einen Datentyp begründet auswählen
+ *
+ * Lernziel:
+ * Für einen bekannten Wertebereich einen passenden Datentyp auswählen und
+ * die Auswahl über die Anzahl der Bitmuster begründen.
+ *
+ * Bezug zu den Unterlagen:
+ * IT01 Daten, Folie „Argumentation für die Auswahl von Datentypen“
+ * (Wert zwischen 0 und 1023).
+ *
+ * Beobachtung:
+ * Derselbe Wert 1023 wird einmal als unsigned int und einmal als byte
+ * gespeichert. Der byte-Wert ist 255 – der Wert passt nicht hinein.
+ */
+
+// Anforderung: Ein Sensorwert liegt immer zwischen 0 und 1023.
+unsigned int sensorwertPassend = 1023;
+
+void setup() {
+  Serial.begin(115200);
+
+  byte sensorwertZuKlein = sensorwertPassend;
+
+  Serial.print("Als unsigned int gespeichert: ");
+  Serial.println(sensorwertPassend);
+  Serial.print("Als byte gespeichert:         ");
+  Serial.println(sensorwertZuKlein);
+}
+
+void loop() {
+}
+
+/*
+ * Experimente:
+ * 1. Setze sensorwertPassend auf 255 und vergleiche beide Ausgaben.
+ * 2. Setze sensorwertPassend auf 300. Welcher byte-Wert erscheint?
+ * 3. Begründe schriftlich nach dem Schema der Folie, welchen Datentyp du für
+ *    einen Füllstand von 0,4 m bis 6,0 m wählen würdest.
+ *
+ * Lernfragen:
+ * 1. Wie viele verschiedene Bitmuster besitzt ein 8-Bit-Datentyp, wie viele
+ *    ein 16-Bit-Datentyp?
+ * 2. Warum ist byte für den Bereich 0 bis 1023 nicht geeignet?
+ * 3. Warum darf hier das Schlüsselwort unsigned verwendet werden?
+ */
+
+/* @unosim-tutor
+schemaVersion: 2
+learningObjectives:
+  - "Die Studierenden sollen einen Datentyp für einen gegebenen Wertebereich auswählen und begründen können."
+  - "Sie sollen die Anzahl der Bitmuster eines Datentyps aus seiner Bitbreite bestimmen können."
+afterFocus: free
+focus:
+  - id: bitmuster
+    title: "Bitmuster und Wertebereich"
+    objective: "Aus der Bitbreite die Anzahl der Bitmuster und den größten Wert bestimmen."
+    questions:
+      - kind: recall
+        text: "Wie viele verschiedene Bitmuster kann ein 8-Bit-Datentyp wie `byte` darstellen?"
+      - kind: concept
+        text: "Warum ist `byte` für Werte bis 1023 zu klein?"
+  - id: argumentation
+    title: "Den Datentyp begründen"
+    objective: "Die Wahl von `unsigned int` nach dem Schema der Folie begründen."
+    questions:
+      - kind: concept
+        text: "Warum darf `sensorwertPassend` mit `unsigned` deklariert werden?"
+      - kind: prediction
+        text: "Welcher Wert erscheint für `sensorwertZuKlein`, wenn `sensorwertPassend` den Wert 300 hat?"
+      - kind: transfer
+        text: "Welchen Datentyp würdest du für einen Füllstand von 0,4 m bis 6,0 m wählen, und wie begründest du das?"
+@end-unosim-tutor */