Improve documentation of firmware code

1 files changed, 58 insertions, 6 deletions

diff --git a/firmware/main.c b/firmware/main.c
index 264d3f5..df35205 100644
--- a/firmware/main.c
+++ b/firmware/main.c
@@ -2,6 +2,8 @@
 
 
 /*
+  ------------------------------------------------------------------------------
+
   ledcontrol firmware
   Copyright (C) 2021  xengineering
 
@@ -19,6 +21,19 @@
   along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
   Contact: me@xengineering.eu
+
+  ------------------------------------------------------------------------------
+
+  This firmware currently has these functions:
+  - blink the onboard LED C13
+  - let an external LED at PB0 fade
+
+  Future features should be:
+  - adjust the brightness of the external LED by an incremental encoder
+  - enable / disable the light by pressing a push button (included in encoder)
+  - offer this functionality via WiFi with an external WiFi-capable board
+
+------------------------------------------------------------------------------
 */
 
 
@@ -36,6 +51,12 @@ static void timer_init(void);
 void tim2_isr(void);
 
 
+/* main function
+
+This should give you a brief overview of the control flow. Read the
+corresponding function definitions for details about configuration and
+implementation.
+*/
 int main(void)
 {
 	clock_init();
@@ -47,9 +68,18 @@ int main(void)
 }
 
 
+/* Clock initialization
+
+This function configures the system clock of the microcontroller (sysclk). The
+dynamic configuration allows to execute the program faster (high clock speed)
+or to save energy (low clock speed).
+
+Important to notice: On STM32 microcontrollers it is mandatory to enable the
+clocks for peripherals and timer / counter units explicitly!
+*/
 static void clock_init(void)
 {
-	// set sysclk to 72 MHz via external 8 MHz crystal
+	// set system clock to 72 MHz via external 8 MHz crystal and a PLL
 	rcc_clock_setup_pll(&rcc_hse_configs[RCC_CLOCK_HSE8_72MHZ]);
 
 	// enable clocks for GPIO ports B and C
@@ -61,12 +91,10 @@ static void clock_init(void)
 
 	// enable clock for timer 3 (PWM)
 	rcc_periph_clock_enable(RCC_TIM3);
-
-	// enable clock for alternate functions
-	rcc_periph_clock_enable(RCC_AFIO);  // TODO is this necessary?
 }
 
 
+/* Initialization of general purpose inputs and outputs (GPIOs) */
 static void gpio_init(void)
 {
 	// init PC13 onboard LED for blinking
@@ -76,7 +104,9 @@ static void gpio_init(void)
 		GPIO_CNF_OUTPUT_PUSHPULL,
 		GPIO13
 	);
-	gpio_clear(GPIOC, GPIO13);  // set initial value to 'on'
+
+	// set initial value to 'on'
+	gpio_clear(GPIOC, GPIO13);
 	
 	// setup PB0 (connected to TIM3_CH3) for PWM
 	gpio_set_mode(
@@ -88,6 +118,11 @@ static void gpio_init(void)
 }
 
 
+/* Nested Vectored Interrupt Controller (NVIC) setup
+
+This function configures NVIC. This way the interrupt triggered by
+timer / counter units is enabled explicitly.
+*/
 static void nvic_init(void)
 {
 	// enable timer 2 interrupt and set priority
@@ -96,6 +131,12 @@ static void nvic_init(void)
 }
 
 
+/* Timer / counter setup
+
+This function configures two timer / counter units (TIM2 and TIM3). TIM2
+controls the blinking and fading animation and TIM3 is for the
+pulse-width-modulation (PWM) of the external LED.
+*/
 static void timer_init(void)
 {
 	// setup timer 2 for blinking
@@ -109,6 +150,7 @@ static void timer_init(void)
 
 	/* 
 		enable timer / counter 3
+		// TODO: clean the rest of this function ... it is a mess
 	*/
 
 	/* Clock division and mode */
@@ -139,10 +181,20 @@ static void timer_init(void)
 }
 
 
+/* Timer / counter 2 interrupt service routine
+
+This function is called by the interrupt of timer / counter 2. The function is
+not called explicitly in this file but hard-coded in the libopencm3 library.
+
+The purpose of TIM2 is to blink the onboard LED and to decrement the PWM value
+resulting in a increment of brightness. Thus this function defines the logic of
+the 'animation' shown by the LEDs.
+*/
 void tim2_isr(void)
 {
 	// PWM handling
-	static uint32_t pwm_value;
+	static uint32_t pwm_value = 0;  // static variable to remember value on next
+	                                // function call
 	if (pwm_value == 0) {
 		pwm_value = 65535;
 	}