docs: Add Doxygen comments to library files

Added Doxygen-style comments to all C source and header files in the
 and  directories. This improves
code documentation and enables VSCode tooltip help.

Additionally, short inline comments were added to all global variables
for better clarity.

software/lib/adc_sensor/adc_sensor.c

@@ -1,3 +1,12 @@
+/**
+ * @file adc_sensor.c
+ * @brief Implementation of the ADC sensor library.
+ *
+ * This file contains the implementation for initializing and reading from ADC sensors.
+ * It currently provides simulated values for voltage and current, with placeholders
+ * for real hardware ADC implementation.
+ */
+
 #include <zephyr/kernel.h>
 #include <zephyr/logging/log.h>
 #include <lib/adc_sensor.h>
@@ -8,7 +17,7 @@ LOG_MODULE_REGISTER(adc_sensor, LOG_LEVEL_INF);
 #define SIMULATED_VOLTAGE_MV 12000
 #define SIMULATED_CURRENT_MA 45
 
-static bool initialized = false;
+static bool initialized = false; // Flag to indicate if the ADC sensor is initialized
 
 int adc_sensor_init(void)
 {

software/lib/fwu/fwu.c

@@ -1,3 +1,13 @@
+/**
+ * @file fwu.c
+ * @brief Implementation of the Firmware Update (FWU) library.
+ *
+ * This file implements the logic for receiving a new firmware image in chunks
+ * over Modbus. It maintains a buffer for the incoming data, calculates the CRC
+ * of the received chunk, and handles commands to verify the chunk and finalize
+ * the update process. The actual writing to flash is simulated.
+ */
+
 #include <zephyr/kernel.h>
 #include <zephyr/sys/crc.h>
 #include <zephyr/sys/byteorder.h>
@@ -7,10 +17,10 @@
 LOG_MODULE_REGISTER(fwu, LOG_LEVEL_INF);
 
 #define FWU_BUFFER_SIZE 256
-static uint8_t fwu_buffer[FWU_BUFFER_SIZE];
-static uint32_t fwu_chunk_offset = 0;
-static uint16_t fwu_chunk_size = 0;
-static uint16_t fwu_last_chunk_crc = 0;
+static uint8_t fwu_buffer[FWU_BUFFER_SIZE]; // Buffer to store incoming firmware data chunks
+static uint32_t fwu_chunk_offset = 0; // Offset for the current firmware chunk in the overall image
+static uint16_t fwu_chunk_size = 0; // Size of the current firmware chunk
+static uint16_t fwu_last_chunk_crc = 0; // CRC16 of the last received firmware chunk
 
 void fwu_init(void) {}
 

software/lib/modbus_server/modbus_server.c

@@ -1,3 +1,12 @@
+/**
+ * @file modbus_server.c
+ * @brief Modbus RTU server implementation for the irrigation system slave node.
+ *
+ * This file implements the Modbus server logic, including register callbacks,
+ * watchdog handling, and dynamic reconfiguration. It interfaces with other
+ * libraries like valve control, ADC sensors, and firmware updates.
+ */
+
 #include <zephyr/kernel.h>
 #include <zephyr/drivers/uart.h>
 #include <zephyr/device.h>
@@ -25,12 +34,27 @@ static struct modbus_iface_param server_param = {
 static uint16_t watchdog_timeout_s = 0;
 static struct k_timer watchdog_timer;
 
+/**
+ * @brief Timer handler for the Modbus watchdog.
+ *
+ * This function is called when the watchdog timer expires, indicating a loss
+ * of communication with the Modbus master. It triggers a fail-safe action,
+ * which is to close the valve.
+ *
+ * @param timer_id Pointer to the timer instance.
+ */
 static void watchdog_timer_handler(struct k_timer *timer_id)
 {
 	LOG_WRN("Modbus watchdog expired! Closing valve as a fail-safe.");
 	valve_close();
 }
 
+/**
+ * @brief Resets the Modbus watchdog timer.
+ *
+ * This function should be called upon receiving any valid Modbus request
+ * to prevent the watchdog from expiring.
+ */
 static inline void reset_watchdog(void)
 {
 	if (watchdog_timeout_s > 0)
@@ -39,6 +63,13 @@ static inline void reset_watchdog(void)
 	}
 }
 
+/**
+ * @brief Callback for reading Modbus holding registers.
+ *
+ * @param addr Register address.
+ * @param reg Pointer to store the read value.
+ * @return 0 on success.
+ */
 static int holding_reg_rd(uint16_t addr, uint16_t *reg)
 {
 	reset_watchdog();
@@ -60,6 +91,13 @@ static int holding_reg_rd(uint16_t addr, uint16_t *reg)
 	return 0;
 }
 
+/**
+ * @brief Callback for writing Modbus holding registers.
+ *
+ * @param addr Register address.
+ * @param reg Value to write.
+ * @return 0 on success.
+ */
 static int holding_reg_wr(uint16_t addr, uint16_t reg)
 {
 	reset_watchdog();
@@ -112,6 +150,13 @@ static int holding_reg_wr(uint16_t addr, uint16_t reg)
 	return 0;
 }
 
+/**
+ * @brief Callback for reading Modbus input registers.
+ *
+ * @param addr Register address.
+ * @param reg Pointer to store the read value.
+ * @return 0 on success.
+ */
 static int input_reg_rd(uint16_t addr, uint16_t *reg)
 {
 	reset_watchdog();
@@ -149,7 +194,7 @@ static int input_reg_rd(uint16_t addr, uint16_t *reg)
 	return 0;
 }
 
-static struct modbus_user_callbacks mbs_cbs = {
+static struct modbus_user_callbacks mbs_cbs = { // Modbus server callback functions
 	.holding_reg_rd = holding_reg_rd,
 	.holding_reg_wr = holding_reg_wr,
 	.input_reg_rd = input_reg_rd,

software/lib/shell_modbus/shell_modbus.c

@@ -1,8 +1,26 @@
+/**
+ * @file shell_modbus.c
+ * @brief Provides shell commands for Modbus and valve configuration.
+ *
+ * This file implements a set of commands for the Zephyr shell to allow
+ * runtime configuration of the Modbus server (baudrate, slave ID) and the
+ * valve (max opening/closing times). The settings are persisted to non-volatile
+ * storage.
+ */
+
 #include <zephyr/shell/shell.h>
 #include <stdlib.h>
 #include <lib/modbus_server.h>
 #include <lib/valve.h>
 
+/**
+ * @brief Shell command to set the Modbus baudrate.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success, -EINVAL on error.
+ */
 static int cmd_modbus_set_baud(const struct shell *sh, size_t argc, char **argv)
 {
 	if (argc != 2) {
@@ -40,6 +58,14 @@ static int cmd_modbus_set_baud(const struct shell *sh, size_t argc, char **argv)
 	return 0;
 }
 
+/**
+ * @brief Shell command to set the Modbus slave ID.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success, -EINVAL on error.
+ */
 static int cmd_modbus_set_id(const struct shell *sh, size_t argc, char **argv)
 {
 	if (argc != 2) {
@@ -63,6 +89,14 @@ static int cmd_modbus_set_id(const struct shell *sh, size_t argc, char **argv)
 	return 0;
 }
 
+/**
+ * @brief Shell command to set the valve's maximum opening time.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success, -EINVAL on error.
+ */
 static int cmd_valve_set_open_time(const struct shell *sh, size_t argc, char **argv)
 {
     if (argc != 2) {
@@ -77,6 +111,14 @@ static int cmd_valve_set_open_time(const struct shell *sh, size_t argc, char **a
     return 0;
 }
 
+/**
+ * @brief Shell command to set the valve's maximum closing time.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success, -EINVAL on error.
+ */
 static int cmd_valve_set_close_time(const struct shell *sh, size_t argc, char **argv)
 {
     if (argc != 2) {
@@ -91,6 +133,14 @@ static int cmd_valve_set_close_time(const struct shell *sh, size_t argc, char **
     return 0;
 }
 
+/**
+ * @brief Shell command to show the current configuration.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success.
+ */
 static int cmd_config_show(const struct shell *sh, size_t argc, char **argv)
 {
 	shell_print(sh, "Current Modbus Configuration:");

software/lib/shell_system/shell_system.c

@@ -1,6 +1,25 @@
+/**
+ * @file shell_system.c
+ * @brief Provides basic system-level shell commands.
+ *
+ * This file implements essential system commands for the Zephyr shell,
+ * such as rebooting the device.
+ */
+
 #include <zephyr/shell/shell.h>
 #include <zephyr/sys/reboot.h>
 
+/**
+ * @brief Shell command to reset the system.
+ *
+ * This command performs a warm reboot of the device after a short delay
+ * to ensure the shell message is printed.
+ *
+ * @param sh The shell instance.
+ * @param argc Argument count.
+ * @param argv Argument values.
+ * @return 0 on success.
+ */
 static int cmd_reset(const struct shell *sh, size_t argc, char **argv)
 {
 	shell_print(sh, "Rebooting system...");

software/lib/valve/valve.c

@@ -1,3 +1,12 @@
+/**
+ * @file valve.c
+ * @brief Implementation of the motorized valve control library.
+ *
+ * This file contains the logic for controlling a motorized valve using a
+ * VND7050AJ high-side driver. It uses a delayed work item to handle the
+ * safety timeouts for opening and closing operations.
+ */
+
 #include <zephyr/kernel.h>
 #include <zephyr/settings/settings.h>
 #include <zephyr/logging/log.h>
@@ -20,8 +29,16 @@ static enum valve_state current_state = VALVE_STATE_CLOSED;
 static enum valve_movement current_movement = VALVE_MOVEMENT_IDLE;
 static uint16_t max_opening_time_s = 60;
 static uint16_t max_closing_time_s = 60;
-static struct k_work_delayable valve_work;
+static struct k_work_delayable valve_work; // Work item for scheduling valve movement timeouts
 
+/**
+ * @brief Work handler for valve movement timeouts.
+ *
+ * This function is executed when the valve's movement timer expires.
+ * It stops the motor to prevent damage and updates the valve's state.
+ * 
+ * @param work Pointer to the k_work item.
+ */
 static void valve_work_handler(struct k_work *work)
 {
     gpio_pin_set_dt(&valve_gpios.in0, 0);