From 1eeabad048867fea8c6ac470014b96b9c928cc1c Mon Sep 17 00:00:00 2001
From: Jim Martens <github@2martens.de>
Date: Wed, 22 Apr 2015 19:06:57 +0200
Subject: [PATCH] [ES-Blatt2] Improved documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-óff-by: Jim Martens <github@2martens.de>
---
 es/blatt2/uebung2-1/uebung2-1.ino | 69 +++++++++++++++++++++++--------
 1 file changed, 51 insertions(+), 18 deletions(-)

diff --git a/es/blatt2/uebung2-1/uebung2-1.ino b/es/blatt2/uebung2-1/uebung2-1.ino
index 3e4f130..b9486fd 100644
--- a/es/blatt2/uebung2-1/uebung2-1.ino
+++ b/es/blatt2/uebung2-1/uebung2-1.ino
@@ -1,21 +1,34 @@
+// these variables describe the used hardware pins
+// adjust them when you use other pins
+// hardware pin for the LED
 int ledPin = 7;
+// hardware pin for the plus button
 int buttonPlusPin = 5;
+// hardware pin for the minus button
 int buttonMinusPin = 3;
+
+// used to achieve a 1kHz frequency
+// don't touch them
+int compareValue = 60;
+int rc = 10499;
+
+// these values are used by the TC0_Handler
+// do not write into them within the loop/setup
+// only the counter should be used within the loop
 int volatile counter = 0;
 int timesPressedPlus = 0;
 int timesPressedMinus = 0;
-int vergleichswert = 60;
-int rc = 10499;
 bool increased = false;
 bool decreased = false;
 
+/**
+ * Setup function for initial setup code
+ */
 void setup() {
-  // put your setup code here, to run once:
-
   pmc_set_writeprotect(false);
   pmc_enable_periph_clk(ID_TC0);
 
-  // Hier erfolgt die Konfiguration des Timers
+  // configure hardware timer
   TC_Configure(TC0, 0, TC_CMR_WAVE | TC_CMR_WAVSEL_UP_RC | TC_CMR_TCCLKS_TIMER_CLOCK2) ;
   TC_SetRC(TC0, 0, rc);
 
@@ -25,45 +38,63 @@ void setup() {
   NVIC_ClearPendingIRQ(TC0_IRQn);
   NVIC_EnableIRQ(TC0_IRQn);
 
-  // Hier wird der konfigurierte Timer gestartet
+  // start hardware timer
   TC_Start(TC0, 0);
 
-  // Hier werden die Taster konfiguriert
+  // Configure button pins for input mode
   pinMode(buttonPlusPin, INPUT);
   pinMode(buttonMinusPin, INPUT);
 
-  // Ausgabe über den seriellen Port
+  // initialize serial port
   Serial.begin(9600);
 }
 
+/**
+ * Loop function for main code
+ */
 void loop() {
-  // put your main code here, to run repeatedly:
-  // Hier wird die Plus Taste abgefragt
+  // write the current counter to the LED pin
   analogWrite(ledPin, counter);
+  // print the current LED value in the serial for debugging purposes
   Serial.print("LED: ");
   Serial.println(counter);
 }
 
+/**
+ * Increases the counter by 1.
+ *
+ * The highest possible value of the counter is 255.
+ */
 void increment() {
   if (counter < 255) {
     counter += 1;
   }
 }
 
+/**
+ * Decreases the counter by 1.
+ *
+ * The lowest possible value of the counter is 0.
+ */
 void decrement() {
   if (counter > 0)  {
     counter -= 1;
   }
-
 }
 
+/**
+ * Used to increase/decrease a counter when the corresponding button is pressed.
+ */
 void TC0_Handler()
 {
+  // request static for some magic behind the curtain
   TC_GetStatus(TC0, 0);
-  bool tasteGedruecktPlus = (digitalRead(buttonPlusPin) == LOW);
-  bool tasteGedruecktMinus = (digitalRead(buttonMinusPin) == LOW);
+  // variables used to determine if the corresponding button is pressed
+  bool buttonPressedPlus = (digitalRead(buttonPlusPin) == LOW);
+  bool buttonPressedMinus = (digitalRead(buttonMinusPin) == LOW);
 
-  if (tasteGedruecktPlus){
+  // handles the plus button
+  if (buttonPressedPlus){
     ++timesPressedPlus;
   }
   else {
@@ -73,7 +104,8 @@ void TC0_Handler()
     timesPressedPlus = 0 ;
   }
 
-  if (tasteGedruecktMinus){
+  // handles the minus button
+  if (buttonPressedMinus){
     ++timesPressedMinus;
   }
   else {
@@ -83,7 +115,8 @@ void TC0_Handler()
     timesPressedMinus = 0 ;
   }
 
-  if (timesPressedPlus >= vergleichswert) {
+  // increases counter if button has been pressed long enough
+  if (timesPressedPlus >= compareValue) {
     if (!increased) {
       increment();
     }
@@ -91,8 +124,8 @@ void TC0_Handler()
     timesPressedPlus = 0;
   }
 
-  // Hier wird die Minus Taste abgefragt
-  if (timesPressedMinus >= vergleichswert) {
+  // decreases counter if button has been pressed long enough
+  if (timesPressedMinus >= compareValue) {
     if (!decreased) {
       decrement();
     }