irrigation_system/software/include/lib/modbus_server.h

#ifndef MODBUS_SERVER_H
#define MODBUS_SERVER_H

#include <stdint.h>

/**
 * @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 {
	/**
	 * @brief Combined status register for the valve.
	 * High-Byte: Movement (0=Idle, 1=Opening, 2=Closing, 3=Error).
	 * Low-Byte: State (0=Closed, 1=Open).
	 */
	REG_INPUT_VALVE_STATE_MOVEMENT = 0x0000,
	/**
	 * @brief Motor current during opening in milliamperes (mA).
	 */
	REG_INPUT_MOTOR_OPEN_CURRENT_MA = 0x0001,
	/**
	 * @brief Motor current during closing in milliamperes (mA).
	 */
	REG_INPUT_MOTOR_CLOSE_CURRENT_MA = 0x0002,
	/**
	 * @brief Bitmask of digital inputs. Bit 0: Input 1, Bit 1: Input 2.
	 * 1=Active.
	 */
	REG_INPUT_DIGITAL_INPUTS_STATE = 0x0020,
	/**
	 * @brief Event flags for buttons (Clear-on-Read). Bit 0: Button 1 pressed.
	 * Bit 1: Button 2 pressed.
	 */
	REG_INPUT_BUTTON_EVENTS = 0x0021,
	/**
	 * @brief Firmware version, e.g., 0x0102 for v1.2.
	 */
	REG_INPUT_FIRMWARE_VERSION_MAJOR_MINOR = 0x00F0,
	/**
	 * @brief Firmware version patch level, e.g., 3 for v1.2.3.
	 */
	REG_INPUT_FIRMWARE_VERSION_PATCH = 0x00F1,
	/**
	 * @brief Device status (0=OK, 1=General Error).
	 */
	REG_INPUT_DEVICE_STATUS = 0x00F2,
	/**
	 * @brief Lower 16 bits of uptime in seconds.
	 */
	REG_INPUT_UPTIME_SECONDS_LOW = 0x00F3,
	/**
	 * @brief Upper 16 bits of uptime in seconds.
	 */
	REG_INPUT_UPTIME_SECONDS_HIGH = 0x00F4,
	/**
	 * @brief Current supply voltage in millivolts (mV).
	 */
	REG_INPUT_SUPPLY_VOLTAGE_MV = 0x00F5,
	/**
	 * @brief CRC16 of the last received data chunk in the buffer for firmware
	 * update.
	 */
	REG_INPUT_FWU_LAST_CHUNK_CRC = 0x0100
};

/**
 * @brief Modbus Holding Register Addresses (Read/Write).
 * @see docs/modbus-registers.de.md
 */
enum {
	/**
	 * @brief Valve control command (1=Open, 2=Close, 0=Stop movement).
	 */
	REG_HOLDING_VALVE_COMMAND = 0x0000,
	/**
	 * @brief Safety timeout in seconds for the opening process.
	 */
	REG_HOLDING_MAX_OPENING_TIME_S = 0x0001,
	/**
	 * @brief Safety timeout in seconds for the closing process.
	 */
	REG_HOLDING_MAX_CLOSING_TIME_S = 0x0002,
	/**
	 * @brief Bitmask for reading and writing digital outputs. Bit 0: Output 1,
	 * Bit 1: Output 2. 1=ON, 0=OFF.
	 */
	REG_HOLDING_DIGITAL_OUTPUTS_STATE = 0x0010,
	/**
	 * @brief Fail-safe watchdog timeout in seconds. 0=Disabled.
	 */
	REG_HOLDING_WATCHDOG_TIMEOUT_S = 0x00F0,
	/**
	 * @brief Writing 1 restarts the device.
	 */
	REG_HOLDING_DEVICE_RESET = 0x00F1,
	/**
	 * @brief Command for firmware update.
	 * 1: Verify Chunk - Slave writes the last chunk to flash.
	 * 2: Finalize Update - Complete installation and restart.
	 */
	REG_HOLDING_FWU_COMMAND = 0x0100,
	/**
	 * @brief Lower 16 bits of the 32-bit offset for the next firmware update
	 * chunk.
	 */
	REG_HOLDING_FWU_CHUNK_OFFSET_LOW = 0x0101,
	/**
	 * @brief Upper 16 bits of the 32-bit offset for the next firmware update
	 * chunk.
	 */
	REG_HOLDING_FWU_CHUNK_OFFSET_HIGH = 0x0102,
	/**
	 * @brief Size of the next firmware update chunk in bytes (max. 256).
	 */
	REG_HOLDING_FWU_CHUNK_SIZE = 0x0103,
	/**
	 * @brief Start address of the 256-byte buffer for firmware update data.
	 */
	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