docs(slave_node): Add Doxygen comments to main.c
- Add Doxygen-compliant comments to functions, enums, and state variables in `main.c`. - This provides a foundation for automatically generating source code documentation. - Remove the separate, now redundant, `firmware-manual.de.md` file.
This commit is contained in:
@@ -1,8 +1,13 @@
|
||||
/*
|
||||
* Copyright (c) 2020 PHYTEC Messtechnik GmbH
|
||||
* Copyright (c) 2022 Nordic Semiconductor ASA
|
||||
/**
|
||||
* @file main.c
|
||||
* @brief Main application for the Irrigation System Slave Node.
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
* This file contains the main logic for the Modbus RTU slave node, including
|
||||
* valve control, digital I/O, system status, and a simulated firmware update process.
|
||||
*
|
||||
* @copyright Copyright (c) 2020 PHYTEC Messtechnik GmbH
|
||||
* @copyright Copyright (c) 2022 Nordic Semiconductor ASA
|
||||
* @license SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
#include <zephyr/kernel.h>
|
||||
@@ -23,49 +28,72 @@ LOG_MODULE_REGISTER(mbs_sample, LOG_LEVEL_INF);
|
||||
#define APP_VERSION_MINOR 0
|
||||
#define APP_VERSION_PATCH 0
|
||||
|
||||
/* Register Definitions from Documentation */
|
||||
/**
|
||||
* @brief Modbus Input Register Addresses.
|
||||
*/
|
||||
enum {
|
||||
REG_INPUT_VALVE_STATE_MOVEMENT = 0x0000, REG_INPUT_MOTOR_CURRENT_MA = 0x0001,
|
||||
REG_INPUT_DIGITAL_INPUTS_STATE = 0x0020, REG_INPUT_BUTTON_EVENTS = 0x0021,
|
||||
REG_INPUT_FIRMWARE_VERSION_MAJOR_MINOR = 0x00F0, REG_INPUT_FIRMWARE_VERSION_PATCH = 0x00F1,
|
||||
REG_INPUT_DEVICE_STATUS = 0x00F2, REG_INPUT_UPTIME_SECONDS_LOW = 0x00F3,
|
||||
REG_INPUT_UPTIME_SECONDS_HIGH = 0x00F4, REG_INPUT_FWU_LAST_CHUNK_CRC = 0x0100,
|
||||
};
|
||||
enum {
|
||||
REG_HOLDING_VALVE_COMMAND = 0x0000, REG_HOLDING_MAX_OPENING_TIME_S = 0x0001,
|
||||
REG_HOLDING_MAX_CLOSING_TIME_S = 0x0002, REG_HOLDING_DIGITAL_OUTPUTS_STATE = 0x0010,
|
||||
REG_HOLDING_WATCHDOG_TIMEOUT_S = 0x00F0, REG_HOLDING_FWU_COMMAND = 0x0100,
|
||||
REG_HOLDING_FWU_CHUNK_OFFSET_LOW = 0x0101, REG_HOLDING_FWU_CHUNK_OFFSET_HIGH = 0x0102,
|
||||
REG_HOLDING_FWU_CHUNK_SIZE = 0x0103, REG_HOLDING_FWU_DATA_BUFFER = 0x0180,
|
||||
/* Valve Control & Status */
|
||||
REG_INPUT_VALVE_STATE_MOVEMENT = 0x0000,
|
||||
REG_INPUT_MOTOR_CURRENT_MA = 0x0001,
|
||||
/* Digital Inputs */
|
||||
REG_INPUT_DIGITAL_INPUTS_STATE = 0x0020,
|
||||
REG_INPUT_BUTTON_EVENTS = 0x0021,
|
||||
/* System Config & Status */
|
||||
REG_INPUT_FIRMWARE_VERSION_MAJOR_MINOR = 0x00F0,
|
||||
REG_INPUT_FIRMWARE_VERSION_PATCH = 0x00F1,
|
||||
REG_INPUT_DEVICE_STATUS = 0x00F2,
|
||||
REG_INPUT_UPTIME_SECONDS_LOW = 0x00F3,
|
||||
REG_INPUT_UPTIME_SECONDS_HIGH = 0x00F4,
|
||||
/* Firmware Update */
|
||||
REG_INPUT_FWU_LAST_CHUNK_CRC = 0x0100,
|
||||
};
|
||||
|
||||
/* Valve Simulation */
|
||||
/**
|
||||
* @brief Modbus Holding Register Addresses.
|
||||
*/
|
||||
enum {
|
||||
/* Valve Control */
|
||||
REG_HOLDING_VALVE_COMMAND = 0x0000,
|
||||
REG_HOLDING_MAX_OPENING_TIME_S = 0x0001,
|
||||
REG_HOLDING_MAX_CLOSING_TIME_S = 0x0002,
|
||||
/* Digital Outputs */
|
||||
REG_HOLDING_DIGITAL_OUTPUTS_STATE = 0x0010,
|
||||
/* System Config */
|
||||
REG_HOLDING_WATCHDOG_TIMEOUT_S = 0x00F0,
|
||||
/* Firmware Update */
|
||||
REG_HOLDING_FWU_COMMAND = 0x0100,
|
||||
REG_HOLDING_FWU_CHUNK_OFFSET_LOW = 0x0101,
|
||||
REG_HOLDING_FWU_CHUNK_OFFSET_HIGH = 0x0102,
|
||||
REG_HOLDING_FWU_CHUNK_SIZE = 0x0103,
|
||||
REG_HOLDING_FWU_DATA_BUFFER = 0x0180,
|
||||
};
|
||||
|
||||
/** @brief Represents the physical state of the valve. */
|
||||
enum valve_state { VALVE_STATE_CLOSED, VALVE_STATE_OPEN };
|
||||
/** @brief Represents the current movement of the valve. */
|
||||
enum valve_movement { VALVE_MOVEMENT_IDLE, VALVE_MOVEMENT_OPENING, VALVE_MOVEMENT_CLOSING, VALVE_MOVEMENT_ERROR };
|
||||
|
||||
/* --- State Variables --- */
|
||||
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;
|
||||
|
||||
/* Digital I/O State */
|
||||
static uint16_t digital_outputs_state = 0;
|
||||
static uint16_t digital_inputs_state = 0;
|
||||
static uint16_t button_events = 0;
|
||||
|
||||
/* System State & Watchdog */
|
||||
static uint16_t device_status = 0; // 0 = OK
|
||||
static uint16_t device_status = 0;
|
||||
static uint16_t watchdog_timeout_s = 0;
|
||||
static struct k_timer watchdog_timer;
|
||||
|
||||
/* Firmware Update State */
|
||||
#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;
|
||||
|
||||
/* Modbus Configuration */
|
||||
static int modbus_iface;
|
||||
static struct modbus_iface_param server_param = {
|
||||
.mode = MODBUS_MODE_RTU,
|
||||
@@ -73,6 +101,12 @@ static struct modbus_iface_param server_param = {
|
||||
.serial = { .baud = 19200, .parity = UART_CFG_PARITY_NONE },
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Triggers the closing of the valve.
|
||||
*
|
||||
* If the valve is currently open, this function initiates the closing movement
|
||||
* and schedules the completion via the valve_work handler.
|
||||
*/
|
||||
static void close_valve_action(void)
|
||||
{
|
||||
if (current_state == VALVE_STATE_OPEN) {
|
||||
@@ -81,12 +115,26 @@ static void close_valve_action(void)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Watchdog timer expiration handler.
|
||||
*
|
||||
* This function is called by the kernel when the Modbus watchdog timer expires.
|
||||
* It triggers the fail-safe action of closing the valve.
|
||||
*
|
||||
* @param timer_id Pointer to the timer instance that expired.
|
||||
*/
|
||||
static void watchdog_timer_handler(struct k_timer *timer_id)
|
||||
{
|
||||
LOG_WRN("Modbus watchdog expired! Closing valve as a fail-safe.");
|
||||
close_valve_action();
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Resets the Modbus communication watchdog timer.
|
||||
*
|
||||
* This function should be called on any valid Modbus communication to prevent
|
||||
* the fail-safe timeout from occurring.
|
||||
*/
|
||||
static inline void reset_watchdog(void)
|
||||
{
|
||||
if (watchdog_timeout_s > 0) {
|
||||
@@ -94,6 +142,14 @@ static inline void reset_watchdog(void)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Work handler for completing valve movement.
|
||||
*
|
||||
* This function is called from a workqueue to finalize the state of the valve
|
||||
* after a time-based movement simulation has completed.
|
||||
*
|
||||
* @param work Pointer to the work item.
|
||||
*/
|
||||
static void valve_work_handler(struct k_work *work)
|
||||
{
|
||||
if (current_movement == VALVE_MOVEMENT_OPENING) {
|
||||
@@ -105,6 +161,12 @@ static void valve_work_handler(struct k_work *work)
|
||||
current_movement = VALVE_MOVEMENT_IDLE;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Modbus callback for reading holding registers.
|
||||
* @param addr Register address.
|
||||
* @param reg Pointer to store the read value.
|
||||
* @return 0 on success, negative error code otherwise.
|
||||
*/
|
||||
static int holding_reg_rd(uint16_t addr, uint16_t *reg)
|
||||
{
|
||||
reset_watchdog();
|
||||
@@ -118,6 +180,12 @@ static int holding_reg_rd(uint16_t addr, uint16_t *reg)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Modbus callback for writing holding registers.
|
||||
* @param addr Register address.
|
||||
* @param reg Value to write.
|
||||
* @return 0 on success, negative error code otherwise.
|
||||
*/
|
||||
static int holding_reg_wr(uint16_t addr, uint16_t reg)
|
||||
{
|
||||
reset_watchdog();
|
||||
@@ -181,6 +249,12 @@ static int holding_reg_wr(uint16_t addr, uint16_t reg)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Modbus callback for reading input registers.
|
||||
* @param addr Register address.
|
||||
* @param reg Pointer to store the read value.
|
||||
* @return 0 on success, negative error code otherwise.
|
||||
*/
|
||||
static int input_reg_rd(uint16_t addr, uint16_t *reg)
|
||||
{
|
||||
reset_watchdog();
|
||||
@@ -216,7 +290,27 @@ void valve_set_max_open_time(uint16_t seconds) { max_opening_time_s = seconds; s
|
||||
void valve_set_max_close_time(uint16_t seconds) { max_closing_time_s = seconds; settings_save_one("valve/max_close_time", &max_closing_time_s, sizeof(max_closing_time_s)); }
|
||||
uint16_t valve_get_max_open_time(void) { return max_opening_time_s; }
|
||||
uint16_t valve_get_max_close_time(void) { return max_closing_time_s; }
|
||||
static int settings_load_cb(const char *name, size_t len, settings_read_cb read_cb, void *cb_arg) { /* ... */ return -ENOENT; }
|
||||
static int settings_load_cb(const char *name, size_t len, settings_read_cb read_cb, void *cb_arg) {
|
||||
const char *next;
|
||||
int rc;
|
||||
if (settings_name_steq(name, "baudrate", &next) && !next) {
|
||||
rc = read_cb(cb_arg, &server_param.serial.baud, sizeof(server_param.serial.baud));
|
||||
return (rc < 0) ? rc : 0;
|
||||
}
|
||||
if (settings_name_steq(name, "unit_id", &next) && !next) {
|
||||
rc = read_cb(cb_arg, &server_param.server.unit_id, sizeof(server_param.server.unit_id));
|
||||
return (rc < 0) ? rc : 0;
|
||||
}
|
||||
if (settings_name_steq(name, "max_open_time", &next) && !next) {
|
||||
rc = read_cb(cb_arg, &max_opening_time_s, sizeof(max_opening_time_s));
|
||||
return (rc < 0) ? rc : 0;
|
||||
}
|
||||
if (settings_name_steq(name, "max_close_time", &next) && !next) {
|
||||
rc = read_cb(cb_arg, &max_closing_time_s, sizeof(max_closing_time_s));
|
||||
return (rc < 0) ? rc : 0;
|
||||
}
|
||||
return -ENOENT;
|
||||
}
|
||||
SETTINGS_STATIC_HANDLER_DEFINE(modbus, "modbus", NULL, settings_load_cb, NULL, NULL);
|
||||
SETTINGS_STATIC_HANDLER_DEFINE(valve, "valve", NULL, settings_load_cb, NULL, NULL);
|
||||
|
||||
@@ -229,6 +323,14 @@ static int init_modbus_server(void)
|
||||
return modbus_init_server(modbus_iface, server_param);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Main entry point for the application.
|
||||
*
|
||||
* Initializes all subsystems including Modbus, settings, and timers,
|
||||
* then enters an idle state.
|
||||
*
|
||||
* @return 0 on success, negative error code otherwise.
|
||||
*/
|
||||
int main(void)
|
||||
{
|
||||
LOG_INF("Starting Irrigation System Slave Node");
|
||||
@@ -247,4 +349,4 @@ int main(void)
|
||||
|
||||
LOG_INF("Irrigation System Slave Node started successfully");
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user