Create documentation

code/rafting-button/.gitignore

@@ -1,4 +1,6 @@
 .vscode/*
+doc/html/*
+doc/latex/*
 # Created by https://www.toptal.com/developers/gitignore/api/cmake
 # Edit at https://www.toptal.com/developers/gitignore?templates=cmake
 

code/rafting-button/components/espnow_utils/espnow_utils.c

@@ -1,3 +1,17 @@
+/**
+ * @file espnow_utils.c
+ * @brief Contains supported functions for the ESP-NOW protocol.
+ * @details This file provides functions for initializing and deinitializing
+ * ESP-NOW, initializing Wi-Fi, printing the device's MAC address, and comparing
+ * MAC addresses.
+ * @version 1.0
+ * @date 2023-06-08
+ * @author Petr Kucera (kucerp28@fel.cvut.cz)
+ *
+ * @note This code is subject to the terms of the MIT license.
+ *
+ */
+
 #include "espnow_utils.h"
 #include "peripheral.h"
 #include <esp_log.h>
@@ -14,28 +28,31 @@ static const char *TAG = "ESPNOW_UTILS";
 
 void wifi_init(void)
 {
-   ESP_ERROR_CHECK(esp_netif_init()); // init  TCP/IP stack layer
+   // 1. Initialize TCP/IP stack layer
+   ESP_ERROR_CHECK(esp_netif_init());
 
-   // create loop for system task like Wi-Fi
+   // 2. Create a loop for system tasks like Wi-Fi
    ESP_ERROR_CHECK(esp_event_loop_create_default());
 
+   // 3. Initialize Wi-Fi with default configuration
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
-   ESP_ERROR_CHECK(esp_wifi_init(&cfg)); // init Wi-Fi with default conf
+   ESP_ERROR_CHECK(esp_wifi_init(&cfg));
 
+   // 4. Set storage
    ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_RAM));
 
-   // Set current WiFi power save type
+   // 5. Set current WiFi power save type
    ESP_ERROR_CHECK(esp_wifi_set_ps(WIFI_PS_NONE));
 
+   // 6. Set Wi-Fi mode
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_start());
    // ESP_ERROR_CHECK(esp_wifi_set_channel())
 }
 
 esp_err_t custom_espnow_init(void)
 {
-
-   // Initialzie ESP-NOW
+   // Initialize ESP-NOW
    ESP_ERROR_CHECK(esp_now_init());
 
    return ESP_OK;
@@ -52,7 +69,7 @@ void print_mac_address()
 {
    uint8_t mac_addr[6];
    ESP_ERROR_CHECK(esp_read_mac(mac_addr, ESP_MAC_BASE));
-   ESP_LOGI(TAG, "Device MAC addres is: " MACSTR "\n", MAC2STR(mac_addr));
+   ESP_LOGI(TAG, "Device MAC address is: " MACSTR "\n", MAC2STR(mac_addr));
 }
 
 uint8_t is_device_mac(uint8_t *mac_addr)
@@ -61,16 +78,16 @@ uint8_t is_device_mac(uint8_t *mac_addr)
    ESP_ERROR_CHECK(esp_read_mac(tmp, ESP_MAC_BASE));
    for (uint8_t i = 0; i < 6; ++i) {
       if (tmp[i] != mac_addr[i])
-         return 0;
+         return FALSE;
    }
-   return 1;
+   return TRUE;
 }
 
 uint8_t is_same_mac(uint8_t *mac_1, uint8_t *mac_2)
 {
    for (uint8_t i = 0; i < ESP_NOW_ETH_ALEN; ++i) {
       if (mac_1[i] != mac_2[i])
-         return 0;
+         return FALSE;
    }
-   return 1;
+   return TRUE;
 }

code/rafting-button/components/espnow_utils/espnow_utils.h

@@ -1,3 +1,17 @@
+/**
+ * @file espnow_utils.h
+ * @brief Contains functions for working with the ESP-NOW protocol.
+ * @details This file provides functions for initializing and deinitializing
+ * ESP-NOW, initializing Wi-Fi for ESP-NOW, printing the device's MAC address,
+ * and comparing MAC addresses.
+ * @version 1.0
+ * @date 2023-06-08
+ * @author Petr Kucera (kucerp28@fel.cvut.cz)
+ *
+ * @note This code is subject to the terms of the MIT license.
+ *
+ */
+
 #ifndef ESPNOW_UTILS_H
 #define ESPNOW_UTILS_H
 
@@ -8,30 +22,43 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
-typedef struct {
-   uint8_t sender_mac_addr[6];
-   uint8_t is_empty;
-   char data[250];
-   uint8_t data_lenght;
-} espnow_data_t;
-
 /**
- * @brief Initialize Wi-Fi for ESP-NOW
- *
+ * @brief Initializes Wi-Fi for ESP-NOW.
  */
 void wifi_init(void);
 
 /**
- * @brief Initialize ESP-NOW
- *
- * @return esp_err_t
+ * @brief Initializes ESP-NOW.
+ * @return esp_err_t The result of the initialization.
  */
 esp_err_t custom_espnow_init(void);
 
+/**
+ * @brief Deinitializes ESP-NOW.
+ * @return esp_err_t The result of the deinitialization.
+ */
 esp_err_t custom_espnow_deinit(void);
 
+/**
+ * @brief Prints the MAC address of the device.
+ */
 void print_mac_address();
+
+/**
+ * @brief Compares the device's MAC address with the provided address.
+ * @param mac_addr The MAC address to compare with the device's address.
+ * @return uint8_t Logic value indicating if the addresses match (1 - true, 0 -
+ * false).
+ */
 uint8_t is_device_mac(uint8_t *mac_addr);
+
+/**
+ * @brief Compares two MAC addresses.
+ * @param mac_1 The first MAC address to compare.
+ * @param mac_2 The second MAC address to compare.
+ * @return uint8_t Logic value indicating if the addresses match (1 - true, 0 -
+ * false).
+ */
 uint8_t is_same_mac(uint8_t *mac_1, uint8_t *mac_2);
 
-#endif // ESPNOW_UTILS_H
+#endif // ESPNOW_UTILS_H

code/rafting-button/components/peripheral/peripheral.c

@@ -1,3 +1,14 @@
+/**
+ * @file peripheral.c
+ * @brief Contains functions for basic manipulation with peripherals.
+ * @version 1.0
+ * @date 2023-06-08
+ * @author Petr Kucera (kucerp28@fel.cvut.cz)
+ *
+ * @note This code is subject to the terms of the MIT license.
+ *
+ */
+
 #include "peripheral.h"
 #include <driver/gpio.h>
 #include <freertos/FreeRTOS.h>
@@ -6,18 +17,19 @@
 
 void config_led(gpio_num_t gpio_num)
 {
-   // Set up mode
+   // Set up GPIO direction as output
    gpio_set_direction(gpio_num, GPIO_MODE_OUTPUT);
 }
 
 void turn_on_led(gpio_num_t gpio_num)
 {
-   // Turn on GPIO output
+   // Set GPIO output level to HIGH (1)
    gpio_set_level(gpio_num, 1);
 }
+
 void turn_off_led(gpio_num_t gpio_num)
 {
-   // Turn off GPIO output
+   // Set GPIO output level to LOW (0)
    gpio_set_level(gpio_num, 0);
 }
 
@@ -26,9 +38,10 @@ void turn_on_buildin_led()
    gpio_set_direction(GPIO_NUM_2, GPIO_MODE_OUTPUT);
    gpio_set_level(GPIO_NUM_2, 1);
 }
+
 void turn_off_buildin_led() { gpio_set_level(GPIO_NUM_2, 0); }
 
-void do_blick_task(uint16_t mils)
+void do_blink_task(uint16_t mils)
 {
    config_led(GPIO_NUM_23);
    turn_on_led(GPIO_NUM_23);
@@ -42,7 +55,7 @@ void do_blick_task(uint16_t mils)
    vTaskDelete(NULL);
 }
 
-void do_blick(uint16_t mils)
+void do_blink(uint16_t mils)
 {
    turn_on_led(GPIO_NUM_23);
    turn_on_buildin_led();

code/rafting-button/components/peripheral/peripheral.h

@@ -1,52 +1,74 @@
+/**
+ * @file peripheral.h
+ * @brief Defines functions for basic manipulation with peripherals.
+ * @details This file provides functions for configuring and controlling GPIO
+ * for LED diodes, including the built-in LED. It also includes functions for
+ * blinking LEDs and controlling LEDs as tasks.
+ * @version 1.0
+ * @date 2023-06-08
+ * @author Petr Kucera (kucerp28@fel.cvut.cz)
+ *
+ * @note This code is subject to the terms of the MIT license.
+ *
+ */
+
 #ifndef PERIPHERAL_H
 #define PERIPHERAL_H
 
 #include <driver/gpio.h>
 
 /**
- * @brief Configure GPIO for led diode
- *
- * @param gpio_num GPIO number
+ * @brief Configures GPIO for an LED diode.
+ * @param gpio_num The GPIO number to configure.
  */
 void config_led(gpio_num_t gpio_num);
 
 /**
- * @brief Turn on GPIO output for LED diode
- *
- * @param gpio_num GPIO number
+ * @brief Turns on the GPIO output for an LED diode.
+ * @param gpio_num The GPIO number of the LED diode.
  */
 void turn_on_led(gpio_num_t gpio_num);
 
 /**
- * @brief Turn off GPIO output for LED diode
- *
- * @param gpio_num GPIO number
+ * @brief Turns off the GPIO output for an LED diode.
+ * @param gpio_num The GPIO number of the LED diode.
  */
 void turn_off_led(gpio_num_t gpio_num);
 
 /**
- * @brief Configure GPIO and turn on built-in LED diode
- *
+ * @brief Configures GPIO and turns on the built-in LED diode.
  */
-void turn_on_buildin_led();
+void turn_on_builtin_led();
 
 /**
- * @brief Turn off built-in LED diode
- *
+ * @brief Turns off the built-in LED diode.
  */
-void turn_off_buildin_led();
+void turn_off_builtin_led();
 
 /**
- * @brief Do blick by buildin LED and on GPIO23
- *
- * @param mils time of blick in miliseconds
+ * @brief Blinks the built-in LED and a specified GPIO as a task.
+ * @param mils The duration of each blink in milliseconds.
  */
-void do_blick_task(uint16_t mils);
+void do_blink_task(uint16_t mils);
 
-void do_blick(uint16_t mils);
+/**
+ * @brief Blinks the built-in LED and a specified GPIO.
+ * @param mils The duration of each blink in milliseconds.
+ */
+void do_blink(uint16_t mils);
 
+/**
+ * @brief Turns on the built-in LED and an LED connected to the specified GPIO
+ * as a task.
+ * @param gpio_num The GPIO number of the LED.
+ */
 void turn_on_led_task(gpio_num_t gpio_num);
 
+/**
+ * @brief Turns off the built-in LED and an LED connected to the specified GPIO
+ * as a task.
+ * @param gpio_num The GPIO number of the LED.
+ */
 void turn_off_led_task(gpio_num_t gpio_num);
 
-#endif // PERIPHERAL_H
+#endif // PERIPHERAL_H