Useless Box – Embedded Systems Semesterprojekt

Dieses Projekt wurde im Rahmen der Vorlesung Embedded Systems (143303) entwickelt. Es handelt sich um eine Useless-Box, die sowohl Hardware als auch Software umfasst. Mit dem Ziel, eine scheinbar "sinnlose" Interaktion zu erzeugen, reagiert die Box humorvoll auf Eingaben: Wird ein Schalter betätigt, bewegt sich ein Arm, der den Schalter wieder zurücksetzt – und das in verschiedenen "Attitüden", die auch auf einen integrierten Annäherungssensor reagieren.

Inhaltsverzeichnis

• Bild der fertigen Useless-Box
• Links zu Präsentationen
• Beteiligte Personen
• Hardware
  • Benötigte Hardware
  • Optionale Hardware
• Schaltplan
• Assembly Guide
• Getting Started Guide
• Build Befehle
• CI/CD Pipeline
• Aktueller Status

Bild der fertigen Useless-Box

Beteiligte Personen

Member	Kürzel
Cedric Gottschalk	cg103
Kathrin Keubler	kk156
Thea Roller	tr094
Simon Wimmer	sw250
Rasmus Wrobel	rw062

Links zu den Präsentationen

• Kickoff Präsentation

• Finale Präsentation

Hardware

Benötigte Hardware

Komponente	Menge	Beschreibung	Bezugslink
Arduino Uno R3	1	Microcontroller-Board mit ATMega328P zur Steuerung der Useless-Box	Link
12g Analoger Servo 5V (für den Arm)	1	Dient zur Bewegung des mechanischen Arms	Link
9g Analoger Servo 5V (für den Deckel)	1	Steuert die Bewegung des Deckels	Link
Kippschalter/Hebelschalter	1	Zum Auslösen der Aktion	Link
APDS-9960 Annäherungssensor	1	Erkennt Annäherungen und triggert alternative Reaktionen	Link
1k Ohm Widerstand	1	Für Signalstabilisierung in der Schaltung	Link
Kabel (z.B. Steckbrückenkabel)	x	Verbindungskomponenten	Link

Weitere Hardware

Komponente	Menge	Beschreibung	Bezugslink
Für Batteriebetrieb (optional):
Hohlstecker	1	Anschluss der Batterie an den Arduino	Link
Wippenschalter	1	Zum Ein- bzw. Ausschalten der Stromzufuhr	Link
Batteriehalter	1	Befestigung der Batterie	Link
9V Blockbatterie	1	Energiequelle für den Batteriebetrieb	Link
Zum Testen (optional):
Breadboard	1	Zum schnellen Prototyping und Testen der Schaltung	Link
Für eine ansprechende Box: (optional)
3D-gedruckte Box	1	Gehäuse für die Useless-Box	3D-Files
M3 Gewindeeinsätze	4	Für die Befestigung des fest fixierten Deckels der Box	Link
M3 Senkkopfschrauben	6	Für die Befestigung des fest fixierten Deckels der Box	Link
Stück dicker Metalldraht	1	Verbindungselement zwischen Deckel und Servo	-
Mehrere kleine selbstschneidende Schrauben	x	Zum befestigen der Sevos und des Arduinos in der Box	Link
Zusätzlich benötigt:
Lötkolben	1	Für dauerhafte elektrische Verbindungen	-
USB Typ A auf USB Typ B Kabel	1	Für die Verbindung des Arduino mit dem Rechner	Link

Schaltplan

Link zum Schaltplan

Assembly Guide

Hier findest du eine Schritt-für-Schritt Anleitung zum Zusammenbau der Useless-Box:

1. Teile drucken, prüfen und vorbereiten

• Drucke alle Teile der Box mit einem 3D-Drucker: 3D-Files (oder Prototype, wenn du die Hardware zuerst testen möchtest).
• Überprüfe alle 3D-gedruckten Teile und entferne alle Druckrückstände.
• Überprüfe, ob alle elektronischen Komponenten (Servos, Schalter, Sensor, Widerstand, Kabel) vorhanden sind und funktionieren.
• Schmelze die Gewindeeinsätze mit einem Lötkolben in die dafür vorgesehenen Löcher im Gehäuse ein.
• Löte an den Hebelschalter/Kippschalter Kabel an.
• Biege aus dem dicken Drahtstück auf der einen Seite eine Öse und auf der anderen Seite einen Haken, der später zur Verbindung des Deckels dient. Befestige den Draht mit der mitgelieferten Hardware am 9g Servo.

2. Montage der Elektronik

• Montiere den gedruckten Arm mit Hilfe der mit dem Servo gelieferten Hardware am 12g Servo.
• Montiere den Hebelschalter/Kippschalter und den APDS-9960 am festen Deckel.
• (optional) Installiere alle Komponenten für den Batteriebetrieb in der Box. Der Minuspol des Batteriehalters wird direkt mit dem Minuspol des Holsteckers verbunden. Der Wippschalter wird zwischen den Pluspol des Batteriehalters und den Pluspol des Holsteckers geschaltet.
• Die beiden Servos werden mit Hilfe von Schrauben am festen Deckel befestigt.

3. Elektronik verkabeln

• Verbinde alle elektronischen Bauteile entsprechend dem Schaltplan mit dem Arduino.
• Einige Kabel/Bauteile müssen gelötet werden (z.B. Widerstand).

4. Kabelmanagement und Endmontage

• Verlege nun alle Kabel ordentlich, um lose Verbindungen zu vermeiden. Optional kannst du die Kabel und Verbindungen auch mit Schrumpfschlauch oder etwas Isolierband fixieren.
• Montiere den Arduino mit 3 Schrauben an der dafür vorgesehenen Stelle im Gehäuse.
• Befestige den beweglichen Deckel mit zwei Senkkopfschrauben an der Box. Die Schrauben nicht zu fest anziehen, der Deckel muss sich noch leicht bewegen lassen.
• Hacke das Stück Metalldraht an der Öse im beweglichen Deckel ein.
• Befestige nun den festen Deckel mit den Senkkopfschrauben an der Box. Eventuell ist etwas Fingerspitzengefühl erforderlich, um den Deckel mit der Elektronik in die Box zu bekommen, ohne dass Kabel eingeklemmt werden.
• Kontrolliere, dass alle mechanischen Teile frei beweglich sind und nicht durch Kabel behindert werden.

Getting Started Guide

Um nun das Projekt erfolgreich zu builden und zu flashen, stelle bitte sicher, dass folgende Software installiert ist:

• AVR-Toolchain – für das Kompilieren des Quellcodes.
• CMake – zum Konfigurieren und Erstellen des Projekts.
• AVRDUDE – zum Flashen der Firmware auf das Arduino Board.

1. Umgebungsvariablen setzen

Bevor das Projekt kompiliert und auf den Arduino geflasht werden kann, müssen zwei Umgebungsvariablen gesetzt werden:

• AVRDUDE_PATH: Der absolute Pfad zur avrdude-Executable.
• ARDUINO_PORT: Der serielle Port, an dem der Arduino angeschlossen ist.

Beispiel (Linux/macOS):

export AVRDUDE_PATH=/pfad/zu/avrdude
export ARDUINO_PORT=/dev/ttyUSB0

Beispiel (Windows - PowerShell):

$env:AVRDUDE_PATH="C:\Pfad\zu\avrdude"
$env:ARDUINO_PORT="COM3"

Diese Umgebungsvariablen müssen gesetzt sein, bevor der Flash-Befehl ausgeführt wird.

2. Repository klonen

Falls das Projekt noch nicht lokal vorhanden ist, klone das Repository:

git clone https://gitlab.mi.hdm-stuttgart.de/embedded/ws24/useless-box.git
cd useless-box

3. Build-Verzeichnis erstellen und konfigurieren

Das Projekt verwendet CMake zur Konfiguration und den AVR Toolchain-Support. Erstelle ein Build-Verzeichnis und konfiguriere das Projekt:

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../avr-toolchain.cmake --fresh ..

4. Projekt bauen und flashen

Der folgende Befehl startet den Build-Prozess und flashed die Software auf den angeschlossenen Arduino:

cmake --build . --target flash

Dadurch wird die Firmware kompiliert und die .hex-Datei für den Arduino erzeugt und im Anschluss direkt auf den Arduino geflashed.

Mit diesen Schritten kannst du das Projekt erfolgreich kompilieren, flashen und testen. Falls Fehler auftreten, überprüfe die gesetzten Umgebungsvariablen und stelle sicher, dass avrdude korrekt installiert ist.

Es kann eventuell nötig sein, dass die Min-, Max- und Positions-Werte der Servos in der servo.h feinjustiert werden müssen.

Build Befehle

Das Projekt enthält mehrere Build-Ziele für unterschiedliche Aufgaben.

1. Standard-Build

Dieser Befehl kompiliert das Projekt und erzeugt die benötigte .hex-Datei für den Arduino:

cmake --build .

2. Firmware builden & flashen

Dieser Befehl kompiliert das Projekt, erzeugt die benötigte .hex-Datei für den Arduino und flashed diese im Anschluss direkt mit Hilfe von avrdude

cmake --build . --target flash

Dieser Befehl nutzt die zuvor gesetzten Umgebungsvariablen AVRDUDE_PATH und ARDUINO_PORT, um die Firmware an das richtige Gerät zu senden.

3. Build-Ordner bereinigen

Falls das Build-Verzeichnis bereinigt werden muss (z. B. nach Änderungen im Code), um eine frische Kompilierung durchzuführen, kann folgender Befehl genutzt werden:

cmake --build . --target clean

Dies entfernt alle kompilierten Dateien und bereitet das Projekt für einen neuen Build vor.

Zusätzlich zur lokalen Entwicklung werden diese Befehle auch in der GitLab CI/CD Pipeline verwendet, um Builds automatisiert zu erstellen und zu testen.

CI/CD Pipeline

Das Projekt verwendet eine GitLab CI/CD Pipeline, um den Build-Prozess zu automatisieren, statische Code-Analysen durchzuführen und Releases zu erstellen. Dadurch wird sichergestellt, dass jeder Code-Commit automatisch getestet, gebaut und – sofern getaggt – als offizielles Release veröffentlicht wird.

Die Pipeline besteht aus mehreren Stufen:

1. Build-Image (build-image)

• Ziel: Erstellen eines Docker-Images mit der benötigten Entwicklungsumgebung.
• Details:
  • Das Docker-Image basiert auf gcr.io/kaniko-project/executor:v1.23.2-debug.
  • Das Image wird aus dem Dockerfile im Repository gebaut und in die GitLab Container Registry hochgeladen.
• Trigger: Dieser Schritt wird nur manuell ausgeführt.

2. Statische Code-Analyse (static-analysis)

• Ziel: Überprüfung des Codes auf potenzielle Fehler und Code-Qualitätsprobleme.
• Details:
  • cppcheck wird verwendet, um den Quellcode zu analysieren.
  • Ergebnisse werden in gl-code-quality-report.json gespeichert und in GitLab als Artefakt hochgeladen.
• Trigger: Wird automatisch bei jedem Push in einen Branch ausgeführt.

3. Build-Prozess (build)

• Ziel: Kompilieren der Firmware für das Arduino Board.
• Details:
  • Ein Build-Ordner wird erstellt und mit CMake konfiguriert.
  • Die AVR Toolchain wird genutzt, um die Firmware zu kompilieren.
  • Die erzeugte .hex-Datei wird mit einem Branch-spezifischen Namen versehen.
• Trigger: Wird bei jedem Commit auf einem Branch ausgeführt.

4. Build für Tags (build-tag)

• Ziel: Spezialisierter Build für ein offizielles Release.
• Details:
  • Gleiche Schritte wie build, aber nur für getaggte Releases.
  • Die erzeugte .hex-Datei wird unter Verwendung des Tag-Namens gespeichert.
• Trigger: Automatisch bei Push eines Tags.

5. Release-Prozess (release)

• Ziel: Erstellung eines neuen GitLab-Releases und Verlinkung der Firmware.
• Details:
  • Ein GitLab-Release wird mit einer passenden Beschreibung erstellt.
  • Die erzeugte .hex-Datei wird als Asset verlinkt, sodass sie einfach heruntergeladen werden kann.
• Trigger: Automatisch nach einem erfolgreichen build-tag.

Pipeline-Ausführung in GitLab

• Reguläre Commits lösen die static-analysis und build Jobs aus.
• Tags lösen build-tag und anschließend release aus.
• Manuelles Starten ist für das build-image erforderlich.

Diese CI/CD Pipeline stellt sicher, dass das Projekt immer in einem funktionsfähigen Zustand bleibt und Releases automatisiert bereitgestellt werden können.

Aktueller Status

1. Integrierte Features

Die folgenden Funktionen sind bereits in das Projekt implementiert:

• Kippschalter als Auslöser

  • Beim Betätigen des Schalters aktiviert sich der mechanische Arm, um den Schalter wieder auszuschalten.
  • Reaktionen des Arms wurden in verschiedenen "Attitüden" programmiert.

• Beweglicher Deckel mit Servo

  • Der Deckel öffnet und schließt sich, um die Mechanik zu verbergen.

• APDS-9960 Annäherungssensor

  • Erkennt Annäherungen und beeinflusst das Verhalten der Box.
  • Reaktionen auf Annäherungen wurden in verschiedenen "Attitüden" programmiert.

• Verschiedene Bewegungsmuster ("Attitüden")

  • Unterschiedliche Reaktionsweisen auf das Betätigen des Schalters oder das Annähern an die Box.
  • Der Arm kann sich mit verschiedenen Geschwindigkeiten und Bewegungen (z. B. Antäuschen) verhalten.
  • "Mad-Mode", bei dem die Box nach einer bestimmten Anzahl von Betätigungen "aggressiver" reagiert.

2. Optionale Erweiterungen (noch nicht umgesetzt)

Folgende zusätzliche Features sind möglich, wurden aber noch nicht integriert:

• Mehrere Schalter mit unterschiedlichen Mechanismen

  • Ein Arm, der sich kippt.
  • Ein Arm, der auf einer Schiene fährt.
  • Mehrere Arme, die sich unterschiedlich verhalten.

• Zusätzliche Reaktionsmuster

  • Komplexere Bewegungsschemata, abhängig von der Sensor-Eingabe.

• Erweiterte Steuerung und Konfigurationsmöglichkeiten

  • Möglichkeit zur Einstellung der Reaktionsgeschwindigkeit.
  • Anpassbare Empfindlichkeit des Annäherungssensors.

Das Projekt ist aktuell voll funktionsfähig, aber es gibt noch Potenzial für Erweiterungen und kreative Verbesserungen!

Lizenz

Dieses Projekt steht unter der MIT-Lizenz.