Assignment 3: comment rework

assignment_3/Libraries/drivers/NUCLEO_F401RE.c

@@ -5,9 +5,8 @@
  *    Nucleo F401RE port file. This file contain the implementation of driver
  *    calls for F401RE board.
  *
- *  Created on: May 23, 2020
- *      Author: Christos Choutouridis AEM: 8997
- *      email : <cchoutou@ece.auth.gr>
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
 #include "NUCLEO_F401RE.h"
 
@@ -123,7 +122,14 @@ void HAL_Delay(uint32_t Delay) {
 /*
  * ================     Jiffies   ======================
  */
-
+/*!
+ * Provide jiffy compatible set frequency functionality
+ * \param jf_freq    The desire frequency
+ * \param jiffies    The number of steps (jiffies)
+ * \return     The status of the operation
+ *    \arg  0  Success
+ *    \arg  1  Fail
+ */
 int JF_setfreq (uint32_t jf_freq, uint32_t jiffies) {
    uint32_t psc=0;
 

assignment_3/Libraries/drivers/NUCLEO_F401RE.h

@@ -5,9 +5,8 @@
  *    Nucleo F401RE port file. This file contain the implementation of driver
  *    calls for F401RE board.
  *
- *  Created on: May 23, 2020
- *      Author: Christos Choutouridis AEM: 8997
- *      email : <cchoutou@ece.auth.gr>
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
 
 #ifndef NUCLEO_F401RE_H_
@@ -28,7 +27,6 @@ typedef enum {
 }LLD_Status_en;
 
 typedef  uint8_t              din_t;
-//typedef  int                  adc_t;
 
 #define  OFF                  (0)
 #define  ON                   (!OFF)

assignment_3/Libraries/drivers/alcd.c

@@ -3,20 +3,8 @@
  * \brief
  *    A target independent Alpharithmetic LCD driver
  *
- * Copyright (C) 2014 Houtouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 

assignment_3/Libraries/drivers/alcd.h

@@ -3,20 +3,8 @@
  * \brief
  *    A target independent Alpharithmetic LCD driver
  *
- * Copyright (C) 2014 Christos Choutouridis (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 

assignment_3/Libraries/drivers/deque08.c

@@ -3,20 +3,8 @@
  * \brief
  *    This file provides double ended queue capability based on a ring buffer
  *
- * Copyright (C) 2014 Houtouridis Christos <houtouridis.ch@gmail.com>
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #include "deque08.h"

assignment_3/Libraries/drivers/deque08.h

@@ -3,20 +3,8 @@
  * \brief
  *    This file provides double ended queue capability based on a ring buffer
  *
- * Copyright (C) 2014 Houtouridis Christos <houtouridis.ch@gmail.com>
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #ifndef  __deque08_h__

assignment_3/Libraries/drivers/driver_types.h

@@ -1,20 +1,8 @@
 /*!
  * \file driver_types.h
  *
- * Copyright (C) 2020 Choutouridis Christos <cchoutou@ece.auth.gr>
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 

assignment_3/Libraries/drivers/hal.c

@@ -1,20 +1,8 @@
 /*!
  * \file hal.c
  *
- * Copyright (C) 2020 Choutouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #include "hal.h"
@@ -30,7 +18,6 @@ proximity_t    prox;
 
 /*!
  * Initialize all hardware
- * @return
  */
 int hal_hw_init (void) {
    // Init base board
@@ -67,14 +54,17 @@ void lcd_init (void) {
    alcd_init (&alcd, (alcd_funset_en)LCD_FUNSET_2L8);
 }
 
+//! lcd enable wrapper
 __INLINE void lcd_enable (uint8_t en) {
    alcd_enable(&alcd, en);
 }
 
+//!< lcd putchar wrapper
 __INLINE int lcd_putchar (char c) {
    return alcd_putchar(&alcd, c);
 }
 
+//! lcd puts wrapper
 int lcd_puts (const char *s) {
    int i =0;
    while (alcd_putchar(&alcd, *s++))
@@ -91,6 +81,9 @@ __INLINE void led_green (uint8_t en) { LED_GREEN (en); }
 /*
  * ========= Relay ===========
  */
+/*!
+ * Create pulses to re-state reay coil
+ */
 void relay (uint8_t on) {
    switch (on) {
       case 0:
@@ -113,19 +106,23 @@ void relay (uint8_t on) {
 uint8_t ds18b20_rom[8];
 uint8_t zero_rom[8] = {0};
 
+/*!
+ * Initialize temperature measurement system
+ */
 int temp_init (uint8_t resolution) {
    if (!IS_TEMP_RESOLUTION(resolution))
       return 1;
 
+   // link with hardware
    ow_uart_link_rw (&ow, (ow_uart_rw_ft)SHIELD_1W_RW);
    ow_uart_link_br (&ow, (ow_uart_br_ft)SHIELD_1W_UART_BR);
    ow_uart_set_timing (&ow, OW_UART_T_STANDARD);
 
-   ow_uart_init (&ow);
-   ow_uart_search(&ow, ds18b20_rom);
+   ow_uart_init (&ow);              // init
+   ow_uart_search(&ow, ds18b20_rom);// do a search
 
    if (!memcmp ((const void*)ds18b20_rom, (const void*)zero_rom, 8))
-      return 1;
+      return 1;                     // if there is no DS18b20 error
 
    // set resolution to 9-bit
    ow_uart_reset(&ow);
@@ -138,6 +135,9 @@ int temp_init (uint8_t resolution) {
    return 0;
 }
 
+/*!
+ * Temperature read functionality
+ */
 float temp_read (void) {
    uint8_t t[2];
 
@@ -164,11 +164,22 @@ float temp_read (void) {
 /*
  * ========= Proximity ===========
  */
+/*!
+ * Initialize proximity system
+ * \param p    Which proximity object to initialize
+ */
 void proximity_init (proximity_t* p){
    for (int i =0 ; i<PROX_READINGS ; ++i)
       proximity(p);
 }
 
+/*!
+ * Read proximity value in [cm]
+ * \note
+ *    This function also implements an embedded averaging filter
+ * @param p    Which proximity object to use
+ * @return     The measured distance
+ */
 float_t proximity (proximity_t* p){
    float_t ret;
    clock_t t1, t2, mark;
@@ -191,13 +202,14 @@ float_t proximity (proximity_t* p){
          return -1;
    } while  (SHIELD_ECHO());
 
+   // Calculate distance
    SystemCoreClockUpdate();
    uint32_t c_usec = SystemCoreClock / 1000000;
    // Load value
    p->readings[p->iter++] = (c_usec) ? ((t2 - t1)/c_usec) / 58.2 : PROX_MAX_DISTANSE;
    p->iter %= PROX_READINGS;
 
-   // Return filtered distance
+   // Return filtered distance (moving average filter FIR)
    ret =0;
    for (int i=0 ; i<PROX_READINGS ; ++i)
       ret += p->readings[i];

assignment_3/Libraries/drivers/hal.h

@@ -1,20 +1,8 @@
 /*!
  * \file hal.h
  *
- * Copyright (C) 2020 Choutouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #ifndef DRIVERS_HAL_H_

assignment_3/Libraries/drivers/jiffies.c

@@ -1,22 +1,10 @@
-/*
+/*!
  * \file jiffies.c
  * \brief
  *    A target independent jiffy functionality
  *
- * Copyright (C) 2014 Houtouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #include "jiffies.h"

assignment_3/Libraries/drivers/jiffies.h

@@ -1,22 +1,10 @@
-/*
+/*!
  * \file jiffies.h
  * \brief
  *    A target independent jiffy functionality
  *
- * Copyright (C) 2014 Houtouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #ifndef __jiffies_h__

assignment_3/Libraries/drivers/onewire_uart.c

@@ -4,20 +4,8 @@
  *    A target independent 1-wire implementation using a microprocessor's uart
  *    for bit timing
  *
- * Copyright (C) 2015 Choutouridis Christos (http://www.houtouridis.net)
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #include "onewire_uart.h"

assignment_3/Libraries/drivers/onewire_uart.h

@@ -12,20 +12,8 @@
  *    3) A receive function even in blocking/polling mode
  *    4) A baudrate set function
  *
- * Copyright (C) 2016 Choutouridis Christos <cchoutou@ece.auth.gr>
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation, either version 3
- * of the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  *
  */
 #ifndef __onewire_uart_h__

assignment_3/Libraries/drivers/thermostat_shield.c

@@ -5,8 +5,8 @@
  *    Nucleo thermostat shield port file. This file contain the implementation of driver
  *    calls for the shield.
  *
- *      Author: Christos Choutouridis AEM: 8997
- *      email : <cchoutou@ece.auth.gr>
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
 #include "thermostat_shield.h"
 
@@ -29,6 +29,10 @@ static void SHIELD_SR04_Port_Init (void);
  * LCD_EN   -- D14 -- PB9
  * LCD_BL   -- D2  -- PA10
  */
+
+/*!
+ * LCD pin Initialize
+ */
 static void SHIELD_LCD_Port_Init (void) {
    GPIO_InitTypeDef  GPIO_InitType;
 
@@ -56,6 +60,10 @@ void SHIELD_LCD_BL (uint8_t en)  { _DOUTx(GPIOA, GPIO_PIN_10, en); }
  * LED0 -- D4 -- PB5
  * LED1 -- D3 -- PB3
  */
+
+/*!
+ * LED pin initialize
+ */
 static void SHIELD_LED_Port_Init (void) {
    GPIO_InitTypeDef  GPIO_InitType;
 
@@ -74,6 +82,10 @@ void SHIELD_LED1 (uint8_t on) { _DOUTx(GPIOB, GPIO_PIN_3, on); }
  * BR1 -- D10 -- PB6
  * BR2 -- D9  -- PC7
  */
+
+/*!
+ * H-Bridge pin initialize
+ */
 static void SHIELD_BRIDGE_Port_Init (void) {
    GPIO_InitTypeDef  GPIO_InitType;
 
@@ -95,6 +107,10 @@ void SHIELD_BR2 (uint8_t on)  { _DOUTx(GPIOC, GPIO_PIN_7, on); }
  *  TRIG -- D11 -- PA7
  *  ECHO -- D12 -- PA6
  */
+
+/*!
+ * SR04 pin initialize
+ */
 static void SHIELD_SR04_Port_Init (void) {
    GPIO_InitTypeDef  GPIO_InitType;
 
@@ -118,7 +134,7 @@ uint8_t SHIELD_ECHO (void)    { return _DINx (GPIOA, GPIO_PIN_6); }
  *  1W_Tx   -- PA11 (OD+PU)
  *  1W_Rx   -- PA12 (I)
  */
-static UART_HandleTypeDef h1w_uart;
+static UART_HandleTypeDef h1w_uart;    //!< 1-wire uart handle
 
 /*!
  * \brief
@@ -180,7 +196,7 @@ static LLD_Status_en _1W_UART_Init (void) {
 
 
 /*!
- * Init the KEY 1wire interface and allocate all resources for it
+ * Init the 1wire interface and allocate all resources for it
  * \return  The status of the operation
  *    \arg  LLD_OK      Success
  *    \arg  LLD_ERROR   The Init failed.
@@ -308,6 +324,9 @@ uint8_t SHIELD_1W_Tx (uint8_t byte) {
    return 0;
 }
 
+/*!
+ * Shield hardware initialization
+ */
 LLD_Status_en SHIELD_Init (void) {
    SHIELD_LCD_Port_Init ();
    SHIELD_LED_Port_Init ();
@@ -324,9 +343,9 @@ LLD_Status_en SHIELD_Init (void) {
  *  COM_Tx -- PA2 (PP)
  *  COM_Rx -- PA3 (I)
  */
-static UART_HandleTypeDef com_huart;
-static deque08_t  _com_rxq;
-static byte_t     _com_rxbuffer[COM_BUFFER_SIZE];
+static UART_HandleTypeDef com_huart;   //!< com uart handle
+static deque08_t  _com_rxq;            //!< deque object
+static byte_t     _com_rxbuffer[COM_BUFFER_SIZE];  //!< buffer for deque
 
 /*!
  * \brief

assignment_3/Libraries/drivers/thermostat_shield.h

@@ -5,8 +5,8 @@
  *    Nucleo thermostat shield port file. This file contain the implementation of driver
  *    calls for the shield.
  *
- *      Author: Christos Choutouridis AEM: 8997
- *      email : <cchoutou@ece.auth.gr>
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
 
 #ifndef DRIVERS_THERMOSTAT_SHIELD_H_

assignment_3/src/console.c

@@ -1,10 +1,11 @@
-/*
- * console.c
+/*!
+ * \file console.c
+ * \brief
+ *    A simple serial console implementation for out thermostat
  *
- *  Created on: Jun 28, 2020
- *      Author: hoo2
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
-
 #include "console.h"
 
 static char _buffer[COM_BUFFER_SIZE];
@@ -12,6 +13,10 @@ static int  _cursor;
 
 static char _ans[512];
 
+/*!
+ * Parse and respond funcionality for serial console
+ * \param buffer  Pointer to buffer
+ */
 void parse (char* buffer) {
    int i;
    float_t s;
@@ -102,6 +107,9 @@ void parse (char* buffer) {
    COM_Transmit((uint8_t*)_ans, i);
 }
 
+/*!
+ * A simple terminal with echo
+ */
 void console (void) {
    int ch;
 

assignment_3/src/console.h

@@ -1,10 +1,11 @@
-/*
- * console.h
+/*!
+ * \file console.h
+ * \brief
+ *    A simple serial console implementation for out thermostat
  *
- *  Created on: Jun 28, 2020
- *      Author: hoo2
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
-
 #ifndef CONSOLE_H_
 #define CONSOLE_H_
 

assignment_3/src/main.c

@@ -27,6 +27,14 @@ float_t temp_get_current (void) {
    return (app_data.cur) ? app_data.T[app_data.cur-1] : app_data.T[MEASUREMENTS-1];
 }
 
+/*!
+ * Control functionality
+ * Handles:
+ *    * Sensor reading
+ *    * Temp averaging
+ *    * Output calculation
+ * \note    Non-blocking
+ */
 void control (void) {
    static time_t sample =0;
    time_t now = time(0);   // get time
@@ -81,6 +89,11 @@ void control (void) {
    }
 }
 
+/*!
+ * Display functionality
+ * Implement a state machine for lcd display
+ * \note    Non-blocking
+ */
 void display (void) {
    static time_t mark =0;
 
@@ -151,6 +164,10 @@ void display (void) {
    lcd_puts(line2);
 }
 
+/*!
+ * Set outputs
+ * \note    Non-blocking
+ */
 void outputs (void) {
    static uint8_t pr_output =0;
 
@@ -166,7 +183,9 @@ void outputs (void) {
 
 }
 
-
+/*
+ * Main loop
+ */
 int main(void) {
 
    hal_hw_init ();

assignment_3/src/thermostat.h

@@ -1,51 +1,67 @@
-/*
- * thermostat.h
+/*!
+ * \file thermostat.h
+ * \brief
+ *    Application wide data type declarations
  *
- *  Created on: Jun 27, 2020
- *      Author: hoo2
+ * Author: Christos Choutouridis AEM: 8997
+ * email : <cchoutou@ece.auth.gr>
  */
-
 #ifndef THERMOSTAT_H_
 #define THERMOSTAT_H_
 
+/*
+ * Hard coded user settings
+ */
 #define  MEAS_WINDOW       (120)    // [sec]
 #define  MEAS_INTERVAL     (5)      // [sec]
 #define  MEASUREMENTS      (MEAS_WINDOW / MEAS_INTERVAL)    // keep this integer
 #define  UI_AVERAGE_TIME   (10)     // [sec]
 //#define  UI_USER_TIME      (10)
 
-typedef float  float_t;
-typedef int    int_t;
 
+typedef float  float_t;    //!< Select the floating point type for application
+typedef int    int_t;      //!< Select the integer type for application
+
+/*!
+ * Thermostat mode enumerator
+ */
 typedef enum {
-   HEATING =0,
-   COOLING
+   HEATING =0, //!< HEATING
+   COOLING     //!< COOLING
 } mode_en;
 
+/*!
+ * Application common data type
+ */
 typedef struct {
-   float_t  T[MEASUREMENTS];
-   float_t  Tav;
-   uint32_t cur;
-   uint8_t  flag_output;
-   uint8_t  flag_init;
-   uint8_t  flag_proximity;
-   uint8_t  signal_cycle;
+   float_t  T[MEASUREMENTS];  //!< Temperature samples
+   float_t  Tav;              //!< Average temperature
+   uint32_t cur;              //!< Cursor on sample array
+   uint8_t  flag_output;      //!< Momentary flag to indicate the relay state
+   uint8_t  flag_init;        //!< Momentary flag to indicate the end of initialization state
+   uint8_t  flag_proximity;   //!< Momentary flag to indicate that the user is near
+   uint8_t  signal_cycle;     //!< Acknolegable flag to indicate the end of measurement cycle
 } app_data_t;
 
-
+/*!
+ * Settings struct
+ */
 typedef struct {
-   mode_en  mode;
-   float_t  Tset;
-   float_t  Thyst;
-   float_t  Pset;
-   float_t  Physt;
+   mode_en  mode;    //!< Operational mode
+   float_t  Tset;    //!< Target temperature
+   float_t  Thyst;   //!< Target temperature hysteresis
+   float_t  Pset;    //!< Proximity distance
+   float_t  Physt;   //!< Proximity distance hysteresis
 } settings_t;
 
+/*!
+ * User interface states
+ */
 typedef enum {
-   ST_INIT =0,
-   ST_COUNT,
-   ST_AVERAGE,
-   ST_USER
+   ST_INIT =0, //!< ST_INIT:     Still initializing
+   ST_COUNT,   //!< ST_COUNT:    Measurement cycle
+   ST_AVERAGE, //!< ST_AVERAGE:  Display average
+   ST_USER     //!< ST_USER:     Display when a user is near
 } state_en;
 
 /*
@@ -55,6 +71,9 @@ extern app_data_t     app_data;
 extern state_en       state;
 extern settings_t     settings;
 
+/*!
+ * Factory defaults
+ */
 #define _Init_settings(s)  s = { \
       .mode = HEATING,           \
       .Tset = 21.0,              \