From bc327acc41bdc3776e3f0bd4c7a6fec63479ff99 Mon Sep 17 00:00:00 2001 From: Eduard Iten Date: Tue, 8 Jul 2025 15:48:13 +0200 Subject: [PATCH] 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/include/lib/adc_sensor.h | 31 +++++- software/include/lib/fwu.h | 37 +++++++ software/include/lib/modbus_server.h | 123 +++++++++++++++++++-- software/include/lib/valve.h | 103 +++++++++++++++-- software/lib/adc_sensor/adc_sensor.c | 11 +- software/lib/fwu/fwu.c | 18 ++- software/lib/modbus_server/modbus_server.c | 47 +++++++- software/lib/shell_modbus/shell_modbus.c | 50 +++++++++ software/lib/shell_system/shell_system.c | 19 ++++ software/lib/valve/valve.c | 19 +++- 10 files changed, 427 insertions(+), 31 deletions(-) diff --git a/software/include/lib/adc_sensor.h b/software/include/lib/adc_sensor.h index 21b7d74..5bfff80 100644 --- a/software/include/lib/adc_sensor.h +++ b/software/include/lib/adc_sensor.h @@ -4,23 +4,42 @@ #include /** - * @brief Initialize the ADC sensor system + * @file adc_sensor.h + * @brief API for the ADC sensor library. + * + * This library provides functions to initialize and read from the ADC sensors, + * specifically for measuring supply voltage and motor current. + * It can operate in a real or simulated mode. + */ + +/** + * @brief Initializes the ADC sensor system. + * + * This function sets up the necessary ADC channels and configurations. + * It should be called once before any other function in this library. + * In simulated mode, it logs the simulated values. * - * @return 0 on success, negative error code on failure + * @return 0 on success, or a negative error code on failure. */ int adc_sensor_init(void); /** - * @brief Get supply voltage reading in millivolts + * @brief Gets the current supply voltage reading. + * + * This function reads the value from the corresponding ADC channel and converts + * it to millivolts. * - * @return Voltage in millivolts (currently simulated: 12000mV) + * @return The supply voltage in millivolts (mV). */ uint16_t adc_sensor_get_voltage_mv(void); /** - * @brief Get motor current reading in milliamps + * @brief Gets the current motor current reading. + * + * This function reads the value from the motor driver's sense pin via ADC + * and converts it to milliamps. This is used for end-stop detection. * - * @return Current in milliamps (currently simulated: 45mA) + * @return The motor current in milliamps (mA). */ uint16_t adc_sensor_get_current_ma(void); diff --git a/software/include/lib/fwu.h b/software/include/lib/fwu.h index 4d43214..673a962 100644 --- a/software/include/lib/fwu.h +++ b/software/include/lib/fwu.h @@ -3,8 +3,45 @@ #include +/** + * @file fwu.h + * @brief API for the Firmware Update (FWU) library. + * + * This library provides the core logic for handling the over-the-air firmware + * update process via Modbus. It manages the data buffer, processes commands, + * and calculates CRC checksums for data verification. + */ + +/** + * @brief Initializes the firmware update module. + * + * This function currently does nothing but is a placeholder for future + * initialization logic. + */ void fwu_init(void); + +/** + * @brief Handles incoming Modbus register writes related to firmware updates. + * + * This function is the main entry point for the FWU process. It parses the + * address and value from a Modbus write operation and takes appropriate action, + * such as storing metadata (offset, size) or data chunks, and processing + * commands (verify, finalize). + * + * @param addr The Modbus register address being written to. + * @param reg The 16-bit value being written to the register. + */ void fwu_handler(uint16_t addr, uint16_t reg); + +/** + * @brief Gets the CRC16-CCITT of the last received firmware chunk. + * + * After a data chunk is fully received into the buffer, this function can be + * called to retrieve the calculated CRC checksum. The master can then compare + * this with its own calculated CRC to verify data integrity. + * + * @return The 16-bit CRC of the last chunk. + */ uint16_t fwu_get_last_chunk_crc(void); #endif // FWU_H diff --git a/software/include/lib/modbus_server.h b/software/include/lib/modbus_server.h index 749b79b..d2091d4 100644 --- a/software/include/lib/modbus_server.h +++ b/software/include/lib/modbus_server.h @@ -4,51 +4,156 @@ #include /** - * @brief Modbus Input Register Addresses. + * @file modbus_server.h + * @brief API for the Modbus server implementation. + * + * This file defines the Modbus register map and provides functions to initialize + * and manage the Modbus server. + */ + +/** + * @brief Modbus Input Register Addresses (Read-Only). + * @see docs/modbus-registers.de.md */ enum { - /* Valve Control & Status */ + /** + * @brief Kombiniertes Status-Register für das Ventil. + * High-Byte: Bewegung (0=Idle, 1=Öffnet, 2=Schliesst, 3=Fehler). + * Low-Byte: Zustand (0=Geschlossen, 1=Geöffnet). + */ REG_INPUT_VALVE_STATE_MOVEMENT = 0x0000, + /** + * @brief Aktueller Motorstrom in Milliampere (mA). + */ REG_INPUT_MOTOR_CURRENT_MA = 0x0001, - /* Digital Inputs */ + /** + * @brief Bitmaske der digitalen Eingänge. Bit 0: Eingang 1, Bit 1: Eingang 2. 1=Aktiv. + */ REG_INPUT_DIGITAL_INPUTS_STATE = 0x0020, + /** + * @brief Event-Flags für Taster (Clear-on-Read). Bit 0: Taster 1 gedrückt. Bit 1: Taster 2 gedrückt. + */ REG_INPUT_BUTTON_EVENTS = 0x0021, - /* System Config & Status */ + /** + * @brief Firmware-Version, z.B. 0x0102 für v1.2. + */ REG_INPUT_FIRMWARE_VERSION_MAJOR_MINOR = 0x00F0, + /** + * @brief Firmware-Version Patch-Level, z.B. 3 für v1.2.3. + */ REG_INPUT_FIRMWARE_VERSION_PATCH = 0x00F1, + /** + * @brief Gerätestatus (0=OK, 1=Allgemeiner Fehler). + */ REG_INPUT_DEVICE_STATUS = 0x00F2, + /** + * @brief Untere 16 Bit der Uptime in Sekunden. + */ REG_INPUT_UPTIME_SECONDS_LOW = 0x00F3, + /** + * @brief Obere 16 Bit der Uptime in Sekunden. + */ REG_INPUT_UPTIME_SECONDS_HIGH = 0x00F4, + /** + * @brief Aktuelle Versorgungsspannung in Millivolt (mV). + */ REG_INPUT_SUPPLY_VOLTAGE_MV = 0x00F5, + /** + * @brief CRC16 des zuletzt im Puffer empfangenen Daten-Chunks für das Firmware-Update. + */ REG_INPUT_FWU_LAST_CHUNK_CRC = 0x0100 }; /** - * @brief Modbus Holding Register Addresses. + * @brief Modbus Holding Register Addresses (Read/Write). + * @see docs/modbus-registers.de.md */ enum { - /* Valve Control */ + /** + * @brief Ventilsteuerungsbefehl (1=Öffnen, 2=Schliessen, 0=Bewegung stoppen). + */ REG_HOLDING_VALVE_COMMAND = 0x0000, + /** + * @brief Sicherheits-Timeout in Sekunden für den Öffnen-Vorgang. + */ REG_HOLDING_MAX_OPENING_TIME_S = 0x0001, + /** + * @brief Sicherheits-Timeout in Sekunden für den Schliessen-Vorgang. + */ REG_HOLDING_MAX_CLOSING_TIME_S = 0x0002, - /* Digital Outputs */ + /** + * @brief Bitmaske zum Lesen und Schreiben der digitalen Ausgänge. Bit 0: Ausgang 1, Bit 1: Ausgang 2. 1=AN, 0=AUS. + */ REG_HOLDING_DIGITAL_OUTPUTS_STATE = 0x0010, - /* System Config */ + /** + * @brief Timeout des Fail-Safe-Watchdogs in Sekunden. 0=Deaktiviert. + */ REG_HOLDING_WATCHDOG_TIMEOUT_S = 0x00F0, + /** + * @brief Schreiben von 1 startet das Gerät neu. + */ REG_HOLDING_DEVICE_RESET = 0x00F1, - /* Firmware Update */ + /** + * @brief Befehl für das Firmware-Update. + * 1: Verify Chunk - Slave schreibt den letzten Chunk ins Flash. + * 2: Finalize Update - Installation abschliessen und neu starten. + */ REG_HOLDING_FWU_COMMAND = 0x0100, + /** + * @brief Untere 16 Bit des 32-Bit-Offsets für den nächsten Firmware-Update-Chunk. + */ REG_HOLDING_FWU_CHUNK_OFFSET_LOW = 0x0101, + /** + * @brief Obere 16 Bit des 32-Bit-Offsets für den nächsten Firmware-Update-Chunk. + */ REG_HOLDING_FWU_CHUNK_OFFSET_HIGH = 0x0102, + /** + * @brief Grösse des nächsten Firmware-Update-Chunks in Bytes (max. 256). + */ REG_HOLDING_FWU_CHUNK_SIZE = 0x0103, + /** + * @brief Startadresse des 256-Byte-Puffers für Firmware-Update-Daten. + */ REG_HOLDING_FWU_DATA_BUFFER = 0x0180, }; +/** + * @brief Initializes the Modbus server. + * + * This function sets up the Modbus RTU server interface, loads saved settings + * (baudrate, unit ID), and starts listening for requests. + * + * @return 0 on success, or a negative error code on failure. + */ int modbus_server_init(void); + +/** + * @brief Reconfigures the Modbus server at runtime. + * + * Updates the baudrate and unit ID of the server. If the reconfiguration + * fails, the settings are saved and will be applied after a device reset. + * + * @param baudrate The new baudrate to set. + * @param unit_id The new Modbus unit ID (slave address). + * @return 0 on success, or a negative error code if immediate reconfiguration fails. + * Returns 0 even on failure if settings could be saved for the next boot. + */ int modbus_reconfigure(uint32_t baudrate, uint8_t unit_id); + +/** + * @brief Gets the current baudrate of the Modbus server. + * + * @return The current baudrate. + */ uint32_t modbus_get_baudrate(void); + +/** + * @brief Gets the current unit ID of the Modbus server. + * + * @return The current unit ID. + */ uint8_t modbus_get_unit_id(void); #endif // MODBUS_SERVER_H diff --git a/software/include/lib/valve.h b/software/include/lib/valve.h index 373215d..17f6b56 100644 --- a/software/include/lib/valve.h +++ b/software/include/lib/valve.h @@ -4,33 +4,118 @@ #include #include +/** + * @file valve.h + * @brief API for controlling the motorized valve. + * + * This library provides functions to initialize, open, close, and stop the valve. + * It also allows getting the valve's state and movement status, and configuring + * the maximum opening and closing times. + */ + +/** + * @brief Defines the GPIO pins used for the valve controller. + */ struct valve_gpios { - const struct gpio_dt_spec in0; - const struct gpio_dt_spec in1; - const struct gpio_dt_spec rst; - const struct gpio_dt_spec sen; - const struct gpio_dt_spec s0; - const struct gpio_dt_spec s1; + const struct gpio_dt_spec in0; /**< Control input 0 for the VND7050AJ driver. */ + const struct gpio_dt_spec in1; /**< Control input 1 for the VND7050AJ driver. */ + const struct gpio_dt_spec rst; /**< Reset pin for the VND7050AJ driver. */ + const struct gpio_dt_spec sen; /**< Sense (current measurement) pin. */ + const struct gpio_dt_spec s0; /**< S0 select pin. */ + const struct gpio_dt_spec s1; /**< S1 select pin. */ }; +/** + * @brief Represents the static state of the valve (open or closed). + */ enum valve_state { - VALVE_STATE_CLOSED, - VALVE_STATE_OPEN, + VALVE_STATE_CLOSED, /**< The valve is fully closed. */ + VALVE_STATE_OPEN, /**< The valve is fully open. */ }; -enum valve_movement { VALVE_MOVEMENT_IDLE, VALVE_MOVEMENT_OPENING, VALVE_MOVEMENT_CLOSING, VALVE_MOVEMENT_ERROR }; +/** + * @brief Represents the dynamic movement status of the valve. + */ +enum valve_movement { + VALVE_MOVEMENT_IDLE, /**< The valve is not moving. */ + VALVE_MOVEMENT_OPENING, /**< The valve is currently opening. */ + VALVE_MOVEMENT_CLOSING, /**< The valve is currently closing. */ + VALVE_MOVEMENT_ERROR /**< An error occurred during movement. */ +}; + +/** + * @brief Initializes the valve control system. + * + * Configures the GPIOs and loads saved settings for timeouts. + */ void valve_init(void); + +/** + * @brief Starts opening the valve. + * + * The valve will open for the configured maximum opening time. + */ void valve_open(void); + +/** + * @brief Starts closing the valve. + * + * The valve will close for the configured maximum closing time. + */ void valve_close(void); + +/** + * @brief Stops any ongoing valve movement immediately. + */ void valve_stop(void); +/** + * @brief Gets the current static state of the valve. + * + * @return The current valve state (VALVE_STATE_CLOSED or VALVE_STATE_OPEN). + */ enum valve_state valve_get_state(void); + +/** + * @brief Gets the current movement status of the valve. + * + * @return The current movement status. + */ enum valve_movement valve_get_movement(void); + +/** + * @brief Gets the motor current. + * + * @return The motor current in milliamps (currently simulated). + */ uint16_t valve_get_motor_current(void); +/** + * @brief Sets the maximum time for the valve to open. + * + * @param seconds The timeout in seconds. + */ void valve_set_max_open_time(uint16_t seconds); + +/** + * @brief Sets the maximum time for the valve to close. + * + * @param seconds The timeout in seconds. + */ void valve_set_max_close_time(uint16_t seconds); + +/** + * @brief Gets the configured maximum opening time. + * + * @return The timeout in seconds. + */ uint16_t valve_get_max_open_time(void); + +/** + * @brief Gets the configured maximum closing time. + * + * @return The timeout in seconds. + */ uint16_t valve_get_max_close_time(void); #endif // VALVE_H diff --git a/software/lib/adc_sensor/adc_sensor.c b/software/lib/adc_sensor/adc_sensor.c index c9a789e..48e8c39 100644 --- a/software/lib/adc_sensor/adc_sensor.c +++ b/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 #include #include @@ -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) { diff --git a/software/lib/fwu/fwu.c b/software/lib/fwu/fwu.c index 27a600f..fd7d7e4 100644 --- a/software/lib/fwu/fwu.c +++ b/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 #include #include @@ -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) {} diff --git a/software/lib/modbus_server/modbus_server.c b/software/lib/modbus_server/modbus_server.c index 9514ce8..ca1fc5c 100644 --- a/software/lib/modbus_server/modbus_server.c +++ b/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 #include #include @@ -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, diff --git a/software/lib/shell_modbus/shell_modbus.c b/software/lib/shell_modbus/shell_modbus.c index d722752..d377da3 100644 --- a/software/lib/shell_modbus/shell_modbus.c +++ b/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 #include #include #include +/** + * @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:"); diff --git a/software/lib/shell_system/shell_system.c b/software/lib/shell_system/shell_system.c index 99dfb24..e339079 100644 --- a/software/lib/shell_system/shell_system.c +++ b/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 #include +/** + * @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..."); diff --git a/software/lib/valve/valve.c b/software/lib/valve/valve.c index 113874e..f281bb3 100644 --- a/software/lib/valve/valve.c +++ b/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 #include #include @@ -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);